diff options
| author | Yuriy Andamasov <yuriy@vyos.io> | 2026-04-15 12:39:08 +0300 |
|---|---|---|
| committer | Yuriy Andamasov <yuriy@vyos.io> | 2026-04-15 12:39:08 +0300 |
| commit | 1802518c053bde050074d85a137ffe672ec99e53 (patch) | |
| tree | c964bba1226ceceac324e7377728da2d1145758d | |
| parent | 2ff3232cac2278f22624a0a2e8daf2280b14912c (diff) | |
| parent | f0402b1a08c393c6f12896e2d27c339030f030b2 (diff) | |
| download | vyos-documentation-1802518c053bde050074d85a137ffe672ec99e53.tar.gz vyos-documentation-1802518c053bde050074d85a137ffe672ec99e53.zip | |
merge: resolve CLAUDE.md conflict, keep current branch version
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
103 files changed, 3549 insertions, 6496 deletions
diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md new file mode 100644 index 00000000..30fa5800 --- /dev/null +++ b/.github/copilot-instructions.md @@ -0,0 +1,80 @@ +## VyOS Documentation Project + +This is VyOS user documentation written in reStructuredText (RST) and built with Sphinx. + +### Review Scope + +When reviewing pull requests, only flag issues **introduced by the PR's changes**. Do not flag pre-existing issues in unchanged lines. Compare against the base branch to determine what was actually changed. + +### RST Heading Hierarchy + +All files must use this heading order: + +``` +##### (Title — one per file, with overline) +***** (Chapters) +===== (Sections) +----- (Subsections) +^^^^^ (Subsubsections) +""""" (Paragraphs) +``` + +### Line Length + +Maximum 80 characters per line. Exception: content inside `.. code-block::` directives is **exempt** — they render with `<pre>` tags and preserve source formatting. Do not flag long lines inside code blocks. + +### Linter Suppression Markers + +`.. stop_vyoslinter` and `.. start_vyoslinter` are RST comments used to suppress CI linter checks. Key conventions: + +- When used **inside an indented directive** (`.. cfgcmd::`, `.. opcmd::`, list items), markers should match the surrounding indentation to stay within the block. +- When used **at top level** (outside any directive), markers are placed at column 0. +- Both patterns exist in this repo. Do not flag either placement as incorrect. +- They must always appear in pairs (stop then start). A missing `start_vyoslinter` is a real issue. +- A `stop_vyoslinter` that covers a large section is acceptable when the content requires it (e.g., files full of real debug output with production IPs). + +### IP Address Rules + +The CI linter checks IP addresses. These are **allowed without suppression** — do not flag them: + +- RFC 5737 documentation addresses: `192.0.2.0/24`, `198.51.100.0/24`, `203.0.113.0/24` +- RFC 3849 documentation IPv6: `2001:db8::/32` +- RFC 1918 private ranges: `10.0.0.0/8`, `172.16.0.0/12`, `192.168.0.0/16` +- Loopback (`127.0.0.0/8`), link-local (`169.254.0.0/16`), `0.0.0.0/0` + +Real public IPs (e.g., `8.8.8.8`) require `stop/start_vyoslinter` suppression. Do not suggest replacing them with documentation addresses if the example intentionally uses real IPs. + +### TODO Markers + +`.. TODO::` directives serve two purposes in this repo: + +1. **Tracking markers** on pages that need `cfgcmd`/`opcmd` conversion (these are intentionally added). +2. **Stale markers** on pages that already have full content (these should be removed). + +A PR that removes some TODOs and adds others is not contradictory — the intent matters. + +### VyOS Directives + +- `.. cfgcmd::` for configuration mode commands +- `.. opcmd::` for operational mode commands +- Do not convert these to plain `.. code-block::` — they are tracked for command coverage. + +### YAML in Code Blocks + +Ansible playbook examples in `.. code-block::` use RST indentation (typically 4 spaces from the directive). The YAML indentation within the block may differ from standalone YAML files. Verify carefully before flagging YAML as invalid — count spaces from the code-block's own indentation base, not from column 0. + +### Page Structure + +Configuration pages follow this order: Theory, Configuration (cfgcmd), Examples, Known Issues, Debugging. + +### Known False Positives + +Do **not** flag the following — they have been verified as correct or intentional: + +- **Markdown tables rendering with `||`**: Diff views may show table pipes as double-pipes. Check the raw source file before flagging. +- **`stop/start_vyoslinter` at column 0 inside directives**: This is one of two accepted patterns. The other is indented markers matching the directive. Both are valid. +- **RFC 1918 addresses without linter suppression**: Private IPs (`10.x`, `172.16.x`, `192.168.x`) are allowed. Do not suggest adding `stop/start_vyoslinter` around them. +- **Long lines inside `.. code-block::`**: Code blocks are exempt from the 80-character line limit. +- **Pre-existing typos or grammar issues in unchanged lines**: Only flag issues introduced by the current PR's diff. If a typo exists on an unchanged line, it is out of scope. +- **Ansible YAML indentation in RST code blocks**: YAML inside `.. code-block::` is indented relative to the directive, not column 0. Verify from the code-block's indentation base before flagging as invalid. +- **Adding `.. TODO::` while removing others**: Tracking TODOs on pages needing `cfgcmd` conversion is intentional. Removing stale TODOs on completed pages is also intentional. Both can happen in the same PR. diff --git a/.github/instructions/rst-linter.instructions.md b/.github/instructions/rst-linter.instructions.md new file mode 100644 index 00000000..419f094a --- /dev/null +++ b/.github/instructions/rst-linter.instructions.md @@ -0,0 +1,70 @@ +--- +applyTo: "**/*.rst" +--- + +## RST Linter Rules + +Every pull request is automatically linted by `doc-linter.py` (from the `vyos/.github` repository). It checks **only changed files** for two things: IP address usage and line length. + +### IP Address Rules + +The linter rejects public IP addresses that are not reserved for documentation. + +**Use these documentation-reserved addresses (no suppression needed):** + +| Type | Range | RFC | +|------|-------|-----| +| IPv4 | `192.0.2.0/24` (TEST-NET-1) | RFC 5737 | +| IPv4 | `198.51.100.0/24` (TEST-NET-2) | RFC 5737 | +| IPv4 | `203.0.113.0/24` (TEST-NET-3) | RFC 5737 | +| IPv6 | `2001:db8::/32` | RFC 3849 | + +**These are allowed without suppression (not flagged by linter):** + +| Type | Range | Why | +|------|-------|-----| +| RFC 1918 private | `10.0.0.0/8` | Private address space | +| RFC 1918 private | `172.16.0.0/12` | Private address space | +| RFC 1918 private | `192.168.0.0/16` | Private address space | +| Loopback | `127.0.0.0/8` | Loopback range | +| Link-local | `169.254.0.0/16` | Link-local | + +**These require `stop/start_vyoslinter` suppression:** + +| Example | Why suppression is needed | +|---------|--------------------------| +| `8.8.8.8` (Google DNS) | Real public IP, not documentation-reserved | +| `64:ff9b::/96` (NAT64) | Well-known prefix, not in doc ranges | +| Real provider IPs in examples | Authenticity matters for the example | + +### Line Length Rules + +Maximum 80 characters per line. Lines inside `.. code-block::` directives are **exempt** from the line length limit (they render with `<pre>` tags and preserve source formatting). + +### Suppression Syntax + +When real public IPs or long lines are unavoidable, wrap the block: + +```rst +.. stop_vyoslinter + +.. code-block:: none + + set system name-server '8.8.8.8' + +.. start_vyoslinter +``` + +**Rules for suppression markers:** + +- Place `.. stop_vyoslinter` on its own line, immediately before the content +- Place `.. start_vyoslinter` on its own line, immediately after the content +- Always re-enable the linter — never leave it stopped for the rest of the file +- Suppress the smallest possible region +- Do NOT use suppression for content that can use documentation-reserved addresses instead + +### Common Mistakes + +- Removing `stop/start_vyoslinter` markers without fixing the underlying issue (exposes the line to the linter and fails CI) +- Using real public IPs when documentation addresses would work just as well +- Adding suppression markers around content that only has private (RFC 1918) addresses or `0.0.0.0/0` — these are allowed and don't need suppression @@ -27,6 +27,10 @@ __pycache__ .env .envrc +# superpowers generated files +.superpowers/ +docs/superpowers/ + # os specific .DS_Store @@ -1,91 +1,118 @@ -# CLAUDE.md +# VyOS Documentation -This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository. +RST documentation for VyOS, built with Sphinx and hosted on Read the Docs. -## Project Overview +## Build -VyOS network OS documentation, built with Sphinx from reStructuredText sources. Hosted at https://docs.vyos.io. The `current` branch tracks VyOS 1.5.x (circinus) rolling release. +```bash +# Docker (recommended) +docker build -t vyos/vyos-documentation docker +docker run --rm -it -v "$(pwd)":/vyos -w /vyos/docs \ + -e GOSU_UID=$(id -u) -e GOSU_GID=$(id -g) \ + vyos/vyos-documentation make html + +# Local +pip install -r requirements.txt +cd docs && make html +``` -## Build Commands +Output goes to `docs/_build/html/`. -All build commands run from the `docs/` directory. +## RST Conventions -### Local (requires Sphinx installed via `pip install -r requirements.txt`) +### Heading Hierarchy -```bash -cd docs -make html # Build HTML to docs/_build/html/ -make livehtml # Live preview at http://localhost:8000 -make pdf # Generate PDF -``` +```rst +##### +Title +##### -### Docker (preferred) +******** +Chapters +******** -```bash -# Build HTML -docker run --rm -it -v "$(pwd)":/vyos -w /vyos/docs -e GOSU_UID=$(id -u) -e GOSU_GID=$(id -g) vyos/vyos-documentation make html +Sections +======== -# Live preview -docker run --rm -it -p 8000:8000 -v "$(pwd)":/vyos -w /vyos/docs -e GOSU_UID=$(id -u) -e GOSU_GID=$(id -g) vyos/vyos-documentation make livehtml +Subsections +----------- + +Subsubsections +^^^^^^^^^^^^^^ + +Paragraphs +"""""""""" ``` -### Linting (Vale) +The first heading in every RST file must use `#` overline+underline. Files may have field lists (e.g., `:lastproofread:`) or labels before the heading. -```bash -# Lint all files -docker run --rm -it -v "$(pwd)":/vyos -w /vyos/docs -e GOSU_UID=$(id -u) -e GOSU_GID=$(id -g) vyos/vyos-documentation vale . +### Formatting Rules -# Lint a single file -docker run --rm -it -v "$(pwd)":/vyos -w /vyos/docs -e GOSU_UID=$(id -u) -e GOSU_GID=$(id -g) vyos/vyos-documentation vale quick-start.rst -``` +- 80 character line limit (except inside `.. code-block::`) +- American English +- Indent with 2 spaces +- Leave a blank line before and after headers +- Use double backticks for inline code: ``` ``command`` ``` +- Use `.. code-block:: none` for command/output blocks -## Architecture +### Address Space -### Documentation Source +See `docs/documentation.rst` for canonical rules. Per RFC 5737, RFC 3849, RFC 5389, and RFC 7042: -- All RST source files live under `docs/` following the VyOS CLI hierarchy (e.g., `set firewall zone` → `docs/configuration/firewall/zone.rst`) -- Main index: `docs/index.rst` -- Sphinx config: `docs/conf.py` +The linter enforces documentation-reserved addresses. Use only: -### Custom Sphinx Extensions (`docs/_ext/`) +- IPv4: `192.0.2.0/24`, `198.51.100.0/24`, `203.0.113.0/24` +- IPv6: `2001:db8::/32` +- ASN: `64496-64511` (16-bit), `65536-65551` (32-bit) +- MAC: `00-53-00` to `00-53-FF` (unicast), `90-10-00` to `90-10-FF` (multicast) -- **vyos.py** — Core extension defining custom directives and roles: - - `.. cfgcmd::` — Document configuration commands - - `.. opcmd::` — Document operational commands - - `.. cfgcmdlist::` / `.. opcmdlist::` — Generate command lists with coverage status - - `.. cmdinclude::` — Include RST with variable substitution (var0-var9) - - Roles: `:vytask:` (links to task tracker), `:cfgcmd:`, `:opcmd:` (inline command references) -- **testcoverage.py** — Compares documented commands against XML definitions and actual VyOS commands -- **releasenotes.py** — Release notes integration +**Allowed without suppression:** +- RFC 1918 private ranges: `10.0.0.0/8`, `172.16.0.0/12`, `192.168.0.0/16` +- Link-local, loopback, and other non-public ranges -### Shared Fragments (`docs/_include/`) +**Requires `stop/start_vyoslinter`:** +- Real public IPs when needed for authenticity (e.g., `8.8.8.8` in DNS examples) +- NAT64 well-known prefix `64:ff9b::/96` +- Long URLs or certificate fingerprints that exceed 80 chars -- `interface-*.txt` files contain shared RST blocks (e.g., common interface options) included via `.. cmdinclude::` with `var0`–`var9` substitution -- `vyos-1x/` submodule contains VyOS source XML definitions used for command coverage analysis +### Linter Suppression -### Additional Extensions +```rst +.. stop_vyoslinter -- **autosectionlabel.py** — Custom wrapper enabling cross-document section references via `autosectionlabel_prefix_document = True` -- Both `.rst` and `.md` (MyST Markdown) are valid source formats +.. code-block:: none -## RST Writing Conventions + content with real IPs or long lines here -- **Language**: American English -- **Line length**: Max 80 characters (URLs exempt) -- **Indentation**: 2 spaces -- **Heading hierarchy** (top to bottom): `#####`, `*****`, `=====`, `-----`, `^^^^^`, `""""""` -- Every RST file must start with the `#####` level title -- Leave a newline before and after headers -- Quote commands/filenames with double backticks; use literal blocks for longer snippets -- Add `:lastproofread: YYYY-MM-DD` metadata to track proofreading currency (warns if >365 days old) +.. start_vyoslinter +``` + +Place markers immediately before/after the block they suppress. Always re-enable with `start_vyoslinter`. + +### VyOS-Specific Directives + +- `.. cfgcmd::` — configuration mode commands +- `.. opcmd::` — operational mode commands +- `.. cmdinclude::` — include command definitions from XML ### Page Structure -Each documentation page should follow this order: -1. Theoretical information (what/why/when) -2. Configuration description (using `cfgcmd` directives) -3. Configuration examples with topology -4. Known issues and workarounds -5. Debugging procedures +Each configuration page should contain: + +1. **Theory** — what it is, when to use it, relevant RFCs +2. **Configuration** — all CLI options with `.. cfgcmd::` directives +3. **Examples** — practical configurations with topology diagrams +4. **Known issues** — problems and workarounds +5. **Debugging** — log collection, `show` commands, state indicators + +## CI + +- **Linter** (`doc-linter.py` from `vyos/.github`): checks line length and IP addresses on changed files only +- **Sphinx build**: runs on Read the Docs for each PR +- **CLA check**: contributors must sign the CLA + +## Git Workflow -### Update `index.rst` when adding new pages. +- Base branch: `current` +- Branch naming: `fix/docs-*`, `feat/docs-*` +- PRs target `current` branch diff --git a/docs/_html_extra/llms.txt b/docs/_html_extra/llms.txt new file mode 100644 index 00000000..a8f5b002 --- /dev/null +++ b/docs/_html_extra/llms.txt @@ -0,0 +1,52 @@ +# VyOS + +> VyOS is a free, open-source network operating system based on Debian GNU/Linux. +> It provides routing, firewall, and VPN functionality via a unified CLI using +> `set`/`delete`/`show` command hierarchy. Current rolling release is 1.5.x (circinus). + +VyOS configuration follows a tree structure. All configuration commands start with +`set` (to add/change) or `delete` (to remove). Changes are staged and applied with +`commit`. The CLI hierarchy maps directly to the documentation structure. + +## Quick Start + +- [Quick Start Guide](https://docs.vyos.io/en/latest/quick-start.html): Minimal setup walkthrough +- [CLI Overview](https://docs.vyos.io/en/latest/cli.html): Command-line interface usage + +## Configuration + +- [Firewall](https://docs.vyos.io/en/latest/configuration/firewall/index.html): Zone-based firewall, rules, groups +- [Interfaces](https://docs.vyos.io/en/latest/configuration/interfaces/index.html): Ethernet, bonding, bridge, VLAN, tunnel, wireless +- [Protocols](https://docs.vyos.io/en/latest/configuration/protocols/index.html): BGP, OSPF, IS-IS, static routing, MPLS +- [VPN](https://docs.vyos.io/en/latest/configuration/vpn/index.html): IPsec, OpenVPN, WireGuard, L2TP, PPTP +- [NAT](https://docs.vyos.io/en/latest/configuration/nat/index.html): Source NAT, destination NAT, NAT66 +- [System](https://docs.vyos.io/en/latest/configuration/system/index.html): DNS, NTP, syslog, users, task scheduler +- [High Availability](https://docs.vyos.io/en/latest/configuration/highavailability/index.html): VRRP +- [Load Balancing](https://docs.vyos.io/en/latest/configuration/loadbalancing/index.html): WAN and reverse proxy +- [Containers](https://docs.vyos.io/en/latest/configuration/container/index.html): Podman-based container support +- [PKI](https://docs.vyos.io/en/latest/configuration/pki/index.html): Certificate management +- [Policy](https://docs.vyos.io/en/latest/configuration/policy/index.html): Route maps, prefix lists, access lists +- [Traffic Policy](https://docs.vyos.io/en/latest/configuration/trafficpolicy/index.html): QoS and shaping +- [Service](https://docs.vyos.io/en/latest/configuration/service/index.html): DHCP, DNS forwarding, SNMP, SSH, HTTPS API +- [VRF](https://docs.vyos.io/en/latest/configuration/vrf/index.html): Virtual routing and forwarding + +## Operations + +- [Operational Commands](https://docs.vyos.io/en/latest/operation/index.html): Show, monitor, restart commands + +## Installation + +- [Installation Guide](https://docs.vyos.io/en/latest/installation/index.html): Bare metal, virtual, cloud deployments + +## Automation + +- [Automation](https://docs.vyos.io/en/latest/automation/index.html): Ansible, Terraform, HTTP API, NETCONF + +## Configuration Examples + +- [Blueprints](https://docs.vyos.io/en/latest/configexamples/index.html): Real-world topology examples + +## Optional + +- [Contributing](https://docs.vyos.io/en/latest/contributing/index.html): Development workflow +- [VPP](https://docs.vyos.io/en/latest/vpp/index.html): Vector Packet Processing integration diff --git a/docs/_html_extra/robots.txt b/docs/_html_extra/robots.txt index 627cb18e..71a6990b 100644 --- a/docs/_html_extra/robots.txt +++ b/docs/_html_extra/robots.txt @@ -1,7 +1,36 @@ -User-agent: atlassian-bot -Disallow: - User-agent: * -Disallow: # Allow everything +Allow: / + +# AI Training Crawlers +User-agent: GPTBot +Allow: / + +User-agent: ClaudeBot +Allow: / + +User-agent: Google-Extended +Allow: / + +User-agent: CCBot +Allow: / + +User-agent: PerplexityBot +Allow: / + +# AI Search/Retrieval +User-agent: ChatGPT-User +Allow: / + +User-agent: Claude-SearchBot +Allow: / + +User-agent: Claude-User +Allow: / + +User-agent: OAI-SearchBot +Allow: / + +User-agent: Perplexity-User +Allow: / -Sitemap: https://docs.vyos.io/sitemap.xml
\ No newline at end of file +Sitemap: https://docs.vyos.io/sitemap.xml diff --git a/docs/automation/command-scripting.rst b/docs/automation/command-scripting.rst index 0e60e6e1..91086b42 100644 --- a/docs/automation/command-scripting.rst +++ b/docs/automation/command-scripting.rst @@ -1,15 +1,16 @@ -:lastproofread: 2023-01-16 +:lastproofread: 2026-03-16 .. _command-scripting: -Command Scripting +Command scripting ================= VyOS supports executing configuration and operational commands non-interactively from shell scripts. -To include VyOS specific functions and aliases you need to ``source -/opt/vyatta/etc/functions/script-template`` files at the top of your script. +To include VyOS-specific functions and aliases, source the +``/opt/vyatta/etc/functions/script-template`` file at the beginning of your +script. .. code-block:: none @@ -33,8 +34,11 @@ following command: 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: +In scripts, present configuration commands as in a standard configuration +session. + +For example, to disable a BGP peer during a VRRP transition to the backup +state, use the following syntax: .. code-block:: none @@ -49,8 +53,7 @@ example, if you want to disable a BGP peer on VRRP transition to backup: 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. +In scripts, **always** prefix operational commands with ``run``. .. code-block:: none @@ -62,8 +65,8 @@ prepended with ``run``, even if you haven't created a session with configure. Run commands remotely --------------------- -Sometimes you simply want to execute a bunch of op-mode commands via SSH on -a remote VyOS system. +You can execute multiple **operational commands** on a remote VyOS system by +passing a script block over SSH. .. code-block:: none @@ -73,7 +76,7 @@ a remote VyOS system. exit EOF -Will return: +Example output: .. code-block:: none @@ -89,10 +92,10 @@ Will return: 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. +If you use a scripting language other than bash, configure your script to +output the relevant commands, and then source that output into a bash script. -Here is a simple example: +The following example demonstrates this two-step process: .. code-block:: python @@ -111,16 +114,14 @@ Here is a simple example: commit -Executing Configuration Scripts +Execute 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. +In Linux, it is common practice to prefix system commands with ``sudo``. -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: +In VyOS, if you prefix a script that modifies the configuration with ``sudo`` +(see the code snippet below), subsequent manual configuration changes fail with +the ``Set failed`` error. Recovery requires a system reboot. .. code-block:: none @@ -128,18 +129,15 @@ anymore: 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: +To avoid this issue, run scripts under the ``vyattacfg`` group using the ``sg`` +command: .. code-block:: 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: +To ensure the script is executed under the ``vyattacfg`` group, safeguard it as +follows: .. code-block:: none @@ -147,12 +145,12 @@ group, the script can be safeguarded like this: exec sg vyattacfg -c "/bin/vbash $(readlink -f $0) $@" fi -Executing pre-hooks/post-hooks Scripts +Executing pre-hooks/post-hooks scripts -------------------------------------- -VyOS has the ability to run custom scripts before and after each commit +VyOS allows you to run custom scripts **before** and **after** each commit. -The default directories where your custom Scripts should be located are: +Place your custom scripts in the following default directories: .. code-block:: none @@ -162,15 +160,15 @@ The default directories where your custom Scripts should be located are: /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. +Scripts run in alphabetical order. Filenames must consist only of ASCII letters +(upper and lowercase), digits (0-9), underscores (_), and hyphens (-). No other +characters are allowed. -.. note:: Custom scripts are not executed with root privileges - (Use sudo inside if this is necessary). +.. note:: Custom scripts are executed **without** root privileges. Prefix + specific commands with ``sudo`` in your script when required. -A simple example is shown below, where the ops command executed in -the post-hook script is "show interfaces". +The following example shows the output after executing a post-hook script +that runs the ``show interfaces`` command: .. code-block:: none @@ -185,16 +183,16 @@ the post-hook script is "show interfaces". eth3 - u/u lo 203.0.113.5/24 u/u -Preconfig on boot ------------------ +Preconfig script on boot +------------------------ -The ``/config/scripts/vyos-preconfig-bootup.script`` script is called on boot -before the VyOS configuration during boot process. +VyOS runs ``/config/scripts/vyos-preconfig-bootup.script`` at boot, **before** +the system configuration is 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. +Use this script to apply **pre-configuration** workarounds for unresolved bugs +or enhancements not yet available in VyOS. -The default file looks like this: +The default script contains the following: .. code-block:: none @@ -204,16 +202,16 @@ The default file looks like this: # services not available through the VyOS CLI system can be placed here. -Postconfig on boot ------------------- +Postconfig script on boot +------------------------- -The ``/config/scripts/vyos-postconfig-bootup.script`` script is called on boot -after the VyOS configuration is fully applied. +VyOS runs ``/config/scripts/vyos-postconfig-bootup.script`` at boot, **after** +the system configuration is 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. +Use this script to apply **post-configuration** workarounds for unresolved bugs +or enhancements not yet available in VyOS. -The default file looks like this: +The default script contains the following: .. code-block:: none @@ -222,6 +220,5 @@ The default file looks like this: # applied. Any modifications required to work around unfixed bugs or use # services not available through the VyOS CLI system can be placed here. -.. hint:: For configuration/upgrade management issues, modification of this - script should be the last option. Always try to find solutions based on CLI - commands first. +.. warning:: For configuration or upgrade management issues, modify this script + only as a last resort. Always try CLI-based solutions first. diff --git a/docs/automation/terraform/index.rst b/docs/automation/terraform/index.rst index 42af58bd..364a00b7 100644 --- a/docs/automation/terraform/index.rst +++ b/docs/automation/terraform/index.rst @@ -1,14 +1,32 @@ +:lastproofread: 2026-03-23 + ############## VyOS Terraform ############## + +VyOS supports development infrastructure via Terraform and provisioning +via Ansible. +Terraform allows you to automate the deployment of instances on a number of +cloud and virtual platforms. This section shows how to deploy VyOS on +multiple platforms: AWS, Microsoft Azure, Google Cloud Platform (GCP), +and VMware vSphere. +For more information, see the +official documentation for Terraform_ and Ansible_. + + + .. toctree:: :maxdepth: 1 - :caption: Content + :caption: Guides - terraformvyos terraformAWS terraformAZ - terraformvSphere terraformGoogle - + terraformvSphere + +.. stop_vyoslinter +.. _Terraform: https://developer.hashicorp.com/terraform/intro +.. _Ansible: https://docs.ansible.com +.. _install: https://developer.hashicorp.com/terraform/tutorials/aws-get-started/install-cli +.. start_vyoslinter
\ No newline at end of file diff --git a/docs/automation/terraform/terraformAWS.rst b/docs/automation/terraform/terraformAWS.rst index 35afc569..8156fac4 100644 --- a/docs/automation/terraform/terraformAWS.rst +++ b/docs/automation/terraform/terraformAWS.rst @@ -1,12 +1,13 @@ -:lastproofread: 2024-01-11 +:lastproofread: 2026-03-16 .. _terraformAWS: -Deploying VyOS in the AWS cloud -=============================== +Deploy VyOS on AWS with Terraform and Ansible +============================================= -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. +You can use Terraform to quickly deploy VyOS-based infrastructure +on AWS and remove infrastructure when it's no longer needed. +Additionally, you can use Ansible for provisioning. .. image:: /_static/images/aws.* @@ -14,28 +15,33 @@ Also we will make provisioning using Ansible. :align: center :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. +On this page you'll learn how to: +* Create the necessary files for Terraform and Ansible. +* Use Terraform to create a single instance on AWS and use Ansible for + provisioning. -Preparation steps for deploying VyOS on AWS -------------------------------------------- -How to create a single instance and install your configuration using Terraform+Ansible+AWS -Step by step: +Prepare to deploy VyOS with Terraform on AWS +-------------------------------------------- + +To create a single instance and install your configuration using +Terraform, Ansible, and AWS, follow these steps: AWS +^^^ -1 Create an account with AWS and get your "access_key", "secret key" +1. Create an account with AWS and get your ``access_key`` and ``secret_key``. -2 Create a key pair_ and download your .pem key +2. Create a key pair_ and download your ``.pem`` key. .. image:: /_static/images/keypairs.* :width: 50% :align: center :alt: Network Topology Diagram -3 Create a security group_ for the new VyOS instance and open all traffic +3. Create a security group_ for the new VyOS instance and open all traffic. .. image:: /_static/images/sg.* :width: 50% @@ -49,57 +55,71 @@ AWS :alt: Network Topology Diagram Terraform +^^^^^^^^^ +1. Create an UNIX or Windows instance. - 1 Create an UNIX or Windows instance +2. Download and install + `Terraform <https://developer.hashicorp.com/terraform/install>`__. - 2 Download and install Terraform +3. Create a folder, for example ``/root/awsterraform``: - 3 Create the folder for example /root/awsterraform + .. code-block:: none -.. code-block:: none + mkdir /root/awsterraform - mkdir /root/awsterraform +.. stop_vyoslinter - 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`_ +4. Copy all files into your Terraform project + (``vyos.tf``, ``var.tf``, ``terraform.tfvars``, ``version.tf``). + See `Structure of files in Terraform for AWS <#structure-of-files-in-terraform-for-aws>`__ for more details. - 5 Type the commands : +.. start_vyoslinter + +5. Run the following commands: .. code-block:: none - cd /<your folder> + cd /<your folder> terraform init - Ansible +^^^^^^^ - 1 Create an UNIX instance whenever you want (local, cloud, and so on) +1. Create a UNIX instance whenever you need. - 2 Download and install Ansible +2. Download and install Ansible - 3 Create the folder for example /root/aws/ +3. Create a 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`_ +.. stop_vyoslinter -mykey.pem you have to get using step 1.2 +4. Copy all files into your Ansible project + (``ansible.cfg``, ``instance.yml``, + ``mykey.pem``, and ``all``). + See `Structure of files in Ansible for AWS <#structure-of-files-in-ansible-for-aws>`__ for more details. + You can obtain ``mykey.pem`` by creating a key pair_ in AWS and + downloading your ``.pem`` key. +.. start_vyoslinter -Start +Deploy with Terraform +^^^^^^^^^^^^^^^^^^^^^ -Type the commands on your Terrafom instance: +Run the following commands on your Terraform instance: .. code-block:: none cd /<your folder> - terraform plan - terraform apply + terraform plan + terraform apply yes -Start creating an AWS instance and check the result ---------------------------------------------------- +Create an AWS instance and check its configuration +-------------------------------------------------- .. code-block:: none @@ -252,8 +272,9 @@ Start creating an AWS instance and check the result -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: +After running all the commands, your VyOS instance is deployed on +AWS with your specified configuration. +To delete the instance, type the following command: .. code-block:: none @@ -263,26 +284,29 @@ If you need to delete the instance please type the command: 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. +1. If Ansible doesn't connect via SSH to your AWS instance, verify that + your SSH key is in the path ``/root/aws/``. You might need to + increase the timeout in ``instance.yml`` from 300 seconds to 500 + seconds or more, depending on your location. Make sure that the + security group allows access to the instance. - 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 +2. If Terraform doesn't connect via SSH to your Ansible instance, + verify the correct login and password in the ``VyOS.tf`` file. -.. code-block:: none + .. code-block:: 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 - } + 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. +Make sure Ansible can ping from Terraform. -Structure of files Terrafom for AWS ------------------------------------ +Structure of files in Terraform for AWS +--------------------------------------- .. code-block:: none @@ -293,20 +317,20 @@ Structure of files Terrafom for AWS └── terraform.tfvars # The value of all variables (passwords, login, ip adresses and so on) - -File contents of Terrafom for AWS ---------------------------------- +File contents of Terraform for AWS +---------------------------------- -vyos.tf +``vyos.tf`` .. code-block:: none ############################################################################## - # Build an VyOS VM from the Marketplace - # To finde nessesery AMI image_ in AWS + # Build a VyOS VM from the Marketplace. + # Find the necessary AMI image_ in AWS. # - # In the script vyos.tf we'll use default values (you can chang it as you need) + # The vyos.tf script uses default values (you can change them as + # needed) # AWS Region = "us-east-1" # AMI = "standard AMI of VyOS from AWS Marketplace" # Size of VM = "t2.micro" @@ -349,9 +373,9 @@ vyos.tf } ############################################################################## - # specific variable (to getting type "terraform plan"): + # 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 + # of our instance, needs for provisioning and SSH connection from Ansible ############################################################################## output "my_IP"{ @@ -359,11 +383,9 @@ vyos.tf } ############################################################################## - # - # IP of aws instance copied to a file ip.txt in local system Terraform - # ip.txt looks like: - # cat ./ip.txt - # ххх.ххх.ххх.ххх + # The IP address of the AWS instance is copied to the ip.txt file + # on the local Terraform system. The ip.txt file contains the public + # IP address in the format: xxx.xxx.xxx.xxx ############################################################################## resource "local_file" "ip" { @@ -374,7 +396,8 @@ vyos.tf #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. + # The "SSHconnection1" and "SSHconnection2" steps retrieve ip.txt + # from the Terraform node and run the Ansible playbook remotely. ############################################################################## resource "null_resource" "SSHconnection1" { @@ -386,8 +409,8 @@ vyos.tf host = var.host } - #copying the ip.txt file to the Ansible control node from local system - + # Copy the ip.txt file to the Ansible control node from the local + # system provisioner "file" { source = "ip.txt" destination = "/root/aws/ip.txt" # The folder of your Ansible project @@ -402,7 +425,7 @@ vyos.tf password = var.password host = var.host } - #command to run Ansible playbook on remote Linux OS + # Run Ansible playbook on remote Linux OS provisioner "remote-exec" { inline = [ "cd /root/aws/", @@ -412,7 +435,7 @@ vyos.tf } -var.tf +``var.tf`` .. code-block:: none @@ -423,7 +446,7 @@ var.tf } variable "host"{ description = "The IP of my Ansible" - type = string + type = string } variable "access" { description = "my access_key for AWS" @@ -436,7 +459,7 @@ var.tf sensitive = true } -versions.tf +``versions.tf`` .. code-block:: none @@ -449,7 +472,7 @@ versions.tf } } -terraform.tfvars +``terraform.tfvars`` .. code-block:: none @@ -459,8 +482,8 @@ terraform.tfvars secret = "" # secret_key for AWS -Structure of files Ansible for AWS ----------------------------------- +Structure of files in Ansible for AWS +------------------------------------- .. code-block:: none @@ -475,7 +498,7 @@ Structure of files Ansible for AWS File contents of Ansible for AWS -------------------------------- -ansible.cfg +``ansible.cfg`` .. code-block:: none @@ -485,14 +508,14 @@ ansible.cfg private_key_file = /root/aws/awsterraform.pem # check the name remote_user=vyos -mykey.pem +``mykey.pem`` .. code-block:: none Copy your key.pem from AWS -instance.yml +``instance.yml`` @@ -500,9 +523,11 @@ instance.yml ############################################################################## # 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:" + # "Wait 300 seconds, but only start checking after 60 seconds" - + # attempts SSH connection every 60 seconds until 300 seconds + # "Configure general settings for the VyOS hosts group" - + # provisions the AWS VyOS node + # Add all necessary VyOS commands under the "lines:" block ############################################################################## @@ -525,7 +550,7 @@ instance.yml true -group_vars/all +``group_vars/all`` .. code-block:: none @@ -533,15 +558,19 @@ group_vars/all ansible_network_os: vyos.vyos.vyos ansible_user: vyos -Sourse files for AWS from GIT ------------------------------ +Source files on GitHub +---------------------- -All files about the article can be found here_ +All files related to deploying VyOS on AWS with Terraform and Ansible +can be found in the vyos-automation_ repository. +.. stop_vyoslinter .. _link: https://developer.hashicorp.com/terraform/intro .. _install: https://developer.hashicorp.com/terraform/tutorials/aws-get-started/install-cli .. _pair: https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/create-key-pairs.html .. _group: https://docs.aws.amazon.com/cli/latest/userguide/cli-services-ec2-sg.html .. _image: https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/AMIs.html -.. _here: https://github.com/vyos/vyos-automation/tree/main/TerraformCloud/AWS_terraform_ansible_single_vyos_instance-main
\ No newline at end of file +.. _vyos-automation: https://github.com/vyos/vyos-automation/tree/main/TerraformCloud/AWS_terraform_ansible_single_vyos_instance-main + +.. start_vyoslinter diff --git a/docs/automation/terraform/terraformAZ.rst b/docs/automation/terraform/terraformAZ.rst index a0fea023..9e094aea 100644 --- a/docs/automation/terraform/terraformAZ.rst +++ b/docs/automation/terraform/terraformAZ.rst @@ -1,69 +1,88 @@ -:lastproofread: 2024-03-03 +:lastproofread: 2026-03-19 .. _terraformAZ: -Deploying VyOS in the Azure cloud -================================= +Deploy VyOS on Microsoft Azure with Terraform and Ansible +========================================================= -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. +You can use Terraform to quickly deploy VyOS-based infrastructure +on Microsoft Azure (hereafter referred to as *Azure*) and remove +infrastructure when it's no longer needed. +Additionally, you can use Ansible for provisioning. -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. +On this page you'll learn how to: -Preparation steps for deploying VyOS on Azure ---------------------------------------------- +* Create the necessary files for Terraform and Ansible. +* Use Terraform to create a single instance on Azure and use Ansible for + provisioning. -How to create a single instance and install your configuration using Terraform+Ansible+Azure -Step by step: +Prepare to deploy VyOS with Terraform on Azure +---------------------------------------------- + +To create a single instance and install your configuration using +Terraform, Ansible, and Azure, follow these steps: Azure +^^^^^ - 1 Create an account with Azure +1. Create an `Azure account <https://azure.microsoft.com/>`__. Terraform +^^^^^^^^^ - 1 Create an UNIX or Windows instance +1. Create an UNIX or Windows instance. - 2 Download and install Terraform +2. Download and install + `Terraform <https://developer.hashicorp.com/terraform/install>`__. - 3 Create the folder for example /root/azvyos/ +3. Create the folder for example ``/root/azvyos/``. .. code-block:: none - mkdir /root/azvyos + 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`_ +.. stop_vyoslinter - 5 Login with Azure using the command +4. Copy all files into your Terraform project "/root/azvyos" + (``vyos.tf``, ``var.tf``, ``terraform.tfvars``). For more details, see + `Structure of files in Terraform for Azure <#structure-of-files-in-terraform-for-azure>`_. -.. code-block:: none +.. start_vyoslinter - az login +5. Log in to Azure using the command: -2.6 Type the commands : + .. code-block:: none -.. code-block:: none + az login + +6. Run the following commands to initialize Terraform: + + .. code-block:: none - cd /<your folder> - terraform init + cd /<your folder> + terraform init Ansible +^^^^^^^ - 1 Create an UNIX instance whenever you want (local, cloud, and so on) +1. Create an UNIX instance either locally or in the cloud. - 2 Download and install Ansible +2. Download and install Ansible - 3 Create the folder for example /root/az/ +3. Create a 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`_ +4. Copy all files into your Ansible project ``/root/az/`` (``ansible.cfg``, + ``instance.yml``, ``all``). For more details, see + `Structure of files in Ansible for Azure`_ -Start +Deploy with Terraform +^^^^^^^^^^^^^^^^^^^^^ -Type the commands on your Terrafom instance: +Run the following commands on your Terraform instance: .. code-block:: none @@ -72,27 +91,29 @@ Type the commands on your Terrafom instance: 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: +After executing all the commands, your VyOS instance is deployed to +Azure with your configuration. +If you need to delete the instance, run the following command: .. code-block:: none terraform destroy -Structure of files Terrafom for Azure -------------------------------------- +Structure of files in Terraform for Azure +----------------------------------------- .. code-block:: 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) + ├── var.tf # File for the Terraform version. + └── terraform.tfvars # Values for all variables (passwords, + # login, IP addresses, etc.) -File contents of Terrafom for Azure ------------------------------------ +File contents of Terraform for Azure +------------------------------------ -vyos.tf +``vyos.tf`` .. code-block:: none @@ -101,18 +122,18 @@ vyos.tf # 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) + # A VyOS server without SSH key (only login+password) ############################################################################## - # Chouse a provider + # Choose a provider provider "azurerm" { features {} } - # Create a resource group. In Azure every resource belongs to a - # resource group. - + # 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}" @@ -126,8 +147,8 @@ vyos.tf address_space = ["${var.address_space}"] resource_group_name = "${var.resource_group}" } - - # Build a subnet to run our VMs in. + + # Build a subnet to run your VMs. resource "azurerm_subnet" "subnet" { name = "${var.prefix}subnet" @@ -137,20 +158,21 @@ vyos.tf } ############################################################################## - # Build an VyOS VM from the Marketplace - # To finde nessesery image use the command: + # Build a VyOS VM from the Marketplace. + # To find the necessary 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. + # Now that you have a network, you can deploy a VyOS server. + # An Azure Virtual Machine has several components. In this example, + # you 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) + # Security group to allow inbound access on port 22 (SSH) resource "azurerm_network_security_group" "vyos-sg" { name = "${var.prefix}-sg" @@ -194,8 +216,9 @@ vyos.tf allocation_method = "Dynamic" } - # Build a virtual machine. This is a standard VyOS instance from Marketplace. - + # Build a virtual machine. This is a standard VyOS instance from + # Marketplace. + resource "azurerm_virtual_machine" "vyos" { name = "${var.hostname}-vyos" location = "${var.location}" @@ -204,8 +227,8 @@ vyos.tf 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: + + # To find information about the plan, use the command: # az vm image list --offer vyos --all plan { @@ -247,27 +270,28 @@ vyos.tf 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 - + + # IP of AZ instance copied to a file ip.txt in the 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 - + + # Connect to the Ansible control node via SSH + resource "null_resource" "nullremote1" { - depends_on = ["azurerm_virtual_machine.vyos"] + 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 - + + # Copy the ip.txt file to the Ansible control node from the local + # system + provisioner "file" { source = "ip.txt" destination = "/root/az/ip.txt" @@ -282,9 +306,9 @@ vyos.tf password = var.password host = var.host } - - # Command to run ansible playbook on remote Linux OS - + + # Run the Ansible playbook on the remote Linux OS + provisioner "remote-exec" { inline = [ @@ -295,15 +319,14 @@ vyos.tf } -var.tf +``var.tf`` .. code-block:: none ############################################################################## # Variables File # - # Here is where we store the default values for all the variables used in our - # Terraform code. + # Default values for all variables used in Terraform code. ############################################################################## variable "resource_group" { @@ -351,7 +374,7 @@ var.tf default = "LRS" } - # The most chippers size + # The most cost-effective size variable "vm_size" { description = "Specifies the size of the virtual machine." @@ -402,7 +425,7 @@ var.tf description = "IP of my Ansible" } -terraform.tfvars +``terraform.tfvars`` .. code-block:: none @@ -410,8 +433,8 @@ terraform.tfvars host = "" # IP of my Ansible -Structure of files Ansible for Azure ------------------------------------- +Structure of files in Ansible for Azure +--------------------------------------- .. code-block:: none @@ -425,7 +448,7 @@ Structure of files Ansible for Azure File contents of Ansible for Azure ---------------------------------- -ansible.cfg +``ansible.cfg`` .. code-block:: none @@ -435,16 +458,18 @@ ansible.cfg remote_user=vyos -instance.yml +``instance.yml`` .. code-block:: 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:" + # "Wait 300 seconds, but only start checking after 60 seconds" - Tries + # to make SSH connection every 60 seconds until 300 seconds. + # "Configure general settings for the VyOS hosts group" - Provision + # the Azure VyOS node. + # Add all necessary commands for VyOS under the block "lines:" ############################################################################## @@ -467,7 +492,7 @@ instance.yml true -group_vars/all +``group_vars/all`` .. code-block:: none @@ -478,11 +503,12 @@ group_vars/all ansible_user: vyos ansible_ssh_pass: Vyos0! -Sourse files for Azure from GIT -------------------------------- - -All files about the article can be found here_ - -.. _here: https://github.com/vyos/vyos-automation/tree/main/TerraformCloud/Azure_terraform_ansible_single_vyos_instance-main - +Source files on GitHub +---------------------- +All files related to deploying VyOS on Azure with Terraform and Ansible +can be found in the vyos-automation_ repository. + +.. stop_vyoslinter +.. _vyos-automation: https://github.com/vyos/vyos-automation/tree/main/TerraformCloud/Azure_terraform_ansible_single_vyos_instance-main +.. start_vyoslinter diff --git a/docs/automation/terraform/terraformGoogle.rst b/docs/automation/terraform/terraformGoogle.rst index d6673a50..eb7e01fe 100644 --- a/docs/automation/terraform/terraformGoogle.rst +++ b/docs/automation/terraform/terraformGoogle.rst @@ -1,32 +1,38 @@ -:lastproofread: 2024-03-25 +:lastproofread: 2026-03-23 .. _terraformgoogle: -Deploying VyOS in the Google Cloud -================================== +Deploy VyOS on Google Cloud with Terraform and Ansible +====================================================== -With the help of Terraform, you can quickly deploy VyOS-based infrastructure in the Google Cloud. If necessary, the infrastructure can be removed using terraform. -Also we will make provisioning using Ansible. +Using Terraform, you can quickly deploy VyOS-based infrastructure on +Google Cloud Platform (GCP) and remove the +infrastructure when it's no longer needed. +Additionally, you can use Ansible for provisioning. -In this case, we'll create the necessary files for Terraform and Ansible. Next, using Terraform, we'll create a single instance on the Google Cloud and make provisioning using Ansible. +On this page you'll learn how to: +* Create the necessary files for Terraform and Ansible. +* Use Terraform to create a single instance on GCP and use Ansible for +provisioning. -Preparation steps for deploying VyOS on Google ----------------------------------------------- +Prepare to deploy VyOS with Terraform on GCP +-------------------------------------------- -How to create a single instance and install your configuration using Terraform+Ansible+Google -Step by step: +To create a single instance and install your configuration using +Terraform, Ansible, and GCP, follow these steps: -Google Cloud +GCP +^^^ -1 Create an account with Google Cloud and a new project +1. Create an account with GCP and a new project. .. image:: /_static/images/project.* :width: 50% :align: center :alt: Network Topology Diagram -2 Create a service aacount and download your key (.JSON) +2. Create a service account and download your key (a JSON file). .. image:: /_static/images/service.* :width: 50% @@ -38,7 +44,8 @@ Google Cloud :align: center :alt: Network Topology Diagram -The .JSON file download automaticly after creating and will look like: +The .JSON file downloads automatically after you create it and looks +like the following: .. image:: /_static/images/json.* :width: 50% @@ -47,21 +54,29 @@ The .JSON file download automaticly after creating and will look like: Terraform +^^^^^^^^^ -1 Create an UNIX or Windows instance +1. Create an UNIX or Windows instance. -2 Download and install Terraform +2. Download and install + `Terraform <https://developer.hashicorp.com/terraform/install>`__. -3 Create the folder for example /root/google +3. Create the folder. For example, ``/root/google``. .. code-block:: none mkdir /root/google + +.. stop_vyoslinter +4. Copy all files into your Terraform project ``/root/google`` + (``vyos.tf``, ``var.tf``, ``terraform.tfvars``, ``mykey.json``). + For more details, + see `Structure of files Terraform for Google Cloud <#structure-of-files-in-terraform-for-google-cloud>`_ -4 Copy all files into your Terraform project "/root/google" (vyos.tf, var.tf, terraform.tfvars, .JSON), more detailed see `Structure of files Terrafom for google cloud`_ +.. start_vyoslinter -5 Type the commands : +5. Run the following commands: .. code-block:: none @@ -71,23 +86,27 @@ Terraform Ansible +^^^^^^^ +1. Create an UNIX instance either locally or in the cloud. -1 Create an UNIX instance whenever you want (local, cloud, and so on) +2. Download and install Ansible -2 Download and install Ansible +3. Create the folder for example /root/google/ -3 Create the folder for example /root/google/ +4. Copy all files into your Ansible project ``/root/google/`` + (``ansible.cfg``, ``instance.yml``, ``mykey.json``, and ``all``). For more + details, see `Structure of files in Ansible for Google Cloud`_ -4 Copy all files into your Ansible project "/root/google/" (ansible.cfg, instance.yml, mykey.json and "all"), more detailed see `Structure of files Ansible for Google Cloud`_ +You obtain ``mykey.json`` when you create a service account in GCP +and download the key (a JSON file). -mykey.json you have to get using step 2 of the Google Cloud +Deploy with Terraform +^^^^^^^^^^^^^^^^^^^^^ -Start - -Type the commands on your Terraform instance: +Run the following commands on your Terraform instance: .. code-block:: none @@ -97,8 +116,8 @@ Type the commands on your Terraform instance: yes -Start creating a Google Cloud instance and check the result. ------------------------------------------------------------ +Create a GCP instance and check its configuration +------------------------------------------------- .. code-block:: none @@ -330,8 +349,9 @@ Start creating a Google Cloud instance and check the result. -After executing all the commands, you will have your VyOS instance on the Google Cloud with your configuration; it's a very convenient decision. -If you need to delete the instance, please type the command: +After running all the commands, your VyOS instance is deployed on +GCP with your specified configuration. +To delete the instance, type the following command: .. code-block:: none @@ -341,10 +361,12 @@ If you need to delete the instance, please type the command: Troubleshooting --------------- -1 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. +1. Increase the timeout value in ``instance.yml`` from 300 seconds to + 500 seconds or more (depends on your location). Ensure that the + security group allows access to the instance. -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 +2. If Terraform doesn't connect via SSH to your Ansible instance: + Check the correct login and password in the ``VyOS.tf`` file. .. code-block:: none @@ -356,25 +378,25 @@ Make sure that you have opened access to the instance in the security group. } -Make sure that Ansible is pinging from Terrafom. +Verify that Ansible can ping from Terraform. -Structure of files Terrafom for Google Cloud --------------------------------------------- +Structure of files in Terraform for Google Cloud +------------------------------------------------ .. code-block:: none . ├── vyos.tf # The main script - ├── ***.JSON # The credential file from Google Cloud + ├── ***.JSON # The credential file from GCP ├── var.tf # The file of all variables in "vyos.tf" └── terraform.tfvars # The value of all variables (passwords, login, IP addresses and so on) -File contents of Terrafom for Google Cloud ------------------------------------------- +File contents of Terraform for Google Cloud +------------------------------------------- -vyos.tf +``vyos.tf`` .. code-block:: none @@ -535,7 +557,7 @@ vyos.tf } -var.tf +``var.tf`` .. code-block:: none @@ -553,7 +575,7 @@ var.tf } ############################################################################## - # You can choose more chipper type than n2-highcpu-4 + # You can choose a lower cost machine type than n2-highcpu-4 ############################################################################## variable "machine_type" { @@ -620,7 +642,7 @@ var.tf } -terraform.tfvars +``terraform.tfvars`` .. code-block:: none @@ -635,8 +657,8 @@ terraform.tfvars host = "" # IP of my Ansible -Structure of files Ansible for Google Cloud -------------------------------------------- +Structure of files in Ansible for Google Cloud +---------------------------------------------- .. code-block:: none @@ -650,7 +672,7 @@ Structure of files Ansible for Google Cloud File contents of Ansible for Google Cloud ----------------------------------------- -ansible.cfg +``ansible.cfg`` .. code-block:: none @@ -659,7 +681,7 @@ ansible.cfg host_key_checking= False remote_user=vyos -instance.yml +``instance.yml`` .. code-block:: none @@ -667,7 +689,7 @@ instance.yml # 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 Google Cloud VyOS node - # You have to add all necessary cammans of VyOS under the block "lines:" + # Add all necessary VyOS commands under the "lines:" block ############################################################################## @@ -690,7 +712,7 @@ instance.yml true -group_vars/all +``group_vars/all`` .. code-block:: none @@ -699,10 +721,12 @@ group_vars/all ansible_user: vyos ansible_ssh_pass: vyos -Sourse files for Google Cloud from GIT --------------------------------------- - -All files about the article can be found here_ +Source files on GitHub +---------------------- +All files related to deploying VyOS on Google Cloud Platform with +Terraform and Ansible can be found in the vyos-automation_ repository. -.. _here: https://github.com/vyos/vyos-automation/tree/main/TerraformCloud/Google_terraform_ansible_single_vyos_instance-main +.. stop_vyoslinter +.. _vyos-automation: https://github.com/vyos/vyos-automation/tree/main/TerraformCloud/Google_terraform_ansible_single_vyos_instance-main +.. start_vyoslinter diff --git a/docs/automation/terraform/terraformvSphere.rst b/docs/automation/terraform/terraformvSphere.rst index 5d39261b..1866fa8e 100644 --- a/docs/automation/terraform/terraformvSphere.rst +++ b/docs/automation/terraform/terraformvSphere.rst @@ -1,45 +1,61 @@ -:lastproofread: 2024-03-03 +:lastproofread: 2026-03-23 .. _terraformvSphere: -Deploying VyOS in the vSphere infrastructure -============================================ +Deploy VyOS on VMware vSphere with Terraform and Ansible +======================================================== -With the help of Terraform, you can quickly deploy VyOS-based infrastructure in the vSphere. -Also we will make provisioning using Ansible. +You can use Terraform to quickly deploy VyOS-based infrastructure +on VMware vSphere (hereafter referred to as *vSphere*) and remove +infrastructure when it's no longer needed. +Additionally, you can use Ansible for provisioning. -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. +On this page you'll learn how to: -Preparation steps for deploying VyOS on vSphere ------------------------------------------------ +* Create the necessary files for Terraform and Ansible. +* Use Terraform to create a single instance on Azure and use Ansible for + provisioning. -How to create a single instance and install your configuration using Terraform+Ansible+vSphere -Step by step: +Prepare to deploy VyOS with Terraform on vSphere +------------------------------------------------ +To create a single instance and install your configuration using +Terraform, Ansible, and vSphere, follow these steps: vSphere +^^^^^^^ - 1 Collect all data in to file "terraform.tfvars" and create resources for example "terraform" +.. stop_vyoslinter +1. Add all necessary data to the ``terraform.tfvars`` + `file <https://github.com/vyos/vyos-automation/blob/main/TerraformCloud/Vsphere_terraform_ansible_single_vyos_instance-main/terraform.tfvars>`__ + and create resources. + +.. start_vyoslinter Terraform +^^^^^^^^^ - 1 Create an UNIX or Windows instance +1. Create an UNIX or Windows instance. - 2 Download and install Terraform +2. Download and install + `Terraform <https://developer.hashicorp.com/terraform/install>`__. - 3 Create the folder for example /root/vsphereterraform +3. Create the folder for example ``/root/vsphereterraform``. .. code-block:: 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`_ +4. Copy all files into your Terraform project ``/root/vsphereterraform`` + (``vyos.tf``, ``var.tf``, ``terraform.tfvars``, ``version.tf``). + For more details, + see `Structure of files in Terraform for vSphere`_ - 5 Type the commands : +5. Run the following commands: .. code-block:: none @@ -48,21 +64,25 @@ Terraform Ansible +^^^^^^^ - 1 Create an UNIX instance whenever you want (local, cloud, and so on) +1. Create an UNIX instance either locally or in the cloud. - 2 Download and install Ansible +2. Download and install Ansible. - 3 Create the folder for example /root/vsphereterraform/ +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`_ +4. Copy all files into your Ansible project ``/root/vsphereterraform/`` + (``ansible.cfg``, ``instance.yml``, ``all``). For more details, see + `Structure of files in Ansible for vSphere`_ -Start +Deploy with Terraform +^^^^^^^^^^^^^^^^^^^^^ -Type the commands on your Terrafom instance: +Run the following commands on your Terraform instance: .. code-block:: none @@ -72,30 +92,31 @@ Type the commands on your Terrafom instance: 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: - +After executing these commands, your VyOS instance is deployed to +vSphere with your configuration. +If you need to delete the instance, run the following command: .. code-block:: none terraform destroy -Structure of files Terrafom for vSphere ---------------------------------------- +Structure of files in Terraform for vSphere +------------------------------------------- .. code-block:: 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) + ├── vyos.tf # The main script. + ├── versions.tf # File for Terraform version. + ├── var.tf # File for Terraform version. + └── terraform.tfvars # Values for all variables (passwords, + # login, IP addresses, etc.). -File contents of Terrafom for vSphere -------------------------------------- +File contents of Terraform for vSphere +-------------------------------------- -vyos.tf +``vyos.tf`` .. code-block:: none @@ -220,7 +241,7 @@ vyos.tf } -versions.tf +``versions.tf`` .. code-block:: none @@ -236,7 +257,7 @@ versions.tf } } -var.tf +``var.tf`` .. code-block:: none @@ -280,17 +301,17 @@ var.tf } variable "host" { - description = "name if yor host" + description = "Name of your host" type = string } variable "remotename" { - description = "the name of you VM" + description = "The name of your VM" type = string } variable "url_ova" { - description = "the URL to .OVA file or cloude store" + description = "The URL to the .OVA file or cloud storage" type = string } @@ -304,7 +325,7 @@ var.tf type = string } -terraform.tfvars +``terraform.tfvars`` .. code-block:: none @@ -322,8 +343,8 @@ terraform.tfvars remotename = "" -Structure of files Ansible for vSphere --------------------------------------- +Structure of files in Ansible for vSphere +----------------------------------------- .. code-block:: none @@ -337,7 +358,7 @@ Structure of files Ansible for vSphere File contents of Ansible for vSphere ------------------------------------ -ansible.cfg +``ansible.cfg`` .. code-block:: none @@ -347,7 +368,7 @@ ansible.cfg remote_user=vyos -instance.yml +``instance.yml`` .. code-block:: none @@ -373,12 +394,13 @@ instance.yml - name: "Configure general settings for the VyOS hosts group" vyos_config: lines: - - set system name-server 8.8.8.8 + - set system name-server 192.0.2.1 + - set system name-server 192.0.2.1 save: true -group_vars/all +``group_vars/all`` .. code-block:: none @@ -391,10 +413,14 @@ group_vars/all ansible_ssh_pass: 12345678 -Sourse files for vSphere from GIT ---------------------------------- +Source files on GitHub +---------------------- + +All files related to deploying VyOS on vSpherewith Terraform and Ansible +can be found in the vyos-automation_ repository. -All files about the article can be found here_ -.. _here: https://github.com/vyos/vyos-automation/tree/main/TerraformCloud/Vsphere_terraform_ansible_single_vyos_instance-main +.. stop_vyoslinter +.. _vyos-automation: https://github.com/vyos/vyos-automation/tree/main/TerraformCloud/Vsphere_terraform_ansible_single_vyos_instance-main +.. start_vyoslinter diff --git a/docs/automation/terraform/terraformvyos.rst b/docs/automation/terraform/terraformvyos.rst deleted file mode 100644 index 42dc7492..00000000 --- a/docs/automation/terraform/terraformvyos.rst +++ /dev/null @@ -1,39 +0,0 @@ -:lastproofread: 2024-03-03 - -.. _terraformvyos: - -Terraform for VyOS -================== - -VyOS supports development infrastructure via Terraform and provisioning via Ansible. -Terraform allows you to automate the process of deploying instances on many cloud and virtual platforms. -In this article, we will look at using terraforms to deploy VyOS on platforms - AWS, Azure, and vSphere. -For more details about Terraform please have a look here link_. - -Need to install_ Terraform - -Structure of files in the standard Terraform project: - -.. code-block:: 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 - - -.. code-block:: 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 - - -.. _link: https://developer.hashicorp.com/terraform/intro -.. _install: https://developer.hashicorp.com/terraform/tutorials/aws-get-started/install-cli
\ No newline at end of file diff --git a/docs/automation/vyos-ansible.rst b/docs/automation/vyos-ansible.rst index 0ebcb924..993d1b21 100644 --- a/docs/automation/vyos-ansible.rst +++ b/docs/automation/vyos-ansible.rst @@ -2,8 +2,9 @@ .. _vyos-ansible: +####### Ansible -======= +####### VyOS supports configuration via ansible. Need to install ``ansible`` and ``python3-paramiko`` module diff --git a/docs/automation/vyos-govyos.rst b/docs/automation/vyos-govyos.rst index 32222441..659c2b6e 100644 --- a/docs/automation/vyos-govyos.rst +++ b/docs/automation/vyos-govyos.rst @@ -2,17 +2,21 @@ .. _vyos-govyos: +####### go-vyos -======= +####### go-vyos is a Go library designed for interacting with VyOS devices through their REST API. This documentation is intended to guide you in using go-vyos for programmatic management of your VyOS devices. -- `go-vyos Documentation & Source Code on GitHub <https://github.com/ganawaj/go-vyos>`_ +- `go-vyos Documentation & Source Code on GitHub + <https://github.com/ganawaj/go-vyos>`_ allows you to access and contribute to the library's code. -- `go-vyos on pkg.go.dev <https://pkg.go.dev/github.com/ganawaj/go-vyos@v0.1.0/vyos>`_ for detailed instructions - on the installation, configuration, and operation of the go-vyos library. +- `go-vyos on pkg.go.dev + <https://pkg.go.dev/github.com/ganawaj/go-vyos@v0.1.0/vyos>`_ + for detailed instructions on the installation, configuration, and + operation of the go-vyos library. Installation @@ -30,11 +34,15 @@ Getting Started Importing and Disabling TLS Verification ------------------------------------------------- +.. stop_vyoslinter + .. code-block:: none import "github.com/ganawaj/go-vyos/vyos" client := vyos.NewClient(nil).WithToken("AUTH_KEY").WithURL("https://192.168.0.1").Insecure() +.. start_vyoslinter + Initializing a VyDevice Object ------------------------------ @@ -64,6 +72,8 @@ Using go-vyos Configure, then Set ^^^^^^^^^^^^^^^^^^^^^^^^ +.. stop_vyoslinter + .. code-block:: none out, resp, err := c.Conf.Set(ctx, "interfaces ethernet eth0 address 192.168.1.1/24") @@ -73,6 +83,8 @@ Configure, then Set fmt.Println(out.Success) +.. start_vyoslinter + Show a Single Object Value ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ diff --git a/docs/automation/vyos-napalm.rst b/docs/automation/vyos-napalm.rst index 75e20b3c..dc4d154f 100644 --- a/docs/automation/vyos-napalm.rst +++ b/docs/automation/vyos-napalm.rst @@ -2,8 +2,9 @@ .. _vyos-napalm: +###### Napalm -====== +###### VyOS supports some napalm_ functions for configuration and op-mode. It requires more tests. diff --git a/docs/automation/vyos-netmiko.rst b/docs/automation/vyos-netmiko.rst index 075b0f34..53082e52 100644 --- a/docs/automation/vyos-netmiko.rst +++ b/docs/automation/vyos-netmiko.rst @@ -2,8 +2,9 @@ .. _vyos-netmiko: +####### Netmiko -======= +####### VyOS supports configuration via netmiko_. It requires to install ``python3-netmiko`` module. diff --git a/docs/automation/vyos-pyvyos.rst b/docs/automation/vyos-pyvyos.rst index 948534f8..c178aeb6 100644 --- a/docs/automation/vyos-pyvyos.rst +++ b/docs/automation/vyos-pyvyos.rst @@ -2,8 +2,9 @@ .. _vyos-pyvyos: +###### pyvyos -====== +###### pyvyos is a Python library designed for interacting with VyOS devices through their API. This documentation is intended to guide you in using pyvyos for diff --git a/docs/automation/vyos-salt.rst b/docs/automation/vyos-salt.rst index 12be32a1..3a5b17d7 100644 --- a/docs/automation/vyos-salt.rst +++ b/docs/automation/vyos-salt.rst @@ -4,8 +4,9 @@ .. include:: /_include/need_improvement.txt +#### Salt -==== +#### VyOS supports op-mode and configuration via salt_. @@ -172,6 +173,8 @@ Examples Example of op-mode: +.. stop_vyoslinter + .. code-block:: none / # salt r11-proxy netmiko.send_command 'show interfaces ethernet eth0 brief' host=192.0.2.14 device_type=vyos username=vyos password=vyos @@ -180,10 +183,14 @@ Example of op-mode: Interface IP Address S/L Description --------- ---------- --- ----------- eth0 192.0.2.14/24 u/u Upstream - / # + / # + +.. start_vyoslinter Example of configuration: +.. stop_vyoslinter + .. code-block:: 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 @@ -196,7 +203,12 @@ Example of configuration: vyos@r14# / # -Example of configuration commands from the file "/srv/salt/states/commands.txt" +.. start_vyoslinter + +Example of configuration commands from the file +"/srv/salt/states/commands.txt" + +.. stop_vyoslinter .. code-block:: none @@ -212,5 +224,9 @@ Example of configuration commands from the file "/srv/salt/states/commands.txt" vyos@r1# / # +.. start_vyoslinter + .. _salt: https://docs.saltproject.io/en/latest/contents.html -.. _netmiko: https://docs.saltproject.io/en/latest/ref/modules/all/salt.modules.netmiko_mod.html#module-salt.modules.netmiko_mod
\ No newline at end of file +.. stop_vyoslinter +.. _netmiko: https://docs.saltproject.io/en/latest/ref/modules/all/salt.modules.netmiko_mod.html#module-salt.modules.netmiko_mod +.. start_vyoslinter
\ No newline at end of file diff --git a/docs/changelog/1.2.1.rst b/docs/changelog/1.2.1.rst deleted file mode 100644 index 4f22dd0a..00000000 --- a/docs/changelog/1.2.1.rst +++ /dev/null @@ -1,52 +0,0 @@ -1.2.1 -===== - -VyOS 1.2.1 is a maintenance release made in April 2019. - -Resolved issues ---------------- - -* Package updates: kernel 4.19.32, open-vm-tools 10.3, latest Intel NIC drivers -* :vytask:`T1326` The kernel now includes drivers for various USB serial - adapters, which allows people to add a serial console to a machine without - onboard RS232, or connect to something else from the router -* The collection of network card firmware is now much more extensive -* :vytask:`T1271` VRRP now correctly uses a virtual rather than physical MAC - addresses in the RFC-compliant mode -* :vytask:`T1330` DHCP WPAD URL option works correctly again -* :vytask:`T1312` Many to many NAT rules now can use source/destination and - translation networks of non-matching size. If 1:1 network bits translation is - desired, it's now users responsibility to check if prefix length matches. -* :vytask:`T1290` IPv6 network prefix translation is fixed -* :vytask:`T1308` Non-alphanumeric characters such as ``>`` can now be safely - used in PPPoE passwords -* :vytask:`T1305` ``show | commands`` no longer fails when a config section ends - with a leaf node such as ``timezone`` in ``show system | commands`` -* :vytask:`T1235` ``show | commands`` correctly works in config mode now -* :vytask:`T1298` VTI is now compatible with the DHCP-interface IPsec option -* :vytask:`T1277` ``show dhcp server statistics`` command was broken in latest - Crux -* :vytask:`T1261` An issue with TFTP server refusing to listen on addresses - other than loopback was fixed -* :vytask:`T1224` Template issue that might cause UDP broadcast relay fail to - start is fixed -* :vytask:`T1067` VXLAN value validation is improved -* :vytask:`T1211` Blank hostnames in DHCP updates no longer can crash DNS - forwarding -* :vytask:`T1322` Correct configuration is now generated for DHCPv6 relays with - more than one upstream interface -* :vytask:`T1234` ``relay-agents-packets`` option works correctly now -* :vytask:`T1231` Dynamic DNS data is now cleaned on configuration change -* :vytask:`T1282` Remote Syslog can now use a fully qualified domain name -* :vytask:`T1279` ACPI power off works again -* :vytask:`T1247` Negation in WAN load balancing rules works again -* :vytask:`T1218` FRR staticd now starts on boot correctly -* :vytask:`T1296` The installer now correctly detects SD card devices -* :vytask:`T1225` Wireguard peers can be disabled now -* :vytask:`T1217` The issue with Wireguard interfaces impossible to delete - is fixed -* :vytask:`T1160` Unintended IPv6 access is fixed in SNMP configuration -* :vytask:`T1060` It's now possible to exclude hosts from the transparent - web proxy -* :vytask:`T484` An issue with rules impossible to delete from the zone-based - firewall is fixed
\ No newline at end of file diff --git a/docs/changelog/1.2.2.rst b/docs/changelog/1.2.2.rst deleted file mode 100644 index 17ba941f..00000000 --- a/docs/changelog/1.2.2.rst +++ /dev/null @@ -1,46 +0,0 @@ -1.2.2 -===== - -1.2.2 is a maintenance release made in July 2019. - -New features ------------- - -* Options for per-interface MSS clamping. -* BGP extended next-hop capability -* Relaxed BGP multipath option -* Internal and external options for "remote-as" (accept any AS as long as it's - the same to this router or different, respectively) -* "Unnumbered" (interface-based) BGP peers -* BGP no-prepend option -* Additive BGP community option -* OSPFv3 network type option -* Custom arguments for VRRP scripts -* A script for querying values from config files - -Resolved issues ---------------- - -* Linux kernel 4.19.54, including a fix for the TCP SACK vulnerability -* :vytask:`T1371` VRRP health-check scripts now can use arguments -* :vytask:`T1497` DNS server addresses coming from a DHCP server are now - correctly propagated to resolv.conf -* :vytask:`T1469` Domain-specific name servers in DNS forwarding are now used - for recursive queries -* :vytask:`T1433` ``run show dhcpv6 server leases`` now display leases correctly -* :vytask:`T1461` Deleting ``firewall options`` node no longer causes errors -* :vytask:`T1458` Correct hostname is sent to remote syslog again -* :vytask:`T1438` Board serial number from DMI is correctly displayed in - ``show version`` -* :vytask:`T1358`, :vytask:`T1355`, :vytask:`T1294` Multiple corrections in - remote syslog config -* :vytask:`T1255` Fixed missing newline in ``/etc/hosts`` -* :vytask:`T1174` ``system domain-name`` is correctly included in - ``/etc/resolv.conf`` -* :vytask:`T1465` Fixed priority inversion in ``interfaces vti vtiX ip`` - settings -* :vytask:`T1446` Fixed errors when installing with RAID1 on UEFI machines -* :vytask:`T1387` Fixed an error on disabling an interfaces that has no address -* :vytask:`T1367` Fixed deleting VLAN interface with non-default MTU -* :vytask:`T1505` vyos.config ``return_effective_values()`` function now - correctly returns a list rather than a string
\ No newline at end of file diff --git a/docs/changelog/1.2.3.rst b/docs/changelog/1.2.3.rst deleted file mode 100644 index 653beec1..00000000 --- a/docs/changelog/1.2.3.rst +++ /dev/null @@ -1,62 +0,0 @@ -1.2.3 -===== - -1.2.3 is a maintenance and feature backport release made in September 2019. - -New features ------------- - -* HTTP API -* :vytask:`T1524` "set service dns forwarding allow-from <IPv4 net|IPv6 net>" - option for limiting queries to specific client networks -* :vytask:`T1503` Functions for checking if a commit is in progress -* :vytask:`T1543` "set system contig-mangement commit-archive source-address" - option -* :vytask:`T1554` Intel NIC drivers now support receive side scaling and - multiqueue - -Resolved issues ---------------- - -* :vytask:`T1209` OSPF max-metric values over 100 no longer causes commit - errors -* :vytask:`T1333` Fixes issue with DNS forwarding not performing recursive - lookups on domain specific forwarders -* :vytask:`T1362` Special characters in VRRP passwords are handled correctly -* :vytask:`T1377` BGP weight is applied properly -* :vytask:`T1420` Fixed permission for log files -* :vytask:`T1425` Wireguard interfaces now support /31 addresses -* :vytask:`T1428` Wireguard correctly handles firewall marks -* :vytask:`T1439` DHCPv6 static mappings now work correctly -* :vytask:`T1450` Flood ping commands now works correctly -* :vytask:`T1460` Op mode "show firewall" commands now support counters longer - than 8 digits (T1460) -* :vytask:`T1465` Fixed priority inversion in VTI commands -* :vytask:`T1468` Fixed remote-as check in the BGP route-reflector-client option -* :vytask:`T1472` It's now possible to re-create VRRP groups with RFC - compatibility mode enabled -* :vytask:`T1527` Fixed a typo in DHCPv6 server help strings -* :vytask:`T1529` Unnumbered BGP peers now support VLAN interfaces -* :vytask:`T1530` Fixed "set system syslog global archive file" command -* :vytask:`T1531` Multiple fixes in cluster configuration scripts -* :vytask:`T1537` Fixed missing help text for "service dns" -* :vytask:`T1541` Fixed input validation in DHCPv6 relay options -* :vytask:`T1551` It's now possible to create a QinQ interface and a firewall - assigned to it in one commit -* :vytask:`T1559` URL filtering now uses correct rule database path and works - again -* :vytask:`T1579` "show log vpn ipsec" command works again -* :vytask:`T1576` "show arp interface <intf>" command works again -* :vytask:`T1605` Fixed regression in L2TP/IPsec server -* :vytask:`T1613` Netflow/sFlow captures IPv6 traffic correctly -* :vytask:`T1616` "renew dhcpv6" command now works from op mode -* :vytask:`T1642` BGP remove-private-as option iBGP vs eBGP check works - correctly now -* :vytask:`T1540`, :vytask:`T1360`, :vytask:`T1264`, :vytask:`T1623` Multiple - improvements in name servers and hosts configuration handling - -Internals ---------- - -``/etc/resolv.conf`` and ``/etc/hosts`` files are now managed by the -*vyos-hostsd* service that listens on a ZMQ socket for update messages.
\ No newline at end of file diff --git a/docs/changelog/1.2.4.rst b/docs/changelog/1.2.4.rst deleted file mode 100644 index 3e228880..00000000 --- a/docs/changelog/1.2.4.rst +++ /dev/null @@ -1,77 +0,0 @@ -1.2.4 -===== - -1.2.4 is a maintenance release made in December 2019. - -Resolved issues ---------------- - -* :vytask:`T258` Can not configure wan load-balancing on vyos-1.2 -* :vytask:`T818` SNMP v3 - remove required engineid from user node -* :vytask:`T1030` Upgrade ddclient from 3.8.2 to 3.9. - (support Cloudflare API v4) -* :vytask:`T1183` BFD Support via FRR -* :vytask:`T1299` Allow SNMPd to be extended with custom scripts -* :vytask:`T1351` accel-pppoe adding CIDR based IP pool option -* :vytask:`T1391` In route-map set community additive -* :vytask:`T1394` syslog systemd and host_name.py race condition -* :vytask:`T1401` Copying files with the FTP protocol fails if the passwor - contains special characters -* :vytask:`T1421` OpenVPN client push-route stopped working, needs added quotes - to fix -* :vytask:`T1430` Add options for custom DHCP client-id and hostname -* :vytask:`T1447` Python subprocess called without import in host_name.py -* :vytask:`T1470` improve output of "show dhcpv6 server leases" -* :vytask:`T1485` Enable 'AdvIntervalOpt' option in for radvd.conf -* :vytask:`T1496` Separate rolling release and LTS kernel builds -* :vytask:`T1560` "set load-balancing wan rule 0" causes segfault and prevent - load balancing from starting -* :vytask:`T1568` strip-private command improvement for additional masking o - IPv6 and MAC address -* :vytask:`T1578` completion offers "show table", but show table does not exist -* :vytask:`T1593` Support ip6gre -* :vytask:`T1597` /usr/sbin/rsyslogd after deleting "system syslog" -* :vytask:`T1638` vyos-hostsd not setting system domain name -* :vytask:`T1678` hostfile-update missing line feed -* :vytask:`T1694` NTPd: Do not listen on all interfaces by default -* :vytask:`T1701` Delete domain-name and domain-search won't work -* :vytask:`T1705` High CPU usage by bgpd when snmp is active -* :vytask:`T1707` DHCP static mapping and exclude address not working -* :vytask:`T1708` Update Rolling Release Kernel to 4.19.76 -* :vytask:`T1709` Update WireGuard to 0.0.20190913 -* :vytask:`T1716` Update Intel NIC drivers to recent versions -* :vytask:`T1726` Update Linux Firmware binaries to a more recen - version 2019-03-14 -> 2019-10-07 -* :vytask:`T1728` Update Linux Kernel to 4.19.79 -* :vytask:`T1737` SNMP tab completion missing -* :vytask:`T1738` Copy SNMP configuration from node to node raises exception -* :vytask:`T1740` Broken OSPFv2 virtual-link authentication -* :vytask:`T1742` NHRP unable to commit. -* :vytask:`T1745` dhcp-server commit fails with "DHCP range stop address - must be greater or equal to the range start address y!" when static mapping - has same IP as range stop -* :vytask:`T1749` numeric validator doesn't support multiple ranges -* :vytask:`T1769` Remove complex SNMPv3 Transport Security Model (TSM) -* :vytask:`T1772` <regex> constraints in XML are partially broken -* :vytask:`T1778` Kilobits/Megabits difference in configuration Vyos/FRR -* :vytask:`T1780` Adding ipsec ike closeaction -* :vytask:`T1786` disable-dhcp-nameservers is missed in current host_name.p - implementation -* :vytask:`T1788` Intel QAT (QuickAssist Technology ) implementation -* :vytask:`T1792` Update WireGuard to Debian release 0.0.20191012-1 -* :vytask:`T1800` Update Linux Kernel to v4.19.84 -* :vytask:`T1809` Wireless: SSID scan does not work in AP mode -* :vytask:`T1811` Upgrade from 1.1.8: Config file migratio - failed: module=l2tp -* :vytask:`T1812` DHCP: hostnames of clients not resolving afte - update v1.2.3 -> 1.2-rolling -* :vytask:`T1819` Reboot kills SNMPv3 configuration -* :vytask:`T1822` Priority inversion wireless interface dhcpv6 -* :vytask:`T1825` Improve DHCP configuration error message -* :vytask:`T1836` import-conf-mode-commands in vyos-1x/scripts fails - to create an xml -* :vytask:`T1839` LLDP shows "VyOS unknown" instead of "VyOS" -* :vytask:`T1841` PPP ipv6-up.d direcotry missing -* :vytask:`T1893` igmp-proxy: Do not allow adding unknown interface -* :vytask:`T1903` Implementation udev predefined interface naming -* :vytask:`T1904` update eth1 and eth2 link files for the vep4600
\ No newline at end of file diff --git a/docs/changelog/1.2.5.rst b/docs/changelog/1.2.5.rst deleted file mode 100644 index 438e84f2..00000000 --- a/docs/changelog/1.2.5.rst +++ /dev/null @@ -1,70 +0,0 @@ -1.2.5 -===== - -1.2.5 is a maintenance release made in April 2020. - -Resolved issues ---------------- - -* :vytask:`T1020` OSPF Stops distributing default route after a while -* :vytask:`T1228` pppoe default-route force option not working (Rel 1.2.0-rc11) -* :vytask:`T1301` bgp peer-groups don't work when "no-ipv4-unicast" is enabled. -* :vytask:`T1341` Adding rate-limiter for pppoe server users -* :vytask:`T1376` Incorrect DHCP lease counting -* :vytask:`T1392` Large firewall rulesets cause the system to lose configuration - and crash at startup -* :vytask:`T1416` 2 dhcp server run in failover mode can't sync hostname with - each other -* :vytask:`T1452` accel-pppoe - add vendor option to shaper -* :vytask:`T1490` BGP configuration (is lost|not applied) when updating - 1.1.8 -> 1.2.1 -* :vytask:`T1780` Adding ipsec ike closeaction -* :vytask:`T1803` Unbind NTP while it's not requested... -* :vytask:`T1821` "authentication mode radius" has no effect for PPPoE server -* :vytask:`T1827` Increase default gc_thresh -* :vytask:`T1828` Missing completion helper for "set system syslog host - 192.0.2.1 facility all protocol" -* :vytask:`T1832` radvd adding feature DNSSL branch.example.com example.com to - existing package -* :vytask:`T1837` PPPoE unrecognized option 'replacedefaultroute' -* :vytask:`T1851` wireguard - changing the pubkey on an existing peer seems to - destroy the running config. -* :vytask:`T1858` l2tp: Delete depricated outside-nexthop and add gateway-address -* :vytask:`T1864` Lower IPSec DPD timeout lower limit from 10s -> 2s -* :vytask:`T1879` Extend Dynamic DNS XML definition value help strings and - validators -* :vytask:`T1881` Execute permissions are removed from custom SNMP scripts at - commit time -* :vytask:`T1884` Keeping VRRP transition-script native behaviour and adding - stop-script -* :vytask:`T1891` Router announcements broken on boot -* :vytask:`T1900` Enable SNMP for VRRP. -* :vytask:`T1902` Add redistribute non main table in bgp -* :vytask:`T1909` Incorrect behaviour of static routes with overlapping networks -* :vytask:`T1913` "system ipv6 blacklist" command has no effect -* :vytask:`T1914` IPv6 multipath hash policy does not apply -* :vytask:`T1917` Update WireGuard to Debian release 0.0.20191219-1 -* :vytask:`T1934` Change default hostname when deploy from OVA without params. -* :vytask:`T1935` NIC identification and usage problem in Hyper-V environments -* :vytask:`T1936` pppoe-server CLI control features -* :vytask:`T1964` SNMP Script-extensions allows names with spaces, but commit - fails -* :vytask:`T1967` BGP parameter "enforce-first-as" does not work anymore -* :vytask:`T1970` Correct adding interfaces on boot -* :vytask:`T1971` Missing modules in initrd.img for PXE boot -* :vytask:`T1998` Update FRR to 7.3 -* :vytask:`T2001` Error when router reboot -* :vytask:`T2032` Monitor bandwidth bits -* :vytask:`T2059` Set source-validation on bond vif don't work -* :vytask:`T2066` PPPoE interface can be created multiple times - last wins -* :vytask:`T2069` PPPoE-client does not works with service-name option -* :vytask:`T2077` ISO build from crux branch is failing -* :vytask:`T2079` Update Linux Kernel to v4.19.106 -* :vytask:`T2087` Add maxfail 0 option to pppoe configuration. -* :vytask:`T2100` BGP route adverisement wih checks rib -* :vytask:`T2120` "reset vpn ipsec-peer" doesn't work with named peers -* :vytask:`T2197` Cant add vif-s interface into a bridge -* :vytask:`T2228` WireGuard does not allow ports < 1024 to be used -* :vytask:`T2252` HTTP API add system image can return '504 Gateway Time-out' -* :vytask:`T2272` Set system flow-accounting disable-imt has syntax error -* :vytask:`T2276` PPPoE server vulnerability
\ No newline at end of file diff --git a/docs/changelog/1.2.6.rst b/docs/changelog/1.2.6.rst deleted file mode 100644 index 70786d07..00000000 --- a/docs/changelog/1.2.6.rst +++ /dev/null @@ -1,108 +0,0 @@ -1.2.6-S1 -======== - -1.2.6-S1 is a security release release made in September 2020. - -Resolved issues ---------------- - -VyOS 1.2.6 release was found to be suspectible to CVE-2020-10995. It's a low- -impact vulnerability in the PowerDNS recursor that allows an attacker to cause -performance degradation via a specially crafted authoritative DNS server reply. - -* :vytask:`T2899` remote syslog server migration error on update - -1.2.6 -===== - -1.2.6 is a maintenance release made in September 2020. - -.. _resovled issues 1.2.6: - -Resolved issues ---------------- - -* :vytask:`T103` DHCP server prepends shared network name to hostnames -* :vytask:`T125` Missing PPPoE interfaces in l2tp configuration -* :vytask:`T1194` cronjob is being setup even if not saved -* :vytask:`T1205` module pcspkr missing -* :vytask:`T1219` Redundant active-active configuration, asymmetric routing and - conntrack-sync cache -* :vytask:`T1220` Show transceiver information from plugin modules, e.g SFP+, - QSFP -* :vytask:`T1221` BGP - Default route injection is not processed by the specific - route-map -* :vytask:`T1241` Remove of policy route throws CLI error -* :vytask:`T1291` Under certain conditions the VTI will stay forever down -* :vytask:`T1463` Missing command `show ip bgp scan` appears in command - completion -* :vytask:`T1575` `show snmp mib ifmib` crashes with IndexError -* :vytask:`T1699` Default net.ipv6.route.max_size 32768 is too low -* :vytask:`T1729` PIM (Protocol Independent Multicast) implementation -* :vytask:`T1901` Semicolon in values is interpreted as a part of the shell - command by validators -* :vytask:`T1934` Change default hostname when deploy from OVA without params. -* :vytask:`T1938` syslog doesn't start automatically -* :vytask:`T1949` Multihop IPv6 BFD is unconfigurable -* :vytask:`T1953` DDNS service name validation rejects valid service names -* :vytask:`T1956` PPPoE server: support PADO-delay -* :vytask:`T1973` Allow route-map to match on BGP local preference value -* :vytask:`T1974` Allow route-map to set administrative distance -* :vytask:`T1982` Increase rotation for atop.acct -* :vytask:`T1983` Expose route-map when BGP routes are programmed in to FIB -* :vytask:`T1985` pppoe: Enable ipv6 modules without configured ipv6 pools -* :vytask:`T2000` strongSwan does not install routes to table 220 in certain - cases -* :vytask:`T2021` OSPFv3 doesn't support decimal area syntax -* :vytask:`T2062` Wrong dhcp-server static route subnet bytes -* :vytask:`T2091` swanctl.conf file is not generated properly is more than one - IPsec profile is used -* :vytask:`T2131` Improve syslog remote host CLI definition -* :vytask:`T2224` Update Linux Kernel to v4.19.114 -* :vytask:`T2286` IPoE server vulnerability -* :vytask:`T2303` Unable to delete the image version that came from OVA -* :vytask:`T2305` Add release name to "show version" command -* :vytask:`T2311` Statically configured name servers may not take precedence - over ones from DHCP -* :vytask:`T2327` Unable to create syslog server entry with different port -* :vytask:`T2332` Backport node option for a syslog server -* :vytask:`T2342` Bridge l2tpv3 + ethX errors -* :vytask:`T2344` PPPoE server client static IP assignment silently fails -* :vytask:`T2385` salt-minion: improve completion helpers -* :vytask:`T2389` BGP community-list unknown command -* :vytask:`T2398` op-mode "dhcp client leases interface" completion helper - misses interfaces -* :vytask:`T2402` Live ISO should warn when configuring that changes won't - persist -* :vytask:`T2443` NHRP: Add debugging information to syslog -* :vytask:`T2448` `monitor protocol bgp` subcommands fail with 'command - incomplete' -* :vytask:`T2458` Update FRR to 7.3.1 -* :vytask:`T2476` Bond member description change leads to network outage -* :vytask:`T2478` login radius: use NAS-IP-Address if defined source address -* :vytask:`T2482` Update PowerDNS recursor to 4.3.1 for CVE-2020-10995 -* :vytask:`T2517` vyos-container: link_filter: No such file or directory -* :vytask:`T2526` Wake-On-Lan CLI implementation -* :vytask:`T2528` "update dns dynamic" throws FileNotFoundError excepton -* :vytask:`T2536` "show log dns forwarding" still refers to dnsmasq -* :vytask:`T2538` Update Intel NIC drivers to recent release (preparation for - Kernel >=5.4) -* :vytask:`T2545` Show physical device offloading capabilities for specified - ethernet interface -* :vytask:`T2563` Wrong interface binding for Dell VEP 1445 -* :vytask:`T2605` SNMP service is not disabled by default -* :vytask:`T2625` Provide generic Library for package builds -* :vytask:`T2686` FRR: BGP: large-community configuration is not applied - properly after upgrading FRR to 7.3.x series -* :vytask:`T2701` `vpn ipsec pfs enable` doesn't work with IKE groups -* :vytask:`T2728` Protocol option ignored for IPSec peers in transport mode -* :vytask:`T2734` WireGuard: fwmark CLI definition is inconsistent -* :vytask:`T2757` "show system image version" contains additional new-line - character breaking output -* :vytask:`T2797` Update Linux Kernel to v4.19.139 -* :vytask:`T2822` Update Linux Kernel to v4.19.141 -* :vytask:`T2829` PPPoE server: mppe setting is implemented as node instead of - leafNode -* :vytask:`T2831` Update Linux Kernel to v4.19.142 -* :vytask:`T2852` rename dynamic dns interface breaks ddclient.cache permissions -* :vytask:`T2853` Intel QAT acceleration does not work
\ No newline at end of file diff --git a/docs/changelog/1.3.rst b/docs/changelog/1.3.rst deleted file mode 100644 index 42a94a63..00000000 --- a/docs/changelog/1.3.rst +++ /dev/null @@ -1,941 +0,0 @@ - -############ -1.3 Eqquleus -############ - -.. - Please don't add anything by hand. - This file is managed by the script: - _ext/releasenotes.py - - -1.3.9 (future release) -====================== - - - - - -**Bug fixes** - - -* :vytask:`T5926` ``IPSEC does not apply after l2tp configuration was changed`` - -**Other resolved issues** - - -* :vytask:`T1311` ``WAN load-balancing can't flush connections when conntrack-sync is enabled`` - -1.3.8 (25th June 2024) -====================== - - - - - -**Bug fixes** - - -* :vytask:`T5725` ``protocol IS-IS configuration is empty if a tunnel does not have remote address`` -* :vytask:`T6337` ``Upgrade from 1.3.5 fails if ssh public key name has a space in it`` -* :vytask:`T6359` ``Multicast does not forward after reboot`` - - -1.3.7 (13th May 2024) -===================== - -**Security** - - -* :vytask:`T6324` ``CVE-2024-2961`` - - - -**New features and improvements** - - -* :vytask:`T1244` ``Add support for StartupResync in conntrack-sync`` -* :vytask:`T5364` ``Make it possible to set the PADO delay to 0`` -* :vytask:`T5418` ``Allow arbitrary subnets in PPPoE client IP pools`` -* :vytask:`T5504` ``Make it possible to set more than one peer-address in unicast VRRP`` -* :vytask:`T6057` ``Add ability to disable syslog for conntrackd`` - -**Bug fixes** - - -* :vytask:`T1751` ``DNS server addresses from DHCPv6 are not added to resolv.conf`` -* :vytask:`T1976` ``deleting address-family under neighbor will disable neighbor`` -* :vytask:`T2044` ``RPKI doesn't boot properly`` -* :vytask:`T2113` ``OpenVPN Options error: you cannot use --verify-x509-name with --compat-names or --no-name-remapping`` -* :vytask:`T2279` ``Router resolves as 127.0.1.1 when using Router's Recursive DNS`` -* :vytask:`T2590` ``DHCPv6 not updating nameservers and search domains since replacing isc-dhcp-client with WIDE dhcp6c`` -* :vytask:`T2612` ``HTTPS API, changing API key fails but goes through`` -* :vytask:`T2801` ``conntrack-tools flooding logs`` -* :vytask:`T2998` ``SNMP v3 oid "exclude" option doesn't work`` -* :vytask:`T3437` ``BGP Confederation Addition Causes Error`` -* :vytask:`T3992` ``Unhandled exception when trying to add an interface with an assigned address to a bridge`` -* :vytask:`T4270` ``When "ignore-hosts-file" is unset, local hostname of the router resolves to 127.0.1.1 in the DNS forwarding service`` -* :vytask:`T4453` ``dhclient fails to renew DHCP lease with VRF`` -* :vytask:`T5239` ``Host name and domain name missing from the FRR configuration`` -* :vytask:`T5982` ``Isolated interfaces smoketest fail`` -* :vytask:`T6004` ``Missing RPKI boot priority prevents it from loading`` -* :vytask:`T6056` ``Applying 'system static-host-mapping' command calls unnecessary snmpd restart`` -* :vytask:`T6088` ``Configuration corrupted after saving and powercut or force reboot`` -* :vytask:`T6096` ``Config commits are not synced properly because 00vyos-sync is deleted by vyos-router`` -* :vytask:`T6110` ``Insufficient validation of range option with failover in DHCP server`` -* :vytask:`T6124` ``Docker equuleus build image doesn't build due to fpm`` -* :vytask:`T6141` ``Trying to set PADO delay in PPPoE server without also configuring the session options causes a commit failure`` -* :vytask:`T6150` ``Impossible to set a static IP address via RADIUS in IPoE`` -* :vytask:`T6193` ``dhcp-client: invalid warning "is not a DHCP interface but uses DHCP name-server option" for VLAN interfaces`` -* :vytask:`T6196` ``route-map and summary-only do not work in BGP aggregation at the same time`` -* :vytask:`T6243` ``Update vyos-http-api-tools for package idna security advisory`` - -**Other resolved issues** - - -* :vytask:`T1198` ``Extra hyphen in suggested image name on upgrade`` -* :vytask:`T3584` ``Migrate NTP server addresses from *.pool.ntp.org to our own`` -* :vytask:`T6261` ``Typo in the operational mode connect and disconnect command output`` - -1.3.6 (14th February 2024) -========================== - -**Security** - - -* :vytask:`T5318` ``Security Vulnerabilities for VyOS 1.3.3`` - - -**Configuration syntax changes (automatically migrated)** - - -* :vytask:`T2060` ``source-validation will be configured at different locations and could lead to massive confusion`` -* :vytask:`T2289` ``Denest cerbot certificate configuration from service https`` - -**New features and improvements** - - -* :vytask:`T1929` ``ipset in firewall`` -* :vytask:`T2060` ``source-validation will be configured at different locations and could lead to massive confusion`` -* :vytask:`T2116` ``Processing configuration via Cloud-init User-Data`` -* :vytask:`T2191` ``Using tallow to block sshd probes`` -* :vytask:`T2289` ``Denest cerbot certificate configuration from service https`` -* :vytask:`T3039` ``Resize a root partition and filesystem automatically during deployment in virtual environments`` -* :vytask:`T4039` ``Rsyslog to use 'protocol23format' for protocol UDP`` -* :vytask:`T4078` ``A hybrid of "network-group" and "address-group".`` -* :vytask:`T5182` ``Update Intel ice driver`` -* :vytask:`T5187` ``Update Realtek r8152 driver`` -* :vytask:`T5275` ``Add op mode commands for exporting certificates to PEM files with correct headers`` -* :vytask:`T5796` ``Openconnect - HTTPS security headers are missing`` - -**Bug fixes** - - -* :vytask:`T117` ``Cannot install from ISO via serial console on ttyS1`` -* :vytask:`T1925` ``DMVPN is always listed as down in "show vpn ipsec sa"`` -* :vytask:`T2085` ``Building some packages with vyos-build no longer works for Equuleus/current`` -* :vytask:`T2163` ``Disabled vif interface with "address dhcp" requests DHCP address`` -* :vytask:`T2404` ``Cannot change MTU`` -* :vytask:`T2509` ``No inotify notifications from /`` -* :vytask:`T2574` ``wan-load-balance snat bug and route problem`` -* :vytask:`T2793` ``compare + TAB completion does not show proper username if user contains _`` -* :vytask:`T2837` ``make-version-file executed too early during build process`` -* :vytask:`T3154` ``route-map CLI allows 32-bit ASNs in community options even though FRR doesn't`` -* :vytask:`T3980` ``vrrp transition-script validator makes warning fatal and also causes a python NameError exception`` -* :vytask:`T4062` ``VRRP IPSEC-AH : sequence number xxxxxxx already processed. Packet dropped. Local(xxxxxxx)`` -* :vytask:`T4566` ``Cannot log in on serial console on Equuleus v1.3.1`` -* :vytask:`T4752` ``ICMP redirects not working / not properly configured`` -* :vytask:`T4760` ``VyOS does not support running multiple instances of DHCPv6 clients`` -* :vytask:`T4990` ``Commit results may not be properly saved if power is cut immediately after a successful commit`` -* :vytask:`T5180` ``initramfs-tools ignores firmware from updates directory`` -* :vytask:`T5543` ``Fix source address handling in static joins`` -* :vytask:`T5625` ``"restart vpn" does not work if ipsec-interfaces is not set`` -* :vytask:`T5739` ``Password recovery does not work if public keys are configured`` -* :vytask:`T5800` ``HTTPS API unavailable after delete VRF`` -* :vytask:`T5852` ``Reboots fail with eapol WAN interface`` -* :vytask:`T5914` ``CVE-2023-48795 - Terrapin vulnerability`` -* :vytask:`T5924` ``Build cannot pass the smoketest dialup-router-medium-vpn`` -* :vytask:`T5967` ``Multi-hop BFD connections can't be established; please add minimum-ttl option.`` -* :vytask:`T6017` ``Update vyos-http-api-tools for security advisory`` - -**Other resolved issues** - - -* :vytask:`T922` ``OSPF - Process Crash after peer reboot`` -* :vytask:`T1297` ``Add GARP settings to VRRP/keepalived`` -* :vytask:`T1369` ``GCP Networking Failure`` -* :vytask:`T1500` ``Slow boot/load and CLI response times`` -* :vytask:`T1667` ``Add a tool for automatically importing old style command definitions into XML`` -* :vytask:`T1671` ``rewrite udev script logic /lib/udev/vyatta_net_name`` -* :vytask:`T1981` ``Allow route-map 'set src' to reference both IPv4 and IPv6`` -* :vytask:`T2223` ``convert operational show interfaces to python/XML`` -* :vytask:`T2353` ``Interface [conf_mode] errors parent task`` -* :vytask:`T2431` ``Python validators are slow`` -* :vytask:`T2452` ``Serial console related issues`` -* :vytask:`T2546` ``The root task for rewriting [op-mode] to XML`` -* :vytask:`T2579` ``The root task for VRF features`` -* :vytask:`T2655` ``ConfigError formatting issue`` -* :vytask:`T2720` ``Rework vyos.template Python module to make future extension easier`` -* :vytask:`T2755` ``Requirements for partial interface setup`` -* :vytask:`T2799` ``VyOS Certificates Manager`` -* :vytask:`T3191` ``PAM RADIUS freezing when accounting does not configured on RADIUS server`` -* :vytask:`T3348` ``dhcpd: Can't create new lease file: Permission denied`` -* :vytask:`T3403` ``Error on interrupting list of pppoe sessions`` -* :vytask:`T3513` ``Attempting to remove firewall rule results in error`` -* :vytask:`T3688` ``Fail to save configuration via scp/sftp`` -* :vytask:`T3737` ``openvpn-option needs to be able to support quotes as since openvpn 2.4.`` -* :vytask:`T3813` ``Some custom sysctl parameters can't be applied bug`` -* :vytask:`T4222` ``Support for TWAMP as round-trip metric`` -* :vytask:`T4646` ``USB serial output console does not work`` -* :vytask:`T5274` ``Add a deprecation warning for OpenVPN site-to-site with pre-shared secret`` -* :vytask:`T5714` ``IPSec VPN: op-mode: "show log vpn" does not show results`` -* :vytask:`T5715` ``IPSec VPN: restart vpn is not working`` -* :vytask:`T6014` ``Bump keepalived version`` -* :vytask:`T6249` ``ISO builder fails because of changed buster-backport repository`` - -1.3.5 (15th December 2023) -========================== - - - -**Configuration syntax changes (automatically migrated)** - - -* :vytask:`T2139` ``openvpn: allow "dh-file none" to disable DH for ECDH keys`` - -**New features and improvements** - - -* :vytask:`T1118` ``Obsolete "utc" option in time selector in firewall`` -* :vytask:`T2014` ``Use vendor specific NTP Pool hostname`` -* :vytask:`T2139` ``openvpn: allow "dh-file none" to disable DH for ECDH keys`` -* :vytask:`T4269` ``node.def generator should automatically add default values`` -* :vytask:`T5213` ``Accel-ppp sending accounting interim updates acct-interim-interval option`` -* :vytask:`T5270` ``Make OpenVPN `tls dh-params` optional`` -* :vytask:`T5271` ``Add support for peer-fingerprint to OpenVPN`` -* :vytask:`T5273` ``Add op mode commands for displaying certificate details and fingerprints`` -* :vytask:`T5387` ``dhcp6c: add a no release option`` -* :vytask:`T5576` ``Add bgp remove-private-as all option`` -* :vytask:`T5586` ``Disable by default SNMP for Keepalived VRRP`` -* :vytask:`T5630` ``pppoe: allow to specify MRU in addition to already configurable MTU`` -* :vytask:`T5661` ``Add show show ssh dynamic-protection attacker and show log ssh dynamic-protection`` - -**Bug fixes** - - -* :vytask:`T305` ``loadbalancing does not work with one pppoe connection and another connection of either dhcp or static`` -* :vytask:`T971` ``authentication public-keys options quoting issue`` -* :vytask:`T1012` ``vyos-build configure script should check /etc/issue to avoid confusion`` -* :vytask:`T2051` ``Throughput anomalies`` -* :vytask:`T2250` ``vyos-build "make iso" error if configure was ran outside of the docker container`` -* :vytask:`T3020` ``The "scp" example is wrong in the bash-completion for "set system config-management commit-archive location"`` -* :vytask:`T3045` ``Changes to Conntrack-Sync don't apply correctly (Mutlicast->UDP)`` -* :vytask:`T3940` ``DHCP client does not remove IP address when stopped by the 02-vyos-stopdhclient hook`` -* :vytask:`T4146` ``Nginx should not listen on port 80`` -* :vytask:`T4328` ``Large MTU on 1.3.1-S1`` -* :vytask:`T4402` ``OpenVPN client-ip-pool option is broken`` -* :vytask:`T4601` ``dhcp : relay agent IP address issue.`` -* :vytask:`T4776` ``NVME storage is not detected properly during installation`` -* :vytask:`T5223` ``tunnel key doesn't clear`` -* :vytask:`T5235` ``SSH keys with special characters cannot be applied via Cloud-init`` -* :vytask:`T5402` ``VRRP router with rfc3768-compatibility sends multiple ARP replies`` -* :vytask:`T5413` ``Deny the opportunity to use one public/private key pair on both wireguard peers.`` -* :vytask:`T5486` ``Service dns dynamic cannot pass the smoketest`` -* :vytask:`T5669` ``VXLAN interface changing port does not work`` -* :vytask:`T5670` ``bridge: missing member interface validator`` -* :vytask:`T5763` ``Fix imprecise check for remote file name in vyos-load-config.py`` -* :vytask:`T5777` ``frr: backport and upstream recent bgpd daemon crashes`` - -**Other resolved issues** - - -* :vytask:`T1276` ``dhcp relay + VLAN fails`` -* :vytask:`T2719` ``Standardized op mode script structure`` -* :vytask:`T3536` ``Unable to list all available routes`` -* :vytask:`T3702` ``Policy: Allow routing by fwmark`` -* :vytask:`T5191` ``Replace underscores with hyphens in command-line options generated by vyos.opmode`` -* :vytask:`T5268` ``OpenVPN: upgrade package to 2.6 series`` -* :vytask:`T5280` ``Update Expired keys (2023-06-08) for PowerDNS`` -* :vytask:`T5578` ``"ikev2-reauth" description contains outdated information`` -* :vytask:`T5624` ``Remove /etc/debian_version from the image`` -* :vytask:`T5632` ``Add jq package to parse JSON files`` -* :vytask:`T5817` ``Show openvpn server fails in some cases`` - -1.3.4 (17th October 2023) -========================= - - - - -**New features and improvements** - - -* :vytask:`T738` ``Add local-port and resolver port options for powerdns in CLI configuration tree`` -* :vytask:`T2123` ``Configure 3 NTP servers`` -* :vytask:`T2424` ``Ability to choose the direction of Mirroring`` -* :vytask:`T3144` ``Support op-mode command to release DHCP leases`` -* :vytask:`T3546` ``Add support for running scripts on PPPoE server session events`` -* :vytask:`T4151` ``IPV6 local PBR Support`` -* :vytask:`T4426` ``Add arpwatch to the image`` -* :vytask:`T4475` ``route-map does not support ipv6 peer`` -* :vytask:`T4825` ``interfaces veth/veth-pairs -standalone used`` -* :vytask:`T5190` ``Cloud-Init cannot fetch Meta-data on machines where the main Ethernet interface is not eth0`` -* :vytask:`T5265` ``WAN load-balancing: missing completion helpers`` -* :vytask:`T5315` ``vrrp: add support for version 3`` -* :vytask:`T5354` ``Add sshguard to protect against brut-forces for 1.3`` - -**Bug fixes** - - -* :vytask:`T2611` ``Prefix list names are shared between ipv4 and ipv6`` -* :vytask:`T2908` ``VRF and bridge membership isn’t mutually exclusive`` -* :vytask:`T2958` ``DHCP server doesn't work from a live CD`` -* :vytask:`T3070` ``Firewall going OOM, possible related to nftables migration`` -* :vytask:`T3098` ``Cannot talk to rtnetlink: Message too long Command failed -:1`` -* :vytask:`T3339` ``Cloud-Init domain search setting not applied`` -* :vytask:`T4113` ``Incorrect GRUB configuration parsing`` -* :vytask:`T4121` ``Nameservers from DHCP client cannot be used in specific cases`` -* :vytask:`T4407` ``Network-config v2 is broken in Cloud-init 22.1 and VyOS 1.3`` -* :vytask:`T4412` ``commit archive: reboot not working with sftp`` -* :vytask:`T4459` ``API service with VRF doesn't work in 1.3.1`` -* :vytask:`T4745` ``CLI TAB issue with values with '-' at the beginning in conf mode`` -* :vytask:`T4790` ``RADIUS login does not work if sum of timeouts more than 50s`` -* :vytask:`T4855` ``Trying to create more than one tunnel of the same type to the same address causes unhandled exception`` -* :vytask:`T4869` ``A network with `/32` or `/128` mask cannot be removed from a network-group`` -* :vytask:`T4895` ``Tag nodes are overwritten when configured by Cloud-Init from User-Data`` -* :vytask:`T5006` ``Http api segfault with concurrent requests`` -* :vytask:`T5140` ``Firewall network-group problems`` -* :vytask:`T5221` ``BGP as-override behavior differs from new FRR and other vendors`` -* :vytask:`T5240` ``Service router-advert failed to start radvd with more then 3 name-servers`` -* :vytask:`T5305` ``REST API configure operation should not be defined as async`` -* :vytask:`T5313` ``UDP broadcast relay - missing verify() that relay interfaces have an IP address assigned`` -* :vytask:`T5329` ``Wireguard interface as GRE tunnel source causes configuration error on boot`` -* :vytask:`T5428` ``dhcp: client renewal fails when running inside VRF`` -* :vytask:`T5506` ``Container bridge interfaces do not have a link-local address`` -* :vytask:`T5524` ``Add config directory to liveCD`` -* :vytask:`T5533` ``Keepalived VRRP IPv6 group enters in FAULT state`` -* :vytask:`T5545` ``sflow is not working`` -* :vytask:`T5555` ``Fix timezone migrator (system 13-to-14)`` -* :vytask:`T5594` ``VRRP - Error if using IPv6 Link Local as hello source address`` - -**Other resolved issues** - - -* :vytask:`T469` ``Problem after commit with errors`` -* :vytask:`T2296` ``Upgrade WALinux to 2.2.41`` -* :vytask:`T3424` ``PPPoE IA-PD doesn't work in VRF`` -* :vytask:`T3577` ``Generating vpn x509 key pair fails with command not found`` -* :vytask:`T3713` ``Create a meta-package for user utilities`` -* :vytask:`T4306` ``Do not check for ditry repository when building release images`` -* :vytask:`T4874` ``Add Warning message to Equuleus`` -* :vytask:`T4933` ``Malformed lines cause vyos.util.colon_separated_to_dict fail with a nondescript error`` -* :vytask:`T5272` ``Upgrade OpenVPN to 2.6 in Equuleus`` -* :vytask:`T5470` ``wlan: can not disable interface if SSID is not configured`` -* :vytask:`T5557` ``bgp: Use treat-as-withdraw for tunnel encapsulation attribute CVE-2023-38802`` - -1.3.3 (22th June 2023) -====================== - -**Security** - - -* :vytask:`T3835` ``vyos router 1.2.7 snmp Dos bug`` -* :vytask:`T4970` ``pin OCaml pcre package to avoid JIT support`` - - -**Configuration syntax changes (automatically migrated)** - - -* :vytask:`T4628` ``ConfigTree() throws ValueError() if tagNode contains whitespaces`` - -**New features and improvements** - - -* :vytask:`T1024` ``Policy Based Routing by DSCP`` -* :vytask:`T1928` ``Is the 'Welcome to VyOS' message when using SSH an information leak?`` -* :vytask:`T1993` ``Extended pppoe rate-limiter`` -* :vytask:`T2603` ``pppoe-server: reduce min MTU`` -* :vytask:`T2640` ``Running VyOS inside Docker containers`` -* :vytask:`T2769` ``Add VRF support for syslog`` -* :vytask:`T3937` ``Rewrite "show system memory" in Python to make it usable as a library function`` -* :vytask:`T4219` ``support incoming-interface (iif) in local PBR`` -* :vytask:`T4575` ``vyos.utill add new wrapper "rc_cmd" to get the return code and output`` -* :vytask:`T4683` ``Add kitty-terminfo package to build`` -* :vytask:`T4727` ``Add RADIUS rate limit support to PPTP server`` -* :vytask:`T4743` ``Enable IPv6 address for Dynamic DNS`` -* :vytask:`T4785` ``snmp: Allow !, @, * and # in community name`` -* :vytask:`T4812` ``IPsec ability to show all configured connections`` -* :vytask:`T4898` ``Add mtu config option for dummy interfaces`` -* :vytask:`T4922` ``Add ssh-client source-interface CLI option`` -* :vytask:`T4947` ``Support mounting container volumes as ro or rw`` -* :vytask:`T4948` ``pppoe: add CLI option to allow definition of host-uniq flag`` -* :vytask:`T4949` ``Backport "monitor log" and "show log" op-mode definitions from current to equuleus`` -* :vytask:`T4959` ``Add container registry authentication config for containers`` -* :vytask:`T4971` ``Radius attribute "Framed-Pool" for PPPoE`` -* :vytask:`T5033` ``generate-public-key command fails for address with multiple public keys like GitHub`` -* :vytask:`T5098` ``PPPoE client holdoff configuration`` - -**Bug fixes** - - -* :vytask:`T2118` ``Failure to boot after power outage due to dirty filesystem and no fsck in initramfs`` -* :vytask:`T2189` ``Adding a large port-range will take ~ 20 minutes to commit`` -* :vytask:`T2516` ``vyos-container: cannot configure ethernet interface`` -* :vytask:`T2838` ``Ethernet device names changing, multiple hw-id being added`` -* :vytask:`T3852` ``DHCP client issue - interface has two dhclient processes when link is unpluged and then plug again`` -* :vytask:`T4117` ``Does not possible to configure PoD/CoA for L2TP vpn`` -* :vytask:`T4153` ``Monitor bandwidth-test initiate not working`` -* :vytask:`T4177` ``Strip-private doesn't work for service monitoring`` -* :vytask:`T4312` ``Telegraf configuration doesn't accept IPs for URL`` -* :vytask:`T4533` ``Radius clients don’t have simple permissions`` -* :vytask:`T4582` ``Router-advert: Preferred lifetime cannot equal valid lifetime in PIOs`` -* :vytask:`T4628` ``ConfigTree() throws ValueError() if tagNode contains whitespaces`` -* :vytask:`T4630` ``Prevent attempts to use the same interface as a source interface for pseudo-ethernet and MACsec at the same time`` -* :vytask:`T4642` ``proxy: hyphen not allowed in proxy URL`` -* :vytask:`T4648` ``PPPoE: Ignore default router from RA when PPPoE default-route is set to none`` -* :vytask:`T4664` ``Add validation to reject whitespace in tag node value names`` -* :vytask:`T4668` ``Adding/removing members from bond doesn't work/results in incorrect interface state`` -* :vytask:`T4671` ``linux-firmware package is missing symlinks defined in WHENCE file`` -* :vytask:`T4679` ``OpenVPN site-to-site incorrect check for IPv6 local and remote address`` -* :vytask:`T4680` ``Telegraf prometheus-client listen-address invalid format`` -* :vytask:`T4702` ``Wireguard peers configuration is not synchronized with CLI`` -* :vytask:`T4709` ``TCP MSS clamping broken in equuleus`` -* :vytask:`T4730` ``Conntrack-sync error - listen-address is not the correct type in config as it should be`` -* :vytask:`T4737` ``FRRouting/zebra 7.5.1 does not redistribute routes to other protocols`` -* :vytask:`T4799` ``PowerDNS >= 4.7 does not get reloaded by vyos-hostsd`` -* :vytask:`T4872` ``Op-mode show openvpn misses a case when parsing for tunnel IP`` -* :vytask:`T4884` ``Missing a community6 in snmpd config`` -* :vytask:`T4896` ``ospfv3: Fix broken not-advertise option`` -* :vytask:`T4902` ``snmpd: exclude container storage from monitoring`` -* :vytask:`T4918` ``Odd show interface behavior`` -* :vytask:`T4939` ``VRRP command no-preempt not work as expected`` -* :vytask:`T4955` ``Openconnect radiusclient.conf generating with extra authserver`` -* :vytask:`T4975` ``CLI does not work after cutting off the power or reset`` -* :vytask:`T4978` ``KeyError: 'memory' container_config['memory'] on upgrading to 1.4-rolling-202302041536`` -* :vytask:`T4992` ``Incorrect check is_local_address for bgp neighbor with option ip_nonlocal_bind set`` -* :vytask:`T4993` ``Can't delete conntrack ignore rule`` -* :vytask:`T5009` ``op-mode command: restart dhcp relay-agent not working`` -* :vytask:`T5011` ``Some interface drivers don't support min_mtu and max_mtu and verify_mtu check should be skipped`` -* :vytask:`T5017` ``Bug with validator interface-name`` -* :vytask:`T5047` ``Recreate only a specific container`` -* :vytask:`T5066` ``Different GRE tunnel but same tunnel keys error`` -* :vytask:`T5136` ``Possible config corruption on upgrade`` -* :vytask:`T5152` ``Telegraf agent hostname isn't qualified`` -* :vytask:`T5175` ``http-api: error in MultiPart parser for FastAPI version >= 0.91.0`` -* :vytask:`T5176` ``http-api: update vyos-http-api-tools for FastAPI security vulnerability`` -* :vytask:`T5186` ``QoS test cannot pass for 1.3`` - -**Other resolved issues** - - -* :vytask:`T1288` ``FRR: rewrite staticd backend (/opt/vyatta/share/vyatta-cfg/templates/protocols/static/*)`` -* :vytask:`T1875` ``Add the ability to use network address as BGP neighbor (bgp listen range)`` -* :vytask:`T2913` ``Failure to install fpm while building builder docker image`` -* :vytask:`T3083` ``Add feature event-handler`` -* :vytask:`T3608` ``Standardize warnings from configure scripts`` -* :vytask:`T3810` ``webproxy squidguard rules don't work properly after rewriting to python.`` -* :vytask:`T4122` ``interface ip address config missing after upgrade from 1.2.8 to 1.3.0 (when redirect is configured?)`` -* :vytask:`T4262` ``install image doesn't respect chosen root partition size`` -* :vytask:`T4381` ``OpenVPN: Add "Tunnel IP" column in "show openvpn server" operational command`` -* :vytask:`T4511` ``IPv6 DNS lookup`` -* :vytask:`T4625` ``Update ocserv to current revision (1.1.6)`` -* :vytask:`T4652` ``Upgrade PowerDNS recursor to 4.7 series`` -* :vytask:`T4798` ``Migrate the file-exists validator away from Python`` -* :vytask:`T4832` ``dhcp: Add IPv6-only dhcp option support (RFC 8925)`` -* :vytask:`T4875` ``Replace Python validator 'interface-name' to avoid Python startup cost`` -* :vytask:`T4900` ``Cache intermediary results of get_config_diff in Config instance`` -* :vytask:`T4906` ``ipsec connections shows only one connection as up`` -* :vytask:`T4925` ``Need to add the possibility to configure Pseudo-Random Functions (PRF) in IKEv2`` -* :vytask:`T4999` ``vyos.util backport dict_search_recursive`` -* :vytask:`T5007` ``Interface multicast setting is invalid`` -* :vytask:`T5008` ``MACsec CKN of 32 chars is not allowed in CLI, but works fine`` -* :vytask:`T5111` ``pppd-dns.service startup failed`` -* :vytask:`T5243` ``Default route is inactive if an interface has multiple ip addresses of the same subnet in 1.3.2 Equuleus`` - -1.3.2 (7th November 2022) -========================= - - - - -**New features and improvements** - - -* :vytask:`T1375` ``Add clear dhcp server lease function`` -* :vytask:`T2580` ``Support for ip pools for ippoe`` -* :vytask:`T2683` ``no dual stack in system static-host-mapping host-name`` -* :vytask:`T2763` ``New SNMP resource request - SNMP over TCP`` -* :vytask:`T3318` ``Update Linux Kernel to v5.4.208 / 5.10.142`` -* :vytask:`T3785` ``Add unicode support to configtree backend`` -* :vytask:`T4260` ``Extend vyos.configdict.node_changed() to support recursiveness`` -* :vytask:`T4315` ``Telegraf - Output to prometheus`` -* :vytask:`T4336` ``isis: add support for MD5 authentication password on a circuit`` -* :vytask:`T4346` ``Deprecate "system ipv6 disable" option to disable address family within OS kernel`` -* :vytask:`T4373` ``PPPoE-server add multiplier option for shaper`` -* :vytask:`T4395` ``Extend show vpn debug`` -* :vytask:`T4421` ``Add support for floating point numbers in the numeric validator`` -* :vytask:`T4442` ``HTTP API add action "reset"`` -* :vytask:`T4456` ``NTP client in VRF tries to bind to interfaces outside VRF, logs many messages`` -* :vytask:`T4489` ``MPLS sysctl not persistent for tunnel interfaces`` -* :vytask:`T4507` ``IPoE-server add multiplier option for shaper`` -* :vytask:`T4509` ``Feature Request: DNS64`` -* :vytask:`T4515` ``Reduce telegraf binary size`` -* :vytask:`T4522` ``bond: add ability to specify mii monitor interval via CLI`` -* :vytask:`T4584` ``hostap: create custom package build`` -* :vytask:`T4614` ``OpenConnect split-dns directive`` -* :vytask:`T4647` ``Add Google Virtual NIC (gVNIC) support`` - -**Bug fixes** - - -* :vytask:`T2194` ``"show firewall" garbled output`` -* :vytask:`T2654` ``Multiple names unable to be assigned to the same static mapping`` -* :vytask:`T3507` ``Bond with mode LACP show u/u in show interfaces even if peer is not configured`` -* :vytask:`T3714` ``Some sysctl custom parameters disappear after reboot`` -* :vytask:`T4206` ``Policy Based Routing with DHCP Interface Issue`` -* :vytask:`T4230` ``OpenVPN server configuration deleted after reboot when using a VRRP virtual-address`` -* :vytask:`T4294` ``Adding a new openvpn-option does not restart the OpenVPN process`` -* :vytask:`T4313` ``"generate public-key-command" throws unhandled exceptions when it cannot retrieve the key`` -* :vytask:`T4319` ``The command "set system ipv6 disable" doesn't work as expected.`` -* :vytask:`T4324` ``wwan: check alive script should only be run via cron if a wwan interface is configured at all`` -* :vytask:`T4330` ``MTU settings cannot be applied when IPv6 is disabled`` -* :vytask:`T4331` ``IPv6 link local addresses are not configured when an interface is in a VRF`` -* :vytask:`T4337` ``isis: IETF SPF delay algorithm can not be configured - results in vyos.frr.CommitError`` -* :vytask:`T4338` ``wwan: changing interface description should not trigger reconnect`` -* :vytask:`T4339` ``wwan: tab-completion results in "No such file or directory" if there is no WWAN interface`` -* :vytask:`T4341` ``login: disable user-account prior to deletion and wait until deletion is complete`` -* :vytask:`T4350` ``DMVPN opennhrp spokes dont work behind NAT`` -* :vytask:`T4354` ``Slave interfaces fall out from bonding during configuration change`` -* :vytask:`T4361` ```vyos.config.exists()` does not work for nodes with multiple values`` -* :vytask:`T4363` ``salt-minion: default mine_interval option is not set`` -* :vytask:`T4366` ``geneve: interface is removed on changes to e.g. description`` -* :vytask:`T4369` ``OpenVPN: daemon not restarted on changes to "openvpn-option" CLI node`` -* :vytask:`T4388` ``dhcp-server: missing constraint on tftp-server-name option`` -* :vytask:`T4405` ``DHCP client sometimes ignores `no-default-route` option of an interface`` -* :vytask:`T4441` ``wwan: connection not possible after a change added after 1.3.1-S1 release`` -* :vytask:`T4447` ``DHCPv6 prefix delegation `sla-id` limited to 128`` -* :vytask:`T4468` ``web-proxy source group cannot start with a number bug`` -* :vytask:`T4510` ``set system static-host-mapping doesn't allow IPv4 and IPv6 for same name.`` -* :vytask:`T4513` ``Webproxy monitor commands do not work`` -* :vytask:`T4521` ``bond: ARP monitor interval is not configured despite set via CLI`` -* :vytask:`T4525` ``Delete interface from VRF and add it to bonding error`` -* :vytask:`T4527` ``Prevent to create VRF name default`` -* :vytask:`T4532` ``Flow-accounting IPv6 server/receiver bug`` -* :vytask:`T4534` ``bond: bridge: error out if member interface is assigned to a VRF instance`` -* :vytask:`T4537` ``MACsec not working with cipher gcm-aes-256`` -* :vytask:`T4538` ``Macsec does not work correctly when the interface status changes.`` -* :vytask:`T4565` ``vlan aware bridge not working with - Kernel: T3318: update Linux Kernel to v5.4.205 #249`` -* :vytask:`T4572` ``Add an option to force interface MTU to the value received from DHCP`` -* :vytask:`T4579` ``bridge: can not delete member interface CLI option when VLAN is enabled`` -* :vytask:`T4592` ``macsec: can not create two interfaces using the same source-interface`` -* :vytask:`T4616` ``openconnect: KeyError: 'local_users'`` -* :vytask:`T4618` ``Traffic policy not set on virtual interfaces`` -* :vytask:`T4632` ``VLAN-aware bridge not working`` -* :vytask:`T4653` ``Interface offload options are not applied correctly`` -* :vytask:`T4666` ``EAP-TLS no longer allows TLSv1.0 after T4537, T4584`` - -**Other resolved issues** - - -* :vytask:`T4415` ``Include license/copyright files in the image but remove user documentation from /usr/share/doc to reduce its size`` -* :vytask:`T4430` ``Show firewall output with visual shift default rule`` -* :vytask:`T4629` ``Raised ConfigErrors contain dict instead of only the dict key`` -* :vytask:`T4654` ``RPKI cache incorrect description`` - -1.3.1 (21th March 2022) -======================= - -**Security** - - -* :vytask:`T4204` ``Update Accel-PPP to a newer revision`` -* :vytask:`T4310` ``CVE-2022-0778: infinite loop in OpenSSL certificate parsing`` -* :vytask:`T4311` ``CVE-2021-4034: local privilege escalation in PolKit`` - - -**Configuration syntax changes (automatically migrated)** - - -* :vytask:`T1972` ``Allow setting interface name for virtual_ipaddress in VRRP VRID`` -* :vytask:`T4273` ``ssh: Upgrade from 1.2.X to 1.3.0 breaks config`` - -**New features and improvements** - - -* :vytask:`T1972` ``Allow setting interface name for virtual_ipaddress in VRRP VRID`` -* :vytask:`T2400` ``OpenVPN: dont restart server if no need`` -* :vytask:`T2764` ``Increase maximum number of NAT rules`` -* :vytask:`T3164` ``console-server ssh does not work with RADIUS PAM auth`` -* :vytask:`T3299` ``Allow the web proxy service to listen on all IP addresses`` -* :vytask:`T3854` ``Missing op-mode commands for conntrack-sync`` -* :vytask:`T3872` ``Add configurable telegraf monitoring service`` -* :vytask:`T4055` ``Add VRF support for HTTP(S) API service`` -* :vytask:`T4100` ``Firewall increase maximum number of rules`` -* :vytask:`T4120` ``[VXLAN] add ability to set multiple unicast-remotes`` -* :vytask:`T4128` ``keepalived: Upgrade package to add VRF support`` -* :vytask:`T4261` ``MACsec: add DHCP client support`` - -**Bug fixes** - - -* :vytask:`T2922` ``The `vpn ipsec logging log-modes` miss the IPSec daemons state check`` -* :vytask:`T3380` ``"show vpn ike sa" does not display IPv6 peers`` -* :vytask:`T3686` ``Bridging OpenVPN tap with no local-address breaks`` -* :vytask:`T3914` ``VRRP rfc3768-compatibility doesn't work with unicast peers`` -* :vytask:`T3924` ``VRRP stops working with VRF`` -* :vytask:`T4002` ``firewall group network-group long names restriction incorrect behavior`` -* :vytask:`T4081` ``VRRP health-check script stops working when setting up a sync group`` -* :vytask:`T4087` ``IPsec IKE-group proposals limit of 10 pieces`` -* :vytask:`T4092` ``IKEv2 mobike commit failed with DMVPN nhrp`` -* :vytask:`T4093` ``SNMPv3 snmpd.conf generation bug`` -* :vytask:`T4101` ``commit-archive: Use of uninitialized value $source_address in concatenation`` -* :vytask:`T4104` ``RAID1: "add raid md0 member sda1" does not restore boot sector`` -* :vytask:`T4110` ``[IPV6-SSH/DNS} enable IPv6 link local adresses as listen-address %eth0`` -* :vytask:`T4141` ``Set high-availability vrrp sync-group without members error`` -* :vytask:`T4142` ``Input ifbX interfaces not displayed in op-mode`` -* :vytask:`T4152` ``NHRP shortcut-target holding-time does not work`` -* :vytask:`T4154` ``Error add second gre tunnel with the same source interface`` -* :vytask:`T4165` ``Custom conntrack rules cannot be deleted`` -* :vytask:`T4168` ``IPsec VPN is impossible to restart when DMVPN is configured`` -* :vytask:`T4183` ``IPv6 link-local address not accepted as wireguard peer`` -* :vytask:`T4184` ``NTP allow-clients address doesn't work it allows to use ntp server for all addresses`` -* :vytask:`T4191` ``Lost access to host after VRF re-creating`` -* :vytask:`T4196` ``DHCP server client-prefix-length parameter results in non-functional leases`` -* :vytask:`T4203` ``Reconfigure DHCP client interface causes brief outages`` -* :vytask:`T4226` ``VRRP transition-script does not work for groups name which contains -(minus) sign`` -* :vytask:`T4228` ``bond: OS error thrown when two bonds use the same member`` -* :vytask:`T4233` ``ssh: sync regex for allow/deny usernames to "system login"`` -* :vytask:`T4234` ``Show firewall partly broken in 1.3.x`` -* :vytask:`T4237` ``Conntrack-sync error - error adding listen-address command`` -* :vytask:`T4240` ``Cannot add wlan0 to bridge via configure`` -* :vytask:`T4241` ``ocserv openconnect looks broken in recent bulds of 1.3 Equuleus`` -* :vytask:`T4242` ``ethernet speed/duplex can never be switched back to auto/auto`` -* :vytask:`T4258` ``[DHCP-SERVER] error parameter on Failover`` -* :vytask:`T4259` ``The conntrackd daemon can be started wrongly`` -* :vytask:`T4263` ``vyos.util.leaf_node_changed() dos not honor valueLess nodes`` -* :vytask:`T4264` ``vxlan: interface is destroyed and rebuild on description change`` -* :vytask:`T4267` ``Error - Missing required "ip key" parameter`` -* :vytask:`T4273` ``ssh: Upgrade from 1.2.X to 1.3.0 breaks config`` -* :vytask:`T4297` ``Interface configuration saving fails for ice/iavf based interfaces because they can't change speed/duplex settings`` -* :vytask:`T4377` ``generate tech-support archive includes previous archives`` - -**Other resolved issues** - - -* :vytask:`T4227` ``Typo in help completion of hello-time option of bridge interface`` -* :vytask:`T4255` ``Unexpected print of dict bridge on delete`` -* :vytask:`T4476` ``Next steps after installation is not communicated properly to new users`` - -1.3.0 (21th December 2021) -========================== - - -**Breaking changes** - - -* :vytask:`T3350` ``OpenVPN config file generation broken`` -* :vytask:`T3866` ``Configs with DNS forwarding listening on OpenVPN interfaces or interfaces without a fixed address cannot be migrated to the new syntax`` - -**Configuration syntax changes (automatically migrated)** - - -* :vytask:`T2162` ``migration script for router-advert sets link-mtu 0 on bridge interfaces`` -* :vytask:`T2691` ``Upgrade from 1.2.5 to 1.3-rolling-202007040117 results in broken config due to case mismatch`` -* :vytask:`T3293` ``RPKI migration script errors out after CLI rewrite`` - -**New features and improvements** - - -* :vytask:`T3704` ``Add ability to interact with Areca RAID adapers`` -* :vytask:`T3745` ``op-mode IPSec show vpn ipse sa sorting`` -* :vytask:`T3912` ``Use a more informative default post-login banner`` -* :vytask:`T3945` ``Add route-map for bgp aggregate-address`` -* :vytask:`T3971` ``Ability to build ISO images for XCP-NG hypervisor`` -* :vytask:`T4012` ``Add VRF support for TFTP`` -* :vytask:`T4013` ``Add pkg cloudwatch for AWS images`` -* :vytask:`T4046` ``Sflow - Add Source address parameter`` -* :vytask:`T4049` ``support command-style output with compare command`` -* :vytask:`T4082` ``Add op mode command to restart ldpd`` -* :vytask:`T4084` ``Dehardcode the default login banner`` - -**Bug fixes** - - -* :vytask:`T1624` ``Failed to set up config session`` -* :vytask:`T1710` ``[equuleus] buster: add patch to fix live-build missing key error`` -* :vytask:`T1847` ``set_level incorrectly handles path given as empty string`` -* :vytask:`T1876` ``IPSec VTI tunnels are deleted after rekey and dangling around as A/D`` -* :vytask:`T2009` ``Ethernet Interface always stays down`` -* :vytask:`T2022` ``When RADIUS config is active, local logins won't work`` -* :vytask:`T2082` ``WireGuard broken after merging T2057`` -* :vytask:`T2158` ``Commit fails if ethernet interface doesn't support flow control (pause)`` -* :vytask:`T2162` ``migration script for router-advert sets link-mtu 0 on bridge interfaces`` -* :vytask:`T2164` ``Package libstrongswan-standard-plugins missing from image`` -* :vytask:`T2167` ``vyos.ifconfig.get_mac() broken`` -* :vytask:`T2176` ``'WiFiIf' object has no attribute 'set_state'`` -* :vytask:`T2177` ``Commit fails on adding disabled interface to bridge`` -* :vytask:`T2241` ``Changing settings on an interface causes it to fall out of bridge`` -* :vytask:`T2273` ``OpenVPN no longer starts in latest rolling, migrate to systemd`` -* :vytask:`T2283` ``openvpn not starting: ccd path in template not moved to /run/openvpn/ccd`` -* :vytask:`T2293` ``OpenVPN: UnboundLocalError after merging server_network PullRequest`` -* :vytask:`T2318` ``dns-forwarding migration script breaks with invalid interface name`` -* :vytask:`T2337` ``hw-id gone missing from interfaces after upgrade to 1.3-rolling-202004191028`` -* :vytask:`T2427` ``Interface addressing broken since fix for T2372 was merged`` -* :vytask:`T2466` ``live-build encounters apt dependency problem when building with local packages`` -* :vytask:`T2578` ``ipaddrcheck unaware of /31 host addresses - can no longer assign /31 mask to interface addresses`` -* :vytask:`T2600` ``RADIUS system login configuration rendered wrongly`` -* :vytask:`T2624` ``Serial Console: fix migration script for configured powersave and no console`` -* :vytask:`T2642` ``sshd fails to start due to configuration error`` -* :vytask:`T2678` ``High RAM usage on SSH logins with lots of IPv6 routes in the routing table.`` -* :vytask:`T2682` ``VRF aware services - connection no longer possible after system reboot`` -* :vytask:`T2691` ``Upgrade from 1.2.5 to 1.3-rolling-202007040117 results in broken config due to case mismatch`` -* :vytask:`T2746` ``IPv6 link-local addresses not configured`` -* :vytask:`T2758` ``router-advert: 'infinity' is not a valid integer number`` -* :vytask:`T2886` ``RADIUS authentication broken only returns operator level`` -* :vytask:`T2894` ``bond: lacp: member interfaces get removed once bond interface has vlans configured`` -* :vytask:`T2952` ``configd: timeout breaks synchronization of messages, causing freeze`` -* :vytask:`T3208` ``Does not possible to change user password`` -* :vytask:`T3350` ``OpenVPN config file generation broken`` -* :vytask:`T3370` ``dhcp: Invalid domain name "private"`` -* :vytask:`T3699` ``login: verify selected "system login user" name is not already used by the base system.`` -* :vytask:`T3707` ``Ping incorrect ip host checks`` -* :vytask:`T3822` ``OpenVPN processes do not have permission to read key files generated with `run generate openvpn key``` -* :vytask:`T3866` ``Configs with DNS forwarding listening on OpenVPN interfaces or interfaces without a fixed address cannot be migrated to the new syntax`` -* :vytask:`T3886` ``DHCP server can not start`` -* :vytask:`T3887` ``Removal of IPv6 BGP-peer with peer-group may trigger problems`` -* :vytask:`T3913` ``VRF traffic fails after upgrade from 1.3.0-RC6 to 1.3.0-EPA1/2`` -* :vytask:`T3934` ``Openconnect VPN broken: ocserv-worker general protection fault on client connect`` -* :vytask:`T3962` ``Image cannot be built without open-vm-tools`` -* :vytask:`T3972` ``Removing vif-c interface raises KeyError`` -* :vytask:`T4015` ``Update Accel-PPP to a newer revision`` -* :vytask:`T4019` ``Smoketests for SSTP and openconnect fails`` -* :vytask:`T4033` ``VRRP - Error security when setting scripts`` -* :vytask:`T4035` ``Geneve interfaces aren't displayed by operational mode commands`` -* :vytask:`T4052` ``Validator return traceback on VRRP configuration with the script path not in config dir`` -* :vytask:`T4053` ``VRRP impossible to set scripts out of the /config directory`` -* :vytask:`T4167` ``DMVPN apply wrong param on the first configuration`` -* :vytask:`T4201` ``Firewall - ICMPv6 matches not working as expected on 1.3.0`` -* :vytask:`T4268` ``Elevated LA while using VyOS monitoring feature`` -* :vytask:`T4296` ``Interface config injected by Cloud-Init may interfere with VyOS native`` -* :vytask:`T4344` ``DHCP statistics not matching, conf-mode generates incorrect pool name with dash`` -* :vytask:`T4571` ``Sflow with vrf configured does not use vrf to validate agent-address IP from vrf-configured interfaces`` - -**Other resolved issues** - - -* :vytask:`T1497` ``"set system name-server" generates invalid/incorrect resolv.conf`` -* :vytask:`T1606` ``Rolling release no longer boots after adding hostname daemon`` -* :vytask:`T1676` ``[equuleus] buster: update GRUB boot parameters during upgrade`` -* :vytask:`T2129` ``XML schema: tagNode not allowed on first level in new XML op-mode definition`` -* :vytask:`T2389` ``BGP community-list unknown command`` -* :vytask:`T2722` ``get_config_dict() and key_mangling=('-', '_') will alter CLI data for tagNodes`` -* :vytask:`T3182` ``Main blocker Task for FRR 7.4/7.5 series update`` -* :vytask:`T3293` ``RPKI migration script errors out after CLI rewrite`` -* :vytask:`T3302` ``Make vyos-configd relay stdout from scripts to the user's console`` -* :vytask:`T3687` ``IS-IS is missing IPv6 support`` -* :vytask:`T3689` ``static ipv6 route doesn't deleted in some cases`` -* :vytask:`T3695` ``OpenConnect reports commit success when ocserv fails to start due to SSL cert/key file issues`` -* :vytask:`T3697` ``Impossible to delete IPsec completely`` -* :vytask:`T3711` ``service router-advert interface <name> dnssl option has no effects`` -* :vytask:`T3725` ``show configuration in json format`` -* :vytask:`T3735` ``Configuration with multiple network addresses of firewall network-group via colud-init fails`` -* :vytask:`T4065` ``IPSEC configuration error: connection to unix:///var/run/charon.ctl failed: No such file or directory`` -* :vytask:`T4088` ``Fix typo in login banner`` -* :vytask:`T4115` ``reboot in <x> not working as expected`` -* :vytask:`T4198` ``Error shown on commit`` - -1.3.0-epa3 (5th November 2021) -============================== - - - -**Configuration syntax changes (automatically migrated)** - - -* :vytask:`T3925` ``Tunnel: dhcp-interface not implemented - use source-interface instead`` - -**New features and improvements** - - -* :vytask:`T3927` ``Kernel: Enable kernel support for HW offload of the TLS protocol`` -* :vytask:`T3942` ``Generate IPSec debug archive from op-mode`` - -**Bug fixes** - - -* :vytask:`T3610` ``DHCP-Server creation for not primary IP address fails`` -* :vytask:`T3846` ``dmvpn configuration not reapllied after "restart vpn"`` -* :vytask:`T3921` ``tunnel: KeyError when using dhcp-interface`` -* :vytask:`T3922` ``NHRP: delete fails`` -* :vytask:`T3925` ``Tunnel: dhcp-interface not implemented - use source-interface instead`` -* :vytask:`T3926` ``strip-private does not sanitize "cisco-authentication" from NHRP configuration`` -* :vytask:`T3941` ``"show vpn ipsec sa" shows established time of parent SA not child SA's`` -* :vytask:`T3943` ``"netflow source-ip" prevents image upgrades if IP address does not exist locally`` -* :vytask:`T3944` ``VRRP fails over when adding new group to master`` -* :vytask:`T3954` ``FTDI cable makes VyOS sagitta latest hang, /dev/serial unpopulated, config system error`` -* :vytask:`T3956` ``GRE tunnel - unable to move from source-interface to source-address, commit error`` -* :vytask:`T4004` ``IPsec ike-group parameters are not saved correctly (after reboot)`` -* :vytask:`T4034` ``"make xcp-ng-iso" still includes vyos-xe-guest-utilities`` - -**Other resolved issues** - - -* :vytask:`T3188` ``Tunnel local-ip to dhcp-interface Change Fails to Update`` -* :vytask:`T3341` ``Wrong behavior of the "reset vpn ipsec-peer XXX tunnel XXX" command`` -* :vytask:`T3626` ``Configuring and disabling DHCP Server`` -* :vytask:`T3918` ``DHCPv6 prefix delegation incorrect verify error`` -* :vytask:`T3920` ``dhclient exit hook script 01-vyos-cleanup causes too many arguments error`` -* :vytask:`T3990` ``WATCHFRR: crashlog and per-thread log buffering unavailable (due to files left behind in /var/tmp/frr/ after reboot)`` -* :vytask:`T4005` ``Feature Request: IPsec IKEv1 + IKEv2 for one peer`` - -1.3.0-epa2 (18th October 2021) -============================== - - - - -**New features and improvements** - - -* :vytask:`T3277` ``DNS Forwarding - reverse zones`` -* :vytask:`T3885` ``dhcpv6-pd: randomly generated DUID is not persisted`` -* :vytask:`T3890` ``dhcp(v6): provide op-mode commands to retrieve both server and client logfiles`` -* :vytask:`T3899` ``Add support for hd44780 LCD displays`` - -**Bug fixes** - - -* :vytask:`T3750` ``pdns-recursor 4.4 issue with dont-query and private DNS servers`` -* :vytask:`T3874` ``D-Link Ethernet Interface not working.`` -* :vytask:`T3877` ``VRRP always enabled rfc3768-compatibility even when not specified`` -* :vytask:`T3878` ``get_config_dict() no_tag_node_value_mangle has no effect`` -* :vytask:`T3879` ``GPG key verification fails when upgrading from a 1.3 beta version`` -* :vytask:`T3883` ``VRF - Delette vrf config on interface`` -* :vytask:`T3893` ``MGRE Tunnel commit crash If sit tunnel available`` -* :vytask:`T3894` ``Tunnel Commit Failed if system does not have `eth0``` -* :vytask:`T3904` ``NTP pool associations silently fail`` - -**Other resolved issues** - - -* :vytask:`T3422` ``Dynamic DNS doesn't allow zone field with cloudflare protocol`` -* :vytask:`T3425` ``Scripts from the /config/scripts/ folder do not run on live system`` -* :vytask:`T3880` ``EFI boot shows error on display`` -* :vytask:`T3882` ``Upgrade PowerDNs recursor to 4.5 series`` -* :vytask:`T3888` ``Incorrect warning when poweroff command executed from configure mode.`` -* :vytask:`T3889` ``Migrate to journalctl when reading daemon logs`` - -1.3.0-epa1 (30th September 2021) -================================ - - - -**Configuration syntax changes (automatically migrated)** - - -* :vytask:`T3672` ``DHCP-FO with multiple subnets results in invalid/non-functioning dhcpd.conf configuration file output`` -* :vytask:`T3779` ``Backport all 1.4 IS-IS features and configuration to 1.3 except VRF`` -* :vytask:`T3804` ``cli: Migrate and merge "system name-servers-dhcp" into "system name-server"`` -* :vytask:`T3842` ``Backport DHCP server improvements from VyOS 1.4 sagitta to 1.3 equuleus`` - -**New features and improvements** - - -* :vytask:`T1099` ``Openvpn: use config files instead of one long command.`` -* :vytask:`T1154` ``use of local cache to build iso`` -* :vytask:`T1176` ``FRR - BGP replicating routes`` -* :vytask:`T1350` ``VRRP transition script will be executed once only`` -* :vytask:`T3716` ``Linux kernel parameters ignore_routes_with_link_down- ignore disconnected routing connections`` -* :vytask:`T3779` ``Backport all 1.4 IS-IS features and configuration to 1.3 except VRF`` -* :vytask:`T3789` ``Add custom validator for base64 encoded CLI data`` -* :vytask:`T3803` ``Add source-address option to the ping CLI`` -* :vytask:`T3804` ``cli: Migrate and merge "system name-servers-dhcp" into "system name-server"`` -* :vytask:`T3840` ``dns forwarding: Cache size should allow values > 10k`` -* :vytask:`T3841` ``dhcp-server: add ping-check option to CLI`` -* :vytask:`T3842` ``Backport DHCP server improvements from VyOS 1.4 sagitta to 1.3 equuleus`` -* :vytask:`T3857` ``reboot: send wall message to all users for information`` -* :vytask:`T3859` ``Add "log-adjacency-changes" to ospfv3 process`` - -**Bug fixes** - - -* :vytask:`T945` ``Unable to change configuration after changing it from script (vbash + script-template)`` -* :vytask:`T1148` ``epa2 BGP peers initiate before config is fully loaded, routes leak.`` -* :vytask:`T1249` ``multiple PBR rules can set to a single interface`` -* :vytask:`T1894` ``FRR config not loaded after daemons segfault or restart`` -* :vytask:`T2019` ``LLDP wrong config generation for interface 'all'`` -* :vytask:`T2127` ``restart dhcp server reports a failure`` -* :vytask:`T2161` ``snmpd cannot start if ipv6 disabled`` -* :vytask:`T2328` ``dhcpv6 server not starting (disable check reversed?)`` -* :vytask:`T2430` ``cannot delete specific route static next-hop`` -* :vytask:`T2432` ``dhcpd: Can't create new lease file: Permission denied`` -* :vytask:`T2434` ``Duplicate Address Detection Breaks Interfaces`` -* :vytask:`T2525` ``OSPFv3 missing route map, not establishing`` -* :vytask:`T2623` ``Creating sit tunnel fails with “Can not set “local” for tunnel sit tun1 at tunnel creation”`` -* :vytask:`T2738` ``Modifying configuration in the "interfaces" section from VRRP transition scripts causes configuration lockup and high CPU utilization`` -* :vytask:`T2759` ``validate-value prints error messages from validators that fail even if overall validation succeeds`` -* :vytask:`T2800` ``Pseudo-Ethernet: source-interface must not be member of a bridge`` -* :vytask:`T2895` ``VPN IPsec "leftsubnet" declared 2 times`` -* :vytask:`T2920` ``Commit crash when adding the second mGRE tunnel with the same key`` -* :vytask:`T2931` ``Unicode decode error causes vyos.configd service to restart`` -* :vytask:`T2941` ``Using a non-ASCII character in the description field causes UnicodeDecodeError in configsource.py`` -* :vytask:`T3076` ``Router reboot adds unwanted 'conntrack-sync mcast-group '225.0.0.50'' line to configuration`` -* :vytask:`T3196` ``No NAT translations showing up`` -* :vytask:`T3219` ``Typo in openvpn server client config for IPv6 iroute`` -* :vytask:`T3601` ``Error in ssh keys for vmware cloud-init if ssh keys is left empty.`` -* :vytask:`T3637` ``vrf: bind-to-all didn't work properly`` -* :vytask:`T3672` ``DHCP-FO with multiple subnets results in invalid/non-functioning dhcpd.conf configuration file output`` -* :vytask:`T3708` ``isisd and gre-bridge commit error`` -* :vytask:`T3731` ``verify_accel_ppp_base_service return wrong config error for SSP`` -* :vytask:`T3738` ``openvpn fails if server and authentication are configured`` -* :vytask:`T3740` ``HTTPs API breaks when the address is IPv6`` -* :vytask:`T3756` ``VyOS generates invalid QR code for wireguard clients`` -* :vytask:`T3772` ``VRRP virtual interfaces are not shown in show interfaces`` -* :vytask:`T3773` ``Delete the "show system integrity" command (to prepare for a re-implementation)`` -* :vytask:`T3777` ``adding IPv6 EUI64 address fails commit in 1.3.0-rc6`` -* :vytask:`T3781` ``Revert the NAT implementation in 1.3 back to iptables`` -* :vytask:`T3782` ``Ingress Shaping with IFB No Longer Functional with 1.3`` -* :vytask:`T3783` ``"set protocols isis spf-delay-ietf" is not working`` -* :vytask:`T3786` ``GRE tunnel source address 0.0.0.0 error`` -* :vytask:`T3788` ``Keys are not allowed with ipip and sit tunnels`` -* :vytask:`T3790` ``Does not possible to configure PPTP static ip-address to users`` -* :vytask:`T3792` ``login: A hypen present in a username from "system login user" is replaced by an underscore`` -* :vytask:`T3797` ``show interface errors with vrrp configuration`` -* :vytask:`T3802` ``Commit fails if ethernet interface doesn't support flow control`` -* :vytask:`T3805` ``OpenVPN insufficient privileges for rtnetlink when closing TUN/TAP interface`` -* :vytask:`T3806` ``Don't set link local ipv6 address if MTU less then 1280`` -* :vytask:`T3807` ``Op Command "show interfaces wireguard" does not show the output`` -* :vytask:`T3808` ``ipsec is mistakenly restarted after delete`` -* :vytask:`T3816` ``Error after entering outbound-interface command in NAT`` -* :vytask:`T3850` ``Dots are no longer allowed in SSH public key names`` -* :vytask:`T3860` ``Error on pppoe, tunnel and wireguard interfaces for IPv6 EUI64 addresses`` -* :vytask:`T3867` ``vxlan: multicast group address is not validated`` - -**Other resolved issues** - - -* :vytask:`T1202` ``Add `hvinfo` to the packages directory`` -* :vytask:`T1214` ``Add `ipaddrcheck` to the packages directory`` -* :vytask:`T1236` ``Update Linux Kernel`` -* :vytask:`T2027` ``get_config_dict is failing when the configuration section is empty/missing`` -* :vytask:`T2555` ``XML op-mode generation scripts silently discard XML nodes`` -* :vytask:`T2727` ``Add a dotted decimal value validator`` -* :vytask:`T2927` ``isc-dhcpd release and expiry events never execute`` -* :vytask:`T3217` ``Save FRR configuration on each commit`` -* :vytask:`T3234` ``multi_to_list fails in certain cases, with root cause an element redundancy in XML interface-definitions`` -* :vytask:`T3254` ``Dynamic DNS status shows incorrect last update time`` -* :vytask:`T3291` ``Fault on setting offload RPS with single-core CPU`` -* :vytask:`T3362` ``1.3 - RC1 ifb redirect failing to commit`` -* :vytask:`T3381` ``Change GRE tunnel failed`` -* :vytask:`T3396` ``syslog can't be configured with an ipv6 literal destination in 1.2.x`` -* :vytask:`T3431` ``Show version all bug`` -* :vytask:`T3537` ``Unable to override the default OSPFv3 link cost for wireguard interface`` -* :vytask:`T3634` ``Add op command option for ping for do not fragment bit to be set`` -* :vytask:`T3683` ``VXLAN not accept ipv6 and source-interface options and mtu bug`` -* :vytask:`T3730` ``op-mode conntrack-sync miss some functions`` -* :vytask:`T3732` ``override-default helper should support adding defaultValues to default less nodes`` -* :vytask:`T3768` ``Remove early syntaxVersion implementation`` -* :vytask:`T3776` ``Rename FRR daemon restart op-mode commands`` -* :vytask:`T3814` ``wireguard: commit error showing incorrect peer name from the configured name`` -* :vytask:`T3819` ``Upgrade Salt Stack 3002.3 -> 3003 release train`` -* :vytask:`T3820` ``PowerDNS recursor - update from 4.3 -> 4.4 to sync with current`` diff --git a/docs/changelog/1.4.rst b/docs/changelog/1.4.rst deleted file mode 100644 index 260020cc..00000000 --- a/docs/changelog/1.4.rst +++ /dev/null @@ -1,433 +0,0 @@ - -########### -1.4 Sagitta -########### - -.. - Please don't add anything by hand. - This file is managed by the script: - _ext/releasenotes.py - - -1.4.1 (future release) -====================== - - - -**Configuration syntax changes (automatically migrated)** - - -* :vytask:`T6505` ``Support VXLAN VLAN-VNI range mapping in CLI`` - -**New features and improvements** - - -* :vytask:`T5878` ``Make the list of SSH server ciphers configurable`` -* :vytask:`T5949` ``Disable USB autosuspend`` -* :vytask:`T6320` ``WiFi: Enable support for 6GHz AccesPoints`` -* :vytask:`T6423` ``Require command definition nodes that have an owner to also have a priority`` -* :vytask:`T6424` ``ipsec: op-mode command to generate client profiles should honor common name of the CA node that signed the server certificate`` -* :vytask:`T6454` ``Explicitly set the default reverse proxy mode to HTTP`` -* :vytask:`T6462` ``wireless: add op-mode command for hostapd and wpa_supplicant logs`` -* :vytask:`T6473` ``bgp: missing completion helper for peer-groups inside a VRF`` -* :vytask:`T6477` ``Adding Loki plugin to Telegraf`` -* :vytask:`T6505` ``Support VXLAN VLAN-VNI range mapping in CLI`` -* :vytask:`T6538` ``Allow adding a geneve interface to the vrf.`` -* :vytask:`T6539` ``Add logging options to load-balancer reverse-proxy`` -* :vytask:`T6566` ``op-mode: "monitor bandwidth" add support for listing all interfaces concurrently`` -* :vytask:`T6576` ``op-mode: ntp: add support for NTP service restart via CLI`` -* :vytask:`T6614` ``Initial support for smoketesting op-mode commands`` - -**Bug fixes** - - -* :vytask:`T2145` ``openvpn: server default topology net30 is incompatible with static client IPs for Windows clients`` -* :vytask:`T4287` ``wireless: cannot set regulatory domain`` -* :vytask:`T5514` ``Improve error handling when/if config.boot is deleted or missing`` -* :vytask:`T5552` ``'set system option performance throughput' enables IPv6 forwarding even if it's explicitly disabled with 'set system ipv6 disable-forwarding'`` -* :vytask:`T5725` ``protocol IS-IS configuration is empty if a tunnel does not have remote address`` -* :vytask:`T5947` ``[1.3.2 -> 1.4.0-RC1 Migration] Static ipv6 routes dropped`` -* :vytask:`T6148` ``Reset vpn ipsec command breaks tunnel and does not reset SAs that are down`` -* :vytask:`T6332` ``IPv6-only ISIS (or, in general, dual topology) is not working with other devices running frr`` -* :vytask:`T6401` ``Attempts to delete vlan-to-vni option causes an unhandled exception`` -* :vytask:`T6429` ``bug - isis metric-style not applied configuration`` -* :vytask:`T6431` ``monitor traceroute broken VRF support`` -* :vytask:`T6453` ``GRUB variables with `=` in a value are parsed improperly`` -* :vytask:`T6460` ``Showing DHCPv6 leases can fail due to DUID parsing issues`` -* :vytask:`T6463` ``reverse-proxy: service not reloaded when updating SSL certificate via PKI`` -* :vytask:`T6464` ``sstpc: interface not restarted when updating SSL certificate via PKI`` -* :vytask:`T6480` ``PermissionError: [Errno 13] Permission denied: '/config/auth/letsencrypt/live/..../cert.pem`` -* :vytask:`T6484` ``Smoketest fails: fastnetmon killed due to OOM`` -* :vytask:`T6503` ``Command 'restart ssh' not working`` -* :vytask:`T6519` ``interfaces: 20-to-21 -> migration fails if new system has less ethernet interfaces`` -* :vytask:`T6523` ``Error: "nft table ip vyos_filter not found" when commiting prometheus-client`` -* :vytask:`T6559` ``vyos-configd should return commit error on config dependency error`` -* :vytask:`T6584` ``Revert addition of Linux Kernel MT7921 driver`` -* :vytask:`T6593` ``Release DHCP interface does not work`` -* :vytask:`T6600` ``ospf: smoketest "router ospf' not found in" for ldp sync`` -* :vytask:`T6602` ``interfaces: verify supplied VRF name on all interface types`` -* :vytask:`T6603` ``vrf: nftables conntrack ct_iface_map contains multiple identical entries`` -* :vytask:`T6605` ```ConfigError()` behavior is wrong with running `vyos-configd``` -* :vytask:`T6610` ``Missing minisign pub key from image`` - -**Other resolved issues** - - -* :vytask:`T4026` ``PKI: generate pki certificate sign <ca-name> is not working`` -* :vytask:`T5570` ``PAM config RADIUS ignore for default and success`` -* :vytask:`T6290` ``SNMPD show logs systemstats_linux: unexpected header length`` -* :vytask:`T6379` ``"generate openvpn" uses "comp-lzo no", which leads to problems on Android-Clients`` -* :vytask:`T6446` ``Display the support URL from image build data in LTS builds`` -* :vytask:`T6486` ``Generate openvpn client-config ignores configured protocol type`` -* :vytask:`T6500` ``openconnect: add support for new multi ca-certificate CLI node`` -* :vytask:`T6524` ``Rewrite "release dhcp interface <interface>" to Python to drop remaining Perl dependencies`` -* :vytask:`T6592` ``Changing VRF on interface fails`` -* :vytask:`T6594` ``IPoE-server extended-scripts do not work`` -* :vytask:`T6597` ``wireless: hostapd occationly gets deactivated via systemd and causes loss in connectivity`` -* :vytask:`T6598` ``Unexpected podman version 4.3.1`` - -1.4.0 (4th June 2024) -===================== - - - - -**New features and improvements** - - -* :vytask:`T3202` ``Enable wireguard debug messages by default`` -* :vytask:`T4022` ``Add package nat-rtsp-dkms`` -* :vytask:`T4393` ``sstp: add support for configuring host-name (SNI)`` -* :vytask:`T5386` ``Execute VRRP transition script when `set high-availability disable` is commited`` -* :vytask:`T5752` ``Check compatibility of new image tools with XCP-NG images`` -* :vytask:`T6293` ``add Mediatek MT7921 to defconfig`` -* :vytask:`T6339` ``Display the flavor name and build comment in "show version"`` -* :vytask:`T6395` ``Enable VFIO No-IOMMU support in kernel config`` - -**Bug fixes** - - -* :vytask:`T4576` ``vpn l2tp logging level configuration`` -* :vytask:`T5527` ``Adjust for change in coreutils behavior on overlayfs`` -* :vytask:`T5939` ``[1.3.5 -> 1.4.0-RC1 Migration] as-path-list Entries Get Messed Up`` -* :vytask:`T5940` ``[1.3.5 -> 1.4.0-RC1 Migration] commit-archive Fails to Migrate`` -* :vytask:`T6038` ``Losing default route after first reboot (cloud-init & DHCP)`` -* :vytask:`T6094` ``Destination Nat not Making Firewall Rules`` -* :vytask:`T6225` ``Unhandled exception when configuring random-detect QoS policy`` -* :vytask:`T6348` ``SNAT op-mode fails with flowtable offload entries`` -* :vytask:`T6356` ``Correct the syntax of config.boot.default [..., 'ntp', 'server'] from leaf node with value to tag node`` -* :vytask:`T6365` ``Negating interface names in NAT configuration causes invalid warnings`` -* :vytask:`T6377` ``PermissionError on /config/auth/letsencrypt/live/ when running show pki`` -* :vytask:`T6400` ``pki: unable to generate fingerprint for ACME issued certificates`` -* :vytask:`T6402` ``Invalid variables referenced in reverse proxy validation`` -* :vytask:`T6404` ``Include constraintGroup element in reference tree`` -* :vytask:`T6407` ``Generate ipsec profile error`` -* :vytask:`T6419` ``reverse-proxy: full CA chain is not build when verifying backend server`` -* :vytask:`T6421` ``host-name has no explicit priority to be set on system boot`` - -**Other resolved issues** - - -* :vytask:`T1981` ``Allow route-map 'set src' to reference both IPv4 and IPv6`` -* :vytask:`T3493` ``DHCPv6 does not have prefix range validation`` -* :vytask:`T4519` ``DHCPv6: "set show dhcpv6 server leases" should show DUID instead of IAID_DUID`` -* :vytask:`T4909` ``Rewrite the NTP op mode in the new format`` -* :vytask:`T5351` ``VyOS deployed with cloud-init improperly saves config.boot`` -* :vytask:`T6022` ``set system image default-boot`` -* :vytask:`T6048` ``Exception in event handler script`` -* :vytask:`T6328` ``Add a warning message about deprecation of web proxy URL filtering`` -* :vytask:`T6333` ``non-free-firmware to trixie`` -* :vytask:`T6345` ``Source NAT Port Mapping setting of Fully-Random is superfluous in Kernels 5.0 onwards`` -* :vytask:`T6346` ``Boot to multi-user.target instead of graphical.target`` -* :vytask:`T6358` ``Container config option to enable host pid`` -* :vytask:`T6367` ``op-mode: commit-archive: TypeError: attribute name must be string, not 'NoneType'`` -* :vytask:`T6383` ``Incorrect completion for rollback-soft`` -* :vytask:`T6384` ``rollback-soft should tell the user to compare and commit`` -* :vytask:`T6391` ``load-balancing reverse-proxy: typo in timeout help`` -* :vytask:`T6396` ``MINOR Typo: set system conntrack timeout custom ipv4 rule X`` -* :vytask:`T6409` ``Remove unused parameter node from reverse-proxy backend`` - -1.4.0-epa3 (14th May 2024) -========================== - -**Security** - - -* :vytask:`T6324` ``CVE-2024-2961`` - - -**Configuration syntax changes (automatically migrated)** - - -* :vytask:`T5535` ``Move disable-directed-broadcast to firewall global-options`` -* :vytask:`T6171` ``Rename the DHCP server "failover" command to "high-availability mode"`` -* :vytask:`T6208` ``container: rename "cap-add" CLI node to "capability"`` -* :vytask:`T6216` ``Firewall group names that contain the '+' character break the config`` -* :vytask:`T6295` ``netns: disable incomplete support in VyOS 1.4 sagitta`` - -**New features and improvements** - - -* :vytask:`T4309` ``Support network/address-groups and ipv6-network/ipv6-address-groups in "conntrack ignore"`` -* :vytask:`T4903` ``Support IPv6 addresses in "set system conntrack ignore"`` -* :vytask:`T5364` ``Make it possible to set the PADO delay to 0`` -* :vytask:`T6127` ``Ability to view logs for rules with Offload not functional`` -* :vytask:`T6133` ``Add domain-name to commit-archive`` -* :vytask:`T6143` ``Increase configuration timeout range for service config-sync`` -* :vytask:`T6154` ``Installer should ask for password twice`` -* :vytask:`T6161` ``Add support for displaying container image data in JSON`` -* :vytask:`T6162` ``ixgbe: Add 1000BASE-BX support`` -* :vytask:`T6171` ``Rename the DHCP server "failover" command to "high-availability mode"`` -* :vytask:`T6176` ``image-tools: rationalize setting of console type`` -* :vytask:`T6184` ``image-tools: add op-mode command to set default boot console type`` -* :vytask:`T6192` ``Support running SSH server in more than one VRF`` -* :vytask:`T6226` ``Add "tcp-requece inspect-delay" to reverse proxy`` -* :vytask:`T6257` ``Add op mode commands for dynamic firewall address groups`` -* :vytask:`T6258` ``Add IPv6 base-reachable-time option to interfaces`` -* :vytask:`T6260` ``image-tools: remove the image directory if it fails to install due to insufficient drive space`` -* :vytask:`T6267` ``Improve commit failure messages for wireless interface configuration`` -* :vytask:`T6278` ``Attempt hint for console type during image install`` -* :vytask:`T6291` ``Add op mode commands for displaying LACP information for bonding interfaces`` -* :vytask:`T6306` ``EVPN-MH - missing options in uplink ports`` - -**Bug fixes** - - -* :vytask:`T2590` ``DHCPv6 not updating nameservers and search domains since replacing isc-dhcp-client with WIDE dhcp6c`` -* :vytask:`T3655` ``NAT doesn't work correctly with VRF`` -* :vytask:`T4718` ``DHCP server listen-address doesn't take effect if the interface is in a VRF`` -* :vytask:`T5164` ``op cmd: "show dhcp server leases state" with available options does not show any result`` -* :vytask:`T5862` ``Default MTU is not acceptable in some environments`` -* :vytask:`T5875` ``login: removing and re-adding a user keeps the home directory but changes the UID, thus SSH keys no longer work`` -* :vytask:`T5996` ``Incorrect behavior for backslash escapes in config save and compare commands`` -* :vytask:`T6082` ``BGP doesn't allow the same local AS and remote AS in peer groups`` -* :vytask:`T6085` ``VTI interfaces are in UP state by default`` -* :vytask:`T6089` ``[1.3.6->1.4.0-epa1 Migration] "ospf passive-interface default" incorrectly added`` -* :vytask:`T6090` ``Migration of "policy route" configs fails due to TCP flag case sensitivity`` -* :vytask:`T6100` ``NAT config migration error in 1.4.0-epa1 if invalid address/network defined in 1.3.6 version`` -* :vytask:`T6106` ``Improve the commit error message for the case when route-reflector-client option is defined in a peer-group`` -* :vytask:`T6119` ``Use a compliant TOML parser`` -* :vytask:`T6130` ``[1.3.6->1.4.0-epa2 Migration] BGP "set community" missing`` -* :vytask:`T6131` ``Disabling openvpn interface(s) causes OSPF to fail to load on reboot`` -* :vytask:`T6136` ``Configuring a dynamic address group, config script did not check whether the group was created`` -* :vytask:`T6138` ``Conntrack table op-mode fails with flowtable offload entries`` -* :vytask:`T6145` ``Service config-sync does not rely on priorities`` -* :vytask:`T6147` ``Conntrack not working as expected with global state-policy`` -* :vytask:`T6149` ``Update node_data when merging nodes in reference tree generation`` -* :vytask:`T6152` ``Kernel panic for ZimaBoard 232`` -* :vytask:`T6160` ``Unhandled exception when configuring IS-IS`` -* :vytask:`T6165` ``grub: vyos-grub-update failed to start on "slow" systems`` -* :vytask:`T6167` ``VNI not set on VRF after reboot`` -* :vytask:`T6168` ``"add system image" does not set the default boot image to the current console type in compatibility mode`` -* :vytask:`T6169` ``DNS forwarding configuration rejects underscores in SRV records`` -* :vytask:`T6173` ``Build Causes Errors When "--version" Contains Slashes ("/")`` -* :vytask:`T6175` ``op-mode: "renew dhcp interface <name>" does not check if it's an actual DHCP interface`` -* :vytask:`T6178` ``reverse-proxy doesn't check that a certificate exists at set time`` -* :vytask:`T6179` ``Incorrect HAProxy config generated for reverse-proxy rules with url-path`` -* :vytask:`T6186` ``'set system image default-boot' fails to find images that actually do exist in the system`` -* :vytask:`T6189` ``BGP L3VPN connectivity is broken after re-enabling VRF`` -* :vytask:`T6191` ``Policy route set-mss option is not working correctly`` -* :vytask:`T6193` ``dhcp-client: invalid warning "is not a DHCP interface but uses DHCP name-server option" for VLAN interfaces`` -* :vytask:`T6196` ``route-map and summary-only do not work in BGP aggregation at the same time`` -* :vytask:`T6197` ``Validation error in the IPoE server interface client-subnet option`` -* :vytask:`T6202` ``Multi-Protocol BGP is broken by 6PE patch in upstream FRR 9.1`` -* :vytask:`T6205` ``ipoe: error in migration script logic while renaming mac-address to mac`` -* :vytask:`T6206` ``L2tp smoketest fails if vyos-configd is running`` -* :vytask:`T6207` ``image-tools: restore ability to copy config.boot.default on image install`` -* :vytask:`T6213` ``Validations in firewall groups mistakenly reject correct configurations`` -* :vytask:`T6216` ``Firewall group names that contain the '+' character break the config`` -* :vytask:`T6218` ``Container network interface in VRF fails to generate IPv6 link-local address`` -* :vytask:`T6221` ``Enabling VRF breaks connectivity`` -* :vytask:`T6222` ``VRRP rfc3768-compatibility not working correctly when resulting interface name is over 15 characters`` -* :vytask:`T6241` ``Updating CRL in "pki" config does not update OpenVPN`` -* :vytask:`T6243` ``Update vyos-http-api-tools for package idna security advisory`` -* :vytask:`T6250` ``"policy route-map set table" cannot be deleted from the rule`` -* :vytask:`T6252` ``GRE tunnels don't allow configuring MTU larger than 8024`` -* :vytask:`T6255` ``Static table description should not contain white-space`` -* :vytask:`T6263` ``Commit failures when trying to set an IGMP group with source address on an interface`` -* :vytask:`T6269` ``Polixy route "set table" option is not working correctly`` -* :vytask:`T6272` ``PPPoE configuration does not load after deleting a PPPoE interface from the system`` -* :vytask:`T6276` ``Do not call config dependencies on script error`` -* :vytask:`T6283` ``Cannot delete as-path prepend from policy when it contains more than one AS`` -* :vytask:`T6284` ``IPoE server op mode commands do not show IPv6 addresses`` -* :vytask:`T6299` ``Building VyOS (Dockerized) current ISO fails dues to unmet dependencies podman : Depends: libgpgme11t64 (>= 1.4.1) but it is not installable`` -* :vytask:`T6305` ``IPoE interface wildcard validation error in firewall rules`` -* :vytask:`T6307` ``procps is missing from vyos-1x build dependencies`` -* :vytask:`T6317` ``VLAN doesn't work on a bridge with a wireless interface member`` -* :vytask:`T6329` ``Firewall - Error while printing groups`` - -**Other resolved issues** - - -* :vytask:`T4516` ``Rewrite system image manipulation tools in Python`` -* :vytask:`T5535` ``Move disable-directed-broadcast to firewall global-options`` -* :vytask:`T6146` ``Add python script to get all priorities of service or section from XML`` -* :vytask:`T6159` ``"show openvpn server" prints a superfluous "OpenVPN status on vtunx" message for every client connection`` -* :vytask:`T6180` ``Add application of mask to configtree`` -* :vytask:`T6185` ``Simplify marshalling of section and config data for config-sync`` -* :vytask:`T6187` ``Use correct CPU counts adjusted for SMT when necessary`` -* :vytask:`T6195` ``dropbear: package upgrade 2022.83-1 -> 2022.83-1+deb12u1`` -* :vytask:`T6198` ``configverify: add common helper for PKI certificate validation`` -* :vytask:`T6203` ``Remove references to the obsolete vyos.xml module (superseded by vyos.xml_ref)`` -* :vytask:`T6208` ``container: rename "cap-add" CLI node to "capability"`` -* :vytask:`T6234` ``PPPoE-server pado-delay refactoring`` -* :vytask:`T6245` ``Unhandled exception in "show openvpn server"`` -* :vytask:`T6295` ``netns: disable incomplete support in VyOS 1.4 sagitta`` -* :vytask:`T6327` ``Drop boot console type ttyUSB (USB serial)`` -* :vytask:`T6330` ``release.pref.chroot indentation broken`` - -1.4.0-epa2 (15th March 2024) -============================ - - - -**Configuration syntax changes (automatically migrated)** - - -* :vytask:`T6079` ``dhcp: migration fails for duplicate static-mapping`` - -**New features and improvements** - - -* :vytask:`T4977` ``Babel routing protocol support`` -* :vytask:`T5504` ``Make it possible to set more than one peer-address in unicast VRRP`` -* :vytask:`T5530` ``Add LFA to IS-IS`` -* :vytask:`T5631` ``Ability to export the current configuration in JSON format`` -* :vytask:`T5717` ``ospfv3 - add allow to set metric-type to ospf redistribution while frr docs says its possible.`` -* :vytask:`T5772` ``Require HTTPS API server configurations to include at least one key if key-based auth is used`` -* :vytask:`T5781` ``Add ability to add additional minisign keys`` -* :vytask:`T6057` ``Add ability to disable syslog for conntrackd`` -* :vytask:`T6060` ``op-mode: container: support removing all container images at once`` -* :vytask:`T6087` ``ospfv3: add support to redistribute IS-IS routes`` - -**Bug fixes** - - -* :vytask:`T2998` ``SNMP v3 oid "exclude" option doesn't work`` -* :vytask:`T4270` ``When "ignore-hosts-file" is unset, local hostname of the router resolves to 127.0.1.1 in the DNS forwarding service`` -* :vytask:`T5121` ``Incorrect "architecture" config loaded`` -* :vytask:`T5646` ``QoS policy limiter broken if class without match`` -* :vytask:`T5909` ``Container registry with authentication prevents config load (section container) after reboot`` -* :vytask:`T6004` ``Missing RPKI boot priority prevents it from loading`` -* :vytask:`T6020` ``VRRP health-check script is not applied correctly in keepalived.conf`` -* :vytask:`T6054` ``load-balancing wan - doesn't configure a list of ports`` -* :vytask:`T6055` ``PKI error: "failed to install x value" when executed the command from conf mode`` -* :vytask:`T6061` ``connection-status nat destination firewall filter not working in 1.4.0-epa1`` -* :vytask:`T6069` ``HTTP API segfault during concurrent configuration requests`` -* :vytask:`T6070` ``bnx2x NIC causes a commit error due to incorrect implementation of EEE status reading`` -* :vytask:`T6073` ``Conntrack/NAT not being disabled when VRFs are defined`` -* :vytask:`T6074` ``container: do not allow deleting images which have a container running`` -* :vytask:`T6079` ``dhcp: migration fails for duplicate static-mapping`` -* :vytask:`T6081` ``QoS policy shaper target and interval wrong calcuations`` -* :vytask:`T6084` ``OpenNHRP DMVPN configuration file clean after reboot if we have any IPSec configuration`` -* :vytask:`T6086` ``NAT does not work with network-groups`` -* :vytask:`T6093` ``Incorrect dhcp-options vendor-class-id regex`` -* :vytask:`T6096` ``Config commits are not synced properly because 00vyos-sync is deleted by vyos-router`` -* :vytask:`T6098` ``Description doesnt seem to allow for non international characters`` -* :vytask:`T6104` ``Regression in commit-archive for non-interactive configuration`` -* :vytask:`T6107` ``Nginx does not allow big config queries for configure endpoint API`` -* :vytask:`T6141` ``Trying to set PADO delay in PPPoE server without also configuring the session options causes a commit failure`` - -**Other resolved issues** - - -* :vytask:`T2199` ``Rewrite firewall in new XML/Python style`` -* :vytask:`T5738` ``Extend XML building blocks`` -* :vytask:`T5870` ``ipsec remote access VPN: add x509 ("pubkey") authentication`` -* :vytask:`T5959` ``Streamline dns forwarding service`` -* :vytask:`T6071` ``firewall: CLI description limit of 256 characters cause config upgrade issues`` -* :vytask:`T6075` ``Applying firewall rules with a non-existent interface group`` -* :vytask:`T6077` ``banner: implement ASCII contest winner default logo`` -* :vytask:`T6083` ``ethtool: move string parsing to JSON parsing`` -* :vytask:`T6095` ``Tab completion for "set interfaces wireless wlan0 country-code" incorrect country "uk"`` -* :vytask:`T6214` ``Error when using some constraints`` - -1.4.0-epa1 (22th February 2024) -=============================== - -**Security** - - -* :vytask:`T4915` ``Minisign verification failure == pass??`` - -**Breaking changes** - - -* :vytask:`T5605` ``Do not generate keysize option in OpenVPN configs`` - -**Configuration syntax changes (automatically migrated)** - - -* :vytask:`T1991` ``Rework time services`` -* :vytask:`T5877` ``Reduce unnecessary nesting in system domain-search path and improve smoketest`` - -**New features and improvements** - - -* :vytask:`T160` ``Support NAT64`` -* :vytask:`T1991` ``Rework time services`` -* :vytask:`T4221` ``Add a template filter for converting scalars to single-item lists`` -* :vytask:`T4883` ``Add a description field for routing tables`` -* :vytask:`T4940` ``Interface debugging`` -* :vytask:`T5122` ``Move "archive-areas" to defaults.toml to support "non-free-firmware" repository`` -* :vytask:`T5418` ``Allow arbitrary subnets in PPPoE client IP pools`` -* :vytask:`T5449` ``Add options for TCP MSS probing`` -* :vytask:`T5497` ``Add ability to resequence rule numbers for firewall`` -* :vytask:`T5615` ``Narrow down spurious name conflict with mdns`` -* :vytask:`T5877` ``Reduce unnecessary nesting in system domain-search path and improve smoketest`` -* :vytask:`T5965` ``WWAN modems using raw-ip do not work with dhclient/dhcp6c`` -* :vytask:`T5972` ``login: add possibility to disable individual local user accounts`` - -**Bug fixes** - - -* :vytask:`T2113` ``OpenVPN Options error: you cannot use --verify-x509-name with --compat-names or --no-name-remapping`` -* :vytask:`T2700` ``Redirecting traffic from PPPoE interface to IFB fails`` -* :vytask:`T2801` ``conntrack-tools flooding logs`` -* :vytask:`T3681` ``The VMware Tools resume script did not run successfully in this virtual machine.`` -* :vytask:`T3774` ``atop logs are not limited in size`` -* :vytask:`T3902` ``Firewall does not load on boot, address-group not found, even though it exists`` -* :vytask:`T4796` ``build-vyos-image ignores multiple options`` -* :vytask:`T5239` ``Host name and domain name missing from the FRR configuration`` -* :vytask:`T5245` ``Wireless interfaces do not get IPv6 link-local address assigned`` -* :vytask:`T5376` ``Conntrack FTP helper does not work properly`` -* :vytask:`T5890` ``OTP key generation is broken`` -* :vytask:`T5926` ``IPSEC does not apply after l2tp configuration was changed`` -* :vytask:`T5977` ``nftables: Operation not supported when using match-ipsec in outbound firewall`` -* :vytask:`T6005` ``Error on adding a wireguard interface to OSPFv3`` -* :vytask:`T6043` ``VxLAN and bridge error bug`` -* :vytask:`T6056` ``Applying 'system static-host-mapping' command calls unnecessary snmpd restart`` -* :vytask:`T6064` ``Can not build VyOS if repository it not cloned to a branch`` - -**Other resolved issues** - - -* :vytask:`T671` ``Identify and remove dead code`` -* :vytask:`T874` ``Support for Two Factor Authentication for CLI access via Google Authenticator/OTP`` -* :vytask:`T1311` ``WAN load-balancing can't flush connections when conntrack-sync is enabled`` -* :vytask:`T1436` ``Config entries with default values do not correctly show as changed`` -* :vytask:`T1487` ``DNS (pdns_recursor) stats logs not saved to disk`` -* :vytask:`T2433` ``Improve CLI value validator performance`` -* :vytask:`T3337` ``Add possibility to serve static DNS zones from the router`` -* :vytask:`T3471` ``DHCP hook is not able to detect all running DHCP instances`` -* :vytask:`T3474` ``Revisit storing syntax version of interface definitions in XML file`` -* :vytask:`T3522` ``policy based routing not working`` -* :vytask:`T3574` ``Add constraintGroup for combining validators with logical AND`` -* :vytask:`T3642` ``PKI configuration`` -* :vytask:`T3722` ``op-mode IPSec show vpn ike sa always shows L-TIME 0`` -* :vytask:`T3766` ``containers: Expanding options for networking and building containers`` -* :vytask:`T4723` ``Error when issuing 'show flow-accounting interface pppoe0'`` -* :vytask:`T4761` ``Add a generic URL validator`` -* :vytask:`T4795` ``Cleanup custom python validators`` -* :vytask:`T4951` ``Add an op mode exception for cases when operations fail due to insufficient system resources`` -* :vytask:`T5109` ``Improve OCaml XML validator`` -* :vytask:`T5195` ``Break up the vyos.util module`` -* :vytask:`T5348` ``Service config-sync can freeze the secondary router if it has commit-archive location`` -* :vytask:`T5605` ``Do not generate keysize option in OpenVPN configs`` -* :vytask:`T5754` ``Update to StrongSwan 5.9.11`` -* :vytask:`T5846` ``Refactor and simplify DUID definition in conf-mode`` -* :vytask:`T5903` ``NHRP don´t start on reboot from version 1.5-rolling-202401010026`` -* :vytask:`T6001` ``Add option to enable resolve-via-default`` -* :vytask:`T6015` ``"journalctl_charon" file does not contain data in the generated "ipsec debug-archive" file`` -* :vytask:`T6050` ``Wrong scripting commands descriptions in accel-ppp services`` -* :vytask:`T6078` ``Update ethtool to 6.6`` diff --git a/docs/changelog/1.5.rst b/docs/changelog/1.5.rst deleted file mode 100644 index 94d7b9ab..00000000 --- a/docs/changelog/1.5.rst +++ /dev/null @@ -1,1295 +0,0 @@ -############ -1.5 Circinus -############ - -.. - Please don't add anything by hand. - This file is managed by the script: - _ext/releasenotes.py - - -2024-04-26 -========== - -* :vytask:`T6259` ``(feature): PKI: Support RFC822 (email) names in SAN`` - - -2024-04-25 -========== - -* :vytask:`T6263` ``(bug): Multicast: Could not commit multicast config with multicast join group using source-address`` -* :vytask:`T5833` ``(bug): Not all AFIs compatible with VRF`` - - -2024-04-24 -========== - -* :vytask:`T6255` ``(bug): Static table description should not contain white-space`` -* :vytask:`T6226` ``(feature): add HAPROXY `tcp-request content accept` related block to load-balancing reverse proxy config`` -* :vytask:`T6109` ``(bug): remote syslog do not get all the logs`` -* :vytask:`T6262` ``(default): Update the boot splash for VyOS 1.5 ISO`` -* :vytask:`T6217` ``(feature): VRRP contrack-sync script change name of the logger`` -* :vytask:`T6244` ``(feature): Spacing of "Show System Uptime" hard to parse`` - - -2024-04-23 -========== - -* :vytask:`T6260` ``(bug): image-tools: remove failed image directory if 'No space left on device' error`` -* :vytask:`T6261` ``(default): Typo in op_mode connect_disconnect print statement for check_ppp_running`` -* :vytask:`T6237` ``(feature): IPSec remote access VPN: ability to set EAP ID of clients`` - - -2024-04-22 -========== - -* :vytask:`T5996` ``(bug): unescape backslashes for config save, compare commands`` - - -2024-04-21 -========== - -* :vytask:`T6191` ``(bug): Policy Route TCP-MSS Behavior Different from 1.3.x`` -* :vytask:`T5535` ``(feature): disable-directed-broadcast should be moved to firewall global-options`` - - -2024-04-20 -========== - -* :vytask:`T6252` ``(bug): gre tunnel - doesn't allow configure jumbo frame more than 8024`` - - -2024-04-19 -========== - -* :vytask:`T6221` ``(bug): Enabling VRF breaks connectivity`` -* :vytask:`T6035` ``(bug): QoS policy shaper queue-type random-detect requires limit avpkt`` -* :vytask:`T6246` ``(feature): Enable basic haproxy http-check configuration options`` -* :vytask:`T6242` ``(feature): Loadbalancer reverse-proxy: SSL backend skip CA certificate verification`` - - -2024-04-17 -========== - -* :vytask:`T6168` ``(bug): add system image does not set default boot to current console type in compatibility mode`` -* :vytask:`T6243` ``(bug): Update vyos-http-api-tools for package idna security advisory`` -* :vytask:`T6154` ``(enhancment): Installer should ask for password twice`` -* :vytask:`T5966` ``(default): Adjust dynamic dns configuration address subpath to be more intuitive and other op-mode adjustments`` -* :vytask:`T5723` ``(default): mdns repeater: Always reload systemd daemon before applying changes`` -* :vytask:`T5722` ``(bug): Failing to add route in failover if gateway not in the same interface network`` -* :vytask:`T5612` ``(default): Miscellaneous improvements and fixes for dynamic DNS configuration`` -* :vytask:`T5574` ``(default): Support per-service cache management for dynamic dns providers`` - - -2024-04-16 -========== - -* :vytask:`T6099` ``(bug): Suppress unsupported interfaces from appearing in messages log by Telegraf`` - - -2024-04-15 -========== - -* :vytask:`T6163` ``(bug): kea-dhcp4-server crashes due to incorrect lease file permissions after 1.5-rolling-202403120022 -> 1.5-rolling-202403230018 upgrade`` -* :vytask:`T6100` ``(bug): NAT config migration error in 1.4.0-epa1 if invalid address/network defined in 1.3.6 version`` -* :vytask:`T6174` ``(bug): can't view dhcp server leases if logged in as a tacacs account`` -* :vytask:`T5734` ``(bug): OpenVPN server dh-params that are not in PKI error`` - - -2024-04-14 -========== - -* :vytask:`T6210` ``(feature): Add container ability to configure capability sys-nice`` - - -2024-04-13 -========== - -* :vytask:`T6173` ``(bug): Build Causes Errors When "--version" Contains Slashes ("/")`` -* :vytask:`T2518` ``(feature): Support NAT for ipv6(NPT)`` - - -2024-04-12 -========== - -* :vytask:`T6214` ``(bug): Error when using some constraints`` -* :vytask:`T6213` ``(bug): Firewall group constraints`` -* :vytask:`T6222` ``(bug): VRRP rfc3768-compatibility not working correctly when resulting interface name is over 15 characters`` -* :vytask:`T6218` ``(bug): Container network interface in VRF fails to generate IPv6 link-local address`` -* :vytask:`T5044` ``(feature): High Availability in DHCPv6 -ISC DHCP Failover/Kea`` -* :vytask:`T6166` ``(bug): Tech support generation error for custom output location`` -* :vytask:`T344` ``(feature): Software basesd FastPath`` - - -2024-04-11 -========== - -* :vytask:`T4516` ``(feature): Rewrite system image manipulation tools in Python`` -* :vytask:`T4548` ``(feature): GRUB loader configuration rework`` -* :vytask:`T6228` ``(bug): Cleanup of not existing units`` - - -2024-04-10 -========== - -* :vytask:`T6207` ``(bug): image-tools: restore ability to copy config.boot.default on image install`` -* :vytask:`T6106` ``(bug): Valid commit error for route-reflector-client option defined in peer-group`` -* :vytask:`T5750` ``(bug): Upgrade from 1.3.4 to 1.4 Rolling fails QoS`` -* :vytask:`T5740` ``(bug): Generate wiregurad keys via HTTP-API fails`` -* :vytask:`T5858` ``(bug): Show conntrack statistics formatting is all over the place`` - - -2024-04-09 -========== - -* :vytask:`T6121` ``(feature): Extend service config-sync for sections vpn, policy, vrf`` - - -2024-04-08 -========== - -* :vytask:`T6197` ``(bug): IPoE-server interface client-subnet looks broken or works with the wrong logic`` -* :vytask:`T6196` ``(bug): Route-map and summary-only do not work in BGP aggregation at the same time`` -* :vytask:`T6068` ``(feature): dhcp server: allow switching between load-balanced and hotspare mode`` - - -2024-04-07 -========== - -* :vytask:`T6205` ``(bug): ipoe: error in migration script logic while renaming mac-address to mac node`` -* :vytask:`T5862` ``(bug): Default MTU is not acceptable in some environments`` -* :vytask:`T6208` ``(feature): container: rename "cap-add" CLI node to "capability"`` -* :vytask:`T6188` ``(feature): Add Firewall Rule Description to "show firewall" commands`` -* :vytask:`T1244` ``(default): Support for StartupResync in conntrackd`` - - -2024-04-06 -========== - -* :vytask:`T6203` ``(enhancment): Remove obsoleted xml lib`` -* :vytask:`T6202` ``(bug): Multi-Protocol BGP is broken by 6PE patch in upstream FRR 9.1`` - - -2024-04-05 -========== - -* :vytask:`T6089` ``(bug): [1.3.6->1.4.0-epa1 Migration] "ospf passive-interface default" incorrectly added`` -* :vytask:`T2590` ``(bug): DHCPv6 not updating nameservers and search domains since replacing isc-dhcp-client with WIDE dhcp6c`` -* :vytask:`T6199` ``(feature): spring cleaning - drop unused Python imports`` - - -2024-04-04 -========== - -* :vytask:`T6119` ``(default): Use a compliant TOML parser`` -* :vytask:`T6171` ``(feature): dhcp server fail-over - Rename fail-over node`` -* :vytask:`T6128` ``(bug): minisign.pub is wrong on https://vyos.net/get/nightly-builds/`` -* :vytask:`T5882` ``(feature): vyos-utils: move to Dune as build system`` -* :vytask:`T5864` ``(default): 'show ntp' Commands Not Working`` -* :vytask:`T3843` ``(bug): l2tp configuration not cleared after delete`` -* :vytask:`T2187` ``(feature): Python Unit testing`` -* :vytask:`T788` ``(bug): Nightly builds are not signed`` - - -2024-04-03 -========== - -* :vytask:`T6198` ``(feature): configverify: add common helper for PKI certificate validation`` -* :vytask:`T6192` ``(feature): Multi VRF support for SSH`` - - -2024-04-02 -========== - -* :vytask:`T6167` ``(bug): VNI not set on VRF after reboot`` -* :vytask:`T6151` ``(default): BGP VRF - Route-leaking not work when the next-hop is a recursive route.`` -* :vytask:`T6033` ``(bug): hsflowd fails to start when using a tunnel interface`` - - -2024-04-01 -========== - -* :vytask:`T6195` ``(feature): dropbear: package upgrade 2022.83-1 -> 2022.83-1+deb12u1`` -* :vytask:`T6193` ``(bug): dhcp-client: invalid warning "is not a DHCP interface but uses DHCP name-server option" for VLAN interfaces`` -* :vytask:`T6178` ``(bug): Reverse-proxy should check that certificate exists during commit`` - - -2024-03-31 -========== - -* :vytask:`T6186` ``(bug): Fix regression in 'set system image default-boot'`` -* :vytask:`T5832` ``(feature): Keepalived: Allow using the 'dev' statement on excluded-addresses`` - - -2024-03-29 -========== - -* :vytask:`T6159` ``(bug): Openvpn Server Op-cmd adds heading "OpenVPN status on vtunx" for every client connection`` - - -2024-03-28 -========== - -* :vytask:`T6147` ``(bug): Conntrack not working as expected with global state-policy`` -* :vytask:`T6175` ``(bug): op-mode: "renew dhcp interface <name>" does not check if it's an actual DHCP interface`` -* :vytask:`T6102` ``(bug): Clear dhcp-server lease throws python exception on 1.5-rolling`` - - -2024-03-26 -========== - -* :vytask:`T6066` ``(bug): Setting same network in different ospf area will raise exception`` - - -2024-03-25 -========== - -* :vytask:`T6145` ``(bug): Service config-sync does not rely on priorities but must`` - - -2024-03-24 -========== - -* :vytask:`T6161` ``(feature): Output container images as JSON`` -* :vytask:`T6165` ``(bug): grub: vyos-grub-update failed to start on "slow" systems`` -* :vytask:`T6085` ``(bug): VTI interfaces are in UP state by default`` -* :vytask:`T6152` ``(bug): Kernel panic for ZimaBoard 232`` - - -2024-03-23 -========== - -* :vytask:`T6160` ``(bug): isis: NameError: name 'process' is not defined`` -* :vytask:`T6131` ``(bug): Disabling openvpn interface(s) causes OSPF to fail to load on reboot`` -* :vytask:`T4022` ``(feature): Add package nat-rtsp-dkms`` - - -2024-03-22 -========== - -* :vytask:`T6136` ``(bug): Configuring a dynamic address group, config script did not check whether the group was created`` -* :vytask:`T6130` ``(bug): [1.3.6->1.4.0-epa2 Migration] BGP "set community" missing`` -* :vytask:`T6090` ``(bug): [1.3.6->1.4.0-epa1 Migration] policy route fails due tcp flag case sensitivity`` -* :vytask:`T6155` ``(default): ixgbe: failed to initialize because an unsupported SFP+ module type was detected.`` -* :vytask:`T6125` ``(feature): Support 802.1ad (0x88a8) vlan filtering for bridge`` - - -2024-03-21 -========== - -* :vytask:`T6143` ``(feature): Increase configuration timeout range for service config-sync`` - - -2024-03-20 -========== - -* :vytask:`T6133` ``(feature): Add domain-name to commit-archive`` -* :vytask:`T6129` ``(feature): bgp: add route-map option "as-path exclude all"`` - - -2024-03-19 -========== - -* :vytask:`T6127` ``(bug): Ability to view logs for rules with Offload not functional`` -* :vytask:`T6138` ``(bug): Conntrack table op-mode fails with flowtable offload entries`` - - -2024-03-15 -========== - -* :vytask:`T6118` ``(feature): radvd: RFC8781: add nat64prefix support`` - - -2024-03-12 -========== - -* :vytask:`T6020` ``(bug): VRRP health-check script is not applied correctly in keepalived.conf`` -* :vytask:`T5646` ``(bug): QoS policy limiter broken if class without match`` - - -2024-03-11 -========== - -* :vytask:`T6098` ``(bug): Description doesnt seem to allow for non international characters`` -* :vytask:`T2998` ``(bug): SNMP v3 oid "exclude" option doesn't work`` -* :vytask:`T6107` ``(bug): Nginx does not allow big config queries for configure endpoint API`` -* :vytask:`T6096` ``(bug): Config commits are not synced properly because 00vyos-sync is deleted by vyos-router`` -* :vytask:`T6093` ``(bug): Incorrect dhcp-options vendor-class-id regex`` -* :vytask:`T6083` ``(feature): ethtool: move string parsing to JSON parsing`` -* :vytask:`T6069` ``(bug): HTTP API segfault during concurrent configuration requests`` -* :vytask:`T6057` ``(feature): Add ability to disable syslog for conntrackd`` -* :vytask:`T5504` ``(feature): Keepalived VRRP ability to set more than one peer-address`` -* :vytask:`T5717` ``(feature): ospfv3 - add allow to set metric-type to ospf redistribution while frr docs says its possible.`` -* :vytask:`T6071` ``(bug): firewall: CLI description limit of 256 characters cause config upgrade issues`` - - -2024-03-08 -========== - -* :vytask:`T6086` ``(bug): NAT does not work with network-groups`` -* :vytask:`T6094` ``(bug): Destination Nat not Making Firewall Rules`` -* :vytask:`T6061` ``(bug): connection-status nat destination firewall filter not working in 1.4.0-epa1`` -* :vytask:`T6075` ``(bug): Applying firewall rules with a non-existent interface group`` - - -2024-03-07 -========== - -* :vytask:`T6104` ``(bug): Regression in commit-archive for non-interactive configuration`` -* :vytask:`T6084` ``(bug): OpenNHRP DMVPN configuration file clean after reboot if we have any IPSec configuration`` -* :vytask:`T5348` ``(bug): Service config-sync can freeze the secondary router if it has commit-archive location`` -* :vytask:`T6073` ``(bug): Conntrack/NAT not being disabled when VRFs are defined`` -* :vytask:`T6095` ``(default): Tab completion for "set interfaces wireless wlan0 country-code" incorrect country "uk"`` - - -2024-03-06 -========== - -* :vytask:`T6079` ``(bug): dhcp: migration fails for duplicate static-mapping`` -* :vytask:`T6063` ``(default): Kea DHCP: Expose match-client-id setting`` -* :vytask:`T5992` ``(default): DHCP: show dhcp server leases not showing all leases`` - - -2024-03-05 -========== - -* :vytask:`T5903` ``(bug): NHRP don´t start on reboot from version 1.5-rolling-202401010026`` -* :vytask:`T2447` ``(feature): Additional Boot Argument Configuration to limit CPU C-States`` - - -2024-03-04 -========== - -* :vytask:`T6087` ``(feature): ospfv3: add support to redistribute IS-IS routes`` - - -2024-03-02 -========== - -* :vytask:`T6081` ``(bug): QoS policy shaper target and interval wrong calcuations`` - - -2024-02-29 -========== - -* :vytask:`T6078` ``(feature): Update ethtool to 6.6`` -* :vytask:`T6077` ``(feature): banner: implement ASCII contest winner default logo`` -* :vytask:`T6074` ``(feature): container: do not allow deleting images which have a container running`` - - -2024-02-28 -========== - -* :vytask:`T4270` ``(bug): dns forwarding - When "ignore-hosts-file" is unset, local hostname of router resolves to 127.0.1.1`` - - -2024-02-26 -========== - -* :vytask:`T6064` ``(bug): Can not build VyOS if repository it not cloned to a branch`` -* :vytask:`T5754` ``(default): Update to StrongSwan 5.9.11`` - - -2024-02-25 -========== - -* :vytask:`T6060` ``(feature): op-mode: container: support removing all container images at once`` - - -2024-02-24 -========== - -* :vytask:`T5909` ``(bug): Container registry with authentication prevents config load (section container) after reboot`` - - -2024-02-23 -========== - -* :vytask:`T5376` ``(bug): Conntrack FTP helper does not work properly`` - - -2024-02-22 -========== - -* :vytask:`T6048` ``(bug): Exception in event handler script`` - - -2024-02-21 -========== - -* :vytask:`T6050` ``(bug): Wrong scripting commands descriptions in accel-ppp services`` -* :vytask:`T3771` ``(feature): DHCPv6 server prefix delegation - dynamically add route to delegated prefix via requesting router`` - - -2024-02-19 -========== - -* :vytask:`T5971` ``(default): Create the same view of ppp section for all accel-ppp services`` -* :vytask:`T6029` ``(default): Rewrite Accel-PPP services to an identical feature set`` -* :vytask:`T3722` ``(bug): op-mode IPSec show vpn ike sa always shows L-TIME 0`` - - -2024-02-18 -========== - -* :vytask:`T6043` ``(bug): VxLAN and bridge error bug`` -* :vytask:`T6041` ``(bug): image-tools: install fails from PXE boot into live iso due to restrictive logic`` - - -2024-02-17 -========== - -* :vytask:`T5972` ``(feature): login: add possibility to disable individual local user accounts`` - - -2024-02-16 -========== - -* :vytask:`T6009` ``(bug): Firewall - Time not working properly when not using UTC`` -* :vytask:`T6005` ``(bug): Error on adding a wireguard interface to OSPFv3`` -* :vytask:`T6019` ``(feature): Bump nftables and libnftnl version`` -* :vytask:`T6001` ``(default): Add option to enable resolve-via-default`` -* :vytask:`T5965` ``(bug): WWAN modems using raw-ip do not work with dhclient/dhcp6c`` -* :vytask:`T5245` ``(bug): Wireless interfaces do not get IPv6 link-local address assigned`` - - -2024-02-15 -========== - -* :vytask:`T5977` ``(bug): nftables: Operation not supported when using match-ipsec in outbound firewall`` -* :vytask:`T2612` ``(bug): HTTPS API, changing API key fails but goes through`` -* :vytask:`T5989` ``(bug): IP subnets not usable in UPnP ACLs`` -* :vytask:`T5719` ``(default): mdns repeater: Add op-mode commands`` -* :vytask:`T4839` ``(feature): Dynamic Firewall groups`` - - -2024-02-14 -========== - -* :vytask:`T6034` ``(feature): rpki: move file based SSH keys for authentication to PKI subsystem`` -* :vytask:`T5981` ``(bug): IPsec site-to-site migrated PKI ca certificates are created with an '@'`` -* :vytask:`T5930` ``(bug): vrf - route-leak not work using route-target both command.`` -* :vytask:`T5709` ``(bug): IPoE-server fails if next pool mentioned but not defined`` -* :vytask:`T2044` ``(bug): RPKI doesn't boot properly`` -* :vytask:`T6032` ``(feature): bgp: add EVPN MAC-VRF Site-of-Origin support`` -* :vytask:`T5960` ``(default): Rewriting authentication section in accel-ppp services`` - - -2024-02-13 -========== - -* :vytask:`T5928` ``(bug): Configuration fails to load on boot if offloading has VLAN interfaces defined`` -* :vytask:`T5064` ``(bug): Value validation for domain-groups seems to be broken`` - - -2024-02-12 -========== - -* :vytask:`T6010` ``(bug): Support setting multiple values in BGP path-attribute`` -* :vytask:`T6004` ``(bug): RPKI is not configured`` -* :vytask:`T5952` ``(default): DHCP allow same MAC Address on same subnet`` -* :vytask:`T5849` ``(feature): Add SRv6 route commands`` - - -2024-02-10 -========== - -* :vytask:`T6023` ``(bug): rpki: add support for CLI knobs expire-interval and retry-interval`` - - -2024-02-09 -========== - -* :vytask:`T6028` ``(bug): QoS policy shaper wrong class_id_max and default_minor_id`` -* :vytask:`T6026` ``(bug): QoS hide attempts to delete qdisc from devices`` -* :vytask:`T5788` ``(feature): frr: update to 9.1 release`` -* :vytask:`T5703` ``(bug): QoS config on pppoe interface resets back to fq_codel after tunnel reboots`` -* :vytask:`T5685` ``(feature): Keepalived VRRP prefix is not necessary for the virtual address`` - - -2024-02-08 -========== - -* :vytask:`T6014` ``(feature): Bump keepalived version`` -* :vytask:`T5910` ``(bug): Grub problem(?) Serial Console no longer working`` -* :vytask:`T6021` ``(bug): QoS r2q wrong calculation`` - - -2024-02-07 -========== - -* :vytask:`T6017` ``(bug): Update vyos-http-api-tools for security advisory`` -* :vytask:`T6016` ``(bug): Resolve intermittent failures in cleanup function after failed image install`` -* :vytask:`T6024` ``(feature): bgp: add additional missing FRR features`` -* :vytask:`T6011` ``(feature): rpki: known-hosts-file is no longer supported by FRR CLI - remove VyOS CLI node`` -* :vytask:`T5998` ``(feature): replay_window setting under vpn in config`` - - -2024-02-06 -========== - -* :vytask:`T6018` ``(default): smoketest: updating http-api framework requires a pause before test`` -* :vytask:`T5921` ``(bug): Trying to commit an OpenConnect configuration without any local users results in an exception`` -* :vytask:`T5687` ``(feature): Implement ECS settings for PowerDNS recursor`` - - -2024-02-05 -========== - -* :vytask:`T5974` ``(bug): QoS policy shaper is currently miscalculating bandwidth and ceil values for the default class`` -* :vytask:`T5865` ``(feature): Rewrite ipv6 pool section to ipv6 named pools in Accel-ppp services`` - - -2024-02-02 -========== - -* :vytask:`T5739` ``(bug): Password recovery does not work if public keys are configured`` -* :vytask:`T5955` ``(feature): Rootless containers/set uid/gid for container`` -* :vytask:`T6003` ``(feature): Add 'show rpki as-number' and 'show rpki prefix'`` -* :vytask:`T5848` ``(feature): Add triple-isolate flow isolation option to CAKE QoS policy`` - - -2024-02-01 -========== - -* :vytask:`T5995` ``(bug): Kernel NIC-drivers for Huawei NICs are not properly enabled`` -* :vytask:`T5978` ``(bug): ethernet: hw-tc-offload does not actually get enabled on the NIC`` -* :vytask:`T5979` ``(enhancment): Add configurable kernel boot parameters`` -* :vytask:`T5973` ``(bug): vrf: RTNETLINK answers: File exists`` -* :vytask:`T5967` ``(bug): Multi-hop BFD connections can't be established; please add minimum-ttl option.`` -* :vytask:`T5619` ``(default): Update the Intel ixgbe driver due to issues with Intel X533`` - - -2024-01-31 -========== - -* :vytask:`T6000` ``(bug): [1.3.x -> 1.5.x] migrating threw exception in /opt/vyatta/etc/config-migrate/migrate/https/5-to-6, performed workaround`` -* :vytask:`T5999` ``(bug): load-balancing reverse-proxy can't configure root as a redirect`` - - -2024-01-30 -========== - -* :vytask:`T5980` ``(feature): Add image-tools support for configurable kernel boot options`` - - -2024-01-29 -========== - -* :vytask:`T5988` ``(bug): image-tools: a check of valid image name is missing from 'add image'`` -* :vytask:`T5994` ``(bug): Fix typo in 'remote' module preventing 'add system image' via ftp`` - - -2024-01-26 -========== - -* :vytask:`T5957` ``(bug): Firewall fails to delete inbound-interface name`` -* :vytask:`T5779` ``(bug): custom conntrack timeout rule not applicable`` -* :vytask:`T5984` ``(feature): Add user util numactl`` - - -2024-01-25 -========== - -* :vytask:`T5983` ``(bug): image-tools: minor regression in pruning version files in compatibility mode`` -* :vytask:`T5927` ``(bug): QoS policy shaper-hfsc class does not have a `bandwidth` node but requires one in the check`` -* :vytask:`T5834` ``(bug): Rename 'enable-default-log' to 'default-log'`` - - -2024-01-22 -========== - -* :vytask:`T5968` ``(feature): hsflowd: add VRF support`` -* :vytask:`T5961` ``(bug): QoS policy shaper vif with ceiling fails on commit`` -* :vytask:`T5958` ``(bug): QoS policy shaper-hfsc is not implemented`` -* :vytask:`T5969` ``(feature): op-mode: list multicast group membership`` - - -2024-01-21 -========== - -* :vytask:`T5799` ``(bug): vyos unbootable after 1.4-rolling-202308240020 to 1.5-rolling-202312010026 upgrade`` -* :vytask:`T5787` ``(bug): dhcp-server allows duplicate static-mapping for the same IP address`` -* :vytask:`T5912` ``(bug): DHCP Static mapping don't work on every first lease`` -* :vytask:`T5692` ``(enhancment): NTP leap smear`` -* :vytask:`T5954` ``(feature): Enable nvme_hwmon and drivetemp in KERNEL`` - - -2024-01-20 -========== - -* :vytask:`T5964` ``(bug): disconnect interface wwan0 throws exception`` -* :vytask:`T5948` ``(bug): pdns-recursor crashes on restart if hostfile-update is enabled and dhcp client sends hostname with trailing dot`` -* :vytask:`T5945` ``(bug): Missing minisign public key for rolling release`` -* :vytask:`T5922` ``(bug): Firewall - bug in zone config`` -* :vytask:`T5915` ``(bug): Firewall zone - Re add op-mode commands`` -* :vytask:`T5724` ``(feature): About dhcp client hooks`` -* :vytask:`T5721` ``(bug): Error in migrating configuration from VyOS 1.4`` -* :vytask:`T5550` ``(bug): Source validation on interface does not work properly`` -* :vytask:`T5239` ``(bug): frr 'hostname' missing or incorrect, and domain-name missing totally`` -* :vytask:`T4726` ``(default): Add completion and validation for the accel-ppp RADIUS vendor option`` -* :vytask:`T4085` ``(feature): Rewrite L2TP/PPTP/SSTP/PPPoE services to get_config_dict`` -* :vytask:`T5963` ``(bug): QoS policy shaper rate calculations could be wrong for some ethernet devices`` -* :vytask:`T5876` ``(bug): Dhcp bug in latest 1.5 rolling releases`` -* :vytask:`T5962` ``(feature): QoS policy set default speed to 100mbit or 1gbit instead of 10mbit`` - - -2024-01-19 -========== - -* :vytask:`T5897` ``(bug): VyOS with Cloud-init and VRF stucks at reboot/shutdown process`` -* :vytask:`T5554` ``(bug): Disable sudo for PAM RADIUS`` -* :vytask:`T4754` ``(default): Improvement: system login: show configured 2FA OTP key`` -* :vytask:`T5857` ``(bug): show interfaces wireless info`` -* :vytask:`T5841` ``(default): Remove old ssh-session-cleanup.service`` -* :vytask:`T5884` ``(default): Minor description fix (op-mode: generate wireguard)`` -* :vytask:`T5781` ``(default): Add ability to add additional minisign keys`` - - -2024-01-18 -========== - -* :vytask:`T5863` ``(bug): Failure to Load Config on Recent 1.5 Versions`` -* :vytask:`T4638` ``(bug): Deleting a parent interface does not delete its underlying VLAN interfaces`` -* :vytask:`T5953` ``(default): Rename 'close_action' value from `hold` to `trap` in IPSEC IKE`` - - -2024-01-17 -========== - -* :vytask:`T5923` ``(bug): Config mode system_console.py is not aware of revised GRUB file structure`` -* :vytask:`T4658` ``(feature): Rename DPD action `hold` to `trap``` - - -2024-01-16 -========== - -* :vytask:`T5859` ``(bug): Invalid format of pool range in accel-ppp services`` -* :vytask:`T5842` ``(feature): Rewrite PPTP service to get_config_dict`` -* :vytask:`T5801` ``(feature): Rewrite L2TP service to get_config_dict`` -* :vytask:`T5688` ``(default): Create the same view of pool configuration for all accel-ppp services`` - - -2024-01-15 -========== - -* :vytask:`T5944` ``(bug): "reboot in 1" not working`` -* :vytask:`T5936` ``(bug): [1.3.5 -> 1.4.0-RC1 Migration] OSPF Passive Interface Configuration Not Working Correctly`` -* :vytask:`T5247` ``(bug): the bug of the command "show interfaces system"`` -* :vytask:`T5901` ``(bug): Cloud-init and DHCP exit hook errors`` -* :vytask:`T2556` ``(bug): "show interfaces vrrp" does not return any interface`` - - -2024-01-12 -========== - -* :vytask:`T5925` ``(feature): Containers change systemd KillMode`` -* :vytask:`T5919` ``(bug): Firewall - opmode for ipv6`` -* :vytask:`T5306` ``(default): bgp config migration failed with v6only option configured with peer-group`` -* :vytask:`T3429` ``(bug): Hyper-V integration services not working on VyOS 1.4 (sagitta/current)`` - - -2024-01-11 -========== - -* :vytask:`T5713` ``(bug): strip-private doesn't strip string after "secret"`` -* :vytask:`T5532` ``(bug): After add system image the boot stuck and works again after the second reboot`` -* :vytask:`T5814` ``(bug): VyOS 1.3 to 1.4 LTS Firewall ruleset migration script breaks configuration`` -* :vytask:`T3191` ``(bug): PAM RADIUS freezing when accounting does not configured on RADIUS server`` -* :vytask:`T5917` ``(feature): Restore annotations of (running)/(default boot) in select image list`` -* :vytask:`T5916` ``(default): Added segment routing check for index size and SRGB size`` -* :vytask:`T5913` ``(feature): Allow for Peer-Groups in ipv4-labeled-unicast SAFI`` - - -2024-01-10 -========== - -* :vytask:`T5918` ``(bug): Verification problem for `set vpn ipsec interface``` -* :vytask:`T5911` ``(bug): pki: service update ignored if certificate name contains a hyphen (-)`` -* :vytask:`T5886` ``(feature): Add support for ACME protocol (LetsEncrypt)`` -* :vytask:`T5766` ``(bug): http: rewrite conf-mode script to get_config_dict()`` -* :vytask:`T4256` ``(feature): Display static DHCP server leases in the operational command output`` -* :vytask:`T5902` ``(bug): http: remove virtual-host configuration in webserver`` -* :vytask:`T3316` ``(feature): Use Kea DHCP(v6) instead of ISC DHCP(v6)`` -* :vytask:`T5791` ``(default): Update dynamic dns configuration path to be consistent with other areas of VyOS`` -* :vytask:`T5708` ``(default): Additional dynamic dns improvements to align with ddclient 3.11.1 release`` -* :vytask:`T5573` ``(bug): Fix ddclient cache entries`` -* :vytask:`T5614` ``(default): Add conntrack helper matching on firewall`` - - -2024-01-09 -========== - -* :vytask:`T5898` ``(bug): Replace partprobe with partx due to unable to install VyOS`` -* :vytask:`T5840` ``(feature): Upgrade Kea to 2.4.x`` -* :vytask:`T5838` ``(feature): Add Infiniband kernel modules`` -* :vytask:`T5785` ``(bug): API output of show container image broken`` -* :vytask:`T5249` ``(feature): Add rollback-soft feature to rollback without a reboot`` -* :vytask:`T2511` ``(feature): Migrate vyatta-op-quagga to new XML format`` -* :vytask:`T5905` ``(bug): pki: IPsec and VTI interface priority inversion when using x509 site-to-site peer`` - - -2024-01-08 -========== - -* :vytask:`T5888` ``(bug): Firewall upgrade fails because of icmpv6`` -* :vytask:`T5844` ``(bug): HTTPS API doesn't start without configured keys even when GraphQL authentication type is set to token`` -* :vytask:`T5904` ``(feature): op-mode: add "show ipv6 route vrf <name> <prefix>" command`` - - -2024-01-07 -========== - -* :vytask:`T5899` ``(feature): VyOS vm images use bookworm repo`` -* :vytask:`T5887` ``(feature): Upgrade Linux Kernel to 6.6.y (2023 LTS edition)`` - - -2024-01-06 -========== - -* :vytask:`T3214` ``(bug): OpenVPN IPv6 fixes`` - - -2024-01-05 -========== - -* :vytask:`T5894` ``(feature): Extend get_config_dict() with additional parameter with_pki that defaults to False`` - - -2024-01-03 -========== - -* :vytask:`T5880` ``(bug): verify_source_interface should not allow dynamic interfaces like ppp, l2tp, ipoe or sstpc client interfaces`` -* :vytask:`T5879` ``(bug): tunnel: sourceing from dynamic pppoe0 interface will fail on reboots`` - - -2024-01-02 -========== - -* :vytask:`T5885` ``(default): image-tools: relax restriction on image-name length from 32 to 64`` - - -2024-01-01 -========== - -* :vytask:`T5883` ``(bug): Preserve file ownership in /config subdirs on add system image`` -* :vytask:`T5474` ``(feature): Establish common file name pattern for XML conf mode commands`` - - -2023-12-30 -========== - -* :vytask:`T5875` ``(bug): login: removing and re-adding a user keeps the home directory but UID will change, thus SSH keys no longer work`` -* :vytask:`T5653` ``(feature): Command to display fingerprint`` - - -2023-12-29 -========== - -* :vytask:`T5829` ``(bug): Can't Add IPv6 Address to Containers`` -* :vytask:`T5852` ``(bug): Reboots fail with eapol WAN interface`` -* :vytask:`T5869` ``(bug): vyos.template.first_host_address() does not honor RFC4291 section 2.6.1`` - - -2023-12-28 -========== - -* :vytask:`T5827` ``(bug): image-tools: 'show system image' Command Not in Order`` -* :vytask:`T4163` ``(feature): [BMP-BGP] Routing monitoring feature`` -* :vytask:`T5867` ``(feature): Upgrade podman to Debian Trixie version 4.7.x`` -* :vytask:`T5866` ``(feature): Add op-mode command to restart IPv6 RA daemon`` -* :vytask:`T5861` ``(bug): Flavor build system fails with third-party packages`` -* :vytask:`T5854` ``(feature): Extend override-default script to allow embedded defaultValue settings`` -* :vytask:`T5792` ``(default): Upgrade ddclient 3.11.2 release`` - - -2023-12-25 -========== - -* :vytask:`T5855` ``(feature): Migrate "set service lldp snmp enable" -> `set service lldp snmp"`` -* :vytask:`T5837` ``(bug): vyos.configdict.node_changed does not return keys per adding`` -* :vytask:`T5856` ``(bug): SNMP service removal fails`` - - -2023-12-23 -========== - -* :vytask:`T5678` ``(feature): Improvements in PPPoE configuration`` - - -2023-12-22 -========== - -* :vytask:`T5804` ``(bug): SNAT "any" interface error`` - - -2023-12-21 -========== - -* :vytask:`T5807` ``(bug): NAT66 op-mode bugs`` -* :vytask:`T5778` ``(bug): The show dhcp server leases operation mode command does not work as expected`` -* :vytask:`T5775` ``(default): Migrated Firewall Global State Policy ineffective on latest firewall zone config`` -* :vytask:`T5676` ``(bug): NAT66 source rule with negation source/destination prefix causes TypeError`` -* :vytask:`T5637` ``(bug): Firewall default-action log`` -* :vytask:`T5796` ``(bug): Openconnect - HTTPS security headers are missing`` - - -2023-12-20 -========== - -* :vytask:`T5823` ``(feature): Protocol BGP add default values for config dictionary`` -* :vytask:`T5798` ``(enhancment): reverse-proxy load-balancing service should support multiple certificates for frontend`` - - -2023-12-19 -========== - -* :vytask:`T5828` ``(default): Fix GRUB installation on arm64`` - - -2023-12-18 -========== - -* :vytask:`T5751` ``(feature): Adjust new image tools for non-interactive use`` -* :vytask:`T5831` ``(feature): show system image should reverse order by addition date`` -* :vytask:`T5825` ``(bug): image-tools: restore authentication on 'add system image'`` -* :vytask:`T5821` ``(bug): image-tools: restore vrf-aware 'add system image'`` -* :vytask:`T5819` ``(bug): Don't echo password on install image`` -* :vytask:`T5806` ``(bug): Clear old raid data on new install image`` -* :vytask:`T5789` ``(bug): image-tools should copy ssh host keys on image update`` -* :vytask:`T5758` ``(default): Restore scanning configs when live installing`` - - -2023-12-15 -========== - -* :vytask:`T5824` ``(bug): busybox cannot connect some websites from initramfs`` -* :vytask:`T5770` ``(bug): MACsec not encrypting`` -* :vytask:`T5803` ``(default): git/github: Adjust configuration for safe and baseline defaults`` - - -2023-12-14 -========== - -* :vytask:`T5773` ``(bug): Unable to load config via HTTP`` -* :vytask:`T5816` ``(bug): BGP Large Community List Validation Broken`` -* :vytask:`T5812` ``(bug): rollback check max revision number does not work`` -* :vytask:`T5749` ``(feature): Show MAC address VRF and MTU by default for "show interfaces"`` -* :vytask:`T5774` ``(bug): commit-archive to FTP server broken after update (VyOS 1.5-rolling)`` -* :vytask:`T5826` ``(default): Add dmicode as an explicit dependency`` -* :vytask:`T5793` ``(default): mdns-repeater: Cleanup avahi-daemon configuration in /etc`` - - -2023-12-13 -========== - -* :vytask:`T591` ``(feature): Support SRv6`` - - -2023-12-12 -========== - -* :vytask:`T5815` ``(enhancment): Add load_config module`` - - -2023-12-11 -========== - -* :vytask:`T5741` ``(bug): WAN Load Balancing failover route tables aren't created`` - - -2023-12-10 -========== - -* :vytask:`T5658` ``(default): Add VRF support for mtr`` - - -2023-12-09 -========== - -* :vytask:`T5808` ``(bug): op-mode: ipv6 ospfv3 graceful-restart description contains incorrect info`` -* :vytask:`T5802` ``(bug): ping (ip or hostname) interface <tab> produces error`` -* :vytask:`T5747` ``(feature): op-mode add MAC VRF and MTU for show interfaces summary`` -* :vytask:`T3983` ``(bug): show pki certificate Doesnt show x509 certificates`` - - -2023-12-08 -========== - -* :vytask:`T5782` ``(enhancment): Use a single config mode script for https and http-api`` -* :vytask:`T5768` ``(enhancment): Remove auxiliary http-api.conf for simplification of http-api config mode script`` - - -2023-12-04 -========== - -* :vytask:`T5769` ``(bug): VTI tunnels lose their v6 Link Local addresses when set down/up`` - - -2023-12-03 -========== - -* :vytask:`T5753` ``(feature): Add VXLAN vnifilter support`` -* :vytask:`T5759` ``(feature): Change VXLAN default MTU to 1500 bytes`` - - -2023-11-27 -========== - -* :vytask:`T5763` ``(bug): Fix imprecise check for remote file name in vyos-load-config.py`` -* :vytask:`T5783` ``(feature): frr: smoketests must notice any daemon crash`` - - -2023-11-26 -========== - -* :vytask:`T5760` ``(feature): DHCP client custom dhcp-options`` -* :vytask:`T2405` ``(feature): archive to GIT or other platform`` - - -2023-11-25 -========== - -* :vytask:`T5655` ``(bug): commit-archive: Ctrl+C should not eror out with stack trace, signal should be cought`` - - -2023-11-24 -========== - -* :vytask:`T5776` ``(feature): Enable VFIO support`` -* :vytask:`T5402` ``(bug): VRRP router with rfc3768-compatibility sends multiple ARP replies`` - - -2023-11-23 -========== - -* :vytask:`T5659` ``(bug): VPP cannot add interface to dataplane if it already has an address configured`` - - -2023-11-22 -========== - -* :vytask:`T5767` ``(feature): Add reboot and poweroff the system via API`` -* :vytask:`T5729` ``(bug): Firewall, nat and policy route - Switch to valueless`` -* :vytask:`T5681` ``(feature): Interface match - Simplified and unified cli`` -* :vytask:`T5643` ``(feature): NAT - Allow interface groups on nat rules`` -* :vytask:`T5616` ``(feature): Firewall mark - Add capabilities for matching firewall mark`` -* :vytask:`T5590` ``(default): Firewall "log enable" logs every packet`` - - -2023-11-21 -========== - -* :vytask:`T5762` ``(bug): http: api: smoketests fail as they can not establish IPv6 connection to uvicorn backend server`` - - -2023-11-18 -========== - -* :vytask:`T1354` ``(feature): Add support for VLAN-Aware bridges`` - - -2023-11-16 -========== - -* :vytask:`T5726` ``(bug): HTTPS API image cannot be updated`` -* :vytask:`T5738` ``(feature): Extend XML building blocks`` -* :vytask:`T5736` ``(feature): igmp: migrate "protocols igmp" to "protocols pim"`` -* :vytask:`T5733` ``(feature): pim(6): rewrite FRR PIM daemon configuration to get_config_dict() and add missing IGMP features`` -* :vytask:`T5689` ``(default): FRR 9.0.1 in VyOS current segfaults on show rpki prefix $prefix`` -* :vytask:`T5595` ``(feature): Multicast - PIM bfd feature enable`` - - -2023-11-15 -========== - -* :vytask:`T5695` ``(feature): Build FRR with LUA scripts --enable-scripting option`` -* :vytask:`T5677` ``(bug): show lldp neighbors generates TypeError when neighbor has no `descr``` -* :vytask:`T5728` ``(bug): Improve compatibility between OpenVPN on VyOS 1.5 and OpenVPN Connect Client`` -* :vytask:`T5732` ``(bug): generate firewall rule-resequence drops geoip country-code from output`` -* :vytask:`T5661` ``(enhancment): Add show show ssh dynamic-protection attacker and show log ssh dynamic-protection`` - - -2023-11-13 -========== - -* :vytask:`T5698` ``(feature): EVPN ESI Multihoming`` -* :vytask:`T5563` ``(bug): container: Container environment variable cannot be set`` -* :vytask:`T5706` ``(bug): Systemd-udevd high CPU utilization for multiple dynamic ppp/l2tp/ipoe interfaces`` - - -2023-11-10 -========== - -* :vytask:`T5727` ``(bug): validator: Use native URL validator instead of regex-based validator`` - - -2023-11-08 -========== - -* :vytask:`T5720` ``(bug): PPPoE-server adding new interface does not work`` -* :vytask:`T5716` ``(bug): PPPoE-server shaper template bug down-limiter option does not rely on fwmark`` -* :vytask:`T5702` ``(feature): Add ability to set include_ifmib_iface_prefix and ifmib_max_num_ifaces for SNMP`` -* :vytask:`T5693` ``(feature): Adding variable vyos_persistence_dir (and improve variable vyos_rootfs_dir)`` -* :vytask:`T5648` ``(bug): ldpd neighbour template errors`` -* :vytask:`T5564` ``(bug): Both show firewall group and show firewall summary fails`` -* :vytask:`T5559` ``(feature): Selective proxy-arp/proxy-ndp when doing SNAT/DNAT`` -* :vytask:`T5541` ``(bug): Zone-Based Firewalling in VyOS Sagitta 1.4`` - - -2023-11-07 -========== - -* :vytask:`T5586` ``(feature): Disable by default SNMP for Keepalived VRRP`` - - -2023-11-06 -========== - -* :vytask:`T5705` ``(bug): rsyslog - Not working when using facility=all`` -* :vytask:`T5704` ``(feature): PPPoE-server add max-starting option`` -* :vytask:`T5707` ``(bug): Wireguard peer public key update leaves redundant peers and breaks connectivity`` - - -2023-11-03 -========== - -* :vytask:`T5700` ``(bug): Monitoring telegraf deprecated plugins inputs outputs`` - - -2023-11-02 -========== - -* :vytask:`T5701` ``(feature): Update telegraf package`` - - -2023-11-01 -========== - -* :vytask:`T5690` ``(bug): Change to definition of environment variable 'vyos_rootfs_dir' is incorrect`` - - -2023-10-31 -========== - -* :vytask:`T5699` ``(feature): vxlan: migrate "external" CLI know to "parameters external"`` -* :vytask:`T5668` ``(feature): Disable VXLAN bridge learning and enable neigh_suppress when using EVPN`` - - -2023-10-27 -========== - -* :vytask:`T5663` ``(bug): pmacct package contains unwanted data`` -* :vytask:`T5652` ``(bug): Config migrate to image upgrade does not properly generate home directory`` - - -2023-10-26 -========== - -* :vytask:`T5683` ``(bug): reverse-proxy pki filenames mismatch`` -* :vytask:`T5600` ``(bug): Firewall - Remove or extend constraint on 'interface-name'`` -* :vytask:`T5598` ``(bug): unknown parameter 'nf_conntrack_helper' ignored`` -* :vytask:`T5571` ``(bug): Firewall does not delete networks from the table raw`` -* :vytask:`T4903` ``(bug): conntrack ignore does not suppotr IPv6 addresses`` -* :vytask:`T4309` ``(feature): Support network/address-groups and ipv6-network/ipv6-address-groups in conntrack ignore`` -* :vytask:`T5594` ``(bug): VRRP - Error if using IPv6 Link Local as hello source address`` -* :vytask:`T5606` ``(feature): IPSec VPN: Allow multiple CAs certificates`` -* :vytask:`T5568` ``(default): Install image from live ISO always defaults boot to KVM entry`` -* :vytask:`T5558` ``(default): Update config test to check resulting migrations`` - - -2023-10-23 -========== - -* :vytask:`T5299` ``(bug): QoS shaper ceiling does not work`` -* :vytask:`T5667` ``(feature): BGP label-unicast - enable ecmp`` - - -2023-10-22 -========== - -* :vytask:`T5254` ``(bug): Modification of any interface setting sets MTU back to default when MTU has been inherited from a bond`` -* :vytask:`T5671` ``(feature): vxlan: change port to IANA assigned default port`` - - -2023-10-21 -========== - -* :vytask:`T5670` ``(bug): bridge: missing member interface validator`` -* :vytask:`T5617` ``(feature): Add an option to exclude single values to the numeric validator`` - - -2023-10-20 -========== - -* :vytask:`T5233` ``(bug): Op-mode flow-accounting netflow with disable-imt errors`` -* :vytask:`T5232` ``(bug): Flow-accounting uacctd.service cannot restart correctly`` - - -2023-10-19 -========== - -* :vytask:`T4913` ``(default): Rewrite the wireless op mode in the new style`` - - -2023-10-18 -========== - -* :vytask:`T5642` ``(bug): op cmd: generate tech-support archive: does not work`` -* :vytask:`T5521` ``(bug): Home owner directory changed to vyos for the user after reboot`` - - -2023-10-17 -========== - -* :vytask:`T5662` ``(bug): Fix indexing error in configdep script organization`` -* :vytask:`T5644` ``(bug): Firewall groups deletion can break config`` - - -2023-10-16 -========== - -* :vytask:`T5165` ``(feature): Policy local-route ability set protocol and port`` - - -2023-10-14 -========== - -* :vytask:`T5629` ``(bug): Policy local-route bug after migration to destination node address`` - - -2023-10-12 -========== - -* :vytask:`T5649` ``(bug): vyos-1x should generate XML cache after building command templates for less cryptic error on typo`` - - -2023-10-10 -========== - -* :vytask:`T5589` ``(bug): Nonstripped binaries exists in VyOS`` -* :vytask:`T5489` ``(feature): Change to BBR as TCP congestion control, or at least make it an config option`` - - -2023-10-08 -========== - -* :vytask:`T5630` ``(feature): pppoe: allow to specify MRU in addition to already configurable MTU`` - - -2023-10-06 -========== - -* :vytask:`T5576` ``(feature): Add bgp remove-private-as all option`` - - -2023-10-05 -========== - -* :vytask:`T4320` ``(default): Remove legacy version files in vyatta-cfg-system/cfg-version`` - - -2023-10-04 -========== - -* :vytask:`T5632` ``(feature): Add jq package to parse JSON files`` -* :vytask:`T3655` ``(bug): NAT Problem with VRF`` -* :vytask:`T5585` ``(bug): Fix file access mode for dynamic dns configuration`` - - -2023-10-03 -========== - -* :vytask:`T5618` ``(bug): Flow-accounting crushes when IMT is enabled`` -* :vytask:`T5579` ``(bug): Log firewall - Wrong command after firewall refactor`` -* :vytask:`T5561` ``(feature): NAT - Inbound or outbound interface should not be mandatory`` -* :vytask:`T5626` ``(feature): Only select required Kernel CGROUP controllers`` -* :vytask:`T5628` ``(feature): op-mode: login: DeprecationWarning: 'spwd'`` - - -2023-09-28 -========== - -* :vytask:`T5596` ``(feature): bgp: add new features from FRR 9`` -* :vytask:`T5412` ``(feature): Add support for extending config-mode dependencies in supplemental package`` - - -2023-09-24 -========== - -* :vytask:`T5604` ``(bug): List of debian archives is out of date (non-free-firmware is missing)`` -* :vytask:`T5591` ``(feature): Cleanup of FRR daemons-file and various FRR fixes`` - - -2023-09-22 -========== - -* :vytask:`T5602` ``(feature): For reverse-proxy type of load-balancing feature, support "backup" option in backends configuration`` -* :vytask:`T5609` ``(enhancment): Add util to get drive device name from id`` -* :vytask:`T5608` ``(enhancment): Rewrite add/delete raid member to Python and remove from vyatta-op`` -* :vytask:`T5607` ``(bug): Adjust RAID smoketest for non-deterministic SCSI device probing`` - - -2023-09-20 -========== - -* :vytask:`T5588` ``(bug): Add kernel conntrack_bridge module`` -* :vytask:`T5241` ``(feature): Support veth interfaces to working with netns`` -* :vytask:`T5592` ``(feature): salt: upgrade minion to 3005.2`` - - -2023-09-19 -========== - -* :vytask:`T5597` ``(feature): isis: add new features from FRR 9.`` - - -2023-09-18 -========== - -* :vytask:`T5575` ``(bug): ARP/NDP table-size isnt set properly`` - - -2023-09-15 -========== - -* :vytask:`T5587` ``(bug): Firwall can not pass the smoketest`` -* :vytask:`T5581` ``(feature): Add "show ip nht" op-mode command (IPv4 nexthop tracking table)`` - - -2023-09-11 -========== - -* :vytask:`T5562` ``(bug): Smoketests fail for vyos:current (test_netns.py)`` -* :vytask:`T5551` ``(bug): Missing check for boot_configuration_complete raises error in vyos-save-config.py`` -* :vytask:`T5353` ``(bug): config-mgmt: normalize archive updates and commit log entries`` - - -2023-09-10 -========== - -* :vytask:`T5555` ``(bug): Fix timezone migrator (system 13-to-14)`` - - -2023-09-09 -========== - -* :vytask:`T5423` ``(bug): ipsec: no output for op-cmd "show vpn ike secrets"`` - - -2023-09-08 -========== - -* :vytask:`T5560` ``(bug): VyOS version in current branch should be changed from 1.4 to 1.5`` - - -2023-09-07 -========== - -* :vytask:`T5556` ``(bug): reboot now and poweroff does not work`` - - -2023-09-06 -========== - -* :vytask:`T5548` ``(bug): HAProxy renders timeouts incorrectly`` diff --git a/docs/changelog/index.rst b/docs/changelog/index.rst deleted file mode 100644 index 9467a716..00000000 --- a/docs/changelog/index.rst +++ /dev/null @@ -1,21 +0,0 @@ -.. _release-notes: - - -######### -Changelog -######### - - -.. toctree:: - :maxdepth: 1 - :includehidden: - - 1.5 - 1.4 - 1.3 - 1.2.6 - 1.2.5 - 1.2.4 - 1.2.3 - 1.2.2 - 1.2.1 diff --git a/docs/cli.rst b/docs/cli.rst index 550494fa..778d3954 100644 --- a/docs/cli.rst +++ b/docs/cli.rst @@ -878,21 +878,21 @@ VyOS lets you compare different configurations. 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 + <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 + 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 :cfgcmd:`compare` allows you to compare different type of @@ -1000,6 +1000,11 @@ be ``config.boot-hostname.YYYYMMDD_HHMMSS``. vyos@vyos# ssh-keyscan <host> >> ~/.ssh/known_hosts +.. cfgcmd:: set system config-management commit-archive vrf <name> + + Specify name of the :abbr:`VRF (Virtual Routing and Forwarding)` instance + used to upload the configuration to the remote system. + Saving and loading manually --------------------------- @@ -1022,14 +1027,14 @@ to load it with the ``load`` command: 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 + <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 diff --git a/docs/conf.py b/docs/conf.py index dc24ba85..7f302ceb 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -48,7 +48,9 @@ extensions = ['sphinx.ext.intersphinx', 'autosectionlabel', 'myst_parser', 'sphinx_design', - 'vyos' + 'vyos', + 'sphinx_llms_txt', + 'sphinx_sitemap', ] # Add any paths that contain templates here, relative to this directory. @@ -111,6 +113,15 @@ html_static_path = ['_static'] html_extra_path = ['_html_extra'] +html_baseurl = 'https://docs.vyos.io/en/latest/' + +# sphinx-sitemap: baseurl already includes /en/latest/, so skip lang+version +sitemap_url_scheme = '{link}' + +# sphinx-llms-txt: disable auto-generated llms.txt, keep curated one from +# _html_extra; llms-full.txt is still auto-generated +llms_txt_file = False + # Custom sidebar templates, must be a dictionary that maps document names # to template names. # diff --git a/docs/configexamples/ansible.rst b/docs/configexamples/ansible.rst index ab3413eb..ee865076 100644 --- a/docs/configexamples/ansible.rst +++ b/docs/configexamples/ansible.rst @@ -9,7 +9,8 @@ Ansible example Setting up Ansible on a server running the Debian operating system. =================================================================== -In this example, we will set up a simple use of Ansible to configure multiple VyoS routers. +In this example, we will set up a simple use of Ansible to configure +multiple VyOS routers. We have four pre-configured routers with this configuration: Using the general schema for example: @@ -23,10 +24,10 @@ We have four pre-configured routers with this configuration: .. code-block:: none - set interfaces ethernet eth0 address dhcp - set service ssh - commit - save + set interfaces ethernet eth0 address dhcp + set service ssh + commit + save * vyos7 - 192.0.2.105 * vyos8 - 192.0.2.106 @@ -37,62 +38,66 @@ Install Ansible: ==================== .. code-block:: none - # apt-get install ansible - Do you want to continue? [Y/n] y + # apt-get install ansible + Do you want to continue? [Y/n] y Install Paramiko: ===================== .. code-block:: none - #apt-get install -y python3-paramiko + #apt-get install -y python3-paramiko Check the version: ================== +.. stop_vyoslinter + .. code-block:: none - # ansible --version - ansible 2.10.8 - config file = None - configured module search path = ['/root/.ansible/plugins/modules', '/usr/share/ansible/plugins/modules'] - ansible python module location = /usr/lib/python3/dist-packages/ansible - executable location = /usr/bin/ansible - python version = 3.9.2 (default, Feb 28 2021, 17:03:44) [GCC 10.2.1 20210110] + # ansible --version + ansible 2.10.8 + config file = None + configured module search path = ['/root/.ansible/plugins/modules', '/usr/share/ansible/plugins/modules'] + ansible python module location = /usr/lib/python3/dist-packages/ansible + executable location = /usr/bin/ansible + python version = 3.9.2 (default, Feb 28 2021, 17:03:44) [GCC 10.2.1 20210110] + +.. start_vyoslinter Basic configuration of ansible.cfg: ======================================= .. code-block:: none - # nano /root/ansible.cfg - [defaults] - host_key_checking = no + # nano /root/ansible.cfg + [defaults] + host_key_checking = no Add all the VyOS hosts: ======================= .. code-block:: none - # nano /root/hosts - [vyos_hosts] - vyos7 ansible_ssh_host=192.0.2.105 - vyos8 ansible_ssh_host=192.0.2.106 - vyos9 ansible_ssh_host=192.0.2.107 - vyos10 ansible_ssh_host=192.0.2.108 + # nano /root/hosts + [vyos_hosts] + vyos7 ansible_ssh_host=192.0.2.105 + vyos8 ansible_ssh_host=192.0.2.106 + vyos9 ansible_ssh_host=192.0.2.107 + vyos10 ansible_ssh_host=192.0.2.108 Add general variables: ====================== .. code-block:: none - # mkdir /root/group_vars/ - # nano /root/group_vars/vyos_hosts - ansible_python_interpreter: /usr/bin/python3 - ansible_network_os: vyos - ansible_connection: network_cli - ansible_user: vyos - ansible_ssh_pass: vyos + # mkdir /root/group_vars/ + # nano /root/group_vars/vyos_hosts + ansible_python_interpreter: /usr/bin/python3 + ansible_network_os: vyos + ansible_connection: network_cli + ansible_user: vyos + ansible_ssh_pass: vyos Add a simple playbook with the tasks for each router: @@ -100,117 +105,122 @@ Add a simple playbook with the tasks for each router: .. code-block:: none - # nano /root/main.yml - - --- - - hosts: vyos_hosts - gather_facts: 'no' - tasks: - - name: Configure general settings for the vyos hosts group - vyos_config: - lines: - - set system name-server 8.8.8.8 - - set interfaces ethernet eth0 description '#WAN#' - - set interfaces ethernet eth1 description '#LAN#' - - set interfaces ethernet eth2 disable - - set interfaces ethernet eth3 disable - - set system host-name {{ inventory_hostname }} - save: - true - + # nano /root/main.yml + + --- + - hosts: vyos_hosts + gather_facts: 'no' + tasks: + - name: Configure general settings for the vyos hosts group + vyos_config: + lines: + - set system name-server 192.0.2.1 + - set interfaces ethernet eth0 description '#WAN#' + - set interfaces ethernet eth1 description '#LAN#' + - set interfaces ethernet eth2 disable + - set interfaces ethernet eth3 disable + - set system host-name {{ inventory_hostname }} + save: true + Start the playbook: =================== +.. stop_vyoslinter + .. code-block:: none - ansible-playbook -i hosts main.yml - PLAY [vyos_hosts] ************************************************************** - - TASK [Configure general settings for the vyos hosts group] ********************* - ok: [vyos9] - ok: [vyos10] - ok: [vyos7] - ok: [vyos8] - - PLAY RECAP ********************************************************************* - vyos10 : ok=2 changed=0 unreachable=0 failed=0 skipped=0 rescued=0 ignored=0 - vyos7 : ok=2 changed=0 unreachable=0 failed=0 skipped=0 rescued=0 ignored=0 - vyos8 : ok=2 changed=0 unreachable=0 failed=0 skipped=0 rescued=0 ignored=0 - vyos9 : ok=2 changed=0 unreachable=0 failed=0 skipped=0 rescued=0 ignored=0 + ansible-playbook -i hosts main.yml + PLAY [vyos_hosts] ************************************************************** + + TASK [Configure general settings for the vyos hosts group] ********************* + ok: [vyos9] + ok: [vyos10] + ok: [vyos7] + ok: [vyos8] + + PLAY RECAP ********************************************************************* + vyos10 : ok=2 changed=0 unreachable=0 failed=0 skipped=0 rescued=0 ignored=0 + vyos7 : ok=2 changed=0 unreachable=0 failed=0 skipped=0 rescued=0 ignored=0 + vyos8 : ok=2 changed=0 unreachable=0 failed=0 skipped=0 rescued=0 ignored=0 + vyos9 : ok=2 changed=0 unreachable=0 failed=0 skipped=0 rescued=0 ignored=0 + +.. start_vyoslinter Check the result on the vyos10 router: ====================================== .. code-block:: none - vyos@vyos10:~$ show interfaces - Codes: S - State, L - Link, u - Up, D - Down, A - Admin Down - Interface IP Address S/L Description - --------- ---------- --- ----------- - eth0 192.0.2.108/24 u/u WAN - eth1 - u/u LAN - eth2 - A/D - eth3 - A/D - lo 127.0.0.1/8 u/u - ::1/128 - - vyos@vyos10:~$ sh configuration commands | grep 8.8.8.8 - set system name-server '8.8.8.8' + vyos@vyos10:~$ show interfaces + Codes: S - State, L - Link, u - Up, D - Down, A - Admin Down + Interface IP Address S/L Description + --------- ---------- --- ----------- + eth0 192.0.2.108/24 u/u WAN + eth1 - u/u LAN + eth2 - A/D + eth3 - A/D + lo 127.0.0.1/8 u/u + ::1/128 + + vyos@vyos10:~$ sh configuration commands | grep 192.0.2.1 + set system name-server '192.0.2.1' The simple way without configuration of the hostname (one task for all routers): ================================================================================ .. code-block:: none - # nano /root/hosts_v2 - [vyos_hosts_group] - vyos7 ansible_ssh_host=192.0.2.105 - vyos8 ansible_ssh_host=192.0.2.106 - vyos9 ansible_ssh_host=192.0.2.107 - vyos10 ansible_ssh_host=192.0.2.108 - [vyos_hosts_group:vars] - ansible_python_interpreter=/usr/bin/python3 - ansible_user=vyos - ansible_ssh_pass=vyos - ansible_network_os=vyos - ansible_connection=network_cli - - # nano /root/main_v2.yml - --- - - hosts: vyos_hosts_group - - connection: network_cli - gather_facts: 'no' - - tasks: - - name: Configure remote vyos_hosts_group - vyos_config: - lines: - - set system name-server 8.8.8.8 - - set interfaces ethernet eth0 description WAN - - set interfaces ethernet eth1 description LAN - - set interfaces ethernet eth2 disable - - set interfaces ethernet eth3 disable - save: - true - + # nano /root/hosts_v2 + [vyos_hosts_group] + vyos7 ansible_ssh_host=192.0.2.105 + vyos8 ansible_ssh_host=192.0.2.106 + vyos9 ansible_ssh_host=192.0.2.107 + vyos10 ansible_ssh_host=192.0.2.108 + [vyos_hosts_group:vars] + ansible_python_interpreter=/usr/bin/python3 + ansible_user=vyos + ansible_ssh_pass=vyos + ansible_network_os=vyos + ansible_connection=network_cli + + # nano /root/main_v2.yml + --- + - hosts: vyos_hosts_group + connection: network_cli + gather_facts: 'no' + tasks: + - name: Configure remote vyos_hosts_group + vyos_config: + lines: + - set system name-server 192.0.2.1 + - set interfaces ethernet eth0 description WAN + - set interfaces ethernet eth1 description LAN + - set interfaces ethernet eth2 disable + - set interfaces ethernet eth3 disable + save: true + + +.. stop_vyoslinter + .. code-block:: none - - # ansible-playbook -i hosts_v2 main_v2.yml - - PLAY [vyos_hosts_group] ******************************************************** - - TASK [Configure remote vyos_hosts_group] *************************************** - ok: [vyos8] - ok: [vyos7] - ok: [vyos9] - ok: [vyos10] - - PLAY RECAP ********************************************************************* - vyos10 : ok=1 changed=0 unreachable=0 failed=0 skipped=0 rescued=0 ignored=0 - vyos7 : ok=1 changed=0 unreachable=0 failed=0 skipped=0 rescued=0 ignored=0 - vyos8 : ok=1 changed=0 unreachable=0 failed=0 skipped=0 rescued=0 ignored=0 - vyos9 : ok=1 changed=0 unreachable=0 failed=0 skipped=0 rescued=0 ignored=0 - - -In the next chapter of the example, we'll use Ansible with jinja2 templates and variables. + + # ansible-playbook -i hosts_v2 main_v2.yml + + PLAY [vyos_hosts_group] ******************************************************** + + TASK [Configure remote vyos_hosts_group] *************************************** + ok: [vyos8] + ok: [vyos7] + ok: [vyos9] + ok: [vyos10] + + PLAY RECAP ********************************************************************* + vyos10 : ok=1 changed=0 unreachable=0 failed=0 skipped=0 rescued=0 ignored=0 + vyos7 : ok=1 changed=0 unreachable=0 failed=0 skipped=0 rescued=0 ignored=0 + vyos8 : ok=1 changed=0 unreachable=0 failed=0 skipped=0 rescued=0 ignored=0 + vyos9 : ok=1 changed=0 unreachable=0 failed=0 skipped=0 rescued=0 ignored=0 + +.. start_vyoslinter + +In the next chapter of the example, we'll use Ansible with jinja2 +templates and variables. diff --git a/docs/configexamples/azure-vpn-bgp.rst b/docs/configexamples/azure-vpn-bgp.rst index 03d637d8..597a4d15 100644 --- a/docs/configexamples/azure-vpn-bgp.rst +++ b/docs/configexamples/azure-vpn-bgp.rst @@ -2,8 +2,9 @@ .. _examples-azure-vpn-bgp: +############################################################ Route-Based Site-to-Site VPN to Azure (BGP over IKEv2/IPsec) ------------------------------------------------------------- +############################################################ This guide shows an example of a route-based IKEv2 site-to-site VPN to Azure using VTI and BGP for dynamic routing updates. diff --git a/docs/configexamples/azure-vpn-dual-bgp.rst b/docs/configexamples/azure-vpn-dual-bgp.rst index d37aa85c..04a6a631 100644 --- a/docs/configexamples/azure-vpn-dual-bgp.rst +++ b/docs/configexamples/azure-vpn-dual-bgp.rst @@ -2,8 +2,9 @@ .. _examples-azure-vpn-dual-bgp: +###################################################################### Route-Based Redundant Site-to-Site VPN to Azure (BGP over IKEv2/IPsec) ----------------------------------------------------------------------- +###################################################################### This guide shows an example of a redundant (active-active) route-based IKEv2 site-to-site VPN to Azure using VTI diff --git a/docs/configexamples/firewall.rst b/docs/configexamples/firewall.rst index a1ad7e19..6968eb04 100644 --- a/docs/configexamples/firewall.rst +++ b/docs/configexamples/firewall.rst @@ -1,9 +1,11 @@ :lastproofread: 2024-09-11 +################# Firewall Examples -================= +################# -This section contains examples of firewall configurations for various deployments. +This section contains examples of firewall configurations for various +deployments. .. toctree:: :maxdepth: 2 diff --git a/docs/configexamples/fwall-and-bridge.rst b/docs/configexamples/fwall-and-bridge.rst index 32c53fa5..134dd6c0 100644 --- a/docs/configexamples/fwall-and-bridge.rst +++ b/docs/configexamples/fwall-and-bridge.rst @@ -1,7 +1,8 @@ :lastproofread: 2024-09-11 +########################### Bridge and firewall example ---------------------------- +########################### Scenario and requirements ^^^^^^^^^^^^^^^^^^^^^^^^^ @@ -353,12 +354,16 @@ For example, while a host tries to get an IP address from a DHCP server in br1 all DHCP discover are dropped, and in br2, we can see that DHCP offers from untrusted servers are dropped: +.. stop_vyoslinter + .. code-block:: none - vyos@bridge:~$ show log firewall bridge - Sep 17 14:22:35 kernel: [bri-NAM-br2-fwd-22-D]IN=eth7 OUT=eth5 MAC=50:00:00:09:00:00:50:00:00:04:00:00:08:00 SRC=10.2.2.199 DST=10.2.2.92 LEN=322 TOS=0x10 PREC=0x00 TTL=128 ID=0 DF PROTO=UDP SPT=67 DPT=68 LEN=302 - Sep 17 14:28:18 kernel: [bri-NAM-br1-pre-10-D]IN=eth3 OUT= MAC=ff:ff:ff:ff:ff:ff:00:50:79:66:68:0c:08:00 SRC=0.0.0.0 DST=255.255.255.255 LEN=392 TOS=0x10 PREC=0x00 TTL=16 ID=0 PROTO=UDP SPT=68 DPT=67 LEN=372 - Sep 17 14:28:19 kernel: [bri-NAM-br1-pre-10-D]IN=eth3 OUT= MAC=ff:ff:ff:ff:ff:ff:00:50:79:66:68:0c:08:00 SRC=0.0.0.0 DST=255.255.255.255 LEN=392 TOS=0x10 PREC=0x00 TTL=16 ID=0 PROTO=UDP SPT=68 DPT=67 LEN=372 + vyos@bridge:~$ show log firewall bridge + Sep 17 14:22:35 kernel: [bri-NAM-br2-fwd-22-D]IN=eth7 OUT=eth5 MAC=50:00:00:09:00:00:50:00:00:04:00:00:08:00 SRC=10.2.2.199 DST=10.2.2.92 LEN=322 TOS=0x10 PREC=0x00 TTL=128 ID=0 DF PROTO=UDP SPT=67 DPT=68 LEN=302 + Sep 17 14:28:18 kernel: [bri-NAM-br1-pre-10-D]IN=eth3 OUT= MAC=ff:ff:ff:ff:ff:ff:00:50:79:66:68:0c:08:00 SRC=0.0.0.0 DST=255.255.255.255 LEN=392 TOS=0x10 PREC=0x00 TTL=16 ID=0 PROTO=UDP SPT=68 DPT=67 LEN=372 + Sep 17 14:28:19 kernel: [bri-NAM-br1-pre-10-D]IN=eth3 OUT= MAC=ff:ff:ff:ff:ff:ff:00:50:79:66:68:0c:08:00 SRC=0.0.0.0 DST=255.255.255.255 LEN=392 TOS=0x10 PREC=0x00 TTL=16 ID=0 PROTO=UDP SPT=68 DPT=67 LEN=372 + +.. start_vyoslinter And with operational mode commands, we can check rules matchers, actions, and diff --git a/docs/configexamples/fwall-and-vrf.rst b/docs/configexamples/fwall-and-vrf.rst index fb65e3a4..bd97e1ad 100644 --- a/docs/configexamples/fwall-and-vrf.rst +++ b/docs/configexamples/fwall-and-vrf.rst @@ -1,5 +1,6 @@ +######################## VRF and firewall example ------------------------- +######################## Scenario and requirements ^^^^^^^^^^^^^^^^^^^^^^^^^ diff --git a/docs/configexamples/index.rst b/docs/configexamples/index.rst index 7f173b4a..b5985d7f 100644 --- a/docs/configexamples/index.rst +++ b/docs/configexamples/index.rst @@ -1,7 +1,8 @@ .. _examples: +######################## Configuration Blueprints -======================== +######################## This chapter contains various configuration examples: diff --git a/docs/configexamples/l3vpn-hub-and-spoke.rst b/docs/configexamples/l3vpn-hub-and-spoke.rst index 1533d0d8..90a036d8 100644 --- a/docs/configexamples/l3vpn-hub-and-spoke.rst +++ b/docs/configexamples/l3vpn-hub-and-spoke.rst @@ -46,7 +46,8 @@ The following software was used in the creation of this document: **NOTE:** VyOS Router (tested with VyOS 1.4-rolling-202110310317) – The configurations below are specifically for VyOS 1.4.x. -General information can be found in the :ref:`configuration/vrf/index:L3VPN VRFs` chapter. +General information can be found in the +:ref:`configuration/vrf/index:L3VPN VRFs` chapter. @@ -64,8 +65,9 @@ Topology 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 +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 @@ -325,10 +327,12 @@ 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: +.. stop_vyoslinter + - VyOS-RR1: .. code-block:: 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' @@ -554,81 +558,81 @@ Let’s check IPv4 routing and MPLS information on provider nodes 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 + 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 .. code-block:: 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 + 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 .. code-block:: 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 + 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: @@ -644,11 +648,11 @@ nodes to other devices: 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 + 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 @@ -660,37 +664,37 @@ nodes to other devices: 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 + 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 + 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 + *>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 + *>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 + *>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 + 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 + *>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 + *>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 @@ -704,11 +708,11 @@ nodes to other devices: 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 + 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: @@ -725,9 +729,9 @@ and installing them to the specific customer VRFs: 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 + 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: @@ -743,19 +747,19 @@ and installing them to the specific customer VRFs: 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 + 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 + 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 ? + 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: @@ -771,8 +775,8 @@ and installing them to the specific customer VRFs: 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 + 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 @@ -785,19 +789,19 @@ and installing them to the specific customer VRFs: 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 + 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 + * 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 + * 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 @@ -811,19 +815,19 @@ and installing them to the specific customer VRFs: 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 + 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 + 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: @@ -839,9 +843,9 @@ Now, let’s check routing information on out Hub PE: 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 + 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 @@ -858,31 +862,31 @@ Now, let’s check routing information on out Hub PE: 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 + 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 + 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 + 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 @@ -897,8 +901,8 @@ Now, let’s check routing information on out Hub PE: 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 + 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 @@ -909,30 +913,30 @@ Now, let’s check routing information on out Hub PE: 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 + 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 + * 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 + * 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 + * 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 + * 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 + * 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 + * 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 @@ -945,19 +949,19 @@ Now, let’s check routing information on out Hub PE: 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 + 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 + 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 @@ -965,19 +969,19 @@ Now, let’s check routing information on out Hub PE: 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 + 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 + 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: @@ -989,10 +993,10 @@ Finally, let’s check the reachability between CEs: # 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 + 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 @@ -1027,10 +1031,10 @@ Finally, let’s check the reachability between CEs: # 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 + 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 @@ -1086,10 +1090,10 @@ Finally, let’s check the reachability between CEs: # 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 + 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 @@ -1117,4 +1121,7 @@ Finally, let’s check the reachability between CEs: 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. +.. start_vyoslinter + +**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/nmp.rst b/docs/configexamples/nmp.rst index b25142cd..8945a9f4 100644 --- a/docs/configexamples/nmp.rst +++ b/docs/configexamples/nmp.rst @@ -7,19 +7,25 @@ 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. +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. +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 .. code-block:: 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' + 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' diff --git a/docs/configexamples/policy-based-ipsec-and-firewall.rst b/docs/configexamples/policy-based-ipsec-and-firewall.rst index cb93daa9..dcf59af9 100644 --- a/docs/configexamples/policy-based-ipsec-and-firewall.rst +++ b/docs/configexamples/policy-based-ipsec-and-firewall.rst @@ -1,8 +1,9 @@ .. _examples-policy-based-ipsec-and-firewall: +######################################################## Policy-Based Site-to-Site VPN and Firewall Configuration --------------------------------------------------------- +######################################################## This guide shows an example policy-based IKEv2 site-to-site VPN between two VyOS routers, and firewall configuration. diff --git a/docs/configexamples/qos.rst b/docs/configexamples/qos.rst index 66751286..96448dd4 100644 --- a/docs/configexamples/qos.rst +++ b/docs/configexamples/qos.rst @@ -9,8 +9,11 @@ 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. +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: @@ -20,8 +23,11 @@ Using the general schema for example: :align: center :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. +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 @@ -32,30 +38,37 @@ 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. +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. +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. + +.. stop_vyoslinter .. code-block:: none - set interfaces ethernet eth0 address '10.1.1.100/24' - set interfaces ethernet eth1 address '172.17.1.1/24' - set protocols static route 0.0.0.0/0 next-hop 10.1.1.1 - set qos policy shaper vyos3 class 10 match ADDRESS10 ip source address '172.17.1.2/32' - set qos policy shaper vyos3 class 10 set-dscp 'CS4' - set qos policy shaper vyos3 class 20 match ADDRESS20 ip source address '172.17.1.3/32' - set qos policy shaper vyos3 class 20 set-dscp 'CS5' - set qos policy shaper vyos3 class 30 match ADDRESS20 ip source address '172.17.1.4/32' - set qos policy shaper vyos3 class 30 set-dscp 'CS6' - set qos policy shaper vyos3 default bandwidth '10%' - set qos policy shaper vyos3 default ceiling '100%' - set qos policy shaper vyos3 default priority '7' - set qos policy shaper vyos3 default queue-type 'fair-queue' - set qos interface eth0 egress 'vyos3' + set interfaces ethernet eth0 address '10.1.1.100/24' + set interfaces ethernet eth1 address '172.17.1.1/24' + set protocols static route 0.0.0.0/0 next-hop 10.1.1.1 + set qos policy shaper vyos3 class 10 match ADDRESS10 ip source address '172.17.1.2/32' + set qos policy shaper vyos3 class 10 set-dscp 'CS4' + set qos policy shaper vyos3 class 20 match ADDRESS20 ip source address '172.17.1.3/32' + set qos policy shaper vyos3 class 20 set-dscp 'CS5' + set qos policy shaper vyos3 class 30 match ADDRESS20 ip source address '172.17.1.4/32' + set qos policy shaper vyos3 class 30 set-dscp 'CS6' + set qos policy shaper vyos3 default bandwidth '10%' + set qos policy shaper vyos3 default ceiling '100%' + set qos policy shaper vyos3 default priority '7' + set qos policy shaper vyos3 default queue-type 'fair-queue' + set qos interface eth0 egress 'vyos3' + +.. start_vyoslinter Main rules: @@ -85,25 +98,27 @@ After the interface eth0 on router VyOS3 :align: center :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 +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 .. code-block:: 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 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 +Next on the router VyOS2 we will change labels on all incoming +traffic only from CS4-> CS6 .. image:: /_static/images/qos5.* :width: 80% @@ -112,20 +127,20 @@ Next on the router VyOS2 we will change labels on all incoming traffic only from .. code-block:: 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 interfaces ethernet eth0 address '10.1.1.1/24' + set interfaces ethernet eth1 address '10.2.1.1/24' + set interfaces ethernet eth2 address '10.9.9.1/24' + set protocols static route 172.17.1.0/24 next-hop 10.1.1.100 + set qos policy shaper vyos2 class 10 bandwidth '100%' + set qos policy shaper vyos2 class 10 burst '15k' + set qos policy shaper vyos2 class 10 match VYOS2 ip dscp 'CS4' + set qos policy shaper vyos2 class 10 queue-type 'fair-queue' + set qos policy shaper vyos2 class 10 set-dscp 'CS5' + set qos policy shaper vyos2 default bandwidth '100%' + set qos policy shaper vyos2 default burst '15k' + set qos policy shaper vyos2 default ceiling '100%' + set qos policy shaper vyos2 default priority '7' + set qos policy shaper vyos2 default queue-type 'fair-queue' set qos interface eth2 egress 'vyos2' .. image:: /_static/images/qos6.* @@ -154,23 +169,26 @@ Next on the router VyOS2 we will change labels on all incoming traffic only from :align: center :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. +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”. .. code-block:: 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 - } - } - } + 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. diff --git a/docs/configexamples/site-2-site-cisco.rst b/docs/configexamples/site-2-site-cisco.rst index 96e48d07..e8322002 100644 --- a/docs/configexamples/site-2-site-cisco.rst +++ b/docs/configexamples/site-2-site-cisco.rst @@ -1,7 +1,8 @@ .. _examples-site-2-site-cisco: +############################################# Site-to-Site IPSec VPN to Cisco using FlexVPN ---------------------------------------------- +############################################# This guide shows a sample configuration for FlexVPN site-to-site Internet Protocol Security (IPsec)/Generic Routing Encapsulation (GRE) tunnel. @@ -28,7 +29,7 @@ VyOS set interfaces tunnel tun1 ip adjust-mss '1336' set interfaces tunnel tun1 mtu '1376' set interfaces tunnel tun1 remote '10.1.1.6' - set interfaces tunnel tun1 source-address '88.2.2.1' + set interfaces tunnel tun1 source-address '198.51.100.1' - IPsec: @@ -59,9 +60,9 @@ VyOS set vpn ipsec site-to-site peer cisco_hub connection-type 'initiate' set vpn ipsec site-to-site peer cisco_hub default-esp-group 'e1' set vpn ipsec site-to-site peer cisco_hub ike-group 'i1' - set vpn ipsec site-to-site peer cisco_hub local-address '88.2.2.1' + set vpn ipsec site-to-site peer cisco_hub local-address '198.51.100.1' set vpn ipsec site-to-site peer cisco_hub remote-address '10.1.1.6' - set vpn ipsec site-to-site peer cisco_hub tunnel 1 local prefix '88.2.2.1/32' + set vpn ipsec site-to-site peer cisco_hub tunnel 1 local prefix '198.51.100.1/32' set vpn ipsec site-to-site peer cisco_hub tunnel 1 protocol 'gre' set vpn ipsec site-to-site peer cisco_hub tunnel 1 remote prefix '10.1.1.6/32' set vpn ipsec site-to-site peer cisco_hub virtual-address '0.0.0.0' @@ -141,7 +142,7 @@ Verification --------- ---------- --- ----------- eth0 - u/u eth1 - u/u - eth2 88.2.2.1/24 u/u + eth2 198.51.100.1/24 u/u eth3 172.16.1.2/24 u/u lo 127.0.0.1/8 u/u ::1/128 @@ -157,7 +158,7 @@ Verification IPv4 Crypto IKEv2 SA Tunnel-id Local Remote fvrf/ivrf Status - 5 10.1.1.6/4500 88.2.2.1/4500 none/none READY + 5 10.1.1.6/4500 198.51.100.1/4500 none/none READY Encr: AES-CBC, keysize: 256, PRF: SHA256, Hash: SHA256, DH Grp:5, Auth sign: PSK, Auth verify: PSK Life/Active Time: 86400/2694 sec CE id: 0, Session-id: 2 diff --git a/docs/configexamples/wan-load-balancing.rst b/docs/configexamples/wan-load-balancing.rst index 906078bb..d03d4ed9 100644 --- a/docs/configexamples/wan-load-balancing.rst +++ b/docs/configexamples/wan-load-balancing.rst @@ -4,8 +4,9 @@ .. stop_vyoslinter # pictures and text have to change +########################## WAN Load Balancer examples -========================== +########################## Example 1: Distributing load evenly diff --git a/docs/configexamples/zone-policy.rst b/docs/configexamples/zone-policy.rst index 3c387519..7ea33b95 100644 --- a/docs/configexamples/zone-policy.rst +++ b/docs/configexamples/zone-policy.rst @@ -2,8 +2,9 @@ .. _examples-zone-policy: +################### Zone-Policy example -------------------- +################### .. note:: In :vytask:`T2199` the syntax of the zone configuration was changed. The zone configuration moved from ``zone-policy zone <name>`` to ``firewall diff --git a/docs/configuration/firewall/bridge.rst b/docs/configuration/firewall/bridge.rst index fdf1179f..832bdf67 100644 --- a/docs/configuration/firewall/bridge.rst +++ b/docs/configuration/firewall/bridge.rst @@ -1,4 +1,4 @@ -:lastproofread: 2024-08-05 +:lastproofread: 2026-03-28 .. _firewall-configuration: @@ -10,13 +10,15 @@ Bridge Firewall Configuration Overview ******** -In this section there's useful information on all firewall configuration that -can be done regarding bridges, and appropriate op-mode commands. -Configuration commands covered in this section: +Learn more about bridge firewall configuration +and related op-mode commands. -.. cfgcmd:: set firewall bridge ... +The following commands are covered in this section: -From the main structure defined in :doc:`Firewall Overview</configuration/firewall/index>` +.. cfgcmd:: set firewall bridge <options> + +From the main structure defined in +:doc:`Firewall Overview</configuration/firewall/index>` in this section you can find detailed information only for the next part of the general structure: @@ -35,7 +37,7 @@ of the general structure: - name + custom_name -Traffic which is received by the router on an interface which is member of a +Traffic that is received by the router on an interface that is a member of a bridge is processed on the **Bridge Layer**. Before the bridge decision is made, all packets are analyzed at **Prerouting**. First filters can be applied here, and also rules for ignoring connection tracking system can be configured. @@ -43,15 +45,16 @@ The relevant configuration that acts in **prerouting** is: * ``set firewall bridge prerouting filter ...``. -For traffic that needs to be switched internally by the bridge, base chain is -**forward**, and it's base command for filtering is ``set firewall bridge -forward filter ...``, which happens in stage 4, highlighted with red color. +For traffic that needs to be switched internally by the bridge, the base +chain is **forward**, and its base command for filtering is ``set firewall +bridge forward filter ...``, which happens in stage 4, highlighted with red +color. .. figure:: /_static/images/firewall-bridge-forward.* -For traffic destined to the router itself, or that needs to be routed (assuming -a layer3 bridge is configured), the base chain is **input**, the base command -is ``set firewall bridge input filter ...`` and the path is: +For traffic destined to the router itself or that needs to be routed +(assuming a layer3 bridge is configured), the base chain is **input**, and the +base command is ``set firewall bridge input filter ...`` and the path is: .. figure:: /_static/images/firewall-bridge-input.* @@ -60,15 +63,15 @@ processed by the **IP Layer** firewall: IPv4 or IPv6 ruleset. Check once again the :doc:`general packet flow diagram</configuration/firewall/index>` if needed. -And for traffic that originates from the bridge itself, the base chain is -**output**, base command is ``set firewall bridge output filter ...``, and -the path is: +For traffic that originates from the bridge itself, the base chain is +**output**, and the base command is ``set firewall bridge output filter +...``, and the path is: .. figure:: /_static/images/firewall-bridge-output.* -Custom bridge firewall chains can be created with the command ``set firewall bridge -name <name> ...``. In order to use such custom chain, a rule with action jump, -and the appropriate target should be defined in a base chain. +Custom bridge firewall chains can be created with the command ``set firewall +bridge name <name> ...``. To use such a custom chain, a rule with action jump +and the appropriate target must be defined in a base chain. ************ Bridge Rules @@ -83,8 +86,8 @@ 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 matching criterea in the rule are met. +If a rule is defined, an action must also be defined for it. This tells the +firewall what to do if all matching criteria in the rule are met. In firewall bridge rules, the action can be: @@ -169,7 +172,7 @@ In firewall bridge rules, the action can be: queue-options fanout Also, **default-action** is an action that takes place whenever a packet does -not match any rule in its' chain. For base chains, possible options for +not match any rule in its chain. For base chains, possible options for **default-action** are **accept** or **drop**. .. cfgcmd:: set firewall bridge forward filter default-action @@ -202,8 +205,8 @@ not match any rule in its' chain. For base chains, possible options for Firewall Logs ============= -Logging can be enable for every single firewall rule. If enabled, other -log options can be defined. +You can enable logging for every firewall rule. If enabled, other log options +can be configured. .. cfgcmd:: set firewall bridge forward filter rule <1-999999> log .. cfgcmd:: set firewall bridge input filter rule <1-999999> log @@ -287,7 +290,7 @@ log options can be defined. Firewall Description ==================== -For reference, a description can be defined for every defined custom chain. +You can define a description for reference for every custom chain. .. cfgcmd:: set firewall bridge name <name> description <text> @@ -309,8 +312,8 @@ For reference, a description can be defined for every defined custom chain. Rule Status =========== -When defining a rule, it is enabled by default. In some cases, it is useful to -just disable the rule, rather than removing it. +By default, when you define a rule, it is enabled. In some cases, it is +useful to disable the rule instead of removing it. .. cfgcmd:: set firewall bridge forward filter rule <1-999999> disable .. cfgcmd:: set firewall bridge input filter rule <1-999999> disable @@ -323,11 +326,11 @@ just disable the rule, rather than removing it. Matching criteria ================= -There are a lot of matching criteria against which the packet can be tested. -Please refer to :doc:`IPv4</configuration/firewall/ipv4>` and +There are many matching criteria against which a packet can be tested. Refer +to :doc:`IPv4</configuration/firewall/ipv4>` and :doc:`IPv6</configuration/firewall/ipv6>` matching criteria for more details. -Since bridges operats at layer 2, both matchers for IPv4 and IPv6 are +Since bridges operate at layer 2, both matchers for IPv4 and IPv6 are supported in bridge firewall configuration. Same applies to firewall groups. Same specific matching criteria that can be used in bridge firewall are @@ -434,15 +437,15 @@ are: .. cfgcmd:: set firewall global-options apply-to-bridged-traffic ipv4 - This command enables the IPv4 firewall for bridged traffic. If this - options is used, then packet will also be parsed by rules defined in ``set - firewall ipv4 ...`` + This command enables the IPv4 firewall for bridged traffic. If this option + is used, packets are also parsed by rules defined in ``set firewall ipv4 + ...`` .. cfgcmd:: set firewall global-options apply-to-bridged-traffic ipv6 - This command enables the IPv6 firewall for bridged traffic. If this - options is used, then packet will also be parsed by rules defined in ``set - firewall ipv6 ...`` + This command enables the IPv6 firewall for bridged traffic. If this option + is used, packets are also parsed by rules defined in ``set firewall ipv6 + ...`` *********************** Operation-mode Firewall diff --git a/docs/configuration/firewall/flowtables.rst b/docs/configuration/firewall/flowtables.rst index 35fb0add..f996a59e 100644 --- a/docs/configuration/firewall/flowtables.rst +++ b/docs/configuration/firewall/flowtables.rst @@ -1,4 +1,4 @@ -:lastproofread: 2024-07-02 +:lastproofread: 2026-03-30 .. _firewall-flowtables-configuration: @@ -6,21 +6,18 @@ Flowtables Firewall Configuration ################################# -.. note:: **Documentation under development** +.. include:: /_include/need_improvement.txt ******** Overview ******** -In this section there's useful information on all firewall configuration that -can be done regarding flowtables. +This section provides information on firewall configuration for flowtables. -.. cfgcmd:: set firewall flowtables ... +.. cfgcmd:: set firewall flowtable ... -From the main structure defined in -:doc:`Firewall Overview</configuration/firewall/index>` -in this section you can find detailed information only for the next part -of the general structure: +To learn about the general traffic flow in VyOS firewalls, +see :doc:`Firewall </configuration/firewall/index>`. .. code-block:: none @@ -30,24 +27,23 @@ of the general structure: + ... -Flowtables allow 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. +Flowtables let you define a fastpath through the flowtable datapath. +Flowtables support layer 3 (IPv4 and IPv6) and layer 4 (TCP and UDP) +protocols. .. figure:: /_static/images/firewall-flowtable-packet-flow.* -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) +After the first packet successfully traverses the IP forwarding path (black +circles path), you can offload subsequent packets to the flowtable through your +ruleset. You specify when to add a flow to the flowtable during 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. +When a packet finds a matching entry in the flowtable (flowtable hit), the +system transmits it to the output netdevice. This means packets bypass the +classic IP forwarding path and use the **Fast Path** (orange circles path). +As a result, you do not see these packets from any Netfilter hooks after +ingress. If no matching entry exists in the flowtable (flowtable miss), the +packet traverses the classic IP forwarding path. .. note:: **Flowtable Reference:** https://docs.kernel.org/networking/nf_flowtable.html @@ -57,64 +53,68 @@ flowtable (flowtable miss), the packet follows the classic IP forwarding path. Flowtable Configuration *********************** -In order to use flowtables, the minimal configuration needed includes: +To use flowtables, you need to configure the following: - * Create flowtable: create flowtable, which includes the interfaces + * Create a flowtable that 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``. + * Create a firewall rule. Set the action to + ``offload`` and use your desired flowtable for ``offload-target``. Creating a flow table: .. cfgcmd:: set firewall flowtable <flow_table_name> interface <iface> - Define interfaces to be used in the flowtable. + Specify interfaces to use in the flowtable. .. cfgcmd:: set firewall flowtable <flow_table_name> description <text> -Provide a description to the flow table. +Provide a description for the flow table. .. 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. + Specify the offload type the flowtable uses: ``hardware`` or + ``software``. The default is ``software`` offload. -.. note:: **Hardware offload:** should be supported by the NICs used. +.. note:: **Hardware offload**: Make sure your network interface controller + (NIC) supports hardware offloading and that you have the necessary drivers + installed before enabling this option. Creating rules for using flow tables: .. cfgcmd:: set firewall [ipv4 | ipv6] forward filter rule <1-999999> action offload - Create firewall rule in forward chain, and set action to ``offload``. + Create a firewall rule in the forward chain with the action set to + ``offload``. .. 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``. + Create a firewall rule in the forward chain and specify which flowtable + to use. Only applicable if the action is ``offload``. ********************* Configuration Example ********************* -Things to be considered in this setup: +Consider the following in this setup: - * Two interfaces are going to be used in the flowtables: eth0 and eth1 + * This example uses two interfaces in the flowtables: ``eth0`` and ``eth1``. - * Minimum firewall ruleset is provided, which includes some filtering rules, - and appropriate rules for using flowtable offload capabilities. + * The example provides a minimal firewall ruleset with filtering rules + and rules for using flowtable offload capabilities. -As described, the first packet will be evaluated by the firewall path, so a -desired connection should be explicitly accepted. Same thing should be taken -into account for traffic in reverse order. In most cases state policies are -used in order to accept a connection in the reverse path. +The first packet is evaluated by the firewall path, so a +desired connection should be explicitly accepted. +The same should occur for traffic in reverse order. +In most cases, state policies are +used to accept a connection in the reverse path. -We will only accept traffic coming from interface eth0, protocol tcp and -destination port 1122. All other traffic trespassing the router should be -blocked. +In the following example only traffic coming from interface ``eth0``, +TCP protocol, and destination port 1122 is accepted. +All other traffic to the router is dropped. Commands -------- @@ -140,33 +140,32 @@ Commands Explanation ----------- -Analysis on what happens for desired connection: +Here's what happens for a desired connection: - 1. Firstly, a 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. + 1. A packet arrives on ``eth0`` with destination address ``192.0.2.100``, TCP + protocol, and destination port 1122. Assume this 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. + 2. For this first packet, the connection state is **new**. Neither rule 10 + nor rule 20 applies. - 3. Rule 110 is hit, so connection is accepted. + 3. Rule 110 matches, so the connection is accepted. - 4. Once an 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. + 4. When the server 192.0.2.100 replies, the connection state becomes + **established**, and rule 20 accepts the reply. - 5. The 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. + 5. The router receives the second packet for this connection. Because the + connection state is **established**, rule 10 matches and adds a new + entry in the flowtable FT01 for this connection. - 6. All the following packets will skip the traditional path, will be - offloaded and use the **Fast Path**. + 6. Subsequent packets skip the traditional path and use the **Fast Path** + for offloading. Checks ------ -It's time to check the conntrack table, to see if any connections were accepted, -and if it was properly offloaded +Check the conntrack table to verify that the system accepted and properly +offloaded connections. .. code-block:: none diff --git a/docs/configuration/firewall/global-options.rst b/docs/configuration/firewall/global-options.rst index 60addbe9..8eec5c3f 100644 --- a/docs/configuration/firewall/global-options.rst +++ b/docs/configuration/firewall/global-options.rst @@ -1,4 +1,4 @@ -:lastproofread: 2024-07-03 +:lastproofread: 2026-03-30 .. _firewall-global-options-configuration: @@ -10,9 +10,9 @@ 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. +Some firewall settings are global and affect the entire system. This section +provides information about these global options that you can configure using +the VyOS CLI. Configuration commands covered in this section: @@ -25,51 +25,50 @@ Configuration .. 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 prevent it - through its firewall. + itself, it answers with an ICMP echo reply, unless your firewall prevents + it. - 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. + You can set firewall rules to accept, drop, or reject ICMP in, out, or + local traffic. You can also use the **firewall global-options all-ping** + command. This command affects only LOCAL traffic (packets destined for your + VyOS system), not IN or OUT traffic. - .. note:: **firewall global-options all-ping** affects only to LOCAL - and it always behaves in the most restrictive way + .. note:: **firewall global-options all-ping** affects only LOCAL traffic + and always behaves in the most restrictive way .. code-block:: none set firewall global-options all-ping enable - When the command above is set, VyOS will answer every ICMP echo request - addressed to itself, but that will only happen if no other rule is - applied dropping or rejecting local echo requests. In case of conflict, - VyOS will not answer ICMP echo requests. + When you set this command, VyOS answers every ICMP echo request addressed + to itself, but that response occurs only if no other rule drops or rejects + local echo requests. In case of conflict, VyOS does not answer ICMP echo + requests. .. code-block:: none set firewall global-options all-ping disable - When the command above is set, VyOS will answer no ICMP echo request - addressed to itself at all, no matter where it comes from or whether - more specific rules are being applied to accept them. + When you set this command, VyOS answers no ICMP echo requests addressed to + itself, regardless of where they come from or what specific rules accept + them. .. cfgcmd:: set firewall global-options apply-to-bridged-traffic [ipv4 | ipv6] - Use these commands to also use IPv4, or IPv6 firewall rules for bridged - traffic + Apply IPv4 or IPv6 firewall rules to bridged traffic. .. cfgcmd:: set firewall global-options broadcast-ping [enable | disable] - This setting enables or disables the response to icmp broadcast - messages. The following system parameter will be altered: + Enable or disable the response to ICMP broadcast messages. The system + alters the following parameter: * ``net.ipv4.icmp_echo_ignore_broadcasts`` .. cfgcmd:: set firewall global-options ip-src-route [enable | disable] .. cfgcmd:: set firewall global-options ipv6-src-route [enable | disable] - This setting handles if VyOS accepts packets with a source route - option. The following system parameters will be altered: + Set whether VyOS accepts packets with a source route option. + The following sysctl parameters will be changed: * ``net.ipv4.conf.all.accept_source_route`` * ``net.ipv6.conf.all.accept_source_route`` @@ -78,23 +77,23 @@ Configuration .. cfgcmd:: set firewall global-options ipv6-receive-redirects [enable | disable] - Enable or disable ICMPv4 or ICMPv6 redirect messages being accepted by - VyOS. The following system parameters will be altered: + Allow VyOS to accept ICMPv4 and ICMPv6 redirect messages. + The following sysctl parameters will be changed: * ``net.ipv4.conf.all.accept_redirects`` * ``net.ipv6.conf.all.accept_redirects`` .. cfgcmd:: set firewall global-options send-redirects [enable | disable] - Enable or disable ICMPv4 redirect messages being sent by VyOS - The following system parameter will be altered: + Allow VyOS to send ICMPv4 redirect messages. + The following sysctl parameter will be changed: * ``net.ipv4.conf.all.send_redirects`` .. 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: + Allow VyOS to log martian IPv4 packets. + The following sysctl parameter will be changed: * ``net.ipv4.conf.all.log_martians`` @@ -102,22 +101,22 @@ Configuration [strict | loose | disable] Set the IPv4 source validation mode. - The following system parameter will be altered: + The following sysctl parameter will be changed: * ``net.ipv4.conf.all.rp_filter`` .. cfgcmd:: set firewall global-options syn-cookies [enable | disable] - Enable or disable if VyOS uses IPv4 TCP SYN Cookies. - The following system parameter will be altered: + Allow VyOS to use IPv4 TCP SYN Cookies. + The following sysctl parameter will be changed: * ``net.ipv4.tcp_syncookies`` .. cfgcmd:: set firewall global-options twa-hazards-protection [enable | disable] - Enable or Disable VyOS to be :rfc:`1337` conformant. - The following system parameter will be altered: + Enable or disable VyOS :rfc:`1337` conformance. + The following sysctl parameter will be changed: * ``net.ipv4.tcp_rfc1337`` @@ -151,10 +150,9 @@ Configuration Set the global setting for related connections. -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. +VyOS supports setting timeouts for connections by connection type. You can +set timeout values for generic connections, ICMP connections, UDP +connections, or TCP connections in various states. .. cfgcmd:: set firewall global-options timeout icmp <1-21474836> :defaultvalue: diff --git a/docs/configuration/firewall/groups.rst b/docs/configuration/firewall/groups.rst index b1accca5..9d29866e 100644 --- a/docs/configuration/firewall/groups.rst +++ b/docs/configuration/firewall/groups.rst @@ -1,4 +1,4 @@ -:lastproofread: 2024-07-03 +:lastproofread: 2026-03-30 .. _firewall-groups-configuration: @@ -11,20 +11,20 @@ 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. +MAC addresses, domains, or interfaces. You can reference a group in firewall, +NAT, and policy route rules as either a source or destination matcher, and/or +as inbound or outbound in the case of interface groups. Address Groups ============== -In an **address group** a single IP address or IP address range is defined. +An **address group** contains a single IP address or IP address range. .. cfgcmd:: set firewall group address-group <name> address [address | address range] .. cfgcmd:: set firewall group ipv6-address-group <name> address <address> - Define a IPv4 or a IPv6 address group + Define an IPv4 or IPv6 address group. .. code-block:: none @@ -35,30 +35,31 @@ In an **address group** a single IP address or IP address range is defined. .. cfgcmd:: set firewall group address-group <name> description <text> .. cfgcmd:: set firewall group ipv6-address-group <name> description <text> - Provide a IPv4 or IPv6 address group description + Provide an IPv4 or IPv6 address group description. Remote Groups ============== -A **remote-group** takes an argument of a URL hosting a linebreak-deliminated -list of IPv4 and/or IPv6 addresses, CIDRs and ranges. VyOS will pull this list periodicity -according to the frequency defined in the firewall **resolver-interval** and load -matching entries into the group for use in rules. The list will be cached in -persistent storage, so in cases of update failure rules will still function. +A **remote-group** uses a URL that hosts a newline-delimited list of IPv4 +and/or IPv6 addresses, CIDRs, and ranges. VyOS pulls this list periodically +according to the frequency you define in the firewall **resolver-interval** +and loads matching entries into the group for use in rules. The list is cached +in persistent storage, so rules continue to function if updates fail. .. cfgcmd:: set firewall group remote-group <name> url <http(s) url> - Define remote list of IPv4 and/or IPv6 addresses/ranges/CIDRs to fetch + Specify a remote list of IPv4 and/or IPv6 addresses, ranges, and CIDRs + to fetch. .. cfgcmd:: set firewall group remote-group <name> description <text> - Set a description for a remote group + Set a description for a remote group. -The format of the remote list is very flexible. VyOS will attempt to parse the -first word of each line as an entry, and will skip if it cannot find a valid -match. Lines that begin with an alphanumeric character but do not match valid IPv4 -or IPv6 addresses, ranges, or CIDRs will be logged to the system log. Below is a -list of acceptable matches that would be parsed correctly: +The remote list format is flexible. VyOS attempts to parse the first word of +each line as an entry and skips lines it cannot match. Lines that begin with +an alphanumeric character but do not match valid IPv4 or IPv6 addresses, +ranges, or CIDRs are logged to the system log. The following examples show +acceptable formats that VyOS parses correctly: .. code-block:: none @@ -72,15 +73,14 @@ list of acceptable matches that would be parsed correctly: 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, then a network group is -recommended. +**Network groups** accept IP networks in CIDR notation. You can add specific +IP addresses as a 32-bit prefix. If you need to add a mix of addresses and +networks, use a network group. .. cfgcmd:: set firewall group network-group <name> network <CIDR> .. cfgcmd:: set firewall group ipv6-network-group <name> network <CIDR> - Define a IPv4 or IPv6 Network group. + Define an IPv4 or IPv6 network group. .. code-block:: none @@ -100,7 +100,9 @@ An **interface group** represents a collection of interfaces. .. cfgcmd:: set firewall group interface-group <name> interface <text> - Define an interface group. Wildcard are accepted too. + Define an interface group. + Wildcard ``*`` is supported. For example: ``eth3*``. + Prepend the character ``!`` to invert the criteria. For example: ``!eth2``. .. code-block:: none @@ -109,22 +111,21 @@ An **interface group** represents a collection of interfaces. .. cfgcmd:: set firewall group interface-group <name> description <text> - Provide an interface group description + Provide an interface group description. Port Groups =========== -A **port group** represents only port numbers, not the protocol. Port -groups can be referenced for either TCP or UDP. It is recommended that -TCP and UDP groups are created separately to avoid accidentally -filtering unnecessary ports. Ranges of ports can be specified by using -`-`. +A **port group** represents only port numbers, not the protocol. You can +reference port groups for either TCP or UDP. Create TCP and UDP groups +separately to avoid accidentally filtering unnecessary ports. Specify port +ranges by using `-`. .. 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 + /etc/services. For example, ``http``. .. code-block:: none @@ -152,7 +153,7 @@ A **mac group** represents a collection of mac addresses. .. cfgcmd:: set firewall group mac-group <name> description <text> - Provide a mac group description. + Provide a MAC group description. Domain Groups ============= @@ -169,24 +170,21 @@ A **domain group** represents a collection of domains. .. cfgcmd:: set firewall group domain-group <name> description <text> - Provide a domain group description. + Provide a domain group description. Dynamic Groups ============== -Firewall dynamic groups are different from all the groups defined previously -because, not only they can be used as source/destination in firewall rules, -but members of these groups are not defined statically using vyos -configuration. - -Instead, members of these groups are added dynamically using firewall -rules. +Firewall dynamic groups differ from other groups because you can use them as +source/destination in firewall rules, and members are not defined statically +in VyOS configuration. Instead, firewall rules dynamically add members to +these groups. 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: +Dynamic address groups support both IPv4 and IPv6 families. Use these +commands to define dynamic IPv4 and IPv6 address groups: .. cfgcmd:: set firewall group dynamic-group address-group <name> .. cfgcmd:: set firewall group dynamic-group ipv6-address-group <name> @@ -201,8 +199,8 @@ Add description to firewall groups: 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. +After you define dynamic firewall groups, use them in firewall rules to +dynamically add elements to them. Commands used for this task are: @@ -228,11 +226,11 @@ Commands used for this task are: .. cfgcmd:: set firewall ipv6 name <name> rule <1-999999> add-address-to-group source-address address-group <name> -Also, specific timeouts can be defined per rule. In case rule gets a hit, -a source or destinatination address will be added to the group, and this -element will remain in the group until the 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. +You can define specific timeouts per rule. When a rule matches, the source or +destination address is added to the group, and the element remains in the group +until the timeout expires. If you do not define a timeout, the element remains +in the group until the next reboot or until you commit firewall configuration +changes. .. cfgcmd:: set firewall ipv4 [forward | input | output] filter rule <1-999999> add-address-to-group [destination-address | source-address] @@ -259,7 +257,7 @@ Timeout can be defined using seconds, minutes, hours or days: Using Dynamic Firewall Groups ----------------------------- -As any other firewall group, dynamic firewall groups can be used in firewall +Like other firewall groups, you can use dynamic firewall groups in firewall rules as matching options. For example: .. code-block:: none @@ -274,10 +272,9 @@ 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: +After you create firewall groups, you can reference them in firewall, NAT, +NAT66, and/or policy-route rules. The following example creates multiple +groups: .. code-block:: none @@ -314,10 +311,9 @@ And next, some configuration example where groups are used: 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: +You can use dynamic firewall groups with port knocking to secure access to +the router or any other device. The following example shows a 4-step port +knocking configuration: .. code-block:: none @@ -371,11 +367,10 @@ Before testing, we can check the members of firewall groups: [edit] vyos@vyos# -With this configuration, in order to get ssh access to the router, the user -needs to: +With this configuration, to gain SSH access to the router, the user must: -1. Generate a new TCP connection with destination port 9990. As shown next, -a new entry was added to dynamic firewall group **PN_01** +1. Create a new TCP connection to destination port 9990. A new entry is added + to dynamic firewall group ``PN_01``. .. code-block:: none @@ -390,8 +385,8 @@ a new entry was added to dynamic firewall group **PN_01** [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** +2. Create a new TCP connection to destination port 9991. A new entry is added + to dynamic firewall group ``PN_02``. .. code-block:: none @@ -406,8 +401,8 @@ a new entry was added to dynamic firewall group **PN_02** [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** +3. Create a new TCP connection to destination port 9992. A new entry is added + to dynamic firewall group ``ALLOWED``. .. code-block:: none @@ -422,7 +417,8 @@ a new entry was added to dynamic firewall group **ALLOWED** [edit] vyos@vyos# -4. Now the user can connect through ssh to the router (assuming ssh is configured). +4. Now you can connect via SSH to the router (assuming SSH is + configured). ************** Operation-mode @@ -431,9 +427,9 @@ Operation-mode .. opcmd:: show firewall group .. 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). + Display an overview of defined groups, including the firewall group name, + type, references (where the group is used), members, timeout, and + expiration (the last two only apply to dynamic firewall groups). Here is an example of such command: diff --git a/docs/configuration/firewall/index.rst b/docs/configuration/firewall/index.rst index 4fd9b208..c4b3c808 100644 --- a/docs/configuration/firewall/index.rst +++ b/docs/configuration/firewall/index.rst @@ -1,128 +1,122 @@ -:lastproofread: 2024-08-05 +:lastproofread: 2026-03-30 ######## Firewall ######## -.. warning:: Due to a race condition that can lead to a failure during boot - process, all interfaces are initialized before firewall is configured. This - leads to a situation where the system is open to all traffic, and can be - considered as a security risk. +.. warning:: Due to a boot-time race condition, all interfaces initialize + before the firewall. This temporarily leaves the system open to all traffic + and poses a security risk. -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). +VyOS uses Netfilter. The Netfilter +project developed ``iptables`` and its successor ``nftables`` for the Linux +kernel to process packet data flows directly. This extends the concept of +zone-based security to let you manipulate data at multiple stages after the +network interface and driver accept it, and before sending it to its +destination (for example, 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. +The following is a simplified traffic flow diagram based on Netfilter +packet flow. +This diagram provides an overview of how packets are processed and the +possible paths traffic can take. .. figure:: /_static/images/firewall-gral-packet-flow.* -The main points regarding this packet flow and terminology used in VyOS -firewall are covered below: +The main points regarding packet flow and terminology in VyOS firewall +are: - * **Bridge Port?**: choose appropriate path based on whether interface - where the packet was received is part of a bridge, or not. + * **Bridge Port?**: Choose the appropriate path based on whether the + interface where the packet was received is part of a bridge. -If the interface where the packet was received isn't part of a bridge, then +If the interface where the packet was received is not part of a bridge, the packet is processed at the **IP Layer**: - * **Prerouting**: All packets that are received by the router - are processed in this stage, regardless of the destination of the packet. - Starting from vyos-1.5-rolling-202406120020, a new section was added to - the firewall configuration. There are several actions that can be done in - this stage, and currently these actions are also defined in different - parts of the VyOS configuration. Order is important, and the relevant - configuration that acts in this stage are: + * **Prerouting**: The router processes all packets in this stage, + regardless of the destination. You can perform several actions in + this stage, and these actions are also defined in different parts of the + VyOS configuration. Order is important. The relevant configuration that + applies in this stage includes: - * **Firewall prerouting**: rules defined under ``set firewall [ipv4 | - ipv6] prerouting raw...``. All rules defined in this section are - processed before connection tracking subsystem. + * **Firewall prerouting**: Rules you define under ``set firewall + [ipv4 | ipv6] prerouting raw...``. The system processes all rules in + this section before the connection tracking subsystem. - * **Conntrack Ignore**: rules defined under ``set system conntrack ignore - [ipv4 | ipv6] ...``. Starting from vyos-1.5-rolling-202406120020, - configuration done in this section can be done in ``firewall [ipv4 | - ipv6] prerouting ...``. For compatibility reasons, this feature is - still present, but it will be removed in the future. + * **Conntrack Ignore**: Rules you define under ``set system conntrack + ignore [ipv4 | ipv6] ...``. You can configure this section with + ``firewall [ipv4 | ipv6] prerouting ...``. For compatibility reasons, + this feature is supported, but will be deprecated in the future. - * **Policy Route**: rules defined under ``set policy [route | route6] - ...``. + * **Policy Route**: Rules you define under ``set policy [route | + route6] ...``. - * **Destination NAT**: rules defined under ``set [nat | nat66] + * **Destination NAT**: Rules you define under ``set [nat | nat66] destination...``. - * **Destination is the router?**: choose an appropriate path based on - destination IP address. Transit forward continues to **forward**, - while traffic where the destination IP address is configured on the router - continues to **input**. + * **Destination is the router?**: Choose the appropriate path based on the + destination IP address. Transit traffic continues to **forward**, while + traffic destined for 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: + * **Input**: The stage where you filter and control traffic destined for + the router itself. This is where you enforce all rules for securing the + router. 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: + * **Forward**: The stage where you filter and control transit traffic. + 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 the VyOS router - such as NTP, or a response to traffic received externally through - **input** (for example response to an ssh login attempt to the router). - This includes ipv4 and ipv6 rules, and two different sections are present: + * **Output**: The stage where you filter and control traffic that the + router originates. Note that this traffic comes from either a new + connection that an internal process on the VyOS router (such as NTP) + originates or a response to traffic the router receives externally through + **input** (for example, a response to an SSH login attempt). This includes + IPv4 and IPv6 rules, and two different sections apply: - * **Output Prerouting**: ``set firewall [ipv4 | ipv6] output filter ...``. - As described in **Prerouting**, rules defined in this section are - processed before connection tracking subsystem. + * **Output Prerouting**: ``set firewall [ipv4 | ipv6] output + filter ...``. As described in **Prerouting**, the system processes + rules in this section before the connection tracking subsystem. * **Output Filter**: ``set firewall [ipv4 | ipv6] output filter ...``. - * **Postrouting**: as in **Prerouting**, several actions defined in - different parts of VyOS configuration are performed in this - stage. This includes: + * **Postrouting**: As in **Prerouting**, you can perform several actions + defined in different parts of VyOS configuration in this stage. This + includes: - * **Source NAT**: rules defined under ``set [nat | nat66] + * **Source NAT**: Rules you define under ``set [nat | nat66] destination...``. -If the interface where the packet was received is part of a bridge, then -the packet is processed at the **Bridge Layer**: +If the interface where the packet was received is part of a bridge, the +packet is processed at the **Bridge Layer**: - * **Prerouting (Bridge)**: all packets that are received by the bridge are - processed in this stage, regardless of the destination of the packet. - First filters can be applied here, and/or also configure rules for - ignoring connection tracking system. The relevant configuration that - acts in: + * **Prerouting (Bridge)**: The bridge processes all packets it receives in + this stage, regardless of the destination. First, you can apply filters + here, or you can configure rules that ignore the connection tracking + system. The relevant configuration that applies: * ``set firewall bridge prerouting filter ...``. - * **Forward (Bridge)**: stage where traffic that is trespassing through the - bridge is filtered and controlled: + * **Forward (Bridge)**: The stage where you filter and control traffic + that passes through the bridge: * ``set firewall bridge forward filter ...``. - * **Input (Bridge)**: stage where traffic destined for the bridge itself can - be filtered and controlled: + * **Input (Bridge)**: The stage where you filter and control traffic + destined for the bridge itself: * ``set firewall bridge input filter ...``. - * **Output (Bridge)**: stage where traffic that originates from the bridge - itself can be filtered and controlled: + * **Output (Bridge)**: The stage where you filter and control traffic that + the bridge originates: * ``set firewall bridge output filter ...``. -The main structure of the VyOS firewall CLI is shown next: +The following is the overall structure of the VyOS firewall CLI: .. code-block:: none @@ -182,8 +176,53 @@ The main structure of the VyOS firewall CLI is shown next: - custom_zone_name + ... -Please, refer to appropriate section for more information about firewall -configuration: +Here is a list of VyOS firewall CLI subcommands and their +corresponding pages in the documentation: + +.. cfgcmd:: set firewall bridge ... + + Configure bridge firewall rules for traffic at the bridge layer. For detailed + information, see + :doc:`Bridge Firewall Configuration</configuration/firewall/bridge>`. + +.. cfgcmd:: set firewall flowtable ... + + Configure firewall flowtables for stateful connection tracking and rules. + For detailed information, see + :doc:`Flowtables Firewall Configuration </configuration/firewall/flowtables>` + . + +.. cfgcmd:: set firewall global-options ... + + Configure global firewall options such as ``all-ping``, ``broadcast-ping``, + ``syn-cookies``, and other system-wide firewall settings. For detailed + information, see + :doc:`Global Firewall Options</configuration/firewall/global-options>`. + +.. cfgcmd:: set firewall group ... + + Organize firewall rules by creating reusable address, network, interface, + MAC, port, and domain groups. Use groups in multiple rules to simplify + configuration and maintenance. For detailed information, see + :doc:`Firewall Groups</configuration/firewall/groups>`. + +.. cfgcmd:: set firewall ipv4 ... + + Configure IPv4-specific firewall rules. For detailed information, see + :doc:`IPv4 Firewall Configuration</configuration/firewall/ipv4>`. + +.. cfgcmd:: set firewall ipv6 ... + + Configure IPv6-specific firewall rules. For detailed information, see + :doc:`IPv6 Firewall Configuration</configuration/firewall/ipv6>`. + +.. cfgcmd:: set firewall zone ... + + Configure zone-based firewall policies for controlling traffic between + different network zones. For detailed information, see + :doc:`Zone-Based Firewall Configuration</configuration/firewall/zone>`. + +For more information on firewall configuration, see the following pages: .. toctree:: :maxdepth: 1 @@ -196,31 +235,32 @@ configuration: ipv6 flowtables -.. note:: **For more information** - of Netfilter hooks and Linux networking packet flows can be - found in `Netfilter-Hooks +.. note:: + For more information on Netfilter hooks and Linux networking packet flows, + see the `Netfilter-Hooks <https://wiki.nftables.org/wiki-nftables/index.php/Netfilter_hooks>`_ + documentation. -Zone-based firewall +Zone-Based firewall ^^^^^^^^^^^^^^^^^^^ + .. toctree:: :maxdepth: 1 :includehidden: zone -With zone-based firewalls a new concept was implemented, in addition to the -standard in and out traffic flows, a local flow was added. This local flow was -for traffic originating and destined to the router itself. Which means that -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. +With zone-based firewalls, a new concept applies. In addition to the standard +in and out traffic flows, a local flow enables traffic originating from and +destined to the router itself. This means you must configure additional rules to +secure the firewall from the network, in addition to the existing inbound and +outbound rules. -To configure VyOS with the -:doc:`zone-based firewall configuration </configuration/firewall/zone>` +To configure VyOS with zone-based firewall, see +:doc:`Zone-Based Firewall Configuration </configuration/firewall/zone>`. -As the example image below shows, the device now needs rules to allow/block +As the following example image shows, you must configure rules to allow or block traffic to or from the services running on the device that have open connections on that interface. diff --git a/docs/configuration/firewall/ipv4.rst b/docs/configuration/firewall/ipv4.rst index 4d54a68f..efd0fe18 100644 --- a/docs/configuration/firewall/ipv4.rst +++ b/docs/configuration/firewall/ipv4.rst @@ -1,4 +1,4 @@ -:lastproofread: 2025-02-14 +:lastproofread: 2026-03-30 .. _firewall-ipv4-configuration: @@ -10,16 +10,14 @@ IPv4 Firewall Configuration Overview ******** -In this section there's useful information on all firewall configuration that -can be done regarding IPv4, and appropriate op-mode commands. -Configuration commands covered in this section: +This section provides information on IPv4 firewall configuration and +appropriate operation-mode commands. This section covers the following +configuration commands: .. cfgcmd:: set firewall ipv4 ... -From the main structure defined in -:doc:`Firewall Overview</configuration/firewall/index>` -in this section you can find detailed information only for the next part -of the general structure: +To learn about the general traffic flow in VyOS firewalls, +see :doc:`Firewall </configuration/firewall/index>`. .. code-block:: none @@ -37,8 +35,8 @@ of the general structure: - name + custom_name -First, all traffic is received by the router, and it is processed in the -**prerouting** section. +First, the router receives all traffic and processes it in the **prerouting** +stage. This stage includes: @@ -52,79 +50,78 @@ This stage includes: ``set nat destination ...`` For transit traffic, which is received by the router and forwarded, the base -chain is **forward**. A simplified packet flow diagram for transit traffic is -shown next: +chain is **forward**. The following is a simplified packet flow diagram for +transit traffic: .. figure:: /_static/images/firewall-fwd-packet-flow.* -The base firewall chain to configure filtering rules for transit traffic -is ``set firewall ipv4 forward filter ...``, which happens in stage 5, -highlighted in the color red. +The base firewall chain for configuring filtering rules for transit traffic is +``set firewall ipv4 forward filter ...``, which occurs in stage 5, highlighted +in red. -For traffic towards the router itself, the base chain is **input**, while -traffic originated by the router has the base chain **output**. -A new simplified packet flow diagram is shown next, which shows the path -for traffic destined to the router itself, and traffic generated by the -router (starting from circle number 6): +For traffic to the router itself, the base chain is **input**. For traffic +the router originates, the base chain is **output**. A simplified packet flow +diagram is shown next, which shows the path for traffic destined to the router +itself and traffic the router generates (starting from circle number 6): .. figure:: /_static/images/firewall-input-packet-flow.* -The base chain for traffic towards the router is ``set firewall ipv4 input -filter ...`` +The base chain for traffic towards the router is +``set firewall ipv4 input filter ...`` -And the base chain for traffic generated by the router is ``set firewall ipv4 +The base chain for traffic the router generates is ``set firewall ipv4 output ...``, where two sub-chains are available: **filter** and **raw**: -* **Output Prerouting**: ``set firewall ipv4 output raw ...``. - As described in **Prerouting**, rules defined in this section are - processed before connection tracking subsystem. -* **Output Filter**: ``set firewall ipv4 output filter ...``. Rules defined - in this section are processed after connection tracking subsystem. +* **Output Prerouting**: ``set firewall ipv4 output raw ...``. As described + in **Prerouting**, the system processes rules in this section before the + connection tracking subsystem. +* **Output Filter**: ``set firewall ipv4 output filter ...``. The system + processes rules in this section after the connection tracking subsystem. .. note:: **Important note about default-actions:** - If a default action for any base chain is not defined, then the default - action is set to **accept** for that chain. For custom chains, if the - default action is not defined, then the default-action is set to **drop** + If you do not define a default action for a base chain, the system sets + the default action to **accept** for that chain. For custom chains, if you + do not define a default action, the system sets the default-action to + **drop**. -Custom firewall chains can be created, with commands -``set firewall ipv4 name <name> ...``. In order to use -such custom chain, a rule with **action jump**, and the appropriate **target** -should be defined in a base chain. +You can create custom firewall chains using the following commands: +``set firewall ipv4 name <name> ...``. To use a custom chain, you must define +a rule with the **action jump** and the appropriate **target** in a base +chain. ********************* Firewall - IPv4 Rules ********************* -For firewall filtering, firewall rules need to be created. Each rule is -numbered, has an action to apply if the rule is matched, and the ability -to specify multiple matching criteria. 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. +Each firewall rule has a +number, an action to apply if the rule matches, and the ability to specify +multiple matching criteria. Packets traverse rules numbered 1-999999, so order +is crucial. The system executes the rule action at the first match. Actions ======= -If a rule is defined, then an action must be defined for it. This tells the -firewall what to do if all of the criteria defined for that rule match. +If you define a rule, you must define an action for it. The action tells the +firewall what to do if all the criteria you define for that rule are met. -The action can be : +The action can be: - * ``accept``: accept the packet. + * ``accept``: Accept the packet. - * ``continue``: continue parsing next rule. + * ``continue``: Continue parsing the next rule. - * ``drop``: drop the packet. + * ``drop``: Drop the packet. - * ``reject``: reject the packet. + * ``reject``: Reject the packet. - * ``jump``: jump to another custom chain. + * ``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. + * ``synproxy``: Synproxy the packet. .. cfgcmd:: set firewall ipv4 forward filter rule <1-999999> action [accept | continue | drop | jump | queue | reject | return | synproxy] @@ -135,8 +132,8 @@ The action can be : .. 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 the action - is set to jump, then a jump-target is also needed. + This required setting defines the action of the current rule. If you set + the action to jump, you must also specify a jump-target. .. cfgcmd:: set firewall ipv4 forward filter rule <1-999999> jump-target <text> @@ -147,8 +144,8 @@ The action can be : .. 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 - the jump target. + Use this command only when the action is set to ``jump``. Specify the + jump target. .. cfgcmd:: set firewall ipv4 forward filter rule <1-999999> queue <0-65535> @@ -159,8 +156,8 @@ The action can be : .. 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 - the queue target to use. Queue range is also supported. + Use this command only when the action is set to ``queue``. Specify the + queue target to use. Queue range is also supported. .. cfgcmd:: set firewall ipv4 forward filter rule <1-999999> queue-options bypass @@ -171,8 +168,8 @@ The action can be : .. 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 the - packet go through firewall when no userspace software is connected to the + Use this command only when the action is set to ``queue``. Allow the packet + to pass through the firewall when no userspace software is connected to the queue. .. cfgcmd:: set firewall ipv4 forward filter rule <1-999999> @@ -184,11 +181,11 @@ The action can be : .. 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. + Use this command only when the action is set to ``queue``. Distribute + packets between several queues. -Also, **default-action** is an action that takes place whenever a packet does -not match any rule in its chain. For base chains, possible options for +Also, **default-action** is an action that applies when a packet does not +match any rule in its chain. For base chains, possible options for **default-action** are **accept** or **drop**. .. cfgcmd:: set firewall ipv4 forward filter default-action @@ -200,43 +197,44 @@ not match any rule in its chain. For base chains, possible options for .. cfgcmd:: set firewall ipv4 name <name> default-action [accept | drop | jump | queue | reject | return] - This sets the default action of the rule-set if a packet does not match the - criteria of any rule. If default-action is set to ``jump``, then - ``default-jump-target`` is also needed. Note that for base chains, the - default action can only be set to ``accept`` or ``drop``, while on custom - chains, more actions are available. + This command sets the default action of the rule-set if a packet does not + match the criteria of any rule. If you set the default-action to ``jump``, + you must also specify ``default-jump-target``. Note that for base chains, + you can set the default action only to ``accept`` or ``drop``, while on + custom chains, more actions are available. .. cfgcmd:: set firewall ipv4 name <name> default-jump-target <text> - To be used only when ``default-action`` is set to ``jump``. Use this - command to specify the jump target for the default rule. + Use this command only when you set ``default-action`` to ``jump``. Specify + the jump target for the default rule. .. note:: **Important note about default-actions:** - If the default action for any base chain is not defined, then the default - action is set to **accept** for that chain. For custom chains if a default - action is not defined then the default-action is set to **drop**. + If you do not define a default action for a base chain, the system sets + the default action to **accept** for that chain. For custom chains, if you + do not define a default action, the system sets the default-action to + **drop**. Firewall Logs ============= -Logging can be enabled for every single firewall rule. If enabled, other -log options can be defined. +You can enable logging for every single firewall rule. If you enable logging, +you can define other log options. .. cfgcmd:: set firewall ipv4 forward filter rule <1-999999> log .. cfgcmd:: set firewall ipv4 input filter rule <1-999999> log .. cfgcmd:: set firewall ipv4 output filter rule <1-999999> log .. cfgcmd:: set firewall ipv4 name <name> rule <1-999999> log - Enable logging for the matched packet. If this configuration command is not - present, then the log is not enabled. + Enable logging for the matched packet. If this command is not present, then + logging is not enabled. .. cfgcmd:: set firewall ipv4 forward filter default-log .. cfgcmd:: set firewall ipv4 input filter default-log .. cfgcmd:: set firewall ipv4 output filter default-log .. cfgcmd:: set firewall ipv4 name <name> default-log - Use this command to enable the logging of the default action on - the specified chain. + Use this command to enable logging of the default action on the specified + chain. .. cfgcmd:: set firewall ipv4 forward filter rule <1-999999> log-options level [emerg | alert | crit | err | warn | notice @@ -251,7 +249,7 @@ log options can be defined. log-options level [emerg | alert | crit | err | warn | notice | info | debug] - Define log-level. Only applicable if rule log is enabled. + Define the log level. Only applicable if you enable rule logging. .. cfgcmd:: set firewall ipv4 forward filter rule <1-999999> log-options group <0-65535> @@ -262,8 +260,8 @@ log options can be defined. .. cfgcmd:: set firewall ipv4 name <name> rule <1-999999> log-options group <0-65535> - Define the log group to send messages to. Only applicable if rule log is - enabled. + Define the log group to send messages to. Only applicable if you enable rule + logging. .. cfgcmd:: set firewall ipv4 forward filter rule <1-999999> log-options snapshot-length <0-9000> @@ -275,7 +273,7 @@ log options can be defined. log-options snapshot-length <0-9000> Define the length of packet payload to include in a netlink message. Only - applicable if rule log is enabled and log group is defined. + applicable if you enable rule logging and define the log group. .. cfgcmd:: set firewall ipv4 forward filter rule <1-999999> log-options queue-threshold <0-65535> @@ -287,17 +285,18 @@ log options can be defined. log-options queue-threshold <0-65535> Define the number of packets to queue inside the kernel before sending them - to userspace. Only applicable if rule log is enabled and log group is defined. + to userspace. Only applicable if you enable rule logging and define the log + group. Firewall Description ==================== -For reference, a description can be defined for every single rule, and for -every defined custom chain. +You can add a description for reference for every single rule and for every +defined custom chain. .. cfgcmd:: set firewall ipv4 name <name> description <text> - Provide a rule-set description to a custom firewall chain. + Provide a rule-set description for a custom firewall chain. .. cfgcmd:: set firewall ipv4 forward filter rule <1-999999> description <text> @@ -312,15 +311,15 @@ every defined custom chain. Rule Status =========== -When defining a rule, it is enabled by default. In some cases, it is useful to -just disable the rule, rather than removing it. +When you define a rule, it is enabled by default. In some cases, it is useful +to disable the rule rather than removing it. .. cfgcmd:: set firewall ipv4 forward filter rule <1-999999> disable .. cfgcmd:: set firewall ipv4 input filter rule <1-999999> disable .. cfgcmd:: set firewall ipv4 output filter rule <1-999999> disable .. cfgcmd:: set firewall ipv4 name <name> rule <1-999999> disable - Command for disabling a rule but keep it in the configuration. + Command for disabling a rule but keeping it in the configuration. Matching criteria ================= @@ -727,9 +726,9 @@ geoip) to keep database and rules updated. .. cfgcmd:: set firewall ipv4 name <name> rule <1-999999> inbound-interface name <iface> - Match based on inbound interface. Wildcard ``*`` can be used. - For example: ``eth2*``. Prepending the character ``!`` to invert the - criteria to match is also supported. For example ``!eth2`` + Match based on inbound interface. Wildcard ``*`` is supported. For example: + ``eth2*``. Prepend the character ``!`` to invert the criteria. For example: + ``!eth2`` .. note:: If an interface is attached to a non-default vrf, when using **inbound-interface**, the vrf name must be used. For example ``set firewall @@ -742,8 +741,8 @@ geoip) to keep database and rules updated. .. cfgcmd:: set firewall ipv4 name <name> rule <1-999999> inbound-interface group <iface_group> - Match based on the inbound interface group. Prepending the character ``!`` - to invert the criteria to match is also supported. For example ``!IFACE_GROUP`` + Match based on the inbound interface group. Prepend the character ``!`` to + invert the criteria. For example, ``!IFACE_GROUP`` .. cfgcmd:: set firewall ipv4 forward filter rule <1-999999> outbound-interface name <iface> @@ -752,9 +751,9 @@ geoip) to keep database and rules updated. .. cfgcmd:: set firewall ipv4 name <name> rule <1-999999> outbound-interface name <iface> - Match based on outbound interface. Wildcard ``*`` can be used. - For example: ``eth2*``. Prepending the character ``!`` to invert the - criteria to match is also supported. For example ``!eth2`` + Match based on outbound interface. Wildcard ``*`` is supported. For example: + ``eth2*``. Prepend the character ``!`` to invert the criteria. For example: + ``!eth2`` .. note:: If an interface is attached to a non-default vrf, when using **outbound-interface**, the real interface name must be used. For example @@ -767,8 +766,8 @@ geoip) to keep database and rules updated. .. cfgcmd:: set firewall ipv4 name <name> rule <1-999999> outbound-interface group <iface_group> - Match based on outbound interface group. Prepending the character ``!`` to - invert the criteria to match is also supported. For example ``!IFACE_GROUP`` + Match based on outbound interface group. Prepend the character ``!`` to + invert the criteria. For example: ``!IFACE_GROUP`` .. cfgcmd:: set firewall ipv4 forward filter rule <1-999999> ipsec [match-ipsec-in | match-ipsec-out | match-none-in | match-none-out] @@ -801,8 +800,8 @@ geoip) to keep database and rules updated. .. 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** + Specify the maximum average rate as **integer/unit**. For example: + **5/minutes** .. cfgcmd:: set firewall ipv4 forward filter rule <1-999999> packet-length <text> @@ -822,8 +821,8 @@ geoip) to keep database and rules updated. .. cfgcmd:: set firewall ipv4 name <name> rule <1-999999> packet-length-exclude <text> - Match based on the packet length. Multiple values from 1 to 65535 - and ranges are supported. + Match based on packet length. Specify multiple values from 1 to 65535 and + ranges. .. cfgcmd:: set firewall ipv4 forward filter rule <1-999999> packet-type [broadcast | host | multicast | other] @@ -846,13 +845,13 @@ geoip) to keep database and rules updated. protocol [<text> | <0-255> | all | tcp_udp] Match based on protocol number or name as 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. + Special names are ``all`` for all protocols and ``tcp_udp`` for TCP and UDP + based packets. The ``!`` character negates the selected protocol. .. code-block:: none - set firewall ipv4 forward fitler rule 10 protocol tcp_udp - set firewall ipv4 forward fitler rule 11 protocol !tcp_udp + set firewall ipv4 forward filter rule 10 protocol tcp_udp + set firewall ipv4 forward filter rule 11 protocol !tcp_udp .. cfgcmd:: set firewall ipv4 forward filter rule <1-999999> recent count <1-255> @@ -883,9 +882,9 @@ geoip) to keep database and rules updated. .. 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. + Specify TCP flags. Allowed values are ``ack``, ``cwr``, ``ecn``, ``fin``, + ``psh``, ``rst``, ``syn``, and ``urg``. Specify multiple values, and use + ``not`` for inverted selection, as shown in the example. .. code-block:: none @@ -956,8 +955,8 @@ geoip) to keep database and rules updated. .. cfgcmd:: set firewall ipv4 name <name> rule <1-999999> ttl <eq | gt | lt> <0-255> - Match the time to live parameter, where 'eq' stands for 'equal'; 'gt' stands - for 'greater than', and 'lt' stands for 'less than'. + Match the time to live parameter, where 'eq' means 'equal', 'gt' means + 'greater than', and 'lt' means 'less than'. .. cfgcmd:: set firewall ipv4 forward filter rule <1-999999> recent count <1-255> @@ -977,14 +976,14 @@ geoip) to keep database and rules updated. .. 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. + Match when 'count' amount of connections appear within 'time'. Use these + matching criteria to block brute-force attempts. Packet Modifications ==================== Starting from **VyOS-1.5-rolling-202410060007**, the firewall can modify -packets before they are sent out. This feaure provides more flexibility in +packets before sending them out. This feature provides more flexibility in packet handling. .. cfgcmd:: set firewall ipv4 prerouting raw rule <1-999999> @@ -1053,9 +1052,9 @@ 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 + * Traffic must be symmetric. + * Synproxy relies on syncookies and TCP timestamps, ensure these are enabled. + * Disable conntrack loose track option. .. code-block:: none @@ -1085,8 +1084,8 @@ Rule-set overview .. opcmd:: show firewall - This will show you a basic firewall overview, for all rule-sets, and not - only for ipv4 + This will show you a basic firewall overview, for all rule-sets, not + only for IPv4. .. code-block:: none @@ -1140,7 +1139,7 @@ Rule-set overview .. opcmd:: show firewall summary - This will show you a summary of rule-sets and groups + This shows you a summary of rule-sets and groups. .. code-block:: none @@ -1215,7 +1214,7 @@ Rule-set overview filter rule <1-999999> .. opcmd:: show firewall ipv4 name <name> rule <1-999999> - This command will give an overview of a rule in a single rule-set, plus + This command gives an overview of a rule in a single rule-set, plus information for default action. .. code-block:: none @@ -1249,9 +1248,9 @@ Show Firewall log .. opcmd:: show log firewall ipv4 [forward | input | output] filter rule <rule> .. opcmd:: show log firewall ipv4 name <name> rule <rule> - Show the logs of all firewall; show all ipv4 firewall logs; show all logs + 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. + show all logs for particular custom chain; show logs for specific rule-set. Example Partial Config ====================== @@ -1303,4 +1302,4 @@ Update geoip database .. opcmd:: update geoip - Command used to update GeoIP database and firewall sets. + Command to update GeoIP database and firewall sets. diff --git a/docs/configuration/firewall/ipv6.rst b/docs/configuration/firewall/ipv6.rst index 905d0d20..d31ceb6f 100644 --- a/docs/configuration/firewall/ipv6.rst +++ b/docs/configuration/firewall/ipv6.rst @@ -1,4 +1,4 @@ -:lastproofread: 2025-02-14 +:lastproofread: 2026-04-01 .. _firewall-ipv6-configuration: @@ -10,16 +10,15 @@ IPv6 Firewall Configuration Overview ******** -In this section there's useful information on all firewall configuration that -can be done regarding IPv6, and appropriate op-mode commands. -Configuration commands covered in this section: +This section covers useful information about IPv6 firewall configuration and +appropriate operation-mode commands. + +This section describes the following configuration commands: .. cfgcmd:: set firewall ipv6 ... -From the main structure defined in -:doc:`Firewall Overview</configuration/firewall/index>` -in this section you can find detailed information only for the next part -of the general structure: +To learn about the general traffic flow in VyOS firewalls, +see :doc:`Firewall </configuration/firewall/index>`. .. code-block:: none @@ -37,8 +36,8 @@ of the general structure: - name + custom_name -First, all traffic is received by the router, and it is processed in the -**prerouting** section. +The router first receives all traffic and processes it in the **prerouting** +section. This stage includes: @@ -51,61 +50,59 @@ This stage includes: * :doc:`Destination NAT</configuration/nat/nat44>`: commands found under ``set nat66 destination ...`` -For transit traffic, which is received by the router and forwarded, the base -chain is **forward**. A simplified packet flow diagram for transit traffic is -shown next: +For transit traffic that the router receives and forwards, the base chain is +**forward**. The following diagram shows a simplified packet flow for transit +traffic: .. figure:: /_static/images/firewall-fwd-packet-flow.* -The base firewall chain to configure filtering rules for transit traffic -is ``set firewall ipv6 forward filter ...``, which happens in stage 5, -highlighted in the color red. +Use ``set firewall ipv6 forward filter ...`` to configure filtering rules for +transit traffic. This command corresponds to stage 5 and is highlighted in red +in the diagram. -For traffic towards the router itself, the base chain is **input**, while -traffic originated by the router has the base chain **output**. -A new simplified packet flow diagram is shown next, which shows the path -for traffic destined to the router itself, and traffic generated by the +For traffic destined to the router, use the **input** chain. For traffic the +router generates, use the **output** chain. The following diagram shows the +packet flow for traffic destined to the router and traffic generated by the router (starting from circle number 6): .. figure:: /_static/images/firewall-input-packet-flow.* -The base chain for traffic towards the router is ``set firewall ipv6 input -filter ...`` +Use ``set firewall ipv6 input filter ...`` to configure traffic destined to +the router. -And the base chain for traffic generated by the router is ``set firewall ipv6 -output ...``, where two sub-chains are available: **filter** and **raw**: +Use ``set firewall ipv6 output ...`` to configure traffic the router generates. +Two sub-chains are available: **filter** and **raw**: * **Output Prerouting**: ``set firewall ipv6 output raw ...``. - As described in **Prerouting**, rules defined in this section are - processed before connection tracking subsystem. -* **Output Filter**: ``set firewall ipv6 output filter ...``. Rules defined - in this section are processed after connection tracking subsystem. + As described in **Prerouting**, the firewall processes rules in this + section before the connection tracking subsystem. +* **Output Filter**: ``set firewall ipv6 output filter ...``. The firewall + processes rules in this section after the connection tracking subsystem. .. note:: **Important note about default-actions:** - If a default action for any base chain is not defined, then the default - action is set to **accept** for that chain. For custom chains, if the - default action is not defined, then the default-action is set to **drop** + If you do not define a default action for a base chain, the system sets + the default action to **accept** for that chain. For custom chains, if you + do not define a default action, the system sets the default-action to + **drop** -Custom firewall chains can be created, with commands -``set firewall ipv6 name <name> ...``. In order to use -such custom chain, a rule with **action jump**, and the appropriate **target** -should be defined in a base chain. +Create custom firewall chains using the commands +``set firewall ipv6 name <name> ...``. To use the custom chain, define a +rule with **action jump** and the appropriate **target** in a base chain. ****************************** Firewall - IPv6 Rules ****************************** -For firewall filtering, firewall rules need to be created. Each rule is -numbered, has an action to apply if the rule is matched, and the ability -to specify multiple matching criteria. 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. +Create firewall rules for firewall filtering. Each rule is numbered and has +an action to apply when the rule is matched. You can specify multiple matching +criteria. Packets go through rules from 1 - 999999, so order is crucial. The +firewall executes the action of the first matching rule. Actions ======= -If a rule is defined, then an action must be defined for it. This tells the -firewall what to do if all of the criteria defined for that rule match. +If you define a rule, you must define an action for it. The action tells the +firewall what to do when all criteria for that rule are met. The action can be : @@ -135,8 +132,8 @@ The action can be : .. 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 the action - is set to jump, then a jump-target is also needed. + This required setting defines the action of the current rule. If you set + the action to jump, you must also define a jump-target. .. cfgcmd:: set firewall ipv6 forward filter rule <1-999999> jump-target <text> @@ -147,8 +144,8 @@ The action can be : .. 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 - the jump target. + Use this command only when action is set to ``jump``. Specify the jump + target. .. cfgcmd:: set firewall ipv6 forward filter rule <1-999999> queue <0-65535> @@ -159,8 +156,8 @@ The action can be : .. 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 - the queue target to use. Queue range is also supported. + Use this command only when action is set to ``queue``. Specify the queue + target. Queue ranges are also supported. .. cfgcmd:: set firewall ipv6 forward filter rule <1-999999> queue-options bypass @@ -171,9 +168,9 @@ The action can be : .. 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 the - packet go through firewall when no userspace software is connected to the - queue. + Use this command only when action is set to ``queue``. This command allows + the packet to go through the firewall when no userspace software is connected + to the queue. .. cfgcmd:: set firewall ipv6 forward filter rule <1-999999> queue-options fanout @@ -184,8 +181,8 @@ The action can be : .. 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. + Use this command only when action is set to ``queue``. This command + distributes packets among multiple queues. Also, **default-action** is an action that takes place whenever a packet does not match any rule in its chain. For base chains, possible options for @@ -200,11 +197,11 @@ not match any rule in its chain. For base chains, possible options for .. cfgcmd:: set firewall ipv6 name <name> default-action [accept | drop | jump | queue | reject | return] - This sets the default action of the rule-set if a packet does not match the - criteria of any rule. If default-action is set to ``jump``, then - ``default-jump-target`` is also needed. Note that for base chains, the - default action can only be set to ``accept`` or ``drop``, while on custom - chains, more actions are available. + Set the default action of the rule-set if a packet does not match any rule + criteria. If you set default-action to ``jump``, you must also define + ``default-jump-target``. For base chains, you can only set the default + action to ``accept`` or ``drop``. For custom chains, more actions are + available. .. cfgcmd:: set firewall ipv6 name <name> default-jump-target <text> @@ -212,23 +209,24 @@ not match any rule in its chain. For base chains, possible options for command to specify the jump target for the default rule. .. note:: **Important note about default-actions:** - If the default action for any base chain is not defined, then the default - action is set to **accept** for that chain. For custom chains if a default - action is not defined then the default-action is set to **drop**. + If you do not define the default action for a base chain, the system sets + the default action to **accept** for that chain. For custom chains, if you + do not define a default action, the system sets the default-action to + **drop**. Firewall Logs ============= -Logging can be enabled for every single firewall rule. If enabled, other -log options can be defined. +You can enable logging for each firewall rule. When enabled, you can also +define other log options. .. cfgcmd:: set firewall ipv6 forward filter rule <1-999999> log .. cfgcmd:: set firewall ipv6 input filter rule <1-999999> log .. cfgcmd:: set firewall ipv6 output filter rule <1-999999> log .. cfgcmd:: set firewall ipv6 name <name> rule <1-999999> log - Enable logging for the matched packet. If this configuration command is not - present, then the log is not enabled. + Enable logging for matched packets. If this configuration command is not + present, logging is disabled. .. cfgcmd:: set firewall ipv6 forward filter default-log .. cfgcmd:: set firewall ipv6 input filter default-log @@ -275,7 +273,7 @@ log options can be defined. log-options snapshot-length <0-9000> Define the length of packet payload to include in a netlink message. Only - applicable if rule log is enabled and log group is defined. + applicable when rule logging is enabled and log group is defined. .. cfgcmd:: set firewall ipv6 forward filter rule <1-999999> log-options queue-threshold <0-65535> @@ -287,13 +285,13 @@ log options can be defined. log-options queue-threshold <0-65535> Define the number of packets to queue inside the kernel before sending them - to userspace. Only applicable if rule log is enabled and log group is defined. + to userspace. Only applicable when rule logging is enabled and log group is + defined. Firewall Description ==================== -For reference, a description can be defined for every single rule, and for -every defined custom chain. +For reference, you can define descriptions on every rule and custom chain. .. cfgcmd:: set firewall ipv6 name <name> description <text> @@ -312,8 +310,8 @@ every defined custom chain. Rule Status =========== -When defining a rule, it is enabled by default. In some cases, it is useful to -just disable the rule, rather than removing it. +New rules are enabled by default. In some cases, you may want to disable a +rule rather than remove it. .. cfgcmd:: set firewall ipv6 forward filter rule <1-999999> disable .. cfgcmd:: set firewall ipv6 input filter rule <1-999999> disable @@ -336,7 +334,7 @@ There are a lot of matching criteria against which the packet can be tested. .. cfgcmd:: set firewall ipv6 name <name> rule <1-999999> connection-status nat [destination | source] - Match based on nat connection status. + Match packets based on NAT connection status. .. cfgcmd:: set firewall ipv6 forward filter rule <1-999999> connection-mark <1-2147483647> @@ -347,7 +345,7 @@ There are a lot of matching criteria against which the packet can be tested. .. cfgcmd:: set firewall ipv6 name <name> rule <1-999999> connection-mark <1-2147483647> - Match based on connection mark. + Match packets based on connection mark. .. cfgcmd:: set firewall ipv6 forward filter rule <1-999999> source address [address | addressrange | CIDR] @@ -367,8 +365,8 @@ There are a lot of matching criteria against which the packet can be tested. .. cfgcmd:: set firewall ipv6 name <name> rule <1-999999> destination address [address | addressrange | CIDR] - Match 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. + Match based on source or destination address. This is similar to network + groups, but you can negate the matching addresses here. .. code-block:: none @@ -392,15 +390,14 @@ There are a lot of matching criteria against which the packet can be tested. .. 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>`_) + Apply an arbitrary netmask to mask addresses and match only a specific + portion. This is useful for IPv6 because rules remain valid when the IPv6 + prefix changes if the host portion of the system's IPv6 address is static. + Examples include SLAAC and `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. + This function works for both individual addresses and address groups. .. stop_vyoslinter .. code-block:: none @@ -433,8 +430,8 @@ There are a lot of matching criteria against which the packet can be tested. .. cfgcmd:: set firewall ipv6 name <name> rule <1-999999> destination fqdn <fqdn> - Specify a Fully Qualified Domain Name as source/destination to match. Ensure - that the router is able to resolve this dns query. + Specify a Fully Qualified Domain Name as source or destination to match. + Ensure that the router can resolve the DNS query. .. cfgcmd:: set firewall ipv6 forward filter rule <1-999999> source geoip country-code <country> @@ -472,14 +469,16 @@ There are a lot of matching criteria against which the packet can be tested. .. 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. + Match IP addresses based on their geolocation. For more information, see + `GeoIP matching <https://wiki.nftables.org/wiki-nftables/index.php/GeoIP_ + matching>`_. Use inverse-match to match anything except the specified + country codes. -Data is provided by DB-IP.com under CC-BY-4.0 license. Attribution required, -permits redistribution so we can include a database in images(~3MB -compressed). Includes cron script (manually callable by op-mode update -geoip) to keep database and rules updated. +DB-IP.com provides data under CC-BY-4.0 license. Attribution is required and +redistribution is permitted, allowing VyOS to include a database in images +(approximately 3 MB compressed). The package includes a cron script that you +can manually call through op-mode update geoip to keep the database and rules +updated. .. cfgcmd:: set firewall ipv6 forward filter rule <1-999999> @@ -491,7 +490,7 @@ geoip) to keep database and rules updated. .. cfgcmd:: set firewall ipv6 name <name> rule <1-999999> source mac-address <mac-address> - You can only specify a source mac-address to match. + You can specify only a source MAC address to match. .. code-block:: none @@ -516,7 +515,7 @@ geoip) to keep database and rules updated. .. cfgcmd:: set firewall ipv6 name <name> rule <1-999999> destination port [1-65535 | portname | start-end] - A port can be set by number or name as defined in ``/etc/services``. + Specify a port by number or by name as defined in ``/etc/services``. .. code-block:: none @@ -549,8 +548,8 @@ geoip) to keep database and rules updated. .. cfgcmd:: set firewall ipv6 name <name> rule <1-999999> destination group address-group <name | !name> - Use a specific address-group. Prepending the character ``!`` to invert the - criteria to match is also supported. + Specify an address group. You can prepend the character ``!`` to invert the + matching criteria. .. cfgcmd:: set firewall ipv6 forward filter rule <1-999999> source group dynamic-address-group <name | !name> @@ -570,8 +569,8 @@ geoip) to keep database and rules updated. .. cfgcmd:: set firewall ipv6 name <name> rule <1-999999> destination group dynamic-address-group <name | !name> - Use a specific dynamic-address-group. Prepending the character ``!`` to - invert the criteria to match is also supported. + Specify a dynamic address group. You can prepend the character ``!`` to + invert the matching criteria. .. cfgcmd:: set firewall ipv6 forward filter rule <1-999999> source group network-group <name | !name> @@ -591,8 +590,8 @@ geoip) to keep database and rules updated. .. cfgcmd:: set firewall ipv6 name <name> rule <1-999999> destination group network-group <name | !name> - Use a specific network-group. Prepending the character ``!`` to invert the - criteria to match is also supported. + Specify a network group. You can prepend the character ``!`` to invert the + matching criteria. .. cfgcmd:: set firewall ipv6 forward filter rule <1-999999> source group port-group <name | !name> @@ -612,8 +611,8 @@ geoip) to keep database and rules updated. .. cfgcmd:: set firewall ipv6 name <name> rule <1-999999> destination group port-group <name | !name> - Use a specific port-group. Prepending the character ``!`` to invert the - criteria to match is also supported. + Specify a port group. You can prepend the character ``!`` to invert the + matching criteria. .. cfgcmd:: set firewall ipv6 forward filter rule <1-999999> source group domain-group <name | !name> @@ -633,8 +632,8 @@ geoip) to keep database and rules updated. .. cfgcmd:: set firewall ipv6 name <name> rule <1-999999> destination group domain-group <name | !name> - Use a specific domain-group. Prepending the character ``!`` to invert the - criteria to match is also supported. + Specify a domain group. You can prepend the character ``!`` to invert the + matching criteria. .. cfgcmd:: set firewall ipv6 forward filter rule <1-999999> source group mac-group <name | !name> @@ -654,8 +653,8 @@ geoip) to keep database and rules updated. .. cfgcmd:: set firewall ipv6 name <name> rule <1-999999> destination group mac-group <name | !name> - Use a specific mac-group. Prepending the character ``!`` to invert the - criteria to match is also supported. + Specify a MAC group. You can prepend the character ``!`` to invert the + matching criteria. .. cfgcmd:: set firewall ipv6 forward filter rule <1-999999> dscp [0-63 | start-end] @@ -686,7 +685,7 @@ geoip) to keep database and rules updated. .. cfgcmd:: set firewall ipv6 name <name> rule <1-999999> fragment [match-frag | match-non-frag] - Match based on fragmentation. + Match packets based on fragmentation. .. cfgcmd:: set firewall ipv6 forward filter rule <1-999999> icmpv6 [code | type] <0-255> @@ -697,7 +696,7 @@ geoip) to keep database and rules updated. .. cfgcmd:: set firewall ipv6 name <name> rule <1-999999> icmpv6 [code | type] <0-255> - Match based on icmp|icmpv6 code and type. + Match packets based on ICMP or ICMPv6 code and type. .. cfgcmd:: set firewall ipv6 forward filter rule <1-999999> icmpv6 type-name <text> @@ -708,8 +707,8 @@ geoip) to keep database and rules updated. .. cfgcmd:: set firewall ipv6 name <name> rule <1-999999> icmpv6 type-name <text> - Match based on icmpv6 type-name. Use tab for information - about what **type-name** criteria are supported. + Match based on ICMPv6 type-name. Press **Tab** for information about + supported **type-name** criteria. .. cfgcmd:: set firewall ipv6 forward filter rule <1-999999> inbound-interface name <iface> @@ -718,13 +717,13 @@ geoip) to keep database and rules updated. .. cfgcmd:: set firewall ipv6 name <name> rule <1-999999> inbound-interface name <iface> - Match based on inbound interface. Wildcard ``*`` can be used. - For example: ``eth2*``. Prepending the character ``!`` to invert the - criteria to match is also supported. For example ``!eth2`` + Match based on inbound interface. You can use the wildcard ``*``. For + example: ``eth2*``. You can prepend the character ``!`` to invert the + matching criteria. For example ``!eth2`` -.. note:: If an interface is attached to a non-default vrf, when using - **inbound-interface**, the vrf name must be used. For example ``set firewall - ipv6 forward filter rule 10 inbound-interface name MGMT`` +.. note:: If an interface is attached to a non-default VRF, when using + **inbound-interface**, use the VRF name. For example: + ``set firewall ipv6 forward filter rule 10 inbound-interface name MGMT`` .. cfgcmd:: set firewall ipv6 forward filter rule <1-999999> inbound-interface group <iface_group> @@ -733,8 +732,8 @@ geoip) to keep database and rules updated. .. cfgcmd:: set firewall ipv6 name <name> rule <1-999999> inbound-interface group <iface_group> - Match based on the inbound interface group. Prepending the character ``!`` - to invert the criteria to match is also supported. For example ``!IFACE_GROUP`` + Match based on the inbound interface group. You can prepend the character + ``!`` to invert the matching criteria. For example ``!IFACE_GROUP`` .. cfgcmd:: set firewall ipv6 forward filter rule <1-999999> outbound-interface name <iface> @@ -743,12 +742,12 @@ geoip) to keep database and rules updated. .. cfgcmd:: set firewall ipv6 name <name> rule <1-999999> outbound-interface name <iface> - Match based on outbound interface. Wildcard ``*`` can be used. - For example: ``eth2*``. Prepending the character ``!`` to invert the - criteria to match is also supported. For example ``!eth2`` + Match based on outbound interface. You can use the wildcard ``*``. For + example: ``eth2*``. You can prepend the character ``!`` to invert the + matching criteria. For example ``!eth2`` -.. note:: If an interface is attached to a non-default vrf, when using - **outbound-interface**, the real interface name must be used. For example +.. note:: If an interface is attached to a non-default VRF, when using + **outbound-interface**, use the physical interface name. For example: ``set firewall ipv6 forward filter rule 10 outbound-interface name eth0`` .. cfgcmd:: set firewall ipv6 forward filter rule <1-999999> @@ -758,8 +757,8 @@ geoip) to keep database and rules updated. .. cfgcmd:: set firewall ipv6 name <name> rule <1-999999> outbound-interface group <iface_group> - Match based on outbound interface group. Prepending the character ``!`` to - invert the criteria to match is also supported. For example ``!IFACE_GROUP`` + Match based on outbound interface group. You can prepend the character ``!`` + to invert the matching criteria. For example ``!IFACE_GROUP`` .. cfgcmd:: set firewall ipv6 forward filter rule <1-999999> ipsec [match-ipsec-in | match-ipsec-out | match-none-in | match-none-out] @@ -770,7 +769,7 @@ geoip) to keep database and rules updated. .. cfgcmd:: set firewall ipv6 name <name> rule <1-999999> ipsec [match-ipsec-in | match-ipsec-out | match-none-in | match-none-out] - Match based on ipsec. + Match packets based on IPsec. .. cfgcmd:: set firewall ipv6 forward filter rule <1-999999> limit burst <0-4294967295> @@ -781,7 +780,8 @@ geoip) to keep database and rules updated. .. 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. + Match based on the maximum number of packets allowed to exceed the rate + limit. .. cfgcmd:: set firewall ipv6 forward filter rule <1-999999> limit rate <text> @@ -792,8 +792,8 @@ geoip) to keep database and rules updated. .. 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** + Match based on the maximum average rate, specified as ``integer/unit``. + For example, specify ``5/minutes``. .. cfgcmd:: set firewall ipv6 forward filter rule <1-999999> packet-length <text> @@ -813,8 +813,8 @@ geoip) to keep database and rules updated. .. cfgcmd:: set firewall ipv6 name <name> rule <1-999999> packet-length-exclude <text> - Match based on the packet length. Multiple values from 1 to 65535 - and ranges are supported. + Match based on packet length. You can specify multiple values from 1 to + 65535 and ranges. .. cfgcmd:: set firewall ipv6 forward filter rule <1-999999> packet-type [broadcast | host | multicast | other] @@ -825,7 +825,7 @@ geoip) to keep database and rules updated. .. cfgcmd:: set firewall ipv6 name <name> rule <1-999999> packet-type [broadcast | host | multicast | other] - Match based on the packet type. + Match based on packet type. .. cfgcmd:: set firewall ipv6 forward filter rule <1-999999> protocol [<text> | <0-255> | all | tcp_udp] @@ -837,8 +837,8 @@ geoip) to keep database and rules updated. protocol [<text> | <0-255> | all | tcp_udp] Match based on protocol number or name as 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. + Specify ``all`` for all protocols and ``tcp_udp`` for TCP and UDP packets. + Prepend ``!`` to negate the protocol selection. .. code-block:: none @@ -862,7 +862,7 @@ geoip) to keep database and rules updated. .. cfgcmd:: set firewall ipv6 name <name> rule <1-999999> recent time [second | minute | hour] - Match bases on recently seen sources. + Match packets based on recently seen sources. .. cfgcmd:: set firewall ipv6 forward filter rule <1-999999> tcp flags [not] <text> @@ -873,9 +873,9 @@ geoip) to keep database and rules updated. .. 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. + Allowed values for TCP flags: ``ack``, ``cwr``, ``ecn``, ``fin``, ``psh``, + ``rst``, ``syn``, and ``urg``. You can specify multiple values. To invert + the selection, use ``not``, as shown in the following example. .. code-block:: none @@ -892,7 +892,7 @@ geoip) to keep database and rules updated. .. cfgcmd:: set firewall ipv6 name <name> rule <1-999999> state [established | invalid | new | related] - Match against the state of a packet. + Match based on packet state. .. cfgcmd:: set firewall ipv6 forward filter rule <1-999999> time startdate <text> @@ -935,7 +935,7 @@ geoip) to keep database and rules updated. .. cfgcmd:: set firewall ipv6 name <name> rule <1-999999> time weekdays <text> - Time to match the defined rule. + Match packets based on time criteria. .. cfgcmd:: set firewall ipv6 forward filter rule <1-999999> hop-limit <eq | gt | lt> <0-255> @@ -946,8 +946,8 @@ geoip) to keep database and rules updated. .. cfgcmd:: set firewall ipv6 name <name> rule <1-999999> hop-limit <eq | gt | lt> <0-255> - Match the hop-limit parameter, where 'eq' stands for 'equal'; 'gt' stands for - 'greater than', and 'lt' stands for 'less than'. + Match the hop-limit parameter. Use ``eq`` for equal, ``gt`` for greater than, + and ``lt`` for less than. .. cfgcmd:: set firewall ipv6 forward filter rule <1-999999> recent count <1-255> @@ -967,15 +967,14 @@ geoip) to keep database and rules updated. .. 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. + Match when the specified number of connections occur within the specified + time period. Use these criteria to block brute-force attempts. Packet Modifications ==================== -Starting from **VyOS-1.5-rolling-202410060007**, the firewall can modify -packets before they are sent out. This feaure provides more flexibility in -packet handling. +The firewall can modify packets before sending them. +This feature provides more flexibility for packet handling. .. cfgcmd:: set firewall ipv6 prerouting raw rule <1-999999> set dscp <0-63> @@ -1032,12 +1031,12 @@ Synproxy connections .. cfgcmd:: set firewall ipv6 [input | forward] filter rule <1-999999> synproxy tcp mss <501-65535> - Set the TCP-MSS (maximum segment size) for the connection + Set the TCP MSS (maximum segment size) for the connection. .. 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 + Set the window scale factor for TCP window scaling. Example synproxy ================ @@ -1075,8 +1074,7 @@ Rule-set overview .. opcmd:: show firewall - This will show you a basic firewall overview, for all rule-sets, and not - only for ipv6 + Show a basic firewall overview for all rule-sets, not only for IPv6: .. code-block:: none @@ -1224,8 +1222,8 @@ Rule-set overview .. opcmd:: show firewall group <name> - Overview of defined groups. You see the type, the members, and where the - group is used. + Show an overview of defined groups, including the type, members, and where + the group is used. .. code-block:: none @@ -1242,7 +1240,7 @@ Rule-set overview .. opcmd:: show firewall statistics - This will show you statistics of all rule-sets since the last boot. + Show statistics of all rule-sets since the last boot. Show Firewall log ================= @@ -1255,9 +1253,8 @@ Show Firewall log .. opcmd:: show log firewall ipv6 [forward | input | output] filter rule <rule> .. 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. + Show firewall logs for all firewalls, all IPv6 firewalls, specific hooks, + specific priorities, specific custom chains, or specific rule-sets. Example Partial Config ====================== diff --git a/docs/configuration/firewall/zone.rst b/docs/configuration/firewall/zone.rst index fde6c162..f3b12473 100644 --- a/docs/configuration/firewall/zone.rst +++ b/docs/configuration/firewall/zone.rst @@ -1,34 +1,27 @@ -:lastproofread: 2024-07-03 +:lastproofread: 2026-03-30 .. _firewall-zone: ################### -Zone Based Firewall +Zone-Based Firewall ################### ******** Overview ******** -.. note:: Starting from VyOS 1.4-rolling-202308040557, a new firewall - structure can be found on all VyOS installations. The 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 have 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. +.. note:: + All VyOS versions built after 2023-10-22 (VyOS 1.4 and 1.5) support + this feature. -In this section there's useful information on all firewall configuration that -is needed for the zone-based firewall. -Configuration commands covered in this section: +This section provides information on firewall configuration for the +zone-based firewall. This section covers the following configuration +commands: .. cfgcmd:: set firewall zone ... -From the main structure defined in -:doc:`Firewall Overview</configuration/firewall/index>` -in this section you can find detailed information only for the next part -of the general structure: +To learn about the general traffic flow in VyOS firewalls, +see :doc:`Firewall </configuration/firewall/index>`. .. code-block:: none @@ -37,22 +30,23 @@ of the general structure: - 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. +In zone-based policy, you assign interfaces to zones and apply inspection +policy to traffic moving between zones. The firewall acts on traffic +according to 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 the system subjects traffic 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 a zone member interface and any interface that is - not a zone member. -* You need 2 separate firewalls to define traffic: one for each direction. +* A zone must be configured before you assign an interface to it, and you + can assign an interface to only a single zone. +* All traffic to and from an interface within a zone flows freely. +* Existing policies affect all traffic between zones. +* Traffic cannot flow between a zone member interface and any interface that + is not a zone member. +* You must define 2 separate firewalls to define traffic: one for each + direction. .. note:: In :vytask:`T2199` the syntax of the zone configuration was changed. The zone configuration moved from ``zone-policy zone <name>`` to ``firewall @@ -62,12 +56,13 @@ Key Points: 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-destination zone pairs. +As an alternative to applying policy to an interface directly, you can +create a zone-based firewall to simplify configuration when multiple +interfaces belong to the same security zone. Instead of applying rule-sets +to interfaces, you apply them to source-destination zone pairs. -A basic introduction to zone-based firewalls can be found `here +You can find a basic introduction to zone-based firewalls in the +`VyOS Knowledge Base <https://support.vyos.io/en/kb/articles/a-primer-to-zone-based-firewall>`_, and an example at :ref:`examples-zone-policy`. @@ -80,7 +75,7 @@ The following steps are required to create a zone-based firewall: Define a Zone ============= -To define a zone setup either one with interfaces or the local zone. +To define a zone, set up either one with interfaces or as the local zone. .. cfgcmd:: set firewall zone <name> interface <interface> @@ -89,41 +84,41 @@ To define a zone setup either one with interfaces or the local zone. .. note:: * An interface can only be a member of one zone. - * A zone can have multiple interfaces, with traffic between interfaces in - the same zone subject to the intra-zone-filtering policy (allowed by - default). + * You can have multiple interfaces in a zone. Traffic between + interfaces in the same zone follows the intra-zone-filtering + policy (allowed by default). .. cfgcmd:: set firewall zone <name> local-zone - Define the zone as the local zone, for traffic originating from and destined - to the router itself. + Define the zone as the local zone for traffic that originates from or is + destined to the router itself. .. note:: * A local zone cannot have any member interfaces - * There cannot be multiple local zones + * You cannot have multiple local zones .. cfgcmd:: set firewall zone <name> default-action [drop | reject] - Change the zone default-action, which applies to traffic destined to this - zone that doesn't match any of the source zone rulesets applied. + Modify the zone default-action, which applies to traffic destined to this + zone that does not match any of the source zone rulesets applied. .. cfgcmd:: set firewall zone <name> default-log - Enable logging of packets that hit this zone's default-action (disabled by - default). + Enable logging of packets that match this zone's default-action (disabled + by default). .. cfgcmd:: set firewall zone <name> description - Set a meaningful description. + Add a meaningful description. Defining a Rule-Set ============================= -Zone-based firewall rule-sets are for traffic from a *Source Zone* to a +Zone-based firewall rule-sets define traffic from a *Source Zone* to a *Destination Zone*. -The rule-sets are created as a custom firewall chain using the commands below +You create rule-sets as a custom firewall chain using the commands below (refer to the firewall IPv4/IPv6 sections for the full syntax): * For :ref:`IPv4<configuration/firewall/ipv4:Firewall - IPv4 Rules>`: @@ -131,15 +126,16 @@ The rule-sets are created as a custom firewall chain using the commands below * For :ref:`IPv6<configuration/firewall/ipv6:Firewall - IPv6 Rules>`: ``set firewall ipv6 name <name> ...`` -It can be helpful to name the rule-sets in the format -``<Sourze Zone>-<Destination Zone>-<v4 | v6>`` to make them easily identifiable. +It is helpful to name the rule-sets in the format +``<Source Zone>-<Destination Zone>-<v4 | v6>`` to make them easily +identifiable. Applying a Rule-Set to a Zone ============================= -Once a rule-set has been defined, it can then be applied to the source and -destination zones. The configuration syntax is anchored on the destination -zone, with each of the source zone rule-sets listed against the destination. +After you define a rule-set, apply it to the source and destination zones. +The configuration syntax anchors to the destination zone, with each of the +source zone rule-sets listed against the destination. .. cfgcmd:: set firewall zone <Destination Zone> from <Source Zone> firewall name <ipv4-rule-set-name> @@ -147,7 +143,8 @@ zone, with each of the source zone rule-sets listed against the destination. .. cfgcmd:: set firewall zone <Destination Zone> from <Source Zone> firewall ipv6-name <ipv6-rule-set-name> -It is recommended to create two rule-sets for each source-destination zone pair. +You should create two rule-sets for each source-destination zone +pair. .. code-block:: none @@ -157,10 +154,10 @@ It is recommended to create two rule-sets for each source-destination zone pair. Applying a Default Rule-Set to a Zone ===================================== -When a destination zone shares a common rule-set for multiple source zones or -a complex set of default policies are required, an optional default rule-set -can be applied. The default rule-set applies to all zones that do not have a -rule-set configured as defined in +When a destination zone shares a common rule-set for multiple source zones, +or when you require a complex set of default policies, you can apply an +optional default rule-set. The default rule-set applies to all zones that do +not have a rule-set configured as defined in :ref:`IPv4<configuration/firewall/zone:Applying a Rule-Set to a Zone>` .. cfgcmd:: set firewall zone <Destination Zone> default-firewall name @@ -175,7 +172,7 @@ Operation-mode .. opcmd:: show firewall zone-policy - This will show you a basic summary of the zone configuration. + Display a basic summary of the zone configuration. .. code-block:: none @@ -191,7 +188,7 @@ Operation-mode .. opcmd:: show firewall zone-policy zone <zone> - This will show you a basic summary of a particular zone. + Display a basic summary of a particular zone. .. code-block:: none diff --git a/docs/configuration/highavailability/index.rst b/docs/configuration/highavailability/index.rst index 40465c30..c82391c7 100644 --- a/docs/configuration/highavailability/index.rst +++ b/docs/configuration/highavailability/index.rst @@ -2,8 +2,9 @@ .. _high-availability: +################# High availability -================= +################# VRRP (Virtual Router Redundancy Protocol) provides active/backup redundancy for routers. Every VRRP router has a physical IP/IPv6 address, and a virtual @@ -252,8 +253,12 @@ need to configure it. But if necessary, Gratuitous ARP can be configured in 0 if not defined. +.. stop_vyoslinter + .. cfgcmd:: set high-availability vrrp global-parameters garp master-delay <1-255> +.. start_vyoslinter + .. cfgcmd:: set high-availability vrrp group <name> garp master-delay <1-255> Set delay for second set of gratuitous ARPs after transition to MASTER. @@ -316,37 +321,46 @@ vice versa and can be used to enable or disable certain services, for example. chmod +x /config/scripts/script-name.sh -.. warning:: It is not recommended to change VRRP configuration inside health-check - and transition scripts. +.. warning:: It is not recommended to change VRRP configuration + inside health-check and transition scripts. Health check scripts ^^^^^^^^^^^^^^^^^^^^ -There is the ability to run an arbitrary script at regular intervals according to health-check -parameters. If a script returns 0, it indicates success. If a script returns anything -else, it will indicate that the VRRP instance should enter the FAULT state. +There is the ability to run an arbitrary script at regular intervals +according to health-check parameters. If a script returns 0, it +indicates success. If a script returns anything else, it will indicate +that the VRRP instance should enter the FAULT state. 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: +.. stop_vyoslinter + .. code-block:: none set high-availability vrrp group Foo health-check script /config/scripts/vrrp-check.sh set high-availability vrrp group Foo health-check interval 60 set high-availability vrrp group Foo health-check failure-count 3 +.. start_vyoslinter + 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: +.. stop_vyoslinter + .. code-block:: 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 +.. start_vyoslinter + Transition scripts ^^^^^^^^^^^^^^^^^^ @@ -356,12 +370,16 @@ 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: +.. stop_vyoslinter + .. code-block:: none set high-availability vrrp group Foo transition-script backup "/config/scripts/vrrp-fail.sh Foo" set high-availability vrrp group Foo transition-script fault "/config/scripts/vrrp-fail.sh Foo" set high-availability vrrp group Foo transition-script master "/config/scripts/vrrp-master.sh Foo" +.. start_vyoslinter + To know more about scripting, check the :ref:`command-scripting` section. Virtual-server @@ -401,10 +419,14 @@ Health-check ^^^^^^^^^^^^ Custom health-check script allows checking real-server availability +.. stop_vyoslinter + .. code-block:: none set high-availability virtual-server 203.0.113.1 real-server 192.0.2.11 health-check script <path-to-script> +.. start_vyoslinter + Fwmark ^^^^^^ Firewall mark. It possible to loadbalancing traffic based on ``fwmark`` value @@ -417,10 +439,14 @@ Real server ^^^^^^^^^^^ Real server IP address and port +.. stop_vyoslinter + .. code-block:: none set high-availability virtual-server 203.0.113.1 real-server 192.0.2.11 port '80' +.. start_vyoslinter + Example ^^^^^^^ @@ -432,6 +458,8 @@ protocol TCP is balanced between 2 real servers ``192.0.2.11`` and Real server is auto-excluded if port check with this server fail. +.. stop_vyoslinter + .. code-block:: none set interfaces ethernet eth0 address '203.0.113.11/24' @@ -451,6 +479,7 @@ Real server is auto-excluded if port check with this server fail. 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' +.. start_vyoslinter A firewall mark ``fwmark`` allows using multiple ports for high-availability virtual-server. @@ -460,6 +489,8 @@ 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. +.. stop_vyoslinter + .. code-block:: none set interfaces ethernet eth0 address 'dhcp' @@ -483,6 +514,8 @@ Port "0" is required if multiple ports are used. set nat source rule 100 source address '192.0.2.0/24' set nat source rule 100 translation address 'masquerade' +.. start_vyoslinter + Op-mode check virtual-server status .. code-block:: none diff --git a/docs/configuration/index.rst b/docs/configuration/index.rst index f607d4d7..f86365a9 100644 --- a/docs/configuration/index.rst +++ b/docs/configuration/index.rst @@ -2,7 +2,7 @@ Configuration Guide ################### -The following structure respresent the cli structure. +The following structure represents the CLI structure. .. toctree:: :maxdepth: 1 diff --git a/docs/configuration/interfaces/openvpn-examples.rst b/docs/configuration/interfaces/openvpn-examples.rst index bba04d9c..6e746e46 100644 --- a/docs/configuration/interfaces/openvpn-examples.rst +++ b/docs/configuration/interfaces/openvpn-examples.rst @@ -1,6 +1,10 @@ +############ Site-to-site -============ +############ + +.. TODO:: Convert raw command blocks in this file to cfgcmd/opcmd + directives for command coverage tracking. OpenVPN is popular for client-server setups, but its site-to-site mode is less common and often not supported by router appliances. Despite limited support, @@ -29,9 +33,9 @@ In both cases, we will use the following settings: * The ``persistent-tunnel`` directive allows us to configure tunnel-related attributes, such as firewall policy, as we would on any standard network interface. -* If known, the remote router's IP address can be configured using the - ``remote-host`` directive. If unknown, it can be omitted. We assume the remote - router has a dynamic IP address. +* If known, the remote router's IP address can be configured using the + ``remote-host`` directive. If unknown, it can be omitted. We assume + the remote router has a dynamic IP address. .. figure:: /_static/images/openvpn_site2site_diagram.* @@ -51,6 +55,8 @@ Elliptic Curve (EC) type. In configuration mode, run the following command: certificate to the configuration session's ``pki`` subtree. Review and commit the changes. +.. stop_vyoslinter + .. code-block:: none vyos@vyos# run generate pki certificate self-signed install openvpn-local @@ -82,16 +88,21 @@ the changes. vyos@vyos# commit +.. start_vyoslinter You do **not** need to copy the certificate to the other router. Instead, retrieve its SHA-256 fingerprint. Since OpenVPN currently supports only SHA-256 fingerprints, use the following command: +.. stop_vyoslinter + .. code-block:: 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 +.. start_vyoslinter + .. note:: Certificate names are arbitrary. While ``openvpn-local`` and ``openvpn-remote`` are used here, you may choose any names. @@ -102,6 +113,8 @@ Set up site-to-site OpenVPN Local configuration: +.. stop_vyoslinter + .. code-block:: none Configure the tunnel: @@ -134,6 +147,8 @@ Remote configuration: set interfaces openvpn vtun1 tls peer-fingerprint <local cert fingerprint> # The output of 'run show pki certificate <name> fingerprint sha256 on the local router set interfaces openvpn vtun1 tls role passive +.. start_vyoslinter + Set up pre-shared keys ---------------------- @@ -146,6 +161,8 @@ First, generate a key by running ``run generate pki openvpn shared-secret install <name>`` in configuration mode. You can use any name; in this example, we use ``s2s``. +.. stop_vyoslinter + .. code-block:: none vyos@local# run generate pki openvpn shared-secret install s2s @@ -163,6 +180,8 @@ we use ``s2s``. vyos@local# commit [edit] +.. start_vyoslinter + Next, install the key on the remote router: .. code-block:: none @@ -181,6 +200,8 @@ Set up firewall exceptions To allow OpenVPN traffic to pass through the WAN interface, create a firewall exception: +.. stop_vyoslinter + .. code-block:: none set firewall ipv4 name OUTSIDE_LOCAL rule 10 action 'accept' @@ -193,6 +214,8 @@ exception: set firewall ipv4 name OUTSIDE_LOCAL rule 20 log set firewall ipv4 name OUTSIDE_LOCAL rule 20 protocol 'udp' +.. start_vyoslinter + Apply the OUTSIDE_LOCAL firewall group to the WAN interface and to the input filter for traffic destined for the router itself: @@ -229,6 +252,8 @@ unique ports to each tunnel. Verify OpenVPN status using the show openvpn operational commands. +.. stop_vyoslinter + .. code-block:: none vyos@vyos:~$ show openvpn site-to-site @@ -239,6 +264,7 @@ Verify OpenVPN status using the show openvpn operational commands. ----------- ----------------- ----------- ------------ ---------- ---------- ----------------- N/A 10.110.12.54:1195 N/A N/A 504.0 B 656.0 B N/A +.. start_vyoslinter Server-client ============= @@ -262,6 +288,8 @@ session's PKI subtree. Certificate Authority (CA): +.. stop_vyoslinter + .. code-block:: none vyos@vyos# run generate pki ca install ca-1 @@ -363,6 +391,8 @@ Client certificate: set pki certificate client1 certificate 'MIIDrjCCApagAwIBAgIUPvtffeYTdoOiHxu++wdrjHwwVX4wDQYJKoZIhvcNAQELBQAwVDELMAkGA1UEBhMCR0IxEzARBgNVBAgMClNvbWUtU3RhdGUxEjAQBgNVBAcMCVNvbWUtQ2l0eTENMAsGA1UECgwEVnlPUzENMAsGA1UEAwwEY2EtMTAeFw0yNTA2MTExMTQxMDlaFw0yNjA2MTExMTQxMDlaMFcxCzAJBgNVBAYTAkdCMRMwEQYDVQQIDApTb21lLVN0YXRlMRIwEAYDVQQHDAlTb21lLUNpdHkxDTALBgNVBAoMBFZ5T1MxEDAOBgNVBAMMB2NsaWVudDEwggEiMA0GCSqGSIb3DQEBAQUAA4IBDwAwggEKAoIBAQC9H6E6gm0PfXO1n/WoA9xlg89/bnScLmfztVDn1uyNn8epE6zAi2GWBhtj4ixLllIwLdkJ7L2mF3yUZtA1Q0oYbGIqTbnaZ37JydCygVGnlLT7UX9zfRfS3KebCIvIte7OyCmnUfVfFzdIsp+4LI3S2wX/9Vyn4UBAR8QQNbezRB3XPMk9gzULnuLhmEDP6GVcPq7RzGXoXUMqsCxfEOJBjej0y4ANKH07HGVVrfVRiY+zlGkM4TFjVuZKnEA0BO6dhOA0E+7gsIXsC06UzzatkjsyWHpb2/DOECIifBoYej9DITu8VxyyZmgaINHEn2gGb0LRHO7rvQapc+XZ2z9DAgMBAAGjdTBzMAwGA1UdEwEB/wQCMAAwDgYDVR0PAQH/BAQDAgeAMBMGA1UdJQQMMAoGCCsGAQUFBwMCMB0GA1UdDgQWBBQnUyqEzG+AqZzsdSud5MDqsOxiXTAfBgNVHSMEGDAWgBQAb2W+vsDMn/Li9j9eVbFeu77qbTANBgkqhkiG9w0BAQsFAAOCAQEAplItvZpoX/joG3QREu9tHVKwDTmXB2lwUM5G8iKPgd6D6oOILZMe2KuvWt12dcdEzUCGfJwJJ8M8R2WD0OmcLdFqvM/8UM1hYzUP2BCnFCLtElVD+b4wMlQNpdHqNbdckw8J4MLQlhUgu9rZAZ0XjWCprr+U50bX++vYRw7Un3Ds6ETEvjflm5WAPb2e0V1hhISPl8K+VXO7RAwxy0DHcDuR+YaD+hnNgMsJV3/QwA17Iy8x86RpOgqmesbt0U7e9Rmo81aVgiy/V4OCV7u6bPX03fmZNS8UwwJuRUlxkjO+epHNYB2cnOcjSkUxaIJ9Hv3tMWHQEtbVZsNYSOZozw==' set pki certificate client1 private key 'MIIEvAIBADANBgkqhkiG9w0BAQEFAASCBKYwggSiAgEAAoIBAQC9H6E6gm0PfXO1n/WoA9xlg89/bnScLmfztVDn1uyNn8epE6zAi2GWBhtj4ixLllIwLdkJ7L2mF3yUZtA1Q0oYbGIqTbnaZ37JydCygVGnlLT7UX9zfRfS3KebCIvIte7OyCmnUfVfFzdIsp+4LI3S2wX/9Vyn4UBAR8QQNbezRB3XPMk9gzULnuLhmEDP6GVcPq7RzGXoXUMqsCxfEOJBjej0y4ANKH07HGVVrfVRiY+zlGkM4TFjVuZKnEA0BO6dhOA0E+7gsIXsC06UzzatkjsyWHpb2/DOECIifBoYej9DITu8VxyyZmgaINHEn2gGb0LRHO7rvQapc+XZ2z9DAgMBAAECggEAPS/Fhtt5k2BgFivZW3FcVc+OS0keGwV8hkFsGoXTZIKEIzSFWIn/mX0CUY90C0Rn9MRwiqB4PwssOAsHY6QQjdRK8irRbVK8l2ZeydHC7DfVUdXtKR0YnxTaePML3nTV/TqPF14Rx6EINtHrkLeBbu2DhGsKfhoHIoTVbvUiKLHa2TkGJOkhvjsyMSPKzUXa1AzLmu+UBIhRYpEPHj0SQUUJJnKgIb7mTR2fhJScHcKwsrPq6S8OpChvsYZ6zatgrTFz9tuhD4IjL7NBiYP45BwGaLIaQjph8yAJwwHWoOP+TTj5WYflkW6Uu8F9gC0ve6dPGPNEi2TUdirvAe4LYQKBgQD0UfAPm6tQg8pdkvfMBvYc21fk8zqmgcA4OtvDi60aXuv5jI5+faISvOG2JLuFhKIDOb5ZerzGvkN+LvWgzr9H7YdGZNNtwKgpS/MGqcuuHncTxWBAwYgKhf26a/tqFZRNurJ6GowxDiAcQEc1mWnmdngRa+dvvCwNbXvGVqfVEQKBgQDGKi447TqD76QfvRPn/fRSjM+QE1duk+XorEJ0HHIha5HV9kCrZdV/olGRjDLwPJO6JW7iE2FUsS9SsIrccFE/9P2ZUqfYP2wL5vNO5kAmoLLUl0gwqg1WnBTPJfXeKReTj2uGmOdEuuMPXpL/49hDuPViiE2Q4MGe2Z+oEYN/EwKBgHfQMuTEl2e9qaDn8OM6SrluC5V4fjunh6dLnfgwaCx1fk1702lOnQuJWzsiml9o4raoO6PP4AGqzphz2PsKSJ2ya1NnIJRDFXRjDYQoAn2Z7RViBsja36chfINObxXgDUFtHBdrK3LnFXIlR4aOfHOLh2grvWx7IDNZjIiAeH+xAoGAJlmFZnjqiRv4bDgAQTZRcSRVCvHjSsAOj0++8I+MutEBgSHN9B2aCsBT/tHeDcX7ZNvXsKLFhElh+iO2S+DkqHb2GRT47I2hkFAaqBtBMPiKgz/ftaNDP46nLEuRYHQdXu4zhfHTV+a/CHtqAWGLuddyjaYJNM96SQ6eqjzxcMcCgYAzdxOF2e27hIgo2ttjsROMGqW0/0r/HsKGKPnao7xHQNCAswTnBT+QGugPCe0NXjuxbySP7V1GeWMWF+WV5khtteWerT1/ELAC48NSDpaMxVa4GP8Q/0w6+ZyJty3UGbCYQzZZue81dU+42LUIaVJ4NAc2tYj3jD780udasawS6w==' +.. start_vyoslinter + Manually copy the CA, client certificate, and Diffie-Hellman key to the client device, then commit them before configuring the OpenVPN interface. @@ -408,7 +438,8 @@ connection resets or daemon reloads. Clients are identified by the CN attribute in their SSL certificates. To grant clients access to a specific network behind the router, use the -push-route option to automatically install the appropriate route on each client. +push-route option to automatically install the appropriate route on +each client. .. code-block:: none @@ -448,6 +479,8 @@ Verification Check the tunnel status: +.. stop_vyoslinter + .. code-block:: none vyos@vyos:~$ show openvpn server @@ -456,9 +489,9 @@ Check the tunnel status: Client CN Remote Host Tunnel IP Local Host TX bytes RX bytes Connected Since ----------- ------------------ ----------- ---------------- ---------- ---------- ------------------- - client1 172.110.12.54:33166 10.23.1.10 172.18.201.10:1194 3.4 KB 3.4 KB 2024-06-11 12:07:25 - + client1 172.16.12.54:33166 10.23.1.10 172.18.201.10:1194 3.4 KB 3.4 KB 2024-06-11 12:07:25 +.. start_vyoslinter Server bridge ============= @@ -525,10 +558,14 @@ configuration file. **Best practice:** Store the configuration file in the ``/config`` directory to ensure it is preserved after image updates. +.. stop_vyoslinter + .. code-block:: none set interfaces openvpn vtun0 openvpn-option "--plugin /usr/lib/openvpn/openvpn-auth-ldap.so /config/auth/ldap-auth.config" +.. start_vyoslinter + A sample configuration file is shown below: .. code-block:: none @@ -558,6 +595,8 @@ Active Directory A sample configuration file is shown below: +.. stop_vyoslinter + .. code-block:: none <LDAP> @@ -589,8 +628,11 @@ A sample configuration file is shown below: </Group> </Authorization> -If you only want to check that the user account is enabled and can authenticate -(against the primary group), the following snippet is sufficient: +.. start_vyoslinter + +If you only want to check that the user account is enabled and can +authenticate (against the primary group), the following snippet is +sufficient: .. code-block:: none @@ -609,8 +651,10 @@ If you only want to check that the user account is enabled and can authenticate RequireGroup false </Authorization> -A complete example of an LDAP authentication configuration for OpenVPN is shown -below: +A complete example of an LDAP authentication configuration for OpenVPN +is shown below: + +.. stop_vyoslinter .. code-block:: none @@ -639,7 +683,14 @@ below: } } -For a detailed example, refer to :doc:`OpenVPN with LDAP</configexamples/autotest/OpenVPN_with_LDAP/OpenVPN_with_LDAP>`. +.. start_vyoslinter + +.. stop_vyoslinter + +For a detailed example, refer to +:doc:`OpenVPN with LDAP</configexamples/autotest/OpenVPN_with_LDAP/OpenVPN_with_LDAP>`. + +.. start_vyoslinter Multi-factor authentication =========================== @@ -671,6 +722,8 @@ To display authentication information, use the following command: Example: +.. stop_vyoslinter + .. code-block:: none vyos@vyos:~$ sh interfaces openvpn vtun20 user user1 mfa qrcode @@ -694,6 +747,8 @@ Example: █████████████████████████████████████ █████████████████████████████████████ +.. start_vyoslinter + Scan the QR code to add the user account to Google Authenticator. On the client side, use the generated OTP as the password. @@ -714,6 +769,8 @@ username and password. Server configuration -------------------- +.. stop_vyoslinter + .. code-block:: none set interfaces openvpn vtun10 local-port '1194' @@ -730,6 +787,8 @@ Server configuration set interfaces openvpn vtun10 tls certificate 'srv-1' set interfaces openvpn vtun10 tls dh-params 'dh-1' +.. start_vyoslinter + The /config/auth/check_user.sh example includes two test users: .. code-block:: none @@ -753,10 +812,14 @@ Client configuration Storing the client certificate locally lets you generate the OpenVPN client configuration file. Use the following command: +.. stop_vyoslinter + .. code-block:: none vyos@vyos:~$ generate openvpn client-config interface vtun10 ca ca-1 certificate client1 +.. start_vyoslinter + Copy the output and save it as a .ovpn file. Add the ``auth-user-pass`` directive to the file. This instructs the OpenVPN client to prompt the user for a username and password, which are then sent to the server over the TLS diff --git a/docs/configuration/interfaces/tunnel.rst b/docs/configuration/interfaces/tunnel.rst index 27c47a91..f1376cdf 100644 --- a/docs/configuration/interfaces/tunnel.rst +++ b/docs/configuration/interfaces/tunnel.rst @@ -2,8 +2,9 @@ .. _tunnel-interface: +###### Tunnel -====== +###### Tunnel interfaces are virtual links that transmit encapsulated traffic between private networks or hosts across public infrastructure, such as the Internet. diff --git a/docs/configuration/interfaces/vti.rst b/docs/configuration/interfaces/vti.rst index 1704b9d1..e45c17d9 100644 --- a/docs/configuration/interfaces/vti.rst +++ b/docs/configuration/interfaces/vti.rst @@ -1,17 +1,92 @@ .. _vti-interface: ############################## -VTI - Virtual Tunnel Interface +VTI (virtual tunnel interface) ############################## -Set Virtual Tunnel Interface +:abbr:`VTIs (virtual tunnel interfaces)` let you create secure, encrypted +tunnels between private networks or hosts across public infrastructure, such as +the Internet. They operate alongside an underlying IPsec tunnel, which handles +encapsulation and encryption, while VTIs function exclusively as routing +interfaces. + +************* +Configuration +************* + +Common interface configuration +============================== + +.. cmdinclude:: /_include/interface-address.txt + :var0: vti + :var1: vti0 + +.. cmdinclude:: /_include/interface-description.txt + :var0: vti + :var1: vti0 + +.. cmdinclude:: /_include/interface-disable.txt + :var0: vti + :var1: vti0 + +.. cmdinclude:: /_include/interface-ip.txt + :var0: vti + :var1: vti0 + +.. cmdinclude:: /_include/interface-ipv6.txt + :var0: vti + :var1: vti0 + +.. cmdinclude:: /_include/interface-mtu.txt + :var0: vti + :var1: vti0 + +.. cfgcmd:: set interfaces vti <interface> mirror egress <monitor-interface> + + Configure mirroring of outgoing traffic from the specified VTI to the + designated monitor interface. + +.. cfgcmd:: set interfaces vti <interface> mirror ingress <monitor-interface> + + Configure mirroring of incoming traffic from the specified VTI to the + designated monitor interface. + +.. cfgcmd:: set interfaces vti <interface> redirect <interface> + + Enable redirection of incoming packets to the specified interface. + +.. cmdinclude:: /_include/interface-vrf.txt + :var0: vti + :var1: vti0 + +********* +Operation +********* + +.. opcmd:: show interfaces vti <vtiX> + + Show the operational status and traffic statistics for the specified VTI. + +.. opcmd:: show interfaces vti <vtiX> brief + + Show a brief operational status summary for the specified VTI. + + +******* +Example +******* + +**Configure a VTI** + +Assign IPv4 and IPv6 addresses to the VTI, along with a brief description: .. code-block:: none set interfaces vti vti0 address 192.168.2.249/30 set interfaces vti vti0 address 2001:db8:2::249/64 + set interfaces vti vti0 description "Description" -Results in: +Resulting configuration: .. code-block:: none @@ -22,19 +97,19 @@ Results in: description "Description" } -.. warning:: When using site-to-site IPsec with VTI interfaces, - be sure to disable route autoinstall +.. warning:: When configuring site-to-site IPsec with VTIs, ensure that route + autoinstall is disabled. .. code-block:: 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 +For more information about the IPsec and VTI issue, as well as the +``disable-route-autoinstall`` option, see: +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.
\ No newline at end of file +The root cause of the problem is that VTI tunnels require their traffic +selectors to be set to ``0.0.0.0/0`` for traffic to match the tunnel, even +though routing decisions are based on netfilter marks. Unless route insertion +is explicitly disabled, strongSWAN incorrectly inserts a default route through +the VTI peer address, causing all traffic to be misrouted. diff --git a/docs/configuration/interfaces/wireless.rst b/docs/configuration/interfaces/wireless.rst index e6a29f9a..728783b2 100644 --- a/docs/configuration/interfaces/wireless.rst +++ b/docs/configuration/interfaces/wireless.rst @@ -1,17 +1,14 @@ -:lastproofread: 2024-07-04 +:lastproofread: 2026-03-23 .. _wireless-interface: -######################## -WLAN/WIFI - Wireless LAN -######################## +#################### +Wireless LAN / Wi-Fi +#################### -The :abbr:`WLAN (Wireless LAN)` interface provides 802.11 (a/b/g/n/ac) wireless -support (commonly referred to as Wi-Fi) by means of compatible hardware. If -your hardware supports it, VyOS supports multiple logical wireless interfaces -per physical device. - -There are three modes of operation for a wireless interface: +:abbr:`WLAN (Wireless LAN)` interfaces provide 802.11 (a/b/g/n/ac) wireless +connectivity, referred to as Wi-Fi, and operate in one of the following +modes: * :abbr:`WAP (Wireless Access-Point)` mode provides network access to connecting stations if the physical hardware supports acting as a WAP @@ -22,7 +19,7 @@ There are three modes of operation for a wireless interface: * Monitor mode lets the system passively monitor wireless traffic If the system detects an unconfigured wireless device, it will be automatically -added the configuration tree, specifying any detected settings (for example, +added to the configuration tree, specifying any detected settings (for example, its MAC address) and configured to run in monitor mode. ************* @@ -36,7 +33,7 @@ Common interface configuration :var0: wireless :var1: wlan0 -System Wide configuration +System-wide configuration ========================= .. cfgcmd:: set system wireless country-code <cc> @@ -45,24 +42,20 @@ System Wide configuration to indicate country in which device is operating. This can limit available channels and transmit power. - .. note:: This option is mandatory in Access-Point mode. + .. note:: This option is mandatory in ``access-point`` mode. Wireless options ================ -.. cfgcmd:: set system wireless country-code <cc> - - Country code (ISO/IEC 3166-1). Used to set regulatory domain. Set as needed - to indicate country in which the box is operating. This can limit available - channels and transmit power. - - .. note:: This option is mandatory in Access-Point mode. - .. cfgcmd:: set interfaces wireless <interface> channel <number> - Channel number (IEEE 802.11), for 2.4Ghz (802.11 b/g/n/ax) channels range from - 1-14. On 5Ghz (802.11 a/h/j/n/ac) channels available are 0, 34 to 177. - On 6GHz (802.11 ax) channels range from 1 to 233. + Configure the IEEE 802.11 wireless radio channel for the interface. + Channel allocation depends on the frequency band: + + * **2.4 GHz** (802.11b/g/n/ax): Channels range from 1 to 14. + * **5 GHz** (802.11a/h/j/n/ac/ax): Channels range from 34 to 177. + * **6 GHz** (802.11ax): Channels range from 1 to 233. + * **Automatic channel selection:** 0. .. cfgcmd:: set interfaces wireless <interface> disable-broadcast-ssid @@ -84,7 +77,7 @@ Wireless options By default, this bridging is allowed. -.. cfgcmd:: set interfaces wireless <interface> max-stations +.. cfgcmd:: set interfaces wireless <interface> max-stations <count> 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 @@ -144,9 +137,9 @@ Wireless options 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 + * ``access-point``: Forwards packets between other nodes. + * ``station``: Connects to another :abbr:`AP (Access Point)`. + * ``monitor``: Passively monitors all packets on the frequency/channel. .. cmdinclude:: /_include/interface-per-client-thread.txt :var0: wireless @@ -164,7 +157,8 @@ PPDU HT (High Throughput) capabilities (802.11n) ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - Configuring HT mode options is required when using 802.11n or 802.11ax at 2.4GHz. + Configuring HT mode options is required when using 802.11n or + 802.11ax at 2.4GHz. .. cfgcmd:: set interfaces wireless <interface> capabilities ht 40mhz-incapable @@ -185,12 +179,9 @@ HT (High Throughput) capabilities (802.11n) * ``ht40+`` - Both 20 MHz and 40 MHz with secondary channel above the primary channel - .. note:: There are limits on which channels can be used with HT40- and HT40+. - Following table shows the channels that may be available for HT40- and HT40+ - use per IEEE 802.11n Annex J: - - Depending on the location, not all of these channels may be available for - use! + .. note:: Channel availability for HT40- and HT40+ is limited. The following + table lists channels permitted for HT40- and HT40+ according to IEEE + 802.11n Annex J. Channel availability may vary by location. .. code-block:: none @@ -199,7 +190,7 @@ HT (High Throughput) capabilities (802.11n) 5 GHz 40,48,56,64 36,44,52,60 .. note:: 40 MHz channels may switch their primary and secondary channels if - needed or creation of 40 MHz channel maybe rejected based on overlapping + needed or creation of 40 MHz channel may be rejected based on overlapping BSSes. These changes are done automatically when hostapd is setting up the 40 MHz channel. @@ -250,7 +241,11 @@ HT (High Throughput) capabilities (802.11n) VHT (Very High Throughput) capabilities (802.11ac) ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -.. cfgcmd:: set interfaces wireless <interface> capabilities vht antenna-count +.. stop_vyoslinter + +.. cfgcmd:: set interfaces wireless <interface> capabilities vht antenna-count <count> + +.. start_vyoslinter Number of antennas on this card @@ -352,7 +347,7 @@ HE (High Efficiency) capabilities (802.11ax) single user beamformer * ``single-user-beamformee`` - Support for operation as single user beamformee - * ``multi-user-beamformer`` - Support for operation as single + * ``multi-user-beamformer`` - Support for operation as multi user beamformer .. cfgcmd:: set interfaces wireless <interface> @@ -394,7 +389,7 @@ HE (High Efficiency) capabilities (802.11ax) .. cfgcmd:: set interfaces wireless <interface> capabilities he coding-scheme <number> - This setting configures Spacial Stream and Modulation Coding Scheme + This setting configures Spatial Stream and Modulation Coding Scheme settings for HE mode (HE-MCS). It is usually not needed to set this explicitly, but it might help with some WiFi adapters. @@ -417,10 +412,10 @@ default physical device (``phy0``) is used. set system wireless country-code de set interfaces wireless wlan0 type station set interfaces wireless wlan0 address dhcp - set interfaces wireless wlan0 ssid Test + set interfaces wireless wlan0 ssid 'TEST' set interfaces wireless wlan0 security wpa passphrase '12345678' -Resulting in +Resulting configuration: .. code-block:: none @@ -445,7 +440,7 @@ Security ======== :abbr:`WPA (Wi-Fi Protected Access)`, WPA2 Enterprise and WPA3 Enterprise in -combination with 802.1x based authentication can be used to authenticate +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 @@ -472,7 +467,7 @@ The WAP in this example has the following characteristics: 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 ssid 'Enterprise-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' @@ -480,7 +475,7 @@ The WAP in this example has the following characteristics: .. start_vyoslinter -Resulting in +Resulting configuration: .. code-block:: none @@ -546,7 +541,7 @@ about all wireless interfaces. .. opcmd:: show interfaces wireless detail -Use this command to view operational status and details wireless-specific +Show the operational status and detailed wireless-specific information about all wireless interfaces. .. stop_vyoslinter @@ -688,7 +683,7 @@ The WAP in this example has the following characteristics: set interfaces wireless wlan0 security wpa cipher CCMP set interfaces wireless wlan0 security wpa passphrase '12345678' -Resulting in +Resulting configuration: .. code-block:: none @@ -715,28 +710,29 @@ Resulting in } } -To get it to work as an access point with this configuration you will need -to set up a DHCP server to work with that network. You can - of course - also -bridge the Wireless interface with any configured bridge -(:ref:`bridge-interface`) on the system. +To enable access point functionality, configure a DHCP server for this +interface's network, or add the interface to an existing local bridge +(see :ref:`bridge-interface` for details). -WiFi-6(e) - 802.11ax -==================== +Wi-Fi 6/6E (802.11ax) +===================== -The following examples will show valid configurations for WiFi-6 (2.4GHz) -and WiFi-6e (6GHz) Access-Points with the following characteristics: +The following examples configure Wi-Fi 6 (2.4 GHz) and Wi-Fi 6E (6 GHz) +:abbr:`APs (Access Points)` with the following parameters: -* Network ID (SSID) ``test.ax`` -* WPA passphrase ``super-dooper-secure-passphrase`` -* Use 802.11ax protocol -* Wireless channel ``11`` for 2.4GHz -* Wireless channel ``5`` for 6GHz +* Network ID (SSID): ``test.ax`` +* WPA passphrase: ``super-dooper-secure-passphrase`` +* Protocol: 802.11ax +* Wireless channel for 2.4 GHz: ``11`` +* Wireless channel for 6 GHz: ``5`` -Example Configuration: WiFi-6 at 2.4GHz ---------------------------------------- +Example configuration: Wi-Fi 6 at 2.4 GHz +------------------------------------------ -You may expect real throughputs around 10MBytes/s or higher in crowded areas. +You may expect real throughput around 10 MB/s or higher in crowded areas. + +.. stop_vyoslinter .. code-block:: none @@ -768,7 +764,9 @@ You may expect real throughputs around 10MBytes/s or higher in crowded areas. set interfaces wireless wlan0 type access-point commit -Resulting in +.. start_vyoslinter + +Resulting configuration: .. code-block:: none @@ -824,14 +822,16 @@ Resulting in } } -Example Configuration: WiFi-6e at 6GHz --------------------------------------- +Example configuration: Wi-Fi 6E at 6 GHz +----------------------------------------- -You may expect real throughputs around 50MBytes/s to 150MBytes/s, -depending on obstructions by walls, water, metal or other materials -with high electro-magnetic dampening at 6GHz. Best results are achieved +You may expect real throughput between 50 MB/s and 150 MB/s, depending on +obstructions from walls, water, metal, or other materials +with high electromagnetic damping at 6 GHz. Best results are achieved with the AP being in the same room and in line-of-sight. +.. stop_vyoslinter + .. code-block:: none set system wireless country-code de @@ -841,7 +841,7 @@ with the AP being in the same room and in line-of-sight. set interfaces wireless wlan0 capabilities he beamform single-user-beamformer set interfaces wireless wlan0 capabilities he bss-color 13 set interfaces wireless wlan0 capabilities he channel-set-width 134 - set interfaces wireless wlan0 capabilities he capabilities he center-channel-freq freq-1 15 + set interfaces wireless wlan0 capabilities he center-channel-freq freq-1 15 set interfaces wireless wlan0 channel 5 set interfaces wireless wlan0 description "802.11ax 6GHz" set interfaces wireless wlan0 mode ax @@ -858,7 +858,9 @@ with the AP being in the same room and in line-of-sight. set interfaces wireless wlan0 stationary-ap commit -Resulting in +.. start_vyoslinter + +Resulting configuration: .. code-block:: none @@ -913,8 +915,7 @@ Resulting in 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 +The Intel AX200 card does not work out of the box in AP mode. You can still put this card into AP mode using the following configuration: .. stop_vyoslinter diff --git a/docs/configuration/interfaces/wwan.rst b/docs/configuration/interfaces/wwan.rst index b4b6a9ce..7ab3ac74 100644 --- a/docs/configuration/interfaces/wwan.rst +++ b/docs/configuration/interfaces/wwan.rst @@ -1,15 +1,15 @@ -:lastproofread: 2024-07-04 +:lastproofread: 2026-03-30 .. _wwan-interface: -################################# -WWAN - Wireless Wide-Area-Network -################################# +#### +WWAN +#### -The Wireless Wide-Area-Network interface provides access (through a wireless -modem/wwan) to wireless networks provided by various cellular providers. +:abbr:`WWAN (Wireless Wide Area Network)` interfaces provide access to cellular +networks via a cellular modem or card. -VyOS uses the `interfaces wwan` subsystem for configuration. +Configure these interfaces under the ``interfaces wwan`` node. ************* Configuration @@ -64,14 +64,18 @@ Common interface configuration :var0: wwan :var1: wwan0 -WirelessModem (WWAN) options -============================ +WWAN options +============ .. cfgcmd:: set interfaces wwan <interface> apn <apn> - Every WWAN connection requires an :abbr:`APN (Access Point Name)` which is - used by the client to dial into the ISPs network. This is a mandatory - parameter. Contact your Service Provider for correct APN. + **Configure the** :abbr:`APN (Access Point Name)` **for the WWAN connection.** + + Every WWAN connection requires an :abbr:`APN (Access Point Name)` to connect to + the cellular network. + + This parameter is mandatory. Contact your service provider for the correct + :abbr:`APN (Access Point Name)`. ********* @@ -80,7 +84,8 @@ Operation .. opcmd:: show interfaces wwan <interface> - Show detailed information on given `<interface>` + Show the operational status and traffic statistics for the specified WWAN + interface. .. code-block:: none @@ -99,7 +104,7 @@ Operation .. opcmd:: show interfaces wwan <interface> summary - Show detailed information summary on given `<interface>` + Show WWAN module hardware characteristics and connection information. .. code-block:: none @@ -166,7 +171,7 @@ Operation .. opcmd:: show interfaces wwan <interface> capabilities - Show WWAN module hardware capabilities. + Show WWAN module radio capabilities. .. code-block:: none @@ -181,7 +186,7 @@ Operation .. opcmd:: show interfaces wwan <interface> firmware - Show WWAN module firmware. + Show WWAN module firmware information. .. code-block:: none @@ -208,7 +213,7 @@ Operation .. opcmd:: show interfaces wwan <interface> imsi - Show WWAN module IMSI. + Show the IMSI of the associated SIM card. .. code-block:: none @@ -226,7 +231,7 @@ Operation .. opcmd:: show interfaces wwan <interface> msisdn - Show WWAN module MSISDN. + Show the MSISDN of the associated SIM card. .. code-block:: none @@ -244,7 +249,7 @@ Operation .. opcmd:: show interfaces wwan <interface> signal - Show WWAN module signal strength. + Show signal information for the cellular connection. .. code-block:: none @@ -293,20 +298,20 @@ Operation Example ******* -The following example is based on a Sierra Wireless MC7710 miniPCIe card (only -the form factor in reality it runs UBS) and Deutsche Telekom as ISP. The card -is assembled into a :ref:`pc-engines-apu4`. +The following example shows how to configure a cellular connection using a +Sierra Wireless MC7710 miniPCIe card that operates over USB despite its form +factor. The card is installed in a :ref:`pc-engines-apu4`. .. code-block:: none set interfaces wwan wwan0 apn 'internet.telekom' set interfaces wwan wwan0 address 'dhcp' -***************** -Supported Modules -***************** +****************** +Supported hardware +****************** -The following hardware modules have been tested successfully in an +The following WWAN modules have been successfully tested with a :ref:`pc-engines-apu4` board: * Sierra Wireless AirPrime MC7304 miniPCIe card (LTE) @@ -318,19 +323,18 @@ The following hardware modules have been tested successfully in an * HP LT4120 Snapdragon X5 LTE *************** -Firmware Update +Firmware update *************** -All available WWAN cards have a built-in, reprogrammable firmware. Most vendors -provide regular updates to firmware used in the baseband chip. +WWAN modules include reprogrammable firmware, and most vendors regularly +provide updates for it. -As VyOS makes use of the QMI interface to connect to the WWAN modem cards, the -firmware can be reprogrammed. +Since VyOS communicates with these devices via the QMI interface, you can +update firmware directly within the system using the ``qmi-firmware-update`` +utility. -To update the firmware, VyOS also ships the `qmi-firmware-update` binary. To -upgrade the firmware of an e.g. Sierra Wireless MC7710 module to the firmware -provided in the file ``9999999_9999999_9200_03.05.14.00_00_generic_000.000_001_SPKG_MC.cwe`` -use the following command: +The following example shows how to update the firmware for a Sierra Wireless +MC7710 module using the provided .cwe file. .. code-block:: bash diff --git a/docs/configuration/loadbalancing/haproxy.rst b/docs/configuration/loadbalancing/haproxy.rst index 667ebb95..d742ec18 100644 --- a/docs/configuration/loadbalancing/haproxy.rst +++ b/docs/configuration/loadbalancing/haproxy.rst @@ -1,21 +1,22 @@ +:lastproofread: 2026-04-06 ############# -Haproxy +HAproxy ############# .. include:: /_include/need_improvement.txt -Haproxy is a balancer and proxy server that provides -high-availability, load balancing and proxying for TCP (level 4) -and HTTP-based (level 7) applications. +HAProxy is a load 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 configuration specifies the port to bind to. Backend +configuration defines the load balancing method and specifies the backend +servers. Service ------- @@ -23,7 +24,8 @@ Service .. cfgcmd:: set load-balancing haproxy service <name> listen-address <address> - Set service to bind on IP address, by default listen on any IPv4 and IPv6 + Set the IP address for the service to bind to. By default, the service + listens on all IPv4 and IPv6 addresses. .. cfgcmd:: set load-balancing haproxy service <name> port <port> @@ -43,19 +45,21 @@ Service .. cfgcmd:: set load-balancing haproxy service <name> ssl certificate <name> - Set SSL certificate <name> for service <name>. Multiple certificates could be defined. + Set the SSL certificate <name> for service <name>. You can define + multiple certificates. .. cfgcmd:: set load-balancing haproxy service <name> http-response-headers <header-name> value <header-value> - Set custom HTTP headers to be included in all responses + Set custom HTTP headers to include in all responses. .. cfgcmd:: set load-balancing haproxy service <name> logging facility <facility> level <level> Specify facility and level for logging. - For an explanation on :ref:`syslog_facilities` and :ref:`syslog_severity_level` - see tables in syslog configuration section. + For an explanation on :ref:`syslog_facilities` and + :ref:`syslog_severity_level`, + see tables in the syslog configuration section. .. cfgcmd:: set load-balancing haproxy service <name> timeout client <seconds> @@ -76,9 +80,9 @@ Service 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. +Rules control and route incoming traffic to specific backends based on +predefined conditions. Rules define matching criteria and specify actions +to perform. .. cfgcmd:: set load-balancing haproxy service <name> rule <rule> domain-name <name> @@ -98,15 +102,13 @@ perform action accordingly. .. cfgcmd:: set load-balancing haproxy 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. + Define URL path matching rules for a specific service. Use this command + to specify how to match the URL path 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 + * ``exact`` Matches the URL path exactly. .. cfgcmd:: set load-balancing haproxy service <name> rule <rule> set backend <name> @@ -116,7 +118,7 @@ perform action accordingly. .. cfgcmd:: set load-balancing haproxy service <name> rule <rule> redirect-location <url> - Redirect URL to a new location + Redirect URL to a new location. Backend @@ -125,37 +127,36 @@ Backend .. cfgcmd:: set load-balancing haproxy backend <name> balance <balance> - Load-balancing algorithms to be used for distributed requests among the - available servers + Specify the load balancing algorithm for distributing requests among + available servers. Balance algorithms: * ``source-address`` Distributes requests based on the source IP address - of the client + of the client. * ``round-robin`` Distributes requests in a circular manner, - sequentially sending each request to the next server in line + sequentially sending each request to the next server in line. * ``least-connection`` Distributes requests to the server with the fewest - active connections + active connections. .. cfgcmd:: set load-balancing haproxy backend <name> mode <mode> - Configure backend `<name>` mode TCP or HTTP + Configure backend `<name>` mode TCP or HTTP. .. cfgcmd:: set load-balancing haproxy backend <name> server <name> address <x.x.x.x> - Set the address of the backend server to which the incoming traffic will - be forwarded + Set the address of the backend server that receives incoming traffic. .. cfgcmd:: set load-balancing haproxy backend <name> server <name> port <port> - Set the address of the backend port + Set the address of the backend port. .. cfgcmd:: set load-balancing haproxy backend <name> server <name> check - Active health check backend server + Active health check backend server. .. cfgcmd:: set load-balancing haproxy backend <name> server <name> check port <port> @@ -166,35 +167,36 @@ Backend .. cfgcmd:: set load-balancing haproxy backend <name> server <name> send-proxy - Send a Proxy Protocol version 1 header (text format) + Send a Proxy Protocol version 1 header (text format). .. cfgcmd:: set load-balancing haproxy backend <name> server <name> send-proxy-v2 - Send a Proxy Protocol version 2 header (binary format) + Send a Proxy Protocol version 2 header (binary format). .. cfgcmd:: set load-balancing haproxy backend <name> ssl ca-certificate <ca-certificate> - Configure requests to the backend server to use SSL encryption and - authenticate backend against <ca-certificate> + Use SSL encryption for backend requests and authenticate the backend + against ``<ca-certificate>``. .. cfgcmd:: set load-balancing haproxy backend <name> ssl no-verify - Configure requests to the backend server to use SSL encryption without - validating server certificate + Use SSL encryption for backend requests without validating the server + certificate. .. cfgcmd:: set load-balancing haproxy backend <name> http-response-headers <header-name> value <header-value> - Set custom HTTP headers to be included in all responses using the backend + Set custom HTTP headers to include in all responses from the backend. .. cfgcmd:: set load-balancing haproxy backend <name> logging facility <facility> level <level> Specify facility and level for logging. - For an explanation on :ref:`syslog_facilities` and :ref:`syslog_severity_level` - see tables in syslog configuration section. + For an explanation on :ref:`syslog_facilities` and + :ref:`syslog_severity_level`, + see tables in the :ref:`syslog` configuration section. .. cfgcmd:: set load-balancing haproxy backend <name> timeout check <seconds> @@ -220,7 +222,7 @@ Backend Global ------- -Global parameters +Global configuration parameters: .. cfgcmd:: set load-balancing haproxy global-parameters max-connections <num> @@ -230,7 +232,7 @@ Global parameters .. cfgcmd:: set load-balancing haproxy global-parameters ssl-bind-ciphers <ciphers> - Limit allowed cipher algorithms used during SSL/TLS handshake + Limit the cipher algorithms allowed during SSL/TLS handshake. .. cfgcmd:: set load-balancing haproxy global-parameters tls-version-min <version> @@ -241,7 +243,8 @@ Global parameters facility <facility> level <level> Specify facility and level for logging. - For an explanation on :ref:`syslog_facilities` and :ref:`syslog_severity_level` + For an explanation on :ref:`syslog_facilities` and + :ref:`syslog_severity_level` see tables in syslog configuration section. .. cfgcmd:: set load-balancing haproxy timeout check <seconds> @@ -271,8 +274,8 @@ Health checks HTTP checks ----------- -For web application providing information about their state HTTP health -checks can be used to determine their availability. +Use HTTP health checks to monitor web applications that provide health status +information and determine their availability. .. cfgcmd:: set load-balancing haproxy backend <name> http-check @@ -282,17 +285,17 @@ checks can be used to determine their availability. .. cfgcmd:: set load-balancing haproxy backend <name> http-check method <method> - Sets the HTTP method to be used, can be either: option, get, post, put + Set the HTTP method: ``OPTION``, ``GET``, ``POST``, or ``PUT``. .. cfgcmd:: set load-balancing haproxy backend <name> http-check uri <path> - Sets the endpoint to be used for health checks + Set the endpoint to use for health checks. .. cfgcmd:: set load-balancing haproxy backend <name> http-check expect <condition> - Sets the expected result condition for considering a server healthy. + Set the expected result condition for a server to be considered healthy. Some possible examples are: * ``status 200`` Expecting a 200 response code @@ -303,8 +306,8 @@ checks can be used to determine their availability. 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: +Configure health checks for TCP mode backends. You can configure protocol-aware +checks for a range of Layer 7 protocols: .. cfgcmd:: set load-balancing haproxy backend <name> health-check <protocol> @@ -315,25 +318,23 @@ protocol aware checks for a range of Layer 7 protocols: * ``pgsql`` PostgreSQL protocol check. * ``smtp`` SMTP protocol check. -.. note:: If you specify a server to be checked but do not configure a - protocol, a basic TCP health check will be attempted. A server shall be - deemed online if it responses to a connection attempt with a valid - ``SYN/ACK`` packet. +.. note:: If you specify a server to check but do not configure a + protocol, HAProxy performs a basic TCP health check. A server is online if + it responds to a connection attempt with a valid ``SYN/ACK`` packet. Redirect HTTP to HTTPS ====================== -Configure the load-balancing haproxy service for HTTP. -This configuration listen on port 80 and redirect incoming -requests to HTTPS: +Configure a HAProxy service for HTTP that listens on port 80 and redirects +incoming requests to HTTPS: .. code-block:: none set load-balancing haproxy service http port '80' set load-balancing haproxy service http redirect-http-to-https -The name of the service can be different, in this example it is only for +You can use a different service name; in this example, ``http`` is just for convenience. @@ -343,9 +344,10 @@ 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. +This configuration enables the TCP reverse proxy for the ``my-tcp-api`` +service. Incoming TCP connections on port 8888 are load balanced across the +backend servers (srv01 and srv02) using the round-robin load balancing +algorithm. .. code-block:: none @@ -365,15 +367,15 @@ servers (srv01 and srv02) using the round-robin load-balancing algorithm. Balancing based on domain name ------------------------------ The following configuration demonstrates how to use VyOS -to achieve load balancing based on the domain name. +to achieve load balancing based on the domain name: -The HTTP service listen on TCP port 80. +The HTTP service listens on TCP port 80. -Rule 10 matches requests with the domain name ``node1.example.com`` forwards -to the backend ``bk-api-01`` +Rule 10 matches requests with the domain name ``node1.example.com`` and +forwards them to the backend ``bk-api-01``. -Rule 20 matches requests with the domain name ``node2.example.com`` forwards -to the backend ``bk-api-02`` +Rule 20 matches requests with the domain name ``node2.example.com`` and +forwards them to the backend ``bk-api-02``. .. code-block:: none @@ -398,23 +400,25 @@ to the backend ``bk-api-02`` Terminate SSL ------------- + The following configuration terminates SSL on the router. -The ``http`` service is listens on port 80 and force redirects from HTTP to +The ``http`` service listens on port 80 and redirects HTTP requests 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. +The ``https`` service listens on port 443 with the ``bk-default`` backend +and handles HTTPS traffic using the ``cert`` certificate for SSL termination. +The HSTS header is set with a 1-year expiry to tell browsers to always use +SSL for the site. -Rule 10 matches requests with the exact URL path ``/.well-known/xxx`` -and redirects to location ``/certs/``. +Rule 10 matches requests with the exact URL path ``/.well-known/xxx`` and +redirects them to ``/certs/``. -Rule 20 matches requests with URL paths ending in ``/mail`` or exact -path ``/email/bar`` redirect to location ``/postfix/``. +Rule 20 matches requests with URL paths ending in ``/mail`` or the exact +path ``/email/bar`` and redirects them to ``/postfix/``. -Additional global parameters are set, including the maximum number -connection limit of 4000 and a minimum TLS version of 1.3. +Global parameters include a maximum connection limit of 4000 and a minimum +TLS version of 1.3. .. code-block:: none @@ -447,9 +451,10 @@ connection limit of 4000 and a minimum TLS version of 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 +then re-encrypts the traffic and sends it to the backend server via HTTPS. +Use this when encryption is required for both paths but you do not want to install publicly trusted certificates on each backend server. Backend service certificates are checked against the certificate authority @@ -458,7 +463,7 @@ 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 +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`` @@ -480,7 +485,7 @@ and checks backend server has a valid certificate trusted by CA ``cacert`` Balancing with HTTP health checks --------------------------------- -This configuration enables HTTP health checks on backend servers. +This configuration enables HTTP health checks for backend servers. .. code-block:: none diff --git a/docs/configuration/loadbalancing/index.rst b/docs/configuration/loadbalancing/index.rst index 92dcc622..b87faed2 100644 --- a/docs/configuration/loadbalancing/index.rst +++ b/docs/configuration/loadbalancing/index.rst @@ -1,3 +1,5 @@ +:lastproofread: 2026-04-06 + .. _load-balancing: ############## diff --git a/docs/configuration/loadbalancing/wan.rst b/docs/configuration/loadbalancing/wan.rst index b376f4fb..56fdb02c 100644 --- a/docs/configuration/loadbalancing/wan.rst +++ b/docs/configuration/loadbalancing/wan.rst @@ -1,22 +1,25 @@ -:lastproofread: 2023-01-27 +:lastproofread: 2026-04-06 +################## 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. +.. TODO:: Convert raw command blocks in this file to cfgcmd/opcmd + directives for command coverage tracking. + +The load balancer distributes outbound traffic across two or more +interfaces. If a path fails, the load balancer balances traffic across the +remaining healthy paths. When a path recovers, it is automatically added back +to the routing table. The load balancer adds routes for each path and +distributes traffic based on 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). + * 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): +The following examples uses two DHCP WAN interfaces and one LAN (``eth2``): .. code-block:: none @@ -28,18 +31,18 @@ Let's assume we have two DHCP WAN interfaces and one LAN (eth2): .. note:: - WAN Load Balacing should not be used when dynamic routing protocol is - used/needed. This feature creates customized routing tables and firewall - rules, that makes it incompatible to use with routing protocols. + Do not use WAN load balancing with dynamic routing protocols. This + feature creates customized routing tables and firewall rules that are + incompatible with routing protocols. -Balancing Rules ---------------- +Load 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. +You define interfaces, their weight, and the traffic type to balance in +numbered rule sets. The load balancer executes rules in numerical order +against outgoing packets. When a packet matches a rule, it is sent through the +specified interface. Packets that do not match any rule use the system routing +table. You cannot change rule numbers. Create a load balancing rule, it can be a number between 1 and 9999: @@ -61,23 +64,25 @@ Create a load balancing rule, it can be a number between 1 and 9999: 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. +By default, the load balancer distributes outbound +traffic randomly across available interfaces. You can assign weights to +interfaces to influence the distribution. If ``eth0`` has more bandwidth +than ``eth1``, you can assign a higher weight to ``eth0`` to send more +traffic through it: .. code-block:: 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. +In this example,``eth0`` receives 66% of traffic, and ``eth1`` receives +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: +Set a packet rate limit for a rule to apply it to traffic above or below a +specified threshold. To configure rate limiting, use: .. code-block:: none @@ -88,22 +93,20 @@ below a specified threshold. To configure the rate limiting use: * ``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. +* ``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. +The load balancer balances outgoing traffic by flow. A connection tracking +table tracks flows by source address, destination address, and port. Each +flow is assigned to an interface based on the balancing rules, and subsequent +packets use the same interface. This ensures packets arrive in order when links +have different speeds. -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: +Packet-based balancing can improve balance across interfaces when packet +order is not critical. Enable per-packet balancing for a rule with: .. code-block:: none @@ -112,8 +115,8 @@ balancing rule with: Exclude traffic *************** -To exclude traffic from load balancing, traffic matching an exclude rule is not -balanced but routed through the system routing table instead: +To exclude traffic from load balancing, traffic matching an exclude rule +bypasses load balancing and uses the system routing table instead: .. code-block:: none @@ -123,10 +126,10 @@ balanced but routed through the system routing table instead: 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. +The load balancer periodically checks the health of interfaces and paths by +sending ICMP packets (ping) to remote destinations, performing TTL tests, or +executing a user-defined script. If an interface fails the health check, the +load balancer removes it from its interface pool. To enable health checking for an interface: .. code-block:: none @@ -138,26 +141,26 @@ To enable health checking for an interface: success-count Success count +> test Rule number -Specify nexthop on the path to the destination, ``ipv4-address`` can be set to -``dhcp`` +Specify the nexthop on the path to the destination. You can set +``ipv4-address`` to ``dhcp``. .. code-block:: none set load-balancing wan interface-health <interface> nexthop <ipv4-address> -Set the number of health check failures before an interface is marked as -unavailable, range for number is 1 to 10, default 1. Or set the number of -successful health checks before an interface is added back to the interface -pool, range for number is 1 to 10, default 1. +Set the number of health check failures before the load balancer marks an +interface as unavailable (range 1-10, default 1). Or set the number of +successful health checks before adding an interface back to the pool +(range 1-10, default 1). .. code-block:: none set load-balancing wan interface-health <interface> failure-count <number> set load-balancing wan interface-health <interface> success-count <number> -Each health check is configured in its own test, tests are numbered and -processed in numeric order. For multi target health checking multiple tests -can be defined: +Configure each health check in its own test. Tests are numbered and processed +in numeric order. You can define multiple tests for multi-target health +checking: .. code-block:: none @@ -169,46 +172,45 @@ can be defined: 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 +* ``resp-time``: The maximum response time for ping in seconds. Range + 1-30, default ``5``. +* ``target``: The target to receive ICMP packets. The address can be an IPv4 + address or hostname. +* ``test-script``: A user-defined script must return 0 to succeed and + non-zero to fail. Scripts reside in ``/config/scripts``. For other locations, + provide the full path. +* ``ttl-limit``: For the UDP TTL limit test, specify the hop count limit. + The limit must be shorter than the path length. The test succeeds when an + ICMP time-expired message is returned. Default ``1``. +* ``type``: Specify the test type: ``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: +By default, interfaces in a load balancing pool replace the source IP of +each outgoing packet with their own address to ensure replies arrive on the +same interface. The load balancer handles this through automatically generated +Source NAT (SNAT) rules applied only to balanced traffic. To disable the +automatic generation of SNAT rules when this behavior is not desired, use: .. code-block:: none set load-balancing wan disable-source-nat -Sticky Connections +Sticky connections ------------------ -Inbound connections to a WAN interface can be improperly handled when the reply -is sent back to the client. +Inbound connections to a WAN interface can be improperly handled when +replies are sent back to the client. .. image:: /_static/images/sticky-connections.* :width: 80% :align: center -Upon reception of an incoming packet, when a response is sent, it might be -desired to ensure that it leaves from the same interface as the inbound one. -This can be achieved by enabling sticky connections in the load balancing: +When responding to an incoming packet, you may want to ensure the response +leaves from the same interface as the incoming packet. Enable sticky +connections in the load balancer to do this: .. code-block:: none @@ -217,23 +219,21 @@ This can be achieved by enabling sticky connections in the load balancing: 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: +In failover mode, one interface is primary and other interfaces are +secondary or spare. The load balancer uses only the primary interface. If it +fails, a secondary interface from the available pool takes over. The load +balancer selects the primary interface based on its weight and health. Other +interfaces become secondary. Secondary interfaces are chosen based on their +weight and health. You can also select interface roles based on rule order by +including interfaces in balancing rules and ordering those rules accordingly. +To enable failover mode, create a failover rule: .. code-block:: none set load-balancing wan rule <number> failover -Because existing sessions do not automatically fail over to a new path, -the session table can be flushed on each connection state change: +Existing sessions do not automatically fail over to a new path. Flush the +session table on each connection state change to enable failover: .. code-block:: none @@ -241,14 +241,15 @@ the session table can be flushed on each connection state change: .. warning:: - Flushing the session table will cause other connections to fall back from + Flushing the session table causes other connections to revert from flow-based to packet-based balancing until each flow is reestablished. Script execution ---------------- -A script can be run when an interface state change occurs. Scripts are run -from /config/scripts, for a different location specify the full path: +Run a script when an interface state changes. Scripts run from the +``/config/scripts`` directory. To use a script in another location, +specify the full path: .. code-block:: none @@ -261,19 +262,20 @@ Two environment variables are available: .. warning:: - Blocking call with no timeout. System will become unresponsive if script - does not return! + Blocking call with no timeout: VyOS becomes unresponsive if the + script does not return. Handling and monitoring ----------------------- -Show WAN load balancer information including test types and targets. -A character at the start of each line depicts the state of the test +The following command shows WAN load balancer information including test +types and targets. The character at the start of each line indicates the test +state: -* ``+`` successful -* ``-`` failed -* a blank indicates that no test has been carried out +* ``+`` successful. +* ``-`` failed. +* A blank indicates that no test has been carried out. .. code-block:: none diff --git a/docs/configuration/nat/nat64.rst b/docs/configuration/nat/nat64.rst index e8a3a0e6..04ba56f4 100644 --- a/docs/configuration/nat/nat64.rst +++ b/docs/configuration/nat/nat64.rst @@ -69,6 +69,8 @@ NAT64 client configuration: Test from the IPv6 only client: +.. stop_vyoslinter + .. code-block:: none vyos@r1:~$ ping 64:ff9b::192.0.2.1 count 2 @@ -79,3 +81,5 @@ Test from the IPv6 only client: --- 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 + +.. start_vyoslinter diff --git a/docs/configuration/nat/nat66.rst b/docs/configuration/nat/nat66.rst index 31f6c002..aecce524 100644 --- a/docs/configuration/nat/nat66.rst +++ b/docs/configuration/nat/nat66.rst @@ -4,6 +4,9 @@ NAT66(NPTv6) ############ +.. TODO:: Convert raw command blocks in this file to cfgcmd/opcmd + directives for command coverage tracking. + :abbr:`NPTv6 (IPv6-to-IPv6 Network Prefix Translation)` is an address translation technology based on IPv6 networks, used to convert an IPv6 address prefix in an IPv6 message into another IPv6 address prefix. @@ -151,14 +154,17 @@ R2: 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. +Use the following topology to translate internal user local addresses +(``fc::/7``) to DHCPv6-PD provided prefixes from an ISP connected to +a VyOS HA pair. .. figure:: /_static/images/vyos_1_5_nat66_dhcpv6_wdummy.* :alt: VyOS NAT66 DHCPv6 using a dummy interface Configure both routers (a and b) for DHCPv6-PD via dummy interface: +.. stop_vyoslinter + .. code-block:: none set interfaces dummy dum1 description 'DHCPv6-PD NPT dummy' @@ -169,6 +175,8 @@ Configure both routers (a and b) for DHCPv6-PD via dummy interface: set interfaces bonding bond0 vif 20 dhcpv6-options rapid-commit commit +.. start_vyoslinter + Get the DHCPv6-PD prefixes from both routers: .. code-block:: none diff --git a/docs/configuration/policy/index.rst b/docs/configuration/policy/index.rst index 51f60479..0394eb21 100644 --- a/docs/configuration/policy/index.rst +++ b/docs/configuration/policy/index.rst @@ -1,4 +1,4 @@ -:lastproofread:2021-07-12 +:lastproofread: 2021-07-12 .. include:: /_include/need_improvement.txt diff --git a/docs/configuration/protocols/index.rst b/docs/configuration/protocols/index.rst index f95c1cf6..d40a4b12 100644 --- a/docs/configuration/protocols/index.rst +++ b/docs/configuration/protocols/index.rst @@ -16,6 +16,7 @@ Protocols mpls multicast segment-routing + traffic-engineering openfabric ospf pim diff --git a/docs/configuration/protocols/isis.rst b/docs/configuration/protocols/isis.rst index 0fb0e9e0..75634800 100644 --- a/docs/configuration/protocols/isis.rst +++ b/docs/configuration/protocols/isis.rst @@ -355,6 +355,69 @@ Loop Free Alternate (LFA) This command will limit LFA backup computation up to the specified prefix priority. +Segment Routing over IPv6 (SRv6) +------------------------- + +.. cfgcmd:: set protocols isis segment-routing srv6 interface <interface> + + The :ref:`dummy interface<configuration/interfaces/dummy:dummy>` used + to install SRv6 SIDs into the Linux data plane. The interface must exist and + must be present when configuring IS-IS with + SRv6. + +.. cfgcmd:: set protocols isis segment-routing srv6 locator <locator> + + Specifies the SRv6 locator to use for IS-IS. IS-IS automatically allocates + prefix and adjacency SIDs, creates local SID entries and advertises them + into the IGP domain. + +.. cfgcmd:: set protocols isis segment-routing srv6 node-msd max-end-d <0-255> + + The Maximum End D MSD Type specifies the maximum number of SIDs present in an + SRH when performing decapsulation. As specified in :rfc:`8986`, the permitted + SID types include, but are not limited to, End.DX6, End.DT4, End.DT46, End + with USD, and End.X with USD. + + If the advertised value is zero or no value is advertised, then the router + cannot apply any behavior that results in decapsulation and forwarding of the + inner packet if the outer IPv6 header contains an SRH. + + Reference: :rfc:`9352` + +.. cfgcmd:: set protocols isis segment-routing srv6 node-msd max-end-pop <0-255> + + The Maximum End Pop MSD Type signals the maximum number of SIDs in the SRH to + which the router can apply "Penultimate Segment Pop (PSP) of the SRH" or + "Ultimate Segment Pop (USP) of the SRH" behavior, as defined in "Flavors" + (Section 4.16 of :rfc:`8986`). + + If the advertised value is zero or no value is advertised, then the router + cannot apply PSP or USP flavors. + + Reference: :rfc:`9352` + +.. cfgcmd:: set protocols isis segment-routing srv6 node-msd max-h-encaps <0-255> + + The Maximum H.Encaps MSD Type signals the maximum number of SIDs that can be + added to the segment list of an SRH as part of the "H.Encaps" behavior, as + defined in :rfc:`8986`. + + If the advertised value is zero or no value is advertised, then the headend + can apply an SR Policy that only contains one segment without inserting any + SRH header. A non-zero SRH Max H.encaps MSD indicates that the headend can + insert an SRH up to the advertised number of SIDs. + + Reference: :rfc:`9352` + +.. cfgcmd:: set protocols isis segment-routing srv6 node-msd max-segs-left <0-255> + + The Maximum Segments Left MSD Type signals the maximum value of the + "Segments Left" field (:rfc:`8754`) in the SRH of a received packet before + applying the Endpoint behavior associated with a SID. + + If no value is advertised, the supported value is 0. + + Reference: :rfc:`9352` ******** Examples @@ -598,3 +661,87 @@ Here is the routing tables showing the MPLS segment routing label operations: 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 IS-IS with Segment Routing over IPv6 (Experimental) +========================================================== + +**Node 1:** + +.. code-block:: none + + set interfaces dummy dum6 description "SRv6 IS-IS" + set interfaces ethernet eth1 address '192.0.2.1/24' + set interfaces loopback lo address '192.168.255.255/32' + + set protocols segment-routing srv6 locator MAIN prefix 2001:db8:1::/64 + set protocols segment-routing interface eth1 + + 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 srv6 locator MAIN + set protocols isis segment-routing srv6 interface dum6 + +**Node 2:** + +.. code-block:: none + + set interfaces dummy dum6 description "SRv6 IS-IS" + set interfaces ethernet eth1 address '192.0.2.2/24' + set interfaces loopback lo address '192.168.255.254/32' + + set protocols segment-routing srv6 locator MAIN prefix 2001:db8:2::/64 + set protocols segment-routing interface eth1 + + 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 srv6 locator MAIN + set protocols isis segment-routing srv6 interface dum6 + +Enable IS-IS with Segment Routing over IPv6 (uSID) (Experimental) +================================================================= + +**Node 1:** + +.. code-block:: none + + set interfaces dummy dum6 description "SRv6 IS-IS" + set interfaces ethernet eth1 address '192.0.2.1/24' + set interfaces loopback lo address '192.168.255.255/32' + + set protocols segment-routing interface eth1 + set protocols segment-routing srv6 locator MAIN prefix 2001:db8:1::/48 + set protocols segment-routing srv6 locator MAIN behavior-usid + set protocols segment-routing srv6 locator MAIN block-len 32 + set protocols segment-routing srv6 locator MAIN format usid-f3216 + set protocols segment-routing srv6 locator MAIN func-bits 16 + set protocols segment-routing srv6 locator MAIN node-len 16 + + 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 srv6 interface dum6 + set protocols isis segment-routing srv6 locator MAIN + +**Node 2:** + +.. code-block:: none + + set interfaces dummy dum6 description "SRv6 IS-IS" + set interfaces ethernet eth1 address '192.0.2.2/24' + set interfaces loopback lo address '192.168.255.254/32' + + set protocols segment-routing interface eth1 + set protocols segment-routing srv6 locator MAIN prefix 2001:db8:2::/48 + set protocols segment-routing srv6 locator MAIN behavior-usid + set protocols segment-routing srv6 locator MAIN block-len 32 + set protocols segment-routing srv6 locator MAIN format usid-f3216 + set protocols segment-routing srv6 locator MAIN func-bits 16 + set protocols segment-routing srv6 locator MAIN node-len 16 + + 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 srv6 interface dum6 + set protocols isis segment-routing srv6 locator MAIN diff --git a/docs/configuration/protocols/static.rst b/docs/configuration/protocols/static.rst index 3e3eb47b..eb5a439c 100644 --- a/docs/configuration/protocols/static.rst +++ b/docs/configuration/protocols/static.rst @@ -70,8 +70,12 @@ IPv4 BFD Configure a static route for `<subnet>` using gateway `<address>` and use the gateway address as BFD peer destination address. +.. stop_vyoslinter + .. cfgcmd:: set protocols static route <subnet> next-hop <address> bfd profile <profile> +.. start_vyoslinter + Configure a static route for `<subnet>` using gateway `<address>` and use the gateway address as BFD peer destination address with BFD profile `<profile>`. @@ -153,13 +157,20 @@ IPv6 Unicast Routes .. note:: Routes with a distance of 255 are effectively disabled and not installed into the kernel. +.. stop_vyoslinter + .. cfgcmd:: set protocols static route6 <subnet> next-hop <address> segments <segments> - It is possible to specify a static route for ipv6 prefixes using an SRv6 segments - instruction. The `/` separator can be used to specify multiple segment instructions. +.. start_vyoslinter + + It is possible to specify a static route for ipv6 prefixes using an + SRv6 segments instruction. The ``/`` separator can be used to specify + multiple segment instructions. Example: +.. stop_vyoslinter + .. code-block:: none set protocols static route6 2001:db8:1000::/36 next-hop 2001:db8:201::ffff segments '2001:db8:aaaa::7/2002::4/2002::3/2002::2' @@ -176,6 +187,8 @@ IPv6 Unicast Routes 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 +.. start_vyoslinter + IPv6 Interface Routes ===================== @@ -202,15 +215,20 @@ IPv6 Interface Routes .. cfgcmd:: set protocols static route6 <subnet> interface <interface> segments <segments> - It is possible to specify a static route for ipv6 prefixes using an SRv6 segments - instruction. The `/` separator can be used to specify multiple segment instructions. + It is possible to specify a static route for ipv6 prefixes using an + SRv6 segments instruction. The ``/`` separator can be used to specify + multiple segment instructions. Example: +.. stop_vyoslinter + .. code-block:: none set protocols static route6 2001:db8:1000::/36 interface eth0 segments '2001:db8:aaaa::7/2002::4/2002::3/2002::2' +.. start_vyoslinter + IPv6 BFD ======== @@ -219,14 +237,22 @@ IPv6 BFD Configure a static route for `<subnet>` using gateway `<address>` and use the gateway address as BFD peer destination address. +.. stop_vyoslinter + .. cfgcmd:: set protocols static route6 <subnet> next-hop <address> bfd profile <profile> +.. start_vyoslinter + Configure a static route for `<subnet>` using gateway `<address>` and use the gateway address as BFD peer destination address with BFD profile `<profile>`. +.. stop_vyoslinter + .. cfgcmd:: set protocols static route6 <subnet> next-hop <address> bfd multi-hop source-address <source> +.. start_vyoslinter + Configure a static route for `<subnet>` using gateway `<address>` and use the gateway address as BFD peer destination address with source address `<source>` but initiate a multi-hop session. @@ -271,7 +297,5 @@ IPv6 Blackhole Routes Alternate Routing Tables ************************ -TBD - Alternate routing tables are used with policy based routing by utilizing :ref:`vrf`. diff --git a/docs/configuration/protocols/traffic-engineering.rst b/docs/configuration/protocols/traffic-engineering.rst new file mode 100644 index 00000000..977a5e5c --- /dev/null +++ b/docs/configuration/protocols/traffic-engineering.rst @@ -0,0 +1,51 @@ +.. _traffic-engineering: + +################### +Traffic Engineering +################### + +Traffic Engineering (TE) is possibility to send traffic from node to node using +alternative path. + +Common link parameters +---------------------- + +Traffic Engineering parameters are used for both IS-IS and OSPF (not supported yet). + +.. cfgcmd:: set protocols traffic-engineering admin-group <admin-group-name> bit-position <bit-position-value> + + Create Administrative group and assosiate bit position with it. These groups can be + used in the following commands. + + <bit-position-value> can have value 0-31. There cannot be two groups with same bit position. + +.. cfgcmd:: set protocols traffic-engineering interface <ifname> admin-group <admin-group-name> + + Set administrative group for interface <ifname>. Multiple values can be provided. + +.. cfgcmd:: set protocols traffic-engineering interface <ifname> max-bandwidth <max-bandwidth-value-mbps> + + Set maximum bandwidth for interface <ifname>. Value given in Mbits per second. + +.. cfgcmd:: set protocols traffic-engineering interface <ifname> max-reservable-bandwidth <max-reservable-bandwidth-value-mbps> + + Set maximum reservable bandwidth for interface <ifname>. Value given in Mbits per second. + + +IS-IS TE Configuration +---------------------- + +Traffic Engineering (TE) can be enabled and exported for IS-IS +using the following commands: + +.. cfgcmd:: set protocols isis traffic-engineering enable + + Enable Traffic Engineering for IS-IS. + +.. cfgcmd:: set protocols isis traffic-engineering export + + Export Traffic Engineering data to neighbors. + +.. cfgcmd:: set protocols isis traffic-engineering address <ipv4-address> + + Configure IPv4 address for MPLS-TE. diff --git a/docs/configuration/service/conntrack-sync.rst b/docs/configuration/service/conntrack-sync.rst index 08b71eed..62e96e0e 100644 --- a/docs/configuration/service/conntrack-sync.rst +++ b/docs/configuration/service/conntrack-sync.rst @@ -98,6 +98,20 @@ Configuration This diable the external cache and directly injects the flow-states into the in-kernel Connection Tracking System of the backup firewall. +.. cfgcmd:: set service conntrack-sync purge-timeout <timeout> + + Timeout (in seconds) for purging synchronized entries on handover events. + + On handover, ``conntrackd -t`` is invoked, which schedules a conntrack table + flush after ``<timeout>`` seconds to purge stale (“zombie”) entries and + reduce clashes when multiple handovers occur in a short period. + The default is 60 seconds. + +.. note:: In VRRP stateful firewall deployments, align VRRP timing with this + behavior: because synchronized conntrack state is purged after the purge + timeout, set **VRRP preempt-delay** to ≥ **purge-timeout** so mastership + can be restored before conntrack state is purged. + .. cfgcmd:: set service conntrack-sync disable-syslog Disable connection logging via Syslog. diff --git a/docs/configuration/service/eventhandler.rst b/docs/configuration/service/eventhandler.rst index 15f08239..9f4ebb04 100644 --- a/docs/configuration/service/eventhandler.rst +++ b/docs/configuration/service/eventhandler.rst @@ -8,8 +8,9 @@ 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. +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. ****************************** @@ -33,49 +34,76 @@ Event Handler Configuration Steps .. cfgcmd:: set service event-handler event <event-handler name> - This is an optional command because the event handler will be automatically created after any of the next commands. + 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 =========================================== - .. cfgcmd:: set service event-handler event <event-handler name> filter pattern <regex> +.. stop_vyoslinter - This is a mandatory command. Sets regular expression to match against log string message. - - .. note:: The regular expression matches if and only if the entire string matches the pattern. + .. cfgcmd:: set service event-handler event <event-handler name> filter pattern <regex> + +.. start_vyoslinter + + This is a mandatory command. Sets regular expression to match + against log string message. + + .. note:: The regular expression matches if and only if the entire + string matches the pattern. 3. Add a full path to the script ================================ +.. stop_vyoslinter + .. cfgcmd:: set service event-handler event <event-handler name> script path <path to script> - - This is a mandatory command. Sets the full path to the script. The script file must be executable. + +.. start_vyoslinter + + This is a mandatory command. Sets the full path to the script. + The script file must be executable. 4. Add optional parameters ========================== - .. cfgcmd:: set service event-handler event <event-handler name> filter syslog-identifier <sylogid name> +.. stop_vyoslinter + + .. cfgcmd:: set service event-handler event <event-handler name> filter syslog-identifier <syslogid name> + +.. start_vyoslinter This is an optional command. Filters log messages by syslog-identifier. +.. stop_vyoslinter + .. cfgcmd:: set service event-handler event <event-handler name> script environment <env name> value <env value> - This is an optional command. Adds environment and its value to the script. Use separate commands for each environment. +.. start_vyoslinter + + 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. +.. stop_vyoslinter + .. cfgcmd:: set service event-handler event <event-handler name> script arguments <arguments> - This is an optional command. Adds arguments to the script. Arguments must be separated by spaces. +.. start_vyoslinter + + This is an optional command. Adds arguments to the script. + Arguments must be separated by spaces. - .. note:: We don't recomend to use arguments. Using environments is more preffereble. + .. note:: We don't recommend to use arguments. Using environments + is more preferable. ******* @@ -84,44 +112,48 @@ Example Event handler that monitors the state of interface eth0. +.. stop_vyoslinter + .. code-block:: 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' + 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 'eth0' + set service event-handler event INTERFACE_STATE_DOWN script path '/config/scripts/eventhandler.py' Event handler script .. code-block:: 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) + #!/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) + +.. start_vyoslinter diff --git a/docs/configuration/service/mdns.rst b/docs/configuration/service/mdns.rst index b4ca1fd1..8a26722e 100644 --- a/docs/configuration/service/mdns.rst +++ b/docs/configuration/service/mdns.rst @@ -1,5 +1,6 @@ +############# mDNS Repeater -------------- +############# Starting with VyOS 1.2 a :abbr:`mDNS (Multicast DNS)` repeater functionality is provided. Additional information can be obtained from diff --git a/docs/configuration/system/flow-accounting.rst b/docs/configuration/system/flow-accounting.rst index a339df75..0664eac7 100644 --- a/docs/configuration/system/flow-accounting.rst +++ b/docs/configuration/system/flow-accounting.rst @@ -84,7 +84,9 @@ CLI command. You may disable using the local in-memory table with the command: .. cfgcmd:: set system flow-accounting syslog-facility <facility> - TBD + Set the syslog facility for flow-accounting log messages. Supported values + include ``daemon``, ``local0`` through ``local7``, and other standard syslog + facilities. Flow Export ----------- @@ -165,6 +167,8 @@ display captured network traffic information for all configured interfaces. Show flow accounting information for given `<interface>`. + .. stop_vyoslinter + .. code-block:: none vyos@vyos:~$ show flow-accounting interface eth0 @@ -178,11 +182,15 @@ display captured network traffic information for all configured interfaces. 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 + .. start_vyoslinter + .. opcmd:: show flow-accounting interface <interface> host <address> Show flow accounting information for given `<interface>` for a specific host only. + .. stop_vyoslinter + .. code-block:: none vyos@vyos:~$ show flow-accounting interface eth0 host 192.0.2.14 @@ -191,3 +199,5 @@ display captured network traffic information for all configured interfaces. 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 + + .. start_vyoslinter diff --git a/docs/configuration/system/lcd.rst b/docs/configuration/system/lcd.rst index 808d45a2..3fcf01dd 100644 --- a/docs/configuration/system/lcd.rst +++ b/docs/configuration/system/lcd.rst @@ -1,8 +1,8 @@ .. _system-display: -******************** +#################### System Display (LCD) -******************** +#################### The system LCD :abbr:`LCD (Liquid-crystal display)` option is for users running VyOS on hardware that features an LCD display. This is typically a small display diff --git a/docs/configuration/system/sysctl.rst b/docs/configuration/system/sysctl.rst index 06e15031..1fedb9bd 100644 --- a/docs/configuration/system/sysctl.rst +++ b/docs/configuration/system/sysctl.rst @@ -4,7 +4,11 @@ Sysctl ###### -This chapeter describes how to configure kernel parameters at runtime. +.. note:: This page is a stub and needs expansion. Contributions + welcome via the `VyOS documentation repository + <https://github.com/vyos/vyos-documentation>`_. + +This chapter 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/. diff --git a/docs/configuration/trafficpolicy/index.rst b/docs/configuration/trafficpolicy/index.rst index 5414ce77..13cfb9dc 100644 --- a/docs/configuration/trafficpolicy/index.rst +++ b/docs/configuration/trafficpolicy/index.rst @@ -53,29 +53,29 @@ They can be **decimal** prefixes. .. code-block:: none - kbit (10^3) kilobit per second - mbit (10^6) megabit per second - gbit (10^9) gigabit per second - tbit (10^12) terabit per second - - kbps (8*10^3) kilobyte per second - mbps (8*10^6) megabyte per second - gbps (8*10^9) gigabyte per second - tbps (8*10^12) terabyte per second + kbit (10^3) kilobit per second + mbit (10^6) megabit per second + gbit (10^9) gigabit per second + tbit (10^12) terabit per second + + kbps (8*10^3) kilobyte per second + mbps (8*10^6) megabyte per second + gbps (8*10^9) gigabyte per second + tbps (8*10^12) terabyte per second Or **binary** prefixes. .. code-block:: none - kibit (2^10 = 1024) kibibit per second - mibit (2^20 = 1024^2) mebibit per second - gibit (2^30 = 1024^3) gibibit per second - tbit (2^40 = 1024^4) tebibit per second + 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 + 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 @@ -88,7 +88,7 @@ A *bit* is written as **bit**, kbit (kilobits per second) mbit (megabits per second) gbit (gigabits per second) - tbit (terabits per second) + tbit (terabits per second) while a *byte* is written as a single **b**. @@ -134,10 +134,13 @@ configuring it. identify it, it also defines its priority. +.. stop_vyoslinter + .. code-block:: none set qos policy <policy> <policy-name> class <class-ID> match <class-matching-rule-name> +.. start_vyoslinter 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 @@ -199,10 +202,14 @@ is based on marks done by the firewall, You can also write a description for a filter: +.. stop_vyoslinter + .. code-block:: none set qos policy shaper MY-SHAPER class 30 match MY-FIRST-FILTER description "My filter description" +.. start_vyoslinter + .. note:: An IPv4 TCP filter will only match packets with an IPv4 header @@ -281,9 +288,11 @@ 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. +.. stop_vyoslinter + .. code-block:: none - vyos@vyos# set qos policy shaper MY-SHAPER class 30 + 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) @@ -299,7 +308,8 @@ possibilities depending on the Traffic Policy you are configuring. 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) - + +.. start_vyoslinter For instance, with :code:`set qos policy shaper MY-SHAPER class 30 set-dscp EF` you would be modifying the DSCP field value of packets in @@ -1140,9 +1150,11 @@ parameters. Random Early Detection (RED) +.. stop_vyoslinter + .. code-block:: none - vyos@vyos# set qos policy shaper HTB class 10 + 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) @@ -1159,6 +1171,8 @@ parameters. set-dscp Change the Differentiated Services (DiffServ) field in the IP header target Acceptable minimum standing/persistent queue delay (default: 5) +.. start_vyoslinter + .. note:: If you configure a class for **VoIP traffic**, don't give it any @@ -1174,6 +1188,8 @@ Example A simple example of Shaper using priorities. +.. stop_vyoslinter + .. code-block:: none set qos policy shaper MY-HTB bandwidth '50mbit' @@ -1195,6 +1211,8 @@ A simple example of Shaper using priorities. set qos policy shaper MY-HTB default priority '7' set qos policy shaper MY-HTB default queue-type 'fair-queue' +.. start_vyoslinter + .. _CAKE: CAKE @@ -1255,8 +1273,8 @@ edge. .. 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. + **(Default)** Flows are defined by the 5-tuple, fairness is applied + over source and destination addresses and also over individual flows. .. cfgcmd:: set qos policy cake <text> rtt diff --git a/docs/configuration/vpn/index.rst b/docs/configuration/vpn/index.rst index d0121abd..6d38e5b5 100644 --- a/docs/configuration/vpn/index.rst +++ b/docs/configuration/vpn/index.rst @@ -13,12 +13,4 @@ VPN pptp rsa-keys sstp - - -pages to sort - -.. toctree:: - :maxdepth: 1 - :includehidden: - dmvpn diff --git a/docs/configuration/vpn/ipsec/index.rst b/docs/configuration/vpn/ipsec/index.rst index e454e2f6..973c76de 100644 --- a/docs/configuration/vpn/ipsec/index.rst +++ b/docs/configuration/vpn/ipsec/index.rst @@ -12,10 +12,4 @@ IPsec remoteaccess_ipsec troubleshooting_ipsec -pages to sort - -.. toctree:: - :maxdepth: 1 - :includehidden: - diff --git a/docs/configuration/vpn/ipsec/remoteaccess_ipsec.rst b/docs/configuration/vpn/ipsec/remoteaccess_ipsec.rst index 1a41d987..50499160 100644 --- a/docs/configuration/vpn/ipsec/remoteaccess_ipsec.rst +++ b/docs/configuration/vpn/ipsec/remoteaccess_ipsec.rst @@ -1,7 +1,11 @@ .. _remoteaccess_ipsec: +############################ IPSec IKEv2 Remote Access VPN -============================= +############################ + +.. TODO:: Convert raw command blocks in this file to cfgcmd/opcmd + directives for command coverage tracking. Internet Key Exchange version 2 (IKEv2) is a tunneling protocol, based on IPsec, that establishes a secure VPN communication between VPN devices, and defines diff --git a/docs/configuration/vpn/ipsec/troubleshooting_ipsec.rst b/docs/configuration/vpn/ipsec/troubleshooting_ipsec.rst index fdeb347d..f0f2e208 100644 --- a/docs/configuration/vpn/ipsec/troubleshooting_ipsec.rst +++ b/docs/configuration/vpn/ipsec/troubleshooting_ipsec.rst @@ -4,6 +4,9 @@ Troubleshooting Site-to-Site VPN IPsec ###################################### +.. TODO:: Convert raw command blocks in this file to cfgcmd/opcmd + directives for command coverage tracking. + ************ Introduction ************ @@ -26,6 +29,8 @@ Checking IKE SA Status The next command shows IKE SAs' statuses. +.. stop_vyoslinter + .. code-block:: none vyos@vyos:~$ show vpn ike sa @@ -317,6 +322,8 @@ The reason of this problem is showed on the responder side. 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) ] +.. start_vyoslinter + Traffic selectors **10.0.2.0/24 === 10.0.0.0/24** are unacceptable on the responder side. diff --git a/docs/configuration/vpn/openconnect.rst b/docs/configuration/vpn/openconnect.rst index 11824e50..0262b3f2 100644 --- a/docs/configuration/vpn/openconnect.rst +++ b/docs/configuration/vpn/openconnect.rst @@ -4,6 +4,9 @@ OpenConnect ########### +.. TODO:: Convert raw command blocks in this file to cfgcmd/opcmd + directives for command coverage tracking. + 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 @@ -37,10 +40,14 @@ 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. +.. stop_vyoslinter + .. code-block:: none sudo certbot certonly --standalone --preferred-challenges http -d <domain name> +.. start_vyoslinter + Server Configuration ==================== @@ -63,6 +70,8 @@ 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: +.. stop_vyoslinter + .. code-block:: none set vpn openconnect authentication mode local <password-otp|otp> @@ -71,6 +80,8 @@ To do this, an OTP configuration must be added to the configuration above: 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)> +.. start_vyoslinter + For generating an OTP key in VyOS, you can use the CLI command (operational mode): @@ -81,9 +92,21 @@ For generating an OTP key in VyOS, you can use the CLI command User Certificate Authentication =============================== -You can configure users to be authenticated by certificate by setting the authentication mode to certificate, and defining what field (by OID) in the certificate will be used to identify the username. Two pre-defined shortcuts for Common Name (OID 2.5.4.3) and User ID (OID 0.9.2342.19200300.100.1.1) have been provide as cn or uid. Otherwise a specific OID value must be provided. +You can configure users to be authenticated by certificate by setting +the authentication mode to certificate, and defining what field (by OID) +in the certificate will be used to identify the username. Two pre-defined + +.. stop_vyoslinter + +shortcuts for Common Name (OID 2.5.4.3) and User ID +(OID 0.9.2342.19200300.100.1.1) have been provided as cn or uid. -The user's certificate must be signed by the certificate authority defined in the configuration for it to be validated for authentication. +.. start_vyoslinter + +Otherwise a specific OID value must be provided. + +The user's certificate must be signed by the certificate authority +defined in the configuration for it to be validated for authentication. .. code-block:: none @@ -95,14 +118,17 @@ The user's certificate must be signed by the certificate authority defined in th Verification ************ -.. code-block:: none +.. stop_vyoslinter +.. code-block:: 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 +.. start_vyoslinter + .. note:: It is compatible with Cisco (R) AnyConnect (R) clients. ******* @@ -114,6 +140,8 @@ SSL Certificates generation Follow the instructions to generate CA cert (in configuration mode): +.. stop_vyoslinter + .. code-block:: none vyos@vyos# run generate pki ca install ca-ocserv @@ -151,6 +179,8 @@ Follow the instructions to generate server cert (in configuration mode): 2 value(s) installed. Use "compare" to see the pending changes, and "commit" to apply. [edit] +.. start_vyoslinter + Each of the install command should be applied to the configuration and commited before using under the openconnect configuration: @@ -168,6 +198,8 @@ Openconnect Configuration Simple setup with one user added and password authentication: +.. stop_vyoslinter + .. code-block:: none set vpn openconnect authentication local-users username tst password 'OC_bad_Secret' @@ -178,6 +210,8 @@ Simple setup with one user added and password authentication: set vpn openconnect ssl ca-certificate 'ca-ocserv' set vpn openconnect ssl certificate 'srv-ocserv' +.. start_vyoslinter + To enable the HTTP security headers in the configuration file, use the command: .. code-block:: none @@ -191,6 +225,8 @@ Adding a 2FA with an OTP-key First the OTP keys must be generated and sent to the user and to the configuration: +.. stop_vyoslinter + .. code-block:: none vyos@vyos:~$ generate openconnect username tst otp-key hotp-time @@ -222,13 +258,19 @@ configuration: # To add this OTP key to configuration, run the following commands: set vpn openconnect authentication local-users username tst otp key 'ebc1c91b13848ce0bb67d9212934546e41803cfa' +.. start_vyoslinter + Next it is necessary to configure 2FA for OpenConnect: +.. stop_vyoslinter + .. code-block:: none set vpn openconnect authentication mode local password-otp set vpn openconnect authentication local-users username tst otp key 'ebc1c91b13848ce0bb67d9212934546e41803cfa' +.. start_vyoslinter + Now when connecting the user will first be asked for the password and then the OTP key. @@ -254,6 +296,8 @@ 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. +.. stop_vyoslinter + .. code-block:: none sudo mkdir -p /config/auth/ocserv/config-per-user @@ -263,6 +307,8 @@ users. 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 +.. start_vyoslinter + .. warning:: The above directory and default-config must be a child directory of /config/auth, since files outside this directory are not persisted after an image upgrade. @@ -297,6 +343,8 @@ connect/disconnect, data transferred, and so on. Configure an accounting server and enable accounting with: +.. stop_vyoslinter + .. code-block:: none set vpn openconnect accounting mode radius @@ -304,12 +352,16 @@ Configure an accounting server and enable accounting with: 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 +.. start_vyoslinter + .. warning:: The RADIUS accounting feature must be used with the OpenConnect authentication mode RADIUS. It cannot be used with local authentication. You must configure the OpenConnect authentication mode to "radius". An example of the data captured by a FREERADIUS server with sql accounting: +.. stop_vyoslinter + .. code-block:: none mysql> SELECT username, nasipaddress, acctstarttime, acctstoptime, acctinputoctets, acctoutputoctets, callingstationid, framedipaddress, connectinfo_start FROM radacct; @@ -318,3 +370,5 @@ An example of the data captured by a FREERADIUS server with sql accounting: +----------+---------------+---------------------+---------------------+-----------------+------------------+-------------------+-----------------+-----------------------------------+ | 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 | +----------+---------------+---------------------+---------------------+-----------------+------------------+-------------------+-----------------+-----------------------------------+ + +.. start_vyoslinter diff --git a/docs/configuration/vpn/rsa-keys.rst b/docs/configuration/vpn/rsa-keys.rst index 0508522f..e7584563 100644 --- a/docs/configuration/vpn/rsa-keys.rst +++ b/docs/configuration/vpn/rsa-keys.rst @@ -2,6 +2,10 @@ ######## RSA-Keys ######## + +.. TODO:: Convert raw command blocks in this file to cfgcmd/opcmd + directives for command coverage tracking. + 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. @@ -9,6 +13,8 @@ RSA keys for authentication. They are very fast and easy to setup. First, on both routers run the operational command "generate pki key-pair install <key-pair nam>>". You may choose different length than 2048 of course. +.. stop_vyoslinter + .. code-block:: none vyos@left# run generate pki key-pair install ipsec-LEFT @@ -23,6 +29,8 @@ install <key-pair nam>>". You may choose different length than 2048 of course. set pki key-pair ipsec-LEFT private key 'MIIEvgIBADAN...' [edit] +.. start_vyoslinter + Configuration commands will display. Note the command with the public key (set pki key-pair ipsec-LEFT public key 'MIIBIjANBgkqh...'). @@ -51,13 +59,19 @@ On the RIGHT: 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. +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): +.. stop_vyoslinter + .. code-block:: none set vpn ipsec interface eth0 @@ -105,3 +119,5 @@ On the RIGHT (dynamic address): 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 + +.. start_vyoslinter diff --git a/docs/contributing/index.rst b/docs/contributing/index.rst new file mode 100644 index 00000000..18b925ec --- /dev/null +++ b/docs/contributing/index.rst @@ -0,0 +1,14 @@ +############ +Contributing +############ + +.. toctree:: + :maxdepth: 1 + + build-vyos + development + cla + issues-features + upstream-packages + debugging + testing diff --git a/docs/index.rst b/docs/index.rst index 00db5dda..660daa46 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -11,20 +11,27 @@ VyOS User Guide .. grid-item-card:: Get / Build VyOS - Quickly :ref:`Build<contributing/build-vyos:build vyos>` your own Image or take a look at how to :ref:`download<installation/install:download>` a free or supported version. + Quickly :ref:`Build<contributing/build-vyos:build vyos>` + your own Image or take a look at how to + :ref:`download<installation/install:download>` + a free or supported version. .. grid-item-card:: Install VyOS - Read about how to install VyOS on :ref:`Bare Metal<installation/install:installation>` or in a - :ref:`Virtual Environment<installation/virtual/index:Virtual Environments>` and - how to use an image with the usual :ref:`cloud<installation/cloud/index:Cloud Environments>` providers + Read about how to install VyOS on + :ref:`Bare Metal<installation/install:installation>` + or in a :ref:`VM <installation/virtual/index:Virtual Environments>` + and how to use an image with the usual + :ref:`cloud<installation/cloud/index:Cloud Environments>` + providers .. grid-item-card:: Configuration and Operation - Use the :ref:`Quickstart Guide<quick-start:Quick Start>`, to have a fast overview. Or go deeper and - set up :ref:`advanced routing<configuration/protocols/index:protocols>`, + Use the :ref:`Quickstart Guide<quick-start:Quick Start>`, + to have a fast overview. Or go deeper and set up + :ref:`advanced routing<configuration/protocols/index:protocols>`, :ref:`VRFs<configuration/vrf/index:vrf>`, or :ref:`VPNs<configuration/vpn/index:vpn>` for example. @@ -33,21 +40,28 @@ VyOS User Guide Integrate VyOS in your automation Workflow with :ref:`Ansible<vyos-ansible>`, - have your own :ref:`local scripts<command-scripting>`, or configure VyOS with the :ref:`HTTPS-API<vyosapi>`. + have your own :ref:`local scripts<command-scripting>`, + or configure VyOS with the + :ref:`HTTPS-API<vyosapi>`. .. grid-item-card:: Examples - Get some inspiration from the :ref:`Configuration Blueprints<configexamples/index:Configuration Blueprints>` + Get some inspiration from the + :ref:`Blueprints <configexamples/index:Configuration Blueprints>` to build your infrastructure. .. grid-item-card:: Contribute and Community | There are many ways to contribute to the project. - | Add missing parts or improve the :ref:`Documentation<documentation:Write Documentation>`. - | Discuss in `Slack <https://slack.vyos.io/>`_ or the `Forum <https://forum.vyos.io>`_. - | Or you can pick up a `Task <https://vyos.dev/>`_ and fix the :ref:`code<contributing/development:development>`. + | Add missing parts or improve the + :ref:`Documentation<documentation:Write Documentation>`. + | Discuss in `Slack <https://slack.vyos.io/>`_ + or the `Forum <https://forum.vyos.io>`_. + | Or you can pick up a `Task <https://vyos.dev/>`_ + and fix the + :ref:`code<contributing/development:development>`. .. toctree:: @@ -56,7 +70,6 @@ VyOS User Guide introducing/about introducing/history - changelog/index .. toctree:: @@ -87,13 +100,7 @@ VyOS User Guide :hidden: :caption: Development - contributing/build-vyos - contributing/development - contributing/cla - contributing/issues-features - contributing/upstream-packages - contributing/debugging - contributing/testing + contributing/index .. toctree:: diff --git a/docs/installation/cloud/oracle.rst b/docs/installation/cloud/oracle.rst index 1d02335b..d71d8039 100644 --- a/docs/installation/cloud/oracle.rst +++ b/docs/installation/cloud/oracle.rst @@ -4,6 +4,10 @@ Oracle ###### +.. note:: This page is a stub and needs expansion. Contributions + welcome via the `VyOS documentation repository + <https://github.com/vyos/vyos-documentation>`_. + .. stop_vyoslinter References ---------- diff --git a/docs/installation/install.rst b/docs/installation/install.rst index b820659b..7b38a06b 100644 --- a/docs/installation/install.rst +++ b/docs/installation/install.rst @@ -147,7 +147,7 @@ To verify a VyOS image starting with VyOS ``1.3.0-rc6``, run: $ minisign -V -P RWSIhkR/dkM2DSaBRniv/bbbAf8hmDqdbOEmgXkf1RxRoxzodgKcDyGq -m vyos-1.5-rolling-202409250007-generic-amd64.iso vyos-1.5-rolling-202409250007-generic-amd64.iso.minisig Signature and comment signature verified - Trusted comment: timestamp:1727223408 file:vyos-1.5-rolling-202409250007-generic-amd64.iso hashed + Trusted comment: timestamp:1727223408 file:vyos-1.5-rolling-202409250007-generic-amd64.iso hashed During an image upgrade, VyOS runs the following command: diff --git a/docs/installation/update.rst b/docs/installation/update.rst index 967f494b..81750dc1 100644 --- a/docs/installation/update.rst +++ b/docs/installation/update.rst @@ -2,8 +2,9 @@ .. _update_vyos: +########### Update VyOS -=========== +########### New system images can be added using the :opcmd:`add system image` command. This command extracts the image and prompts you to use the current system diff --git a/docs/installation/virtual/docker.rst b/docs/installation/virtual/docker.rst index 282e4e63..d62c011b 100644 --- a/docs/installation/virtual/docker.rst +++ b/docs/installation/virtual/docker.rst @@ -2,9 +2,9 @@ .. _docker: -****************************** +############################## Run VyOS in a 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 diff --git a/docs/installation/virtual/eve-ng.rst b/docs/installation/virtual/eve-ng.rst index 855daeb0..f3db28fe 100644 --- a/docs/installation/virtual/eve-ng.rst +++ b/docs/installation/virtual/eve-ng.rst @@ -4,6 +4,10 @@ EVE-NG ###### +.. note:: This page is a stub and needs expansion. Contributions + welcome via the `VyOS documentation repository + <https://github.com/vyos/vyos-documentation>`_. + References ========== diff --git a/docs/installation/virtual/libvirt.rst b/docs/installation/virtual/libvirt.rst index 5da1503f..7374e42c 100644 --- a/docs/installation/virtual/libvirt.rst +++ b/docs/installation/virtual/libvirt.rst @@ -2,9 +2,9 @@ .. _libvirt: -**************************** +############################ Run VyOS on Libvirt QEMU/KVM -**************************** +############################ Libvirt is an open-source API, daemon, and management tool for managing platform virtualization. You can deploy VyOS on libvirt KVM in several ways: diff --git a/docs/installation/virtual/proxmox.rst b/docs/installation/virtual/proxmox.rst index 070627aa..6bd030e3 100644 --- a/docs/installation/virtual/proxmox.rst +++ b/docs/installation/virtual/proxmox.rst @@ -2,9 +2,9 @@ .. _proxmox: -****************** +################## Running on Proxmox -****************** +################## Proxmox is an open-source platform for virtualization. Visit https://vyos.io to download a ``.qcow2`` image that you can import into diff --git a/docs/operation/information.rst b/docs/operation/information.rst index fbff53a3..1b3d876a 100644 --- a/docs/operation/information.rst +++ b/docs/operation/information.rst @@ -2,9 +2,9 @@ .. _information: -****************** +################## System Information -****************** +################## VyOS features a rich set of operational level commands to retrieve arbitrary information about your running system. For more information on the VyOS command @@ -42,6 +42,8 @@ recent Linux distributions. .. note:: If a device is unplugged and plugged in again, it is assigned a new ``Port``, ``Dev``, and ``If``. +.. stop_vyoslinter + .. code-block:: none vyos@vyos:~$ show hardware usb @@ -70,6 +72,8 @@ recent Linux distributions. |__ 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 +.. start_vyoslinter + .. opcmd:: show hardware usb serial @@ -77,6 +81,8 @@ recent Linux distributions. device name displayed, (for example ``usb0b2.4p1.0``), can be used directly when accessing the serial console as console-server device. +.. stop_vyoslinter + .. code-block:: none vyos@vyos$ show hardware usb serial @@ -99,6 +105,8 @@ recent Linux distributions. usb0b2.4p1.2 Quad_RS232-HS Future Technology Devices International, Ltd usb0b2.4p1.3 Quad_RS232-HS Future Technology Devices International, Ltd +.. start_vyoslinter + .. _information_version: ######## @@ -107,8 +115,9 @@ Version .. opcmd:: show version - Return the currently running VyOS version and build information. This includes - the name of the release train, e.g., ``sagitta`` on VyOS 1.4, and ``circinus`` on VyOS 1.5. + Return the currently running VyOS version and build information. This + includes the name of the release train, e.g., ``sagitta`` on VyOS 1.4, + and ``circinus`` on VyOS 1.5. .. code-block:: none diff --git a/docs/superpowers/plans/2026-03-21-docs-improvements.md b/docs/superpowers/plans/2026-03-21-docs-improvements.md deleted file mode 100644 index a2656f15..00000000 --- a/docs/superpowers/plans/2026-03-21-docs-improvements.md +++ /dev/null @@ -1,712 +0,0 @@ -# VyOS Documentation Improvements Implementation Plan - -> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking. - -**Goal:** Fix documentation quality issues across 4 work streams: mechanical fixes, content quality, structural reorganization, and RTD platform cleanup. - -**Architecture:** 3 separate git branches each producing one PR, plus direct RTD API calls. Each PR is independent — PR 1 and PR 2 can run in parallel; PR 3 should follow PR 1 to avoid merge conflicts. - -**Tech Stack:** RST (reStructuredText), Sphinx, Read the Docs API v3, curl, git - -**Spec:** `docs/superpowers/specs/2026-03-21-docs-improvements-design.md` - ---- - -## PR 1: Mechanical Fixes (`fix/docs-mechanical-cleanup`) - -### Task 1: Create branch and fix heading hierarchy — `=` files (23 files) - -**Files:** All under `docs/` prefix. -- Modify: `automation/command-scripting.rst`, `automation/terraform/terraformAWS.rst`, `automation/terraform/terraformAZ.rst`, `automation/terraform/terraformGoogle.rst`, `automation/terraform/terraformvSphere.rst`, `automation/terraform/terraformvyos.rst`, `automation/vyos-ansible.rst`, `automation/vyos-govyos.rst`, `automation/vyos-napalm.rst`, `automation/vyos-netmiko.rst`, `automation/vyos-pyvyos.rst`, `automation/vyos-salt.rst`, `configexamples/firewall.rst`, `configexamples/index.rst`, `configexamples/wan-load-balancing.rst`, `configuration/highavailability/index.rst`, `configuration/interfaces/openvpn-examples.rst`, `configuration/interfaces/tunnel.rst`, `configuration/loadbalancing/wan.rst`, `configuration/service/mdns.rst`, `configuration/vpn/ipsec/remoteaccess_ipsec.rst`, `installation/update.rst`, `vpp/configuration/ipfix.rst` - -These files use `====` underline-only for their first heading. The fix is to add a `####` overline above the title and replace the `====` underline with `####`, matching the title length. - -**Pattern — before:** -```rst -Command Scripting -================= -``` - -**Pattern — after:** -```rst -################# -Command Scripting -################# -``` - -- [ ] **Step 1: Create feature branch** - -```bash -cd /Users/syncer/GitHub/vyos-documentation -git checkout -b fix/docs-mechanical-cleanup current -``` - -- [ ] **Step 2: Fix all 23 `=` heading files** - -For each file: read the first heading, add a `#` overline of the same length as the title, replace the `=` underline with `#` of the same length. Preserve any `:lastproofread:` or `.. _label:` lines above the heading. - -- [ ] **Step 3: Verify no RST syntax errors** - -```bash -cd /Users/syncer/GitHub/vyos-documentation/docs -python3 -c " -import subprocess, sys -result = subprocess.run(['python3', '-m', 'sphinx', '-b', 'html', '-W', '--keep-going', '.', '_build/verify'], capture_output=True, text=True, timeout=300) -print(result.stdout[-2000:] if len(result.stdout) > 2000 else result.stdout) -print(result.stderr[-2000:] if len(result.stderr) > 2000 else result.stderr) -sys.exit(result.returncode) -" -``` - -If Sphinx is not installed locally, verify manually by checking each file's first 5 lines have the pattern: overline `####`, title text, underline `####`. - -- [ ] **Step 4: Commit** - -```bash -git add -A docs/ -git commit -m "fix: correct heading hierarchy in 23 files using = as first heading - -Replace underline-only = headings with proper ##### overline+underline -format per project convention." -``` - -### Task 2: Fix heading hierarchy — `-` files (7 files) - -**Files:** All under `docs/` prefix. -- Modify: `configexamples/azure-vpn-bgp.rst`, `configexamples/azure-vpn-dual-bgp.rst`, `configexamples/fwall-and-bridge.rst`, `configexamples/fwall-and-vrf.rst`, `configexamples/policy-based-ipsec-and-firewall.rst`, `configexamples/site-2-site-cisco.rst`, `configexamples/zone-policy.rst` - -These files use `----` underline-only for their first heading. Same fix pattern: add `####` overline, replace `----` underline with `####`. - -**Pattern — before:** -```rst -Route-Based Site-to-Site VPN to Azure (BGP over IKEv2/IPsec) ------------------------------------------------------------- -``` - -**Pattern — after:** -```rst -############################################################## -Route-Based Site-to-Site VPN to Azure (BGP over IKEv2/IPsec) -############################################################## -``` - -- [ ] **Step 1: Fix all 7 `-` heading files** - -Same approach as Task 1 Step 2. - -- [ ] **Step 2: Commit** - -```bash -git add -A docs/configexamples/ -git commit -m "fix: correct heading hierarchy in 7 files using - as first heading" -``` - -### Task 3: Fix heading hierarchy — `*` files (5 files) - -**Files:** All under `docs/` prefix. -- Modify: `configuration/system/lcd.rst`, `installation/virtual/docker.rst`, `installation/virtual/libvirt.rst`, `installation/virtual/proxmox.rst`, `operation/information.rst` - -These files use `****` overline+underline. Replace both `*` lines with `#` of the same length. - -**Pattern — before:** -```rst -******************** -System Display (LCD) -******************** -``` - -**Pattern — after:** -```rst -#################### -System Display (LCD) -#################### -``` - -- [ ] **Step 1: Fix all 5 `*` heading files** - -Replace `*` with `#` on both overline and underline. - -- [ ] **Step 2: Commit** - -```bash -git add -A docs/ -git commit -m "fix: correct heading hierarchy in 5 files using * as first heading" -``` - -### Task 4: Replace tab characters (13 files) - -**Files:** All under `docs/` prefix. -- Modify: `configuration/trafficpolicy/index.rst`, `configuration/service/eventhandler.rst`, `configuration/interfaces/wireless.rst`, `cli.rst`, `installation/install.rst`, `automation/terraform/terraformGoogle.rst`, `automation/terraform/terraformAWS.rst`, `automation/terraform/terraformAZ.rst`, `automation/terraform/terraformvSphere.rst`, `configexamples/nmp.rst`, `configexamples/ansible.rst`, `configexamples/qos.rst`, `configexamples/l3vpn-hub-and-spoke.rst` - -- [ ] **Step 1: Replace tabs with spaces in all 13 files** - -For each file, read it, identify tab characters, and replace with appropriate spacing. Tabs inside code blocks (``.. code-block::``) should be replaced with the equivalent visual spacing (typically 2 or 3 spaces depending on context). Tabs in RST structural content should be replaced with 2 spaces. - -**Important:** Be careful with tabs inside table markup or code blocks — preserve visual alignment. - -- [ ] **Step 2: Verify no tabs remain** - -```bash -grep -rP '\t' /Users/syncer/GitHub/vyos-documentation/docs/ --include='*.rst' -l -``` - -Expected: no output (no files with tabs). - -- [ ] **Step 3: Commit** - -```bash -git add -A docs/ -git commit -m "fix: replace tab characters with spaces in 13 RST files" -``` - -### Task 5: Fix typos and metadata formatting (3 files) - -**Files:** All under `docs/` prefix. -- Modify: `configuration/index.rst`, `configuration/system/sysctl.rst`, `configuration/policy/index.rst` - -- [ ] **Step 1: Fix typo in `configuration/index.rst`** - -Line 5: change `respresent` to `represent`. - -- [ ] **Step 2: Fix typo in `configuration/system/sysctl.rst`** - -Line 7: change `chapeter` to `chapter`. - -- [ ] **Step 3: Fix metadata formatting in `configuration/policy/index.rst`** - -Line 1: change `:lastproofread:2021-07-12` to `:lastproofread: 2021-07-12` (add space after colon). - -- [ ] **Step 4: Commit** - -```bash -git add docs/configuration/index.rst docs/configuration/system/sysctl.rst docs/configuration/policy/index.rst -git commit -m "fix: correct typos and metadata formatting in 3 files" -``` - -### Task 6: Create PR for mechanical fixes - -- [ ] **Step 1: Push branch and create PR** - -```bash -git push -u origin fix/docs-mechanical-cleanup -gh pr create --title "Fix heading hierarchy, tabs, and typos across docs" --body "$(cat <<'EOF' -## Summary -- Fix first-heading hierarchy in 35 RST files (must use `#####` overline+underline) -- Replace tab characters with spaces in 13 RST files -- Fix typos: "respresent" → "represent", "chapeter" → "chapter" -- Fix `:lastproofread:` metadata formatting in policy/index.rst - -## Test plan -- [ ] Verify Sphinx build succeeds without warnings -- [ ] Spot-check heading rendering in built HTML -- [ ] Verify no tab characters remain: `grep -rP '\t' docs/ --include='*.rst'` - -🤖 Generated with [Claude Code](https://claude.com/claude-code) -EOF -)" -``` - ---- - -## PR 2: Content Quality (`fix/docs-content-quality`) - -### Task 7: Create branch and add TODO comments (12 files) - -**Files:** All under `docs/` prefix. -- Modify: `configuration/vpn/ipsec/remoteaccess_ipsec.rst`, `configuration/vpn/ipsec/troubleshooting_ipsec.rst`, `configuration/vpn/rsa-keys.rst`, `configuration/vpn/openconnect.rst`, `configuration/nat/nat64.rst`, `configuration/nat/nat66.rst`, `configuration/loadbalancing/wan.rst`, `configuration/firewall/index.rst`, `configuration/service/snmp.rst`, `configuration/policy/examples.rst`, `configuration/interfaces/vti.rst`, `configuration/interfaces/openvpn-examples.rst` - -- [ ] **Step 1: Create feature branch** - -```bash -git checkout current -git checkout -b fix/docs-content-quality current -``` - -- [ ] **Step 2: Add TODO comment to each of the 12 files** - -For each file, add the following line after the first heading block (after the heading underline — which may be `====`, `----`, `****`, or `####` depending on whether PR 1 has been merged — and any blank line): - -```rst -.. TODO:: Convert raw command blocks in this file to cfgcmd/opcmd - directives for command coverage tracking. -``` - -Read each file first to find the correct insertion point — it should go right after the title heading and any introductory label/metadata, before the first content paragraph. - -- [ ] **Step 3: Commit** - -```bash -git add -A docs/ -git commit -m "chore: add TODO markers for 12 files needing cfgcmd/opcmd conversion" -``` - -### Task 8: Fill TBD placeholders (2 files) - -**Files:** All under `docs/` prefix. -- Modify: `configuration/system/flow-accounting.rst`, `configuration/protocols/static.rst` - -- [ ] **Step 1: Fill TBD in `flow-accounting.rst`** - -At line 87, replace `TBD` with: - -```rst - Configure the syslog facility used for flow-accounting log messages. - Available facilities follow standard syslog conventions (e.g., - ``daemon``, ``local0`` through ``local7``). -``` - -(This sits under the `.. cfgcmd::` directive at line 85, so it must be indented with 3 spaces to be part of the directive body.) - -- [ ] **Step 2: Fill TBD in `static.rst`** - -At line 274, replace the standalone `TBD` with nothing — the explanation already follows on line 276-277. Just remove the `TBD` line so the text flows naturally from the heading into the existing content: - -```rst -************************ -Alternate Routing Tables -************************ - -Alternate routing tables are used with policy based routing by utilizing -:ref:`vrf`. -``` - -- [ ] **Step 3: Commit** - -```bash -git add docs/configuration/system/flow-accounting.rst docs/configuration/protocols/static.rst -git commit -m "fix: fill TBD placeholder in flow-accounting, remove TBD in static routes" -``` - -### Task 9: Add stub admonitions (3 files) - -**Files:** All under `docs/` prefix. -- Modify: `installation/virtual/eve-ng.rst`, `installation/cloud/oracle.rst`, `configuration/system/sysctl.rst` - -- [ ] **Step 1: Add stub note to `eve-ng.rst`** - -After line 5 (the `######` underline), add a blank line then: - -```rst -.. note:: This page is a stub and needs expansion. Contributions - welcome via the `VyOS documentation repository - <https://github.com/vyos/vyos-documentation>`_. -``` - -- [ ] **Step 2: Add stub note to `oracle.rst`** - -After line 5 (the `######` underline), add a blank line then the same note. - -- [ ] **Step 3: Add stub note to `sysctl.rst`** - -After line 5 (the `######` underline), add a blank line then the same note. - -- [ ] **Step 4: Commit** - -```bash -git add docs/installation/virtual/eve-ng.rst docs/installation/cloud/oracle.rst docs/configuration/system/sysctl.rst -git commit -m "docs: add stub admonitions to 3 minimal pages" -``` - -### Task 10: Create PR for content quality - -- [ ] **Step 1: Push branch and create PR** - -```bash -git push -u origin fix/docs-content-quality -gh pr create --title "Add TODO markers, fill placeholders, mark stub pages" --body "$(cat <<'EOF' -## Summary -- Add TODO comments to 12 files that use raw command blocks instead of cfgcmd/opcmd directives -- Fill TBD placeholder in flow-accounting.rst with syslog-facility description -- Remove orphan TBD in static.rst (content already follows the heading) -- Add stub admonitions to 3 minimal pages (eve-ng, oracle, sysctl) - -## Test plan -- [ ] Verify Sphinx build succeeds -- [ ] Verify TODO directives render as expected -- [ ] Verify stub notes render correctly - -🤖 Generated with [Claude Code](https://claude.com/claude-code) -EOF -)" -``` - ---- - -## PR 3: Structural Reorganization (`fix/docs-structural-reorg`) - -### Task 11: Create branch and split troubleshooting page - -**Files:** All under `docs/troubleshooting/` prefix. -- Modify: `index.rst` -- Create: `connectivity.rst`, `interfaces.rst`, `monitoring.rst`, `terminal.rst`, `system.rst` - -- [ ] **Step 1: Create feature branch** - -```bash -git checkout current -git checkout -b fix/docs-structural-reorg current -``` - -- [ ] **Step 2: Read `troubleshooting/index.rst` completely** - -Read the full 460-line file to understand exact content boundaries. - -- [ ] **Step 3: Create `troubleshooting/connectivity.rst`** - -Extract lines 12–158 (Connectivity Tests section). Add proper heading: - -```rst -################## -Connectivity Tests -################## -``` - -Keep all `.. opcmd::` directives and code blocks. Promote internal headings: -- `Basic Connectivity Tests` (was `=====`) → use `*****` -- `Advanced Connectivity Tests` (was `=====`) → use `*****` -- `IPv6 Topology Discovery` (was `=====`) → use `*****` -- `Router Discovery` (was `-----`) → use `=====` -- `Neighbor Discovery` (was `-----`) → use `=====` - -- [ ] **Step 4: Create `troubleshooting/interfaces.rst`** - -Extract lines 160–199 (Interface names section): - -```rst -############### -Interface Names -############### - -If you find the names of your interfaces have changed... -``` - -No sub-headings in this section. - -- [ ] **Step 5: Create `troubleshooting/monitoring.rst`** - -Extract lines 201–358 (Monitoring section): - -```rst -########## -Monitoring -########## - -VyOS features several monitoring tools. -``` - -Promote internal headings: -- `Traffic Dumps` (was `=====`) → use `*****` -- `Interface Bandwidth Usage` (was `=====`) → use `*****` -- `Interface Performance` (was `=====`) → use `*****` -- `Monitor command` (was `=====`) → use `*****` - -- [ ] **Step 6: Create `troubleshooting/terminal.rst`** - -Extract lines 360–401 (Terminal/Console section). Lines 402–403 are blank separators and can be dropped. - -```rst -################ -Terminal/Console -################ - -Sometimes you need to clear counters or statistics... -``` - -No sub-headings to promote. - -- [ ] **Step 7: Create `troubleshooting/system.rst`** - -Extract lines 404–460 (System Information section). This MUST include: -- Lines 404–448: the System Information content and Boot Steps -- Lines 449–460: `.. stop_vyoslinter`, all `.. _link:` reference definitions, AND `.. start_vyoslinter` on the final line - -The `.. stop_vyoslinter` / `.. start_vyoslinter` pair must stay balanced — both must be in this file since the reference link definitions between them use bare URLs that would otherwise trigger linter warnings. - -```rst -################## -System Information -################## -``` - -Promote internal headings: -- `Boot Steps` (was `=====`) → use `*****` - -Keep the `.. _boot-steps:` label. Keep the `.. stop_vyoslinter` / `.. start_vyoslinter` directives and all `.. _link:` references at the bottom. - -- [ ] **Step 8: Rewrite `troubleshooting/index.rst`** - -Replace the entire file with: - -```rst -.. _troubleshooting: - -############### -Troubleshooting -############### - -Sometimes things break or don't work as expected. This section describes -several troubleshooting tools provided by VyOS that can help when something -goes wrong. - -.. toctree:: - :maxdepth: 1 - - connectivity - interfaces - monitoring - terminal - system -``` - -- [ ] **Step 9: Commit** - -```bash -git add docs/troubleshooting/ -git commit -m "refactor: split troubleshooting into 5 focused sub-pages - -Split monolithic 460-line troubleshooting/index.rst into: -- connectivity.rst (ping, traceroute, mtr, IPv6 discovery) -- interfaces.rst (interface naming, MAC addresses) -- monitoring.rst (traffic dumps, bandwidth, iperf) -- terminal.rst (console clearing, counter resets) -- system.rst (boot steps, system information)" -``` - -### Task 12: Create `contributing/index.rst` and update root index - -**Files:** -- Create: `docs/contributing/index.rst` -- Modify: `docs/index.rst` - -- [ ] **Step 1: Create `contributing/index.rst`** - -```rst -############ -Contributing -############ - -.. toctree:: - :maxdepth: 1 - - build-vyos - development - cla - issues-features - upstream-packages - debugging - testing -``` - -- [ ] **Step 2: Update root `index.rst`** - -Replace the "Development" toctree section (lines 85–97): - -**Before:** -```rst -.. toctree:: - :maxdepth: 2 - :hidden: - :caption: Development - - contributing/build-vyos - contributing/development - contributing/cla - contributing/issues-features - contributing/upstream-packages - contributing/debugging - contributing/testing -``` - -**After:** -```rst -.. toctree:: - :maxdepth: 2 - :hidden: - :caption: Development - - contributing/index -``` - -- [ ] **Step 3: Commit** - -```bash -git add docs/contributing/index.rst docs/index.rst -git commit -m "refactor: create contributing/index.rst, simplify root toctree" -``` - -### Task 13: Clean up VPN "pages to sort" - -**Files:** All under `docs/configuration/vpn/` prefix. -- Modify: `index.rst`, `ipsec/index.rst` - -- [ ] **Step 1: Fix `configuration/vpn/index.rst`** - -Replace the entire file content with: - -```rst -### -VPN -### - - -.. toctree:: - :maxdepth: 1 - :includehidden: - - dmvpn - ipsec/index - l2tp - openconnect - pptp - rsa-keys - sstp -``` - -This integrates `dmvpn` into the main toctree (sorted alphabetically) and removes the "pages to sort" text and second toctree. - -- [ ] **Step 2: Fix `configuration/vpn/ipsec/index.rst`** - -Replace the entire file content with: - -```rst -##### -IPsec -##### - - -.. toctree:: - :maxdepth: 1 - :includehidden: - - ipsec_general - site2site_ipsec - remoteaccess_ipsec - troubleshooting_ipsec -``` - -This removes the "pages to sort" text and empty second toctree. - -- [ ] **Step 3: Commit** - -```bash -git add docs/configuration/vpn/index.rst docs/configuration/vpn/ipsec/index.rst -git commit -m "fix: remove 'pages to sort' placeholders from VPN section" -``` - -### Task 14: Create PR for structural reorganization - -- [ ] **Step 1: Push branch and create PR** - -```bash -git push -u origin fix/docs-structural-reorg -gh pr create --title "Split troubleshooting, add contributing index, clean VPN structure" --body "$(cat <<'EOF' -## Summary -- Split `troubleshooting/index.rst` (460 lines) into 5 focused sub-pages: connectivity, interfaces, monitoring, terminal, system -- Create `contributing/index.rst` with toctree, simplify root index.rst -- Remove "pages to sort" placeholders from VPN and IPsec index files, integrate dmvpn into main toctree - -## Test plan -- [ ] Verify Sphinx build succeeds without warnings -- [ ] Verify troubleshooting sub-pages render correctly and navigation works -- [ ] Verify contributing section appears correctly in sidebar -- [ ] Verify VPN section navigation is clean -- [ ] Verify `.. _boot-steps:` and `.. _troubleshooting:` cross-references still work - -🤖 Generated with [Claude Code](https://claude.com/claude-code) -EOF -)" -``` - ---- - -## RTD Platform Cleanup (Direct API Actions) - -### Task 15: Capture RTD state and hide inactive versions - -**No files modified — API actions only.** - -RTD API base: `https://app.readthedocs.org/api/v3/projects/vyos` -Auth header: `Authorization: Token $RTD_TOKEN` (token: `$RTD_TOKEN`) - -- [ ] **Step 1: Capture current version state for rollback** - -```bash -curl -s -H "Authorization: Token $RTD_TOKEN" \ - "https://app.readthedocs.org/api/v3/projects/vyos/versions/?limit=100" \ - > /tmp/rtd-versions-backup-$(date +%Y%m%d).json -``` - -- [ ] **Step 2: Hide 16 inactive versions** - -Run PATCH for each version slug to set `hidden: true`: - -```bash -for slug in \ - revert-1544-t6652-current \ - mergify-bp-sagitta-pr-1533 \ - vpp-next \ - 1.4.3 1.4.0 \ - 1.3.8 1.3.7 1.3.6 1.3.5 1.3.4 1.3.3-epa1 1.3.3 1.3.2 \ - 1.2.9-s1 \ - vyos_1.2-2019q4 \ - stable; do - echo "Hiding $slug..." - curl -s -X PATCH \ - -H "Authorization: Token $RTD_TOKEN" \ - -H "Content-Type: application/json" \ - -d '{"hidden": true}' \ - "https://app.readthedocs.org/api/v3/projects/vyos/versions/$slug/" - echo "" -done -``` - -Expected: each call returns 200 OK with JSON body showing the updated version. - -- [ ] **Step 3: Verify versions are hidden** - -```bash -curl -s -H "Authorization: Token $RTD_TOKEN" \ - "https://app.readthedocs.org/api/v3/projects/vyos/versions/?limit=100" \ - | python3 -c "import json,sys; versions=json.load(sys.stdin)['results']; [print(f'{v[\"slug\"]:40s} active={v[\"active\"]} hidden={v[\"hidden\"]}') for v in versions]" -``` - -Expected: 16 slugs show `hidden=True`, 4 active versions show `hidden=False`. - -### Task 16: Delete disabled redirects - -- [ ] **Step 1: List redirects to get IDs** - -```bash -curl -s -H "Authorization: Token $RTD_TOKEN" \ - "https://app.readthedocs.org/api/v3/projects/vyos/redirects/" \ - | python3 -m json.tool -``` - -Find the `pk` values for the two disabled redirects: -- `changelog.html` → `changelog/$(version).html` -- `installation/vyos-on-baremetal.html` → `installation/bare-metal.html` - -- [ ] **Step 2: Delete the two disabled redirects** - -```bash -# Replace <ID1> and <ID2> with actual pk values from step 1 -curl -s -X DELETE \ - -H "Authorization: Token $RTD_TOKEN" \ - "https://app.readthedocs.org/api/v3/projects/vyos/redirects/<ID1>/" - -curl -s -X DELETE \ - -H "Authorization: Token $RTD_TOKEN" \ - "https://app.readthedocs.org/api/v3/projects/vyos/redirects/<ID2>/" -``` - -Expected: 204 No Content for each. - -- [ ] **Step 3: Verify redirects are cleaned up** - -```bash -curl -s -H "Authorization: Token $RTD_TOKEN" \ - "https://app.readthedocs.org/api/v3/projects/vyos/redirects/" \ - | python3 -m json.tool -``` - -Expected: 5 remaining redirects (all enabled). diff --git a/docs/superpowers/specs/2026-03-21-docs-improvements-design.md b/docs/superpowers/specs/2026-03-21-docs-improvements-design.md deleted file mode 100644 index abec6829..00000000 --- a/docs/superpowers/specs/2026-03-21-docs-improvements-design.md +++ /dev/null @@ -1,227 +0,0 @@ -# VyOS Documentation Improvements — Design Spec - -**Date:** 2026-03-21 -**Scope:** Documentation quality, consistency, structure, and RTD platform cleanup -**Delivery:** 3 separate PRs + direct RTD API actions - ---- - -## PR 1: Mechanical Fixes (`fix/docs-mechanical-cleanup`) - -### Heading Hierarchy (35 files) - -Every RST file must start with `#####` (overline + underline) as its first heading. Fix 35 files that use `=`, `*`, or `-` instead. - -**Affected files:** - -Using `=` as first heading (23 files): -- `automation/command-scripting.rst` -- `automation/terraform/terraformAWS.rst` -- `automation/terraform/terraformAZ.rst` -- `automation/terraform/terraformGoogle.rst` -- `automation/terraform/terraformvSphere.rst` -- `automation/terraform/terraformvyos.rst` -- `automation/vyos-ansible.rst` -- `automation/vyos-govyos.rst` -- `automation/vyos-napalm.rst` -- `automation/vyos-netmiko.rst` -- `automation/vyos-pyvyos.rst` -- `automation/vyos-salt.rst` -- `configexamples/firewall.rst` -- `configexamples/index.rst` -- `configexamples/wan-load-balancing.rst` -- `configuration/highavailability/index.rst` -- `configuration/interfaces/openvpn-examples.rst` -- `configuration/interfaces/tunnel.rst` -- `configuration/loadbalancing/wan.rst` -- `configuration/service/mdns.rst` -- `configuration/vpn/ipsec/remoteaccess_ipsec.rst` -- `installation/update.rst` -- `vpp/configuration/ipfix.rst` - -Using `-` as first heading (7 files): -- `configexamples/azure-vpn-bgp.rst` -- `configexamples/azure-vpn-dual-bgp.rst` -- `configexamples/fwall-and-bridge.rst` -- `configexamples/fwall-and-vrf.rst` -- `configexamples/policy-based-ipsec-and-firewall.rst` -- `configexamples/site-2-site-cisco.rst` -- `configexamples/zone-policy.rst` - -Using `*` as first heading (5 files): -- `configuration/system/lcd.rst` -- `installation/virtual/docker.rst` -- `installation/virtual/libvirt.rst` -- `installation/virtual/proxmox.rst` -- `operation/information.rst` - -**Approach:** For each file, replace the first heading underline/overline character with `#`, keeping the same length. Adjust subsequent heading levels downward if needed to maintain proper hierarchy. - -### Tab Indentation (13 files) - -Replace tab characters with appropriate space indentation in RST files: - -- `configuration/trafficpolicy/index.rst` -- `configuration/service/eventhandler.rst` -- `configuration/interfaces/wireless.rst` -- `cli.rst` -- `installation/install.rst` -- `automation/terraform/terraformGoogle.rst` -- `automation/terraform/terraformAWS.rst` -- `automation/terraform/terraformAZ.rst` -- `automation/terraform/terraformvSphere.rst` -- `configexamples/nmp.rst` -- `configexamples/ansible.rst` -- `configexamples/qos.rst` -- `configexamples/l3vpn-hub-and-spoke.rst` - -### Typos (2 files) - -- `configuration/index.rst`: "respresent" → "represent" -- `configuration/system/sysctl.rst` line 7: "chapeter" → "chapter" - -### Metadata Formatting (1 file) - -- `configuration/policy/index.rst` line 1: `:lastproofread:2021-07-12` → `:lastproofread: 2021-07-12` (add missing space) - ---- - -## PR 2: Content Quality (`fix/docs-content-quality`) - -### TODO Comments for Raw Command Blocks (12 files) - -Add `.. TODO:: Convert raw command blocks to cfgcmd/opcmd directives` near the top of these files: - -- `configuration/vpn/ipsec/remoteaccess_ipsec.rst` -- `configuration/vpn/ipsec/troubleshooting_ipsec.rst` -- `configuration/vpn/rsa-keys.rst` -- `configuration/vpn/openconnect.rst` -- `configuration/nat/nat64.rst` -- `configuration/nat/nat66.rst` -- `configuration/loadbalancing/wan.rst` -- `configuration/firewall/index.rst` -- `configuration/service/snmp.rst` -- `configuration/policy/examples.rst` -- `configuration/interfaces/vti.rst` -- `configuration/interfaces/openvpn-examples.rst` - -### Fill TBD Placeholders (2 files) - -- `configuration/system/flow-accounting.rst` line 87: Replace `TBD` with description of the `syslog-facility` parameter (controls which syslog facility flow-accounting messages are sent to). -- `configuration/protocols/static.rst` line 274: Replace `TBD` with brief content about alternate routing tables (VRF-based routing table selection for static routes). - -### Stub Page Admonitions (3 files) - -Add `.. note:: This page is a stub and needs expansion. Contributions welcome.` to: - -- `installation/virtual/eve-ng.rst` -- `installation/cloud/oracle.rst` -- `configuration/system/sysctl.rst` - ---- - -## PR 3: Structural Reorganization (`fix/docs-structural-reorg`) - -### Split `troubleshooting/index.rst` - -Current file: 460 lines covering 5 distinct topics. Split into: - -| New File | Content | Source Lines | -|---|---|---| -| `troubleshooting/index.rst` | Intro + toctree only | Lines 1–9 (rewritten) | -| `troubleshooting/connectivity.rst` | Ping, traceroute, mtr, IPv6 discovery | Lines 12–158 | -| `troubleshooting/interfaces.rst` | Interface names, MAC address issues | Lines 160–199 | -| `troubleshooting/monitoring.rst` | Traffic dumps, bandwidth, iperf, monitor command | Lines 201–358 | -| `troubleshooting/terminal.rst` | Console clearing, counter resets | Lines 360–401 | -| `troubleshooting/system.rst` | Boot steps, system information | Lines 404–460 | - -**Heading levels in sub-pages:** Each sub-page starts with `#####` as its title. Internal sections are promoted accordingly: current `*****` sections become `*****` (unchanged if already second-level) or promoted to match. Current `=====` sub-sections become `*****`, and `-----` become `=====`. The goal is each sub-page has a self-contained heading hierarchy starting from `#####`. - -New `troubleshooting/index.rst` content: - -```rst -.. _troubleshooting: - -############### -Troubleshooting -############### - -Sometimes things break or don't work as expected. This section describes -several troubleshooting tools provided by VyOS that can help when something -goes wrong. - -.. toctree:: - :maxdepth: 1 - - connectivity - interfaces - monitoring - terminal - system -``` - -Each sub-page gets a proper `#####` title heading. - -### Create `contributing/index.rst` - -Create `contributing/index.rst` with title and toctree listing the 7 existing contributing pages. Update root `index.rst` "Development" toctree to reference `contributing/index` instead of listing individual pages. Note: `documentation.rst` stays in the "Misc" toctree — it is a general writing guide, not a contributing-specific page. - -### Clean up VPN "pages to sort" - -- `configuration/vpn/index.rst`: Remove "pages to sort" text, integrate `dmvpn` into the main toctree -- `configuration/vpn/ipsec/index.rst`: Remove empty second toctree - ---- - -## RTD Platform Cleanup (Direct API Actions) - -### Hide Inactive Versions (16 versions) - -Set `hidden: true` via PATCH on these inactive version slugs: - -- `revert-1544-t6652-current` -- `mergify-bp-sagitta-pr-1533` -- `vpp-next` -- `1.4.3`, `1.4.0` -- `1.3.8`, `1.3.7`, `1.3.6`, `1.3.5`, `1.3.4`, `1.3.3-epa1`, `1.3.3`, `1.3.2` -- `1.2.9-s1` -- `vyos_1.2-2019q4` -- `stable` - -Note: `current` is NOT hidden — it is the primary branch (`current` tracks VyOS 1.5.x rolling). The `latest` slug already points to this branch and is the active version; `current` is already inactive but should not be hidden in case it is referenced by external links. - -**Verification before applying:** Capture current state of all versions via `GET /api/v3/projects/vyos/versions/?limit=100` and save the response locally before making any PATCH calls. This provides a rollback reference. - -### Delete Disabled Redirects (2 redirects) - -Delete redirect IDs for: -- `changelog.html` → `changelog/$(version).html` (disabled, broken) -- `installation/vyos-on-baremetal.html` → `installation/bare-metal.html` (disabled, obsolete) - -### No Action Items - -- **Translations:** Locale directories kept as-is for future use -- **PDF for 1.2:** Left as-is (EOL version) - ---- - -## Execution Order - -1. **PR 1** (mechanical fixes) — no dependencies, merge first -2. **PR 2** (content quality) — no dependencies on PR 1, can be parallel -3. **PR 3** (structural reorg) — should go after PR 1 to avoid merge conflicts on shared files -4. **RTD cleanup** — independent, can run anytime - -## Success Criteria - -- All 35 heading hierarchy violations fixed -- Zero tab characters in RST files (13 files cleaned) -- Zero typos in the identified files -- 12 files flagged with TODO for directive conversion -- Zero TBD placeholders remaining -- 3 stub pages clearly marked -- `troubleshooting/` split into 5 focused sub-pages -- `contributing/` has proper index page -- VPN section has no "pages to sort" placeholders -- RTD: 16 stale inactive versions hidden from version selector -- No disabled redirects remain diff --git a/docs/troubleshooting/connectivity.rst b/docs/troubleshooting/connectivity.rst new file mode 100644 index 00000000..aa2a0151 --- /dev/null +++ b/docs/troubleshooting/connectivity.rst @@ -0,0 +1,150 @@ +################## +Connectivity Tests +################## + +************************ +Basic Connectivity Tests +************************ + +Verifying connectivity can be done with the familiar `ping` and `traceroute` +commands. The options for each are shown (the options for each command were +displayed using the built-in help as described in the :ref:`cli` +section and are omitted from the output here): + +.. opcmd:: ping <destination> + + Send ICMP echo requests to destination host. There are multiple options to + ping, including VRF support. + + .. code-block:: none + + vyos@vyos:~$ ping 10.1.1.1 + Possible completions: + <Enter> Execute the current command + adaptive Ping options + allow-broadcast + audible + bypass-route + count + deadline + do-not-fragment + flood + interface + interval + mark + no-loopback + numeric + pattern + quiet + record-route + size + timestamp + tos + ttl + verbose + vrf + + +.. opcmd:: traceroute <destination> + + Trace path to target. + + .. code-block:: none + + vyos@vyos:~$ traceroute + Possible completions: + <hostname> Track network path to specified node + <x.x.x.x> + <h:h:h:h:h:h:h:h> + ipv4 Track network path to <hostname|IPv4 address> + ipv6 Track network path to <hostname|IPv6 address> + + +*************************** +Advanced Connectivity Tests +*************************** + +.. opcmd:: monitor traceroute <destination> + + However, another helper is available which combines ping and traceroute + into a single tool. An example of its output is shown: + + .. code-block:: none + + vyos@vyos:~$ mtr 10.62.212.12 + + My traceroute [v0.85] + vyos (0.0.0.0) + Keys: Help Display mode Restart statistics Order of fields quit + Packets Pings + Host Loss% Snt Last Avg Best Wrst StDev + 1. 10.11.110.4 0.0% 34 0.5 0.5 0.4 0.8 0.1 + 2. 10.62.255.184 0.0% 34 1.1 1.0 0.9 1.4 0.1 + 3. 10.62.255.71 0.0% 34 1.4 1.4 1.3 2.0 0.1 + 4. 10.62.212.12 0.0% 34 1.6 1.6 1.6 1.7 0.0 + + .. note:: The output consumes the screen and will replace your command + prompt. + + Several options are available for changing the display output. Press `h` to + invoke the built in help system. To quit, just press `q` and you'll be + returned to the VyOS command prompt. + +*********************** +IPv6 Topology Discovery +*********************** + +IPv6 uses different techniques to discover its Neighbors/topology. + +Router Discovery +================ + +.. opcmd:: force ipv6-rd interface <interface> [address <ipv6-address>] + + Discover routers via eth0. + + Example: + + .. code-block:: none + + vyos@vyos:~$ force ipv6-rd interface eth0 + Soliciting ff02::2 (ff02::2) on eth0... + + Hop limit : 60 ( 0x3c) + Stateful address conf. : No + Stateful other conf. : No + Mobile home agent : No + Router preference : high + Neighbor discovery proxy : No + Router lifetime : 1800 (0x00000708) seconds + Reachable time : unspecified (0x00000000) + Retransmit time : unspecified (0x00000000) + Prefix : 240e:fe:8ca7:ea01::/64 + On-link : Yes + Autonomous address conf.: Yes + Valid time : 2592000 (0x00278d00) seconds + Pref. time : 14400 (0x00003840) seconds + Prefix : fc00:470:f1cd:101::/64 + On-link : Yes + Autonomous address conf.: Yes + Valid time : 2592000 (0x00278d00) seconds + Pref. time : 14400 (0x00003840) seconds + Recursive DNS server : fc00:470:f1cd::ff00 + DNS server lifetime : 600 (0x00000258) seconds + Source link-layer address: 00:98:2B:F8:3F:11 + from fe80::298:2bff:fef8:3f11 + +Neighbor Discovery +================== + +.. opcmd:: force ipv6-nd interface <interface> address <ipv6-address> + + + Example: + + .. code-block:: none + + vyos@vyos:~$ force ipv6-nd interface eth0 address fc00:470:f1cd:101::1 + + Soliciting fc00:470:f1cd:101::1 (fc00:470:f1cd:101::1) on eth0... + Target link-layer address: 00:98:2B:F8:3F:11 from fc00:470:f1cd:101::1 diff --git a/docs/troubleshooting/index.rst b/docs/troubleshooting/index.rst index 8a34edd9..791afc56 100644 --- a/docs/troubleshooting/index.rst +++ b/docs/troubleshooting/index.rst @@ -8,453 +8,11 @@ Sometimes things break or don't work as expected. This section describes several troubleshooting tools provided by VyOS that can help when something goes wrong. -****************** -Connectivity Tests -****************** - -Basic Connectivity Tests -======================== - -Verifying connectivity can be done with the familiar `ping` and `traceroute` -commands. The options for each are shown (the options for each command were -displayed using the built-in help as described in the :ref:`cli` -section and are omitted from the output here): - -.. opcmd:: ping <destination> - - Send ICMP echo requests to destination host. There are multiple options to - ping, inkl. VRF support. - - .. code-block:: none - - vyos@vyos:~$ ping 10.1.1.1 - Possible completions: - <Enter> Execute the current command - adaptive Ping options - allow-broadcast - audible - bypass-route - count - deadline - do-not-fragment - flood - interface - interval - mark - no-loopback - numeric - pattern - quiet - record-route - size - timestamp - tos - ttl - verbose - vrf - - -.. opcmd:: traceroute <destination> - - Trace path to target. - - .. code-block:: none - - vyos@vyos:~$ traceroute - Possible completions: - <hostname> Track network path to specified node - <x.x.x.x> - <h:h:h:h:h:h:h:h> - ipv4 Track network path to <hostname|IPv4 address> - ipv6 Track network path to <hostname|IPv6 address> - - -Advanced Connectivity Tests -=========================== - -.. opcmd:: monitor traceroute <destination> - - However, another helper is available which combines ping and traceroute - into a single tool. An example of its output is shown: - - .. code-block:: none - - vyos@vyos:~$ mtr 10.62.212.12 - - My traceroute [v0.85] - vyos (0.0.0.0) - Keys: Help Display mode Restart statistics Order of fields quit - Packets Pings - Host Loss% Snt Last Avg Best Wrst StDev - 1. 10.11.110.4 0.0% 34 0.5 0.5 0.4 0.8 0.1 - 2. 10.62.255.184 0.0% 34 1.1 1.0 0.9 1.4 0.1 - 3. 10.62.255.71 0.0% 34 1.4 1.4 1.3 2.0 0.1 - 4. 10.62.212.12 0.0% 34 1.6 1.6 1.6 1.7 0.0 - - .. note:: The output consumes the screen and will replace your command - prompt. - - Several options are available for changing the display output. Press `h` to - invoke the built in help system. To quit, just press `q` and you'll be - returned to the VyOS command prompt. - -IPv6 Topology Discovery -======================= - -IPv6 uses different techniques to discover its Neighbors/topology. - -Router Discovery ----------------- - -.. opcmd:: force ipv6-rd interface <interface> [address <ipv6-address>] - - Discover routers via eth0. - - Example: - - .. code-block:: none - - vyos@vyos:~$ force ipv6-rd interface eth0 - Soliciting ff02::2 (ff02::2) on eth0... - - Hop limit : 60 ( 0x3c) - Stateful address conf. : No - Stateful other conf. : No - Mobile home agent : No - Router preference : high - Neighbor discovery proxy : No - Router lifetime : 1800 (0x00000708) seconds - Reachable time : unspecified (0x00000000) - Retransmit time : unspecified (0x00000000) - Prefix : 240e:fe:8ca7:ea01::/64 - On-link : Yes - Autonomous address conf.: Yes - Valid time : 2592000 (0x00278d00) seconds - Pref. time : 14400 (0x00003840) seconds - Prefix : fc00:470:f1cd:101::/64 - On-link : Yes - Autonomous address conf.: Yes - Valid time : 2592000 (0x00278d00) seconds - Pref. time : 14400 (0x00003840) seconds - Recursive DNS server : fc00:470:f1cd::ff00 - DNS server lifetime : 600 (0x00000258) seconds - Source link-layer address: 00:98:2B:F8:3F:11 - from fe80::298:2bff:fef8:3f11 - -Neighbor Discovery ------------------- - -.. opcmd:: force ipv6-nd interface <interface> address <ipv6-address> - - - Example: - - .. code-block:: none - - vyos@vyos:~$ force ipv6-nd interface eth0 address fc00:470:f1cd:101::1 - - Soliciting fc00:470:f1cd:101::1 (fc00:470:f1cd:101::1) on eth0... - Target link-layer address: 00:98:2B:F8:3F:11 from fc00:470:f1cd:101::1 - - -*************** -Interface names -*************** - -If you find the names of your interfaces have changed, this could be because -your MAC addresses have changed. - -* For example, you have a VyOS VM with 4 Ethernet interfaces named - eth0, eth1, eth2 and eth3. Then, you migrate your VyOS VM to a different - host and find your interfaces now are eth4, eth5, eth6 and eth7. - - One way to fix this issue **taking control of the MAC addresses** is: - - Log into VyOS and run this command to display your interface settings. - - .. code-block:: 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. - - .. code-block:: 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. - -.. code-block:: none - - vyos@vyos:~$ monitor - Possible completions: - bandwidth Monitor interface bandwidth in real time - bandwidth-test - Initiate or wait for bandwidth test - cluster Monitor clustering service - command Monitor an operational mode command (refreshes every 2 seconds) - conntrack-sync - Monitor conntrack-sync - content-inspection - Monitor Content-Inspection - dhcp Monitor Dynamic Host Control Protocol (DHCP) - dns Monitor a Domain Name Service (DNS) daemon - firewall Monitor Firewall - https Monitor the Secure Hypertext Transfer Protocol (HTTPS) service - lldp Monitor Link Layer Discovery Protocol (LLDP) daemon - log Monitor last lines of messages file - nat Monitor network address translation (NAT) - ndp Monitor the NDP information received by the router through the device - openvpn Monitor OpenVPN - protocol Monitor routing protocols - snmp Monitor Simple Network Management Protocol (SNMP) daemon - stop-all Stop all current background monitoring processes - traceroute Monitor the path to a destination in realtime - traffic Monitor traffic dumps - vpn Monitor VPN - vrrp Monitor Virtual Router Redundancy Protocol (VRRP) - webproxy Monitor Webproxy service - - -Traffic Dumps -============= - -To monitor interface traffic, issue the :code:`monitor traffic interface <name>` -command, replacing `<name>` with your chosen interface. - -.. code-block:: none - - vyos@vyos:~$ monitor traffic interface eth0 - tcpdump: verbose output suppressed, use -v or -vv for full protocol decode - listening on eth0, link-type EN10MB (Ethernet), capture size 262144 bytes - 15:54:28.581601 IP 192.168.0.1 > vyos: ICMP echo request, id 1870, seq 3848, length 64 - 15:54:28.581660 IP vyos > 192.168.0.1: ICMP echo reply, id 1870, seq 3848, length 64 - 15:54:29.583399 IP 192.168.0.1 > vyos: ICMP echo request, id 1870, seq 3849, length 64 - 15:54:29.583454 IP vyos > 192.168.0.1: ICMP echo reply, id 1870, seq 3849, length 64 - ^C - 4 packets captured - 4 packets received by filter - 0 packets dropped by kernel - vyos@vyos:~$ - -To quit monitoring, press `Ctrl-c` and you'll be returned to the VyOS command -prompt. - -Traffic can be filtered and saved. - -.. code-block:: 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 - -.. code-block:: none - - vyos@vyos:~$ monitor bandwidth interface eth0 - -show the following: - -.. code-block:: 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. - -.. code-block:: 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. - -.. code-block:: 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. - -.. code-block:: none - - vyos@router:~$ monitor command "show interfaces" - -Will clear the screen and show you the output of ``show interfaces`` every -2 seconds. - -.. code-block:: 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 - -.. code-block:: none - - vyos@vyos:~$ clear console - -to clear interface counters - -.. code-block:: 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. - -.. code-block:: 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 - -.. code-block:: none - - vyos@vyos:~$ clear firewall name <ipv4 ruleset name> counters - vyos@vyos:~$ clear firewall name <ipv4 ruleset name> rule <rule#> counters - - vyos@vyos:~$ clear firewall ipv6-name <ipv6 ruleset name> counters - vyos@vyos:~$ clear firewall ipv6-name <ipv6 ruleset name> rule <rule#> counters - - -****************** -System Information -****************** - -.. _boot-steps: - -Boot Steps -========== - -VyOS 1.2 uses `Debian Jessie`_ as the base Linux operating system. Jessie was -the first version of Debian that uses systemd_ as the default init system. - -These are the boot steps for VyOS 1.2 - -1. The BIOS loads Grub (or isolinux for the Live CD) -2. Grub then starts the Linux boot and loads the Linux Kernel ``/boot/vmlinuz`` -3. Kernel Launches Systemd ``/lib/systemd/systemd`` -4. Systemd loads the VyOS service file - ``/lib/systemd/system/vyos-router.service`` -5. The service file launches the VyOS router init script - ``/usr/libexec/vyos/init/vyos-router`` - this is part of the vyatta-cfg_ - Debian package - - 1. Starts FRR_ - successor to `GNU Zebra`_ and Quagga_ - - 2. Initialises the boot configuration file - copies over - ``config.boot.default`` if there is no configuration - 3. Runs the configuration migration, if the configuration is for an older - version of VyOS - 4. Runs The pre-config script, if there is one - ``/config/scripts/vyos-preconfig-bootup.script`` - 5. If the config file was upgraded, runs any post upgrade scripts - ``/config/scripts/post-upgrade.d`` - 6. Starts ``rl-system`` and ``firewall`` - 7. Mounts the ``/boot`` partition - 8. The boot configuration file is then applied by ``/opt/vyatta/sbin/ - vyatta-boot-config-loader/opt/vyatta/etc/config/config.boot`` - - 1. The config loader script writes log entries to - ``/var/log/vyatta-config-loader.log`` - - 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`` - -.. stop_vyoslinter - -.. _Quagga: https://www.quagga.net/ -.. _`GNU Zebra`: https://www.gnu.org/software/zebra/ -.. _FRR: https://frrouting.org/ -.. _vyatta-cfg: https://github.com/vyos/vyatta-cfg -.. _systemd: https://freedesktop.org/wiki/Software/systemd/ -.. _`Debian Jessie`: https://www.debian.org/releases/jessie/ -.. _tshark: https://www.wireshark.org/docs/man-pages/tshark.html -.. _`PCAP filter expressions`: http://www.tcpdump.org/manpages/pcap-filter.7.html - -.. start_vyoslinter +.. toctree:: + :maxdepth: 1 + + connectivity + interfaces + monitoring + terminal + system diff --git a/docs/troubleshooting/interfaces.rst b/docs/troubleshooting/interfaces.rst new file mode 100644 index 00000000..95aceb12 --- /dev/null +++ b/docs/troubleshooting/interfaces.rst @@ -0,0 +1,39 @@ +############### +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. + + .. code-block:: 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. + + .. code-block:: none + + set interfaces ethernet 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. diff --git a/docs/troubleshooting/monitoring.rst b/docs/troubleshooting/monitoring.rst new file mode 100644 index 00000000..ef40c937 --- /dev/null +++ b/docs/troubleshooting/monitoring.rst @@ -0,0 +1,161 @@ +########## +Monitoring +########## + +VyOS features several monitoring tools. + +.. code-block:: none + + vyos@vyos:~$ monitor + Possible completions: + bandwidth Monitor interface bandwidth in real time + bandwidth-test + Initiate or wait for bandwidth test + cluster Monitor clustering service + command Monitor an operational mode command (refreshes every 2 seconds) + conntrack-sync + Monitor conntrack-sync + content-inspection + Monitor Content-Inspection + dhcp Monitor Dynamic Host Control Protocol (DHCP) + dns Monitor a Domain Name Service (DNS) daemon + firewall Monitor Firewall + https Monitor the Secure Hypertext Transfer Protocol (HTTPS) service + lldp Monitor Link Layer Discovery Protocol (LLDP) daemon + log Monitor last lines of messages file + nat Monitor network address translation (NAT) + ndp Monitor the NDP information received by the router through the device + openvpn Monitor OpenVPN + protocol Monitor routing protocols + snmp Monitor Simple Network Management Protocol (SNMP) daemon + stop-all Stop all current background monitoring processes + traceroute Monitor the path to a destination in realtime + traffic Monitor traffic dumps + vpn Monitor VPN + vrrp Monitor Virtual Router Redundancy Protocol (VRRP) + webproxy Monitor Webproxy service + + +************* +Traffic Dumps +************* + +To monitor interface traffic, issue the :code:`monitor traffic interface <name>` +command, replacing `<name>` with your chosen interface. + +.. code-block:: 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 :kbd:`Ctrl-C` and you'll be returned to the VyOS command +prompt. + +Traffic can be filtered and saved. + +.. code-block:: 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 quickly view the bandwidth usage of an interface, use the ``monitor bandwidth`` command: + +.. code-block:: none + + vyos@vyos:~$ monitor bandwidth interface eth0 + +This shows the following: + +.. code-block:: 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. + +.. code-block:: 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. + +.. code-block:: 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. + +.. code-block:: none + + vyos@router:~$ monitor command "show interfaces" + +Will clear the screen and show you the output of ``show interfaces`` every +2 seconds. + +.. code-block:: 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 diff --git a/docs/troubleshooting/system.rst b/docs/troubleshooting/system.rst new file mode 100644 index 00000000..3a9ec735 --- /dev/null +++ b/docs/troubleshooting/system.rst @@ -0,0 +1,57 @@ +################## +System Information +################## + +.. _boot-steps: + +********** +Boot Steps +********** + +VyOS 1.2 uses `Debian Jessie`_ as the base Linux operating system. Jessie was +the first version of Debian that uses systemd_ as the default init system. + +These are the boot steps for VyOS 1.2 + +1. The BIOS loads Grub (or isolinux for the Live CD) +2. Grub then starts the Linux boot and loads the Linux Kernel ``/boot/vmlinuz`` +3. Kernel Launches Systemd ``/lib/systemd/systemd`` +4. Systemd loads the VyOS service file + ``/lib/systemd/system/vyos-router.service`` +5. The service file launches the VyOS router init script + ``/usr/libexec/vyos/init/vyos-router`` - this is part of the vyatta-cfg_ + Debian package + + 1. Starts FRR_ - successor to `GNU Zebra`_ and Quagga_ + + 2. Initialises the boot configuration file - copies over + ``config.boot.default`` if there is no configuration + 3. Runs the configuration migration, if the configuration is for an older + version of VyOS + 4. Runs The pre-config script, if there is one + ``/config/scripts/vyos-preconfig-bootup.script`` + 5. If the config file was upgraded, runs any post upgrade scripts + ``/config/scripts/post-upgrade.d`` + 6. Starts ``rl-system`` and ``firewall`` + 7. Mounts the ``/boot`` partition + 8. The boot configuration file is then applied by ``/opt/vyatta/sbin/vyatta-boot-config-loader/opt/vyatta/etc/config/config.boot`` + + 1. The config loader script writes log entries to + ``/var/log/vyatta-config-loader.log`` + + 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`` + +.. stop_vyoslinter + +.. _Quagga: https://www.quagga.net/ +.. _`GNU Zebra`: https://www.gnu.org/software/zebra/ +.. _FRR: https://frrouting.org/ +.. _vyatta-cfg: https://github.com/vyos/vyatta-cfg +.. _systemd: https://freedesktop.org/wiki/Software/systemd/ +.. _`Debian Jessie`: https://www.debian.org/releases/jessie/ +.. _tshark: https://www.wireshark.org/docs/man-pages/tshark.html +.. _`PCAP filter expressions`: http://www.tcpdump.org/manpages/pcap-filter.7.html + +.. start_vyoslinter diff --git a/docs/troubleshooting/terminal.rst b/docs/troubleshooting/terminal.rst new file mode 100644 index 00000000..fb197730 --- /dev/null +++ b/docs/troubleshooting/terminal.rst @@ -0,0 +1,42 @@ +################ +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 + +.. code-block:: none + + vyos@vyos:~$ clear console + +to clear interface counters + +.. code-block:: none + + # clear all interfaces + vyos@vyos:~$ clear interface ethernet counters + # clear specific interface + vyos@vyos:~$ clear interface ethernet eth0 counters + +The command follows the same logic as the ``set`` command in configuration mode. + +.. code-block:: none + + # clear all counters of an interface type + vyos@vyos:~$ clear interface <interface_type> counters + # clear counter of an interface in interface_type + vyos@vyos:~$ clear interface <interface_type> <interface_name> counters + + +to clear counters on firewall rulesets or single rules + +.. code-block:: 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 diff --git a/docs/vpp/configuration/ipfix.rst b/docs/vpp/configuration/ipfix.rst index 2085740a..92c734be 100644 --- a/docs/vpp/configuration/ipfix.rst +++ b/docs/vpp/configuration/ipfix.rst @@ -1,5 +1,6 @@ +####################### VPP IPFIX Configuration -======================= +####################### VPP IPFIX in VyOS allows monitoring and exporting network traffic flows for analytics, security, and accounting. IPFIX works with the VPP @@ -18,7 +19,8 @@ Key IPFIX Concepts - **Active timeout**: Maximum time a flow is kept active before export. - **Inactive timeout**: Maximum time an idle flow is kept before export. - **Collector**: The remote host and port to which flow records are sent. -- **Flow layers**: Determines which layer information is included (`l2`, `l3`, `l4`). +- **Flow layers**: Determines which layer information is included + (``l2``, ``l3``, ``l4``). - **Interfaces**: Physical or virtual interfaces to monitor. - **Direction**: Which traffic to monitor (`rx`, `tx`, `both`). - **Flow variant**: Optional filter for IPv4 or IPv6 flows. @@ -26,12 +28,16 @@ Key IPFIX Concepts Configuration Options --------------------- -- **active-timeout**: Duration (in seconds) after which active flows are exported. -- **inactive-timeout**: Duration (in seconds) after which idle flows are exported. +- **active-timeout**: Duration (in seconds) after which active flows + are exported. +- **inactive-timeout**: Duration (in seconds) after which idle flows + are exported. - **collector `<ip>` port `<port>`**: IP and UDP port of the IPFIX collector. - **collector `<ip>` source-address `<ip>`**: Source address for flow export. - **flowprobe-record `<l2|l3|l4>`**: Layers to include in flow records. -- **interface `<interface>` [direction `<rx|tx|both>`] [flow-variant `<ipv4|ipv6>`]**: Interfaces to monitor, direction of traffic, and optional flow variant filter. +- **interface** ``<interface>`` **[direction** ``<rx|tx|both>``\ **]** + **[flow-variant** ``<ipv4|ipv6>``\ **]**: Interfaces to monitor, + direction of traffic, and optional flow variant filter. Example Configuration --------------------- diff --git a/requirements.txt b/requirements.txt index c719ad77..78fe8dbe 100644 --- a/requirements.txt +++ b/requirements.txt @@ -5,4 +5,6 @@ sphinx-autobuild==2021.3.14 sphinx-notfound-page==1.0.0 lxml==5.1.0 myst-parser==2.0.0 -sphinx_design==0.5.0
\ No newline at end of file +sphinx_design==0.5.0 +sphinx-llms-txt==0.7.1 +sphinx-sitemap==2.9.0
\ No newline at end of file |