diff options
| author | Yuriy Andamasov <yuriy@vyos.io> | 2026-05-10 17:19:31 +0300 |
|---|---|---|
| committer | Yuriy Andamasov <yuriy@vyos.io> | 2026-05-10 17:19:31 +0300 |
| commit | 3fd1787d50dda76619647dd95ea6e1d421204734 (patch) | |
| tree | 3e4f5341e2b4c5618ba1fa6b52a5cda63c4c1c29 /docs/configuration | |
| parent | d7e63e1923814a791dadf93453e8c090d26ca896 (diff) | |
| download | vyos-documentation-3fd1787d50dda76619647dd95ea6e1d421204734.tar.gz vyos-documentation-3fd1787d50dda76619647dd95ea6e1d421204734.zip | |
chore: remove RST swap mechanism, archive rst-*.rst under docs/_rst_legacy/
The swap mechanism (RST-as-fallback for migrated MD pages) is dormant —
docs/_rst_overrides.txt has been empty since the MyST flip trio
(#1899/#1900/#1901) landed in May 2026. The mechanism's surface area
(scripts/swap_sources.py, its 245-line test, RTD pre/post hooks,
Makefile glue, conf.py dynamic loader) is dead weight, and the
rst-*.rst shadows scattered across the source tree cause Context7's
parser to misclassify the project as RST.
Changes:
- Move 253 rst-*.rst shadow files into docs/_rst_legacy/ preserving
subdirectory structure. They remain in the repo for reference; Sphinx
excludes the folder via exclude_patterns; Context7 excludes it via
excludeFolders.
- Strip swap_sources.py invocation from docs/Makefile (swap/restore
targets, : swap deps, trap chains).
- Strip jobs: pre_build/post_build block from .readthedocs.yml.
- Strip rst-*.rst exclude entry and the _md_exclude.txt loader from
docs/conf.py; replace with a single _rst_legacy exclude.
- Delete scripts/swap_sources.py, tests/test_swap_sources.py,
docs/_rst_overrides.txt.
- Update context7.json: add docs/_rst_legacy to excludeFolders;
fix stale "Branch current tracks…" rule to "Branch rolling tracks…"
(default branch was renamed 2026-05-10).
- Update AGENTS.md: drop the "RST override mechanism" section and the
test-runner snippet for the deleted test; describe _rst_legacy as
archive only.
Verified: sphinx-build -b html with --keep-going produces identical
warning set (68 unique), identical sitemap entry count (257), identical
llms.txt entry count (22), zero rst-* URLs in any artifact.
🤖 Generated by [robots](https://vyos.io)
Diffstat (limited to 'docs/configuration')
130 files changed, 0 insertions, 38314 deletions
diff --git a/docs/configuration/container/rst-index.rst b/docs/configuration/container/rst-index.rst deleted file mode 100644 index 398f1941..00000000 --- a/docs/configuration/container/rst-index.rst +++ /dev/null @@ -1,417 +0,0 @@ -:lastproofread: 2024-07-03 - -######### -Container -######### - -The VyOS container implementation is based on `Podman <https://podman.io/>`_ as -a deamonless container engine. - -************* -Configuration -************* - -.. cfgcmd:: set container name <name> image - - Sets the image name in the hub registry - - .. code-block:: none - - set container name mysql-server image mysql:8.0 - - If a registry is not specified, Docker.io will be used as the container - registry unless an alternative registry is specified using - **set container registry <name>** or the registry is included - in the image name - - .. code-block:: none - - set container name mysql-server image quay.io/mysql:8.0 - -.. cfgcmd:: set container name <name> entrypoint <entrypoint> - - Override the default entrypoint from the image for a container. - -.. cfgcmd:: set container name <name> command <command> - - Override the default command from the image for a container. - -.. cfgcmd:: set container name <name> arguments <arguments> - - Set the command arguments for a container. - -.. cfgcmd:: set container name <name> host-name <hostname> - - Set the host name for a container. - -.. cfgcmd:: set container name <name> allow-host-pid - - The container and the host share the same process namespace. - This means that processes running on the host are visible inside the - container, and processes inside the container are visible on the host. - - The command translates to "--pid host" when the container is created. - -.. cfgcmd:: set container name <name> allow-host-networks - - Allow host networking in a container. The network stack of the container is - not isolated from the host and will use the host IP. - - The command translates to "--net host" when the container is created. - - .. note:: **allow-host-networks** cannot be used with **network** - -.. cfgcmd:: set container name <name> network <networkname> - - Attaches user-defined network to a container. - Only one network must be specified and must already exist. - -.. cfgcmd:: set container name <name> network <networkname> address <address> - - Optionally set a specific static IPv4 or IPv6 address for the container. - This address must be within the named network prefix. - - .. note:: The first IP in the container network is reserved by the - engine and cannot be used - -.. cfgcmd:: set container name <name> name-server <address> - - Optionally set a custom name server. - If a container network is used with DNS enabled, - this setting will not have any effect. - -.. cfgcmd:: set container name <name> description <text> - - Set a container description - -.. cfgcmd:: set container name <name> environment <key> value <value> - - Add custom environment variables. - Multiple environment variables are allowed. - The following commands translate to "-e key=value" when the container - is created. - - .. code-block:: none - - set container name mysql-server environment MYSQL_DATABASE value 'zabbix' - set container name mysql-server environment MYSQL_USER value 'zabbix' - set container name mysql-server environment MYSQL_PASSWORD value 'zabbix_pwd' - set container name mysql-server environment MYSQL_ROOT_PASSWORD value 'root_pwd' - -.. cfgcmd:: set container name <name> port <portname> source <portnumber> -.. cfgcmd:: set container name <name> port <portname> destination <portnumber> -.. cfgcmd:: set container name <name> port <portname> protocol <tcp | udp> - - Publish a port for the container. - - .. code-block:: none - - set container name zabbix-web-nginx-mysql port http source 80 - set container name zabbix-web-nginx-mysql port http destination 8080 - set container name zabbix-web-nginx-mysql port http protocol tcp - -.. note:: Port publishing cannot be used with **network**. For this purpose, a workaround - using destination NAT and static IP assignment for the container is available. - -.. cfgcmd:: set container name <name> volume <volumename> source <path> -.. cfgcmd:: set container name <name> volume <volumename> destination <path> - - Mount a volume into the container - - .. code-block:: none - - set container name coredns volume 'corefile' source /config/coredns/Corefile - set container name coredns volume 'corefile' destination /etc/Corefile - -.. cfgcmd:: set container name <name> volume <volumename> mode <ro | rw> - - Volume is either mounted as rw (read-write - default) or ro (read-only) - -.. cfgcmd:: set container name <name> tmpfs <tmpfsname> destination <path> - - Mount a tmpfs *(ramdisk)* filesystem to the given path within the container. - -.. cfgcmd:: set container name <name> tmpfs <tmpfsname> size <MB> - - Size in MB for tmpfs filesystem, maximum size is 64GB or 50% of the - systems total available memory. - -.. cfgcmd:: set container name <name> uid <number> -.. cfgcmd:: set container name <name> gid <number> - - Set the User ID or Group ID of the container - -.. cfgcmd:: set container name <name> restart [no | on-failure | always] - - Set the restart behavior of the container. - - - **no**: Do not restart containers on exit - - **on-failure**: Restart containers when they exit with a non-zero - exit code, retrying indefinitely (default) - - **always**: Restart containers when they exit, regardless of status, - retrying indefinitely - -.. cfgcmd:: set container name <name> cpu-quota <num> - - This specifies the number of CPU resources the container can use. - - Default is 0 for unlimited. - For example, 1.25 limits the container to use up to 1.25 cores - worth of CPU time. - This can be a decimal number with up to three decimal places. - - The command translates to "--cpus=<num>" when the container is created. - -.. cfgcmd:: set container name <name> memory <MB> - - Constrain the memory available to the container. - - Default is 512 MB. Use 0 MB for unlimited memory. - -.. cfgcmd:: set container name <name> device <devicename> source <path> -.. cfgcmd:: set container name <name> device <devicename> destination <path> - - Add a host device to the container. - -.. cfgcmd:: set container name <name> capability <text> - - Set container capabilities or permissions. - - - **net-admin**: Network operations (interface, firewall, routing tables) - - **net-bind-service**: Bind a socket to privileged ports - (port numbers less than 1024) - - **net-raw**: Permission to create raw network sockets - - **setpcap**: Capability sets (from bounded or inherited set) - - **sys-admin**: Administration operations (quotactl, mount, sethostname, - setdomainame) - - **sys-time**: Permission to set system clock - -.. cfgcmd:: set container name <name> sysctl parameter <parameter> value <value> - - Set container sysctl values. - - The subset of possible parameters are: - - - Kernel Parameters: kernel.msgmax, kernel.msgmnb, kernel.msgmni, kernel.sem, - kernel.shmall, kernel.shmmax, kernel.shmmni, kernel.shm_rmid_forced - - Parameters beginning with fs.mqueue.* - - Parameters beginning with net.* (only if user-defined network is used) - -.. cfgcmd:: set container name <name> label <label> value <value> - - Add metadata label for this container. - -.. cfgcmd:: set container name <name> disable - - Disable a container. - -Container Health checks -======================= - -By default, no health checks are run, even when defined by the image. - -.. cfgcmd:: set container name <name> health-check - - Default health check is run for the container if defined by the image. - -.. cfgcmd:: set container name <name> health-check command <command> - - Override the default health check command from the image for a container. - -.. cfgcmd:: set container name <name> health check interval <interval> - - Override the default health-check interval. For example: `60` - -.. cfgcmd:: set container name <name> health check timeout <timeout> - - Override the default health-check timeout. For example: `10` - -.. cfgcmd:: set container name <name> health check retries <retries> - - Number of health check retries before container is considered unhealthy. For example: `1` - -Container Networks -================== - -.. cfgcmd:: set container network <name> - - Creates a named container network - -.. cfgcmd:: set container network <name> description - - A brief description what this network is all about. - -.. cfgcmd:: set container network <name> prefix <ipv4|ipv6> - - Define IPv4 and/or IPv6 prefix for a given network name. - Both IPv4 and IPv6 can be used in parallel. - -.. cfgcmd:: set container network <name> mtu <number> - - Configure :abbr:`MTU (Maximum Transmission Unit)` for a given network. It - is the size (in bytes) of the largest ethernet frame sent on this link. - -.. cfgcmd:: set container network <name> no-name-server - - Disable Domain Name System (DNS) plugin for this network. - -.. cfgcmd:: set container network <name> vrf <nme> - - Bind container network to a given VRF instance. - -Container Registry -================== - -.. cfgcmd:: set container registry <name> - - Adds registry to list of unqualified-search-registries. By default, for any - image that does not include the registry in the image name, VyOS will use - docker.io and quay.io as the container registry. - -.. cfgcmd:: set container registry <name> disable - - Disable a given container registry - -.. cfgcmd:: set container registry <name> authentication username -.. cfgcmd:: set container registry <name> authentication password - - Some container registries require credentials to be used. - - Credentials can be defined here and will only be used when adding a - container image to the system. - -.. cfgcmd:: set container registry <name> insecure - - Allow registry access over unencrypted HTTP or TLS connections with - untrusted certificates. - -.. cfgcmd:: set container registry <name> mirror address <address> - -.. cfgcmd:: set container registry <name> mirror host-name <host-name> - -.. cfgcmd:: set container registry <name> mirror port <port> - -.. cfgcmd:: set container registry <name> mirror path <path> - - Registry mirror, use ``(host-name|address)[:port][/path]``. - - If you have mirror http://192.168.1.1:8080 for docker.io, you can use ``docker.io/some/repo`` or run ``podman pull docker.io/some/repo`` - - .. code-block:: none - - set container registry docker.io mirror address 192.168.1.1 - set container registry docker.io mirror port 8080 - set container registry docker.io insecure - - If http://192.168.1.1:8080 is your own registry, you can use ``192.168.1.1:8080/some/repo`` or run ``podman pull 192.168.1.1:8080/some/repo`` - - .. code-block:: none - - set container registry 192.168.1.1:8080 insecure - - -Log Configuration -==================== - -.. cfgcmd:: set container name <name> log-driver [k8s-file | journald | none] - - Set the default log driver for containers. - - - **k8s-file**: Log to a plain text file in Kubernetes-style format. - - **journald**: Log to the system journal - - **none**: Disable logging for the container - - Current default is journald. - - -****************** -Operation Commands -****************** - -.. opcmd:: add container image <containername> - - Pull a new image for container - -.. opcmd:: show container - - Show the list of all active containers. - -.. opcmd:: show container image - - Show the local container images. - -.. opcmd:: show container log <containername> - - Show logs from a given container - -.. opcmd:: show container network - - Show a list available container networks - -.. opcmd:: restart container <containername> - - Restart a given container - -.. opcmd:: update container image <containername> - - Update container image - -.. opcmd:: delete container image <image id|all> [force] - - Delete a particular container image based on it's image ID. - You can also delete all container images at once. - - You can not delete a container image if it has more then one tag - assigned, this is why there is a `force` option to pass down to - the container image to also remove those images. - -********************* -Example Configuration -********************* - - For the sake of demonstration, `example #1 in the official documentation - <https://www.zabbix.com/documentation/current/manual/ - installation/containers>`_ - to the declarative VyOS CLI syntax. - - .. code-block:: none - - set container network zabbix prefix 172.20.0.0/16 - set container network zabbix description 'Network for Zabbix component containers' - - set container name mysql-server image mysql:8.0 - set container name mysql-server network zabbix - - set container name mysql-server environment 'MYSQL_DATABASE' value 'zabbix' - set container name mysql-server environment 'MYSQL_USER' value 'zabbix' - set container name mysql-server environment 'MYSQL_PASSWORD' value 'zabbix_pwd' - set container name mysql-server environment 'MYSQL_ROOT_PASSWORD' value 'root_pwd' - - set container name zabbix-java-gateway image zabbix/zabbix-java-gateway:alpine-5.2-latest - set container name zabbix-java-gateway network zabbix - - set container name zabbix-server-mysql image zabbix/zabbix-server-mysql:alpine-5.2-latest - set container name zabbix-server-mysql network zabbix - - set container name zabbix-server-mysql environment 'DB_SERVER_HOST' value 'mysql-server' - set container name zabbix-server-mysql environment 'MYSQL_DATABASE' value 'zabbix' - set container name zabbix-server-mysql environment 'MYSQL_USER' value 'zabbix' - set container name zabbix-server-mysql environment 'MYSQL_PASSWORD' value 'zabbix_pwd' - set container name zabbix-server-mysql environment 'MYSQL_ROOT_PASSWORD' value 'root_pwd' - set container name zabbix-server-mysql environment 'ZBX_JAVAGATEWAY' value 'zabbix-java-gateway' - - set container name zabbix-server-mysql port zabbix source 10051 - set container name zabbix-server-mysql port zabbix destination 10051 - - set container name zabbix-web-nginx-mysql image zabbix/zabbix-web-nginx-mysql:alpine-5.2-latest - set container name zabbix-web-nginx-mysql network zabbix - - set container name zabbix-web-nginx-mysql environment 'MYSQL_DATABASE' value 'zabbix' - set container name zabbix-web-nginx-mysql environment 'ZBX_SERVER_HOST' value 'zabbix-server-mysql' - set container name zabbix-web-nginx-mysql environment 'DB_SERVER_HOST' value 'mysql-server' - set container name zabbix-web-nginx-mysql environment 'MYSQL_USER' value 'zabbix' - set container name zabbix-web-nginx-mysql environment 'MYSQL_PASSWORD' value 'zabbix_pwd' - set container name zabbix-web-nginx-mysql environment 'MYSQL_ROOT_PASSWORD' value 'root_pwd' - - set container name zabbix-web-nginx-mysql port http source 80 - set container name zabbix-web-nginx-mysql port http destination 8080 diff --git a/docs/configuration/firewall/rst-bridge.rst b/docs/configuration/firewall/rst-bridge.rst deleted file mode 100644 index 53775514..00000000 --- a/docs/configuration/firewall/rst-bridge.rst +++ /dev/null @@ -1,573 +0,0 @@ -:lastproofread: 2026-03-28 - -.. _firewall-configuration: - -############################# -Bridge Firewall Configuration -############################# - -******** -Overview -******** - -Learn more about bridge firewall configuration -and related op-mode commands. - -The following commands are covered in this section: - -.. 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: - -.. code-block:: none - - - set firewall - * bridge - - forward - + filter - - input - + filter - - output - + filter - - prerouting - + filter - - name - + custom_name - -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. -The relevant configuration that acts in **prerouting** is: - - * ``set firewall bridge prerouting filter ...``. - -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**, and the -base command is ``set firewall bridge input filter ...`` and the path is: - -.. figure:: /_static/images/firewall-bridge-input.* - -If it's not dropped, then the packet is sent to **IP Layer**, and will be -processed by the **IP Layer** firewall: IPv4 or IPv6 ruleset. Check once again -the :doc:`general packet flow diagram</configuration/firewall/index>` if -needed. - -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> ...``. To use such a custom chain, a rule with action jump -and the appropriate target must be defined in a base chain. - -************ -Bridge 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. - -Actions -======= - -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: - - * ``accept``: accept the packet. - - * ``continue``: continue parsing next rule. - - * ``drop``: drop the packet. - - * ``jump``: jump to another custom chain. - - * ``return``: Return from the current chain and continue at the next rule - of the last chain. - - * ``queue``: Enqueue packet to userspace. - - * ``notrack``: ignore connection tracking system. This action is only - available in prerouting chain. - -.. cfgcmd:: set firewall bridge forward filter rule <1-999999> action - [accept | continue | drop | jump | queue | return] -.. cfgcmd:: set firewall bridge input filter rule <1-999999> action - [accept | continue | drop | jump | queue | return] -.. cfgcmd:: set firewall bridge output filter rule <1-999999> action - [accept | continue | drop | jump | queue | return] -.. cfgcmd:: set firewall bridge prerouting filter rule <1-999999> action - [accept | continue | drop | jump | notrack | queue | return] -.. cfgcmd:: set firewall bridge name <name> rule <1-999999> action - [accept | continue | drop | jump | queue | return] - - This required setting defines the action of the current rule. If action is - set to jump, then jump-target is also needed. - -.. cfgcmd:: set firewall bridge forward filter rule <1-999999> - jump-target <text> -.. cfgcmd:: set firewall bridge input filter rule <1-999999> - jump-target <text> -.. cfgcmd:: set firewall bridge output filter rule <1-999999> - jump-target <text> -.. cfgcmd:: set firewall bridge prerouting filter rule <1-999999> - jump-target <text> -.. cfgcmd:: set firewall bridge name <name> rule <1-999999> - jump-target <text> - - If action is set to ``queue``, use next command to specify the queue - target. Range is also supported: - -.. cfgcmd:: set firewall bridge forward filter rule <1-999999> - queue <0-65535> -.. cfgcmd:: set firewall bridge input filter rule <1-999999> - queue <0-65535> -.. cfgcmd:: set firewall bridge output filter rule <1-999999> - queue <0-65535> -.. cfgcmd:: set firewall bridge prerouting filter rule <1-999999> - queue <0-65535> -.. cfgcmd:: set firewall bridge name <name> rule <1-999999> - queue <0-65535> - - Also, if action is set to ``queue``, use next command to specify the queue - options. Possible options are ``bypass`` and ``fanout``: - -.. cfgcmd:: set firewall bridge forward filter rule <1-999999> - queue-options bypass -.. cfgcmd:: set firewall bridge input filter rule <1-999999> - queue-options bypass -.. cfgcmd:: set firewall bridge output filter rule <1-999999> - queue-options bypass -.. cfgcmd:: set firewall bridge prerouting filter rule <1-999999> - queue-options bypass -.. cfgcmd:: set firewall bridge name <name> rule <1-999999> - queue-options bypass - -.. cfgcmd:: set firewall bridge forward filter rule <1-999999> - queue-options fanout -.. cfgcmd:: set firewall bridge input filter rule <1-999999> - queue-options fanout -.. cfgcmd:: set firewall bridge output filter rule <1-999999> - queue-options fanout -.. cfgcmd:: set firewall bridge prerouting filter rule <1-999999> - queue-options fanout -.. cfgcmd:: set firewall bridge name <name> rule <1-999999> - 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 -**default-action** are **accept** or **drop**. - -.. cfgcmd:: set firewall bridge forward filter default-action - [accept | drop] -.. cfgcmd:: set firewall bridge input filter default-action - [accept | drop] -.. cfgcmd:: set firewall bridge output filter default-action - [accept | drop] -.. cfgcmd:: set firewall bridge prerouting filter default-action - [accept | drop] -.. cfgcmd:: set firewall bridge name <name> default-action - [accept | continue | drop | jump | reject | return] - - This sets the default action of the rule-set if a packet does not match - any of the rules in that chain. If default-action is set to ``jump``, then - ``default-jump-target`` is also needed. Note that for base chains, default - action can only be set to ``accept`` or ``drop``, while on custom chains - more actions are available. - -.. cfgcmd:: set firewall bridge name <name> default-jump-target <text> - - To be used only when ``default-action`` is set to ``jump``. Use this - command to specify jump target for 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 the - default action is not defined, then the default-action is set to **drop**. - -Firewall Logs -============= - -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 -.. cfgcmd:: set firewall bridge output filter rule <1-999999> log -.. cfgcmd:: set firewall bridge prerouting filter rule <1-999999> log -.. cfgcmd:: set firewall bridge 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. - -.. cfgcmd:: set firewall bridge forward filter default-log -.. cfgcmd:: set firewall bridge input filter default-log -.. cfgcmd:: set firewall bridge output filter default-log -.. cfgcmd:: set firewall bridge prerouting filter default-log -.. cfgcmd:: set firewall bridge name <name> default-log - - Use this command to enable the logging of the default action on - the specified chain. - -.. cfgcmd:: set firewall bridge forward filter rule <1-999999> - log-options level [emerg | alert | crit | err | warn | notice - | info | debug] -.. cfgcmd:: set firewall bridge input filter rule <1-999999> - log-options level [emerg | alert | crit | err | warn | notice - | info | debug] -.. cfgcmd:: set firewall bridge output filter rule <1-999999> - log-options level [emerg | alert | crit | err | warn | notice - | info | debug] -.. cfgcmd:: set firewall bridge prerouting filter rule <1-999999> - log-options level [emerg | alert | crit | err | warn | notice - | info | debug] -.. cfgcmd:: set firewall bridge name <name> rule <1-999999> - log-options level [emerg | alert | crit | err | warn | notice - | info | debug] - - Define log-level. Only applicable if rule log is enabled. - -.. cfgcmd:: set firewall bridge forward filter rule <1-999999> - log-options group <0-65535> -.. cfgcmd:: set firewall bridge input filter rule <1-999999> - log-options group <0-65535> -.. cfgcmd:: set firewall bridge output filter rule <1-999999> - log-options group <0-65535> -.. cfgcmd:: set firewall bridge prerouting filter rule <1-999999> - log-options group <0-65535> -.. cfgcmd:: set firewall bridge 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. - -.. cfgcmd:: set firewall bridge forward filter rule <1-999999> - log-options snapshot-length <0-9000> -.. cfgcmd:: set firewall bridge input filter rule <1-999999> - log-options snapshot-length <0-9000> -.. cfgcmd:: set firewall bridge output filter rule <1-999999> - log-options snapshot-length <0-9000> -.. cfgcmd:: set firewall bridge prerouting filter rule <1-999999> - log-options snapshot-length <0-9000> -.. cfgcmd:: set firewall bridge name <name> rule <1-999999> - log-options snapshot-length <0-9000> - - Define length of packet payload to include in netlink message. Only - applicable if rule log is enabled and the log group is defined. - -.. cfgcmd:: set firewall bridge forward filter rule <1-999999> - log-options queue-threshold <0-65535> -.. cfgcmd:: set firewall bridge input filter rule <1-999999> - log-options queue-threshold <0-65535> -.. cfgcmd:: set firewall bridge output filter rule <1-999999> - log-options queue-threshold <0-65535> -.. cfgcmd:: set firewall bridge prerouting filter rule <1-999999> - log-options queue-threshold <0-65535> -.. cfgcmd:: set firewall bridge name <name> rule <1-999999> - 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 the log group is - defined. - -Firewall Description -==================== - -You can define a description for reference for every custom chain. - -.. cfgcmd:: set firewall bridge name <name> description <text> - - Provide a rule-set description to a custom firewall chain. - -.. cfgcmd:: set firewall bridge forward filter rule <1-999999> - description <text> -.. cfgcmd:: set firewall bridge input filter rule <1-999999> - description <text> -.. cfgcmd:: set firewall bridge output filter rule <1-999999> - description <text> -.. cfgcmd:: set firewall bridge prerouting filter rule <1-999999> - description <text> -.. cfgcmd:: set firewall bridge name <name> rule <1-999999> - description <text> - - Provide a description for each rule. - -Rule Status -=========== - -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 -.. cfgcmd:: set firewall bridge output filter rule <1-999999> disable -.. cfgcmd:: set firewall bridge prerouting filter rule <1-999999> disable -.. cfgcmd:: set firewall bridge name <name> rule <1-999999> disable - - Command for disabling a rule but keep it in the configuration. - -Matching criteria -================= - -There are 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 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 -described in this section: - -.. cfgcmd:: set firewall bridge forward filter rule <1-999999> ethernet-type - [802.1q | 802.1ad | arp | ipv4 | ipv6] -.. cfgcmd:: set firewall bridge input filter rule <1-999999> ethernet-type - [802.1q | 802.1ad | arp | ipv4 | ipv6] -.. cfgcmd:: set firewall bridge output filter rule <1-999999> ethernet-type - [802.1q | 802.1ad | arp | ipv4 | ipv6] -.. cfgcmd:: set firewall bridge prerouting filter rule <1-999999> ethernet-type - [802.1q | 802.1ad | arp | ipv4 | ipv6] -.. cfgcmd:: set firewall bridge name <name> rule <1-999999> ethernet-type - [802.1q | 802.1ad | arp | ipv4 | ipv6] - - Match based on the Ethernet type of the packet. - -.. cfgcmd:: set firewall bridge forward filter rule <1-999999> vlan - ethernet-type [802.1q | 802.1ad | arp | ipv4 | ipv6] -.. cfgcmd:: set firewall bridge input filter rule <1-999999> vlan - ethernet-type [802.1q | 802.1ad | arp | ipv4 | ipv6] -.. cfgcmd:: set firewall bridge output filter rule <1-999999> vlan - ethernet-type [802.1q | 802.1ad | arp | ipv4 | ipv6] -.. cfgcmd:: set firewall bridge prerouting filter rule <1-999999> vlan - ethernet-type [802.1q | 802.1ad | arp | ipv4 | ipv6] -.. cfgcmd:: set firewall bridge name <name> rule <1-999999> vlan - ethernet-type [802.1q | 802.1ad | arp | ipv4 | ipv6] - - Match based on the Ethernet type of the packet when it is VLAN tagged. - -.. cfgcmd:: set firewall bridge forward filter rule <1-999999> vlan id - <0-4096> -.. cfgcmd:: set firewall bridge input filter rule <1-999999> vlan id - <0-4096> -.. cfgcmd:: set firewall bridge output filter rule <1-999999> vlan id - <0-4096> -.. cfgcmd:: set firewall bridge prerouting filter rule <1-999999> vlan id - <0-4096> -.. cfgcmd:: set firewall bridge name <name> rule <1-999999> vlan id - <0-4096> - - Match based on VLAN identifier. Range is also supported. - -.. cfgcmd:: set firewall bridge forward filter rule <1-999999> vlan priority - <0-7> -.. cfgcmd:: set firewall bridge input filter rule <1-999999> vlan priority - <0-7> -.. cfgcmd:: set firewall bridge output filter rule <1-999999> vlan priority - <0-7> -.. cfgcmd:: set firewall bridge prerouting filter rule <1-999999> vlan priority - <0-7> -.. cfgcmd:: set firewall bridge name <name> rule <1-999999> vlan priority - <0-7> - - Match based on VLAN priority (Priority Code Point - PCP). Range is also - supported. - -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. - -.. cfgcmd:: set firewall bridge [prerouting | forward | output] filter - rule <1-999999> set dscp <0-63> - - Set a specific value of Differentiated Services Codepoint (DSCP). - -.. cfgcmd:: set firewall bridge [prerouting | forward | output] filter - rule <1-999999> set mark <1-2147483647> - - Set a specific packet mark value. - -.. cfgcmd:: set firewall bridge [prerouting | forward | output] filter - rule <1-999999> set tcp-mss <500-1460> - - Set the TCP-MSS (TCP maximum segment size) for the connection. - -.. cfgcmd:: set firewall bridge [prerouting | forward | output] filter - rule <1-999999> set ttl <0-255> - - Set the TTL (Time to Live) value. - -.. cfgcmd:: set firewall bridge [prerouting | forward | output] filter - rule <1-999999> set hop-limit <0-255> - - Set hop limit value. - -.. cfgcmd:: set firewall bridge [forward | output] filter - rule <1-999999> set connection-mark <0-2147483647> - - Set connection mark value. - - -Use IP firewall -=============== - -By default, for switched traffic, only the rules defined under ``set firewall -bridge`` are applied. There are two global-options that can be configured in -order to force deeper analysis of the packet on the IP layer. These options -are: - -.. cfgcmd:: set firewall global-options apply-to-bridged-traffic 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 option - is used, packets are also parsed by rules defined in ``set firewall ipv6 - ...`` - -*********************** -Operation-mode Firewall -*********************** - -Rule-set overview -================= - -In this section you can find all useful firewall op-mode commands. - -General commands for firewall configuration, counter and statistics: - -.. opcmd:: show firewall -.. opcmd:: show firewall summary -.. opcmd:: show firewall statistics - -And, to print only bridge firewall information: - -.. opcmd:: show firewall bridge -.. opcmd:: show firewall bridge forward filter -.. opcmd:: show firewall bridge forward filter rule <rule> -.. opcmd:: show firewall bridge name <name> -.. opcmd:: show firewall bridge name <name> rule <rule> - -Show Firewall log -================= - -.. opcmd:: show log firewall -.. opcmd:: show log firewall bridge -.. opcmd:: show log firewall bridge forward -.. opcmd:: show log firewall bridge forward filter -.. opcmd:: show log firewall bridge name <name> -.. opcmd:: show log firewall bridge forward filter rule <rule> -.. opcmd:: show log firewall bridge name <name> rule <rule> - - Show the logs of all firewall; show all bridge firewall logs; show all logs - for forward hook; show all logs for forward hook and priority filter; show - all logs for particular custom chain; show logs for specific Rule-Set. - -Example -======= - -Configuration example: - -.. code-block:: none - - set firewall bridge forward filter default-action 'drop' - set firewall bridge forward filter default-log - set firewall bridge forward filter rule 10 action 'continue' - set firewall bridge forward filter rule 10 inbound-interface name 'eth2' - set firewall bridge forward filter rule 10 vlan id '22' - set firewall bridge forward filter rule 20 action 'drop' - set firewall bridge forward filter rule 20 inbound-interface group 'TRUNK-RIGHT' - set firewall bridge forward filter rule 20 vlan id '60' - set firewall bridge forward filter rule 30 action 'jump' - set firewall bridge forward filter rule 30 jump-target 'TEST' - set firewall bridge forward filter rule 30 outbound-interface name '!eth1' - set firewall bridge forward filter rule 35 action 'accept' - set firewall bridge forward filter rule 35 vlan id '11' - set firewall bridge forward filter rule 40 action 'continue' - set firewall bridge forward filter rule 40 destination mac-address '66:55:44:33:22:11' - set firewall bridge forward filter rule 40 source mac-address '11:22:33:44:55:66' - set firewall bridge name TEST default-action 'accept' - set firewall bridge name TEST default-log - set firewall bridge name TEST rule 10 action 'continue' - set firewall bridge name TEST rule 10 log - set firewall bridge name TEST rule 10 vlan priority '0' - -And op-mode commands: - -.. code-block:: none - - vyos@BRI:~$ show firewall bridge - Rulesets bridge Information - - --------------------------------- - bridge Firewall "forward filter" - - Rule Action Protocol Packets Bytes Conditions - ------- -------- ---------- --------- ------- --------------------------------------------------------------------- - 10 continue all 0 0 iifname "eth2" vlan id 22 continue - 20 drop all 0 0 iifname @I_TRUNK-RIGHT vlan id 60 - 30 jump all 2130 170688 oifname != "eth1" jump NAME_TEST - 35 accept all 2080 168616 vlan id 11 accept - 40 continue all 0 0 ether daddr 66:55:44:33:22:11 ether saddr 11:22:33:44:55:66 continue - default drop all 0 0 - - --------------------------------- - bridge Firewall "name TEST" - - Rule Action Protocol Packets Bytes Conditions - ------- -------- ---------- --------- ------- -------------------------------------------------- - 10 continue all 2130 170688 vlan pcp 0 prefix "[bri-NAM-TEST-10-C]" continue - default accept all 2130 170688 - - vyos@BRI:~$ - vyos@BRI:~$ show firewall bridge name TEST - Ruleset Information - - --------------------------------- - bridge Firewall "name TEST" - - Rule Action Protocol Packets Bytes Conditions - ------- -------- ---------- --------- ------- -------------------------------------------------- - 10 continue all 2130 170688 vlan pcp 0 prefix "[bri-NAM-TEST-10-C]" continue - default accept all 2130 170688 - - vyos@BRI:~$ - -Inspect logs: - -.. stop_vyoslinter - -.. code-block:: none - - vyos@BRI:~$ show log firewall bridge - Dec 05 14:37:47 kernel: [bri-NAM-TEST-10-C]IN=eth1 OUT=eth2 ARP HTYPE=1 PTYPE=0x0800 OPCODE=1 MACSRC=50:00:00:04:00:00 IPSRC=10.11.11.101 MACDST=00:00:00:00:00:00 IPDST=10.11.11.102 - Dec 05 14:37:48 kernel: [bri-NAM-TEST-10-C]IN=eth1 OUT=eth2 ARP HTYPE=1 PTYPE=0x0800 OPCODE=1 MACSRC=50:00:00:04:00:00 IPSRC=10.11.11.101 MACDST=00:00:00:00:00:00 IPDST=10.11.11.102 - Dec 05 14:37:49 kernel: [bri-NAM-TEST-10-C]IN=eth1 OUT=eth2 ARP HTYPE=1 PTYPE=0x0800 OPCODE=1 MACSRC=50:00:00:04:00:00 IPSRC=10.11.11.101 MACDST=00:00:00:00:00:00 IPDST=10.11.11.102 - ... - vyos@BRI:~$ show log firewall bridge forward filter - Dec 05 14:42:22 kernel: [bri-FWD-filter-default-D]IN=eth2 OUT=eth1 MAC=33:33:00:00:00:16:50:00:00:06:00:00:86:dd SRC=0000:0000:0000:0000:0000:0000:0000:0000 DST=ff02:0000:0000:0000:0000:0000:0000:0016 LEN=96 TC=0 HOPLIMIT=1 FLOWLBL=0 PROTO=ICMPv6 TYPE=143 CODE=0 - Dec 05 14:42:22 kernel: [bri-FWD-filter-default-D]IN=eth2 OUT=eth1 MAC=33:33:00:00:00:16:50:00:00:06:00:00:86:dd SRC=0000:0000:0000:0000:0000:0000:0000:0000 DST=ff02:0000:0000:0000:0000:0000:0000:0016 LEN=96 TC=0 HOPLIMIT=1 FLOWLBL=0 PROTO=ICMPv6 TYPE=143 CODE=0 - -.. start_vyoslinter diff --git a/docs/configuration/firewall/rst-flowtables.rst b/docs/configuration/firewall/rst-flowtables.rst deleted file mode 100644 index f996a59e..00000000 --- a/docs/configuration/firewall/rst-flowtables.rst +++ /dev/null @@ -1,188 +0,0 @@ -:lastproofread: 2026-03-30 - -.. _firewall-flowtables-configuration: - -################################# -Flowtables Firewall Configuration -################################# - -.. include:: /_include/need_improvement.txt - -******** -Overview -******** - -This section provides information on firewall configuration for flowtables. - -.. cfgcmd:: set firewall flowtable ... - -To learn about the general traffic flow in VyOS firewalls, -see :doc:`Firewall </configuration/firewall/index>`. - -.. code-block:: none - - - set firewall - * flowtable - - custom_flow_table - + ... - - -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.* - -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). - -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 - - -*********************** -Flowtable Configuration -*********************** - -To use flowtables, you need to configure the following: - - * Create a flowtable that includes the interfaces - that are going to be used by the flowtable. - - * 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> - - Specify interfaces to use in the flowtable. - -.. cfgcmd:: set firewall flowtable <flow_table_name> description <text> - -Provide a description for the flow table. - -.. cfgcmd:: set firewall flowtable <flow_table_name> offload - <hardware | software> - - Specify the offload type the flowtable uses: ``hardware`` or - ``software``. The default is ``software`` offload. - -.. 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 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 a firewall rule in the forward chain and specify which flowtable - to use. Only applicable if the action is ``offload``. - -********************* -Configuration Example -********************* - -Consider the following in this setup: - - * This example uses two interfaces in the flowtables: ``eth0`` and ``eth1``. - - * The example provides a minimal firewall ruleset with filtering rules - and rules for using flowtable offload capabilities. - -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. - -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 --------- - -.. code-block:: none - - set firewall flowtable FT01 interface 'eth0' - set firewall flowtable FT01 interface 'eth1' - set firewall ipv4 forward filter default-action 'drop' - set firewall ipv4 forward filter rule 10 action 'offload' - set firewall ipv4 forward filter rule 10 offload-target 'FT01' - set firewall ipv4 forward filter rule 10 state 'established' - set firewall ipv4 forward filter rule 10 state 'related' - set firewall ipv4 forward filter rule 20 action 'accept' - set firewall ipv4 forward filter rule 20 state 'established' - set firewall ipv4 forward filter rule 20 state 'related' - set firewall ipv4 forward filter rule 110 action 'accept' - set firewall ipv4 forward filter rule 110 destination address '192.0.2.100' - set firewall ipv4 forward filter rule 110 destination port '1122' - set firewall ipv4 forward filter rule 110 inbound-interface name 'eth0' - set firewall ipv4 forward filter rule 110 protocol 'tcp' - -Explanation ------------ - -Here's what happens for a desired connection: - - 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. For this first packet, the connection state is **new**. Neither rule 10 - nor rule 20 applies. - - 3. Rule 110 matches, so the connection is accepted. - - 4. When the server 192.0.2.100 replies, the connection state becomes - **established**, and rule 20 accepts the reply. - - 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. Subsequent packets skip the traditional path and use the **Fast Path** - for offloading. - -Checks ------- - -Check the conntrack table to verify that the system accepted and properly -offloaded connections. - -.. code-block:: none - - vyos@FlowTables:~$ show firewall ipv4 forward filter - Ruleset Information - - --------------------------------- - ipv4 Firewall "forward filter" - - Rule Action Protocol Packets Bytes Conditions - ------- -------- ---------- --------- ------- ---------------------------------------------------------------- - 10 offload all 8 468 ct state { established, related } flow add @VYOS_FLOWTABLE_FT01 - 20 accept all 8 468 ct state { established, related } accept - 110 accept tcp 2 120 ip daddr 192.0.2.100 tcp dport 1122 iifname "eth0" accept - default drop all 7 420 - - vyos@FlowTables:~$ sudo conntrack -L | grep tcp - conntrack v1.4.6 (conntrack-tools): 5 flow entries have been shown. - tcp 6 src=198.51.100.100 dst=192.0.2.100 sport=41676 dport=1122 src=192.0.2.100 dst=198.51.100.100 sport=1122 dport=41676 [OFFLOAD] mark=0 use=2 - vyos@FlowTables:~$ diff --git a/docs/configuration/firewall/rst-global-options.rst b/docs/configuration/firewall/rst-global-options.rst deleted file mode 100644 index 8eec5c3f..00000000 --- a/docs/configuration/firewall/rst-global-options.rst +++ /dev/null @@ -1,182 +0,0 @@ -:lastproofread: 2026-03-30 - -.. _firewall-global-options-configuration: - -##################################### -Global Options Firewall Configuration -##################################### - -******** -Overview -******** - -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: - -.. cfgcmd:: set firewall global-options ... - -************* -Configuration -************* - -.. cfgcmd:: set firewall global-options all-ping [enable | disable] - - By default, when VyOS receives an ICMP echo request packet destined for - itself, it answers with an ICMP echo reply, unless your firewall prevents - it. - - 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 LOCAL traffic - and always behaves in the most restrictive way - - .. code-block:: none - - set firewall global-options all-ping enable - - 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 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] - - Apply IPv4 or IPv6 firewall rules to bridged traffic. - -.. cfgcmd:: set firewall global-options broadcast-ping [enable | disable] - - 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] - - 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`` - -.. cfgcmd:: set firewall global-options receive-redirects [enable | disable] -.. cfgcmd:: set firewall global-options ipv6-receive-redirects - [enable | disable] - - 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] - - 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] - - Allow VyOS to log martian IPv4 packets. - The following sysctl parameter will be changed: - - * ``net.ipv4.conf.all.log_martians`` - -.. cfgcmd:: set firewall global-options source-validation - [strict | loose | disable] - - Set the IPv4 source validation mode. - The following sysctl parameter will be changed: - - * ``net.ipv4.conf.all.rp_filter`` - -.. cfgcmd:: set firewall global-options syn-cookies [enable | disable] - - 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 :rfc:`1337` conformance. - The following sysctl parameter will be changed: - - * ``net.ipv4.tcp_rfc1337`` - -.. cfgcmd:: set firewall global-options state-policy established action - [accept | drop | reject] - -.. cfgcmd:: set firewall global-options state-policy established log - -.. cfgcmd:: set firewall global-options state-policy established log-level - [emerg | alert | crit | err | warn | notice | info | debug] - - Set the global setting for an established connection. - -.. cfgcmd:: set firewall global-options state-policy invalid action - [accept | drop | reject] - -.. cfgcmd:: set firewall global-options state-policy invalid log - -.. cfgcmd:: set firewall global-options state-policy invalid log-level - [emerg | alert | crit | err | warn | notice | info | debug] - - Set the global setting for invalid packets. - -.. cfgcmd:: set firewall global-options state-policy related action - [accept | drop | reject] - -.. cfgcmd:: set firewall global-options state-policy related log - -.. cfgcmd:: set firewall global-options state-policy related log-level - [emerg | alert | crit | err | warn | notice | info | debug] - - Set the global setting for related connections. - -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: -.. cfgcmd:: set firewall global-options timeout other <1-21474836> - :defaultvalue: -.. cfgcmd:: set firewall global-options timeout tcp close <1-21474836> - :defaultvalue: -.. cfgcmd:: set firewall global-options timeout tcp close-wait <1-21474836> - :defaultvalue: -.. cfgcmd:: set firewall global-options timeout tcp established <1-21474836> - :defaultvalue: -.. cfgcmd:: set firewall global-options timeout tcp fin-wait <1-21474836> - :defaultvalue: -.. cfgcmd:: set firewall global-options timeout tcp last-ack <1-21474836> - :defaultvalue: -.. cfgcmd:: set firewall global-options timeout tcp syn-recv <1-21474836> - :defaultvalue: -.. cfgcmd:: set firewall global-options timeout tcp syn-sent <1-21474836> - :defaultvalue: -.. cfgcmd:: set firewall global-options timeout tcp time-wait <1-21474836> - :defaultvalue: -.. cfgcmd:: set firewall global-options timeout udp other <1-21474836> - :defaultvalue: -.. cfgcmd:: set firewall global-options timeout udp stream <1-21474836> - :defaultvalue: - - Set the timeout in seconds for a protocol or state.
\ No newline at end of file diff --git a/docs/configuration/firewall/rst-groups.rst b/docs/configuration/firewall/rst-groups.rst deleted file mode 100644 index 9d29866e..00000000 --- a/docs/configuration/firewall/rst-groups.rst +++ /dev/null @@ -1,457 +0,0 @@ -:lastproofread: 2026-03-30 - -.. _firewall-groups-configuration: - -############### -Firewall groups -############### - -************* -Configuration -************* - -Firewall groups represent collections of IP addresses, networks, ports, -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 -============== - -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 an IPv4 or IPv6 address group. - - .. code-block:: none - - set firewall group address-group ADR-INSIDE-v4 address 192.168.0.1 - set firewall group address-group ADR-INSIDE-v4 address 10.0.0.1-10.0.0.8 - set firewall group ipv6-address-group ADR-INSIDE-v6 address 2001:db8::1 - -.. cfgcmd:: set firewall group address-group <name> description <text> -.. cfgcmd:: set firewall group ipv6-address-group <name> description <text> - - Provide an IPv4 or IPv6 address group description. - -Remote Groups -============== - -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> - - 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. - -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 - - 127.0.0.1 - 127.0.0.0/24 - 127.0.0.1-127.0.0.254 - 2001:db8::1 - 2001:db8:cafe::/48 - 2001:db8:cafe::1-2001:db8:cafe::ffff - -Network Groups -============== - -**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 an IPv4 or IPv6 network group. - - .. code-block:: none - - set firewall group network-group NET-INSIDE-v4 network 192.168.0.0/24 - set firewall group network-group NET-INSIDE-v4 network 192.168.1.0/24 - set firewall group ipv6-network-group NET-INSIDE-v6 network 2001:db8::/64 - -.. cfgcmd:: set firewall group network-group <name> description <text> -.. cfgcmd:: set firewall group ipv6-network-group <name> description <text> - - Provide an IPv4 or IPv6 network group description. - -Interface Groups -================ - -An **interface group** represents a collection of interfaces. - -.. cfgcmd:: set firewall group interface-group <name> interface <text> - - Define an interface group. - Wildcard ``*`` is supported. For example: ``eth3*``. - Prepend the character ``!`` to invert the criteria. For example: ``!eth2``. - -.. code-block:: none - - set firewall group interface-group LAN interface bond1001 - set firewall group interface-group LAN interface eth3* - -.. cfgcmd:: set firewall group interface-group <name> description <text> - - Provide an interface group description. - -Port Groups -=========== - -A **port group** represents only port numbers, not the protocol. 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. For example, ``http``. - - .. code-block:: none - - set firewall group port-group PORT-TCP-SERVER1 port http - set firewall group port-group PORT-TCP-SERVER1 port 443 - set firewall group port-group PORT-TCP-SERVER1 port 5000-5010 - -.. cfgcmd:: set firewall group port-group <name> description <text> - - Provide a port group description. - -MAC Groups -========== - -A **mac group** represents a collection of mac addresses. - -.. cfgcmd:: set firewall group mac-group <name> mac-address <mac-address> - - Define a mac group. - -.. code-block:: none - - set firewall group mac-group MAC-G01 mac-address 88:a4:c2:15:b6:4f - set firewall group mac-group MAC-G01 mac-address 4c:d5:77:c0:19:81 - -.. cfgcmd:: set firewall group mac-group <name> description <text> - - Provide a MAC group description. - -Domain Groups -============= - -A **domain group** represents a collection of domains. - -.. cfgcmd:: set firewall group domain-group <name> address <domain> - - Define a domain group. - -.. code-block:: none - - set firewall group domain-group DOM address example.com - -.. cfgcmd:: set firewall group domain-group <name> description <text> - - Provide a domain group description. - -Dynamic Groups -============== - -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 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> - -Add description to firewall groups: - -.. cfgcmd:: set firewall group dynamic-group address-group <name> - description <text> -.. cfgcmd:: set firewall group dynamic-group ipv6-address-group <name> - description <text> - -Adding elements to Dynamic Firewall Groups ------------------------------------------- - -After you define dynamic firewall groups, use them in firewall rules to -dynamically add elements to them. - -Commands used for this task are: - -* Add destination IP address of the connection to a dynamic address group: - -.. cfgcmd:: set firewall ipv4 [forward | input | output] filter rule - <1-999999> add-address-to-group destination-address address-group <name> -.. cfgcmd:: set firewall ipv4 name <name> rule <1-999999> add-address-to-group - destination-address address-group <name> -.. cfgcmd:: set firewall ipv6 [forward | input | output] filter rule - <1-999999> add-address-to-group destination-address address-group <name> -.. cfgcmd:: set firewall ipv6 name <name> rule <1-999999> add-address-to-group - destination-address address-group <name> - -* Add source IP address of the connection to a dynamic address group: - -.. cfgcmd:: set firewall ipv4 [forward | input | output] filter rule - <1-999999> add-address-to-group source-address address-group <name> -.. cfgcmd:: set firewall ipv4 name <name> rule <1-999999> add-address-to-group - source-address address-group <name> -.. cfgcmd:: set firewall ipv6 [forward | input | output] filter rule - <1-999999> add-address-to-group source-address address-group <name> -.. cfgcmd:: set firewall ipv6 name <name> rule <1-999999> add-address-to-group - source-address address-group <name> - -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] - timeout <timeout> -.. cfgcmd:: set firewall ipv4 name <name> rule <1-999999> add-address-to-group - [destination-address | source-address] timeout <timeout> -.. cfgcmd:: set firewall ipv6 [forward | input | output] filter rule - <1-999999> add-address-to-group [destination-address | source-address] - timeout <timeout> -.. cfgcmd:: set firewall ipv6 name <name> rule <1-999999> add-address-to-group - [destination-address | source-address] timeout <timeout> - -Timeout can be defined using seconds, minutes, hours or days: - -.. code-block:: none - - set firewall ipv6 name FOO rule 10 add-address-to-group source-address timeout - Possible completions: - <number>s Timeout value in seconds - <number>m Timeout value in minutes - <number>h Timeout value in hours - <number>d Timeout value in days - -Using Dynamic Firewall Groups ------------------------------ - -Like other firewall groups, you can use dynamic firewall groups in firewall -rules as matching options. For example: - -.. code-block:: none - - set firewall ipv4 input filter rule 10 source group dynamic-address-group FOO - set firewall ipv4 input filter rule 10 destination group dynamic-address-group BAR - -******** -Examples -******** - -General example -=============== - -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 - - set firewall group address-group SERVERS address 198.51.100.101 - set firewall group address-group SERVERS address 198.51.100.102 - set firewall group network-group TRUSTEDv4 network 192.0.2.0/30 - set firewall group network-group TRUSTEDv4 network 203.0.113.128/25 - set firewall group ipv6-network-group TRUSTEDv6 network 2001:db8::/64 - set firewall group interface-group LAN interface eth2.2001 - set firewall group interface-group LAN interface bon0 - set firewall group port-group PORT-SERVERS port http - set firewall group port-group PORT-SERVERS port 443 - set firewall group port-group PORT-SERVERS port 5000-5010 - -And next, some configuration example where groups are used: - - .. code-block:: none - - set firewall ipv4 output filter rule 10 action accept - set firewall ipv4 output filter rule 10 outbound-interface group !LAN - set firewall ipv4 forward filter rule 20 action accept - set firewall ipv4 forward filter rule 20 source group network-group TRUSTEDv4 - set firewall ipv6 input filter rule 10 action accept - set firewall ipv6 input filter rule 10 source group network-group TRUSTEDv6 - set nat destination rule 101 inbound-interface group LAN - set nat destination rule 101 destination group address-group SERVERS - set nat destination rule 101 protocol tcp - set nat destination rule 101 destination group port-group PORT-SERVERS - set nat destination rule 101 translation address 203.0.113.250 - set policy route PBR rule 201 destination group port-group PORT-SERVERS - set policy route PBR rule 201 protocol tcp - set policy route PBR rule 201 set table 15 - -Port knocking example -===================== - -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 - - set firewall global-options state-policy established action 'accept' - set firewall global-options state-policy invalid action 'drop' - set firewall global-options state-policy related action 'accept' - set firewall group dynamic-group address-group ALLOWED - set firewall group dynamic-group address-group PN_01 - set firewall group dynamic-group address-group PN_02 - set firewall ipv4 input filter default-action 'drop' - set firewall ipv4 input filter rule 5 action 'accept' - set firewall ipv4 input filter rule 5 protocol 'icmp' - set firewall ipv4 input filter rule 10 action 'drop' - set firewall ipv4 input filter rule 10 add-address-to-group source-address address-group 'PN_01' - set firewall ipv4 input filter rule 10 add-address-to-group source-address timeout '2m' - set firewall ipv4 input filter rule 10 description 'Port_nock 01' - set firewall ipv4 input filter rule 10 destination port '9990' - set firewall ipv4 input filter rule 10 protocol 'tcp' - set firewall ipv4 input filter rule 20 action 'drop' - set firewall ipv4 input filter rule 20 add-address-to-group source-address address-group 'PN_02' - set firewall ipv4 input filter rule 20 add-address-to-group source-address timeout '3m' - set firewall ipv4 input filter rule 20 description 'Port_nock 02' - set firewall ipv4 input filter rule 20 destination port '9991' - set firewall ipv4 input filter rule 20 protocol 'tcp' - set firewall ipv4 input filter rule 20 source group dynamic-address-group 'PN_01' - set firewall ipv4 input filter rule 30 action 'drop' - set firewall ipv4 input filter rule 30 add-address-to-group source-address address-group 'ALLOWED' - set firewall ipv4 input filter rule 30 add-address-to-group source-address timeout '2h' - set firewall ipv4 input filter rule 30 description 'Port_nock 03' - set firewall ipv4 input filter rule 30 destination port '9992' - set firewall ipv4 input filter rule 30 protocol 'tcp' - set firewall ipv4 input filter rule 30 source group dynamic-address-group 'PN_02' - set firewall ipv4 input filter rule 99 action 'accept' - set firewall ipv4 input filter rule 99 description 'Port_nock 04 - Allow ssh' - set firewall ipv4 input filter rule 99 destination port '22' - set firewall ipv4 input filter rule 99 protocol 'tcp' - set firewall ipv4 input filter rule 99 source group dynamic-address-group 'ALLOWED' - -Before testing, we can check the members of firewall groups: - - .. code-block:: none - - vyos@vyos# run show firewall group - Firewall Groups - - Name Type References Members Timeout Expires - ------- ---------------------- -------------------- ------------- --------- --------- - ALLOWED address_group(dynamic) ipv4-input-filter-30 N/D N/D N/D - PN_01 address_group(dynamic) ipv4-input-filter-10 N/D N/D N/D - PN_02 address_group(dynamic) ipv4-input-filter-20 N/D N/D N/D - [edit] - vyos@vyos# - -With this configuration, to gain SSH access to the router, the user must: - -1. Create a new TCP connection to destination port 9990. A new entry is added - to dynamic firewall group ``PN_01``. - - .. code-block:: none - - vyos@vyos# run show firewall group - Firewall Groups - - Name Type References Members Timeout Expires - ------- ---------------------- -------------------- ------------- --------- --------- - ALLOWED address_group(dynamic) ipv4-input-filter-30 N/D N/D N/D - PN_01 address_group(dynamic) ipv4-input-filter-10 192.168.89.31 120 119 - PN_02 address_group(dynamic) ipv4-input-filter-20 N/D N/D N/D - [edit] - vyos@vyos# - -2. Create a new TCP connection to destination port 9991. A new entry is added - to dynamic firewall group ``PN_02``. - - .. code-block:: none - - vyos@vyos# run show firewall group - Firewall Groups - - Name Type References Members Timeout Expires - ------- ---------------------- -------------------- ------------- --------- --------- - ALLOWED address_group(dynamic) ipv4-input-filter-30 N/D N/D N/D - PN_01 address_group(dynamic) ipv4-input-filter-10 192.168.89.31 120 106 - PN_02 address_group(dynamic) ipv4-input-filter-20 192.168.89.31 180 179 - [edit] - vyos@vyos# - -3. Create a new TCP connection to destination port 9992. A new entry is added - to dynamic firewall group ``ALLOWED``. - - .. code-block:: none - - vyos@vyos# run show firewall group - Firewall Groups - - Name Type References Members Timeout Expires - ------- ---------------------- -------------------- ------------- --------- --------- - ALLOWED address_group(dynamic) ipv4-input-filter-30 192.168.89.31 7200 7199 - PN_01 address_group(dynamic) ipv4-input-filter-10 192.168.89.31 120 89 - PN_02 address_group(dynamic) ipv4-input-filter-20 192.168.89.31 180 170 - [edit] - vyos@vyos# - -4. Now you can connect via SSH to the router (assuming SSH is - configured). - -************** -Operation-mode -************** - -.. opcmd:: show firewall group -.. opcmd:: show firewall group <name> - - 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: - - .. code-block:: none - - vyos@vyos:~$ show firewall group - Firewall Groups - - Name Type References Members Timeout Expires - ------------ ---------------------- ---------------------- ---------------- --------- --------- - SERVERS address_group nat-destination-101 198.51.100.101 - 198.51.100.102 - ALLOWED address_group(dynamic) ipv4-input-filter-30 192.168.77.39 7200 7174 - PN_01 address_group(dynamic) ipv4-input-filter-10 192.168.0.245 120 112 - 192.168.77.39 120 85 - PN_02 address_group(dynamic) ipv4-input-filter-20 192.168.77.39 180 151 - LAN interface_group ipv4-output-filter-10 bon0 - nat-destination-101 eth2.2001 - TRUSTEDv6 ipv6_network_group ipv6-input-filter-10 2001:db8::/64 - TRUSTEDv4 network_group ipv4-forward-filter-20 192.0.2.0/30 - 203.0.113.128/25 - PORT-SERVERS port_group route-PBR-201 443 - route-PBR-201 5000-5010 - nat-destination-101 http - vyos@vyos:~$ diff --git a/docs/configuration/firewall/rst-index.rst b/docs/configuration/firewall/rst-index.rst deleted file mode 100644 index c4b3c808..00000000 --- a/docs/configuration/firewall/rst-index.rst +++ /dev/null @@ -1,267 +0,0 @@ -:lastproofread: 2026-03-30 - -######## -Firewall -######## - -.. 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. - -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). - -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 packet flow and terminology in VyOS firewall -are: - - * **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 is not part of a bridge, the -packet is processed at the **IP Layer**: - - * **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 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 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 you define under ``set policy [route | - route6] ...``. - - * **Destination NAT**: Rules you define under ``set [nat | nat66] - destination...``. - - * **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**: 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**: 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**: 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**, the system processes - rules in this section before the connection tracking subsystem. - - * **Output Filter**: ``set firewall [ipv4 | ipv6] output filter ...``. - - * **Postrouting**: As in **Prerouting**, you can perform several actions - defined in different parts of VyOS configuration in this stage. This - includes: - - * **Source NAT**: Rules you define under ``set [nat | nat66] - destination...``. - -If the interface where the packet was received is part of a bridge, the -packet is processed at the **Bridge Layer**: - - * **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)**: The stage where you filter and control traffic - that passes through the bridge: - - * ``set firewall bridge forward filter ...``. - - * **Input (Bridge)**: The stage where you filter and control traffic - destined for the bridge itself: - - * ``set firewall bridge input filter ...``. - - * **Output (Bridge)**: The stage where you filter and control traffic that - the bridge originates: - - * ``set firewall bridge output filter ...``. - -The following is the overall structure of the VyOS firewall CLI: - -.. code-block:: none - - - set firewall - * bridge - - forward - + filter - - input - + filter - - output - + filter - - prerouting - + filter - - name - + custom_name - * flowtable - - custom_flow_table - + ... - * global-options - + all-ping - + broadcast-ping - + ... - * group - - address-group - - ipv6-address-group - - network-group - - ipv6-network-group - - interface-group - - mac-group - - port-group - - domain-group - * ipv4 - - forward - + filter - - input - + filter - - output - + filter - + raw - - prerouting - + raw - - name - + custom_name - * ipv6 - - forward - + filter - - input - + filter - - output - + filter - + raw - - prerouting - + raw - - ipv6-name - + custom_name - * zone - - custom_zone_name - + ... - -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 - :includehidden: - - global-options - groups - bridge - ipv4 - ipv6 - flowtables - -.. 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 -^^^^^^^^^^^^^^^^^^^ - -.. toctree:: - :maxdepth: 1 - :includehidden: - - zone - -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 zone-based firewall, see -:doc:`Zone-Based Firewall Configuration </configuration/firewall/zone>`. - -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. - -.. figure:: /_static/images/firewall-zonebased.* diff --git a/docs/configuration/firewall/rst-ipv4.rst b/docs/configuration/firewall/rst-ipv4.rst deleted file mode 100644 index efd0fe18..00000000 --- a/docs/configuration/firewall/rst-ipv4.rst +++ /dev/null @@ -1,1305 +0,0 @@ -:lastproofread: 2026-03-30 - -.. _firewall-ipv4-configuration: - -########################### -IPv4 Firewall Configuration -########################### - -******** -Overview -******** - -This section provides information on IPv4 firewall configuration and -appropriate operation-mode commands. This section covers the following -configuration commands: - -.. cfgcmd:: set firewall ipv4 ... - -To learn about the general traffic flow in VyOS firewalls, -see :doc:`Firewall </configuration/firewall/index>`. - -.. code-block:: none - - - set firewall - * ipv4 - - forward - + filter - - input - + filter - - output - + filter - + raw - - prerouting - + raw - - name - + custom_name - -First, the router receives all traffic and processes it in the **prerouting** -stage. - -This stage includes: - - * **Firewall Prerouting**: commands found under ``set firewall ipv4 - prerouting raw ...`` - * :doc:`Conntrack Ignore</configuration/system/conntrack>`: ``set system - conntrack ignore ipv4...`` - * :doc:`Policy Route</configuration/policy/route>`: commands found under - ``set policy route ...`` - * :doc:`Destination NAT</configuration/nat/nat44>`: commands found under - ``set nat destination ...`` - -For transit traffic, which is received by the router and forwarded, the base -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 for configuring filtering rules for transit traffic is -``set firewall ipv4 forward filter ...``, which occurs in stage 5, highlighted -in red. - -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 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**, 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 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**. - -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 -********************* - -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 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: - - * ``accept``: Accept the packet. - - * ``continue``: Continue parsing the next rule. - - * ``drop``: Drop the packet. - - * ``reject``: Reject the packet. - - * ``jump``: Jump to another custom chain. - - * ``return``: Return from the current chain and continue at the next rule - of the last chain. - - * ``queue``: Enqueue packet to userspace. - - * ``synproxy``: Synproxy the packet. - -.. cfgcmd:: set firewall ipv4 forward filter rule <1-999999> action - [accept | continue | drop | jump | queue | reject | return | synproxy] -.. cfgcmd:: set firewall ipv4 input filter rule <1-999999> action - [accept | continue | drop | jump | queue | reject | return | synproxy] -.. cfgcmd:: set firewall ipv4 output filter rule <1-999999> action - [accept | continue | drop | jump | queue | reject | return] -.. 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 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> -.. cfgcmd:: set firewall ipv4 input filter rule <1-999999> - jump-target <text> -.. cfgcmd:: set firewall ipv4 output filter rule <1-999999> - jump-target <text> -.. cfgcmd:: set firewall ipv4 name <name> rule <1-999999> - jump-target <text> - - 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> -.. cfgcmd:: set firewall ipv4 input filter rule <1-999999> - queue <0-65535> -.. cfgcmd:: set firewall ipv4 output filter rule <1-999999> - queue <0-65535> -.. cfgcmd:: set firewall ipv4 name <name> rule <1-999999> - queue <0-65535> - - 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 -.. cfgcmd:: set firewall ipv4 input filter rule <1-999999> - queue-options bypass -.. cfgcmd:: set firewall ipv4 output filter rule <1-999999> - queue-options bypass -.. cfgcmd:: set firewall ipv4 name <name> rule <1-999999> - queue-options bypass - - 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> - queue-options fanout -.. cfgcmd:: set firewall ipv4 input filter rule <1-999999> - queue-options fanout -.. cfgcmd:: set firewall ipv4 output filter rule <1-999999> - queue-options fanout -.. cfgcmd:: set firewall ipv4 name <name> rule <1-999999> - queue-options fanout - - Use this command only when the action is set to ``queue``. Distribute - packets between several queues. - -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 - [accept | drop] -.. cfgcmd:: set firewall ipv4 input filter default-action - [accept | drop] -.. cfgcmd:: set firewall ipv4 output filter default-action - [accept | drop] -.. cfgcmd:: set firewall ipv4 name <name> default-action - [accept | drop | jump | queue | reject | return] - - 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> - - 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 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 -============= - -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 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 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 - | info | debug] -.. cfgcmd:: set firewall ipv4 input filter rule <1-999999> - log-options level [emerg | alert | crit | err | warn | notice - | info | debug] -.. cfgcmd:: set firewall ipv4 output filter rule <1-999999> - log-options level [emerg | alert | crit | err | warn | notice - | info | debug] -.. cfgcmd:: set firewall ipv4 name <name> rule <1-999999> - log-options level [emerg | alert | crit | err | warn | notice - | info | debug] - - 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> -.. cfgcmd:: set firewall ipv4 input filter rule <1-999999> - log-options group <0-65535> -.. cfgcmd:: set firewall ipv4 output filter rule <1-999999> - log-options group <0-65535> -.. 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 you enable rule - logging. - -.. cfgcmd:: set firewall ipv4 forward filter rule <1-999999> - log-options snapshot-length <0-9000> -.. cfgcmd:: set firewall ipv4 input filter rule <1-999999> - log-options snapshot-length <0-9000> -.. cfgcmd:: set firewall ipv4 output filter rule <1-999999> - log-options snapshot-length <0-9000> -.. cfgcmd:: set firewall ipv4 name <name> rule <1-999999> - log-options snapshot-length <0-9000> - - Define the length of packet payload to include in a netlink message. Only - 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> -.. cfgcmd:: set firewall ipv4 input filter rule <1-999999> - log-options queue-threshold <0-65535> -.. cfgcmd:: set firewall ipv4 output filter rule <1-999999> - log-options queue-threshold <0-65535> -.. cfgcmd:: set firewall ipv4 name <name> rule <1-999999> - log-options queue-threshold <0-65535> - - Define the number of packets to queue inside the kernel before sending them - to userspace. Only applicable if you enable rule logging and define the log - group. - -Firewall Description -==================== - -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 for a custom firewall chain. - -.. cfgcmd:: set firewall ipv4 forward filter rule <1-999999> - description <text> -.. cfgcmd:: set firewall ipv4 input filter rule <1-999999> - description <text> -.. cfgcmd:: set firewall ipv4 output filter rule <1-999999> - description <text> -.. cfgcmd:: set firewall ipv4 name <name> rule <1-999999> description <text> - - Provide a description for each rule. - -Rule Status -=========== - -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 keeping it in the configuration. - -Matching criteria -================= - -There are a lot of matching criteria against which the packet can be tested. - -.. cfgcmd:: set firewall ipv4 forward filter rule <1-999999> - connection-status nat [destination | source] -.. cfgcmd:: set firewall ipv4 input filter rule <1-999999> - connection-status nat [destination | source] -.. cfgcmd:: set firewall ipv4 output filter rule <1-999999> - connection-status nat [destination | source] -.. cfgcmd:: set firewall ipv4 name <name> rule <1-999999> - connection-status nat [destination | source] - - Match based on nat connection status. - -.. cfgcmd:: set firewall ipv4 forward filter rule <1-999999> - connection-mark <1-2147483647> -.. cfgcmd:: set firewall ipv4 input filter rule <1-999999> - connection-mark <1-2147483647> -.. cfgcmd:: set firewall ipv4 output filter rule <1-999999> - connection-mark <1-2147483647> -.. cfgcmd:: set firewall ipv4 name <name> rule <1-999999> - connection-mark <1-2147483647> - - Match based on connection mark. - -.. cfgcmd:: set firewall ipv4 forward filter rule <1-999999> - conntrack-helper <module> -.. cfgcmd:: set firewall ipv4 input filter rule <1-999999> - conntrack-helper <module> -.. cfgcmd:: set firewall ipv4 output filter rule <1-999999> - conntrack-helper <module> -.. cfgcmd:: set firewall ipv4 name <name> rule <1-999999> - conntrack-helper <module> - - Match based on connection tracking protocol helper module to secure use of - that helper module. See below for possible completions `<module>`. - - .. code-block:: none - - Possible completions: - ftp Related traffic from FTP helper - h323 Related traffic from H.323 helper - pptp Related traffic from PPTP helper - nfs Related traffic from NFS helper - sip Related traffic from SIP helper - tftp Related traffic from TFTP helper - sqlnet Related traffic from SQLNet helper - -.. cfgcmd:: set firewall ipv4 forward filter rule <1-999999> - source address [address | addressrange | CIDR] -.. cfgcmd:: set firewall ipv4 input filter rule <1-999999> - source address [address | addressrange | CIDR] -.. cfgcmd:: set firewall ipv4 output filter rule <1-999999> - source address [address | addressrange | CIDR] -.. cfgcmd:: set firewall ipv4 name <name> rule <1-999999> - source address [address | addressrange | CIDR] - -.. cfgcmd:: set firewall ipv4 forward filter rule <1-999999> - destination address [address | addressrange | CIDR] -.. cfgcmd:: set firewall ipv4 input filter rule <1-999999> - destination address [address | addressrange | CIDR] -.. cfgcmd:: set firewall ipv4 output filter rule <1-999999> - destination address [address | addressrange | CIDR] -.. cfgcmd:: set firewall ipv4 name <name> rule <1-999999> - destination address [address | addressrange | CIDR] - - Match criteria based on source and/or destination address. This is similar - to the network groups part, but here you are able to negate the matching - addresses. - - .. code-block:: none - - set firewall ipv4 name FOO rule 50 source address 192.0.2.10-192.0.2.11 - # with a '!' the rule match everything except the specified subnet - set firewall ipv4 input filter FOO rule 51 source address !203.0.113.0/24 - -.. cfgcmd:: set firewall ipv4 forward filter rule <1-999999> - source address-mask [address] -.. cfgcmd:: set firewall ipv4 input filter rule <1-999999> - source address-mask [address] -.. cfgcmd:: set firewall ipv4 output filter rule <1-999999> - source address-mask [address] -.. cfgcmd:: set firewall ipv4 name <name> rule <1-999999> - source address-mask [address] - -.. cfgcmd:: set firewall ipv4 forward filter rule <1-999999> - destination address-mask [address] -.. cfgcmd:: set firewall ipv4 input filter rule <1-999999> - destination address-mask [address] -.. cfgcmd:: set firewall ipv4 output filter rule <1-999999> - destination address-mask [address] -.. cfgcmd:: set firewall ipv4 name <name> rule <1-999999> - destination address-mask [address] - - An arbitrary netmask can be applied to mask addresses to only match against - a specific portion. - - This functions for both individual addresses and address groups. - - .. code-block:: none - - # Match any IPv4 address with `11` as the 2nd octet and `13` as the forth octet - set firewall ipv4 name FOO rule 100 destination address 0.11.0.13 - set firewall ipv4 name FOO rule 100 destination address-mask 0.255.0.255 - -.. cfgcmd:: set firewall ipv4 forward filter rule <1-999999> - source fqdn <fqdn> -.. cfgcmd:: set firewall ipv4 input filter rule <1-999999> - source fqdn <fqdn> -.. cfgcmd:: set firewall ipv4 output filter rule <1-999999> - source fqdn <fqdn> -.. cfgcmd:: set firewall ipv4 name <name> rule <1-999999> - source fqdn <fqdn> -.. cfgcmd:: set firewall ipv4 forward filter rule <1-999999> - destination fqdn <fqdn> -.. cfgcmd:: set firewall ipv4 input filter rule <1-999999> - destination fqdn <fqdn> -.. cfgcmd:: set firewall ipv4 output filter rule <1-999999> - destination fqdn <fqdn> -.. cfgcmd:: set firewall ipv4 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. - -.. cfgcmd:: set firewall ipv4 forward filter rule <1-999999> - source geoip country-code <country> -.. cfgcmd:: set firewall ipv4 input filter rule <1-999999> - source geoip country-code <country> -.. cfgcmd:: set firewall ipv4 output filter rule <1-999999> - source geoip country-code <country> -.. cfgcmd:: set firewall ipv4 name <name> rule <1-999999> - source geoip country-code <country> - -.. cfgcmd:: set firewall ipv4 forward filter rule <1-999999> - destination geoip country-code <country> -.. cfgcmd:: set firewall ipv4 input filter rule <1-999999> - destination geoip country-code <country> -.. cfgcmd:: set firewall ipv4 output filter rule <1-999999> - destination geoip country-code <country> -.. cfgcmd:: set firewall ipv4 name <name> rule <1-999999> - destination geoip country-code <country> - -.. cfgcmd:: set firewall ipv4 forward filter rule <1-999999> - source geoip inverse-match -.. cfgcmd:: set firewall ipv4 input filter rule <1-999999> - source geoip inverse-match -.. cfgcmd:: set firewall ipv4 output filter rule <1-999999> - source geoip inverse-match -.. cfgcmd:: set firewall ipv4 name <name> rule <1-999999> - source geoip inverse-match - -.. cfgcmd:: set firewall ipv4 forward filter rule <1-999999> - destination geoip inverse-match -.. cfgcmd:: set firewall ipv4 input filter rule <1-999999> - destination geoip inverse-match -.. cfgcmd:: set firewall ipv4 output filter rule <1-999999> - destination geoip inverse-match -.. cfgcmd:: set firewall ipv4 name <name> rule <1-999999> - destination geoip inverse-match - - Match IP addresses based on its geolocation. More info: `geoip matching - <https://wiki.nftables.org/wiki-nftables/index.php/GeoIP_matching>`_. - Use inverse-match to match anything except the given country-codes. - -Data is provided by DB-IP.com under CC-BY-4.0 license. Attribution required, -permits redistribution so we can include a database in images(~3MB -compressed). Includes cron script (manually callable by op-mode update -geoip) to keep database and rules updated. - - -.. cfgcmd:: set firewall ipv4 forward filter rule <1-999999> - source mac-address <mac-address> -.. cfgcmd:: set firewall ipv4 input filter rule <1-999999> - source mac-address <mac-address> -.. cfgcmd:: set firewall ipv4 output filter rule <1-999999> - source mac-address <mac-address> -.. cfgcmd:: set firewall ipv4 name <name> rule <1-999999> - source mac-address <mac-address> - - You can only specify a source mac-address to match. - - .. code-block:: none - - set firewall ipv4 input filter rule 100 source mac-address 00:53:00:11:22:33 - set firewall ipv4 input filter rule 101 source mac-address !00:53:00:aa:12:34 - -.. cfgcmd:: set firewall ipv4 forward filter rule <1-999999> - source port [1-65535 | portname | start-end] -.. cfgcmd:: set firewall ipv4 input filter rule <1-999999> - source port [1-65535 | portname | start-end] -.. cfgcmd:: set firewall ipv4 output filter rule <1-999999> - source port [1-65535 | portname | start-end] -.. cfgcmd:: set firewall ipv4 name <name> rule <1-999999> - source port [1-65535 | portname | start-end] - -.. cfgcmd:: set firewall ipv4 forward filter rule <1-999999> - destination port [1-65535 | portname | start-end] -.. cfgcmd:: set firewall ipv4 input filter rule <1-999999> - destination port [1-65535 | portname | start-end] -.. cfgcmd:: set firewall ipv4 output filter rule <1-999999> - destination port [1-65535 | portname | start-end] -.. cfgcmd:: set firewall ipv4 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``. - - .. code-block:: none - - set firewall ipv4 forward filter rule 10 source port '22' - set firewall ipv4 forward filter rule 11 source port '!http' - set firewall ipv4 forward filter rule 12 source port 'https' - - Multiple source ports can be specified as a comma-separated list. - The whole list can also be "negated" using ``!``. For example: - -.. cfgcmd:: set firewall ipv4 forward filter rule <1-999999> - source group address-group <name | !name> -.. cfgcmd:: set firewall ipv4 input filter rule <1-999999> - source group address-group <name | !name> -.. cfgcmd:: set firewall ipv4 output filter rule <1-999999> - source group address-group <name | !name> -.. cfgcmd:: set firewall ipv4 name <name> rule <1-999999> - source group address-group <name | !name> - -.. cfgcmd:: set firewall ipv4 forward filter rule <1-999999> - destination group address-group <name | !name> -.. cfgcmd:: set firewall ipv4 input filter rule <1-999999> - destination group address-group <name | !name> -.. cfgcmd:: set firewall ipv4 output filter rule <1-999999> - destination group address-group <name | !name> -.. cfgcmd:: set firewall ipv4 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. - -.. cfgcmd:: set firewall ipv4 forward filter rule <1-999999> - source group dynamic-address-group <name | !name> -.. cfgcmd:: set firewall ipv4 input filter rule <1-999999> - source group dynamic-address-group <name | !name> -.. cfgcmd:: set firewall ipv4 output filter rule <1-999999> - source group dynamic-address-group <name | !name> -.. cfgcmd:: set firewall ipv4 name <name> rule <1-999999> - source group dynamic-address-group <name | !name> - -.. cfgcmd:: set firewall ipv4 forward filter rule <1-999999> - destination group dynamic-address-group <name | !name> -.. cfgcmd:: set firewall ipv4 input filter rule <1-999999> - destination group dynamic-address-group <name | !name> -.. cfgcmd:: set firewall ipv4 output filter rule <1-999999> - destination group dynamic-address-group <name | !name> -.. cfgcmd:: set firewall ipv4 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. - -.. cfgcmd:: set firewall ipv4 forward filter rule <1-999999> - source group network-group <name | !name> -.. cfgcmd:: set firewall ipv4 input filter rule <1-999999> - source group network-group <name | !name> -.. cfgcmd:: set firewall ipv4 output filter rule <1-999999> - source group network-group <name | !name> -.. cfgcmd:: set firewall ipv4 name <name> rule <1-999999> - source group network-group <name | !name> - -.. cfgcmd:: set firewall ipv4 forward filter rule <1-999999> - destination group network-group <name | !name> -.. cfgcmd:: set firewall ipv4 input filter rule <1-999999> - destination group network-group <name | !name> -.. cfgcmd:: set firewall ipv4 output filter rule <1-999999> - destination group network-group <name | !name> -.. cfgcmd:: set firewall ipv4 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. - -.. cfgcmd:: set firewall ipv4 forward filter rule <1-999999> - source group port-group <name | !name> -.. cfgcmd:: set firewall ipv4 input filter rule <1-999999> - source group port-group <name | !name> -.. cfgcmd:: set firewall ipv4 output filter rule <1-999999> - source group port-group <name | !name> -.. cfgcmd:: set firewall ipv4 name <name> rule <1-999999> - source group port-group <name | !name> - -.. cfgcmd:: set firewall ipv4 forward filter rule <1-999999> - destination group port-group <name | !name> -.. cfgcmd:: set firewall ipv4 input filter rule <1-999999> - destination group port-group <name | !name> -.. cfgcmd:: set firewall ipv4 output filter rule <1-999999> - destination group port-group <name | !name> -.. cfgcmd:: set firewall ipv4 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. - -.. cfgcmd:: set firewall ipv4 forward filter rule <1-999999> - source group domain-group <name | !name> -.. cfgcmd:: set firewall ipv4 input filter rule <1-999999> - source group domain-group <name | !name> -.. cfgcmd:: set firewall ipv4 output filter rule <1-999999> - source group domain-group <name | !name> -.. cfgcmd:: set firewall ipv4 name <name> rule <1-999999> - source group domain-group <name | !name> - -.. cfgcmd:: set firewall ipv4 forward filter rule <1-999999> - destination group domain-group <name | !name> -.. cfgcmd:: set firewall ipv4 input filter rule <1-999999> - destination group domain-group <name | !name> -.. cfgcmd:: set firewall ipv4 output filter rule <1-999999> - destination group domain-group <name | !name> -.. cfgcmd:: set firewall ipv4 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. - -.. cfgcmd:: set firewall ipv4 forward filter rule <1-999999> - source group mac-group <name | !name> -.. cfgcmd:: set firewall ipv4 input filter rule <1-999999> - source group mac-group <name | !name> -.. cfgcmd:: set firewall ipv4 output filter rule <1-999999> - source group mac-group <name | !name> -.. cfgcmd:: set firewall ipv4 name <name> rule <1-999999> - source group mac-group <name | !name> - -.. cfgcmd:: set firewall ipv4 forward filter rule <1-999999> - destination group mac-group <name | !name> -.. cfgcmd:: set firewall ipv4 input filter rule <1-999999> - destination group mac-group <name | !name> -.. cfgcmd:: set firewall ipv4 output filter rule <1-999999> - destination group mac-group <name | !name> -.. cfgcmd:: set firewall ipv4 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. - -.. cfgcmd:: set firewall ipv4 forward filter rule <1-999999> - dscp [0-63 | start-end] -.. cfgcmd:: set firewall ipv4 input filter rule <1-999999> - dscp [0-63 | start-end] -.. cfgcmd:: set firewall ipv4 output filter rule <1-999999> - dscp [0-63 | start-end] -.. cfgcmd:: set firewall ipv4 name <name> rule <1-999999> - dscp [0-63 | start-end] - -.. cfgcmd:: set firewall ipv4 forward filter rule <1-999999> - dscp-exclude [0-63 | start-end] -.. cfgcmd:: set firewall ipv4 input filter rule <1-999999> - dscp-exclude [0-63 | start-end] -.. cfgcmd:: set firewall ipv4 output filter rule <1-999999> - dscp-exclude [0-63 | start-end] -.. cfgcmd:: set firewall ipv4 name <name> rule <1-999999> - dscp-exclude [0-63 | start-end] - - Match based on dscp value. - -.. cfgcmd:: set firewall ipv4 forward filter rule <1-999999> - fragment [match-frag | match-non-frag] -.. cfgcmd:: set firewall ipv4 input filter rule <1-999999> - fragment [match-frag | match-non-frag] -.. cfgcmd:: set firewall ipv4 output filter rule <1-999999> - fragment [match-frag | match-non-frag] -.. cfgcmd:: set firewall ipv4 name <name> rule <1-999999> - fragment [match-frag | match-non-frag] - - Match based on fragmentation. - -.. cfgcmd:: set firewall ipv4 forward filter rule <1-999999> - icmp [code | type] <0-255> -.. cfgcmd:: set firewall ipv4 input filter rule <1-999999> - icmp [code | type] <0-255> -.. cfgcmd:: set firewall ipv4 output filter rule <1-999999> - icmp [code | type] <0-255> -.. cfgcmd:: set firewall ipv4 name <name> rule <1-999999> - icmp [code | type] <0-255> - - Match based on icmp code and type. - -.. cfgcmd:: set firewall ipv4 forward filter rule <1-999999> - icmp type-name <text> -.. cfgcmd:: set firewall ipv4 input filter rule <1-999999> - icmp type-name <text> -.. cfgcmd:: set firewall ipv4 output filter rule <1-999999> - icmp type-name <text> -.. cfgcmd:: set firewall ipv4 name <name> rule <1-999999> - icmp type-name <text> - - Match based on icmp type-name. Use tab for information - about what **type-name** criteria are supported. - -.. cfgcmd:: set firewall ipv4 forward filter rule <1-999999> - inbound-interface name <iface> -.. cfgcmd:: set firewall ipv4 input filter rule <1-999999> - inbound-interface name <iface> -.. cfgcmd:: set firewall ipv4 name <name> rule <1-999999> - inbound-interface name <iface> - - 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 - ipv4 forward filter rule 10 inbound-interface name MGMT`` - -.. cfgcmd:: set firewall ipv4 forward filter rule <1-999999> - inbound-interface group <iface_group> -.. cfgcmd:: set firewall ipv4 input filter rule <1-999999> - inbound-interface group <iface_group> -.. cfgcmd:: set firewall ipv4 name <name> rule <1-999999> - inbound-interface group <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> -.. cfgcmd:: set firewall ipv4 output filter rule <1-999999> - outbound-interface name <iface> -.. cfgcmd:: set firewall ipv4 name <name> rule <1-999999> - outbound-interface name <iface> - - 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 - ``set firewall ipv4 forward filter rule 10 outbound-interface name eth0`` - -.. cfgcmd:: set firewall ipv4 forward filter rule <1-999999> - outbound-interface group <iface_group> -.. cfgcmd:: set firewall ipv4 output filter rule <1-999999> - outbound-interface group <iface_group> -.. cfgcmd:: set firewall ipv4 name <name> rule <1-999999> - outbound-interface group <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] -.. cfgcmd:: set firewall ipv4 input filter rule <1-999999> - ipsec [match-ipsec-in | match-none-in] -.. cfgcmd:: set firewall ipv4 output filter rule <1-999999> - ipsec [match-ipsec-out | match-none-out] -.. cfgcmd:: set firewall ipv4 name <name> rule <1-999999> - ipsec [match-ipsec-in | match-ipsec-out | match-none-in | match-none-out] - - Match based on ipsec. - -.. cfgcmd:: set firewall ipv4 forward filter rule <1-999999> - limit burst <0-4294967295> -.. cfgcmd:: set firewall ipv4 input filter rule <1-999999> - limit burst <0-4294967295> -.. cfgcmd:: set firewall ipv4 output filter rule <1-999999> - limit burst <0-4294967295> -.. cfgcmd:: set firewall ipv4 name <name> rule <1-999999> - limit burst <0-4294967295> - - Match based on the maximum number of packets to allow in excess of rate. - -.. cfgcmd:: set firewall ipv4 forward filter rule <1-999999> - limit rate <text> -.. cfgcmd:: set firewall ipv4 input filter rule <1-999999> - limit rate <text> -.. cfgcmd:: set firewall ipv4 output filter rule <1-999999> - limit rate <text> -.. cfgcmd:: set firewall ipv4 name <name> rule <1-999999> - limit rate <text> - - Specify the maximum average rate as **integer/unit**. For example: - **5/minutes** - -.. cfgcmd:: set firewall ipv4 forward filter rule <1-999999> - packet-length <text> -.. cfgcmd:: set firewall ipv4 input filter rule <1-999999> - packet-length <text> -.. cfgcmd:: set firewall ipv4 output filter rule <1-999999> - packet-length <text> -.. cfgcmd:: set firewall ipv4 name <name> rule <1-999999> - packet-length <text> - -.. cfgcmd:: set firewall ipv4 forward filter rule <1-999999> - packet-length-exclude <text> -.. cfgcmd:: set firewall ipv4 input filter rule <1-999999> - packet-length-exclude <text> -.. cfgcmd:: set firewall ipv4 output filter rule <1-999999> - packet-length-exclude <text> -.. cfgcmd:: set firewall ipv4 name <name> rule <1-999999> - packet-length-exclude <text> - - 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] -.. cfgcmd:: set firewall ipv4 input filter rule <1-999999> - packet-type [broadcast | host | multicast | other] -.. cfgcmd:: set firewall ipv4 output filter rule <1-999999> - packet-type [broadcast | host | multicast | other] -.. cfgcmd:: set firewall ipv4 name <name> rule <1-999999> - packet-type [broadcast | host | multicast | other] - - Match based on the packet type. - -.. cfgcmd:: set firewall ipv4 forward filter rule <1-999999> - protocol [<text> | <0-255> | all | tcp_udp] -.. cfgcmd:: set firewall ipv4 input filter rule <1-999999> - protocol [<text> | <0-255> | all | tcp_udp] -.. cfgcmd:: set firewall ipv4 output filter rule <1-999999> - protocol [<text> | <0-255> | all | tcp_udp] -.. cfgcmd:: set firewall ipv4 name <name> rule <1-999999> - 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 ``!`` character negates the selected protocol. - - .. code-block:: none - - 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> -.. cfgcmd:: set firewall ipv4 input filter rule <1-999999> - recent count <1-255> -.. cfgcmd:: set firewall ipv4 output filter rule <1-999999> - recent count <1-255> -.. cfgcmd:: set firewall ipv4 name <name> rule <1-999999> - recent count <1-255> - -.. cfgcmd:: set firewall ipv4 forward filter rule <1-999999> - recent time [second | minute | hour] -.. cfgcmd:: set firewall ipv4 input filter rule <1-999999> - recent time [second | minute | hour] -.. cfgcmd:: set firewall ipv4 output filter rule <1-999999> - recent time [second | minute | hour] -.. cfgcmd:: set firewall ipv4 name <name> rule <1-999999> - recent time [second | minute | hour] - - Match based on recently seen sources. - -.. cfgcmd:: set firewall ipv4 forward filter rule <1-999999> - tcp flags [not] <text> -.. cfgcmd:: set firewall ipv4 input filter rule <1-999999> - tcp flags [not] <text> -.. cfgcmd:: set firewall ipv4 output filter rule <1-999999> - tcp flags [not] <text> -.. cfgcmd:: set firewall ipv4 name <name> rule <1-999999> - tcp flags [not] <text> - - 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 - - set firewall ipv4 input filter rule 10 tcp flags 'ack' - set firewall ipv4 input filter rule 12 tcp flags 'syn' - set firewall ipv4 input filter rule 13 tcp flags not 'fin' - -.. cfgcmd:: set firewall ipv4 forward filter rule <1-999999> - state [established | invalid | new | related] -.. cfgcmd:: set firewall ipv4 input filter rule <1-999999> - state [established | invalid | new | related] -.. cfgcmd:: set firewall ipv4 output filter rule <1-999999> - state [established | invalid | new | related] -.. cfgcmd:: set firewall ipv4 name <name> rule <1-999999> - state [established | invalid | new | related] - - Match against the state of a packet. - -.. cfgcmd:: set firewall ipv4 forward filter rule <1-999999> - time startdate <text> -.. cfgcmd:: set firewall ipv4 input filter rule <1-999999> - time startdate <text> -.. cfgcmd:: set firewall ipv4 output filter rule <1-999999> - time startdate <text> -.. cfgcmd:: set firewall ipv4 name <name> rule <1-999999> - time startdate <text> -.. cfgcmd:: set firewall ipv4 forward filter rule <1-999999> - time starttime <text> -.. cfgcmd:: set firewall ipv4 input filter rule <1-999999> - time starttime <text> -.. cfgcmd:: set firewall ipv4 output filter rule <1-999999> - time starttime <text> -.. cfgcmd:: set firewall ipv4 name <name> rule <1-999999> - time starttime <text> -.. cfgcmd:: set firewall ipv4 forward filter rule <1-999999> - time stopdate <text> -.. cfgcmd:: set firewall ipv4 input filter rule <1-999999> - time stopdate <text> -.. cfgcmd:: set firewall ipv4 output filter rule <1-999999> - time stopdate <text> -.. cfgcmd:: set firewall ipv4 name <name> rule <1-999999> - time stopdate <text> -.. cfgcmd:: set firewall ipv4 forward filter rule <1-999999> - time stoptime <text> -.. cfgcmd:: set firewall ipv4 input filter rule <1-999999> - time stoptime <text> -.. cfgcmd:: set firewall ipv4 output filter rule <1-999999> - time stoptime <text> -.. cfgcmd:: set firewall ipv4 name <name> rule <1-999999> - time stoptime <text> -.. cfgcmd:: set firewall ipv4 forward filter rule <1-999999> - time weekdays <text> -.. cfgcmd:: set firewall ipv4 input filter rule <1-999999> - time weekdays <text> -.. cfgcmd:: set firewall ipv4 output filter rule <1-999999> - time weekdays <text> -.. cfgcmd:: set firewall ipv4 name <name> rule <1-999999> - time weekdays <text> - - Time to match the defined rule. - -.. cfgcmd:: set firewall ipv4 forward filter rule <1-999999> - ttl <eq | gt | lt> <0-255> -.. cfgcmd:: set firewall ipv4 input filter rule <1-999999> - ttl <eq | gt | lt> <0-255> -.. cfgcmd:: set firewall ipv4 output filter rule <1-999999> - ttl <eq | gt | lt> <0-255> -.. cfgcmd:: set firewall ipv4 name <name> rule <1-999999> - ttl <eq | gt | lt> <0-255> - - 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> -.. cfgcmd:: set firewall ipv4 input filter rule <1-999999> - recent count <1-255> -.. cfgcmd:: set firewall ipv4 output filter rule <1-999999> - recent count <1-255> -.. cfgcmd:: set firewall ipv4 name <name> rule <1-999999> - recent count <1-255> - -.. cfgcmd:: set firewall ipv4 forward filter rule <1-999999> - recent time <second | minute | hour> -.. cfgcmd:: set firewall ipv4 input filter rule <1-999999> - recent time <second | minute | hour> -.. cfgcmd:: set firewall ipv4 output filter rule <1-999999> - recent time <second | minute | hour> -.. cfgcmd:: set firewall ipv4 name <name> rule <1-999999> - recent time <second | minute | hour> - - 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 sending them out. This feature provides more flexibility in -packet handling. - -.. cfgcmd:: set firewall ipv4 prerouting raw rule <1-999999> - set dscp <0-63> -.. cfgcmd:: set firewall ipv4 forward filter rule <1-999999> - set dscp <0-63> -.. cfgcmd:: set firewall ipv4 output [filter | raw] rule <1-999999> - set dscp <0-63> - - Set a specific value of Differentiated Services Codepoint (DSCP). - -.. cfgcmd:: set firewall ipv4 prerouting raw rule <1-999999> - set mark <1-2147483647> -.. cfgcmd:: set firewall ipv4 forward filter rule <1-999999> - set mark <1-2147483647> -.. cfgcmd:: set firewall ipv4 output [filter | raw] rule <1-999999> - set mark <1-2147483647> - - Set a specific packet mark value. - -.. cfgcmd:: set firewall ipv4 prerouting raw rule <1-999999> - set tcp-mss <500-1460> -.. cfgcmd:: set firewall ipv4 forward filter rule <1-999999> - set tcp-mss <500-1460> -.. cfgcmd:: set firewall ipv4 output [filter | raw] rule <1-999999> - set tcp-mss <500-1460> - - Set the TCP-MSS (TCP maximum segment size) for the connection. - -.. cfgcmd:: set firewall ipv4 prerouting raw rule <1-999999> - set ttl <0-255> -.. cfgcmd:: set firewall ipv4 forward filter rule <1-999999> - set ttl <0-255> -.. cfgcmd:: set firewall ipv4 output [filter | raw] rule <1-999999> - set ttl <0-255> - - Set the TTL (Time to Live) value. - -.. cfgcmd:: set firewall ipv4 forward filter rule <1-999999> - set connection-mark <0-2147483647> -.. cfgcmd:: set firewall ipv4 output [filter | raw] rule <1-999999> - set connection-mark <0-2147483647> - - Set connection mark value. - -******** -Synproxy -******** -Synproxy connections - -.. cfgcmd:: set firewall ipv4 [input | forward] filter rule <1-999999> - action synproxy -.. cfgcmd:: set firewall ipv4 [input | forward] filter rule <1-999999> - protocol tcp -.. cfgcmd:: set firewall ipv4 [input | forward] filter rule <1-999999> - synproxy tcp mss <501-65535> - - Set the TCP-MSS (maximum segment size) for the connection - -.. cfgcmd:: set firewall ipv4 [input | forward] filter rule <1-999999> - synproxy tcp window-scale <1-14> - - Set the window scale factor for TCP window scaling - -Example synproxy -================ -Requirements to enable synproxy: - - * Traffic must be symmetric. - * Synproxy relies on syncookies and TCP timestamps, ensure these are enabled. - * Disable conntrack loose track option. - -.. code-block:: none - - set system sysctl parameter net.ipv4.tcp_timestamps value '1' - - set system conntrack tcp loose disable - set system conntrack ignore ipv4 rule 10 destination port '8080' - set system conntrack ignore ipv4 rule 10 protocol 'tcp' - set system conntrack ignore ipv4 rule 10 tcp flags syn - - set firewall global-options syn-cookies 'enable' - set firewall ipv4 input filter rule 10 action 'synproxy' - set firewall ipv4 input filter rule 10 destination port '8080' - set firewall ipv4 input filter rule 10 inbound-interface name 'eth1' - set firewall ipv4 input filter rule 10 protocol 'tcp' - set firewall ipv4 input filter rule 10 synproxy tcp mss '1460' - set firewall ipv4 input filter rule 10 synproxy tcp window-scale '7' - set firewall ipv4 input filter rule 1000 action 'drop' - set firewall ipv4 input filter rule 1000 state invalid - -*********************** -Operation-mode Firewall -*********************** - -Rule-set overview -================= - -.. opcmd:: show firewall - - This will show you a basic firewall overview, for all rule-sets, not - only for IPv4. - - .. code-block:: none - - vyos@vyos:~$ show firewall - Rulesets Information - - --------------------------------- - ipv4 Firewall "forward filter" - - Rule Action Protocol Packets Bytes Conditions - ------- -------- ---------- --------- ------- ----------------------------- - 20 accept all 0 0 ip saddr @N_TRUSTEDv4 accept - 21 jump all 0 0 jump NAME_AUX - default accept all 0 0 - - --------------------------------- - ipv4 Firewall "input filter" - - Rule Action Protocol Packets Bytes Conditions - ------- -------- ---------- --------- ------- ------------------------- - 10 accept all 156 14377 iifname != @I_LAN accept - default accept all 0 0 - - --------------------------------- - ipv4 Firewall "name AUX" - - Rule Action Protocol Packets Bytes Conditions - ------ -------- ---------- --------- ------- -------------------------------------------- - 10 accept icmp 0 0 meta l4proto icmp accept - 20 accept udp 0 0 meta l4proto udp ip saddr @A_SERVERS accept - 30 drop all 0 0 ip saddr != @A_SERVERS iifname "eth2" - - --------------------------------- - ipv4 Firewall "output filter" - - Rule Action Protocol Packets Bytes Conditions - ------- -------- ---------- --------- ------- ---------------------------------------- - 10 reject all 0 0 oifname @I_LAN - 20 accept icmp 2 168 meta l4proto icmp oifname "eth0" accept - default accept all 72 9258 - - --------------------------------- - ipv6 Firewall "input filter" - - Rule Action Protocol Packets Bytes Conditions - ------- -------- ---------- --------- ------- ------------------------------- - 10 accept all 0 0 ip6 saddr @N6_TRUSTEDv6 accept - default accept all 2 112 - - vyos@vyos:~$ - -.. opcmd:: show firewall summary - - This shows you a summary of rule-sets and groups. - - .. code-block:: none - - vyos@vyos:~$ show firewall summary - Ruleset Summary - - IPv6 Ruleset: - - Ruleset Hook Ruleset Priority Description - -------------- -------------------- ------------------------- - forward filter - input filter - ipv6_name IPV6-VyOS_MANAGEMENT - ipv6_name IPV6-WAN_IN PUBLIC_INTERNET - - IPv4 Ruleset: - - Ruleset Hook Ruleset Priority Description - -------------- ------------------ ------------------------- - forward filter - input filter - name VyOS_MANAGEMENT - name WAN_IN PUBLIC_INTERNET - - Firewall Groups - - Name Type References Members - ----------------------- ------------------ ----------------------- ---------------- - PBX address_group WAN_IN-100 198.51.100.77 - SERVERS address_group WAN_IN-110 192.0.2.10 - WAN_IN-111 192.0.2.11 - WAN_IN-112 192.0.2.12 - WAN_IN-120 - WAN_IN-121 - WAN_IN-122 - SUPPORT address_group VyOS_MANAGEMENT-20 192.168.1.2 - WAN_IN-20 - PHONE_VPN_SERVERS address_group WAN_IN-160 10.6.32.2 - PINGABLE_ADRESSES address_group WAN_IN-170 192.168.5.2 - WAN_IN-171 - PBX ipv6_address_group IPV6-WAN_IN-100 2001:db8::1 - SERVERS ipv6_address_group IPV6-WAN_IN-110 2001:db8::2 - IPV6-WAN_IN-111 2001:db8::3 - IPV6-WAN_IN-112 2001:db8::4 - IPV6-WAN_IN-120 - IPV6-WAN_IN-121 - IPV6-WAN_IN-122 - SUPPORT ipv6_address_group IPV6-VyOS_MANAGEMENT-20 2001:db8::5 - IPV6-WAN_IN-20 - - -.. opcmd:: show firewall ipv4 [forward | input | output] filter - -.. opcmd:: show firewall ipv4 name <name> - - This command will give an overview of a single rule-set. - - .. code-block:: none - - vyos@vyos:~$ show firewall ipv4 input filter - Ruleset Information - - --------------------------------- - IPv4 Firewall "input filter" - - Rule Action Protocol Packets Bytes Conditions - ------- -------- ---------- --------- ------- ----------------------------------------- - 5 jump all 0 0 iifname "eth2" jump NAME_VyOS_MANAGEMENT - default accept all - -.. opcmd:: show firewall ipv4 [forward | input | output] - filter rule <1-999999> -.. opcmd:: show firewall ipv4 name <name> rule <1-999999> - - This command gives an overview of a rule in a single rule-set, plus - information for default action. - -.. code-block:: none - - vyos@vyos:~$show firewall ipv4 output filter rule 20 - Rule Information - - --------------------------------- - ipv4 Firewall "output filter" - - Rule Action Protocol Packets Bytes Conditions - ------- -------- ---------- --------- ------- ---------------------------------------- - 20 accept icmp 2 168 meta l4proto icmp oifname "eth0" accept - default accept all 286 47614 - - vyos@vyos:~$ - - -.. opcmd:: show firewall statistics - - This will show you statistics of all rule-sets since the last boot. - -Show Firewall log -================= - -.. opcmd:: show log firewall -.. opcmd:: show log firewall ipv4 -.. opcmd:: show log firewall ipv4 [forward | input | output | name] -.. opcmd:: show log firewall ipv4 [forward | input | output] filter -.. opcmd:: show log firewall ipv4 name <name> -.. 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 - for particular hook; show all logs for particular hook and priority; - show all logs for particular custom chain; show logs for specific rule-set. - -Example Partial Config -====================== - -.. code-block:: none - - firewall { - group { - network-group BAD-NETWORKS { - network 198.51.100.0/24 - network 203.0.113.0/24 - } - network-group GOOD-NETWORKS { - network 192.0.2.0/24 - } - port-group BAD-PORTS { - port 65535 - } - } - ipv4 { - forward { - filter { - default-action accept - rule 5 { - action accept - source { - group { - network-group GOOD-NETWORKS - } - } - } - rule 10 { - action drop - description "Bad Networks" - protocol all - source { - group { - network-group BAD-NETWORKS - } - } - } - } - } - } - } - -Update geoip database -===================== - -.. opcmd:: update geoip - - Command to update GeoIP database and firewall sets. diff --git a/docs/configuration/firewall/rst-ipv6.rst b/docs/configuration/firewall/rst-ipv6.rst deleted file mode 100644 index d31ceb6f..00000000 --- a/docs/configuration/firewall/rst-ipv6.rst +++ /dev/null @@ -1,1302 +0,0 @@ -:lastproofread: 2026-04-01 - -.. _firewall-ipv6-configuration: - -########################### -IPv6 Firewall Configuration -########################### - -******** -Overview -******** - -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 ... - -To learn about the general traffic flow in VyOS firewalls, -see :doc:`Firewall </configuration/firewall/index>`. - -.. code-block:: none - - - set firewall - * ipv6 - - forward - + filter - - input - + filter - - output - + filter - + raw - - prerouting - + raw - - name - + custom_name - -The router first receives all traffic and processes it in the **prerouting** -section. - -This stage includes: - - * **Firewall Prerouting**: commands found under ``set firewall ipv6 - prerouting raw ...`` - * :doc:`Conntrack Ignore</configuration/system/conntrack>`: ``set system - conntrack ignore ipv6...`` - * :doc:`Policy Route</configuration/policy/route>`: commands found under - ``set policy route6 ...`` - * :doc:`Destination NAT</configuration/nat/nat44>`: commands found under - ``set nat66 destination ...`` - -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.* - -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 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.* - -Use ``set firewall ipv6 input filter ...`` to configure traffic destined to -the router. - -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**, 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 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** - -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 -****************************** - -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 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 : - - * ``accept``: accept the packet. - - * ``continue``: continue parsing next rule. - - * ``drop``: drop the packet. - - * ``reject``: reject the packet. - - * ``jump``: jump to another custom chain. - - * ``return``: Return from the current chain and continue at the next rule - of the last chain. - - * ``queue``: Enqueue packet to userspace. - - * ``synproxy``: synproxy the packet. - -.. cfgcmd:: set firewall ipv6 forward filter rule <1-999999> action - [accept | continue | drop | jump | queue | reject | return | synproxy] -.. cfgcmd:: set firewall ipv6 input filter rule <1-999999> action - [accept | continue | drop | jump | queue | reject | return | synproxy] -.. cfgcmd:: set firewall ipv6 output filter rule <1-999999> action - [accept | continue | drop | jump | queue | reject | return] -.. 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 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> -.. cfgcmd:: set firewall ipv6 input filter rule <1-999999> - jump-target <text> -.. cfgcmd:: set firewall ipv6 output filter rule <1-999999> - jump-target <text> -.. cfgcmd:: set firewall ipv6 name <name> rule <1-999999> - jump-target <text> - - 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> -.. cfgcmd:: set firewall ipv6 input filter rule <1-999999> - queue <0-65535> -.. cfgcmd:: set firewall ipv6 output filter rule <1-999999> - queue <0-65535> -.. cfgcmd:: set firewall ipv6 name <name> rule <1-999999> - queue <0-65535> - - 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 -.. cfgcmd:: set firewall ipv6 input filter rule <1-999999> - queue-options bypass -.. cfgcmd:: set firewall ipv6 output filter rule <1-999999> - queue-options bypass -.. cfgcmd:: set firewall ipv6 name <name> rule <1-999999> - queue-options bypass - - 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 -.. cfgcmd:: set firewall ipv6 input filter rule <1-999999> - queue-options fanout -.. cfgcmd:: set firewall ipv6 output filter rule <1-999999> - queue-options fanout -.. cfgcmd:: set firewall ipv6 name <name> rule <1-999999> - queue-options fanout - - 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 -**default-action** are **accept** or **drop**. - -.. cfgcmd:: set firewall ipv6 forward filter default-action - [accept | drop] -.. cfgcmd:: set firewall ipv6 input filter default-action - [accept | drop] -.. cfgcmd:: set firewall ipv6 output filter default-action - [accept | drop] -.. cfgcmd:: set firewall ipv6 name <name> default-action - [accept | drop | jump | queue | reject | return] - - 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> - - To be used only when ``default-action`` is set to ``jump``. Use this - command to specify the jump target for the default rule. - -.. note:: **Important note about default-actions:** - 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 -============= - -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 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 -.. cfgcmd:: set firewall ipv6 output filter default-log -.. cfgcmd:: set firewall ipv6 name <name> default-log - - Use this command to enable the logging of the default action on - the specified chain. - -.. cfgcmd:: set firewall ipv6 forward filter rule <1-999999> - log-options level [emerg | alert | crit | err | warn | notice - | info | debug] -.. cfgcmd:: set firewall ipv6 input filter rule <1-999999> - log-options level [emerg | alert | crit | err | warn | notice - | info | debug] -.. cfgcmd:: set firewall ipv6 output filter rule <1-999999> - log-options level [emerg | alert | crit | err | warn | notice - | info | debug] -.. cfgcmd:: set firewall ipv6 name <name> rule <1-999999> - log-options level [emerg | alert | crit | err | warn | notice - | info | debug] - - Define log-level. Only applicable if rule log is enabled. - -.. cfgcmd:: set firewall ipv6 forward filter rule <1-999999> - log-options group <0-65535> -.. cfgcmd:: set firewall ipv6 input filter rule <1-999999> - log-options group <0-65535> -.. cfgcmd:: set firewall ipv6 output filter rule <1-999999> - log-options group <0-65535> -.. cfgcmd:: set firewall ipv6 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. - -.. cfgcmd:: set firewall ipv6 forward filter rule <1-999999> - log-options snapshot-length <0-9000> -.. cfgcmd:: set firewall ipv6 input filter rule <1-999999> - log-options snapshot-length <0-9000> -.. cfgcmd:: set firewall ipv6 output filter rule <1-999999> - log-options snapshot-length <0-9000> -.. cfgcmd:: set firewall ipv6 name <name> rule <1-999999> - log-options snapshot-length <0-9000> - - Define the length of packet payload to include in a netlink message. Only - 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> -.. cfgcmd:: set firewall ipv6 input filter rule <1-999999> - log-options queue-threshold <0-65535> -.. cfgcmd:: set firewall ipv6 output filter rule <1-999999> - log-options queue-threshold <0-65535> -.. cfgcmd:: set firewall ipv6 name <name> rule <1-999999> - log-options queue-threshold <0-65535> - - Define the number of packets to queue inside the kernel before sending them - to userspace. Only applicable when rule logging is enabled and log group is - defined. - -Firewall Description -==================== - -For reference, you can define descriptions on every rule and custom chain. - -.. cfgcmd:: set firewall ipv6 name <name> description <text> - - Provide a rule-set description to a custom firewall chain. - -.. cfgcmd:: set firewall ipv6 forward filter rule <1-999999> - description <text> -.. cfgcmd:: set firewall ipv6 input filter rule <1-999999> - description <text> -.. cfgcmd:: set firewall ipv6 output filter rule <1-999999> - description <text> -.. cfgcmd:: set firewall ipv6 name <name> rule <1-999999> description <text> - - Provide a description for each rule. - -Rule Status -=========== - -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 -.. cfgcmd:: set firewall ipv6 output filter rule <1-999999> disable -.. cfgcmd:: set firewall ipv6 name <name> rule <1-999999> disable - - Command for disabling a rule but keep it in the configuration. - -Matching criteria -================= - -There are a lot of matching criteria against which the packet can be tested. - -.. cfgcmd:: set firewall ipv6 forward filter rule <1-999999> - connection-status nat [destination | source] -.. cfgcmd:: set firewall ipv6 input filter rule <1-999999> - connection-status nat [destination | source] -.. cfgcmd:: set firewall ipv6 output filter rule <1-999999> - connection-status nat [destination | source] -.. cfgcmd:: set firewall ipv6 name <name> rule <1-999999> - connection-status nat [destination | source] - - Match packets based on NAT connection status. - -.. cfgcmd:: set firewall ipv6 forward filter rule <1-999999> - connection-mark <1-2147483647> -.. cfgcmd:: set firewall ipv6 input filter rule <1-999999> - connection-mark <1-2147483647> -.. cfgcmd:: set firewall ipv6 output filter rule <1-999999> - connection-mark <1-2147483647> -.. cfgcmd:: set firewall ipv6 name <name> rule <1-999999> - connection-mark <1-2147483647> - - Match packets based on connection mark. - -.. cfgcmd:: set firewall ipv6 forward filter rule <1-999999> - source address [address | addressrange | CIDR] -.. cfgcmd:: set firewall ipv6 input filter rule <1-999999> - source address [address | addressrange | CIDR] -.. cfgcmd:: set firewall ipv6 output filter rule <1-999999> - source address [address | addressrange | CIDR] -.. cfgcmd:: set firewall ipv6 name <name> rule <1-999999> - source address [address | addressrange | CIDR] - -.. cfgcmd:: set firewall ipv6 forward filter rule <1-999999> - destination address [address | addressrange | CIDR] -.. cfgcmd:: set firewall ipv6 input filter rule <1-999999> - destination address [address | addressrange | CIDR] -.. cfgcmd:: set firewall ipv6 output filter rule <1-999999> - destination address [address | addressrange | CIDR] -.. cfgcmd:: set firewall ipv6 name <name> rule <1-999999> - destination address [address | addressrange | CIDR] - - Match based on source or destination address. This is similar to network - groups, but you can negate the matching addresses here. - - .. code-block:: none - - set firewall ipv6 name FOO rule 100 source address 2001:db8::202 - -.. cfgcmd:: set firewall ipv6 forward filter rule <1-999999> - source address-mask [address] -.. cfgcmd:: set firewall ipv6 input filter rule <1-999999> - source address-mask [address] -.. cfgcmd:: set firewall ipv6 output filter rule <1-999999> - source address-mask [address] -.. cfgcmd:: set firewall ipv6 name <name> rule <1-999999> - source address-mask [address] - -.. cfgcmd:: set firewall ipv6 forward filter rule <1-999999> - destination address-mask [address] -.. cfgcmd:: set firewall ipv6 input filter rule <1-999999> - destination address-mask [address] -.. cfgcmd:: set firewall ipv6 output filter rule <1-999999> - destination address-mask [address] -.. cfgcmd:: set firewall ipv6 name <name> rule <1-999999> - destination address-mask [address] - - 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 function works for both individual addresses and address groups. - - .. stop_vyoslinter - .. code-block:: none - - # Match any IPv6 address with the suffix ::0000:0000:0000:beef - set firewall ipv6 forward filter rule 100 destination address ::beef - set firewall ipv6 forward filter rule 100 destination address-mask ::ffff:ffff:ffff:ffff - # Address groups - set firewall group ipv6-address-group WEBSERVERS address ::1000 - set firewall group ipv6-address-group WEBSERVERS address ::2000 - set firewall ipv6 forward filter rule 200 source group address-group WEBSERVERS - set firewall ipv6 forward filter rule 200 source address-mask ::ffff:ffff:ffff:ffff - - .. start_vyoslinter - -.. cfgcmd:: set firewall ipv6 forward filter rule <1-999999> - source fqdn <fqdn> -.. cfgcmd:: set firewall ipv6 input filter rule <1-999999> - source fqdn <fqdn> -.. cfgcmd:: set firewall ipv6 output filter rule <1-999999> - source fqdn <fqdn> -.. cfgcmd:: set firewall ipv6 name <name> rule <1-999999> - source fqdn <fqdn> -.. cfgcmd:: set firewall ipv6 forward filter rule <1-999999> - destination fqdn <fqdn> -.. cfgcmd:: set firewall ipv6 input filter rule <1-999999> - destination fqdn <fqdn> -.. cfgcmd:: set firewall ipv6 output filter rule <1-999999> - destination fqdn <fqdn> -.. cfgcmd:: set firewall ipv6 name <name> rule <1-999999> - destination fqdn <fqdn> - - 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> -.. cfgcmd:: set firewall ipv6 input filter rule <1-999999> - source geoip country-code <country> -.. cfgcmd:: set firewall ipv6 output filter rule <1-999999> - source geoip country-code <country> -.. cfgcmd:: set firewall ipv6 name <name> rule <1-999999> - source geoip country-code <country> - -.. cfgcmd:: set firewall ipv6 forward filter rule <1-999999> - destination geoip country-code <country> -.. cfgcmd:: set firewall ipv6 input filter rule <1-999999> - destination geoip country-code <country> -.. cfgcmd:: set firewall ipv6 output filter rule <1-999999> - destination geoip country-code <country> -.. cfgcmd:: set firewall ipv6 name <name> rule <1-999999> - destination geoip country-code <country> - -.. cfgcmd:: set firewall ipv6 forward filter rule <1-999999> - source geoip inverse-match -.. cfgcmd:: set firewall ipv6 input filter rule <1-999999> - source geoip inverse-match -.. cfgcmd:: set firewall ipv6 output filter rule <1-999999> - source geoip inverse-match -.. cfgcmd:: set firewall ipv6 name <name> rule <1-999999> - source geoip inverse-match - -.. cfgcmd:: set firewall ipv6 forward filter rule <1-999999> - destination geoip inverse-match -.. cfgcmd:: set firewall ipv6 input filter rule <1-999999> - destination geoip inverse-match -.. cfgcmd:: set firewall ipv6 output filter rule <1-999999> - destination geoip inverse-match -.. cfgcmd:: set firewall ipv6 name <name> rule <1-999999> - destination geoip inverse-match - - 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. - -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> - source mac-address <mac-address> -.. cfgcmd:: set firewall ipv6 input filter rule <1-999999> - source mac-address <mac-address> -.. cfgcmd:: set firewall ipv6 output filter rule <1-999999> - source mac-address <mac-address> -.. cfgcmd:: set firewall ipv6 name <name> rule <1-999999> - source mac-address <mac-address> - - You can specify only a source MAC address to match. - - .. code-block:: none - - set firewall ipv6 input filter rule 100 source mac-address 00:53:00:11:22:33 - set firewall ipv6 input filter rule 101 source mac-address !00:53:00:aa:12:34 - -.. cfgcmd:: set firewall ipv6 forward filter rule <1-999999> - source port [1-65535 | portname | start-end] -.. cfgcmd:: set firewall ipv6 input filter rule <1-999999> - source port [1-65535 | portname | start-end] -.. cfgcmd:: set firewall ipv6 output filter rule <1-999999> - source port [1-65535 | portname | start-end] -.. cfgcmd:: set firewall ipv6 name <name> rule <1-999999> - source port [1-65535 | portname | start-end] - -.. cfgcmd:: set firewall ipv6 forward filter rule <1-999999> - destination port [1-65535 | portname | start-end] -.. cfgcmd:: set firewall ipv6 input filter rule <1-999999> - destination port [1-65535 | portname | start-end] -.. cfgcmd:: set firewall ipv6 output filter rule <1-999999> - destination port [1-65535 | portname | start-end] -.. cfgcmd:: set firewall ipv6 name <name> rule <1-999999> - destination port [1-65535 | portname | start-end] - - Specify a port by number or by name as defined in ``/etc/services``. - - .. code-block:: none - - set firewall ipv6 forward filter rule 10 source port '22' - set firewall ipv6 forward filter rule 11 source port '!http' - set firewall ipv6 forward filter rule 12 source port 'https' - - Multiple source ports can be specified as a comma-separated list. - The whole list can also be "negated" using ``!``. For example: - - .. code-block:: none - - set firewall ipv6 forward filter rule 10 source port '!22,https,3333-3338' - -.. cfgcmd:: set firewall ipv6 forward filter rule <1-999999> - source group address-group <name | !name> -.. cfgcmd:: set firewall ipv6 input filter rule <1-999999> - source group address-group <name | !name> -.. cfgcmd:: set firewall ipv6 output filter rule <1-999999> - source group address-group <name | !name> -.. cfgcmd:: set firewall ipv6 name <name> rule <1-999999> - source group address-group <name | !name> - -.. cfgcmd:: set firewall ipv6 forward filter rule <1-999999> - destination group address-group <name | !name> -.. cfgcmd:: set firewall ipv6 input filter rule <1-999999> - destination group address-group <name | !name> -.. cfgcmd:: set firewall ipv6 output filter rule <1-999999> - destination group address-group <name | !name> -.. cfgcmd:: set firewall ipv6 name <name> rule <1-999999> - destination group address-group <name | !name> - - 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> -.. cfgcmd:: set firewall ipv6 input filter rule <1-999999> - source group dynamic-address-group <name | !name> -.. cfgcmd:: set firewall ipv6 output filter rule <1-999999> - source group dynamic-address-group <name | !name> -.. cfgcmd:: set firewall ipv6 name <name> rule <1-999999> - source group dynamic-address-group <name | !name> - -.. cfgcmd:: set firewall ipv6 forward filter rule <1-999999> - destination group dynamic-address-group <name | !name> -.. cfgcmd:: set firewall ipv6 input filter rule <1-999999> - destination group dynamic-address-group <name | !name> -.. cfgcmd:: set firewall ipv6 output filter rule <1-999999> - destination group dynamic-address-group <name | !name> -.. cfgcmd:: set firewall ipv6 name <name> rule <1-999999> - destination group dynamic-address-group <name | !name> - - 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> -.. cfgcmd:: set firewall ipv6 input filter rule <1-999999> - source group network-group <name | !name> -.. cfgcmd:: set firewall ipv6 output filter rule <1-999999> - source group network-group <name | !name> -.. cfgcmd:: set firewall ipv6 name <name> rule <1-999999> - source group network-group <name | !name> - -.. cfgcmd:: set firewall ipv6 forward filter rule <1-999999> - destination group network-group <name | !name> -.. cfgcmd:: set firewall ipv6 input filter rule <1-999999> - destination group network-group <name | !name> -.. cfgcmd:: set firewall ipv6 output filter rule <1-999999> - destination group network-group <name | !name> -.. cfgcmd:: set firewall ipv6 name <name> rule <1-999999> - destination group network-group <name | !name> - - 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> -.. cfgcmd:: set firewall ipv6 input filter rule <1-999999> - source group port-group <name | !name> -.. cfgcmd:: set firewall ipv6 output filter rule <1-999999> - source group port-group <name | !name> -.. cfgcmd:: set firewall ipv6 name <name> rule <1-999999> - source group port-group <name | !name> - -.. cfgcmd:: set firewall ipv6 forward filter rule <1-999999> - destination group port-group <name | !name> -.. cfgcmd:: set firewall ipv6 input filter rule <1-999999> - destination group port-group <name | !name> -.. cfgcmd:: set firewall ipv6 output filter rule <1-999999> - destination group port-group <name | !name> -.. cfgcmd:: set firewall ipv6 name <name> rule <1-999999> - destination group port-group <name | !name> - - 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> -.. cfgcmd:: set firewall ipv6 input filter rule <1-999999> - source group domain-group <name | !name> -.. cfgcmd:: set firewall ipv6 output filter rule <1-999999> - source group domain-group <name | !name> -.. cfgcmd:: set firewall ipv6 name <name> rule <1-999999> - source group domain-group <name | !name> - -.. cfgcmd:: set firewall ipv6 forward filter rule <1-999999> - destination group domain-group <name | !name> -.. cfgcmd:: set firewall ipv6 input filter rule <1-999999> - destination group domain-group <name | !name> -.. cfgcmd:: set firewall ipv6 output filter rule <1-999999> - destination group domain-group <name | !name> -.. cfgcmd:: set firewall ipv6 name <name> rule <1-999999> - destination group domain-group <name | !name> - - 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> -.. cfgcmd:: set firewall ipv6 input filter rule <1-999999> - source group mac-group <name | !name> -.. cfgcmd:: set firewall ipv6 output filter rule <1-999999> - source group mac-group <name | !name> -.. cfgcmd:: set firewall ipv6 name <name> rule <1-999999> - source group mac-group <name | !name> - -.. cfgcmd:: set firewall ipv6 forward filter rule <1-999999> - destination group mac-group <name | !name> -.. cfgcmd:: set firewall ipv6 input filter rule <1-999999> - destination group mac-group <name | !name> -.. cfgcmd:: set firewall ipv6 output filter rule <1-999999> - destination group mac-group <name | !name> -.. cfgcmd:: set firewall ipv6 name <name> rule <1-999999> - destination group mac-group <name | !name> - - 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] -.. cfgcmd:: set firewall ipv6 input filter rule <1-999999> - dscp [0-63 | start-end] -.. cfgcmd:: set firewall ipv6 output filter rule <1-999999> - dscp [0-63 | start-end] -.. cfgcmd:: set firewall ipv6 name <name> rule <1-999999> - dscp [0-63 | start-end] - -.. cfgcmd:: set firewall ipv6 forward filter rule <1-999999> - dscp-exclude [0-63 | start-end] -.. cfgcmd:: set firewall ipv6 input filter rule <1-999999> - dscp-exclude [0-63 | start-end] -.. cfgcmd:: set firewall ipv6 output filter rule <1-999999> - dscp-exclude [0-63 | start-end] -.. cfgcmd:: set firewall ipv6 name <name> rule <1-999999> - dscp-exclude [0-63 | start-end] - - Match based on dscp value. - -.. cfgcmd:: set firewall ipv6 forward filter rule <1-999999> - fragment [match-frag | match-non-frag] -.. cfgcmd:: set firewall ipv6 input filter rule <1-999999> - fragment [match-frag | match-non-frag] -.. cfgcmd:: set firewall ipv6 output filter rule <1-999999> - fragment [match-frag | match-non-frag] -.. cfgcmd:: set firewall ipv6 name <name> rule <1-999999> - fragment [match-frag | match-non-frag] - - Match packets based on fragmentation. - -.. cfgcmd:: set firewall ipv6 forward filter rule <1-999999> - icmpv6 [code | type] <0-255> -.. cfgcmd:: set firewall ipv6 input filter rule <1-999999> - icmpv6 [code | type] <0-255> -.. cfgcmd:: set firewall ipv6 output filter rule <1-999999> - icmpv6 [code | type] <0-255> -.. cfgcmd:: set firewall ipv6 name <name> rule <1-999999> - icmpv6 [code | type] <0-255> - - Match packets based on ICMP or ICMPv6 code and type. - -.. cfgcmd:: set firewall ipv6 forward filter rule <1-999999> - icmpv6 type-name <text> -.. cfgcmd:: set firewall ipv6 input filter rule <1-999999> - icmpv6 type-name <text> -.. cfgcmd:: set firewall ipv6 output filter rule <1-999999> - icmpv6 type-name <text> -.. cfgcmd:: set firewall ipv6 name <name> rule <1-999999> - icmpv6 type-name <text> - - 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> -.. cfgcmd:: set firewall ipv6 input filter rule <1-999999> - inbound-interface name <iface> -.. cfgcmd:: set firewall ipv6 name <name> rule <1-999999> - inbound-interface name <iface> - - 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**, 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> -.. cfgcmd:: set firewall ipv6 input filter rule <1-999999> - inbound-interface group <iface_group> -.. cfgcmd:: set firewall ipv6 name <name> rule <1-999999> - inbound-interface group <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> -.. cfgcmd:: set firewall ipv6 output filter rule <1-999999> - outbound-interface name <iface> -.. cfgcmd:: set firewall ipv6 name <name> rule <1-999999> - outbound-interface name <iface> - - 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**, 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> - outbound-interface group <iface_group> -.. cfgcmd:: set firewall ipv6 output filter rule <1-999999> - outbound-interface group <iface_group> -.. cfgcmd:: set firewall ipv6 name <name> rule <1-999999> - outbound-interface group <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] -.. cfgcmd:: set firewall ipv6 input filter rule <1-999999> - ipsec [match-ipsec-in | match-none-in] -.. cfgcmd:: set firewall ipv6 output filter rule <1-999999> - ipsec [match-ipsec-out | match-none-out] -.. cfgcmd:: set firewall ipv6 name <name> rule <1-999999> - ipsec [match-ipsec-in | match-ipsec-out | match-none-in | match-none-out] - - Match packets based on IPsec. - -.. cfgcmd:: set firewall ipv6 forward filter rule <1-999999> - limit burst <0-4294967295> -.. cfgcmd:: set firewall ipv6 input filter rule <1-999999> - limit burst <0-4294967295> -.. cfgcmd:: set firewall ipv6 output filter rule <1-999999> - limit burst <0-4294967295> -.. cfgcmd:: set firewall ipv6 name <name> rule <1-999999> - limit burst <0-4294967295> - - 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> -.. cfgcmd:: set firewall ipv6 input filter rule <1-999999> - limit rate <text> -.. cfgcmd:: set firewall ipv6 output filter rule <1-999999> - limit rate <text> -.. 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, specify ``5/minutes``. - -.. cfgcmd:: set firewall ipv6 forward filter rule <1-999999> - packet-length <text> -.. cfgcmd:: set firewall ipv6 input filter rule <1-999999> - packet-length <text> -.. cfgcmd:: set firewall ipv6 output filter rule <1-999999> - packet-length <text> -.. cfgcmd:: set firewall ipv6 name <name> rule <1-999999> - packet-length <text> - -.. cfgcmd:: set firewall ipv6 forward filter rule <1-999999> - packet-length-exclude <text> -.. cfgcmd:: set firewall ipv6 input filter rule <1-999999> - packet-length-exclude <text> -.. cfgcmd:: set firewall ipv6 output filter rule <1-999999> - packet-length-exclude <text> -.. cfgcmd:: set firewall ipv6 name <name> rule <1-999999> - packet-length-exclude <text> - - 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] -.. cfgcmd:: set firewall ipv6 input filter rule <1-999999> - packet-type [broadcast | host | multicast | other] -.. cfgcmd:: set firewall ipv6 output filter rule <1-999999> - packet-type [broadcast | host | multicast | other] -.. cfgcmd:: set firewall ipv6 name <name> rule <1-999999> - packet-type [broadcast | host | multicast | other] - - Match based on packet type. - -.. cfgcmd:: set firewall ipv6 forward filter rule <1-999999> - protocol [<text> | <0-255> | all | tcp_udp] -.. cfgcmd:: set firewall ipv6 input filter rule <1-999999> - protocol [<text> | <0-255> | all | tcp_udp] -.. cfgcmd:: set firewall ipv6 output filter rule <1-999999> - protocol [<text> | <0-255> | all | tcp_udp] -.. cfgcmd:: set firewall ipv6 name <name> rule <1-999999> - protocol [<text> | <0-255> | all | tcp_udp] - - Match based on protocol number or name as defined in ``/etc/protocols``. - Specify ``all`` for all protocols and ``tcp_udp`` for TCP and UDP packets. - Prepend ``!`` to negate the protocol selection. - - .. code-block:: none - - set firewall ipv6 input filter rule 10 protocol tcp - -.. cfgcmd:: set firewall ipv6 forward filter rule <1-999999> - recent count <1-255> -.. cfgcmd:: set firewall ipv6 input filter rule <1-999999> - recent count <1-255> -.. cfgcmd:: set firewall ipv6 output filter rule <1-999999> - recent count <1-255> -.. cfgcmd:: set firewall ipv6 name <name> rule <1-999999> - recent count <1-255> - -.. cfgcmd:: set firewall ipv6 forward filter rule <1-999999> - recent time [second | minute | hour] -.. cfgcmd:: set firewall ipv6 input filter rule <1-999999> - recent time [second | minute | hour] -.. cfgcmd:: set firewall ipv6 output filter rule <1-999999> - recent time [second | minute | hour] -.. cfgcmd:: set firewall ipv6 name <name> rule <1-999999> - recent time [second | minute | hour] - - Match packets based on recently seen sources. - -.. cfgcmd:: set firewall ipv6 forward filter rule <1-999999> - tcp flags [not] <text> -.. cfgcmd:: set firewall ipv6 input filter rule <1-999999> - tcp flags [not] <text> -.. cfgcmd:: set firewall ipv6 output filter rule <1-999999> - tcp flags [not] <text> -.. cfgcmd:: set firewall ipv6 name <name> rule <1-999999> - tcp flags [not] <text> - - 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 - - set firewall ipv6 input filter rule 10 tcp flags 'ack' - set firewall ipv6 input filter rule 12 tcp flags 'syn' - set firewall ipv6 input filter rule 13 tcp flags not 'fin' - -.. cfgcmd:: set firewall ipv6 forward filter rule <1-999999> - state [established | invalid | new | related] -.. cfgcmd:: set firewall ipv6 input filter rule <1-999999> - state [established | invalid | new | related] -.. cfgcmd:: set firewall ipv6 output filter rule <1-999999> - state [established | invalid | new | related] -.. cfgcmd:: set firewall ipv6 name <name> rule <1-999999> - state [established | invalid | new | related] - - Match based on packet state. - -.. cfgcmd:: set firewall ipv6 forward filter rule <1-999999> - time startdate <text> -.. cfgcmd:: set firewall ipv6 input filter rule <1-999999> - time startdate <text> -.. cfgcmd:: set firewall ipv6 output filter rule <1-999999> - time startdate <text> -.. cfgcmd:: set firewall ipv6 name <name> rule <1-999999> - time startdate <text> -.. cfgcmd:: set firewall ipv6 forward filter rule <1-999999> - time starttime <text> -.. cfgcmd:: set firewall ipv6 input filter rule <1-999999> - time starttime <text> -.. cfgcmd:: set firewall ipv6 output filter rule <1-999999> - time starttime <text> -.. cfgcmd:: set firewall ipv6 name <name> rule <1-999999> - time starttime <text> -.. cfgcmd:: set firewall ipv6 forward filter rule <1-999999> - time stopdate <text> -.. cfgcmd:: set firewall ipv6 input filter rule <1-999999> - time stopdate <text> -.. cfgcmd:: set firewall ipv6 output filter rule <1-999999> - time stopdate <text> -.. cfgcmd:: set firewall ipv6 name <name> rule <1-999999> - time stopdate <text> -.. cfgcmd:: set firewall ipv6 forward filter rule <1-999999> - time stoptime <text> -.. cfgcmd:: set firewall ipv6 input filter rule <1-999999> - time stoptime <text> -.. cfgcmd:: set firewall ipv6 output filter rule <1-999999> - time stoptime <text> -.. cfgcmd:: set firewall ipv6 name <name> rule <1-999999> - time stoptime <text> -.. cfgcmd:: set firewall ipv6 forward filter rule <1-999999> - time weekdays <text> -.. cfgcmd:: set firewall ipv6 input filter rule <1-999999> - time weekdays <text> -.. cfgcmd:: set firewall ipv6 output filter rule <1-999999> - time weekdays <text> -.. cfgcmd:: set firewall ipv6 name <name> rule <1-999999> - time weekdays <text> - - Match packets based on time criteria. - -.. cfgcmd:: set firewall ipv6 forward filter rule <1-999999> - hop-limit <eq | gt | lt> <0-255> -.. cfgcmd:: set firewall ipv6 input filter rule <1-999999> - hop-limit <eq | gt | lt> <0-255> -.. cfgcmd:: set firewall ipv6 output filter rule <1-999999> - hop-limit <eq | gt | lt> <0-255> -.. cfgcmd:: set firewall ipv6 name <name> rule <1-999999> - hop-limit <eq | gt | lt> <0-255> - - 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> -.. cfgcmd:: set firewall ipv6 input filter rule <1-999999> - recent count <1-255> -.. cfgcmd:: set firewall ipv6 output filter rule <1-999999> - recent count <1-255> -.. cfgcmd:: set firewall ipv6 name <name> rule <1-999999> - recent count <1-255> - -.. cfgcmd:: set firewall ipv6 forward filter rule <1-999999> - recent time <second | minute | hour> -.. cfgcmd:: set firewall ipv6 input filter rule <1-999999> - recent time <second | minute | hour> -.. cfgcmd:: set firewall ipv6 output filter rule <1-999999> - recent time <second | minute | hour> -.. cfgcmd:: set firewall ipv6 name <name> rule <1-999999> - recent time <second | minute | hour> - - Match when the specified number of connections occur within the specified - time period. Use these criteria to block brute-force attempts. - -Packet Modifications -==================== - -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> -.. cfgcmd:: set firewall ipv6 forward filter rule <1-999999> - set dscp <0-63> -.. cfgcmd:: set firewall ipv6 output [filter | raw] rule <1-999999> - set dscp <0-63> - - Set a specific value of Differentiated Services Codepoint (DSCP). - -.. cfgcmd:: set firewall ipv6 prerouting raw rule <1-999999> - set mark <1-2147483647> -.. cfgcmd:: set firewall ipv6 forward filter rule <1-999999> - set mark <1-2147483647> -.. cfgcmd:: set firewall ipv6 output [filter | raw] rule <1-999999> - set mark <1-2147483647> - - Set a specific packet mark value. - -.. cfgcmd:: set firewall ipv6 prerouting raw rule <1-999999> - set tcp-mss <500-1460> -.. cfgcmd:: set firewall ipv6 forward filter rule <1-999999> - set tcp-mss <500-1460> -.. cfgcmd:: set firewall ipv6 output [filter | raw] rule <1-999999> - set tcp-mss <500-1460> - - Set the TCP-MSS (TCP maximum segment size) for the connection. - -.. cfgcmd:: set firewall ipv6 prerouting raw rule <1-999999> - set hop-limit <0-255> -.. cfgcmd:: set firewall ipv6 forward filter rule <1-999999> - set hop-limit <0-255> -.. cfgcmd:: set firewall ipv6 output [filter | raw] rule <1-999999> - set hop-limit <0-255> - - Set hop limit value. - -.. cfgcmd:: set firewall ipv6 forward filter rule <1-999999> - set connection-mark <0-2147483647> -.. cfgcmd:: set firewall ipv4 output [filter | raw] rule <1-999999> - set connection-mark <0-2147483647> - - Set connection mark value. - -******** -Synproxy -******** -Synproxy connections - -.. cfgcmd:: set firewall ipv6 [input | forward] filter rule <1-999999> - action synproxy -.. cfgcmd:: set firewall ipv6 [input | forward] filter rule <1-999999> - protocol tcp -.. 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. - -.. cfgcmd:: set firewall ipv6 [input | forward] filter rule <1-999999> - synproxy tcp window-scale <1-14> - - Set the window scale factor for TCP window scaling. - -Example synproxy -================ -Requirements to enable synproxy: - - * Traffic must be symmetric - * Synproxy relies on syncookies and TCP timestamps, ensure these are enabled - * Disable conntrack loose track option - -.. code-block:: none - - set system sysctl parameter net.ipv4.tcp_timestamps value '1' - - set system conntrack tcp loose disable - set system conntrack ignore ipv6 rule 10 destination port '8080' - set system conntrack ignore ipv6 rule 10 protocol 'tcp' - set system conntrack ignore ipv6 rule 10 tcp flags syn - - set firewall global-options syn-cookies 'enable' - set firewall ipv6 input filter rule 10 action 'synproxy' - set firewall ipv6 input filter rule 10 destination port '8080' - set firewall ipv6 input filter rule 10 inbound-interface name 'eth1' - set firewall ipv6 input filter rule 10 protocol 'tcp' - set firewall ipv6 input filter rule 10 synproxy tcp mss '1460' - set firewall ipv6 input filter rule 10 synproxy tcp window-scale '7' - set firewall ipv6 input filter rule 1000 action 'drop' - set firewall ipv6 input filter rule 1000 state invalid - -*********************** -Operation-mode Firewall -*********************** - -Rule-set overview -================= - -.. opcmd:: show firewall - - Show a basic firewall overview for all rule-sets, not only for IPv6: - - .. code-block:: none - - vyos@vyos:~$ show firewall - Rulesets Information - - --------------------------------- - IPv4 Firewall "forward filter" - - Rule Action Protocol Packets Bytes Conditions - ------- -------- ---------- --------- ------- ----------------------------------------- - 5 jump all 0 0 iifname "eth1" jump NAME_VyOS_MANAGEMENT - 10 jump all 0 0 oifname "eth1" jump NAME_WAN_IN - 15 jump all 0 0 iifname "eth3" jump NAME_WAN_IN - default accept all - - --------------------------------- - IPv4 Firewall "name VyOS_MANAGEMENT" - - Rule Action Protocol Packets Bytes Conditions - ------- -------- ---------- --------- ------- -------------------------------- - 5 accept all 0 0 ct state established accept - 10 drop all 0 0 ct state invalid - 20 accept all 0 0 ip saddr @A_GOOD_GUYS accept - 30 accept all 0 0 ip saddr @N_ENTIRE_RANGE accept - 40 accept all 0 0 ip saddr @A_VyOS_SERVERS accept - 50 accept icmp 0 0 meta l4proto icmp accept - default drop all 0 0 - - --------------------------------- - IPv6 Firewall "forward filter" - - Rule Action Protocol - ------- -------- ---------- - 5 jump all - 10 jump all - 15 jump all - default accept all - - --------------------------------- - IPv6 Firewall "input filter" - - Rule Action Protocol - ------- -------- ---------- - 5 jump all - default accept all - - --------------------------------- - IPv6 Firewall "ipv6_name IPV6-VyOS_MANAGEMENT" - - Rule Action Protocol - ------- -------- ---------- - 5 accept all - 10 drop all - 20 accept all - 30 accept all - 40 accept all - 50 accept ipv6-icmp - default drop all - -.. opcmd:: show firewall summary - - This will show you a summary of rule-sets and groups - - .. code-block:: none - - vyos@vyos:~$ show firewall summary - Ruleset Summary - - IPv6 Ruleset: - - Ruleset Hook Ruleset Priority Description - -------------- -------------------- ------------------------- - forward filter - input filter - ipv6_name IPV6-VyOS_MANAGEMENT - ipv6_name IPV6-WAN_IN PUBLIC_INTERNET - - IPv4 Ruleset: - - Ruleset Hook Ruleset Priority Description - -------------- ------------------ ------------------------- - forward filter - input filter - name VyOS_MANAGEMENT - name WAN_IN PUBLIC_INTERNET - - Firewall Groups - - Name Type References Members - ----------------------- ------------------ ----------------------- ---------------- - PBX address_group WAN_IN-100 198.51.100.77 - SERVERS address_group WAN_IN-110 192.0.2.10 - WAN_IN-111 192.0.2.11 - WAN_IN-112 192.0.2.12 - WAN_IN-120 - WAN_IN-121 - WAN_IN-122 - SUPPORT address_group VyOS_MANAGEMENT-20 192.168.1.2 - WAN_IN-20 - PHONE_VPN_SERVERS address_group WAN_IN-160 10.6.32.2 - PINGABLE_ADRESSES address_group WAN_IN-170 192.168.5.2 - WAN_IN-171 - PBX ipv6_address_group IPV6-WAN_IN-100 2001:db8::1 - SERVERS ipv6_address_group IPV6-WAN_IN-110 2001:db8::2 - IPV6-WAN_IN-111 2001:db8::3 - IPV6-WAN_IN-112 2001:db8::4 - IPV6-WAN_IN-120 - IPV6-WAN_IN-121 - IPV6-WAN_IN-122 - SUPPORT ipv6_address_group IPV6-VyOS_MANAGEMENT-20 2001:db8::5 - IPV6-WAN_IN-20 - - -.. opcmd:: show firewall ipv6 [forward | input | output] filter - -.. opcmd:: show firewall ipv6 ipv6-name <name> - - This command will give an overview of a single rule-set. - - .. code-block:: none - - vyos@vyos:~$ show firewall ipv6 input filter - Ruleset Information - - --------------------------------- - ipv6 Firewall "input filter" - - Rule Action Protocol Packets Bytes Conditions - ------- -------- ---------- --------- ------- ------------------------------------------------------------------------------ - 10 jump all 13 1456 iifname "eth1" jump NAME6_INP-ETH1 - 20 accept ipv6-icmp 10 1112 meta l4proto ipv6-icmp iifname "eth0" prefix "[ipv6-INP-filter-20-A]" accept - default accept all 14 1584 - - vyos@vyos:~$ - -.. opcmd:: show firewall ipv6 [forward | input | output] - filter rule <1-999999> - -.. opcmd:: show firewall ipv6 name <name> rule <1-999999> - -.. opcmd:: show firewall ipv6 ipv6-name <name> rule <1-999999> - - This command will give an overview of a rule in a single rule-set - -.. opcmd:: show firewall group <name> - - Show an overview of defined groups, including the type, members, and where - the group is used. - - .. code-block:: none - - vyos@vyos:~$ show firewall group LAN - Firewall Groups - - Name Type References Members - ------------ ------------------ ----------------------- ---------------- - LAN ipv6_network_group IPV6-VyOS_MANAGEMENT-30 2001:db8::0/64 - IPV6-WAN_IN-30 - LAN network_group VyOS_MANAGEMENT-30 192.168.200.0/24 - WAN_IN-30 - - -.. opcmd:: show firewall statistics - - Show statistics of all rule-sets since the last boot. - -Show Firewall log -================= - -.. opcmd:: show log firewall -.. opcmd:: show log firewall ipv6 -.. opcmd:: show log firewall ipv6 [forward | input | output | name] -.. opcmd:: show log firewall ipv6 [forward | input | output] filter -.. opcmd:: show log firewall ipv6 name <name> -.. opcmd:: show log firewall ipv6 [forward | input | output] filter rule <rule> -.. opcmd:: show log firewall ipv6 name <name> rule <rule> - - Show firewall logs for all firewalls, all IPv6 firewalls, specific hooks, - specific priorities, specific custom chains, or specific rule-sets. - -Example Partial Config -====================== - -.. code-block:: none - - firewall { - ipv6 { - input { - filter { - rule 10 { - action jump - inbound-interface { - name eth1 - } - jump-target INP-ETH1 - } - rule 20 { - action accept - inbound-interface { - name eth0 - } - log - protocol ipv6-icmp - } - } - } - name INP-ETH1 { - default-action drop - default-log - rule 10 { - action accept - protocol tcp_udp - } - } - } - } - - -Update geoip database -===================== - -.. opcmd:: update geoip - - Command used to update GeoIP database and firewall sets. diff --git a/docs/configuration/firewall/rst-zone.rst b/docs/configuration/firewall/rst-zone.rst deleted file mode 100644 index f3b12473..00000000 --- a/docs/configuration/firewall/rst-zone.rst +++ /dev/null @@ -1,205 +0,0 @@ -:lastproofread: 2026-03-30 - -.. _firewall-zone: - -################### -Zone-Based Firewall -################### - -******** -Overview -******** - -.. note:: - All VyOS versions built after 2023-10-22 (VyOS 1.4 and 1.5) support - this feature. - -This section provides information on firewall configuration for the -zone-based firewall. This section covers the following configuration -commands: - -.. cfgcmd:: set firewall zone ... - -To learn about the general traffic flow in VyOS firewalls, -see :doc:`Firewall </configuration/firewall/index>`. - -.. code-block:: none - - - set firewall - * zone - - custom_zone_name - + ... - -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 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 - zone <name>``. - -************* -Configuration -************* - -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. - -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`. - -The following steps are required to create a zone-based firewall: - -1. Define both the source and destination zones -2. Define the rule-set -3. Apply the rule-set to the zones - -Define a Zone -============= - -To define a zone, set up either one with interfaces or as the local zone. - -.. cfgcmd:: set firewall zone <name> interface <interface> - - Assign interfaces as a member of a zone. - - .. note:: - - * An interface can only be a member of one zone. - * 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 that originates from or is - destined to the router itself. - - .. note:: - - * A local zone cannot have any member interfaces - * You cannot have multiple local zones - -.. cfgcmd:: set firewall zone <name> default-action [drop | reject] - - 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 match this zone's default-action (disabled - by default). - -.. cfgcmd:: set firewall zone <name> description - - Add a meaningful description. - -Defining a Rule-Set -============================= - -Zone-based firewall rule-sets define traffic from a *Source Zone* to a -*Destination Zone*. - -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>`: - ``set firewall ipv4 name <name> ...`` -* For :ref:`IPv6<configuration/firewall/ipv6:Firewall - IPv6 Rules>`: - ``set firewall ipv6 name <name> ...`` - -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 -============================= - -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> - -.. cfgcmd:: set firewall zone <Destination Zone> from <Source Zone> - firewall ipv6-name <ipv6-rule-set-name> - -You should create two rule-sets for each source-destination zone -pair. - -.. code-block:: none - - set firewall zone DMZ from LAN firewall name LAN-DMZ-v4 - set firewall zone LAN from DMZ firewall name DMZ-LAN-v4 - -Applying a Default Rule-Set to a Zone -===================================== - -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 - <ipv4-rule-set-name> - -.. cfgcmd:: set firewall zone <Destination Zone> default-firewall ipv6-name - <ipv6-rule-set-name> - -************** -Operation-mode -************** - -.. opcmd:: show firewall zone-policy - - Display a basic summary of the zone configuration. - - .. code-block:: none - - vyos@vyos:~$ show firewall zone-policy - Zone Interfaces From Zone Firewall IPv4 Firewall IPv6 - ------ ------------ ----------- --------------- --------------- - LAN eth1 WAN WAN-LAN-v4 - eth2 - LOCAL LOCAL LAN LAN-LOCAL-v4 - WAN WAN-LOCAL-v4 WAN-LOCAL-v6 - WAN eth3 LAN LAN-WAN-v4 - eth0 LOCAL LOCAL-WAN-v4 - -.. opcmd:: show firewall zone-policy zone <zone> - - Display a basic summary of a particular zone. - - .. code-block:: none - - vyos@vyos:~$ show firewall zone-policy zone WAN - Zone Interfaces From Zone Firewall IPv4 Firewall IPv6 - ------ ------------ ----------- --------------- --------------- - WAN eth3 LAN LAN-WAN-v4 - eth0 LOCAL LOCAL-WAN-v4 - - vyos@vyos:~$ show firewall zone-policy zone LOCAL - Zone Interfaces From Zone Firewall IPv4 Firewall IPv6 - ------ ------------ ----------- --------------- --------------- - LOCAL LOCAL LAN LAN-LOCAL-v4 - WAN WAN-LOCAL-v4 WAN-LOCAL-v6 diff --git a/docs/configuration/highavailability/rst-index.rst b/docs/configuration/highavailability/rst-index.rst deleted file mode 100644 index 952a345b..00000000 --- a/docs/configuration/highavailability/rst-index.rst +++ /dev/null @@ -1,545 +0,0 @@ -:lastproofread: 2021-06-30 - -.. _high-availability: - -################# -High availability -################# - -VRRP (Virtual Router Redundancy Protocol) provides active/backup redundancy for -routers. Every VRRP router has a physical IP/IPv6 address, and a virtual -address. On startup, routers elect the master, and the router with the highest -priority becomes the master and assigns the virtual address to its interface. -All routers with lower priorities become backup routers. The master then starts -sending keepalive packets to notify other routers that it's available. If the -master fails and stops sending keepalive packets, the router with the next -highest priority becomes the new master and takes over the virtual address. - -VRRP keepalive packets use multicast, and VRRP setups are limited to a single -datalink layer segment. You can setup multiple VRRP groups -(also called virtual routers). Virtual routers are identified by a -VRID (Virtual Router IDentifier). If you setup multiple groups on the same -interface, their VRIDs must be unique if they use the same address family, -but it's possible (even if not recommended for readability reasons) to use -duplicate VRIDs on different interfaces. - -Basic setup ------------ - -VRRP groups are created with the -``set high-availability vrrp group $GROUP_NAME`` commands. The required -parameters are interface, vrid, and address. - -minimal config - -.. code-block:: none - - set high-availability vrrp group Foo vrid 10 - set high-availability vrrp group Foo interface eth0 - set high-availability vrrp group Foo address 192.0.2.1/24 - -You can verify your VRRP group status with the operational mode -``run show vrrp`` command: - -.. code-block:: none - - vyos@vyos# run show vrrp - Name Interface VRID State Last Transition - ---------- ----------- ------ ------- ----------------- - Foo eth1 10 MASTER 2s - -IPv6 support ------------- - -The ``address`` parameter can be either an IPv4 or IPv6 address, but you can -not mix IPv4 and IPv6 in the same group, and will need to create groups with -different VRIDs specially for IPv4 and IPv6. -If you want to use IPv4 + IPv6 address you can use option ``excluded-address`` - -Address -------- -The ``address`` can be configured either on the VRRP interface or on not VRRP -interface. - -.. code-block:: none - - set high-availability vrrp group Foo address 192.0.2.1/24 - set high-availability vrrp group Foo address 203.0.113.22/24 interface eth2 - set high-availability vrrp group Foo address 198.51.100.33/24 interface eth3 - -Disabling a VRRP group ----------------------- - -You can disable a VRRP group with ``disable`` option: - -.. code-block:: none - - set high-availability vrrp group Foo disable - -A disabled group will be removed from the VRRP process and your router will not -participate in VRRP for that VRID. It will disappear from operational mode -commands output, rather than enter the backup state. - -Exclude address ---------------- - -Exclude IP addresses from ``VRRP packets``. This option ``excluded-address`` is -used when you want to set IPv4 + IPv6 addresses on the same virtual interface -or when used more than 20 IP addresses. - -.. code-block:: none - - set high-availability vrrp group Foo excluded-address '203.0.113.254/24' - set high-availability vrrp group Foo excluded-address '2001:db8:aa::1/64' - set high-availability vrrp group Foo excluded-address '2001:db8:22::1/64' - -Setting VRRP group priority ---------------------------- - -VRRP priority can be set with ``priority`` option: - -.. code-block:: none - - set high-availability vrrp group Foo priority 200 - -The priority must be an integer number from 1 to 255. Higher priority value -increases router's precedence in the master elections. - -Sync groups ------------ - -A sync group allows VRRP groups to transition together. - -.. code-block:: none - - edit high-availability vrrp - set sync-group MAIN member VLAN9 - set sync-group MAIN member VLAN20 - -In the following example, when VLAN9 transitions, VLAN20 will also transition: - -.. code-block:: none - - vrrp { - group VLAN9 { - interface eth0.9 - address 10.9.1.1/24 - priority 200 - vrid 9 - } - group VLAN20 { - interface eth0.20 - priority 200 - address 10.20.20.1/24 - vrid 20 - } - sync-group MAIN { - member VLAN20 - member VLAN9 - } - } - - -.. warning:: All items in a sync group should be similarly configured. - If one VRRP group is set to a different preemption delay or priority, - it would result in an endless transition loop. - - -Preemption ----------- - -VRRP can use two modes: preemptive and non-preemptive. In the preemptive mode, -if a router with a higher priority fails and then comes back, routers with lower -priority will give up their master status. In non-preemptive mode, the newly -elected master will keep the master status and the virtual address indefinitely. - -By default VRRP uses preemption. You can disable it with the "no-preempt" -option: - -.. code-block:: none - - set high-availability vrrp group Foo no-preempt - -You can also configure the time interval for preemption with the "preempt-delay" -option. For example, to set the higher priority router to take over in 180 -seconds, use: - -.. code-block:: none - - set high-availability vrrp group Foo preempt-delay 180 - -Track ------ - -Track option to track non VRRP interface states. VRRP changes status to -``FAULT`` if one of the track interfaces in state ``down``. - -.. code-block:: none - - set high-availability vrrp group Foo track interface eth0 - set high-availability vrrp group Foo track interface eth1 - -Ignore VRRP main interface faults - -.. code-block:: none - - set high-availability vrrp group Foo track exclude-vrrp-interface - -Unicast VRRP ------------- - -By default VRRP uses multicast packets. If your network does not support -multicast for whatever reason, you can make VRRP use unicast communication -instead. - -.. code-block:: none - - set high-availability vrrp group Foo peer-address 192.0.2.10 - set high-availability vrrp group Foo hello-source-address 192.0.2.15 - -rfc3768-compatibility ---------------------- - -RFC 3768 defines a virtual MAC address to each VRRP virtual router. -This virtual router MAC address will be used as the source in all periodic VRRP -messages sent by the active node. When the rfc3768-compatibility option is set, -a new VRRP interface is created, to which the MAC address and the virtual IP -address is automatically assigned. - -.. code-block:: none - - set high-availability vrrp group Foo rfc3768-compatibility - -Verification - -.. code-block:: none - - $show interfaces ethernet eth0v10 - eth0v10@eth0: <BROADCAST,MULTICAST,UP,LOWER_UP> mtu 1500 qdisc noqueue - state UP group default qlen 1000 - link/ether 00:00:5e:00:01:0a brd ff:ff:ff:ff:ff:ff - inet 172.25.0.247/16 scope global eth0v10 - valid_lft forever preferred_lft forever - -.. warning:: RFC 3768 creates a virtual interface. If you want to apply - the destination NAT rule to the traffic sent to the virtual MAC, set - the created virtual interface as `inbound-interface`. - -Global options --------------- - -On most scenarios, there's no need to change specific parameters, and using -default configuration is enough. But there are cases were extra configuration -is needed. - -.. cfgcmd:: set high-availability vrrp global-parameters startup_delay <1-600> - - This option specifies a delay in seconds before vrrp instances start up - after keepalived starts. - -Gratuitous ARP --------------- - -These configuration is not mandatory and in most cases there's no -need to configure it. But if necessary, Gratuitous ARP can be configured in -``global-parameters`` and/or in ``group`` section. - -.. cfgcmd:: set high-availability vrrp global-parameters garp interval - <0.000-1000> - -.. cfgcmd:: set high-availability vrrp group <name> garp interval <0.000-1000> - - Set delay between gratuitous ARP messages sent on an interface. - - 0 if not defined. - -.. 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. - - 5 if not defined. - -.. cfgcmd:: set high-availability vrrp global-parameters garp master-refresh - <1-600> - -.. cfgcmd:: set high-availability vrrp group <name> garp master-refresh - <1-600> - - Set minimum time interval for refreshing gratuitous ARPs while MASTER. - - 0 if not defined, which means no refreshing. - -.. cfgcmd:: set high-availability vrrp global-parameters garp - master-refresh-repeat <1-600> - -.. cfgcmd:: set high-availability vrrp group <name> garp - master-refresh-repeat <1-600> - - Set number of gratuitous ARP messages to send at a time while MASTER. - - 1 if not defined. - -.. cfgcmd:: set high-availability vrrp global-parameters garp master-repeat - <1-600> - -.. cfgcmd:: set high-availability vrrp group <name> garp master-repeat - <1-600> - - Set number of gratuitous ARP messages to send at a time after transition to - MASTER. - - 5 if not defined. - -Version -------- - -.. cfgcmd:: set high-availability vrrp global-parameters version 2|3 - - Set the default VRRP version to use. This defaults to 2, but IPv6 instances - will always use version 3. - -Scripting ---------- - -VRRP functionality can be extended with scripts. VyOS supports two kinds of -scripts: health check scripts and transition scripts. Health check scripts -execute custom checks in addition to the master router reachability. Transition -scripts are executed when VRRP state changes from master to backup or fault and -vice versa and can be used to enable or disable certain services, for example. - -.. note:: Simply placing script files in ``/config/scripts/`` does not mean the - system can execute them. To make custom scripts executable, grant them - **execute permissions**. Use the following command: - - .. code-block:: none - - chmod +x /config/scripts/script-name.sh - -.. 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. - -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 - -An optional ``timeout`` can be set to define the maximum number of seconds the -script is allowed to run. This is useful for scripts that may hang or take -longer than expected — setting the timeout higher than the interval allows -longer-running scripts to complete before being considered failed. - -.. 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 20 - set high-availability vrrp group Foo health-check failure-count 3 - set high-availability vrrp group Foo health-check timeout 40 - -.. 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 -^^^^^^^^^^^^^^^^^^ - -Transition scripts can help you implement various fixups, such as starting and -stopping services, or even modifying the VyOS config on VRRP transition. -This setup will make the VRRP process execute the -``/config/scripts/vrrp-fail.sh`` with argument ``Foo`` when VRRP fails, -and the ``/config/scripts/vrrp-master.sh`` when the router becomes the master: - -.. 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 --------------- -.. include:: /_include/need_improvement.txt - -Virtual Server allows to Load-balance traffic destination virtual-address:port -between several real servers. - -Algorithm -^^^^^^^^^ -Load-balancing schedule algorithm: - -* round-robin -* weighted-round-robin -* least-connection -* weighted-least-connection -* source-hashing -* destination-hashing -* locality-based-least-connection - -.. code-block:: none - - set high-availability virtual-server 203.0.113.1 algorithm 'least-connection' - -Forward method -^^^^^^^^^^^^^^ -* NAT -* direct -* tunnel - -.. code-block:: none - - set high-availability virtual-server 203.0.113.1 forward-method 'nat' - -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 - -.. code-block:: none - - set high-availability virtual-server 203.0.113.1 fwmark '111' - -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 -^^^^^^^ -Virtual-server can be configured with VRRP virtual address or without VRRP. - -In the next example all traffic destined to ``203.0.113.1`` and port ``8280`` -protocol TCP is balanced between 2 real servers ``192.0.2.11`` and -``192.0.2.12`` to port ``80`` - -Real server is auto-excluded if port check with this server fail. - -.. stop_vyoslinter - -.. code-block:: none - - set interfaces ethernet eth0 address '203.0.113.11/24' - set interfaces ethernet eth1 address '192.0.2.1/24' - set high-availability vrrp group FOO interface 'eth0' - set high-availability vrrp group FOO no-preempt - set high-availability vrrp group FOO priority '150' - set high-availability vrrp group FOO address '203.0.113.1/24' - set high-availability vrrp group FOO vrid '10' - - set high-availability virtual-server 203.0.113.1 algorithm 'source-hashing' - set high-availability virtual-server 203.0.113.1 delay-loop '10' - set high-availability virtual-server 203.0.113.1 forward-method 'nat' - set high-availability virtual-server 203.0.113.1 persistence-timeout '180' - set high-availability virtual-server 203.0.113.1 port '8280' - set high-availability virtual-server 203.0.113.1 protocol 'tcp' - set high-availability virtual-server 203.0.113.1 real-server 192.0.2.11 port '80' - set high-availability virtual-server 203.0.113.1 real-server 192.0.2.12 port '80' - -.. start_vyoslinter - -A firewall mark ``fwmark`` allows using multiple ports for high-availability -virtual-server. -It uses fwmark value. - -In this example all traffic destined to ports "80, 2222, 8888" protocol TCP -marks to fwmark "111" and balanced between 2 real servers. -Port "0" is required if multiple ports are used. - -.. stop_vyoslinter - -.. code-block:: none - - set interfaces ethernet eth0 address 'dhcp' - set interfaces ethernet eth0 description 'WAN' - set interfaces ethernet eth1 address '192.0.2.1/24' - set interfaces ethernet eth1 description 'LAN' - - set policy route PR interface 'eth0' - set policy route PR rule 10 destination port '80,2222,8888' - set policy route PR rule 10 protocol 'tcp' - set policy route PR rule 10 set mark '111' - - set high-availability virtual-server vyos fwmark '111' - set high-availability virtual-server vyos protocol 'tcp' - set high-availability virtual-server vyos real-server 192.0.2.11 health-check script '/config/scripts/check-real-server-first.sh' - set high-availability virtual-server vyos real-server 192.0.2.11 port '0' - set high-availability virtual-server vyos real-server 192.0.2.12 health-check script '/config/scripts/check-real-server-second.sh' - set high-availability virtual-server vyos real-server 192.0.2.12 port '0' - - set nat source rule 100 outbound-interface name 'eth0' - 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 - - vyos@r14:~$ run show virtual-server - IP Virtual Server version 1.2.1 (size=4096) - Prot LocalAddress:Port Scheduler Flags - -> RemoteAddress:Port Forward Weight ActiveConn InActConn - FWM 111 lc persistent 300 - -> 192.0.2.11:0 Masq 1 0 0 - -> 192.0.2.12:0 Masq 1 1 0 diff --git a/docs/configuration/interfaces/rst-bonding.rst b/docs/configuration/interfaces/rst-bonding.rst deleted file mode 100644 index 7637790c..00000000 --- a/docs/configuration/interfaces/rst-bonding.rst +++ /dev/null @@ -1,767 +0,0 @@ -:lastproofread: 2025-12-09 - -.. _bond-interface: - -####################### -Bond / link aggregation -####################### - -A **bonding interface** aggregates multiple network interfaces into a single -logical interface (referred to as a bond, :abbr:`LAG (Link Aggregation Group)`, -EtherChannel, or port-channel). - -The behavior of a bonding interface depends on the selected mode. Modes provide -either fault tolerance or a combination of load balancing and fault tolerance. -Additionally, the bonding interface can be configured for link integrity -monitoring. - - -************* -Configuration -************* - -Common interface configuration -============================== - -.. cmdinclude:: /_include/interface-common-with-dhcp.txt - :var0: bonding - :var1: bond0 - -Member interfaces -================= - -.. cfgcmd:: set interfaces bonding <interface> member interface <member> - - **Add an interface to the bonding group.** - - **Example:** - - To configure eth0 and eth1 as members of the bonding interface bond0, execute - the following commands: - -.. code-block:: none - - set interfaces bonding bond0 member interface eth0 - set interfaces bonding bond0 member interface eth1 - -Bond modes -============ - -.. cfgcmd:: set interfaces bonding <interface> mode <802.3ad | active-backup | - broadcast | round-robin | transmit-load-balance | adaptive-load-balance | - xor-hash> - - **Configure the bonding mode on the interface. The default mode is** - ``802.3ad``. - - The available modes are: - - * ``802.3ad`` - - .. list-table:: - :widths: 20 80 - - * - **Description:** - - IEEE 802.3ad Dynamic Link Aggregation. Groups only member - interfaces with the same speed (e.g., 1 Gbps) and duplex - settings. Member interfaces with different speed and duplex - settings are not included in the active bond. - - Provides load balancing and fault tolerance. Uses the - :abbr:`LACP (Link Aggregation Control Protocol)` to - negotiate the bond with the switch. - * - **Traffic distribution:** - - Traffic is distributed according to the **transmit hash - policy** (default: XOR). - - The bonding driver applies an XOR operation to specific - packet header fields, generating a hash value that maps to - a particular member interface. This ensures the same network - flow is consistently transmitted over the same member - interface. - - The transmit hash policy is configured via the ``hash-policy`` option. - * - **Failover:** - - If a member interface fails, the hash is recalculated to distribute - traffic among the remaining active member interfaces. - - .. note:: Not all transmit hash policies comply with 802.3ad, particularly - section 43.2.4. Using a non-compliant policy may result in out-of-order - packet delivery. - - * ``active-backup`` - - .. list-table:: - :widths: 20 80 - - * - **Description:** - - Provides fault tolerance. Only one member interface is active - at a time. Other member interfaces remain in a standby mode. - * - **Traffic distribution:** - - All traffic (incoming and outgoing) is routed via one active - member interface. - * - **Failover:** - - If the designated member interface fails, all traffic is - routed to another member interface. The bonding driver sends - a Gratuitous ARP to update the peer's MAC address table, - linking the bond's MAC address to another physical port. - - * ``broadcast`` - - .. list-table:: - :widths: 20 80 - - * - **Description:** - - Provides maximum fault tolerance by duplicating traffic. - * - **Traffic distribution:** - - Every packet is duplicated and transmitted on **all** member - interfaces. - * - **Failover:** - - Traffic flow is not interrupted as long as at least one - member interface remains active. - - * ``round-robin`` - - .. list-table:: - :widths: 20 80 - - * - **Description:** - - Provides load balancing and fault tolerance. - * - **Traffic distribution:** - - Packets are transmitted in sequential order across the member - interfaces (e.g., packet 1 > interface A, packet 2 > - interface B, etc.). - * - **Failover:** - - If a member interface fails, the sequence skips the failed - interface and continues with the remaining active members. - - * ``transmit-load-balance`` - - .. list-table:: - :widths: 20 80 - - * - **Description:** - - Provides adaptive transmit load balancing and fault tolerance. - * - **Traffic distribution:** - - **Outgoing:** Distributed across all active member interfaces - based on the current load. - - **Incoming:** Received by a designated member interface - (active receiver). - * - **Failover:** - - If the active receiver fails, another member interface takes - over as the new active receiver. - - * ``adaptive-load-balance`` - - .. list-table:: - :widths: 20 80 - - * - **Description:** - - Provides adaptive transmit load balancing identical to - ``transmit-load-balance``, receive load balancing for IPv4 - traffic, and fault tolerance for both incoming and outgoing - traffic. - * - **Traffic distribution:** - - **Outgoing:** Identical to ``transmit-load-balance``. - - **Incoming:** Distributed based on ARP manipulation. For - both local and remote connections, the bonding driver - intercepts ARP traffic and changes the source MAC address - to the MAC address of the least loaded member interface. - - All traffic from that peer is then routed to the chosen - member interface. - * - **Failover:** - - If a member interface's state changes (fails, recovers, is - added, or excluded), the traffic is redistributed among all - active member interfaces. - - * ``xor-hash``: Provides load balancing and fault tolerance - based on a hash formula. Distributes traffic and handles - failover identically to ``802.3ad``, but operates without - the :abbr:`LACP (Link Aggregation Control Protocol)`. - -.. cfgcmd:: set interfaces bonding <interface> min-links <0-16> - - **Configure how many member interfaces must be active (in the - link-up state) to mark the bonding interface UP (carrier - asserted).** - - This command applies only when the bonding interface is configured - in 802.3ad mode and functions like the Cisco EtherChannel min-links - feature. It ensures that a bonding interface is marked UP (carrier - asserted) only when a specified number of member interfaces are - active (in the link-up state). This helps guarantee a minimum level - of bandwidth for higher-level services (such as clustering) relying - on the bonding interface. - - The default value is 0. This marks the bonding interface UP - (carrier asserted) whenever an active LACP aggregator exists, - regardless of the number of member interfaces in that aggregator. - - .. note:: In 802.3ad mode, a bond cannot be active without at - least one active member interface. Therefore, setting min-links - to 0 or 1 has the same result: the bonding interface is marked - UP (carrier asserted). - -.. cfgcmd:: set interfaces bonding <interface> lacp-rate <slow|fast> - - **Configure the rate at which the bonding interface requests its - link partner to send** - :abbr:`LACPDUs (Link Aggregation Control Protocol Data Units)` - **in 802.3ad mode.** - - This command applies only when the bonding interface is configured - in 802.3ad mode. - - The following options are available: - - * **slow (default):** Requests the link partner to transmit - LACPDUs every 30 seconds. - - * **fast:** Requests the link partner to transmit LACPDUs every - 1 second. - - -.. cfgcmd:: set interfaces bonding <interface> system-mac <mac address> - - **Configure a specific MAC address for the bonding interface.** - - This sets the 802.3ad system MAC address, which is used for - :abbr:`LACPDU (Link Aggregation Control Protocol Data Unit)` - exchanges with the link partner. You can assign a fixed MAC address - or generate a random one for these - :abbr:`LACPDU (Link Aggregation Control Protocol Data Unit)` - exchanges. - - -.. cfgcmd:: set interfaces bonding <interface> hash-policy <policy> - - **Configure which transmit hash policy to use for distributing - traffic across member interfaces.** - - The following policies are available: - - * ``layer2`` - - .. list-table:: - :widths: 20 80 - - * - **Description:** - - Routes all traffic destined for a specific network peer - through the same member interface. The policy is - 802.3ad-compliant. - * - **Hash inputs:** - - Source MAC address, destination MAC address, and Ethernet - packet type ID. - * - **Formula:** - - .. code-block:: none - - hash = source MAC address XOR destination MAC address XOR packet type ID - member interface number = hash modulo member interface count - - * ``layer2+3`` - - .. list-table:: - :widths: 20 80 - - * - **Description:** - - Similar to ``layer2``, routes all traffic destined for a - specific network peer through the same member interface - and is IEEE 802.3ad-compliant. Uses both Layer 2 and - Layer 3 information to provide a more balanced traffic - distribution. - * - **Hash inputs:** - - * Source MAC address, destination MAC address, and - Ethernet packet type ID. - * Source IP address, destination IP address. IPv6 - addresses are first hashed using ``IPv6_addr_hash``. - * - **Formula:** - - .. code-block:: none - - hash = source MAC address XOR destination MAC address XOR packet type ID - hash = hash XOR source IP address XOR destination IP address - hash = hash XOR (hash RSHIFT 16) - hash = hash XOR (hash RSHIFT 8) - member interface number = hash modulo member interface count - - For non-IP traffic, the formula is the same as for ``layer2``. - - * ``layer3+4`` - - .. list-table:: - :widths: 20 80 - - * - **Description:** - - Routes different connections (flows) destined for a - specific network peer through multiple member interfaces, - but ensures each individual flow is routed through only - one member interface. - - .. note:: This policy is not fully 802.3ad-compliant. - When a single TCP or UDP flow contains both fragmented - and unfragmented packets, the algorithm may distribute - them across different member interfaces. This may - result in out-of-order packet delivery, violating the - 802.3ad standard. - * - **Hash inputs:** - - * Source port, destination port (if available). - * Source IP address, destination IP address. IPv6 - addresses are first hashed using ``IPv6_addr_hash``. - * - **Formula:** - - .. code-block:: none - - hash = source port, destination port (as in the header) - hash = hash XOR source IP address XOR destination IP address - hash = hash XOR (hash RSHIFT 16) - hash = hash XOR (hash RSHIFT 8) - member interface number = hash modulo member interface count - - For fragmented TCP or UDP packets and all other IPv4 and - IPv6 traffic, the source and destination port information - is omitted. - - For non-IP traffic, the formula is the same as for ``layer2``. - -.. cfgcmd:: set interfaces bonding <interface> primary <interface> - - **Configure the primary member interface in the bond.** - - The primary member interface remains active as long as it is - operational; alternative member interfaces are used only if it - fails. - - Use this configuration when a specific member interface is - preferred, such as one with higher throughput. - - This command applies only to ``active-backup``, - ``transmit-load-balance``, and ``adaptive-load-balance`` modes. - -.. cfgcmd:: set interfaces bonding <interface> arp-monitor interval <time> - - **Configure the ARP monitoring interval, in seconds, for the - bonding interface.** - - ARP monitoring periodically assesses the health of each member - interface by checking whether it has recently sent or received - traffic (this criterion varies depending on the bonding mode and - the member interface’s state). ARP probes are sent to the IP - addresses specified with the arp-monitor target option. - - When ARP monitoring is used with EtherChannel-compatible modes - (such as ``round-robin`` or ``xor-hash``), the switch should be - configured to distribute traffic across all member interfaces. If - the switch distributes traffic using an XOR-based policy, all ARP - replies will be received on one member interface, causing other - member interfaces to be incorrectly marked as failed. - - Setting this value to 0 disables ARP monitoring. - - The default value is 0. - -.. cfgcmd:: set interfaces bonding <interface> arp-monitor target <address> - - **Configure the IP addresses for ARP monitoring requests.** - - The bonding driver sends ARP requests to these IP addresses to - check the state of member interfaces. - - To enable ARP monitoring, configure at least one IP address (up to - 16 per bonding interface). - - By default, no IP addresses are configured. - -:abbr:`VLAN (Virtual Local Area Network)` -========================================= - -.. cmdinclude:: /_include/interface-vlan-8021q.txt - :var0: bonding - :var1: bond0 - -SPAN port mirroring -=================== - -.. cmdinclude:: ../../_include/interface-mirror.txt - :var0: bonding - :var1: bond1 - :var2: eth3 - -EVPN multihoming ----------------- - -EVPN multihoming (EVPN-MH) is a standards-based solution (RFC 7432, RFC 8365) -that enables Customer Edge (CE) devices, such as servers, to connect to two -or more Provider Edge (PE) devices for redundancy and load balancing. - -EVPN-MH is often used as a modern, standards-based alternative to -:abbr:`MLAG (Multi-Chassis Link Aggregation)` and :abbr:`VTEPs (Virtual -Tunnel Endpoints)`. - -**Ethernet Segment (ES) and Ethernet Segment Identifier (ESI)** - -Physical links that connect a CE device to PE devices are bundled using link -aggregation. This logical bundle is called an Ethernet Segment (ES) and is -uniquely identified by an Ethernet Segment Identifier (ESI) within the -EVPN domain. - -To enable EVPN-MH, configure the same ESI on the bonding interfaces of all -PE devices connected to a single CE device. - -An ESI is configured by specifying either a system MAC address and a local -discriminator, or an Ethernet Segment Identifier Name (ESINAME). - -The following two commands generate a 10-byte Type-3 ESI by combining the -system MAC and local discriminator: - -.. stop_vyoslinter - -.. cfgcmd:: set interfaces bonding <interface> evpn es-id <1-16777215|10-byte ID> -.. cfgcmd:: set interfaces bonding <interface> evpn es-sys-mac <xx:xx:xx:xx:xx:xx> - - Alternatively, assign an ESINAME directly as a 10-byte Type-0 ESI - using the following format: 00:AA:BB:CC:DD:EE:FF:GG:HH:II. - - **BGP-EVPN route usage** - - EVPN-MH uses BGP-EVPN route types 1 and 2 for ES discovery and - MAC-IP synchronization: - - * **Type 1 (EAD-per-ES and EAD-per-EVI)** routes advertise the - locally attached ESs and discover remote ESs in the network. - * **Type 2 (MAC-IP advertisement)** routes are advertised with a - destination ESI, enabling MAC-IP synchronization between ES peers. - -.. stop_vyoslinter - -.. cfgcmd:: set interfaces bonding <interface> evpn es-df-pref <1-65535> - - **Configure the** :abbr:`DF (Designated Forwarder)` **preference (1-65535) for - the interface. A higher value indicates a higher preference to become the** - :abbr:`DF (Designated Forwarder)`. **The** :abbr:`DF (Designated Forwarder)` - **preference is configured per-ES.** - - The DF election process determines which interface in a specific ES forwards - :abbr:`BUM (Broadcast, Unknown Unicast, and Multicast)` traffic from the EVPN - overlay to the connected CE device. EVPN Type-4 (Ethernet Segment) routes are - used to elect the DF, implementing the preference-based election method defined - in RFC 9785. - - Interfaces not elected as the DF drop any BUM traffic from the EVPN overlay - using non-DF filters. Similarly, traffic received from ES peers via the EVPN - overlay is blocked from forwarding to the CE device to maintain split-horizon - filtering with local bias. - -.. start_vyoslinter - -.. cmdinclude:: /_include/interface-evpn-uplink.txt - :var0: bonding - :var1: bond0 - -******* -Example -******* - -The following configuration example applies to all listed third-party vendors. -It creates a bonding interface with two member interfaces, defines VLANs 10 -and 100 on the bonding interface, and assigns an IPv4 address to each VLAN -subinterface. - -.. code-block:: none - - # Create the bonding interface bond0 with 802.3ad LACP - set interfaces bonding bond0 hash-policy 'layer2' - set interfaces bonding bond0 mode '802.3ad' - - # Add the required VLANs and IPv4 addresses on them - set interfaces bonding bond0 vif 10 address 192.168.0.1/24 - set interfaces bonding bond0 vif 100 address 10.10.10.1/24 - - # Add the member interfaces to the bonding interface - set interfaces bonding bond0 member interface eth1 - set interfaces bonding bond0 member interface eth2 - -.. note:: If you are running this configuration in a virtual environment like - EVE-NG, ensure the e1000 driver is chosen for your VyOS NIC. The default - drivers, such as ``virtio-net-pci`` or ``vmxnet3``, are incompatible with - this configuration. Specifically, ICMP messages will not be processed - correctly. - - To check your NIC driver, use the following command: - :opcmd:`show interfaces ethernet eth0 physical | grep -i driver` - -Cisco Catalyst configuration -============================ - -Configure a Cisco Catalyst switch to integrate with a two-member VyOS bonding -interface. - -Assign member interfaces to PortChannel: - -.. code-block:: none - - interface GigabitEthernet1/0/23 - description VyOS eth1 - channel-group 1 mode active - ! - interface GigabitEthernet1/0/24 - description VyOS eth2 - channel-group 1 mode active - ! - -A new interface, ``Port-channel1``, becomes available; all configuration, -such as allowed VLAN interfaces and STP, is applied here. - -.. code-block:: none - - interface Port-channel1 - description LACP Channel for VyOS - switchport trunk encapsulation dot1q - switchport trunk allowed vlan 10,100 - switchport mode trunk - spanning-tree portfast trunk - ! - - -Juniper EX Switch configuration -=============================== - -Configure a Juniper EX Series switch to integrate with a two-member VyOS -bonding interface. - -.. code-block:: none - - # Create aggregated ethernet device with 802.3ad LACP and port speeds of 10gbit/s - set interfaces ae0 aggregated-ether-options link-speed 10g - set interfaces ae0 aggregated-ether-options lacp active - - # Create layer 2 on the aggregated ethernet device with trunking for our VLANs - set interfaces ae0 unit 0 family ethernet-switching port-mode trunk - - # Add the required vlans to the device - set interfaces ae0 unit 0 family ethernet-switching vlan members 10 - set interfaces ae0 unit 0 family ethernet-switching vlan members 100 - - # Add the two interfaces to the aggregated ethernet device, in this setup both - # ports are on the same switch (switch 0, module 1, port 0 and 1) - set interfaces xe-0/1/0 ether-options 802.3ad ae0 - set interfaces xe-0/1/1 ether-options 802.3ad ae0 - - # But this can also be done with multiple switches in a stack, a virtual - # chassis on Juniper (switch 0 and switch 1, module 1, port 0 on both switches) - set interfaces xe-0/1/0 ether-options 802.3ad ae0 - set interfaces xe-1/1/0 ether-options 802.3ad ae0 - -Aruba/HP configuration -====================== - -Configure an Aruba/HP 2510G switch to integrate with a two-member VyOS bonding -interface. - -.. code-block:: none - - # Create trunk with 2 member interfaces (interface 1 and 2) and LACP - trunk 1-2 Trk1 LACP - - # Add the required VLANs to the trunk - vlan 10 tagged Trk1 - vlan 100 tagged Trk1 - -Arista EOS configuration -======================== - -When deploying VyOS in environments with Arista switches, use the following -blueprint as an initial setup to configure an operational LACP port-channel -between the two devices. - -Let's assume the following topology: - -.. figure:: /_static/images/vyos_arista_bond_lacp.* - :alt: VyOS Arista EOS setup - -**R1** - - .. code-block:: none - - interfaces { - bonding bond10 { - hash-policy layer3+4 - member { - interface eth1 - interface eth2 - } - mode 802.3ad - vif 100 { - address 192.0.2.1/30 - address 2001:db8::1/64 - } - } - -**R2** - - .. code-block:: none - - interfaces { - bonding bond10 { - hash-policy layer3+4 - member { - interface eth1 - interface eth2 - } - mode 802.3ad - vif 100 { - address 192.0.2.2/30 - address 2001:db8::2/64 - } - } - -**SW1** - - .. code-block:: none - - ! - vlan 100 - name FOO - ! - interface Port-Channel10 - switchport trunk allowed vlan 100 - switchport mode trunk - spanning-tree portfast - ! - interface Port-Channel20 - switchport mode trunk - no spanning-tree portfast auto - spanning-tree portfast network - ! - interface Ethernet1 - channel-group 10 mode active - ! - interface Ethernet2 - channel-group 10 mode active - ! - interface Ethernet3 - channel-group 20 mode active - ! - interface Ethernet4 - channel-group 20 mode active - ! - -**SW2** - - .. code-block:: none - - ! - vlan 100 - name FOO - ! - interface Port-Channel10 - switchport trunk allowed vlan 100 - switchport mode trunk - spanning-tree portfast - ! - interface Port-Channel20 - switchport mode trunk - no spanning-tree portfast auto - spanning-tree portfast network - ! - interface Ethernet1 - channel-group 10 mode active - ! - interface Ethernet2 - channel-group 10 mode active - ! - interface Ethernet3 - channel-group 20 mode active - ! - interface Ethernet4 - channel-group 20 mode active - ! - -.. note:: When testing this environment in EVE-NG, ensure the e1000 driver - is chosen for your VyOS network interfaces. If the default virtio driver - is used, VyOS will not transmit LACP PDUs, preventing the port-channel - from ever becoming active. - -********* -Operation -********* - -.. opcmd:: show interfaces bonding - - Show brief interface information. - - .. code-block:: none - - vyos@vyos:~$ show interfaces bonding - Codes: S - State, L - Link, u - Up, D - Down, A - Admin Down - Interface IP Address S/L Description - --------- ---------- --- ----------- - bond0 - u/u my-sw1 int 23 and 24 - bond0.10 192.168.0.1/24 u/u office-net - bond0.100 10.10.10.1/24 u/u management-net - - -.. opcmd:: show interfaces bonding <interface> - - Show detailed interface information. - - .. code-block:: none - - vyos@vyos:~$ show interfaces bonding bond5 - bond5: <NO-CARRIER,BROADCAST,MULTICAST,MASTER,UP> mtu 1500 qdisc noqueue state DOWN group default qlen 1000 - link/ether 00:50:56:bf:ef:aa brd ff:ff:ff:ff:ff:ff - inet6 fe80::e862:26ff:fe72:2dac/64 scope link tentative - valid_lft forever preferred_lft forever - - RX: bytes packets errors dropped overrun mcast - 0 0 0 0 0 0 - TX: bytes packets errors dropped carrier collisions - 0 0 0 0 0 0 - -.. opcmd:: show interfaces bonding <interface> detail - - Show detailed information about the underlying physical links on the given - bonding interface. - - .. code-block:: none - - vyos@vyos:~$ show interfaces bonding bond5 detail - Ethernet Channel Bonding Driver: v3.7.1 (April 27, 2011) - - Bonding Mode: IEEE 802.3ad Dynamic link aggregation - Transmit Hash Policy: layer2 (0) - MII Status: down - MII Polling Interval (ms): 100 - Up Delay (ms): 0 - Down Delay (ms): 0 - - 802.3ad info - LACP rate: slow - Min links: 0 - Aggregator selection policy (ad_select): stable - - Slave Interface: eth1 - MII Status: down - Speed: Unknown - Duplex: Unknown - Link Failure Count: 0 - Permanent HW addr: 00:50:56:bf:ef:aa - Slave queue ID: 0 - Aggregator ID: 1 - Actor Churn State: churned - Partner Churn State: churned - Actor Churned Count: 1 - Partner Churned Count: 1 - - Slave Interface: eth2 - MII Status: down - Speed: Unknown - Duplex: Unknown - Link Failure Count: 0 - Permanent HW addr: 00:50:56:bf:19:26 - Slave queue ID: 0 - Aggregator ID: 2 - Actor Churn State: churned - Partner Churn State: churned - Actor Churned Count: 1 - Partner Churned Count: 1 diff --git a/docs/configuration/interfaces/rst-bridge.rst b/docs/configuration/interfaces/rst-bridge.rst deleted file mode 100644 index a1710804..00000000 --- a/docs/configuration/interfaces/rst-bridge.rst +++ /dev/null @@ -1,424 +0,0 @@ -:lastproofread: 2025-12-22 - -.. _bridge-interface: - -###### -Bridge -###### - -VyOS bridges connect Ethernet segments by grouping multiple interfaces into a -single bridge interface, which acts as a virtual software switch. Unlike -routers, which forward traffic based on Layer 3 IP addresses, bridges operate -at Layer 2 and forward traffic based on MAC addresses. Operating at Layer 2, -bridges are protocol-agnostic and transparently forward all Ethernet- -encapsulated traffic, whether it is IPv4, IPv6, or specialized industrial -protocols. - -This implementation utilizes the Linux bridge subsystem to support a subset of -the ANSI/IEEE 802.1d standard for transparent bridging and MAC address learning. - -.. note:: :abbr:`STP (Spanning Tree Protocol)` is disabled by default in VyOS - and must be explicitly enabled if required. See :ref:`stp` for details. - -************* -Configuration -************* - -Common interface configuration -============================== - -.. cmdinclude:: /_include/interface-common-with-dhcp.txt - :var0: bridge - :var1: br0 - -Member interfaces -================= - -.. cfgcmd:: set interfaces bridge <interface> member interface <member> - - **Configure an interface as a bridge member.** - - Valid interface types are: :ref:`ethernet-interface`, :ref:`bond-interface`, - :ref:`l2tpv3-interface`, :ref:`openvpn`, :ref:`vxlan-interface`, - :ref:`wireless-interface`, :ref:`tunnel-interface`, and - :ref:`geneve-interface`. - - Use tab completion to list interfaces that can be bridged. - -.. cfgcmd:: set interfaces bridge <interface> member interface <member> - priority <priority> - - **Configure the** :abbr:`STP (Spanning Tree Protocol)` **port priority - for a specific member interface within a bridge.** - - Within the :abbr:`STP (Spanning Tree Protocol)` topology, each member interface - in a bridge operates as a port with an assigned **priority** and **path cost**. - :abbr:`STP (Spanning Tree Protocol)` uses these values to determine the - **lowest-cost path** to the root bridge, maintaining a loop-free topology. - Traffic flows through the path with the lowest path cost, while alternate - paths remain in standby. - - A **lower** priority value means **higher** precedence in path selection. - - :abbr:`STP (Spanning Tree Protocol)` considers the port priority only if - multiple member interfaces have the same path costs. - - -.. cfgcmd:: set interfaces bridge <interface> member interface <member> - cost <cost> - - **Configure the** :abbr:`STP (Spanning Tree Protocol)` **path cost for a - specific member interface within the bridge.** - - Path cost is the primary metric :abbr:`STP (Spanning Tree Protocol)` uses to - determine the path to the root bridge. This value is based on interface - bandwidth; faster interfaces receive lower costs. - - By assigning a lower cost, you give the interface higher precedence during - path selection. - -.. cfgcmd:: set interfaces bridge <interface> member interface <member> - disable-learning - - **Disable MAC address learning for a specific member interface - within a bridge.** - - When learning is disabled, the bridge will not add source MAC addresses - observed on this port to its forwarding database (FDB). Frames destined - to MACs not present in the FDB are then flooded to all bridge ports - rather than unicast-forwarded. - -Bridge options -============== - -Configure how bridge interfaces maintain their :abbr:`FDB (Forwarding Database)` -, react to topology changes, and optimize multicast data streams. - -.. cfgcmd:: set interfaces bridge <interface> aging <time> - - **Configure the MAC address aging time for the bridge.** - - The duration in seconds that a MAC address remains in the bridge’s :abbr:`FDB - (Forwarding Database)` before removal if no traffic is received from that - address. - - The default value is 300 seconds. - -.. cfgcmd:: set interfaces bridge <interface> max-age <time> - - **Configure the** :abbr:`STP (Spanning Tree Protocol)` **max age timer for - the bridge.** - - The duration in seconds that the bridge waits for a :abbr:`BPDU (Bridge - Protocol Data Unit)` from the root bridge. - - If the bridge does not receive a :abbr:`BPDU (Bridge Protocol Data Unit)` - within this period, it recalculates the path to the root bridge or initiates - a new root bridge election. - -.. cfgcmd:: set interfaces bridge <interface> igmp querier - - **Configure the bridge interface to act as the** :abbr:`IGMP (Internet Group - Management Protocol)`/:abbr:`MLD (Multicast Listener Discovery)` **Querier.** - - **When configured:** The bridge interface sends :abbr:`IGMP (Internet Group - Management Protocol)` (IPv4) and :abbr:`MLD (Multicast Listener Discovery)` - (IPv6) general queries to all connected hosts to identify active multicast - listeners. - -.. cfgcmd:: set interfaces bridge <interface> igmp snooping - - **Configure the bridge interface to perform** :abbr:`IGMP (Internet Group - Management Protocol)`/:abbr:`MLD (Multicast Listener Discovery)` - **snooping.** - - **When configured:** The bridge interface monitors :abbr:`IGMP (Internet Group - Management Protocol)` (IPv4) and :abbr:`MLD (Multicast Listener Discovery)` - (IPv6) join requests and restricts multicast traffic forwarding to only active - listeners. This prevents network flooding. - -.. _stp: - -STP configuration ------------------ - -:abbr:`STP (Spanning Tree Protocol)` is a Layer 2 protocol that prevents loops -in Ethernet networks by ensuring only one logical path exists between any two -bridges. This creates a loop-free topology and prevents broadcast storms that -can crash the network. - -By default, :abbr:`STP (Spanning Tree Protocol)` is disabled on bridge interfaces. -To activate loop prevention, you must explicitly enable the protocol and -configure its parameters. - -.. cfgcmd:: set interfaces bridge <interface> stp - - Enable :abbr:`STP (Spanning Tree Protocol)` on the bridge interface. - -.. cfgcmd:: set interfaces bridge <interface> forwarding-delay <delay> - - **Configure the** :abbr:`STP (Spanning Tree Protocol)` **delay, in seconds, - for the bridge interface.** - - This parameter defines how long the bridge interface remains in the listening - and learning states before forwarding traffic. The delay ensures that the - bridge has sufficient time to detect loops (in the listening state) and learn - the MAC addresses of connected devices (in the learning state). - - The default value is 15 seconds. The total time before forwarding begins is - twice this value. - -.. cfgcmd:: set interfaces bridge <interface> hello-time <interval> - - **Configure the** :abbr:`STP (Spanning Tree Protocol)` **Hello advertisement - interval, in seconds.** - - This parameter sets the frequency at which the bridge interface transmits - Hello packets (:abbr:`BPDUs (Bridge Protocol Data Units)`). These packets - originate from the root bridge and are propagated by designated bridges. If - neighbors stop receiving Hello packets, they assume a connection failure and - trigger a topology recalculation. - - The default value is 2 seconds. - -VLAN -==== - -VLAN-aware bridges ------------------- - -.. cfgcmd:: set interfaces bridge <interface> enable-vlan - - **Enable VLAN filtering (also known as VLAN awareness) on the bridge interface.** - - When enabled, the bridge strictly segregates traffic among VLANs configured - on its member interfaces. - - .. note:: - Do not configure **vif 1** on a VLAN-aware bridge. The main bridge - interface acts as VLAN 1 (the default native VLAN) and automatically - handles all untagged traffic. - -.. cfgcmd:: set interfaces bridge <interface> protocol <802.1ad | 802.1q> - - **Configure the VLAN protocol (EtherType) for the bridge interface.** - - The following options are available: - - * ``802.1q`` (default): Sets the EtherType to ``0x8100``. Used for standard - enterprise VLANs. - * ``802.1ad``: Sets the EtherType to ``0x88a8``. Used for QinQ (provider bridging). - -VLAN configuration ------------------- - -.. cmdinclude:: /_include/interface-vlan-8021q.txt - :var0: bridge - :var1: br0 - -.. cfgcmd:: set interfaces bridge <interface> member interface <member> - native-vlan <vlan-id> - - **Configure the native VLAN ID for a specific member interface within a - VLAN-aware bridge.** - - This assigns the specified ``<vlan-id>`` to untagged traffic entering the member - interface. The bridge strips the VLAN tag from outgoing traffic matching this - ID. - - **Example:** - - Set the native VLAN ID to 2 for the member interface ``eth0``: - - .. code-block:: none - - set interfaces bridge br1 member interface eth0 native-vlan 2 - -.. cfgcmd:: set interfaces bridge <interface> member interface <member> - allowed-vlan <vlan-id> - - **Configure allowed VLAN IDs for a specific member interface within a - VLAN-aware bridge.** - - Enter a single VLAN ID or a range of VLAN IDs separated by a hyphen. - - **Example:** - - To allow VLAN ID 4 on member interface ``eth0``: - - .. code-block:: none - - set interfaces bridge br1 member interface eth0 allowed-vlan 4 - - **Example:** - - To allow VLAN IDs 6 through 8 on member interface ``eth0``: - - .. code-block:: none - - set interfaces bridge br1 member interface eth0 allowed-vlan 6-8 - -SPAN port mirroring -=================== -.. cmdinclude:: ../../_include/interface-mirror.txt - :var0: bridge - :var1: br1 - :var2: eth3 - -******** -Examples -******** - -Configure a standard bridge -=========================== - -The following example creates a bridge named br100 with :abbr:`STP (Spanning -Tree Protocol)` enabled. - -Configuration requirements: - -* **Bridge name:** ``br100`` -* **Member interfaces:** Physical interface ``eth1`` and VLAN interface ``eth2.10``. -* **STP:** Enabled. -* **Bridge IP addresses:** ``192.0.2.1/24`` (IPv4) and ``2001:db8::ffff/64`` (IPv6). - -.. code-block:: none - - set interfaces bridge br100 address 192.0.2.1/24 - set interfaces bridge br100 address 2001:db8::ffff/64 - set interfaces bridge br100 member interface eth1 - set interfaces bridge br100 member interface eth2.10 - set interfaces bridge br100 stp - -Verify the configuration: - -.. code-block:: none - - vyos@vyos# show interfaces bridge br100 - address 192.0.2.1/24 - address 2001:db8::ffff/64 - member { - interface eth1 { - } - interface eth2.10 { - } - } - stp - - -Configure a VLAN-aware bridge -============================= - -The following example creates a VLAN-aware bridge named br100. In this setup, -one member interface is configured as a trunk port, and the other as an access -port. The VLAN interface is configured with IP addresses. - -**Configuration requirements:** - -* **Bridge name:** ``br100``. -* **Trunk port** (``eth1``): Handles **tagged** traffic for VLAN 10. -* **Access port** (``eth2``): Handles **untagged** traffic (assigned to native - VLAN 10). -* **STP:** Enabled. -* **VLAN IP addresses** (``vif 10``): ``192.0.2.1/24`` (IPv4) and - ``2001:db8::ffff/64`` (IPv6). - -.. code-block:: none - - set interfaces bridge br100 enable-vlan - set interfaces bridge br100 member interface eth1 allowed-vlan 10 - set interfaces bridge br100 member interface eth2 native-vlan 10 - set interfaces bridge br100 vif 10 address 192.0.2.1/24 - set interfaces bridge br100 vif 10 address 2001:db8::ffff/64 - set interfaces bridge br100 stp - -Verify the configuration: - -.. code-block:: none - - vyos@vyos# show interfaces bridge br100 - enable-vlan - member { - interface eth1 { - allowed-vlan 10 - } - interface eth2 { - native-vlan 10 - } - } - stp - vif 10 { - address 192.0.2.1/24 - address 2001:db8::ffff/64 - } - - -Operation -========= - -.. opcmd:: show bridge - - Show the status of member interfaces for all configured bridges. - - .. code-block:: none - - vyos@vyos:~$ show bridge - 3: eth1: <BROADCAST,MULTICAST,UP,LOWER_UP> mtu 1500 master br0 state forwarding - priority 32 cost 100 - 4: eth2: <BROADCAST,MULTICAST,UP,LOWER_UP> mtu 1500 master br0 state forwarding - priority 32 cost 100 - -.. opcmd:: show bridge <name> fdb - - Show the :abbr:`FDB (Forwarding Database)` for the specified bridge. - - .. code-block:: none - - vyos@vyos:~$ show bridge br0 fdb - 50:00:00:08:00:01 dev eth1 vlan 20 master br0 permanent - 50:00:00:08:00:01 dev eth1 vlan 10 master br0 permanent - 50:00:00:08:00:01 dev eth1 master br0 permanent - 33:33:00:00:00:01 dev eth1 self permanent - 33:33:00:00:00:02 dev eth1 self permanent - 01:00:5e:00:00:01 dev eth1 self permanent - 50:00:00:08:00:02 dev eth2 vlan 20 master br0 permanent - 50:00:00:08:00:02 dev eth2 vlan 10 master br0 permanent - 50:00:00:08:00:02 dev eth2 master br0 permanent - 33:33:00:00:00:01 dev eth2 self permanent - 33:33:00:00:00:02 dev eth2 self permanent - 01:00:5e:00:00:01 dev eth2 self permanent - 33:33:00:00:00:01 dev br0 self permanent - 33:33:00:00:00:02 dev br0 self permanent - 33:33:ff:08:00:01 dev br0 self permanent - 01:00:5e:00:00:6a dev br0 self permanent - 33:33:00:00:00:6a dev br0 self permanent - 01:00:5e:00:00:01 dev br0 self permanent - 33:33:ff:00:00:00 dev br0 self permanent - -.. opcmd:: show bridge <name> mdb - - Show the :abbr:`MDB (Multicast group Database)` for the specified bridge. - - The :abbr:`MDB (Multicast group Database)` is populated by :abbr:`IGMP - (Internet Group Management Protocol)`/:abbr:`MLD (Multicast Listener - Discovery)` snooping and lists the multicast groups currently active on the - bridge. - - .. code-block:: none - - vyos@vyos:~$ show bridge br0 mdb - dev br0 port br0 grp ff02::1:ff00:0 temp vid 1 - dev br0 port br0 grp ff02::2 temp vid 1 - dev br0 port br0 grp ff02::1:ff08:1 temp vid 1 - dev br0 port br0 grp ff02::6a temp vid 1 - -.. opcmd:: show bridge <name> macs - - Show the learned :abbr:`MAC (Media Access Control)` address table for the - specified bridge. - - .. code-block:: none - - vyos@vyos:~$ show bridge br100 macs - port no mac addr is local? ageing timer - 1 00:53:29:44:3b:19 yes 0.00 diff --git a/docs/configuration/interfaces/rst-dummy.rst b/docs/configuration/interfaces/rst-dummy.rst deleted file mode 100644 index 55c134e3..00000000 --- a/docs/configuration/interfaces/rst-dummy.rst +++ /dev/null @@ -1,87 +0,0 @@ -:lastproofread: 2026-01-23 - -.. _dummy-interface: - -##### -Dummy -##### - -A dummy interface is a virtual network interface that operates like the -loopback interface, accepting traffic and routing it back to the local host. -Unlike the loopback interface, which is limited to one per system and reserved -for internal system use, multiple dummy interfaces can be created, removed, and -managed without impacting core operations. - -As a software-based interface, the dummy interface does not depend on physical -link state and remains active as long as the operating system is running. - -Dummy interfaces are commonly used in environments with multiple redundant -uplinks (e.g., a server connected to two different switches), where assigning a -management IP address to a specific physical interface is risky. If that -interface fails, the management IP address becomes unreachable. - -Assigning the management IP address to a dummy interface and advertising it -over all available physical links ensures the address remains reachable as long -as at least one physical path is active. - -Dummy interfaces are also used for testing and simulation purposes. - -************* -Configuration -************* - -Common interface configuration -============================== - -.. cmdinclude:: /_include/interface-address.txt - :var0: dummy - :var1: dum0 - -.. cmdinclude:: /_include/interface-description.txt - :var0: dummy - :var1: dum0 - -.. cmdinclude:: /_include/interface-disable.txt - :var0: dummy - :var1: dum0 - -.. cmdinclude:: /_include/interface-vrf.txt - :var0: dummy - :var1: dum0 - -********* -Operation -********* - -.. opcmd:: show interfaces dummy - - Show brief interface information. - - .. code-block:: none - - vyos@vyos:~$ show interfaces dummy - Codes: S - State, L - Link, u - Up, D - Down, A - Admin Down - Interface IP Address S/L Description - --------- ---------- --- ----------- - dum0 172.18.254.201/32 u/u - -.. opcmd:: show interfaces dummy <interface> - - Show detailed interface information. - - .. code-block:: none - - vyos@vyos:~$ show interfaces dummy dum0 - dum0: <BROADCAST,NOARP,UP,LOWER_UP> mtu 1500 qdisc noqueue state UNKNOWN group default qlen 1000 - link/ether 26:7c:8e:bc:fc:f5 brd ff:ff:ff:ff:ff:ff - inet 172.18.254.201/32 scope global dum0 - valid_lft forever preferred_lft forever - inet6 fe80::247c:8eff:febc:fcf5/64 scope link - valid_lft forever preferred_lft forever - - RX: bytes packets errors dropped overrun mcast - 0 0 0 0 0 0 - TX: bytes packets errors dropped carrier collisions - 1369707 4267 0 0 0 0 - - diff --git a/docs/configuration/interfaces/rst-ethernet.rst b/docs/configuration/interfaces/rst-ethernet.rst deleted file mode 100644 index e6c385e7..00000000 --- a/docs/configuration/interfaces/rst-ethernet.rst +++ /dev/null @@ -1,468 +0,0 @@ -:lastproofread: 2026-01-19 - -.. _ethernet-interface: - -######## -Ethernet -######## - -Ethernet interfaces (e.g., ``eth0``, ``eth1``) represent the host's physical -or virtual network ports. - -They are the most common interface type, serving as the base layer upon which -IP addresses, VLANs, and tunnels are configured to carry traffic across both -LANs and WANs. - -************* -Configuration -************* - -Common interface configuration -============================== - -.. cmdinclude:: /_include/interface-common-with-dhcp.txt - :var0: ethernet - :var1: eth0 - -.. cfgcmd:: set interfaces ethernet <interface> switchdev - - **Enable** ``switchdev`` **mode for the interface.** - - In ``switchdev`` mode, the interface offloads traffic switching between ports - to the hardware, bypassing the host CPU. This increases the interface’s - traffic-handling capacity and reduces its forwarding delay. - -.. note:: ``switchdev`` mode is available only on certain physical network - interfaces and requires a switchdev-compatible driver. - - -Ethernet options -================ - -.. cfgcmd:: set interfaces ethernet <interface> duplex <auto | full | half> - - **Configure duplex mode for the interface.** - - The following duplex modes are available: - - * ``auto``: The interface negotiates the duplex mode with the connected device. - * ``full``: The interface sends and receives data simultaneously. The - connected device must also be set to full-duplex to avoid a duplex mismatch. - * ``half``: The interface either sends or receives data, but not both at the - same time. - - The default duplex mode is ``auto``. - -.. cfgcmd:: set interfaces ethernet <interface> speed <auto | 10 | 100 | 1000 | - 2500 | 5000 | 10000 | 25000 | 40000 | 50000 | 100000> - - **Configure the interface's speed, in Mbit/s.** - - The following options are available: - - * ``auto``: The interface negotiates the speed with the connected device. - * ``10, 100, 1000 ...``: The interface operates at the selected speed. The - connected device must be set to the same speed to establish a connection. - - The default option is ``auto``. - -.. cfgcmd:: set interfaces ethernet <interface> ring-buffer rx <value> - - **Configure the receive (RX) ring buffer size for the interface.** - - The RX ring buffer size defines the number of incoming packets the interface - can queue in hardware before the CPU processes them. - - Higher values reduce the risk of drops when the NIC receives network traffic - faster than the CPU can process it, though latency may increase. Lower values - reduce latency but increase the risk of packet drops during incoming traffic - bursts. - - To view supported values for a specific interface, use: - -.. code-block:: none - - ethtool -g <interface> - -.. cfgcmd:: set interfaces ethernet <interface> ring-buffer tx <value> - - **Configure the transmit (TX) ring buffer size.** - - The TX ring buffer size defines the number of outgoing packets the interface - can queue in hardware before they are transmitted onto the network. - - Higher values reduce the risk of drops when the CPU generates traffic faster - than the NIC can handle, though latency may increase. Lower values reduce - latency but increase the risk of packet drops during outgoing traffic bursts. - - To view supported values for a specific interface, use: - -.. code-block:: none - - ethtool -g <interface> - -Interrupt Coalescing ----------- - -Interrupt coalescing is a mechanism that reduces CPU interrupt load by bundling -multiple packets into a single interrupt event instead of interrupting -the CPU for every packet arrival or transmission. - -.. note:: Not all network drivers or virtual interfaces support all - coalescing parameters. Use ``ethtool --show-coalesce <interface>`` - to verify which settings are supported by your hardware and driver. - -**Basic adaptive coalescing** - -.. cfgcmd:: set interfaces ethernet <interface> interrupt-coalescing adaptive-rx -.. cfgcmd:: set interfaces ethernet <interface> interrupt-coalescing adaptive-tx - - Enable adaptive interrupt coalescing. The NIC automatically tunes RX/TX - interrupt pacing based on traffic patterns to reduce CPU utilization - during high throughput while preserving latency at low packet rates. - -**Basic interrupt delay** - -.. cfgcmd:: set interfaces ethernet <interface> interrupt-coalescing rx-usecs <0-16384> -.. cfgcmd:: set interfaces ethernet <interface> interrupt-coalescing tx-usecs <0-16384> - - Set the delay in microseconds before generating an RX/TX interrupt after - receiving or transmitting a packet. Lower values reduce latency; higher - values reduce CPU load. - -**Interrupt frame thresholds** - -.. cfgcmd:: set interfaces ethernet <interface> interrupt-coalescing rx-frames <number> -.. cfgcmd:: set interfaces ethernet <interface> interrupt-coalescing tx-frames <number> - - Generate an RX/TX interrupt only after the specified number of packets - have been received or transmitted. - -**IRQ-specific coalescing** - -.. cfgcmd:: set interfaces ethernet <interface> interrupt-coalescing rx-usecs-irq <number> -.. cfgcmd:: set interfaces ethernet <interface> interrupt-coalescing rx-frames-irq <number> -.. cfgcmd:: set interfaces ethernet <interface> interrupt-coalescing tx-usecs-irq <number> -.. cfgcmd:: set interfaces ethernet <interface> interrupt-coalescing tx-frames-irq <number> - - Control interrupt coalescing parameters while the driver is already - servicing an interrupt (IRQ context). These settings allow finer tuning - of interrupt behavior under sustained load. - -**Adaptive rate thresholds** - -.. cfgcmd:: set interfaces ethernet <interface> interrupt-coalescing pkt-rate-low <number> -.. cfgcmd:: set interfaces ethernet <interface> interrupt-coalescing pkt-rate-high <number> - - Define packet-rate thresholds (packets per second) used by adaptive - coalescing to switch between low-rate and high-rate interrupt coalescing - profiles. - -**Low-rate adaptive parameters** - -.. cfgcmd:: set interfaces ethernet <interface> interrupt-coalescing rx-usecs-low <number> -.. cfgcmd:: set interfaces ethernet <interface> interrupt-coalescing rx-frame-low <number> -.. cfgcmd:: set interfaces ethernet <interface> interrupt-coalescing tx-usecs-low <number> -.. cfgcmd:: set interfaces ethernet <interface> interrupt-coalescing tx-frame-low <number> - - Interrupt coalescing parameters applied when the packet rate is below - ``pkt-rate-low``. Typically optimized for lower latency. - -**High-rate adaptive parameters** - -.. cfgcmd:: set interfaces ethernet <interface> interrupt-coalescing rx-usecs-high <number> -.. cfgcmd:: set interfaces ethernet <interface> interrupt-coalescing rx-frame-high <number> -.. cfgcmd:: set interfaces ethernet <interface> interrupt-coalescing tx-usecs-high <number> -.. cfgcmd:: set interfaces ethernet <interface> interrupt-coalescing tx-frame-high <number> - - Interrupt coalescing parameters applied when the packet rate exceeds - ``pkt-rate-high``. Typically optimized for maximum throughput and - reduced CPU utilization. - -**Statistics and sampling** - -.. cfgcmd:: set interfaces ethernet <interface> interrupt-coalescing stats-block-usecs <number> -.. cfgcmd:: set interfaces ethernet <interface> interrupt-coalescing sample-interval <number> - - Control how frequently coalescing statistics are updated and how often - the NIC samples traffic rates for adaptive coalescing decisions. - -**Completion queue (CQE) mode** - -.. cfgcmd:: set interfaces ethernet <interface> interrupt-coalescing cqe-mode-rx -.. cfgcmd:: set interfaces ethernet <interface> interrupt-coalescing cqe-mode-tx - - Enable RX/TX Completion Queue Entry (CQE) mode, if supported by the - driver. CQE mode can improve performance on high-speed NICs by - optimizing completion handling. - -**Transmit aggregation** - -.. cfgcmd:: set interfaces ethernet <interface> interrupt-coalescing tx-aggr-max-bytes <number> -.. cfgcmd:: set interfaces ethernet <interface> interrupt-coalescing tx-aggr-max-frames <number> -.. cfgcmd:: set interfaces ethernet <interface> interrupt-coalescing tx-aggr-time-usecs <number> - - Control transmit packet aggregation. Packets may be buffered and sent - together until one of the configured limits (bytes, frames, or time) - is reached, reducing interrupt and DMA overhead. - - -Offloading ----------- - -.. cfgcmd:: set interfaces ethernet <interface> offload <lro | tso | gso | - gro | rps | sg > - - **Configure the offloading features for the interface.** - - The interface offloading features define whether specific packet-processing tasks - are performed by hardware (the NIC) or by software (the kernel). You can enable - multiple offloading features for a single interface. - - - * ``lro`` **(Large Receive Offload):** Instructs the NIC to merge multiple - incoming packets into one larger packet before sending it to the CPU. - - .. note:: :abbr:`LRO (Large Receive Offload)` hardware support is often limited - to TCP/IPv4 packets. For details on LRO limitations, see - https://lwn.net/Articles/358910/ - - .. warning:: :abbr:`LRO (Large Receive Offload)` irreversibly alters packet - headers during merging. This prevents the merged packet from being correctly - split back into the original packets, causing packet drops and forwarding - failures on routers and bridges. Use :abbr:`LRO (Large Receive Offload)` only - for end-hosts that do not forward traffic. - - * ``tso`` **(TCP Segmentation Offload):** Instructs the NIC to split large TCP - packets into smaller ones before transmitting them to the network. - - **Important:** :abbr:`SG (Scatter-Gather/Scatter-Gather DMA)` must be enabled - for :abbr:`TSO (TCP Segmentation Offload)` to work. Additionally, :abbr:`GSO - (Generic Segmentation Offload)` should be enabled as a safety fallback; it - ensures that if traffic is rerouted to hardware without :abbr:`TSO (TCP - Segmentation Offload)` support, the kernel can still segment the packets, - preventing transmission failures. - - * ``gso`` **(Generic Segmentation Offload):** Instructs the kernel to split - large packets into smaller ones before sending them to the NIC. - - :abbr:`GSO (Generic Segmentation Offload)` serves as a software fallback for - hardware that does not support :abbr:`TSO (TCP Segmentation Offload)` or for - protocols (like UDP) that hardware cannot offload. - - **Important:** :abbr:`SG (Scatter-Gather/Scatter-Gather DMA)` must be enabled - for :abbr:`GSO (Generic Segmentation Offload)` to work. - - * ``gro`` **(Generic Receive Offload):** Instructs the kernel to merge multiple - incoming packets into one larger packet before passing it to upper protocol - layers. - - Unlike LRO, GRO preserves the necessary packet metadata so the merged packet - can be correctly split back into the original packets. This makes GRO safe for - use on routers and bridges. - - .. note:: The exception is for IPv4 IDs. If the "Don't Fragment" (DF) bit is - set and IDs are not sequential, :abbr:`GSO (Generic Segmentation Offload)` - alters them to maintain a consistent sequence for :abbr:`GSO (Generic - Segmentation Offload)` compatibility. - - * ``rps`` **(Receive Packet Steering):** Instructs the kernel to distribute - the processing of incoming packets across multiple CPU cores. - - The kernel calculates a hash from packet headers (IP addresses and ports) to - ensure packets from the same flow are processed by the same CPU core. - - .. note:: :abbr:`RPS (Receive Packet Steering)` is a software version of - :abbr:`RSS (Receive Side Scaling)` and is useful for NICs without hardware - multi-queue support. - - * ``sg`` **(Scatter-Gather/Scatter-Gather DMA):** Instructs the NIC to fetch - data fragments from various RAM locations and transmit them as a single packet - to the network, eliminating the need for the kernel to copy them into a - contiguous block first. - -802.1X (EAPOL) authentication ------------------------------ - -.. cmdinclude:: /_include/interface-eapol.txt - :var0: ethernet - :var1: eth0 - -EVPN Multihoming ----------------- - -Uplink/core tracking. - -.. cmdinclude:: /_include/interface-evpn-uplink.txt - :var0: ethernet - :var1: eth0 - -VLAN -==== - -Regular VLANs (802.1q) ----------------------- - -.. cmdinclude:: /_include/interface-vlan-8021q.txt - :var0: ethernet - :var1: eth0 - -802.1ad (QinQ) --------------- - -.. cmdinclude:: /_include/interface-vlan-8021ad.txt - :var0: ethernet - :var1: eth0 - -SPAN port mirroring -=================== -.. cmdinclude:: ../../_include/interface-mirror.txt - :var0: ethernet - :var1: eth1 - :var2: eth3 - -********* -Operation -********* - -.. opcmd:: show interfaces ethernet - - Show brief interface information. - - .. code-block:: none - - vyos@vyos:~$ show interfaces ethernet - Codes: S - State, L - Link, u - Up, D - Down, A - Admin Down - Interface IP Address S/L Description - --------- ---------- --- ----------- - eth0 172.18.201.10/24 u/u LAN - eth1 172.18.202.11/24 u/u WAN - eth2 - u/D - -.. opcmd:: show interfaces ethernet <interface> - - Show detailed interface information. - - .. code-block:: none - - vyos@vyos:~$ show interfaces ethernet eth0 - eth0: <BROADCAST,MULTICAST,UP,LOWER_UP> mtu 1500 qdisc pfifo_fast state UP group default qlen 1000 - link/ether 00:50:44:00:f5:c9 brd ff:ff:ff:ff:ff:ff - inet6 fe80::250:44ff:fe00:f5c9/64 scope link - valid_lft forever preferred_lft forever - - RX: bytes packets errors dropped overrun mcast - 56735451 179841 0 0 0 142380 - TX: bytes packets errors dropped carrier collisions - 5601460 62595 0 0 0 0 - -.. stop_vyoslinter - -.. opcmd:: show interfaces ethernet <interface> physical - - Show interface hardware-level and driver details. - - .. code-block:: none - - vyos@vyos:~$ show interfaces ethernet eth0 physical - Settings for eth0: - Supported ports: [ TP ] - Supported link modes: 1000baseT/Full - 10000baseT/Full - Supported pause frame use: No - Supports auto-negotiation: No - Supported FEC modes: Not reported - Advertised link modes: Not reported - Advertised pause frame use: No - Advertised auto-negotiation: No - Advertised FEC modes: Not reported - Speed: 10000Mb/s - Duplex: Full - Port: Twisted Pair - PHYAD: 0 - Transceiver: internal - Auto-negotiation: off - MDI-X: Unknown - Supports Wake-on: uag - Wake-on: d - Link detected: yes - driver: vmxnet3 - version: 1.4.16.0-k-NAPI - firmware-version: - expansion-rom-version: - bus-info: 0000:0b:00.0 - supports-statistics: yes - supports-test: no - supports-eeprom-access: no - supports-register-dump: yes - supports-priv-flags: no - -.. start_vyoslinter - -.. opcmd:: show interfaces ethernet <interface> physical offload - - Show the status of the interface offloading features. - - .. code-block:: none - - vyos@vyos:~$ show interfaces ethernet eth0 physical offload - rx-checksumming on - tx-checksumming on - tx-checksum-ip-generic on - scatter-gather off - tx-scatter-gather off - tcp-segmentation-offload off - tx-tcp-segmentation off - tx-tcp-mangleid-segmentation off - tx-tcp6-segmentation off - udp-fragmentation-offload off - generic-segmentation-offload off - generic-receive-offload off - large-receive-offload off - rx-vlan-offload on - tx-vlan-offload on - ntuple-filters off - receive-hashing on - tx-gre-segmentation on - tx-gre-csum-segmentation on - tx-udp_tnl-segmentation on - tx-udp_tnl-csum-segmentation on - tx-gso-partial on - tx-nocache-copy off - rx-all off - -.. opcmd:: show interfaces ethernet <interface> transceiver - - Show information about the transceiver module plugged into the interface - (e.g., SFP+, QSFP). - - .. code-block:: none - - vyos@vyos:~$ show interfaces ethernet eth5 transceiver - Identifier : 0x03 (SFP) - Extended identifier : 0x04 (GBIC/SFP defined by 2-wire interface ID) - Connector : 0x07 (LC) - Transceiver codes : 0x00 0x00 0x00 0x01 0x00 0x00 0x00 0x00 0x00 - Transceiver type : Ethernet: 1000BASE-SX - Encoding : 0x01 (8B/10B) - BR, Nominal : 1300MBd - Rate identifier : 0x00 (unspecified) - Length (SMF,km) : 0km - Length (SMF) : 0m - Length (50um) : 550m - Length (62.5um) : 270m - Length (Copper) : 0m - Length (OM3) : 0m - Laser wavelength : 850nm - Vendor name : CISCO-FINISAR - Vendor OUI : 00:90:65 - Vendor PN : FTRJ-8519-7D-CS4 - Vendor rev : A - Option values : 0x00 0x1a - Option : RX_LOS implemented - Option : TX_FAULT implemented - Option : TX_DISABLE implemented - BR margin, max : 0% - BR margin, min : 0% - Vendor SN : FNS092xxxxx - Date code : 0506xx diff --git a/docs/configuration/interfaces/rst-geneve.rst b/docs/configuration/interfaces/rst-geneve.rst deleted file mode 100644 index bcd6c591..00000000 --- a/docs/configuration/interfaces/rst-geneve.rst +++ /dev/null @@ -1,100 +0,0 @@ -:lastproofread: 2026-02-02 - -.. _geneve-interface: - -###### -Geneve -###### - -:abbr:`Geneve (Generic Network Virtualization Encapsulation)` interfaces -operate as virtual network ports. Administrators can apply standard network -configurations on them, such as IP addressing, bridging, or firewall rules, -just as they would on physical Ethernet ports. - -The Geneve protocol encapsulates Layer 2 Ethernet frames originating from -endpoints such as virtual machines, containers, or physical servers inside UDP -packets. It unifies the features of earlier encapsulation protocols, including -VXLAN, NVGRE, and STT, and addresses their limitations, such as fixed header -structures and a lack of metadata support. Because of its extensibility, Geneve -may eventually replace those older protocols. - -Geneve tunnels are used to connect virtual switches residing within -hypervisors, physical switches, middleboxes, and other network appliances. - -Geneve tunnels operate over any standard IP network. In larger deployments, -the underlying network (underlay) is often built using a **Clos** topology, -also known as a *leaf-and-spine* or *fat-tree* topology. - -Geneve header: - -.. code-block:: none - - +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ - |Ver| Opt Len |O|C| Rsvd. | Protocol Type | - +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ - | Virtual Network Identifier (VNI) | Reserved | - +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ - | Variable Length Options | - +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ - -************* -Configuration -************* - -Common interface configuration -============================== - -.. cmdinclude:: /_include/interface-address.txt - :var0: geneve - :var1: gnv0 - -.. cmdinclude:: /_include/interface-description.txt - :var0: geneve - :var1: gnv0 - -.. cmdinclude:: /_include/interface-disable.txt - :var0: geneve - :var1: gnv0 - -.. cmdinclude:: /_include/interface-mac.txt - :var0: geneve - :var1: gnv0 - -.. cmdinclude:: /_include/interface-mtu.txt - :var0: geneve - :var1: gnv0 - -.. cmdinclude:: /_include/interface-ip.txt - :var0: geneve - :var1: gnv0 - -.. cmdinclude:: /_include/interface-ipv6.txt - :var0: geneve - :var1: gnv0 - -Geneve options -============== - -.. cfgcmd:: set interfaces geneve gnv0 remote <address> - - Configure the remote endpoint IP address for the Geneve tunnel. - -.. cfgcmd:: set interfaces geneve gnv0 vni <vni> - - **Configure** :abbr:`VNI (Virtual Network Identifier)` **for the Geneve - interface.** - - The VNI is a virtual network identifier. It allows multiple virtual networks to - share the same physical infrastructure and remain isolated. - - The VNI is also used to distribute traffic after it leaves the tunnel, for - example, to map packets with overlapping IP addresses to specific routing - tables. - -.. cfgcmd:: set interfaces gnv0 <interface> port <port> - - **Configure the destination UDP port for the remote Geneve tunnel endpoint.** - - Ensure the remote peer is configured to listen on this specific port. - - diff --git a/docs/configuration/interfaces/rst-index.rst b/docs/configuration/interfaces/rst-index.rst deleted file mode 100644 index 46d521b0..00000000 --- a/docs/configuration/interfaces/rst-index.rst +++ /dev/null @@ -1,28 +0,0 @@ -########## -Interfaces -########## - - -.. toctree:: - :maxdepth: 1 - :includehidden: - - bonding - bridge - dummy - ethernet - geneve - l2tpv3 - loopback - macsec - openvpn - wireguard - pppoe - pseudo-ethernet - sstp-client - tunnel - virtual-ethernet - vti - vxlan - wireless - wwan diff --git a/docs/configuration/interfaces/rst-l2tpv3.rst b/docs/configuration/interfaces/rst-l2tpv3.rst deleted file mode 100644 index 692dff93..00000000 --- a/docs/configuration/interfaces/rst-l2tpv3.rst +++ /dev/null @@ -1,167 +0,0 @@ -:lastproofread: 2026-02-05 - -.. _l2tpv3-interface: - -###### -L2TPv3 -###### - -:abbr:`L2TPv3 (Layer 2 Tunneling Protocol version 3)` interfaces let you -establish L2TPv3 tunnels to transport Layer 2 traffic over IP networks. - -The L2TPv3 protocol (defined in RFC 3931) wraps Layer 2 frames (e.g., Ethernet, -Frame Relay, HDLC) within IP packets, allowing them to traverse the underlying -IP infrastructure. - -Unlike L2TPv2, which strictly requires UDP encapsulation, the L2TPv3 protocol -is more flexible and supports two encapsulation types: - - * **Direct IP:** Tunnel data is encapsulated directly inside IP packets - (Protocol 115) for lower overhead. - * **UDP:** Tunnel data is encapsulated inside a UDP datagram. This allows the - tunnel to traverse NAT more easily. - -L2TPv3 tunnels connect geographically separated sites, serving as a simpler -alternative to :ref:`mpls` by operating over basic IP connectivity rather than -requiring a full MPLS infrastructure. - -L2TPv3 tunnels can be established over both IPv4 and IPv6 underlying networks. - -************* -Configuration -************* - -Common interface configuration -============================== - -.. cmdinclude:: /_include/interface-common-without-dhcp.txt - :var0: l2tpv3 - :var1: l2tpeth0 - -L2TPv3 options -============== - -Use the following commands to configure the L2TPv3 tunnel's specific parameters. - -.. cfgcmd:: set interfaces l2tpv3 <interface> encapsulation <udp | ip> - - **Configure the encapsulation type for the L2TPv3 tunnel.** - - Valid values are ``udp`` and ``ip``. - - The default encapsulation type is ``udp``. - -.. note:: The encapsulation type must match on both the local and remote peers - for the tunnel to establish. - -.. cfgcmd:: set interfaces l2tpv3 <interface> source-address <address> - - **Configure the L2TPv3 tunnel source IP address.** - - The specified address must be a local interface IP address and can be either - IPv4 or IPv6. - -.. cfgcmd:: set interfaces l2tpv3 <interface> remote <address> - - **Configure the L2TPv3 tunnel destination IP address.** - - The specified address must be a remote peer’s interface IP address and can be - either IPv4 or IPv6. - -.. cfgcmd:: set interfaces l2tpv3 <interface> session-id <id> - - **Configure the local session ID within the L2TPv3 tunnel.** - - The ``session-id`` is a 32-bit value that identifies an incoming tunnel session - on the local peer. - - The ``peer-session-id`` that identifies this session on the remote peer must be - set to the same value. - -.. cfgcmd:: set interfaces l2tpv3 <interface> peer-session-id <id> - - **Configure the peer session ID within the L2TPv3 tunnel.** - - The ``peer-session-id`` is a 32-bit value that identifies an outgoing tunnel - session from the local peer. - - The ``peer-session-id`` must match the ``session-id`` configured for this - session on the remote peer. - -.. cfgcmd:: set interfaces l2tpv3 <interface> tunnel-id <id> - - **Configure the local identifier for the L2TPv3 tunnel.** - - The ``tunnel-id`` is a 32-bit value that identifies the L2TPv3 tunnel on the - local peer. - - The ``peer-tunnel-id`` that identifies this tunnel on the remote peer must be - set to the same value. - -.. cfgcmd:: set interfaces l2tpv3 <interface> peer-tunnel-id <id> - - **Configure the peer identifier for the L2TPv3 tunnel.** - - The ``peer-tunnel-id`` is a 32-bit value that identifies the L2TPv3 tunnel on - the remote peer and must correspond to the ``tunnel-id`` configured for that - tunnel on that peer. - - The ``peer-tunnel-id`` must match the ``tunnel-id`` that identifies this tunnel - on the remote peer. - -******* -Example -******* - -L2TPv3 tunnel with IP encapsulation -=================================== - -The following example shows the configuration of an L2TPv3 tunnel using direct -IP encapsulation: - -.. code-block:: none - - # show interfaces l2tpv3 - l2tpv3 l2tpeth10 { - address 192.168.37.1/27 - encapsulation ip - source-address 192.0.2.1 - peer-session-id 100 - peer-tunnel-id 200 - remote 203.0.113.24 - session-id 100 - tunnel-id 200 - } - -The inverse configuration must be applied to the remote peer. - -L2TPv3 tunnel with UDP encapsulation -==================================== - -The following example shows the configuration of an L2TPv3 tunnel using UDP -encapsulation. - -This setup is recommended when the tunnel traverses NAT devices. - -Configuration notes: - -* Use a local LAN IP address as the ``source-address``. -* Configure a forwarding rule to allow tunnel traffic on the specified UDP port - on the upstream NAT device. -* Use a distinct UDP port for each individual tunnel. - -.. code-block:: none - - # show interfaces l2tpv3 - l2tpv3 l2tpeth10 { - address 192.168.37.1/27 - destination-port 9001 - encapsulation udp - source-address 192.0.2.1 - peer-session-id 100 - peer-tunnel-id 200 - remote 203.0.113.24 - session-id 100 - source-port 9000 - tunnel-id 200 - } diff --git a/docs/configuration/interfaces/rst-loopback.rst b/docs/configuration/interfaces/rst-loopback.rst deleted file mode 100644 index 68158111..00000000 --- a/docs/configuration/interfaces/rst-loopback.rst +++ /dev/null @@ -1,65 +0,0 @@ -:lastproofread: 2026-01-23 - -.. _loopback-interface: - -######## -Loopback -######## - -The loopback interface is a virtual, software-based network interface. All -traffic sent to it loops back and only targets services on the local host. - -.. note:: Only one loopback ``lo`` interface is allowed per operating system. - If you require multiple virtual interfaces, use the :ref:`dummy-interface` - interface type. - -************* -Configuration -************* - -Common interface configuration -============================== - -.. cmdinclude:: /_include/interface-address.txt - :var0: loopback - :var1: lo - -.. cmdinclude:: /_include/interface-description.txt - :var0: loopback - :var1: lo - -********* -Operation -********* - -.. opcmd:: show interfaces loopback - - Show brief interface information. - - .. code-block:: none - - vyos@vyos:~$ show interfaces loopback - Codes: S - State, L - Link, u - Up, D - Down, A - Admin Down - Interface IP Address S/L Description - --------- ---------- --- ----------- - lo 127.0.0.1/8 u/u - ::1/128 - -.. opcmd:: show interfaces loopback lo - - Show detailed interface information. - - .. code-block:: none - - vyos@vyos:~$ show interfaces loopback lo - lo: <LOOPBACK,UP,LOWER_UP> mtu 65536 qdisc noqueue state UNKNOWN group default qlen 1000 - link/loopback 00:00:00:00:00:00 brd 00:00:00:00:00:00 - inet 127.0.0.1/8 scope host lo - valid_lft forever preferred_lft forever - inet6 ::1/128 scope host - valid_lft forever preferred_lft forever - - RX: bytes packets errors dropped overrun mcast - 300 6 0 0 0 0 - TX: bytes packets errors dropped carrier collisions - 300 6 0 0 0 0 diff --git a/docs/configuration/interfaces/rst-macsec.rst b/docs/configuration/interfaces/rst-macsec.rst deleted file mode 100644 index 2a893943..00000000 --- a/docs/configuration/interfaces/rst-macsec.rst +++ /dev/null @@ -1,322 +0,0 @@ -:lastproofread: 2026-02-13 - -.. _macsec-interface: - -###### -MACsec -###### - -MACsec is an IEEE standard (IEEE 802.1AE) for MAC security, introduced in -2006. It enables protocol-independent connectivity between two hosts, providing -data confidentiality, authenticity, and integrity using GCM-AES ciphers. MACsec -operates at the Ethernet layer as a Layer 2 protocol and secures traffic within -Layer 2 networks, including DHCP and ARP requests. It does not compete with -other security solutions, such as IPsec (Layer 3) or TLS (Layer 4), as each -addresses distinct use cases. - -************* -Configuration -************* - -Common interface configuration -============================== - -.. cmdinclude:: /_include/interface-common-with-dhcp.txt - :var0: macsec - :var1: macsec0 - -MACsec options -============== - -.. cfgcmd:: set interfaces macsec <interface> security cipher <gcm-aes-128|gcm-aes-256> - - **Configure the cipher suite for the MACsec interface.** - - This configuration parameter is mandatory. - -.. cfgcmd:: set interfaces macsec <interface> security encrypt - - **Enable encryption on the MACsec interface.** - - By default, MACsec interfaces only provide authentication; encryption is - optional. - - When enabled, outgoing packets are encrypted using the configured cipher suite. - -.. cfgcmd:: set interfaces macsec <interface> source-interface <physical-source> - - **Configure a physical source interface for the MACsec interface.** - - Traffic transmitted through this interface is authenticated and, if configured, - encrypted. - -MACsec key management ---------------------- - -**Static** :abbr:`SAK (Secure Authentication Key)` **mode** - -In static SAK mode, administrators must manually configure and update SAKs on -each MACsec peer. :abbr:`MKA (MACsec Key Agreement protocol)` cannot be used in -this mode. - -.. cfgcmd:: set interfaces macsec <interface> security static key <key> - - **Configure the Transmit (TX) SAK for the MACsec interface.** - - The key must be a 16-byte (GCM-AES-128) or 64-byte (GCM-AES-256) hexadecimal - string. - -.. cfgcmd:: set interfaces macsec <interface> security static peer <peer> mac <mac address> - - **Configure the MAC address associated with the MACsec peer.** - -.. cfgcmd:: set interfaces macsec <interface> security static peer <peer> key <key> - - **Configure the RX SAK for traffic from the MACsec peer.** - - The key must be a 16-byte (GCM-AES-128) or 64-byte (GCM-AES-256) hexadecimal - string. - -.. cfgcmd:: set interfaces macsec <interface> security static peer <peer> disable - - Disable the specific MACsec peer. - - -**Dynamic** :abbr:`MKA (MACsec Key Agreement protocol)` **mode** - -In this mode, the :abbr:`MKA (MACsec Key Agreement protocol)` protocol is used -to generate, distribute, and update :abbr:`CAKs (MACsec Connectivity -Association Keys)`, and to authenticate MACsec peers. - - -.. cfgcmd:: set interfaces macsec <interface> security mka cak <key> - - **Configure the** :abbr:`CAK (MACsec Connectivity Association Key)` **for the - MACsec interface.** - - The :abbr:`CAK (MACsec Connectivity Association Key)` and its :abbr:`CKN - (MACsec Connectivity Association Key Name)` form the pre-shared master key pair - used to authenticate MACsec peers. - -.. cfgcmd:: set interfaces macsec <interface> security mka ckn <key> - - Configure the :abbr:`CKN (MACsec Connectivity Association Key Name)` for the - MACsec interface. - -.. cfgcmd:: set interfaces macsec <interface> security mka priority <priority> - - Configure the MKA key server priority for the MACsec interface. - - The peer with the lowest priority is elected as the key server. - -Replay protection ------------------ - -.. cfgcmd:: set interfaces macsec <interface> security replay-window <window> - - The replay protection window defines how many out-of-order frames can be - received before they are dropped as a potential replay attack. - - The following values are valid: - - - ``0``: Any out-of-order frame is immediately dropped. - - ``1-4294967295``: Allows the specified number of out-of-order frames. - -********* -Operation -********* - -.. opcmd:: run generate macsec mka cak <gcm-aes-128|gcm-aes-256> - - Generate a 128-bit (GCM-AES-128) or 256-bit (GCM-AES-256) :abbr:`MKA (MACsec - Key Agreement protocol)` :abbr:`CAK (MACsec Connectivity Association Key)`. - - .. code-block:: none - - vyos@vyos:~$ generate macsec mka cak gcm-aes-128 - 20693b6e08bfa482703a563898c9e3ad - -.. opcmd:: run generate macsec mka ckn - - Generate an :abbr:`MKA (MACsec Key Agreement protocol)` :abbr:`CAK (MACsec - Connectivity Association Key)`. - - .. code-block:: none - - vyos@vyos:~$ generate macsec mka ckn - 88737efef314ee319b2cbf30210a5f164957d884672c143aefdc0f5f6bc49eb2 - -.. opcmd:: show interfaces macsec - - Show all MACsec interfaces. - - .. code-block:: none - - vyos@vyos:~$ show interfaces macsec - 17: macsec1: protect on validate strict sc off sa off encrypt on send_sci on end_station off scb off replay off - cipher suite: GCM-AES-128, using ICV length 16 - TXSC: 005056bfefaa0001 on SA 0 - 20: macsec0: protect on validate strict sc off sa off encrypt off send_sci on end_station off scb off replay off - cipher suite: GCM-AES-128, using ICV length 16 - TXSC: 005056bfefaa0001 on SA 0 - -.. opcmd:: show interfaces macsec <interface> - - Show information for a specific MACsec interface. - - .. code-block:: none - - vyos@vyos:~$ show interfaces macsec macsec1 - 17: macsec1: protect on validate strict sc off sa off encrypt on send_sci on end_station off scb off replay off - cipher suite: GCM-AES-128, using ICV length 16 - TXSC: 005056bfefaa0001 on SA 0 - -******** -Examples -******** - -**Site-to-site MACsec with dynamic MKA over an untrusted network** - -In the following example, two routers (R1 and R2) are connected via an -untrusted switch, using their ``eth1`` interfaces as the underlay. The MACsec -interface (``macsec1``) with dynamic MKA encrypts traffic between them. - -Topology details: - -* R1 IP addresses: ``192.0.2.1/24`` and ``2001:db8::1/64``. -* R2 IP addresses: ``192.0.2.2/24`` and ``2001:db8::2/64``. - -**R1** - -.. code-block:: none - - set interfaces macsec macsec1 address '192.0.2.1/24' - set interfaces macsec macsec1 address '2001:db8::1/64' - set interfaces macsec macsec1 security cipher 'gcm-aes-128' - set interfaces macsec macsec1 security encrypt - set interfaces macsec macsec1 security mka cak '232e44b7fda6f8e2d88a07bf78a7aff4' - set interfaces macsec macsec1 security mka ckn '40916f4b23e3d548ad27eedd2d10c6f98c2d21684699647d63d41b500dfe8836' - set interfaces macsec macsec1 source-interface 'eth1' - -**R2** - -.. code-block:: none - - set interfaces macsec macsec1 address '192.0.2.2/24' - set interfaces macsec macsec1 address '2001:db8::2/64' - set interfaces macsec macsec1 security cipher 'gcm-aes-128' - set interfaces macsec macsec1 security encrypt - set interfaces macsec macsec1 security mka cak '232e44b7fda6f8e2d88a07bf78a7aff4' - set interfaces macsec macsec1 security mka ckn '40916f4b23e3d548ad27eedd2d10c6f98c2d21684699647d63d41b500dfe8836' - set interfaces macsec macsec1 source-interface 'eth1' - -Pinging (IPv6) the other host and intercepting traffic on ``eth1`` confirm that -the content is encrypted. - -.. code-block:: none - - 17:35:44.586668 00:50:56:bf:ef:aa > 00:50:56:b3:ad:d6, ethertype Unknown (0x88e5), length 150: - 0x0000: 2c00 0000 000a 0050 56bf efaa 0001 d9fb ,......PV....... - 0x0010: 920a 8b8d 68ed 9609 29dd e767 25a4 4466 ....h...)..g%.Df - 0x0020: 5293 487b 9990 8517 3b15 22c7 ea5c ac83 R.H{....;."..\.. - 0x0030: 4c6e 13cf 0743 f917 2c4e 694e 87d1 0f09 Ln...C..,NiN.... - 0x0040: 0f77 5d53 ed75 cfe1 54df 0e5a c766 93cb .w]S.u..T..Z.f.. - 0x0050: c4f2 6e23 f200 6dfe 3216 c858 dcaa a73b ..n#..m.2..X...; - 0x0060: 4dd1 9358 d9e4 ed0e 072f 1acc 31c4 f669 M..X...../..1..i - 0x0070: e93a 9f38 8a62 17c6 2857 6ac5 ec11 8b0e .:.8.b..(Wj..... - 0x0080: 6b30 92a5 7ccc 720b k0..|.r. - -Disabling encryption on the MACsec interface by removing the ``security -encrypt`` option shows the unencrypted but authenticated content. - -.. code-block:: none - - 17:37:00.746155 00:50:56:bf:ef:aa > 00:50:56:b3:ad:d6, ethertype Unknown (0x88e5), length 150: - 0x0000: 2000 0000 0009 0050 56bf efaa 0001 86dd .......PV....... - 0x0010: 6009 86f3 0040 3a40 2001 0db8 0000 0000 `....@:@........ - 0x0020: 0000 0000 0000 0001 2001 0db8 0000 0000 ................ - 0x0030: 0000 0000 0000 0002 8100 d977 0f30 0003 ...........w.0.. - 0x0040: 1ca0 c65e 0000 0000 8d93 0b00 0000 0000 ...^............ - 0x0050: 1011 1213 1415 1617 1819 1a1b 1c1d 1e1f ................ - 0x0060: 2021 2223 2425 2627 2829 2a2b 2c2d 2e2f .!"#$%&'()*+,-./ - 0x0070: 3031 3233 3435 3637 87d5 eed3 3a39 d52b 01234567....:9.+ - 0x0080: a282 c842 5254 ef28 ...BRT.( - -**Site-to-site MACsec with static SAK over an untrusted network** - -This example uses the same topology as above, but applies static SAK mode to -the MACsec interface configuration. - -**R1** - -.. code-block:: none - - set interfaces macsec macsec1 address '192.0.2.1/24' - set interfaces macsec macsec1 address '2001:db8::1/64' - set interfaces macsec macsec1 security cipher 'gcm-aes-128' - set interfaces macsec macsec1 security encrypt - set interfaces macsec macsec1 security static key 'ddd6f4a7be4d8bbaf88b26f10e1c05f7' - set interfaces macsec macsec1 security static peer R2 mac 00:11:22:33:44:02 - set interfaces macsec macsec1 security static peer R2 key 'eadcc0aa9cf203f3ce651b332bd6e6c7' - set interfaces macsec macsec1 source-interface 'eth1' - -**R2** - -.. code-block:: none - - set interfaces macsec macsec1 address '192.0.2.2/24' - set interfaces macsec macsec1 address '2001:db8::2/64' - set interfaces macsec macsec1 security cipher 'gcm-aes-128' - set interfaces macsec macsec1 security encrypt - set interfaces macsec macsec1 security static key 'eadcc0aa9cf203f3ce651b332bd6e6c7' - set interfaces macsec macsec1 security static peer R1 mac 00:11:22:33:44:01 - set interfaces macsec macsec1 security static peer R1 key 'ddd6f4a7be4d8bbaf88b26f10e1c05f7' - set interfaces macsec macsec1 source-interface 'eth1' - -*************** -MACsec over WAN -*************** - -MACsec offers an alternative to traditional tunneling solutions by securing -Layer 2 with integrity, origin authentication, and optional encryption. - -While typically deployed between hosts and access switches, MACsec can also -secure traffic over a WAN. In the following example, we combine VXLAN (for -transport) and MACsec (for security) to create a secure tunnel between two -sites. - -**R1 MACsec01** - -.. code-block:: none - - set interfaces macsec macsec1 address '192.0.2.1/24' - set interfaces macsec macsec1 address '2001:db8::1/64' - set interfaces macsec macsec1 security cipher 'gcm-aes-128' - set interfaces macsec macsec1 security encrypt - set interfaces macsec macsec1 security static key 'ddd6f4a7be4d8bbaf88b26f10e1c05f7' - set interfaces macsec macsec1 security static peer SEC02 key 'eadcc0aa9cf203f3ce651b332bd6e6c7' - set interfaces macsec macsec1 security static peer SEC02 mac '00:11:22:33:44:02' - set interfaces macsec macsec1 source-interface 'vxlan1' - set interfaces vxlan vxlan1 mac '00:11:22:33:44:01' - set interfaces vxlan vxlan1 remote '10.1.3.3' - set interfaces vxlan vxlan1 source-address '172.16.100.1' - set interfaces vxlan vxlan1 vni '10' - set protocols static route 10.1.3.3/32 next-hop 172.16.100.2 - -**R2 MACsec02** - -.. code-block:: none - - set interfaces macsec macsec1 address '192.0.2.2/24' - set interfaces macsec macsec1 address '2001:db8::2/64' - set interfaces macsec macsec1 security cipher 'gcm-aes-128' - set interfaces macsec macsec1 security encrypt - set interfaces macsec macsec1 security static key 'eadcc0aa9cf203f3ce651b332bd6e6c7' - set interfaces macsec macsec1 security static peer SEC01 key 'ddd6f4a7be4d8bbaf88b26f10e1c05f7' - set interfaces macsec macsec1 security static peer SEC01 mac '00:11:22:33:44:01' - set interfaces macsec macsec1 source-interface 'vxlan1' - set interfaces vxlan vxlan1 mac '00:11:22:33:44:02' - set interfaces vxlan vxlan1 remote '10.1.2.2' - set interfaces vxlan vxlan1 source-address '172.16.100.2' - set interfaces vxlan vxlan1 vni '10' - set protocols static route 10.1.2.2/32 next-hop 172.16.100.1 diff --git a/docs/configuration/interfaces/rst-openvpn-examples.rst b/docs/configuration/interfaces/rst-openvpn-examples.rst deleted file mode 100644 index 6e746e46..00000000 --- a/docs/configuration/interfaces/rst-openvpn-examples.rst +++ /dev/null @@ -1,929 +0,0 @@ - -############ -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, -it is effective for quickly establishing tunnels between routers. - -As of VyOS 1.4, OpenVPN site-to-site mode can use either pre-shared keys or -x.509 certificates. - -Pre-shared key mode is now deprecated and will be removed from future OpenVPN -versions. VyOS will also discontinue support for this option because pre-shared -keys are significantly less secure than TLS. - -We will configure OpenVPN with self-signed certificates, and then discuss the -legacy pre-shared key mode. - -In both cases, we will use the following settings: - -* The public IP address of the local VPN endpoint is 198.51.100.10. -* The public IP address of the remote VPN endpoint is 203.0.113.11. -* The tunnel uses 10.255.1.1 for the local IP address and 10.255.1.2 for the - remote IP address. -* The local site has a subnet of 10.0.0.0/16. -* The remote site has a subnet of 10.1.0.0/16. -* The official OpenVPN port 1194 is reserved for client VPN. For site-to-site - VPN, port 1195 is used. -* 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. - - -.. figure:: /_static/images/openvpn_site2site_diagram.* - -Set up site-to-site certificates --------------------------------- - -Deploying a complete Public Key Infrastructure (PKI) with a Certificate -Authority (CA) would overcomplicate site-to-site OpenVPN setups, which are -primarily designed for simplicity. To keep their configuration simple without -compromising security, VyOS 1.4 and later lets you verify self-signed -certificates using certificate fingerprints. - -Generate a self-signed certificate on each router, preferably using the -Elliptic Curve (EC) type. In configuration mode, run the following command: -``run generate pki certificate self-signed install <name>``. This adds the -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 - Enter private key type: [rsa, dsa, ec] (Default: rsa) ec - Enter private key bits: (Default: 256) - Enter country code: (Default: GB) - Enter state: (Default: Some-State) - Enter locality: (Default: Some-City) - Enter organization name: (Default: VyOS) - Enter common name: (Default: vyos.io) - Do you want to configure Subject Alternative Names? [y/N] - Enter how many days certificate will be valid: (Default: 365) - Enter certificate type: (client, server) (Default: server) - Note: If you plan to use the generated key on this router, do not encrypt the private key. - Do you want to encrypt the private key with a passphrase? [y/N] - 2 value(s) installed. Use "compare" to see the pending changes, and "commit" to apply. - [edit] - - vyos@vyos# compare - [pki] - + certificate openvpn-local { - + certificate "MIICJTCCAcugAwIBAgIUMXLfRNJ5iOjk/uAZqUe4phW8MdgwCgYIKoZIzj0EAwIwVzELMAkGA1UEBhMCR0IxEzARBgNVBAgMClNvbWUtU3RhdGUxEjAQBgNVBAcMCVNvbWUtQ2l0eTENMAsGA1UECgwEVnlPUzEQMA4GA1UEAwwHdnlvcy5pbzAeFw0yMzA5MDcyMTQzMTNaFw0yNDA5MDYyMTQzMTNaMFcxCzAJBgNVBAYTAkdCMRMwEQYDVQQIDApTb21lLVN0YXRlMRIwEAYDVQQHDAlTb21lLUNpdHkxDTALBgNVBAoMBFZ5T1MxEDAOBgNVBAMMB3Z5b3MuaW8wWTATBgcqhkjOPQIBBggqhkjOPQMBBwNCAASp7D0vE3SKSAWAzr/lw9Eq9Q89r247AJR6ec/GT26AIcVA1bsongV1YaWvRwzTPC/yi5pkzV/PcT/WU7JQIyMWo3UwczAMBgNVHRMBAf8EAjAAMA4GA1UdDwEB/wQEAwIHgDATBgNVHSUEDDAKBggrBgEFBQcDATAdBgNVHQ4EFgQUBrAxRdFppdG/UBRdo7qNyHutaTQwHwYDVR0jBBgwFoAUBrAxRdFppdG/UBRdo7qNyHutaTQwCgYIKoZIzj0EAwIDSAAwRQIhAI2+8C92z9wTcTWkQ/goRxs10EBC+h78O+vgo9k97z5iAiBSeqfaVr5taQTS31+McGTAK3cYWNTg0DlOBI8aKO2oRg==" - + private { - + key "MIGHAgEAMBMGByqGSM49AgEGCCqGSM49AwEHBG0wawIBAQQgtOeEb0dMb5P/2Exi09WWvk6Cvz0oOBoDuP68ZimS2LShRANCAASp7D0vE3SKSAWAzr/lw9Eq9Q89r247AJR6ec/GT26AIcVA1bsongV1YaWvRwzTPC/yi5pkzV/PcT/WU7JQIyMW" - + } - + } - - [edit] - - vyos@vyos# commit - -.. 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. - -Repeat the procedure on the other router. - -Set up site-to-site OpenVPN ---------------------------- - -Local configuration: - -.. stop_vyoslinter - -.. code-block:: none - - Configure the tunnel: - - set interfaces openvpn vtun1 mode site-to-site - set interfaces openvpn vtun1 protocol udp - set interfaces openvpn vtun1 persistent-tunnel - set interfaces openvpn vtun1 remote-host '203.0.113.11' # Public IP of the other side - set interfaces openvpn vtun1 local-port '1195' - set interfaces openvpn vtun1 remote-port '1195' - set interfaces openvpn vtun1 local-address '10.255.1.1' # Local IP of vtun interface - set interfaces openvpn vtun1 remote-address '10.255.1.2' # Remote IP of vtun interface - set interfaces openvpn vtun1 tls certificate 'openvpn-local' # The self-signed certificate - set interfaces openvpn vtun1 tls peer-fingerprint <remote cert fingerprint> # The output of 'run show pki certificate <name> fingerprint sha256' on the remote router - set interfaces openvpn vtun1 tls role active - -Remote configuration: - -.. code-block:: none - - set interfaces openvpn vtun1 mode site-to-site - set interfaces openvpn vtun1 protocol udp - set interfaces openvpn vtun1 persistent-tunnel - set interfaces openvpn vtun1 remote-host '198.51.100.10' # Pub IP of other site - set interfaces openvpn vtun1 local-port '1195' - set interfaces openvpn vtun1 remote-port '1195' - set interfaces openvpn vtun1 local-address '10.255.1.2' # Local IP of vtun interface - set interfaces openvpn vtun1 remote-address '10.255.1.1' # Remote IP of vtun interface - set interfaces openvpn vtun1 tls certificate 'openvpn-remote' # The self-signed certificate - set interfaces openvpn vtun1 tls peer-fingerprint <local cert fingerprint> # The output of 'run show pki certificate <name> fingerprint sha256 on the local router - set interfaces openvpn vtun1 tls role passive - -.. start_vyoslinter - -Set up pre-shared keys ----------------------- - -Before VyOS 1.4, site-to-site OpenVPN without PKI required pre-shared keys. -This option is still available but is deprecated and will be removed in future -releases. If you need to set up a tunnel to an older VyOS version or a system -with older OpenVPN, you still need to use pre-shared keys. - -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 - 2 value(s) installed. Use "compare" to see the pending changes, and "commit" to apply. - [edit] - vyos@local# compare - [pki openvpn shared-secret] - + s2s { - + key "7c73046a9da91e874d31c7ad894a32688cda054bde157c64270f28eceebc0bb2f44dbb70335fad45148b0456aaa78cb34a34c0958eeed4f75e75fd99ff519ef940f7029a316c436d2366a2b0fb8ea1d1c792a65f67d10a461af83ef4530adc25d1c872de6d9c7d5f338223d1f3b66dc3311bbbddc0e05228c47b91c817c721aadc7ed18f0662df52ad14f898904372679e3d9697d062b0869d12de47ceb2e626fa12e1926a3119be37dd29c9b0ad81997230f4038926900d5edb78522d2940cfe207f8e2b948e0d459fa137ebb18064ac5982b28dd1899020b4f2b082a20d5d4eb65710fbb1e62b5e061df39620267eab429d3eedd9a1ae85957457c8e4655f3" - + version "1" - + } - - [edit] - - vyos@local# commit - [edit] - -.. start_vyoslinter - -Next, install the key on the remote router: - -.. code-block:: none - - vyos@remote# set pki openvpn shared-secret s2s key <generated key string> - -Finally, configure the key in your OpenVPN interface settings: - -.. code-block:: none - - set interfaces openvpn vtun1 shared-secret-key s2s - -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' - set firewall ipv4 name OUTSIDE_LOCAL rule 10 description 'Allow established/related' - set firewall ipv4 name OUTSIDE_LOCAL rule 10 state 'established' - set firewall ipv4 name OUTSIDE_LOCAL rule 10 state 'related' - set firewall ipv4 name OUTSIDE_LOCAL rule 20 action 'accept' - set firewall ipv4 name OUTSIDE_LOCAL rule 20 description 'OpenVPN_IN' - set firewall ipv4 name OUTSIDE_LOCAL rule 20 destination port '1195' - 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: - -.. code-block:: none - - set firewall ipv4 input filter rule 10 action 'jump' - set firewall ipv4 input filter rule 10 inbound-interface name eth0 - set firewall ipv4 input filter rule 10 jump-target OUTSIDE_LOCAL - -Static routing: - -Configure static routes by referencing the tunnel interface. For example, if -the local router's network is ``10.0.0.0/16`` and the remote router's network -is ``10.1.0.0/16``, define the routes as follows: - -Local configuration: - -.. code-block:: none - - set protocols static route 10.1.0.0/16 interface vtun1 - -Remote configuration: - -.. code-block:: none - - set protocols static route 10.0.0.0/16 interface vtun1 - -As with standard Ethernet interfaces, you can apply firewall policies to the -tunnel interface for input, output, and forward directions. - -If you use multiple tunnels, OpenVPN must distinguish between them beyond just -the pre-shared key. To achieve this, assign either unique IP addresses or -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 - - OpenVPN status on vtun1 - - Client CN Remote Host Tunnel IP Local Host TX bytes RX bytes Connected Since - ----------- ----------------- ----------- ------------ ---------- ---------- ----------------- - N/A 10.110.12.54:1195 N/A N/A 504.0 B 656.0 B N/A - -.. start_vyoslinter - -Server-client -============= - -In OpenVPN’s server-client mode, the server acts as a central hub, allowing -multiple clients to connect and securely route their traffic or access a -private network. Multi-client server is the most popular OpenVPN mode for -routers. - -Set up server-client certificates ---------------------------------- - -Server-client mode always uses x.509 authentication and therefore requires a -PKI setup. The PKI utility now simplifies the creation of Certificate -Authorities (CAs), server and client certificates, and Diffie-Hellman keys -directly in VyOS using configuration or operational mode commands. - -On the server, generate all certificates by running the following commands in -configuration mode. The certificates will be added to the configuration -session's PKI subtree. - -Certificate Authority (CA): - -.. stop_vyoslinter - -.. code-block:: none - - vyos@vyos# run generate pki ca install ca-1 - Enter private key type: [rsa, dsa, ec] (Default: rsa) - Enter private key bits: (Default: 2048) - Enter country code: (Default: GB) - Enter state: (Default: Some-State) - Enter locality: (Default: Some-City) - Enter organization name: (Default: VyOS) - Enter common name: (Default: vyos.io) ca-1 - Enter how many days certificate will be valid: (Default: 1825) - Note: If you plan to use the generated key on this router, do not encrypt the private key. - Do you want to encrypt the private key with a passphrase? [y/N] - 2 value(s) installed. Use "compare" to see the pending changes, and "commit" to apply. - [edit] - vyos@vyos# compare - [pki] - + ca ca-1 { - + certificate "MIIDlzCCAn+gAwIBAgIUQW7AtPu0Qzp7VzT0TyYx83/ME8swDQYJKoZIhvcNAQELBQAwVDELMAkGA1UEBhMCR0IxEzARBgNVBAgMClNvbWUtU3RhdGUxEjAQBgNVBAcMCVNvbWUtQ2l0eTENMAsGA1UECgwEVnlPUzENMAsGA1UEAwwEY2EtMTAeFw0yNTA2MTExMTIyMjJaFw0zMDA2MTAxMTIyMjJaMFQxCzAJBgNVBAYTAkdCMRMwEQYDVQQIDApTb21lLVN0YXRlMRIwEAYDVQQHDAlTb21lLUNpdHkxDTALBgNVBAoMBFZ5T1MxDTALBgNVBAMMBGNhLTEwggEiMA0GCSqGSIb3DQEBAQUAA4IBDwAwggEKAoIBAQDi+v6i241T9ABxq1ngjWxDQITkqjV0nq2Jb3HSSuQpXRCu7DWdQZlbvnMHnkV/WTL0RNgkhS4iV/WYhE+bLihwiZ0GTeQnUd1QJSkusFROX46w6kKXYUR5IQtcBC+vdky8PESynPd+DXsJn5X9JTWqDeviUAQz/ZjDzWk+71MBCqa+Zps1zpIjK0ywn7pR/HnDrxJOQXlBMNgvbv8U3IAZ2jJp0jTB8TnuDtWSA+XZejMm/EN/AWUQyliX6OJFSCIhBL2BZ9lmVms4/HkRpbd50k3vvCoz+lAOEE6VsH0fEdLC3lZ+CtXZ7kjp2wdWWuSs5ggIJYZZkixsCisbtEmbAgMBAAGjYTBfMA8GA1UdEwEB/wQFMAMBAf8wDgYDVR0PAQH/BAQDAgGGMB0GA1UdJQQWMBQGCCsGAQUFBwMCBggrBgEFBQcDATAdBgNVHQ4EFgQUAG9lvr7AzJ/y4vY/XlWxXru+6m0wDQYJKoZIhvcNAQELBQADggEBAKsu4eZa8Fha9aKfuKqlGQHPpEFfVDaVJmebw0uMw+b5Y8EpBxzZrgbqbk3Mty8pBjNa9jkZzph04gHN4pR6kg3iQlUKGxZUfsB9ZUjKhkgNdUI9zq1323MKEvuIuYdt61DCfBHwY6Xax5Ge+BahR2bXdPaQH452/+xMTqkukkpLbioTeIDg6FCU2HYPY5emDF5DDZAZWXtTqi0zdT3Y6FqiTvs5VuWwXCcp+HM+Lwe1/VVJhwi4CHTq0CKWnQIH5blYjmyxzRBlrlZm4ntWlL5Mtepa1A3DJirY4kw/SqMAAh/Q9lh41JzBc8epf+OdnOzK55YmtmctGO2o+NBCFi0=" - + private { - + key "MIIEvgIBADANBgkqhkiG9w0BAQEFAASCBKgwggSkAgEAAoIBAQDi+v6i241T9ABxq1ngjWxDQITkqjV0nq2Jb3HSSuQpXRCu7DWdQZlbvnMHnkV/WTL0RNgkhS4iV/WYhE+bLihwiZ0GTeQnUd1QJSkusFROX46w6kKXYUR5IQtcBC+vdky8PESynPd+DXsJn5X9JTWqDeviUAQz/ZjDzWk+71MBCqa+Zps1zpIjK0ywn7pR/HnDrxJOQXlBMNgvbv8U3IAZ2jJp0jTB8TnuDtWSA+XZejMm/EN/AWUQyliX6OJFSCIhBL2BZ9lmVms4/HkRpbd50k3vvCoz+lAOEE6VsH0fEdLC3lZ+CtXZ7kjp2wdWWuSs5ggIJYZZkixsCisbtEmbAgMBAAECggEAZdykF6wV8Z4n8NsoG4j8E/ZJbWEhWjO3x1y3JNutJw735LhmmysMSsreToXtxGfgYRTgNwt5l7oHoqmGHCsLxO1NBb5A7JBllIkIwUYqn31syOJofg0NsJpuwZ2zVLfvWe5mGg4tV2lvVPNEWXWwbp+Ow2KLcFWXkA+H8tFuW6F2mH3ntYlIi/WiCNjsEotNx8Kk7OVwt43DbkN/rbF5lxquuLedaSspOHuhIAOfZB5ZySfqohQalSAaguVD66rGPMrerZ2Vc7B1iJ6Mn/KZrSaQeHwyWrwDDHdzVwG9waydevtGTVO0dvH4etWnRypDx8p1FPJJKD4XVcsl3rR6oQKBgQD497Ep2RJcbNnKVj+kNXGriSGmyRSp6CL61KotepzgucK0RtGMeFJge56/otMHMAxIOcDMX6vRn2MB2pqVqwqUBQy6JfLrSemdpIjMN9xlX6Dw3BWP39SdewZ896/Eo0Q1ythMj1ORp+u3PqOlSa14Cy9aPwDWmNy2deD68YDnsQKBgQDpZE/T84BMQ0FzL6NRijZRzR6Dc775hRfmmSTYI0KqpG0gXNSc5UgrWSLN5H7fnx36mT01P7UkgXCInV0AlJOfkt4a8QTqM1Fh/rZbLLWpQE55S6Fs28GDiFYl2kvZT/TtxhA/E0POf/YXl/8KITS7ZVAZxE8rxBe1hVUfDbnlCwKBgQDeWUguGaGeTdCMNk8MNnbYPdaCAB+mRp3G6ls51sF4qi5Lltva2jKn3H/AoohZaP3vGzUm0WLACdsAct2QQXtnCsN9FBtJK2+qzKEn0dPR7X/s3IGdRse6BX+b6BFgSnfGmuxmI7L86L1JoHXCTnTQOx0FOjNjdI3ZnplZRIpdYQKBgFJacASU9l9yl+SiGZnLEDG7FBpEPE3lVbKrtSGDB6IY1NzHhMo76URKdop6Jv6XMcfcTIm+ihdwiRnblRaAVrrG4xJUm2xcYUoXy5bOZudq5oXMVxCHVngoImXG6l6q5P0Fl3P6Q0HZSye2HWsgnm/FZwdAisMhtU/61TdY65BTAoGBAM4jKeImiXta5lz1RgNiW/TPhft3UbOLj3TbzchNCNAamqCv4Tmh9YKB2d/mz2hNxbnAGe2cYn4iRYKcjJLMZ0UfBL2WxlrgQYQPPGzSD0fH1pLIXPohpBZpsGqNR3Nc8Jd+Uw3IiIJ2oxPCOPTOJsklNB0Xf1AlUUagB16bhhZZ" - + } - + } - - [edit] - vyos@vyos# commit - - -Server certificate: - -.. code-block:: none - - vyos@vyos# run generate pki certificate sign ca-1 install srv-1 - Do you already have a certificate request? [y/N] N - Enter private key type: [rsa, dsa, ec] (Default: rsa) - Enter private key bits: (Default: 2048) - Enter country code: (Default: GB) - Enter state: (Default: Some-State) - Enter locality: (Default: Some-City) - Enter organization name: (Default: VyOS) - Enter common name: (Default: vyos.io) srv-1 - Do you want to configure Subject Alternative Names? [y/N] - Enter how many days certificate will be valid: (Default: 365) - Enter certificate type: (client, server) (Default: server) server - Note: If you plan to use the generated key on this router, do not encrypt the private key. - Do you want to encrypt the private key with a passphrase? [y/N] - 2 value(s) installed. Use "compare" to see the pending changes, and "commit" to apply. - [edit] - vyos@vyos# compare - [pki certificate] - + srv-1 { - + certificate "MIIDrDCCApSgAwIBAgIULpu+qZjfG01kUI58XNmqXbQC3qQwDQYJKoZIhvcNAQELBQAwVDELMAkGA1UEBhMCR0IxEzARBgNVBAgMClNvbWUtU3RhdGUxEjAQBgNVBAcMCVNvbWUtQ2l0eTENMAsGA1UECgwEVnlPUzENMAsGA1UEAwwEY2EtMTAeFw0yNTA2MTExMTMxMDJaFw0yNjA2MTExMTMxMDJaMFUxCzAJBgNVBAYTAkdCMRMwEQYDVQQIDApTb21lLVN0YXRlMRIwEAYDVQQHDAlTb21lLUNpdHkxDTALBgNVBAoMBFZ5T1MxDjAMBgNVBAMMBXNydi0xMIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAysTrMfVH63aVidJT7bIf+zLwkLse07nGsv4aliGEbufr239RBHV4Jn8LbQ+nB/8mhYGjNY4OnZ7NYz3FU/iglo8qFtaZ26mWtPWpv2xW1F8JAEK7l5BAg42cBucxiIZFeRm+jkE6VN1bcNU0utnn3sbCwZMyH6pS9k08G1qrrFLA7ZFhv5AmgJcODmO8sigSAu7rRS/6O3eO6ICnVjvIfHLb+9DKKUEffHzFV8RrkqVCGmgisz9fF+j1Rvg9s+ylNc2lZJTbb1XnzixvSRro4t9I3uIWdpJ0iOu09YiTXGQgH9ER6V3rFiX00RdSiSXf+MJCV64hC1msg+8V3Nrw9QIDAQABo3UwczAMBgNVHRMBAf8EAjAAMA4GA1UdDwEB/wQEAwIHgDATBgNVHSUEDDAKBggrBgEFBQcDATAdBgNVHQ4EFgQUzH0h4vBxma89HF9rUQ+DW052c5swHwYDVR0jBBgwFoAUAG9lvr7AzJ/y4vY/XlWxXru+6m0wDQYJKoZIhvcNAQELBQADggEBAI/Cyd0y7AJ7wY3yRssCud2iJAl9/ZjgxzXOUo6ibawYIYOnSf9tS3eD4CIH4BgppDXoJZ/qEA4WvIsLx3yvnyOxiqyk3TQmKIZ27VJH+yQkgzPeiKrHn1pCXBKEb1/jlT8Ozu4Lmn/oFwDH6nk8toxI8DM+qsTxqUFlTA3ea9yaRtxeNPMWJdaxZSUYGVSZL0wVKw5ZuQ1Gn7vGVApWlYDKYbMozCuZUG1q8wMzFBRa7x0anvh5hM4bksLz+Y1ujCS8f8b4Xtb8KIdFrZtTvtl97crv62bN05VueAcbwtYbIBNWNoT/CvmqV7k3uPg95GYSNddFqEMbQHoyd8hdDCo=" - + private { - + key "MIIEvQIBADANBgkqhkiG9w0BAQEFAASCBKcwggSjAgEAAoIBAQDKxOsx9UfrdpWJ0lPtsh/7MvCQux7Tucay/hqWIYRu5+vbf1EEdXgmfwttD6cH/yaFgaM1jg6dns1jPcVT+KCWjyoW1pnbqZa09am/bFbUXwkAQruXkECDjZwG5zGIhkV5Gb6OQTpU3Vtw1TS62efexsLBkzIfqlL2TTwbWqusUsDtkWG/kCaAlw4OY7yyKBIC7utFL/o7d47ogKdWO8h8ctv70MopQR98fMVXxGuSpUIaaCKzP18X6PVG+D2z7KU1zaVklNtvVefOLG9JGuji30je4hZ2knSI67T1iJNcZCAf0RHpXesWJfTRF1KJJd/4wkJXriELWayD7xXc2vD1AgMBAAECggEACsUk3PVzSX11+ekTDigM7NHK11UpEQPoGu/GR70mBKIK9BCyI/N9W0YaPEO9kn4p9KNrINgXzKV3sVLBnXEyTmzyRl5Fs9YxLBF0X7eIcSVPHBVvU2CVHKez5uX2ypKfNAx7A6FRUNqlFbwtXdNfLoUOKSwBWI86ctytWaKaRb/TTSGQkaP/z/cwIsXOLfG9m6iFkw98ShUzalrUWNo/4fJKlO1+DvXVYE9sv9rjD8J7DtAbr5KykQ5n0AAlZTCWQ7jwMybSnjjY9ypZUms0l17raJrfhrdbWayc6xMDvtrmNIDebkF+J7cHU06aEV+yQXV/7yjyZgUSM2ANcHMdzQKBgQDmTi5tUeaj1JUSl9lAP/XUzcElw2tcU1B8qpX69J4ofjTNgj5okLWQZVIy1UyAfLOI3LJbHTBUtSvedhH0VaMulq99NXs5qnbPGG3//RBAc0wKhJknB5Qv0D3FxMI14kMO6jzPly+aIGEk4dTtHvZuHbbVHbKSZ5MMouLyT+SS7wKBgQDhZETARZ0MazeWRaPJwdkjlfNcqqcsnDicdcppCkcDCjeLxkVPZc8ej37rshOvw2Pf1D0PddGyOhJoWCWA8QE2LQoDHLaDnQ0L6aQ3yjN5Gxx9RCDFi3Zuat/mPcv3tFO7uUmeYvRC5fGYrghq29NADmUefOopAc06Izd4A3iqWwKBgQC1uPrpR7a1jwgRo7/I8q8HO1MseQY903+u3ut5GYuyZ+NCRYL4/zZEua4ibivvNnZzh7E0M9PvAwWag4+nO+uG11+hbJHO7rLQtnYVh5lLQa6+neI66cAD+kzDwH1+BwriufFB3Amzk9kTQR7B+6x3NvsNLmG5JADj96Mbj+7MAQKBgFIevEXplyzdK6WevexWqoyip8aNjtdcG+w1pofa7MCYymAs3zfseihCVBYADdguModsxsqJPNvY+Lf31cJDDRP2GP3FSmJtqEE84U5KZ7KqRBkH54DSLVZRrj4vKc+YbiGpgr8ogqKVMQ9V6U81xKREGmefT5mdRG74Qc+CREadAoGAFtdsH5js1yFEeGFad4BZJ69grEavD3pNCfIe9oIPtXvvFdzxd+QbKgqFf3JMJp/HYi8A0iv/i4mzf00KXzF4JU7bIJYrUVlk/w8x77gzDRIphsPqpMBJkTI0jisQHZKWNEe7IbmM/dWW2S4jvCkrhB7F5Szf72Q+j/lPbfx2g/8=" - + } - + } - - [edit] - vyos@vyos# commit - - -Diffie-Hellman key: - -.. code-block:: none - - vyos@vyos# run generate pki dh install dh-1 - Enter DH parameters key size: (Default: 2048) - Generating parameters... - 1 value(s) installed. Use "compare" to see the pending changes, and "commit" to apply. - [edit] - vyos@vyos# compare - [pki] - + dh dh-1 { - + parameters "MIIBCAKCAQEAp25kxwZeLZ7wcbRii5E5RD4uWCUOBxarzKEE0msa84omh5nZ9dv/4bfJw4gIXlA2+sGc2lLV/jajZminMryiSwJdisyVuUdOB7sJWZwrzHBAY0qFbNyaRMVJBar2xVm+XcKd3A2eNTEgn10G7rPPvf6CJ5isUKFaKT8ymUv+mI0upLneYdGs8/yS3sAojzeulCf49fa5SiaGCcZZkdOI3Nby1u/ZG4okqJ2wE2c2hRVLs1k5qrrono0OF4Dh0B91ihnywRfp1xPYeqpiln+OPh+PPgTuBxkz4VxwRDoQ+NhVr/LOCb3vbhnyFisxI0w4r3109cA3QiDmo1L14aKl1wIBAg==" - + } - - [edit] - vyos@vyos# commit - -Client certificate: - -.. code-block:: none - - vyos@vyos:~$ generate pki certificate sign ca-1 install client1 - Do you already have a certificate request? [y/N] N - Enter private key type: [rsa, dsa, ec] (Default: rsa) - Enter private key bits: (Default: 2048) - Enter country code: (Default: GB) - Enter state: (Default: Some-State) - Enter locality: (Default: Some-City) - Enter organization name: (Default: VyOS) - Enter common name: (Default: vyos.io) client1 - Do you want to configure Subject Alternative Names? [y/N] - Enter how many days certificate will be valid: (Default: 365) - Enter certificate type: (client, server) (Default: server) client - Note: If you plan to use the generated key on this router, do not encrypt the private key. - Do you want to encrypt the private key with a passphrase? [y/N] - You are not in configure mode, commands to install manually from configure mode: - 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. - -For more options, refer to :ref:`configuration/pki/index:pki`. - -Set up server-client OpenVPN ----------------------------- - -The following example demonstrates the most complicated scenario: each client -acts as a router with its own subnet (e.g., an HQ and multiple branch offices). -Simpler setups are subsets of it. - -In this scenario, the 10.23.1.0/24 network is used for client tunnel endpoints, -and all client subnets belong to 10.23.0.0/20. Each client needs access to the -192.168.0.0/16 network. - -Server configuration: - -.. code-block:: none - - set interfaces openvpn vtun10 encryption data-ciphers 'aes256' - set interfaces openvpn vtun10 hash 'sha512' - set interfaces openvpn vtun10 local-host '172.18.201.10' - set interfaces openvpn vtun10 local-port '1194' - set interfaces openvpn vtun10 mode 'server' - set interfaces openvpn vtun10 persistent-tunnel - set interfaces openvpn vtun10 protocol 'udp' - set interfaces openvpn vtun10 server client client1 ip '10.23.1.10' - set interfaces openvpn vtun10 server client client1 subnet '10.23.2.0/25' - set interfaces openvpn vtun10 server domain-name 'vyos.net' - set interfaces openvpn vtun10 server max-connections '250' - set interfaces openvpn vtun10 server name-server '172.16.254.30' - set interfaces openvpn vtun10 server subnet '10.23.1.0/24' - set interfaces openvpn vtun10 server topology 'subnet' - set interfaces openvpn vtun10 tls ca-certificate ca-1 - set interfaces openvpn vtun10 tls certificate srv-1 - set interfaces openvpn vtun10 tls dh-params dh-1 - -The configuration above uses the default 1194/UDP port, 256-bit AES encryption, -SHA-512 for HMAC authentication, and the persistent-tunnel option. -Persistent-tunnel is recommended as it keeps the TUN/TAP device active during -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. - -.. code-block:: none - - set interfaces openvpn vtun10 server push-route 192.168.0.0/16 - -OpenVPN does not automatically create kernel routes for client subnets when -clients connect; it only uses client-subnet association internally. Therefore, -you must manually create a route to the 10.23.0.0/20 network: - -.. code-block:: none - - set protocols static route 10.23.0.0/20 interface vtun10 - -Set up OpenVPN client ---------------------- - -VyOS can operate not only as an OpenVPN site-to-site peer or a server for -multiple clients, but also as an OpenVPN client. Any VyOS OpenVPN interface -can be configured to connect to another VyOS or third-party OpenVPN server. - -Client configuration: - -.. code-block:: none - - set interfaces openvpn vtun10 encryption data-ciphers 'aes256' - set interfaces openvpn vtun10 hash 'sha512' - set interfaces openvpn vtun10 mode 'client' - set interfaces openvpn vtun10 persistent-tunnel - set interfaces openvpn vtun10 protocol 'udp' - set interfaces openvpn vtun10 remote-host '172.18.201.10' - set interfaces openvpn vtun10 remote-port '1194' - set interfaces openvpn vtun10 tls ca-certificate ca-1 - set interfaces openvpn vtun10 tls certificate client1 - -Verification ------------- - -Check the tunnel status: - -.. stop_vyoslinter - -.. code-block:: none - - vyos@vyos:~$ show openvpn server - - OpenVPN status on vtun10 - - Client CN Remote Host Tunnel IP Local Host TX bytes RX bytes Connected Since - ----------- ------------------ ----------- ---------------- ---------- ---------- ------------------- - 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 -============= - -In Ethernet bridging configurations, an OpenVPN interface operating in server -mode with the device type set to TAP can be added to a bridge. By encapsulating -entire Ethernet frames (up to 1514 bytes) rather than just IP packets (up to -1500 bytes), this setup enables clients to transmit Layer 2 frames through the -OpenVPN tunnel. - -The following is a basic configuration example: - -Server side: - -.. code-block:: none - - set interfaces bridge br10 member interface eth1.10 - set interfaces bridge br10 member interface vtun10 - set interfaces openvpn vtun10 device-type 'tap' - set interfaces openvpn vtun10 encryption data-ciphers 'aes192' - set interfaces openvpn vtun10 hash 'sha256' - set interfaces openvpn vtun10 local-host '172.18.201.10' - set interfaces openvpn vtun10 local-port '1194' - set interfaces openvpn vtun10 mode 'server' - set interfaces openvpn vtun10 server bridge gateway '10.10.0.1' - set interfaces openvpn vtun10 server bridge start '10.10.0.100' - set interfaces openvpn vtun10 server bridge stop '10.10.0.200' - set interfaces openvpn vtun10 server bridge subnet-mask '255.255.255.0' - set interfaces openvpn vtun10 server topology 'subnet' - set interfaces openvpn vtun10 tls ca-certificate 'ca-1' - set interfaces openvpn vtun10 tls certificate 'srv-1' - set interfaces openvpn vtun10 tls dh-params 'dh-1' - -Client side: - -.. code-block:: none - - set interfaces openvpn vtun10 device-type 'tap' - set interfaces openvpn vtun10 encryption data-ciphers 'aes192' - set interfaces openvpn vtun10 hash 'sha256' - set interfaces openvpn vtun10 mode 'client' - set interfaces openvpn vtun10 protocol 'udp' - set interfaces openvpn vtun10 remote-host '172.18.201.10' - set interfaces openvpn vtun10 remote-port '1194' - set interfaces openvpn vtun10 tls ca-certificate 'ca-1' - set interfaces openvpn vtun10 tls certificate 'client-1' - - - -Server LDAP authentication -========================== - -LDAP ----- - -Enterprise installations usually include a directory service to centralize -employee password management. VyOS and OpenVPN support using LDAP and Active -Directory as a single user backend. - -Authentication is performed by the ``openvpn-auth-ldap.so`` plugin, included -with every VyOS installation. To use it, you must create a dedicated -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 - - <LDAP> - # LDAP server URL - URL ldap://ldap.example.com - # Bind DN (If your LDAP server doesn't support anonymous binds) - BindDN cn=LDAPUser,dc=example,dc=com - # Bind Password password - Password S3cr3t - # Network timeout (in seconds) - Timeout 15 - </LDAP> - - <Authorization> - # Base DN - BaseDN "ou=people,dc=example,dc=com" - # User Search Filter - SearchFilter "(&(uid=%u)(objectClass=shadowAccount))" - # Require Group Membership - allow all users - RequireGroup false - </Authorization> - -Active Directory -^^^^^^^^^^^^^^^^ - -A sample configuration file is shown below: - -.. stop_vyoslinter - -.. code-block:: none - - <LDAP> - # LDAP server URL - URL ldap://dc01.example.com - # Bind DN (If your LDAP server doesn’t support anonymous binds) - BindDN CN=LDAPUser,DC=example,DC=com - # Bind Password - Password mysecretpassword - # Network timeout (in seconds) - Timeout 15 - # Enable Start TLS - TLSEnable no - # Follow LDAP Referrals (anonymously) - FollowReferrals no - </LDAP> - - <Authorization> - # Base DN - BaseDN "DC=example,DC=com" - # User Search Filter, user must be a member of the VPN AD group - SearchFilter "(&(sAMAccountName=%u)(memberOf=CN=VPN,OU=Groups,DC=example,DC=com))" - # Require Group Membership - RequireGroup false # already handled by SearchFilter - <Group> - BaseDN "OU=Groups,DC=example,DC=com" - SearchFilter "(|(cn=VPN))" - MemberAttribute memberOf - </Group> - </Authorization> - -.. 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 - - <LDAP> - URL ldap://dc01.example.com - BindDN CN=SA_OPENVPN,OU=ServiceAccounts,DC=example,DC=com - Password ThisIsTopSecret - Timeout 15 - TLSEnable no - FollowReferrals no - </LDAP> - - <Authorization> - BaseDN "DC=example,DC=com" - SearchFilter "sAMAccountName=%u" - RequireGroup false - </Authorization> - -A complete example of an LDAP authentication configuration for OpenVPN -is shown below: - -.. stop_vyoslinter - -.. code-block:: none - - vyos@vyos# show interfaces openvpn - openvpn vtun0 { - mode server - openvpn-option "--tun-mtu 1500 --fragment 1300 --mssfix" - openvpn-option "--plugin /usr/lib/openvpn/openvpn-auth-ldap.so /config/auth/ldap-auth.config" - openvpn-option "--push redirect-gateway" - openvpn-option --duplicate-cn - openvpn-option "--verify-client-cert none" - openvpn-option --comp-lzo - openvpn-option --persist-key - openvpn-option --persist-tun - server { - domain-name example.com - max-connections 5 - name-server 203.0.113.0.10 - name-server 198.51.100.3 - subnet 172.18.100.128/29 - } - tls { - ca-certificate ca.crt - certificate server.crt - dh-params dh1024.pem - } - } - -.. 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 -=========================== - -VyOS supports multi-factor authentication (MFA) or two-factor authentication -using Time-based One-Time Passwords (TOTP). It is compatible with Google -Authenticator and other software tokens. - -Server side ------------ - -.. code-block:: none - - set interfaces openvpn vtun20 encryption cipher 'aes256' - set interfaces openvpn vtun20 hash 'sha512' - set interfaces openvpn vtun20 mode 'server' - set interfaces openvpn vtun20 persistent-tunnel - set interfaces openvpn vtun20 server client user1 - set interfaces openvpn vtun20 server mfa totp challenge 'disable' - set interfaces openvpn vtun20 server subnet '10.10.2.0/24' - set interfaces openvpn vtun20 server topology 'subnet' - set interfaces openvpn vtun20 tls ca-certificate 'openvpn_vtun20' - set interfaces openvpn vtun20 tls certificate 'openvpn_vtun20' - set interfaces openvpn vtun20 tls dh-params 'dh-pem' - -A TOTP secret is created for each client in the OpenVPN server configuration. -To display authentication information, use the following command: -``show interfaces openvpn vtun20 user user1 mfa qrcode``. - -Example: - -.. stop_vyoslinter - -.. code-block:: none - - vyos@vyos:~$ sh interfaces openvpn vtun20 user user1 mfa qrcode - █████████████████████████████████████ - █████████████████████████████████████ - ████ ▄▄▄▄▄ █▀▄▀ ▀▀▄▀ ▀▀▄ █ ▄▄▄▄▄ ████ - ████ █ █ █▀▀▄ █▀▀▀█▀██ █ █ █ ████ - ████ █▄▄▄█ █▀█ ▄ █▀▀ █▄▄▄█ █▄▄▄█ ████ - ████▄▄▄▄▄▄▄█▄█ █ █ ▀ █▄▀▄█▄▄▄▄▄▄▄████ - ████▄▄ ▄ █▄▄ ▄▀▄█▄ ▄▀▄█ ▄▄▀ ▀▄█ ▀████ - ████ ▀██▄▄▄█▄ ██ █▄▄▄▄ █▄▀█ █ █▀█████ - ████ ▄█▀▀▄▄ ▄█▀ ▀▄ ▄▄▀▄█▀▀▀ ▄▄▀████ - ████▄█ ▀▄▄▄▀ ▀ ▄█ ▄ █▄█▀ █▀ █▀█████ - ████▀█▀ ▀ ▄█▀▄▀▀█▄██▄█▀▀ ▀ ▀ ▄█▀████ - ████ ██▄▄▀▄▄█ ██ ▀█ ▄█ ▀▄█ █▀██▀████ - ████▄███▄█▄█ ▀█▄ ██▄▄▄█▀ ▄▄▄ █ ▀ ████ - ████ ▄▄▄▄▄ █▄█▀▄ ▀▄ ▀█▀ █▄█ ██▀█████ - ████ █ █ █ ▄█▀█▀▀▄ ▄▀▀▄▄▄▄▄▄ ████ - ████ █▄▄▄█ █ ▄ ▀ █▄▄▄██▄▀█▄▀▄█▄ █████ - ████▄▄▄▄▄▄▄█▄██▄█▄▄▄▄▄█▄█▄█▄██▄██████ - █████████████████████████████████████ - █████████████████████████████████████ - -.. 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. - -Authentication with username/password -===================================== - -An OpenVPN server can securely obtain a username and password from a connecting -client and use this information for authentication. - -First, configure the server to use an authentication plugin or script. The -server calls this plugin every time a client tries to connect, passing it the -client's credentials. - -In the following example, the ``--auth-user-pass-verify`` directive is used -with the via-env method and a specified script path to validate the client's -username and password. - -Server configuration --------------------- - -.. stop_vyoslinter - -.. code-block:: none - - set interfaces openvpn vtun10 local-port '1194' - set interfaces openvpn vtun10 mode 'server' - set interfaces openvpn vtun10 openvpn-option '--auth-user-pass-verify /config/auth/check_user.sh via-env' - set interfaces openvpn vtun10 openvpn-option '--script-security 3' - set interfaces openvpn vtun10 persistent-tunnel - set interfaces openvpn vtun10 protocol 'udp' - set interfaces openvpn vtun10 server client client-1 ip '10.10.10.55' - set interfaces openvpn vtun10 server push-route 192.0.2.0/24 - set interfaces openvpn vtun10 server subnet '10.10.10.0/24' - set interfaces openvpn vtun10 server topology 'subnet' - set interfaces openvpn vtun10 tls ca-certificate 'ca-1' - set interfaces openvpn vtun10 tls certificate 'srv-1' - set interfaces openvpn vtun10 tls dh-params 'dh-1' - -.. start_vyoslinter - -The /config/auth/check_user.sh example includes two test users: - -.. code-block:: none - - #!/bin/bash - USERNAME="$username" - PASSWORD="$password" - - # Replace this with real user checking logic or use getent - if [[ "$USERNAME" == "client1" && "$PASSWORD" == "pass123" ]]; then - exit 0 - elif [[ "$USERNAME" == "peter" && "$PASSWORD" == "qwerty" ]]; then - exit 0 - else - exit 1 - fi - -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 -channel. You can now import this file into any OpenVPN client application. - -.. code-block:: none - - client - dev tun - proto udp - remote 192.168.77.10 1194 - - remote-cert-tls server - proto udp - dev tun - dev-type tun - persist-key - persist-tun - verb 3 - auth-user-pass - - - <ca> - -----BEGIN CERTIFICATE----- - MIIDlzCCAn+gAwIBAgIUQW7AtPu0Qzp7VzT0TyYx83/ME8swDQYJKoZIhvcNAQEL - BQAwVDELMAkGA1UEBhMCR0IxEzARBgNVBAgMClNvbWUtU3RhdGUxEjAQBgNVBAcM - CVNvbWUtQ2l0eTENMAsGA1UECgwEVnlPUzENMAsGA1UEAwwEY2EtMTAeFw0yNTA2 - MTExMTIyMjJaFw0zMDA2MTAxMTIyMjJaMFQxCzAJBgNVBAYTAkdCMRMwEQYDVQQI - DApTb21lLVN0YXRlMRIwEAYDVQQHDAlTb21lLUNpdHkxDTALBgNVBAoMBFZ5T1Mx - DTALBgNVBAMMBGNhLTEwggEiMA0GCSqGSIb3DQEBAQUAA4IBDwAwggEKAoIBAQDi - +v6i241T9ABxq1ngjWxDQITkqjV0nq2Jb3HSSuQpXRCu7DWdQZlbvnMHnkV/WTL0 - RNgkhS4iV/WYhE+bLihwiZ0GTeQnUd1QJSkusFROX46w6kKXYUR5IQtcBC+vdky8 - PESynPd+DXsJn5X9JTWqDeviUAQz/ZjDzWk+71MBCqa+Zps1zpIjK0ywn7pR/HnD - rxJOQXlBMNgvbv8U3IAZ2jJp0jTB8TnuDtWSA+XZejMm/EN/AWUQyliX6OJFSCIh - BL2BZ9lmVms4/HkRpbd50k3vvCoz+lAOEE6VsH0fEdLC3lZ+CtXZ7kjp2wdWWuSs - 5ggIJYZZkixsCisbtEmbAgMBAAGjYTBfMA8GA1UdEwEB/wQFMAMBAf8wDgYDVR0P - AQH/BAQDAgGGMB0GA1UdJQQWMBQGCCsGAQUFBwMCBggrBgEFBQcDATAdBgNVHQ4E - FgQUAG9lvr7AzJ/y4vY/XlWxXru+6m0wDQYJKoZIhvcNAQELBQADggEBAKsu4eZa - 8Fha9aKfuKqlGQHPpEFfVDaVJmebw0uMw+b5Y8EpBxzZrgbqbk3Mty8pBjNa9jkZ - zph04gHN4pR6kg3iQlUKGxZUfsB9ZUjKhkgNdUI9zq1323MKEvuIuYdt61DCfBHw - Y6Xax5Ge+BahR2bXdPaQH452/+xMTqkukkpLbioTeIDg6FCU2HYPY5emDF5DDZAZ - WXtTqi0zdT3Y6FqiTvs5VuWwXCcp+HM+Lwe1/VVJhwi4CHTq0CKWnQIH5blYjmyx - zRBlrlZm4ntWlL5Mtepa1A3DJirY4kw/SqMAAh/Q9lh41JzBc8epf+OdnOzK55Ym - tmctGO2o+NBCFi0= - -----END CERTIFICATE----- - - </ca> - - <cert> - -----BEGIN CERTIFICATE----- - MIIDrjCCApagAwIBAgIUN6vPxDEW89cfbEFPa0tZlnsW1GkwDQYJKoZIhvcNAQEL - BQAwVDELMAkGA1UEBhMCR0IxEzARBgNVBAgMClNvbWUtU3RhdGUxEjAQBgNVBAcM - CVNvbWUtQ2l0eTENMAsGA1UECgwEVnlPUzENMAsGA1UEAwwEY2EtMTAeFw0yNTA2 - MTExMTQ0MjlaFw0yNjA2MTExMTQ0MjlaMFcxCzAJBgNVBAYTAkdCMRMwEQYDVQQI - DApTb21lLVN0YXRlMRIwEAYDVQQHDAlTb21lLUNpdHkxDTALBgNVBAoMBFZ5T1Mx - EDAOBgNVBAMMB2NsaWVudDEwggEiMA0GCSqGSIb3DQEBAQUAA4IBDwAwggEKAoIB - AQCdOWq8vdO8CznGN83uAXCuN4PcdTJaRFEdJIEfqHjlcG0MZQuPIAlDbOU+IWmu - QBmeCj7SlbYtVYo1uQOMUaIrAvxLIQUaL1Y60oLVTF5eAPrGV+NSTQR5uMApcH9/ - RcZcW530pu/QpYinKTbGkEd54so6YRVPmYbIOPNUMbnZbccpinYi5t2dqubBb585 - A7L40043VtsVVbPjQq5V0HDursvqlaMqMRcffhR8H4B4ByU/EPRK4yTKm1hi19v3 - UtRHiq74CfGtJzYtplgrLJBON7TsbIi/fEux4q1yhbKA0S66L6e5DZldRxNZOXG6 - QjEL0RkYloMgkbv/2HLCu09hAgMBAAGjdTBzMAwGA1UdEwEB/wQCMAAwDgYDVR0P - AQH/BAQDAgeAMBMGA1UdJQQMMAoGCCsGAQUFBwMCMB0GA1UdDgQWBBQCkfdfq3hv - 7UtqAxq/5VDRIdgJLTAfBgNVHSMEGDAWgBQAb2W+vsDMn/Li9j9eVbFeu77qbTAN - BgkqhkiG9w0BAQsFAAOCAQEAJ43+aDVRC+y2vsu6WRG2l6zYnLoIJZW4afdKMC1a - nhTWhj4AhAt8evhVbAxi/8qhQX3yXF2bUQKdS++8AVcvZFlSES32S5eBx83AwGLt - QkgvGx+QThKmoJwrelyuS2X0XX3P0WzohYI6HzSr6p9F8KhTvSW97E6SnldpdvEM - uG1C+61/Vys7WLmDBh1PZTGE03nRp3H4Q9ynyXEEf1MK3eZkzg5H3Evj66p82pD5 - 8IauRfghMHJf3tOC+y0YIoXshF3lPq4nYso5Jc/HGCHlsboCODMCnY3CZsH7/O1n - /MI710KpzZTCLnv4Qtx9JpZxR7FTddl36OOuYUXU3Gcnsg== - -----END CERTIFICATE----- - - </cert> - - <key> - -----BEGIN PRIVATE KEY----- - MIIEvQIBADANBgkqhkiG9w0BAQEFAASCBKcwggSjAgEAAoIBAQCdOWq8vdO8CznG - N83uAXCuN4PcdTJaRFEdJIEfqHjlcG0MZQuPIAlDbOU+IWmuQBmeCj7SlbYtVYo1 - uQOMUaIrAvxLIQUaL1Y60oLVTF5eAPrGV+NSTQR5uMApcH9/RcZcW530pu/QpYin - KTbGkEd54so6YRVPmYbIOPNUMbnZbccpinYi5t2dqubBb585A7L40043VtsVVbPj - Qq5V0HDursvqlaMqMRcffhR8H4B4ByU/EPRK4yTKm1hi19v3UtRHiq74CfGtJzYt - plgrLJBON7TsbIi/fEux4q1yhbKA0S66L6e5DZldRxNZOXG6QjEL0RkYloMgkbv/ - 2HLCu09hAgMBAAECggEAOR3xRVUO9Sr816JRSQwz486eNDpNSxazgwtOb3JUTUH9 - E7onq1y/kMOgOmSIEHoP9GaTcQxbbPe86IxomhLT/50ri52YzWzx/heY2SVPyQXB - FMo79putKw0vnj5UyydNiyLrbMQyrhFc5iFmWVdz5/c4cWHwjIThPp7V4znXYwHZ - OB/Xn1NNHDNy872oQn5wZWzuA4ml0OqjU5D+Ne9srODl3r4OTo3lb1N3JuH3aOSA - cACl1JnN/KElN8IotIdweeUFAdn2jsGjZnCpGaJvZQ+2iMn6doJXHgFiF5+GMF7o - aOatglElIuqgPtB/4nvnegSL0DSnB36ojqv2PAh24wKBgQDPBt4S4muqo8SqP2e0 - 8X78MyK3tz1VmgPKn3O68Vdi1V7FPz0RHRGsw/kdgxXsJlfZTWgzcq2NNFu0yPBJ - A/h7qo16mv8GW7cJCd2exjb+/oq4r5iWeqLdSsMUXN87x02LRaMNd9wz1mls1Z73 - oQ5hJ7zTtlyYXnvKPQo8X1ImjwKBgQDCaptQxZ/a3tcUQQlXAFMAScviODZd0LCL - 30ZalwpNs6nVVIPoZHD3tlzWN5Es74gndfkC7/Gm2cnsOW9QQaU56q+5LeNXItW8 - rc6yXq3vNQerqJxHNUmKWwLCQtSyLRjFqpGTl/PyX2bGXQ7/zjTL3W8VMD5otf4Y - SJJB+sKjDwKBgHSVX3WvAAamFtfwwMwKuwH3IfPnQqj0BHKUfK2nvxgvJCFbzV3X - yt5Jtf3ClhPYO9xpVOa0C7va4lHaXkYf8Exj7SxAIKFKALccUStaYBoU6bW7XOhQ - w2pu8ZCEBEo7oBVv77Rj7SNb+R6K5ex5TAm2QQXQSjCb9IYc/ail3TNNAoGBALu6 - GPMrgKnlFyV1j0E1DPBwUbDEuqpoArFtDRAYXFifLVTS4PQbWIG403f9++659Gy2 - G5ZcfqiwD6xL4VJLsPF1zewvhR/0gRJJehb+GVGrkRaOHykbKUGxk75kreDGbu8f - PqaXyXS17hWIch1Lzes0jDiXdwvA//QOzztqmVq9AoGAVMbmf04+QtzckLolAP4q - Uwr5svfy14A7V3IGkwlsHZdm37L26lfxW0kpOOE7g7D6gdinuALo6oopP7RN/IDq - PLaaHaGrIoLAEVFa0bRLGsrU2q87ytwfSgdra4jmsTn+xEabdI4IgmqWgwSRvGVf - KN18e19Ssw5x7Wq0Rsw/3VM= - -----END PRIVATE KEY----- - - </key> - -When prompted, log in with the username and password. diff --git a/docs/configuration/interfaces/rst-openvpn.rst b/docs/configuration/interfaces/rst-openvpn.rst deleted file mode 100644 index 85877d48..00000000 --- a/docs/configuration/interfaces/rst-openvpn.rst +++ /dev/null @@ -1,521 +0,0 @@ -.. _openvpn: - -####### -OpenVPN -####### - -Traditionally, hardware routers use IPsec exclusively because it is easy to -implement in hardware, and their CPUs lack sufficient power for software-based -encryption. This limitation is less relevant for VyOS, as it is a software -router. - -OpenVPN has been widely used on UNIX platforms for a long time and is a popular -choice for remote-access VPNs. It also supports site-to-site connections. - -OpenVPN offers the following advantages: - -* It uses a single TCP or UDP connection and does not rely on packet source - addresses, so it works even through double NAT. This makes it well-suited for - public hotspots. - -* It is easy to set up and offers very flexible split tunneling. - -* A variety of client GUI frontends are available for any platform. - -Disadvantages include: - -* It is slower than IPsec due to higher protocol overhead and because it runs - in user mode, while IPsec on Linux runs in kernel mode. - -* No operating system includes OpenVPN client software by default. - -In the VyOS CLI, OpenVPN is configured as a network interface using ``set -interfaces openvpn`` rather than ``set vpn``, which is often overlooked. - -************* -Configuration -************* - -.. cfgcmd:: set interfaces openvpn <interface> authentication password <text> - - **Configure the password for the** ``auth-user-pass`` **authentication method.** - - This option applies only to OpenVPN clients. - -.. cfgcmd:: set interfaces openvpn <interface> authentication username <text> - - **Configure the username for the** ``auth-user-pass`` **authentication method.** - - This option applies only to OpenVPN clients. - -.. cfgcmd:: set interfaces openvpn <interface> description <description> - - Configure the description for the OpenVPN interface. - -.. cfgcmd:: set interfaces openvpn <interface> device-type <tap | tun> - - **Configure the virtual network device type for the OpenVPN interface:** - - * ``tun`` **(default)**: Operates at Layer 3, encapsulating IPv4 or IPv6 packets. - * ``tap``: Operates at Layer 2, encapsulating Ethernet 802.3 frames. - -.. cfgcmd:: set interfaces openvpn <interface> disable - - Disable the specific OpenVPN interface. - -.. cfgcmd:: set interfaces openvpn <interface> encryption cipher < 3des | aes128 | aes128gcm | aes192 | aes192gcm | aes256 | aes256gcm | none > - - **Configure the static encryption cipher for the OpenVPN tunnel.** - - The ``cipher`` option maps to OpenVPN’s ``--cipher`` directive and specifies - the symmetric encryption algorithm for both control and data channels. - - This was previously the default encryption method in all OpenVPN modes. In - newer OpenVPN versions, the ``--cipher`` directive is considered **legacy** - and should be used only in compatibility scenarios. - -.. cfgcmd:: set interfaces openvpn <interface> encryption data-ciphers < 3des | aes128 | aes128gcm | aes192 | aes192gcm | aes256 | aes256gcm | none > - - **Configure a prioritized list of negotiated ciphers for OpenVPN in** - ``client`` **or** ``server`` **mode.** - - The ``data-ciphers`` option represents a list of supported encryption - algorithms. It corresponds to OpenVPN’s ``--data-ciphers`` directive and - enables cipher negotiation, where both peers automatically agree on a mutually - supported cipher during session startup. - - .. note:: This option is not compatible with ``site-to-site`` mode. - -.. cfgcmd:: set interfaces openvpn <interface> encryption data-ciphers-fallback < 3des | aes128 | aes128gcm | aes192 | aes192gcm | aes256 | aes256gcm | none > - - **Configure the fallback cipher for** ``site-to-site`` **mode.** - - The ``data-ciphers-fallback`` option maps to OpenVPN’s ``--data-ciphers- - fallback`` directive. It defines the cipher to use if negotiation is **not - supported**. - - .. note:: This option ensures consistent encryption between two static peers - without cipher negotiation capability. - -.. cfgcmd:: set interfaces openvpn <interface> hash <md5 | sha1 | sha256 | ...> - - Configure the hashing algorithm for the OpenVPN interface. - -.. cmdinclude:: /_include/interface-ip.txt - :var0: openvpn - :var1: vtun0 - -.. cmdinclude:: /_include/interface-ipv6.txt - :var0: openvpn - :var1: vtun0 - -.. cfgcmd:: set interfaces openvpn <interface> keep-alive failure-count <value> - - **Configure the number of tolerated keepalive packet failures.** - - Default: 60 consecutive failures. - -.. cfgcmd:: set interfaces openvpn <interface> keep-alive interval <value> - - **Configure the frequency, in seconds, at which keepalive packets are sent.** - - Default: 10 seconds. - -.. cfgcmd:: set interfaces openvpn <interface> local-address <address> - - Configure the local tunnel IP address for ``site-to-site`` mode. - -.. cfgcmd:: set interfaces openvpn <interface> local-host <address> - - **Configure the local IP address to accept connections.** - - If configured, OpenVPN binds to this IP address only. - - By default, OpenVPN binds to all interfaces. - -.. cfgcmd:: set interfaces openvpn <interface> local-port <port> - - Configure the local port to accept connections. - -.. cfgcmd:: set interfaces openvpn <interface> mirror egress <monitor-interface> - - Configure mirroring of outgoing traffic from this OpenVPN interface to the - designated monitor interface. - -.. cfgcmd:: set interfaces openvpn <interface> mirror ingress <monitor-interface> - - Configure mirroring of incoming traffic from this OpenVPN interface to the - designated monitor interface. - -.. cfgcmd:: set interfaces openvpn <interface> mode <site-to-site | server | client> - - **Configure OpenVPN operation mode:** - - * ``site-to-site``: Establishes a site-to-site VPN connection. - * ``client``: Operates as a client in server-client mode. - * ``server``: Operates as a server in server-client mode. - - -OpenVPN Data Channel Offload (DCO) -================================== - -OpenVPN :abbr:`DCO (Data Channel Offload)` improves the performance of -encrypted OpenVPN data processing by keeping most data handling in the kernel -and avoiding frequent context switches between the kernel and user space. - -As a result, packet processing becomes more efficient and may utilize hardware -encryption offload support available in the kernel. - -.. note:: - - * :abbr:`DCO (Data Channel Offload)` is an **experimental**, not fully supported - OpenVPN feature. Some OpenVPN features and deployment scenarios are **not - compatible** with :abbr:`DCO (Data Channel Offload)`. - - For a complete list of supported features, visit: - - https://community.openvpn.net/openvpn/wiki/DataChannelOffload/Features - - * :abbr:`DCO (Data Channel Offload)` is configured per tunnel and disabled - by default. Existing tunnels operate without :abbr:`DCO (Data Channel - Offload)` unless it is explicitly enabled. - - * Enabling :abbr:`DCO (Data Channel Offload)` resets the interface. - -**Best practice:** Create a new tunnel with :abbr:`DCO (Data Channel Offload)` -enabled to avoid compatibility issues with existing clients. - -.. cfgcmd:: set interfaces openvpn <interface> offload dco - - **Enable** :abbr:`DCO (Data Channel Offload)` **for the specified OpenVPN - interface.** - - Example: - - .. code-block:: none - - set interfaces openvpn vtun0 offload dco - - This command enables :abbr:`DCO (Data Channel Offload)` and loads the required - kernel module. - -.. cfgcmd:: set interfaces openvpn <interface> openvpn-option <text> - - **Add raw OpenVPN configuration options to the openvpn.conf file.** - - OpenVPN provides many configuration options, but not all are available in the - VyOS CLI. - - If a required option is missing, you may submit a feature request at - Phabricator so all users can benefit from it (see :ref:`issues_features`). - - Alternatively, use ``openvpn-option`` to pass raw OpenVPN configuration options - to the openvpn.conf file. - - .. warning:: Use this option only as a last resort. Invalid options or syntax - may prevent OpenVPN from starting. Check system logs for errors after applying - changes. - - Example: - - .. code-block:: none - - set interfaces openvpn vtun0 openvpn-option 'persist-key' - - This command adds ``persist-key`` to the configuration file. This solves the - problem by persisting keys across resets, so they do not need to be re-read. - - .. code-block:: none - - set interfaces openvpn vtun0 openvpn-option 'route-up "/config/auth/tun_up.sh arg1"' - - This command adds ``route-up "/config/auth/tun_up.sh arg1"`` to the - configuration file. This option is executed after connection authentication, - either immediately or after a short delay, as defined. - - Ensure the path and arguments are enclosed in single or double quotes. - - .. note:: Some raw configuration options require quotes. To include them, use - the " statement. - -.. cfgcmd:: set interfaces openvpn <interface> persistent-tunnel - - **Enable always-active mode for the TUN/TAP device.** - - When enabled, the TUN/TAP device remains active upon connection resets or - daemon reloads. - -.. cfgcmd:: set interfaces openvpn <interface> protocol <udp | tcp-passive | tcp-active > - - **Configure the protocol for OpenVPN communication with a remote host:** - - * ``udp`` **(default)**: Uses the UDP protocol. - * ``tcp-passive``: Uses the TCP protocol and accepts connections passively. - * ``tcp-active``: Uses the TCP protocol and initiates connections actively. - -.. cfgcmd:: set interfaces openvpn <interface> redirect <interface> - - Enable redirection of incoming packets to the specified interface. - -.. cfgcmd:: set interfaces openvpn <interface> remote-address <address> - - Configure the remote tunnel IP address for site-to-site mode. - -.. cfgcmd:: set interfaces openvpn <interface> remote-host <address | host> - - **Configure the IPv4/IPv6 address or hostname for a server device if OpenVPN - runs in client mode.** - - This setting is not used in server mode. - -.. cfgcmd:: set interfaces openvpn <interface> remote-port <port> - - Configure the remote port to connect to the server. - -.. cfgcmd:: set interfaces openvpn <interface> replace-default-route - - Configure the OpenVPN tunnel as the default route. - -.. cfgcmd:: set interfaces openvpn <interface> server bridge disable - - Disable the given instance. - -.. cfgcmd:: set interfaces openvpn <interface> server bridge gateway <ipv4 address> - - Configure the gateway IP address. - -.. cfgcmd:: set interfaces openvpn <interface> server bridge start <ipv4 address> - - Configure the first IP address in the pool to allocate to connecting clients. - -.. cfgcmd:: set interfaces openvpn <interface> server bridge stop <ipv4 address> - - Configure the last IP address in the pool to allocate to connecting clients. - -.. cfgcmd:: set interfaces openvpn <interface> server bridge subnet-mask <ipv4 subnet mask> - - Configure the subnet mask pushed to dynamic clients. - -.. cfgcmd:: set interfaces openvpn <interface> server client <name> - - Configure the Common Name (CN) specified in the client certificate. - -.. cfgcmd:: set interfaces openvpn <interface> server client <name> disable - - Disable the client connection. - -.. cfgcmd:: set interfaces openvpn <interface> server client <name> ip <address> - - Configure the IPv4/IPv6 address for the client. - -.. cfgcmd:: set interfaces openvpn <interface> server client <name> push-route <subnet> - - Configure a route to be pushed to the specific client. - -.. cfgcmd:: set interfaces openvpn <interface> server client <name> subnet <subnet> - - **Configure a fixed subnet to be routed from the server to the specified - client.** - - Used as OpenVPN’s ``iroute`` directive. - -.. cfgcmd:: set interfaces openvpn <interface> server client-ip-pool start <address> - - Configure the first IP address in the subnet's IPv4 pool to be dynamically - allocated to connecting clients. - -.. cfgcmd:: set interfaces openvpn <interface> server client-ip-pool stop <address> - - Configure the last IP address in the subnet's IPv4 pool to be dynamically - allocated to connecting clients. - -.. cfgcmd:: set interfaces openvpn <interface> server client-ip-pool subnet <netmask> - - **Configure the subnet mask pushed to dynamic clients.** - - Use this command only for the TAP device type. Do not use it for bridged - interfaces. - -.. cfgcmd:: set interfaces openvpn <interface> server client-ipv6-pool base <ipv6addr/bits> - - Configure the IPv6 address pool for dynamic assignment to clients. - -.. cfgcmd:: set interfaces openvpn <interface> server domain-name <name> - - Configure the DNS suffix to be pushed to all clients. - -.. cfgcmd:: set interfaces openvpn <interface> server max-connections <1-4096> - - Configure the maximum number of client connections. - -.. cfgcmd:: set interfaces openvpn <interface> server mfa totp challenge <enable | disable> - - If enabled, openvpn-otp expects a password as a result of the challenge/ - response protocol. - -.. cfgcmd:: set interfaces openvpn <interface> server mfa totp digits <1-65535> - - **Configure the number of digits to use for the** :abbr:`TOTP (Time-based - One-Time Password)` **hash.** - - Default: 6. - -.. cfgcmd:: set interfaces openvpn <interface> server mfa totp drift <1-65535> - - **Configure the time drift in seconds.** - - Default: 0. - -.. cfgcmd:: set interfaces openvpn <interface> server mfa totp slop <1-65535> - - **Configure the allowed clock slop in seconds.** - - Default: 180. - -.. cfgcmd:: set interfaces openvpn <interface> server mfa totp step <1-65535> - - **Configure the step value for** :abbr:`TOTP (Time-based One-Time Password)` - **in seconds.** - - Default: 30. - -.. cfgcmd:: set interfaces openvpn <interface> server name-server <address> - - Define the client DNS configuration to be used with the connection. - -.. cfgcmd:: set interfaces openvpn <interface> server push-route <subnet> - - Configure the route to be pushed to all clients. - -.. cfgcmd:: set interfaces openvpn <interface> server reject-unconfigured-client - - Reject connections from clients that are not explicitly configured. - -.. cfgcmd:: set interfaces openvpn <interface> server subnet <subnet> - - **Configure the IPv4 or IPv6 network.** - - This parameter is mandatory when operating in server mode. - -.. cfgcmd:: set interfaces openvpn <interface> server topology < net30 | point-to-point | subnet> - - **Configure the virtual addressing topology for** ``tun`` **mode.** - - This command does not affect ``tap`` mode, which always uses the ``subnet`` - topology. - - * ``subnet`` **(default)**: Allocates a single IP address to each connecting client. - This is the recommended topology. - * ``net30``: Allocates a /30 subnet to each connecting client. This is a legacy - topology used to support Windows clients. It is now effectively deprecated. - * ``point-to-point``: Creates a point-to-point topology where the remote - endpoint of the client’s ``tun`` interface always points to the local endpoint - of the server’s ``tun`` interface. - - Like ``subnet``, this topology allocates a single IP address per client. Use it - only if no clients run Windows operating systems. - - -.. cfgcmd:: set interfaces openvpn <interface> shared-secret-key <key> - - Configure the static secret key for a site-to-site OpenVPN connection. - -.. cfgcmd:: set interfaces openvpn <interface> tls auth-key <key> - - **Configure the TLS secret key for tls-auth.** - - This adds an HMAC signature to all SSL/TLS handshake packets to verify - integrity. - - Use ``run generate pki openvpn shared-secret install <name>`` to generate - the key. - -.. cfgcmd:: set interfaces openvpn <interface> tls ca-certificate <name> - - Configure the Certificate Authority chain in the PKI configuration. - -.. cfgcmd:: set interfaces openvpn <interface> tls certificate <name> - - Configure the certificate name in the PKI configuration. - -.. cfgcmd:: set interfaces openvpn <interface> tls crypt-key - - Configure a shared secret key to provide an additional level of security, - a variant similar to tls-auth. - -.. cfgcmd:: set interfaces openvpn <interface> tls dh-params - - Configure Diffie-Hellman parameters for server mode. - -.. cfgcmd:: set interfaces openvpn <interface> tls peer-fingerprint <text> - - Configure the peer certificate SHA256 fingerprint for site-to-site mode. - -.. cfgcmd:: set interfaces openvpn <interface> tls role <active | passive> - - **Configure the TLS negotiation role, preferably used in site-to-site mode:** - - * ``active``: Initiates TLS negotiation actively. - * ``passive``: Waits for incoming TLS connections. - -.. cfgcmd:: set interfaces openvpn <interface> tls tls-version-min <1.0 | 1.1 | 1.2 | 1.3 > - - Configure the minimum TLS version to be accepted from the peer. - -.. cfgcmd:: set interfaces openvpn <interface> use-lzo-compression - - Configure fast LZO compression on this TUN/TAP interface. - -.. cfgcmd:: set interfaces openvpn <interface> vrf <name> - - Assign the interface to a specific VRF instance. - -************** -Operation mode -************** - -.. opcmd:: show openvpn site-to-site - - Show tunnel status for OpenVPN site-to-site interfaces. - -.. opcmd:: show openvpn server - - Show tunnel status for OpenVPN server interfaces. - -.. opcmd:: show openvpn client - - Show tunnel status for OpenVPN client interfaces. - -.. opcmd:: show log openvpn - - Show logs for all OpenVPN interfaces. - -.. opcmd:: show log openvpn interface <interface> - - Show logs for the specific OpenVPN interface. - -.. opcmd:: reset openvpn client <text> - - Reset the specified OpenVPN client. - -.. opcmd:: reset openvpn interface <interface> - - Reset the OpenVPN process on the specified interface. - -.. opcmd:: generate openvpn client-config interface <interface> ca <name> certificate <name> - - Generate an OpenVPN client configuration file in the .ovpn format for client machines. - -******** -Examples -******** - -This section covers examples of OpenVPN configurations for various deployments. - -.. toctree:: - :maxdepth: 1 - :includehidden: - - openvpn-examples - -.. include:: /_include/common-references.txt diff --git a/docs/configuration/interfaces/rst-pppoe.rst b/docs/configuration/interfaces/rst-pppoe.rst deleted file mode 100644 index d2f8271c..00000000 --- a/docs/configuration/interfaces/rst-pppoe.rst +++ /dev/null @@ -1,391 +0,0 @@ -:lastproofread: 2026-03-03 - -.. _pppoe-interface: - -##### -PPPoE -##### - -:abbr:`PPPoE (Point-to-Point Protocol over Ethernet)` is a network protocol -that encapsulates PPP frames within Ethernet frames. -It's often used for connecting ISP clients to a broadband access server. - -************* -Configuration -************* - -Common interface configuration -============================== - -.. cmdinclude:: /_include/interface-description.txt - :var0: pppoe - :var1: pppoe0 - -.. cmdinclude:: /_include/interface-disable.txt - :var0: pppoe - :var1: pppoe0 - -.. cmdinclude:: /_include/interface-mtu.txt - :var0: pppoe - :var1: pppoe0 - -.. cmdinclude:: /_include/interface-vrf.txt - :var0: pppoe - :var1: pppoe0 - -PPPoE options -============= - -.. cfgcmd:: set interfaces pppoe <interface> access-concentrator <name> - - **Configure the name of the target access concentrator for the PPPoE session.** - - During the PPPoE discovery process, the client sends a PPPoE initiation packet. - Multiple access concentrators may respond with offer packets, and the client - selects one of them. - - This setting restricts the client to establishing sessions only with the - specified access concentrator. - -.. cfgcmd:: set interfaces pppoe <interface> authentication username <username> - - **Configure the username for PPPoE session authentication.** - - Although authentication is optional in the interface configuration, most ISPs - require it to establish a connection. - -.. cfgcmd:: set interfaces pppoe <interface> authentication password <password> - - **Configure the password for PPPoE session authentication.** - - Although authentication is optional in the interface configuration, most ISPs - require it to establish a connection. - -.. cfgcmd:: set interfaces pppoe <interface> connect-on-demand - - **Enable dial-on-demand on the PPPoE interface.** - - When enabled, the system establishes a PPPoE connection only when traffic - passes through the interface. If the connection fails, it is reestablished when - traffic resumes. - - For on-demand connections, you must also configure an ``idle-timeout`` period - to disconnect the session after inactivity. - - .. note:: Setting the idle timeout to zero, or leaving it unconfigured, keeps - the connection active continuously once established. - - By default, the PPPoE connection is established at boot and remains active - continuously; if the connection fails, it is reestablished immediately. - -.. cfgcmd:: set interfaces pppoe <interface> no-default-route - - Request an IP address from the PPPoE server without installing a default route. - - Example: - - .. code-block:: none - - set interfaces pppoe pppoe0 no-default-route - - .. note:: Introduced in VyOS 1.4, this command inverts the logic of the former - ``default-route`` CLI option. - -.. cfgcmd:: set interfaces pppoe <interface> default-route-distance <distance> - - Configure the distance for the default gateway provided by the PPPoE server. - - Example: - - .. code-block:: none - - set interfaces pppoe pppoe0 default-route-distance 220 - -.. cfgcmd:: set interfaces pppoe <interface> mru <mru> - - **Configure the** :abbr:`MRU (Maximum Receive Unit)` **for the PPPoE - interface.** - - This setting instructs the pppd daemon to restrict the remote peer from sending - packets larger than the configured MRU. Allowed MRU values range from 128 to - 16384 bytes. - - An MRU of 296 is suitable for very slow links (40 bytes for the TCP/IP header - and 256 bytes for data). - - The default MRU is 1492 bytes. - - .. note:: When using the IPv6 protocol, the MRU must be at least 1280 bytes. - -.. cfgcmd:: set interfaces pppoe <interface> idle-timeout <time> - - **Configure the idle timeout for on-demand PPPoE sessions.** - - This setting defines how long the connection remains active without any traffic - before being disconnected. - - .. note:: Setting the idle timeout to zero, or leaving it unconfigured, keeps - the connection active continuously once established. - -.. cfgcmd:: set interfaces pppoe <interface> holdoff <time> - - **Configure the redial delay for persistent PPPoE sessions.** - - If a persistent session (with ``connect-on-demand`` disabled) is terminated by - the remote peer or drops unexpectedly, the router waits the specified interval - before attempting to reconnect. - - The default redial delay is 30 seconds. - -.. cfgcmd:: set interfaces pppoe <interface> local-address <address> - - **Configure the local endpoint IP address for PPPoE sessions.** - - By default, this IP address is negotiated. - -.. cfgcmd:: set interfaces pppoe <interface> no-peer-dns - - Disable the installation of advertised DNS nameservers on the local system. - -.. cfgcmd:: set interfaces pppoe <interface> remote-address <address> - - **Configure the remote endpoint IP address for PPPoE sessions.** - - By default, this IP address is negotiated. - -.. cfgcmd:: set interfaces pppoe <interface> service-name <name> - - **Configure the service name of the target access concentrator for the PPPoE - session.** - - By default, the PPPoE interface connects to any available access concentrator. - -.. cfgcmd:: set interfaces pppoe <interface> source-interface <source-interface> - - **Configure the underlying interface for the PPPoE connection.** - - Each PPPoE connection is established over an underlying interface, which can be - an Ethernet interface, a VIF, or a bonding interface. - -.. cfgcmd:: set interfaces pppoe <interface> ip adjust-mss <mss | clamp-mss-to-pmtu> - - **Configure the** :abbr:`MSS (Maximum Segment Size)` **advertised in outgoing - TCP SYN packets on the specified interface.** - - By clamping the MSS value in TCP SYN packets, you instruct the remote side not - to send packets larger than the specified size. This helps prevent connection - issues if :abbr:`PMTUD (Path MTU Discovery)` fails. - - The following options are available: - - * ``mss``: Sets the MSS to a specific value in bytes. - * ``clamp-mss-to-pmtu``: Sets the MSS to the interface’s MTU minus 40 bytes for - IPv4 traffic (20 bytes for the IPv4 header and 20 bytes for the TCP header). - This option is recommended to automatically set the proper value. - - .. note:: Introduced in VyOS 1.4, this command replaces the older ``set firewall - options interface <name> adjust-mss <value>`` syntax. - -.. cfgcmd:: set interfaces pppoe <interface> ip disable-forwarding - - **Configure the interface for host or router behavior.** - - If configured, the interface switches to host mode, and IPv4 forwarding is - disabled on it. - -.. cfgcmd:: set interfaces pppoe <interface> ip source-validation <strict | loose | disable> - - **Configure source IP address validation using** - :abbr:`RPF (Reverse Path Forwarding)` **on this interface, as specified in** - :rfc:`3704`. - - The following options are available: - - * ``strict``: Each incoming packet’s source IP address is checked against the - :abbr:`FIB (Forwarding Information Base)`. If the interface is not the best - route back to that source, validation fails, and the packet is dropped. - * ``loose``: Each incoming packet’s source IP address is checked against the - :abbr:`FIB (Forwarding Information Base)`. If the source IP address is - unreachable through any interface, validation fails. - * ``disable``: No source IP address validation is performed. All incoming - packets are accepted. - - :rfc:`3704` recommends enabling ``strict`` mode to prevent IP spoofing, such as - DDoS attacks. For asymmetric or other complex routing scenarios, use ``loose`` - mode. - -IPv6 ----- - -.. cfgcmd:: set interfaces pppoe <interface> ipv6 address autoconf - - Enable IPv6 address assignment via :abbr:`SLAAC (Stateless Address - Auto-Configuration)` on this interface. - -.. cfgcmd:: set interfaces pppoe <interface> ipv6 adjust-mss <mss | clamp-mss-to-pmtu> - - **Configure the** :abbr:`MSS (Maximum Segment Size)` **advertised in outgoing - TCP SYN packets on the specified interface.** - - By clamping the MSS value in TCP SYN packets, you instruct the remote side not - to send packets larger than the specified size. This helps prevent connection - issues if :abbr:`PMTUD (Path MTU Discovery)` fails. - - The following options are available: - - * ``mss``: Sets the MSS to a specific value in bytes. - * ``clamp-mss-to-pmtu``: Sets the MSS to the interface’s MTU minus 60 bytes for - IPv6 traffic (40 bytes for the IPv6 header and 20 bytes for the TCP header). - This option is recommended to automatically set the proper value. - - .. note:: Introduced in VyOS 1.4, this command replaces the older ``set firewall - options interface <name> adjust-mss <value>`` syntax. - - -.. cfgcmd:: set interfaces pppoe <interface> ipv6 disable-forwarding - - **Configure the interface for host or router behavior.** - - If configured, the interface switches to host mode, and IPv6 forwarding is - disabled on it. - -.. cmdinclude:: /_include/interface-dhcpv6-prefix-delegation.txt - :var0: pppoe - :var1: pppoe0 - -********* -Operation -********* - -.. opcmd:: show interfaces pppoe <interface> - - Show detailed information about a specific PPPoE interface. - - .. code-block:: none - - vyos@vyos:~$ show interfaces pppoe pppoe0 - pppoe0: <POINTOPOINT,MULTICAST,NOARP,UP,LOWER_UP> mtu 1492 qdisc pfifo_fast state UNKNOWN group default qlen 3 - link/ppp - inet 192.0.2.1 peer 192.0.2.255/32 scope global pppoe0 - valid_lft forever preferred_lft forever - - RX: bytes packets errors dropped overrun mcast - 7002658233 5064967 0 0 0 0 - TX: bytes packets errors dropped carrier collisions - 533822843 1620173 0 0 0 0 - -.. opcmd:: show interfaces pppoe <interface> queue - - Show queue information for a specific PPPoE interface. - - .. code-block:: none - - vyos@vyos:~$ show interfaces pppoe pppoe0 queue - qdisc pfifo_fast 0: root refcnt 2 bands 3 priomap 1 2 2 2 1 2 0 0 1 1 1 1 1 1 1 1 - Sent 534625359 bytes 1626761 pkt (dropped 62, overlimits 0 requeues 0) - backlog 0b 0p requeues 0 - -Connect/disconnect -================== - -.. opcmd:: disconnect interface <interface> - - Disconnect the specified interface. - -.. opcmd:: connect interface <interface> - - Initiate a session on the specified interface. - -******* -Example -******* - -PPPoE over DSL -============== - -**Configuration scenario:** - -* Your ISP's DSL modem is connected to the ``eth0`` interface on your VyOS - router. -* Your ISP does not require VLAN tagging. -* PPPoE credentials are provided by your ISP. The typical username format is - ``name@host.net``, though this may vary. - -**Configuration notes:** - -* The maximum MTU size for DSL is 1492 because of PPPoE overhead. If you are - switching from a DHCP-based ISP (e.g., a standard cable connection), ensure - VPN links have MTU sizes adjusted accordingly. -* To ignore ISP-provided nameservers and use only your statically configured - ones, set the ``name-server`` option to ``none``. -* A default route is automatically installed once the interface is up. To - change this behavior, use the ``no-default-route`` CLI option. - -.. note:: The PPPoE configuration syntax changed after VyOS 1.2 (Crux) and is - automatically migrated during an upgrade. - - -.. code-block:: none - - set interfaces pppoe pppoe0 authentication username 'userid' - set interfaces pppoe pppoe0 authentication password 'secret' - set interfaces pppoe pppoe0 source-interface 'eth0' - - -Secure your setup by creating rules matching the ``pppoe0`` interface in the -firewall chains: - -.. code-block:: none - - set firewall ipv4 input filter rule 10 inbound-interface name 'pppoe0' - set firewall ipv4 forward filter rule 10 inbound-interface name 'pppoe0' - - -PPPoE over VLAN -=============== - -Some ISPs require PPPoE connections to be -established over a VLAN interface. This specific topology is fully supported by -VyOS. - -The following configuration establishes the PPPoE connection through VLAN 7, -which is the default VLAN for Deutsche Telekom: - -.. code-block:: none - - set interfaces pppoe pppoe0 authentication username 'userid' - set interfaces pppoe pppoe0 authentication password 'secret' - set interfaces pppoe pppoe0 source-interface 'eth0.7' - - -IPv6 DHCPv6 prefix delegation ------------------------------ - -.. stop_vyoslinter - -**Configuration scenario:** - -The following configuration establishes a PPPoE session on the ``eth1`` -interface, requests a ``/56`` IPv6 prefix delegation from the ISP, and assigns -a ``/64`` subnet from that delegation to the ``eth0`` interface. - -**Configuration notes:** - -* The IPv6 address assigned to ``eth0`` is ``<prefix>::1/64``. -* If you do not know your delegated prefix size, begin with ``sla-len 0``. -* To advertise the prefix on the ``eth0`` link, configure IPv6 Router - Advertisement. - -.. start_vyoslinter - -.. code-block:: none - - set interfaces pppoe pppoe0 authentication username vyos - set interfaces pppoe pppoe0 authentication password vyos - set interfaces pppoe pppoe0 dhcpv6-options pd 0 interface eth0 address '1' - set interfaces pppoe pppoe0 dhcpv6-options pd 0 interface eth0 sla-id '0' - set interfaces pppoe pppoe0 dhcpv6-options pd 0 length '56' - set interfaces pppoe pppoe0 ipv6 address autoconf - set interfaces pppoe pppoe0 source-interface eth1 - - set service router-advert interface eth0 prefix ::/64 diff --git a/docs/configuration/interfaces/rst-pseudo-ethernet.rst b/docs/configuration/interfaces/rst-pseudo-ethernet.rst deleted file mode 100644 index cb42fafc..00000000 --- a/docs/configuration/interfaces/rst-pseudo-ethernet.rst +++ /dev/null @@ -1,54 +0,0 @@ -:lastproofread: 2026-03-05 - -.. _pseudo-ethernet-interface: - -######################### -MACVLAN (pseudo-Ethernet) -######################### - -MACVLAN, or pseudo-Ethernet interfaces, operate as logical subinterfaces of -standard Ethernet interfaces. Each subinterface has a unique MAC address but -shares a single physical Ethernet port. -That allows the user to send packets from different source IPv4 or IPv6 addresses -using a different MAC address. - - -Pseudo-Ethernet interfaces behave like physical Ethernet interfaces. They -support IPv4 and IPv6 addressing, can obtain IP addresses through DHCP or -DHCPv6, and are mapped to a physical Ethernet port. They inherit -characteristics such as speed and duplex from their parent interface and can -be referenced like standard Ethernet interfaces once created. - - -Pseudo-Ethernet interfaces may not work in environments that require a - :abbr:`NIC (Network Interface Card)` to have only one MAC address. - This includes: - - * VMware machines with default settings. - * Network switches that permit only a single MAC address. - * xDSL modems that learn the NIC's MAC address. - -************* -Configuration -************* - -Common interface configuration -============================== - -.. cmdinclude:: /_include/interface-common-with-dhcp.txt - :var0: pseudo-ethernet - :var1: peth0 - -MACVLAN (pseudo-Ethernet) options -================================= - -.. cfgcmd:: set interfaces pseudo-ethernet <interface> source-interface <ethX> - - Assign a physical Ethernet interface to the specified pseudo-Ethernet interface. - -VLAN -==== - -.. cmdinclude:: /_include/interface-vlan-8021q.txt - :var0: pseudo-ethernet - :var1: peth0 diff --git a/docs/configuration/interfaces/rst-sstp-client.rst b/docs/configuration/interfaces/rst-sstp-client.rst deleted file mode 100644 index 9c6c6e9b..00000000 --- a/docs/configuration/interfaces/rst-sstp-client.rst +++ /dev/null @@ -1,158 +0,0 @@ -:lastproofread: 2026-03-16 - -.. _sstp-client-interface: - -########### -SSTP client -########### - -:abbr:`SSTP (Secure Socket Tunneling Protocol)` transports PPP traffic over an -SSL/TLS channel, providing transport-level security through key negotiation, -encryption, and traffic integrity checking. The use of SSL/TLS over TCP port -443 (by default, the port can be changed) allows SSTP to pass through virtually -all firewalls and proxy servers, except for authenticated web proxies. - -.. note:: VyOS includes a built-in SSTP server. For more information, see - :ref:`sstp`. - -************* -Configuration -************* - -Common interface configuration -============================== - -.. cmdinclude:: /_include/interface-description.txt - :var0: sstpc - :var1: sstpc0 - -.. cmdinclude:: /_include/interface-disable.txt - :var0: sstpc - :var1: sstpc0 - -.. cmdinclude:: /_include/interface-mtu.txt - :var0: sstpc - :var1: sstpc0 - -.. cmdinclude:: /_include/interface-vrf.txt - :var0: sstpc - :var1: sstpc0 - -SSTP client options -=================== - -.. cfgcmd:: set interfaces sstpc <interface> no-default-route - - Request an IP address from the SSTP server without installing a default route. - - Example: - - .. code-block:: none - - set interfaces sstpc sstpc0 no-default-route - - .. note:: Introduced in VyOS 1.4, this command inverts the logic of the former - ``default-route`` CLI option. - -.. cfgcmd:: set interfaces sstpc <interface> default-route-distance <distance> - - Configure the distance for the default gateway provided by the SSTP server. - - Example: - - .. code-block:: none - - set interfaces sstpc sstpc0 default-route-distance 220 - -.. cfgcmd:: set interfaces sstpc <interface> no-peer-dns - - Disable the installation of advertised DNS nameservers on the local system. - -.. cfgcmd:: set interfaces sstpc <interface> server <address> - - **Configure the remote SSTP server address for the client connection.** - - The address can be either an IP address or a :abbr:`FQDN (Fully Qualified - Domain Name)`. - -.. cfgcmd:: set interfaces sstpc <interface> ip adjust-mss <mss | clamp-mss-to-pmtu> - - **Configure the** :abbr:`MSS (Maximum Segment Size)` **advertised in outgoing - TCP SYN packets on the specified interface.** - - By clamping the MSS value in TCP SYN packets, you instruct the remote side not - to send packets larger than the specified size. This helps prevent connection - issues if :abbr:`PMTUD (Path MTU Discovery)` fails. - - The following options are available: - - * ``mss``: Sets the MSS to a specific value in bytes. - * ``clamp-mss-to-pmtu``: Sets the MSS to the interface’s MTU minus 40 bytes for - IPv4 traffic (20 bytes for the IPv4 header and 20 bytes for the TCP header). - This option is recommended to automatically set the proper value. - - .. note:: Introduced in VyOS 1.4, this command replaces the older ``set firewall - options interface <name> adjust-mss <value>`` syntax. - -.. cfgcmd:: set interfaces sstpc <interface> ip disable-forwarding - - **Configure the interface for host or router behavior.** - - If configured, the interface switches to host mode, and IPv4 forwarding is - disabled on it. - -.. cfgcmd:: set interfaces sstpc <interface> ip source-validation <strict | loose | disable> - - **Configure source IP address validation using** - :abbr:`RPF (Reverse Path Forwarding)` **on this interface, as specified in** - :rfc:`3704`. - - The following options are available: - - * ``strict``: Each incoming packet’s source IP address is checked against the - :abbr:`FIB (Forwarding Information Base)`. If the interface is not the best - route back to that source, validation fails, and the packet is dropped. - * ``loose``: Each incoming packet’s source IP address is checked against the - :abbr:`FIB (Forwarding Information Base)`. If the source IP address is - unreachable through any interface, validation fails. - * ``disable``: No source IP address validation is performed. All incoming - packets are accepted. - - :rfc:`3704` recommends enabling ``strict`` mode to prevent IP spoofing, such as - DDoS attacks. For asymmetric or other complex routing scenarios, use ``loose`` - mode. - -********* -Operation -********* - -.. opcmd:: show interfaces sstpc <interface> - - Show detailed information about the specified interface. - - .. code-block:: none - - vyos@vyos:~$ show interfaces sstpc sstpc10 - sstpc10: <POINTOPOINT,MULTICAST,NOARP,UP,LOWER_UP> mtu 1500 qdisc pfifo_fast state UNKNOWN group default qlen 3 - link/ppp - inet 192.0.2.5 peer 192.0.2.254/32 scope global sstpc10 - valid_lft forever preferred_lft forever - inet6 fe80::fd53:c7ff:fe8b:144f/64 scope link - valid_lft forever preferred_lft forever - - RX: bytes packets errors dropped overrun mcast - 215 9 0 0 0 0 - TX: bytes packets errors dropped carrier collisions - 539 14 0 0 0 0 - - -Connect/disconnect -================== - -.. opcmd:: disconnect interface <interface> - - Disconnect the specified interface. - -.. opcmd:: connect interface <interface> - - Initiate a session on the specified interface. diff --git a/docs/configuration/interfaces/rst-tunnel.rst b/docs/configuration/interfaces/rst-tunnel.rst deleted file mode 100644 index f1376cdf..00000000 --- a/docs/configuration/interfaces/rst-tunnel.rst +++ /dev/null @@ -1,308 +0,0 @@ -:lastproofread: 2026-01-23 - -.. _tunnel-interface: - -###### -Tunnel -###### - -Tunnel interfaces are virtual links that transmit encapsulated traffic between -private networks or hosts across public infrastructure, such as the Internet. -They operate using encapsulation protocols to wrap original traffic for -transport. The supported protocols include :abbr:`GRE (Generic Routing -Encapsulation)`, IPIP, IPIP6, IP6IP6, and 6in4 (SIT). - -While :abbr:`GRE (Generic Routing Encapsulation)` is often the preferred -one-size-fits-all solution due to its versatility, other encapsulation -protocols may be better suited for specific use cases. - -VyOS uses a single tunnel interface type for all of these protocols. There are -no separate :abbr:`GRE (Generic Routing Encapsulation)`, IPIP, or IP6IP6 -interface types; instead, the desired encapsulation protocol is selected within -the ``set interfaces tunnel`` configuration. - -Configuration options for each protocol are described below. - -.. warning:: Do not change the encapsulation type for already configured tunnel - interfaces, as this may break their dependent configurations. - -Common interface configuration ------------------------------- - -.. cmdinclude:: /_include/interface-address.txt - :var0: tunnel - :var1: tun0 - -.. cmdinclude:: /_include/interface-common-without-mac.txt - :var0: tunnel - :var1: tun0 - -IPIP ----- - -IPIP is a straightforward encapsulation protocol defined in RFC 2003. It -encapsulates one IPv4 packet inside another IPv4 packet. - -Tunnels with IPIP encapsulation do not have protocol-specific configuration -options except for explicitly defining the encapsulation type as IPIP (see -the example below). - -Example: - -.. code-block:: none - - set interfaces tunnel tun0 encapsulation ipip - set interfaces tunnel tun0 source-address 192.0.2.10 - set interfaces tunnel tun0 remote 203.0.113.20 - set interfaces tunnel tun0 address 192.168.100.200/24 - -IP6IP6 ------- - -IP6IP6 is the IPv6 counterpart to IPIP. It encapsulates one IPv6 packet inside -another IPv6 packet. - -Similar to their IPIP counterparts, tunnels with IP6IP6 encapsulation do not -have protocol-specific configuration options except for explicitly defining -the encapsulation type as IP6IP6. - -Example: - -.. code-block:: none - - set interfaces tunnel tun0 encapsulation ip6ip6 - set interfaces tunnel tun0 source-address 2001:db8:aa::1 - set interfaces tunnel tun0 remote 2001:db8:aa::2 - set interfaces tunnel tun0 address 2001:db8:bb::1/64 - -IPIP6 ------ - -IPIP6 is an encapsulation protocol that wraps IPv4 packets inside IPv6 packets. - -Similar to IPIP and IP6IP6, protocol-specific configuration for tunnels with -IPIP6 encapsulation only requires defining the encapsulation type as IP6IP6. - -Example: - -.. code-block:: none - - set interfaces tunnel tun0 encapsulation ipip6 - set interfaces tunnel tun0 source-address 2001:db8:aa::1 - set interfaces tunnel tun0 remote 2001:db8:aa::2 - set interfaces tunnel tun0 address 192.168.70.80/24 - -6in4 (SIT) ----------- - -6in4, also known as :abbr:`SIT (Simple Internet Transition)`, is an -encapsulation protocol defined in :rfc:`4213` that wraps IPv6 packets -inside IPv4 packets. The encapsulating IPv4 headers use IP protocol number 41, -which is reserved exclusively for IPv6 encapsulation. - -The encapsulation process adds a 20-byte IPv4 header to each IPv6 packet. -Consequently, 6in4 tunnel interfaces can transmit IPv6 packets up to 1480 bytes -over an underlying network with a standard MTU of 1500 bytes without -fragmentation. - -6in4 tunnel interfaces are frequently used by IPv6 tunnel brokers (such as -`Hurricane Electric`_) to connect isolated IPv6 networks or individual hosts to -the IPv6 internet. - -Example: - -.. code-block:: none - - set interfaces tunnel tun0 encapsulation sit - set interfaces tunnel tun0 source-address 192.0.2.10 - set interfaces tunnel tun0 remote 192.0.2.20 - set interfaces tunnel tun0 address 2001:db8:bb::1/64 - -.. seealso:: For a practical configuration example, see the - :ref:`Tunnelbroker.net (IPv6) <examples-tunnelbroker-ipv6>` section. - -Generic Routing Encapsulation (GRE) ------------------------------------ - -:abbr:`GRE (Generic Routing Encapsulation)` is a versatile encapsulation -protocol defined in RFC 2784. Unlike simpler protocols such as IPIP, it allows -both IPv4 and IPv6 to be transported through the same tunnel. - -:abbr:`GRE (Generic Routing Encapsulation)` encapsulates original data packets -by adding a :abbr:`GRE (Generic Routing Encapsulation)` header, followed by an -IP header (the delivery header). The delivery header uses IP protocol number 47 -to identify :abbr:`GRE (Generic Routing Encapsulation)`-encapsulated traffic. - -In VyOS, :abbr:`GRE (Generic Routing Encapsulation)` tunnels can be established -over both IPv4 (encapsulation ``gre``) and IPv6 (encapsulation ``ip6gre``) -transport networks. - - -Configuration -^^^^^^^^^^^^^ - -To configure a :abbr:`GRE (Generic Routing Encapsulation)` tunnel, you need to -define a tunnel source IP address, a tunnel destination IP address, an -encapsulation type (:abbr:`GRE (Generic Routing Encapsulation)`), and a tunnel -interface IP address. - -Example: - -The following example shows how to configure an IPv4/IPv6-over-IPv6 :abbr:`GRE -(Generic Routing Encapsulation)` tunnel between a VyOS router and a Linux host -running ``systemd-networkd``. - -**VyOS router:** - -.. code-block:: none - - set interfaces tunnel tun101 address '2001:db8:feed:beef::1/126' - set interfaces tunnel tun101 address '192.168.5.1/30' - set interfaces tunnel tun101 encapsulation 'ip6gre' - set interfaces tunnel tun101 source-address '2001:db8:babe:face::3afe:3' - set interfaces tunnel tun101 remote '2001:db8:9bb:3ce::5' - -**Linux** ``systemd-networkd``: - -The ``systemd-networkd`` setup requires two configuration files: ``xxx.netdev`` -to create the :abbr:`GRE (Generic Routing Encapsulation)` tunnel interface, and -``xxx.network`` to assign IP addresses to it. - -.. code-block:: none - - # cat /etc/systemd/network/gre-example.netdev - [NetDev] - Name=gre-example - Kind=ip6gre - MTUBytes=14180 - - [Tunnel] - Remote=2001:db8:babe:face::3afe:3 - - - # cat /etc/systemd/network/gre-example.network - [Match] - Name=gre-example - - [Network] - Address=2001:db8:feed:beef::2/126 - - [Address] - Address=192.168.5.2/30 - -GRE keys -^^^^^^^^ - -A GRE key is an optional 32-bit field in the GRE header that allows multiple -GRE tunnels to operate between the same source and destination endpoints. When -a packet arrives, the receiver checks the GRE key to determine which tunnel -interface should process it. - -Although it may sound security-related, the GRE key is only an identifier and -provides no encryption or data protection. - -Example: - -.. code-block:: none - - set interfaces tunnel tun0 source-address 192.0.2.10 - set interfaces tunnel tun0 remote 192.0.2.20 - set interfaces tunnel tun0 address 10.40.50.60/24 - set interfaces tunnel tun0 parameters ip key 10 - -.. code-block:: none - - set interfaces tunnel tun1 source-address 192.0.2.10 - set interfaces tunnel tun1 remote 192.0.2.20 - set interfaces tunnel tun1 address 172.16.17.18/24 - set interfaces tunnel tun1 parameters ip key 20 - -GRETAP -^^^^^^^ - -Unlike GRE, which encapsulates only Layer 3 (IP) traffic, GRETAP encapsulates -Layer 2 (Ethernet) frames. - -That means that GRETAP tunnel interfaces can be members of a bridge interface. -This allows two geographically distant sites to connect as if they were on the -same LAN. - -GRETAP tunnels can be established over both IPv4 and IPv6 transport networks. - -Example: - -.. code-block:: none - - set interfaces bridge br0 member interface eth0 - set interfaces bridge br0 member interface tun0 - set interfaces tunnel tun0 encapsulation gretap - set interfaces tunnel tun0 source-address 198.51.100.2 - set interfaces tunnel tun0 remote 203.0.113.10 - - -Troubleshooting -^^^^^^^^^^^^^^^ - -GRE is a standardized tunneling protocol used in many network environments. - -Although the GRE tunnel setup is straightforward, connectivity failures -frequently occur because ACLs or firewall rules block IP protocol 47 or -prevent direct communication between the tunnel endpoints. - -If your GRE tunnel fails to establish, perform these diagnostic steps: - -1. Verify that the remote peer is reachable from the configured -``source-address``. - -This ensures that the underlying physical path between the two endpoints is -functional. - -.. code-block:: none - - vyos@vyos:~$ ping 203.0.113.10 interface 198.51.100.2 count 4 - PING 203.0.113.10 (203.0.113.10) from 198.51.100.2 : 56(84) bytes of data. - 64 bytes from 203.0.113.10: icmp_seq=1 ttl=254 time=0.807 ms - 64 bytes from 203.0.113.10: icmp_seq=2 ttl=254 time=1.50 ms - 64 bytes from 203.0.113.10: icmp_seq=3 ttl=254 time=0.624 ms - 64 bytes from 203.0.113.10: icmp_seq=4 ttl=254 time=1.41 ms - - --- 203.0.113.10 ping statistics --- - 4 packets transmitted, 4 received, 0% packet loss, time 3007ms - rtt min/avg/max/mdev = 0.624/1.087/1.509/0.381 ms - -2. Verify that the tunnel interface is correctly configured (with the link type -set to GRE) and is actively processing traffic. - -.. code-block:: none - - vyos@vyos:~$ show interfaces tunnel tun100 - tun100@NONE: <POINTOPOINT,NOARP,UP,LOWER_UP> mtu 1476 qdisc noqueue state UNKNOWN group default qlen 1000 - link/gre 198.51.100.2 peer 203.0.113.10 - inet 10.0.0.1/30 brd 10.0.0.3 scope global tun100 - valid_lft forever preferred_lft forever - inet6 fe80::5efe:c612:2/64 scope link - valid_lft forever preferred_lft forever - - RX: bytes packets errors dropped overrun mcast - 2183 27 0 0 0 0 - TX: bytes packets errors dropped carrier collisions - 836 9 0 0 0 0 - -3. Test the connection through the tunnel using the private IP addresses -assigned to each tunnel endpoint. - -.. code-block:: none - - vyos@vyos:~$ ping 10.0.0.2 interface 10.0.0.1 count 4 - PING 10.0.0.2 (10.0.0.2) from 10.0.0.1 : 56(84) bytes of data. - 64 bytes from 10.0.0.2: icmp_seq=1 ttl=255 time=1.05 ms - 64 bytes from 10.0.0.2: icmp_seq=2 ttl=255 time=1.88 ms - 64 bytes from 10.0.0.2: icmp_seq=3 ttl=255 time=1.98 ms - 64 bytes from 10.0.0.2: icmp_seq=4 ttl=255 time=1.98 ms - - --- 10.0.0.2 ping statistics --- - 4 packets transmitted, 4 received, 0% packet loss, time 3008ms - rtt min/avg/max/mdev = 1.055/1.729/1.989/0.395 ms - -.. _`other proposals`: https://www.isc.org/othersoftware/ -.. _`Hurricane Electric`: https://tunnelbroker.net/ diff --git a/docs/configuration/interfaces/rst-virtual-ethernet.rst b/docs/configuration/interfaces/rst-virtual-ethernet.rst deleted file mode 100644 index 5df7e962..00000000 --- a/docs/configuration/interfaces/rst-virtual-ethernet.rst +++ /dev/null @@ -1,117 +0,0 @@ -:lastproofread: 2026-01-26 - -.. _virtual-ethernet: - -################ -Virtual Ethernet -################ - -Virtual Ethernet (veth) interfaces are software-based interfaces that operate -in pairs, creating a tunnel between each other. Traffic transmitted into one -interface of the pair (e.g., ``veth0``) is delivered directly to its peer -interface (e.g., ``veth1``). - -Veth interfaces are commonly used to connect network namespaces or VRFs, but -they can also function as standalone virtual network interfaces. - -.. note:: Veth interfaces must be created in pairs, where each interface acts - as the peer of the other. - -************* -Configuration -************* - -Common interface configuration -============================== - -.. cmdinclude:: /_include/interface-address-with-dhcp.txt - :var0: virtual-ethernet - :var1: veth0 - -.. cmdinclude:: /_include/interface-description.txt - :var0: virtual-ethernet - :var1: veth0 - -VLAN -==== - -Regular VLANs (802.1q) ----------------------- -.. cmdinclude:: /_include/interface-vlan-8021q.txt - :var0: virtual-ethernet - :var1: veth0 - -802.1ad (QinQ) --------------- - -.. cmdinclude:: /_include/interface-vlan-8021ad.txt - :var0: virtual-ethernet - :var1: veth0 - -.. cmdinclude:: /_include/interface-disable.txt - :var0: virtual-ethernet - :var1: veth0 - -.. cmdinclude:: /_include/interface-vrf.txt - :var0: virtual-ethernet - :var1: veth0 - -********* -Operation -********* - -.. opcmd:: show interfaces virtual-ethernet - - Show brief interface information. - - .. code-block:: none - - vyos@vyos:~$ show interfaces virtual-ethernet - Codes: S - State, L - Link, u - Up, D - Down, A - Admin Down - Interface IP Address S/L Description - --------- ---------- --- ----------- - veth10 100.64.0.0/31 u/u - veth11 100.64.0.1/31 u/u - -.. opcmd:: show interfaces virtual-ethernet <interface> - - Show detailed interface information. - - .. code-block:: none - - vyos@vyos:~$ show interfaces virtual-ethernet veth11 - 10: veth11@veth10: <BROADCAST,MULTICAST,UP,LOWER_UP> mtu 1500 qdisc noqueue master red state UP group default qlen 1000 - link/ether b2:7b:df:47:e9:11 brd ff:ff:ff:ff:ff:ff - inet 100.64.0.1/31 scope global veth11 - valid_lft forever preferred_lft forever - inet6 fe80::b07b:dfff:fe47:e911/64 scope link - valid_lft forever preferred_lft forever - - - RX: bytes packets errors dropped overrun mcast - 0 0 0 0 0 0 - TX: bytes packets errors dropped carrier collisions - 1369707 4267 0 0 0 0 - -******* -Example -******* - -The following example shows how to connect the global VRF to VRF ‘red ‘ using -the ``veth10`` and ``veth11`` veth pair. - -.. code-block:: none - - set interfaces virtual-ethernet veth10 address '100.64.0.0/31' - set interfaces virtual-ethernet veth10 peer-name 'veth11' - set interfaces virtual-ethernet veth11 address '100.64.0.1/31' - set interfaces virtual-ethernet veth11 peer-name 'veth10' - set interfaces virtual-ethernet veth11 vrf 'red' - set vrf name red table '1000' - - vyos@vyos:~$ ping 100.64.0.1 - PING 100.64.0.1 (100.64.0.1) 56(84) bytes of data. - 64 bytes from 100.64.0.1: icmp_seq=1 ttl=64 time=0.080 ms - 64 bytes from 100.64.0.1: icmp_seq=2 ttl=64 time=0.119 ms - - diff --git a/docs/configuration/interfaces/rst-vti.rst b/docs/configuration/interfaces/rst-vti.rst deleted file mode 100644 index e45c17d9..00000000 --- a/docs/configuration/interfaces/rst-vti.rst +++ /dev/null @@ -1,115 +0,0 @@ -.. _vti-interface: - -############################## -VTI (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" - -Resulting configuration: - -.. code-block:: none - - vyos@vyos# show interfaces vti - vti vti0 { - address 192.168.2.249/30 - address 2001:db8:2::249/64 - description "Description" - } - -.. 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 - -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 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/rst-vxlan.rst b/docs/configuration/interfaces/rst-vxlan.rst deleted file mode 100644 index 0d357e9b..00000000 --- a/docs/configuration/interfaces/rst-vxlan.rst +++ /dev/null @@ -1,358 +0,0 @@ -:lastproofread: 2026-03-16 - -.. _vxlan-interface: - -##### -VXLAN -##### - -:abbr:`VXLAN (Virtual Extensible LAN)` is a network virtualization technology -that addresses scalability challenges in large cloud computing environments. -It encapsulates Ethernet frames (Layer 2) within UDP datagrams (Layer 4), which -are then transmitted via UDP port 4789, as assigned by IANA. VXLAN endpoints, -called :abbr:`VTEPs (VXLAN tunnel endpoints)`, terminate VXLAN tunnels and can -be either virtual or physical switch ports. - -VXLAN supports up to 16 million logical networks and enables Layer 2 adjacency -across Layer 3 IP networks. It uses multicast or unicast with head-end -replication (HER) to flood broadcast, unknown unicast, and multicast (BUM) -traffic. - -The VXLAN specification was initially developed by VMware, Arista Networks, and -Cisco. Other supporters include Huawei, Broadcom, Citrix, Pica8, Big Switch -Networks, Cumulus Networks, Dell EMC, Ericsson, Mellanox, FreeBSD, OpenBSD, Red -Hat, Joyent, and Juniper Networks. - -VXLAN is officially documented by the IETF in :rfc:`7348`. - -When configuring VXLAN in a VyOS virtual machine, ensure that MAC spoofing -(Hyper-V) or Forged Transmits (ESX) are permitted. Otherwise, the hypervisor -may block forwarded frames. - -.. note:: Although the IANA-assigned VXLAN port is **4789**, VyOS uses the - Linux default UDP port **8472** for VXLAN interfaces. To ensure compatibility - with other vendors, set the port to the IANA standard **4789**. - -Configuration -============= - -Common interface configuration ------------------------------- - -.. cmdinclude:: /_include/interface-common-without-dhcp.txt - :var0: vxlan - :var1: vxlan0 - -VXLAN-specific options ------------------------ - -.. cfgcmd:: set interfaces vxlan <interface> vni <number> - - **Configure a** :abbr:`VNI (VXLAN Network Identifier)` **for the VXLAN - interface.** - - Each VXLAN segment is identified by this 24-bit VNI, allowing up to 16 million - segments to coexist within the same administrative domain. - -.. cfgcmd:: set interfaces vxlan <interface> port <port> - - Configure the UDP port of the remote VXLAN endpoint. - - .. note:: Although the IANA-assigned VXLAN port is **4789**, VyOS uses the - Linux default UDP port **8472** for VXLAN interfaces. - -.. cfgcmd:: set interfaces vxlan <interface> source-address <address> - - Configure the source IP address for the VXLAN underlay. - - .. warning:: This setting is mandatory when deploying VXLAN via L2VPN/EVPN. - -.. cfgcmd:: set interfaces vxlan <interface> gpe - - **Enable the** :abbr:`GPE (Generic Protocol Extension)` **for the VXLAN - interface.** - - To use this feature, you must configure the interface with the ``external`` - parameter. - -.. cfgcmd:: set interfaces vxlan <interface> parameters external - - **Configure the VXLAN interface to use an external control plane, such as BGP - L2VPN/EVPN, for remote endpoint discovery.** - - If not configured, the internal :abbr:`FDB (Forwarding Database)` is used. - -.. cfgcmd:: set interfaces vxlan <interface> parameters neighbor-suppress - - **Enable ARP and ND suppression on the VXLAN interface.** - - This reduces ARP and ND message flooding across the VXLAN network. As defined - in :rfc:`7432#section-10`, participating VTEPs use known MAC-to-IP bindings - to reply to local requests on behalf of remote hosts. - -.. cfgcmd:: set interfaces vxlan <interface> parameters nolearning - - Disable :abbr:`SLLA (Source Link-Layer Address)` and IP address learning on - the VXLAN interface. - -.. cfgcmd:: set interfaces vxlan <interface> parameters vni-filter - - **Enable** :abbr:`VNI (VXLAN Network Identifier)` **filtering on the VXLAN - interface.** - - When enabled, the interface only receives packets with VNIs configured in its - VNI filtering table. - - .. note:: VNI filtering works only if the interface is configured with the - ``external`` parameter. - -Unicast -^^^^^^^ - -.. cfgcmd:: set interfaces vxlan <interface> remote <address> - - **Configure the IPv4 or IPv6 address of the remote VTEP.** - - Unlike multicast setups, this command allows you to directly configure the - remote IPv4 or IPv6 address. - -Multicast -^^^^^^^^^ - -.. cfgcmd:: set interfaces vxlan <interface> source-interface <interface> - - **Configure the source interface for the VXLAN underlay.** - - All VXLAN traffic is sent and received through the specified interface. - - This setting is mandatory when deploying VXLAN over a multicast network. - -.. cfgcmd:: set interfaces vxlan <interface> group <address> - - **Configure the IPv4 or IPv6 multicast group address for the VXLAN interface.** - - VXLAN tunnels can be built using either multicast group or unicast IP addresses. - -Multicast VXLAN -=============== - -Topology: PC4 - Leaf2 - Spine1 - Leaf3 - PC5 - -PC4 uses the IP address ``10.0.0.4/24``, and PC5 uses the IP address -``10.0.0.5/24``. Both devices assume they reside within the same broadcast -domain. - -Assume PC4 on Leaf2 pings PC5 on Leaf3. Rather than manually specifying Leaf3 -as the remote endpoint, Leaf2 encapsulates the packet into a UDP datagram and -sends it to the designated multicast address via Spine1. Spine1 forwards the -packet to all leaves in the same multicast group, including Leaf3. Upon -receiving the datagram, Leaf3 forwards it to PC5 and learns that PC4 is -reachable through Leaf2 by inspecting the source IP in the encapsulated -datagram. - -PC5 receives the ping and responds with an echo reply. Leaf3, now aware of -PC4's location, forwards the reply directly to Leaf2's unicast address. Upon -receiving the echo reply, Leaf2 learns that PC5 is reachable through Leaf3. - -After this discovery, subsequent traffic between PC4 and PC5 will not use the -multicast address between the leaves, as both leaves have learned the PCs' -locations. This reduces multicast traffic and network load, improving -scalability as more leaves are added. - -Single VXLAN device (SVD) -========================= - -In VyOS, you can configure multiple **VLAN-to-VNI mappings** for EVPN-VXLAN on -a single container interface, known as a single VXLAN device (SVD). This -enables significant VNI scaling because a separate VXLAN interface is not -required for each VNI. - -.. cfgcmd:: set interfaces vxlan <interface> vlan-to-vni <vlan> vni <vni> - - **Map a VLAN ID to a VNI on the specified VXLAN interface.** - - The VXLAN interface can be added to a bridge. - - The following example shows an SVD configuration with multiple VLAN-to-VNI - mappings. - - .. code-block:: none - - set interfaces bridge br0 member interface vxlan0 - set interfaces vxlan vxlan0 parameters external - set interfaces vxlan vxlan0 source-interface 'dum0' - set interfaces vxlan vxlan0 vlan-to-vni 10 vni '10010' - set interfaces vxlan vxlan0 vlan-to-vni 11 vni '10011' - set interfaces vxlan vxlan0 vlan-to-vni 30 vni '10030' - set interfaces vxlan vxlan0 vlan-to-vni 31 vni '10031' - -Example -------- - -The following example demonstrates a multicast VXLAN deployment. - -The setup includes three routers: Spine1, a Cisco IOS router, and Leaf2 and -Leaf3, which are VyOS routers. - -**Topology:** Leaf2 - Spine1 - Leaf3. - -The topology is built using GNS3. - -.. code-block:: none - - Spine1: - fa0/2 towards Leaf2, IP-address: 10.1.2.1/24 - fa0/3 towards Leaf3, IP-address: 10.1.3.1/24 - - Leaf2: - Eth0 towards Spine1, IP-address: 10.1.2.2/24 - Eth1 towards a VLAN-aware switch - - Leaf3: - Eth0 towards Spine1, IP-address 10.1.3.3/24 - Eth1 towards a VLAN-aware switch - -**Spine1 configuration:** - -.. code-block:: none - - conf t - ip multicast-routing - ! - interface fastethernet0/2 - ip address 10.1.2.1 255.255.255.0 - ip pim sparse-dense-mode - ! - interface fastethernet0/3 - ip address 10.1.3.1 255.255.255.0 - ip pim sparse-dense-mode - ! - router ospf 1 - network 10.0.0.0 0.255.255.255 area 0 - -Multicast routing is required for scalable traffic forwarding between leaves. -:abbr:`PIM (Protocol Independent Multicast)` must be enabled towards the leaves -so the spine can learn from which multicast groups each leaf expects traffic. - -**Leaf2 configuration:** - -.. code-block:: none - - set interfaces ethernet eth0 address '10.1.2.2/24' - set protocols ospf area 0 network '10.0.0.0/8' - - ! First VXLAN interface - set interfaces bridge br241 address '172.16.241.1/24' - set interfaces bridge br241 member interface 'eth1.241' - set interfaces bridge br241 member interface 'vxlan241' - - set interfaces vxlan vxlan241 group '239.0.0.241' - set interfaces vxlan vxlan241 source-interface 'eth0' - set interfaces vxlan vxlan241 vni '241' - - ! Second VXLAN interface - set interfaces bridge br242 address '172.16.242.1/24' - set interfaces bridge br242 member interface 'eth1.242' - set interfaces bridge br242 member interface 'vxlan242' - - set interfaces vxlan vxlan242 group '239.0.0.242' - set interfaces vxlan vxlan242 source-interface 'eth0' - set interfaces vxlan vxlan242 vni '242' - -**Leaf3 configuration:** - -.. code-block:: none - - set interfaces ethernet eth0 address '10.1.3.3/24' - set protocols ospf area 0 network '10.0.0.0/8' - - ! First VXLAN interface - set interfaces bridge br241 address '172.16.241.1/24' - set interfaces bridge br241 member interface 'eth1.241' - set interfaces bridge br241 member interface 'vxlan241' - - set interfaces vxlan vxlan241 group '239.0.0.241' - set interfaces vxlan vxlan241 source-interface 'eth0' - set interfaces vxlan vxlan241 vni '241' - - ! Second VXLAN interface - set interfaces bridge br242 address '172.16.242.1/24' - set interfaces bridge br242 member interface 'eth1.242' - set interfaces bridge br242 member interface 'vxlan242' - - set interfaces vxlan vxlan242 group '239.0.0.242' - set interfaces vxlan vxlan242 source-interface 'eth0' - set interfaces vxlan vxlan242 vni '242' - -The configurations for Leaf2 and Leaf3 are nearly identical. Detailed -explanations for each command are provided below. - -.. code-block:: none - - set interfaces bridge br241 address '172.16.241.1/24' - -This command creates a bridge to bind traffic on ``eth1`` VLAN 241 with the -``vxlan241`` interface. The IP address is optional. If configured, it can serve -as the default gateway for each leaf, allowing devices on the VLAN to reach -other subnets. Subnets must be redistributed by :abbr:`OSPF (Open Shortest Path -First)` so the spine can learn how to reach them. To advertise ``172.16/12`` -networks, change the :abbr:`OSPF (Open Shortest Path First)` network from -``10.0.0.0/8`` to ``0.0.0.0/0``. - -.. code-block:: none - - set interfaces bridge br241 member interface 'eth1.241' - set interfaces bridge br241 member interface 'vxlan241' - -These commands bind ``eth1.241`` and ``vxlan241`` as member interfaces of the -same bridge. - -.. code-block:: none - - set interfaces vxlan vxlan241 group '239.0.0.241' - -This command configures the multicast group used by all leaves for this VLAN -extension. It must be the same on all leaves that have this interface. - -.. code-block:: none - - set interfaces vxlan vxlan241 source-interface 'eth0' - -This command configures the interface that listens for multicast packets. It -can also be a loopback interface. - -.. code-block:: none - - set interfaces vxlan vxlan241 vni '241' - -This command configures the unique ID for the VXLAN interface. - -.. code-block:: none - - set interfaces vxlan vxlan241 port 12345 - -VyOS uses the Linux default UDP port **8472** for VXLAN interfaces. This -command allows you to configure a different UDP port. - -Unicast VXLAN -============= - -As an alternative to multicast, you can configure the VXLAN tunnel by -specifying the remote IPv4 address directly. The following updates the previous -multicast example: - -.. code-block:: none - - # leaf2 and leaf3 - delete interfaces vxlan vxlan241 group '239.0.0.241' - delete interfaces vxlan vxlan241 source-interface 'eth0' - - # leaf2 - set interfaces vxlan vxlan241 remote 10.1.3.3 - - # leaf3 - set interfaces vxlan vxlan241 remote 10.1.2.2 - -The default UDP port is 8472. To configure a different port, use ``set -interfaces vxlan <vxlanN> port <port>``. - diff --git a/docs/configuration/interfaces/rst-wireguard.rst b/docs/configuration/interfaces/rst-wireguard.rst deleted file mode 100644 index bc53b388..00000000 --- a/docs/configuration/interfaces/rst-wireguard.rst +++ /dev/null @@ -1,439 +0,0 @@ -:lastproofread: 2026-03-02 - -.. _wireguard: - -######### -WireGuard -######### - -WireGuard is an extremely simple, fast, and modern VPN that utilizes -state-of-the-art cryptography. See https://www.wireguard.com for more -information. - -**************** -Site-to-site VPN -**************** - -The following diagram illustrates a site-to-site VPN setup. - -.. figure:: /_static/images/wireguard_site2site_diagram.* - -******** -Keypairs -******** - -WireGuard requires a keypair, which includes a **private** key -to decrypt incoming traffic, and a **public** key for peer(s) to encrypt -outgoing traffic. - -Generate keypair -================ - -.. opcmd:: generate pki wireguard key-pair - - Generate a keypair: a public and a private key. - - .. note:: This command only outputs the keys to your console. It - neither stores them in the system nor applies them to the system - configuration. - - - .. code-block:: none - - vyos@vyos:~$ generate pki wireguard key-pair - Private key: iJJyEARGK52Ls1GYRCcFvPuTj7WyWYDo//BknoDU0XY= - Public key: EKY0dxRrSD98QHjfHOK13mZ5PJ7hnddRZt5woB3szyw= - -.. opcmd:: generate pki wireguard key-pair install interface <interface> - - Generate a keypair and output the private key assignment command for the - specified interface. - - .. code-block:: none - - vyos@vyos:~$ generate pki wireguard key-pair install interface wg10 - "generate" CLI command executed from operational level. - Generated private key is not automatically added to the VyOS configuration, use the following configuration mode commands to install key: - - set interfaces wireguard wg10 private-key '4Krkv8h6NkAYMMaBWI957yYDJDMvj9URTHstdlOcDU0=' - - Corresponding public-key to use on peer system is: 'UxDsYT6EnpTIOKUzvMlw2p0sNOKQvFxEdSVrnNrX1Ro=' - - .. note:: If you invoke this command from configuration mode with - the ``run`` prefix, the generated private key is automatically - assigned to the specified interface. - - .. code-block:: none - - vyos@vyos# run generate pki wireguard key-pair install interface wg10 - "generate" CLI command executed from config session. - Generated private-key was imported to CLI! - - Use the following command to verify: show interfaces wireguard wg10 - Corresponding public-key to use on peer system is: '7d9KwabjLhHpJiEJeIGd0CBlao/eTwFOh6xyCovTfG8=' - - vyos@vyos# compare - [edit interfaces] - +wireguard wg10 { - + private-key CJweb8FC6BU3Loj4PC2pn5V82cDjIPs7G1saW0ZfLWc= - +} - -.. opcmd:: show interfaces wireguard <interface> public-key - - Show the public key assigned to the interface. - - .. code-block:: none - - vyos@vyos:~$ show interfaces wireguard wg01 public-key - EKY0dxRrSD98QHjfHOK13mZ5PJ7hnddRZt5woB3szyw= - - -Optional --------- - -.. opcmd:: generate pki wireguard preshared-key - - Generate a pre-shared key. - - The pre-shared key is optional. It adds an additional layer of symmetric-key - cryptography on top of the asymmetric cryptography. - - .. code-block:: none - - vyos@vyos:~$ generate pki wireguard preshared-key - Pre-shared key: OHH2EwZfMNK+1L6BXbYw3bKCtMrfjpR4mCAEeBlFnRs= - - -.. stop_vyoslinter - -.. opcmd:: generate pki wireguard preshared-key install interface <interface> peer <peer> - - Generate a pre-shared key and output the key assignment command for - the specified peer. - - .. code-block:: none - - vyos@vyos:~$ generate pki wireguard preshared-key install interface wg10 peer foo - "generate" CLI command executed from operational level. - Generated preshared-key is not stored to CLI, use configure mode commands to install key: - - set interfaces wireguard wg10 peer foo preshared-key '32vQ1w1yFKTna8n7Gu7EimubSe2Y63m8bafz55EG3Ro=' - - Pre-shared key: +LuaZ8W6DjsDFJFX3jJzoNqrsXHhvq08JztM9z8LHCs= - - - .. note:: If you invoke this command from configuration mode with - the run prefix, the generated key is automatically assigned to - the specified peer. - -.. start_vyoslinter - - -*********************** -Interface configuration -*********************** - -The next step is to configure your local WireGuard interface and define the -networks you want to tunnel (``allowed-ips``). - -If your system only initiates connections, specifying the listen port is -optional. If your system accepts incoming connections, you must define a port -for peers to connect to. Otherwise, WireGuard selects a random port at each -reboot, and that may break your peers' ability to connect if that port -is not enabled in your firewall rules. - -To configure a WireGuard tunnel, you also need your peer's public key. - -.. note:: The public key specified in the peer configuration block is always - the **remote** peer's public key, never your local one. - -**Local side configuration** - -The local side is configured with the following parameters: - -* Local WireGuard interface IP: ``10.1.0.1/30`` -* Local listen port: ``51820`` -* Remote peer name: ``to-wg02`` -* Remote peer endpoint: ``192.0.2.1`` on port ``51820`` -* Remote peer public key: ``XMrlPykaxhdAAiSjhtPlvi30NVkvLQliQuKP7AI7CyI=`` -* Allowed networks: ``192.168.2.0/24`` - -.. code-block:: none - - set interfaces wireguard wg01 address '10.1.0.1/30' - set interfaces wireguard wg01 description 'VPN-to-wg02' - set interfaces wireguard wg01 peer to-wg02 allowed-ips '192.168.2.0/24' - set interfaces wireguard wg01 peer to-wg02 address '192.0.2.1' - set interfaces wireguard wg01 peer to-wg02 port '51820' - set interfaces wireguard wg01 peer to-wg02 public-key 'XMrlPykaxhdAAiSjhtPlvi30NVkvLQliQuKP7AI7CyI=' - set interfaces wireguard wg01 port '51820' - - set protocols static route 192.168.2.0/24 interface wg01 - -To send traffic destined for ``192.168.2.0/24`` through the WireGuard interface -(``wg01``), configure a static route. Multiple IP addresses or networks can be -defined and routed. The final check is performed against ``allowed-ips``, which -either permits or drops the traffic. - -.. warning:: You cannot assign the same ``allowed-ips`` to multiple WireGuard - peers. This is a strict design restriction. For more information, check the - `WireGuard mailing list`_. - - -.. cfgcmd:: set interfaces wireguard <interface> private-key <private-key> - - Assign a private key to the specified WireGuard interface. - - Example: - - .. code-block:: none - - set interfaces wireguard wg01 private-key 'iJJyEARGK52Ls1GYRCcFvPuTj7WyWYDo//BknoDU0XY=' - - - To generate a private key, use the following command: - :opcmd:`generate pki wireguard key-pair`. - - To view the public key assigned to the interface so you can share it with a - peer, use the following command: - :opcmd:`show interfaces wireguard wg01 public-key`. - -.. cmdinclude:: /_include/interface-per-client-thread.txt - :var0: wireguard - :var1: wg01 - -**Remote side configuration** - -.. code-block:: none - - set interfaces wireguard wg01 address '10.1.0.2/30' - set interfaces wireguard wg01 description 'VPN-to-wg01' - set interfaces wireguard wg01 peer to-wg01 allowed-ips '192.168.1.0/24' - set interfaces wireguard wg01 peer to-wg01 address '192.0.2.2' - set interfaces wireguard wg01 peer to-wg01 port '51820' - set interfaces wireguard wg01 peer to-wg01 public-key 'EKY0dxRrSD98QHjfHOK13mZ5PJ7hnddRZt5woB3szyw=' - set interfaces wireguard wg01 port '51820' - set interfaces wireguard wg01 private-key 'OLTQY3HuK5qWDgVs6fJR093SwPgOmCKkDI1+vJLGoFU=' - - set protocols static route 192.168.1.0/24 interface wg01 - -******************* -Firewall exceptions -******************* - -To allow WireGuard traffic through the WAN interface, create a firewall -exception: - -.. code-block:: none - - set firewall ipv4 name OUTSIDE_LOCAL rule 10 action accept - set firewall ipv4 name OUTSIDE_LOCAL rule 10 description 'Allow established/related' - set firewall ipv4 name OUTSIDE_LOCAL rule 10 state established enable - set firewall ipv4 name OUTSIDE_LOCAL rule 10 state related enable - set firewall ipv4 name OUTSIDE_LOCAL rule 20 action accept - set firewall ipv4 name OUTSIDE_LOCAL rule 20 description WireGuard_IN - set firewall ipv4 name OUTSIDE_LOCAL rule 20 destination port 51820 - set firewall ipv4 name OUTSIDE_LOCAL rule 20 log enable - set firewall ipv4 name OUTSIDE_LOCAL rule 20 protocol udp - -Ensure that the OUTSIDE_LOCAL firewall group is applied to the WAN interface -and in an input (local) direction. - -.. code-block:: none - - set firewall ipv4 input filter rule 10 action jump - set firewall ipv4 input filter rule 10 jump-target 'OUTSIDE_LOCAL' - set firewall ipv4 input filter rule 10 inbound-interface name 'eth0' - -Verify that your firewall rules permit traffic. If so, your WireGuard VPN -should be operational. - -.. code-block:: none - - wg01# ping 192.168.1.1 - PING 192.168.1.1 (192.168.1.1) 56(84) bytes of data. - 64 bytes from 192.168.1.1: icmp_seq=1 ttl=64 time=1.16 ms - 64 bytes from 192.168.1.1: icmp_seq=2 ttl=64 time=1.77 ms - - wg02# ping 192.168.2.1 - PING 192.168.2.1 (192.168.2.1) 56(84) bytes of data. - 64 bytes from 192.168.2.1: icmp_seq=1 ttl=64 time=4.40 ms - 64 bytes from 192.168.2.1: icmp_seq=2 ttl=64 time=1.02 ms - -An additional layer of symmetric-key cryptography can be used on top of the -asymmetric cryptography. This is optional. - -.. code-block:: none - - vyos@vyos:~$ generate pki wireguard preshared-key - Pre-shared key: rvVDOoc2IYEnV+k5p7TNAmHBMEGTHbPU8Qqg8c/sUqc= - -Copy the key, as it is not stored locally. Since it is a symmetric key, only -you and your peer should know its contents. Distribute the key securely. - -.. code-block:: none - - wg01# set interfaces wireguard wg01 peer to-wg02 preshared-key 'rvVDOoc2IYEnV+k5p7TNAmHBMEGTHbPU8Qqg8c/sUqc=' - wg02# set interfaces wireguard wg01 peer to-wg01 preshared-key 'rvVDOoc2IYEnV+k5p7TNAmHBMEGTHbPU8Qqg8c/sUqc=' - - -**************************** -Remote access (road warrior) -**************************** - -With WireGuard, a road warrior VPN configuration is similar to a site-to-site -VPN. It just omits the ``address`` and ``port`` statements. - -In the following example, the IP addresses for remote clients are defined -within each peer configuration. This allows peers to communicate with each -other. - -Additionally, this setup uses a ``persistent-keepalive`` flag set to 15 seconds -to keep the connection alive. This setting is mainly relevant if a peer is -behind NAT and cannot be reached if the connection is lost. For effectiveness, -the value should be lower than the UDP timeout. - -.. code-block:: none - - wireguard wg01 { - address 10.172.24.1/24 - address 2001:db8:470:22::1/64 - description RoadWarrior - peer MacBook { - allowed-ips 10.172.24.30/32 - allowed-ips 2001:db8:470:22::30/128 - persistent-keepalive 15 - pubkey F5MbW7ye7DsoxdOaixjdrudshjjxN5UdNV+pGFHqehc= - } - peer iPhone { - allowed-ips 10.172.24.20/32 - allowed-ips 2001:db8:470:22::20/128 - persistent-keepalive 15 - pubkey BknHcLFo8nOo8Dwq2CjaC/TedchKQ0ebxC7GYn7Al00= - } - port 2224 - private-key OLTQY3HuK5qWDgVs6fJR093SwPgOmCKkDI1+vJLGoFU= - } - -Below is the configuration for the iPhone peer. The ``AllowedIPs`` wildcard -setting directs all IPv4 and IPv6 traffic through the VPN connection. - -.. code-block:: none - - [Interface] - PrivateKey = ARAKLSDJsadlkfjasdfiowqeruriowqeuasdf= - Address = 10.172.24.20/24, 2001:db8:470:22::20/64 - DNS = 10.0.0.53, 10.0.0.54 - - [Peer] - PublicKey = RIbtUTCfgzNjnLNPQ/ulkGnnB2vMWHm7l2H/xUfbyjc= - AllowedIPs = 0.0.0.0/0, ::/0 - Endpoint = 192.0.2.1:2224 - PersistentKeepalive = 15 - -To enable split tunneling, specify the remote subnets. This ensures that only -traffic destined for the remote site is sent through the tunnel, while all -other traffic remains unaffected. - -.. code-block:: none - - [Interface] - PrivateKey = 8Iasdfweirousd1EVGUk5XsT+wYFZ9mhPnQhmjzaJE6Go= - Address = 10.172.24.30/24, 2001:db8:470:22::30/64 - - [Peer] - PublicKey = RIbtUTCfgzNjnLNPQ/ulkGnnB2vMWHm7l2H/xUfbyjc= - AllowedIPs = 10.172.24.30/24, 2001:db8:470:22::/64 - Endpoint = 192.0.2.1:2224 - PersistentKeepalive = 15 - - -******************** -Operational commands -******************** - -Status -====== - -.. opcmd:: show interfaces wireguard wg01 summary - - Show information about the WireGuard service, including the latest handshake. - - .. code-block:: none - - vyos@vyos:~$ show interfaces wireguard wg01 summary - interface: wg01 - public key: - private key: (hidden) - listening port: 51820 - - peer: <peer pubkey> - endpoint: <peer public IP> - allowed ips: 10.69.69.2/32 - latest handshake: 23 hours, 45 minutes, 26 seconds ago - transfer: 1.26 MiB received, 6.47 MiB sent - -.. opcmd:: show interfaces wireguard - - Show a list of all WireGuard interfaces. - - .. code-block:: none - - Codes: S - State, L - Link, u - Up, D - Down, A - Admin Down - Interface IP Address S/L Description - --------- ---------- --- ----------- - wg01 10.0.0.1/24 u/u - - -.. opcmd:: show interfaces wireguard <interface> - - Show general information about a specific WireGuard interface. - - .. code-block:: none - - vyos@vyos:~$ show interfaces wireguard wg01 - interface: wg01 - address: 10.0.0.1/24 - public key: h1HkYlSuHdJN6Qv4Hz4bBzjGg5WUty+U1L7DJsZy1iE= - private key: (hidden) - listening port: 41751 - - RX: bytes packets errors dropped overrun mcast - 0 0 0 0 0 0 - TX: bytes packets errors dropped carrier collisions - 0 0 0 0 0 0 - -************************************ -Remote access (road warrior) clients -************************************ - -Some users connect mobile devices to their VyOS router using WireGuard. To -simplify deployment, generate a per-mobile configuration from the VyOS CLI. - -.. warning:: From a security perspective, it is not recommended to let a third - party create and share the private key for a secure connection. You should - create the private portion yourself and hand out only the public key. - - -.. opcmd:: generate wireguard client-config <name> interface <interface> server - <ip|fqdn> address <client-ip> - - **Generate a client configuration file that establishes a connection to the - specified interface.** - - The public key from the specified interface is automatically included in the - configuration file. - - The command also generates a configuration snippet that can be copied - into the VyOS CLI. The ``<name>`` you provide will be used as the peer - name in the snippet. - - You must also specify the IP address or FQDN of the server the client - connects to. The address parameter can be used twice to assign both an - IPv4 (/32) and an IPv6 (/128) address to the client. - - .. figure:: /_static/images/wireguard_qrcode.* - :alt: WireGuard Client QR code - -.. _`WireGuard mailing list`: - https://lists.zx2c4.com/pipermail/wireguard/2018-December/003704.html diff --git a/docs/configuration/interfaces/rst-wireless.rst b/docs/configuration/interfaces/rst-wireless.rst deleted file mode 100644 index 728783b2..00000000 --- a/docs/configuration/interfaces/rst-wireless.rst +++ /dev/null @@ -1,931 +0,0 @@ -:lastproofread: 2026-03-23 - -.. _wireless-interface: - -#################### -Wireless LAN / Wi-Fi -#################### - -: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 - -* Station mode acts as a Wi-Fi client accessing the network through an available - WAP - -* Monitor mode lets the system passively monitor wireless traffic - -If the system detects an unconfigured wireless device, it will be automatically -added to the configuration tree, specifying any detected settings (for example, -its MAC address) and configured to run in monitor mode. - -************* -Configuration -************* - -Common interface configuration -============================== - -.. cmdinclude:: /_include/interface-common-with-dhcp.txt - :var0: wireless - :var1: wlan0 - -System-wide configuration -========================= - -.. 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 device is operating. This can limit available - channels and transmit power. - - .. note:: This option is mandatory in ``access-point`` mode. - -Wireless options -================ - -.. cfgcmd:: set interfaces wireless <interface> channel <number> - - 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 - - Send empty SSID in beacons and ignore probe request frames that do not specify - full SSID, i.e., require stations to know the SSID. - -.. cfgcmd:: set interfaces wireless <interface> expunge-failing-stations - - Disassociate stations based on excessive transmission failures or other - indications of connection loss. - - This depends on the driver capabilities and may not be available with all - drivers. - -.. cfgcmd:: set interfaces wireless <interface> isolate-stations - - Client isolation can be used to prevent low-level bridging of frames between - associated stations in the BSS. - - By default, this bridging is allowed. - -.. 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 - different association IDs, so this number should not be larger than that. - - This defaults to 2007. - -.. cfgcmd:: set interfaces wireless <interface> mgmt-frame-protection - - Management Frame Protection (MFP) according to IEEE 802.11w - - .. note:: :abbr:`MFP (Management Frame Protection)` is required for WPA3. - -.. cfgcmd:: set interfaces wireless <interface> enable-bf-protection - - Beacon Protection: management frame protection for Beacon frames. - - .. note:: This option requires :abbr:`MFP (Management Frame Protection)` - to be enabled. - -.. cfgcmd:: set interfaces wireless <interface> mode <a | b | g | n | ac | ax> - - Operation mode of wireless radio. - - * ``a`` - 802.11a - 54 Mbits/sec - * ``b`` - 802.11b - 11 Mbits/sec - * ``g`` - 802.11g - 54 Mbits/sec (default) - * ``n`` - 802.11n - 600 Mbits/sec - * ``ac`` - 802.11ac - 1300 Mbits/sec - * ``ax`` - 802.11ax - exceeds 1GBit/sec - - .. note:: In VyOS, 802.11ax is only implemented for 2.4GHz and 6GHz. - -.. cfgcmd:: set interfaces wireless <interface> physical-device <device> - - Wireless hardware device used as underlay radio. - - This defaults to phy0. - -.. cfgcmd:: set interfaces wireless <interface> reduce-transmit-power <number> - - Adds the Power Constraint information element to Beacon and Probe Response - frames. - - This option adds the Power Constraint information element when applicable - and the Country information element is configured. The Power Constraint - element is required by Transmit Power Control. - - Valid values are 0..255. - -.. cfgcmd:: set interfaces wireless <interface> ssid <ssid> - - SSID to be used in IEEE 802.11 management frames - -.. cfgcmd:: set interfaces wireless <interface> type - <access-point | station | monitor> - - Wireless device type for this interface - - * ``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 - :var1: wlan0 - -PPDU ----- - -.. cfgcmd:: set interfaces wireless <interface> capabilities require-ht - -.. cfgcmd:: set interfaces wireless <interface> capabilities require-vht - -.. cfgcmd:: set interfaces wireless <interface> capabilities require-he - -HT (High Throughput) capabilities (802.11n) -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - - 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 - - Device is incapable of 40 MHz, do not advertise. This sets ``[40-INTOLERANT]`` - -.. cfgcmd:: set interfaces wireless <interface> capabilities ht auto-powersave - - WMM-PS Unscheduled Automatic Power Save Delivery [U-APSD] - -.. cfgcmd:: set interfaces wireless <interface> capabilities ht - channel-set-width <ht20 | ht40+ | ht40-> - - Supported channel width set. - - * ``ht20`` - 20 MHz channel width - * ``ht40-`` - Both 20 MHz and 40 MHz with secondary channel below the primary - channel - * ``ht40+`` - Both 20 MHz and 40 MHz with secondary channel above the primary - channel - - .. note:: 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 - - freq HT40- HT40+ - 2.4 GHz 5-13 1-7 (1-9 in Europe/Japan) - 5 GHz 40,48,56,64 36,44,52,60 - - .. note:: 40 MHz channels may switch their primary and secondary channels if - needed or creation of 40 MHz channel may be rejected based on overlapping - BSSes. These changes are done automatically when hostapd is setting up the - 40 MHz channel. - -.. cfgcmd:: set interfaces wireless <interface> capabilities ht - delayed-block-ack - - Enable HT-delayed Block Ack ``[DELAYED-BA]`` - -.. cfgcmd:: set interfaces wireless <interface> capabilities ht dsss-cck-40 - - DSSS/CCK Mode in 40 MHz, this sets ``[DSSS_CCK-40]`` - -.. cfgcmd:: set interfaces wireless <interface> capabilities ht greenfield - - This enables the greenfield option which sets the ``[GF]`` option - -.. cfgcmd:: set interfaces wireless <interface> capabilities ht ldpc - - Enable LDPC coding capability - -.. cfgcmd:: set interfaces wireless <interface> capabilities ht lsig-protection - - Enable L-SIG TXOP protection capability - -.. cfgcmd:: set interfaces wireless <interface> capabilities ht max-amsdu - <3839 | 7935> - - Maximum A-MSDU length 3839 (default) or 7935 octets - -.. cfgcmd:: set interfaces wireless <interface> capabilities ht - short-gi <20 | 40> - - Short GI capabilities for 20 and 40 MHz - -.. cfgcmd:: set interfaces wireless <interface> capabilities ht - smps <static | dynamic> - - Spatial Multiplexing Power Save (SMPS) settings - -.. cfgcmd:: set interfaces wireless <interface> capabilities ht stbc rx <num> - - Enable receiving PPDU using STBC (Space Time Block Coding) - -.. cfgcmd:: set interfaces wireless <interface> capabilities ht stbc tx - - Enable sending PPDU using STBC (Space Time Block Coding) - -VHT (Very High Throughput) capabilities (802.11ac) -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -.. stop_vyoslinter - -.. cfgcmd:: set interfaces wireless <interface> capabilities vht antenna-count <count> - -.. start_vyoslinter - - Number of antennas on this card - -.. cfgcmd:: set interfaces wireless <interface> capabilities vht - antenna-pattern-fixed - - Set if antenna pattern does not change during the lifetime of an association - -.. cfgcmd:: set interfaces wireless <interface> capabilities vht beamform - <single-user-beamformer | single-user-beamformee | multi-user-beamformer | - multi-user-beamformee> - - Beamforming capabilities: - - * ``single-user-beamformer`` - Support for operation as - single user beamformer - * ``single-user-beamformee`` - Support for operation as - single user beamformee - * ``multi-user-beamformer`` - Support for operation as - multi user beamformer - * ``multi-user-beamformee`` - Support for operation as - multi user beamformee - -.. cfgcmd:: set interfaces wireless <interface> capabilities vht - center-channel-freq <freq-1 | freq-2> <number> - - VHT operating channel center frequency - center freq 1 - (for use with 80, 80+80 and 160 modes) - - VHT operating channel center frequency - center freq 2 - (for use with the 80+80 mode) - - <number> must be from 34 - 173. For 80 MHz channels it should be channel + 6. - -.. cfgcmd:: set interfaces wireless <interface> capabilities vht - channel-set-width <0 | 1 | 2 | 3> - - * ``0`` - 20 or 40 MHz channel width (default) - * ``1`` - 80 MHz channel width - * ``2`` - 160 MHz channel width - * ``3`` - 80+80 MHz channel width - -.. cfgcmd:: set interfaces wireless <interface> capabilities vht ldpc - - Enable LDPC (Low Density Parity Check) coding capability - -.. cfgcmd:: set interfaces wireless <interface> - capabilities vht link-adaptation - - VHT link adaptation capabilities - -.. cfgcmd:: set interfaces wireless <interface> capabilities vht - max-mpdu <value> - - Increase Maximum MPDU length to 7991 or 11454 octets (default 3895 octets) - -.. cfgcmd:: set interfaces wireless <interface> capabilities vht - max-mpdu-exp <value> - - Set the maximum length of A-MPDU pre-EOF padding that the station can - receive - -.. cfgcmd:: set interfaces wireless <interface> capabilities vht - short-gi <80 | 160> - - Short GI capabilities - -.. cfgcmd:: set interfaces wireless <interface> capabilities vht stbc rx <num> - - Enable receiving PPDU using STBC (Space Time Block Coding) - -.. cfgcmd:: set interfaces wireless <interface> capabilities vht stbc tx - - Enable sending PPDU using STBC (Space Time Block Coding) - -.. cfgcmd:: set interfaces wireless <interface> capabilities vht tx-powersave - - Enable VHT TXOP Power Save Mode - -.. cfgcmd:: set interfaces wireless <interface> capabilities vht vht-cf - - Station supports receiving VHT variant HT Control field - -HE (High Efficiency) capabilities (802.11ax) -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -.. cfgcmd:: set interfaces wireless <interface> - capabilities he antenna-pattern-fixed - - Tell the AP that antenna positions are fixed and will not change - during the lifetime of an association. - -.. cfgcmd:: set interfaces wireless <interface> capabilities he beamform - <single-user-beamformer | single-user-beamformee | multi-user-beamformer> - - Beamforming capabilities: - - * ``single-user-beamformer`` - Support for operation as - single user beamformer - * ``single-user-beamformee`` - Support for operation as - single user beamformee - * ``multi-user-beamformer`` - Support for operation as multi - user beamformer - -.. cfgcmd:: set interfaces wireless <interface> - capabilities he bss-color <number> - - BSS coloring helps to prevent channel jamming when multiple APs use - the same channels. - - Valid values are 1..63 - -.. cfgcmd:: set interfaces wireless <interface> capabilities he - center-channel-freq <freq-1 | freq-2> <number> - - HE operating channel center frequency - center freq 1 - (for use with 80, 80+80 and 160 modes) - - HE operating channel center frequency - center freq 2 - (for use with the 80+80 mode) - - <number> must be within 1..233. For 80 MHz channels it should be - channel + 6 and for 160 MHz channels, it should be channel + 14. - -.. cfgcmd:: set interfaces wireless <interface> - capabilities he channel-set-width <number> - - <number> must be one of: - - * ``81`` - 20 MHz channel width (2.4GHz) - * ``83`` - 40 MHz channel width, secondary 20MHz channel above primary - channel (2.4GHz) - * ``84`` - 40 MHz channel width, secondary 20MHz channel below primary - channel (2.4GHz) - * ``131`` - 20 MHz channel width (6GHz) - * ``132`` - 40 MHz channel width (6GHz) - * ``133`` - 80 MHz channel width (6GHz) - * ``134`` - 160 MHz channel width (6GHz) - * ``135`` - 80+80 MHz channel width (6GHz) - -.. cfgcmd:: set interfaces wireless <interface> - capabilities he coding-scheme <number> - - 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. - - <number> must be one of: - - * ``0`` - HE-MCS 0-7 - * ``1`` - HE-MCS 0-9 - * ``2`` - HE-MCS 0-11 - * ``3`` - HE-MCS is not supported - -Wireless options (Station/Client) -================================= - -The example creates a wireless station (commonly referred to as Wi-Fi client) -that accesses the network through the WAP defined in the above example. The -default physical device (``phy0``) is used. - -.. code-block:: none - - 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 security wpa passphrase '12345678' - -Resulting configuration: - -.. code-block:: none - - system { - wireless { - country-code de - } - } - interfaces { - wireless wlan0 { - address dhcp - security { - wpa { - passphrase "12345678" - } - } - ssid TEST - type station - } - -Security -======== - -:abbr:`WPA (Wi-Fi Protected Access)`, WPA2 Enterprise and WPA3 Enterprise in -combination with 802.1X based authentication can be used to authenticate -users or computers in a domain. - -The wireless client (supplicant) authenticates against the RADIUS server -(authentication server) using an :abbr:`EAP (Extensible Authentication -Protocol)` method configured on the RADIUS server. The WAP (also referred -to as authenticator) role is to send all authentication messages between the -supplicant and the configured authentication server, thus the RADIUS server -is responsible for authenticating the users. - -The WAP in this example has the following characteristics: - -* IP address ``192.168.2.1/24`` -* Network ID (SSID) ``Enterprise-TEST`` -* WPA passphrase ``12345678`` -* Use 802.11n protocol -* Wireless channel ``1`` -* RADIUS server at ``192.168.3.10`` with shared-secret ``VyOSPassword`` - -.. stop_vyoslinter -.. code-block:: none - - set system wireless country-code de - set interfaces wireless wlan0 address '192.168.2.1/24' - set interfaces wireless wlan0 type access-point - set interfaces wireless wlan0 channel 1 - set interfaces wireless wlan0 mode n - set interfaces wireless wlan0 ssid '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' - set interfaces wireless wlan0 security wpa radius server 192.168.3.10 port 1812 - -.. start_vyoslinter - -Resulting configuration: - -.. code-block:: none - - system { - wireless { - country-code de - } - } - interfaces { - [...] - wireless wlan0 { - address 192.168.2.1/24 - channel 1 - mode n - security { - wpa { - cipher CCMP - mode wpa2 - radius { - server 192.168.3.10 { - key 'VyOSPassword' - port 1812 - } - } - } - } - ssid "Enterprise-TEST" - type access-point - } - } - -VLAN -==== - -Regular VLANs (802.1q) ----------------------- - -.. cmdinclude:: /_include/interface-vlan-8021q.txt - :var0: wireless - :var1: wlan0 - -QinQ (802.1ad) --------------- - -.. cmdinclude:: /_include/interface-vlan-8021ad.txt - :var0: wireless - :var1: wlan0 - -********* -Operation -********* - -.. opcmd:: show interfaces wireless info - -Use this command to view operational status and wireless-specific information -about all wireless interfaces. - -.. code-block:: none - - vyos@vyos:~$ show interfaces wireless info - Interface Type SSID Channel - wlan0 access-point VyOS-TEST-0 1 - -.. opcmd:: show interfaces wireless detail - -Show the operational status and detailed wireless-specific -information about all wireless interfaces. - -.. stop_vyoslinter -.. code-block:: none - - vyos@vyos:~$ show interfaces wireless detail - wlan0: <BROADCAST,MULTICAST,UP,LOWER_UP> mtu 1500 qdisc noqueue state UP group default qlen 1000 - link/ether XX:XX:XX:XX:XX:c3 brd XX:XX:XX:XX:XX:ff - inet xxx.xxx.99.254/24 scope global wlan0 - valid_lft forever preferred_lft forever - inet6 fe80::xxxx:xxxx:fe54:2fc3/64 scope link - valid_lft forever preferred_lft forever - - RX: bytes packets errors dropped overrun mcast - 66072 282 0 0 0 0 - TX: bytes packets errors dropped carrier collisions - 83413 430 0 0 0 0 - - wlan1: <BROADCAST,MULTICAST,UP,LOWER_UP> mtu 1500 qdisc noqueue state UP group default qlen 1000 - link/ether XX:XX:XX:XX:XX:c3 brd XX:XX:XX:XX:XX:ff - inet xxx.xxx.100.254/24 scope global wlan0 - valid_lft forever preferred_lft forever - inet6 fe80::xxxx:xxxx:ffff:2ed3/64 scope link - valid_lft forever preferred_lft forever - - RX: bytes packets errors dropped overrun mcast - 166072 5282 0 0 0 0 - TX: bytes packets errors dropped carrier collisions - 183413 5430 0 0 0 0 - -.. start_vyoslinter - -.. opcmd:: show interfaces wireless <wlanX> - -This command shows both status and statistics on the specified wireless -interface. The wireless interface identifier can range from wlan0 to wlan999. - -.. stop_vyoslinter -.. code-block:: none - - vyos@vyos:~$ show interfaces wireless wlan0 - wlan0: <BROADCAST,MULTICAST,UP,LOWER_UP> mtu 1500 qdisc noqueue state UP group default qlen 1000 - link/ether XX:XX:XX:XX:XX:c3 brd XX:XX:XX:XX:XX:ff - inet xxx.xxx.99.254/24 scope global wlan0 - valid_lft forever preferred_lft forever - inet6 fe80::xxxx:xxxx:fe54:2fc3/64 scope link - valid_lft forever preferred_lft forever - - RX: bytes packets errors dropped overrun mcast - 66072 282 0 0 0 0 - TX: bytes packets errors dropped carrier collisions - 83413 430 0 0 0 0 - -.. start_vyoslinter - - -.. opcmd:: show interfaces wireless <wlanX> brief - -This command gives a brief status overview of a specified wireless interface. -The wireless interface identifier can range from wlan0 to wlan999. - -.. code-block:: none - - vyos@vyos:~$ show interfaces wireless wlan0 brief - Codes: S - State, L - Link, u - Up, D - Down, A - Admin Down - Interface IP Address S/L Description - --------- ---------- --- ----------- - wlan0 192.168.2.254/24 u/u - - -.. opcmd:: show interfaces wireless <wlanX> queue - -Use this command to view wireless interface queue information. -The wireless interface identifier can range from wlan0 to wlan999. - -.. code-block:: none - - vyos@vyos:~$ show interfaces wireless wlan0 queue - qdisc pfifo_fast 0: root bands 3 priomap 1 2 2 2 1 2 0 0 1 1 1 1 1 1 1 1 - Sent 810323 bytes 6016 pkt (dropped 0, overlimits 0 requeues 0) - rate 0bit 0pps backlog 0b 0p requeues 0 - - -.. opcmd:: show interfaces wireless <wlanX> scan - -This command is used to retrieve information about WAP within the range of your -wireless interface. This command is useful on wireless interfaces configured -in station mode. - -.. note:: Scanning is not supported on all wireless drivers and wireless - hardware. Refer to your driver and wireless hardware documentation for - further details. - -.. code-block:: none - - vyos@vyos:~$ show interfaces wireless wlan0 scan - Address SSID Channel Signal (dbm) - 00:53:3b:88:6e:d8 WLAN-576405 1 -64.00 - 00:53:3b:88:6e:da Telekom_FON 1 -64.00 - 00:53:00:f2:c2:a4 BabyView_F2C2A4 6 -60.00 - 00:53:3b:88:6e:d6 Telekom_FON 100 -72.00 - 00:53:3b:88:6e:d4 WLAN-576405 100 -71.00 - 00:53:44:a4:96:ec KabelBox-4DC8 56 -81.00 - 00:53:d9:7a:67:c2 WLAN-741980 1 -75.00 - 00:53:7c:99:ce:76 Vodafone Homespot 1 -86.00 - 00:53:44:a4:97:21 KabelBox-4DC8 1 -78.00 - 00:53:44:a4:97:21 Vodafone Hotspot 1 -79.00 - 00:53:44:a4:97:21 Vodafone Homespot 1 -79.00 - 00:53:86:40:30:da Telekom_FON 1 -86.00 - 00:53:7c:99:ce:76 Vodafone Hotspot 1 -86.00 - 00:53:44:46:d2:0b Vodafone Hotspot 1 -87.00 - - -******** -Examples -******** - -The following example creates a WAP. When configuring multiple WAP interfaces, -you must specify unique IP addresses, channels, Network IDs commonly referred -to as :abbr:`SSID (Service Set Identifier)`, and MAC addresses. - -The WAP in this example has the following characteristics: - -* IP address ``192.168.2.1/24`` -* Network ID (SSID) ``TEST`` -* WPA passphrase ``12345678`` -* Use 802.11n protocol -* Wireless channel ``1`` - -.. code-block:: none - - set system wireless country-code de - set interfaces wireless wlan0 address '192.168.2.1/24' - set interfaces wireless wlan0 type access-point - set interfaces wireless wlan0 channel 1 - set interfaces wireless wlan0 mode n - set interfaces wireless wlan0 ssid 'TEST' - set interfaces wireless wlan0 security wpa mode wpa2 - set interfaces wireless wlan0 security wpa cipher CCMP - set interfaces wireless wlan0 security wpa passphrase '12345678' - -Resulting configuration: - -.. code-block:: none - - system { - wireless { - country-code de - } - } - interfaces { - [...] - wireless wlan0 { - address 192.168.2.1/24 - channel 1 - mode n - security { - wpa { - cipher CCMP - mode wpa2 - passphrase "12345678" - } - } - ssid "TEST" - type access-point - } - } - -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). - -Wi-Fi 6/6E (802.11ax) -===================== - -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`` -* Protocol: 802.11ax -* Wireless channel for 2.4 GHz: ``11`` -* Wireless channel for 6 GHz: ``5`` - - -Example configuration: Wi-Fi 6 at 2.4 GHz ------------------------------------------- - -You may expect real throughput around 10 MB/s or higher in crowded areas. - -.. stop_vyoslinter - -.. code-block:: none - - set system wireless country-code de - set interfaces wireless wlan0 capabilities he antenna-pattern-fixed - set interfaces wireless wlan0 capabilities he beamform multi-user-beamformer - set interfaces wireless wlan0 capabilities he beamform single-user-beamformee - 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 81 - set interfaces wireless wlan0 capabilities ht 40mhz-incapable - set interfaces wireless wlan0 capabilities ht channel-set-width ht20 - set interfaces wireless wlan0 capabilities ht channel-set-width ht40+ - set interfaces wireless wlan0 capabilities ht channel-set-width ht40- - set interfaces wireless wlan0 capabilities ht short-gi 20 - set interfaces wireless wlan0 capabilities ht short-gi 40 - set interfaces wireless wlan0 capabilities ht stbc rx 2 - set interfaces wireless wlan0 capabilities ht stbc tx - set interfaces wireless wlan0 channel 11 - set interfaces wireless wlan0 description "802.11ax 2.4GHz" - set interfaces wireless wlan0 mode ax - set interfaces wireless wlan0 security wpa cipher CCMP - set interfaces wireless wlan0 security wpa cipher CCMP-256 - set interfaces wireless wlan0 security wpa cipher GCMP-256 - set interfaces wireless wlan0 security wpa cipher GCMP - set interfaces wireless wlan0 security wpa mode wpa2 - set interfaces wireless wlan0 security wpa passphrase super-dooper-secure-passphrase - set interfaces wireless wlan0 ssid test.ax - set interfaces wireless wlan0 type access-point - commit - -.. start_vyoslinter - -Resulting configuration: - -.. code-block:: none - - system { - wireless { - country-code de - } - } - interfaces { - [...] - wireless wlan0 { - capabilities { - he { - antenna-pattern-fixed - beamform { - multi-user-beamformer - single-user-beamformee - single-user-beamformer - } - bss-color 13 - channel-set-width 81 - } - ht { - 40mhz-incapable - channel-set-width ht20 - channel-set-width ht40+ - channel-set-width ht40- - short-gi 20 - short-gi 40 - stbc { - rx 2 - tx - } - } - } - channel 11 - description "802.11ax 2.4GHz" - hw-id [...] - mode ax - physical-device phy0 - security { - wpa { - cipher CCMP - cipher CCMP-256 - cipher GCMP-256 - cipher GCMP - mode wpa2 - passphrase super-dooper-secure-passphrase - } - } - ssid test.ax - type access-point - } - } - -Example configuration: Wi-Fi 6E at 6 GHz ------------------------------------------ - -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 - set interfaces wireless wlan0 capabilities he antenna-pattern-fixed - set interfaces wireless wlan0 capabilities he beamform multi-user-beamformer - set interfaces wireless wlan0 capabilities he beamform single-user-beamformee - 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 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 - set interfaces wireless wlan0 security wpa cipher CCMP - set interfaces wireless wlan0 security wpa cipher CCMP-256 - set interfaces wireless wlan0 security wpa cipher GCMP-256 - set interfaces wireless wlan0 security wpa cipher GCMP - set interfaces wireless wlan0 security wpa mode wpa3 - set interfaces wireless wlan0 security wpa passphrase super-dooper-secure-passphrase - set interfaces wireless wlan0 mgmt-frame-protection required - set interfaces wireless wlan0 enable-bf-protection - set interfaces wireless wlan0 ssid test.ax - set interfaces wireless wlan0 type access-point - set interfaces wireless wlan0 stationary-ap - commit - -.. start_vyoslinter - -Resulting configuration: - -.. code-block:: none - - system { - wireless { - country-code de - } - } - interfaces { - [...] - wireless wlan0 { - capabilities { - he { - antenna-pattern-fixed - beamform { - multi-user-beamformer - single-user-beamformee - single-user-beamformer - } - bss-color 13 - center-channel-freq { - freq-1 15 - } - channel-set-width 134 - } - } - channel 5 - description "802.11ax 6GHz" - enable-bf-protection - hw-id [...] - mgmt-frame-protection required - mode ax - physical-device phy0 - security { - wpa { - cipher CCMP - cipher CCMP-256 - cipher GCMP-256 - cipher GCMP - mode wpa3 - passphrase super-dooper-secure-passphrase - } - } - ssid test.ax - stationary-ap - type access-point - } - } - -.. _wireless-interface-intel-ax200: - -Intel AX200 -=========== - -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 -.. code-block:: none - - set system wireless country-code 'us' - set interfaces wireless wlan0 channel '1' - set interfaces wireless wlan0 mode 'n' - set interfaces wireless wlan0 physical-device 'phy0' - set interfaces wireless wlan0 ssid 'VyOS' - set interfaces wireless wlan0 type 'access-point' - -.. start_vyoslinter diff --git a/docs/configuration/interfaces/rst-wwan.rst b/docs/configuration/interfaces/rst-wwan.rst deleted file mode 100644 index 7ab3ac74..00000000 --- a/docs/configuration/interfaces/rst-wwan.rst +++ /dev/null @@ -1,342 +0,0 @@ -:lastproofread: 2026-03-30 - -.. _wwan-interface: - -#### -WWAN -#### - -:abbr:`WWAN (Wireless Wide Area Network)` interfaces provide access to cellular -networks via a cellular modem or card. - -Configure these interfaces under the ``interfaces wwan`` node. - -************* -Configuration -************* - -Common interface configuration -============================== - -.. cmdinclude:: /_include/interface-address-with-dhcp.txt - :var0: wwan - :var1: wwan0 - -.. cmdinclude:: /_include/interface-description.txt - :var0: wwan - :var1: wwan0 - -.. cmdinclude:: /_include/interface-disable.txt - :var0: wwan - :var1: wwan0 - -.. cmdinclude:: /_include/interface-disable-link-detect.txt - :var0: wwan - :var1: wwan0 - -.. cmdinclude:: /_include/interface-mtu.txt - :var0: wwan - :var1: wwan0 - -.. cmdinclude:: /_include/interface-ip.txt - :var0: wwan - :var1: wwan0 - -.. cmdinclude:: /_include/interface-ipv6.txt - :var0: wwan - :var1: wwan0 - -.. cmdinclude:: /_include/interface-vrf.txt - :var0: wwan - :var1: wwan0 - -**DHCP(v6)** - -.. cmdinclude:: /_include/interface-dhcp-options.txt - :var0: wwan - :var1: wwan0 - -.. cmdinclude:: /_include/interface-dhcpv6-options.txt - :var0: wwan - :var1: wwan0 - -.. cmdinclude:: /_include/interface-dhcpv6-prefix-delegation.txt - :var0: wwan - :var1: wwan0 - -WWAN options -============ - -.. cfgcmd:: set interfaces wwan <interface> apn <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)`. - - -********* -Operation -********* - -.. opcmd:: show interfaces wwan <interface> - - Show the operational status and traffic statistics for the specified WWAN - interface. - - .. code-block:: none - - vyos@vyos:~$ show interfaces wwan wwan0 - wwan0: <BROADCAST,MULTICAST,UP,LOWER_UP> mtu 1500 qdisc pfifo_fast state UNKNOWN group default qlen 1000 - link/ether 02:c2:f3:00:01:02 brd ff:ff:ff:ff:ff:ff - inet 10.155.144.12/30 brd 10.155.144.15 scope global dynamic wwan0 - valid_lft 7012sec preferred_lft 7012sec - inet6 fe80::c2:f3ff:fe00:0102/64 scope link - valid_lft forever preferred_lft forever - - RX: bytes packets errors dropped overrun mcast - 640 2 0 0 0 0 - TX: bytes packets errors dropped carrier collisions - 3229 16 0 0 0 0 - -.. opcmd:: show interfaces wwan <interface> summary - - Show WWAN module hardware characteristics and connection information. - - .. code-block:: none - - vyos@vyos:~$ show interfaces wwan wwan0 summary - -------------------------------- - General | dbus path: /org/freedesktop/ModemManager1/Modem/0 - | device id: 79f4e9cc2e9fc8d4a3b8c8f6327c2e363170194d - -------------------------------- - Hardware | manufacturer: Sierra Wireless, Incorporated - | model: MC7710 - | revision: SWI9200X_03.05.29.03ap r6485 CNSHZ-ED-XP0031 2014/12/02 17:53:15 - | h/w revision: 1.0 - | supported: gsm-umts, lte - | current: gsm-umts, lte - | equipment id: 358xxxxxxxxxxxx - -------------------------------- - System | device: /sys/devices/pci0000:00/0000:00:13.0/usb3/3-1/3-1.3 - | drivers: qcserial, qmi_wwan - | plugin: Generic - | primary port: cdc-wdm0 - | ports: ttyUSB0 (qcdm), ttyUSB2 (at), cdc-wdm0 (qmi), wwan0 (net) - -------------------------------- - Numbers | own: 4917xxxxxxxx - -------------------------------- - Status | lock: sim-pin2 - | unlock retries: sim-pin (3), sim-pin2 (3), sim-puk (10), sim-puk2 (10) - | state: connected - | power state: on - | access tech: lte - | signal quality: 63% (recent) - -------------------------------- - Modes | supported: allowed: 2g; preferred: none - | allowed: 3g; preferred: none - | allowed: 4g; preferred: none - | allowed: 2g, 3g; preferred: 3g - | allowed: 2g, 3g; preferred: 2g - | allowed: 2g, 4g; preferred: 4g - | allowed: 2g, 4g; preferred: 2g - | allowed: 3g, 4g; preferred: 3g - | allowed: 3g, 4g; preferred: 4g - | allowed: 2g, 3g, 4g; preferred: 4g - | allowed: 2g, 3g, 4g; preferred: 3g - | allowed: 2g, 3g, 4g; preferred: 2g - | current: allowed: 2g, 3g, 4g; preferred: 2g - -------------------------------- - Bands | supported: egsm, dcs, pcs, utran-1, utran-8, eutran-1, eutran-3, - | eutran-7, eutran-8, eutran-20 - | current: egsm, dcs, pcs, utran-1, utran-8, eutran-1, eutran-3, - | eutran-7, eutran-8, eutran-20 - -------------------------------- - IP | supported: ipv4, ipv6, ipv4v6 - -------------------------------- - 3GPP | imei: 358xxxxxxxxxxxx - | operator id: 26201 - | operator name: Telekom.de - | registration: home - -------------------------------- - 3GPP EPS | ue mode of operation: ps-1 - -------------------------------- - SIM | dbus path: /org/freedesktop/ModemManager1/SIM/0 - -------------------------------- - Bearer | dbus path: /org/freedesktop/ModemManager1/Bearer/0 - - -.. opcmd:: show interfaces wwan <interface> capabilities - - Show WWAN module radio capabilities. - - .. code-block:: none - - vyos@vyos:~$ show interfaces wwan wwan0 capabilities - Max TX channel rate: '50000000' - Max RX channel rate: '100000000' - Data Service: 'simultaneous-cs-ps' - SIM: 'supported' - Networks: 'gsm, umts, lte' - Bands: 'gsm-dcs-1800, gsm-900-extended, gsm-900-primary, gsm-pcs-1900, wcdma-2100, wcdma-900' - LTE bands: '1, 3, 7, 8, 20' - -.. opcmd:: show interfaces wwan <interface> firmware - - Show WWAN module firmware information. - - .. code-block:: none - - vyos@vyos:~$ show interfaces wwan wwan0 firmware - Model: MC7710 - Boot version: SWI9200X_03.05.29.03bt r6485 CNSHZ-ED-XP0031 2014/12/02 17:33:08 - AMSS version: SWI9200X_03.05.29.03ap r6485 CNSHZ-ED-XP0031 2014/12/02 17:53:15 - SKU ID: unknown - Package ID: unknown - Carrier ID: 0 - Config version: unknown - - -.. opcmd:: show interfaces wwan <interface> imei - - Show WWAN module IMEI. - - .. code-block:: none - - vyos@vyos:~$ show interfaces wwan wwan0 imei - ESN: '0' - IMEI: '358xxxxxxxxxxxx' - MEID: 'unknown' - -.. opcmd:: show interfaces wwan <interface> imsi - - Show the IMSI of the associated SIM card. - - .. code-block:: none - - vyos@vyos:~$ show interfaces wwan wwan0 imsi - IMSI: '262xxxxxxxxxxxx' - -.. opcmd:: show interfaces wwan <interface> model - - Show WWAN module model. - - .. code-block:: none - - vyos@vyos:~$ show interfaces wwan wwan0 model - Model: 'MC7710' - -.. opcmd:: show interfaces wwan <interface> msisdn - - Show the MSISDN of the associated SIM card. - - .. code-block:: none - - vyos@vyos:~$ show interfaces wwan wwan0 msisdn - MSISDN: '4917xxxxxxxx' - -.. opcmd:: show interfaces wwan <interface> revision - - Show WWAN module hardware revision. - - .. code-block:: none - - vyos@vyos:~$ show interfaces wwan wwan0 revision - Revision: 'SWI9200X_03.05.29.03ap r6485 CNSHZ-ED-XP0031 2014/12/02 17:53:15' - -.. opcmd:: show interfaces wwan <interface> signal - - Show signal information for the cellular connection. - - .. code-block:: none - - vyos@vyos:~$ show interfaces wwan wwan0 signal - LTE: - RSSI: '-74 dBm' - RSRQ: '-7 dB' - RSRP: '-100 dBm' - SNR: '13.0 dB' - Radio Interface: 'lte' - Active Band Class: 'eutran-3' - Active Channel: '1300' - -.. opcmd:: show interfaces wwan <interface> sim - - Show WWAN module SIM card information. - - .. code-block:: none - - vyos@vyos:~$ show interfaces wwan wwan0 sim - Provisioning applications: - Primary GW: slot '1', application '1' - Primary 1X: session doesn't exist - Secondary GW: session doesn't exist - Secondary 1X: session doesn't exist - Slot [1]: - Card state: 'present' - UPIN state: 'not-initialized' - UPIN retries: '0' - UPUK retries: '0' - Application [1]: - Application type: 'usim (2)' - Application state: 'ready' - Application ID: - A0:00:00:00:87:10:02:FF:49:94:20:89:03:10:00:00 - Personalization state: 'ready' - UPIN replaces PIN1: 'no' - PIN1 state: 'disabled' - PIN1 retries: '3' - PUK1 retries: '10' - PIN2 state: 'enabled-not-verified' - PIN2 retries: '3' - PUK2 retries: '10' - -******* -Example -******* - -The following example 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 hardware -****************** - -The following WWAN modules have been successfully tested with a -:ref:`pc-engines-apu4` board: - -* Sierra Wireless AirPrime MC7304 miniPCIe card (LTE) -* Sierra Wireless AirPrime MC7430 miniPCIe card (LTE) -* Sierra Wireless AirPrime MC7455 miniPCIe card (LTE) -* Sierra Wireless AirPrime MC7710 miniPCIe card (LTE) -* Huawei ME909u-521 miniPCIe card (LTE) -* Huawei ME909s-120 miniPCIe card (LTE) -* HP LT4120 Snapdragon X5 LTE - -*************** -Firmware update -*************** - -WWAN modules include reprogrammable firmware, and most vendors regularly -provide updates for it. - -Since VyOS communicates with these devices via the QMI interface, you can -update firmware directly within the system using the ``qmi-firmware-update`` -utility. - -The following example shows how to update the firmware for a Sierra Wireless -MC7710 module using the provided .cwe file. - -.. code-block:: bash - - $ sudo qmi-firmware-update --update -d 1199:68a2 \ - 9999999_9999999_9200_03.05.14.00_00_generic_000.000_001_SPKG_MC.cwe diff --git a/docs/configuration/loadbalancing/rst-haproxy.rst b/docs/configuration/loadbalancing/rst-haproxy.rst deleted file mode 100644 index d742ec18..00000000 --- a/docs/configuration/loadbalancing/rst-haproxy.rst +++ /dev/null @@ -1,509 +0,0 @@ -:lastproofread: 2026-04-06 - -############# -HAproxy -############# - -.. include:: /_include/need_improvement.txt - -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 specifies the port to bind to. Backend -configuration defines the load balancing method and specifies the backend -servers. - -Service -------- - -.. cfgcmd:: set load-balancing haproxy service <name> listen-address - <address> - - 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> - - Create service `<name>` to listen on <port> - -.. cfgcmd:: set load-balancing haproxy service <name> mode - <tcp|http> - - Configure service `<name>` mode TCP or HTTP - -.. cfgcmd:: set load-balancing haproxy service <name> backend - <name> - - Configure service `<name>` to use the backend <name> - -.. cfgcmd:: set load-balancing haproxy service <name> ssl - certificate <name> - - 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 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 the syslog configuration section. - -.. cfgcmd:: set load-balancing haproxy service <name> timeout client - <seconds> - - Set the maximum inactivity time on the client side for this service. - Value range 1-3600 seconds. - -.. cfgcmd:: set load-balancing haproxy service <name> http-compression algorithm - <gzip | deflate | identity | raw-deflate> - - Set the compression algorithm to be used when compressing HTTP responses. - -.. cfgcmd:: set load-balancing haproxy service <name> http-compression mime-type - <mime-type> - - Set the list of HTTP response MIME types which haproxy will attempt to - compress, if received uncompressed from backend server. - -Rules -^^^^^ -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> - - Match domain name - -.. cfgcmd:: set load-balancing haproxy service <name> rule <rule> - ssl <sni> - - SSL match Server Name Indication (SNI) option: - * ``req-ssl-sni`` SSL Server Name Indication (SNI) request match - * ``ssl-fc-sni`` SSL frontend connection Server Name Indication match - * ``ssl-fc-sni-end`` SSL frontend match end of connection Server Name - - Indication - -.. cfgcmd:: set load-balancing haproxy service <name> rule <rule> - url-path <match> <url> - - 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`` Matches the URL path exactly. - -.. cfgcmd:: set load-balancing haproxy service <name> rule <rule> - set backend <name> - - Assign a specific backend to a rule - -.. cfgcmd:: set load-balancing haproxy service <name> rule <rule> - redirect-location <url> - - Redirect URL to a new location. - - -Backend -------- - -.. cfgcmd:: set load-balancing haproxy backend <name> balance - <balance> - - 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. - * ``round-robin`` Distributes requests in a circular manner, - sequentially sending each request to the next server in line. - * ``least-connection`` Distributes requests to the server with the fewest - active connections. - -.. cfgcmd:: set load-balancing haproxy backend <name> mode - <mode> - - 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 that receives incoming traffic. - -.. cfgcmd:: set load-balancing haproxy backend <name> server - <name> port <port> - - Set the address of the backend port. - -.. cfgcmd:: set load-balancing haproxy backend <name> server - <name> check - - Active health check backend server. - -.. cfgcmd:: set load-balancing haproxy backend <name> server - <name> check port <port> - - Set an alternative port number for health checks. - Overrides the default server port used for TCP/HTTP checks. - -.. cfgcmd:: set load-balancing haproxy backend <name> server - <name> send-proxy - - 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). - -.. cfgcmd:: set load-balancing haproxy backend <name> ssl - ca-certificate <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 - - 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 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 the :ref:`syslog` configuration section. - -.. cfgcmd:: set load-balancing haproxy backend <name> timeout check - <seconds> - - Set the timeout in seconds for established connections. - Value range 1-3600 seconds. - - -.. cfgcmd:: set load-balancing haproxy backend <name> timeout connect - <seconds> - - Set the maximum time to wait for a connection attempt to a server to succeed. - Value range 1-3600 seconds. - -.. cfgcmd:: set load-balancing haproxy backend <name> timeout server - <seconds> - - Set the maximum inactivity time on the server side. - Value range 1-3600 seconds. - - - -Global -------- - -Global configuration parameters: - -.. cfgcmd:: set load-balancing haproxy global-parameters max-connections - <num> - - Limit maximum number of connections - -.. cfgcmd:: set load-balancing haproxy global-parameters ssl-bind-ciphers - <ciphers> - - Limit the cipher algorithms allowed during SSL/TLS handshake. - -.. cfgcmd:: set load-balancing haproxy global-parameters tls-version-min - <version> - - Specify the minimum required TLS version 1.2 or 1.3 - -.. cfgcmd:: set load-balancing haproxy global-parameters logging - facility <facility> level <level> - - Specify facility and level for logging. - For an explanation on :ref:`syslog_facilities` and - :ref:`syslog_severity_level` - see tables in syslog configuration section. - -.. cfgcmd:: set load-balancing haproxy timeout check <seconds> - - Set the timeout in seconds for established connections. - Value range 1-3600 seconds. Default is 5 seconds. - -.. cfgcmd:: set load-balancing haproxy timeout client <seconds> - - Set the maximum inactivity time on the client side. - Value range 1-3600 seconds. Default is 50 seconds. - -.. cfgcmd:: set load-balancing haproxy timeout connect <seconds> - - Set the maximum time to wait for a connection attempt to a server to succeed. - Value range 1-3600 seconds. Default is 10 seconds. - -.. cfgcmd:: set load-balancing haproxy timeout server <seconds> - - Set the maximum inactivity time on the server side. - Value range 1-3600 seconds. Default is 50 seconds. - -Health checks -============= - - -HTTP checks ------------ - -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 - - Enables HTTP health checks using OPTION HTTP requests against '/' and - expecting a successful response code in the 200-399 range. - -.. cfgcmd:: set load-balancing haproxy backend <name> http-check - method <method> - - Set the HTTP method: ``OPTION``, ``GET``, ``POST``, or ``PUT``. - -.. cfgcmd:: set load-balancing haproxy backend <name> http-check - uri <path> - - Set the endpoint to use for health checks. - -.. cfgcmd:: set load-balancing haproxy backend <name> http-check - expect <condition> - - Set the expected result condition for a server to be considered healthy. - - Some possible examples are: - * ``status 200`` Expecting a 200 response code - * ``status 200-399`` Expecting a non-failure response code - * ``string success`` Expecting the string `success` in the response body - - -TCP checks ----------- - -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> - - Available health check protocols: - * ``ldap`` LDAP protocol check. - * ``redis`` Redis protocol check. - * ``mysql`` MySQL protocol check. - * ``pgsql`` PostgreSQL protocol check. - * ``smtp`` SMTP protocol check. - -.. note:: If you specify a server to 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 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 - -You can use a different service name; in this example, ``http`` is just for -convenience. - - -Examples -======== - -Level 4 balancing ------------------ - -This configuration enables the TCP reverse proxy for the ``my-tcp-api`` -service. Incoming TCP connections on port 8888 are load balanced across the -backend servers (srv01 and srv02) using the round-robin load balancing -algorithm. - -.. code-block:: none - - set load-balancing haproxy service my-tcp-api backend 'bk-01' - set load-balancing haproxy service my-tcp-api mode 'tcp' - set load-balancing haproxy service my-tcp-api port '8888' - - set load-balancing haproxy backend bk-01 balance 'round-robin' - set load-balancing haproxy backend bk-01 mode 'tcp' - - set load-balancing haproxy backend bk-01 server srv01 address '192.0.2.11' - set load-balancing haproxy backend bk-01 server srv01 port '8881' - set load-balancing haproxy backend bk-01 server srv02 address '192.0.2.12' - set load-balancing haproxy backend bk-01 server srv02 port '8882' - - -Balancing based on domain name ------------------------------- -The following configuration demonstrates how to use VyOS -to achieve load balancing based on the domain name: - -The HTTP service listens on TCP port 80. - -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`` and -forwards them to the backend ``bk-api-02``. - -.. code-block:: none - - set load-balancing haproxy service http description 'bind app listen on 443 port' - set load-balancing haproxy service http mode 'tcp' - set load-balancing haproxy service http port '80' - - set load-balancing haproxy service http rule 10 domain-name 'node1.example.com' - set load-balancing haproxy service http rule 10 set backend 'bk-api-01' - set load-balancing haproxy service http rule 20 domain-name 'node2.example.com' - set load-balancing haproxy service http rule 20 set backend 'bk-api-02' - - set load-balancing haproxy backend bk-api-01 description 'My API-1' - set load-balancing haproxy backend bk-api-01 mode 'tcp' - set load-balancing haproxy backend bk-api-01 server api01 address '127.0.0.1' - set load-balancing haproxy backend bk-api-01 server api01 port '4431' - set load-balancing haproxy backend bk-api-02 description 'My API-2' - set load-balancing haproxy backend bk-api-02 mode 'tcp' - set load-balancing haproxy backend bk-api-02 server api01 address '127.0.0.2' - set load-balancing haproxy backend bk-api-02 server api01 port '4432' - - -Terminate SSL -------------- - -The following configuration terminates SSL on the router. - -The ``http`` service listens on port 80 and redirects HTTP requests to -HTTPS. - -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 them to ``/certs/``. - -Rule 20 matches requests with URL paths ending in ``/mail`` or the exact -path ``/email/bar`` and redirects them to ``/postfix/``. - -Global parameters include a maximum connection limit of 4000 and a minimum -TLS version of 1.3. - - -.. code-block:: none - - set load-balancing haproxy service http description 'Force redirect to HTTPS' - set load-balancing haproxy service http port '80' - set load-balancing haproxy service http redirect-http-to-https - - set load-balancing haproxy service https backend 'bk-default' - set load-balancing haproxy service https description 'listen on 443 port' - set load-balancing haproxy service https mode 'http' - set load-balancing haproxy service https port '443' - set load-balancing haproxy service https ssl certificate 'cert' - set load-balancing haproxy service https http-response-headers Strict-Transport-Security value 'max-age=31536000' - - set load-balancing haproxy service https rule 10 url-path exact '/.well-known/xxx' - set load-balancing haproxy service https rule 10 set redirect-location '/certs/' - set load-balancing haproxy service https rule 20 url-path end '/mail' - set load-balancing haproxy service https rule 20 url-path exact '/email/bar' - set load-balancing haproxy service https rule 20 set redirect-location '/postfix/' - - set load-balancing haproxy backend bk-default description 'Default backend' - set load-balancing haproxy backend bk-default mode 'http' - set load-balancing haproxy backend bk-default server sr01 address '192.0.2.23' - set load-balancing haproxy backend bk-default server sr01 port '80' - - set load-balancing haproxy global-parameters max-connections '4000' - set load-balancing haproxy global-parameters tls-version-min '1.3' - - -SSL Bridging -------------- - -The following configuration terminates incoming HTTPS traffic on the router, -then re-encrypts the traffic and sends 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 -specified in the configuration, which could be an internal CA. - -The ``https`` service listens on port 443 with backend ``bk-bridge-ssl`` to -handle HTTPS traffic. It uses certificate named ``cert`` for SSL termination. - -The ``bk-bridge-ssl`` backend connects to ``sr01`` server on port 443 via HTTPS -and checks backend server has a valid certificate trusted by CA ``cacert`` - - -.. code-block:: none - - set load-balancing haproxy service https backend 'bk-bridge-ssl' - set load-balancing haproxy service https description 'listen on 443 port' - set load-balancing haproxy service https mode 'http' - set load-balancing haproxy service https port '443' - set load-balancing haproxy service https ssl certificate 'cert' - - set load-balancing haproxy backend bk-bridge-ssl description 'SSL backend' - set load-balancing haproxy backend bk-bridge-ssl mode 'http' - set load-balancing haproxy backend bk-bridge-ssl ssl ca-certificate 'cacert' - set load-balancing haproxy backend bk-bridge-ssl server sr01 address '192.0.2.23' - set load-balancing haproxy backend bk-bridge-ssl server sr01 port '443' - - -Balancing with HTTP health checks ---------------------------------- - -This configuration enables HTTP health checks for backend servers. - -.. code-block:: none - - set load-balancing haproxy service my-tcp-api backend 'bk-01' - set load-balancing haproxy service my-tcp-api mode 'tcp' - set load-balancing haproxy service my-tcp-api port '8888' - - set load-balancing haproxy backend bk-01 balance 'round-robin' - set load-balancing haproxy backend bk-01 mode 'tcp' - - set load-balancing haproxy backend bk-01 http-check method 'get' - set load-balancing haproxy backend bk-01 http-check uri '/health' - set load-balancing haproxy backend bk-01 http-check expect 'status 200' - - set load-balancing haproxy backend bk-01 server srv01 address '192.0.2.11' - set load-balancing haproxy backend bk-01 server srv01 port '8881' - set load-balancing haproxy backend bk-01 server srv01 check - set load-balancing haproxy backend bk-01 server srv02 address '192.0.2.12' - set load-balancing haproxy backend bk-01 server srv02 port '8882' - set load-balancing haproxy backend bk-01 server srv02 check port '8892' - diff --git a/docs/configuration/loadbalancing/rst-index.rst b/docs/configuration/loadbalancing/rst-index.rst deleted file mode 100644 index b87faed2..00000000 --- a/docs/configuration/loadbalancing/rst-index.rst +++ /dev/null @@ -1,14 +0,0 @@ -:lastproofread: 2026-04-06 - -.. _load-balancing: - -############## -Load-balancing -############## - -.. toctree:: - :maxdepth: 1 - :includehidden: - - wan - haproxy diff --git a/docs/configuration/loadbalancing/rst-wan.rst b/docs/configuration/loadbalancing/rst-wan.rst deleted file mode 100644 index 56fdb02c..00000000 --- a/docs/configuration/loadbalancing/rst-wan.rst +++ /dev/null @@ -1,315 +0,0 @@ -:lastproofread: 2026-04-06 - -################## -WAN load balancing -################## - -.. 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). - -The following examples uses two DHCP WAN interfaces and one LAN (``eth2``): - -.. code-block:: none - - set load-balancing wan interface-health eth0 nexthop 'dhcp' - set load-balancing wan interface-health eth1 nexthop 'dhcp' - set load-balancing wan rule 1 inbound-interface 'eth2' - set load-balancing wan rule 1 interface eth0 - set load-balancing wan rule 1 interface eth1 - -.. note:: - - 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. - -Load balancing rules --------------------- - -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: - -.. code-block:: none - - vyos@vyos# set load-balancing wan rule 1 - Possible completions: - description Description for this rule - > destination Destination - exclude Exclude packets matching this rule from wan load balance - failover Enable failover for packets matching this rule from wan load balance - inbound-interface Inbound interface name (e.g., "eth0") [REQUIRED] - +> interface Interface name [REQUIRED] - > limit Enable packet limit for this rule - per-packet-balancing Option to match traffic per-packet instead of the default, per-flow - protocol Protocol to match - > source Source information - -Interface weight -**************** - -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 - -In this example,``eth0`` receives 66% of traffic, and ``eth1`` receives -33% of traffic. - -Rate limit -********** - -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 - - set load-balancing wan rule <rule> limit <parameter> - -* ``burst``: Number of packets allowed to overshoot the limit within ``period``. - Default 5. -* ``period``: Time window for rate calculation. Possible values: - ``second`` (one second), ``minute`` (one minute), ``hour`` (one hour). - Default is ``second``. -* ``rate``: Number of packets. Default: ``5``. -* ``threshold``: ``below`` or ``above`` the specified rate limit. - -Flow and packet-based balancing -******************************* - -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 improve balance across interfaces when packet -order is not critical. Enable per-packet balancing for a rule with: - -.. code-block:: none - - set load-balancing wan rule <rule> per-packet-balancing - -Exclude traffic -*************** - -To exclude traffic from load balancing, traffic matching an exclude rule -bypasses load balancing and uses the system routing table instead: - -.. code-block:: none - - set load-balancing wan rule <rule> exclude - - -Health checks -------------- - -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 - - vyos@vyos# set load-balancing wan interface-health <interface> - Possible completions: - failure-count Failure count - nexthop Outbound interface nexthop address. Can be 'dhcp or ip address' [REQUIRED] - success-count Success count - +> test Rule number - -Specify 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 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> - -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 - - vyos@vyos# set load-balancing wan interface-health eth1 test 0 - Possible completions: - resp-time Ping response time (seconds) - target Health target address - test-script Path to user defined script - ttl-limit Ttl limit (hop count) - type WLB test type - -* ``resp-time``: The maximum response time for ping in seconds. Range - 1-30, default ``5``. -* ``target``: The target to 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 ----------------- - -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 ------------------- -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 - - -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 - - set load-balancing wan sticky-connections inbound - -Failover --------- - -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 - -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 - - set load-balancing wan flush-connections - -.. warning:: - - Flushing the session table causes other connections to revert from - flow-based to packet-based balancing until each flow is reestablished. - -Script execution ----------------- - -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 - - set load-balancing wan hook script-name - -Two environment variables are available: - -* ``WLB_INTERFACE_NAME=[interfacename]``: Interface to be monitored -* ``WLB_INTERFACE_STATE=[ACTIVE|FAILED]``: Interface state - -.. warning:: - - Blocking call with no timeout: VyOS becomes unresponsive if the - script does not return. - -Handling and monitoring ------------------------ - - -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. - -.. code-block:: none - - vyos@vyos:~$ show wan-load-balance - Interface: eth0 - Status: failed - Last Status Change: Tue Jun 11 20:12:19 2019 - -Test: ping Target: - Last Interface Success: 55s - Last Interface Failure: 0s - # Interface Failure(s): 5 - - Interface: eth1 - Status: active - Last Status Change: Tue Jun 11 20:06:42 2019 - +Test: ping Target: - Last Interface Success: 0s - Last Interface Failure: 6m26s - # Interface Failure(s): 0 - -Show connection data of load balanced traffic: - -.. code-block:: none - - vyos@vyos:~$ show wan-load-balance connection - conntrack v1.4.2 (conntrack-tools): 3 flow entries have been shown. - Type State Src Dst Packets Bytes - tcp TIME_WAIT 10.1.1.13:38040 203.0.113.2:80 203.0.113.2 192.168.188.71 - udp 10.1.1.13:41891 198.51.100.3:53 198.51.100.3 192.168.188.71 - udp 10.1.1.13:55437 198.51.100.3:53 198.51.100.3 192.168.188.71 - -Restart -******* - -.. code-block:: none - - restart wan-load-balance diff --git a/docs/configuration/nat/rst-cgnat.rst b/docs/configuration/nat/rst-cgnat.rst deleted file mode 100644 index 1848d45e..00000000 --- a/docs/configuration/nat/rst-cgnat.rst +++ /dev/null @@ -1,196 +0,0 @@ -.. _cgnat: - -##### -CGNAT -##### - -:abbr:`CGNAT (Carrier-Grade Network Address Translation)` , also known as -Large-Scale NAT (LSN), is a type of network address translation used by -Internet Service Providers (ISPs) to enable multiple private IP addresses to -share a single public IP address. This technique helps to conserve the limited -IPv4 address space. -The 100.64.0.0/10 address block is reserved for use in carrier-grade NAT - -Overview -======== - -CGNAT works by placing a NAT device within the ISP's network. This device -translates private IP addresses from customer networks to a limited pool of -public IP addresses assigned to the ISP. This allows many customers to share a -smaller number of public IP addresses. - -Not all :rfc:`6888` requirements are implemented in CGNAT. - -Implemented the following :rfc:`6888` requirements: - -- REQ 2: A CGN must have a default "IP address pooling" behavior of "Paired". - CGN must use the same external IP address mapping for all sessions associated - with the same internal IP address, be they TCP, UDP, ICMP, something else, - or a mix of different protocols. -- REQ 3: The CGN function should not have any limitations on the size or the - contiguity of the external address pool. -- REQ 4: A CGN must support limiting the number of external ports (or, - equivalently, "identifiers" for ICMP) that are assigned per subscriber - -Advantages of CGNAT -------------------- - -- **IPv4 Address Conservation**: CGNAT helps mitigate the exhaustion of IPv4 addresses by allowing multiple customers to share a single public IP address. -- **Scalability**: ISPs can support more customers without needing a proportional increase in public IP addresses. -- **Cost-Effective**: Reduces the cost associated with acquiring additional public IPv4 addresses. - -Considerations --------------- - -- **Traceability Issues**: Since multiple users share the same public IP address, tracking individual users for security and legal purposes can be challenging. -- **Performance Overheads**: The translation process can introduce latency and potential performance bottlenecks, especially under high load. -- **Application Compatibility**: Some applications and protocols may not work well with CGNAT due to their reliance on unique public IP addresses. -- **Port Allocation Limits**: Each public IP address has a limited number of ports, which can be exhausted, affecting the ability to establish new connections. -- **Port Control Protocol**: PCP is not implemented. - -Port calculation -================ - -When implementing CGNAT, ensuring that there are enough ports allocated per subscriber is critical. Below is a summary based on RFC 6888. - -1. **Total Ports Available**: - - - Total Ports: 65536 (0 to 65535) - - Reserved Ports: Assume 1024 ports are reserved for well-known services and administrative purposes. - - Usable Ports: 65536 - 1024 = 64512 - -2. **Estimate Ports Needed per Subscriber**: - - - Example: A household might need 1000 ports to ensure smooth operation for multiple devices and applications. - -3. **Calculate the Number of Subscribers per Public IP**: - - - Usable Ports / Ports per Subscriber - - 64512 / 1000 ≈ 64 subscribers per public IP - - -Configuration -============= - -.. cfgcmd:: set nat cgnat pool external <pool-name> external-port-range <port-range> - - Set an external port-range for the external pool, the default range is - 1024-65535. Multiple entries can be added to the same pool. - -.. cfgcmd:: set nat cgnat pool external <pool-name> per-user-limit port <num> - - Set external source port limits that will be allocated to each subscriber - individually. The default value is 2000. - -.. cfgcmd:: set nat cgnat pool external <pool-name> range [address | address range | network] [seq] - - Set the range of external IP addresses for the CGNAT pool. - The sequence is optional; if set, a lower value means higher priority. - -.. cfgcmd:: set nat cgnat pool internal <pool-name> range [address range | network] - - Set the range of internal IP addresses for the CGNAT pool. - -.. cfgcmd:: set nat cgnat rule <num> source pool <internal-pool-name> - - Set the rule for the source pool. - -.. cfgcmd:: set nat cgnat rule <num> translation pool <external-pool-name> - - Set the rule for the translation pool. - -.. cfgcmd:: set nat cgnat log-allocation - - Enable logging of IP address and ports allocations. - - -Configuration Examples -====================== - -Single external address ------------------------ - -Example of setting up a basic CGNAT configuration: -In the following example, we define an external pool named `ext-1` with one external IP address - - -Each subscriber will be allocated a maximum of 2000 ports from the external pool. - -.. code-block:: none - - set nat cgnat pool external ext1 external-port-range '1024-65535' - set nat cgnat pool external ext1 per-user-limit port '2000' - set nat cgnat pool external ext1 range '192.0.2.222/32' - set nat cgnat pool internal int1 range '100.64.0.0/28' - set nat cgnat rule 10 source pool 'int1' - set nat cgnat rule 10 translation pool 'ext1' - -Multiple external addresses ---------------------------- - -.. code-block:: none - - set nat cgnat pool external ext1 external-port-range '1024-65535' - set nat cgnat pool external ext1 per-user-limit port '8000' - set nat cgnat pool external ext1 range '192.0.2.1-192.0.2.2' - set nat cgnat pool external ext1 range '203.0.113.253-203.0.113.254' - set nat cgnat pool internal int1 range '100.64.0.1-100.64.0.32' - set nat cgnat rule 10 source pool 'int1' - set nat cgnat rule 10 translation pool 'ext1' - -External address sequences ------------------------------------ - -.. code-block:: none - - set nat cgnat pool external ext-01 per-user-limit port '16000' - set nat cgnat pool external ext-01 range 203.0.113.1/32 seq '10' - set nat cgnat pool external ext-01 range 192.0.2.1/32 seq '20' - set nat cgnat pool internal int-01 range '100.64.0.0/29' - set nat cgnat rule 10 source pool 'int-01' - set nat cgnat rule 10 translation pool 'ext-01' - - -Operation commands -================== - -.. opcmd:: show nat cgnat allocation - - Show address and port allocations - -.. opcmd:: show nat cgnat allocation external-address <address> - - Show all allocations for an external IP address - -.. opcmd:: show nat cgnat allocation internal-address <address> - - Show all allocations for an internal IP address - -Show CGNAT allocations ----------------------- - -.. code-block:: none - - vyos@vyos:~$ show nat cgnat allocation - Internal IP External IP Port range - ------------- ------------- ------------ - 100.64.0.0 203.0.113.1 1024-17023 - 100.64.0.1 203.0.113.1 17024-33023 - 100.64.0.2 203.0.113.1 33024-49023 - 100.64.0.3 203.0.113.1 49024-65023 - 100.64.0.4 192.0.2.1 1024-17023 - 100.64.0.5 192.0.2.1 17024-33023 - 100.64.0.6 192.0.2.1 33024-49023 - 100.64.0.7 192.0.2.1 49024-65023 - - vyos@vyos:~$ show nat cgnat allocation internal-address 100.64.0.4 - Internal IP External IP Port range - ------------- ------------- ------------ - 100.64.0.4 192.0.2.1 1024-17023 - - -Further Reading -=============== - -- :rfc:`6598` - IANA-Reserved IPv4 Prefix for Shared Address Space -- :rfc:`6888` - Requirements for CGNAT diff --git a/docs/configuration/nat/rst-index.rst b/docs/configuration/nat/rst-index.rst deleted file mode 100644 index 2ecacc72..00000000 --- a/docs/configuration/nat/rst-index.rst +++ /dev/null @@ -1,14 +0,0 @@ -.. _nat: - -### -NAT -### - -.. toctree:: - :maxdepth: 1 - :includehidden: - - nat44 - nat64 - nat66 - cgnat diff --git a/docs/configuration/nat/rst-nat44.rst b/docs/configuration/nat/rst-nat44.rst deleted file mode 100644 index 63b787ba..00000000 --- a/docs/configuration/nat/rst-nat44.rst +++ /dev/null @@ -1,826 +0,0 @@ -.. _nat44: - -##### -NAT44 -##### - -:abbr:`NAT (Network Address Translation)` is a common method of -remapping one IP address space into another by modifying network address -information in the IP header of packets while they are in transit across -a traffic routing device. The technique was originally used as a -shortcut to avoid the need to readdress every host when a network was -moved. It has become a popular and essential tool in conserving global -address space in the face of IPv4 address exhaustion. One -Internet-routable IP address of a NAT gateway can be used for an entire -private network. - -IP masquerading is a technique that hides an entire IP address space, -usually consisting of private IP addresses, behind a single IP address -in another, usually public address space. The hidden addresses are -changed into a single (public) IP address as the source address of the -outgoing IP packets so they appear as originating not from the hidden -host but from the routing device itself. Because of the popularity of -this technique to conserve IPv4 address space, the term NAT has become -virtually synonymous with IP masquerading. - -As network address translation modifies the IP address information in -packets, NAT implementations may vary in their specific behavior in -various addressing cases and their effect on network traffic. The -specifics of NAT behavior are not commonly documented by vendors of -equipment containing NAT implementations. - -The computers on an internal network can use any of the addresses set -aside by the :abbr:`IANA (Internet Assigned Numbers Authority)` for -private addressing (see :rfc:`1918`). These reserved IP addresses are -not in use on the Internet, so an external machine will not directly -route to them. The following addresses are reserved for private use: - -* 10.0.0.0 to 10.255.255.255 (CIDR: 10.0.0.0/8) -* 172.16.0.0 to 172.31.255.255 (CIDR: 172.16.0.0/12) -* 192.168.0.0 to 192.168.255.255 (CIDR: 192.168.0.0/16) - - -If an ISP deploys a :abbr:`CGN (Carrier-grade NAT)`, and uses -:rfc:`1918` address space to number customer gateways, the risk of -address collision, and therefore routing failures, arises when the -customer network already uses an :rfc:`1918` address space. - -This prompted some ISPs to develop a policy within the :abbr:`ARIN -(American Registry for Internet Numbers)` to allocate new private -address space for CGNs, but ARIN deferred to the IETF before -implementing the policy indicating that the matter was not a typical -allocation issue but a reservation of addresses for technical purposes -(per :rfc:`2860`). - -IETF published :rfc:`6598`, detailing a shared address space for use in -ISP CGN deployments that can handle the same network prefixes occurring -both on inbound and outbound interfaces. ARIN returned address space to -the :abbr:`IANA (Internet Assigned Numbers Authority)` for this -allocation. - -The allocated address block is 100.64.0.0/10. - -Devices evaluating whether an IPv4 address is public must be updated to -recognize the new address space. Allocating more private IPv4 address -space for NAT devices might prolong the transition to IPv6. - -Overview -======== - -Different NAT Types -------------------- - -.. _source-nat: - -SNAT -^^^^ - -:abbr:`SNAT (Source Network Address Translation)` is the most common -form of :abbr:`NAT (Network Address Translation)` and is typically -referred to simply as NAT. To be more correct, what most people refer -to as :abbr:`NAT (Network Address Translation)` is actually the process -of :abbr:`PAT (Port Address Translation)`, or NAT overload. SNAT is -typically used by internal users/private hosts to access the Internet -- the source address is translated and thus kept private. - -.. _destination-nat: - -DNAT -^^^^ - -:abbr:`DNAT (Destination Network Address Translation)` changes the -destination address of packets passing through the router, while -:ref:`source-nat` changes the source address of packets. DNAT is -typically used when an external (public) host needs to initiate a -session with an internal (private) host. A customer needs to access a -private service behind the routers public IP. A connection is -established with the routers public IP address on a well known port and -thus all traffic for this port is rewritten to address the internal -(private) host. - -.. _bidirectional-nat: - -Bidirectional NAT -^^^^^^^^^^^^^^^^^ - -This is a common scenario where both :ref:`source-nat` and -:ref:`destination-nat` are configured at the same time. It's commonly -used when internal (private) hosts need to establish a connection with -external resources and external systems need to access internal -(private) resources. - -NAT, Routing, Firewall Interaction ----------------------------------- - -There is a very nice picture/explanation in the Vyatta documentation -which should be rewritten here. - -NAT Ruleset ------------ - -:abbr:`NAT (Network Address Translation)` is configured entirely on a -series of so called `rules`. Rules are numbered and evaluated by the -underlying OS in numerical order! The rule numbers can be changes by -utilizing the :cfgcmd:`rename` and :cfgcmd:`copy` commands. - -.. note:: Changes to the NAT system only affect newly established - connections. Already established connections are not affected. - -.. hint:: When designing your NAT ruleset leave some space between - consecutive rules for later extension. Your ruleset could start with - numbers 10, 20, 30. You thus can later extend the ruleset and place - new rules between existing ones. - -Rules will be created for both :ref:`source-nat` and -:ref:`destination-nat`. - -For :ref:`bidirectional-nat` a rule for both :ref:`source-nat` and -:ref:`destination-nat` needs to be created. - -.. _traffic-filters: - -Traffic Filters ---------------- - -Traffic Filters are used to control which packets will have the defined -NAT rules applied. Five different filters can be applied within a NAT -rule. - -* **outbound-interface** - applicable only to :ref:`source-nat`. It - configures the interface which is used for the outside traffic that - this translation rule applies to. Interface groups, inverted - selection and wildcard, are also supported. - - Examples: - - .. code-block:: none - - set nat source rule 20 outbound-interface name eth0 - set nat source rule 30 outbound-interface name bond1* - set nat source rule 20 outbound-interface name !vtun2 - set nat source rule 20 outbound-interface group GROUP1 - set nat source rule 20 outbound-interface group !GROUP2 - - -* **inbound-interface** - applicable only to :ref:`destination-nat`. It - configures the interface which is used for the inside traffic the - translation rule applies to. Interface groups, inverted - selection and wildcard, are also supported. - - Example: - - .. code-block:: none - - set nat destination rule 20 inbound-interface name eth0 - set nat destination rule 30 inbound-interface name bond1* - set nat destination rule 20 inbound-interface name !vtun2 - set nat destination rule 20 inbound-interface group GROUP1 - set nat destination rule 20 inbound-interface group !GROUP2 - - -* **protocol** - specify which types of protocols this translation rule - applies to. Only packets matching the specified protocol are NATed. - By default this applies to `all` protocols. - - Example: - - * Set SNAT rule 20 to only NAT TCP and UDP packets - * Set DNAT rule 20 to only NAT UDP packets - - .. code-block:: none - - set nat source rule 20 protocol tcp_udp - set nat destination rule 20 protocol udp - -* **source** - specifies which packets the NAT translation rule applies - to based on the packets source IP address and/or source port. Only - matching packets are considered for NAT. - - Example: - - * Set SNAT rule 20 to only NAT packets arriving from the 192.0.2.0/24 - network - * Set SNAT rule 30 to only NAT packets arriving from the 203.0.113.0/24 - network with a source port of 80 and 443 - - .. code-block:: none - - set nat source rule 20 source address 192.0.2.0/24 - set nat source rule 30 source address 203.0.113.0/24 - set nat source rule 30 source port 80,443 - - -* **destination** - specify which packets the translation will be - applied to, only based on the destination address and/or port number - configured. - - .. note:: If no destination is specified the rule will match on any - destination address and port. - - Example: - - * Configure SNAT rule (40) to only NAT packets with a destination - address of 192.0.2.1. - - .. code-block:: none - - set nat source rule 40 destination address 192.0.2.1 - - -Address Conversion ------------------- - -Every NAT rule has a translation command defined. The address defined -for the translation is the address used when the address information in -a packet is replaced. - -Source Address -^^^^^^^^^^^^^^ - -For :ref:`source-nat` rules the packets source address will be replaced -with the address specified in the translation command. A port -translation can also be specified and is part of the translation -address. - -.. note:: The translation address must be set to one of the available - addresses on the configured `outbound-interface` or it must be set to - `masquerade` which will use the primary IP address of the - `outbound-interface` as its translation address. - -.. note:: When using NAT for a large number of host systems it - recommended that a minimum of 1 IP address is used to NAT every 256 - private host systems. This is due to the limit of 65,000 port numbers - available for unique translations and a reserving an average of - 200-300 sessions per host system. - -Example: - -* Define a discrete source IP address of 100.64.0.1 for SNAT rule 20 -* Use address `masquerade` (the interfaces primary address) on rule 30 -* For a large amount of private machines behind the NAT your address - pool might to be bigger. Use any address in the range 100.64.0.10 - - 100.64.0.20 on SNAT rule 40 when doing the translation - - -.. code-block:: none - - set nat source rule 20 translation address 100.64.0.1 - set nat source rule 30 translation address 'masquerade' - set nat source rule 40 translation address 100.64.0.10-100.64.0.20 - - -Destination Address -^^^^^^^^^^^^^^^^^^^ - -For :ref:`destination-nat` rules the packets destination address will be -replaced by the specified address in the `translation address` command. - -Example: - -* DNAT rule 10 replaces the destination address of an inbound packet - with 192.0.2.10 - -.. code-block:: none - - set nat destination rule 10 translation address 192.0.2.10 - - -Also, in :ref:`destination-nat`, redirection to localhost is supported. -The redirect statement is a special form of dnat which always translates -the destination address to the local host’s one. - -Example of redirection: - -.. code-block:: none - - set nat destination rule 10 translation redirect port 22 - -NAT Load Balance ----------------- - -Advanced configuration can be used in order to apply source or destination NAT, -and within a single rule, be able to define multiple translated addresses, -so NAT balances the translations among them. - -NAT Load Balance uses an algorithm that generates a hash and based on it, then -it applies corresponding translation. This hash can be generated randomly, or -can use data from the ip header: source-address, destination-address, -source-port and/or destination-port. By default, it will generate the hash -randomly. - -When defining the translated address, called ``backends``, a ``weight`` must -be configured. This lets the user define load balance distribution according -to their needs. Them sum of all the weights defined for the backends should -be equal to 100. In oder words, the weight defined for the backend is the -percentage of the connections that will receive such backend. - -.. cfgcmd:: set nat [source | destination] rule <rule> load-balance hash - [source-address | destination-address | source-port | destination-port - | random] -.. cfgcmd:: set nat [source | destination] rule <rule> load-balance backend - <x.x.x.x> weight <1-100> - - -Configuration Examples -====================== - -To setup SNAT, we need to know: - -* The internal IP addresses we want to translate -* The outgoing interface to perform the translation on -* The external IP address to translate to - -In the example used for the Quick Start configuration above, we -demonstrate the following configuration: - -.. code-block:: none - - set nat source rule 100 outbound-interface name 'eth0' - set nat source rule 100 source address '192.168.0.0/24' - set nat source rule 100 translation address 'masquerade' - -Which generates the following configuration: - -.. code-block:: none - - rule 100 { - outbound-interface { - name eth0 - } - source { - address 192.168.0.0/24 - } - translation { - address masquerade - } - } - -In this example, we use **masquerade** as the translation address -instead of an IP address. The **masquerade** target is effectively an -alias to say "use whatever IP address is on the outgoing interface", -rather than a statically configured IP address. This is useful if you -use DHCP for your outgoing interface and do not know what the external -address will be. - -When using NAT for a large number of host systems it recommended that a -minimum of 1 IP address is used to NAT every 256 host systems. This is -due to the limit of 65,000 port numbers available for unique -translations and a reserving an average of 200-300 sessions per host -system. - -Example: For an ~8,000 host network a source NAT pool of 32 IP addresses -is recommended. - -A pool of addresses can be defined by using a hyphen between two IP -addresses: - -.. code-block:: none - - set nat source rule 100 translation address '203.0.113.32-203.0.113.63' - -.. _avoidng_leaky_nat: - -Avoiding "leaky" NAT --------------------- - -Linux netfilter will not NAT traffic marked as INVALID. This often -confuses people into thinking that Linux (or specifically VyOS) has a -broken NAT implementation because non-NATed traffic is seen leaving an -external interface. This is actually working as intended, and a packet -capture of the "leaky" traffic should reveal that the traffic is either -an additional TCP "RST", "FIN,ACK", or "RST,ACK" sent by client systems -after Linux netfilter considers the connection closed. The most common -is the additional TCP RST some host implementations send after -terminating a connection (which is implementation-specific). - -In other words, connection tracking has already observed the connection -be closed and has transition the flow to INVALID to prevent attacks from -attempting to reuse the connection. - -You can avoid the "leaky" behavior by using a firewall policy that drops -"invalid" state packets. - -Having control over the matching of INVALID state traffic, e.g. the -ability to selectively log, is an important troubleshooting tool for -observing broken protocol behavior. For this reason, VyOS does not -globally drop invalid state traffic, instead allowing the operator to -make the determination on how the traffic is handled. - -.. _hairpin_nat_reflection: - -Hairpin NAT/NAT Reflection --------------------------- - -A typical problem with using NAT and hosting public servers is the -ability for internal systems to reach an internal server using it's -external IP address. The solution to this is usually the use of -split-DNS to correctly point host systems to the internal address when -requests are made internally. Because many smaller networks lack DNS -infrastructure, a work-around is commonly deployed to facilitate the -traffic by NATing the request from internal hosts to the source address -of the internal interface on the firewall. - -This technique is commonly referred to as NAT Reflection or Hairpin NAT. - -Example: - -* Redirect Microsoft RDP traffic from the outside (WAN, external) world - via :ref:`destination-nat` in rule 100 to the internal, private host - 192.0.2.40. - -* Redirect Microsoft RDP traffic from the internal (LAN, private) - network via :ref:`destination-nat` in rule 110 to the internal, - private host 192.0.2.40. We also need a :ref:`source-nat` rule 110 for - the reverse path of the traffic. The internal network 192.0.2.0/24 is - reachable via interface `eth0.10`. - -.. code-block:: none - - set nat destination rule 100 description 'Regular destination NAT from external' - set nat destination rule 100 destination port '3389' - set nat destination rule 100 inbound-interface name 'pppoe0' - set nat destination rule 100 protocol 'tcp' - set nat destination rule 100 translation address '192.0.2.40' - - set nat destination rule 110 description 'NAT Reflection: INSIDE' - set nat destination rule 110 destination port '3389' - set nat destination rule 110 inbound-interface name 'eth0.10' - set nat destination rule 110 protocol 'tcp' - set nat destination rule 110 translation address '192.0.2.40' - - set nat source rule 110 description 'NAT Reflection: INSIDE' - set nat source rule 110 destination address '192.0.2.0/24' - set nat source rule 110 outbound-interface name 'eth0.10' - set nat source rule 110 protocol 'tcp' - set nat source rule 110 source address '192.0.2.0/24' - set nat source rule 110 translation address 'masquerade' - -Which results in a configuration of: - -.. code-block:: none - - vyos@vyos# show nat - destination { - rule 100 { - description "Regular destination NAT from external" - destination { - port 3389 - } - inbound-interface { - name pppoe0 - } - protocol tcp - translation { - address 192.0.2.40 - } - } - rule 110 { - description "NAT Reflection: INSIDE" - destination { - port 3389 - } - inbound-interface { - name eth0.10 - } - protocol tcp - translation { - address 192.0.2.40 - } - } - } - source { - rule 110 { - description "NAT Reflection: INSIDE" - destination { - address 192.0.2.0/24 - } - outbound-interface { - name eth0.10 - } - protocol tcp - source { - address 192.0.2.0/24 - } - translation { - address masquerade - } - } - } - - -Destination NAT ---------------- - -DNAT is typically referred to as a **Port Forward**. When using VyOS as -a NAT router and firewall, a common configuration task is to redirect -incoming traffic to a system behind the firewall. - -In this example, we will be using the example Quick Start configuration -above as a starting point. - -To setup a destination NAT rule we need to gather: - -* The interface traffic will be coming in on; -* The protocol and port we wish to forward; -* The IP address of the internal system we wish to forward traffic to. - -In our example, we will be forwarding web server traffic to an internal -web server on 192.168.0.100. HTTP traffic makes use of the TCP protocol -on port 80. For other common port numbers, see: -https://en.wikipedia.org/wiki/List_of_TCP_and_UDP_port_numbers - -Our configuration commands would be: - -.. code-block:: none - - set nat destination rule 10 description 'Port Forward: HTTP to 192.168.0.100' - set nat destination rule 10 destination port '80' - set nat destination rule 10 inbound-interface name 'eth0' - set nat destination rule 10 protocol 'tcp' - set nat destination rule 10 translation address '192.168.0.100' - -Which would generate the following NAT destination configuration: - -.. code-block:: none - - nat { - destination { - rule 10 { - description "Port Forward: HTTP to 192.168.0.100" - destination { - port 80 - } - inbound-interface { - name eth0 - } - protocol tcp - translation { - address 192.168.0.100 - } - } - } - } - -.. note:: If forwarding traffic to a different port than it is arriving - on, you may also configure the translation port using - `set nat destination rule [n] translation port`. - -This establishes our Port Forward rule, but if we created a firewall -policy it will likely block the traffic. - -Firewall rules for Destination NAT -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -It is important to note that when creating firewall rules, the DNAT -translation occurs **before** traffic traverses the firewall. In other -words, the destination address has already been translated to -192.168.0.100. - -So in our firewall ruleset, we want to allow traffic which previously matched -a destination nat rule. In order to avoid creating many rules, one for each -destination nat rule, we can accept all **'dnat'** connections with one simple -rule, using ``connection-status`` matcher: - -.. code-block:: none - - set firewall ipv4 forward filter rule 10 action accept - set firewall ipv4 forward filter rule 10 connection-status nat destination - set firewall ipv4 forward filter rule 10 state new - -This would generate the following configuration: - -.. code-block:: none - - ipv4 { - forward { - filter { - rule 10 { - action accept - connection-status { - nat destination - } - state new - } - } - } - } - - -1-to-1 NAT ----------- - -Another term often used for DNAT is **1-to-1 NAT**. For a 1-to-1 NAT -configuration, both DNAT and SNAT are used to NAT all traffic from an -external IP address to an internal IP address and vice-versa. - -Typically, a 1-to-1 NAT rule omits the destination port (all ports) and -replaces the protocol with either **all** or **ip**. - -Then a corresponding SNAT rule is created to NAT outgoing traffic for -the internal IP to a reserved external IP. This dedicates an external IP -address to an internal IP address and is useful for protocols which -don't have the notion of ports, such as GRE. - -Here's an extract of a simple 1-to-1 NAT configuration with one internal -and one external interface: - -.. code-block:: none - - set interfaces ethernet eth0 address '192.168.1.1/24' - set interfaces ethernet eth0 description 'Inside interface' - set interfaces ethernet eth1 address '192.0.2.30/24' - set interfaces ethernet eth1 description 'Outside interface' - set nat destination rule 2000 description '1-to-1 NAT example' - set nat destination rule 2000 destination address '192.0.2.30' - set nat destination rule 2000 inbound-interface name 'eth1' - set nat destination rule 2000 translation address '192.168.1.10' - set nat source rule 2000 description '1-to-1 NAT example' - set nat source rule 2000 outbound-interface name 'eth1' - set nat source rule 2000 source address '192.168.1.10' - set nat source rule 2000 translation address '192.0.2.30' - -Firewall rules are written as normal, using the internal IP address as -the source of outbound rules and the destination of inbound rules. - -NAT before VPN --------------- - -Some application service providers (ASPs) operate a VPN gateway to -provide access to their internal resources, and require that a -connecting organisation translate all traffic to the service provider -network to a source address provided by the ASP. - -Load Balance ------------- -Here we provide two examples on how to apply NAT Load Balance. - -First scenario: apply destination NAT for all HTTP traffic comming through -interface eth0, and user 4 backends. First backend should received 30% of -the request, second backend should get 20%, third 15% and the fourth 35% -We will use source and destination address for hash generation. - -.. code-block:: none - - set nat destination rule 10 inbound-interface name eth0 - set nat destination rule 10 protocol tcp - set nat destination rule 10 destination port 80 - set nat destination rule 10 load-balance hash source-address - set nat destination rule 10 load-balance hash destination-address - set nat destination rule 10 load-balance backend 198.51.100.101 weight 30 - set nat destination rule 10 load-balance backend 198.51.100.102 weight 20 - set nat destination rule 10 load-balance backend 198.51.100.103 weight 15 - set nat destination rule 10 load-balance backend 198.51.100.104 weight 35 - -Second scenario: apply source NAT for all outgoing connections from -LAN 10.0.0.0/8, using 3 public addresses and equal distribution. -We will generate the hash randomly. - -.. code-block:: none - - set nat source rule 10 outbound-interface name eth0 - set nat source rule 10 source address 10.0.0.0/8 - set nat source rule 10 load-balance hash random - set nat source rule 10 load-balance backend 192.0.2.251 weight 33 - set nat source rule 10 load-balance backend 192.0.2.252 weight 33 - set nat source rule 10 load-balance backend 192.0.2.253 weight 34 - -Example Network -^^^^^^^^^^^^^^^ - -Here's one example of a network environment for an ASP. -The ASP requests that all connections from this company should come from -172.29.41.89 - an address that is assigned by the ASP and not in use at -the customer site. - -.. figure:: /_static/images/nat_before_vpn_topology.* - :scale: 100 % - :alt: NAT before VPN Topology - - NAT before VPN Topology - - -Configuration -^^^^^^^^^^^^^ - -The required configuration can be broken down into 4 major pieces: - -* A dummy interface for the provider-assigned IP; -* NAT (specifically, Source NAT); -* IPSec IKE and ESP Groups; -* IPSec VPN tunnels. - - -Dummy interface -""""""""""""""" - -The dummy interface allows us to have an equivalent of the Cisco IOS -Loopback interface - a router-internal interface we can use for IP -addresses the router must know about, but which are not actually -assigned to a real network. - -We only need a single step for this interface: - -.. code-block:: none - - set interfaces dummy dum0 address '172.29.41.89/32' - -NAT Configuration -""""""""""""""""" - -.. code-block:: none - - set nat source rule 110 description 'Internal to ASP' - set nat source rule 110 destination address '172.27.1.0/24' - set nat source rule 110 source address '192.168.43.0/24' - set nat source rule 110 translation address '172.29.41.89' - set nat source rule 120 description 'Internal to ASP' - set nat source rule 120 destination address '10.125.0.0/16' - set nat source rule 120 source address '192.168.43.0/24' - set nat source rule 120 translation address '172.29.41.89' - -IPSec IKE and ESP -""""""""""""""""" - -The ASP has documented their IPSec requirements: - -* IKE Phase: - - * aes256 Encryption - * sha256 Hashes - -* ESP Phase: - - * aes256 Encryption - * sha256 Hashes - * DH Group 14 - - -Additionally, we want to use VPNs only on our eth1 interface (the -external interface in the image above) - -.. code-block:: none - - set vpn ipsec ike-group my-ike key-exchange 'ikev1' - set vpn ipsec ike-group my-ike lifetime '7800' - set vpn ipsec ike-group my-ike proposal 1 dh-group '14' - set vpn ipsec ike-group my-ike proposal 1 encryption 'aes256' - set vpn ipsec ike-group my-ike proposal 1 hash 'sha256' - - set vpn ipsec esp-group my-esp lifetime '3600' - set vpn ipsec esp-group my-esp mode 'tunnel' - set vpn ipsec esp-group my-esp pfs 'disable' - set vpn ipsec esp-group my-esp proposal 1 encryption 'aes256' - set vpn ipsec esp-group my-esp proposal 1 hash 'sha256' - - set vpn ipsec interface 'eth1' - -IPSec VPN Tunnels -""""""""""""""""" - -We'll use the IKE and ESP groups created above for this VPN. Because we -need access to 2 different subnets on the far side, we will need two -different tunnels. If you changed the names of the ESP group and IKE -group in the previous step, make sure you use the correct names here -too. - -.. code-block:: none - - set vpn ipsec authentication psk vyos id '203.0.113.46' - set vpn ipsec authentication psk vyos id '198.51.100.243' - set vpn ipsec authentication psk vyos secret 'MYSECRETPASSWORD' - set vpn ipsec site-to-site peer branch authentication local-id '203.0.113.46' - set vpn ipsec site-to-site peer branch authentication mode 'pre-shared-secret' - set vpn ipsec site-to-site peer branch authentication remote-id '198.51.100.243' - set vpn ipsec site-to-site peer branch connection-type 'initiate' - set vpn ipsec site-to-site peer branch default-esp-group 'my-esp' - set vpn ipsec site-to-site peer branch ike-group 'my-ike' - set vpn ipsec site-to-site peer branch ikev2-reauth 'inherit' - set vpn ipsec site-to-site peer branch local-address '203.0.113.46' - set vpn ipsec site-to-site peer branch remote-address '198.51.100.243' - set vpn ipsec site-to-site peer branch tunnel 0 local prefix '172.29.41.89/32' - set vpn ipsec site-to-site peer branch tunnel 0 remote prefix '172.27.1.0/24' - set vpn ipsec site-to-site peer branch tunnel 1 local prefix '172.29.41.89/32' - set vpn ipsec site-to-site peer branch tunnel 1 remote prefix '10.125.0.0/16' - -Testing and Validation -"""""""""""""""""""""" - -If you've completed all the above steps you no doubt want to see if it's -all working. - -Start by checking for IPSec SAs (Security Associations) with: - -.. code-block:: none - - $ show vpn ipsec sa - - Peer ID / IP Local ID / IP - ------------ ------------- - 198.51.100.243 203.0.113.46 - - Tunnel State Bytes Out/In Encrypt Hash NAT-T A-Time L-Time Proto - ------ ----- ------------- ------- ---- ----- ------ ------ ----- - 0 up 0.0/0.0 aes256 sha256 no 1647 3600 all - 1 up 0.0/0.0 aes256 sha256 no 865 3600 all - -That looks good - we defined 2 tunnels and they're both up and running. diff --git a/docs/configuration/nat/rst-nat64.rst b/docs/configuration/nat/rst-nat64.rst deleted file mode 100644 index 04ba56f4..00000000 --- a/docs/configuration/nat/rst-nat64.rst +++ /dev/null @@ -1,85 +0,0 @@ -.. _nat64: - -##### -NAT64 -##### - -:abbr:`NAT64 (IPv6-to-IPv4 Prefix Translation)` is a critical component in -modern networking, facilitating communication between IPv6 and IPv4 networks. -This documentation outlines the setup, configuration, and usage of the NAT64 -feature in your project. Whether you are transitioning to IPv6 or need to -seamlessly connect IPv4 and IPv6 devices. -NAT64 is a stateful translation mechanism that translates IPv6 addresses to -IPv4 addresses and IPv4 addresses to IPv6 addresses. NAT64 is used to enable -IPv6-only clients to contact IPv4 servers using unicast UDP, TCP, or ICMP. - - -Overview -======== - -Different NAT Types -------------------- - -.. _source-nat64: - -SNAT64 -^^^^^^ - -:abbr:`SNAT64 (IPv6-to-IPv4 Source Address Translation)` is a stateful -translation mechanism that translates IPv6 addresses to IPv4 addresses. - -``64:ff9b::/96`` is the well-known prefix for IPv4-embedded IPv6 addresses. -The prefix is used to represent IPv4 addresses in an IPv6 address format. -The IPv4 address is encoded in the low-order 32 bits of the IPv6 address. -The high-order 32 bits are set to the well-known prefix 64:ff9b::/96. - - -Configuration Examples -====================== - -The following examples show how to configure NAT64 on a VyOS router. -The 192.0.2.10 address is used as the IPv4 address for the translation pool. - - -NAT64 server configuration: - -.. code-block:: none - - set interfaces ethernet eth0 address '192.0.2.1/24' - set interfaces ethernet eth0 address '192.0.2.10/24' - set interfaces ethernet eth0 description 'WAN' - set interfaces ethernet eth1 address '2001:db8::1/64' - set interfaces ethernet eth1 description 'LAN' - - set service dns forwarding allow-from '2001:db8::/64' - set service dns forwarding dns64-prefix '64:ff9b::/96' - set service dns forwarding listen-address '2001:db8::1' - - set nat64 source rule 100 source prefix '64:ff9b::/96' - set nat64 source rule 100 translation pool 10 address '192.0.2.10' - set nat64 source rule 100 translation pool 10 port '1-65535' - -NAT64 client configuration: - -.. code-block:: none - - set interfaces ethernet eth1 address '2001:db8::2/64' - set protocols static route6 64:ff9b::/96 next-hop 2001:db8::1 - set system name-server '2001:db8::1' - -Test from the IPv6 only client: - -.. stop_vyoslinter - -.. code-block:: none - - vyos@r1:~$ ping 64:ff9b::192.0.2.1 count 2 - PING 64:ff9b::192.0.2.1(64:ff9b::c000:201) 56 data bytes - 64 bytes from 64:ff9b::c000:201: icmp_seq=1 ttl=63 time=0.351 ms - 64 bytes from 64:ff9b::c000:201: icmp_seq=2 ttl=63 time=0.373 ms - - --- 64:ff9b::192.0.2.1 ping statistics --- - 2 packets transmitted, 2 received, 0% packet loss, time 1023ms - rtt min/avg/max/mdev = 0.351/0.362/0.373/0.011 ms - -.. start_vyoslinter diff --git a/docs/configuration/nat/rst-nat66.rst b/docs/configuration/nat/rst-nat66.rst deleted file mode 100644 index aecce524..00000000 --- a/docs/configuration/nat/rst-nat66.rst +++ /dev/null @@ -1,256 +0,0 @@ -.. _nat66: - -############ -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. -We call this address translation method NAT66. Devices that support the NAT66 -function are called NAT66 devices, which can provide NAT66 source -and destination address translation functions. - -Overview -======== - -Different NAT Types -------------------- - -.. _source-nat66: - -SNAT66 -^^^^^^ - -:abbr:`SNPTv6 (Source IPv6-to-IPv6 Network Prefix Translation)` The conversion -function is mainly used in the following scenarios: - -* A single internal network and external network. Use the NAT66 device to - connect a single internal network and public network, and the hosts in - the internal network use IPv6 address prefixes that only support - routing within the local range. When a host in the internal network - accesses the external network, the source IPv6 address prefix in - the message will be converted into a global unicast IPv6 address - prefix by the NAT66 device. -* Redundancy and load sharing. There are multiple NAT66 devices at the edge - of an IPv6 network to another IPv6 network. The path through the NAT66 - device to another IPv6 network forms an equivalent route, and traffic - can be load-shared on these NAT66 devices. In this case, you - can configure the same source address translation rules on these - NAT66 devices, so that any NAT66 device can handle IPv6 traffic between - different sites. -* Multi-homed. In a multi-homed network environment, the NAT66 device - connects to an internal network and simultaneously connects to - different external networks. Address translation can be configured - on each external network side interface of the NAT66 device to - convert the same internal network address into different external - network addresses, and realize the mapping of the same internal - address to multiple external addresses. - -.. _destination-nat66: - -DNAT66 -^^^^^^ - -The :abbr:`DNPTv6 (Destination IPv6-to-IPv6 Network Prefix Translation)` -destination address translation function is used in scenarios where the -server in the internal network provides services to the external network, -such as providing Web services or FTP services to the external network. -By configuring the mapping relationship between the internal server -address and the external network address on the external network -side interface of the NAT66 device, external network users can -access the internal network server through the designated -external network address. - -Prefix Conversion ------------------- - -Source Prefix -^^^^^^^^^^^^^ - -Every SNAT66 rule has a translation command defined. The prefix defined -for the translation is the prefix used when the address information in -a packet is replaced.、 - -The :ref:`source-nat66` rule replaces the source address of the packet -and calculates the converted address using the prefix specified in the rule. - -Example: - -* Convert the address prefix of a single `fc01::/64` network to `fc00::/64` -* Output from `eth0` network interface - -.. code-block:: none - - set nat66 source rule 1 outbound-interface name 'eth0' - set nat66 source rule 1 source prefix 'fc01::/64' - set nat66 source rule 1 translation address 'fc00::/64' - -Destination Prefix -^^^^^^^^^^^^^^^^^^ - -For the :ref:`destination-nat66` rule, the destination address of -the packet isreplaced by the address calculated from the specified -address or prefix in the `translation address` command - -Example: - -* Convert the address prefix of a single `fc00::/64` network - to `fc01::/64` -* Input from `eth0` network interface - -.. code-block:: none - - set nat66 destination rule 1 inbound-interface name 'eth0' - set nat66 destination rule 1 destination address 'fc00::/64' - set nat66 destination rule 1 translation address 'fc01::/64' - -For the destination, groups can also be used instead of an address. - -Example: - -.. code-block:: none - - set firewall group ipv6-address-group ADR-INSIDE-v6 address fc00::1 - - set nat66 destination rule 1 inbound-interface name 'eth0' - set nat66 destination rule 1 destination group address-group ADR-INSIDE-v6 - set nat66 destination rule 1 translation address 'fc01::/64' - -Configuration Examples -====================== - -Use the following topology to build a nat66 based isolated -network between internal and external networks (dynamic prefix is -not supported): - -.. figure:: /_static/images/vyos_1_4_nat66_simple.* - :alt: VyOS NAT66 Simple Configure - -R1: - -.. code-block:: none - - set interfaces ethernet eth0 ipv6 address autoconf - set interfaces ethernet eth1 address 'fc01::1/64' - set nat66 destination rule 1 destination address 'fc00:470:f1cd:101::/64' - set nat66 destination rule 1 inbound-interface name 'eth0' - set nat66 destination rule 1 translation address 'fc01::/64' - set nat66 source rule 1 outbound-interface name 'eth0' - set nat66 source rule 1 source prefix 'fc01::/64' - set nat66 source rule 1 translation address 'fc00:470:f1cd:101::/64' - -R2: - -.. code-block:: none - - set interfaces bridge br1 address 'fc01::2/64' - set interfaces bridge br1 member interface eth0 - set interfaces bridge br1 member interface eth1 - set protocols static route6 ::/0 next-hop fc01::1 - set service router-advert interface br1 prefix ::/0 - - -Use the following topology to translate internal user local addresses -(``fc::/7``) to DHCPv6-PD provided prefixes from an ISP connected to -a VyOS HA pair. - -.. figure:: /_static/images/vyos_1_5_nat66_dhcpv6_wdummy.* - :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' - set interfaces bonding bond0 vif 20 dhcpv6-options pd 0 interface dum1 address '0' - set interfaces bonding bond0 vif 20 dhcpv6-options pd 1 interface dum1 address '0' - set interfaces bonding bond0 vif 20 dhcpv6-options pd 2 interface dum1 address '0' - set interfaces bonding bond0 vif 20 dhcpv6-options pd 3 interface dum1 address '0' - set interfaces bonding bond0 vif 20 dhcpv6-options rapid-commit - commit - -.. start_vyoslinter - -Get the DHCPv6-PD prefixes from both routers: - -.. code-block:: none - - trae@cr01a-vyos# run show interfaces dummy dum1 br - Codes: S - State, L - Link, u - Up, D - Down, A - Admin Down - Interface IP Address S/L Description - --------- ---------- --- ----------- - dum1 2001:db8:123:b008::/64 u/u DHCPv6-PD NPT dummy - 2001:db8:123:b00a::/64 - 2001:db8:123:b00b::/64 - 2001:db8:123:b009::/64 - - trae@cr01b-vyos# run show int dummy dum1 brief - Codes: S - State, L - Link, u - Up, D - Down, A - Admin Down - Interface IP Address S/L Description - --------- ---------- --- ----------- - dum1 2001:db8:123:b00d::/64 u/u DHCPv6-PD NPT dummy - 2001:db8:123:b00c::/64 - 2001:db8:123:b00e::/64 - 2001:db8:123:b00f::/64 - -Configure the A-side router for NPTv6 using the prefixes above: - -.. code-block:: none - - set nat66 source rule 10 description 'NPT to VLAN 10' - set nat66 source rule 10 outbound-interface name 'bond0.20' - set nat66 source rule 10 source prefix 'fd52:d62e:8011:a::/64' - set nat66 source rule 10 translation address '2001:db8:123:b008::/64' - set nat66 source rule 20 description 'NPT to VLAN 70' - set nat66 source rule 20 outbound-interface name 'bond0.20' - set nat66 source rule 20 source prefix 'fd52:d62e:8011:46::/64' - set nat66 source rule 20 translation address '2001:db8:123:b009::/64' - set nat66 source rule 30 description 'NPT to VLAN 200' - set nat66 source rule 30 outbound-interface name 'bond0.20' - set nat66 source rule 30 source prefix 'fd52:d62e:8011:c8::/64' - set nat66 source rule 30 translation address '2001:db8:123:b00a::/64' - set nat66 source rule 40 description 'NPT to VLAN 240' - set nat66 source rule 40 outbound-interface name 'bond0.20' - set nat66 source rule 40 source prefix 'fd52:d62e:8011:f0::/64' - set nat66 source rule 40 translation address '2001:db8:123:b00b::/64' - commit - -Configure the B-side router for NPTv6 using the prefixes above: - -.. code-block:: none - - set nat66 source rule 10 description 'NPT to VLAN 10' - set nat66 source rule 10 outbound-interface name 'bond0.20' - set nat66 source rule 10 source prefix 'fd52:d62e:8011:a::/64' - set nat66 source rule 10 translation address '2001:db8:123:b00c::/64' - set nat66 source rule 20 description 'NPT to VLAN 70' - set nat66 source rule 20 outbound-interface name 'bond0.20' - set nat66 source rule 20 source prefix 'fd52:d62e:8011:46::/64' - set nat66 source rule 20 translation address '2001:db8:123:b00d::/64' - set nat66 source rule 30 description 'NPT to VLAN 200' - set nat66 source rule 30 outbound-interface name 'bond0.20' - set nat66 source rule 30 source prefix 'fd52:d62e:8011:c8::/64' - set nat66 source rule 30 translation address '2001:db8:123:b00e::/64' - set nat66 source rule 40 description 'NPT to VLAN 240' - set nat66 source rule 40 outbound-interface name 'bond0.20' - set nat66 source rule 40 source prefix 'fd52:d62e:8011:f0::/64' - set nat66 source rule 40 translation address '2001:db8:123:b00f::/64' - commit - -Verify that connections are hitting the rule on both sides: - -.. code-block:: none - - trae@cr01a-vyos# run show nat66 source statistics - Rule Packets Bytes Interface - ------ --------- ------- ----------- - 10 1 104 bond0.20 - 20 1 104 bond0.20 - 30 8093 669445 bond0.20 - 40 2446 216912 bond0.20 diff --git a/docs/configuration/pki/rst-index.rst b/docs/configuration/pki/rst-index.rst deleted file mode 100644 index cad80f25..00000000 --- a/docs/configuration/pki/rst-index.rst +++ /dev/null @@ -1,488 +0,0 @@ -:lastproofread: 2024-01-05 - -.. include:: /_include/need_improvement.txt - -.. _pki: - -### -PKI -### - -VyOS 1.4 changed the way in how encryption keys or certificates are stored on the -system. In the pre VyOS 1.4 era, certificates got stored under /config and every -service referenced a file. That made copying a running configuration from system -A to system B a bit harder, as you had to copy the files and their permissions -by hand. - -:vytask:`T3642` describes a new CLI subsystem that serves as a "certstore" to -all services requiring any kind of encryption key(s). In short, public and -private certificates are now stored in PKCS#8 format in the regular VyOS CLI. -Keys can now be added, edited, and deleted using the regular set/edit/delete -CLI commands. - -VyOS not only can now manage certificates issued by 3rd party Certificate -Authorities, it can also act as a CA on its own. You can create your own root -CA and sign keys with it by making use of some simple op-mode commands. - -Don't be afraid that you need to re-do your configuration. Key transformation is -handled, as always, by our migration scripts, so this will be a smooth transition -for you! - -Key Generation -============== - -Certificate Authority (CA) --------------------------- - -VyOS now also has the ability to create CAs, keys, Diffie-Hellman and other -keypairs from an easy to access operational level command. - -.. opcmd:: generate pki ca - - Create a new :abbr:`CA (Certificate Authority)` and output the CAs public and - private key on the console. - -.. opcmd:: generate pki ca install <name> - - Create a new :abbr:`CA (Certificate Authority)` and output the CAs public and - private key on the console. - - .. include:: pki_cli_import_help.txt - -.. opcmd:: generate pki ca sign <ca-name> - - Create a new subordinate :abbr:`CA (Certificate Authority)` and sign it using - the private key referenced by `ca-name`. - -.. opcmd:: generate pki ca sign <ca-name> install <name> - - Create a new subordinate :abbr:`CA (Certificate Authority)` and sign it using - the private key referenced by `name`. - - .. include:: pki_cli_import_help.txt - -Certificates ------------- - -.. opcmd:: generate pki certificate - - Create a new public/private keypair and output the certificate on the console. - -.. opcmd:: generate pki certificate install <name> - - Create a new public/private keypair and output the certificate on the console. - - .. include:: pki_cli_import_help.txt - -.. opcmd:: generate pki certificate self-signed - - Create a new self-signed certificate. The public/private is then shown on the - console. - -.. opcmd:: generate pki certificate self-signed install <name> - - Create a new self-signed certificate. The public/private is then shown on the - console. - - .. include:: pki_cli_import_help.txt - -.. opcmd:: generate pki certificate sign <ca-name> - - Create a new public/private keypair which is signed by the CA referenced by - `ca-name`. The signed certificate is then output to the console. - -.. opcmd:: generate pki certificate sign <ca-name> install <name> - - Create a new public/private keypair which is signed by the CA referenced by - `ca-name`. The signed certificate is then output to the console. - - .. include:: pki_cli_import_help.txt - -Diffie-Hellman parameters -------------------------- - -.. opcmd:: generate pki dh - - Generate a new set of :abbr:`DH (Diffie-Hellman)` parameters. The key size - is requested by the CLI and defaults to 2048 bit. - - The generated parameters are then output to the console. - -.. opcmd:: generate pki dh install <name> - - Generate a new set of :abbr:`DH (Diffie-Hellman)` parameters. The key size - is requested by the CLI and defaults to 2048 bit. - - .. include:: pki_cli_import_help.txt - -OpenVPN -------- - -.. opcmd:: generate pki openvpn shared-secret - - Generate a new OpenVPN shared secret. The generated secret is the output to - the console. - -.. opcmd:: generate pki openvpn shared-secret install <name> - - Generate a new OpenVPN shared secret. The generated secret is the output to - the console. - - .. include:: pki_cli_import_help.txt - -WireGuard ---------- - -.. opcmd:: generate pki wireguard key-pair - - Generate a new WireGuard public/private key portion and output the result to - the console. - -.. opcmd:: generate pki wireguard key-pair install <interface> - - Generate a new WireGuard public/private key portion and output the result to - the console. - - .. note:: In addition to the command above, the output is in a format which can - be used to directly import the key into the VyOS CLI by simply copy-pasting - the output from op-mode into configuration mode. - - ``interface`` is used for the VyOS CLI command to identify the WireGuard - interface where this private key is to be used. - -.. opcmd:: generate pki wireguard preshared-key - - Generate a WireGuard pre-shared secret used for peers to communicate. - -.. opcmd:: generate pki wireguard preshared-key install <peer> - - Generate a WireGuard pre-shared secret used for peers to communicate. - - .. note:: In addition to the command above, the output is in a format which can - be used to directly import the key into the VyOS CLI by simply copy-pasting - the output from op-mode into configuration mode. - - ``peer`` is used for the VyOS CLI command to identify the WireGuard peer where - this secret is to be used. - -Key usage (CLI) -=============== - -CA (Certificate Authority) --------------------------- - -.. cfgcmd:: set pki ca <name> certificate - - Add the public CA certificate for the CA named `name` to the VyOS CLI. - - .. note:: When loading the certificate you need to manually strip the - ``-----BEGIN CERTIFICATE-----`` and ``-----END CERTIFICATE-----`` tags. - Also, the certificate/key needs to be presented in a single line without - line breaks (``\n``), this can be done using the following shell command: - - ``$ tail -n +2 ca.pem | head -n -1 | tr -d '\n'`` - -.. cfgcmd:: set pki ca <name> crl - - Certificate revocation list in PEM format. - -.. cfgcmd:: set pki ca <name> description - - A human readable description what this CA is about. - -.. cfgcmd:: set pki ca <name> private key - - Add the CAs private key to the VyOS CLI. This should never leave the system, - and is only required if you use VyOS as your certificate generator as - mentioned above. - - .. note:: When loading the certificate you need to manually strip the - ``-----BEGIN KEY-----`` and ``-----END KEY-----`` tags. Also, the - certificate/key needs to be presented in a single line without line - breaks (``\n``), this can be done using the following shell command: - - ``$ tail -n +2 ca.key | head -n -1 | tr -d '\n'`` - -.. cfgcmd:: set pki ca <name> private password-protected - - Mark the CAs private key as password protected. User is asked for the password - when the key is referenced. - -Server Certificate ------------------- - -After we have imported the CA certificate(s) we can now import and add -certificates used by services on this router. - -.. cfgcmd:: set pki certificate <name> certificate - - Add public key portion for the certificate named `name` to the VyOS CLI. - - .. note:: When loading the certificate you need to manually strip the - ``-----BEGIN CERTIFICATE-----`` and ``-----END CERTIFICATE-----`` tags. - Also, the certificate/key needs to be presented in a single line without - line breaks (``\n``), this can be done using the following shell command: - - ``$ tail -n +2 cert.pem | head -n -1 | tr -d '\n'`` - -.. cfgcmd:: set pki certificate <name> description - - A human readable description what this certificate is about. - -.. cfgcmd:: set pki certificate <name> private key - - Add the private key portion of this certificate to the CLI. This should never - leave the system as it is used to decrypt the data. - - .. note:: When loading the certificate you need to manually strip the - ``-----BEGIN KEY-----`` and ``-----END KEY-----`` tags. Also, the - certificate/key needs to be presented in a single line without line - breaks (``\n``), this can be done using the following shell command: - - ``$ tail -n +2 cert.key | head -n -1 | tr -d '\n'`` - -.. cfgcmd:: set pki certificate <name> private password-protected - - Mark the private key as password protected. User is asked for the password - when the key is referenced. - -.. cfgcmd:: set pki certificate <name> revoke - - If CA is present, this certificate will be included in generated CRLs - -Import files to PKI format --------------------------- -VyOS provides this utility to import existing certificates/key files directly -into PKI from op-mode. Previous to VyOS 1.4, certificates were stored under the -/config folder permanently and will be retained post upgrade. - -.. opcmd:: import pki ca <name> file <Path to CA certificate file> - - Import the public CA certificate from the defined file to VyOS CLI. - -.. opcmd:: import pki ca <name> key-file <Path to private key file> - - Import the CAs private key portion to the CLI. This should never leave the - system as it is used to decrypt the data. The key is required if you use - VyOS as your certificate generator. - -.. opcmd:: import pki certificate <name> file <path to certificate> - - Import the certificate from the file to VyOS CLI. - -.. opcmd:: import pki certificate <name> key-file <path to private key> - - Import the private key of the certificate to the VyOS CLI. This should never - leave the system as it is used to decrypt the data. - -.. opcmd:: import pki openvpn shared-secret <name> file <path to OpenVPN secret key> - - Import the OpenVPN shared secret stored in file to the VyOS CLI. - -ACME -^^^^ - -The VyOS PKI subsystem can also be used to automatically retrieve Certificates -using the :abbr:`ACME (Automatic Certificate Management Environment)` protocol. - -.. cfgcmd:: set pki certificate <name> acme domain-name <name> - - Domain names to apply, multiple domain-names can be specified. - - This is a mandatory option - -.. cfgcmd:: set pki certificate <name> acme email <address> - - Email used for registration and recovery contact. - - This is a mandatory option - -.. cfgcmd:: set pki certificate <name> acme listen-address <address> - - The address the server listens to during http-01 challenge - -.. cfgcmd:: set pki certificate <name> acme rsa-key-size <2048 | 3072 | 4096> - - Size of the RSA key. - - This options defaults to 2048 - -.. cfgcmd:: set pki certificate <name> acme url <url> - - ACME Directory Resource URI. - - This defaults to https://acme-v02.api.letsencrypt.org/directory - - .. note:: During initial deployment we recommend using the staging API - of LetsEncrypt to prevent and blacklisting of your system. The API - endpoint is https://acme-staging-v02.api.letsencrypt.org/directory - -Operation -========= - -VyOS operational mode commands are not only available for generating keys but -also to display them. - -.. opcmd:: show pki ca - - Show a list of installed :abbr:`CA (Certificate Authority)` certificates. - - .. code-block:: none - - vyos@vyos:~$ show pki ca - Certificate Authorities: - Name Subject Issuer CN Issued Expiry Private Key Parent - -------------- ------------------------------------------------------- ----------------- ------------------- ------------------- ------------- -------------- - DST_Root_CA_X3 CN=ISRG Root X1,O=Internet Security Research Group,C=US CN=DST Root CA X3 2021-01-20 19:14:03 2024-09-30 18:14:03 No N/A - R3 CN=R3,O=Let's Encrypt,C=US CN=ISRG Root X1 2020-09-04 00:00:00 2025-09-15 16:00:00 No DST_Root_CA_X3 - vyos_rw CN=VyOS RW CA,O=VyOS,L=Some-City,ST=Some-State,C=GB CN=VyOS RW CA 2021-07-05 13:46:03 2026-07-04 13:46:03 Yes N/A - -.. opcmd:: show pki ca <name> - - Show only information for specified Certificate Authority. - -.. opcmd:: show pki certificate - - Show a list of installed certificates - - .. code-block:: none - - vyos@vyos:~$ show pki certificate - Certificates: - Name Type Subject CN Issuer CN Issued Expiry Revoked Private Key CA Present - --------- ------ --------------------- ------------- ------------------- ------------------- --------- ------------- ------------- - ac2 Server CN=ac2.vyos.net CN=R3 2021-07-05 07:29:59 2021-10-03 07:29:58 No Yes Yes (R3) - rw_server Server CN=VyOS RW CN=VyOS RW CA 2021-07-05 13:48:02 2022-07-05 13:48:02 No Yes Yes (vyos_rw) - -.. opcmd:: show pki certificate <name> - - Show only information for specified certificate. - -.. opcmd:: show pki crl - - Show a list of installed :abbr:`CRLs (Certificate Revocation List)`. - -.. opcmd:: renew certbot - - Manually trigger certificate renewal. This will be done twice a day. - -Examples -======== - -Create a CA chain and leaf certificates ---------------------------------------- - -This configuration generates & installs into the VyOS PKI system a root -certificate authority, alongside two intermediary certificate authorities for -client & server certificates. These CAs are then used to generate a server -certificate for the router, and a client certificate for a user. - - -* ``vyos_root_ca`` is the root certificate authority. - -* ``vyos_client_ca`` and ``vyos_server_ca`` are intermediary certificate authorities, - which are signed by the root CA. - -* ``vyos_cert`` is a leaf server certificate used to identify the VyOS router, - signed by the server intermediary CA. - -* ``vyos_example_user`` is a leaf client certificate used to identify a user, - signed by client intermediary CA. - - -First, we create the root certificate authority. - -.. code-block:: none - - [edit] - vyos@vyos# run generate pki ca install vyos_root_ca - Enter private key type: [rsa, dsa, ec] (Default: rsa) rsa - Enter private key bits: (Default: 2048) 2048 - Enter country code: (Default: GB) GB - Enter state: (Default: Some-State) Some-State - Enter locality: (Default: Some-City) Some-City - Enter organization name: (Default: VyOS) VyOS - Enter common name: (Default: vyos.io) VyOS Root CA - Enter how many days certificate will be valid: (Default: 1825) 1825 - Note: If you plan to use the generated key on this router, do not encrypt the private key. - Do you want to encrypt the private key with a passphrase? [y/N] n - 2 value(s) installed. Use "compare" to see the pending changes, and "commit" to apply. - -Secondly, we create the intermediary certificate authorities, which are used to -sign the leaf certificates. - -.. code-block:: none - - [edit] - vyos@vyos# run generate pki ca sign vyos_root_ca install vyos_server_ca - Do you already have a certificate request? [y/N] n - Enter private key type: [rsa, dsa, ec] (Default: rsa) rsa - Enter private key bits: (Default: 2048) 2048 - Enter country code: (Default: GB) GB - Enter state: (Default: Some-State) Some-State - Enter locality: (Default: Some-City) Some-City - Enter organization name: (Default: VyOS) VyOS - Enter common name: (Default: vyos.io) VyOS Intermediary Server CA - Enter how many days certificate will be valid: (Default: 1825) 1095 - Note: If you plan to use the generated key on this router, do not encrypt the private key. - Do you want to encrypt the private key with a passphrase? [y/N] n - 2 value(s) installed. Use "compare" to see the pending changes, and "commit" to apply. - - - [edit] - vyos@vyos# run generate pki ca sign vyos_root_ca install vyos_client_ca - Do you already have a certificate request? [y/N] n - Enter private key type: [rsa, dsa, ec] (Default: rsa) rsa - Enter private key bits: (Default: 2048) 2048 - Enter country code: (Default: GB) GB - Enter state: (Default: Some-State) Some-State - Enter locality: (Default: Some-City) Some-City - Enter organization name: (Default: VyOS) VyOS - Enter common name: (Default: vyos.io) VyOS Intermediary Client CA - Enter how many days certificate will be valid: (Default: 1825) 1095 - Note: If you plan to use the generated key on this router, do not encrypt the private key. - Do you want to encrypt the private key with a passphrase? [y/N] n - 2 value(s) installed. Use "compare" to see the pending changes, and "commit" to apply. - -Lastly, we can create the leaf certificates that devices and users will utilise. - -.. code-block:: none - - [edit] - vyos@vyos# run generate pki certificate sign vyos_server_ca install vyos_cert - Do you already have a certificate request? [y/N] n - Enter private key type: [rsa, dsa, ec] (Default: rsa) rsa - Enter private key bits: (Default: 2048) 2048 - Enter country code: (Default: GB) GB - Enter state: (Default: Some-State) Some-State - Enter locality: (Default: Some-City) Some-City - Enter organization name: (Default: VyOS) VyOS - Enter common name: (Default: vyos.io) vyos.net - Do you want to configure Subject Alternative Names? [y/N] y - Enter alternative names in a comma separate list, example: ipv4:1.1.1.1,ipv6:fe80::1,dns:vyos.net - Enter Subject Alternative Names: dns:vyos.net,dns:www.vyos.net - Enter how many days certificate will be valid: (Default: 365) 365 - Enter certificate type: (client, server) (Default: server) server - Note: If you plan to use the generated key on this router, do not encrypt the private key. - Do you want to encrypt the private key with a passphrase? [y/N] n - 2 value(s) installed. Use "compare" to see the pending changes, and "commit" to apply. - - - [edit] - vyos@vyos# run generate pki certificate sign vyos_client_ca install vyos_example_user - Do you already have a certificate request? [y/N] n - Enter private key type: [rsa, dsa, ec] (Default: rsa) rsa - Enter private key bits: (Default: 2048) 2048 - Enter country code: (Default: GB) GB - Enter state: (Default: Some-State) Some-State - Enter locality: (Default: Some-City) Some-City - Enter organization name: (Default: VyOS) VyOS - Enter common name: (Default: vyos.io) Example User - Do you want to configure Subject Alternative Names? [y/N] y - Enter alternative names in a comma separate list, example: ipv4:1.1.1.1,ipv6:fe80::1,dns:vyos.net,rfc822:user@vyos.net - Enter Subject Alternative Names: rfc822:example.user@vyos.net - Enter how many days certificate will be valid: (Default: 365) 365 - Enter certificate type: (client, server) (Default: server) client - Note: If you plan to use the generated key on this router, do not encrypt the private key. - Do you want to encrypt the private key with a passphrase? [y/N] n - 2 value(s) installed. Use "compare" to see the pending changes, and "commit" to apply. diff --git a/docs/configuration/policy/rst-access-list.rst b/docs/configuration/policy/rst-access-list.rst deleted file mode 100644 index 0af9b911..00000000 --- a/docs/configuration/policy/rst-access-list.rst +++ /dev/null @@ -1,70 +0,0 @@ -################## -Access List Policy -################## - -Filtering is used for both input and output of the routing information. Once -filtering is defined, it can be applied in any direction. VyOS makes filtering -possible using acls and prefix lists. - -Basic filtering can be done using access-list and access-list6. - -************* -Configuration -************* - -Access Lists -============ - -.. cfgcmd:: set policy access-list <acl_number> - - This command creates the new access list policy, where <acl_number> must be - a number from 1 to 2699. - -.. cfgcmd:: set policy access-list <acl_number> description <text> - - Set description for the access list. - -.. cfgcmd:: set policy access-list <acl_number> rule <1-65535> action - <permit|deny> - - This command creates a new rule in the access list and defines an action. - -.. cfgcmd:: set policy access-list <acl_number> rule <1-65535> - <destination|source> <any|host|inverse-mask|network> - - This command defines matching parameters for access list rule. Matching - criteria could be applied to destination or source parameters: - - * any: any IP address to match. - * host: single host IP address to match. - * inverse-match: network/netmask to match (requires network be defined). - * network: network/netmask to match (requires inverse-match be defined). - -IPv6 Access List -================ - -Basic filtering could also be applied to IPv6 traffic. - -.. cfgcmd:: set policy access-list6 <text> - - This command creates the new IPv6 access list, identified by <text> - -.. cfgcmd:: set policy access-list6 <text> description <text> - - Set description for the IPv6 access list. - -.. cfgcmd:: set policy access-list6 <text> rule <1-65535> action <permit|deny> - - This command creates a new rule in the IPv6 access list and defines an - action. - -.. cfgcmd:: set policy access-list6 <text> rule <1-65535> source - <any|exact-match|network> - - This command defines matching parameters for IPv6 access list rule. Matching - criteria could be applied to source parameters: - - * any: any IPv6 address to match. - * exact-match: exact match of the network prefixes. - * network: network/netmask to match (requires inverse-match be defined) BUG, - NO invert-match option in access-list6
\ No newline at end of file diff --git a/docs/configuration/policy/rst-as-path-list.rst b/docs/configuration/policy/rst-as-path-list.rst deleted file mode 100644 index ceeb8e01..00000000 --- a/docs/configuration/policy/rst-as-path-list.rst +++ /dev/null @@ -1,33 +0,0 @@ -#################### -BGP - AS Path Policy -#################### - -VyOS provides policies commands exclusively for BGP traffic filtering and -manipulation: **as-path-list** is one of them. - -************* -Configuration -************* - -policy as-path-list -=================== - -.. cfgcmd:: set policy as-path-list <text> - - Create as-path-policy identified by name <text>. - -.. cfgcmd:: set policy as-path-list <text> description <text> - - Set description for as-path-list policy. - -.. cfgcmd:: set policy as-path-list <text> rule <1-65535> action <permit|deny> - - Set action to take on entries matching this rule. - -.. cfgcmd:: set policy as-path-list <text> rule <1-65535> description <text> - - Set description for rule. - -.. cfgcmd:: set policy as-path-list <text> rule <1-65535> regex <text> - - Regular expression to match against an AS path. For example "64501 64502". diff --git a/docs/configuration/policy/rst-community-list.rst b/docs/configuration/policy/rst-community-list.rst deleted file mode 100644 index ee2da03c..00000000 --- a/docs/configuration/policy/rst-community-list.rst +++ /dev/null @@ -1,35 +0,0 @@ -#################### -BGP - Community List -#################### - -VyOS provides policies commands exclusively for BGP traffic filtering and -manipulation: **community-list** is one of them. - -************* -Configuration -************* - -policy community-list -===================== - -.. cfgcmd:: set policy community-list <text> - - Creat community-list policy identified by name <text>. - -.. cfgcmd:: set policy community-list <text> description <text> - - Set description for community-list policy. - -.. cfgcmd:: set policy community-list <text> rule <1-65535> action - <permit|deny> - - Set action to take on entries matching this rule. - -.. cfgcmd:: set policy community-list <text> rule <1-65535> description <text> - - Set description for rule. - -.. cfgcmd:: set policy community-list <text> rule <1-65535> regex - <aa:nn|local-AS|no-advertise|no-export|additive> - - Regular expression to match against a community-list.
\ No newline at end of file diff --git a/docs/configuration/policy/rst-examples.rst b/docs/configuration/policy/rst-examples.rst deleted file mode 100644 index 6c5c592a..00000000 --- a/docs/configuration/policy/rst-examples.rst +++ /dev/null @@ -1,213 +0,0 @@ -########### -BGP Example -########### - -**Policy definition:** - -.. code-block:: none - - # Create policy - set policy route-map setmet rule 2 action 'permit' - set policy route-map setmet rule 2 set as-path prepend '2 2 2' - - # Apply policy to BGP - set protocols bgp system-as 1 - set protocols bgp neighbor 203.0.113.2 address-family ipv4-unicast route-map import 'setmet' - set protocols bgp neighbor 203.0.113.2 address-family ipv4-unicast soft-reconfiguration 'inbound' - -Using 'soft-reconfiguration' we get the policy update without bouncing the -neighbor. - -**Routes learned before routing policy applied:** - -.. code-block:: none - - vyos@vos1:~$ show ip bgp - BGP table version is 0, local router ID is 192.168.56.101 - Status codes: s suppressed, d damped, h history, * valid, > best, i - internal, - r RIB-failure, S Stale, R Removed - Origin codes: i - IGP, e - EGP, ? - incomplete - - Network Next Hop Metric LocPrf Weight Path - *> 198.51.100.3/32 203.0.113.2 1 0 2 i < Path - - Total number of prefixes 1 - -**Routes learned after routing policy applied:** - -.. code-block:: none - - vyos@vos1:~$ show ip bgp - BGP table version is 0, local router ID is 192.168.56.101 - Status codes: s suppressed, d damped, h history, * valid, > best, i - internal, - r RIB-failure, S Stale, R Removed - Origin codes: i - IGP, e - EGP, ? - incomplete - - Network Next Hop Metric LocPrf Weight Path - *> 198.51.100.3/32 203.0.113.2 1 0 2 2 2 2 i - - Total number of prefixes 1 - vyos@vos1:~$ - -You now see the longer AS path. - -################# -Transparent Proxy -################# - -The following example will show how VyOS can be used to redirect web -traffic to an external transparent proxy: - -.. code-block:: none - - set policy route FILTER-WEB rule 1000 destination port 80 - set policy route FILTER-WEB rule 1000 protocol tcp - set policy route FILTER-WEB rule 1000 set table 100 - -This creates a route policy called FILTER-WEB with one rule to set the -routing table for matching traffic (TCP port 80) to table ID 100 -instead of the default routing table. - -To create routing table 100 and add a new default gateway to be used by -traffic matching our route policy: - -.. code-block:: none - - set protocols static table 100 route 0.0.0.0/0 next-hop 10.255.0.2 - -This can be confirmed using the ``show ip route table 100`` operational -command. - -Finally, to apply the policy route to ingress traffic on our LAN -interface, we use: - -.. code-block:: none - - set policy route FILTER-WEB interface eth1 - -################ -Multiple Uplinks -################ - -VyOS Policy-Based Routing (PBR) works by matching source IP address -ranges and forwarding the traffic using different routing tables. - -Routing tables that will be used in this example are: - -* ``table 10`` Routing table used for VLAN 10 (192.168.188.0/24) -* ``table 11`` Routing table used for VLAN 11 (192.168.189.0/24) -* ``main`` Routing table used by VyOS and other interfaces not - participating in PBR - -.. figure:: /_static/images/pbr_example_1.* - :scale: 80 % - :alt: PBR multiple uplinks - - Policy-Based Routing with multiple ISP uplinks - (source ./draw.io/pbr_example_1.drawio) - -Add default routes for routing ``table 10`` and ``table 11`` - -.. code-block:: none - - set protocols static table 10 route 0.0.0.0/0 next-hop 192.0.1.1 - set protocols static table 11 route 0.0.0.0/0 next-hop 192.0.2.2 - -Add policy route matching VLAN source addresses - -.. code-block:: none - - set policy route PBR rule 20 set table '10' - set policy route PBR rule 20 description 'Route VLAN10 traffic to table 10' - set policy route PBR rule 20 source address '192.168.188.0/24' - - set policy route PBR rule 30 set table '11' - set policy route PBR rule 30 description 'Route VLAN11 traffic to table 11' - set policy route PBR rule 30 source address '192.168.189.0/24' - -Apply routing policy to **inbound** direction of out VLAN interfaces - -.. code-block:: none - - set policy route 'PBR' interface eth0.10 - set policy route 'PBR' interface eth0.11 - - -**OPTIONAL:** Exclude Inter-VLAN traffic (between VLAN10 and VLAN11) -from PBR - -.. code-block:: none - - set firewall group network-group VLANS-GR description 'VLANs networks' - set firewall group network-group VLANS-GR network '192.168.188.0/24' - set firewall group network-group VLANS-GR network '192.168.189.0/24' - - set policy route PBR rule 10 description 'VLAN10 <-> VLAN11 shortcut' - set policy route PBR rule 10 destination group network-group 'VLANS-GR' - set policy route PBR rule 10 set table 'main' - -These commands allow the VLAN10 and VLAN11 hosts to communicate with -each other using the main routing table. - -Local route -=========== - -The following example allows VyOS to use :abbr:`PBR (Policy-Based Routing)` -for traffic, which originated from the router itself. That solution for multiple -ISP's and VyOS router will respond from the same interface that the packet was -received. Also, it used, if we want that one VPN tunnel to be through one -provider, and the second through another. - -* ``203.0.113.254`` IP addreess on VyOS eth1 from ISP1 -* ``192.168.2.254`` IP addreess on VyOS eth2 from ISP2 -* ``table 10`` Routing table used for ISP1 -* ``table 11`` Routing table used for ISP2 - - -.. code-block:: none - - set policy local-route rule 101 set table '10' - set policy local-route rule 101 source address '203.0.113.254' - set policy local-route rule 102 set table '11' - set policy local-route rule 102 source address '192.0.2.254' - set protocols static table 10 route 0.0.0.0/0 next-hop '203.0.113.1' - set protocols static table 11 route 0.0.0.0/0 next-hop '192.0.2.2' - -Add multiple source IP in one rule with same priority - -.. code-block:: none - - set policy local-route rule 101 set table '10' - set policy local-route rule 101 source address '203.0.113.254' - set policy local-route rule 101 source address '203.0.113.253' - set policy local-route rule 101 source address '198.51.100.0/24' - -########################### -Clamp MSS for a specific IP -########################### - -This example shows how to target an MSS clamp (in our example to 1360 bytes) -to a specific destination IP. - -.. code-block:: none - - set policy route IP-MSS-CLAMP rule 10 description 'Clamp TCP session MSS to 1360 for 198.51.100.30' - set policy route IP-MSS-CLAMP rule 10 destination address '198.51.100.30/32' - set policy route IP-MSS-CLAMP rule 10 protocol 'tcp' - set policy route IP-MSS-CLAMP rule 10 set tcp-mss '1360' - set policy route IP-MSS-CLAMP rule 10 tcp flags 'SYN' - -To apply this policy to the correct interface, configure it on the -interface the inbound local host will send through to reach our -destined target host (in our example eth1). - -.. code-block:: none - - set policy route IP-MSS-CLAMP interface eth1 - -You can view that the policy is being correctly (or incorrectly) utilised -with the following command: - -.. code-block:: none - - show policy route statistics diff --git a/docs/configuration/policy/rst-extcommunity-list.rst b/docs/configuration/policy/rst-extcommunity-list.rst deleted file mode 100644 index c413b8b5..00000000 --- a/docs/configuration/policy/rst-extcommunity-list.rst +++ /dev/null @@ -1,40 +0,0 @@ -############################# -BGP - Extended Community List -############################# - -VyOS provides policies commands exclusively for BGP traffic filtering and -manipulation: **extcommunity-list** is one of them. - -************* -Configuration -************* - -policy extcommunity-list -======================== - -.. cfgcmd:: set policy extcommunity-list <text> - - Creat extcommunity-list policy identified by name <text>. - -.. cfgcmd:: set policy extcommunity-list <text> description <text> - - Set description for extcommunity-list policy. - -.. cfgcmd:: set policy extcommunity-list <text> rule <1-65535> action - <permit|deny> - - Set action to take on entries matching this rule. - -.. cfgcmd:: set policy extcommunity-list <text> rule <1-65535> description - <text> - - Set description for rule. - -.. cfgcmd:: set policy extcommunity-list <text> rule <1-65535> regex <text> - - Regular expression to match against an extended community list, where text - could be: - - * <aa:nn:nn>: Extended community list regular expression. - * <rt aa:nn:nn>: Route Target regular expression. - * <soo aa:nn:nn>: Site of Origin regular expression. diff --git a/docs/configuration/policy/rst-index.rst b/docs/configuration/policy/rst-index.rst deleted file mode 100644 index 0394eb21..00000000 --- a/docs/configuration/policy/rst-index.rst +++ /dev/null @@ -1,54 +0,0 @@ -:lastproofread: 2021-07-12 - -.. include:: /_include/need_improvement.txt - -###### -Policy -###### - -Policies are used for filtering and traffic management. With policies, network -administrators could filter and treat traffic -according to their needs. - -There could be a wide range of routing policies. Some examples are listed -below: - -* Filter traffic based on source/destination address. -* Set some metric to routes learned from a particular neighbor. -* Set some attributes (like AS PATH or Community value) to advertised routes - to neighbors. -* Prefer a specific routing protocol routes over another routing protocol - running on the same router. - -Policies, in VyOS, are implemented using FRR filtering and route maps. Detailed -information of FRR could be found in http://docs.frrouting.org/ - -*************** -Policy Sections -*************** - -.. toctree:: - :maxdepth: 1 - :includehidden: - - access-list - prefix-list - route - route-map - local-route - as-path-list - community-list - extcommunity-list - large-community-list - -******** -Examples -******** - -Examples of policies usage: - -.. toctree:: - :maxdepth: 1 - :includehidden: - - examples
\ No newline at end of file diff --git a/docs/configuration/policy/rst-large-community-list.rst b/docs/configuration/policy/rst-large-community-list.rst deleted file mode 100644 index 0c57fd4a..00000000 --- a/docs/configuration/policy/rst-large-community-list.rst +++ /dev/null @@ -1,36 +0,0 @@ -########################## -BGP - Large Community List -########################## - -VyOS provides policies commands exclusively for BGP traffic filtering and -manipulation: **large-community-list** is one of them. - -************* -Configuration -************* - -policy large-community-list -=========================== - -.. cfgcmd:: set policy large-community-list <text> - - Create large-community-list policy identified by name <text>. - -.. cfgcmd:: set policy large-community-list <text> description <text> - - Set description for large-community-list policy. - -.. cfgcmd:: set policy large-community-list <text> rule <1-65535> action - <permit|deny> - - Set action to take on entries matching this rule. - -.. cfgcmd:: set policy large-community-list <text> rule <1-65535> description - <text> - - Set description for rule. - -.. cfgcmd:: set policy large-community-list <text> rule <1-65535> regex - <aa:nn:nn> - - Regular expression to match against a large community list. diff --git a/docs/configuration/policy/rst-local-route.rst b/docs/configuration/policy/rst-local-route.rst deleted file mode 100644 index a3e42816..00000000 --- a/docs/configuration/policy/rst-local-route.rst +++ /dev/null @@ -1,87 +0,0 @@ -################## -Local Route Policy -################## - -Policies for local traffic are defined in this section. - -************* -Configuration -************* - -Local Route IPv4 -================ - -.. cfgcmd:: set policy local-route rule <1-32765> set table <1-200|main> - - Set the routing table to use for forwarding matching packets. - -.. cfgcmd:: set policy local-route rule <1-32765> set vrf <vrf|default> - - Set the VRF to use for forwarding matching packets. - -.. cfgcmd:: set policy local-route rule <1-32765> protocol <protocol> - - Match specified protocol (name or number). - -.. cfgcmd:: set policy local-route rule <1-32765> fwmark <1-2147483647> - - Match specified firewall mark (fwmark). - -.. cfgcmd:: set policy local-route rule <1-32765> source address <x.x.x.x|x.x.x.x/x> - - Match specified source address or prefix. - -.. cfgcmd:: set policy local-route rule <1-32765> source port <1-65535> - - Match specified source port. - -.. cfgcmd:: set policy local-route rule <1-32765> destination address <x.x.x.x|x.x.x.x/x> - - Match specified destination address or prefix. - -.. cfgcmd:: set policy local-route rule <1-32765> destination port <1-65535> - - Match specified destination port. - -.. cfgcmd:: set policy local-route rule <1-32765> inbound-interface <interface> - - Match specified inbound interface. - -Local Route IPv6 -================ - -.. cfgcmd:: set policy local-route6 rule <1-32765> set table <1-200|main> - - Set the routing table to use for forwarding matching packets. - -.. cfgcmd:: set policy local-route6 rule <1-32765> set vrf <vrf|default> - - Set the VRF to use for forwarding matching packets. - -.. cfgcmd:: set policy local-route6 rule <1-32765> protocol <protocol> - - Match specified protocol (name or number). - -.. cfgcmd:: set policy local-route6 rule <1-32765> fwmark <1-2147483647> - - Match specified firewall mark (fwmark). - -.. cfgcmd:: set policy local-route6 rule <1-32765> source address <h:h:h:h:h:h:h:h|h:h:h:h:h:h:h:h/x> - - Match specified source address or prefix. - -.. cfgcmd:: set policy local-route6 rule <1-32765> source port <1-65535> - - Match specified source port. - -.. cfgcmd:: set policy local-route6 rule <1-32765> destination address <h:h:h:h:h:h:h:h|h:h:h:h:h:h:h:h/x> - - Match specified destination address or prefix. - -.. cfgcmd:: set policy local-route6 rule <1-32765> destination port <1-65535> - - Match specified destination port. - -.. cfgcmd:: set policy local-route6 rule <1-32765> inbound-interface <interface> - - Match specified inbound interface.
\ No newline at end of file diff --git a/docs/configuration/policy/rst-prefix-list.rst b/docs/configuration/policy/rst-prefix-list.rst deleted file mode 100644 index 98df1b9b..00000000 --- a/docs/configuration/policy/rst-prefix-list.rst +++ /dev/null @@ -1,112 +0,0 @@ -################## -Prefix List Policy -################## - -Prefix lists provides the most powerful prefix based filtering mechanism. In -addition to access-list functionality, ip prefix-list has prefix length range -specification. - -If no ip prefix list is specified, it acts as permit. If ip prefix list is -defined, and no match is found, default deny is applied. - -Prefix filtering can be done using prefix-list and prefix-list6. - -************* -Configuration -************* - -IPv4 Prefix Lists (prefix-list) -============ - -.. cfgcmd:: set policy prefix-list <text> - - This command creates the new prefix-list policy, identified by <text>. - -.. cfgcmd:: set policy prefix-list <text> description <text> - - Set description for the prefix-list policy. - -.. cfgcmd:: set policy prefix-list <text> rule <1-65535> action <permit|deny> - - This command creates a new rule in the prefix-list and defines an action. - -.. cfgcmd:: set policy prefix-list <text> rule <1-65535> description <text> - - Set description for rule in the prefix-list. - -.. cfgcmd:: set policy prefix-list <text> rule <1-65535> prefix <x.x.x.x/x> - - Prefix to match against. - -.. cfgcmd:: set policy prefix-list <text> rule <1-65535> ge <0-32> - - Netmask greater than length. - -.. cfgcmd:: set policy prefix-list <text> rule <1-65535> le <0-32> - - Netmask less than length - -Example: IPv4 Prefix Lists (prefix-list) -============ - -This example creates an IPv4 prefix-list named PL4-EXAMPLE-NAME, defines 3 -rules each with 1 prefix, and matches le (less than/equal to) /32. - -.. cfgcmd:: set policy prefix-list PL4-EXAMPLE-NAME rule 10 action 'permit' -.. cfgcmd:: set policy prefix-list PL4-EXAMPLE-NAME rule 10 le '32' -.. cfgcmd:: set policy prefix-list PL4-EXAMPLE-NAME rule 10 prefix '192.0.2.0/24' -.. cfgcmd:: set policy prefix-list PL4-EXAMPLE-NAME rule 20 action 'permit' -.. cfgcmd:: set policy prefix-list PL4-EXAMPLE-NAME rule 20 le '32' -.. cfgcmd:: set policy prefix-list PL4-EXAMPLE-NAME rule 20 prefix '198.51.100.0/24' -.. cfgcmd:: set policy prefix-list PL4-EXAMPLE-NAME rule 30 action 'permit' -.. cfgcmd:: set policy prefix-list PL4-EXAMPLE-NAME rule 30 le '32' -.. cfgcmd:: set policy prefix-list PL4-EXAMPLE-NAME rule 30 prefix '203.0.113.0/24' - -IPv6 Prefix Lists (prefix-list6) -================= - -.. cfgcmd:: set policy prefix-list6 <text> - - This command creates the new IPv6 prefix-list policy, identified by <text>. - -.. cfgcmd:: set policy prefix-list6 <text> description <text> - - Set description for the IPv6 prefix-list policy. - -.. cfgcmd:: set policy prefix-list6 <text> rule <1-65535> action <permit|deny> - - This command creates a new rule in the IPv6 prefix-list and defines an - action. - -.. cfgcmd:: set policy prefix-list6 <text> rule <1-65535> description <text> - - Set description for rule in IPv6 prefix-list. - -.. cfgcmd:: set policy prefix-list6 <text> rule <1-65535> prefix - <h:h:h:h:h:h:h:h/x> - - IPv6 prefix. - -.. cfgcmd:: set policy prefix-list6 <text> rule <1-65535> ge <0-128> - - Netmask greater than length. - -.. cfgcmd:: set policy prefix-list6 <text> rule <1-65535> le <0-128> - - Netmask less than length - -Example: IPv6 Prefix Lists (prefix-list6) -============ - -This example creates an IPv6 prefix-list6 named PL6-EXAMPLE-NAME, defines 3 -rules each with 1 prefix, and matches le (less than/equal to) /128. - -.. cfgcmd:: set policy prefix-list6 PL6-EXAMPLE-NAME rule 10 action 'permit' -.. cfgcmd:: set policy prefix-list6 PL6-EXAMPLE-NAME rule 10 le '128' -.. cfgcmd:: set policy prefix-list6 PL6-EXAMPLE-NAME rule 10 prefix '2001:db8:0:0::/64' -.. cfgcmd:: set policy prefix-list6 PL6-EXAMPLE-NAME rule 20 action 'permit' -.. cfgcmd:: set policy prefix-list6 PL6-EXAMPLE-NAME rule 20 le '128' -.. cfgcmd:: set policy prefix-list6 PL6-EXAMPLE-NAME rule 20 prefix '2001:db8:0:1::/64' -.. cfgcmd:: set policy prefix-list6 PL6-EXAMPLE-NAME rule 30 action 'permit' -.. cfgcmd:: set policy prefix-list6 PL6-EXAMPLE-NAME rule 30 le '128' -.. cfgcmd:: set policy prefix-list6 PL6-EXAMPLE-NAME rule 30 prefix '2001:db8:0:2::/64'
\ No newline at end of file diff --git a/docs/configuration/policy/rst-route-map.rst b/docs/configuration/policy/rst-route-map.rst deleted file mode 100644 index a2313466..00000000 --- a/docs/configuration/policy/rst-route-map.rst +++ /dev/null @@ -1,383 +0,0 @@ -################ -Route Map Policy -################ - -Route map is a powerfull command, that gives network administrators a very -useful and flexible tool for traffic manipulation. - -************* -Configuration -************* - -Route Map -========= - -.. cfgcmd:: set policy route-map <text> - - This command creates a new route-map policy, identified by <text>. - -.. cfgcmd:: set policy route-map <text> description <text> - - Set description for the route-map policy. - -.. cfgcmd:: set policy route-map <text> rule <1-65535> action <permit|deny> - - Set action for the route-map policy. - -.. cfgcmd:: set policy route-map <text> rule <1-65535> call <text> - - Call another route-map policy on match. - -.. cfgcmd:: set policy route-map <text> rule <1-65535> continue <1-65535> - - Jump to a different rule in this route-map on a match. - -.. cfgcmd:: set policy route-map <text> rule <1-65535> description <text> - - Set description for the rule in the route-map policy. - -.. cfgcmd:: set policy route-map <text> rule <1-65535> match as-path <text> - - BGP as-path list to match. - -.. cfgcmd:: set policy route-map <text> rule <1-65535> match community - community-list <text> - - BGP community-list to match. - -.. cfgcmd:: set policy route-map <text> rule <1-65535> match community - exact-match - - Set BGP community-list to exactly match. - -.. cfgcmd:: set policy route-map <text> rule <1-65535> match extcommunity - <text> - - BGP extended community to match. - -.. cfgcmd:: set policy route-map <text> rule <1-65535> match interface <text> - - First hop interface of a route to match. - -.. cfgcmd:: set policy route-map <text> rule <1-65535> match ip address - access-list <1-2699> - - IP address of route to match, based on access-list. - -.. cfgcmd:: set policy route-map <text> rule <1-65535> match ip address - prefix-list <text> - - IP address of route to match, based on prefix-list. - -.. cfgcmd:: set policy route-map <text> rule <1-65535> match ip address - prefix-len <0-32> - - IP address of route to match, based on specified prefix-length. - Note that this can be used for kernel routes only. - Do not apply to the routes of dynamic routing protocols (e.g. BGP, - RIP, OSFP), as this can lead to unexpected results.. - -.. cfgcmd:: set policy route-map <text> rule <1-65535> match ip nexthop - access-list <1-2699> - - IP next-hop of route to match, based on access-list. - -.. cfgcmd:: set policy route-map <text> rule <1-65535> match ip nexthop - address <x.x.x.x> - - IP next-hop of route to match, based on ip address. - -.. cfgcmd:: set policy route-map <text> rule <1-65535> match ip nexthop - prefix-len <0-32> - - IP next-hop of route to match, based on prefix length. - -.. cfgcmd:: set policy route-map <text> rule <1-65535> match ip nexthop - prefix-list <text> - - IP next-hop of route to match, based on prefix-list. - -.. cfgcmd:: set policy route-map <text> rule <1-65535> match ip nexthop - type <blackhole> - - IP next-hop of route to match, based on type. - -.. cfgcmd:: set policy route-map <text> rule <1-65535> match ip route-source - access-list <1-2699> - - IP route source of route to match, based on access-list. - -.. cfgcmd:: set policy route-map <text> rule <1-65535> match ip route-source - prefix-list <text> - - IP route source of route to match, based on prefix-list. - -.. cfgcmd:: set policy route-map <text> rule <1-65535> match ipv6 address - access-list <text> - - IPv6 address of route to match, based on IPv6 access-list. - -.. cfgcmd:: set policy route-map <text> rule <1-65535> match ipv6 address - prefix-list <text> - - IPv6 address of route to match, based on IPv6 prefix-list. - -.. cfgcmd:: set policy route-map <text> rule <1-65535> match ipv6 address - prefix-len <0-128> - - IPv6 address of route to match, based on specified prefix-length. - Note that this can be used for kernel routes only. - Do not apply to the routes of dynamic routing protocols (e.g. BGP, - RIP, OSFP), as this can lead to unexpected results.. - -.. cfgcmd:: set policy route-map <text> rule <1-65535> match ipv6 nexthop - <h:h:h:h:h:h:h:h> - - Nexthop IPv6 address to match. - -.. cfgcmd:: set policy route-map <text> rule <1-65535> match large-community - large-community-list <text> - - Match BGP large communities. - -.. cfgcmd:: set policy route-map <text> rule <1-65535> match local-preference - <0-4294967295> - - Match local preference. - -.. cfgcmd:: set policy route-map <text> rule <1-65535> match metric <1-65535> - - Match route metric. - -.. cfgcmd:: set policy route-map <text> rule <1-65535> match origin - <egp|igp|incomplete> - - Boarder Gateway Protocol (BGP) origin code to match. - -.. cfgcmd:: set policy route-map <text> rule <1-65535> match peer <x.x.x.x> - - Peer IP address to match. - -.. cfgcmd:: set policy route-map <text> rule <1-65535> match protocol <protocol> - - Source protocol to match. - * ``babel`` - Babel routing protocol (Babel) - * ``bgp`` - Border Gateway Protocol (BGP) - * ``connected`` - Connected routes (directly attached subnet or host) - * ``isis`` - Intermediate System to Intermediate System (IS-IS) - * ``kernel`` - Kernel routes - * ``ospf`` - Open Shortest Path First (OSPFv2) - * ``ospfv3`` - Open Shortest Path First (IPv6) (OSPFv3) - * ``rip`` - Routing Information Protocol (RIP) - * ``ripng`` - Routing Information Protocol next-generation (IPv6) (RIPng) - * ``static`` - Statically configured routes - * ``table`` - Non-main Kernel Routing Table - * ``vnc`` - Virtual Network Control (VNC) - -.. cfgcmd:: set policy route-map <text> rule <1-65535> match rpki - <invalid|notfound|valid> - - Match RPKI validation result. - -.. cfgcmd:: set policy route-map <text> rule <1-65535> match source-vrf <text> - - Source VRF to match. - -.. cfgcmd:: set policy route-map <text> rule <1-65535> match tag <1-65535> - - Route tag to match. - -.. cfgcmd:: set policy route-map <text> rule <1-65535> on-match goto <1-65535> - - Exit policy on match: go to rule <1-65535> - -.. cfgcmd:: set policy route-map <text> rule <1-65535> on-match next - - Exit policy on match: go to next sequence number. - -.. cfgcmd:: set policy route-map <text> rule <1-65535> set aggregator <as|ip> - <1-4294967295|x.x.x.x> - - BGP aggregator attribute: AS number or IP address of an aggregation. - -.. cfgcmd:: set policy route-map <text> rule <1-65535> set as-path exclude - <1-4294967295 | all> - - Drop AS-NUMBER from the BGP AS path. - - If ``all`` is specified, remove all AS numbers from the AS_PATH of the BGP - path's NLRI. - -.. cfgcmd:: set policy route-map <text> rule <1-65535> set as-path prepend - <1-4294967295> - - Prepend the given string of AS numbers to the AS_PATH of the BGP path's NLRI. - -.. cfgcmd:: set policy route-map <text> rule <1-65535> set as-path - prepend-last-as <n> - - Prepend the existing last AS number (the leftmost ASN) to the AS_PATH. - -.. cfgcmd:: set policy route-map <text> rule <1-65535> set atomic-aggregate - - BGP atomic aggregate attribute. - -.. cfgcmd:: set policy route-map <text> rule <1-65535> set community - <add|replace> <community> - - Add or replace BGP community attribute in format ``<0-65535:0-65535>`` - or from well-known community list - -.. cfgcmd:: set policy route-map <text> rule <1-65535> set community none - - Delete all BGP communities - -.. cfgcmd:: set policy route-map <text> rule <1-65535> set community delete - <text> - - Delete BGP communities matching the community-list. - -.. cfgcmd:: set policy route-map <text> rule <1-65535> set large-community - <add|replace> <GA:LDP1:LDP2> - - Add or replace BGP large-community attribute in format - ``<0-4294967295:0-4294967295:0-4294967295>`` - -.. cfgcmd:: set policy route-map <text> rule <1-65535> set large-community none - - Delete all BGP large-communities - -.. cfgcmd:: set policy route-map <text> rule <1-65535> set large-community delete - <text> - - Delete BGP communities matching the large-community-list. - -.. cfgcmd:: set policy route-map <text> rule <1-65535> set extcommunity bandwidth - <1-25600|cumulative|num-multipaths> - - Set extcommunity bandwidth - -.. cfgcmd:: set policy route-map <text> rule <1-65535> set extcommunity bandwidth-non-transitive - - The link bandwidth extended community is encoded as non-transitive - -.. cfgcmd:: set policy route-map <text> rule <1-65535> set extcommunity rt - <text> - - Set route target value in format ``<0-65535:0-4294967295>`` or ``<IP:0-65535>``. - -.. cfgcmd:: set policy route-map <text> rule <1-65535> set extcommunity soo - <text> - - Set site of origin value in format ``<0-65535:0-4294967295>`` or ``<IP:0-65535>``. - -.. cfgcmd:: set policy route-map <text> rule <1-65535> set extcommunity none - - Clear all BGP extcommunities. - -.. cfgcmd:: set policy route-map <text> rule <1-65535> set distance <0-255> - - Locally significant administrative distance. - - -.. cfgcmd:: set policy route-map <text> rule <1-65535> set ip-next-hop - <x.x.x.x> - - Nexthop IP address. - -.. cfgcmd:: set policy route-map <text> rule <1-65535> set ip-next-hop - unchanged - - Set the next-hop as unchanged. Pass through the route-map without - changing its value - -.. cfgcmd:: set policy route-map <text> rule <1-65535> set ip-next-hop - peer-address - - Set the BGP nexthop address to the address of the peer. For an incoming - route-map this means the ip address of our peer is used. For an - outgoing route-map this means the ip address of our self is used to - establish the peering with our neighbor. - -.. cfgcmd:: set policy route-map <text> rule <1-65535> set ipv6-next-hop - <global|local> <h:h:h:h:h:h:h:h> - - Nexthop IPv6 address. - -.. cfgcmd:: set policy route-map <text> rule <1-65535> set ipv6-next-hop - peer-address - - Set the BGP nexthop address to the address of the peer. For an incoming - route-map this means the ip address of our peer is used. For an - outgoing route-map this means the ip address of our self is used to - establish the peering with our neighbor. - -.. cfgcmd:: set policy route-map <text> rule <1-65535> set ipv6-next-hop - prefer-global - - For Incoming and Import Route-maps if we receive a v6 global and v6 LL - address for the route, then prefer to use the global address as the - nexthop. - -.. cfgcmd:: set policy route-map <text> rule <1-65535> set local-preference - <0-4294967295> - - Set BGP local preference attribute. - -.. cfgcmd:: set policy route-map <text> rule <1-65535> set metric - <+/-metric|0-4294967295|rtt|+rtt|-rtt> - - Set the route metric. When used with BGP, set the BGP attribute MED - to a specific value. Use ``+/-`` to add or subtract the specified value - to/from the existing/MED. Use ``rtt`` to set the MED to the round trip - time or ``+rtt/-rtt`` to add/subtract the round trip time to/from the MED. - -.. cfgcmd:: set policy route-map <text> rule <1-65535> set metric-type - <type-1|type-2> - - Set OSPF external metric-type. - -.. cfgcmd:: set policy route-map <text> rule <1-65535> set origin - <igp|egp|incomplete> - - Set BGP origin code. - -.. cfgcmd:: set policy route-map <text> rule <1-65535> set originator-id - <x.x.x.x> - - Set BGP originator ID attribute. - -.. cfgcmd:: set policy route-map <text> rule <1-65535> set src - <x.x.x.x|h:h:h:h:h:h:h:h> - - Set source IP/IPv6 address for route. - -.. cfgcmd:: set policy route-map <text> rule <1-65535> set table <1-200> - - Set prefixes to table. - -.. cfgcmd:: set policy route-map <text> rule <1-65535> set tag <1-65535> - - Set tag value for routing protocol. - -.. cfgcmd:: set policy route-map <text> rule <1-65535> set weight - <0-4294967295> - - Set BGP weight attribute - -List of well-known communities -============================== - * ``local-as`` - Well-known communities value NO_EXPORT_SUBCONFED 0xFFFFFF03 - * ``no-advertise`` - Well-known communities value NO_ADVERTISE 0xFFFFFF02 - * ``no-export`` - Well-known communities value NO_EXPORT 0xFFFFFF01 - * ``graceful-shutdown`` - Well-known communities value GRACEFUL_SHUTDOWN 0xFFFF0000 - * ``accept-own`` - Well-known communities value ACCEPT_OWN 0xFFFF0001 - * ``route-filter-translated-v4`` - Well-known communities value ROUTE_FILTER_TRANSLATED_v4 0xFFFF0002 - * ``route-filter-v4`` - Well-known communities value ROUTE_FILTER_v4 0xFFFF0003 - * ``route-filter-translated-v6`` - Well-known communities value ROUTE_FILTER_TRANSLATED_v6 0xFFFF0004 - * ``route-filter-v6`` - Well-known communities value ROUTE_FILTER_v6 0xFFFF0005 - * ``llgr-stale`` - Well-known communities value LLGR_STALE 0xFFFF0006 - * ``no-llgr`` - Well-known communities value NO_LLGR 0xFFFF0007 - * ``accept-own-nexthop`` - Well-known communities value accept-own-nexthop 0xFFFF0008 - * ``blackhole`` - Well-known communities value BLACKHOLE 0xFFFF029A - * ``no-peer`` - Well-known communities value NOPEER 0xFFFFFF04 diff --git a/docs/configuration/policy/rst-route.rst b/docs/configuration/policy/rst-route.rst deleted file mode 100644 index 1ddd04cf..00000000 --- a/docs/configuration/policy/rst-route.rst +++ /dev/null @@ -1,306 +0,0 @@ -####################### -Route and Route6 Policy -####################### - -IPv4 route and IPv6 route policies are defined in this section. These route -policies can then be associated to interfaces. - -********* -Rule-Sets -********* - -A rule-set is a named collection of rules that can be applied to an interface. -Each rule is numbered, has an action to apply if the rule is matched, and the -ability to specify the criteria to match. Data packets go through the rules -from 1 - 999999, at the first match the action of the rule will be executed. - -.. cfgcmd:: set policy route <name> description <text> -.. cfgcmd:: set policy route6 <name> description <text> - - Provide a rule-set description. - -.. cfgcmd:: set policy route <name> default-log -.. cfgcmd:: set policy route6 <name> default-log - - Option to log packets hitting default-action. - -.. cfgcmd:: set policy route <name> interface <interface> -.. cfgcmd:: set policy route6 <name> interface <interface> - - Apply routing policy to interface - -.. cfgcmd:: set policy route <name> rule <n> description <text> -.. cfgcmd:: set policy route6 <name> rule <n> description <text> - - Provide a description for each rule. - -.. cfgcmd:: set policy route <name> rule <n> log <enable|disable> -.. cfgcmd:: set policy route6 <name> rule <n> log <enable|disable> - - Option to enable or disable log matching rule. - -Matching criteria -================= - -There are a lot of matching criteria options available, both for -``policy route`` and ``policy route6``. These options are listed -in this section. - -.. cfgcmd:: set policy route <name> rule <n> connection-mark <1-2147483647> -.. cfgcmd:: set policy route6 <name> rule <n> connection-mark <1-2147483647> - - Set match criteria based on connection mark. - -.. cfgcmd:: set policy route <name> rule <n> mark <match_criteria> -.. cfgcmd:: set policy route6 <name> rule <n> mark <match_criteria> - - Match based on the firewall mark (fwmark), where <match_criteria> can be: - - * <0-2147483647> a single fwmark - * !<0-2147483647> everything except a single fwmark - * <start-end> a range of marks - * !<start-end> everything except the range of marks - - .. note:: When using the ``set table`` or ``set vrf`` commands the mark - settings are ignored and overwritten with a table-specific mark that - is set to 0x7FFFFFFF - the id of the table/VRF. - -.. cfgcmd:: set policy route <name> rule <n> source address - <match_criteria> -.. cfgcmd:: set policy route <name> rule <n> destination address - <match_criteria> -.. cfgcmd:: set policy route6 <name> rule <n> source address - <match_criteria> -.. cfgcmd:: set policy route6 <name> rule <n> destination address - <match_criteria> - - Set match criteria based on source or destination ipv4|ipv6 address, where - <match_criteria> could be: - -For ipv4: - * <x.x.x.x>: IP address to match. - * <x.x.x.x/x>: Subnet to match. - * <x.x.x.x>-<x.x.x.x>: IP range to match. - * !<x.x.x.x>: Match everything except the specified address. - * !<x.x.x.x/x>: Match everything except the specified subnet. - * !<x.x.x.x>-<x.x.x.x>: Match everything except the specified range. - -And for ipv6: - * <h:h:h:h:h:h:h:h>: IPv6 address to match. - * <h:h:h:h:h:h:h:h/x>: IPv6 prefix to match. - * <h:h:h:h:h:h:h:h>-<h:h:h:h:h:h:h:h>: IPv6 range to match. - * !<h:h:h:h:h:h:h:h>: Match everything except the specified address. - * !<h:h:h:h:h:h:h:h/x>: Match everything except the specified prefix. - * !<h:h:h:h:h:h:h:h>-<h:h:h:h:h:h:h:h>: Match everything except the - specified range. - -.. cfgcmd:: set policy route <name> rule <n> source group - <address-group|domain-group|mac-group|network-group|port-group> <text> -.. cfgcmd:: set policy route <name> rule <n> destination group - <address-group|domain-group|mac-group|network-group|port-group> <text> -.. cfgcmd:: set policy route6 <name> rule <n> source group - <address-group|domain-group|mac-group|network-group|port-group> <text> -.. cfgcmd:: set policy route6 <name> rule <n> destination group - <address-group|domain-group|mac-group|network-group|port-group> <text> - - Set match criteria based on source or destination groups, where <text> - would be the group name/identifier. Prepend character '!' for inverted - matching criteria. - -.. cfgcmd:: set policy route <name> rule <n> destination port <match_criteria> -.. cfgcmd:: set policy route6 <name> rule <n> destination port <match_criteria> - - Set match criteria based on destination port, where <match_criteria> could - be: - - * <port name>: Named port (any name in /etc/services, e.g., http). - * <1-65535>: Numbered port. - * <start>-<end>: Numbered port range (e.g., 1001-1005). - - Multiple destination ports can be specified as a comma-separated list. The - whole list can also be "negated" using '!'. For example: - '!22,telnet,http,123,1001-1005' - -.. cfgcmd:: set policy route <name> rule <n> disable -.. cfgcmd:: set policy route6 <name> rule <n> disable - - Option to disable rule. - -.. cfgcmd:: set policy route <name> rule <n> dscp <text> -.. cfgcmd:: set policy route6 <name> rule <n> dscp <text> -.. cfgcmd:: set policy route <name> rule <n> dscp-exclude <text> -.. cfgcmd:: set policy route6 <name> rule <n> dscp-exclude <text> - - Match based on dscp value criteria. Multiple values from 0 to 63 - and ranges are supported. - -.. cfgcmd:: set policy route <name> rule <n> fragment - <match-grag|match-non-frag> -.. cfgcmd:: set policy route6 <name> rule <n> fragment - <match-grag|match-non-frag> - - Set IP fragment match, where: - - * match-frag: Second and further fragments of fragmented packets. - * match-non-frag: Head fragments or unfragmented packets. - -.. cfgcmd:: set policy route <name> rule <n> icmp <code | type> -.. cfgcmd:: set policy route6 <name> rule <n> icmpv6 <code | type> - - Match based on icmp|icmpv6 code and type. - -.. cfgcmd:: set policy route <name> rule <n> icmp type-name <text> -.. cfgcmd:: set policy route6 <name> rule <n> icmpv6 type-name <text> - - Match based on icmp|icmpv6 type-name criteria. Use tab for information - about what type-name criteria are supported. - -.. cfgcmd:: set policy route <name> rule <n> ipsec - <match-ipsec|match-none> -.. cfgcmd:: set policy route6 <name> rule <n> ipsec - <match-ipsec|match-none> - - Set IPSec inbound match criterias, where: - - * match-ipsec: match inbound IPsec packets. - * match-none: match inbound non-IPsec packets. - -.. cfgcmd:: set policy route <name> rule <n> limit burst <0-4294967295> -.. cfgcmd:: set policy route6 <name> rule <n> limit burst <0-4294967295> - - Set maximum number of packets to alow in excess of rate. - -.. cfgcmd:: set policy route <name> rule <n> limit rate <text> -.. cfgcmd:: set policy route6 <name> rule <n> limit rate <text> - - Set maximum average matching rate. Format for rate: integer/time_unit, where - time_unit could be any one of second, minute, hour or day.For example - 1/second implies rule to be matched at an average of once per second. - -.. cfgcmd:: set policy route <name> rule <n> protocol - <text | 0-255 | tcp_udp | all > -.. cfgcmd:: set policy route6 <name> rule <n> protocol - <text | 0-255 | tcp_udp | all > - - Match a protocol criteria. A protocol number or a name which is defined in: - ``/etc/protocols``. Special names are ``all`` for all protocols and - ``tcp_udp`` for tcp and udp based packets. The ``!`` negates the selected - protocol. - -.. cfgcmd:: set policy route <name> rule <n> packet-length <text> -.. cfgcmd:: set policy route6 <name> rule <n> packet-length <text> -.. cfgcmd:: set policy route <name> rule <n> packet-length-exclude <text> -.. cfgcmd:: set policy route6 <name> rule <n> packet-length-exclude <text> - - Match based on packet length criteria. Multiple values from 1 to 65535 - and ranges are supported. - -.. cfgcmd:: set policy route <name> rule <n> packet-type [broadcast | host - | multicast | other] -.. cfgcmd:: set policy route6 <name> rule <n> packet-type [broadcast | host - | multicast | other] - - Match based on packet type criteria. - -.. cfgcmd:: set policy route <name> rule <n> recent count <1-255> -.. cfgcmd:: set policy route6 <name> rule <n> recent count <1-255> -.. cfgcmd:: set policy route <name> rule <n> recent time <1-4294967295> -.. cfgcmd:: set policy route6 <name> rule <n> recent time <1-4294967295> - - Set parameters for matching recently seen sources. This match could be used - by seeting count (source address seen more than <1-255> times) and/or time - (source address seen in the last <0-4294967295> seconds). - -.. cfgcmd:: set policy route <name> rule <n> state - <established | invalid | new | related> -.. cfgcmd:: set policy route6 <name> rule <n> state - <established | invalid | new | related> - - Set match criteria based on session state. - -.. cfgcmd:: set policy route <name> rule <n> tcp flags <text> -.. cfgcmd:: set policy route6 <name> rule <n> tcp flags <text> - - Set match criteria based on tcp flags. Allowed values for TCP flags: SYN ACK - FIN RST URG PSH ALL. When specifying more than one flag, flags should be - comma-separated. For example : value of 'SYN,!ACK,!FIN,!RST' will only match - packets with the SYN flag set, and the ACK, FIN and RST flags unset. - -.. cfgcmd:: set policy route <name> rule <n> time monthdays <text> -.. cfgcmd:: set policy route6 <name> rule <n> time monthdays <text> -.. cfgcmd:: set policy route <name> rule <n> time startdate <text> -.. cfgcmd:: set policy route6 <name> rule <n> time startdate <text> -.. cfgcmd:: set policy route <name> rule <n> time starttime <text> -.. cfgcmd:: set policy route6 <name> rule <n> time starttime <text> -.. cfgcmd:: set policy route <name> rule <n> time stopdate <text> -.. cfgcmd:: set policy route6 <name> rule <n> time stopdate <text> -.. cfgcmd:: set policy route <name> rule <n> time stoptime <text> -.. cfgcmd:: set policy route6 <name> rule <n> time stoptime <text> -.. cfgcmd:: set policy route <name> rule <n> time weekdays <text> -.. cfgcmd:: set policy route6 <name> rule <n> time weekdays <text> -.. cfgcmd:: set policy route <name> rule <n> time utc -.. cfgcmd:: set policy route6 <name> rule <n> time utc - - Time to match the defined rule. - -.. cfgcmd:: set policy route rule <n> ttl <eq | gt | lt> <0-255> - - Match time to live parameter, where 'eq' stands for 'equal'; 'gt' stands for - 'greater than', and 'lt' stands for 'less than'. - -.. cfgcmd:: set policy route6 rule <n> hop-limit <eq | gt | lt> <0-255> - - Match hop-limit parameter, where 'eq' stands for 'equal'; 'gt' stands for - 'greater than', and 'lt' stands for 'less than'. - -Actions -======= - -When mathcing all patterns defined in a rule, then different actions can -be made. This includes droping the packet, modifying certain data, or -setting a different routing table. - -.. cfgcmd:: set policy route <name> rule <n> action drop -.. cfgcmd:: set policy route6 <name> rule <n> action drop - - Set rule action to drop. - -.. cfgcmd:: set policy route <name> rule <n> set connection-mark - <1-2147483647> -.. cfgcmd:: set policy route6 <name> rule <n> set connection-mark - <1-2147483647> - - Set a specific connection mark. - -.. cfgcmd:: set policy route <name> rule <n> set dscp <0-63> -.. cfgcmd:: set policy route6 <name> rule <n> set dscp <0-63> - - Set packet modifications: Packet Differentiated Services Codepoint (DSCP) - -.. cfgcmd:: set policy route <name> rule <n> set mark <1-2147483647> -.. cfgcmd:: set policy route6 <name> rule <n> set mark <1-2147483647> - - Set a specific packet mark. - -.. cfgcmd:: set policy route <name> rule <n> set table <main | 1-200> -.. cfgcmd:: set policy route6 <name> rule <n> set table <main | 1-200> - - Set the routing table to forward packet with. - - .. note:: When using the ``set table`` or ``set vrf`` commands matching - against the mark is not possible, because it gets overwritten with a - table-specific mark that is 0x7FFFFFFF - the id of the table/VRF. - -.. cfgcmd:: set policy route <name> rule <n> set tcp-mss <500-1460> -.. cfgcmd:: set policy route6 <name> rule <n> set tcp-mss <500-1460> - - Set packet modifications: Explicitly set TCP Maximum segment size value. - -.. cfgcmd:: set policy route <name> rule <n> set vrf <default | text > -.. cfgcmd:: set policy route6 <name> rule <n> set vrf <default | text > - - Set the VRF to forward packet with. - - .. note:: When using the ``set table`` or ``set vrf`` commands matching - against the mark is not possible, because it gets overwritten with a - table-specific mark that is 0x7FFFFFFF - the id of the table/VRF. diff --git a/docs/configuration/protocols/rst-arp.rst b/docs/configuration/protocols/rst-arp.rst deleted file mode 100644 index 00865104..00000000 --- a/docs/configuration/protocols/rst-arp.rst +++ /dev/null @@ -1,64 +0,0 @@ -.. _routing-static-arp: -.. meta:: - :description: The Address Resolution Protocol (ARP) resolves - network-layer addresses to link-layer MAC addresses. - :keywords: arp, network, protocol, mac, address, ipv4, static - -### -ARP -### - -The :abbr:`ARP (Address Resolution Protocol)` resolves IPv4 network layer addresses -to link layer MAC addresses. -addresses. This mapping is essential for communication within the Internet -Protocol suite. ARP was standardized in 1982 by :rfc:`826` (STD 37). - -.. note:: In Internet Protocol version 6 (IPv6) networks, address resolution is - performed by the Neighbor Discovery Protocol (NDP). - -Use the following commands to configure or view ARP table entries. - -Configuration -------------- - -.. cfgcmd:: set protocols static arp interface <interface> address <host> mac <mac> - - **Configure a static ARP entry on the specified interface.** - - This creates a permanent mapping between an IP address and a MAC address - on the specified interface. - - Example: - - .. code-block:: none - - set protocols static arp interface eth0 address 192.0.2.1 mac 01:23:45:67:89:01 - -Operation ---------- - -.. opcmd:: show protocols static arp - - Show all ARP table entries across all interfaces. - - .. code-block:: none - - vyos@vyos:~$ show protocols static arp - Address HWtype HWaddress Flags Mask Iface - 10.1.1.1 ether 00:53:00:de:23:2e C eth1 - 10.1.1.100 ether 00:53:00:de:23:aa CM eth1 - -.. opcmd:: show protocols static arp interface <interface> - - Show all ARP table entries for the specific interface. - - Example for ``eth1``: - - .. code-block:: none - - vyos@vyos:~$ show protocols static arp interface eth1 - Address HWtype HWaddress Flags Mask Iface - 10.1.1.1 ether 00:53:00:de:23:2e C eth1 - 10.1.1.100 ether 00:53:00:de:23:aa CM eth1 - -.. _ARP: https://en.wikipedia.org/wiki/Address_Resolution_Protocol
\ No newline at end of file diff --git a/docs/configuration/protocols/rst-babel.rst b/docs/configuration/protocols/rst-babel.rst deleted file mode 100644 index 95543da2..00000000 --- a/docs/configuration/protocols/rst-babel.rst +++ /dev/null @@ -1,278 +0,0 @@ -.. _babel: -.. meta:: - :description: The Babel routing protocol provides robust and efficient - routing for wired and wireless mesh networks. - :keywords: babel, routing, protocol, wireless, mesh, network, metric, - ipv4, ipv6 - -##### -Babel -##### - -The Babel protocol provides robust and efficient routing for both wired and -wireless mesh networks. By default, Babel uses hop-count metrics on wired links -and a variant of Expected Transmission Count (ETX) on wireless links. -Administrators can configure Babel to account for radio diversity, -automatically compute link latency, and include that latency in the routing -metric. :rfc:`8966` defines the Babel protocol. - -Babel is a dual-stack protocol. A single Babel instance routes both IPv4 and -IPv6 traffic simultaneously. - -General configuration ---------------------- - -VyOS does not require a specific command to start the Babel process. The system -automatically starts the routing process when you configure the first -Babel-enabled interface. - -.. cfgcmd:: set protocols babel interface <interface> - - **Enable Babel routing on the specified interface.** - - The system immediately begins sending and receiving Babel packets on this - interface. - -Optional configuration ----------------------- - -.. cfgcmd:: set protocols babel parameters diversity - - **Enable radio-frequency diversity routing for the Babel process.** - - Enabling this feature is highly recommended for networks with many - wireless nodes. - - .. note:: When you enable diversity routing, you should also configure the - ``diversity-factor`` and ``channel`` parameters. - -.. cfgcmd:: set protocols babel parameters diversity-factor <1-256> - - **Configure the multiplicative factor for diversity routing, in units of - 1/256.** - - Lower multiplicative factors give greater weight to diversity in route - selection. The default value is 256, which disables diversity routing. - On nodes with multiple independent radios, configure a value of 128 or less. - -.. cfgcmd:: set protocols babel parameters resend-delay <20-655340> - - **Configure the delay in milliseconds before the system resends an - important request or update.** - - The default value is 2000 ms. - -.. cfgcmd:: set protocols babel parameters smoothing-half-life <0-65534> - - **Configure the time constant, in seconds, for the smoothing algorithm used - to implement hysteresis.** - - Higher values reduce route oscillation but slightly increase convergence - time. A value of 0 disables hysteresis and is suitable for wired networks. - The default is 4 seconds. - -Interfaces configuration ------------------------- - -.. cfgcmd:: set protocols babel interface <interface> type <auto|wired|wireless> - - **Configure the network type for the Babel-enabled interface.** - - Choose from the following: - - * ``auto``: Babel automatically detects if an interface is wired or - wireless. - * ``wired``: Babel enables optimizations for wired interfaces. - * ``wireless``: Babel disables optimizations suitable only for wired - interfaces. Specifying wireless is always correct, but may cause slower - convergence and increased routing traffic. - -.. cfgcmd:: set protocols babel interface <interface> split-horizon <default|disable|enable> - - **Configure the split-horizon routing behavior for the specified - interface.** - - Use one of the following options: - - * ``default``: Babel automatically enables split-horizon on wired - interfaces and disables it on wireless interfaces. - * ``enable``: Babel enables split-horizon on the interface. This - optimization should be used only on symmetric, transitive (wired) - networks. - * ``disable``: Babel disables split-horizon on the interface. Disabling - split-horizon is always safe and correct. - -.. cfgcmd:: set protocols babel interface <interface> hello-interval <20-655340> - - **Configure the interval, in milliseconds, between scheduled hello messages - on the specified interface.** - - On wired links, Babel detects link failures within two hello intervals. - On wireless links, link quality is reestimated at each interval. The - default is 4000 ms. - -.. cfgcmd:: set protocols babel interface <interface> update-interval <20-655340> - - **Configure the interval, in milliseconds, between scheduled routing - updates on the specified interface.** - - Because Babel uses triggered updates extensively, you can increase this - value on reliable links with minimal packet loss. The default is 20000 ms. - -.. cfgcmd:: set protocols babel interface <interface> rxcost <1-65534> - - **Configure the base receive cost for the specified interface.** - - Babel applies this value based on the configured network type: - - * ``wired``: The value is the routing cost advertised to neighboring - routers. - * ``wireless``: The value is a multiplier used to compute the ETX - (Expected Transmission Count) reception cost. - - The default value is 256. - -.. cfgcmd:: set protocols babel interface <interface> rtt-decay <1-256> - - **Configure the decay factor for the exponential moving average of RTT - samples, in units of 1/256.** - - Higher values discard older samples faster. The default value is 42. - -.. cfgcmd:: set protocols babel interface <interface> rtt-min <1-65535> - - **Configure the minimum RTT, in milliseconds, at which the cost to a - neighbor begins to increase.** - - The additional cost is linear in (rtt - rtt-min). The default value is 10 ms. - -.. cfgcmd:: set protocols babel interface <interface> rtt-max <1-65535> - - **Configure the maximum RTT, in milliseconds, above which the cost to a - neighbor stops increasing.** - - The default value is 120 ms. - -.. cfgcmd:: set protocols babel interface <interface> max-rtt-penalty <0-65535> - - **Configure the maximum cost added to a neighbor when RTT meets or exceeds - rtt-max.** - - Setting this value to 0 disables RTT-based costs. The default value is 150. - -.. cfgcmd:: set protocols babel interface <interface> enable-timestamps - - **Configure adding timestamps to each Hello and IHU message to calculate - RTT values.** - - Enabling timestamps is recommended for tunnel interfaces. - -.. cfgcmd:: set protocols babel interface <interface> channel <1-254|interfering|noninterfering> - - **Configure the channel identifier that diversity routing uses for the - specified interface.** - - Interfaces interfere with each other based on the assigned channel - identifier: - - * ``1–254``: The interface interferes with interfaces sharing the same - channel number and with interfaces configured as ``interfering``. - * ``interfering``: The interface interferes with all others except those - configured as ``noninterfering``. - * ``noninterfering``: The interface interferes only with itself. - -Redistribution configuration ----------------------------- - -.. cfgcmd:: set protocols babel redistribute <ipv4|ipv6> <route source> - - **Configure the redistribution of routing information from the specified - route source into the Babel process.** - - The following route sources are available: - - * **ipv4:** ``bgp``, ``connected``, ``eigrp``, ``isis``, ``kernel``, - ``nhrp``, ``ospf``, ``rip``, ``static`` - * **ipv6:** ``bgp``, ``connected``, ``eigrp``, ``isis``, ``kernel``, - ``nhrp``, ``ospfv3``, ``ripng``, ``static`` - -.. cfgcmd:: set protocols babel distribute-list <ipv4|ipv6> access-list <in|out> <number> - - **Configure global Babel route filtering using an access list.** - - Specify the direction in which the access list is applied: - - * ``in``: Filters incoming routes. - * ``out``: Filters outgoing routes. - -.. cfgcmd:: set protocols babel distribute-list <ipv4|ipv6> interface <interface> access-list <in|out> <number> - - **Configure Babel route filtering on the specified interface using an - access list.** - - Specify the direction in which the access list is applied: - - * ``in``: Filters incoming routes. - * ``out``: Filters outgoing routes. - -.. cfgcmd:: set protocols babel distribute-list <ipv4|ipv6> prefix-list <in|out> <name> - - **Configure global Babel route filtering using a prefix list.** - - Specify the direction in which the prefix list is applied: - - * ``in``: Filters incoming routes. - * ``out``: Filters outgoing routes. - -.. cfgcmd:: set protocols babel distribute-list <ipv4|ipv6> interface <interface> prefix-list <in|out> <name> - - **Configure Babel route filtering on the specified interface using a - prefix list.** - - Specify the direction in which the prefix list is applied: - - * ``in``: Filters incoming routes. - * ``out``: Filters outgoing routes. - -Configuration example ---------------------- - -Basic two-node babel network -^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -**Goal:** The following example connects two routers (Node 1 and Node 2) via -their eth0 interfaces and uses the Babel routing protocol to advertise -(redistribute) each router's locally configured networks (represented by -loopback addresses) to one another. - -**Node 1:** - -.. code-block:: none - - # Configure the loopback (local networks) and physical (eth0) addresses - set interfaces loopback lo address 10.1.1.1/32 - set interfaces loopback lo address fd12:3456:dead:beef::1/128 - set interfaces ethernet eth0 address 192.168.1.1/24 - - # Enable Babel on the physical link - set protocols babel interface eth0 type wired - - # Instruct Babel to advertise (redistribute) the locally configured networks - set protocols babel redistribute ipv4 connected - set protocols babel redistribute ipv6 connected - -**Node 2:** - -.. code-block:: none - - # Configure the loopback (local networks) and physical (eth0) addresses - set interfaces loopback lo address 10.2.2.2/32 - set interfaces loopback lo address fd12:3456:beef:dead::2/128 - set interfaces ethernet eth0 address 192.168.1.2/24 - - # Enable Babel on the physical link - set protocols babel interface eth0 type wired - - # Tell Babel to advertise (redistribute) the locally configured networks - set protocols babel redistribute ipv4 connected - set protocols babel redistribute ipv6 connected diff --git a/docs/configuration/protocols/rst-bfd.rst b/docs/configuration/protocols/rst-bfd.rst deleted file mode 100644 index 30876efc..00000000 --- a/docs/configuration/protocols/rst-bfd.rst +++ /dev/null @@ -1,199 +0,0 @@ -:lastproofread: 2023-01-27 - -.. include:: /_include/need_improvement.txt - -.. _routing-bfd: - -### -BFD -### - -:abbr:`BFD (Bidirectional Forwarding Detection)` is described and extended by -the following RFCs: :rfc:`5880`, :rfc:`5881` and :rfc:`5883`. - -In the age of very fast networks, a second of unreachability may equal millions of lost packets. -The idea behind BFD is to detect very quickly when a peer is down and take action extremely fast. - -BFD sends lots of small UDP packets very quickly to ensures that the peer is still alive. - -This allows avoiding the timers defined in BGP and OSPF protocol to expires. - -Configure BFD -============= - -.. cfgcmd:: set protocols bfd peer <address> - - Set BFD peer IPv4 address or IPv6 address - -.. cfgcmd:: set protocols bfd peer <address> echo-mode - - Enables the echo transmission mode - -.. cfgcmd:: set protocols bfd peer <address> multihop - - Allow this BFD peer to not be directly connected - -.. cfgcmd:: set protocols bfd peer <address> source - [address <address> | interface <interface>] - - Bind listener to specific interface/address, mandatory for IPv6 - -.. cfgcmd:: set protocols bfd peer <address> interval echo-interval <10-60000> - - The minimal echo receive transmission interval that this system is - capable of handling - -.. cfgcmd:: set protocols bfd peer <address> interval multiplier <2-255> - - Remote transmission interval will be multiplied by this value - -.. cfgcmd:: set protocols bfd peer <address> interval - [receive | transmit] <10-60000> - - Interval in milliseconds - -.. cfgcmd:: set protocols bfd peer <address> shutdown - - Disable a BFD peer - -.. cfgcmd:: set protocols bfd peer <address> minimum-ttl <1-254> - - For multi hop sessions only. Configure the minimum expected TTL for an - incoming BFD control packet. - - This feature serves the purpose of thightening the packet validation - requirements to avoid receiving BFD control packets from other sessions. - -Enable BFD in BGP ------------------ - -.. cfgcmd:: set protocols bgp neighbor <neighbor> bfd - - Enable BFD on a single BGP neighbor - -.. cfgcmd:: set protocols bgp peer-group <neighbor> bfd - - Enable BFD on a BGP peer group - - -Enable BFD in OSPF ------------------- - -.. cfgcmd:: set protocols ospf interface <interface> bfd - - Enable BFD for OSPF on an interface - -.. cfgcmd:: set protocols ospfv3 interface <interface> bfd - - Enable BFD for OSPFv3 on an interface - - -Enable BFD in ISIS ------------------- - -.. cfgcmd:: set protocols isis <name> interface <interface> bfd - - Enable BFD for ISIS on an interface - - - -Operational Commands -==================== - -.. opcmd:: show bfd peers - - Show all BFD peers - - .. code-block:: none - - BFD Peers: - peer 198.51.100.33 vrf default interface eth4.100 - ID: 4182341893 - Remote ID: 12678929647 - Status: up - Uptime: 1 month(s), 16 hour(s), 29 minute(s), 38 second(s) - Diagnostics: ok - Remote diagnostics: ok - Local timers: - Receive interval: 300ms - Transmission interval: 300ms - Echo transmission interval: 50ms - Remote timers: - Receive interval: 300ms - Transmission interval: 300ms - Echo transmission interval: 0ms - - peer 198.51.100.55 vrf default interface eth4.101 - ID: 4618932327 - Remote ID: 3312345688 - Status: up - Uptime: 20 hour(s), 16 minute(s), 19 second(s) - Diagnostics: ok - Remote diagnostics: ok - Local timers: - Receive interval: 300ms - Transmission interval: 300ms - Echo transmission interval: 50ms - Remote timers: - Receive interval: 300ms - Transmission interval: 300ms - Echo transmission interval: 0ms - -BFD Static Route Monitoring -=========================== - -A monitored static route conditions the installation to the RIB on the BFD -session running state: when BFD session is up the route is installed to RIB, -but when the BFD session is down it is removed from the RIB. - -Configuration -------------- - -.. cfgcmd:: set protocols static route <subnet> next-hop <address> - bfd profile <profile> - - Configure a static route for <subnet> using gateway <address> - and use the gateway address as BFD peer destination address. - -.. cfgcmd:: set protocols static route <subnet> next-hop <address> - bfd multi-hop source <address> profile <profile> - - Configure a static route for <subnet> using gateway <address> - , use source address to indentify the peer when is multi-hop session - and the gateway address as BFD peer destination address. - -.. cfgcmd:: set protocols static route6 <subnet> next-hop <address> - bfd profile <profile> - - Configure a static route for <subnet> using gateway <address> - and use the gateway address as BFD peer destination address. - -.. cfgcmd:: set protocols static route6 <subnet> next-hop <address> - bfd multi-hop source <address> profile <profile> - - Configure a static route for <subnet> using gateway <address> - , use source address to indentify the peer when is multi-hop session - and the gateway address as BFD peer destination address. - - -.. _BFD Operational Commands: - -Operational Commands -==================== - -.. opcmd:: show bfd static routes - - Showing BFD monitored static routes - - .. code-block:: none - - Showing BFD monitored static routes: - - Next hops: - VRF default IPv4 Unicast: - 10.10.13.3/32 peer 192.168.2.3 (status: installed) - 172.16.10.3/32 peer 192.168.10.1 (status: uninstalled) - - VRF default IPv4 Multicast: - - VRF default IPv6 Unicast: diff --git a/docs/configuration/protocols/rst-bgp.rst b/docs/configuration/protocols/rst-bgp.rst deleted file mode 100644 index 736cb4cc..00000000 --- a/docs/configuration/protocols/rst-bgp.rst +++ /dev/null @@ -1,1281 +0,0 @@ -.. _routing-bgp: - -### -BGP -### - -:abbr:`BGP (Border Gateway Protocol)` is one of the Exterior Gateway Protocols -and the de facto standard interdomain routing protocol. The latest BGP version -is 4. BGP-4 is described in :rfc:`1771` and updated by :rfc:`4271`. :rfc:`2858` -adds multiprotocol support to BGP. - -VyOS makes use of :abbr:`FRR (Free Range Routing)` and we would like to thank -them for their effort! - -************** -Basic Concepts -************** - -.. _bgp-autonomous-systems: - -Autonomous Systems -================== - -From :rfc:`1930`: - - An AS is a connected group of one or more IP prefixes run by one or more - network operators which has a SINGLE and CLEARLY DEFINED routing policy. - -Each :abbr:`AS (Autonomous System)` has an identifying number associated with it -called an :abbr:`ASN (Autonomous System Number)`. This is a two octet value -ranging in value from 1 to 65535. The AS numbers 64512 through 65535 are defined -as private AS numbers. Private AS numbers must not be advertised on the global -Internet. The 2-byte AS number range has been exhausted. 4-byte AS numbers are -specified in :rfc:`6793`, and provide a pool of 4294967296 AS numbers. - -The :abbr:`ASN (Autonomous System Number)` is one of the essential elements of -BGP. BGP is a distance vector routing protocol, and the AS-Path framework -provides distance vector metric and loop detection to BGP. - -.. cfgcmd:: set protocols bgp system-as <asn> - - Set local :abbr:`ASN (Autonomous System Number)` that this router represents. - This is a a mandatory option! - -.. _bgp-address-families: - -Address Families -================ - -Multiprotocol extensions enable BGP to carry routing information for multiple -network layer protocols. BGP supports an Address Family Identifier (AFI) for -IPv4 and IPv6. - -.. _bgp-route-selection: - -Route Selection -=============== - -The route selection process used by FRR's BGP implementation uses the following -decision criterion, starting at the top of the list and going towards the -bottom until one of the factors can be used. - -1. **Weight check** - - Prefer higher local weight routes to lower routes. - -2. **Local preference check** - - Prefer higher local preference routes to lower. - -3. **Local route check** - - Prefer local routes (statics, aggregates, redistributed) to received routes. - -4. **AS path length check** - - Prefer shortest hop-count AS_PATHs. - -5. **Origin check** - - Prefer the lowest origin type route. That is, prefer IGP origin routes to - EGP, to Incomplete routes. - -6. **MED check** - - Where routes with a MED were received from the same AS, prefer the route - with the lowest MED. - -7. **External check** - - Prefer the route received from an external, eBGP peer over routes received - from other types of peers. - -8. **IGP cost check** - - Prefer the route with the lower IGP cost. - -9. **Multi-path check** - - If multi-pathing is enabled, then check whether the routes not yet - distinguished in preference may be considered equal. If - :cfgcmd:`bgp bestpath as-path multipath-relax` is set, all such routes are - considered equal, otherwise routes received via iBGP with identical AS_PATHs - or routes received from eBGP neighbours in the same AS are considered equal. - -10. **Already-selected external check** - - Where both routes were received from eBGP peers, then prefer the route - which is already selected. Note that this check is not applied if - :cfgcmd:`bgp bestpath compare-routerid` is configured. This check can - prevent some cases of oscillation. - -11. **Router-ID check** - - Prefer the route with the lowest `router-ID`. If the route has an - `ORIGINATOR_ID` attribute, through iBGP reflection, then that router ID is - used, otherwise the `router-ID` of the peer the route was received from is - used. - -12. **Cluster-List length check** - - The route with the shortest cluster-list length is used. The cluster-list - reflects the iBGP reflection path the route has taken. - -13. **Peer address** - - Prefer the route received from the peer with the higher transport layer - address, as a last-resort tie-breaker. - -.. _bgp-capability-negotiation: - -Capability Negotiation -====================== - -When adding IPv6 routing information exchange feature to BGP. There were some -proposals. :abbr:`IETF (Internet Engineering Task Force)` -:abbr:`IDR (Inter Domain Routing)` adopted a proposal called Multiprotocol -Extension for BGP. The specification is described in :rfc:`2283`. The protocol -does not define new protocols. It defines new attributes to existing BGP. When -it is used exchanging IPv6 routing information it is called BGP-4+. When it is -used for exchanging multicast routing information it is called MBGP. - -*bgpd* supports Multiprotocol Extension for BGP. So if a remote peer supports -the protocol, *bgpd* can exchange IPv6 and/or multicast routing information. - -Traditional BGP did not have the feature to detect a remote peer's -capabilities, e.g. whether it can handle prefix types other than IPv4 unicast -routes. This was a big problem using Multiprotocol Extension for BGP in an -operational network. :rfc:`2842` adopted a feature called Capability -Negotiation. *bgpd* use this Capability Negotiation to detect the remote peer's -capabilities. If a peer is only configured as an IPv4 unicast neighbor, *bgpd* -does not send these Capability Negotiation packets (at least not unless other -optional BGP features require capability negotiation). - -By default, FRR will bring up peering with minimal common capability for the -both sides. For example, if the local router has unicast and multicast -capabilities and the remote router only has unicast capability the local router -will establish the connection with unicast only capability. When there are no -common capabilities, FRR sends Unsupported Capability error and then resets the -connection. - -************* -Configuration -************* - -.. _bgp-router-configuration: - -BGP Router Configuration -======================== - -First of all you must configure BGP router with the :abbr:`ASN (Autonomous -System Number)`. The AS number is an identifier for the autonomous system. -The BGP protocol uses the AS number for detecting whether the BGP connection -is internal or external. VyOS does not have a special command to start the BGP -process. The BGP process starts when the first neighbor is configured. - -.. cfgcmd:: set protocols bgp system-as <asn> - - Set local autonomous system number that this router represents. This is a - mandatory option! - -Peers Configuration -------------------- - -Defining Peers -^^^^^^^^^^^^^^ - -.. cfgcmd:: set protocols bgp neighbor <address|interface> remote-as - <asn> - - This command creates a new neighbor whose remote-as is <asn>. The neighbor - address can be an IPv4 address or an IPv6 address or an interface to use - for the connection. The command is applicable for peer and peer group. - -.. cfgcmd:: set protocols bgp neighbor <address|interface> remote-as - internal - - Create a peer as you would when you specify an ASN, except that if the - peers ASN is different than mine as specified under the :cfgcmd:`protocols - bgp <asn>` command the connection will be denied. - -.. cfgcmd:: set protocols bgp neighbor <address|interface> remote-as - external - - Create a peer as you would when you specify an ASN, except that if the - peers ASN is the same as mine as specified under the :cfgcmd:`protocols - bgp <asn>` command the connection will be denied. - -.. cfgcmd:: set protocols bgp neighbor <address|interface> remote-as - auto - - Create a peer as you would when you specify an ASN, except that the peers - remote ASN is detected automatically from the OPEN message. - -.. cfgcmd:: set protocols bgp neighbor <address|interface> local-role - <role> [strict] - - BGP roles are defined in RFC :rfc:`9234` and provide an easy way to - add route leak prevention, detection and mitigation. The local Role - value is negotiated with the new BGP Role capability which has a - built-in check of the corresponding value. In case of a mismatch the - new OPEN Roles Mismatch Notification <2, 11> would be sent. - The correct Role pairs are: - - Provider - Customer - - Peer - Peer - - RS-Server - RS-Client - - If :cfgcmd:`strict` is set the BGP session won’t become established - until the BGP neighbor sets local Role on its side. This - configuration parameter is defined in RFC :rfc:`9234` and is used to - enforce the corresponding configuration at your counter-parts side. - - Routes that are sent from provider, rs-server, or the peer local-role - (or if received by customer, rs-client, or the peer local-role) will - be marked with a new Only to Customer (OTC) attribute. - - Routes with this attribute can only be sent to your neighbor if your - local-role is provider or rs-server. Routes with this attribute can - be received only if your local-role is customer or rs-client. - - In case of peer-peer relationship routes can be received only if OTC - value is equal to your neighbor AS number. - - All these rules with OTC will help to detect and mitigate route leaks - and happen automatically if local-role is set. - -.. cfgcmd:: set protocols bgp neighbor <address|interface> shutdown - - This command disable the peer or peer group. To reenable the peer use - the delete form of this command. - -.. cfgcmd:: set protocols bgp neighbor <address|interface> description - <text> - - Set description of the peer or peer group. - -.. cfgcmd:: set protocols bgp neighbor <address|interface> update-source - <address|interface> - - Specify the IPv4 source address to use for the BGP session to this neighbor, - may be specified as either an IPv4 address directly or as an interface name. - -.. _bgp_capability_negotiation: - -Capability Negotiation -^^^^^^^^^^^^^^^^^^^^^^ - -.. cfgcmd:: set protocols bgp neighbor <address|interface> capability - dynamic - - This command would allow the dynamic update of capabilities over an - established BGP session. - -.. cfgcmd:: set protocols bgp neighbor <address|interface> capability - extended-nexthop - - Allow bgp to negotiate the extended-nexthop capability with it’s peer. - If you are peering over a IPv6 Link-Local address then this capability - is turned on automatically. If you are peering over a IPv6 Global Address - then turning on this command will allow BGP to install IPv4 routes with - IPv6 nexthops if you do not have IPv4 configured on interfaces. - -.. cfgcmd:: set protocols bgp neighbor <address|interface> - disable-capability-negotiation - - Suppress sending Capability Negotiation as OPEN message optional - parameter to the peer. This command only affects the peer is - configured other than IPv4 unicast configuration. - - When remote peer does not have capability negotiation feature, - remote peer will not send any capabilities at all. In that case, - bgp configures the peer with configured capabilities. - - You may prefer locally configured capabilities more than the negotiated - capabilities even though remote peer sends capabilities. If the peer is - configured by :cfgcmd:`override-capability`, VyOS ignores received - capabilities then override negotiated capabilities with configured values. - - Additionally you should keep in mind that this feature fundamentally - disables the ability to use widely deployed BGP features. BGP unnumbered, - hostname support, AS4, Addpath, Route Refresh, ORF, Dynamic Capabilities, - and graceful restart. - -.. cfgcmd:: set protocols bgp neighbor <address|interface> - override-capability - - This command allow override the result of Capability Negotiation with - local configuration. Ignore remote peer’s capability value. - -.. cfgcmd:: set protocols bgp neighbor <address|interface> - strict-capability-match - - This command forces strictly compare remote capabilities and local - capabilities. If capabilities are different, send Unsupported Capability - error then reset connection. - - You may want to disable sending Capability Negotiation OPEN message - optional parameter to the peer when remote peer does not implement - Capability Negotiation. Please use :cfgcmd:`disable-capability-negotiation` - command to disable the feature. - - -Peer Parameters -^^^^^^^^^^^^^^^ - -.. cfgcmd:: set protocols bgp neighbor <address|interface> address-family - <ipv4-unicast|ipv6-unicast> allowas-in number <number> - - This command accept incoming routes with AS path containing AS - number with the same value as the current system AS. This is - used when you want to use the same AS number in your sites, - but you can’t connect them directly. - - The number parameter (1-10) configures the amount of accepted - occurences of the system AS number in AS path. - - This command is only allowed for eBGP peers. It is not applicable - for peer groups. - -.. cfgcmd:: set protocols bgp neighbor <address|interface> address-family - <ipv4-unicast|ipv6-unicast> as-override - - This command override AS number of the originating router with - the local AS number. - - Usually this configuration is used in PEs (Provider Edge) to - replace the incoming customer AS number so the connected CE ( - Customer Edge) can use the same AS number as the other customer - sites. This allows customers of the provider network to use the - same AS number across their sites. - - This command is only allowed for eBGP peers. - -.. cfgcmd:: set protocols bgp neighbor <address|interface> address-family - <ipv4-unicast|ipv6-unicast> attribute-unchanged <as-path|med|next-hop> - - This command specifies attributes to be left unchanged for - advertisements sent to a peer or peer group. - -.. cfgcmd:: set protocols bgp neighbor <address|interface> address-family - <ipv4-unicast|ipv6-unicast> maximum-prefix <number> - - This command specifies a maximum number of prefixes we can receive - from a given peer. If this number is exceeded, the BGP session - will be destroyed. The number range is 1 to 4294967295. - -.. cfgcmd:: set protocols bgp neighbor <address|interface> address-family - <ipv4-unicast|ipv6-unicast> nexthop-self - - This command forces the BGP speaker to report itself as the - next hop for an advertised route it advertised to a neighbor. - -.. cfgcmd:: set protocols bgp neighbor <address|interface> address-family - <ipv4-unicast|ipv6-unicast> remove-private-as - - This command removes the private ASN of routes that are advertised - to the configured peer. It removes only private ASNs on routes - advertised to EBGP peers. - - If the AS-Path for the route has only private ASNs, the private - ASNs are removed. - - If the AS-Path for the route has a private ASN between public - ASNs, it is assumed that this is a design choice, and the - private ASN is not removed. - -.. cfgcmd:: set protocols bgp neighbor <address|interface> address-family - <ipv4-unicast|ipv6-unicast> soft-reconfiguration inbound - - Changes in BGP policies require the BGP session to be cleared. Clearing has a - large negative impact on network operations. Soft reconfiguration enables you - to generate inbound updates from a neighbor, change and activate BGP policies - without clearing the BGP session. - - This command specifies that route updates received from this neighbor will be - stored unmodified, regardless of the inbound policy. When inbound soft - reconfiguration is enabled, the stored updates are processed by the new - policy configuration to create new inbound updates. - - .. note:: Storage of route updates uses memory. If you enable soft - reconfiguration inbound for multiple neighbors, the amount of memory used - can become significant. - -.. cfgcmd:: set protocols bgp neighbor <address|interface> address-family - <ipv4-unicast|ipv6-unicast> weight <number> - - This command specifies a default weight value for the neighbor’s - routes. The number range is 1 to 65535. - -.. cfgcmd:: set protocols bgp neighbor <address|interface> - advertisement-interval <seconds> - - This command specifies the minimum route advertisement interval for - the peer. The interval value is 0 to 600 seconds, with the default - advertisement interval being 0. - -.. cfgcmd:: set protocols bgp neighbor <address|interface> - disable-connected-check - - This command allows peerings between directly connected eBGP peers - using loopback addresses without adjusting the default TTL of 1. - -.. cfgcmd:: set protocols bgp neighbor <address|interface> - disable-send-community <extended|standard> - - This command specifies that the community attribute should not be sent - in route updates to a peer. By default community attribute is sent. - -.. cfgcmd:: set protocols bgp neighbor <address|interface> ebgp-multihop - <number> - - This command allows sessions to be established with eBGP neighbors - when they are multiple hops away. When the neighbor is not directly - connected and this knob is not enabled, the session will not establish. - The number of hops range is 1 to 255. This command is mutually - exclusive with :cfgcmd:`ttl-security hops`. - -.. cfgcmd:: set protocols bgp neighbor <address|interface> local-as <asn> - [no-prepend] [replace-as] - - Specify an alternate AS for this BGP process when interacting with - the specified peer or peer group. With no modifiers, the specified - local-as is prepended to the received AS_PATH when receiving routing - updates from the peer, and prepended to the outgoing AS_PATH (after - the process local AS) when transmitting local routes to the peer. - - If the :cfgcmd:`no-prepend` attribute is specified, then the supplied - local-as is not prepended to the received AS_PATH. - - If the :cfgcmd:`replace-as` attribute is specified, then only the supplied - local-as is prepended to the AS_PATH when transmitting local-route - updates to this peer. - - .. note:: This command is only allowed for eBGP peers. - -.. cfgcmd:: set protocols bgp neighbor <address|interface> passive - - Configures the BGP speaker so that it only accepts inbound connections - from, but does not initiate outbound connections to the peer or peer group. - -.. cfgcmd:: set protocols bgp neighbor <address|interface> password - <text> - - This command specifies a MD5 password to be used with the tcp socket that - is being used to connect to the remote peer. - -.. cfgcmd:: set protocols bgp neighbor <address|interface> ttl-security - hops <number> - - This command enforces Generalized TTL Security Mechanism (GTSM), - as specified in :rfc:`5082`. With this command, only neighbors - that are specified number of hops away will be allowed to - become neighbors. The number of hops range is 1 to 254. This - command is mutually exclusive with :cfgcmd:`ebgp-multihop`. - - -Peer Groups -^^^^^^^^^^^ - -Peer groups are used to help improve scaling by generating the same update -information to all members of a peer group. Note that this means that the -routes generated by a member of a peer group will be sent back to that -originating peer with the originator identifier attribute set to indicated -the originating peer. All peers not associated with a specific peer group -are treated as belonging to a default peer group, and will share updates. - -.. cfgcmd:: set protocols bgp peer-group <name> - - This command defines a new peer group. You can specify to the group the same - parameters that you can specify for specific neighbors. - - .. note:: If you apply a parameter to an individual neighbor IP address, you - override the action defined for a peer group that includes that IP - address. - -.. cfgcmd:: set protocols bgp neighbor <address|interface> peer-group - <name> - - This command bind specific peer to peer group with a given name. - - -Network Advertisement Configuration ------------------------------------ - -.. cfgcmd:: set protocols bgp address-family <ipv4-unicast|ipv6-unicast> - network <prefix> - - This command is used for advertising IPv4 or IPv6 networks. - - .. note:: By default, the BGP prefix is advertised even if it's not present - in the routing table. This behaviour differs from the implementation of - some vendors. - -.. cfgcmd:: set protocols bgp parameters network-import-check - - This configuration modifies the behavior of the network statement. If you - have this configured the underlying network must exist in the routing table. - -.. cfgcmd:: set protocols bgp neighbor <address|interface> address-family - <ipv4-unicast|ipv6-unicast> default-originate [route-map <name>] - - By default, VyOS does not advertise a default route (0.0.0.0/0) even if it is - in routing table. When you want to announce default routes to the peer, use - this command. Using optional argument :cfgcmd:`route-map` you can inject the - default route to given neighbor only if the conditions in the route map are - met. - - -Route Aggregation Configuration -------------------------------- - -.. cfgcmd:: set protocols bgp address-family <ipv4-unicast|ipv6-unicast> - aggregate-address <prefix> - - This command specifies an aggregate address. The router will also - announce longer-prefixes inside of the aggregate address. - -.. cfgcmd:: set protocols bgp address-family <ipv4-unicast|ipv6-unicast> - aggregate-address <prefix> as-set - - This command specifies an aggregate address with a mathematical set of - autonomous systems. This command summarizes the AS_PATH attributes of - all the individual routes. - -.. cfgcmd:: set protocols bgp address-family <ipv4-unicast|ipv6-unicast> - aggregate-address <prefix> summary-only - - This command specifies an aggregate address and provides that - longer-prefixes inside of the aggregate address are suppressed - before sending BGP updates out to peers. - -.. cfgcmd:: set protocols bgp neighbor <address|interface> address-family - <ipv4-unicast|ipv6-unicast> unsuppress-map <name> - - This command applies route-map to selectively unsuppress prefixes - suppressed by summarisation. - - -Redistribution Configuration ----------------------------- - -.. cfgcmd:: set protocols bgp address-family <ipv4-unicast|ipv6-unicast> - redistribute <route source> - - This command redistributes routing information from the given route source - to the BGP process. There are six modes available for route source: - connected, kernel, ospf, rip, static, table. - -.. cfgcmd:: set protocols bgp address-family <ipv4-unicast|ipv6-unicast> - redistribute <route source> metric <number> - - This command specifies metric (MED) for redistributed routes. The - metric range is 0 to 4294967295. There are six modes available for - route source: connected, kernel, ospf, rip, static, table. - -.. cfgcmd:: set protocols bgp address-family <ipv4-unicast|ipv6-unicast> - redistribute <route source> route-map <name> - - This command allows to use route map to filter redistributed routes. - There are six modes available for route source: connected, kernel, - ospf, rip, static, table. - - -General Configuration ---------------------- - -Common parameters -^^^^^^^^^^^^^^^^^ - -.. cfgcmd:: set protocols bgp parameters allow-martian-nexthop - - When a peer receives a martian nexthop as part of the NLRI for a route - permit the nexthop to be used as such, instead of rejecting and resetting - the connection. - -.. cfgcmd:: set protocols bgp parameters router-id <id> - - This command specifies the router-ID. If router ID is not specified it will - use the highest interface IP address. - -.. cfgcmd:: set protocols bgp address-family <ipv4-unicast|ipv6-unicast> - maximum-paths <ebgp|ibgp> <number> - - This command defines the maximum number of parallel routes that - the BGP can support. In order for BGP to use the second path, the - following attributes have to match: Weight, Local Preference, AS - Path (both AS number and AS path length), Origin code, MED, IGP - metric. Also, the next hop address for each path must be different. - -.. cfgcmd:: set protocols bgp parameters no-hard-administrative-reset - - Do not send Hard Reset CEASE Notification for "Administrative Reset" - events. When set and Graceful Restart Notification capability is exchanged - between the peers, Graceful Restart procedures apply, and routes will be retained. - -.. cfgcmd:: set protocols bgp parameters log-neighbor-changes - - This command enable logging neighbor up/down changes and reset reason. - -.. cfgcmd:: set protocols bgp parameters no-client-to-client-reflection - - This command disables route reflection between route reflector clients. - By default, the clients of a route reflector are not required to be - fully meshed and the routes from a client are reflected to other clients. - However, if the clients are fully meshed, route reflection is not required. - In this case, use the :cfgcmd:`no-client-to-client-reflection` command - to disable client-to-client reflection. - -.. cfgcmd:: set protocols bgp parameters no-fast-external-failover - - Disable immediate session reset if peer's connected link goes down. - -.. cfgcmd:: set protocols bgp parameters no-ipv6-auto-ra - - By default, FRR sends router advertisement packets when Extended Next Hop is - on or when a connection is established directly using the device name (Unnumbered BGP). - Setting this option prevents FRR from sending router advertisement packets, but could break Unnumbered BGP. - -.. cfgcmd:: set protocols bgp listen range <prefix> peer-group <name> - - This command is useful if one desires to loosen the requirement for BGP - to have strictly defined neighbors. Specifically what is allowed is for - the local router to listen to a range of IPv4 or IPv6 addresses defined - by a prefix and to accept BGP open messages. When a TCP connection - (and subsequently a BGP open message) from within this range tries to - connect the local router then the local router will respond and connect - with the parameters that are defined within the peer group. One must define - a peer-group for each range that is listed. If no peer-group is defined - then an error will keep you from committing the configuration. - -.. cfgcmd:: set protocols bgp listen limit <number> - - This command goes hand in hand with the listen range command to limit the - amount of BGP neighbors that are allowed to connect to the local router. - The limit range is 1 to 5000. - -.. cfgcmd:: set protocols bgp parameters ebgp-requires-policy - - This command changes the eBGP behavior of FRR. By default FRR enables - :rfc:`8212` functionality which affects how eBGP routes are advertised, - namely no routes are advertised across eBGP sessions without some - sort of egress route-map/policy in place. In VyOS however we have this - RFC functionality disabled by default so that we can preserve backwards - compatibility with older versions of VyOS. With this option one can - enable :rfc:`8212` functionality to operate. - -.. cfgcmd:: set protocols bgp parameters labeled-unicast <explicit-null | - ipv4-explicit-null | ipv6-explicit-null> - - By default, locally advertised prefixes use the implicit-null label to - encode in the outgoing NLRI. - - The following command uses the explicit-null label value for all the - BGP instances. - - -Administrative Distance -^^^^^^^^^^^^^^^^^^^^^^^ - -.. cfgcmd:: set protocols bgp parameters distance global - <external|internal|local> <distance> - - This command change distance value of BGP. The arguments are the distance - values for external routes, internal routes and local routes respectively. - The distance range is 1 to 255. - -.. cfgcmd:: set protocols bgp parameters distance prefix <subnet> - distance <distance> - - This command sets the administrative distance for a particular route. The - distance range is 1 to 255. - - .. note:: Routes with a distance of 255 are effectively disabled and not - installed into the kernel. - - -Timers -^^^^^^ - -.. cfgcmd:: set protocols bgp timers holdtime <seconds> - - This command specifies hold-time in seconds. The timer range is - 4 to 65535. The default value is 180 second. If you set value to 0 - VyOS will not hold routes. - -.. cfgcmd:: set protocols bgp timers keepalive <seconds> - - This command specifies keep-alive time in seconds. The timer - can range from 4 to 65535. The default value is 60 second. - - -Route Dampening -^^^^^^^^^^^^^^^ - -When a route fails, a routing update is sent to withdraw the route from the -network's routing tables. When the route is re-enabled, the change in -availability is also advertised. A route that continually fails and returns -requires a great deal of network traffic to update the network about the -route's status. - -Route dampening wich described in :rfc:`2439` enables you to identify routes -that repeatedly fail and return. If route dampening is enabled, an unstable -route accumulates penalties each time the route fails and returns. If the -accumulated penalties exceed a threshold, the route is no longer advertised. -This is route suppression. Routes that have been suppressed are re-entered -into the routing table only when the amount of their penalty falls below a -threshold. - -A penalty of 1000 is assessed each time the route fails. When the penalties -reach a predefined threshold (suppress-value), the router stops advertising -the route. - -Once a route is assessed a penalty, the penalty is decreased by half each time -a predefined amount of time elapses (half-life-time). When the accumulated -penalties fall below a predefined threshold (reuse-value), the route is -unsuppressed and added back into the BGP routing table. - -No route is suppressed indefinitely. Maximum-suppress-time defines the maximum -time a route can be suppressed before it is re-advertised. - -.. cfgcmd:: set protocols bgp parameters dampening - half-life <minutes> - - This command defines the amount of time in minutes after - which a penalty is reduced by half. The timer range is - 10 to 45 minutes. - -.. cfgcmd:: set protocols bgp parameters dampening - re-use <seconds> - - This command defines the accumulated penalty amount at which the - route is re-advertised. The penalty range is 1 to 20000. - -.. cfgcmd:: set protocols bgp parameters dampening - start-suppress-time <seconds> - - This command defines the accumulated penalty amount at which the - route is suppressed. The penalty range is 1 to 20000. - -.. cfgcmd:: set protocols bgp parameters dampening - max-suppress-time <seconds> - - This command defines the maximum time in minutes that a route is - suppressed. The timer range is 1 to 255 minutes. - - -Route Selection Configuration ------------------------------ - -.. cfgcmd:: set protocols bgp parameters always-compare-med - - This command provides to compare the MED on routes, even when they were - received from different neighbouring ASes. Setting this option makes the - order of preference of routes more defined, and should eliminate MED - induced oscillations. - -.. cfgcmd:: set protocols bgp parameters bestpath as-path confed - - This command specifies that the length of confederation path sets and - sequences should be taken into account during the BGP best path - decision process. - -.. cfgcmd:: set protocols bgp parameters bestpath as-path multipath-relax - - This command specifies that BGP decision process should consider paths - of equal AS_PATH length candidates for multipath computation. Without - the knob, the entire AS_PATH must match for multipath computation. - -.. cfgcmd:: set protocols bgp parameters bestpath as-path ignore - - Ignore AS_PATH length when selecting a route - -.. cfgcmd:: set protocols bgp parameters bestpath compare-routerid - - Ensure that when comparing routes where both are equal on most metrics, - including local-pref, AS_PATH length, IGP cost, MED, that the tie is - broken based on router-ID. - - If this option is enabled, then the already-selected check, where - already selected eBGP routes are preferred, is skipped. - - If a route has an ORIGINATOR_ID attribute because it has been reflected, - that ORIGINATOR_ID will be used. Otherwise, the router-ID of the peer - the route was received from will be used. - - The advantage of this is that the route-selection (at this point) will - be more deterministic. The disadvantage is that a few or even one lowest-ID - router may attract all traffic to otherwise-equal paths because of this - check. It may increase the possibility of MED or IGP oscillation, unless - other measures were taken to avoid these. The exact behaviour will be - sensitive to the iBGP and reflection topology. - -.. cfgcmd:: set protocols bgp parameters bestpath med confed - - This command specifies that BGP considers the MED when comparing routes - originated from different sub-ASs within the confederation to which this - BGP speaker belongs. The default state, where the MED attribute is not - considered. - -.. cfgcmd:: set protocols bgp parameters bestpath med missing-as-worst - - This command specifies that a route with a MED is always considered to be - better than a route without a MED by causing the missing MED attribute to - have a value of infinity. The default state, where the missing MED - attribute is considered to have a value of zero. - -.. cfgcmd:: set protocols bgp parameters default local-pref - <local-pref value> - - This command specifies the default local preference value. The local - preference range is 0 to 4294967295. - -.. cfgcmd:: set protocols bgp parameters deterministic-med - - This command provides to compare different MED values that advertised by - neighbours in the same AS for routes selection. When this command is - enabled, routes from the same autonomous system are grouped together, and - the best entries of each group are compared. - -.. cfgcmd:: set protocols bgp address-family ipv4-unicast network - <prefix> backdoor - - This command allows the router to prefer route to specified prefix learned - via IGP through backdoor link instead of a route to the same prefix learned - via EBGP. - - -Route Filtering Configuration ------------------------------ - -In order to control and modify routing information that is exchanged between -peers you can use route-map, filter-list, prefix-list, distribute-list. - -For inbound updates the order of preference is: - - - route-map - - filter-list - - prefix-list, distribute-list - -For outbound updates the order of preference is: - - - prefix-list, distribute-list - - filter-list - - route-map - - .. note:: The attributes :cfgcmd:`prefix-list` and :cfgcmd:`distribute-list` - are mutually exclusive, and only one command (distribute-list or - prefix-list) can be applied to each inbound or outbound direction for a - particular neighbor. - -.. cfgcmd:: set protocols bgp neighbor <address|interface> address-family - <ipv4-unicast|ipv6-unicast> distribute-list <export|import> <number> - - This command applies the access list filters named in <number> to the - specified BGP neighbor to restrict the routing information that BGP learns - and/or advertises. The arguments :cfgcmd:`export` and :cfgcmd:`import` - specify the direction in which the access list are applied. - -.. cfgcmd:: set protocols bgp neighbor <address|interface> address-family - <ipv4-unicast|ipv6-unicast> prefix-list <export|import> <name> - - This command applies the prfefix list filters named in <name> to the - specified BGP neighbor to restrict the routing information that BGP learns - and/or advertises. The arguments :cfgcmd:`export` and :cfgcmd:`import` - specify the direction in which the prefix list are applied. - -.. cfgcmd:: set protocols bgp neighbor <address|interface> address-family - <ipv4-unicast|ipv6-unicast> route-map <export|import> <name> - - This command applies the route map named in <name> to the specified BGP - neighbor to control and modify routing information that is exchanged - between peers. The arguments :cfgcmd:`export` and :cfgcmd:`import` - specify the direction in which the route map are applied. - -.. cfgcmd:: set protocols bgp neighbor <address|interface> address-family - <ipv4-unicast|ipv6-unicast> filter-list <export|import> <name> - - This command applies the AS path access list filters named in <name> to the - specified BGP neighbor to restrict the routing information that BGP learns - and/or advertises. The arguments :cfgcmd:`export` and :cfgcmd:`import` - specify the direction in which the AS path access list are applied. - -.. cfgcmd:: set protocols bgp neighbor <address|interface> address-family - <ipv4-unicast|ipv6-unicast> capability orf <receive|send> - - This command enables the ORF capability (described in :rfc:`5291`) on the - local router, and enables ORF capability advertisement to the specified BGP - peer. The :cfgcmd:`receive` keyword configures a router to advertise ORF - receive capabilities. The :cfgcmd:`send` keyword configures a router to - advertise ORF send capabilities. To advertise a filter from a sender, you - must create an IP prefix list for the specified BGP peer applied in inbound - derection. - -.. cfgcmd:: set protocols bgp neighbor <address|interface> solo - - This command prevents from sending back prefixes learned from the neighbor. - -BGP Scaling Configuration -------------------------- - -BGP routers connected inside the same AS through BGP belong to an internal BGP -session, or IBGP. In order to prevent routing table loops, IBGP speaker does -not advertise IBGP-learned routes to other IBGP speaker (Split Horizon -mechanism). As such, IBGP requires a full mesh of all peers. For large -networks, this quickly becomes unscalable. - -There are two ways that help us to mitigate the BGPs full-mesh requirement in -a network: - - - Using BGP route-reflectors - - Using BGP confederation - - -Route Reflector Configuration -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -Introducing route reflectors removes the need for the full-mesh. When you -configure a route reflector you have to tell the router whether the other IBGP -router is a client or non-client. A client is an IBGP router that the route -reflector will “reflect” routes to, the non-client is just a regular IBGP -neighbor. Route reflectors mechanism is described in :rfc:`4456` and updated -by :rfc:`7606`. - -.. cfgcmd:: set protocols bgp neighbor <address> address-family - <ipv4-unicast|ipv6-unicast> route-reflector-client - - This command specifies the given neighbor as route reflector client. - -.. cfgcmd:: set protocols bgp parameters cluster-id <id> - - This command specifies cluster ID which identifies a collection of route - reflectors and their clients, and is used by route reflectors to avoid - looping. By default cluster ID is set to the BGP router id value, but can be - set to an arbitrary 32-bit value. - - -Confederation Configuration -^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -A BGP confederation divides our AS into sub-ASes to reduce the number of -required IBGP peerings. Within a sub-AS we still require full-mesh IBGP but -between these sub-ASes we use something that looks like EBGP but behaves like -IBGP (called confederation BGP). Confederation mechanism is described in -:rfc:`5065` - -.. cfgcmd:: set protocols bgp parameters confederation identifier - <asn> - - This command specifies a BGP confederation identifier. <asn> is the number - of the autonomous system that internally includes multiple sub-autonomous - systems (a confederation). - -.. cfgcmd:: set protocols bgp parameters confederation peers <nsubasn> - - This command sets other confederations <nsubasn> as members of autonomous - system specified by :cfgcmd:`confederation identifier <asn>`. - - -************************* -Operational Mode Commands -************************* - -Show -==== - -.. opcmd:: show bgp <ipv4|ipv6> - - This command displays all entries in BGP routing table. - -.. code-block:: none - - BGP table version is 10, local router ID is 10.0.35.3, vrf id 0 - Default local pref 100, local AS 65000 - Status codes: s suppressed, d damped, h history, * valid, > best, = multipath, - i internal, r RIB-failure, S Stale, R Removed - Nexthop codes: @NNN nexthop's vrf id, < announce-nh-self - Origin codes: i - IGP, e - EGP, ? - incomplete - RPKI validation codes: V valid, I invalid, N Not found - - Network Next Hop Metric LocPrf Weight Path - *> 198.51.100.0/24 10.0.34.4 0 0 65004 i - *> 203.0.113.0/24 10.0.35.5 0 0 65005 i - - Displayed 2 routes and 2 total paths - -.. opcmd:: show bgp <ipv4|ipv6> <address|prefix> - - This command displays information about the particular entry in the BGP - routing table. - -.. code-block:: none - - BGP routing table entry for 198.51.100.0/24 - Paths: (1 available, best #1, table default) - Advertised to non peer-group peers: - 10.0.13.1 10.0.23.2 10.0.34.4 10.0.35.5 - 65004 - 10.0.34.4 from 10.0.34.4 (10.0.34.4) - Origin IGP, metric 0, valid, external, best (First path received) - Last update: Wed Jan 6 12:18:53 2021 - -.. opcmd:: show bgp cidr-only - - This command displays routes with classless interdomain routing (CIDR). - -.. opcmd:: show bgp <ipv4|ipv6> community <value> - - This command displays routes that belong to specified BGP communities. - Valid value is a community number in the range from 1 to 4294967200, - or AA:NN (autonomous system-community number/2-byte number), no-export, - local-as, or no-advertise. - -.. opcmd:: show bgp <ipv4|ipv6> community-list <name> - - This command displays routes that are permitted by the BGP - community list. - -.. opcmd:: show bgp <ipv4|ipv6> dampening dampened-paths - - This command displays BGP dampened routes. - -.. opcmd:: show bgp <ipv4|ipv6> dampening flap-statistics - - This command displays information about flapping BGP routes. - -.. opcmd:: show bgp <ipv4|ipv6> filter-list <name> - - This command displays BGP routes allowed by the specified AS Path - access list. - -.. opcmd:: show bgp <ipv4|ipv6> neighbors <address> advertised-routes - - This command displays BGP routes advertised to a neighbor. - -.. opcmd:: show bgp <ipv4|ipv6> neighbors <address> received-routes - - This command displays BGP routes originating from the specified BGP - neighbor before inbound policy is applied. To use this command inbound - soft reconfiguration must be enabled. - -.. opcmd:: show bgp <ipv4|ipv6> neighbors <address> routes - - This command displays BGP received-routes that are accepted after filtering. - -.. opcmd:: show bgp <ipv4|ipv6> neighbors <address> dampened-routes - - This command displays dampened routes received from BGP neighbor. - -.. opcmd:: show bgp <ipv4|ipv6> regexp <text> - - This command displays information about BGP routes whose AS path - matches the specified regular expression. - -.. opcmd:: show bgp <ipv4|ipv6> summary - - This command displays the status of all BGP connections. - -.. code-block:: none - - IPv4 Unicast Summary: - BGP router identifier 10.0.35.3, local AS number 65000 vrf-id 0 - BGP table version 11 - RIB entries 5, using 920 bytes of memory - Peers 4, using 82 KiB of memory - - Neighbor V AS MsgRcvd MsgSent TblVer InQ OutQ Up/Down State/PfxRcd - 10.0.13.1 4 65000 148 159 0 0 0 02:16:01 0 - 10.0.23.2 4 65000 136 143 0 0 0 02:13:21 0 - 10.0.34.4 4 65004 161 163 0 0 0 02:16:01 1 - 10.0.35.5 4 65005 162 166 0 0 0 02:16:01 1 - - Total number of neighbors 4 - -Reset -===== - -.. opcmd:: reset bgp <ipv4|ipv6> <address> [soft [in|out]] - - This command resets BGP connections to the specified neighbor IP address. - With argument :cfgcmd:`soft` this command initiates a soft reset. If - you do not specify the :cfgcmd:`in` or :cfgcmd:`out` options, both - inbound and outbound soft reconfiguration are triggered. - -.. opcmd:: reset bgp all - - This command resets all BGP connections of given router. - -.. opcmd:: reset bgp <ipv4|ipv6> external - - This command resets all external BGP peers of given router. - -.. opcmd:: reset bgp <ipv4|ipv6> peer-group <name> [soft [in|out]] - - This command resets BGP connections to the specified peer group. - With argument :cfgcmd:`soft` this command initiates a soft reset. If - you do not specify the :cfgcmd:`in` or :cfgcmd:`out` options, both - inbound and outbound soft reconfiguration are triggered. - - -******** -Examples -******** - -IPv4 peering -============ - -A simple eBGP configuration: - -**Node 1:** - -.. code-block:: none - - set protocols bgp system-as 65534 - set protocols bgp neighbor 192.168.0.2 ebgp-multihop '2' - set protocols bgp neighbor 192.168.0.2 remote-as '65535' - set protocols bgp neighbor 192.168.0.2 update-source '192.168.0.1' - set protocols bgp neighbor 192.168.0.2 address-family ipv4-unicast - set protocols bgp address-family ipv4-unicast network '172.16.0.0/16' - set protocols bgp parameters router-id '192.168.0.1' - -**Node 2:** - -.. code-block:: none - - set protocols bgp system-as 65535 - set protocols bgp neighbor 192.168.0.1 ebgp-multihop '2' - set protocols bgp neighbor 192.168.0.1 remote-as '65534' - set protocols bgp neighbor 192.168.0.1 update-source '192.168.0.2' - set protocols bgp neighbor 192.168.0.1 address-family ipv4-unicast - set protocols bgp address-family ipv4-unicast network '172.17.0.0/16' - set protocols bgp parameters router-id '192.168.0.2' - - -Don't forget, the CIDR declared in the network statement MUST **exist in your -routing table (dynamic or static), the best way to make sure that is true is -creating a static route:** - -**Node 1:** - -.. code-block:: none - - set protocols static route 172.16.0.0/16 blackhole distance '254' - -**Node 2:** - -.. code-block:: none - - set protocols static route 172.17.0.0/16 blackhole distance '254' - - -IPv6 peering -============ - -A simple BGP configuration via IPv6. - -**Node 1:** - -.. code-block:: none - - set protocols bgp system-as 65534 - set protocols bgp neighbor 2001:db8::2 ebgp-multihop '2' - set protocols bgp neighbor 2001:db8::2 remote-as '65535' - set protocols bgp neighbor 2001:db8::2 update-source '2001:db8::1' - set protocols bgp neighbor 2001:db8::2 address-family ipv6-unicast - set protocols bgp address-family ipv6-unicast network '2001:db8:1::/48' - set protocols bgp parameters router-id '10.1.1.1' - -**Node 2:** - -.. code-block:: none - - set protocols bgp system-as 65535 - set protocols bgp neighbor 2001:db8::1 ebgp-multihop '2' - set protocols bgp neighbor 2001:db8::1 remote-as '65534' - set protocols bgp neighbor 2001:db8::1 update-source '2001:db8::2' - set protocols bgp neighbor 2001:db8::1 address-family ipv6-unicast - set protocols bgp address-family ipv6-unicast network '2001:db8:2::/48' - set protocols bgp parameters router-id '10.1.1.2' - -Don't forget, the CIDR declared in the network statement **MUST exist in your -routing table (dynamic or static), the best way to make sure that is true is -creating a static route:** - -**Node 1:** - -.. code-block:: none - - set protocols static route6 2001:db8:1::/48 blackhole distance '254' - -**Node 2:** - -.. code-block:: none - - set protocols static route6 2001:db8:2::/48 blackhole distance '254' - -Route Filtering -=============== - -Route filter can be applied using a route-map: - -**Node1:** - -.. code-block:: none - - set policy prefix-list AS65535-IN rule 10 action 'permit' - set policy prefix-list AS65535-IN rule 10 prefix '172.16.0.0/16' - set policy prefix-list AS65535-OUT rule 10 action 'deny' - set policy prefix-list AS65535-OUT rule 10 prefix '172.16.0.0/16' - set policy prefix-list6 AS65535-IN rule 10 action 'permit' - set policy prefix-list6 AS65535-IN rule 10 prefix '2001:db8:2::/48' - set policy prefix-list6 AS65535-OUT rule 10 action 'deny' - set policy prefix-list6 AS65535-OUT rule 10 prefix '2001:db8:2::/48' - - set policy route-map AS65535-IN rule 10 action 'permit' - set policy route-map AS65535-IN rule 10 match ip address prefix-list 'AS65535-IN' - set policy route-map AS65535-IN rule 10 match ipv6 address prefix-list 'AS65535-IN' - set policy route-map AS65535-IN rule 20 action 'deny' - set policy route-map AS65535-OUT rule 10 action 'deny' - set policy route-map AS65535-OUT rule 10 match ip address prefix-list 'AS65535-OUT' - set policy route-map AS65535-OUT rule 10 match ipv6 address prefix-list 'AS65535-OUT' - set policy route-map AS65535-OUT rule 20 action 'permit' - - set protocols bgp system-as 65534 - set protocols bgp neighbor 2001:db8::2 address-family ipv4-unicast route-map export 'AS65535-OUT' - set protocols bgp neighbor 2001:db8::2 address-family ipv4-unicast route-map import 'AS65535-IN' - set protocols bgp neighbor 2001:db8::2 address-family ipv6-unicast route-map export 'AS65535-OUT' - set protocols bgp neighbor 2001:db8::2 address-family ipv6-unicast route-map import 'AS65535-IN' - -**Node2:** - -.. code-block:: none - - set policy prefix-list AS65534-IN rule 10 action 'permit' - set policy prefix-list AS65534-IN rule 10 prefix '172.17.0.0/16' - set policy prefix-list AS65534-OUT rule 10 action 'deny' - set policy prefix-list AS65534-OUT rule 10 prefix '172.17.0.0/16' - set policy prefix-list6 AS65534-IN rule 10 action 'permit' - set policy prefix-list6 AS65534-IN rule 10 prefix '2001:db8:1::/48' - set policy prefix-list6 AS65534-OUT rule 10 action 'deny' - set policy prefix-list6 AS65534-OUT rule 10 prefix '2001:db8:1::/48' - - set policy route-map AS65534-IN rule 10 action 'permit' - set policy route-map AS65534-IN rule 10 match ip address prefix-list 'AS65534-IN' - set policy route-map AS65534-IN rule 10 match ipv6 address prefix-list 'AS65534-IN' - set policy route-map AS65534-IN rule 20 action 'deny' - set policy route-map AS65534-OUT rule 10 action 'deny' - set policy route-map AS65534-OUT rule 10 match ip address prefix-list 'AS65534-OUT' - set policy route-map AS65534-OUT rule 10 match ipv6 address prefix-list 'AS65534-OUT' - set policy route-map AS65534-OUT rule 20 action 'permit' - - set protocols bgp system-as 65535 - set protocols bgp neighbor 2001:db8::1 address-family ipv4-unicast route-map export 'AS65534-OUT' - set protocols bgp neighbor 2001:db8::1 address-family ipv4-unicast route-map import 'AS65534-IN' - set protocols bgp neighbor 2001:db8::1 address-family ipv6-unicast route-map export 'AS65534-OUT' - set protocols bgp neighbor 2001:db8::1 address-family ipv6-unicast route-map import 'AS65534-IN' - -We could expand on this and also deny link local and multicast in the rule 20 -action deny. diff --git a/docs/configuration/protocols/rst-failover.rst b/docs/configuration/protocols/rst-failover.rst deleted file mode 100644 index c479649e..00000000 --- a/docs/configuration/protocols/rst-failover.rst +++ /dev/null @@ -1,224 +0,0 @@ -:description: Failover routes are static routes that are installed in the routing - table only while a configured health-check target responds. VyOS uses them - to switch traffic to a backup path when the primary next hop becomes - unreachable, and to restore the primary path automatically once it recovers. -:keywords: failover, failover route, static route, health check, icmp probe, - next hop, route metric - -######## -Failover -######## - -Failover routes are manually configured network paths used only while their -health-check targets are reachable. If the target stops responding, VyOS -removes the route from the routing table and reinstalls it once the target -recovers. - -************* -Configuration -************* - -Use the following commands to configure failover routes for a specific remote -``<subnet>`` reachable via next-hop ``<address>``. - -.. cfgcmd:: set protocols failover route <subnet> next-hop <address> check target <target-address> - - **Configure the health check target IP address.** - - This is typically a highly available host, either within the destination - subnet or on the public internet. - - Example: - - .. code-block:: none - - set protocols failover route 203.0.113.1/32 next-hop 10.217.37.254 check target 8.8.8.8 - -.. cfgcmd:: set protocols failover route <subnet> next-hop <address> check timeout <timeout> - - **Configure the timeout interval, in seconds, between target health checks.** - - The valid range is 1 to 300 seconds. The default is 10 seconds. - - Example: - - .. code-block:: none - - set protocols failover route 203.0.113.1/32 next-hop 10.217.37.254 check timeout 2 - -.. cfgcmd:: set protocols failover route <subnet> next-hop <address> check type <protocol> - - **Configure the protocol to use for health checks.** - - The following protocols are available: - - * ``icmp``: VyOS sends two ICMP echo request packets with a 1-second - response timeout. The health check is successful if at least one response - is received. - * ``arp``: VyOS sends two ARP requests with a 1-second response timeout. - The health check is successful if at least one response is received. - * ``tcp``: VyOS verifies whether the destination TCP port is open. The - health check is successful if a TCP connection is successfully - established with the target port. - - The default protocol is ``icmp``. - - .. note:: - - When the check type is set to ``tcp``, you must also define the target - TCP port. - - Example: - - .. code-block:: none - - set protocols failover route 203.0.113.1/32 next-hop 10.217.37.254 check type tcp - -.. cfgcmd:: set protocols failover route <subnet> next-hop <address> check port <port> - - **Configure the destination TCP port on the health check target.** - - This parameter applies only when the check type is configured as ``tcp``. - - The valid port range is 1 to 65535. - - Example: - - .. code-block:: none - - set protocols failover route 203.0.113.1/32 next-hop 10.217.37.254 check port 443 - -.. cfgcmd:: set protocols failover route <subnet> next-hop <address> check policy <policy> - - **Configure the health check success policy for multiple targets.** - - The following policies are available: - - * ``any-available``: The health check succeeds if at least one of the - configured targets responds successfully. - * ``all-available``: The health check succeeds only if every configured - target responds successfully. - - The default policy is ``any-available``. - - Example: - - .. code-block:: none - - set protocols failover route 203.0.113.1/32 next-hop 10.217.37.254 check policy all-available - -.. cfgcmd:: set protocols failover route <subnet> next-hop <address> interface <interface> - - **Configure the local interface used to reach the next-hop address.** - - This parameter is mandatory. - - Example: - - .. code-block:: none - - set protocols failover route 203.0.113.1/32 next-hop 10.217.37.254 interface eth0 - -.. cfgcmd:: set protocols failover route <subnet> next-hop <address> metric <1-255> - - **Configure the metric (cost) for the failover route.** - - The metric defines the route priority. A lower metric value indicates a - more preferred route. - - The default value is 1. - - Example: - - .. code-block:: none - - set protocols failover route 203.0.113.1/32 next-hop 10.217.37.254 metric 50 - -.. cfgcmd:: set protocols failover route <subnet> next-hop <address> onlink - - Configure the next-hop to be reachable via the assigned interface, even - when ``<address>`` is outside any subnet configured on that interface. - - Example: - - .. code-block:: none - - set protocols failover route 203.0.113.1/32 next-hop 10.217.37.254 onlink - -******** -Examples -******** - -Failover route with a single next-hop and ICMP health check -=========================================================== - -The following example configures a failover route to ``203.0.113.1/32`` -through next-hop ``192.0.2.1`` on ``eth0``. The next-hop is monitored with -ICMP probes to ``192.0.2.1`` every 5 seconds, and the route is installed with -a metric of 10. - -.. code-block:: none - - set protocols failover route 203.0.113.1/32 next-hop 192.0.2.1 check target '192.0.2.1' - set protocols failover route 203.0.113.1/32 next-hop 192.0.2.1 check timeout '5' - set protocols failover route 203.0.113.1/32 next-hop 192.0.2.1 check type 'icmp' - set protocols failover route 203.0.113.1/32 next-hop 192.0.2.1 interface 'eth0' - set protocols failover route 203.0.113.1/32 next-hop 192.0.2.1 metric '10' - -Verify the route: - -.. code-block:: none - - vyos@vyos:~$ show ip route 203.0.113.1 - Routing entry for 203.0.113.1/32 - Known via "kernel", distance 0, metric 10, best - Last update 00:00:39 ago - Flags: Selected - Status: Installed - * 192.0.2.1, via eth0, weight 1 - -Two failover routes with different metrics -========================================== - -The following example configures two failover routes to ``203.0.113.1/32``, -each through a different next-hop. The primary next-hop ``192.0.2.1`` is -reached on ``eth0`` with metric 10, and the backup next-hop ``198.51.100.1`` -is reached on ``eth2`` with metric 20. Both next-hops are monitored with ICMP -probes every 5 seconds. - -While both health checks succeed, the lower-metric route through ``eth0`` is -preferred. If the primary target stops responding, its route is removed from -the routing table, and traffic falls over to ``198.51.100.1`` via ``eth2``. - -.. code-block:: none - - set protocols failover route 203.0.113.1/32 next-hop 192.0.2.1 check target '192.0.2.1' - set protocols failover route 203.0.113.1/32 next-hop 192.0.2.1 check timeout '5' - set protocols failover route 203.0.113.1/32 next-hop 192.0.2.1 check type 'icmp' - set protocols failover route 203.0.113.1/32 next-hop 192.0.2.1 interface 'eth0' - set protocols failover route 203.0.113.1/32 next-hop 192.0.2.1 metric '10' - - set protocols failover route 203.0.113.1/32 next-hop 198.51.100.1 check target '198.51.100.99' - set protocols failover route 203.0.113.1/32 next-hop 198.51.100.1 check timeout '5' - set protocols failover route 203.0.113.1/32 next-hop 198.51.100.1 check type 'icmp' - set protocols failover route 203.0.113.1/32 next-hop 198.51.100.1 interface 'eth2' - set protocols failover route 203.0.113.1/32 next-hop 198.51.100.1 metric '20' - -Verify routes: - -.. code-block:: none - - vyos@vyos:~$ show ip route 203.0.113.1 - Routing entry for 203.0.113.1/32 - Known via "kernel", distance 0, metric 10, best - Last update 00:08:06 ago - Flags: Selected - Status: Installed - * 192.0.2.1, via eth0, weight 1 - - Routing entry for 203.0.113.1/32 - Known via "kernel", distance 0, metric 20 - Last update 00:08:14 ago - Flags: None - Status: Installed - * 198.51.100.1, via eth2, weight 1
\ No newline at end of file diff --git a/docs/configuration/protocols/rst-igmp-proxy.rst b/docs/configuration/protocols/rst-igmp-proxy.rst deleted file mode 100644 index f62a289e..00000000 --- a/docs/configuration/protocols/rst-igmp-proxy.rst +++ /dev/null @@ -1,77 +0,0 @@ -:lastproofread: 2023-11-13 - -.. _igmp_proxy: - -########## -IGMP Proxy -########## - -:abbr:`IGMP (Internet Group Management Protocol)` proxy sends IGMP host messages -on behalf of a connected client. The configuration must define one, and only one -upstream interface, and one or more downstream interfaces. - -Configuration -============= - -.. cfgcmd:: set protocols igmp-proxy interface <interface> role - <upstream | downstream> - - * **upstream:** The upstream network interface is the outgoing interface - which is responsible for communicating to available multicast data sources. - There can only be one upstream interface. - - * **downstream:** Downstream network interfaces are the distribution - interfaces to the destination networks, where multicast clients can join - groups and receive multicast data. One or more downstream interfaces must - be configured. - -.. cfgcmd:: set protocols igmp-proxy interface <interface> alt-subnet <network> - - Defines alternate sources for multicasting and IGMP data. The network address - must be on the following format 'a.b.c.d/n'. By default, the router will - accept data from sources on the same network as configured on an interface. - If the multicast source lies on a remote network, one must define from where - traffic should be accepted. - - This is especially useful for the upstream interface, since the source for - multicast traffic is often from a remote location. - - This option can be supplied multiple times. - -.. cfgcmd:: set protocols igmp-proxy disable-quickleave - - Disables quickleave mode. In this mode the daemon will not send a Leave IGMP - message upstream as soon as it receives a Leave message for any downstream - interface. The daemon will not ask for Membership reports on the downstream - interfaces, and if a report is received the group is not joined again the - upstream. - - If it's vital that the daemon should act exactly like a real multicast client - on the upstream interface, this function should be enabled. - - Enabling this function increases the risk of bandwidth saturation. - -.. cfgcmd:: set protocols igmp-proxy disable - - Disable this service. - -.. _igmp:proxy_example: - -Example -------- - -Interface `eth1` LAN is behind NAT. In order to subscribe `10.0.0.0/23` subnet -multicast which is in `eth0` WAN we need to configure igmp-proxy. - -.. code-block:: none - - set protocols igmp-proxy interface eth0 role upstream - set protocols igmp-proxy interface eth0 alt-subnet 10.0.0.0/23 - set protocols igmp-proxy interface eth1 role downstream - -Operation -========= - -.. opcmd:: restart igmp-proxy - - Restart the IGMP proxy process. diff --git a/docs/configuration/protocols/rst-index.rst b/docs/configuration/protocols/rst-index.rst deleted file mode 100644 index d40a4b12..00000000 --- a/docs/configuration/protocols/rst-index.rst +++ /dev/null @@ -1,26 +0,0 @@ -######### -Protocols -######### - -.. toctree:: - :maxdepth: 1 - :includehidden: - - arp - babel - bfd - bgp - failover - igmp-proxy - isis - mpls - multicast - segment-routing - traffic-engineering - openfabric - ospf - pim - pim6 - rip - rpki - static diff --git a/docs/configuration/protocols/rst-isis.rst b/docs/configuration/protocols/rst-isis.rst deleted file mode 100644 index 75634800..00000000 --- a/docs/configuration/protocols/rst-isis.rst +++ /dev/null @@ -1,747 +0,0 @@ -.. include:: /_include/need_improvement.txt - -.. _routing-isis: - -##### -IS-IS -##### - -:abbr:`IS-IS (Intermediate System to Intermediate System)` is a link-state -interior gateway protocol (IGP) which is described in ISO10589, -:rfc:`1195`, :rfc:`5308`. IS-IS runs the Dijkstra shortest-path first (SPF) -algorithm to create a database of the network’s topology, and -from that database to determine the best (that is, lowest cost) path to a -destination. The intermediate systems (the name for routers) exchange topology -information with their directly connected neighbors. IS-IS runs directly on -the data link layer (Layer 2). IS-IS addresses are called -:abbr:`NETs (Network Entity Titles)` and can be 8 to 20 bytes long, but are -generally 10 bytes long. The tree database that is created with IS-IS is -similar to the one that is created with OSPF in that the paths chosen should -be similar. Comparisons to OSPF are inevitable and often are reasonable ones -to make in regards to the way a network will respond with either IGP. - -******* -General -******* - -Configuration -============= - -Mandatory Settings ------------------- - -For IS-IS top operate correctly, one must do the equivalent of a Router ID in -CLNS. This Router ID is called the :abbr:`NET (Network Entity Title)`. This -must be unique for each and every router that is operating in IS-IS. It also -must not be duplicated otherwise the same issues that occur within OSPF will -occur within IS-IS when it comes to said duplication. - - -.. cfgcmd:: set protocols isis net <network-entity-title> - - This command sets network entity title (NET) provided in ISO format. - - Here is an example :abbr:`NET (Network Entity Title)` value: - - .. code-block:: none - - 49.0001.1921.6800.1002.00 - - The CLNS address consists of the following parts: - - * :abbr:`AFI (Address family authority identifier)` - ``49`` The AFI value - 49 is what IS-IS uses for private addressing. - - * Area identifier: ``0001`` IS-IS area number (numerical area ``1``) - - * System identifier: ``1921.6800.1002`` - for system identifiers we recommend - to use IP address or MAC address of the router itself. The way to construct - this is to keep all of the zeroes of the router IP address, and then change - the periods from being every three numbers to every four numbers. The - address that is listed here is ``192.168.1.2``, which if expanded will turn - into ``192.168.001.002``. Then all one has to do is move the dots to have - four numbers instead of three. This gives us ``1921.6800.1002``. - - * :abbr:`NET (Network Entity Title)` selector: ``00`` Must always be 00. This - setting indicates "this system" or "local system." - -.. cfgcmd:: set protocols isis interface <interface> - - This command enables IS-IS on this interface, and allows for - adjacency to occur. Note that the name of IS-IS instance must be - the same as the one used to configure the IS-IS process. - -IS-IS Global Configuration --------------------------- - -.. cfgcmd:: set protocols isis dynamic-hostname - - This command enables support for dynamic hostname TLV. Dynamic hostname - mapping determined as described in :rfc:`2763`, Dynamic Hostname - Exchange Mechanism for IS-IS. - -.. cfgcmd:: set protocols isis level <level-1|level-1-2|level-2> - - This command defines the IS-IS router behavior: - - * **level-1** - Act as a station (Level 1) router only. - * **level-1-2** - Act as a station (Level 1) router and area (Level 2) router. - * **level-2-only** - Act as an area (Level 2) router only. - -.. cfgcmd:: set protocols isis lsp-mtu <size> - - This command configures the maximum size of generated - :abbr:`LSPs (Link State PDUs)`, in bytes. The size range is 128 to 4352. - -.. cfgcmd:: set protocols isis metric-style <narrow|transition|wide> - - This command sets old-style (ISO 10589) or new style packet formats: - - * **narrow** - Use old style of TLVs with narrow metric. - * **transition** - Send and accept both styles of TLVs during transition. - * **wide** - Use new style of TLVs to carry wider metric. - -.. cfgcmd:: set protocols isis purge-originator - - This command enables :rfc:`6232` purge originator identification. Enable - purge originator identification (POI) by adding the type, length and value - (TLV) with the Intermediate System (IS) identification to the LSPs that do - not contain POI information. If an IS generates a purge, VyOS adds this TLV - with the system ID of the IS to the purge. - -.. cfgcmd:: set protocols isis set-attached-bit - - This command sets ATT bit to 1 in Level1 LSPs. It is described in :rfc:`3787`. - -.. cfgcmd:: set protocols isis set-overload-bit - - This command sets overload bit to avoid any transit traffic through this - router. It is described in :rfc:`3787`. - -.. cfgcmd:: set protocols isis default-information originate <ipv4|ipv6> - level-1 - - This command will generate a default-route in L1 database. - -.. cfgcmd:: set protocols isis default-information originate <ipv4|ipv6> - level-2 - - This command will generate a default-route in L2 database. - - -.. cfgcmd:: set protocols isis ldp-sync - - This command will enable IGP-LDP synchronization globally for ISIS. This - requires for LDP to be functional. This is described in :rfc:`5443`. By - default all interfaces operational in IS-IS are enabled for synchronization. - Loopbacks are exempt. - -.. cfgcmd:: set protocols isis ldp-sync holddown <seconds> - - This command will change the hold down value globally for IGP-LDP - synchronization during convergence/interface flap events. - - -Interface Configuration ------------------------ - -.. cfgcmd:: set protocols isis interface <interface> circuit-type - <level-1|level-1-2|level-2-only> - - This command specifies circuit type for interface: - - * **level-1** - Level-1 only adjacencies are formed. - * **level-1-2** - Level-1-2 adjacencies are formed - * **level-2-only** - Level-2 only adjacencies are formed - -.. cfgcmd:: set protocols isis interface <interface> hello-interval - <seconds> - - This command sets hello interval in seconds on a given interface. - The range is 1 to 600. - -.. cfgcmd:: set protocols isis interface <interface> hello-multiplier - <seconds> - - This command sets multiplier for hello holding time on a given - interface. The range is 2 to 100. - -.. cfgcmd:: set protocols isis interface <interface> hello-padding - - This command configures padding on hello packets to accommodate asymmetrical - maximum transfer units (MTUs) from different hosts as described in - :rfc:`3719`. This helps to prevent a premature adjacency Up state when one - routing devices MTU does not meet the requirements to establish the adjacency. - -.. cfgcmd:: set protocols isis interface <interface> metric <metric> - - This command set default metric for circuit. - - The metric range is 1 to 16777215 (Max value depend if metric support narrow - or wide value). - -.. cfgcmd:: set protocols isis interface <interface> network - point-to-point - - This command specifies network type to Point-to-Point. The default - network type is broadcast. - -.. cfgcmd:: set protocols isis interface <interface> passive - - This command configures the passive mode for this interface. - -.. cfgcmd:: set protocols isis interface <interface> password - plaintext-password <text> - - This command configures the authentication password for the interface. - -.. cfgcmd:: set protocols isis interface <interface> priority <number> - - This command sets priority for the interface for - :abbr:`DIS (Designated Intermediate System)` election. The priority - range is 0 to 127. - -.. cfgcmd:: set protocols isis interface <interface> psnp-interval - <number> - - This command sets PSNP interval in seconds. The interval range is 0 - to 127. - -.. cfgcmd:: set protocols isis interface <interface> - no-three-way-handshake - - This command disables Three-Way Handshake for P2P adjacencies which - described in :rfc:`5303`. Three-Way Handshake is enabled by default. - -.. cfgcmd:: set protocols isis interface <interface> ldp-sync disable - - This command disables IGP-LDP sync for this specific interface. - -.. cfgcmd:: set protocols isis interface <interface> ldp-sync holddown - <seconds> - - This command will change the hold down value for IGP-LDP synchronization - during convergence/interface flap events, but for this interface only. - -.. cfgcmd:: set protocols isis interface <interface> fast-reroute lfa [level-1 | level-2] enable - - This command enables per-prefix local LFA fast reroute link protection. - -.. cfgcmd:: set protocols isis interface <interface> fast-reroute lfa [level-1 | level-2] exclude - - This command excludes an interface from the local LFA backup nexthop computation. - -.. cfgcmd:: set protocols isis interface <interface> fast-reroute remote-lfa [level-1 | level-2] tunnel mpls-ldp - - This command enables per-prefix Remote LFA fast reroute link protection. - Note that other routers in the network need to be configured to accept LDP - targeted hello messages in order for RLFA to work. - -.. cfgcmd:: set protocols isis interface <interface> fast-reroute remote-lfa [level-1 | level-2] maximum-metric <metric> - - This command limits Remote LFA PQ node selection within the specified metric. Metric value range (1-16777215). - -.. cfgcmd:: set protocols isis interface <interface> fast-reroute ti-lfa [level-1|level-2] [node-protection [link-fallback]] - - This command enables per-prefix TI-LFA fast reroute link or node protection. - When node protection is used, option link-fallback enables the computation - and use of link-protecting LFAs for destinations unprotected by node - protection. - -Route Redistribution --------------------- - -.. cfgcmd:: set protocols isis redistribute ipv4 <route source> level-1 - - This command redistributes routing information from the given route source - into the ISIS database as Level-1. There are six modes available for route - source: bgp, connected, kernel, ospf, rip, static. - -.. cfgcmd:: set protocols isis redistribute ipv4 <route source> level-2 - - This command redistributes routing information from the given route source - into the ISIS database as Level-2. There are six modes available for route - source: bgp, connected, kernel, ospf, rip, static. - -.. cfgcmd:: set protocols isis redistribute ipv4 <route source> - <level-1|level-2> metric <number> - - This command specifies metric for redistributed routes from the given route - source. There are six modes available for route source: bgp, connected, - kernel, ospf, rip, static. The metric range is 1 to 16777215. - -.. cfgcmd:: set protocols isis redistribute ipv4 <route source> - <level-1|level-2> route-map <name> - - This command allows to use route map to filter redistributed routes from - the given route source. There are six modes available for route source: - bgp, connected, kernel, ospf, rip, static. - - -Timers ------- - -.. cfgcmd:: set protocols isis lsp-gen-interval <seconds> - - This command sets minimum interval in seconds between regenerating same - LSP. The interval range is 1 to 120. - -.. cfgcmd:: set protocols isis lsp-refresh-interval <seconds> - - This command sets LSP refresh interval in seconds. IS-IS generates LSPs - when the state of a link changes. However, to ensure that routing - databases on all routers remain converged, LSPs in stable networks are - generated on a regular basis even though there has been no change to - the state of the links. The interval range is 1 to 65235. The default - value is 900 seconds. - -.. cfgcmd:: set protocols isis max-lsp-lifetime <seconds> - - This command sets LSP maximum LSP lifetime in seconds. The interval range - is 350 to 65535. LSPs remain in a database for 1200 seconds by default. - If they are not refreshed by that time, they are deleted. You can change - the LSP refresh interval or the LSP lifetime. The LSP refresh interval - should be less than the LSP lifetime or else LSPs will time out before - they are refreshed. - -.. cfgcmd:: set protocols isis spf-interval <seconds> - - This command sets minimum interval between consecutive SPF calculations in - seconds.The interval range is 1 to 120. - -.. cfgcmd:: set protocols isis spf-delay-ietf holddown <milliseconds> - -.. cfgcmd:: set protocols isis spf-delay-ietf init-delay - <milliseconds> - -.. cfgcmd:: set protocols isis spf-delay-ietf long-delay - <milliseconds> - -.. cfgcmd:: set protocols isis spf-delay-ietf short-delay - <milliseconds> - -.. cfgcmd:: set protocols isis spf-delay-ietf time-to-learn - <milliseconds> - - This commands specifies the Finite State Machine (FSM) intended to - control the timing of the execution of SPF calculations in response - to IGP events. The process described in :rfc:`8405`. - -Loop Free Alternate (LFA) -------------------------- - -.. cfgcmd:: set protocols isis fast-reroute lfa remote prefix-list <name> - <level-1|level-2> - - This command enables IP fast re-routing that is part of :rfc:`5286`. - Specifically this is a prefix list which references a prefix in which - will select eligible PQ nodes for remote LFA backups. - -.. cfgcmd:: set protocols isis fast-reroute lfa local load-sharing disable - <level-1|level-2> - - This command disables the load sharing across multiple LFA backups. - -.. cfgcmd:: set protocols isis fast-reroute lfa local tiebreaker - <downstream|lowest-backup-metric|node-protecting> index <number> - <level-1|level-2> - - This command will configure a tie-breaker for multiple local LFA backups. - The lower index numbers will be processed first. - -.. cfgcmd:: set protocols isis fast-reroute lfa local priority-limit - <medium|high|critical> <level-1|level-2> - - 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 -******** - -Enable IS-IS -============ - -**Node 1:** - -.. code-block:: none - - set interfaces loopback lo address '192.168.255.255/32' - set interfaces ethernet eth1 address '192.0.2.1/24' - - set protocols isis interface eth1 - set protocols isis interface lo - set protocols isis net '49.0001.1921.6825.5255.00' - -**Node 2:** - -.. code-block:: none - - set interfaces ethernet eth1 address '192.0.2.2/24' - - set interfaces loopback lo address '192.168.255.254/32' - set interfaces ethernet eth1 address '192.0.2.2/24' - - set protocols isis interface eth1 - set protocols isis interface lo - set protocols isis net '49.0001.1921.6825.5254.00' - - - -This gives us the following neighborships, Level 1 and Level 2: - -.. code-block:: none - - Node-1@vyos:~$ show isis neighbor - Area VyOS: - System Id Interface L State Holdtime SNPA - vyos eth1 1 Up 28 0c87.6c09.0001 - vyos eth1 2 Up 28 0c87.6c09.0001 - - Node-2@vyos:~$ show isis neighbor - Area VyOS: - System Id Interface L State Holdtime SNPA - vyos eth1 1 Up 29 0c33.0280.0001 - vyos eth1 2 Up 28 0c33.0280.0001 - - - -Here's the IP routes that are populated. Just the loopback: - -.. code-block:: none - - Node-1@vyos:~$ show ip route isis - Codes: K - kernel route, C - connected, S - static, R - RIP, - O - OSPF, I - IS-IS, B - BGP, E - EIGRP, N - NHRP, - T - Table, v - VNC, V - VNC-Direct, A - Babel, F - PBR, - f - OpenFabric, - > - selected route, * - FIB route, q - queued, r - rejected, b - backup - t - trapped, o - offload failure - - I 192.0.2.0/24 [115/20] via 192.0.2.2, eth1 inactive, weight 1, 00:02:22 - I>* 192.168.255.254/32 [115/20] via 192.0.2.2, eth1, weight 1, 00:02:22 - - Node-2@vyos:~$ show ip route isis - Codes: K - kernel route, C - connected, S - static, R - RIP, - O - OSPF, I - IS-IS, B - BGP, E - EIGRP, N - NHRP, - T - Table, v - VNC, V - VNC-Direct, A - Babel, F - PBR, - f - OpenFabric, - > - selected route, * - FIB route, q - queued, r - rejected, b - backup - t - trapped, o - offload failure - - I 192.0.2.0/24 [115/20] via 192.0.2.1, eth1 inactive, weight 1, 00:02:21 - I>* 192.168.255.255/32 [115/20] via 192.0.2.1, eth1, weight 1, 00:02:21 - - - -Enable IS-IS and redistribute routes not natively in IS-IS -========================================================== - -**Node 1:** - -.. code-block:: none - - set interfaces dummy dum0 address '203.0.113.1/24' - set interfaces ethernet eth1 address '192.0.2.1/24' - - set policy prefix-list EXPORT-ISIS rule 10 action 'permit' - set policy prefix-list EXPORT-ISIS rule 10 prefix '203.0.113.0/24' - set policy route-map EXPORT-ISIS rule 10 action 'permit' - set policy route-map EXPORT-ISIS rule 10 match ip address prefix-list 'EXPORT-ISIS' - - set protocols isis interface eth1 - set protocols isis net '49.0001.1921.6800.1002.00' - set protocols isis redistribute ipv4 connected level-2 route-map 'EXPORT-ISIS' - -**Node 2:** - -.. code-block:: none - - set interfaces ethernet eth1 address '192.0.2.2/24' - - set protocols isis interface eth1 - set protocols isis net '49.0001.1921.6800.2002.00' - -Routes on Node 2: - -.. code-block:: none - - Node-2@r2:~$ show ip route isis - Codes: K - kernel route, C - connected, S - static, R - RIP, - O - OSPF, I - IS-IS, B - BGP, E - EIGRP, N - NHRP, - T - Table, v - VNC, V - VNC-Direct, A - Babel, D - SHARP, - F - PBR, f - OpenFabric, - > - selected route, * - FIB route, q - queued route, r - rejected route - - I 203.0.113.0/24 [115/10] via 192.0.2.1, eth1, 00:03:42 - -Enable IS-IS and IGP-LDP synchronization -======================================== - -**Node 1:** - -.. code-block:: none - - set interfaces loopback lo address 192.168.255.255/32 - set interfaces ethernet eth0 address 192.0.2.1/24 - - set protocols isis interface eth0 - set protocols isis interface lo passive - set protocols isis ldp-sync - set protocols isis net 49.0001.1921.6825.5255.00 - - set protocols mpls interface eth0 - set protocols mpls ldp discovery transport-ipv4-address 192.168.255.255 - set protocols mpls ldp interface lo - set protocols mpls ldp interface eth0 - set protocols mpls ldp parameters transport-prefer-ipv4 - set protocols mpls ldp router-id 192.168.255.255 - - -This gives us IGP-LDP synchronization for all non-loopback interfaces with -a holddown timer of zero seconds: - - -.. code-block:: none - - Node-1@vyos:~$ show isis mpls ldp-sync - eth0 - LDP-IGP Synchronization enabled: yes - holddown timer in seconds: 0 - State: Sync achieved - - - - -Enable IS-IS with Segment Routing (Experimental) -================================================ - -**Node 1:** - -.. code-block:: none - - set interfaces loopback lo address '192.168.255.255/32' - set interfaces ethernet eth1 address '192.0.2.1/24' - - set protocols isis interface eth1 - set protocols isis interface lo - set protocols isis net '49.0001.1921.6825.5255.00' - set protocols isis segment-routing global-block high-label-value '599' - set protocols isis segment-routing global-block low-label-value '550' - set protocols isis segment-routing prefix 192.168.255.255/32 index value '1' - set protocols isis segment-routing prefix 192.168.255.255/32 index explicit-null - set protocols mpls interface 'eth1' - -**Node 2:** - -.. code-block:: none - - set interfaces loopback lo address '192.168.255.254/32' - set interfaces ethernet eth1 address '192.0.2.2/24' - - set protocols isis interface eth1 - set protocols isis interface lo - set protocols isis net '49.0001.1921.6825.5254.00' - set protocols isis segment-routing global-block high-label-value '599' - set protocols isis segment-routing global-block low-label-value '550' - set protocols isis segment-routing prefix 192.168.255.254/32 index value '2' - set protocols isis segment-routing prefix 192.168.255.254/32 index explicit-null - set protocols mpls interface 'eth1' - - - -This gives us MPLS segment routing enabled and labels for far end loopbacks: - -.. code-block:: none - - Node-1@vyos:~$ show mpls table - Inbound Label Type Nexthop Outbound Label - ---------------------------------------------------------------------- - 552 SR (IS-IS) 192.0.2.2 IPv4 Explicit Null <-- Node-2 loopback learned on Node-1 - 15000 SR (IS-IS) 192.0.2.2 implicit-null - 15001 SR (IS-IS) fe80::e87:6cff:fe09:1 implicit-null - 15002 SR (IS-IS) 192.0.2.2 implicit-null - 15003 SR (IS-IS) fe80::e87:6cff:fe09:1 implicit-null - - Node-2@vyos:~$ show mpls table - Inbound Label Type Nexthop Outbound Label - --------------------------------------------------------------------- - 551 SR (IS-IS) 192.0.2.1 IPv4 Explicit Null <-- Node-1 loopback learned on Node-2 - 15000 SR (IS-IS) 192.0.2.1 implicit-null - 15001 SR (IS-IS) fe80::e33:2ff:fe80:1 implicit-null - 15002 SR (IS-IS) 192.0.2.1 implicit-null - 15003 SR (IS-IS) fe80::e33:2ff:fe80:1 implicit-null - -Here is the routing tables showing the MPLS segment routing label operations: - -.. code-block:: none - - Node-1@vyos:~$ show ip route isis - Codes: K - kernel route, C - connected, S - static, R - RIP, - O - OSPF, I - IS-IS, B - BGP, E - EIGRP, N - NHRP, - T - Table, v - VNC, V - VNC-Direct, A - Babel, F - PBR, - f - OpenFabric, - > - selected route, * - FIB route, q - queued, r - rejected, b - backup - t - trapped, o - offload failure - - I 192.0.2.0/24 [115/20] via 192.0.2.2, eth1 inactive, weight 1, 00:07:48 - I>* 192.168.255.254/32 [115/20] via 192.0.2.2, eth1, label IPv4 Explicit Null, weight 1, 00:03:39 - - Node-2@vyos:~$ show ip route isis - Codes: K - kernel route, C - connected, S - static, R - RIP, - O - OSPF, I - IS-IS, B - BGP, E - EIGRP, N - NHRP, - T - Table, v - VNC, V - VNC-Direct, A - Babel, F - PBR, - f - OpenFabric, - > - selected route, * - FIB route, q - queued, r - rejected, b - backup - t - trapped, o - offload failure - - I 192.0.2.0/24 [115/20] via 192.0.2.1, eth1 inactive, weight 1, 00:07:46 - I>* 192.168.255.255/32 [115/20] via 192.0.2.1, eth1, label IPv4 Explicit Null, weight 1, 00:03:43 - -Enable 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/rst-mpls.rst b/docs/configuration/protocols/rst-mpls.rst deleted file mode 100644 index 550473d7..00000000 --- a/docs/configuration/protocols/rst-mpls.rst +++ /dev/null @@ -1,259 +0,0 @@ -.. _mpls: - -#### -MPLS -#### - -:abbr:`MPLS (Multi-Protocol Label Switching)` is a packet forwarding paradigm -which differs from regular IP forwarding. Instead of IP addresses being used to -make the decision on finding the exit interface, a router will instead use an -exact match on a 32 bit/4 byte header called the MPLS label. This label is -inserted between the ethernet (layer 2) header and the IP (layer 3) header. -One can statically or dynamically assign label allocations, but we will focus -on dynamic allocation of labels using some sort of label distribution protocol -(such as the aptly named Label Distribution Protocol / LDP, Resource Reservation -Protocol / RSVP, or Segment Routing through OSPF/ISIS). These protocols allow -for the creation of a unidirectional/unicast path called a labeled switched -path (initialized as LSP) throughout the network that operates very much like -a tunnel through the network. An easy way of thinking about how an MPLS LSP -actually forwards traffic throughout a network is to think of a GRE tunnel. -They are not the same in how they operate, but they are the same in how they -handle the tunneled packet. It would be good to think of MPLS as a tunneling -technology that can be used to transport many different types of packets, to -aid in traffic engineering by allowing one to specify paths throughout the -network (using RSVP or SR), and to generally allow for easier intra/inter -network transport of data packets. - -For more information on how MPLS label switching works, please go visit -`Wikipedia (MPLS)`_. - -.. note:: MPLS support in VyOS is not finished yet, and therefore its - functionality is limited. Currently there is no support for MPLS enabled VPN - services such as L2VPNs and mVPNs. RSVP support is also not present as the - underlying routing stack (FRR) does not implement it. Currently VyOS - implements LDP as described in RFC 5036; other LDP standard are the - following ones: RFC 6720, RFC 6667, RFC 5919, RFC 5561, RFC 7552, RFC 4447. - Because MPLS is already available (FRR also supports RFC 3031). - - -Label Distribution Protocol -=========================== - -The :abbr:`MPLS (Multi-Protocol Label Switching)` architecture does not assume -a single protocol to create MPLS paths. VyOS supports the Label Distribution -Protocol (LDP) as implemented by FRR, based on :rfc:`5036`. - -:abbr:`LDP (Label Distribution Protocol)` is a TCP based MPLS signaling protocol -that distributes labels creating MPLS label switched paths in a dynamic manner. -LDP is not a routing protocol, as it relies on other routing protocols for -forwarding decisions. LDP cannot bootstrap itself, and therefore relies on said -routing protocols for communication with other routers that use LDP. - -In order to allow for LDP on the local router to exchange label advertisements -with other routers, a TCP session will be established between automatically -discovered and statically assigned routers. LDP will try to establish a TCP -session to the **transport address** of other routers. Therefore for LDP to -function properly please make sure the transport address is shown in the -routing table and reachable to traffic at all times. - -It is highly recommended to use the same address for both the LDP router-id and -the discovery transport address, but for VyOS MPLS LDP to work both parameters -must be explicitly set in the configuration. - -Another thing to keep in mind with LDP is that much like BGP, it is a protocol -that runs on top of TCP. It however does not have an ability to do something -like a refresh capability like BGPs route refresh capability. Therefore one -might have to reset the neighbor for a capability change or a configuration -change to work. - -Configuration Options -===================== - -.. cfgcmd:: set protocols mpls interface <interface> - - Use this command to enable MPLS processing on the interface you define. - -.. cfgcmd:: set protocols mpls ldp interface <interface> - - Use this command to enable LDP on the interface you define. - -.. cfgcmd:: set protocols mpls ldp router-id <address> - - Use this command to configure the IP address used as the LDP router-id of the - local device. - -.. cfgcmd:: set protocols mpls ldp discovery transport-ipv4-address <address> -.. cfgcmd:: set protocols mpls ldp discovery transport-ipv6-address <address> - - Use this command to set the IPv4 or IPv6 transport-address used by LDP. - -.. cfgcmd:: set protocols mpls ldp neighbor <address> password <password> - - Use this command to configure authentication for LDP peers. Set the - IP address of the LDP peer and a password that should be shared in - order to become neighbors. - -.. cfgcmd:: set protocols mpls ldp neighbor <address> session-holdtime <seconds> - - Use this command to configure a specific session hold time for LDP peers. - Set the IP address of the LDP peer and a session hold time that should be - configured for it. You may have to reset the neighbor for this to work. - -.. cfgcmd:: set protocols mpls ldp neighbor <address> ttl-security - <disable | hop count> - - Use this command to enable, disable, or specify hop count for TTL security - for LDP peers. By default the value is set to 255 (or max TTL). - -.. cfgcmd:: set protocols mpls ldp discovery hello-ipv4-interval <seconds> -.. cfgcmd:: set protocols mpls ldp discovery hello-ipv4-holdtime <seconds> -.. cfgcmd:: set protocols mpls ldp discovery hello-ipv6-interval <seconds> -.. cfgcmd:: set protocols mpls ldp discovery hello-ipv6-holdtime <seconds> - - Use these commands if you would like to set the discovery hello and hold time - parameters. - -.. cfgcmd:: set protocols mpls ldp discovery session-ipv4-holdtime <seconds> -.. cfgcmd:: set protocols mpls ldp discovery session-ipv6-holdtime <seconds> - - Use this command if you would like to set the TCP session hold time intervals. - -.. cfgcmd:: set protocols mpls ldp import ipv4 import-filter filter-access-list - <access list number> -.. cfgcmd:: set protocols mpls ldp import ipv6 import-filter filter-access-list6 - <access list number> - - Use these commands to control the importing of forwarding equivalence classes - (FECs) for LDP from neighbors. This would be useful for example on only - accepting the labeled routes that are needed and not ones that are not - needed, such as accepting loopback interfaces and rejecting all others. - -.. cfgcmd:: set protocols mpls ldp export ipv4 export-filter filter-access-list - <access list number> -.. cfgcmd:: set protocols mpls ldp export ipv6 export-filter filter-access-list6 - <access list number> - - Use these commands to control the exporting of forwarding equivalence classes - (FECs) for LDP to neighbors. This would be useful for example on only - announcing the labeled routes that are needed and not ones that are not - needed, such as announcing loopback interfaces and no others. - -.. cfgcmd:: set protocols mpls ldp export ipv4 explicit-null -.. cfgcmd:: set protocols mpls ldp export ipv6 explicit-null - - Use this command if you would like for the router to advertise FECs with a - label of 0 for explicit null operations. - -.. cfgcmd:: set protocols mpls ldp allocation ipv4 access-list - <access list number> -.. cfgcmd:: set protocols mpls ldp allocation ipv6 access-list6 - <access list number> - - Use this command if you would like to control the local FEC allocations for - LDP. A good example would be for your local router to not allocate a label for - everything. Just a label for what it's useful. A good example would be just a - loopback label. - -.. cfgcmd:: set protocols mpls ldp parameters cisco-interop-tlv - - Use this command to use a Cisco non-compliant format to send and interpret - the Dual-Stack capability TLV for IPv6 LDP communications. This is related to - :rfc:`7552`. - -.. cfgcmd:: set protocols mpls ldp parameters ordered-control - - Use this command to use ordered label distribution control mode. FRR - by default uses independent label distribution control mode for label - distribution. This is related to :rfc:`5036`. - -.. cfgcmd:: set protocols mpls ldp parameters transport-prefer-ipv4 - - Use this command to prefer IPv4 for TCP peer transport connection for LDP - when both an IPv4 and IPv6 LDP address are configured on the same interface. - -.. cfgcmd:: set protocols mpls ldp targeted-neighbor ipv4 enable -.. cfgcmd:: set protocols mpls ldp targeted-neighbor ipv6 enable - - Use this command to enable targeted LDP sessions to the local router. The - router will then respond to any sessions that are trying to connect to it that - are not a link local type of TCP connection. - -.. cfgcmd:: set protocols mpls ldp targeted-neighbor ipv4 address <address> -.. cfgcmd:: set protocols mpls ldp targeted-neighbor ipv6 address <address> - - Use this command to enable the local router to try and connect with a targeted - LDP session to another router. - -.. cfgcmd:: set protocols mpls ldp targeted-neighbor ipv4 hello-holdtime - <seconds> -.. cfgcmd:: set protocols mpls ldp targeted-neighbor ipv4 hello-interval - <seconds> -.. cfgcmd:: set protocols mpls ldp targeted-neighbor ipv6 hello-holdtime - <seconds> -.. cfgcmd:: set protocols mpls ldp targeted-neighbor ipv6 hello-interval - <seconds> - - Use these commands if you would like to set the discovery hello and hold time - parameters for the targeted LDP neighbors. - - -Sample configuration to setup LDP on VyOS ------------------------------------------ - -.. code-block:: none - - set protocols ospf area 0 network '192.168.255.252/32' <--- Routing for loopback - set protocols ospf area 0 network '192.168.0.5/32' <--- Routing for an interface connecting to the network - set protocols ospf parameters router-id '192.168.255.252' <--- Router ID setting for OSPF - set protocols mpls interface 'eth1' <--- Enable MPLS for an interface connecting to network - set protocols mpls ldp discovery transport-ipv4-address '192.168.255.252' <--- Transport address for LDP for TCP sessions to connect to - set protocols mpls ldp interface 'eth1' <--- Enable LDP for an interface connecting to network - set protocols mpls ldp interface 'lo' <--- Enable LDP on loopback for future services connectivity - set protocols mpls ldp router-id '192.168.255.252' <--- Router ID setting for LDP - set interfaces ethernet eth1 address '192.168.0.5/31' <--- Interface IP for connecting to network - set interfaces loopback lo address '192.168.255.252/32' <--- Interface loopback IP for router ID and other uses - - -Operational Mode Commands -========================= - -When LDP is working, you will be able to see label information in the outcome -of ``show ip route``. Besides that information, there are also specific *show* -commands for LDP: - -Show ----- - -.. opcmd:: show mpls ldp binding - - Use this command to see the Label Information Base. - -.. opcmd:: show mpls ldp discovery - - Use this command to see discovery hello information - -.. opcmd:: show mpls ldp interface - - Use this command to see LDP interface information - -.. opcmd:: show mpls ldp neighbor - - Use this command to see LDP neighbor information - -.. opcmd:: show mpls ldp neighbor detail - - Use this command to see detailed LDP neighbor information - -Reset ------ - -.. opcmd:: reset mpls ldp neighbor <IPv4 or IPv6 address> - - Use this command to reset an LDP neighbor/TCP session that is established - - -.. stop_vyoslinter - -.. _`Wikipedia (MPLS)`: https://en.wikipedia.org/wiki/Multiprotocol_Label_Switching - -.. start_vyoslinter
\ No newline at end of file diff --git a/docs/configuration/protocols/rst-multicast.rst b/docs/configuration/protocols/rst-multicast.rst deleted file mode 100644 index 61a04e5e..00000000 --- a/docs/configuration/protocols/rst-multicast.rst +++ /dev/null @@ -1,34 +0,0 @@ -.. _routing-static: - -######### -Multicast -######### - -In order to influence Multicast :abbr:`RPF (Reverse Path Forwarding)` lookup, -it is possible to insert into zebra routes for the Multicast -:abbr:`RIB (Routing Information Base)`. These routes are only used for RPF -lookup and will not be used by ZEBRA for insertion into the kernel or for -normal RIB processing. As such it is possible to create weird states with -these commands. - -Use with caution. Most of the time this will not be necessary. - -.. cfgcmd:: set protocols static mroute <subnet> next-hop <address> - [distance <distance>] - - Insert into the Multicast RIB Route `<subnet>` with specified next-hop. - The distance can be specified as well if desired. - -.. cfgcmd:: set protocols static mroute <subnet> next-hop <address> disable - - Do not install route for `<subnet>` into the Multicast RIB. - -.. cfgcmd:: set protocols static mroute <subnet> interface <interface> - [distance <distance>] - - Insert into the Multicast RIB Route `<subnet>` with specified `<interface>`. - The distance can be specified as well if desired. - -.. cfgcmd:: set protocols static mroute <subnet> interface <interface> disable - - Do not install route for `<subnet>` into the Multicast RIB. diff --git a/docs/configuration/protocols/rst-openfabric.rst b/docs/configuration/protocols/rst-openfabric.rst deleted file mode 100644 index aecb5181..00000000 --- a/docs/configuration/protocols/rst-openfabric.rst +++ /dev/null @@ -1,237 +0,0 @@ -.. _openfabric: - -########## -OpenFabric -########## - -OpenFabric, specified in `draft-white-openfabric-06.txt -<https://datatracker.ietf.org/doc/html/draft-white-openfabric-06>`_, is -a routing protocol derived from IS-IS, providing link-state routing with -efficient flooding for topologies like spine-leaf networks. - -OpenFabric a dual stack protocol. -A single OpenFabric instance is able to perform routing for both IPv4 and IPv6. - -******* -General -******* - -Configuration -============= - -Mandatory Settings ------------------- - -For OpenFabric to operate correctly, one must do the equivalent of a Router ID -in Connectionless Network Service (CLNS). This Router ID is called the -:abbr:`NET (Network Entity Title)`. The system identifier must be unique within -the network - -.. cfgcmd:: set protocols openfabric net <network-entity-title> - - This command sets network entity title (NET) provided in ISO format. - - Here is an example :abbr:`NET (Network Entity Title)` value: - - .. code-block:: none - - 49.0001.1921.6800.1002.00 - - The CLNS address consists of the following parts: - - * :abbr:`AFI (Address family authority identifier)` - ``49`` The AFI value - 49 is what OpenFabric uses for private addressing. - - * Area identifier: ``0001`` OpenFabric area number (numerical area ``1``) - - * System identifier: ``1921.6800.1002`` - for system identifiers we recommend - to use IP address or MAC address of the router itself. The way to construct - this is to keep all of the zeroes of the router IP address, and then change - the periods from being every three numbers to every four numbers. The - address that is listed here is ``192.168.1.2``, which if expanded will turn - into ``192.168.001.002``. Then all one has to do is move the dots to have - four numbers instead of three. This gives us ``1921.6800.1002``. - - * :abbr:`NET (Network Entity Title)` selector: ``00`` Must always be 00. This - setting indicates "this system" or "local system." - -.. cfgcmd:: set protocols openfabric domain <name> interface <interface> - address-family <ipv4|ipv6> - - This command enables OpenFabric instance with <NAME> on this interface, and - allows for adjacency to occur for address family (IPv4 or IPv6 or both). - -OpenFabric Global Configuration -------------------------------- - -.. cfgcmd:: set protocols openfabric domain-password <plaintext-password|md5> - <password> - - This command configures the authentication password for a routing domain, - as clear text or md5 one. - -.. cfgcmd:: set protocols openfabric domain <name> purge-originator - - This command enables :rfc:`6232` purge originator identification. - -.. cfgcmd:: set protocols openfabric domain <name> set-overload-bit - - This command sets overload bit to avoid any transit traffic through this - router. - -.. cfgcmd:: set protocols openfabric domain <name> log-adjacency-changes - - Log changes in adjacency state. - -.. cfgcmd:: set protocols openfabric domain <name> fabric-tier <number> - - This command sets a static tier number to advertise as location - in the fabric. - - -Interface Configuration ------------------------ - -.. cfgcmd:: set protocols openfabric interface <interface> hello-interval - <seconds> - - This command sets hello interval in seconds on a given interface. - The range is 1 to 600. Hello packets are used to establish and maintain - adjacency between OpenFabric neighbors. - -.. cfgcmd:: set protocols openfabric domain <name> interface <interface> - hello-multiplier <number> - - This command sets multiplier for hello holding time on a given - interface. The range is 2 to 100. - -.. cfgcmd:: set protocols openfabric domain <name> interface <interface> - metric <metric> - - This command sets default metric for circuit. - The metric range is 1 to 16777215. - -.. cfgcmd:: set protocols openfabric interface <interface> passive - - This command enables the passive mode for this interface. - -.. cfgcmd:: set protocols openfabric domain <name> interface <interface> - password plaintext-password <text> - - This command sets the authentication password for the interface. - -.. cfgcmd:: set protocols openfabric domain <name> interface <interface> - csnp-interval <seconds> - - This command sets Complete Sequence Number Packets (CSNP) interval in seconds. - The interval range is 1 to 600. - -.. cfgcmd:: set protocols openfabric domain <name> interface <interface> - psnp-interval <number> - - This command sets Partial Sequence Number Packets (PSNP) interval in seconds. - The interval range is 1 to 120. - -Timers ------- - -.. cfgcmd:: set protocols openfabric domain <name> lsp-gen-interval <seconds> - - This command sets minimum interval at which link-state packets (LSPs) are - generated. The interval range is 1 to 120. - -.. cfgcmd:: set protocols openfabric domain <name> lsp-refresh-interval <seconds> - - This command sets LSP refresh interval in seconds. The interval range - is 1 to 65235. - -.. cfgcmd:: set protocols openfabric domain <name> max-lsp-lifetime <seconds> - - This command sets LSP maximum LSP lifetime in seconds. The interval range - is 360 to 65535. LSPs remain in a database for 1200 seconds by default. - If they are not refreshed by that time, they are deleted. You can change - the LSP refresh interval or the LSP lifetime. The LSP refresh interval - should be less than the LSP lifetime or else LSPs will time out before - they are refreshed. - -.. cfgcmd:: set protocols openfabric domain <name> spf-interval <seconds> - - This command sets minimum interval between consecutive shortest path first - (SPF) calculations in seconds.The interval range is 1 to 120. - - -******** -Examples -******** - -Enable OpenFabric -================= - -**Node 1:** - -.. code-block:: none - - set interfaces loopback lo address '192.168.255.255/32' - set interfaces ethernet eth1 address '192.0.2.1/24' - - set protocols openfabric domain VyOS interface eth1 address-family ipv4 - set protocols openfabric domain VyOS interface lo address-family ipv4 - set protocols openfabric net '49.0001.1921.6825.5255.00' - -**Node 2:** - -.. code-block:: none - - set interfaces loopback lo address '192.168.255.254/32' - set interfaces ethernet eth1 address '192.0.2.2/24' - - set protocols openfabric domain VyOS interface eth1 address-family ipv4 - set protocols openfabric domain VyOS interface lo address-family ipv4 - set protocols openfabric net '49.0001.1921.6825.5254.00' - - - -This gives us the following neighborships: - -.. code-block:: none - - Node-1@vyos:~$ show openfabric neighbor - show openfabric neighbor - Area VyOS: - System Id Interface L State Holdtime SNPA - vyos eth1 2 Up 27 2020.2020.2020 - - - Node-2@vyos:~$ show openfabric neighbor - show openfabric neighbor - Area VyOS: - System Id Interface L State Holdtime SNPA - vyos eth1 2 Up 30 2020.2020.2020 - -Here's the IP routes that are populated: - -.. code-block:: none - - Node-1@vyos:~$ show ip route openfabric - show ip route openfabric - Codes: K - kernel route, C - connected, S - static, R - RIP, - O - OSPF, I - IS-IS, B - BGP, E - EIGRP, N - NHRP, - T - Table, v - VNC, V - VNC-Direct, A - Babel, F - PBR, - f - OpenFabric, - > - selected route, * - FIB route, q - queued, r - rejected, b - backup - t - trapped, o - offload failure - - f 192.0.2.0/24 [115/20] via 192.0.2.2, eth1 onlink, weight 1, 00:00:10 - f>* 192.168.255.254/32 [115/20] via 192.0.2.2, eth1 onlink, weight 1, 00:00:10 - - Node-2@vyos:~$ show ip route openfabric - show ip route openfabric - Codes: K - kernel route, C - connected, S - static, R - RIP, - O - OSPF, I - IS-IS, B - BGP, E - EIGRP, N - NHRP, - T - Table, v - VNC, V - VNC-Direct, A - Babel, F - PBR, - f - OpenFabric, - > - selected route, * - FIB route, q - queued, r - rejected, b - backup - t - trapped, o - offload failure - - f 192.0.2.0/24 [115/20] via 192.0.2.1, eth1 onlink, weight 1, 00:00:48 - f>* 192.168.255.255/32 [115/20] via 192.0.2.1, eth1 onlink, weight 1, 00:00:48 diff --git a/docs/configuration/protocols/rst-ospf.rst b/docs/configuration/protocols/rst-ospf.rst deleted file mode 100644 index ac0ed160..00000000 --- a/docs/configuration/protocols/rst-ospf.rst +++ /dev/null @@ -1,1386 +0,0 @@ -.. _routing-ospf: - -#### -OSPF -#### - -:abbr:`OSPF (Open Shortest Path First)` is a routing protocol for Internet -Protocol (IP) networks. It uses a link state routing (LSR) algorithm and falls -into the group of interior gateway protocols (IGPs), operating within a single -autonomous system (AS). It is defined as OSPF Version 2 in :rfc:`2328` (1998) -for IPv4. Updates for IPv6 are specified as OSPF Version 3 in :rfc:`5340` -(2008). OSPF supports the :abbr:`CIDR (Classless Inter-Domain Routing)` -addressing model. - -OSPF is a widely used IGP in large enterprise networks. - -************* -OSPFv2 (IPv4) -************* - -Configuration -============= - -General -------- - -VyOS does not have a special command to start the OSPF process. The OSPF process -starts when the first ospf enabled interface is configured. - -.. cfgcmd:: set protocols ospf area <number> network <A.B.C.D/M> - - This command specifies the OSPF enabled interface(s). If the interface has - an address from defined range then the command enables OSPF on this - interface so router can provide network information to the other ospf - routers via this interface. - - This command is also used to enable the OSPF process. The area number can be - specified in decimal notation in the range from 0 to 4294967295. Or it - can be specified in dotted decimal notation similar to ip address. - - Prefix length in interface must be equal or bigger (i.e. smaller network) - than prefix length in network statement. For example statement above doesn't - enable ospf on interface with address 192.168.1.1/23, but it does on - interface with address 192.168.1.129/25. - - In some cases it may be more convenient to enable OSPF on a per - interface/subnet - basis :cfgcmd:`set protocols ospf interface <interface> area <x.x.x.x | x>` - -.. cfgcmd:: set protocols ospf auto-cost reference-bandwidth <number> - - This command sets the reference bandwidth for cost calculations, where - bandwidth can be in range from 1 to 4294967, specified in Mbits/s. The - default is 100Mbit/s (i.e. a link of bandwidth 100Mbit/s or higher will - have a cost of 1. Cost of lower bandwidth links will be scaled with - reference to this cost). - -.. cfgcmd:: set protocols ospf parameters router-id <rid> - - This command sets the router-ID of the OSPF process. The router-ID may be an - IP address of the router, but need not be – it can be any arbitrary 32bit - number. However it MUST be unique within the entire OSPF domain to the OSPF - speaker – bad things will happen if multiple OSPF speakers are configured - with the same router-ID! - - -Optional --------- - -.. cfgcmd:: set protocols ospf default-information originate [always] - [metric <number>] [metric-type <1|2>] [route-map <name>] - - Originate an AS-External (type-5) LSA describing a default route into all - external-routing capable areas, of the specified metric and metric type. - If the :cfgcmd:`always` keyword is given then the default is always - advertised, even when there is no default present in the routing table. - The argument :cfgcmd:`route-map` specifies to advertise the default route - if the route map is satisfied. - -.. cfgcmd:: set protocols ospf distance global <distance> - - This command change distance value of OSPF globally. - The distance range is 1 to 255. - -.. cfgcmd:: set protocols ospf distance ospf <external|inter-area|intra-area> - <distance> - - This command change distance value of OSPF. The arguments are the distance - values for external routes, inter-area routes and intra-area routes - respectively. The distance range is 1 to 255. - - .. note:: Routes with a distance of 255 are effectively disabled and not - installed into the kernel. - -.. cfgcmd:: set protocols ospf log-adjacency-changes [detail] - - This command allows to log changes in adjacency. With the optional - :cfgcmd:`detail` argument, all changes in adjacency status are shown. - Without :cfgcmd:`detail`, only changes to full or regressions are shown. - -.. cfgcmd:: set protocols ospf max-metric router-lsa - <administrative|on-shutdown <seconds>|on-startup <seconds>> - - This enables :rfc:`3137` support, where the OSPF process describes its - transit links in its router-LSA as having infinite distance so that other - routers will avoid calculating transit paths through the router while - still being able to reach networks through the router. - - This support may be enabled administratively (and indefinitely) with the - :cfgcmd:`administrative` command. It may also be enabled conditionally. - Conditional enabling of max-metric router-lsas can be for a period of - seconds after startup with the :cfgcmd:`on-startup <seconds>` command - and/or for a period of seconds prior to shutdown with the - :cfgcmd:`on-shutdown <seconds>` command. The time range is 5 to 86400. - -.. cfgcmd:: set protocols ospf parameters abr-type - <cisco|ibm|shortcut|standard> - - This command selects ABR model. OSPF router supports four ABR models: - - **cisco** – a router will be considered as ABR if it has several configured - links to the networks in different areas one of which is a backbone area. - Moreover, the link to the backbone area should be active (working). - **ibm** – identical to "cisco" model but in this case a backbone area link - may not be active. - **standard** – router has several active links to different areas. - **shortcut** – identical to "standard" but in this model a router is - allowed to use a connected areas topology without involving a backbone - area for inter-area connections. - - Detailed information about "cisco" and "ibm" models differences can be - found in :rfc:`3509`. A "shortcut" model allows ABR to create routes - between areas based on the topology of the areas connected to this router - but not using a backbone area in case if non-backbone route will be - cheaper. For more information about "shortcut" model, - see :t:`ospf-shortcut-abr-02.txt` - -.. cfgcmd:: set protocols ospf parameters rfc1583-compatibility - - :rfc:`2328`, the successor to :rfc:`1583`, suggests according to section - G.2 (changes) in section 16.4.1 a change to the path preference algorithm - that prevents possible routing loops that were possible in the old version - of OSPFv2. More specifically it demands that inter-area paths and - intra-area backbone path are now of equal preference but still both - preferred to external paths. - - This command should NOT be set normally. - -.. cfgcmd:: set protocols ospf interface <interface> passive [disable] - - This command specifies interface as passive. Passive interface advertises - its address, but does not run the OSPF protocol (adjacencies are not formed - and hello packets are not generated). - - The optional `disable` option allows to exclude interface from passive state. - This command is used if the command :cfgcmd:`passive-interface default` was - configured. - -.. cfgcmd:: set protocols ospf passive-interface default - - This command specifies all interfaces as passive by default. Because this - command changes the configuration logic to a default passive; therefore, - interfaces where router adjacencies are expected need to be configured - with the :cfgcmd:`passive-interface-exclude` command. - -.. cfgcmd:: set protocols ospf maximum-paths <1-64> - - Use this command to control the maximum number of equal cost paths to reach - a specific destination. The upper limit may differ if you change the value - of MULTIPATH_NUM during compilation. The default is MULTIPATH_NUM (64). - -.. cfgcmd:: set protocols ospf refresh timers <seconds> - - The router automatically updates link-state information with its neighbors. - Only an obsolete information is updated which age has exceeded a specific - threshold. This parameter changes a threshold value, which by default is - 1800 seconds (half an hour). The value is applied to the whole OSPF router. - The timer range is 10 to 1800. - -.. cfgcmd:: set protocols ospf timers throttle spf - <delay|initial-holdtime|max-holdtime> <seconds> - - This command sets the initial delay, the initial-holdtime and the - maximum-holdtime between when SPF is calculated and the event which - triggered the calculation. The times are specified in milliseconds and must - be in the range of 0 to 600000 milliseconds. :cfgcmd:`delay` sets the - initial SPF schedule delay in milliseconds. The default value is 200 ms. - :cfgcmd:`initial-holdtime` sets the minimum hold time between two - consecutive SPF calculations. The default value is 1000 ms. - :cfgcmd:`max-holdtime` sets the maximum wait time between two - consecutive SPF calculations. The default value is 10000 ms. - -.. cfgcmd:: set protocols ospf ldp-sync - - This command will enable IGP-LDP synchronization globally for OSPF. This - requires for LDP to be functional. This is described in :rfc:`5443`. By - default all interfaces operational in OSPF are enabled for synchronization. - Loopbacks are exempt. - -.. cfgcmd:: set protocols ospf ldp-sync holddown <seconds> - - This command will change the hold down value globally for IGP-LDP - synchronization during convergence/interface flap events. - -.. cfgcmd:: set protocols ospf capability opaque - - ospfd supports Opaque LSA :rfc:`2370` as partial support for MPLS Traffic - Engineering LSAs. The opaque-lsa capability must be enabled in the - configuration. - - An alternate command could be "mpls-te on" (Traffic Engineering) - - .. note:: FRR offers only partial support for some of the routing - protocol extensions that are used with MPLS-TE; it does not - support a complete RSVP-TE solution. - -Area Configuration ------------------- - -.. cfgcmd:: set protocols ospf area <number> area-type stub - - This command specifies the area to be a Stub Area. That is, an area where - no router originates routes external to OSPF and hence an area where all - external routes are via the ABR(s). Hence, ABRs for such an area do not - need to pass AS-External LSAs (type-5) or ASBR-Summary LSAs (type-4) into - the area. They need only pass Network-Summary (type-3) LSAs into such an - area, along with a default-route summary. - -.. cfgcmd:: set protocols ospf area <number> area-type stub no-summary - - This command specifies the area to be a Totally Stub Area. In addition to - stub area limitations this area type prevents an ABR from injecting - Network-Summary (type-3) LSAs into the specified stub area. Only default - summary route is allowed. - -.. cfgcmd:: set protocols ospf area <number> area-type stub default-cost - <number> - - This command sets the cost of default-summary LSAs announced to stubby - areas. The cost range is 0 to 16777215. - -.. cfgcmd:: set protocols ospf area <number> area-type nssa - - This command specifies the area to be a Not So Stubby Area. External - routing information is imported into an NSSA in Type-7 LSAs. Type-7 LSAs - are similar to Type-5 AS-external LSAs, except that they can only be - flooded into the NSSA. In order to further propagate the NSSA external - information, the Type-7 LSA must be translated to a Type-5 AS-external-LSA - by the NSSA ABR. - -.. cfgcmd:: set protocols ospf area <number> area-type nssa no-summary - - This command specifies the area to be a NSSA Totally Stub Area. ABRs for - such an area do not need to pass Network-Summary (type-3) LSAs (except the - default summary route), ASBR-Summary LSAs (type-4) and AS-External LSAs - (type-5) into the area. But Type-7 LSAs that convert to Type-5 at the NSSA - ABR are allowed. - -.. cfgcmd:: set protocols ospf area <number> area-type nssa default-cost - <number> - - This command sets the default cost of LSAs announced to NSSA areas. - The cost range is 0 to 16777215. - -.. cfgcmd:: set protocols ospf area <number> area-type nssa translate - <always|candidate|never> - - Specifies whether this NSSA border router will unconditionally translate - Type-7 LSAs into Type-5 LSAs. When role is Always, Type-7 LSAs are - translated into Type-5 LSAs regardless of the translator state of other - NSSA border routers. When role is Candidate, this router participates in - the translator election to determine if it will perform the translations - duties. When role is Never, this router will never translate Type-7 LSAs - into Type-5 LSAs. - -.. cfgcmd:: set protocols ospf area <number> authentication plaintext-password - - This command specifies that simple password authentication should be used - for the given area. The password must also be configured on a per-interface - basis. - -.. cfgcmd:: set protocols ospf area <number> authentication md5 - - This command specify that OSPF packets must be authenticated with MD5 HMACs - within the given area. Keying material must also be configured on a - per-interface basis. - -.. cfgcmd:: set protocols ospf area <number> range <A.B.C.D/M> [cost <number>] - - This command summarizes intra area paths from specified area into one - summary-LSA (Type-3) announced to other areas. This command can be used - only in ABR and ONLY router-LSAs (Type-1) and network-LSAs (Type-2) - (i.e. LSAs with scope area) can be summarized. AS-external-LSAs (Type-5) - can’t be summarized - their scope is AS. The optional argument - :cfgcmd:`cost` specifies the aggregated link metric. The metric range is 0 - to 16777215. - -.. cfgcmd:: set protocols ospf area <number> range <A.B.C.D/M> not-advertise - - This command instead of summarizing intra area paths filter them - i.e. - intra area paths from this range are not advertised into other areas. - This command makes sense in ABR only. - -.. cfgcmd:: set protocols ospf area <number> export-list <acl_number> - - Filter Type-3 summary-LSAs announced to other areas originated from - intra- area paths from specified area. - This command makes sense in ABR only. - -.. cfgcmd:: set protocols ospf area <number> import-list <acl_number> - - Same as export-list, but it applies to paths announced into specified - area as Type-3 summary-LSAs. - This command makes sense in ABR only. - -.. cfgcmd:: set protocols ospf area <number> range <A.B.C.D/M> substitute - <E.F.G.H/M> - - One Type-3 summary-LSA with routing info <E.F.G.H/M> is announced into - backbone area if defined area contains at least one intra-area network - (i.e. described with router-LSA or network-LSA) from range <A.B.C.D/M>. - This command makes sense in ABR only. - -.. cfgcmd:: set protocols ospf area <number> shortcut <default|disable|enable> - - This parameter allows to "shortcut" routes (non-backbone) for inter-area - routes. There are three modes available for routes shortcutting: - - **default** – this area will be used for shortcutting only if ABR does not - have a link to the backbone area or this link was lost. - **enable** – the area will be used for shortcutting every time the route - that goes through it is cheaper. - **disable** – this area is never used by ABR for routes shortcutting. - -.. cfgcmd:: set protocols ospf area <number> virtual-link <A.B.C.D> - - Provides a backbone area coherence by virtual link establishment. - - In general, OSPF protocol requires a backbone area (area 0) to be coherent - and fully connected. I.e. any backbone area router must have a route to any - other backbone area router. Moreover, every ABR must have a link to - backbone area. However, it is not always possible to have a physical link - to a backbone area. In this case between two ABR (one of them has a link to - the backbone area) in the area (not stub area) a virtual link is organized. - - <number> – area identifier through which a virtual link goes. - <A.B.C.D> – ABR router-id with which a virtual link is established. Virtual - link must be configured on both routers. - - Formally, a virtual link looks like a point-to-point network connecting two - ABR from one area one of which physically connected to a backbone area. - This pseudo-network is considered to belong to a backbone area. - - -Interface Configuration ------------------------ - -.. cfgcmd:: set protocols ospf interface <interface> area <x.x.x.x | x> - - Enable ospf on an interface and set associated area. - - If you have a lot of interfaces, and/or a lot of subnets, then enabling - OSPF via this command may result in a slight performance improvement. - -.. cfgcmd:: set protocols ospf interface <interface> authentication - plaintext-password <text> - - This command sets OSPF authentication key to a simple password. After - setting, all OSPF packets are authenticated. Key has length up to 8 chars. - - Simple text password authentication is insecure and deprecated in favour of - MD5 HMAC authentication. - -.. cfgcmd:: set protocols ospf interface <interface> authentication md5 - key-id <id> md5-key <text> - - This command specifys that MD5 HMAC authentication must be used on this - interface. It sets OSPF authentication key to a cryptographic password. - Key-id identifies secret key used to create the message digest. This ID - is part of the protocol and must be consistent across routers on a link. - The key can be long up to 16 chars (larger strings will be truncated), - and is associated with the given key-id. - -.. cfgcmd:: set protocols ospf interface <interface> bandwidth <number> - - This command sets the interface bandwidth for cost calculations, where - bandwidth can be in range from 1 to 100000, specified in Mbits/s. - -.. cfgcmd:: set protocols ospf interface <interface> cost <number> - - This command sets link cost for the specified interface. The cost value is - set to router-LSA’s metric field and used for SPF calculation. The cost - range is 1 to 65535. - -.. cfgcmd:: set protocols ospf interface <interface> dead-interval <number> - - Set number of seconds for router Dead Interval timer value used for Wait - Timer and Inactivity Timer. This value must be the same for all routers - attached to a common network. The default value is 40 seconds. The - interval range is 1 to 65535. - -.. cfgcmd:: set protocols ospf interface <interface> hello-multiplier <number> - - The hello-multiplier specifies how many Hellos to send per second, from 1 - (every second) to 10 (every 100ms). Thus one can have 1s convergence time - for OSPF. If this form is specified, then the hello-interval advertised in - Hello packets is set to 0 and the hello-interval on received Hello packets - is not checked, thus the hello-multiplier need NOT be the same across - multiple routers on a common link. - -.. cfgcmd:: set protocols ospf interface <interface> hello-interval <number> - - Set number of seconds for Hello Interval timer value. Setting this value, - Hello packet will be sent every timer value seconds on the specified - interface. This value must be the same for all routers attached to a - common network. The default value is 10 seconds. The interval range is 1 - to 65535. - -.. cfgcmd:: set protocols ospf interface <interface> bfd - - This command enables :abbr:`BFD (Bidirectional Forwarding Detection)` on - this OSPF link interface. - -.. cfgcmd:: set protocols ospf interface <interface> mtu-ignore - - This command disables check of the MTU value in the OSPF DBD packets. Thus, - use of this command allows the OSPF adjacency to reach the FULL state even - though there is an interface MTU mismatch between two OSPF routers. - -.. cfgcmd:: set protocols ospf interface <interface> network <type> - - This command allows to specify the distribution type for the network - connected to this interface: - - **broadcast** – broadcast IP addresses distribution. - **non-broadcast** – address distribution in NBMA networks topology. - **point-to-multipoint** – address distribution in point-to-multipoint - networks. - **point-to-point** – address distribution in point-to-point networks. - -.. cfgcmd:: set protocols ospf interface <interface> priority <number> - - This command sets Router Priority integer value. The router with the - highest priority will be more eligible to become Designated Router. - Setting the value to 0, makes the router ineligible to become - Designated Router. The default value is 1. The interval range is 0 to 255. - -.. cfgcmd:: set protocols ospf interface <interface> retransmit-interval - <number> - - This command sets number of seconds for RxmtInterval timer value. This - value is used when retransmitting Database Description and Link State - Request packets if acknowledge was not received. The default value is 5 - seconds. The interval range is 3 to 65535. - -.. cfgcmd:: set protocols ospf interface <interface> transmit-delay <number> - - This command sets number of seconds for InfTransDelay value. It allows to - set and adjust for each interface the delay interval before starting the - synchronizing process of the router's database with all neighbors. The - default value is 1 seconds. The interval range is 3 to 65535. - -.. cfgcmd:: set protocols ospf interface <interface> ldp-sync disable - - This command disables IGP-LDP sync for this specific interface. - -.. cfgcmd:: set protocols ospf interface <interface> ldp-sync holddown - <seconds> - - This command will change the hold down value for IGP-LDP synchronization - during convergence/interface flap events, but for this interface only. - -External Route Summarisation ----------------------------- - -This feature summarises originated external LSAs (Type-5 and Type-7). Summary -Route will be originated on-behalf of all matched external LSAs. - -.. cfgcmd:: set protocols ospf aggregation timer <seconds> - - Configure aggregation delay timer interval. - - Summarisation starts only after this delay timer expiry. - -.. cfgcmd:: set protocols ospf summary-address x.x.x.x/y [tag (1-4294967295)] - - This command enable/disables summarisation for the configured address range. - - Tag is the optional parameter. If tag configured Summary route will be - originated with the configured tag. - -.. cfgcmd:: set protocols ospf summary-address x.x.x.x/y no-advertise - - This command to ensure not advertise the summary lsa for the matched - external LSAs. - -Graceful Restart ----------------- - -.. cfgcmd:: set protocols ospf graceful-restart [grace-period (1-1800)] - - Configure Graceful Restart :rfc:`3623` restarting support. When enabled, - the default grace period is 120 seconds. - - To perform a graceful shutdown, the FRR ``graceful-restart prepare ip - ospf`` EXEC-level command needs to be issued before restarting the - ospfd daemon. - -.. cfgcmd:: set protocols ospf graceful-restart helper enable [router-id A.B.C.D] - - Configure Graceful Restart :rfc:`3623` helper support. By default, helper support - is disabled for all neighbours. This config enables/disables helper support - on this router for all neighbours. - - To enable/disable helper support for a specific neighbour, the router-id - (A.B.C.D) has to be specified. - -.. cfgcmd:: set protocols ospf graceful-restart helper no-strict-lsa-checking - - By default `strict-lsa-checking` is configured then the helper will abort - the Graceful Restart when a LSA change occurs which affects the restarting - router. - - This command disables it. - -.. cfgcmd:: set protocols ospf graceful-restart helper supported-grace-time - - Supports as HELPER for configured grace period. - -.. cfgcmd:: set protocols ospf graceful-restart helper planned-only - - It helps to support as HELPER only for planned restarts. - - By default, it supports both planned and unplanned outages. - -Manual Neighbor Configuration ------------------------------ - -OSPF routing devices normally discover their neighbors dynamically by -listening to the broadcast or multicast hello packets on the network. -Because an NBMA network does not support broadcast (or multicast), the -device cannot discover its neighbors dynamically, so you must configure all -the neighbors statically. - -.. cfgcmd:: set protocols ospf neighbor <A.B.C.D> - - This command specifies the IP address of the neighboring device. - -.. cfgcmd:: set protocols ospf neighbor <A.B.C.D> poll-interval <seconds> - - This command specifies the length of time, in seconds, before the routing - device sends hello packets out of the interface before it establishes - adjacency with a neighbor. The range is 1 to 65535 seconds. The default - value is 60 seconds. - -.. cfgcmd:: set protocols ospf neighbor <A.B.C.D> priority <number> - - This command specifies the router priority value of the nonbroadcast - neighbor associated with the IP address specified. The default is 0. - This keyword does not apply to point-to-multipoint interfaces. - - -Redistribution Configuration ----------------------------- - -.. cfgcmd:: set protocols ospf redistribute <route source> - - This command redistributes routing information from the given route source - to the OSPF process. There are five modes available for route source: bgp, - connected, kernel, rip, static. - -.. cfgcmd:: set protocols ospf default-metric <number> - - This command specifies the default metric value of redistributed routes. - The metric range is 0 to 16777214. - -.. cfgcmd:: set protocols ospf redistribute <route source> metric <number> - - This command specifies metric for redistributed routes from the given - route source. There are five modes available for route source: bgp, - connected, kernel, rip, static. The metric range is 1 to 16777214. - -.. cfgcmd:: set protocols ospf redistribute <route source> metric-type <1|2> - - This command specifies metric type for redistributed routes. Difference - between two metric types that metric type 1 is a metric which is - "commensurable" with inner OSPF links. When calculating a metric to the - external destination, the full path metric is calculated as a metric sum - path of a router which had advertised this link plus the link metric. - Thus, a route with the least summary metric will be selected. If external - link is advertised with metric type 2 the path is selected which lies - through the router which advertised this link with the least metric - despite of the fact that internal path to this router is longer (with more - cost). However, if two routers advertised an external link and with metric - type 2 the preference is given to the path which lies through the router - with a shorter internal path. If two different routers advertised two - links to the same external destimation but with different metric type, - metric type 1 is preferred. If type of a metric left undefined the router - will consider these external links to have a default metric type 2. - -.. cfgcmd:: set protocols ospf redistribute <route source> route-map <name> - - This command allows to use route map to filter redistributed routes from - the given route source. There are five modes available for route source: - bgp, connected, kernel, rip, static. - - -Operational Mode Commands -------------------------- - -.. opcmd:: show ip ospf neighbor - - This command displays the neighbors status. - -.. code-block:: none - - Neighbor ID Pri State Dead Time Address Interface RXmtL RqstL DBsmL - 10.0.13.1 1 Full/DR 38.365s 10.0.13.1 eth0:10.0.13.3 0 0 0 - 10.0.23.2 1 Full/Backup 39.175s 10.0.23.2 eth1:10.0.23.3 0 0 0 - -.. opcmd:: show ip ospf neighbor detail - - This command displays the neighbors information in a detailed form, not - just a summary table. - -.. code-block:: none - - Neighbor 10.0.13.1, interface address 10.0.13.1 - In the area 0.0.0.0 via interface eth0 - Neighbor priority is 1, State is Full, 5 state changes - Most recent state change statistics: - Progressive change 11m55s ago - DR is 10.0.13.1, BDR is 10.0.13.3 - Options 2 *|-|-|-|-|-|E|- - Dead timer due in 34.854s - Database Summary List 0 - Link State Request List 0 - Link State Retransmission List 0 - Thread Inactivity Timer on - Thread Database Description Retransmision off - Thread Link State Request Retransmission on - Thread Link State Update Retransmission on - - Neighbor 10.0.23.2, interface address 10.0.23.2 - In the area 0.0.0.1 via interface eth1 - Neighbor priority is 1, State is Full, 4 state changes - Most recent state change statistics: - Progressive change 41.193s ago - DR is 10.0.23.3, BDR is 10.0.23.2 - Options 2 *|-|-|-|-|-|E|- - Dead timer due in 35.661s - Database Summary List 0 - Link State Request List 0 - Link State Retransmission List 0 - Thread Inactivity Timer on - Thread Database Description Retransmision off - Thread Link State Request Retransmission on - Thread Link State Update Retransmission on - -.. opcmd:: show ip ospf neighbor <A.B.C.D> - - This command displays the neighbors information in a detailed form for a - neighbor whose IP address is specified. - -.. opcmd:: show ip ospf neighbor <interface> - - This command displays the neighbors status for a neighbor on the specified - interface. - -.. opcmd:: show ip ospf interface [<interface>] - - This command displays state and configuration of OSPF the specified - interface, or all interfaces if no interface is given. - -.. code-block:: none - - eth0 is up - ifindex 2, MTU 1500 bytes, BW 4294967295 Mbit <UP,BROADCAST,RUNNING,MULTICAST> - Internet Address 10.0.13.3/24, Broadcast 10.0.13.255, Area 0.0.0.0 - MTU mismatch detection: enabled - Router ID 10.0.23.3, Network Type BROADCAST, Cost: 1 - Transmit Delay is 1 sec, State Backup, Priority 1 - Backup Designated Router (ID) 10.0.23.3, Interface Address 10.0.13.3 - Multicast group memberships: OSPFAllRouters OSPFDesignatedRouters - Timer intervals configured, Hello 10s, Dead 40s, Wait 40s, Retransmit 5 - Hello due in 4.470s - Neighbor Count is 1, Adjacent neighbor count is 1 - eth1 is up - ifindex 3, MTU 1500 bytes, BW 4294967295 Mbit <UP,BROADCAST,RUNNING,MULTICAST> - Internet Address 10.0.23.3/24, Broadcast 10.0.23.255, Area 0.0.0.1 - MTU mismatch detection: enabled - Router ID 10.0.23.3, Network Type BROADCAST, Cost: 1 - Transmit Delay is 1 sec, State DR, Priority 1 - Backup Designated Router (ID) 10.0.23.2, Interface Address 10.0.23.2 - Saved Network-LSA sequence number 0x80000002 - Multicast group memberships: OSPFAllRouters OSPFDesignatedRouters - Timer intervals configured, Hello 10s, Dead 40s, Wait 40s, Retransmit 5 - Hello due in 4.563s - Neighbor Count is 1, Adjacent neighbor count is 1 - -.. opcmd:: show ip ospf route [detail] - - This command displays the OSPF routing table, as determined by the most - recent SPF calculation. With the optional :cfgcmd:`detail` argument, - each route item's advertiser router and network attribute will be shown. - -.. code-block:: none - - ============ OSPF network routing table ============ - N IA 10.0.12.0/24 [3] area: 0.0.0.0 - via 10.0.13.3, eth0 - N 10.0.13.0/24 [1] area: 0.0.0.0 - directly attached to eth0 - N IA 10.0.23.0/24 [2] area: 0.0.0.0 - via 10.0.13.3, eth0 - N 10.0.34.0/24 [2] area: 0.0.0.0 - via 10.0.13.3, eth0 - - ============ OSPF router routing table ============= - R 10.0.23.3 [1] area: 0.0.0.0, ABR - via 10.0.13.3, eth0 - R 10.0.34.4 [2] area: 0.0.0.0, ASBR - via 10.0.13.3, eth0 - - ============ OSPF external routing table =========== - N E2 172.16.0.0/24 [2/20] tag: 0 - via 10.0.13.3, eth0 - -The table consists of following data: - -**OSPF network routing table** – includes a list of acquired routes for all -accessible networks (or aggregated area ranges) of OSPF system. "IA" flag -means that route destination is in the area to which the router is not -connected, i.e. it’s an inter-area path. In square brackets a summary metric -for all links through which a path lies to this network is specified. "via" -prefix defines a router-gateway, i.e. the first router on the way to the -destination (next hop). -**OSPF router routing table** – includes a list of acquired routes to all -accessible ABRs and ASBRs. -**OSPF external routing table** – includes a list of acquired routes that are -external to the OSPF process. "E" flag points to the external link metric type -(E1 – metric type 1, E2 – metric type 2). External link metric is printed in -the "<metric of the router which advertised the link>/<link metric>" format. - -.. opcmd:: show ip ospf border-routers - - This command displays a table of paths to area boundary and autonomous - system boundary routers. - -.. opcmd:: show ip ospf database - - This command displays a summary table with a database contents (LSA). - -.. code-block:: none - - OSPF Router with ID (10.0.13.1) - - Router Link States (Area 0.0.0.0) - - Link ID ADV Router Age Seq# CkSum Link count - 10.0.13.1 10.0.13.1 984 0x80000005 0xd915 1 - 10.0.23.3 10.0.23.3 1186 0x80000008 0xfe62 2 - 10.0.34.4 10.0.34.4 1063 0x80000004 0x4e3f 1 - - Net Link States (Area 0.0.0.0) - - Link ID ADV Router Age Seq# CkSum - 10.0.13.1 10.0.13.1 994 0x80000003 0x30bb - 10.0.34.4 10.0.34.4 1188 0x80000001 0x9411 - - Summary Link States (Area 0.0.0.0) - - Link ID ADV Router Age Seq# CkSum Route - 10.0.12.0 10.0.23.3 1608 0x80000001 0x6ab6 10.0.12.0/24 - 10.0.23.0 10.0.23.3 981 0x80000003 0xe232 10.0.23.0/24 - - AS External Link States - - Link ID ADV Router Age Seq# CkSum Route - 172.16.0.0 10.0.34.4 1063 0x80000001 0xc40d E2 172.16.0.0/24 [0x0] - -.. opcmd:: show ip ospf database <type> [A.B.C.D] - [adv-router <A.B.C.D>|self-originate] - - This command displays a database contents for a specific link advertisement - type. - - The type can be the following: - asbr-summary, external, network, nssa-external, opaque-area, opaque-as, - opaque-link, router, summary. - - [A.B.C.D] – link-state-id. With this specified the command displays portion - of the network environment that is being described by the advertisement. - The value entered depends on the advertisement’s LS type. It must be - entered in the form of an IP address. - - :cfgcmd:`adv-router <A.B.C.D>` – router id, which link advertisements need - to be reviewed. - - :cfgcmd:`self-originate` displays only self-originated LSAs from the local - router. - -.. code-block:: none - - OSPF Router with ID (10.0.13.1) - - Router Link States (Area 0.0.0.0) - - LS age: 1213 - Options: 0x2 : *|-|-|-|-|-|E|- - LS Flags: 0x3 - Flags: 0x0 - LS Type: router-LSA - Link State ID: 10.0.13.1 - Advertising Router: 10.0.13.1 - LS Seq Number: 80000009 - Checksum: 0xd119 - Length: 36 - - Number of Links: 1 - - Link connected to: a Transit Network - (Link ID) Designated Router address: 10.0.13.1 - (Link Data) Router Interface address: 10.0.13.1 - Number of TOS metrics: 0 - TOS 0 Metric: 1 - -.. opcmd:: show ip ospf database max-age - - This command displays LSAs in MaxAge list. - - -Examples --------- - - -Enable OSPF -^^^^^^^^^^^ - -**Node 1** - -.. code-block:: none - - set interfaces loopback lo address 10.1.1.1/32 - set interfaces ethernet eth0 address 192.168.0.1/24 - set protocols ospf area 0 network 192.168.0.0/24 - set protocols ospf area 0 network 10.1.1.1/32 - set protocols ospf parameters router-id 10.1.1.1 - -**Node 2** - -.. code-block:: none - - set interfaces loopback lo address 10.1.1.2/32 - set interfaces ethernet eth0 address 192.168.0.2/24 - set protocols ospf area 0 network 192.168.0.0/24 - set protocols ospf area 0 network 10.1.1.2/32 - set protocols ospf parameters router-id 10.1.1.2 - - - -Here's the neighbors up: - -.. code-block:: none - - Node-1@vyos:~$ show ip ospf neighbor - - Neighbor ID Pri State Up Time Dead Time Address Interface RXmtL RqstL DBsmL - 10.1.1.2 1 Full/DR 3m43s 36.094s 192.168.0.2 eth0:192.168.0.1 0 0 0 - - - - Node-2@vyos:~$ show ip ospf neighbor - - Neighbor ID Pri State Up Time Dead Time Address Interface RXmtL RqstL DBsmL - 10.1.1.1 1 Full/Backup 3m47s 31.736s 192.168.0.1 eth0:192.168.0.2 0 0 0 - -Here's the routes: - -.. code-block:: none - - Node-1@vyos:~$ show ip route ospf - Codes: K - kernel route, C - connected, S - static, R - RIP, - O - OSPF, I - IS-IS, B - BGP, E - EIGRP, N - NHRP, - T - Table, v - VNC, V - VNC-Direct, A - Babel, F - PBR, - f - OpenFabric, - > - selected route, * - FIB route, q - queued, r - rejected, b - backup - t - trapped, o - offload failure - - O 10.1.1.1/32 [110/0] is directly connected, lo, weight 1, 00:00:14 - O>* 10.1.1.2/32 [110/1] via 192.168.0.2, eth0, weight 1, 00:00:07 - O 192.168.0.0/24 [110/1] is directly connected, eth0, weight 1, 00:03:32 - - Node-2@vyos:~$ show ip route ospf - Codes: K - kernel route, C - connected, S - static, R - RIP, - O - OSPF, I - IS-IS, B - BGP, E - EIGRP, N - NHRP, - T - Table, v - VNC, V - VNC-Direct, A - Babel, F - PBR, - f - OpenFabric, - > - selected route, * - FIB route, q - queued, r - rejected, b - backup - t - trapped, o - offload failure - - O>* 10.1.1.1/32 [110/1] via 192.168.0.1, eth0, weight 1, 00:00:11 - O 10.1.1.2/32 [110/0] is directly connected, lo, weight 1, 00:00:04 - O 192.168.0.0/24 [110/1] is directly connected, eth0, weight 1, 00:03:18 - - - - - -Enable OSPF with route redistribution of the loopback and default originate: -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -**Node 1** - -.. code-block:: none - - set interfaces loopback lo address 10.1.1.1/32 - set protocols ospf area 0 network 192.168.0.0/24 - set protocols ospf default-information originate always - set protocols ospf default-information originate metric 10 - set protocols ospf default-information originate metric-type 2 - set protocols ospf log-adjacency-changes - set protocols ospf parameters router-id 10.1.1.1 - set protocols ospf redistribute connected metric-type 2 - set protocols ospf redistribute connected route-map CONNECT - - set policy route-map CONNECT rule 10 action permit - set policy route-map CONNECT rule 10 match interface lo - -**Node 2** - -.. code-block:: none - - set interfaces loopback lo address 10.2.2.2/32 - set protocols ospf area 0 network 192.168.0.0/24 - set protocols ospf log-adjacency-changes - set protocols ospf parameters router-id 10.2.2.2 - set protocols ospf redistribute connected metric-type 2 - set protocols ospf redistribute connected route-map CONNECT - - set policy route-map CONNECT rule 10 action permit - set policy route-map CONNECT rule 10 match interface lo - - -Enable OSPF and IGP-LDP synchronization: -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -**Node 1:** - -.. code-block:: none - - set interfaces loopback lo address 10.1.1.1/32 - set interfaces ethernet eth0 address 192.168.0.1/24 - - set protocols ospf area 0 network '192.168.0.0/24' - set protocols ospf area 0 network '10.1.1.1/32' - set protocols ospf parameters router-id '10.1.1.1' - set protocols ospf ldp-sync - - set protocols mpls interface eth0 - set protocols mpls ldp discovery transport-ipv4-address 10.1.1.1 - set protocols mpls ldp interface lo - set protocols mpls ldp interface eth0 - set protocols mpls ldp parameters transport-prefer-ipv4 - set protocols mpls ldp router-id 10.1.1.1 - - -This gives us IGP-LDP synchronization for all non-loopback interfaces with -a holddown timer of zero seconds: - - -.. code-block:: none - - Node-1@vyos:~$ show ip ospf mpls ldp-sync - eth0 - LDP-IGP Synchronization enabled: yes - Holddown timer in seconds: 0 - State: Sync achieved - - - -Enable OSPF with Segment Routing (Experimental): -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -**Node 1** - -.. code-block:: none - - set interfaces loopback lo address 10.1.1.1/32 - set interfaces ethernet eth0 address 192.168.0.1/24 - - set protocols ospf area 0 network '192.168.0.0/24' - set protocols ospf area 0 network '10.1.1.1/32' - set protocols ospf parameters opaque-lsa - set protocols ospf parameters router-id '10.1.1.1' - set protocols ospf segment-routing global-block high-label-value '1100' - set protocols ospf segment-routing global-block low-label-value '1000' - set protocols ospf segment-routing prefix 10.1.1.1/32 index explicit-null - set protocols ospf segment-routing prefix 10.1.1.1/32 index value '1' - -**Node 2** - -.. code-block:: none - - set interfaces loopback lo address 10.1.1.2/32 - set interfaces ethernet eth0 address 192.168.0.2/24 - - set protocols ospf area 0 network '192.168.0.0/24' - set protocols ospf area 0 network '10.1.1.2/32' - set protocols ospf parameters opaque-lsa - set protocols ospf parameters router-id '10.1.1.2' - set protocols ospf segment-routing global-block high-label-value '1100' - set protocols ospf segment-routing global-block low-label-value '1000' - set protocols ospf segment-routing prefix 10.1.1.2/32 index explicit-null - set protocols ospf segment-routing prefix 10.1.1.2/32 index value '2' - - -This gives us MPLS segment routing enabled and labels for far end loopbacks: - -.. code-block:: none - - Node-1@vyos:~$ show mpls table - Inbound Label Type Nexthop Outbound Label - ----------------------------------------------------------- - 1002 SR (OSPF) 192.168.0.2 IPv4 Explicit Null <-- Node-2 loopback learned on Node-1 - 15000 SR (OSPF) 192.168.0.2 implicit-null - 15001 SR (OSPF) 192.168.0.2 implicit-null - - Node-2@vyos:~$ show mpls table - Inbound Label Type Nexthop Outbound Label - ----------------------------------------------------------- - 1001 SR (OSPF) 192.168.0.1 IPv4 Explicit Null <-- Node-1 loopback learned on Node-2 - 15000 SR (OSPF) 192.168.0.1 implicit-null - 15001 SR (OSPF) 192.168.0.1 implicit-null - -Here is the routing tables showing the MPLS segment routing label operations: - -.. code-block:: none - - Node-1@vyos:~$ show ip route ospf - Codes: K - kernel route, C - connected, S - static, R - RIP, - O - OSPF, I - IS-IS, B - BGP, E - EIGRP, N - NHRP, - T - Table, v - VNC, V - VNC-Direct, A - Babel, F - PBR, - f - OpenFabric, - > - selected route, * - FIB route, q - queued, r - rejected, b - backup - t - trapped, o - offload failure - - O 10.1.1.1/32 [110/0] is directly connected, lo, weight 1, 00:03:43 - O>* 10.1.1.2/32 [110/1] via 192.168.0.2, eth0, label IPv4 Explicit Null, weight 1, 00:03:32 - O 192.168.0.0/24 [110/1] is directly connected, eth0, weight 1, 00:03:43 - - Node-2@vyos:~$ show ip route ospf - Codes: K - kernel route, C - connected, S - static, R - RIP, - O - OSPF, I - IS-IS, B - BGP, E - EIGRP, N - NHRP, - T - Table, v - VNC, V - VNC-Direct, A - Babel, F - PBR, - f - OpenFabric, - > - selected route, * - FIB route, q - queued, r - rejected, b - backup - t - trapped, o - offload failure - - O>* 10.1.1.1/32 [110/1] via 192.168.0.1, eth0, label IPv4 Explicit Null, weight 1, 00:03:36 - O 10.1.1.2/32 [110/0] is directly connected, lo, weight 1, 00:03:51 - O 192.168.0.0/24 [110/1] is directly connected, eth0, weight 1, 00:03:51 - - - - -.. _routing-ospfv3: - -************* -OSPFv3 (IPv6) -************* - -.. _ospf:v3_configuration: - -Configuration -============= - -.. _ospf:v3_general: - -General -------- - -VyOS does not have a special command to start the OSPFv3 process. The OSPFv3 -process starts when the first ospf enabled interface is configured. - -.. cfgcmd:: set protocols ospfv3 interface <interface> area <number> - - This command specifies the OSPFv3 enabled interface. This command is also - used to enable the OSPF process. The area number can be specified in - decimal notation in the range from 0 to 4294967295. Or it can be specified - in dotted decimal notation similar to ip address. - -.. cfgcmd:: set protocols ospfv3 parameters router-id <rid> - - This command sets the router-ID of the OSPFv3 process. The router-ID may be - an IP address of the router, but need not be – it can be any arbitrary - 32bit number. However it MUST be unique within the entire OSPFv3 domain to - the OSPFv3 speaker – bad things will happen if multiple OSPFv3 speakers are - configured with the same router-ID! - - -.. _ospf:v3_optional: - -Optional --------- - -.. cfgcmd:: set protocols ospfv3 distance global <distance> - - This command change distance value of OSPFv3 globally. - The distance range is 1 to 255. - -.. cfgcmd:: set protocols ospfv3 distance ospfv3 - <external|inter-area|intra-area> <distance> - - This command change distance value of OSPFv3. The arguments are the - distance values for external routes, inter-area routes and intra-area - routes respectively. The distance range is 1 to 255. - -.. _ospf:v3_area_configuration: - -Area Configuration ------------------- - -.. cfgcmd:: set protocols ospfv3 area <number> range <prefix> - - This command summarizes intra area paths from specified area into one - Type-3 Inter-Area Prefix LSA announced to other areas. This command can be - used only in ABR. - -.. cfgcmd:: set protocols ospfv3 area <number> range <prefix> not-advertise - - This command instead of summarizing intra area paths filter them - i.e. - intra area paths from this range are not advertised into other areas. This - command makes sense in ABR only. - -.. _ospf:v3_interface_config: - -Interface Configuration ------------------------ - -.. cfgcmd:: set protocols ospfv3 interface <interface> ipv6 cost <number> - - This command sets link cost for the specified interface. The cost value is - set to router-LSA’s metric field and used for SPF calculation. The cost - range is 1 to 65535. - -.. cfgcmd:: set protocols ospfv3 interface <interface> dead-interval <number> - - Set number of seconds for router Dead Interval timer value used for Wait - Timer and Inactivity Timer. This value must be the same for all routers - attached to a common network. The default value is 40 seconds. The - interval range is 1 to 65535. - -.. cfgcmd:: set protocols ospfv3 interface <interface> hello-interval - <number> - - Set number of seconds for Hello Interval timer value. Setting this value, - Hello packet will be sent every timer value seconds on the specified - interface. This value must be the same for all routers attached to a - common network. The default value is 10 seconds. The interval range is 1 - to 65535. - -.. cfgcmd:: set protocols ospfv3 interface <interface> mtu-ignore - - This command disables check of the MTU value in the OSPF DBD packets. - Thus, use of this command allows the OSPF adjacency to reach the FULL - state even though there is an interface MTU mismatch between two OSPF - routers. - -.. cfgcmd:: set protocols ospfv3 interface <interface> network <type> - - This command allows to specify the distribution type for the network - connected to this interface: - - **broadcast** – broadcast IP addresses distribution. - **point-to-point** – address distribution in point-to-point networks. - -.. cfgcmd:: set protocols ospfv3 interface <interface> priority <number> - - This command sets Router Priority integer value. The router with the - highest priority will be more eligible to become Designated Router. - Setting the value to 0, makes the router ineligible to become Designated - Router. The default value is 1. The interval range is 0 to 255. - -.. cfgcmd:: set protocols ospfv3 interface <interface> passive - - This command specifies interface as passive. Passive interface advertises - its address, but does not run the OSPF protocol (adjacencies are not formed - and hello packets are not generated). - -.. cfgcmd:: set protocols ospfv3 interface <interface> retransmit-interval - <number> - - This command sets number of seconds for RxmtInterval timer value. This - value is used when retransmitting Database Description and Link State - Request packets if acknowledge was not received. The default value is 5 - seconds. The interval range is 3 to 65535. - -.. cfgcmd:: set protocols ospfv3 interface <interface> transmit-delay - <number> - - This command sets number of seconds for InfTransDelay value. It allows to - set and adjust for each interface the delay interval before starting the - synchronizing process of the router's database with all neighbors. The - default value is 1 seconds. The interval range is 3 to 65535. - -.. _ospf:v3_graceful_restart: - -Graceful Restart ----------------- - -.. cfgcmd:: set protocols ospfv3 graceful-restart [grace-period (1-1800)] - - Configure Graceful Restart :rfc:`3623` restarting support. When enabled, - the default grace period is 120 seconds. - - To perform a graceful shutdown, the FRR ``graceful-restart prepare ip - ospf`` EXEC-level command needs to be issued before restarting the - ospfd daemon. - -.. cfgcmd:: set protocols ospfv3 graceful-restart helper enable [router-id A.B.C.D] - - Configure Graceful Restart :rfc:`3623` helper support. By default, helper support - is disabled for all neighbours. This config enables/disables helper support - on this router for all neighbours. - - To enable/disable helper support for a specific neighbour, the router-id - (A.B.C.D) has to be specified. - -.. cfgcmd:: set protocols ospfv3 graceful-restart helper lsa-check-disable - - By default `strict-lsa-checking` is configured then the helper will abort - the Graceful Restart when a LSA change occurs which affects the restarting - router. - - This command disables it. - -.. cfgcmd:: set protocols ospfv3 graceful-restart helper supported-grace-time - - Supports as HELPER for configured grace period. - -.. cfgcmd:: set protocols ospfv3 graceful-restart helper planned-only - - It helps to support as HELPER only for planned restarts. - - By default, it supports both planned and unplanned outages. - -.. _ospf:v3_redistribution_config: - -Redistribution Configuration ----------------------------- - -.. cfgcmd:: set protocols ospfv3 redistribute <route source> - - This command redistributes routing information from the given route source - to the OSPFv3 process. There are five modes available for route source: - bgp, connected, kernel, ripng, static. - -.. cfgcmd:: set protocols ospf redistribute <route source> route-map <name> - - This command allows to use route map to filter redistributed routes from - given route source. There are five modes available for route source: bgp, - connected, kernel, ripng, static. - -.. _ospf:v3_op_cmd: - -Operational Mode Commands -------------------------- - -.. opcmd:: show ipv6 ospfv3 neighbor - - This command displays the neighbors status. - -.. opcmd:: show ipv6 ospfv3 neighbor detail - - This command displays the neighbors information in a detailed form, not - just a summary table. - -.. opcmd:: show ipv6 ospfv3 neighbor drchoice - - This command displays the neighbor DR choice information. - -.. opcmd:: show ipv6 ospfv3 interface [prefix]|[<interface> [prefix]] - - This command displays state and configuration of OSPF the specified - interface, or all interfaces if no interface is given. Whith the argument - :cfgcmd:`prefix` this command shows connected prefixes to advertise. - -.. opcmd:: show ipv6 ospfv3 route - - This command displays the OSPF routing table, as determined by the most - recent SPF calculation. - -.. opcmd:: show ipv6 ospfv3 border-routers - - This command displays a table of paths to area boundary and autonomous - system boundary routers. - -.. opcmd:: show ipv6 ospfv3 database - - This command displays a summary table with a database contents (LSA). - -.. opcmd:: show ipv6 ospfv3 database <type> [A.B.C.D] - [adv-router <A.B.C.D>|self-originate] - - This command displays a database contents for a specific link - advertisement type. - -.. opcmd:: show ipv6 ospfv3 redistribute - - This command displays external information redistributed into OSPFv3 - -.. _ospf:v3_config_example: - -Configuration Example ---------------------- - -A typical configuration using 2 nodes. - -**Node 1:** - -.. code-block:: none - - set protocols ospfv3 interface eth1 area 0.0.0.0 - set protocols ospfv3 area 0.0.0.0 range 2001:db8:1::/64 - set protocols ospfv3 parameters router-id 192.168.1.1 - set protocols ospfv3 redistribute connected - -**Node 2:** - -.. code-block:: none - - set protocols ospfv3 interface eth1 area 0.0.0.0 - set protocols ospfv3 area 0.0.0.0 range 2001:db8:2::/64 - set protocols ospfv3 parameters router-id 192.168.2.1 - set protocols ospfv3 redistribute connected - -**To see the redistributed routes:** - -.. code-block:: none - - show ipv6 ospfv3 redistribute - -Cost calculation wireguard interfaces is unreliable as ospfv3 uses the link speed to calculate the link cost. -You might therefore want to set the link cost to a fixed value on WireGuard tunnels. - -Example configuration for WireGuard interfaces: - -**Node 1** - -.. code-block:: none - - set interfaces wireguard wg01 peer ospf02 allowed-ips '::/0' - set interfaces wireguard wg01 peer ospf02 endpoint '10.1.1.101:12345' - set interfaces wireguard wg01 peer ospf02 pubkey 'ie3...=' - set interfaces wireguard wg01 port '12345' - set protocols ospfv3 parameters router-id 192.168.1.1 - set protocols ospfv3 interface 'wg01' area 0.0.0.0 - set protocols ospfv3 interface 'wg01' cost 10 - set protocols ospfv3 interface 'lo' area 0.0.0.0 - -**Node 2** - -.. code-block:: none - - set interfaces wireguard wg01 peer ospf01 allowed-ips '::/0' - set interfaces wireguard wg01 peer ospf01 endpoint '10.1.1.100:12345' - set interfaces wireguard wg01 peer ospf01 pubkey 'NHI...=' - set interfaces wireguard wg01 port '12345' - set protocols ospfv3 parameters router-id 192.168.1.2 - set protocols ospfv3 interface 'wg01' area 0.0.0.0 - set protocols ospfv3 interface 'wg01' cost 10 - set protocols ospfv3 interface 'lo' area 0.0.0.0 - -**Status** - -.. code-block:: none - - vyos@ospf01:~$ sh ipv6 ospfv3 neighbor - Neighbor ID Pri DeadTime State/IfState Duration I/F[State] - 192.168.0.2 1 00:00:37 Full/PointToPoint 00:18:03 wg01[PointToPoint] - - vyos@ospf02# run sh ipv6 ospfv3 neighbor - Neighbor ID Pri DeadTime State/IfState Duration I/F[State] - 192.168.0.1 1 00:00:39 Full/PointToPoint 00:19:44 wg01[PointToPoint] - diff --git a/docs/configuration/protocols/rst-pim.rst b/docs/configuration/protocols/rst-pim.rst deleted file mode 100644 index f3f388ba..00000000 --- a/docs/configuration/protocols/rst-pim.rst +++ /dev/null @@ -1,281 +0,0 @@ -:lastproofread: 2023-11-13 - -.. _pim: - -#################################### -PIM – Protocol Independent Multicast -#################################### - -VyOS supports :abbr:`PIM-SM (PIM Sparse Mode)` as well as -:abbr:`IGMP (Internet Group Management Protocol)` v2 and v3 - -:abbr:`PIM (Protocol Independent Multicast)` must be configured in every -interface of every participating router. Every router must also have the -location of the Rendevouz Point manually configured. Then, unidirectional -shared trees rooted at the Rendevouz Point will automatically be built -for multicast distribution. - -Traffic from multicast sources will go to the Rendezvous Point, and -receivers will pull it from a shared tree using :abbr:`IGMP (Internet -Group Management Protocol)`. - -Multicast receivers will talk IGMP to their local router, so, besides -having PIM configured in every router, IGMP must also be configured in -any router where there could be a multicast receiver locally connected. - -VyOS supports both IGMP version 2 and version 3 (which allows -source-specific multicast). - -************************ -PIM-SM - PIM Sparse Mode -************************ - -.. cfgcmd:: set protocols pim ecmp - - If PIM has the a choice of ECMP nexthops for a particular - :abbr:`RPF (Reverse Path Forwarding)`, PIM will cause S,G flows to be - spread out amongst the nexthops. If this command is not specified then - the first nexthop found will be used. - -.. cfgcmd:: set protocols pim ecmp rebalance - - If PIM is using ECMP and an interface goes down, cause PIM to rebalance all - S,G flows across the remaining nexthops. If this command is not configured - PIM only modifies those S,G flows that were using the interface that went - down. - -.. cfgcmd:: set protocols pim join-prune-interval <n> - - Modify the join/prune interval that PIM uses to the new value. Time is - specified in seconds. - - The default time is 60 seconds. - - If you enter a value smaller than 60 seconds be aware that this can and - will affect convergence at scale. - -.. cfgcmd:: set protocols pim keep-alive-timer <n> - - Modify the time out value for a S,G flow from 1-65535 seconds. If choosing - a value below 31 seconds be aware that some hardware platforms cannot see - data flowing in better than 30 second chunks. - -.. cfgcmd:: set protocols pim packets <n> - - When processing packets from a neighbor process the number of packets - incoming at one time before moving on to the next task. - - The default value is 3 packets. - - This command is only useful at scale when you can possibly have a large - number of PIM control packets flowing. - -.. stop_vyoslinter - -.. cfgcmd:: set protocols pim register-accept-list <prefix-list> - - When PIM receives a register packet the source of the packet will be - compared to the prefix-list specified, and if a permit is received - normal processing continues. If a deny is returned for the source - address of the register packet a register stop message is sent to - the source. - -.. start_vyoslinter - -.. cfgcmd:: set protocols pim register-suppress-time <n> - - Modify the time that pim will register suppress a FHR will send register - notifications to the kernel. - -.. cfgcmd:: set protocols pim rp <address> group <group> - - In order to use PIM, it is necessary to configure a - :abbr:`RP (Rendezvous Point)` for join messages to be sent to. - Currently the only methodology to do this is via static rendezvous - point commands. - - All routers in the PIM network must agree on these values. - - The first ip address is the RP's address and the second value is the matching - prefix of group ranges covered. - -.. cfgcmd:: set protocols pim rp keep-alive-timer <n> - - Modify the time out value for a S,G flow from 1-65535 seconds at - :abbr:`RP (Rendezvous Point)`. The normal keepalive period for the KAT(S,G) - defaults to 210 seconds. However, at the :abbr:`RP (Rendezvous Point)`, the - keepalive period must be at least the Register_Suppression_Time, or the RP - may time out the (S,G) state before the next Null-Register arrives. - Thus, the KAT(S,G) is set to max(Keepalive_Period, RP_Keepalive_Period) - when a Register-Stop is sent. - - If choosing a value below 31 seconds be aware that some hardware platforms - cannot see data flowing in better than 30 second chunks. - - See :rfc:`7761#section-4.1` for details. - -.. cfgcmd:: set protocols pim no-v6-secondary - - When sending PIM hello packets tell PIM to not send any v6 secondary - addresses on the interface. This information is used to allow PIM to use v6 - nexthops in it's decision for :abbr:`RPF (Reverse Path Forwarding)` lookup - if this option is not set (default). - -.. stop_vyoslinter - -.. cfgcmd:: set protocols pim spt-switchover infinity-and-beyond [prefix-list <list>] - - On the last hop router if it is desired to not switch over to the - SPT tree configure this command. - - Optional parameter prefix-list can be use to control which groups - to switch or not switch. If a group is PERMIT as per the - prefix-list, then the SPT switchover does not happen for it and if - it is DENY, then the SPT switchover happens. - -.. start_vyoslinter - -.. cfgcmd:: set protocols pim ssm prefix-list <list> - - Specify a range of group addresses via a prefix-list that forces PIM to never - do :abbr:`SSM (Source-Specific Multicast)` over. - -Interface specific commands -=========================== - -.. cfgcmd:: set protocols pim interface <interface> bfd [profile <name>] - - Automatically create BFD session for each RIP peer discovered in this - interface. When the BFD session monitor signalize that the link is down - the RIP peer is removed and all the learned routes associated with that - peer are removed. - - If optional profile parameter is used, select a BFD profile for the BFD - sessions created via this interface. - -.. cfgcmd:: set protocols pim interface <interface> dr-priority <n> - - Set the :abbr:`DR (Designated Router)` Priority for the interface. - This command is useful to allow the user to influence what node becomes - the DR for a LAN segment. - -.. cfgcmd:: set protocols pim interface <interface> hello <n> - - Set the PIM hello and hold interval for a interface. - -.. cfgcmd:: set protocols pim interface <interface> no-bsm - - Tell PIM that we would not like to use this interface to process - bootstrap messages. - -.. cfgcmd:: set protocols pim interface <interface> no-unicast-bsm - - Tell PIM that we would not like to use this interface to process - unicast bootstrap messages. - -.. cfgcmd:: set protocols pim interface <interface> passive - - Disable sending and receiving PIM control packets on the interface. - - .. cfgcmd:: set protocols pim interface <interface> source-address <ip-address> - - If you have multiple addresses configured on a particular interface and would - like PIM to use a specific source address associated with that interface. - -****************************************** -IGMP - Internet Group Management Protocol) -****************************************** - -.. cfgcmd:: set protocols pim igmp watermark-warning <n> - - Configure watermark warning generation for an IGMP group limit. Generates - warning once the configured group limit is reached while adding new groups. - -.. _pim:igmp_interface_commands: - -Interface specific commands -=========================== - -.. cfgcmd:: set protocols pim interface <interface> igmp - join <multicast-address> source-address <IP-address> - - Use this command to allow the selected interface to join a multicast - group defining the multicast address you want to join and the source - IP address too. - -.. cfgcmd:: set protocols pim interface <interface> igmp - query-interval <seconds> - - Use this command to configure in the selected interface the IGMP - host query interval (1-1800) in seconds that PIM will use. - -.. cfgcmd:: set protocols pim interface <interface> igmp - query-max-response-time <n> - - Use this command to configure in the selected interface the IGMP - query response timeout value (10-250) in deciseconds. If a report is - not returned in the specified time, it will be assumed the (S,G) or - (\*,G) state :rfc:`7761#section-4.1` has timed out. - -.. stop_vyoslinter - -.. cfgcmd:: set protocols pim interface <interface> igmp version <version-number> - - Use this command to define in the selected interface whether you - choose IGMP version 2 or 3. - - The default value is 3. - -.. start_vyoslinter - -Example -------- - -In the following example we can see a basic multicast setup: - -.. image:: /_static/images/multicast-basic.* - :width: 90% - :align: center - :alt: Network Topology Diagram - - - -**Router 1** - -.. code-block:: none - - set interfaces ethernet eth2 address '172.16.0.2/24' - set interfaces ethernet eth1 address '100.64.0.1/24' - set protocols ospf area 0 network '172.16.0.0/24' - set protocols ospf area 0 network '100.64.0.0/24' - set protocols igmp interface eth1 - set protocols pim interface eth1 - set protocols pim interface eth2 - set protocols pim rp address 172.16.255.1 group '224.0.0.0/4' - -**Router 3** - -.. code-block:: none - - set interfaces dummy dum0 address '172.16.255.1/24' - set interfaces ethernet eth0 address '172.16.0.1/24' - set interfaces ethernet eth1 address '172.16.1.1/24' - set protocols ospf area 0 network '172.16.0.0/24' - set protocols ospf area 0 network '172.16.255.0/24' - set protocols ospf area 0 network '172.16.1.0/24' - set protocols pim interface dum0 - set protocols pim interface eth0 - set protocols pim interface eth1 - set protocols pim rp address 172.16.255.1 group '224.0.0.0/4' - -**Router 2** - -.. code-block:: none - - set interfaces ethernet eth1 address '10.0.0.1/24' - set interfaces ethernet eth2 address '172.16.1.2/24' - set protocols ospf area 0 network '10.0.0.0/24' - set protocols ospf area 0 network '172.16.1.0/24' - set protocols pim interface eth1 - set protocols pim interface eth2 - set protocols pim rp address 172.16.255.1 group '224.0.0.0/4' diff --git a/docs/configuration/protocols/rst-pim6.rst b/docs/configuration/protocols/rst-pim6.rst deleted file mode 100644 index 2b2276a7..00000000 --- a/docs/configuration/protocols/rst-pim6.rst +++ /dev/null @@ -1,94 +0,0 @@ -.. _pim6: - -############################################## -PIM6 - Protocol Independent Multicast for IPv6 -############################################## - -VyOS facilitates IPv6 Multicast by supporting **PIMv6** and **MLD**. - -PIMv6 (Protocol Independent Multicast for IPv6) must be configured in every -interface of every participating router. Every router must also have the -location of the Rendevouz Point manually configured. -Then, unidirectional shared trees rooted at the Rendevouz Point will -automatically be built for multicast distribution. - -Traffic from multicast sources will go to the Rendezvous Point, and receivers -will pull it from a shared tree using MLD (Multicast Listener Discovery). - -Multicast receivers will talk MLD to their local router, so, besides having -PIMv6 configured in every router, MLD must also be configured in any router -where there could be a multicast receiver locally connected. - -VyOS supports both MLD version 1 and version 2 -(which allows source-specific multicast). - -Basic commands -============== -These are the commands for a basic setup. - -.. cfgcmd:: set protocols pim6 interface <interface-name> - - Use this command to enable PIMv6 in the selected interface so that it - can communicate with PIMv6 neighbors. This command also enables MLD reports - and query on the interface unless :cfgcmd:`mld disable` is configured. - -.. cfgcmd:: set protocols pim6 interface <interface-name> mld disable - - Disable MLD reports and query on the interface. - - -Tuning commands -=============== -You can also tune multicast with the following commands. - - -.. cfgcmd:: set protocols pim6 interface <interface-name> mld interval <seconds> - - Use this command to configure in the selected interface the MLD - host query interval (1-65535) in seconds that PIM will use. - The default value is 125 seconds. - -.. cfgcmd:: set protocols pim6 interface <interface-name> mld join <multicast-address> - - Use this command to allow the selected interface to join a multicast group. - -.. cfgcmd:: set protocols pim6 interface <interface-name> mld join <multicast-address> source <source-address> - - Use this command to allow the selected interface to join a source-specific multicast - group. - -.. cfgcmd:: set protocols pim6 interface <interface-name> mld last-member-query-count <count> - - Set the MLD last member query count. The default value is 2. - -.. cfgcmd:: set protocols pim6 interface <interface-name> mld last-member-query-interval <milliseconds> - - Set the MLD last member query interval in milliseconds (100-6553500). The default value is 1000 milliseconds. - -.. cfgcmd:: set protocols pim6 interface <interface-name> mld max-response-time <milliseconds> - - Set the MLD query response timeout in milliseconds (100-6553500). The default value is 10000 milliseconds. - -.. cfgcmd:: set protocols pim6 interface <interface-name> mld version <version-number> - - Set the MLD version used on this interface. The default value is 2. - -********************* -Configuration Example -********************* - -To enable MLD reports and query on interfaces `eth0` and `eth1`: - -.. code-block:: none - - set protocols pim6 interface eth0 - set protocols pim6 interface eth1 - -The following configuration explicitly joins multicast group `ff15::1234` on interface `eth1` -and source-specific multicast group `ff15::5678` with source address `2001:db8::1` on interface -`eth1`: - -.. code-block:: none - - set protocols pim6 interface eth0 mld join ff15::1234 - set protocols pim6 interface eth1 mld join ff15::5678 source 2001:db8::1 diff --git a/docs/configuration/protocols/rst-rip.rst b/docs/configuration/protocols/rst-rip.rst deleted file mode 100644 index fd20a90c..00000000 --- a/docs/configuration/protocols/rst-rip.rst +++ /dev/null @@ -1,257 +0,0 @@ -:lastproofread: 2021-10-04 - -.. _rip: - -### -RIP -### - -:abbr:`RIP (Routing Information Protocol)` is a widely deployed interior gateway -protocol. RIP was developed in the 1970s at Xerox Labs as part of the XNS -routing protocol. RIP is a distance-vector protocol and is based on the -Bellman-Ford algorithms. As a distance-vector protocol, RIP router send updates -to its neighbors periodically, thus allowing the convergence to a known -topology. In each update, the distance to any given network will be broadcast -to its neighboring router. - -Supported versions of RIP are: - - - RIPv1 as described in :rfc:`1058` - - RIPv2 as described in :rfc:`2453` - -General Configuration ---------------------- - -.. cfgcmd:: set protocols rip network <A.B.C.D/M> - - This command enables RIP and sets the RIP enable interface by NETWORK. - The interfaces which have addresses matching with NETWORK are enabled. - -.. cfgcmd:: set protocols rip interface <interface> - - This command specifies a RIP enabled interface by interface name. Both - the sending and receiving of RIP packets will be enabled on the port - specified in this command. - -.. cfgcmd:: set protocols rip neighbor <A.B.C.D> - - This command specifies a RIP neighbor. When a neighbor doesn’t understand - multicast, this command is used to specify neighbors. In some cases, not - all routers will be able to understand multicasting, where packets are - sent to a network or a group of addresses. In a situation where a neighbor - cannot process multicast packets, it is necessary to establish a direct - link between routers. - -.. cfgcmd:: set protocols rip passive-interface interface <interface> - - This command sets the specified interface to passive mode. On passive mode - interface, all receiving packets are processed as normal and VyOS does not - send either multicast or unicast RIP packets except to RIP neighbors - specified with neighbor command. - -.. cfgcmd:: set protocols rip passive-interface interface default - - This command specifies all interfaces to passive mode. - - -Optional Configuration ----------------------- - -.. cfgcmd:: set protocols rip default-distance <distance> - - This command change the distance value of RIP. The distance range is 1 to 255. - - .. note:: Routes with a distance of 255 are effectively disabled and not - installed into the kernel. - -.. cfgcmd:: set protocols rip network-distance <A.B.C.D/M> distance <distance> - - This command sets default RIP distance to a specified value when the routes - source IP address matches the specified prefix. - -.. cfgcmd:: set protocols rip network-distance <A.B.C.D/M> access-list <name> - - This command can be used with previous command to sets default RIP distance - to specified value when the route source IP address matches the specified - prefix and the specified access-list. - -.. cfgcmd:: set protocols rip default-information originate - - This command generate a default route into the RIP. - -.. cfgcmd:: set protocols rip distribute-list access-list <in|out> <number> - - This command can be used to filter the RIP path using access lists. - :cfgcmd:`in` and :cfgcmd:`out` this is the direction in which the access - lists are applied. - -.. cfgcmd:: set protocols rip distribute-list interface <interface> access-list <in|out> <number> - - This command allows you apply access lists to a chosen interface to - filter the RIP path. - -.. cfgcmd:: set protocols rip distribute-list prefix-list <in|out> <name> - - This command can be used to filter the RIP path using prefix lists. - :cfgcmd:`in` and :cfgcmd:`out` this is the direction in which the prefix - lists are applied. - -.. cfgcmd:: set protocols rip distribute-list interface <interface> prefix-list <in|out> <name> - - This command allows you apply prefix lists to a chosen interface to - filter the RIP path. - -.. cfgcmd:: set protocols rip route <A.B.C.D/M> - - This command is specific to FRR and VyOS. The route command makes a static - route only inside RIP. This command should be used only by advanced users - who are particularly knowledgeable about the RIP protocol. In most cases, - we recommend creating a static route in VyOS and redistributing it in RIP - using :cfgcmd:`redistribute static`. - -.. cfgcmd:: set protocols rip timers update <seconds> - - This command specifies the update timer. Every update timer seconds, the - RIP process is awakened to send an unsolicited response message containing - the complete routing table to all neighboring RIP routers. The time range - is 5 to 2147483647. The default value is 30 seconds. - -.. cfgcmd:: set protocols rip timers timeout <seconds> - - This command specifies the timeout timer. Upon expiration of the timeout, - the route is no longer valid; however, it is retained in the routing table - for a short time so that neighbors can be notified that the route has been - dropped. The time range is 5 to 2147483647. The default value is 180 - seconds. - -.. cfgcmd:: set protocols rip timers garbage-collection <seconds> - - This command specifies the garbage-collection timer. Upon expiration of - the garbage-collection timer, the route is finally removed from the - routing table. The time range is 5 to 2147483647. The default value is 120 - seconds. - - -Redistribution Configuration ----------------------------- - -.. cfgcmd:: set protocols rip redistribute <route source> - - This command redistributes routing information from the given route source - into the RIP tables. There are five modes available for route source: bgp, - connected, kernel, ospf, static. - -.. cfgcmd:: set protocols rip redistribute <route source> metric <metric> - - This command specifies metric for redistributed routes from the given route - source. There are five modes available for route source: bgp, connected, - kernel, ospf, static. The metric range is 1 to 16. - -.. cfgcmd:: set protocols rip redistribute <route source> route-map <name> - - This command allows to use route map to filter redistributed routes from - the given route source. There are five modes available for route source: - bgp, connected, kernel, ospf, static. - -.. cfgcmd:: set protocols rip default-metric <metric> - - This command modifies the default metric (hop count) value for redistributed - routes. The metric range is 1 to 16. The default value is 1. This command - does not affect connected route even if it is redistributed by - :cfgcmd:`redistribute connected`. To modify connected routes metric - value, please use :cfgcmd:`redistribute connected metric`. - - -Interfaces Configuration ------------------------- - -.. cfgcmd:: set interfaces <inttype> <intname> ip rip authentication plaintext-password <text> - - This command sets the interface with RIP simple password authentication. - This command also sets authentication string. The string must be shorter - than 16 characters. - -.. cfgcmd:: set interfaces <inttype> <intname> ip rip authentication md5 <id> password <text> - - This command sets the interface with RIP MD5 authentication. This command - also sets MD5 Key. The key must be shorter than 16 characters. - -.. cfgcmd:: set interfaces <inttype> <intname> ip rip split-horizon disable - - This command disables split-horizon on the interface. By default, VyOS does - not advertise RIP routes out the interface over which they were learned - (split horizon).3 - -.. cfgcmd:: set interfaces <inttype> <intname> ip rip split-horizon poison-reverse - - This command enables poison-reverse on the interface. If both poison reverse - and split horizon are enabled, then VyOS advertises the learned routes - as unreachable over the interface on which the route was learned. - - -Operational Mode Commands -------------------------- - -.. opcmd:: show ip rip - - This command displays RIP routes. - -.. code-block:: none - - Codes: R - RIP, C - connected, S - Static, O - OSPF, B - BGP - Sub-codes: - (n) - normal, (s) - static, (d) - default, (r) - redistribute, - (i) - interface - - Network Next Hop Metric From Tag Time - C(i) 10.0.12.0/24 0.0.0.0 1 self 0 - C(i) 10.0.13.0/24 0.0.0.0 1 self 0 - R(n) 10.0.23.0/24 10.0.12.2 2 10.0.12.2 0 02:53 - -.. opcmd:: show ip rip status - - The command displays current RIP status. It includes RIP timer, filtering, - version, RIP enabled interface and RIP peer information. - -.. code-block:: none - - Routing Protocol is "rip" - Sending updates every 30 seconds with +/-50%, next due in 11 seconds - Timeout after 180 seconds, garbage collect after 120 seconds - Outgoing update filter list for all interface is not set - Incoming update filter list for all interface is not set - Default redistribution metric is 1 - Redistributing: - Default version control: send version 2, receive any version - Interface Send Recv Key-chain - eth0 2 1 2 - eth2 2 1 2 - Routing for Networks: - 10.0.12.0/24 - eth0 - Routing Information Sources: - Gateway BadPackets BadRoutes Distance Last Update - 10.0.12.2 0 0 120 00:00:11 - Distance: (default is 120) - - -Configuration Example ---------------------- - -Simple RIP configuration using 2 nodes and redistributing connected interfaces. - -**Node 1:** - -.. code-block:: none - - set interfaces loopback address 10.1.1.1/32 - set protocols rip network 192.168.0.0/24 - set protocols rip redistribute connected - -**Node 2:** - -.. code-block:: none - - set interfaces loopback address 10.2.2.2/32 - set protocols rip network 192.168.0.0/24 - set protocols rip redistribute connected diff --git a/docs/configuration/protocols/rst-rpki.rst b/docs/configuration/protocols/rst-rpki.rst deleted file mode 100644 index 17557884..00000000 --- a/docs/configuration/protocols/rst-rpki.rst +++ /dev/null @@ -1,211 +0,0 @@ -.. _rpki: - -#### -RPKI -#### - -.. pull-quote:: - - There are two types of Network Admins who deal with BGP, those who have - created an international incident and/or outage, and those who are lying - - -- `tweet by EvilMog`_, 2020-02-21 - -:abbr:`RPKI (Resource Public Key Infrastructure)` is a framework designed to -secure the Internet routing infrastructure. It associates BGP route -announcements with the correct originating :abbr:`ASN (Autonomus System -Number)` which BGP routers can then use to check each route against the -corresponding :abbr:`ROA (Route Origin Authorisation)` for validity. RPKI is -described in :rfc:`6480`. - -A BGP-speaking router like VyOS can retrieve ROA information from RPKI -"Relying Party software" (often just called an "RPKI server" or "RPKI -validator") by using :abbr:`RTR (RPKI to Router)` protocol. There are several -open source implementations to choose from, such as NLNetLabs' Routinator_ -(written in Rust), OpenBSD's rpki-client_ (written in C), and StayRTR_ (written -in Go). The RTR protocol is described in :rfc:`8210`. - -.. tip:: - If you are new to these routing security technologies then there is an - `excellent guide to RPKI`_ by NLnet Labs which will get you up to speed - very quickly. Their documentation explains everything from what RPKI is to - deploying it in production. It also has some - `help and operational guidance`_ including "What can I do about my route - having an Invalid state?" - -*************** -Getting started -*************** - -First you will need to deploy an RPKI validator for your routers to use. NLnet -Labs provides a collection of software_ you can compare and settle on one. -Once your server is running you can start validating announcements. - -Imported prefixes during the validation may have values: - - valid - The prefix and ASN that originated it match a signed ROA. These are - probably trustworthy route announcements. - - invalid - The prefix or prefix length and ASN that originated it doesn't - match any existing ROA. This could be the result of a prefix hijack, or - merely a misconfiguration, but should probably be treated as - untrustworthy route announcements. - - notfound - No ROA exists which covers that prefix. Unfortunately this is the case for - about 40%-50% of the prefixes which were announced to the :abbr:`DFZ - (default-free zone)` at the start of 2024. - -.. note:: - If you are responsible for the global addresses assigned to your - network, please make sure that your prefixes have ROAs associated with them - to avoid being `notfound` by RPKI. For most ASNs this will involve - publishing ROAs via your :abbr:`RIR (Regional Internet Registry)` (RIPE - NCC, APNIC, ARIN, LACNIC, or AFRINIC), and is something you are encouraged - to do whenever you plan to announce addresses into the DFZ. - - Particularly large networks may wish to run their own RPKI certificate - authority and publication server instead of publishing ROAs via their RIR. - This is a subject far beyond the scope of VyOS' documentation. Consider - reading about Krill_ if this is a rabbit hole you need or especially want - to dive down. - -Features of the Current Implementation -====================================== - -In a nutshell, the current implementation provides the following features: - -* The BGP router can connect to one or more RPKI cache servers to receive - validated prefix to origin AS mappings. Advanced failover can be implemented - by server sockets with different preference values. - -* If no connection to an RPKI cache server can be established after a - pre-defined timeout, the router will process routes without prefix origin - validation. It still will try to establish a connection to an RPKI cache - server in the background. - -* By default, enabling RPKI does not change best path selection. In particular, - invalid prefixes will still be considered during best path selection. However, - the router can be configured to ignore all invalid prefixes. - -* Route maps can be configured to match a specific RPKI validation state. This - allows the creation of local policies, which handle BGP routes based on the - outcome of the Prefix Origin Validation. - -* Updates from the RPKI cache servers are directly applied and path selection is - updated accordingly. (Soft reconfiguration must be enabled for this to work). - -************* -Configuration -************* - -.. cfgcmd:: set protocols rpki polling-period <1-86400> - - Define the time interval to update the local cache - - The default value is 300 seconds. - -.. cfgcmd:: set protocols rpki expire-interval <600-172800> - - Set the number of seconds the router waits until the router - expires the cache. - - The default value is 7200 seconds. - -.. cfgcmd:: set protocols rpki retry-interval <1-7200> - - Set the number of seconds the router waits until retrying to connect - to the cache server. - - The default value is 600 seconds. - -.. cfgcmd:: set protocols rpki cache <address> port <port> - - Defined the IPv4, IPv6 or FQDN and port number of the caching RPKI caching - instance which is used. - - This is a mandatory setting. - -.. cfgcmd:: set protocols rpki cache <address> preference <preference> - - Multiple RPKI caching instances can be supplied and they need a preference in - which their result sets are used. - - This is a mandatory setting. - -SSH -=== - -Connections to the RPKI caching server can not only be established by TCP using -the RTR protocol but you can also rely on a secure SSH session to the server. -This provides transport integrity and confidentiality and it is a good idea if -your validation software supports it. To enable SSH, first you need to create -an SSH client keypair using ``generate ssh client-key -/config/auth/id_rsa_rpki``. Once your key is created you can setup the -connection. - -.. cfgcmd:: set protocols rpki cache <address> ssh username <user> - - SSH username to establish an SSH connection to the cache server. - -.. cfgcmd:: set protocols rpki cache <address> ssh private-key-file <filepath> - - Local path that includes the private key file of the router. - -.. cfgcmd:: set protocols rpki cache <address> ssh public-key-file <filepath> - - Local path that includes the public key file of the router. - -.. note:: When using SSH, private-key-file and public-key-file - are mandatory options. - -******* -Example -******* - -We can build route-maps for import based on these states. Here is a simple -RPKI configuration, where `routinator` is the RPKI-validating "cache" -server with ip `192.0.2.1`: - -.. code-block:: none - - set protocols rpki cache 192.0.2.1 port '3323' - set protocols rpki cache 192.0.2.1 preference '1' - -Here is an example route-map to apply to routes learned at import. In this -filter we reject prefixes with the state `invalid`, and set a higher -`local-preference` if the prefix is RPKI `valid` rather than merely -`notfound`. - -.. code-block:: none - - set policy route-map ROUTES-IN rule 10 action 'permit' - set policy route-map ROUTES-IN rule 10 match rpki 'valid' - set policy route-map ROUTES-IN rule 10 set local-preference '300' - set policy route-map ROUTES-IN rule 20 action 'permit' - set policy route-map ROUTES-IN rule 20 match rpki 'notfound' - set policy route-map ROUTES-IN rule 20 set local-preference '125' - set policy route-map ROUTES-IN rule 30 action 'deny' - set policy route-map ROUTES-IN rule 30 match rpki 'invalid' - -Once your routers are configured to reject RPKI-invalid prefixes, you can -test whether the configuration is working correctly using Cloudflare's test_ -website. Keep in mind that in order for this to work, you need to have no -default routes or anything else that would still send traffic to RPKI-invalid -destinations. - -.. stop_vyoslinter - -.. _tweet by EvilMog: https://twitter.com/Evil_Mog/status/1230924170508169216 -.. _Routinator: https://www.nlnetlabs.nl/projects/rpki/routinator/ -.. _Krill: https://www.nlnetlabs.nl/projects/rpki/krill/ -.. _excellent guide to RPKI: https://rpki.readthedocs.io/ -.. _help and operational guidance: https://rpki.readthedocs.io/en/latest/about/help.html -.. _rpki-client: https://www.rpki-client.org/ -.. _StayRTR: https://github.com/bgp/stayrtr/ -.. _software: https://rpki.readthedocs.io/en/latest/ops/tools.html#relying-party-software -.. _test: https://isbgpsafeyet.com/ - -.. start_vyoslinter diff --git a/docs/configuration/protocols/rst-segment-routing.rst b/docs/configuration/protocols/rst-segment-routing.rst deleted file mode 100644 index 5ee710e9..00000000 --- a/docs/configuration/protocols/rst-segment-routing.rst +++ /dev/null @@ -1,357 +0,0 @@ -.. _segment-routing: - -############### -Segment Routing -############### - -Segment Routing (SR) is a network architecture that is similar to source-routing -. In this architecture, the ingress router adds a list of segments, known as -SIDs, to the packet as it enters the network. These segments represent different -portions of the network path that the packet will take. - -The SR segments are portions of the network path taken by the packet, and are -called SIDs. At each node, the first SID of the list is read, executed as a -forwarding function, and may be popped to let the next node read the next SID of -the list. The SID list completely determines the path where the packet is -forwarded. - -Segment Routing can be applied to an existing MPLS-based data plane and defines -a control plane network architecture. In MPLS networks, segments are encoded as -MPLS labels and are added at the ingress router. These MPLS labels are then -exchanged and populated by Interior Gateway Protocols (IGPs) like IS-IS or OSPF -which are running on most ISPs. - - -.. note:: Segment routing defines a control plane network architecture and - can be applied to an existing MPLS based dataplane. In the MPLS networks, - segments are encoded as MPLS labels and are imposed at the ingress router. - MPLS labels are exchanged and populated by IGPs like IS-IS.Segment Routing - as per RFC8667 for MPLS dataplane. It supports IPv4, IPv6 and ECMP and has - been tested against Cisco & Juniper routers.however,this deployment is still - EXPERIMENTAL for FRR. - - -IS-IS SR Configuration ----------------------- - -Segment routing (SR) is used by the IGP protocols to interconnect network -devices, below configuration shows how to enable SR on IS-IS: - - -.. note:: ``Known limitations:`` - - No support for level redistribution (L1 to L2 or L2 to L1) - - No support for binding SID - - No support for SRLB - - Only one SRGB and default SPF Algorithm is supported - - - -.. cfgcmd:: set protocols isis segment-routing global-block high-label-value - <label-value> - - Set the Segment Routing Global Block i.e. the label range used by MPLS to - store label in the MPLS FIB for Prefix SID. Note that the block size may - not exceed 65535. - -.. cfgcmd:: set protocols isis segment-routing global-block low-label-value - <label-value> - - Set the Segment Routing Global Block i.e. the low label range used by MPLS to - store label in the MPLS FIB for Prefix SID. Note that the block size may - not exceed 65535. - -.. cfgcmd:: set protocols isis segment-routing local-block high-label-value - <label-value> - - Set the Segment Routing Local Block i.e. the label range used by MPLS to - store label in the MPLS FIB for Prefix SID. Note that the block size may - not exceed 65535.Segment Routing Local Block, The negative command always - unsets both. - -.. cfgcmd:: set protocols isis segment-routing local-block <low-label-value - <label-value> - - Set the Segment Routing Local Block i.e. the low label range used by MPLS to - store label in the MPLS FIB for Prefix SID. Note that the block size may - not exceed 65535.Segment Routing Local Block, The negative command always - unsets both. - -.. cfgcmd:: set protocols isis segment-routing maximum-label-depth <1-16> - - Set the Maximum Stack Depth supported by the router. The value depend of - the MPLS dataplane. - -.. cfgcmd:: set protocols isis segment-routing prefix <address> index value - <0-65535> - - A segment ID that contains an IP address prefix calculated by an IGP in the - service provider core network. Prefix SIDs are globally unique, this value - indentify it - -.. cfgcmd:: set protocols isis segment-routing prefix <address> index - <no-php-flag | explicit-null| n-flag-clear> - - this option allows to configure prefix-sid on SR. The ‘no-php-flag’ means NO - Penultimate Hop Popping that allows SR node to request to its neighbor to - not pop the label. The ‘explicit-null’ flag allows SR node to request to its - neighbor to send IP packet with the EXPLICIT-NULL label. The ‘n-flag-clear’ - option can be used to explicitly clear the Node flag that is set by default - for Prefix-SIDs associated to loopback addresses. This option is necessary - to configure Anycast-SIDs. - - -.. opcmd:: show isis segment-routing node - - Show detailed information about all learned Segment Routing Nodes - -.. opcmd:: show isis route prefix-sid - - Show detailed information about prefix-sid and label learned - -.. note:: more information related IGP - :ref:`routing-isis` - - - -OSPF SR Configuration ----------------------- - -Segment routing (SR) is used by the IGP protocols to interconnect network -devices, below configuration shows how to enable SR on OSPF: - -.. cfgcmd:: set protocols ospf parameters opaque-lsa - - Enable the Opaque-LSA capability (rfc2370), necessary to transport label - on IGP - - -.. cfgcmd:: set protocols ospf segment-routing global-block high-label-value - <label-value> - - Set the Segment Routing Global Block i.e. the label range used by MPLS to - store label in the MPLS FIB for Prefix SID. Note that the block size may - not exceed 65535. - -.. cfgcmd:: set protocols ospf segment-routing global-block low-label-value - <label-value> - - Set the Segment Routing Global Block i.e. the low label range used by MPLS to - store label in the MPLS FIB for Prefix SID. Note that the block size may - not exceed 65535. - -.. cfgcmd:: set protocols ospf segment-routing local-block high-label-value - <label-value> - - Set the Segment Routing Local Block i.e. the label range used by MPLS to - store label in the MPLS FIB for Prefix SID. Note that the block size may - not exceed 65535.Segment Routing Local Block, The negative command always - unsets both. - -.. cfgcmd:: set protocols ospf segment-routing local-block <low-label-value - <label-value> - - Set the Segment Routing Local Block i.e. the low label range used by MPLS to - store label in the MPLS FIB for Prefix SID. Note that the block size may - not exceed 65535.Segment Routing Local Block, The negative command always - unsets both. - -.. cfgcmd:: set protocols ospf segment-routing maximum-label-depth <1-16> - - Set the Maximum Stack Depth supported by the router. The value depend of - the MPLS dataplane. - -.. cfgcmd:: set protocols ospf segment-routing prefix <address> index value - <0-65535> - - A segment ID that contains an IP address prefix calculated by an IGP in the - service provider core network. Prefix SIDs are globally unique, this value - indentify it - -.. cfgcmd:: set protocols ospf segment-routing prefix <address> index - <no-php-flag | explicit-null| n-flag-clear> - - this option allows to configure prefix-sid on SR. The ‘no-php-flag’ means NO - Penultimate Hop Popping that allows SR node to request to its neighbor to - not pop the label. The ‘explicit-null’ flag allows SR node to request to its - neighbor to send IP packet with the EXPLICIT-NULL label. The ‘n-flag-clear’ - option can be used to explicitly clear the Node flag that is set by default - for Prefix-SIDs associated to loopback addresses. This option is necessary - to configure Anycast-SIDs. - -.. note:: more information related IGP - :ref:`routing-ospf` - -Configuration Example ---------------------- - -we described the configuration SR ISIS / SR OSPF using 2 connected with them to -share label information. - -Enable IS-IS with Segment Routing (Experimental) -================================================ - -**Node 1:** - -.. code-block:: none - - set interfaces loopback lo address '192.168.255.255/32' - set interfaces ethernet eth1 address '192.0.2.1/24' - - set protocols isis interface eth1 - set protocols isis interface lo - set protocols isis net '49.0001.1921.6825.5255.00' - set protocols isis segment-routing global-block high-label-value '599' - set protocols isis segment-routing global-block low-label-value '550' - set protocols isis segment-routing prefix 192.168.255.255/32 index value '1' - set protocols isis segment-routing prefix 192.168.255.255/32 index explicit-null - set protocols mpls interface 'eth1' - -**Node 2:** - -.. code-block:: none - - set interfaces loopback lo address '192.168.255.254/32' - set interfaces ethernet eth1 address '192.0.2.2/24' - - set protocols isis interface eth1 - set protocols isis interface lo - set protocols isis net '49.0001.1921.6825.5254.00' - set protocols isis segment-routing global-block high-label-value '599' - set protocols isis segment-routing global-block low-label-value '550' - set protocols isis segment-routing prefix 192.168.255.254/32 index value '2' - set protocols isis segment-routing prefix 192.168.255.254/32 index explicit-null - set protocols mpls interface 'eth1' - - - -This gives us MPLS segment routing enabled and labels for far end loopbacks: - -.. code-block:: none - - Node-1@vyos:~$ show mpls table - Inbound Label Type Nexthop Outbound Label - ---------------------------------------------------------------------- - 552 SR (IS-IS) 192.0.2.2 IPv4 Explicit Null <-- Node-2 loopback learned on Node-1 - 15000 SR (IS-IS) 192.0.2.2 implicit-null - 15001 SR (IS-IS) fe80::e87:6cff:fe09:1 implicit-null - 15002 SR (IS-IS) 192.0.2.2 implicit-null - 15003 SR (IS-IS) fe80::e87:6cff:fe09:1 implicit-null - - Node-2@vyos:~$ show mpls table - Inbound Label Type Nexthop Outbound Label - --------------------------------------------------------------------- - 551 SR (IS-IS) 192.0.2.1 IPv4 Explicit Null <-- Node-1 loopback learned on Node-2 - 15000 SR (IS-IS) 192.0.2.1 implicit-null - 15001 SR (IS-IS) fe80::e33:2ff:fe80:1 implicit-null - 15002 SR (IS-IS) 192.0.2.1 implicit-null - 15003 SR (IS-IS) fe80::e33:2ff:fe80:1 implicit-null - -Here is the routing tables showing the MPLS segment routing label operations: - -.. code-block:: none - - Node-1@vyos:~$ show ip route isis - Codes: K - kernel route, C - connected, S - static, R - RIP, - O - OSPF, I - IS-IS, B - BGP, E - EIGRP, N - NHRP, - T - Table, v - VNC, V - VNC-Direct, A - Babel, F - PBR, - f - OpenFabric, - > - selected route, * - FIB route, q - queued, r - rejected, b - backup - t - trapped, o - offload failure - - I 192.0.2.0/24 [115/20] via 192.0.2.2, eth1 inactive, weight 1, 00:07:48 - I>* 192.168.255.254/32 [115/20] via 192.0.2.2, eth1, label IPv4 Explicit Null, weight 1, 00:03:39 - - Node-2@vyos:~$ show ip route isis - Codes: K - kernel route, C - connected, S - static, R - RIP, - O - OSPF, I - IS-IS, B - BGP, E - EIGRP, N - NHRP, - T - Table, v - VNC, V - VNC-Direct, A - Babel, F - PBR, - f - OpenFabric, - > - selected route, * - FIB route, q - queued, r - rejected, b - backup - t - trapped, o - offload failure - - I 192.0.2.0/24 [115/20] via 192.0.2.1, eth1 inactive, weight 1, 00:07:46 - I>* 192.168.255.255/32 [115/20] via 192.0.2.1, eth1, label IPv4 Explicit Null, weight 1, 00:03:43 - - -Enable OSPF with Segment Routing (Experimental): -================================================ - -**Node 1** - -.. code-block:: none - - set interfaces loopback lo address 10.1.1.1/32 - set interfaces ethernet eth0 address 192.168.0.1/24 - set protocols ospf area 0 network '192.168.0.0/24' - set protocols ospf area 0 network '10.1.1.1/32' - set protocols ospf parameters opaque-lsa - set protocols ospf parameters router-id '10.1.1.1' - set protocols ospf segment-routing global-block high-label-value '1100' - set protocols ospf segment-routing global-block low-label-value '1000' - set protocols ospf segment-routing prefix 10.1.1.1/32 index explicit-null - set protocols ospf segment-routing prefix 10.1.1.1/32 index value '1' - -**Node 2** - -.. code-block:: none - - set interfaces loopback lo address 10.1.1.2/32 - set interfaces ethernet eth0 address 192.168.0.2/24 - set protocols ospf area 0 network '192.168.0.0/24' - set protocols ospf area 0 network '10.1.1.2/32' - set protocols ospf parameters opaque-lsa - set protocols ospf parameters router-id '10.1.1.2' - set protocols ospf segment-routing global-block high-label-value '1100' - set protocols ospf segment-routing global-block low-label-value '1000' - set protocols ospf segment-routing prefix 10.1.1.2/32 index explicit-null - set protocols ospf segment-routing prefix 10.1.1.2/32 index value '2' - - -This gives us MPLS segment routing enabled and labels for far end loopbacks: - -.. code-block:: none - - Node-1@vyos:~$ show mpls table - Inbound Label Type Nexthop Outbound Label - ----------------------------------------------------------- - 1002 SR (OSPF) 192.168.0.2 IPv4 Explicit Null <-- Node-2 loopback learned on Node-1 - 15000 SR (OSPF) 192.168.0.2 implicit-null - 15001 SR (OSPF) 192.168.0.2 implicit-null - - Node-2@vyos:~$ show mpls table - Inbound Label Type Nexthop Outbound Label - ----------------------------------------------------------- - 1001 SR (OSPF) 192.168.0.1 IPv4 Explicit Null <-- Node-1 loopback learned on Node-2 - 15000 SR (OSPF) 192.168.0.1 implicit-null - 15001 SR (OSPF) 192.168.0.1 implicit-null - -Here is the routing tables showing the MPLS segment routing label operations: - -.. code-block:: none - - Node-1@vyos:~$ show ip route ospf - Codes: K - kernel route, C - connected, S - static, R - RIP, - O - OSPF, I - IS-IS, B - BGP, E - EIGRP, N - NHRP, - T - Table, v - VNC, V - VNC-Direct, A - Babel, F - PBR, - f - OpenFabric, - > - selected route, * - FIB route, q - queued, r - rejected, b - backup - t - trapped, o - offload failure - - O 10.1.1.1/32 [110/0] is directly connected, lo, weight 1, 00:03:43 - O>* 10.1.1.2/32 [110/1] via 192.168.0.2, eth0, label IPv4 Explicit Null, weight 1, 00:03:32 - O 192.168.0.0/24 [110/1] is directly connected, eth0, weight 1, 00:03:43 - - Node-2@vyos:~$ show ip route ospf - Codes: K - kernel route, C - connected, S - static, R - RIP, - O - OSPF, I - IS-IS, B - BGP, E - EIGRP, N - NHRP, - T - Table, v - VNC, V - VNC-Direct, A - Babel, F - PBR, - f - OpenFabric, - > - selected route, * - FIB route, q - queued, r - rejected, b - backup - t - trapped, o - offload failure - - O>* 10.1.1.1/32 [110/1] via 192.168.0.1, eth0, label IPv4 Explicit Null, weight 1, 00:03:36 - O 10.1.1.2/32 [110/0] is directly connected, lo, weight 1, 00:03:51 - O 192.168.0.0/24 [110/1] is directly connected, eth0, weight 1, 00:03:51 - diff --git a/docs/configuration/protocols/rst-static.rst b/docs/configuration/protocols/rst-static.rst deleted file mode 100644 index eb5a439c..00000000 --- a/docs/configuration/protocols/rst-static.rst +++ /dev/null @@ -1,301 +0,0 @@ -.. _routing-static: - -###### -Static -###### - -Static routes are manually configured routes, which, in general, cannot be -updated dynamically from information VyOS learns about the network topology from -other routing protocols. However, if a link fails, the router will remove -routes, including static routes, from the :abbr:`RIPB (Routing Information -Base)` that used this interface to reach the next hop. In general, static -routes should only be used for very simple network topologies, or to override -the behavior of a dynamic routing protocol for a small number of routes. The -collection of all routes the router has learned from its configuration or from -its dynamic routing protocols is stored in the RIB. Unicast routes are directly -used to determine the forwarding table used for unicast packet forwarding. - -******************* -IPv4 Unicast Routes -******************* - -.. cfgcmd:: set protocols static route <subnet> next-hop <address> - - Configure next-hop `<address>` for an IPv4 static route. Multiple static - routes can be created. - -.. cfgcmd:: set protocols static route <subnet> next-hop <address> disable - - Disable this IPv4 static route entry. - -.. cfgcmd:: set protocols static route <subnet> next-hop <address> - distance <distance> - - Defines next-hop distance for this route, routes with smaller administrative - distance are elected prior to those with a higher distance. - - Range is 1 to 255, default is 1. - - .. note:: Routes with a distance of 255 are effectively disabled and not - installed into the kernel. - -IPv4 Interface Routes -===================== - -.. cfgcmd:: set protocols static route <subnet> interface - <interface> - - Allows you to configure the next-hop interface for an interface-based IPv4 - static route. `<interface>` will be the next-hop interface where traffic is - routed for the given `<subnet>`. - -.. cfgcmd:: set protocols static route <subnet> interface - <interface> disable - - Disables interface-based IPv4 static route. - -.. cfgcmd:: set protocols static route <subnet> interface - <interface> distance <distance> - - Defines next-hop distance for this route, routes with smaller administrative - distance are elected prior to those with a higher distance. - - Range is 1 to 255, default is 1. - -IPv4 BFD -======== - -.. cfgcmd:: set protocols static route <subnet> next-hop <address> 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>`. - -.. cfgcmd:: set protocols static route <subnet> next-hop <address> bfd multi-hop - source-address <source-address> - - 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. - -DHCP Interface Routes -===================== - -.. cfgcmd:: set protocols static route <subnet> dhcp-interface <interface> - - Defines route with DHCP interface supplying next-hop IP address. - -IPv4 Reject Routes -================== - -.. cfgcmd:: set protocol static route <subnet> reject - - Defines route which emits an ICMP unreachable when matched. - -.. cfgcmd:: set protocols static route <subnet> reject distance <distance> - - Defines distance for this route, routes with smaller administrative - distance are elected prior to those with a higher distance. - -.. cfgcmd:: set protocols static route <subnet> reject tag <tag> - - Sets a tag for this route. - -.. cfgcmd:: set protocol static route6 <subnet> reject - - Defines route which emits an ICMP unreachable when matched. - -IPv4 Blackhole Routes -===================== - -.. cfgcmd:: set protocols static route <subnet> blackhole - - Use this command to configure a "black-hole" route on the router. A - black-hole route is a route for which the system silently discard packets - that are matched. This prevents networks leaking out public interfaces, but - it does not prevent them from being used as a more specific route inside your - network. - -.. cfgcmd:: set protocols static route <subnet> blackhole distance <distance> - - Defines blackhole distance for this route, routes with smaller administrative - distance are elected prior to those with a higher distance. - -.. cfgcmd:: set protocols static route <subnet> blackhole tag <tag> - - Sets a tag for this route. - -******************* -IPv6 Unicast Routes -******************* - -.. cfgcmd:: set protocols static route6 <subnet> next-hop <address> - - Configure next-hop `<address>` for an IPv6 static route. Multiple static - routes can be created. - -.. cfgcmd:: set protocols static route6 <subnet> next-hop <address> disable - - Disable this IPv6 static route entry. - -.. cfgcmd:: set protocols static route6 <subnet> next-hop <address> - distance <distance> - - Defines next-hop distance for this route, routes with smaller administrative - distance are elected prior to those with a higher distance. - - Range is 1 to 255, default is 1. - - .. note:: Routes with a distance of 255 are effectively disabled and not - installed into the kernel. - -.. stop_vyoslinter - -.. cfgcmd:: set protocols static route6 <subnet> next-hop <address> segments <segments> - -.. 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' - - .. code-block:: none - - vyos@vyos:~$ show ipv6 route - Codes: K - kernel route, C - connected, S - static, R - RIPng, - O - OSPFv3, I - IS-IS, B - BGP, N - NHRP, T - Table, - v - VNC, V - VNC-Direct, A - Babel, F - PBR, - f - OpenFabric, - > - selected route, * - FIB route, q - queued, r - rejected, b - backup - t - trapped, o - offload failure - C>* 2001:db8:201::/64 is directly connected, eth0.201, 00:00:46 - S>* 2001:db8:1000::/36 [1/0] via 2001:db8:201::ffff, eth0.201, seg6 2001:db8:aaaa::7,2002::4,2002::3,2002::2, weight 1, 00:00:08 - -.. start_vyoslinter - -IPv6 Interface Routes -===================== - -.. cfgcmd:: set protocols static route6 <subnet> interface - <interface> - - Allows you to configure the next-hop interface for an interface-based IPv6 - static route. `<interface>` will be the next-hop interface where traffic is - routed for the given `<subnet>`. - -.. cfgcmd:: set protocols static route6 <subnet> interface - <interface> disable - - Disables interface-based IPv6 static route. - -.. cfgcmd:: set protocols static route6 <subnet> interface - <interface> distance <distance> - - Defines next-hop distance for this route, routes with smaller administrative - distance are elected prior to those with a higher distance. - - Range is 1 to 255, default is 1. - -.. cfgcmd:: set protocols static route6 <subnet> interface - <interface> segments <segments> - - It is possible to specify a static route for ipv6 prefixes using an - SRv6 segments instruction. The ``/`` separator can be used to specify - multiple segment instructions. - - Example: - -.. 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 -======== - -.. cfgcmd:: set protocols static route6 <subnet> next-hop <address> 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. - -IPv6 Reject Routes -================== - -.. cfgcmd:: set protocol static route6 <subnet> reject - - Defines route which emits an ICMP unreachable when matched. - -.. cfgcmd:: set protocols static route6 <subnet> reject distance <distance> - - Defines distance for this route, routes with smaller administrative - distance are elected prior to those with a higher distance. - -.. cfgcmd:: set protocols static route6 <subnet> reject tag <tag> - - Sets a tag for this route. - -IPv6 Blackhole Routes -===================== - -.. cfgcmd:: set protocols static route6 <subnet> blackhole - - Use this command to configure a "black-hole" route on the router. A - black-hole route is a route for which the system silently discard packets - that are matched. This prevents networks leaking out public interfaces, but - it does not prevent them from being used as a more specific route inside your - network. - -.. cfgcmd:: set protocols static route6 <subnet> blackhole distance <distance> - - Defines blackhole distance for this route, routes with smaller administrative - distance are elected prior to those with a higher distance. - -.. cfgcmd:: set protocols static route6 <subnet> blackhole tag <tag> - - Sets a tag for this route. - -************************ -Alternate Routing Tables -************************ - -Alternate routing tables are used with policy based routing by utilizing -:ref:`vrf`. diff --git a/docs/configuration/protocols/rst-traffic-engineering.rst b/docs/configuration/protocols/rst-traffic-engineering.rst deleted file mode 100644 index 977a5e5c..00000000 --- a/docs/configuration/protocols/rst-traffic-engineering.rst +++ /dev/null @@ -1,51 +0,0 @@ -.. _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/rst-index.rst b/docs/configuration/rst-index.rst deleted file mode 100644 index f86365a9..00000000 --- a/docs/configuration/rst-index.rst +++ /dev/null @@ -1,24 +0,0 @@ -################### -Configuration Guide -################### - -The following structure represents the CLI structure. - -.. toctree:: - :maxdepth: 1 - :includehidden: - - container/index - firewall/index - highavailability/index - interfaces/index - loadbalancing/index - nat/index - policy/index - pki/index - protocols/index - service/index - system/index - trafficpolicy/index - vpn/index - vrf/index diff --git a/docs/configuration/service/rst-broadcast-relay.rst b/docs/configuration/service/rst-broadcast-relay.rst deleted file mode 100644 index f64bb208..00000000 --- a/docs/configuration/service/rst-broadcast-relay.rst +++ /dev/null @@ -1,66 +0,0 @@ -.. _udp_broadcast_relay: - -################### -UDP Broadcast Relay -################### - -Certain vendors use broadcasts to identify their equipment within one ethernet -segment. Unfortunately if you split your network with multiple VLANs you loose -the ability of identifying your equipment. - -This is where "UDP broadcast relay" comes into play! It will forward received -broadcasts to other configured networks. - -Every UDP port which will be forward requires one unique ID. Currently we -support 99 IDs! - -Configuration -------------- - -.. cfgcmd:: set service broadcast-relay id <n> description <description> - - A description can be added for each and every unique relay ID. This is - useful to distinguish between multiple different ports/applications. - -.. cfgcmd:: set service broadcast-relay id <n> interface <interface> - - The interface used to receive and relay individual broadcast packets. If you - want to receive/relay packets on both `eth1` and `eth2` both interfaces need - to be added. - -.. cfgcmd:: set service broadcast-relay id <n> address <ipv4-address> - - Set the source IP of forwarded packets, otherwise original senders address - is used. - -.. cfgcmd:: set service broadcast-relay id <n> port <port> - - The UDP port number used by your application. It is mandatory for this kind - of operation. - -.. cfgcmd:: set service broadcast-relay id <n> disable - - Each broadcast relay instance can be individually disabled without deleting - the configured node by using the following command: - -.. cfgcmd:: set service broadcast-relay disable - - In addition you can also disable the whole service without the need to remove - it from the current configuration. - -.. note:: You can run the UDP broadcast relay service on multiple routers - connected to a subnet. There is **NO** UDP broadcast relay packet storm! - -Example -------- - -To forward all broadcast packets received on `UDP port 1900` on `eth3`, `eth4` -or `eth5` to all other interfaces in this configuration. - -.. code-block:: none - - set service broadcast-relay id 1 description 'SONOS' - set service broadcast-relay id 1 interface 'eth3' - set service broadcast-relay id 1 interface 'eth4' - set service broadcast-relay id 1 interface 'eth5' - set service broadcast-relay id 1 port '1900' diff --git a/docs/configuration/service/rst-config-sync.rst b/docs/configuration/service/rst-config-sync.rst deleted file mode 100644 index a8984a0d..00000000 --- a/docs/configuration/service/rst-config-sync.rst +++ /dev/null @@ -1,160 +0,0 @@ -.. _config-sync: - -########### -Config Sync -########### - -Configuration synchronization (config sync) is a feature of VyOS that -permits synchronization of the configuration of one VyOS router to -another in a network. - -The main benefit to configuration synchronization is that it eliminates having -to manually replicate configuration changes made on the primary router to the -secondary (replica) router. - -The writing of the configuration to the secondary router is performed through -the VyOS HTTP API. The user can specify which portion(s) of the configuration will -be synchronized and the mode to use - whether to replace or add. - -To prevent issues with divergent configurations between the pair of routers, -synchronization is strictly unidirectional from primary to replica. Both -routers should be online and run the same version of VyOS. - -Configuration -------------- - -.. cfgcmd:: set service config-sync secondary - <address|key|timeout|port> - - Specify the address, API key, timeout and port of the secondary router. - You need to enable and configure the HTTP API service on the secondary - router for config sync to operate. - -.. cfgcmd:: set service config-sync section <section> - - Specify the section of the configuration to synchronize. If more than one - section is to be synchronized, repeat the command to add additional - sections as required. - -.. cfgcmd:: set service config-sync mode <load|set> - - Two options are available for `mode`: either `load` and replace or `set` - the configuration section. - -.. code-block:: none - - Supported options for <section> include: - firewall - interfaces <interface> - nat - nat66 - pki - policy - protocols <protocol> - qos <interface|policy> - service <service> - system <conntrack| - flow-accounting|option|sflow|static-host-mapping|sysctl|time-zone> - vpn - vrf - -Operational Commands --------------------- - -.. opcmd:: show configuration secondary sync [commands] [running | candidate | saved] [<config-node-path>] - - Display configuration differences between the local node and - a config-sync secondary node. - - This command allows operators to compare configurations across nodes - participating in configuration synchronization (e.g., primary and - secondary routers). It helps detect configuration drift and validate - intended changes before synchronization. - - **Parameters:** - - .. list-table:: - :widths: 30 70 - :header-rows: 0 - - * - ``commands`` (optional) - - Show output as a list of configuration commands instead of raw diff. - * - ``running|candidate|saved`` (optional, mutually exclusive) - - Select which configuration to compare: - ``running`` (current active configuration, default), - ``candidate`` (uncommitted changes), or - ``saved`` (last saved configuration). Only one of these may be - specified at a time; if omitted, ``running`` is used. - - **Examples:** - - .. code-block:: none - - # compare full running configuration with a secondary node - show configuration secondary sync - - # compare only interface configuration - show configuration secondary sync running interfaces dummy - - # compare candidate configuration and display as a list of commands - show configuration secondary sync commands candidate - -Without a built-in cross-node diff, operators may unintentionally push -changes that conflict with the remote configuration (e.g., mismatched -interfaces, firewall policies, or protocol settings). - -Example -------- -* Synchronize the time-zone and OSPF configuration from Router A to Router B -* The address of Router B is 10.0.20.112 and the port used is 8443 - -Configure the HTTP API service on Router B - -.. code-block:: none - - set service https listen-address '10.0.20.112' - set service https port '8443' - set service https api keys id KID key 'foo' - set service https api rest - -Configure the config-sync service on Router A - -.. code-block:: none - - set service config-sync mode 'load' - set service config-sync secondary address '10.0.20.112' - set service config-sync secondary port '8443' - set service config-sync secondary key 'foo' - set service config-sync section protocols 'ospf' - set service config-sync section system 'time-zone' - -Make config-sync relevant changes to Router A's configuration - -.. code-block:: none - - vyos@vyos-A# set system time-zone 'America/Los_Angeles' - vyos@vyos-A# commit - INFO:vyos_config_sync:Config synchronization: Mode=load, - Secondary=10.0.20.112 - vyos@vyos-A# save - - vyos@vyos-A# set protocols ospf area 0 network '10.0.48.0/30' - vyos@vyos-A# commit - INFO:vyos_config_sync:Config synchronization: Mode=load, - Secondary=10.0.20.112 - yos@vyos-A# save - -Verify configuration changes have been replicated to Router B - -.. code-block:: none - - vyos@vyos-B:~$ show configuration commands | match time-zone - set system time-zone 'America/Los_Angeles' - - vyos@vyos-B:~$ show configuration commands | match ospf - set protocols ospf area 0 network '10.0.48.0/30' - -Known issues ------------- -Configuration resynchronization. With the current implementation of `service -config-sync`, the secondary node must be online. diff --git a/docs/configuration/service/rst-conntrack-sync.rst b/docs/configuration/service/rst-conntrack-sync.rst deleted file mode 100644 index 2527407e..00000000 --- a/docs/configuration/service/rst-conntrack-sync.rst +++ /dev/null @@ -1,302 +0,0 @@ -.. _conntrack-sync: - -############## -Conntrack Sync -############## - -One of the important features built on top of the Netfilter framework is -connection tracking. Connection tracking allows the kernel to keep track of all -logical network connections or sessions, and thereby relate all of the packets -which may make up that connection. NAT relies on this information to translate -all related packets in the same way, and iptables can use this information to -act as a stateful firewall. - -The connection state however is completely independent of any upper-level -state, such as TCP's or SCTP's state. Part of the reason for this is that when -merely forwarding packets, i.e. no local delivery, the TCP engine may not -necessarily be invoked at all. Even connectionless-mode transmissions such as -UDP, IPsec (AH/ESP), GRE and other tunneling protocols have, at least, a pseudo -connection state. The heuristic for such protocols is often based upon a preset -timeout value for inactivity, after whose expiration a Netfilter connection is -dropped. - -Each Netfilter connection is uniquely identified by a (layer-3 protocol, source -address, destination address, layer-4 protocol, layer-4 key) tuple. The layer-4 -key depends on the transport protocol; for TCP/UDP it is the port numbers, for -tunnels it can be their tunnel ID, but otherwise is just zero, as if it were -not part of the tuple. To be able to inspect the TCP port in all cases, packets -will be mandatorily defragmented. - -It is possible to use either Multicast or Unicast to sync conntrack traffic. -Most examples below show Multicast, but unicast can be specified by using the -"peer" keywork after the specified interface, as in the following example: - -:cfgcmd:`set service conntrack-sync interface eth0 peer 192.168.0.250` - -************* -Configuration -************* - -.. cfgcmd:: set service conntrack-sync accept-protocol - - Accept only certain protocols: You may want to replicate the state of flows - depending on their layer 4 protocol. - - Protocols are: tcp, sctp, dccp, udp, icmp and ipv6-icmp. - -.. cfgcmd:: set service conntrack-sync event-listen-queue-size <size> - - The daemon doubles the size of the netlink event socket buffer size if it - detects netlink event message dropping. This clause sets the maximum buffer - size growth that can be reached. - - Queue size for listening to local conntrack events in MB. - -.. cfgcmd:: set service conntrack-sync expect-sync <all|ftp|h323|nfs|sip|sqlnet> - - Protocol for which expect entries need to be synchronized. - -.. stop_vyoslinter - -.. cfgcmd:: set service conntrack-sync failover-mechanism vrrp sync-group <group> - - Failover mechanism to use for conntrack-sync. - - Only VRRP is supported. Required option. - -.. cfgcmd:: set service conntrack-sync ignore-address <x.x.x.x> - - IP addresses or networks for which local conntrack entries will not - be synced - -.. start_vyoslinter - -.. cfgcmd:: set service conntrack-sync interface <name> - - Interface to use for syncing conntrack entries. - -.. cfgcmd:: set service conntrack-sync interface <name> port <port> - - Port number used by connection. - -.. cfgcmd:: set service conntrack-sync listen-address <ipv4address> - - Local IPv4 addresses for service to listen on. - -.. cfgcmd:: set service conntrack-sync mcast-group <x.x.x.x> - - Multicast group to use for syncing conntrack entries. - - Defaults to 225.0.0.50. - -.. cfgcmd:: set service conntrack-sync interface <name> peer <address> - - Peer to send unicast UDP conntrack sync entires to, if not using Multicast - configuration from above above. - -.. cfgcmd:: set service conntrack-sync sync-queue-size <size> - - Queue size for syncing conntrack entries in MB. - -.. cfgcmd:: set service conntrack-sync disable-external-cache - - This diable the external cache and directly injects the flow-states into the - in-kernel Connection Tracking System of the backup firewall. - -.. 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. - -.. cfgcmd:: set service conntrack-sync startup-resync - - Order conntrackd to request a complete conntrack table resync against - the other node at startup. - -********* -Operation -********* - -.. opcmd:: show conntrack table ipv4 - - Make sure conntrack is enabled by running and show connection tracking table. - - .. code-block:: none - - vyos@vyos:~$ show conntrack table ipv4 - TCP state codes: SS - SYN SENT, SR - SYN RECEIVED, ES - ESTABLISHED, - FW - FIN WAIT, CW - CLOSE WAIT, LA - LAST ACK, - TW - TIME WAIT, CL - CLOSE, LI - LISTEN - - CONN ID Source Destination Protocol TIMEOUT - 1015736576 10.35.100.87:58172 172.31.20.12:22 tcp [6] ES 430279 - 1006235648 10.35.101.221:57483 172.31.120.21:22 tcp [6] ES 413310 - 1006237088 10.100.68.100 172.31.120.21 icmp [1] 29 - 1015734848 10.35.100.87:56282 172.31.20.12:22 tcp [6] ES 300 - 1015734272 172.31.20.12:60286 239.10.10.14:694 udp [17] 29 - 1006239392 10.35.101.221 172.31.120.21 icmp [1] 29 - - .. note:: - - If the table is empty and you have a warning message, it means - conntrack is not enabled. To enable conntrack, just create a NAT - or a firewall rule. - :cfgcmd:`set firewall state-policy established action accept` - -.. opcmd:: show conntrack-sync cache external - - Show connection syncing external cache entries - -.. opcmd:: show conntrack-sync cache internal - - Show connection syncing internal cache entries - -.. opcmd:: show conntrack-sync statistics - - Retrieve current statistics of connection tracking subsystem. - - .. code-block:: none - - vyos@vyos:~$ show conntrack-sync statistics - Main Table Statistics: - - cache internal: - current active connections: 19606 - connections created: 6298470 failed: 0 - connections updated: 3786793 failed: 0 - connections destroyed: 6278864 failed: 0 - - cache external: - current active connections: 15771 - connections created: 1660193 failed: 0 - connections updated: 77204 failed: 0 - connections destroyed: 1644422 failed: 0 - - traffic processed: - 0 Bytes 0 Pckts - - multicast traffic (active device=eth0.5): - 976826240 Bytes sent 212898000 Bytes recv - 8302333 Pckts sent 2009929 Pckts recv - 0 Error send 0 Error recv - - message tracking: - 0 Malformed msgs 263 Lost msgs - - -.. opcmd:: show conntrack-sync status - - Retrieve current status of connection tracking subsystem. - - .. code-block:: none - - vyos@vyos:~$ show conntrack-sync status - sync-interface : eth0.5 - failover-mechanism : vrrp [sync-group GEFOEKOM] - last state transition : no transition yet! - ExpectationSync : disabled - - -******* -Example -******* - -The next example is a simple configuration of conntrack-sync. - -.. figure:: /_static/images/service_conntrack_sync-schema.* - :scale: 60 % - :alt: Conntrack Sync Example - -Now configure conntrack-sync service on ``router1`` **and** ``router2`` - -.. code-block:: none - - set high-availability vrrp group internal virtual-address ... etc ... - set high-availability vrrp sync-group syncgrp member 'internal' - set service conntrack-sync accept-protocol 'tcp' - set service conntrack-sync accept-protocol 'udp' - set service conntrack-sync accept-protocol 'icmp' - set service conntrack-sync failover-mechanism vrrp sync-group 'syncgrp' - set service conntrack-sync interface 'eth0' - set service conntrack-sync mcast-group '225.0.0.50' - -On the active router, you should have information in the internal-cache of -conntrack-sync. The same current active connections number should be shown in -the external-cache of the standby router - -On active router run: - -.. code-block:: none - - $ show conntrack-sync statistics - - Main Table Statistics: - - cache internal: - current active connections: 10 - connections created: 8517 failed: 0 - connections updated: 127 failed: 0 - connections destroyed: 8507 failed: 0 - - cache external: - current active connections: 0 - connections created: 0 failed: 0 - connections updated: 0 failed: 0 - connections destroyed: 0 failed: 0 - - traffic processed: - 0 Bytes 0 Pckts - - multicast traffic (active device=eth0): - 868780 Bytes sent 224136 Bytes recv - 20595 Pckts sent 14034 Pckts recv - 0 Error send 0 Error recv - - message tracking: - 0 Malformed msgs 0 Lost msgs - -On standby router run: - -.. code-block:: none - - - $ show conntrack-sync statistics - - Main Table Statistics: - - cache internal: - current active connections: 0 - connections created: 0 failed: 0 - connections updated: 0 failed: 0 - connections destroyed: 0 failed: 0 - - cache external: - current active connections: 10 - connections created: 888 failed: 0 - connections updated: 134 failed: 0 - connections destroyed: 878 failed: 0 - - traffic processed: - 0 Bytes 0 Pckts - - multicast traffic (active device=eth0): - 234184 Bytes sent 907504 Bytes recv - 14663 Pckts sent 21495 Pckts recv - 0 Error send 0 Error recv - - message tracking: - 0 Malformed msgs 0 Lost msgs - diff --git a/docs/configuration/service/rst-console-server.rst b/docs/configuration/service/rst-console-server.rst deleted file mode 100644 index c9ea7f77..00000000 --- a/docs/configuration/service/rst-console-server.rst +++ /dev/null @@ -1,120 +0,0 @@ -.. _console_server: - -############## -Console Server -############## - -Starting of with VyOS 1.3 (equuleus) we added support for running VyOS as an -Out-of-Band Management device which provides remote access by means of SSH to -directly attached serial interfaces. - -Serial interfaces can be any interface which is directly connected to the CPU -or chipset (mostly known as a ttyS interface in Linux) or any other USB to -serial converter (Prolific PL2303 or FTDI FT232/FT4232 based chips). - -If you happened to use a Cisco NM-16A - Sixteen Port Async Network Module or -NM-32A - Thirty-two Port Async Network Module - this is your VyOS replacement. - -For USB port information please refor to: :ref:`hardware_usb`. - -Configuration -============= - -Between computers, the most common configuration used was "8N1": eight bit -characters, with one start bit, one stop bit, and no parity bit. Thus 10 Baud -times are used to send a single character, and so dividing the signalling -bit-rate by ten results in the overall transmission speed in characters per -second. This is also the default setting if none of those options are defined. - -.. cfgcmd:: set service console-server device <device> data-bits [7 | 8] - - Configure either seven or eight data bits. This defaults to eight data - bits if left unconfigured. - -.. cfgcmd:: set service console-server device <device> description <string> - - A user friendly description identifying the connected peripheral. - -.. cfgcmd:: set service console-server device <device> alias <string> - - A user friendly alias for this connection. Can be used instead of the - device name when connecting. - -.. cfgcmd:: set service console-server device <device> parity [even | odd | none] - - Set the parity option for the console. If unset this will default to none. - -.. cfgcmd:: set service console-server device <device> stop-bits [1 | 2] - - Configure either one or two stop bits. This defaults to one stop bits if - left unconfigured. - -.. cfgcmd:: set service console-server device <device> speed - [ 300 | 1200 | 2400 | 4800 | 9600 | 19200 | 38400 | 57600 | 115200 ] - - .. note:: USB to serial converters will handle most of their work in software - so you should be carefull with the selected baudrate as some times they - can't cope with the expected speed. - -Remote Access -------------- - -Each individual configured console-server device can be directly exposed to -the outside world. A user can directly connect via SSH to the configured -port. - -.. cfgcmd:: set service console-server device <device> ssh port <port> - - Accept SSH connections for the given `<device>` on TCP port `<port>`. - After successfull authentication the user will be directly dropped to - the connected serial device. - - .. hint:: Multiple users can connect to the same serial device but only - one is allowed to write to the console port. - -Operation -========= - -.. opcmd:: show console-server ports - - Show configured serial ports and their respective interface configuration. - - .. code-block:: none - - vyos@vyos:~$ show console-server ports - usb0b2.4p1.0 on /dev/serial/by-bus/usb0b2.4p1.0@ at 9600n - -.. opcmd:: show console-server user - - Show currently connected users. - - .. code-block:: none - - vyos@vyos:~$ show console-server user - usb0b2.4p1.0 up vyos@localhost - - -.. opcmd:: connect console <device> - - Locally connect to serial port identified by `<device>`. - - .. code-block:: none - - vyos@vyos-r1:~$ connect console usb0b2.4p1.0 - [Enter `^Ec?' for help] - [-- MOTD -- VyOS Console Server] - - vyos-r2 login: - - .. hint:: Multiple users can connect to the same serial device but only - one is allowed to write to the console port. - - .. hint:: The sequence ``^Ec?`` translates to: ``Ctrl+E c ?``. To quit - the session use: ``Ctrl+E c .`` - - .. hint:: If ``alias`` is set, it can be used instead of the device when - connecting. - -.. opcmd:: show log console-server - - Show the console server log.
\ No newline at end of file diff --git a/docs/configuration/service/rst-dhcp-relay.rst b/docs/configuration/service/rst-dhcp-relay.rst deleted file mode 100644 index 6a1b02f2..00000000 --- a/docs/configuration/service/rst-dhcp-relay.rst +++ /dev/null @@ -1,205 +0,0 @@ -.. _dhcp-relay: - -########## -DHCP Relay -########## - -If you want your router to forward DHCP requests to an external DHCP server -you can configure the system to act as a DHCP relay agent. The DHCP relay -agent works with IPv4 and IPv6 addresses. - -All interfaces used for the DHCP relay must be configured. This includes the -uplink to the DHCP server. - -********** -IPv4 relay -********** - -Configuration -============= - -.. cfgcmd:: set service dhcp-relay interface <interface> - - Interfaces that participate in the DHCP relay process. If this command is - used, at least two entries of it are required: one for the interface that - captures the dhcp-requests, and one for the interface to forward such - requests. A warning message will be shown if this command is used, since - new implementations should use ``listen-interface`` and - ``upstream-interface``. - -.. cfgcmd:: set service dhcp-relay listen-interface <interface> - - Interface for DHCP Relay Agent to listen for requests. - -.. cfgcmd:: set service dhcp-relay upstream-interface <interface> - - Interface for DHCP Relay Agent to forward requests out. - -.. cfgcmd:: set service dhcp-relay server <server> - - Configure IP address of the DHCP `<server>` which will handle the relayed - packets. - -.. cfgcmd:: set service dhcp-relay relay-options relay-agents-packets discard - - The router should discard DHCP packages already containing relay agent - information to ensure that only requests from DHCP clients are forwarded. - -.. cfgcmd:: set service dhcp-relay disable - - Disable dhcp-relay service. - -Options -------- - -.. cfgcmd:: set service dhcp-relay relay-options hop-count <count> - - Set the maximum hop `<count>` before packets are discarded. Range 0...255, - default 10. - -.. cfgcmd:: set service dhcp-relay relay-options max-size <size> - - Set maximum `<size>` of DHCP packets including relay agent information. If a - DHCP packet size surpasses this value it will be forwarded without appending - relay agent information. Range 64...1400, default 576. - -.. cfgcmd:: set service dhcp-relay relay-options relay-agents-packets - <append | discard | forward | replace> - - Four policies for reforwarding DHCP packets exist: - - * **append:** The relay agent is allowed to append its own relay information - to a received DHCP packet, disregarding relay information already present - in the packet. - - * **discard:** Received packets which already contain relay information will - be discarded. - - * **forward:** All packets are forwarded, relay information already present - will be ignored. - - * **replace:** Relay information already present in a packet is stripped and - replaced with the router's own relay information set. - -Example -======= - -* Listen for DHCP requests on interface ``eth1``. -* DHCP server is located at IPv4 address 10.0.1.4 on ``eth2``. -* Router receives DHCP client requests on ``eth1`` and relays them to the - server at 10.0.1.4 on ``eth2``. - -.. figure:: /_static/images/service_dhcp-relay01.* - :scale: 80 % - :alt: DHCP relay example - - DHCP relay example - -The generated configuration will look like: - -.. code-block:: none - - show service dhcp-relay - listen-interface eth1 - upstream-interface eth2 - server 10.0.1.4 - relay-options { - relay-agents-packets discard - } - -Also, for backwards compatibility this configuration, which uses generic -interface definition, is still valid: - -.. code-block:: none - - show service dhcp-relay - interface eth1 - interface eth2 - server 10.0.1.4 - relay-options { - relay-agents-packets discard - } - -Operation -========= - -.. opcmd:: restart dhcp relay-agent - - Restart DHCP relay service - -********** -IPv6 relay -********** - -.. _dhcp-relay:ipv6_configuration: - -Configuration -============= - -.. cfgcmd:: set service dhcpv6-relay listen-interface <interface> - - Set eth1 to be the listening interface for the DHCPv6 relay. - - Multiple interfaces may be specified. - -.. cfgcmd:: set service dhcpv6-relay upstream-interface <interface> - address <server> - - Specifies an upstream network `<interface>` from which replies from - `<server>` and other relay agents will be accepted. - -.. _dhcp-relay:ipv6_options: - -.. cfgcmd:: set service dhcpv6-relay disable - - Disable dhcpv6-relay service. - -.. _dhcp_relay:v6_options: - -Options -------- - -.. cfgcmd:: set service dhcpv6-relay max-hop-count <count> - - Set maximum hop count before packets are discarded, default: 10 - -.. cfgcmd:: set service dhcpv6-relay use-interface-id-option - - If this is set the relay agent will insert the interface ID. This option is - set automatically if more than one listening interfaces are in use. - -.. _dhcp-relay:ipv6_example: - -Example -======= - -* DHCPv6 requests are received by the router on `listening interface` ``eth1`` -* Requests are forwarded through ``eth2`` as the `upstream interface` -* External DHCPv6 server is at 2001:db8::4 - -.. figure:: /_static/images/service_dhcpv6-relay01.* - :scale: 80 % - :alt: DHCPv6 relay example - - DHCPv6 relay example - -The generated configuration will look like: - -.. code-block:: none - - commit - show service dhcpv6-relay - listen-interface eth1 { - } - upstream-interface eth2 { - address 2001:db8::4 - } - -.. _dhcp-relay:ipv6_op_cmd: - -Operation -========= - -.. opcmd:: restart dhcpv6 relay-agent - - Restart DHCPv6 relay agent immediately. diff --git a/docs/configuration/service/rst-dhcp-server.rst b/docs/configuration/service/rst-dhcp-server.rst deleted file mode 100644 index 09f40b37..00000000 --- a/docs/configuration/service/rst-dhcp-server.rst +++ /dev/null @@ -1,1087 +0,0 @@ -.. _dhcp-server: - -########### -DHCP Server -########### - -VyOS uses Kea DHCP server for both IPv4 and IPv6 address assignment. - -*********** -IPv4 server -*********** - -The network topology is declared by shared-network-name and the subnet -declarations. The DHCP service can serve multiple shared networks, with each -shared network having 1 or more subnets. Each subnet must be present on an -interface. A range can be declared inside a subnet to define a pool of dynamic -addresses. Multiple ranges can be defined and can contain holes. Static -mappings can be set to assign "static" addresses to clients based on their MAC -address. - -Configuration -============= - -.. cfgcmd:: set service dhcp-server hostfile-update - - Create DNS record per client lease, by adding clients to /etc/hosts file. - Entry will have format: `<shared-network-name>_<hostname>.<domain-name>` - -.. cfgcmd:: set service dhcp-server shared-network-name <name> option domain-name <domain-name> - - The domain-name parameter should be the domain name that will be appended to - the client's hostname to form a fully-qualified domain-name (FQDN) (DHCP - Option 015). - - This is the configuration parameter for the entire shared network definition. - All subnets will inherit this configuration item if not specified locally. - -.. cfgcmd:: set service dhcp-server shared-network-name <name> option domain-search <domain-name> - - The domain-name parameter should be the domain name used when completing DNS - request where no full FQDN is passed. This option can be given multiple times - if you need multiple search domains (DHCP Option 119). - - This is the configuration parameter for the entire shared network definition. - All subnets will inherit this configuration item if not specified locally. - -.. cfgcmd:: set service dhcp-server shared-network-name <name> option name-server <address> - - Inform client that the DNS server can be found at `<address>`. - - This is the configuration parameter for the entire shared network definition. - All subnets will inherit this configuration item if not specified locally. - Multiple DNS servers can be defined. - -.. cfgcmd:: set service dhcp-server shared-network-name <name> option - vendor-option <option-name> - - This configuration parameter lets you specify a vendor-option for the - entire shared network definition. All subnets will inherit this - configuration item if not specified locally. An example for Ubiquiti is - shown below: - -**Example:** - -Pass address of Unifi controller at ``172.16.100.1`` to all clients of ``NET1`` - -.. code-block:: none - - set service dhcp-server shared-network-name 'NET1' option vendor-option - ubiquiti '172.16.100.1' - -.. cfgcmd:: set service dhcp-server listen-address <address> - - This configuration parameter lets the DHCP server to listen for DHCP - requests sent to the specified address, it is only realistically useful for - a server whose only clients are reached via unicasts, such as via DHCP relay - agents. - -Individual Client Subnet -------------------------- - -.. cfgcmd:: set service dhcp-server shared-network-name <name> authoritative - - This says that this device is the only DHCP server for this network. If other - devices are trying to offer DHCP leases, this machine will send 'DHCPNAK' to - any device trying to request an IP address that is not valid for this - network. - -.. cfgcmd:: set service dhcp-server shared-network-name <name> subnet <subnet> - subnet-id <id> - - This configuration parameter is required and must be unique to each subnet. - It is required to map subnets to lease file entries. - -.. cfgcmd:: set service dhcp-server shared-network-name <name> subnet <subnet> - option default-router <address> - - This is a configuration parameter for the `<subnet>`, saying that as part of - the response, tell the client that the default gateway can be reached at - `<address>`. - -.. cfgcmd:: set service dhcp-server shared-network-name <name> subnet <subnet> - option name-server <address> - - This is a configuration parameter for the subnet, saying that as part of the - response, tell the client that the DNS server can be found at `<address>`. - - Multiple DNS servers can be defined. - -.. cfgcmd:: set service dhcp-server shared-network-name <name> subnet <subnet> - lease <time> - - Assign the IP address to this machine for `<time>` seconds. - - The default value is 86400 seconds which corresponds to one day. - -.. cfgcmd:: set service dhcp-server shared-network-name <name> subnet <subnet> - range <n> start <address> - - Create DHCP address range with a range id of `<n>`. DHCP leases are taken - from this pool. The pool starts at address `<address>`. - -.. cfgcmd:: set service dhcp-server shared-network-name <name> subnet <subnet> - range <n> stop <address> - - Create DHCP address range with a range id of `<n>`. DHCP leases are taken - from this pool. The pool stops with address `<address>`. - -.. cfgcmd:: set service dhcp-server shared-network-name <name> subnet <subnet> - exclude <address> - - Always exclude this address from any defined range. This address will never - be assigned by the DHCP server. - - This option can be specified multiple times. - -.. cfgcmd:: set service dhcp-server shared-network-name <name> subnet <subnet> - option domain-name <domain-name> - - The domain-name parameter should be the domain name that will be appended to - the client's hostname to form a fully-qualified domain-name (FQDN) (DHCP - Option 015). - -.. cfgcmd:: set service dhcp-server shared-network-name <name> subnet <subnet> - option domain-search <domain-name> - - The domain-name parameter should be the domain name used when completing DNS - request where no full FQDN is passed. This option can be given multiple times - if you need multiple search domains (DHCP Option 119). - -.. cfgcmd:: set service dhcp-server shared-network-name <name> subnet <subnet> - option vendor-option <option-name> - - This configuration parameter lets you specify a vendor-option for the - subnet specified within the shared network definition. An example for - Ubiquiti is shown below: - -**Example:** - -Create ``172.18.201.0/24`` as a subnet within ``NET1`` and pass address of -Unifi controller at ``172.16.100.1`` to clients of that subnet. - -.. code-block:: none - - set service dhcp-server shared-network-name 'NET1' subnet - '172.18.201.0/24' option vendor-option ubiquiti '172.16.100.1' - - -Dynamic DNS Update (RFC 2136) ------------------------------ - -VyOS DHCP service supports RFC-2136 DDNS protocol. Based on DHCP lease change -events, DHCP server generates DDNS update requests (defines as NameChangeRequests -or NCRs) and posts them to a compliant DNS server, that will update its name -database accordingly. - -VyOS built-in DNS Forwarder does not support DDNS, you will need an external DNS -server with RFC-2136 DDNS support. - -.. cfgcmd:: set service dhcp-server dynamic-dns-update - - Enables DDNS globally. - -**Behavioral settings** - -These settings can be configured on the global level and overridden on the scope -level, i.e. for individual shared networks or subnets. See examples below. - -.. cfgcmd:: set service dhcp-server dynamic-dns-update send-updates [ enable - | disable ] - - If set to ``enable`` on global level, updates for all scopes will be enabled, - except if explicitly set to ``disable`` on the scope level. If set to ``disable``, - updates will only be sent for scopes, where ``send-updates`` is explicity - set to ``enable``. - - This model is followed for a few behavioral settings below: if the option is - not set, the setting is inherited from the parent scope. You can override the - parent scope setting by setting the option explicitly. - -.. cfgcmd:: set service dhcp-server dynamic-dns-update override-no-update [ enable - | disable ] - - VyOS will ignore client request not to update DNS records and send DDNS - update requests regardless. - -.. cfgcmd:: set service dhcp-server dynamic-dns-update override-client-update [ enable - | disable ] - - VyOS will override client DDNS request settings and always update both - forward and reverse DNS records. - -.. cfgcmd:: set service dhcp-server dynamic-dns-update update-on-renew [ enable - | disable ] - - Issue DDNS update requests on DHCP lease renew. In busy networks this may - generate a lot of traffic. - -.. cfgcmd:: set service dhcp-server dynamic-dns-update conflict-resolution [ enable - | disable ] - - Use RFC-4703 conflict resolution. This algorithm helps in situation when - multiple clients reserve same IP addresses or advertise identical hostnames. - Should be used in most situations. - -.. cfgcmd:: set service dhcp-server dynamic-dns-update replace-client-name [ never - | always | when-present | when-not-present ] - - * **never**: use the name sent by the client. If the client didn't provide any, - do not generate one. This is the default behavior - - * **always**: always generate a name for the client - - * **when-present**: replace the name the client sent with a generated one, if - the client didn't send any, do not generate one - - * **when-not-present**: use the name sent by the client. If the client didn't - send any, generate one for the client - - The names are generated using ``generated-prefix``, ``qualifying-suffix`` and the - client's IP address string. - -.. cfgcmd:: set service dhcp-server dynamic-dns-update generated-prefix <prefix> - - Prefix used in client name generation. - -.. cfgcmd:: set service dhcp-server dynamic-dns-update qualifying-suffix <suffix> - - DNS suffix used in client name generation. - -.. cfgcmd:: set service dhcp-server dynamic-dns-update ttl-percent <0-100> - - TTL of the DNS record as a percentage of the DHCP lease time. - -.. cfgcmd:: set service dhcp-server dynamic-dns-update hostname-char-set - <character string> - - Characters, that are considered invalid in the client name. They will be replaced - with ``hostname-char-replacement`` string. - -.. cfgcmd:: set service dhcp-server dynamic-dns-update hostname-char-replacement - <character string> - - Replacement string for the invalid characters defined by ``hostname-char-set``. - -**TSIG keys definition** - -This is the global list of TSIG keys for DDNS updates. They need to be specified by -the name in the DNS domain definitions. - -.. cfgcmd:: set service dhcp-server dynamic-dns-update tsig-key <key-name> - algorithm <algorithm> - - Sets the algorithm for the TSIG key. Supported algorithms are ``hmac-md5``, - ``hmac-sha1``, ``hmac-sha224``, ``hmac-sha256``, ``hmac-sha384``, ``hmac-sha512`` - -.. cfgcmd:: set service dhcp-server dynamic-dns-update tsig-key <key-name> - secret <key-secret> - - base64-encoded TSIG key secret value - -**DNS domains definition** - -This is global configuration of DNS servers for the updatable forward and reverse -DNS domains. For every domain multiple DNS servers can be specified. - -.. cfgcmd:: set service dhcp-server dynamic-dns-update [forward|reverse]-domain - <domain-name> key-name <tsig-key-name> - - TSIG key used for the domain. - -.. cfgcmd:: set service dhcp-server dynamic-dns-update [forward|reverse]-domain - <domain-name> dns-server <number> address <ip-address> - - IP address of the DNS server. - -.. cfgcmd:: set service dhcp-server dynamic-dns-update [forward|reverse]-domain - <domain-name> dns-server <number> port <port> - - UDP port of the DNS server. ``53`` is the default. - -**Example:** - -Global configuration you will most likely want: - -.. code-block:: none - - set service dhcp-server dynamic-dns-update send-updates enable - set service dhcp-server dynamic-dns-update conflict-resolution enable - -Override the above configuration for a shared network NET1: - -.. code-block:: none - - set service dhcp-server shared-network-name 'NET1' dynamic-dns-update replace-client-name when-not-present - set service dhcp-server shared-network-name 'NET1' dynamic-dns-update generated-prefix ip - set service dhcp-server shared-network-name 'NET1' dynamic-dns-update qualifying-suffix mybigdomain.net - -And in a subnet within the same shared network: - -.. code-block:: none - - set service dhcp-server shared-network-name 'NET1' subnet '172.18.201.0/24' dynamic-dns-update qualifying-suffix mydomain.net - -Configure TSIG keys: - -.. code-block:: none - - set service dhcp-server dynamic-dns-update tsig-key mydomain-net algorithm hmac-sha256 - set service dhcp-server dynamic-dns-update tsig-key mydomain-net secret eWF5YW15bGl0dGxla2V5IQ== - set service dhcp-server dynamic-dns-update tsig-key reverse-172-18-201 algorithm hmac-sha256 - set service dhcp-server dynamic-dns-update tsig-key reverse-172-18-201 secret eWF5YW15YW5vdGhlcmxpdHRsZWtleSE= - -Configure DDNS domains: - -.. code-block:: none - - set service dhcp-server dynamic-dns-update forward-domain mydomain.net key-name mydomain-net - set service dhcp-server dynamic-dns-update forward-domain mydomain.net dns-server 1 address '172.18.0.254' - set service dhcp-server dynamic-dns-update forward-domain mydomain.net dns-server 1 port 1053 - set service dhcp-server dynamic-dns-update forward-domain mydomain.net dns-server 2 address '192.168.124.254' - set service dhcp-server dynamic-dns-update forward-domain mydomain.net dns-server 2 port 53 - set service dhcp-server dynamic-dns-update forward-domain 201.18.172.in-addr.arpa key-name reverse-172-18-201 - set service dhcp-server dynamic-dns-update reverse-domain 201.18.172.in-addr.arpa dns-server 1 address '172.18.0.254' - set service dhcp-server dynamic-dns-update reverse-domain 201.18.172.in-addr.arpa dns-server 1 port 1053 - set service dhcp-server dynamic-dns-update reverse-domain 201.18.172.in-addr.arpa dns-server 2 address '192.168.124.254' - set service dhcp-server dynamic-dns-update reverse-domain 201.18.172.in-addr.arpa dns-server 2 port 53 - - -High Availability ------------------ - -VyOS provides High Availability support for DHCP server. DHCP High -Availability can act in two different modes: - -* **Active-active**: both DHCP servers will respond to DHCP requests. If - ``mode`` is not defined, this is the default behavior. - -* **Active-passive**: only ``primary`` server will respond to DHCP requests. - If this server goes offline, then ``secondary`` server will take place. - -DHCP High Availability must be configured explicitly by the following -statements on both servers: - -.. cfgcmd:: set service dhcp-server high-availability mode [active-active - | active-passive] - - Define operation mode of High Availability feature. Default value if command - is not specified is `active-active` - -.. cfgcmd:: set service dhcp-server high-availability source-address <address> - - Local IP `<address>` used when communicating to the HA peer. - -.. cfgcmd:: set service dhcp-server high-availability remote <address> - - Remote peer IP `<address>` of the second DHCP server in this HA - cluster. - -.. cfgcmd:: set service dhcp-server high-availability name <name> - - Define the name of the peer server to establish and identify the HA (High Availability) connection. - - .. note:: Make sure the specified value does not conflict with the system host-name. - -.. cfgcmd:: set service dhcp-server high-availability status <primary - | secondary> - - The primary and secondary statements determines whether the server is primary - or secondary. - - .. note:: In order for the primary and the secondary DHCP server to keep - their lease tables in sync, they must be able to reach each other on TCP - port 647. If you have firewall rules in effect, adjust them accordingly. - - .. hint:: The dialogue between HA partners is neither encrypted nor - authenticated. Since most DHCP servers exist within an organisation's own - secure Intranet, this would be an unnecessary overhead. However, if you - have DHCP HA peers whose communications traverse insecure networks, - then we recommend that you consider the use of VPN tunneling between them - to ensure that the HA partnership is immune to disruption - (accidental or otherwise) via third parties. - -Static mappings ---------------- - -You can specify a static DHCP assignment on a per host basis. You will need the -MAC address of the station and your desired IP address. The address must be -inside the subnet definition but can be outside of the range statement. - -.. cfgcmd:: set service dhcp-server shared-network-name <name> subnet - <subnet> static-mapping <description> mac <address> - - Create a new DHCP static mapping named `<description>` which is valid for - the host identified by its MAC `<address>`. - -.. cfgcmd:: set service dhcp-server shared-network-name <name> subnet - <subnet> static-mapping <description> duid <identifier> - - Create a new DHCP static mapping named `<description>` which is valid for - the host identified by its DHCP unique identifier (DUID) `<identifier>`. - -.. cfgcmd:: set service dhcp-server shared-network-name <name> subnet - <subnet> static-mapping <description> ip-address <address> - - Static DHCP IP address assign to host identified by `<description>`. IP - address must be inside the `<subnet>` which is defined but can be outside - the dynamic range created with :cfgcmd:`set service dhcp-server - shared-network-name <name> subnet <subnet> range <n>`. If no ip-address is - specified, an IP from the dynamic pool is used. - - This is useful, for example, in combination with hostfile update. - - .. hint:: This is the equivalent of the host block in dhcpd.conf of - isc-dhcpd. - -**Example:** - -* IP address ``192.168.1.100`` shall be statically mapped to client named ``client1`` - -.. code-block:: none - - set service dhcp-server shared-network-name 'NET1' subnet 192.168.1.0/24 subnet-id 1 - set service dhcp-server shared-network-name 'NET1' subnet 192.168.1.0/24 static-mapping client1 ip-address 192.168.1.100 - set service dhcp-server shared-network-name 'NET1' subnet 192.168.1.0/24 static-mapping client1 mac aa:bb:11:22:33:00 - -The configuration will look as follows: - -.. code-block:: none - - show service dhcp-server shared-network-name NET1 - subnet 192.168.1.0/24 { - static-mapping client1 { - ip-address 192.168.1.100 - mac aa:bb:11:22:33:00 - } - subnet-id 1 - } - -Relay agent information (Option 82) ------------------------------------ - -Some DHCP relays support the injection of information into a DHCP request, depending on -where the request originated from. This is commonly used to determine the -behaviour of the DHCP server, based on the port/switch combination where the -request was first detected. I.e. the device plugged into a particular port (or -set of ports) always gets the same IP address (or range of IP addresses). This -information is usually included in the request using Option 82, hence this -is what we call this part of the configuration. - -This behaviour is controlled in two parts. First, "client classes" are defined -which determine which inputs match. Once a positive match has been found the -request is "tagged" with this client class. Second, when the DHCP server -processes the request it checks to see if the configuration has a client class -defined. If it does then that part of the configuration will override the others - -Client classes can be applied at either the subnet or range level, depending on -how you want the server to behave. - -**Client Class definition** - -.. cfgcmd:: set service dhcp-server client-class <name> relay-agent-information circuit-id - <value> - - Create a new client class (if not already defined) and set it to match on - the "Circuit ID" part of the Option 82 field in the DHCP request. This is - sub option "1" as specified by RFC 3046. The value specified here is either - interpreted as a raw hex value, if it starts with the prefix 0x, or ASCII text - otherwise. e.g. ``e1-5`` and ``0x65312d35`` are the same - -.. cfgcmd:: set service dhcp-server client-class <name> relay-agent-information remote-id - <value> - - Create a new client class (if not already defined) and set it to match on - the "Remote ID" part of the Option 82 field in the DHCP request. This is - sub option "2" as specified by RFC 3046. The value specified here is either - interpreted as a raw hex value, if it starts with the prefix 0x, or ASCII text - otherwise. e.g. ``10.100.0.41`` and ``0x31302e3130302e302e3431`` are the - same - -**Client Class application** - -.. cfgcmd:: set service dhcp-server shared-network-name <subnet-name> subnet - <CIDR> client-class <class-name> - - Applies the Client Class with the name `<class-name>` to the subnet `<subnet-name>`. - This means that whenever the client class matches a request it is always - routed to this subnet definition first. - -.. cfgcmd:: set service dhcp-server shared-network-name <subnet-name> subnet - <CIDR> range <range-name> client-class <class-name> - - Applies the Client Class with the name `<class-name>` to the range - `<range-name>` which belongs to subnet `<subnet-name>`. This means that whenever the - client class matches a request it is always routed to this range definition - first. - -NB: Kea (the DHCP server used by VyOS) is programmed to offer as many -alternatives as it can to repeated DHCP Discover requests. Some operating -systems (Notably Microsoft Windows) make multiple DHCP Discover requests before -settling on an address. This particularly seems to happen when the DHCP server -isn't set to authorative. This may explain why the address you espect isn't -being chosen. Wireshark is helpful in these situations. - -**Example:** - -The following configuration example will classify requests coming in on port -``e1-5`` from DHCP Relay ``192.0.2.1`` and make sure that they are allocated the -address ``192.0.2.4``. Any requests which do not match the circuit and remote ID -will, instead, be allocated from the range otherRange in the usual manner. - -NB: Both the Circuit ID and Remote ID fields are arbitrary free text. *Most* -switches set the Remote ID to the IP address of the management interface but -that should not be relied upon. Check the documentation of your DHCP Relay for -more detail or, as a measure of last resort, inspect the DHCP requests in -Wireshark. - -.. code-block:: none - - service { - dhcp-server { - client-class className { - relay-agent-information { - circuit-id e1-5 - remote-id 192.0.2.1 - } - } - shared-network-name test { - subnet 192.0.2.0/24 { - range classNameRange { - client-class className - start 192.0.2.4 - stop 192.0.2.4 - } - range otherRange { - start 192.0.2.5 - stop 192.0.2.100 - } - subnet-id 1 - } - } - } - } - -Options -======= - -.. list-table:: - :header-rows: 1 - :stub-columns: 0 - :widths: 12 7 23 40 20 - - * - Setting name - - Option number - - ISC-DHCP Option name - - Option description - - Multi - * - client-prefix-length - - 1 - - subnet-mask - - Specifies the clients subnet mask as per RFC 950. If unset, - subnet declaration is used. - - N - * - time-offset - - 2 - - time-offset - - Offset of the client's subnet in seconds from Coordinated - Universal Time (UTC) - - N - * - default-router - - 3 - - routers - - IPv4 address of router on the client's subnet - - N - * - time-server - - 4 - - time-servers - - RFC 868 time server IPv4 address - - Y - * - name-server - - 6 - - domain-name-servers - - DNS server IPv4 address - - Y - * - domain-name - - 15 - - domain-name - - Client domain name - - Y - * - ip-forwarding - - 19 - - ip-forwarding - - Enable IP forwarding on client - - N - * - ntp-server - - 42 - - ntp-servers - - IP address of NTP server - - Y - * - wins-server - - 44 - - netbios-name-servers - - NetBIOS over TCP/IP name server - - Y - * - server-identifier - - 54 - - dhcp-server-identifier - - IP address for DHCP server identifier - - N - * - bootfile-server - - siaddr - - next-server - - IPv4 address of next bootstrap server - - N - * - tftp-server-name - - 66 - - tftp-server-name - - Name or IPv4 address of TFTP server - - N - * - bootfile-name - - 67 - - bootfile-name, filename - - Bootstrap file name - - N - * - bootfile-size - - 13 - - boot-size - - Boot image length in 512-octet blocks - - N - * - smtp-server - - 69 - - smtp-server - - IP address of SMTP server - - Y - * - pop-server - - 70 - - pop-server - - IP address of POP3 server - - Y - * - domain-search - - 119 - - domain-search - - Client domain search - - Y - * - static-route - - 121, 249 - - rfc3442-static-route, windows-static-route - - Classless static route - - N - * - wpad-url - - 252 - - wpad-url, wpad-url code 252 = text - - Web Proxy Autodiscovery (WPAD) URL - - N - * - lease - - - - default-lease-time, max-lease-time - - Lease timeout in seconds (default: 86400) - - N - * - range - - - - range - - DHCP lease range - - Y - * - exclude - - - - - - IP address to exclude from DHCP lease range - - Y - * - failover - - - - - - DHCP failover parameters - - - * - static-mapping - - - - - - Name of static mapping - - Y - -Multi: can be specified multiple times. - -Example -======= - -Please see the :ref:`dhcp-dns-quick-start` configuration. - -.. _dhcp-server:v4_example_failover: - -High Availability ------------------ - -Configuration of a DHCP HA pair: - -* Setup DHCP HA for network 192.0.2.0/24 -* Use active-active HA mode. -* Default gateway and DNS server is at `192.0.2.254` -* The primary DHCP server named dhcp-primary uses address `192.168.189.252` -* The secondary DHCP server with named dhcp-secondary uses address `192.168.189.253` -* DHCP range spans from `192.168.189.10` - `192.168.189.250` - -Common configuration, valid for both primary and secondary node. - -.. code-block:: none - - set service dhcp-server shared-network-name NET-VYOS subnet 192.0.2.0/24 option default-router '192.0.2.254' - set service dhcp-server shared-network-name NET-VYOS subnet 192.0.2.0/24 option name-server '192.0.2.254' - set service dhcp-server shared-network-name NET-VYOS subnet 192.0.2.0/24 option domain-name 'vyos.net' - set service dhcp-server shared-network-name NET-VYOS subnet 192.0.2.0/24 range 0 start '192.0.2.10' - set service dhcp-server shared-network-name NET-VYOS subnet 192.0.2.0/24 range 0 stop '192.0.2.250' - set service dhcp-server shared-network-name NET-VYOS subnet 192.0.2.0/24 subnet-id '1' - - -**Primary** - -.. code-block:: none - - set service dhcp-server high-availability mode 'active-active' - set service dhcp-server high-availability source-address '192.168.189.252' - set service dhcp-server high-availability name 'dhcp-secondary' - set service dhcp-server high-availability remote '192.168.189.253' - set service dhcp-server high-availability status 'primary' - -**Secondary** - -.. code-block:: none - - set service dhcp-server high-availability mode 'active-active' - set service dhcp-server high-availability source-address '192.168.189.253' - set service dhcp-server high-availability name 'dhcp-primary' - set service dhcp-server high-availability remote '192.168.189.252' - set service dhcp-server high-availability status 'secondary' - -.. _dhcp-server:v4_example_raw: - -Operation Mode -============== - -.. opcmd:: show log dhcp server - - Show DHCP server daemon log file - -.. opcmd:: show log dhcp client - - Show logs from all DHCP client processes. - -.. opcmd:: show log dhcp client interface <interface> - - Show logs from specific `interface` DHCP client process. - -.. opcmd:: restart dhcp server - - Restart the DHCP server - -.. opcmd:: show dhcp server statistics - - Show the DHCP server statistics: - -.. code-block:: none - - vyos@vyos:~$ show dhcp server statistics - Pool Size Leases Available Usage - ----------- ------ -------- ----------- ------- - dhcpexample 99 2 97 2% - -.. opcmd:: show dhcp server statistics pool <pool> - - Show the DHCP server statistics for the specified pool. - -.. opcmd:: show dhcp server leases - - Show statuses of all active leases: - -.. code-block:: none - - vyos@vyos:~$ show dhcp server leases - IP Address MAC address State Lease start Lease expiration Remaining Pool Hostname Origin - -------------- ----------------- ------- ------------------- ------------------- ----------- -------- ---------- -------- - 192.168.11.134 00:50:79:66:68:09 active 2023/11/29 09:51:05 2023/11/29 10:21:05 0:24:10 LAN VPCS1 local - 192.168.11.133 50:00:00:06:00:00 active 2023/11/29 09:51:38 2023/11/29 10:21:38 0:24:43 LAN VYOS-6 local - 10.11.11.108 50:00:00:05:00:00 active 2023/11/29 09:51:43 2023/11/29 10:21:43 0:24:48 VIF-1001 VYOS5 local - 192.168.11.135 00:50:79:66:68:07 active 2023/11/29 09:55:16 2023/11/29 09:59:16 0:02:21 remote - vyos@vyos:~$ - -.. hint:: Static mappings aren't shown. To show all states, use - ``show dhcp server leases state all``. - -.. opcmd:: show dhcp server leases origin [local | remote] - - Show statuses of all active leases granted by local (this server) or - remote (failover server): - -.. code-block:: none - - vyos@vyos:~$ show dhcp server leases origin remote - IP Address MAC address State Lease start Lease expiration Remaining Pool Hostname Origin - -------------- ----------------- ------- ------------------- ------------------- ----------- -------- ---------- -------- - 192.168.11.135 00:50:79:66:68:07 active 2023/11/29 09:55:16 2023/11/29 09:59:16 0:02:21 remote - vyos@vyos:~$ - -.. opcmd:: show dhcp server leases pool <pool> - - Show only leases in the specified pool. - -.. code-block:: none - - vyos@vyos:~$ show dhcp server leases pool LAN - IP Address MAC address State Lease start Lease expiration Remaining Pool Hostname Origin - -------------- ----------------- ------- ------------------- ------------------- ----------- ------ ---------- -------- - 192.168.11.134 00:50:79:66:68:09 active 2023/11/29 09:51:05 2023/11/29 10:21:05 0:23:55 LAN VPCS1 local - 192.168.11.133 50:00:00:06:00:00 active 2023/11/29 09:51:38 2023/11/29 10:21:38 0:24:28 LAN VYOS-6 local - vyos@vyos:~$ - -.. opcmd:: show dhcp server leases sort <key> - - Sort the output by the specified key. Possible keys: ip, hardware_address, - state, start, end, remaining, pool, hostname (default = ip) - -.. opcmd:: show dhcp server leases state <state> - - Show only leases with the specified state. Possible states: all, active, - free, expired, released, abandoned, reset, backup (default = active) - - -*********** -IPv6 server -*********** - -VyOS also provides DHCPv6 server functionality which is described in this -section. - -.. _dhcp-server:v6_config: - -Configuration -============= - -.. cfgcmd:: set service dhcpv6-server preference <preference value> - - Clients receiving advertise messages from multiple servers choose the server - with the highest preference value. The range for this value is ``0...255``. - -.. cfgcmd:: set service dhcpv6-server shared-network-name <name> subnet <subnet> - subnet-id <id> - - This configuration parameter is required and must be unique to each subnet. - It is required to map subnets to lease file entries. - -.. cfgcmd:: set service dhcpv6-server shared-network-name <name> subnet - <prefix> lease-time {default | maximum | minimum} - - The default lease time for DHCPv6 leases is 24 hours. This can be changed by - supplying a ``default-time``, ``maximum-time`` and ``minimum-time``. All - values need to be supplied in seconds. - -.. cfgcmd:: set service dhcpv6-server shared-network-name <name> subnet - <prefix> option nis-domain <domain-name> - - A :abbr:`NIS (Network Information Service)` domain can be set to be used for - DHCPv6 clients. - -.. cfgcmd:: set service dhcpv6-server shared-network-name <name> subnet - <prefix> option nisplus-domain <domain-name> - - The procedure to specify a :abbr:`NIS+ (Network Information Service Plus)` - domain is similar to the NIS domain one: - -.. cfgcmd:: set service dhcpv6-server shared-network-name <name> subnet - <prefix> option nis-server <address> - - Specify a NIS server address for DHCPv6 clients. - -.. cfgcmd:: set service dhcpv6-server shared-network-name <name> subnet - <prefix> option nisplus-server <address> - - Specify a NIS+ server address for DHCPv6 clients. - -.. cfgcmd:: set service dhcpv6-server shared-network-name <name> subnet - <prefix> option sip-server <address | fqdn> - - Specify a :abbr:`SIP (Session Initiation Protocol)` server by IPv6 - address of Fully Qualified Domain Name for all DHCPv6 clients. - -.. cfgcmd:: set service dhcpv6-server shared-network-name <name> subnet - <prefix> option sntp-server-address <address> - - A SNTP server address can be specified for DHCPv6 clients. - -Prefix Delegation ------------------ - -To hand out individual prefixes to your clients the following configuration is -used: - - -.. cfgcmd:: set service dhcpv6-server shared-network-name <name> subnet - <prefix> prefix-delegation prefix <pd-prefix> prefix-length <lenght> - - Delegate prefixes from `<pd-prefix>` to clients in subnet `<prefix>`. Range - is defined by `<lenght>` in bits, 32 to 64. - -.. cfgcmd:: set service dhcpv6-server shared-network-name <name> subnet - <prefix> prefix-delegation prefix <pd-prefix> delegated-length <lenght> - - Hand out prefixes of size `<length>` in bits from `<pd-prefix>` to clients - in subnet `<prefix>` when the request for prefix delegation. - -.. cfgcmd:: set service dhcpv6-server shared-network-name <name> subnet - <prefix> prefix-delegation prefix <pd-prefix> excluded-prefix <exclude-prefix> - - Exclude `<exclude-prefix>` from `<pd-prefix>`. - - -.. cfgcmd:: set service dhcpv6-server shared-network-name <name> subnet - <prefix> prefix-delegation prefix <pd-prefix> excluded-prefix-length <length> - - Define lenght of exclude prefix in `<pd-prefix>`. - -**Example:** - -* A shared network named ``PD-NET`` serves subnet ``2001:db8::/64``. -* It is connected to ``eth1``. -* Address pool shall be ``2001:db8::100`` through ``2001:db8::199``. -* It hands out prefixes ``2001:db8:0:10::/64`` through ``2001:db8:0:1f::/64``. - -.. code-block:: none - - set service dhcpv6-server shared-network-name 'PD-NET' interface 'eth1' - set service dhcpv6-server shared-network-name 'PD-NET' subnet 2001:db8::/64 range 1 start 2001:db8::100 - set service dhcpv6-server shared-network-name 'PD-NET' subnet 2001:db8::/64 range 1 stop 2001:db8::199 - set service dhcpv6-server shared-network-name 'PD-NET' subnet 2001:db8::/64 prefix-delegation prefix 2001:db8:0:10:: delegated-length '64' - set service dhcpv6-server shared-network-name 'PD-NET' subnet 2001:db8::/64 prefix-delegation prefix 2001:db8:0:10:: prefix-length '60' - set service dhcpv6-server shared-network-name 'PD-NET' subnet 2001:db8::/64 subnet-id 1 - -Address pools -------------- - -DHCPv6 address pools must be configured for the system to act as a DHCPv6 -server. The following example describes a common scenario. - -**Example:** - -* A shared network named ``NET1`` serves subnet ``2001:db8::/64`` -* It is connected to ``eth1`` -* DNS server is located at ``2001:db8::ffff`` -* Address pool shall be ``2001:db8::100`` through ``2001:db8::199``. -* Lease time will be left at the default value which is 24 hours - -.. code-block:: none - - set service dhcpv6-server shared-network-name 'NET' interface 'eth1' - set service dhcpv6-server shared-network-name 'NET1' subnet 2001:db8::/64 range 1 start 2001:db8::100 - set service dhcpv6-server shared-network-name 'NET1' subnet 2001:db8::/64 range 1 stop 2001:db8::199 - set service dhcpv6-server shared-network-name 'NET1' subnet 2001:db8::/64 option name-server 2001:db8::ffff - set service dhcpv6-server shared-network-name 'NET1' subnet 2001:db8::/64 subnet-id 1 - -The configuration will look as follows: - -.. code-block:: none - - show service dhcpv6-server - shared-network-name NET1 { - subnet 2001:db8::/64 { - range 1 { - start 2001:db8::100 - stop 2001:db8::199 - } - option { - name-server 2001:db8::ffff - } - subnet-id 1 - } - } - -.. _dhcp-server:v6_static_mapping: - -Static mappings ---------------- - -In order to map specific IPv6 addresses to specific hosts static mappings can -be created. The following example explains the process. - -**Example:** - -* IPv6 address ``2001:db8::101`` shall be statically mapped -* IPv6 prefix ``2001:db8:0:101::/64`` shall be statically mapped -* Host specific mapping shall be named ``client1`` - -.. hint:: The identifier is the device's DUID: colon-separated hex list (as - used by isc-dhcp option dhcpv6.client-id). If the device already has a - dynamic lease from the DHCPv6 server, its DUID can be found with ``show - service dhcpv6 server leases``. The DUID begins at the 5th octet (after the - 4th colon) of IAID_DUID. - -.. code-block:: none - - set service dhcpv6-server shared-network-name 'NET1' subnet 2001:db8::/64 static-mapping client1 ipv6-address 2001:db8::101 - set service dhcpv6-server shared-network-name 'NET1' subnet 2001:db8::/64 static-mapping client1 ipv6-prefix 2001:db8:0:101::/64 - set service dhcpv6-server shared-network-name 'NET1' subnet 2001:db8::/64 static-mapping client1 duid 00:01:00:01:12:34:56:78:aa:bb:cc:dd:ee:ff - -The configuration will look as follows: - -.. stop_vyoslinter (00:01:00:01:12:34:56:78:aa:bb:cc:dd:ee:ff false positive) - -.. code-block:: none - - show service dhcpv6-server shared-network-name NET1 - subnet 2001:db8::/64 { - static-mapping client1 { - duid 00:01:00:01:12:34:56:78:aa:bb:cc:dd:ee:ff - ipv6-address 2001:db8::101 - ipv6-prefix 2001:db8:0:101::/64 - } - } - -.. start_vyoslinter - -.. _dhcp-server:v6_op_cmd: - -Operation Mode -============== - -.. opcmd:: show log dhcpv6 server - - Show DHCPv6 server daemon log file - -.. opcmd:: show log dhcpv6 client - - Show logs from all DHCPv6 client processes. - -.. opcmd:: show log dhcpv6 client interface <interface> - - Show logs from specific `interface` DHCPv6 client process. - -.. opcmd:: restart dhcpv6 server - - To restart the DHCPv6 server - -.. opcmd:: show dhcpv6 server leases - - Shows status of all assigned leases: - -.. code-block:: none - - vyos@vyos:~$ show dhcpv6 server leases - IPv6 address State Last communication Lease expiration Remaining Type Pool DUID - ---------------- ------- -------------------- ------------------- ----------- ----- -------- -------------------------------------------- - 2001:db8::101 active 2019/12/05 19:40:10 2019/12/06 07:40:10 11:45:21 IA_NA NET1 98:76:54:32:00:01:00:01:12:34:56:78:aa:bb:cc:dd:ee:ff - 2001:db8::102 active 2019/12/05 14:01:23 2019/12/06 02:01:23 6:06:34 IA_NA NET1 87:65:43:21:00:01:00:01:11:22:33:44:fa:fb:fc:fd:fe:ff - 2001:db8:10::/64 active 2019/12/05 23:20:10 2019/12/06 11:40:10 11:45:21 IA_PD PD-NET1 98:76:54:32:00:01:00:01:12:34:56:78:aa:bb:cc:dd:ee:ff - - -.. hint:: Static mappings aren't shown. To show all states, use ``show dhcp - server leases state all``. - -.. opcmd:: show dhcpv6 server leases pool <pool> - - Show only leases in the specified pool. - -.. opcmd:: show dhcpv6 server leases sort <key> - - Sort the output by the specified key. Possible keys: expires, iaid_duid, ip, - last_comm, pool, remaining, state, type (default = ip) - -.. opcmd:: show dhcpv6 server leases state <state> - - Show only leases with the specified state. Possible states: abandoned, - active, all, backup, expired, free, released, reset (default = active) diff --git a/docs/configuration/service/rst-dns.rst b/docs/configuration/service/rst-dns.rst deleted file mode 100644 index 365e7885..00000000 --- a/docs/configuration/service/rst-dns.rst +++ /dev/null @@ -1,511 +0,0 @@ -.. _dns-forwarding: - -############## -DNS Forwarding -############## - -Configuration -============= - -VyOS provides DNS infrastructure for small networks. It is designed to be -lightweight and have a small footprint, suitable for resource constrained -routers and firewalls. For this we utilize PowerDNS recursor. - -The VyOS DNS forwarder does not require an upstream DNS server. It can serve as -a full recursive DNS server - but it can also forward queries to configurable -upstream DNS servers. By not configuring any upstream DNS servers you also -avoid being tracked by the provider of your upstream DNS server. - -.. cfgcmd:: set service dns forwarding system - - Forward incoming DNS queries to the DNS servers configured under the ``system - name-server`` nodes. - -.. cfgcmd:: set service dns forwarding dhcp <interface> - - Interfaces whose DHCP client nameservers to forward requests to. - -.. cfgcmd:: set service dns forwarding name-server <address> port <port> - - Send all DNS queries to the IPv4/IPv6 DNS server specified under `<address>` - on optional port specified under `<port>`. The port defaults to 53. You can - configure multiple nameservers here. - -.. cfgcmd:: set service dns forwarding domain <domain-name> name-server <address> - - Forward received queries for a particular domain - (specified via `domain-name`) to a given nameserver. Multiple nameservers - can be specified. You can use this feature for a DNS split-horizon - configuration. - - .. note:: This also works for reverse-lookup zones (``18.172.in-addr.arpa``). - -.. cfgcmd:: set service dns forwarding domain <domain-name> addnta - - Add NTA (negative trust anchor) for this domain. This must be set if the - domain does not support DNSSEC. - -.. cfgcmd:: set service dns forwarding domain <domain-name> recursion-desired - - Set the "recursion desired" bit in requests to the upstream nameserver. - -.. cfgcmd:: set service dns forwarding allow-from <network> - - Given the fact that open DNS recursors could be used on DDoS amplification - attacks, you must configure the networks which are allowed to use this - recursor. A network of ``0.0.0.0/0`` or ``::/0`` would allow all IPv4 and - IPv6 networks to query this server. This is generally a bad idea. - -.. cfgcmd:: set service dns forwarding dnssec - <off | process-no-validate | process | log-fail | validate> - - The PowerDNS recursor has 5 different levels of DNSSEC processing, which can - be set with the dnssec setting. In order from least to most processing, these - are: - - * **off** In this mode, no DNSSEC processing takes place. The recursor will - not set the DNSSEC OK (DO) bit in the outgoing queries and will ignore the - DO and AD bits in queries. - - * **process-no-validate** In this mode the recursor acts as a "security - aware, non-validating" nameserver, meaning it will set the DO-bit on - outgoing queries and will provide DNSSEC related RRsets (NSEC, RRSIG) to - clients that ask for them (by means of a DO-bit in the query), except for - zones provided through the auth-zones setting. It will not do any - validation in this mode, not even when requested by the client. - - * **process** When dnssec is set to process the behavior is similar to - process-no-validate. However, the recursor will try to validate the data - if at least one of the DO or AD bits is set in the query; in that case, - it will set the AD-bit in the response when the data is validated - successfully, or send SERVFAIL when the validation comes up bogus. - - * **log-fail** In this mode, the recursor will attempt to validate all data - it retrieves from authoritative servers, regardless of the client's DNSSEC - desires, and will log the validation result. This mode can be used to - determine the extra load and amount of possibly bogus answers before - turning on full-blown validation. Responses to client queries are the same - as with process. - - * **validate** The highest mode of DNSSEC processing. In this mode, all - queries will be validated and will be answered with a SERVFAIL in case of - bogus data, regardless of the client's request. - - .. note:: The popular Unix/Linux ``dig`` tool sets the AD-bit in the query. - This might lead to unexpected query results when testing. Set ``+noad`` - on the ``dig`` command line when this is the case. - - .. note:: The ``CD``-bit is honored correctly for process and validate. For - log-fail, failures will be logged too. - -.. cfgcmd:: set service dns forwarding ignore-hosts-file - - Do not use the local ``/etc/hosts`` file in name resolution. VyOS DHCP - server will use this file to add resolvers to assigned addresses. - -.. cfgcmd:: set service dns forwarding cache-size <0-2147483647> - - Maximum number of DNS cache entries. 1 million per CPU core will generally - suffice for most installations. - - This defaults to 10000. - -.. cfgcmd:: set service dns forwarding negative-ttl <0-7200> - - A query for which there is authoritatively no answer is cached to quickly - deny a record's existence later on, without putting a heavy load on the - remote server. In practice, caches can become saturated with hundreds of - thousands of hosts which are tried only once. - - This setting, which defaults to 3600 seconds, puts a maximum on the amount - of time negative entries are cached. - -.. cfgcmd:: set service dns forwarding timeout <10-60000> - - The number of milliseconds to wait for a remote authoritative server to - respond before timing out and responding with SERVFAIL. - - This setting defaults to 1500 and is valid between 10 and 60000. - -.. cfgcmd:: set service dns forwarding listen-address <address> - - The local IPv4 or IPv6 addresses to bind the DNS forwarder to. The forwarder - will listen on this address for incoming connections. - -.. cfgcmd:: set service dns forwarding source-address <address> - - The local IPv4 or IPv6 addresses to use as a source address for sending queries. - The forwarder will send forwarded outbound DNS requests from this address. - -.. cfgcmd:: set service dns forwarding no-serve-rfc1918 - - This makes the server authoritatively not aware of: 10.in-addr.arpa, - 168.192.in-addr.arpa, 16-31.172.in-addr.arpa, which enabling upstream - DNS server(s) to be used for reverse lookups of these zones. - -Authoritative zones -------------------- - -The VyOS DNS forwarder can also be configured to host authoritative records for a domain. - -.. cfgcmd:: set service dns forwarding authoritative-domain <domain-name> disable - - Disable hosting authoritative zone for `<domain-name>` without deleting from - configuration. - -.. cfgcmd:: set service dns forwarding authoritative-domain <domain-name> records <type> - <name> disable - - Disable specific record without deleting it from configuration. - -.. cfgcmd:: set service dns forwarding authoritative-domain <domain-name> records <type> - <name> ttl <seconds> - - Set the :abbr:`TTL (Time-to-live)` for the record in seconds. Default is 300 seconds. - -Record types -^^^^^^^^^^^^ - -Below are a list of record types available to be configured within VyOS. Some records -support special `<name>` keywords: - -* ``@`` Use @ as record name to set the record for the root domain. - -* ``any`` Use any as record name to configure the record as a wildcard. - -.. cfgcmd:: set service dns forwarding authoritative-domain <domain-name> records - a <name> address <x.x.x.x> - - Set an :abbr:`A (Address)` record. Supports ``@`` and ``any`` keywords. - -.. cfgcmd:: set service dns forwarding authoritative-domain <domain-name> records - aaaa <name> address <h:h:h:h:h:h:h:h> - - Set an :abbr:`AAAA (IPv6 Address)` record. Supports ``@`` and ``any`` keywords. - -.. cfgcmd:: set service dns forwarding authoritative-domain <domain-name> records - cname <name> target <target-domain-name> - - Set an :abbr:`CNAME (Canonical name)` record. Supports ``@`` keyword. - -.. cfgcmd:: set service dns forwarding authoritative-domain <domain-name> records - naptr <name> rule <rule-number> <option> <value> - - Set an :abbr:`NAPTR (Naming authority pointer)` record. Supports ``@`` keyword. - NAPTR records support the following options: - - * **lookup-a** A Flag. - - * **lookup-srv** S flag. - - * **order** Rule order. Requires `<value>`. - - * **preference** Rule preference. Requires `<value>`. Defaults to 0 if not set. - - * **protocol-specific** P flag. - - * **regexp** Regular expression. Requires `<value>`. - - * **replacement** Replacement DNS name. - - * **resolve-uri** U flag. - - * **service** Service type. Requires `<value>`. - -.. cfgcmd:: set service dns forwarding authoritative-domain <domain-name> records - ns <name> target <target-name> - - Set an :abbr:`NS (Nameserver)` record. - -.. cfgcmd:: set service dns forwarding authoritative-domain <domain-name> records - ptr <name> target <target-name> - - Set an :abbr:`PTR (Pointer record)` record. Supports ``@`` keyword. - -.. cfgcmd:: set service dns forwarding authoritative-domain <domain-name> records - spf <name> value <value> - - Set an :abbr:`SPF (Sender policy framework)` record. Supports ``@`` keyword. - -.. cfgcmd:: set service dns forwarding authoritative-domain <domain-name> records - srv <name> entry <entry-number> [hostname | port | priority | weight] <value> - - Set an :abbr:`SRV (Service)` record. Supports ``@`` keyword. - -.. cfgcmd:: set service dns forwarding authoritative-domain <domain-name> records - txt <name> value <value> - - Set an :abbr:`TXT (Text)` record. Supports ``@`` keyword. - -Example -======= - -A VyOS router with two interfaces - eth0 (WAN) and eth1 (LAN) - is required to -implement a split-horizon DNS configuration for example.com. - -In this scenario: - -* All DNS requests for example.com must be forwarded to a DNS server - at 192.0.2.254 and 2001:db8:cafe::1 -* All other DNS requests will be forwarded to a different set of DNS servers at - 192.0.2.1, 192.0.2.2, 2001:db8::1:ffff and 2001:db8::2:ffff -* The VyOS DNS forwarder will only listen for requests on the eth1 (LAN) - interface addresses - 192.168.1.254 for IPv4 and 2001:db8::ffff for IPv6 -* The VyOS DNS forwarder will only accept lookup requests from the - LAN subnets - 192.168.1.0/24 and 2001:db8::/64 -* The VyOS DNS forwarder will pass reverse lookups for 10.in-addr.arpa, - 168.192.in-addr.arpa, 16-31.172.in-addr.arpa zones to upstream server. - -.. code-block:: none - - set service dns forwarding domain example.com name-server 192.0.2.254 - set service dns forwarding domain example.com name-server 2001:db8:cafe::1 - set service dns forwarding name-server 192.0.2.1 - set service dns forwarding name-server 192.0.2.2 - set service dns forwarding name-server 192.0.2.3 port 853 - set service dns forwarding name-server 2001:db8::1:ffff - set service dns forwarding name-server 2001:db8::2:ffff - set service dns forwarding name-server 2001:db8::3:ffff port 8053 - set service dns forwarding listen-address 192.168.1.254 - set service dns forwarding listen-address 2001:db8::ffff - set service dns forwarding allow-from 192.168.1.0/24 - set service dns forwarding allow-from 2001:db8::/64 - set service dns forwarding no-serve-rfc1918 - -Operation -========= - -.. opcmd:: reset dns forwarding <all | domain> - - Resets the local DNS forwarding cache database. You can reset the cache - for all entries or only for entries to a specific domain. - -.. opcmd:: restart dns forwarding - - Restarts the DNS recursor process. This also invalidates the local DNS - forwarding cache. - - -.. _dynamic-dns: - -########### -Dynamic DNS -########### - -VyOS is able to update a remote DNS record when an interface gets a new IP -address. In order to do so, VyOS includes ddclient_, a Perl script written for -this only one purpose. - -ddclient_ uses two methods to update a DNS record. The first one will send -updates directly to the DNS daemon, in compliance with :rfc:`2136`. The second -one involves a third party service, like DynDNS.com or any other such -service provider. This method uses HTTP requests to transmit the new IP address. You -can configure both in VyOS. - -.. _dns:dynamic_config: - -Configuration -============= - -:rfc:`2136` Based ------------------ - -.. cfgcmd:: set service dns dynamic name <service-name> address interface <interface> - - Create new dynamic DNS update configuration which will update the IP - address assigned to `<interface>` on the service you configured under - `<service-name>`. - -.. cfgcmd:: set service dns dynamic name <service-name> description <text> - - Set description `<text>` for dynamic DNS service being configured. - -.. cfgcmd:: set service dns dynamic name <service-name> key <filename> - - File identified by `<filename>` containing the TSIG authentication key for RFC2136 - nsupdate on remote DNS server. - -.. cfgcmd:: set service dns dynamic name <service-name> server <server> - - Configure the DNS `<server>` IP/FQDN used when updating this dynamic - assignment. - -.. cfgcmd:: set service dns dynamic name <service-name> zone <zone> - - Configure DNS `<zone>` to be updated. - -.. cfgcmd:: set service dns dynamic name <service-name> host-name <record> - - Configure DNS `<record>` which should be updated. This can be set multiple times. - -.. cfgcmd:: set service dns dynamic name <service-name> ttl <ttl> - - Configure optional TTL value on the given resource record. This defaults to - 600 seconds. - -.. cfgcmd:: set service dns dynamic interval <60-3600> - - Specify interval in seconds to wait between Dynamic DNS updates. - The default is 300 seconds. - -.. _dns:dynamic_example: - -Example -^^^^^^^ - -* Register DNS record ``example.vyos.io`` on DNS server ``ns1.vyos.io`` -* Use auth key file at ``/config/auth/my.key`` -* Set TTL to 300 seconds - -.. code-block:: none - - # Configuration commands entered: - # - set service dns dynamic name 'VyOS-DNS' address interface 'eth0' - set service dns dynamic name 'VyOS-DNS' description 'RFC 2136 dynamic dns service' - set service dns dynamic name 'VyOS-DNS' key '/config/auth/my.key' - set service dns dynamic name 'VyOS-DNS' server 'ns1.vyos.io' - set service dns dynamic name 'VyOS-DNS' zone 'vyos.io' - set service dns dynamic name 'VyOS-DNS' host-name 'example.vyos.io' - set service dns dynamic name 'VyOS-DNS' protocol 'nsupdate' - set service dns dynamic name 'VyOS-DNS' ttl '300' - - # Resulting config: - # - vyos@vyos# show service dns dynamic - name VyOS-DNS { - address { - interface eth0 - } - description "RFC 2136 dynamic dns service" - host-name example.vyos.io - key /config/auth/my.key - protocol nsupdate - server ns1.vyos.io - ttl 300 - zone vyos.io - } - -This will render the following ddclient_ configuration entry: - -.. code-block:: none - - # ddclient configuration for interface "eth0": - # - - # Web service dynamic DNS configuration for VyOS-DNS: [nsupdate, example.vyos.io] - use=if, \ - if=eth0, \ - protocol=nsupdate, \ - server=ns1.vyos.io, \ - zone=vyos.io, \ - password='/config/auth/my.key', \ - ttl=300 \ - example.vyos.io - -.. note:: You can also keep different DNS zone updated. Just create a new - config node: ``set service dns dynamic interface <interface> rfc2136 - <other-service-name>`` - -HTTP based services -------------------- - -VyOS is also able to use any service relying on protocols supported by ddclient. - -To use such a service, one must define a login, password, one or multiple -hostnames, protocol and server. - -.. cfgcmd:: set service dns dynamic name <service-name> address interface <interface> - - Create new dynamic DNS update configuration which will update the IP - address assigned to `<interface>` on the service you configured under - `<service-name>`. - -.. cfgcmd:: set service dns dynamic name <service-name> description <text> - - Set description `<text>` for dynamic DNS service being configured. - -.. cfgcmd:: set service dns dynamic name <service-name> host-name <hostname> - - Setup the dynamic DNS hostname `<hostname>` associated with the DynDNS - provider identified by `<service-name>`. - -.. cfgcmd:: set service dns dynamic name <service-name> username <username> - - Configure `<username>` used when authenticating the update request for - DynDNS service identified by `<service-name>`. - -.. cfgcmd:: set service dns dynamic name <service-name> password <password> - - Configure `<password>` used when authenticating the update request for - DynDNS service identified by `<service-name>`. - -.. cfgcmd:: set service dns dynamic name <service-name> protocol <protocol> - - When a ``custom`` DynDNS provider is used, the protocol used for communicating - to the provider must be specified under `<protocol>`. See the embedded - completion helper when entering above command for available protocols. - -.. cfgcmd:: set service dns dynamic name <service-name> server <server> - - When a ``custom`` DynDNS provider is used the `<server>` where update - requests are being sent to must be specified. - -.. cfgcmd:: set service dns dynamic name <service-name> ip-version 'ipv6' - - Allow explicit IPv6 address for the interface. - - -Example: -^^^^^^^^ - -Use deSEC (dedyn.io) as your preferred provider: - -.. code-block:: none - - set service dns dynamic name dedyn description 'deSEC dynamic dns service' - set service dns dynamic name dedyn username 'myusername' - set service dns dynamic name dedyn password 'mypassword' - set service dns dynamic name dedyn host-name 'myhostname.dedyn.io' - set service dns dynamic name dedyn protocol 'dyndns2' - set service dns dynamic name dedyn server 'update.dedyn.io' - set service dns dynamic name dedyn address interface 'eth0' - -.. note:: Multiple services can be used per interface. Just specify as many - services per interface as you like! - -Example IPv6 only: -^^^^^^^^^^^^^^^^^^ - -.. code-block:: none - - set service dns dynamic name dedyn description 'deSEC ipv6 dynamic dns service' - set service dns dynamic name dedyn username 'myusername' - set service dns dynamic name dedyn password 'mypassword' - set service dns dynamic name dedyn host-name 'myhostname.dedyn.io' - set service dns dynamic name dedyn protocol 'dyndns2' - set service dns dynamic name dedyn ip-version 'ipv6' - set service dns dynamic name dedyn server 'update6.dedyn.io' - set service dns dynamic name dedyn address interface 'eth0' - - -Running Behind NAT ------------------- - -By default, ddclient_ will update a dynamic dns record using the IP address -directly attached to the interface. If your VyOS instance is behind NAT, your -record will be updated to point to your internal IP. - -ddclient_ has another way to determine the WAN IP address. This is controlled -by: - -.. cfgcmd:: set service dns dynamic name <service-name> address web <url> - - Use configured `<url>` to determine your IP address. ddclient_ will load - `<url>` and tries to extract your IP address from the response. - -.. cfgcmd:: set service dns dynamic name <service-name> address web skip <pattern> - - ddclient_ will skip any address located before the string set in `<pattern>`. - -.. _ddclient: https://github.com/ddclient/ddclient diff --git a/docs/configuration/service/rst-eventhandler.rst b/docs/configuration/service/rst-eventhandler.rst deleted file mode 100644 index 9f4ebb04..00000000 --- a/docs/configuration/service/rst-eventhandler.rst +++ /dev/null @@ -1,159 +0,0 @@ -.. _event-handler: - -############# -Event Handler -############# - -********************************* -Event Handler Technology Overview -********************************* - -Event handler allows you to execute scripts when a string that matches -a regex or a regex with a service name appears in journald logs. You -can pass variables, arguments, and a full matching string to the script. - - -****************************** -How to configure Event Handler -****************************** - - `1. Create an event handler`_ - - `2. Add regex to the script`_ - - `3. Add a full path to the script`_ - - `4. Add optional parameters`_ - -********************************* -Event Handler Configuration Steps -********************************* - -1. Create an event handler -========================== - - .. cfgcmd:: set service event-handler event <event-handler name> - - This is an optional command because the event handler will be - automatically created after any of the next commands. - - -2. Add regex to the script -=========================================== - -.. stop_vyoslinter - - .. 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> - -.. start_vyoslinter - - This is a mandatory command. Sets the full path to the script. - The script file must be executable. - - - -4. Add optional parameters -========================== - -.. 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> - -.. 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> - -.. start_vyoslinter - - This is an optional command. Adds arguments to the script. - Arguments must be separated by spaces. - - .. note:: We don't recommend to use arguments. Using environments - is more preferable. - - -******* -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 '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) - -.. start_vyoslinter diff --git a/docs/configuration/service/rst-https.rst b/docs/configuration/service/rst-https.rst deleted file mode 100644 index e72e8e8b..00000000 --- a/docs/configuration/service/rst-https.rst +++ /dev/null @@ -1,124 +0,0 @@ -.. _http-api: - -######## -HTTP API -######## - -VyOS provide an HTTP API. You can use it to execute op-mode commands, -update VyOS, set or delete config. - -Please take a look at the :ref:`vyosapi` page for an detailed how-to. - -************* -Configuration -************* - -.. cfgcmd:: set service https allow-client address <address> - - Only allow certain IP addresses or prefixes to access the https - webserver. - -.. cfgcmd:: set service https certificates ca-certificate <name> - - Use CA certificate from PKI subsystem - -.. cfgcmd:: set service https certificates certificate <name> - - Use certificate from PKI subsystem - -.. cfgcmd:: set service https certificates dh-params <name> - - Use :abbr:`DH (Diffie–Hellman)` parameters from PKI subsystem. - Must be at least 2048 bits in length. - -.. cfgcmd:: set service https listen-address <address> - - Webserver should only listen on specified IP address - -.. cfgcmd:: set service https port <number> - - Webserver should listen on specified port. - - Default: 443 - -.. cfgcmd:: set service https enable-http-redirect - - Enable automatic redirect from http to https. - -.. cfgcmd:: set service https tls-version <1.2 | 1.3> - - Select TLS version used. - - This defaults to both 1.2 and 1.3. - -.. cfgcmd:: set service https vrf <name> - - Start Webserver in given VRF. - -.. cfgcmd:: set service https request-body-size-limit <size> - - Set the maximum request body size in megabytes. Default is 1MB. - -API -=== - -.. cfgcmd:: set service https api keys id <name> key <apikey> - - Set a named api key. Every key has the same, full permissions - on the system. - -REST -==== - -.. cfgcmd:: set service https api rest - - Enable REST API - -.. cfgcmd:: set service https api rest debug - - To enable debug messages. Available via :opcmd:`show log` or - :opcmd:`monitor log` - -.. cfgcmd:: set service https api rest strict - - Enforce strict path checking. - -GraphQL -======= - -.. cfgcmd:: set service https api graphql introspection - - Enable GraphQL Schema introspection. - -.. note:: Do not leave introspection enabled in production, it is a security risk. - -.. cfgcmd:: set service https api graphql authentication type <key | token> - - Set the authentication type for GraphQL, default option is key. Available options are: - - * ``key`` use API keys configured in ``service https api keys`` - - * ``token`` use JWT tokens. - -.. cfgcmd:: set service https api graphql authentication expiration - - Set the lifetime for JWT tokens in seconds. Default is 3600 seconds. - -.. cfgcmd:: set service https api graphql authentication secret-length - - Set the byte length of the JWT secret. Default is 32. - -.. cfgcmd:: set service https api graphql cors allow-origin <origin> - - Allow cross-origin requests from `<origin>`. - -********************* -Example Configuration -********************* - -Setting REST API and an API-KEY is the minimal configuration to get a working API Endpoint. - -.. code-block:: none - - set service https api keys id MY-HTTPS-API-ID key MY-HTTPS-API-PLAINTEXT-KEY - set service https api rest diff --git a/docs/configuration/service/rst-index.rst b/docs/configuration/service/rst-index.rst deleted file mode 100644 index fb6f8413..00000000 --- a/docs/configuration/service/rst-index.rst +++ /dev/null @@ -1,31 +0,0 @@ -####### -Service -####### - - -.. toctree:: - :maxdepth: 1 - :includehidden: - - broadcast-relay - config-sync - conntrack-sync - console-server - dhcp-relay - dhcp-server - dns - eventhandler - https - ipoe-server - lldp - mdns - monitoring - ntp - pppoe-server - router-advert - salt-minion - snmp - ssh - tftp-server - webproxy - suricata diff --git a/docs/configuration/service/rst-ipoe-server.rst b/docs/configuration/service/rst-ipoe-server.rst deleted file mode 100644 index 5d7acd5a..00000000 --- a/docs/configuration/service/rst-ipoe-server.rst +++ /dev/null @@ -1,450 +0,0 @@ -.. _ipoe_server: - -########### -IPoE Server -########### - -VyOS utilizes `accel-ppp`_ to provide :abbr:`IPoE (Internet Protocol over -Ethernet)` server functionality. It can be used with local authentication -(mac-address) or a connected RADIUS server. - -IPoE is a method of delivering an IP payload over an Ethernet-based access -network or an access network using bridged Ethernet over Asynchronous Transfer -Mode (ATM) without using PPPoE. It directly encapsulates the IP datagrams in -Ethernet frames, using the standard :rfc:`894` encapsulation. - -The use of IPoE addresses the disadvantage that PPP is unsuited for multicast -delivery to multiple users. Typically, IPoE uses Dynamic Host Configuration -Protocol and Extensible Authentication Protocol to provide the same -functionality as PPPoE, but in a less robust manner. - -.. note:: Please be aware, due to an upstream bug, config changes/commits - will restart the ppp daemon and will reset existing IPoE sessions, - in order to become effective. - -*********************** -Configuring IPoE Server -*********************** - -IPoE can be configured on different interfaces, it will depend on each specific -situation which interface will provide IPoE to clients. The client's mac address -and the incoming interface is being used as control parameter, to authenticate -a client. - -The example configuration below will assign an IP to the client on the incoming -interface eth1 with the client mac address 00:50:79:66:68:00. Other DHCP -discovery requests will be ignored, unless the client mac has been enabled in -the configuration. - -.. code-block:: none - - set interfaces ethernet eth1 address '192.168.0.1/24' - set service ipoe-server authentication interface eth1.100 mac 00:50:79:66:68:00 - set service ipoe-server authentication interface eth1.101 mac 00:50:79:66:68:01 - set service ipoe-server authentication mode 'local' - set service ipoe-server client-ip-pool IPOE-POOL range '192.168.0.2-192.168.0.254' - set service ipoe-server default-pool 'IPOE-POOL' - set service ipoe-server gateway-address '192.168.0.1/24' - set service ipoe-server interface eth1 mode 'l2' - set service ipoe-server interface eth1 network 'vlan' - set service ipoe-server interface eth1 vlan '100-200' - - -.. cfgcmd:: set service ipoe-server authentication interface <interface> mac <MAC> - - Creates local IPoE user with username=**<interface>** and - password=**<MAC>** (mac-address) - -.. cfgcmd:: set service ipoe-server authentication mode <local | radius> - - Set authentication backend. The configured authentication backend is used - for all queries. - - * **radius**: All authentication queries are handled by a configured RADIUS - server. - * **local**: All authentication queries are handled locally. - * **noauth**: Authentication disabled - -.. cfgcmd:: set service ipoe-server client-ip-pool <POOL-NAME> range <x.x.x.x-x.x.x.x | x.x.x.x/x> - - Use this command to define the first IP address of a pool of - addresses to be given to IPoE clients. If notation ``x.x.x.x-x.x.x.x``, - it must be within a /24 subnet. If notation ``x.x.x.x/x`` is - used there is possibility to set host/netmask. - -.. cfgcmd:: set service ipoe-server default-pool <POOL-NAME> - - Use this command to define default address pool name. - -.. cfgcmd:: set service ipoe-server gateway-address <x.x.x.x/x> - - Specifies address to be used as server ip address if radius can assign - only client address. In such case if client address is matched network - and mask then specified address and mask will be used. You can specify - multiple such options. - -.. cfgcmd:: set service ipoe-server interface <interface> mode <l2 | l3> - - Specifies the client connectivity mode. - - * **l2**: It means that clients are on same network where interface - is.**(default)** - * **l3**: It means that client are behind some router. - -.. cfgcmd:: set service ipoe-server interface <interface> network <shared | vlan> - - Specify where interface is shared by multiple users or it is vlan-per-user. - - * **shared**: Multiple clients share the same network. **(default)** - * **vlan**: One VLAN per client. - -.. code-block:: none - - vyos@vyos:~$ show ipoe-server sessions - - ifname | username | calling-sid | ip | rate-limit | type | comp | state | uptime - --------+----------+-------------------+-------------+------------+------+------+--------+---------- - ipoe0 | eth1.100 | 00:50:79:66:68:00 | 192.168.0.2 | | ipoe | | active | 00:04:55 - ipoe1 | eth1.101 | 00:50:79:66:68:01 | 192.168.0.3 | | ipoe | | active | 00:04:44 - - -********************************* -Configuring RADIUS authentication -********************************* - -To enable RADIUS based authentication, the authentication mode needs to be -changed within the configuration. Previous settings like the local users, still -exists within the configuration, however they are not used if the mode has been -changed from local to radius. Once changed back to local, it will use all local -accounts again. - -.. code-block:: none - - set service ipoe-server authentication mode radius - -.. cfgcmd:: set service ipoe-server authentication radius server <server> key <secret> - - Configure RADIUS `<server>` and its required shared `<secret>` for - communicating with the RADIUS server. - -Since the RADIUS server would be a single point of failure, multiple RADIUS -servers can be setup and will be used subsequentially. -For example: - -.. code-block:: none - - set service ipoe-server authentication radius server 10.0.0.1 key 'foo' - set service ipoe-server authentication radius server 10.0.0.2 key 'foo' - -.. note:: Some RADIUS severs use an access control list which allows or denies - queries, make sure to add your VyOS router to the allowed client list. - -RADIUS source address -===================== - -If you are using OSPF as IGP, always the closest interface connected to the -RADIUS server is used. With VyOS 1.2 you can bind all outgoing RADIUS requests -to a single source IP e.g. the loopback interface. - -.. cfgcmd:: set service ipoe-server authentication radius source-address <address> - - Source IPv4 address used in all RADIUS server queires. - -.. note:: The ``source-address`` must be configured on one of VyOS interface. - Best practice would be a loopback or dummy interface. - -RADIUS advanced options -======================= - -.. cfgcmd:: set service ipoe-server authentication radius server <server> port <port> - - Configure RADIUS `<server>` and its required port for authentication requests. - -.. cfgcmd:: set service ipoe-server authentication radius server <server> fail-time <time> - - Mark RADIUS server as offline for this given `<time>` in seconds. - -.. cfgcmd:: set service ipoe-server authentication radius server <server> disable - - Temporary disable this RADIUS server. - -.. cfgcmd:: set service ipoe-server authentication radius acct-timeout <timeout> - - Timeout to wait reply for Interim-Update packets. (default 3 seconds) - -.. cfgcmd:: set service ipoe-server authentication radius dynamic-author server <address> - - Specifies IP address for Dynamic Authorization Extension server (DM/CoA). - This IP must exist on any VyOS interface or it can be ``0.0.0.0``. - -.. cfgcmd:: set service ipoe-server authentication radius dynamic-author port <port> - - UDP port for Dynamic Authorization Extension server (DM/CoA) - -.. cfgcmd:: set service ipoe-server authentication radius dynamic-author key <secret> - - Secret for Dynamic Authorization Extension server (DM/CoA) - -.. cfgcmd:: set service ipoe-server authentication radius max-try <number> - - Maximum number of tries to send Access-Request/Accounting-Request queries - -.. cfgcmd:: set service ipoe-server authentication radius timeout <timeout> - - Timeout to wait response from server (seconds) - -.. cfgcmd:: set service ipoe-server authentication radius nas-identifier <identifier> - - Value to send to RADIUS server in NAS-Identifier attribute and to be matched - in DM/CoA requests. - -.. cfgcmd:: set service ipoe-server authentication radius nas-ip-address <address> - - Value to send to RADIUS server in NAS-IP-Address attribute and to be matched - in DM/CoA requests. Also DM/CoA server will bind to that address. - -.. cfgcmd:: set service ipoe-server authentication radius source-address <address> - - Source IPv4 address used in all RADIUS server queires. - -.. cfgcmd:: set service ipoe-server authentication radius rate-limit attribute <attribute> - - Specifies which RADIUS server attribute contains the rate limit information. - The default attribute is `Filter-Id`. - -.. note:: If you set a custom RADIUS attribute you must define it on both - dictionaries at RADIUS server and client. - -.. cfgcmd:: set service ipoe-server authentication radius rate-limit enable - - Enables bandwidth shaping via RADIUS. - -.. cfgcmd:: set service ipoe-server authentication radius rate-limit vendor - - Specifies the vendor dictionary, dictionary needs to be in - /usr/share/accel-ppp/radius. - -Received RADIUS attributes have a higher priority than parameters defined within -the CLI configuration, refer to the explanation below. - -Allocation clients ip addresses by RADIUS -========================================= - -If the RADIUS server sends the attribute ``Framed-IP-Address`` then this IP -address will be allocated to the client and the option ``default-pool`` within the CLI -config is being ignored. - -If the RADIUS server sends the attribute ``Framed-Pool``, IP address will be allocated -from a predefined IP pool whose name equals the attribute value. - -If the RADIUS server sends the attribute ``Stateful-IPv6-Address-Pool``, IPv6 address -will be allocated from a predefined IPv6 pool ``prefix`` whose name equals the attribute value. - -If the RADIUS server sends the attribute ``Delegated-IPv6-Prefix-Pool``, IPv6 -delegation pefix will be allocated from a predefined IPv6 pool ``delegate`` -whose name equals the attribute value. - -.. note:: ``Stateful-IPv6-Address-Pool`` and ``Delegated-IPv6-Prefix-Pool`` are defined in - RFC6911. If they are not defined in your RADIUS server, add new dictionary_. - -User interface can be put to VRF context via RADIUS Access-Accept packet, or change -it via RADIUS CoA. ``Accel-VRF-Name`` is used from these purposes. It is custom `ACCEL-PPP attribute`_. -Define it in your RADIUS server. - -**** -IPv6 -**** - -.. cfgcmd:: set service ipoe-server client-ipv6-pool <IPv6-POOL-NAME> prefix <address> - mask <number-of-bits> - - Use this comand to set the IPv6 address pool from which an IPoE client - will get an IPv6 prefix of your defined length (mask) to terminate the - IPoE endpoint at their side. The mask length can be set from 48 to 128 - bit long, the default value is 64. - -.. cfgcmd:: set service ipoe-server client-ipv6-pool <IPv6-POOL-NAME> delegate <address> - delegation-prefix <number-of-bits> - - Use this command to configure DHCPv6 Prefix Delegation (RFC3633) on - IPoE. You will have to set your IPv6 pool and the length of the - delegation prefix. From the defined IPv6 pool you will be handing out - networks of the defined length (delegation-prefix). The length of the - delegation prefix can be set from 32 to 64 bit long. - -.. cfgcmd:: set service ipoe-server default-ipv6-pool <IPv6-POOL-NAME> - - Use this command to define default IPv6 address pool name. - -.. code-block:: none - - set service ipoe-server client-ipv6-pool IPv6-POOL delegate '2001:db8:8003::/48' delegation-prefix '56' - set service ipoe-server client-ipv6-pool IPv6-POOL prefix '2001:db8:8002::/48' mask '64' - set service ipoe-server default-ipv6-pool IPv6-POOL - -********* -Scripting -********* - -.. cfgcmd:: set service ipoe-server extended-scripts on-change <path_to_script> - - Script to run when session interface changed by RADIUS CoA handling - -.. cfgcmd:: set service ipoe-server extended-scripts on-down <path_to_script> - - Script to run when session interface going to terminate - -.. cfgcmd:: set service ipoe-server extended-scripts on-pre-up <path_to_script> - - Script to run before session interface comes up - -.. cfgcmd:: set service ipoe-server extended-scripts on-up <path_to_script> - - Script to run when session interface is completely configured and started - -**************** -Advanced Options -**************** - -Authentication Advanced Options -=============================== - -.. cfgcmd:: set service ipoe-server authentication interface <interface> mac <MAC> vlan - <vlan-id> - - VLAN monitor for automatic creation of VLAN interfaces for specific user on specific <interface> - -.. cfgcmd:: set service ipoe-server authentication interface <interface> mac <MAC> rate-limit - download <bandwidth> - - Download bandwidth limit in kbit/s for user on interface `<interface>`. - -.. cfgcmd:: set service ipoe-server authentication interface <interface> mac <MAC> rate-limit - upload <bandwidth> - - Upload bandwidth limit in kbit/s for for user on interface `<interface>`. - -Client IP Pool Advanced Options -=============================== - -.. cfgcmd:: set service ipoe-server client-ip-pool <POOL-NAME> next-pool <NEXT-POOL-NAME> - - Use this command to define the next address pool name. - -Advanced Interface Options -============================== - -.. cfgcmd:: set service ipoe-server interface <interface> client-subnet <x.x.x.x/x> - - Specify local range of ip address to give to dhcp clients. First IP in range is router IP. - If you need more customization use `client-ip-pool` - -.. cfgcmd:: set service ipoe-server interface <interface> external-dhcp dhcp-relay <x.x.x.x> - - Specify DHCPv4 relay IP address to pass requests to. If specified giaddr is also needed. - -.. cfgcmd:: set service ipoe-server interface <interface> external-dhcp giaddr <x.x.x.x> - - Specifies relay agent IP addre - - -Global Advanced options -======================= - -.. cfgcmd:: set service ipoe-server description <description> - - Set description. - -.. cfgcmd:: set service ipoe-server limits burst <value> - - Burst count - -.. cfgcmd:: set service ipoe-server limits connection-limit <value> - - Acceptable rate of connections (e.g. 1/min, 60/sec) - -.. cfgcmd:: set service ipoe-server limits timeout <value> - - Timeout in seconds - -.. cfgcmd:: set service ipoe-server max-concurrent-sessions - - Maximum number of concurrent session start attempts - -.. cfgcmd:: set service ipoe-server name-server <address> - - Connected client should use `<address>` as their DNS server. This - command accepts both IPv4 and IPv6 addresses. Up to two nameservers - can be configured for IPv4, up to three for IPv6. - -.. cfgcmd:: set service ipoe-server shaper fwmark <1-2147483647> - - Match firewall mark value - -.. cfgcmd:: set service ipoe-server snmp master-agent - - Enable SNMP - -********** -Monitoring -********** - -.. opcmd:: show ipoe-server sessions - - Use this command to locally check the active sessions in the IPoE - server. - -.. code-block:: none - - vyos@vyos:~$ show ipoe-server sessions - ifname | username | calling-sid | ip | rate-limit | type | comp | state | uptime - ----------+----------+-------------------+-------------+------------+------+------+--------+---------- - eth1.100 | eth1.100 | 0c:98:bd:b8:00:01 | 192.168.0.3 | | ipoe | | active | 03:03:58 - -.. code-block:: none - - vyos@vyos:~$ show ipoe-server statistics - uptime: 0.03:31:36 - cpu: 0% - mem(rss/virt): 6044/101360 kB - core: - mempool_allocated: 148628 - mempool_available: 144748 - thread_count: 1 - thread_active: 1 - context_count: 10 - context_sleeping: 0 - context_pending: 0 - md_handler_count: 6 - md_handler_pending: 0 - timer_count: 1 - timer_pending: 0 - sessions: - starting: 0 - active: 1 - finishing: 0 - ipoe: - starting: 0 - active: 1 - delayed: 0 - -************** -Toubleshooting -************** - -.. code-block:: none - - vyos@vyos:~$ show log ipoe-server - - Feb 27 14:29:27 vyos accel-ipoe[2262]: eth1.100:: recv [DHCPv4 Discover xid=55df9228 chaddr=0c:98:bd:b8:00:01 <Message-Type Discover> <Request-IP 192.168.0.3> <Host-Name vyos> <Request-List Subnet,Broadcast,Router,DNS,Classless-Route,Domain-Name,MTU>] - Feb 27 14:29:27 vyos accel-ipoe[2262]: eth1.100:eth1.100: eth1.100: authentication succeeded - Feb 27 14:29:27 vyos accel-ipoe[2262]: eth1.100:eth1.100: send [DHCPv4 Offer xid=55df9228 yiaddr=192.168.0.4 chaddr=0c:98:bd:b8:00:01 <Message-Type Offer> <Server-ID 192.168.0.1> <Lease-Time 600> <T1 300> <T2 525> <Router 192.168.0.1> <Subnet 255.255.255.0>] - Feb 27 14:29:27 vyos accel-ipoe[2262]: eth1.100:eth1.100: recv [DHCPv4 Request xid=55df9228 chaddr=0c:98:bd:b8:00:01 <Message-Type Request> <Server-ID 192.168.0.1> <Request-IP 192.168.0.4> <Host-Name vyos> <Request-List Subnet,Broadcast,Router,DNS,Classless-Route,Domain-Name,MTU>] - Feb 27 14:29:27 vyos accel-ipoe[2262]: eth1.100:eth1.100: ipoe: activate session - Feb 27 14:29:27 vyos accel-ipoe[2262]: eth1.100:eth1.100: ipoe: no free IPv6 address - Feb 27 14:29:27 vyos accel-ipoe[2262]: eth1.100:eth1.100: ipoe: session started - Feb 27 14:29:27 vyos accel-ipoe[2262]: eth1.100:eth1.100: send [DHCPv4 Ack xid=55df9228 yiaddr=192.168.0.4 chaddr=0c:98:bd:b8:00:01 <Message-Type Ack> <Server-ID 192.168.0.1> <Lease-Time 600> <T1 300> <T2 525> <Router 192.168.0.1> <Subnet 255.255.255.0>] - -.. include:: /_include/common-references.txt -.. _dictionary: https://github.com/accel-ppp/accel-ppp/blob/master/accel-pppd/radius/dict/dictionary.rfc6911 -.. _`ACCEL-PPP attribute`: https://github.com/accel-ppp/accel-ppp/blob/master/accel-pppd/radius/dict/dictionary.accel diff --git a/docs/configuration/service/rst-lldp.rst b/docs/configuration/service/rst-lldp.rst deleted file mode 100644 index 8aee6183..00000000 --- a/docs/configuration/service/rst-lldp.rst +++ /dev/null @@ -1,148 +0,0 @@ -.. _lldp: - -#### -LLDP -#### - -:abbr:`LLDP (Link Layer Discovery Protocol)` is a vendor-neutral link layer -protocol in the Internet Protocol Suite used by network devices for advertising -their identity, capabilities, and neighbors on an IEEE 802 local area network, -principally wired Ethernet. The protocol is formally referred to by the IEEE -as Station and Media Access Control Connectivity Discovery specified in IEEE -802.1AB and IEEE 802.3-2012 section 6 clause 79. - -LLDP performs functions similar to several proprietary protocols, such as -:abbr:`CDP (Cisco Discovery Protocol)`, -:abbr:`FDP (Foundry Discovery Protocol)`, -:abbr:`NDP (Nortel Discovery Protocol)` and :abbr:`LLTD (Link Layer Topology -Discovery)`. - -Information gathered with LLDP is stored in the device as a :abbr:`MIB -(Management Information Database)` and can be queried with :abbr:`SNMP (Simple -Network Management Protocol)` as specified in :rfc:`2922`. The topology of an -LLDP-enabled network can be discovered by crawling the hosts and querying this -database. Information that may be retrieved include: - -* System Name and Description -* Port name and description -* VLAN name -* IP management address -* System capabilities (switching, routing, etc.) -* MAC/PHY information -* MDI power -* Link aggregation - -Configuration -============= - -.. cfgcmd:: set service lldp - - Enable LLDP service - -.. cfgcmd:: set service lldp management-address <address> - - Define IPv4/IPv6 management address transmitted via LLDP. Multiple addresses - can be defined. Only addresses connected to the system will be transmitted. - -.. cfgcmd:: set service lldp interface <interface> - - Enable transmission of LLDP information on given `<interface>`. You can also - say ``all`` here so LLDP is turned on on every interface. - -.. cfgcmd:: set service lldp interface <interface> mode [disable|rx-tx|rx|tx] - - Configure the administrative status of the given port. - - By default, all ports are configured to be in rx-tx mode. This means they - can receive and transmit LLDP frames. - - In rx mode, they won't emit any frames. In tx mode, they won't receive - any frames. In disabled mode, no frame will be sent and any incoming frame - will be discarded. - -.. cfgcmd:: set service lldp snmp - - Enable SNMP queries of the LLDP database - -.. cfgcmd:: set service lldp legacy-protocols <cdp|edp|fdp|sonmp> - - Enable given legacy protocol on this LLDP instance. Legacy protocols include: - - * ``cdp`` - Listen for CDP for Cisco routers/switches - * ``edp`` - Listen for EDP for Extreme routers/switches - * ``fdp`` - Listen for FDP for Foundry routers/switches - * ``sonmp`` - Listen for SONMP for Nortel routers/switches - -Operation -========= - -.. opcmd:: show lldp neighbors - - Displays information about all neighbors discovered via LLDP. - - .. code-block:: none - - vyos@vyos:~$ show lldp neighbors - Capability Codes: R - Router, B - Bridge, W - Wlan r - Repeater, S - Station - D - Docsis, T - Telephone, O - Other - - Device ID Local Proto Cap Platform Port ID - --------- ----- ----- --- -------- ------- - BR2.vyos.net eth0 LLDP R VyOS 1.2.4 eth1 - BR3.vyos.net eth0 LLDP RB VyOS 1.2.4 eth2 - SW1.vyos.net eth0 LLDP B Cisco IOS Software GigabitEthernet0/6 - -.. opcmd:: show lldp neighbors detail - - Get detailed information about LLDP neighbors. - - .. code-block:: none - - vyos@vyos:~$ show lldp neighbors detail - ------------------------------------------------------------------------------- - LLDP neighbors: - ------------------------------------------------------------------------------- - Interface: eth0, via: LLDP, RID: 28, Time: 0 day, 00:24:33 - Chassis: - ChassisID: mac 00:53:00:01:02:c9 - SysName: BR2.vyos.net - SysDescr: VyOS 1.3-rolling-201912230217 - MgmtIP: 192.0.2.1 - MgmtIP: 2001:db8::ffff - Capability: Bridge, on - Capability: Router, on - Capability: Wlan, off - Capability: Station, off - Port: - PortID: mac 00:53:00:01:02:c9 - PortDescr: eth0 - TTL: 120 - PMD autoneg: supported: no, enabled: no - MAU oper type: 10GigBaseCX4 - X copper over 8 pair 100-Ohm balanced cable - VLAN: 201 eth0.201 - VLAN: 205 eth0.205 - LLDP-MED: - Device Type: Network Connectivity Device - Capability: Capabilities, yes - Capability: Policy, yes - Capability: Location, yes - Capability: MDI/PSE, yes - Capability: MDI/PD, yes - Capability: Inventory, yes - Inventory: - Hardware Revision: None - Software Revision: 4.19.89-amd64-vyos - Firmware Revision: 6.00 - Serial Number: VMware-42 1d 83 b9 fe c1 bd b2-7 - Manufacturer: VMware, Inc. - Model: VMware Virtual Platform - Asset ID: No Asset Tag - ------------------------------------------------------------------------------- - -.. opcmd:: show lldp neighbors interface <interface> - - Show LLDP neighbors connected via interface `<interface>`. - -.. opcmd:: show log lldp - - Used for troubleshooting. diff --git a/docs/configuration/service/rst-mdns.rst b/docs/configuration/service/rst-mdns.rst deleted file mode 100644 index 8a26722e..00000000 --- a/docs/configuration/service/rst-mdns.rst +++ /dev/null @@ -1,124 +0,0 @@ -############# -mDNS Repeater -############# - -Starting with VyOS 1.2 a :abbr:`mDNS (Multicast DNS)` repeater functionality is -provided. Additional information can be obtained from -https://en.wikipedia.org/wiki/Multicast_DNS. - -Multicast DNS uses the reserved address ``224.0.0.251``, which is -`"administratively scoped"` and does not leave the subnet. mDNS repeater -retransmits mDNS packets from one interface to other interfaces. This enables -support for devices using mDNS discovery (like network printers, Apple Airplay, -Chromecast, various IP based home-automation devices etc) across multiple VLANs. - -Since the mDNS protocol sends the :abbr:`AA(Authoritative Answer)` records in -the packet itself, the repeater does not need to forge the source address. -Instead, the source address is of the interface that repeats the packet. - -.. note:: You can not run this in a VRRP setup, if multiple mDNS repeaters - are launched in a subnet you will experience the mDNS packet storm death! - -Configuration -============= - -.. cfgcmd:: set service mdns repeater interface <interface> - - To enable mDNS repeater you need to configure at least two interfaces so that - all incoming mDNS packets from one interface configured here can be - re-broadcasted to any other interface(s) configured under this section. - -.. cfgcmd:: set service mdns repeater disable - - mDNS repeater can be temporarily disabled without deleting the service using - -.. cfgcmd:: set service mdns repeater ip-version <ipv4 | ipv6 | both> - - mDNS repeater can be enabled either on IPv4 socket or on IPv6 socket or both - to re-broadcast. By default, mDNS repeater will listen on both IPv4 and IPv6. - -.. cfgcmd:: set service mdns repeater allow-service <service> - - mDNS repeater can be configured to re-broadcast only specific services. By - default, all services are re-broadcasted. - -.. cfgcmd:: set service mdns repeater browse-domain <domain> - - Allow listing additional custom domains to be browsed (in addition to the - default ``local``) so that they can be reflected. - -.. cfgcmd:: set service mdns repeater cache-entries <entries> - - Specify how many resource records are cached per interface. Bigger values - allow mDNS work correctly in large LANs but also increase memory consumption. - - Defaults to: 4096 - -Firewall recommendations -======================== - -Unlike typical routed traffic, mDNS packets relayed between interfaces do not -traverse the FORWARD hook chain in the firewall. Instead, they are processed -through the following hooks: - - - **INPUT**: For packets received by the local system - - **OUTPUT**: For packets sent from the local system - -To control or allow mDNS packet forwarding via the relay, you must define -appropriate rules in the INPUT and OUTPUT directions. Rules in the FORWARD -direction will have no effect on mDNS relay traffic. - -.. code-block:: none - - set firewall ipv4 input filter rule 10 action 'accept' - set firewall ipv4 input filter rule 10 destination address '224.0.0.251' - set firewall ipv4 input filter rule 10 destination port '5353' - set firewall ipv4 input filter rule 10 protocol 'udp' - set firewall ipv4 output filter rule 10 action 'accept' - set firewall ipv4 output filter rule 10 destination address '224.0.0.251' - set firewall ipv4 output filter rule 10 destination port '5353' - set firewall ipv4 output filter rule 10 protocol 'udp' - -Example -======= - -To listen on both `eth0` and `eth1` mDNS packets and also repeat packets -received on `eth0` to `eth1` (and vice-versa) use the following commands: - -.. code-block:: none - - set service mdns repeater interface 'eth0' - set service mdns repeater interface 'eth1' - -To allow only specific services, for example ``_airplay._tcp`` or ``_ipp._tcp``, -(instead of all services) to be re-broadcasted, use the following command: - -.. code-block:: none - - set service mdns repeater allow-service '_airplay._tcp' - set service mdns repeater allow-service '_ipp._tcp' - -To allow listing additional custom domain, for example -``openthread.thread.home.arpa``, so that it can reflected in addition to the -default ``local``, use the following command: - -.. code-block:: none - - set service mdns repeater browse-domain 'openthread.thread.home.arpa' - -.. _`Multicast DNS`: https://en.wikipedia.org/wiki/Multicast_DNS - -Operation -========= - -.. opcmd:: restart mdns repeater - - Restart mDNS repeater service. - -.. opcmd:: show log mdns repeater - - Show logs for mDNS repeater service. - -.. opcmd:: monitor log mdns repeater - - Follow the logs for mDNS repeater service. diff --git a/docs/configuration/service/rst-monitoring.rst b/docs/configuration/service/rst-monitoring.rst deleted file mode 100644 index 8faf0eb8..00000000 --- a/docs/configuration/service/rst-monitoring.rst +++ /dev/null @@ -1,289 +0,0 @@ -########## -Monitoring -########## - -VyOS supports monitoring through Telegraf as well as through Prometheus exporters. - -******** -Telegraf -******** - -Telegraf is the open source server agent to help you collect metrics, events -and logs from your routers. - -The following Telegraf plugins are configurable to export metrics and logs: - * Azure Data Explorer - * Prometheus Client - * Splunk - * InfluxDB - * Loki - - -Azure data explorer -=================== -Telegraf output plugin azure-data-explorer_. - -.. cfgcmd:: set service monitoring telegraf azure-data-explorer authentication client-id <client-id> - - Authentication application client-id. - -.. cfgcmd:: set service monitoring telegraf azure-data-explorer authentication client-secret <client-secret> - - Authentication application client-secret. - -.. cfgcmd:: set service monitoring telegraf azure-data-explorer authentication tenant-id <tenant-id> - - Authentication application tenant-id - -.. cfgcmd:: set service monitoring telegraf azure-data-explorer database <name> - - Remote database name. - -.. cfgcmd:: set service monitoring telegraf azure-data-explorer group-metrics <single-table | table-per-metric> - - Type of metrics grouping when push to Azure Data Explorer. The default is - ``table-per-metric``. - -.. cfgcmd:: set service monitoring telegraf azure-data-explorer table <name> - - Name of the single table Only if set group-metrics single-table. - -.. cfgcmd:: set service monitoring telegraf azure-data-explorer url <url> - - Remote URL. - - -Prometheus client -================= -Telegraf output plugin prometheus-client_ -This plugin allows export of Telegraf metrics to Prometheus, -for Prometheus native metrics through exporters see section below. - -.. cfgcmd:: set service monitoring telegraf prometheus-client - - Output plugin Prometheus client - -.. cfgcmd:: set service monitoring telegraf prometheus-client allow-from <prefix> - - Networks allowed to query this server - -.. cfgcmd:: set service monitoring telegraf prometheus-client authentication username <username> - - HTTP basic authentication username - -.. cfgcmd:: set service monitoring telegraf prometheus-client authentication password <password> - - HTTP basic authentication username - -.. cfgcmd:: set service monitoring telegraf prometheus-client listen-address <address> - - Local IP addresses to listen on - -.. cfgcmd:: set service monitoring telegraf prometheus-client metric-version <1 | 2> - - Metris version, the default is ``2`` - -.. cfgcmd:: set service monitoring telegraf prometheus-client port <port> - - Port number used by connection, default is ``9273`` - -Example: - -.. code-block:: none - - set service monitoring telegraf prometheus-client - -.. code-block:: none - - vyos@r14:~$ curl --silent localhost:9273/metrics | egrep -v "#" | grep cpu_usage_system - cpu_usage_system{cpu="cpu-total",host="r14"} 0.20040080160320556 - cpu_usage_system{cpu="cpu0",host="r14"} 0.17182130584191915 - cpu_usage_system{cpu="cpu1",host="r14"} 0.22896393817971655 - - -Splunk -====== -Telegraf output plugin splunk_ HTTP Event Collector. - -.. cfgcmd:: set service monitoring telegraf splunk authentication insecure - - Use TLS but skip host validation - -.. cfgcmd:: set service monitoring telegraf splunk authentication token <token> - - Authorization token - -.. cfgcmd:: set service monitoring telegraf splunk authentication url <url> - - Remote URL to Splunk collector - -Example: - -.. code-block:: none - - set service monitoring telegraf splunk authentication insecure - set service monitoring telegraf splunk authentication token 'xxxxf5b8-xxxx-452a-xxxx-43828911xxxx' - set service monitoring telegraf splunk url 'https://192.0.2.10:8088/services/collector' - - -InfluxDB -======== -Telegraf output plugin influxdb_ to write metrics to ``InfluxDB`` via HTTP. - -.. cfgcmd:: set service monitoring telegraf influxdb authentication organization <organization> - - Authentication organization name - -.. cfgcmd:: set service monitoring telegraf influxdb authentication token <token> - - Authentication token - -.. cfgcmd:: set service monitoring telegraf bucket <bucket> - - Remote ``InfluxDB`` bucket name - -.. cfgcmd:: set service monitoring telegraf influxdb port <port> - - Remote port - -.. cfgcmd:: set service monitoring telegraf influxdb url <url> - - Remote URL - - -Example: - -.. code-block:: none - - set service monitoring telegraf influxdb authentication organization 'vyos' - set service monitoring telegraf influxdb authentication token 'ZAml9Uy5wrhA...==' - set service monitoring telegraf influxdb bucket 'bucket_vyos' - set service monitoring telegraf influxdb port '8086' - set service monitoring telegraf influxdb url 'http://r1.influxdb2.local' - - -Loki -==== - -Telegraf can be used to send logs to loki_ using tags as labels. - -.. cfgcmd:: set service monitoring telegraf loki port <port> - - Remote Loki port - - Default is 3100 - -.. cfgcmd:: set service monitoring telegraf loki url <url> - - Remote Loki url - -.. cfgcmd:: set service monitoring telegraf loki authentication username <username> -.. cfgcmd:: set service monitoring telegraf loki authentication password <password> - - HTTP basic authentication. - - If either is set both must be set. - -.. cfgcmd:: set service monitoring telegraf loki metric-name-label <label> - - Label to use for the metric name when sending metrics. - - If set to an empty string, the label will not be added. - This is NOT recommended, as it makes it impossible to differentiate - between multiple metrics. - -.. _azure-data-explorer: https://github.com/influxdata/telegraf/tree/master/plugins/outputs/azure_data_explorer -.. _prometheus-client: https://github.com/influxdata/telegraf/tree/master/plugins/outputs/prometheus_client -.. _influxdb: https://github.com/influxdata/telegraf/tree/master/plugins/outputs/influxdb_v2 -.. _splunk: https://www.splunk.com/en_us/blog/it/splunk-metrics-via-telegraf.html -.. _loki: https://github.com/influxdata/telegraf/tree/master/plugins/outputs/loki - - -********** -Prometheus -********** - -The following Prometheus exporters are configurable to export metrics: - * Node Exporter - * FRR Exporter - - -Node Exporter -============= -Prometheus node_exporter_ which provides a wide range of hardware and OS metrics. - -.. cfgcmd:: set service monitoring prometheus node-exporter listen-address <address> - - Configure the address node_exporter is listening on. - -.. cfgcmd:: set service monitoring prometheus node-exporter port <port> - - Configure the port number node_exporter is listening on. - -.. cfgcmd:: set service monitoring prometheus node-exporter vrf <name> - - Configure name of the :abbr:`VRF (Virtual Routing and Forwarding)` instance. - -.. cfgcmd:: set service monitoring prometheus node-exporter collectors textfile - - Configure textfile collector to export custom metrics read from - `/run/node_exporter/collector` - - -FRR Exporter -============ -Prometheus frr_exporter_ which provides free range routing metrics. - -.. cfgcmd:: set service monitoring prometheus frr-exporter listen-address <address> - - Configure the address frr_exporter is listening on. - -.. cfgcmd:: set service monitoring prometheus frr-exporter port <port> - - Configure the port number frr_exporter is listening on. - -.. cfgcmd:: set service monitoring prometheus frr-exporter vrf <name> - - Configure name of the :abbr:`VRF (Virtual Routing and Forwarding)` instance. - - -Blackbox Exporter -================= -Prometheus blackbox_exporter_ which allows probing of endpoints over -HTTP, HTTPS, DNS, TCP, ICMP and gRPC . - -.. cfgcmd:: set service monitoring prometheus blackbox-exporter listen-address <address> - - Configure the address blackbox_exporter is listening on. - -.. cfgcmd:: set service monitoring prometheus blackbox-exporter port <port> - - Configure the port number blackbox_exporter is listening on. - -.. cfgcmd:: set service monitoring prometheus blackbox-exporter vrf <name> - - Configure name of the :abbr:`VRF (Virtual Routing and Forwarding)` instance. - -Configuring modules -------------------- -Blackbox exporter can be configured with different modules for probing DNS or ICMP. - -DNS module example: - -.. code-block:: none - - set service monitoring prometheus blackbox-exporter modules dns name dns4 preferred-ip-protocol ipv4 - set service monitoring prometheus blackbox-exporter modules dns name dns4 query-name vyos.io - set service monitoring prometheus blackbox-exporter modules dns name dns4 query-type A - -ICMP module example: - -.. code-block:: none - - set service monitoring prometheus blackbox-exporter modules icmp name ping6 preferred-ip-protocol ipv6 - set service monitoring prometheus blackbox-exporter modules icmp name ping6 ip-protocol-fallback - set service monitoring prometheus blackbox-exporter modules icmp name ping6 timeout 3 - -.. _node_exporter: https://github.com/prometheus/node_exporter -.. _frr_exporter: https://github.com/tynany/frr_exporter -.. _blackbox_exporter: https://github.com/prometheus/blackbox_exporter diff --git a/docs/configuration/service/rst-ntp.rst b/docs/configuration/service/rst-ntp.rst deleted file mode 100644 index f4ccb4b1..00000000 --- a/docs/configuration/service/rst-ntp.rst +++ /dev/null @@ -1,197 +0,0 @@ -.. _ntp: - -### -NTP -### - -:abbr:`NTP (Network Time Protocol`) is a networking protocol for clock -synchronization between computer systems over packet-switched, variable-latency -data networks. In operation since before 1985, NTP is one of the oldest Internet -protocols in current use. - -NTP is intended to synchronize all participating computers to within a few -milliseconds of :abbr:`UTC (Coordinated Universal Time)`. It uses the -intersection algorithm, a modified version of Marzullo's algorithm, to select -accurate time servers and is designed to mitigate the effects of variable -network latency. NTP can usually maintain time to within tens of milliseconds -over the public Internet, and can achieve better than one millisecond accuracy -in local area networks under ideal conditions. Asymmetric routes and network -congestion can cause errors of 100 ms or more. - -The protocol is usually described in terms of a client-server model, but can as -easily be used in peer-to-peer relationships where both peers consider the other -to be a potential time source. Implementations send and receive timestamps using -:abbr:`UDP (User Datagram Protocol)` on port number 123. - -NTP supplies a warning of any impending leap second adjustment, but no -information about local time zones or daylight saving time is transmitted. - -The current protocol is version 4 (NTPv4), which is a proposed standard as -documented in :rfc:`5905`. It is backward compatible with version 3, specified -in :rfc:`1305`. - -.. note:: VyOS 1.4 uses chrony instead of ntpd (see :vytask:`T3008`) which will - no longer accept anonymous NTP requests as in VyOS 1.3. All configurations - will be migrated to keep the anonymous functionality. For new setups if you - have clients using your VyOS installation as NTP server, you must specify - the `allow-client` directive. - -Configuration -============= - -.. cfgcmd:: set service ntp server <address> - - Configure one or more servers for synchronisation. Server name can be either - an IP address or :abbr:`FQDN (Fully Qualified Domain Name)`. - - There are 3 default NTP server set. You are able to change them. - - * ``time1.vyos.net`` - * ``time2.vyos.net`` - * ``time3.vyos.net`` - -.. cfgcmd:: set service ntp server <address> <noselect | nts | pool | prefer | ptp | interleave> - - Configure one or more attributes to the given NTP server. - - * ``noselect`` marks the server as unused, except for display purposes. The - server is discarded by the selection algorithm. - - * ``nts`` enables Network Time Security (NTS) for the server as specified - in :rfc:`8915` - - * ``pool`` mobilizes persistent client mode association with a number of - remote servers. - - * ``prefer`` marks the server as preferred. All other things being equal, - this host will be chosen for synchronization among a set of correctly - operating hosts. - - * ``ptp`` enables the PTP transport for this server (see :ref:`ptp-transport`). - - * ``interleave`` enables NTP interleaved mode (see - `draft-ntp-interleaved-modes`_), which can improve synchronization accuracy - and stability when supported by both parties. - -.. cfgcmd:: set service ntp listen-address <address> - - NTP process will only listen on the specified IP address. You must specify - the `<address>` and optionally the permitted clients. Multiple listen - addresses for same IP family is no longer supported. Only one IPv4 and one - IPv6 address can be configured, using separate commands for each. - -.. cfgcmd:: set service ntp allow-client address <address> - - List of networks or client addresses permitted to contact this NTP server. - - Multiple networks/client IP addresses can be configured. - -.. cfgcmd:: set service ntp vrf <name> - - Specify name of the :abbr:`VRF (Virtual Routing and Forwarding)` instance. - -.. cfgcmd:: set service ntp leap-second [ignore|smear|system|timezone] - - Define how to handle leap-seconds. - - * `ignore`: No correction is applied to the clock for the leap second. The - clock will be corrected later in normal operation when new measurements are - made and the estimated offset includes the one second error. - - * `smear`: When smearing a leap second, the leap status is suppressed on the - server and the served time is corrected slowly by slewing instead of - stepping. The clients do not need any special configuration as they do not - know there is any leap second and they follow the server time which - eventually brings them back to UTC. Care must be taken to ensure they use - only NTP servers which smear the leap second in exactly the same way for - synchronisation. - - * `system`: When inserting a leap second, the kernel steps the system clock - backwards by one second when the clock gets to 00:00:00 UTC. When deleting - a leap second, it steps forward by one second when the clock gets to - 23:59:59 UTC. - - * `timezone`: This directive specifies a timezone in the system timezone - database which chronyd can use to determine when will the next leap second - occur and what is the current offset between TAI and UTC. It will - periodically check if 23:59:59 and 23:59:60 are valid times in the - timezone. This normally works with the right/UTC timezone which is the - default - -.. _draft-ntp-interleaved-modes: https://datatracker.ietf.org/doc/draft-ietf-ntp-interleaved-modes/07/ - -Hardware Timestamping of NTP Packets -====================================== - -The chrony daemon on VyOS can leverage NIC hardware capabilities to record the -exact time packets are received on the interface, as well as when packets were -actually transmitted. This provides improved accuracy and stability when the -system is under load, as queuing and OS context switching can introduce a -variable delay between when the packet is received on the network and when it -is actually processed by the NTP daemon. - -Hardware timestamping depends on NIC support. Some NICs can be configured to -apply timestamps to any incoming packet, while others only support applying -timestamps to specific protocols (e.g. PTP). - -When timestamping is enabled on an interface, chrony's default behavior is to -try to configure the interface to only timestamp NTP packets. If this mode is -not supported, chrony will attempt to set it to timestamp all packets. If -neither option is supported (e.g. the NIC can only timestamp received PTP -packets), chrony will leverage timestamping on transmitted packets only, which -still provides some benefit. - -.. cfgcmd:: set service ntp timestamp interface <interface> - - Configures hardware timestamping on the interface <interface>. The special - value `all` can also be specified to enable timestamping on all interfaces - that support it. - - Configure the timestamping behavior with the following option: - - * ``receive-filter [all|ntp|ptp|none]`` selects the receive filter mode, - which controls which inbound packets the NIC applies timestamps to. The - selected mode must be supported by the NIC, or timestamping will be - disabled for the interface. - - -The following `receive-filter` modes can be selected: - -* `all`: All received packets will be timestamped. - -* `ntp`: Only received NTP protocol packets will be timestamped. - -* `ptp`: Only received PTP protocol packets will be timestamped. Combined with - the PTP transport for NTP packets, this can be leveraged to take advantage of - hardware timestamping on NICs that only support the ptp filter mode. - -* `none`: No received packets will be timestamped. Hardware timestamping of - transmitted packets will still be leveraged, if supported by the NIC. - -.. _ptp-transport: - -PTP Transport of NTP Packets -============================= - -The Precision Time Protocol (IEEE 1588) is a local network time synchronization -protocol that provides high precision time synchronization by leveraging -hardware clocks in NICs and other network elements. VyOS does not currently -support standards-based PTP, which can be deployed independently of -NTP. - -For networks consisting of VyOS and other Linux systems running relatively -recent versions of the chrony daemon, NTP packets can be "tunneled" over -PTP. NTP over PTP provides the best of both worlds, leveraging hardware support -for timestamping PTP packets while retaining the configuration flexibility and -fault tolerance of NTP. - -.. cfgcmd:: set service ntp ptp - - Enables the NTP daemon PTP transport. The NTP daemon will listen on the - configured PTP port. Note that one or more servers must be individually - enabled for PTP before the daemon will synchronize over the transport. - -.. cfgcmd:: set service ntp ptp port <port> - - Configures the PTP port. By default, the standard port 319 is used. - diff --git a/docs/configuration/service/rst-pppoe-server.rst b/docs/configuration/service/rst-pppoe-server.rst deleted file mode 100644 index f763536a..00000000 --- a/docs/configuration/service/rst-pppoe-server.rst +++ /dev/null @@ -1,685 +0,0 @@ -:lastproofread: 2022-09-17 - -.. _pppoe-server: - -############ -PPPoE Server -############ - -VyOS utilizes `accel-ppp`_ to provide PPPoE server functionality. It can -be used with local authentication or a connected RADIUS server. - -.. note:: Please be aware, due to an upstream bug, config - changes/commits will restart the ppp daemon and will reset existing - PPPoE connections from connected users, in order to become effective. - -************************ -Configuring PPPoE Server -************************ - -.. code-block:: none - - set service pppoe-server access-concentrator PPPoE-Server - set service pppoe-server authentication mode local - set service pppoe-server authentication local-users username test password 'test' - set service pppoe-server client-ip-pool PPPOE-POOL range 192.168.255.2-192.168.255.254 - set service pppoe-server default-pool 'PPPOE-POOL' - set service pppoe-server gateway-address 192.168.255.1 - set service pppoe-server interface eth0 - -.. cfgcmd:: set service pppoe-server access-concentrator <name> - - Use this command to set a name for this PPPoE-server access - concentrator. - -.. cfgcmd:: set service pppoe-server authentication mode <local | radius> - - Set authentication backend. The configured authentication backend is used - for all queries. - - * **radius**: All authentication queries are handled by a configured RADIUS - server. - * **local**: All authentication queries are handled locally. - * **noauth**: Authentication disabled. - -.. cfgcmd:: set service pppoe-server authentication local-users username - <name> password <password> - - Create `<user>` for local authentication on this system. The users password - will be set to `<pass>`. - -.. cfgcmd:: set service pppoe-server client-ip-pool <POOL-NAME> - range <x.x.x.x-x.x.x.x | x.x.x.x/x> - - Use this command to define the first IP address of a pool of - addresses to be given to pppoe clients. If notation ``x.x.x.x-x.x.x.x``, - it must be within a /24 subnet. If notation ``x.x.x.x/x`` is - used there is possibility to set host/netmask. - -.. cfgcmd:: set service pppoe-server default-pool <POOL-NAME> - - Use this command to define default address pool name. - -.. cfgcmd:: set service pppoe-server interface <interface> - - Use this command to define the interface the PPPoE server will use to - listen for PPPoE clients. - -.. cfgcmd:: set service pppoe-server gateway-address <address> - - Specifies single `<gateway>` IP address to be used as local address of PPP - interfaces. - - -********************************* -Configuring RADIUS authentication -********************************* - -To enable RADIUS based authentication, the authentication mode needs to be -changed within the configuration. Previous settings like the local users, still -exists within the configuration, however they are not used if the mode has been -changed from local to radius. Once changed back to local, it will use all local -accounts again. - -.. code-block:: none - - set service pppoe-server authentication mode radius - -.. cfgcmd:: set service pppoe-server authentication radius - server <server> key <secret> - - Configure RADIUS `<server>` and its required shared `<secret>` for - communicating with the RADIUS server. - -Since the RADIUS server would be a single point of failure, multiple RADIUS -servers can be setup and will be used subsequentially. -For example: - -.. code-block:: none - - set service pppoe-server authentication radius server 10.0.0.1 key 'foo' - set service pppoe-server authentication radius server 10.0.0.2 key 'foo' - -.. note:: Some RADIUS severs use an access control list which allows or denies - queries, make sure to add your VyOS router to the allowed client list. - -RADIUS source address -===================== - -If you are using OSPF as IGP, always the closest interface connected to the -RADIUS server is used. With VyOS 1.2 you can bind all outgoing RADIUS requests -to a single source IP e.g. the loopback interface. - -.. cfgcmd:: set service pppoe-server authentication radius - source-address <address> - - Source IPv4 address used in all RADIUS server queires. - -.. note:: The ``source-address`` must be configured on one of VyOS interface. - Best practice would be a loopback or dummy interface. - -RADIUS advanced options -======================= - -.. cfgcmd:: set service pppoe-server authentication radius - server <server> port <port> - - Configure RADIUS `<server>` and its required port for authentication requests. - -.. cfgcmd:: set service pppoe-server authentication radius - server <server> fail-time <time> - - Mark RADIUS server as offline for this given `<time>` in seconds. - -.. cfgcmd:: set service pppoe-server authentication radius - server <server> disable - - Temporary disable this RADIUS server. - -.. cfgcmd:: set service pppoe-server authentication radius - acct-timeout <timeout> - - Timeout to wait reply for Interim-Update packets. (default 3 seconds) - -.. cfgcmd:: set service pppoe-server authentication radius - dynamic-author server <address> - - Specifies IP address for Dynamic Authorization Extension server (DM/CoA). - This IP must exist on any VyOS interface or it can be ``0.0.0.0``. - -.. cfgcmd:: set service pppoe-server authentication radius - dynamic-author port <port> - - UDP port for Dynamic Authorization Extension server (DM/CoA) - -.. cfgcmd:: set service pppoe-server authentication radius dynamic-author - key <secret> - - Secret for Dynamic Authorization Extension server (DM/CoA) - -.. cfgcmd:: set service pppoe-server authentication radius - max-try <number> - - Maximum number of tries to send Access-Request/Accounting-Request queries - -.. cfgcmd:: set service pppoe-server authentication radius - timeout <timeout> - - Timeout to wait response from server (seconds) - -.. cfgcmd:: set service pppoe-server authentication radius - nas-identifier <identifier> - - Value to send to RADIUS server in NAS-Identifier attribute and to be matched - in DM/CoA requests. - -.. cfgcmd:: set service pppoe-server authentication radius - nas-ip-address <address> - - Value to send to RADIUS server in NAS-IP-Address attribute and to be matched - in DM/CoA requests. Also DM/CoA server will bind to that address. - -.. cfgcmd:: set service pppoe-server authentication radius - source-address <address> - - Source IPv4 address used in all RADIUS server queires. - -.. cfgcmd:: set service pppoe-server authentication radius - rate-limit attribute <attribute> - - Specifies which RADIUS server attribute contains the rate limit information. - The default attribute is ``Filter-Id``. - -.. note:: If you set a custom RADIUS attribute you must define it on both - dictionaries at RADIUS server and client. - -.. cfgcmd:: set service pppoe-server authentication radius - rate-limit enable - - Enables bandwidth shaping via RADIUS. - -.. cfgcmd:: set service pppoe-server authentication radius - rate-limit vendor - - Specifies the vendor dictionary, dictionary needs to be in - /usr/share/accel-ppp/radius. - -Received RADIUS attributes have a higher priority than parameters defined within -the CLI configuration, refer to the explanation below. - -Allocation clients ip addresses by RADIUS -========================================= - -If the RADIUS server sends the attribute ``Framed-IP-Address`` then this IP -address will be allocated to the client and the option ``default-pool`` -within the CLI config is being ignored. - -If the RADIUS server sends the attribute ``Framed-Pool``, IP address will -be allocated from a predefined IP pool whose name equals the attribute value. - -If the RADIUS server sends the attribute ``Stateful-IPv6-Address-Pool``, -IPv6 address will be allocated from a predefined IPv6 pool ``prefix`` -whose name equals the attribute value. - -If the RADIUS server sends the attribute ``Delegated-IPv6-Prefix-Pool``, -IPv6 delegation pefix will be allocated from a predefined IPv6 pool ``delegate`` -whose name equals the attribute value. - -.. note:: ``Stateful-IPv6-Address-Pool`` and ``Delegated-IPv6-Prefix-Pool`` - are defined in RFC6911. If they are not defined in your RADIUS server, - add new dictionary_. - -User interface can be put to VRF context via RADIUS Access-Accept packet, -or change it via RADIUS CoA. ``Accel-VRF-Name`` is used from these purposes. -It is custom `ACCEL-PPP attribute`_. Define it in your RADIUS server. - -Renaming clients interfaces by RADIUS -===================================== - -If the RADIUS server uses the attribute ``NAS-Port-Id``, ppp tunnels will be -renamed. - -.. note:: The value of the attribute ``NAS-Port-Id`` must be less than 16 - characters, otherwise the interface won't be renamed. - - -*********************** -Automatic VLAN Creation -*********************** - -.. cfgcmd:: set service pppoe-server interface <interface> vlan <id | range> - - VLAN's can be created by Accel-ppp on the fly via the use of a Kernel module - named ``vlan_mon``, which is monitoring incoming vlans and creates the - necessary VLAN if required and allowed. VyOS supports the use of either - VLAN ID's or entire ranges, both values can be defined at the same time for - an interface. - - When configured, PPPoE will create the necessary VLANs when required. Once - the user session has been cancelled and the VLAN is not needed anymore, VyOS - will remove it again. - -.. code-block:: none - - set service pppoe-server interface eth3 vlan 100 - set service pppoe-server interface eth3 vlan 200 - set service pppoe-server interface eth3 vlan 500-1000 - set service pppoe-server interface eth3 vlan 2000-3000 - -***************** -Bandwidth Shaping -***************** - -Bandwidth rate limits can be set for local users or RADIUS based -attributes. - -For Local Users -=============== - -.. cfgcmd:: set service pppoe-server authentication local-users username - <user> rate-limit download <bandwidth> - - Download bandwidth limit in kbit/s for `<user>`. - -.. cfgcmd:: set service pppoe-server authentication local-users username - <user> rate-limit upload <bandwidth> - - Upload bandwidth limit in kbit/s for `<user>`. - - -.. code-block:: none - - set service pppoe-server access-concentrator 'ACN' - set service pppoe-server authentication local-users username foo password 'bar' - set service pppoe-server authentication local-users username foo rate-limit download '20480' - set service pppoe-server authentication local-users username foo rate-limit upload '10240' - set service pppoe-server authentication mode 'local' - set service pppoe-server client-ip-pool IP-POOL range '10.1.1.100/24' - set service pppoe-server default-pool 'IP-POOL' - set service pppoe-server name-server '10.100.100.1' - set service pppoe-server name-server '10.100.200.1' - set service pppoe-server interface 'eth1' - set service pppoe-server gateway-address '10.1.1.2' - - -Once the user is connected, the user session is using the set limits and -can be displayed via ``show pppoe-server sessions``. - -.. code-block:: none - - show pppoe-server sessions - ifname | username | ip | calling-sid | rate-limit | state | uptime | rx-bytes | tx-bytes - -------+----------+------------+-------------------+-------------+--------+----------+----------+---------- - ppp0 | foo | 10.1.1.100 | 00:53:00:ba:db:15 | 20480/10240 | active | 00:00:11 | 214 B | 76 B - - -For RADIUS users -================ - -The current attribute ``Filter-Id`` is being used as default and can be -setup within RADIUS: - -Filter-Id=2000/3000 (means 2000Kbit down-stream rate and 3000Kbit -up-stream rate) - -The command below enables it, assuming the RADIUS connection has been -setup and is working. - -.. cfgcmd:: set service pppoe-server authentication radius rate-limit enable - - Use this command to enable bandwidth shaping via RADIUS. - -Other attributes can be used, but they have to be in one of the -dictionaries in */usr/share/accel-ppp/radius*. - -************** -Load Balancing -************** - - -.. cfgcmd:: set service pppoe-server pado-delay <number-of-ms> - sessions <number-of-sessions> - - Use this command to enable the delay of PADO (PPPoE Active Discovery - Offer) packets, which can be used as a session balancing mechanism - with other PPPoE servers. - -.. code-block:: none - - set service pppoe-server pado-delay 50 sessions '500' - set service pppoe-server pado-delay 100 sessions '1000' - set service pppoe-server pado-delay 300 sessions '3000' - -In the example above, the first 499 sessions connect without delay. PADO -packets will be delayed 50 ms for connection from 500 to 999, this trick -allows other PPPoE servers send PADO faster and clients will connect to -other servers. Last command says that this PPPoE server can serve only -3000 clients. - -**** -IPv6 -**** - -.. cfgcmd:: set service pppoe-server ppp-options - ipv6 <require | prefer | allow | deny> - - Specifies IPv6 negotiation preference. - - * **require** - Require IPv6 negotiation - * **prefer** - Ask client for IPv6 negotiation, do not fail if it rejects - * **allow** - Negotiate IPv6 only if client requests - * **deny** - Do not negotiate IPv6 (default value) - -.. cfgcmd:: set service pppoe-server client-ipv6-pool <IPv6-POOL-NAME> - prefix <address> mask <number-of-bits> - - Use this comand to set the IPv6 address pool from which an PPPoE client - will get an IPv6 prefix of your defined length (mask) to terminate the - PPPoE endpoint at their side. The mask length can be set from 48 to 128 - bit long, the default value is 64. - -.. cfgcmd:: set service pppoe-server client-ipv6-pool <IPv6-POOL-NAME> - delegate <address> delegation-prefix <number-of-bits> - - Use this command to configure DHCPv6 Prefix Delegation (RFC3633) on - PPPoE. You will have to set your IPv6 pool and the length of the - delegation prefix. From the defined IPv6 pool you will be handing out - networks of the defined length (delegation-prefix). The length of the - delegation prefix can be set from 32 to 64 bit long. - -.. cfgcmd:: set service pppoe-server default-ipv6-pool <IPv6-POOL-NAME> - - Use this command to define default IPv6 address pool name. - -.. code-block:: none - - set service pppoe-server ppp-options ipv6 allow - set service pppoe-server client-ipv6-pool IPv6-POOL delegate '2001:db8:8003::/48' delegation-prefix '56' - set service pppoe-server client-ipv6-pool IPv6-POOL prefix '2001:db8:8002::/48' mask '64' - set service pppoe-server default-ipv6-pool IPv6-POOL - -IPv6 Advanced Options -===================== -.. cfgcmd:: set service pppoe-server ppp-options ipv6-accept-peer-interface-id - - Accept peer interface identifier. By default is not defined. - -.. cfgcmd:: set service pppoe-server ppp-options ipv6-interface-id - <random | x:x:x:x> - - Specifies fixed or random interface identifier for IPv6. - By default is fixed. - - * **random** - Random interface identifier for IPv6 - * **x:x:x:x** - Specify interface identifier for IPv6 - -.. cfgcmd:: set service pppoe-server ppp-options ipv6-interface-id - <random | x:x:x:x> - - Specifies peer interface identifier for IPv6. By default is fixed. - - * **random** - Random interface identifier for IPv6 - * **x:x:x:x** - Specify interface identifier for IPv6 - * **ipv4-addr** - Calculate interface identifier from IPv4 address. - * **calling-sid** - Calculate interface identifier from calling-station-id. - -********* -Scripting -********* - -.. cfgcmd:: set service pppoe-server extended-scripts on-change <path_to_script> - - Script to run when session interface changed by RADIUS CoA handling - -.. cfgcmd:: set service pppoe-server extended-scripts on-down <path_to_script> - - Script to run when session interface going to terminate - -.. cfgcmd:: set service pppoe-server extended-scripts on-pre-up <path_to_script> - - Script to run before session interface comes up - -.. cfgcmd:: set service pppoe-server extended-scripts on-up <path_to_script> - - Script to run when session interface is completely configured and started - -**************** -Advanced Options -**************** - -Authentication Advanced Options -=============================== - -.. cfgcmd:: set service pppoe-server authentication local-users - username <user> disable - - Disable `<user>` account. - -.. cfgcmd:: set service pppoe-server authentication local-users - username <user> static-ip <address> - - Assign static IP address to `<user>` account. - -.. cfgcmd:: set service pppoe-server authentication protocols - <pap | chap | mschap | mschap-v2> - - Require the peer to authenticate itself using one of the following protocols: - pap, chap, mschap, mschap-v2. - -Client IP Pool Advanced Options -=============================== - -.. cfgcmd:: set service pppoe-server client-ip-pool <POOL-NAME> - next-pool <NEXT-POOL-NAME> - - Use this command to define the next address pool name. - -PPP Advanced Options -==================== - -.. cfgcmd:: set service pppoe-server ppp-options disable-ccp - - Disable Compression Control Protocol (CCP). - CCP is enabled by default. - -.. cfgcmd:: set service pppoe-server ppp-options interface-cache <number> - - Specifies number of interfaces to keep in cache. It means that don’t - destroy interface after corresponding session is destroyed, instead - place it to cache and use it later for new sessions repeatedly. - This should reduce kernel-level interface creation/deletion rate lack. - Default value is **0**. - -.. cfgcmd:: set service pppoe-server ppp-options ipv4 - <require | prefer | allow | deny> - - Specifies IPv4 negotiation preference. - - * **require** - Require IPv4 negotiation - * **prefer** - Ask client for IPv4 negotiation, do not fail if it rejects - * **allow** - Negotiate IPv4 only if client requests (Default value) - * **deny** - Do not negotiate IPv4 - -.. cfgcmd:: set service pppoe-server ppp-options lcp-echo-failure <number> - - Defines the maximum `<number>` of unanswered echo requests. Upon reaching the - value `<number>`, the session will be reset. Default value is **3**. - -.. cfgcmd:: set service pppoe-server ppp-options lcp-echo-interval <interval> - - If this option is specified and is greater than 0, then the PPP module will - send LCP pings of the echo request every `<interval>` seconds. - Default value is **30**. - -.. cfgcmd:: set service pppoe-server ppp-options lcp-echo-timeout - - Specifies timeout in seconds to wait for any peer activity. If this option - specified it turns on adaptive lcp echo functionality and "lcp-echo-failure" - is not used. Default value is **0**. - -.. cfgcmd:: set service pppoe-server ppp-options min-mtu <number> - - Defines minimum acceptable MTU. If client will try to negotiate less then - specified MTU then it will be NAKed or disconnected if rejects greater MTU. - Default value is **100**. - -.. cfgcmd:: set service pppoe-server ppp-options mppe <require | prefer | deny> - - Specifies :abbr:`MPPE (Microsoft Point-to-Point Encryption)` negotiation - preference. - - * **require** - ask client for mppe, if it rejects drop connection - * **prefer** - ask client for mppe, if it rejects don't fail. (Default value) - * **deny** - deny mppe - - Default behavior - don't ask client for mppe, but allow it if client wants. - Please note that RADIUS may override this option by MS-MPPE-Encryption-Policy - attribute. - -.. cfgcmd:: set service pppoe-server ppp-options mru <number> - - Defines preferred MRU. By default is not defined. - -Global Advanced options -======================= - -.. cfgcmd:: set service pppoe-server description <description> - - Set description. - -.. cfgcmd:: set service pppoe-server limits burst <value> - - Burst count - -.. cfgcmd:: set service pppoe-server limits connection-limit <value> - - Acceptable rate of connections (e.g. 1/min, 60/sec) - -.. cfgcmd:: set service pppoe-server limits timeout <value> - - Timeout in seconds - -.. cfgcmd:: set service pppoe-server mtu - - Maximum Transmission Unit (MTU) (default: **1492**) - -.. cfgcmd:: set service pppoe-server max-concurrent-sessions - - Maximum number of concurrent session start attempts - -.. cfgcmd:: set service pppoe-server name-server <address> - - Connected client should use `<address>` as their DNS server. This - command accepts both IPv4 and IPv6 addresses. Up to two nameservers - can be configured for IPv4, up to three for IPv6. - -.. cfgcmd:: set service pppoe-server service-name <names> - - Specifies Service-Name to respond. If absent any Service-Name is - acceptable and client’s Service-Name will be sent back. Also possible - set multiple service-names: `sn1,sn2,sn3` - -Per default the user session is being replaced if a second -authentication request succeeds. Such session requests can be either -denied or allowed entirely, which would allow multiple sessions for a -user in the latter case. If it is denied, the second session is being -rejected even if the authentication succeeds, the user has to terminate -its first session and can then authentication again. - -.. cfgcmd:: set service pppoe-server session-control - - * **disable**: Disables session control. - * **deny**: Deny second session authorization. - * **replace**: Terminate first session when second is authorized **(default)** - -.. cfgcmd:: set service pppoe-server shaper fwmark <1-2147483647> - - Match firewall mark value - -.. cfgcmd:: set service pppoe-server snmp master-agent - - Enable SNMP - -.. cfgcmd:: set service pppoe-server wins-server <address> - - Windows Internet Name Service (WINS) servers propagated to client - -********** -Monitoring -********** - -.. opcmd:: show pppoe-server sessions - - Use this command to locally check the active sessions in the PPPoE - server. - - -.. code-block:: none - - show pppoe-server sessions - ifname | username | ip | calling-sid | rate-limit | state | uptime | rx-bytes | tx-bytes - -------+----------+------------+-------------------+-------------+--------+----------+----------+---------- - ppp0 | foo | 10.1.1.100 | 00:53:00:ba:db:15 | 20480/10240 | active | 00:00:11 | 214 B | 76 B - - -******** -Examples -******** - -IPv4 -==== - -The example below uses ACN as access-concentrator name, assigns an -address from the pool 10.1.1.100-111, terminates at the local endpoint -10.1.1.1 and serves requests only on eth1. - -.. code-block:: none - - set service pppoe-server access-concentrator 'ACN' - set service pppoe-server authentication local-users username foo password 'bar' - set service pppoe-server authentication mode 'local' - set service pppoe-server client-ip-pool IP-POOL range '10.1.1.100-10.1.1.111' - set service pppoe-server default-pool 'IP-POOL' - set service pppoe-server interface eth1 - set service pppoe-server gateway-address '10.1.1.2' - set service pppoe-server name-server '10.100.100.1' - set service pppoe-server name-server '10.100.200.1' - - - -Dual-Stack IPv4/IPv6 provisioning with Prefix Delegation -======================================================== - -The example below covers a dual-stack configuration. - -.. code-block:: none - - set service pppoe-server authentication local-users username test password 'test' - set service pppoe-server authentication mode 'local' - set service pppoe-server client-ip-pool IP-POOL range '192.168.0.1/24' - set service pppoe-server default-pool 'IP-POOL' - set service pppoe-server client-ipv6-pool IPv6-POOL delegate '2001:db8:8003::/48' delegation-prefix '56' - set service pppoe-server client-ipv6-pool IPV6-POOL prefix '2001:db8:8002::/48' mask '64' - set service pppoe-server default-ipv6-pool IPv6-POOL - set service pppoe-server ppp-options ipv6 allow - set service pppoe-server name-server '10.1.1.1' - set service pppoe-server name-server '2001:db8:4860::8888' - set service pppoe-server interface 'eth2' - set service pppoe-server gateway-address '10.100.100.1' - -The client, once successfully authenticated, will receive an IPv4 and an -IPv6 /64 address to terminate the PPPoE endpoint on the client side and -a /56 subnet for the clients internal use. - -.. code-block:: none - - vyos@pppoe-server:~$ sh pppoe-server sessions - ifname | username | ip | ip6 | ip6-dp | calling-sid | rate-limit | state | uptime | rx-bytes | tx-bytes - --------+----------+-------------+--------------------------+---------------------+-------------------+------------+--------+----------+----------+---------- - ppp0 | test | 192.168.0.1 | 2001:db8:8002:0:200::/64 | 2001:db8:8003::1/56 | 00:53:00:12:42:eb | | active | 00:00:49 | 875 B | 2.1 KiB - -.. include:: /_include/common-references.txt -.. _dictionary: https://github.com/accel-ppp/accel-ppp/blob/master/ - accel-pppd/radius/dict/dictionary.rfc6911 -.. _`ACCEL-PPP attribute`: https://github.com/accel-ppp/accel-ppp/ - blob/master/accel-pppd/radius/dict/dictionary.accel diff --git a/docs/configuration/service/rst-router-advert.rst b/docs/configuration/service/rst-router-advert.rst deleted file mode 100644 index 80f5ae30..00000000 --- a/docs/configuration/service/rst-router-advert.rst +++ /dev/null @@ -1,130 +0,0 @@ -.. _router-advert: - -##################### -Router Advertisements -##################### - -:abbr:`RAs (Router advertisements)` are described in :rfc:`4861#section-4.6.2`. -They are part of what is known as :abbr:`SLAAC (Stateless Address -Autoconfiguration)`. - -Supported interface types: - - * bonding - * bridge - * ethernet - * geneve - * l2tpv3 - * openvpn - * pseudo-ethernet - * tunnel - * vxlan - * wireguard - * wireless - * wwan - -************* -Configuration -************* - -.. cfgcmd:: set service router-advert interface <interface> ... - -.. stop_vyoslinter - -.. csv-table:: - :header: "Field", "VyOS Option", "Description" - :widths: 10, 10, 20 - - "Cur Hop Limit", "hop-limit", "Hop count field of the outgoing RA packets" - """Managed address configuration"" flag", "managed-flag", "Tell hosts to use the administered stateful protocol (i.e. DHCP) for autoconfiguration" - """Other configuration"" flag", "other-config-flag", "Tell hosts to use the administered (stateful) protocol (i.e. DHCP) for autoconfiguration of other (non-address) information" - "MTU","link-mtu","Link MTU value placed in RAs, excluded in RAs if unset" - "Router Lifetime","default-lifetime","Lifetime associated with the default router in units of seconds" - "Reachable Time","reachable-time","Time, in milliseconds, that a node assumes a neighbor is reachable after having received a reachability confirmation" - "Retransmit Timer","retrans-timer","Time in milliseconds between retransmitted Neighbor Solicitation messages" - "Default Router Preference","default-preference","Preference associated with the default router" - "Interval", "interval", "Min and max intervals between unsolicited multicast RAs" - "DNSSL", "dnssl", "DNS search list to advertise" - "Name Server", "name-server", "Advertise DNS server per https://tools.ietf.org/html/rfc6106" - "Auto Ignore Prefix", "auto-ignore", "Exclude a prefix from being advertised when the wildcard ::/64 prefix is used" - "Captive Portal", "captive-portal", "Advertise a URL pointing to an RFC 8908-compliant API to tell hosts that they are behind a captive portal" - -.. start_vyoslinter - - -Advertising a Prefix --------------------- - -.. cfgcmd:: set service router-advert interface <interface> prefix <prefix/mask> - - .. note:: You can also opt for using `::/64` as prefix for your :abbr:`RAs (Router - Advertisements)`. This is a special wildcard prefix that will emit :abbr:`RAs (Router Advertisements)` for every prefix assigned to the interface. - This comes in handy when using dynamically obtained prefixes from DHCPv6-PD. - -.. stop_vyoslinter - -.. csv-table:: - :header: "VyOS Field", "Description" - :widths: 10,30 - - "decrement-lifetime", "Lifetime is decremented by the number of seconds since the last RA - use in conjunction with a DHCPv6-PD prefix" - "deprecate-prefix", "Upon shutdown, this option will deprecate the prefix by announcing it in the shutdown RA" - "no-autonomous-flag","Prefix can not be used for stateless address auto-configuration" - "no-on-link-flag","Prefix can not be used for on-link determination" - "preferred-lifetime","Time in seconds that the prefix will remain preferred (default 4 hours)" - "valid-lifetime","Time in seconds that the prefix will remain valid (default: 30 days)" - -.. start_vyoslinter - -Advertising a NAT64 Prefix --------------------------- - -.. cfgcmd:: set service router-advert interface <interface> nat64prefix <prefix/mask> - - Enable PREF64 option as outlined in :rfc:`8781`. - - NAT64 prefix mask must be one of: /32, /40, /48, /56, /64 or 96. - - .. note:: The well known NAT64 prefix is ``64:ff9b::/96`` - -.. stop_vyoslinter - -.. csv-table:: - :header: "VyOS Field", "Description" - :widths: 10,30 - - "valid-lifetime","Time in seconds that the prefix will remain valid (default: 65528 seconds)" - -.. start_vyoslinter - -Disabling Advertisements ------------------------- - -To disable advertisements without deleting the configuration: - -.. cfgcmd:: set service router-advert interface <interface> no-send-advert - - If set, the router will no longer send periodic router advertisements and - will not respond to router solicitations. - -.. cfgcmd:: set service router-advert interface <interface> no-send-interval - - Advertisement Interval Option (specified by Mobile IPv6) is always included in - Router Advertisements unless this option is set. - -******* -Example -******* - -Your LAN connected on eth0 uses prefix ``2001:db8:beef:2::/64`` with the router -beeing ``2001:db8:beef:2::1`` - -.. code-block:: none - - set interfaces ethernet eth0 address 2001:db8:beef:2::1/64 - - set service router-advert interface eth0 default-preference 'high' - set service router-advert interface eth0 name-server '2001:db8::1' - set service router-advert interface eth0 name-server '2001:db8::2' - set service router-advert interface eth0 other-config-flag - set service router-advert interface eth0 prefix 2001:db8:beef:2::/64 diff --git a/docs/configuration/service/rst-salt-minion.rst b/docs/configuration/service/rst-salt-minion.rst deleted file mode 100644 index 8638246b..00000000 --- a/docs/configuration/service/rst-salt-minion.rst +++ /dev/null @@ -1,53 +0,0 @@ -.. _saltminion: - -########### -Salt-Minion -########### - -SaltStack_ is Python-based, open-source -software for event-driven IT automation, remote task execution, and -configuration management. Supporting the "infrastructure as code" -approach to data center system and network deployment and management, -configuration automation, SecOps orchestration, vulnerability remediation, -and hybrid cloud control. - - -************ -Requirements -************ - -To use the Salt-Minion, a running Salt-Master is required. You can find more -in the `Salt Project Documentation -<https://docs.saltproject.io/en/latest/contents.html>`_ - -************* -Configuration -************* - -.. cfgcmd:: set service salt-minion hash <type> - - The hash type used when discovering file on master server (default: sha256) - -.. cfgcmd:: set service salt-minion id <id> - - Explicitly declare ID for this minion to use (default: hostname) - -.. cfgcmd:: set service salt-minion interval <1-1440> - - Interval in minutes between updates (default: 60) - -.. cfgcmd:: set service salt-minion master <hostname | IP> - - The hostname or IP address of the master - -.. cfgcmd:: set service salt-minion master-key <key> - - URL with signature of master for auth reply verification - - -Please take a look in the Automation section to find some usefull -Examples. - - - -.. _SaltStack: https://saltproject.io/
\ No newline at end of file diff --git a/docs/configuration/service/rst-snmp.rst b/docs/configuration/service/rst-snmp.rst deleted file mode 100644 index 6dc13240..00000000 --- a/docs/configuration/service/rst-snmp.rst +++ /dev/null @@ -1,276 +0,0 @@ -.. _snmp: - -#### -SNMP -#### - -:abbr:`SNMP (Simple Network Management Protocol)` is an Internet Standard -protocol for collecting and organizing information about managed devices on -IP networks and for modifying that information to change device behavior. -Devices that typically support SNMP include cable modems, routers, switches, -servers, workstations, printers, and more. - -SNMP is widely used in network management for network monitoring. SNMP exposes -management data in the form of variables on the managed systems organized in -a management information base (MIB_) which describe the system status and -configuration. These variables can then be remotely queried (and, in some -circumstances, manipulated) by managing applications. - -Three significant versions of SNMP have been developed and deployed. SNMPv1 is -the original version of the protocol. More recent versions, SNMPv2c and SNMPv3, -feature improvements in performance, flexibility and security. - -SNMP is a component of the Internet Protocol Suite as defined by the Internet -Engineering Task Force (IETF). It consists of a set of standards for network -management, including an application layer protocol, a database schema, and a -set of data objects. - -Overview and basic concepts -=========================== - -In typical uses of SNMP, one or more administrative computers called managers -have the task of monitoring or managing a group of hosts or devices on a -computer network. Each managed system executes a software component called an -agent which reports information via SNMP to the manager. - -An SNMP-managed network consists of three key components: - -* Managed devices -* Agent - software which runs on managed devices -* Network management station (NMS) - software which runs on the manager - -A managed device is a network node that implements an SNMP interface that -allows unidirectional (read-only) or bidirectional (read and write) access to -node-specific information. Managed devices exchange node-specific information -with the NMSs. Sometimes called network elements, the managed devices can be -any type of device, including, but not limited to, routers, access servers, -switches, cable modems, bridges, hubs, IP telephones, IP video cameras, -computer hosts, and printers. - -An agent is a network-management software module that resides on a managed -device. An agent has local knowledge of management information and translates -that information to or from an SNMP-specific form. - -A network management station executes applications that monitor and control -managed devices. NMSs provide the bulk of the processing and memory resources -required for network management. One or more NMSs may exist on any managed -network. - -.. figure:: /_static/images/service_snmp_communication_principles_diagram.* - :scale: 20 % - :alt: Principle of SNMP Communication - - Image thankfully borrowed from - https://en.wikipedia.org/wiki/File:SNMP_communication_principles_diagram.PNG - which is under the GNU Free Documentation License - -.. note:: VyOS SNMP supports both IPv4 and IPv6. - -SNMP Protocol Versions -====================== - -VyOS itself supports SNMPv2_ (version 2) and SNMPv3_ (version 3) where the -later is recommended because of improved security (optional authentication and -encryption). - -SNMPv2 ------- - -SNMPv2 is the original and most commonly used version. For authorizing clients, -SNMP uses the concept of communities. Communities may have authorization set -to read only (this is most common) or to read and write (this option is not -actively used in VyOS). - -SNMP can work synchronously or asynchronously. In synchronous communication, -the monitoring system queries the router periodically. In asynchronous, the -router sends notification to the "trap" (the monitoring host). - -SNMPv2 does not support any authentication mechanisms, other than client source -address, so you should specify addresses of clients allowed to monitor the -router. Note that SNMPv2 also supports no encryption and always sends data in -plain text. - -Example -^^^^^^^ - -.. code-block:: none - - # Define a community - set service snmp community routers authorization ro - - # Allow monitoring access from the entire network - set service snmp community routers network 192.0.2.0/24 - set service snmp community routers network 2001::db8:ffff:eeee::/64 - - # Allow monitoring access from specific addresses - set service snmp community routers client 203.0.113.10 - set service snmp community routers client 203.0.113.20 - - # Define optional router information - set service snmp location "UK, London" - set service snmp contact "admin@example.com" - - # Trap target if you want asynchronous communication - set service snmp trap-target 203.0.113.10 - - # Listen only on specific IP addresses (port defaults to 161) - set service snmp listen-address 172.16.254.36 port 161 - set service snmp listen-address 2001:db8::f00::1 - - -SNMPv3 ------- - -SNMPv3 (version 3 of the SNMP protocol) introduced a whole slew of new security -related features that have been missing from the previous versions. Security -was one of the biggest weakness of SNMP until v3. Authentication in SNMP -Versions 1 and 2 amounts to nothing more than a password (community string) -sent in clear text between a manager and agent. Each SNMPv3 message contains -security parameters which are encoded as an octet string. The meaning of these -security parameters depends on the security model being used. - -The security approach in SNMPv3 targets: - -* Confidentiality – Encryption of packets to prevent snooping by an - unauthorized source. - -* Integrity – Message integrity to ensure that a packet has not been tampered - while in transit including an optional packet replay protection mechanism. - -* Authentication – to verify that the message is from a valid source. - -.. _snmp:v3_example: - -Example -^^^^^^^ - -* Let SNMP daemon listen only on IP address 192.0.2.1 -* Configure new SNMP user named "vyos" with password "vyos12345678" -* New user will use SHA/AES for authentication and privacy - -.. code-block:: none - - set service snmp listen-address 192.0.2.1 - set service snmp location 'VyOS Datacenter' - set service snmp v3 engineid '000000000000000000000002' - set service snmp v3 group default mode 'ro' - set service snmp v3 group default view 'default' - set service snmp v3 user vyos auth plaintext-password 'vyos12345678' - set service snmp v3 user vyos auth type 'sha' - set service snmp v3 user vyos group 'default' - set service snmp v3 user vyos privacy plaintext-password 'vyos12345678' - set service snmp v3 user vyos privacy type 'aes' - set service snmp v3 view default oid 1 - -After commit the plaintext passwords will be hashed and stored in your -configuration. The resulting CLI config will look like: - -.. code-block:: none - - vyos@vyos# show service snmp - listen-address 192.0.2.1 { - } - location "VyOS Datacenter" - v3 { - engineid 000000000000000000000002 - group default { - mode ro - view default - } - user vyos { - auth { - encrypted-password 4e52fe55fd011c9c51ae2c65f4b78ca93dcafdfe - type sha - } - group default - privacy { - encrypted-password 4e52fe55fd011c9c51ae2c65f4b78ca93dcafdfe - type aes - } - } - view default { - oid 1 { - } - } - } - -You can test the SNMPv3 functionality from any linux based system, just run the -following command: ``snmpwalk -v 3 -u vyos -a SHA -A vyos12345678 -x AES --X vyos12345678 -l authPriv 192.0.2.1 .1`` - -VyOS MIBs -========= - -All SNMP MIBs are located in each image of VyOS here: ``/usr/share/snmp/mibs/`` - -You are be able to download the files using SCP, once the SSH service -has been activated like so - -.. code-block:: none - - scp -r vyos@your_router:/usr/share/snmp/mibs /your_folder/mibs - -SNMP Extensions -=============== - -To extend SNMP agent functionality, custom scripts can be executed every time -the agent is being called. This can be achieved by using -``arbitrary extensioncommands``. The first step is to create a functional -script of course, then upload it to your VyOS instance via the command -``scp your_script.sh vyos@your_router:/config/user-data``. -Once the script is uploaded, it needs to be configured via the command below. - - -.. code-block:: none - - set service snmp script-extensions extension-name my-extension script your_script.sh - commit - -.. stop_vyoslinter - -The OID ``.1.3.6.1.4.1.8072.1.3.2.3.1.1.4.116.101.115.116``, once called, will -contain the output of the extension. - -.. start_vyoslinter - -.. code-block:: none - - root@vyos:/home/vyos# snmpwalk -v2c -c public 127.0.0.1 nsExtendOutput1 - NET-SNMP-EXTEND-MIB::nsExtendOutput1Line."my-extension" = STRING: hello - NET-SNMP-EXTEND-MIB::nsExtendOutputFull."my-extension" = STRING: hello - NET-SNMP-EXTEND-MIB::nsExtendOutNumLines."my-extension" = INTEGER: 1 - NET-SNMP-EXTEND-MIB::nsExtendResult."my-extension" = INTEGER: 0 - -SolarWinds -========== - -If you happen to use SolarWinds Orion as NMS you can also use the Device -Templates Management. A template for VyOS can be easily imported. - -.. stop_vyoslinter - -Create a file named ``VyOS-1.3.6.1.4.1.44641.ConfigMgmt-Commands`` using the -following content: - - -.. code-block:: none - - <Configuration-Management Device="VyOS" SystemOID="1.3.6.1.4.1.44641"> - <Commands> - <Command Name="Reset" Value="set terminal width 0${CRLF}set terminal length 0"/> - <Command Name="Reboot" Value="reboot${CRLF}Yes"/> - <Command Name="EnterConfigMode" Value="configure"/> - <Command Name="ExitConfigMode" Value="commit${CRLF}exit"/> - <Command Name="DownloadConfig" Value="show configuration commands"/> - <Command Name="SaveConfig" Value="commit${CRLF}save"/> - <Command Name="Version" Value="show version"/> - <Command Name="MenuBased" Value="False"/> - <Command Name="VirtualPrompt" Value=":~"/> - </Commands> - </Configuration-Management> - -.. _MIB: https://en.wikipedia.org/wiki/Management_information_base -.. _SNMPv2: https://en.wikipedia.org/wiki/Simple_Network_Management_Protocol#Version_2 -.. _SNMPv3: https://en.wikipedia.org/wiki/Simple_Network_Management_Protocol#Version_3 - -.. start_vyoslinter diff --git a/docs/configuration/service/rst-ssh.rst b/docs/configuration/service/rst-ssh.rst deleted file mode 100644 index 11f58201..00000000 --- a/docs/configuration/service/rst-ssh.rst +++ /dev/null @@ -1,334 +0,0 @@ -.. _ssh: - -### -SSH -### - -:abbr:`SSH (Secure Shell)` is a cryptographic network protocol for operating -network services securely over an unsecured network. The standard TCP port for -SSH is 22. The best known example application is for remote login to computer -systems by users. - -SSH provides a secure channel over an unsecured network in a client-server -architecture, connecting an SSH client application with an SSH server. Common -applications include remote command-line login and remote command execution, -but any network service can be secured with SSH. The protocol specification -distinguishes between two major versions, referred to as SSH-1 and SSH-2. - -The most visible application of the protocol is for access to shell accounts -on Unix-like operating systems, but it sees some limited use on Windows as -well. In 2015, Microsoft announced that they would include native support for -SSH in a future release. - -SSH was designed as a replacement for Telnet and for unsecured remote shell -protocols such as the Berkeley rlogin, rsh, and rexec protocols. -Those protocols send information, notably passwords, in plaintext, -rendering them susceptible to interception and disclosure using packet -analysis. The encryption used by SSH is intended to provide confidentiality -and integrity of data over an unsecured network, such as the Internet. - -.. note:: VyOS 1.1 supported login as user ``root``. This has been removed due - to tighter security in VyOS 1.2. - -.. seealso:: SSH :ref:`ssh_key_based_authentication` - -Configuration -============= - -.. cfgcmd:: set service ssh port <port> - - Enabling SSH only requires you to specify the port ``<port>`` you want SSH to - listen on. By default, SSH runs on port 22. - -.. cfgcmd:: set service ssh listen-address <address> - - Specify IPv4/IPv6 listen address of SSH server. Multiple addresses can be - defined. - -.. cfgcmd:: set service ssh cipher <cipher> - - Define allowed ciphers used for the SSH connection. A number of allowed - ciphers can be specified, use multiple occurrences to allow multiple ciphers. - - List of supported ciphers: ``3des-cbc``, ``aes128-cbc``, ``aes192-cbc``, - ``aes256-cbc``, ``aes128-ctr``, ``aes192-ctr``, ``aes256-ctr``, - ``aes128-gcm@openssh.com``, ``aes256-gcm@openssh.com``, - ``chacha20-poly1305@openssh.com`` - -.. cfgcmd:: set service ssh disable-password-authentication - - Disable password based authentication. Login via SSH keys only. This hardens - security! - -.. cfgcmd:: set service ssh fido pin-required - - Require FIDO2 keys to attest that a user has been verified (e.g. via a PIN). - -.. cfgcmd:: set service ssh fido touch-required - - Require FIDO2 keys to attest that a user is physically present. - - VyOS supports SSH authentication using FIDO2-backed keys generated by OpenSSH. - Two FIDO2 key types are supported by OpenSSH: ``ed25519-sk``, ``ecdsa-sk`` - - Generic FIDO2-backed SSH key generation example: - - .. code-block:: none - - ssh-keygen -t ecdsa-sk -O verify-required -C "fido2-ssh-key" - - During key generation, OpenSSH will: - * Request user presence (for example, a physical touch or confirmation) - * Optionally request user verification (PIN), if supported by the authenticator - * Create a local key handle file and a corresponding public key (``.pub``) - - The private key material never leaves the authenticator device. - - VyOS configuration example: - - .. code-block:: none - - # Generate a FIDO2 SSH key on the client system - # Copy the public key to the VyOS instance - set system login user vyos authentication public-keys fido key '<public-key>' - set system login user vyos authentication public-keys fido type 'sk-ecdsa-sha2-nistp256@openssh.com' - set service ssh fido touch-required - - You can now log into the system using: ``ssh -i ~/.ssh/id_fido_key vyos@192.0.2.1`` - -.. cfgcmd:: set service ssh disable-host-validation - - Disable the host validation through reverse DNS lookups - can speedup login - time when reverse lookup is not possible. - -.. cfgcmd:: set service ssh mac <mac> - - Specifies the available :abbr:`MAC (Message Authentication Code)` algorithms. - The MAC algorithm is used in protocol version 2 for data integrity protection. - Multiple algorithms can be provided by using multiple commands, defining - one algorithm per command. - - List of supported MACs: ``hmac-md5``, ``hmac-md5-96``, ``hmac-ripemd160``, - ``hmac-sha1``, ``hmac-sha1-96``, ``hmac-sha2-256``, ``hmac-sha2-512``, - ``umac-64@openssh.com``, ``umac-128@openssh.com``, - ``hmac-md5-etm@openssh.com``, ``hmac-md5-96-etm@openssh.com``, - ``hmac-ripemd160-etm@openssh.com``, ``hmac-sha1-etm@openssh.com``, - ``hmac-sha1-96-etm@openssh.com``, ``hmac-sha2-256-etm@openssh.com``, - ``hmac-sha2-512-etm@openssh.com``, ``umac-64-etm@openssh.com``, - ``umac-128-etm@openssh.com`` - -.. cfgcmd:: set service ssh access-control <allow | deny> <group | user> <name> - - Add access-control directive to allow or deny users and groups. Directives - are processed in the following order of precedence: ``deny-users``, - ``allow-users``, ``deny-groups`` and ``allow-groups``. - -.. cfgcmd:: set service ssh client-keepalive-interval <interval> - - Specify timeout interval for keepalive message in seconds. - -.. cfgcmd:: set service ssh key-exchange <kex> - - Specify allowed :abbr:`KEX (Key Exchange)` algorithms. - - List of supported algorithms: ``diffie-hellman-group1-sha1``, - ``diffie-hellman-group14-sha1``, ``diffie-hellman-group14-sha256``, - ``diffie-hellman-group16-sha512``, ``diffie-hellman-group18-sha512``, - ``diffie-hellman-group-exchange-sha1``, - ``diffie-hellman-group-exchange-sha256``, - ``ecdh-sha2-nistp256``, ``ecdh-sha2-nistp384``, ``ecdh-sha2-nistp521``, - ``curve25519-sha256`` and ``curve25519-sha256@libssh.org``. - -.. cfgcmd:: set service ssh loglevel <quiet | fatal | error | info | verbose> - - Set the ``sshd`` log level. The default is ``info``. - -.. cfgcmd:: set service ssh vrf <name> - - Specify name of the :abbr:`VRF (Virtual Routing and Forwarding)` instance. - -.. cfgcmd:: set service ssh pubkey-accepted-algorithm <name> - - Specifies the signature algorithms that will be accepted for public key - authentication - - List of supported algorithms: ``ssh-ed25519``, - ``ssh-ed25519-cert-v01@openssh.com``, ``sk-ssh-ed25519@openssh.com``, - ``sk-ssh-ed25519-cert-v01@openssh.com``, ``ecdsa-sha2-nistp256``, - ``ecdsa-sha2-nistp256-cert-v01@openssh.com``, ``ecdsa-sha2-nistp384``, - ``ecdsa-sha2-nistp384-cert-v01@openssh.com``, ``ecdsa-sha2-nistp521``, - ``ecdsa-sha2-nistp521-cert-v01@openssh.com``, - ``sk-ecdsa-sha2-nistp256@openssh.com``, - ``sk-ecdsa-sha2-nistp256-cert-v01@openssh.com``, - ``webauthn-sk-ecdsa-sha2-nistp256@openssh.com``, - ``ssh-dss``, ``ssh-dss-cert-v01@openssh.com``, ``ssh-rsa``, - ``ssh-rsa-cert-v01@openssh.com``, ``rsa-sha2-256``, - ``rsa-sha2-256-cert-v01@openssh.com``, ``rsa-sha2-512``, - ``rsa-sha2-512-cert-v01@openssh.com`` - -.. cfgcmd:: set service ssh trusted-user-ca <name> - - Specify the name of the OpenSSH key-pair that acts as certificate authority - and will be used to verify user certificates. - - You can use it by adding the OpenSSH key-pair under the PKI subsystem. - - Example: - - .. code-block:: none - - # Generate key-pair acting as CA - $ ssh-keygen -f vyos-ssh-ca.key - - # Generate key for user: vyos_testca - $ ssh-keygen -f vyos_testca -C "vyos_tesca@vyos.net" - - # Sign public key from user vyos_testca and insert principal names: vyos, vyos_testca - # with a key lifetime of two weeks - after which the key is unusable - $ ssh-keygen -s vyos-ssh-ca.key -I vyos_testca@vyos.net -n vyos,vyos_testca -V +2w vyos_testca.pub - - $ set system login user vyos_testca - $ set pki openssh test_ca public key AAAAB3N..... - $ set pki openssh test_ca public type ssh-rsa - $ set service ssh trusted-user-ca test_ca - - You can now log into the system using: ``ssh -i vyos_testca vyos_testca@vyos.test.com`` - - -Dynamic-protection -================== -Protects host from brute-force attacks against -SSH. Log messages are parsed, line-by-line, for recognized patterns. If an -attack, such as several login failures within a few seconds, is detected, the -offending IP is blocked. Offenders are unblocked after a set interval. - -.. cfgcmd:: set service ssh dynamic-protection - - Allow ``ssh`` dynamic-protection. - -.. cfgcmd:: set service ssh dynamic-protection allow-from <address | prefix> - - Whitelist of addresses and networks. Always allow inbound connections from - these systems. - -.. cfgcmd:: set service ssh dynamic-protection block-time <sec> - - Block source IP in seconds. Subsequent blocks increase by a factor of 1.5 - The default is 120. - -.. cfgcmd:: set service ssh dynamic-protection detect-time <sec> - - Remember source IP in seconds before reset their score. The default is 1800. - -.. cfgcmd:: set service ssh dynamic-protection threshold <sec> - - Block source IP when their cumulative attack score exceeds threshold. The - default is 30. - -.. _ssh_operation: - -Operation -========= - -.. opcmd:: restart ssh - - Restart the SSH daemon process, the current session is not affected, only the - background daemon is restarted. - -.. opcmd:: generate ssh server-key - - Re-generated the public/private keyportion which SSH uses to secure - connections. - - .. note:: Already learned known_hosts files of clients need an update as the - public key will change. - -.. opcmd:: generate ssh client-key /path/to/private_key - - Re-generated a known pub/private keyfile which can be used to connect to - other services (e.g. RPKI cache). - - Example: - - .. code-block:: none - - vyos@vyos:~$ generate ssh client-key /config/auth/id_rsa_rpki - Generating public/private rsa key pair. - Your identification has been saved in /config/auth/id_rsa_rpki. - Your public key has been saved in /config/auth/id_rsa_rpki.pub. - The key fingerprint is: - SHA256:XGv2PpdOzVCzpmEzJZga8hTRq7B/ZYL3fXaioLFLS5Q vyos@vyos - The key's randomart image is: - +---[RSA 2048]----+ - | oo | - | ..o | - | . o.o.. o.| - | o+ooo o.o| - | Eo* =.o | - | o = +.o*+ | - | = o *.o.o| - | o * +.o+.+| - | =.. o=.oo| - +----[SHA256]-----+ - - Two new files ``/config/auth/id_rsa_rpki`` and - ``/config/auth/id_rsa_rpki.pub`` - will be created. - -.. opcmd:: generate public-key-command user <username> path <location> - - Generate the configuration mode commands to add a public key for - :ref:`ssh_key_based_authentication`. - ``<location>`` can be a local path or a URL pointing at a remote file. - - Supported remote protocols are FTP, FTPS, HTTP, HTTPS, SCP/SFTP and TFTP. - - Example: - - .. code-block:: none - - alyssa@vyos:~$ generate public-key-command user alyssa path sftp://example.net/home/alyssa/.ssh/id_rsa.pub - # To add this key as an embedded key, run the following commands: - configure - set system login user alyssa authentication public-keys alyssa@example.net key AAA... - set system login user alyssa authentication public-keys alyssa@example.net type ssh-rsa - commit - save - exit - - ben@vyos:~$ generate public-key-command user ben path ~/.ssh/id_rsa.pub - # To add this key as an embedded key, run the following commands: - configure - set system login user ben authentication public-keys ben@vyos key AAA... - set system login user ben authentication public-keys ben@vyos type ssh-dss - commit - save - exit - -.. opcmd:: show log ssh - - Show SSH server log. - -.. opcmd:: monitor log ssh - - Follow the SSH server log. - -.. opcmd:: show log ssh dynamic-protection - - Show SSH dynamic-protection log. - -.. opcmd:: monitor log ssh dynamic-protection - - Follow the SSH dynamic-protection log. - -.. opcmd:: show ssh dynamic-protection - - Show list of IPs currently blocked by SSH dynamic-protection. - -.. opcmd:: show ssh fingerprints - - Show SSH server public key fingerprints. - -.. opcmd:: show ssh fingerprints ascii - - Show SSH server public key fingerprints, including a visual ASCII art representation. diff --git a/docs/configuration/service/rst-suricata.rst b/docs/configuration/service/rst-suricata.rst deleted file mode 100644 index b72bc52a..00000000 --- a/docs/configuration/service/rst-suricata.rst +++ /dev/null @@ -1,101 +0,0 @@ -.. _suricata: - -######## -suricata -######## - -Suricata and VyOS are powerful tools for ensuring network security and traffic management. -Suricata is an open-source intrusion detection and prevention system (IDS/IPS) that analyzes network packets in real-time. - - -Suricata Features -================= - -Intrusion Detection (IDS): Analyzes network traffic and detects suspicious activities, attacks, and malicious traffic. -Intrusion Prevention (IPS): Blocks or modifies suspicious traffic in real-time, preventing attacks before they penetrate the network. -Network Security Monitoring (NSM): Collects and analyzes network data to detect anomalies and identify threats. -Multi-Protocol Support: Suricata supports analysis of various network protocols such as HTTP, FTP, SMB, and many others. -In configuration mode, the commands are as follows: - -.. code-block:: none - - vyos@vyos# set service suricata - Possible completions: - +> address-group Address group name - + interface Interface to use - > log Suricata log outputs - +> port-group Port group name - -These commands create a flexible interface for configuring the Suricata service, allowing users to specify addresses, ports, -and logging parameters. - -After completing the service configuration in configuration mode, the main configuration file suricata.yaml is created, -into which all specified parameters are added. Then, to ensure proper operation, the command :opcmd:`update suricata` must be run -from operational mode, waiting for Suricata to update all its rules, which are used for analyzing traffic for threats and attacks. - - -Configuration -============= - -.. cfgcmd:: set service suricata address-group <text> <address | group> - - Address groups are useful when you need to create rules that apply to specific IP addresses. - For example, if you want to create a rule that monitors traffic going to or from a specific IP address, - you can use the group name instead of the actual IP address. This simplifies rule management and makes the - configuration more flexible. - - * ``address`` IP address or subnet. - - * ``group`` Address group. - -.. cfgcmd:: set service suricata port-group <text> <address | group> - - Port groups are useful when you need to create rules that apply to specific ports. - For example, if you want to create a rule that monitors traffic directed to a specific port or group of ports, - you can use the group name instead of the actual port. This also simplifies rule management and makes - the configuration more flexible. - - * ``port`` Port number. - - * ``group`` Port group. - -.. cfgcmd:: set service suricata interface <text> - - The interface that will be monitored by the Suricata service. - - -.. cfgcmd:: set service suricata log eve <filename | filetype | type> - - Configuration of the logging file. - - * ``filename`` Log file (default: eve.json). - - * ``filetype`` EVE logging destination (default: regular). - - * ``type`` Log types. - -Operation Mode -============== - -.. cfgcmd:: update suricata - - Checks for the existence of the Suricata configuration file, updates the service, - and then restarts it. If the configuration file is not found, a message indicates that Suricata is not configured. - - -.. cfgcmd:: restart suricata - - Restarts the service. It checks if the Suricata service is active before attempting to restart it. - If it is not active, a message indicates that the service is not configured. This command is used when adding new rules manually. - -Conclusion -============== - -Using address and port groups allows you to make your Suricata configuration more flexible and manageable. -Instead of specifying IP addresses and ports directly in each rule, you can define them once in the vars section and then -reference them by group names. This is especially useful in large networks and complex configurations where multiple IP addresses -and ports need to be monitored. - - - -
\ No newline at end of file diff --git a/docs/configuration/service/rst-tftp-server.rst b/docs/configuration/service/rst-tftp-server.rst deleted file mode 100644 index 84acf3d4..00000000 --- a/docs/configuration/service/rst-tftp-server.rst +++ /dev/null @@ -1,80 +0,0 @@ -.. _tftp-server: - -########### -TFTP Server -########### - -:abbr:`TFTP (Trivial File Transfer Protocol)` is a simple, lockstep file -transfer protocol which allows a client to get a file from or put a file onto -a remote host. One of its primary uses is in the early stages of nodes booting -from a local area network. TFTP has been used for this application because it -is very simple to implement. - -Configuration -============= - -.. cfgcmd:: set service tftp-server directory <directory> - - Enable TFTP service by specifying the `<directory>` which will be used to serve - files. - -.. hint:: Choose your ``directory`` location carefully or you will loose the - content on image upgrades. Any directory under ``/config`` is save at this - will be migrated. - -.. cfgcmd:: set service tftp-server listen-address <address> - - Configure the IPv4 or IPv6 listen address of the TFTP server. Multiple IPv4 and - IPv6 addresses can be given. There will be one TFTP server instances listening - on each IP address. - -.. cfgcmd:: set service tftp-server listen-address <address> vrf <name> - -.. stop_vyoslinter - -Additional option to run TFTP server in the :abbr:`VRF (Virtual Routing and Forwarding)` context - -.. start_vyoslinter - -.. note:: Configuring a listen-address is essential for the service to work. - -.. cfgcmd:: set service tftp-server allow-upload - - Optional, if you want to enable uploads, else TFTP server will act as a - read-only server. - -Example -------- - -Provide TFTP server listening on both IPv4 and IPv6 addresses ``192.0.2.1`` and -``2001:db8::1`` serving the content from ``/config/tftpboot``. Uploading via -TFTP to this server is disabled. - -The resulting configuration will look like: - -.. code-block:: none - - vyos@vyos# show service - tftp-server { - directory /config/tftpboot - listen-address 2001:db8::1 - listen-address 192.0.2.1 - } - -Verification ------------- - -Client: - -.. code-block:: none - - vyos@RTR2:~$ tftp -p -l /config/config.boot -r backup 192.0.2.1 - backup1 100% |******************************| 723 0:00:00 ETA - -Server: - -.. code-block:: none - - vyos@RTR1# ls -ltr /config/tftpboot/ - total 1 - -rw-rw-rw- 1 tftp tftp 1995 May 19 16:02 backup diff --git a/docs/configuration/service/rst-webproxy.rst b/docs/configuration/service/rst-webproxy.rst deleted file mode 100644 index a6c5ff0a..00000000 --- a/docs/configuration/service/rst-webproxy.rst +++ /dev/null @@ -1,445 +0,0 @@ -.. _webproxy: - -######## -Webproxy -######## - -The proxy service in VyOS is based on Squid_ and some related modules. - -Squid_ is a caching and forwarding HTTP web proxy. It has a wide variety of -uses, including speeding up a web server by caching repeated requests, caching -web, DNS and other computer network lookups for a group of people sharing -network resources, and aiding security by filtering traffic. Although primarily -used for HTTP and FTP, Squid includes limited support for several other -protocols including Internet Gopher, SSL,[6] TLS and HTTPS. Squid does not -support the SOCKS protocol. - -URL Filtering is provided by SquidGuard_. - -************* -Configuration -************* - -.. cfgcmd:: set service webproxy append-domain <domain> - - Use this command to specify a domain name to be appended to domain-names - within URLs that do not include a dot ``.`` the domain is appended. - - Example: to be appended is set to ``vyos.net`` and the URL received is - ``www/foo.html``, the system will use the generated, final URL of - ``www.vyos.net/foo.html``. - - .. code-block:: none - - set service webproxy append-domain vyos.net - -.. cfgcmd:: set service webproxy cache-size <size> - - The size of the on-disk Proxy cache is user configurable. The Proxies default - cache-size is configured to 100 MB. - - Unit of this command is MB. - - .. code-block:: none - - set service webproxy cache-size 1024 - -.. cfgcmd:: set service webproxy default-port <port> - - Specify the port used on which the proxy service is listening for requests. - This port is the default port used for the specified listen-address. - - Default port is 3128. - - .. code-block:: none - - set service webproxy default-port 8080 - -.. cfgcmd:: set service webproxy domain-block <domain> - - Used to block specific domains by the Proxy. Specifying "vyos.net" will block - all access to vyos.net, and specifying ".xxx" will block all access to URLs - having an URL ending on .xxx. - - .. code-block:: none - - set service webproxy domain-block vyos.net - -.. cfgcmd:: set service webproxy domain-noncache <domain> - - Allow access to sites in a domain without retrieving them from the Proxy - cache. Specifying "vyos.net" will allow access to vyos.net but the pages - accessed will not be cached. It useful for working around problems with - "If-Modified-Since" checking at certain sites. - - .. code-block:: none - - set service webproxy domain-noncache vyos.net - -.. cfgcmd:: set service webproxy listen-address <address> - - Specifies proxy service listening address. The listen address is the IP - address on which the web proxy service listens for client requests. - - For security, the listen address should only be used on internal/trusted - networks! - - .. code-block:: none - - set service webproxy listen-address 192.0.2.1 - -.. cfgcmd:: set service webproxy listen-address <address> disable-transparent - - Disables web proxy transparent mode at a listening address. - - In transparent proxy mode, all traffic arriving on port 80 and destined for - the Internet is automatically forwarded through the proxy. This allows - immediate proxy forwarding without configuring client browsers. - - Non-transparent proxying requires that the client browsers be configured with - the proxy settings before requests are redirected. The advantage of this is - that the client web browser can detect that a proxy is in use and can behave - accordingly. In addition, web-transmitted malware can sometimes be blocked by - a non-transparent web proxy, since they are not aware of the proxy settings. - - .. code-block:: none - - set service webproxy listen-address 192.0.2.1 disable-transparent - -.. cfgcmd:: set service webproxy listen-address <address> port <port> - - Sets the listening port for a listening address. This overrides the default - port of 3128 on the specific listen address. - - .. code-block:: none - - set service webproxy listen-address 192.0.2.1 port 8080 - - -.. cfgcmd:: set service webproxy reply-block-mime <mime> - - Used to block a specific mime-type. - - .. code-block:: none - - # block all PDFs - set service webproxy reply-block-mime application/pdf - - -.. cfgcmd:: set service webproxy reply-body-max-size <size> - - Specifies the maximum size of a reply body in KB, used to limit the reply - size. - - All reply sizes are accepted by default. - - .. code-block:: none - - set service webproxy reply-body-max-size 2048 - -.. cfgcmd:: set service webproxy safe-ports <port> - - Add new port to Safe-ports acl. Ports included by default in Safe-ports acl: - 21, 70, 80, 210, 280, 443, 488, 591, 777, 873, 1025-65535 - -.. cfgcmd:: set service webproxy ssl-safe-ports <port> - - Add new port to SSL-ports acl. Ports included by default in SSL-ports acl: - 443 - - -Authentication -============== - -The embedded Squid proxy can use LDAP to authenticate users against a company -wide directory. The following configuration is an example of how to use Active -Directory as authentication backend. Queries are done via LDAP. - -.. cfgcmd:: set service webproxy authentication children <number> - - Maximum number of authenticator processes to spawn. If you start too few - Squid will have to wait for them to process a backlog of credential - verifications, slowing it down. When password verifications are done via a - (slow) network you are likely to need lots of authenticator processes. - - This defaults to 5. - - .. code-block:: none - - set service webproxy authentication children 10 - -.. cfgcmd:: set service webproxy authentication credentials-ttl <time> - - Specifies how long squid assumes an externally validated username:password - pair is valid for - in other words how often the helper program is called for - that user. Set this low to force revalidation with short lived passwords. - - Time is in minutes and defaults to 60. - - .. code-block:: none - - set service webproxy authentication credentials-ttl 120 - - -.. cfgcmd:: set service webproxy authentication method <ldap> - - Proxy authentication method, currently only LDAP is supported. - - .. code-block:: none - - set service webproxy authentication method ldap - -.. cfgcmd:: set service webproxy authentication realm - - Specifies the protection scope (aka realm name) which is to be reported to - the client for the authentication scheme. It is commonly part of the text - the user will see when prompted for their username and password. - - .. code-block:: none - - set service webproxy authentication realm "VyOS proxy auth" - -LDAP ----- - -.. cfgcmd:: set service webproxy authentication ldap base-dn <base-dn> - - Specifies the base DN under which the users are located. - - .. code-block:: none - - set service webproxy authentication ldap base-dn DC=vyos,DC=net - - -.. cfgcmd:: set service webproxy authentication ldap bind-dn <bind-dn> - - The DN and password to bind as while performing searches. - - .. code-block:: none - - set service webproxy authentication ldap bind-dn CN=proxyuser,CN=Users,DC=vyos,DC=net - -.. cfgcmd:: set service webproxy authentication ldap filter-expression <expr> - - LDAP search filter to locate the user DN. Required if the users are in a - hierarchy below the base DN, or if the login name is not what builds the user - specific part of the users DN. - - The search filter can contain up to 15 occurrences of %s which will be - replaced by the username, as in "uid=%s" for :rfc:`2037` directories. For a - detailed description of LDAP search filter syntax see :rfc:`2254`. - - .. code-block:: none - - set service webproxy authentication ldap filter-expression (cn=%s) - -.. cfgcmd:: set service webproxy authentication ldap password <password> - - The DN and password to bind as while performing searches. As the password - needs to be printed in plain text in your Squid configuration it is strongly - recommended to use a account with minimal associated privileges. This to limit - the damage in case someone could get hold of a copy of your Squid - configuration file. - - .. code-block:: none - - set service webproxy authentication ldap password vyos - -.. cfgcmd:: set service webproxy authentication ldap persistent-connection - - Use a persistent LDAP connection. Normally the LDAP connection is only open - while validating a username to preserve resources at the LDAP server. This - option causes the LDAP connection to be kept open, allowing it to be reused - for further user validations. - - Recommended for larger installations. - - .. code-block:: none - - set service webproxy authentication ldap persistent-connection - -.. cfgcmd:: set service webproxy authentication ldap port <port> - - Specify an alternate TCP port where the ldap server is listening if other than - the default LDAP port 389. - - .. code-block:: none - - set service webproxy authentication ldap port 389 - -.. cfgcmd:: set service webproxy authentication ldap server <server> - - Specify the LDAP server to connect to. - - .. code-block:: none - - set service webproxy authentication ldap server ldap.vyos.net - - -.. cfgcmd:: set service webproxy authentication ldap use-ssl - - Use TLS encryption. - - .. code-block:: none - - set service webproxy authentication ldap use-ssl - - -.. cfgcmd:: set service webproxy authentication ldap username-attribute <attr> - - Specifies the name of the DN attribute that contains the username/login. - Combined with the base DN to construct the users DN when no search filter is - specified (`filter-expression`). - - Defaults to 'uid' - - .. note:: This can only be done if all your users are located directly under - the same position in the LDAP tree and the login name is used for naming - each user object. If your LDAP tree does not match these criterias or if you - want to filter who are valid users then you need to use a search filter to - search for your users DN (`filter-expression`). - - .. code-block:: none - - set service webproxy authentication ldap username-attribute uid - -.. cfgcmd:: set service webproxy authentication ldap version <2 | 3> - - LDAP protocol version. Defaults to 3 if not specified. - - .. code-block:: none - - set service webproxy authentication ldap version 2 - -URL filtering -============= - -.. include:: /_include/need_improvement.txt - - -.. cfgcmd:: set service webproxy url-filtering disable - - Disables web filtering without discarding configuration. - - .. code-block:: none - - set service webproxy url-filtering disable - -********* -Operation -********* - -.. include:: /_include/need_improvement.txt - -Filtering -========= - -Update ------- - -If you want to use existing blacklists you have to create/download a database -first. Otherwise you will not be able to commit the config changes. - - -.. opcmd:: update webproxy blacklists - - Download/Update complete blacklist - - .. code-block:: none - - vyos@vyos:~$ update webproxy blacklists - Warning: No url-filtering blacklist installed - Would you like to download a default blacklist? [confirm][y] - Connecting to ftp.univ-tlse1.fr (193.49.48.249:21) - blacklists.gz 100% |*************************************************************************************************************| 17.0M 0:00:00 ETA - Uncompressing blacklist... - Checking permissions... - Skip link for [ads] -> [publicite] - Building DB for [adult/domains] - 2467177 entries - Building DB for [adult/urls] - 67798 entries - Skip link for [aggressive] -> [agressif] - Building DB for [agressif/domains] - 348 entries - Building DB for [agressif/urls] - 36 entries - Building DB for [arjel/domains] - 69 entries - ... - - Building DB for [webmail/domains] - 374 entries - Building DB for [webmail/urls] - 9 entries - - The webproxy daemon must be restarted - Would you like to restart it now? [confirm][y] - - [ ok ] Restarting squid (via systemctl): squid.service. - vyos@vyos:~$ - -.. opcmd:: update webproxy blacklists category <category> - - Download/Update partial blacklist. - - Use tab completion to get a list of categories. - -* To auto update the blacklist files - - :code:`set service webproxy url-filtering squidguard auto-update - update-hour 23` - -* To configure blocking add the following to the configuration - - :code:`set service webproxy url-filtering squidguard block-category ads` - - :code:`set service webproxy url-filtering squidguard block-category malware` - -Bypassing the webproxy ----------------------- - -.. include:: /_include/need_improvement.txt - -Some services don't work correctly when being handled via a web proxy. -So sometimes it is useful to bypass a transparent proxy: - -* To bypass the proxy for every request that is directed to a specific - destination: - - :code:`set service webproxy whitelist destination-address 198.51.100.33` - - :code:`set service webproxy whitelist destination-address 192.0.2.0/24` - - -* To bypass the proxy for every request that is coming from a specific source: - - :code:`set service webproxy whitelist source-address 192.168.1.2` - - :code:`set service webproxy whitelist source-address 192.168.2.0/24` - - (This can be useful when a called service has many and/or often changing - destination addresses - e.g. Netflix.) - -******** -Examples -******** - -.. code-block:: none - - vyos@vyos# show service webproxy - authentication { - children 5 - credentials-ttl 60 - ldap { - base-dn DC=example,DC=local - bind-dn CN=proxyuser,CN=Users,DC=example,DC=local - filter-expression (cn=%s) - password Qwert1234 - server ldap.example.local - username-attribute cn - } - method ldap - realm "VyOS Webproxy" - } - cache-size 100 - default-port 3128 - listen-address 192.168.188.103 { - disable-transparent - } - -.. _Squid: http://www.squid-cache.org/ -.. _SquidGuard: http://www.squidguard.org/ diff --git a/docs/configuration/system/rst-acceleration.rst b/docs/configuration/system/rst-acceleration.rst deleted file mode 100644 index 63506d6d..00000000 --- a/docs/configuration/system/rst-acceleration.rst +++ /dev/null @@ -1,157 +0,0 @@ -.. _acceleration: - -############ -Acceleration -############ - -In this command tree, all hardware acceleration options will be handled. -At the moment only `Intel® QAT`_ is supported - -********** -Intel® QAT -********** - -.. opcmd:: show system acceleration qat - - use this command to check if there is an Intel® QAT supported Processor in - your system. - - .. code-block:: - - vyos@vyos:~$ show system acceleration qat - 01:00.0 Co-processor [0b40]: Intel Corporation Atom Processor C3000 Series QuickAssist Technology [8086:19e2] (rev 11) - - if there is non device the command will show ```No QAT device found``` - -.. cfgcmd:: set system acceleration qat - - if there is a supported device, enable Intel® QAT - -.. opcmd:: show system acceleration qat status - - Check if the Intel® QAT device is up and ready to do the job. - - .. code-block:: - - vyos@vyos:~$ show system acceleration qat status - Checking status of all devices. - There is 1 QAT acceleration device(s) in the system: - qat_dev0 - type: c3xxx, inst_id: 0, node_id: 0, bsf: 0000:01:00.0, #accel: 3 #engines: 6 state: up - -Operation Mode -============== - -.. opcmd:: show system acceleration qat device <device> config - - Show the full config uploaded to the QAT device. - -.. opcmd:: show system acceleration qat device <device> flows - - Get an overview over the encryption counters. - -.. opcmd:: show system acceleration qat interrupts - - Show binded qat device interrupts to certain core. - - -Example -======= - -Let's build a simple VPN between 2 Intel® QAT ready devices. - -Side A: - -.. code-block:: - - - set interfaces vti vti1 address '192.168.1.2/24' - set vpn ipsec authentication psk right id '10.10.10.2' - set vpn ipsec authentication psk right id '10.10.10.1' - set vpn ipsec authentication psk right secret 'Qwerty123' - set vpn ipsec esp-group MyESPGroup proposal 1 encryption 'aes256' - set vpn ipsec esp-group MyESPGroup proposal 1 hash 'sha256' - set vpn ipsec ike-group MyIKEGroup proposal 1 dh-group '14' - set vpn ipsec ike-group MyIKEGroup proposal 1 encryption 'aes256' - set vpn ipsec ike-group MyIKEGroup proposal 1 hash 'sha256' - set vpn ipsec interface 'eth0' - set vpn ipsec site-to-site peer right authentication local-id '10.10.10.2' - set vpn ipsec site-to-site peer right authentication mode 'pre-shared-secret' - set vpn ipsec site-to-site peer right authentication remote-id '10.10.10.1' - set vpn ipsec site-to-site peer right connection-type 'initiate' - set vpn ipsec site-to-site peer right default-esp-group 'MyESPGroup' - set vpn ipsec site-to-site peer right ike-group 'MyIKEGroup' - set vpn ipsec site-to-site peer right local-address '10.10.10.2' - set vpn ipsec site-to-site peer right remote-address '10.10.10.1' - set vpn ipsec site-to-site peer right vti bind 'vti1' - -Side B: - -.. code-block:: - - set interfaces vti vti1 address '192.168.1.1/24' - set vpn ipsec authentication psk left id '10.10.10.2' - set vpn ipsec authentication psk left id '10.10.10.1' - set vpn ipsec authentication psk left secret 'Qwerty123' - set vpn ipsec esp-group MyESPGroup proposal 1 encryption 'aes256' - set vpn ipsec esp-group MyESPGroup proposal 1 hash 'sha256' - set vpn ipsec ike-group MyIKEGroup proposal 1 dh-group '14' - set vpn ipsec ike-group MyIKEGroup proposal 1 encryption 'aes256' - set vpn ipsec ike-group MyIKEGroup proposal 1 hash 'sha256' - set vpn ipsec interface 'eth0' - set vpn ipsec site-to-site peer left authentication local-id '10.10.10.1' - set vpn ipsec site-to-site peer left authentication mode 'pre-shared-secret' - set vpn ipsec site-to-site peer left authentication remote-id '10.10.10.2' - set vpn ipsec site-to-site peer left connection-type 'initiate' - set vpn ipsec site-to-site peer left default-esp-group 'MyESPGroup' - set vpn ipsec site-to-site peer left ike-group 'MyIKEGroup' - set vpn ipsec site-to-site peer left local-address '10.10.10.1' - set vpn ipsec site-to-site peer left remote-address '10.10.10.2' - set vpn ipsec site-to-site peer left vti bind 'vti1' - -a bandwidth test over the VPN got these results: - -.. code-block:: - - Connecting to host 192.168.1.2, port 5201 - [ 9] local 192.168.1.1 port 51344 connected to 192.168.1.2 port 5201 - [ ID] Interval Transfer Bitrate Retr Cwnd - [ 9] 0.00-1.01 sec 32.3 MBytes 268 Mbits/sec 0 196 KBytes - [ 9] 1.01-2.03 sec 32.5 MBytes 268 Mbits/sec 0 208 KBytes - [ 9] 2.03-3.03 sec 32.5 MBytes 271 Mbits/sec 0 208 KBytes - [ 9] 3.03-4.04 sec 32.5 MBytes 272 Mbits/sec 0 208 KBytes - [ 9] 4.04-5.00 sec 31.2 MBytes 272 Mbits/sec 0 208 KBytes - [ 9] 5.00-6.01 sec 32.5 MBytes 272 Mbits/sec 0 234 KBytes - [ 9] 6.01-7.04 sec 32.5 MBytes 265 Mbits/sec 0 234 KBytes - [ 9] 7.04-8.04 sec 32.5 MBytes 272 Mbits/sec 0 234 KBytes - [ 9] 8.04-9.04 sec 32.5 MBytes 273 Mbits/sec 0 336 KBytes - [ 9] 9.04-10.00 sec 31.2 MBytes 272 Mbits/sec 0 336 KBytes - - - - - - - - - - - - - - - - - - - - - - - - - - - [ ID] Interval Transfer Bitrate Retr - [ 9] 0.00-10.00 sec 322 MBytes 270 Mbits/sec 0 sender - [ 9] 0.00-10.00 sec 322 MBytes 270 Mbits/sec receiver - -with :cfgcmd:`set system acceleration qat` on both systems the bandwidth -increases. - -.. code-block:: - - Connecting to host 192.168.1.2, port 5201 - [ 9] local 192.168.1.1 port 51340 connected to 192.168.1.2 port 5201 - [ ID] Interval Transfer Bitrate Retr Cwnd - [ 9] 0.00-1.00 sec 97.3 MBytes 817 Mbits/sec 0 1000 KBytes - [ 9] 1.00-2.00 sec 92.5 MBytes 776 Mbits/sec 0 1.07 MBytes - [ 9] 2.00-3.00 sec 92.5 MBytes 776 Mbits/sec 0 820 KBytes - [ 9] 3.00-4.00 sec 92.5 MBytes 776 Mbits/sec 0 899 KBytes - [ 9] 4.00-5.00 sec 91.2 MBytes 765 Mbits/sec 0 972 KBytes - [ 9] 5.00-6.00 sec 92.5 MBytes 776 Mbits/sec 0 1.02 MBytes - [ 9] 6.00-7.00 sec 92.5 MBytes 776 Mbits/sec 0 1.08 MBytes - [ 9] 7.00-8.00 sec 92.5 MBytes 776 Mbits/sec 0 1.14 MBytes - [ 9] 8.00-9.00 sec 91.2 MBytes 765 Mbits/sec 0 915 KBytes - [ 9] 9.00-10.00 sec 92.5 MBytes 776 Mbits/sec 0 1000 KBytes - - - - - - - - - - - - - - - - - - - - - - - - - - - [ ID] Interval Transfer Bitrate Retr - [ 9] 0.00-10.00 sec 927 MBytes 778 Mbits/sec 0 sender - [ 9] 0.00-10.01 sec 925 MBytes 775 Mbits/sec receiver - - -.. _`Intel® QAT`: https://www.intel.com/content/www/us/en/architecture-and-technology/intel-quick-assist-technology-overview.html diff --git a/docs/configuration/system/rst-conntrack.rst b/docs/configuration/system/rst-conntrack.rst deleted file mode 100644 index 59209b36..00000000 --- a/docs/configuration/system/rst-conntrack.rst +++ /dev/null @@ -1,210 +0,0 @@ - -######### -Conntrack -######### - -VyOS can be configured to track connections using the connection -tracking subsystem. Connection tracking becomes operational once either -stateful firewall or NAT is configured. - -********* -Configure -********* - -.. cfgcmd:: set system conntrack table-size <1-50000000> - :defaultvalue: - - The connection tracking table contains one entry for each connection being - tracked by the system. - -.. cfgcmd:: set system conntrack expect-table-size <1-50000000> - :defaultvalue: - - The connection tracking expect table contains one entry for each expected - connection related to an existing connection. These are generally used by - “connection tracking helper” modules such as FTP. - The default size of the expect table is 2048 entries. - -.. cfgcmd:: set system conntrack hash-size <1-50000000> - :defaultvalue: - - Set the size of the hash table. The connection tracking hash table makes - searching the connection tracking table faster. The hash table uses - “buckets” to record entries in the connection tracking table. - -.. cfgcmd:: set system conntrack modules ftp -.. cfgcmd:: set system conntrack modules h323 -.. cfgcmd:: set system conntrack modules nfs -.. cfgcmd:: set system conntrack modules pptp -.. cfgcmd:: set system conntrack modules sip -.. cfgcmd:: set system conntrack modules sqlnet -.. cfgcmd:: set system conntrack modules tftp - - Configure the connection tracking protocol helper modules. - All modules are enable by default. - - | Use `delete system conntrack modules` to deactive all modules. - | Or, for example ftp, `delete system conntrack modules ftp`. - -.. cfgcmd:: set system conntrack tcp half-open-connections <1-21474836> - :defaultvalue: - - Set the maximum number of TCP half-open connections. - -.. cfgcmd:: set system conntrack tcp loose <enable | disable> - :defaultvalue: - - Policy to track previously established connections. - -.. cfgcmd:: set system conntrack tcp max-retrans <1-2147483647> - :defaultvalue: - - Set the number of TCP maximum retransmit attempts. - -Contrack Timeouts -================= - -You can define custom timeout values to apply to a specific subset of -connections, based on a packet and flow selector. To do this, you need to -create a rule defining the packet and flow selector. - -.. cfgcmd:: set system conntrack timeout custom [ipv4 | ipv6] rule <1-999999> - description <test> - - Set a rule description. - -.. cfgcmd:: set system conntrack timeout custom [ipv4 | ipv6] rule <1-999999> - destination address <ip-address> -.. cfgcmd:: set system conntrack timeout custom [ipv4 | ipv6] rule <1-999999> - source address <ip-address> - - Set a destination and/or source address. Accepted input for ipv4: - - .. code-block:: none - - set system conntrack timeout custom ipv4 rule <1-999999> [source | destination] address - Possible completions: - <x.x.x.x> IPv4 address to match - <x.x.x.x/x> IPv4 prefix to match - <x.x.x.x>-<x.x.x.x> IPv4 address range to match - !<x.x.x.x> Match everything except the specified address - !<x.x.x.x/x> Match everything except the specified prefix - !<x.x.x.x>-<x.x.x.x> Match everything except the specified range - - set system conntrack timeout custom ipv6 rule <1-999999> [source | destination] address - Possible completions: - <h:h:h:h:h:h:h:h> IP address to match - <h:h:h:h:h:h:h:h/x> Subnet to match - <h:h:h:h:h:h:h:h>-<h:h:h:h:h:h:h:h> - IP range to match - !<h:h:h:h:h:h:h:h> Match everything except the specified address - !<h:h:h:h:h:h:h:h/x> Match everything except the specified prefix - !<h:h:h:h:h:h:h:h>-<h:h:h:h:h:h:h:h> - Match everything except the specified range - -.. cfgcmd:: set system conntrack timeout custom [ipv4 | ipv6] rule <1-999999> - destination port <value> -.. cfgcmd:: set system conntrack timeout custom [ipv4 | ipv6] rule <1-999999> - source port <value> - - Set a destination and/or source port. Accepted input: - - .. code-block:: none - - <port name> Named port (any name in /etc/services, e.g., http) - <1-65535> Numbered port - <start>-<end> Numbered port range (e.g., 1001-1005) - - Multiple destination ports can be specified as a comma-separated list. - The whole list can also be "negated" using '!'. For example: - `!22,telnet,http,123,1001-1005`` - -.. cfgcmd:: set system conntrack timeout custom [ipv4 | ipv6] rule <1-999999> - protocol tcp close <1-21474836> -.. cfgcmd:: set system conntrack timeout custom [ipv4 | ipv6] rule <1-999999> - protocol tcp close-wait <1-21474836> -.. cfgcmd:: set system conntrack timeout custom [ipv4 | ipv6] rule <1-999999> - protocol tcp established <1-21474836> -.. cfgcmd:: set system conntrack timeout custom [ipv4 | ipv6] rule <1-999999> - protocol tcp fin-wait <1-21474836> -.. cfgcmd:: set system conntrack timeout custom [ipv4 | ipv6] rule <1-999999> - protocol tcp last-ack <1-21474836> -.. cfgcmd:: set system conntrack timeout custom [ipv4 | ipv6] rule <1-999999> - protocol tcp syn-recv <1-21474836> -.. cfgcmd:: set system conntrack timeout custom [ipv4 | ipv6] rule <1-999999> - protocol tcp syn-sent <1-21474836> -.. cfgcmd:: set system conntrack timeout custom [ipv4 | ipv6] rule <1-999999> - protocol tcp time-wait <1-21474836> -.. cfgcmd:: set system conntrack timeout custom [ipv4 | ipv6] rule <1-999999> - protocol udp replied <1-21474836> -.. cfgcmd:: set system conntrack timeout custom [ipv4 | ipv6] rule <1-999999> - protocol udp unreplied <1-21474836> - - Set the timeout in seconds for a protocol or state in a custom rule. - -Conntrack ignore rules -====================== - -.. note:: **Important note about conntrack ignore rules:** - Starting from vyos-1.5-rolling-202406120020, ignore rules can be defined in - ``set firewall [ipv4 | ipv6] prerouting raw ...``. It's expected that in - the future the conntrack ignore rules will be removed. - - Customized ignore rules, based on a packet and flow selector. - -.. cfgcmd:: set system conntrack ignore [ipv4 | ipv6] rule <1-999999> - description <text> -.. cfgcmd:: set system conntrack ignore [ipv4 | ipv6] rule <1-999999> - destination address <ip-address> -.. cfgcmd:: set system conntrack ignore [ipv4 | ipv6] rule <1-999999> - destination port <port> -.. cfgcmd:: set system conntrack ignore [ipv4 | ipv6] rule <1-999999> - inbound-interface <interface> -.. cfgcmd:: set system conntrack ignore [ipv4 | ipv6] rule <1-999999> - protocol <protocol> -.. cfgcmd:: set system conntrack ignore [ipv4 | ipv6] rule <1-999999> - source address <ip-address> -.. cfgcmd:: set system conntrack ignore [ipv4 | ipv6] rule <1-999999> - source port <port> -.. cfgcmd:: set system conntrack ignore [ipv4 | ipv6] 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. - -Conntrack log -============= - -.. cfgcmd:: set system conntrack log event destroy -.. cfgcmd:: set system conntrack log event new -.. cfgcmd:: set system conntrack log event update - - Log the connection tracking events per type. - -.. cfgcmd:: set system conntrack log event destroy icmp -.. cfgcmd:: set system conntrack log event destroy other -.. cfgcmd:: set system conntrack log event destroy tcp -.. cfgcmd:: set system conntrack log event destroy udp -.. cfgcmd:: set system conntrack log event new icmp -.. cfgcmd:: set system conntrack log event new other -.. cfgcmd:: set system conntrack log event new tcp -.. cfgcmd:: set system conntrack log event new udp -.. cfgcmd:: set system conntrack log event update icmp -.. cfgcmd:: set system conntrack log event update other -.. cfgcmd:: set system conntrack log event update tcp -.. cfgcmd:: set system conntrack log event update udp - - Log the connection tracking events per protocol. - -.. cfgcmd:: set system conntrack log timestamp - - Turn on flow-based timestamp extension. - -.. cfgcmd:: set system conntrack log queue-size <100-999999> - - Manage internal queue size, default size is 4096 events. - -.. cfgcmd:: set system conntrack log log-level <info | debug> - - Manage log level diff --git a/docs/configuration/system/rst-console.rst b/docs/configuration/system/rst-console.rst deleted file mode 100644 index a0e46afb..00000000 --- a/docs/configuration/system/rst-console.rst +++ /dev/null @@ -1,57 +0,0 @@ -.. _serial-console: - -############## -Serial Console -############## - -For the average user a serial console has no advantage over a console offered -by a directly attached keyboard and screen. Serial consoles are much slower, -taking up to a second to fill a 80 column by 24 line screen. Serial consoles -generally only support non-proportional ASCII text, with limited support for -languages other than English. - -There are some scenarios where serial consoles are useful. System administration -of remote computers is usually done using :ref:`ssh`, but there are times when -access to the console is the only way to diagnose and correct software failures. -Major upgrades to the installed distribution may also require console access. - - -.. cfgcmd:: set system console device <device> - - Defines the specified device as a system console. Available console devices - can be (see completion helper): - - * ``ttySN`` - Serial device name - * ``ttyAMAN``- Serial device name for some arm64 systems - * ``ttyUSBX`` - USB Serial device name - * ``hvc0`` - Xen console - -.. cfgcmd:: set system console device <device> kernel - - When set, the selected serial console is used as the kernel boot console. - When removed, the kernel boot console falls back to tty0. - - .. note:: Only one serial console can carry the ``kernel`` option. - When VyOS is installed via serial console, this option is set automatically - for the serial interface used during installation; usually ``ttyS0`` or - ``ttyAMA0``. - -.. cfgcmd:: set system console device <device> speed <speed> - - The speed (baudrate) of the console device. Supported values are: - - * ``1200`` - 1200 bps - * ``2400`` - 2400 bps - * ``4800`` - 4800 bps - * ``9600`` - 9600 bps - * ``19200`` - 19,200 bps - * ``38400`` - 38,400 bps (default for Xen console) - * ``57600`` - 57,600 bps - * ``115200`` - 115,200 bps (default for serial console) - - .. note:: If you use USB to serial converters for connecting to your VyOS - appliance please note that most of them use software emulation without flow - control. This means you should start with a common baud rate (most likely - 9600 baud) as otherwise you probably can not connect to the device using - high speed baud rates as your serial converter simply can not process this - data rate. diff --git a/docs/configuration/system/rst-default-route.rst b/docs/configuration/system/rst-default-route.rst deleted file mode 100644 index e102eb9c..00000000 --- a/docs/configuration/system/rst-default-route.rst +++ /dev/null @@ -1,40 +0,0 @@ -.. _default_gateway: - -##################### -Default Gateway/Route -##################### - -In the past (VyOS 1.1) used a gateway-address configured under the system tree -(:cfgcmd:`set system gateway-address <address>`), this is no longer supported -and existing configurations are migrated to the new CLI command. - -Configuration -============= - -.. cfgcmd:: set protocols static route 0.0.0.0/0 next-hop <address> - - Specify static route into the routing table sending all non local traffic - to the nexthop address `<address>`. - - -.. cfgcmd:: delete protocols static route 0.0.0.0/0 - - Delete default route from the system. - -Operation -========= - -.. opcmd:: show ip route 0.0.0.0 - - Show routing table entry for the default route. - - .. code-block:: none - - vyos@vyos:~$ show ip route 0.0.0.0 - Routing entry for 0.0.0.0/0 - Known via "static", distance 10, metric 0, best - Last update 09:46:30 ago - * 172.18.201.254, via eth0.201 - -.. seealso:: Configuration of :ref:`routing-static` - diff --git a/docs/configuration/system/rst-flow-accounting.rst b/docs/configuration/system/rst-flow-accounting.rst deleted file mode 100644 index 0664eac7..00000000 --- a/docs/configuration/system/rst-flow-accounting.rst +++ /dev/null @@ -1,203 +0,0 @@ -.. _flow-accounting: - -############### -Flow Accounting -############### - -VyOS supports flow-accounting for both IPv4 and IPv6 traffic. The system acts -as a flow exporter, and you are free to use it with any compatible collector. - -Flows can be exported via protocol NetFlow (versions 5, 9 and -10/IPFIX). Additionally, you may save flows to an in-memory table -internally in a router. - -.. warning:: You need to disable the in-memory table in production environments! - Using :abbr:`IMT (In-Memory Table)` may lead to heavy CPU overloading and - unstable flow-accounting behavior. - - -NetFlow / IPFIX -=============== -NetFlow is a feature that was introduced on Cisco routers around 1996 that -provides the ability to collect IP network traffic as it enters or exits an -interface. By analyzing the data provided by NetFlow, a network administrator -can determine things such as the source and destination of traffic, class of -service, and the causes of congestion. A typical flow monitoring setup (using -NetFlow) consists of three main components: - -* **exporter**: aggregates packets into flows and exports flow records towards - one or more flow collectors -* **collector**: responsible for reception, storage and pre-processing of flow - data received from a flow exporter -* **application**: analyzes received flow data in the context of intrusion - detection or traffic profiling, for example - -For connectionless protocols as like ICMP and UDP, a flow is considered -complete once no more packets for this flow appear after configurable timeout. - -NetFlow is usually enabled on a per-interface basis to limit load on the router -components involved in NetFlow, or to limit the amount of NetFlow records -exported. - -Configuration -============= - -.. warning:: Using NetFlow on routers with high traffic levels may lead to - high CPU usage and may affect the router's performance. In such cases, - consider using sFlow instead. - -In order for flow accounting information to be collected and displayed for an -interface, the interface must be configured for flow accounting. - -.. cfgcmd:: set system flow-accounting interface <interface> - - Configure and enable collection of flow information for the interface - identified by `<interface>`. - - You can configure multiple interfaces which would participate in flow - accounting. - -.. note:: Will be recorded only packets/flows on **incoming** direction in - configured interfaces by default. - - -By default, recorded flows will be saved internally and can be listed with the -CLI command. You may disable using the local in-memory table with the command: - -.. cfgcmd:: set system flow-accounting disable-imt - - If you need to sample also egress traffic, you may want to - configure egress flow-accounting: - -.. cfgcmd:: set system flow-accounting enable-egress - - Internally, in flow-accounting processes exist a buffer for data exchanging - between core process and plugins (each export target is a separated plugin). - If you have high traffic levels or noted some problems with missed records - or stopping exporting, you may try to increase a default buffer size (10 - MiB) with the next command: - -.. cfgcmd:: set system flow-accounting buffer-size <buffer size> - - In case, if you need to catch some logs from flow-accounting daemon, you may - configure logging facility: - -.. cfgcmd:: set system flow-accounting syslog-facility <facility> - - Set the syslog facility for flow-accounting log messages. Supported values - include ``daemon``, ``local0`` through ``local7``, and other standard syslog - facilities. - -Flow Export ------------ - -In addition to displaying flow accounting information locally, one can also -exported them to a collection server. - -NetFlow -^^^^^^^ - -.. cfgcmd:: set system flow-accounting netflow version <version> - - There are multiple versions available for the NetFlow data. The `<version>` - used in the exported flow data can be configured here. The following - versions are supported: - - * **5** - Most common version, but restricted to IPv4 flows only - * **9** - NetFlow version 9 (default) - * **10** - :abbr:`IPFIX (IP Flow Information Export)` as per :rfc:`3917` - -.. cfgcmd:: set system flow-accounting netflow server <address> - - Configure address of NetFlow collector. NetFlow server at `<address>` can - be both listening on an IPv4 or IPv6 address. - -.. cfgcmd:: set system flow-accounting netflow source-ip <address> - - IPv4 or IPv6 source address of NetFlow packets - -.. cfgcmd:: set system flow-accounting netflow engine-id <id> - - NetFlow engine-id which will appear in NetFlow data. The range is 0 to 255. - -.. cfgcmd:: set system flow-accounting netflow sampling-rate <rate> - - Use this command to configure the sampling rate for flow accounting. The - system samples one in every `<rate>` packets, where `<rate>` is the value - configured for the sampling-rate option. The advantage of sampling every n - packets, where n > 1, allows you to decrease the amount of processing - resources required for flow accounting. The disadvantage of not sampling - every packet is that the statistics produced are estimates of actual data - flows. - - Per default every packet is sampled (that is, the sampling rate is 1). - -.. cfgcmd:: set system flow-accounting netflow timeout expiry-interval - <interval> - - Specifies the interval at which Netflow data will be sent to a collector. As - per default, Netflow data will be sent every 60 seconds. - - You may also additionally configure timeouts for different types of - connections. - -.. cfgcmd:: set system flow-accounting netflow max-flows <n> - - If you want to change the maximum number of flows, which are tracking - simultaneously, you may do this with this command (default 8192). - -Example: --------- - -NetFlow v5 example: - -.. code-block:: none - - set system flow-accounting netflow engine-id 100 - set system flow-accounting netflow version 5 - set system flow-accounting netflow server 192.168.2.10 port 2055 - -Operation -========= - -Once flow accounting is configured on an interfaces it provides the ability to -display captured network traffic information for all configured interfaces. - -.. opcmd:: show flow-accounting interface <interface> - - Show flow accounting information for given `<interface>`. - - .. stop_vyoslinter - - .. code-block:: none - - vyos@vyos:~$ show flow-accounting interface eth0 - IN_IFACE SRC_MAC DST_MAC SRC_IP DST_IP SRC_PORT DST_PORT PROTOCOL TOS PACKETS FLOWS BYTES - ---------- ----------------- ----------------- ------------------------ --------------- ---------- ---------- ---------- ----- --------- ------- ------- - eth0 00:53:01:a8:28:ac ff:ff:ff:ff:ff:ff 192.0.2.2 255.255.255.255 5678 5678 udp 0 1 1 178 - eth0 00:53:01:b2:2f:34 33:33:ff:00:00:00 fe80::253:01ff:feb2:2f34 ff02::1:ff00:0 0 0 ipv6-icmp 0 2 1 144 - eth0 00:53:01:1a:b4:53 33:33:ff:00:00:00 fe80::253:01ff:fe1a:b453 ff02::1:ff00:0 0 0 ipv6-icmp 0 1 1 72 - eth0 00:53:01:b2:22:48 00:53:02:58:a2:92 192.0.2.100 192.0.2.14 40152 22 tcp 16 39 1 2064 - eth0 00:53:01:c8:33:af ff:ff:ff:ff:ff:ff 192.0.2.3 255.255.255.255 5678 5678 udp 0 1 1 154 - eth0 00:53:01:b2:22:48 00:53:02:58:a2:92 192.0.2.100 192.0.2.14 40006 22 tcp 16 146 1 9444 - eth0 00:53:01:b2:22:48 00:53:02:58:a2:92 192.0.2.100 192.0.2.14 0 0 icmp 192 27 1 4455 - - .. 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 - IN_IFACE SRC_MAC DST_MAC SRC_IP DST_IP SRC_PORT DST_PORT PROTOCOL TOS PACKETS FLOWS BYTES - ---------- ----------------- ----------------- ----------- ---------- ---------- ---------- ---------- ----- --------- ------- ------- - eth0 00:53:01:b2:22:48 00:53:02:58:a2:92 192.0.2.100 192.0.2.14 40006 22 tcp 16 197 2 12940 - eth0 00:53:01:b2:22:48 00:53:02:58:a2:92 192.0.2.100 192.0.2.14 40152 22 tcp 16 94 1 4924 - eth0 00:53:01:b2:22:48 00:53:02:58:a2:92 192.0.2.100 192.0.2.14 0 0 icmp 192 36 1 5877 - - .. start_vyoslinter diff --git a/docs/configuration/system/rst-frr.rst b/docs/configuration/system/rst-frr.rst deleted file mode 100644 index 2fa6e3c3..00000000 --- a/docs/configuration/system/rst-frr.rst +++ /dev/null @@ -1,43 +0,0 @@ -.. _system_frr: - -### -FRR -### - -VyOS uses `FRRouting <https://frrouting.org/>`_ as the control plane for dynamic -and static routing. The routing daemon behavior can be adjusted during runtime, -but requires either a restart of the routing daemon, or a reboot of the system. - -.. cfgcmd:: set system frr bmp - - Enable :abbr:`BMP (BGP Monitoring Protocol)` support. - -.. cfgcmd:: set system frr descriptors <numer> - - This allows the operator to control the number of open file descriptors - each daemon is allowed to start with. If the operator plans to run bgp with - several thousands of peers then this is where we would modify FRR to allow - this to happen. - -.. cfgcmd:: set system frr irdp - - Enable ICMP Router Discovery Protocol support. - -.. cfgcmd:: set system frr profile <traditional | datacenter> - - Select an FRR profile to adapt its default settings. If unset, the - traditional profile is applied. - -.. cfgcmd:: set system frr snmp <daemon> - - Enable SNMP support for an individual routing daemon. - - Supported daemons: - - - bgpd - - isisd - - ldpd - - ospf6d - - ospfd - - ripd - - zebra diff --git a/docs/configuration/system/rst-host-name.rst b/docs/configuration/system/rst-host-name.rst deleted file mode 100644 index 4d1567bf..00000000 --- a/docs/configuration/system/rst-host-name.rst +++ /dev/null @@ -1,68 +0,0 @@ -.. _host-information: - -################ -Host Information -################ - -This section describes the system's host information and how to configure them, -it covers the following topics: - -* Host name -* Domain -* IP address -* Aliases - -Hostname -======== - -A hostname is the label (name) assigned to a network device (a host) on a -network and is used to distinguish one device from another on specific networks -or over the internet. On the other hand this will be the name which appears on -the command line prompt. - -.. cfgcmd:: set system host-name <hostname> - - The hostname can be up to 63 characters. A hostname - must start and end with a letter or digit, and have as interior characters - only letters, digits, or a hyphen. - - The default hostname used is `vyos`. - -Domain Name -=========== - -A domain name is the label (name) assigned to a computer network and is thus -unique. VyOS appends the domain name as a suffix to any unqualified name. For -example, if you set the domain name `example.com`, and you would ping the -unqualified name of `crux`, then VyOS qualifies the name to `crux.example.com`. - -.. cfgcmd:: set system domain-name <domain> - - Configure system domain name. A domain name must start and end with a letter - or digit, and have as interior characters only letters, digits, or a hyphen. - -Static Hostname Mapping -======================= - -How an IP address is assigned to an interface in :ref:`ethernet-interface`. -This section shows how to statically map an IP address to a hostname for local -(meaning on this VyOS instance) name resolution. This is the VyOS equivalent to -`/etc/hosts` file entries. - -.. note:: Do *not* manually edit `/etc/hosts`. This file will automatically be - regenerated on boot based on the settings in this section, which means you'll - lose all your manual edits. Instead, configure static host mappings as follows. - -.. cfgcmd:: set system static-host-mapping host-name <hostname> inet <address> - - Create a static hostname mapping which will always resolve the name - `<hostname>` to IP address `<address>`. - - -.. cfgcmd:: set system static-host-mapping host-name <hostname> alias <alias> - - Create named `<alias>` for the configured static mapping for `<hostname>`. - Thus the address configured as :cfgcmd:`set system static-host-mapping - host-name <hostname> inet <address>` can be reached via multiple names. - - Multiple aliases can be specified per host-name. diff --git a/docs/configuration/system/rst-index.rst b/docs/configuration/system/rst-index.rst deleted file mode 100644 index c0113cce..00000000 --- a/docs/configuration/system/rst-index.rst +++ /dev/null @@ -1,36 +0,0 @@ -###### -System -###### - - -.. toctree:: - :maxdepth: 1 - :includehidden: - - acceleration - conntrack - console - flow-accounting - frr - host-name - ip - ipv6 - lcd - login - name-server - option - proxy - sflow - syslog - sysctl - task-scheduler - time-zone - updates - watchdog - - -.. toctree:: - :maxdepth: 1 - :includehidden: - - default-route diff --git a/docs/configuration/system/rst-ip.rst b/docs/configuration/system/rst-ip.rst deleted file mode 100644 index c724faac..00000000 --- a/docs/configuration/system/rst-ip.rst +++ /dev/null @@ -1,120 +0,0 @@ -## -IP -## - -System configuration commands ------------------------------ - -.. cfgcmd:: set system ip disable-forwarding - - Use this command to disable IPv4 forwarding on all interfaces. - -.. cfgcmd:: set system ip disable-directed-broadcast - - Use this command to disable IPv4 directed broadcast forwarding on all - interfaces. - - If set, IPv4 directed broadcast forwarding will be completely disabled - regardless of whether per-interface directed broadcast forwarding is - enabled or not. - -.. cfgcmd:: set system ip arp table-size <number> - - Use this command to define the maximum number of entries to keep in - the ARP cache (1024, 2048, 4096, 8192, 16384, 32768). - -.. cfgcmd:: set system ip multipath layer4-hashing - - Use this command to use Layer 4 information for IPv4 ECMP hashing. - -.. cfgcmd:: set system ip import-table <table-id> - - Use this command to immport the table, by given table id, into the main RIB. - -.. cfgcmd:: set system ip import-table <table-id> distance <distance> - - Use this command to override the default distance when importing routers - from the alternate table. - -.. cfgcmd:: set system ip import-table <table-id> route-map <route-map> - - Use this command to filter routes that are imported into the main table - from alternate table using route-map. - -Zebra/Kernel route filtering -^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -Zebra supports prefix-lists and Route Maps to match routes received from -other FRR components. The permit/deny facilities provided by these commands -can be used to filter which routes zebra will install in the kernel. - -.. cfgcmd:: set system ip protocol <protocol> route-map <route-map> - - Apply a route-map filter to routes for the specified protocol. The following - protocols can be used: any, babel, bgp, eigrp, isis, ospf, rip, static - - .. note:: If you choose any as the option that will cause all protocols that - are sending routes to zebra. - -Nexthop Tracking -^^^^^^^^^^^^^^^^ - -Nexthop tracking resolve nexthops via the default route by default. This is enabled -by default for a traditional profile of FRR which we use. It and can be disabled if -you do not want to e.g. allow BGP to peer across the default route. - -.. cfgcmd:: set system ip nht no-resolve-via-default - - Do not allow IPv4 nexthop tracking to resolve via the default route. This - parameter is configured per-VRF, so the command is also available in the VRF - subnode. - -Operational commands --------------------- - -show commands -^^^^^^^^^^^^^ - -See below the different parameters available for the IPv4 **show** command: - -.. code-block:: none - - vyos@vyos:~$ show ip - Possible completions: - access-list Show all IP access-lists - as-path-access-list - Show all as-path-access-lists - bgp Show Border Gateway Protocol (BGP) information - community-list - Show IP community-lists - extcommunity-list - Show extended IP community-lists - forwarding Show IP forwarding status - groups Show IP multicast group membership - igmp Show IGMP (Internet Group Management Protocol) information - large-community-list - Show IP large-community-lists - multicast Show IP multicast - ospf Show IPv4 Open Shortest Path First (OSPF) routing information - pim Show PIM (Protocol Independent Multicast) information - ports Show IP ports in use by various system services - prefix-list Show all IP prefix-lists - protocol Show IP route-maps per protocol - rip Show Routing Information Protocol (RIP) information - route Show IP routes - - -reset commands -^^^^^^^^^^^^^^ - -And the different IPv4 **reset** commands available: - -.. code-block:: none - - vyos@vyos:~$ reset ip - Possible completions: - arp Reset Address Resolution Protocol (ARP) cache - bgp Clear Border Gateway Protocol (BGP) statistics or status - igmp IGMP clear commands - multicast IP multicast routing table - route Reset IP route diff --git a/docs/configuration/system/rst-ipv6.rst b/docs/configuration/system/rst-ipv6.rst deleted file mode 100644 index eaa1d2b8..00000000 --- a/docs/configuration/system/rst-ipv6.rst +++ /dev/null @@ -1,178 +0,0 @@ -#### -IPv6 -#### - -System configuration commands ------------------------------ - -.. cfgcmd:: set system ipv6 disable-forwarding - - Use this command to disable IPv6 forwarding on all interfaces. - -.. cfgcmd:: set system ipv6 neighbor table-size <number> - - Use this command to define the maximum number of entries to keep in - the Neighbor cache (1024, 2048, 4096, 8192, 16384, 32768). - -.. cfgcmd:: set system ipv6 strict-dad - - Use this command to disable IPv6 operation on interface when - Duplicate Address Detection fails on Link-Local address. - -.. cfgcmd:: set system ipv6 multipath layer4-hashing - - Use this command to user Layer 4 information for ECMP hashing. - -Zebra/Kernel route filtering -^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -Zebra supports prefix-lists and Route Maps to match routes received from -other FRR components. The permit/deny facilities provided by these commands -can be used to filter which routes zebra will install in the kernel. - -.. cfgcmd:: set system ipv6 protocol <protocol> route-map <route-map> - - Apply a route-map filter to routes for the specified protocol. The following - protocols can be used: any, babel, bgp, isis, ospfv3, ripng, static - - .. note:: If you choose any as the option that will cause all protocols that - are sending routes to zebra. - -Nexthop Tracking -^^^^^^^^^^^^^^^^ - -Nexthop tracking resolve nexthops via the default route by default. This is enabled -by default for a traditional profile of FRR which we use. It and can be disabled if -you do not want to e.g. allow BGP to peer across the default route. - -.. cfgcmd:: set system ipv6 nht no-resolve-via-default - - Do not allow IPv6 nexthop tracking to resolve via the default route. This - parameter is configured per-VRF, so the command is also available in the VRF - subnode. - -Operational commands --------------------- - -Show commands -^^^^^^^^^^^^^ - -.. opcmd:: show ipv6 neighbors - - Use this command to show IPv6 Neighbor Discovery Protocol information. - -.. opcmd:: show ipv6 groups - - Use this command to show IPv6 multicast group membership. - -.. opcmd:: show ipv6 forwarding - - Use this command to show IPv6 forwarding status. - -.. opcmd:: show ipv6 route - - Use this command to show IPv6 routes. - - Check the many parameters available for the `show ipv6 route` command: - - .. code-block:: none - - vyos@vyos:~$ show ipv6 route - Possible completions: - <Enter> Execute the current command - <X:X::X:X> Show IPv6 routes of given address or prefix - <X:X::X:X/M> - bgp Show IPv6 BGP routes - cache Show kernel IPv6 route cache - connected Show IPv6 connected routes - forward Show kernel IPv6 route table - isis Show IPv6 ISIS routes - kernel Show IPv6 kernel routes - ospfv3 Show IPv6 OSPF6 routes - ripng Show IPv6 RIPNG routes - static Show IPv6 static routes - summary Show IPv6 routes summary - table Show IP routes in policy table - tag Show only routes with tag - vrf Show IPv6 routes in VRF - - -.. opcmd:: show ipv6 prefix-list - - Use this command to show all IPv6 prefix lists - - There are different parameters for getting prefix-list information: - - .. code-block:: none - - vyos@vyos:~$ show ipv6 prefix-list - Possible completions: - <Enter> Execute the current command - <WORD> Show specified IPv6 prefix-list - detail Show detail of IPv6 prefix-lists - summary Show summary of IPv6 prefix-lists - -.. opcmd:: show ipv6 access-list - - Use this command to show all IPv6 access lists - - You can also specify which IPv6 access-list should be shown: - - .. code-block:: none - - vyos@vyos:~$ show ipv6 access-list - Possible completions: - <Enter> Execute the current command - <text> Show specified IPv6 access-list - - - -.. opcmd:: show ipv6 ospfv3 - - Use this command to get information about OSPFv3. - - You can get more specific OSPFv3 information by using the parameters - shown below: - - .. code-block:: none - - vyos@vyos:~$ show ipv6 ospfv3 - Possible completions: - <Enter> Execute the current command - area Show OSPFv3 spf-tree information - border-routers - Show OSPFv3 border-router (ABR and ASBR) information - database Show OSPFv3 Link state database information - interface Show OSPFv3 interface information - linkstate Show OSPFv3 linkstate routing information - neighbor Show OSPFv3 neighbor information - redistribute Show OSPFv3 redistribute External information - route Show OSPFv3 routing table information - -.. opcmd:: show ipv6 ripng - - Use this command to get information about the RIPNG protocol - -.. opcmd:: show ipv6 ripng status - - Use this command to show the status of the RIPNG protocol - - -Reset commands -^^^^^^^^^^^^^^ - -.. opcmd:: reset bgp ipv6 <address> - - Use this command to clear Border Gateway Protocol statistics or - status. - - -.. opcmd:: reset ipv6 neighbors <address | interface> - - Use this command to reset IPv6 Neighbor Discovery Protocol cache for - an address or interface. - -.. opcmd:: reset ipv6 route cache - - Use this command to flush the kernel IPv6 route cache. - An address can be added to flush it only for that route. diff --git a/docs/configuration/system/rst-lcd.rst b/docs/configuration/system/rst-lcd.rst deleted file mode 100644 index 3fcf01dd..00000000 --- a/docs/configuration/system/rst-lcd.rst +++ /dev/null @@ -1,45 +0,0 @@ -.. _system-display: - -#################### -System Display (LCD) -#################### - -The system LCD :abbr:`LCD (Liquid-crystal display)` option is for users running -VyOS on hardware that features an LCD display. This is typically a small display -built in an 19 inch rack-mountable appliance. Those displays are used to show -runtime data. - -To configure your LCD display you must first identify the used hardware, and -connectivity of the display to your system. This can be any serial port -(`ttySxx`) or serial via USB or even old parallel port interfaces. - -Configuration -============= - -.. cfgcmd:: set system lcd device <device> - - This is the name of the physical interface used to connect to your LCD - display. Tab completion is supported and it will list you all available - serial interface. - - For serial via USB port information please refor to: :ref:`hardware_usb`. - -.. cfgcmd:: set system lcd model <model> - - This is the LCD model used in your system. - - At the time of this writing the following displays are supported: - - * Crystalfontz CFA-533 - - * Crystalfontz CFA-631 - - * Crystalfontz CFA-633 - - * Crystalfontz CFA-635 - - .. note:: We can't support all displays from the beginning. If your display - type is missing, please create a feature request via Phabricator_. - -.. include:: /_include/common-references.txt - diff --git a/docs/configuration/system/rst-login.rst b/docs/configuration/system/rst-login.rst deleted file mode 100644 index 1a2c2c5a..00000000 --- a/docs/configuration/system/rst-login.rst +++ /dev/null @@ -1,597 +0,0 @@ -:lastproofread: 2026-01-12 - -.. _user_management: - -##################### -Login/user management -##################### - -The default VyOS user account (``vyos``), as well as newly created user accounts, -possess full system configuration privileges. These accounts are granted sudo -privileges, allowing them to execute commands as the root user. - -VyOS supports both local authentication and remote authentication via -:abbr:`RADIUS (Remote Authentication Dial-In User Service)`/ :abbr:`TACACS+ -(Terminal Access Controller Access-Control System)`. - - -Local authentication -==================== - -.. cfgcmd:: set system login user <name> full-name "<string>" - - **Configure the real name or description for a system user.** - - If the description includes spaces, enclose ``<string>`` in double quotes. - - If the user ``<name>`` already exists, the command updates the current - description. If not, it creates a new user with the specified description. - -.. cfgcmd:: set system login user <name> authentication plaintext-password - <password> - - **Configure a password for a system user.** - - Enter the password in plaintext. Upon ``commit``, VyOS hashes the password for - secure storage and removes the plaintext value. - - If the user ``<name>`` already exists, the command updates the current password. - If not, it creates a new user with the specified plaintext password. - -.. cfgcmd:: set system login user <name> authentication encrypted-password - <password> - - **Configure a pre-encrypted password for a system user.** - - Enter the password in its hashed format. Upon ``commit``, VyOS stores this value - directly without modification. - - If the user ``<name>`` already exists, the command updates the current password. - If not, it creates a new user with the specified pre-encrypted password. - -.. cfgcmd:: set system login user <name> authentication principal <principal> - - **Configure an SSH certificate principal for a system user.** - - Enter the principal (a string included in the user's signed SSH certificate). - Upon ``commit``, VyOS stores this mapping, allowing the user to log in if the - certificate they present contains this principal. - - If the user ``<name>`` already exists, the command updates the principal. If not, - it creates a new user linked to the specified principal. - - **If not configured**, the principal defaults to ``<name>``. - -.. cfgcmd:: set system login user <name> disable - - **Disable a system user account.** - - VyOS locks the account, preventing the user from logging in. - -.. _ssh_key_based_authentication: - - -Key-based authentication -======================== - -Key-based authentication is the recommended method for securing SSH access in -VyOS. It uses a **public/private key pair** to verify user identity without -requiring a password. To authorize access, you assign **SSH public keys** to -user accounts on the router, while SSH private keys remain on local devices. -VyOS allows assigning multiple SSH public keys to a single user account, which -is useful for accessing a router from different devices. - -Generate the key pair -^^^^^^^^^^^^^^^^^^^^^ - -Generate an SSH key pair on your **local machine** using the ``ssh-keygen`` -command. This creates two files: - -* **Private key** (e.g., ``id_rsa``): Remains on your local machine and must - never be shared. -* **Public key** (e.g., ``id_rsa.pub``): Is used to configure the VyOS user - account. By default, it is saved to ``~/.ssh/id_rsa.pub``. - -Each SSH public key consists of three parts, separated by spaces: - -* **Encryption algorithm type:** ``ssh-rsa``, ``ssh-ed25519``, etc. -* **Key:** The actual data (a long string beginning with ``AAAA...``). -* **Comment:** An identifier for your reference (e.g., ``user@host``). - -Only the encryption algorithm type and key parts are required to -configure the authorization entry in VyOS. The comment part is optional. - -.. seealso:: :ref:`SSH operation <ssh_operation>` - -.. warning:: SSH key strings are long. When copying and pasting, ensure your - terminal does not insert line breaks. The key must be entered as a **single - line** to function correctly. - - -Configure the router -^^^^^^^^^^^^^^^^^^^^ - -To configure SSH public key authentication for a user account, run the -following two commands using the same ``<identifier>``: - -.. cfgcmd:: set system login user <username> authentication public-keys - <identifier> key <key> - - **Configure the SSH public key for the user account.** - - * ``<identifier>``: A unique label that identifies this specific key entry. - - * ``<key>``: The actual string of characters from your public key. - -.. cfgcmd:: set system login user <username> authentication public-keys - <identifier> type <type> - - **Configure the SSH key's encryption type.** - - The following encryption algorithm types are available: - - * ``ecdsa-sha2-nistp256`` - * ``ecdsa-sha2-nistp384`` - * ``ecdsa-sha2-nistp521`` - * ``ssh-dss`` - * ``ssh-ed25519`` - * ``ssh-rsa`` - - .. note:: To assign multiple SSH public keys to a user account, repeat the - commands above with a unique identifier for each key. - -.. cfgcmd:: set system login user <username> authentication public-keys - <identifier> options <options> - - **Configure specific restrictions or behaviors for an SSH public key.** - - ``<options>``: A string of comma-separated values that define permissions - or restrictions for this key. - - The command accepts standard OpenSSH options listed in the router's - ``~/.ssh/authorized_keys`` file. - - To include a ``"`` character in the options string, use ``"``. - - For example, to restrict allowed source IP addresses for an SSH public key, - use: ``from="10.0.0.0/24"``. - -OTP-based MFA -============= -VyOS lets you enhance user access security by enabling :abbr:`OTP (One-time -password)`-based :abbr:`MFA (Multi-factor Authentication)` for individual -users. Users with :abbr:`OTP (One-time password)`-based :abbr:`MFA -(Multi-factor Authentication)` must enter a valid :abbr:`OTP (One-time -password)` along with their password at login. Users without :abbr:`OTP -(One-time password)`-based :abbr:`MFA (Multi-factor Authentication)` use -standard authentication. - -.. cfgcmd:: set system login user <username> authentication otp key <key> - - **Configure** :abbr:`OTP (One-time password)`**-based** :abbr:`MFA - (Multi-factor Authentication)` **for a user.** - - ``<key>``: A Base32-encoded secret key. This key must be added to the user's - authenticator app to generate valid :abbr:`OTPs (One-time passwords)`. - - **When configured**, the user is required to enter their password followed by - a valid OTP for all subsequent logins. - -OTP settings -^^^^^^^^^^^^ - -.. cfgcmd:: set system login user <username> authentication otp rate-limit <limit> - - **Configure the number of** :abbr:`OTP (One-time password)` **authentication - attempts allowed within a specified time period.** - - If this limit is exceeded, the user is temporarily blocked. - - The default value is 3 attempts. The valid range is 1 to 10 attempts. - -.. cfgcmd:: set system login user <username> authentication otp rate-time <seconds> - - **Configure the time period, in seconds, for tracking** :abbr:`OTP (One-time - password)` **authentication attempts.** - - The default value is 30 seconds. The valid range is 1 to 600 seconds. - -.. cfgcmd:: set system login user <username> authentication otp window-size <size> - - **Configure the** :abbr:`OTP (One-time password)` **window size for a user.** - - The :abbr:`OTP (One-time password)` window size defines the number of - concurrently valid :abbr:`OTPs (One-time passwords)` that the authentication - server accepts. This setting assumes a new token is generated every 30 seconds. - - The default value is 3. This permits 3 concurrent codes: the code for the - current 30-second interval, the preceding code, and the following code. This - allows up to 30 seconds of time skew between the authentication server and - client. - - If the window size is increased to 17, the system permits 17 concurrent codes - (the current code, the 8 preceding codes, and the 8 following codes). This - allows for a time skew of up to 4 minutes. - - The valid range is 1 to 21. - -Generate an OTP-key -^^^^^^^^^^^^^^^^^^^ - -Use the following command to generate an OTP key: - -.. cfgcmd:: generate system login username <username> otp-key hotp-time - rate-limit <1-10> rate-time <15-600> window-size <1-21> - -Key generation example: - -.. code-block:: none - - vyos@vyos:~$ generate system login username otptester otp-key hotp-time rate-limit 2 rate-time 20 window-size 5 - # You can share it with the user, he just needs to scan the QR in his OTP app - # username: otptester - # OTP KEY: J5A64ERPMGJOZXY6FMHHLKXKANNI6TCY - # OTP URL: otpauth://totp/otptester@vyos?secret=J5A64ERPMGJOZXY6FMHHLKXKANNI6TCY&digits=6&period=30 - █████████████████████████████████████████████ - █████████████████████████████████████████████ - ████ ▄▄▄▄▄ █▀█ █▄ ▀▄▀▄█▀▄ ▀█▀ █ ▄▄▄▄▄ ████ - ████ █ █ █▀▀▀█ ▄▀ █▄▀ ▀▄ ▄ ▀ ▄█ █ █ ████ - ████ █▄▄▄█ █▀ █▀▀██▄▄ █ █ ██ ▀▄▀ █ █▄▄▄█ ████ - ████▄▄▄▄▄▄▄█▄▀ ▀▄█ █ ▀ █ █ █ █▄█▄█▄▄▄▄▄▄▄████ - ████ ▄ █▄ ▄ ▀▄▀▀▀▀▄▀▄▀▄▄▄▀▀▄▄▄ █ █▄█ █████ - ████▄▄ ██▀▄▄▄▀▀█▀ ▄ ▄▄▄ ▄▀ ▀ █ ▄ ▄ ██▄█ ████ - █████▄ ██▄▄▀█▄█▄█▄ ▀█▄▀▄ ▀█▀▄ █▄▄▄ ▄ ▄████ - ████▀▀▄ ▄█▀▄▀ ▄█▀█▀▄▄▄▀█▄ ██▄▄▄ ▀█ █ ████ - ████ ▄▀▄█▀▄▄█▀▀▄▀▀▀▀█ ▄▀▄▀ ▄█ ▀▄ ▄ ▄▀ █▄████ - ████▄ ██ ▀▄▀▀ ▄█▀ ▄ ██ ▀█▄█ ▄█ ▄ ▀▄ ▄▄ ████ - ████▄█▀▀▄ ▄▄ █▄█▄█▄ █▄▄▀▄▄▀▀▄▄██▀ ▄▀▄▄ ▀▄████ - ████▀▄▀ ▄ ▄▀█ ▄ ▄█▀ █ ▀▄▄ ▄█▀ ▄▄ ▀▄▄ ████ - ████ ▀███▄ █▄█▄▀▀▀▀▄ ▄█▄▄▀ ▀███ ▄▄█▄▄ ▄████ - ████ ███▀ ▄▄▀▀██▀ ▄▀▄█▄▄▄ ██▄▄▀▄▀ ███▄ ▄████ - ████▄████▄▄▄▀▄ █▄█▄▀▄▄▄▄██▀ ▄▀ ▄ ▄▄▄ █▄▄█████ - ████ ▄▄▄▄▄ █▄▄▄ ▄█▀█▀▀▀▀█▀█▀ █▄█ █▄█ ▄█ ████ - ████ █ █ █ ██▄▀▀▀▀▄▄▄▀ ▄▄▄ ▀ ▄ ▄ ▄▄████ - ████ █▄▄▄█ █ ▀▀█▀ ▄▄█ █▄▄██▀▀█▀ █▄▀▄██▄█ ████ - ████▄▄▄▄▄▄▄█▄█▄█▄█▄▄▄▄▄█▄▄▄█▄██████▄██▄▄▄████ - █████████████████████████████████████████████ - █████████████████████████████████████████████ - # To add this OTP key to configuration, run the following commands: - set system login user otptester authentication otp key 'J5A64ERPMGJOZXY6FMHHLKXKANNI6TCY' - set system login user otptester authentication otp rate-limit '2' - set system login user otptester authentication otp rate-time '20' - set system login user otptester authentication otp window-size '5' - -Display the OTP key for a user -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -Use the following command to display the :abbr:`OTP (One-time password)` -key for a user: - -.. cfgcmd:: sh system login authentication user <username> otp - <full | key-b32 | qrcode | uri> - -Example: - -.. code-block:: none - - vyos@vyos:~$ sh system login authentication user otptester otp full - # You can share the OTP key with the user. They just need to scan the QR in their OTP app. - # username: otptester - # OTP KEY: J5A64ERPMGJOZXY6FMHHLKXKANNI6TCY - # OTP URL: otpauth://totp/otptester@vyos?secret=J5A64ERPMGJOZXY6FMHHLKXKANNI6TCY&digits=6&period=30 - █████████████████████████████████████████████ - █████████████████████████████████████████████ - ████ ▄▄▄▄▄ █▀█ █▄ ▀▄▀▄█▀▄ ▀█▀ █ ▄▄▄▄▄ ████ - ████ █ █ █▀▀▀█ ▄▀ █▄▀ ▀▄ ▄ ▀ ▄█ █ █ ████ - ████ █▄▄▄█ █▀ █▀▀██▄▄ █ █ ██ ▀▄▀ █ █▄▄▄█ ████ - ████▄▄▄▄▄▄▄█▄▀ ▀▄█ █ ▀ █ █ █ █▄█▄█▄▄▄▄▄▄▄████ - ████ ▄ █▄ ▄ ▀▄▀▀▀▀▄▀▄▀▄▄▄▀▀▄▄▄ █ █▄█ █████ - ████▄▄ ██▀▄▄▄▀▀█▀ ▄ ▄▄▄ ▄▀ ▀ █ ▄ ▄ ██▄█ ████ - █████▄ ██▄▄▀█▄█▄█▄ ▀█▄▀▄ ▀█▀▄ █▄▄▄ ▄ ▄████ - ████▀▀▄ ▄█▀▄▀ ▄█▀█▀▄▄▄▀█▄ ██▄▄▄ ▀█ █ ████ - ████ ▄▀▄█▀▄▄█▀▀▄▀▀▀▀█ ▄▀▄▀ ▄█ ▀▄ ▄ ▄▀ █▄████ - ████▄ ██ ▀▄▀▀ ▄█▀ ▄ ██ ▀█▄█ ▄█ ▄ ▀▄ ▄▄ ████ - ████▄█▀▀▄ ▄▄ █▄█▄█▄ █▄▄▀▄▄▀▀▄▄██▀ ▄▀▄▄ ▀▄████ - ████▀▄▀ ▄ ▄▀█ ▄ ▄█▀ █ ▀▄▄ ▄█▀ ▄▄ ▀▄▄ ████ - ████ ▀███▄ █▄█▄▀▀▀▀▄ ▄█▄▄▀ ▀███ ▄▄█▄▄ ▄████ - ████ ███▀ ▄▄▀▀██▀ ▄▀▄█▄▄▄ ██▄▄▀▄▀ ███▄ ▄████ - ████▄████▄▄▄▀▄ █▄█▄▀▄▄▄▄██▀ ▄▀ ▄ ▄▄▄ █▄▄█████ - ████ ▄▄▄▄▄ █▄▄▄ ▄█▀█▀▀▀▀█▀█▀ █▄█ █▄█ ▄█ ████ - ████ █ █ █ ██▄▀▀▀▀▄▄▄▀ ▄▄▄ ▀ ▄ ▄ ▄▄████ - ████ █▄▄▄█ █ ▀▀█▀ ▄▄█ █▄▄██▀▀█▀ █▄▀▄██▄█ ████ - ████▄▄▄▄▄▄▄█▄█▄█▄█▄▄▄▄▄█▄▄▄█▄██████▄██▄▄▄████ - █████████████████████████████████████████████ - █████████████████████████████████████████████ - # To add this OTP key to configuration, run the following commands: - set system login user otptester authentication otp key 'J5A64ERPMGJOZXY6FMHHLKXKANNI6TCY' - set system login user otptester authentication otp rate-limit '2' - set system login user otptester authentication otp rate-time '20' - set system login user otptester authentication otp window-size '5' - -Once :abbr:`OTP (One-time password)`-based :abbr:`MFA (Multi-factor -Authentication)` is configured for a user account, this user must enter their -standard password followed by the current 6-digit OTP code at login. For -example, if the user's password is ``vyosrocks`` and the OTP is ``817454``, they -should enter ``vyosrocks817454``. - - -RADIUS authentication -===================== - -For large-scale deployments, managing individual user accounts across multiple -VyOS instances is inefficient. VyOS supports centralized authentication via -:abbr:`RADIUS (Remote Authentication Dial-In User Service)`, consolidating user -account management on a single backend server. - -Configuration -^^^^^^^^^^^^^ - -.. cfgcmd:: set system login radius server <address> key <secret> - - **Configure the** :abbr:`RADIUS (Remote Authentication Dial-In User Service)` - **server's IP address and shared secret.** - - The shared secret is used to verify the router's identity and to encrypt user - passwords during authentication. - - You can configure multiple :abbr:`RADIUS (Remote Authentication Dial-In User - Service)` servers. - -.. cfgcmd:: set system login radius server <address> port <port> - - **Configure the UDP port for communication with the** :abbr:`RADIUS (Remote - Authentication Dial-In User Service)` **server.** - - The default port is 1812. - -.. cfgcmd:: set system login radius server <address> disable - - **Disable a** :abbr:`RADIUS (Remote Authentication Dial-In User Service)` - **server from the authentication process.** - - Disabling a specific :abbr:`RADIUS (Remote Authentication Dial-In User - Service)` server doesn’t remove its configuration settings (the server's IP - address and shared secret). - -.. cfgcmd:: set system login radius server <address> timeout <timeout> - - Configure the duration, in seconds, that the VyOS router waits for a - response from the :abbr:`RADIUS (Remote Authentication Dial-In User Service)` - server after sending an authentication request. - - If the server does not respond within this timeframe, the VyOS router tries to - connect to another configured server or falls back to local authentication. - -.. cfgcmd:: set system login radius source-address <address> - - **Configure the source IP address the router uses for** :abbr:`RADIUS (Remote - Authentication Dial-In User Service)` **authentication requests.** - - A consistent source IP address is recommended as RADIUS servers typically - accept requests only from known, trusted IP addresses. - - If not explicitly defined, the router uses the current egress interface - address, which may change (e.g., due to a link outage), causing authentication - failures. - -.. cfgcmd:: set system login radius vrf <name> - - **Configure the router to send all** :abbr:`RADIUS (Remote Authentication - Dial-In User Service)` **authentication requests via a specific VRF.** - - By default, :abbr:`RADIUS (Remote Authentication Dial-In User Service)` - authentication requests are sent via the global routing table. - -Configuration example -^^^^^^^^^^^^^^^^^^^^^ - -.. code-block:: none - - set system login radius server 192.168.0.2 key 'test-vyos' - set system login radius server 192.168.0.2 port '1812' - set system login radius server 192.168.0.2 timeout '5' - set system login radius source-address '192.168.0.1' - - -If communication with the :abbr:`RADIUS (Remote Authentication Dial-In User -Service)` server fails, the router falls back to local user authentication. -During this process, users may experience a login delay while the system waits -for the :abbr:`RADIUS (Remote Authentication Dial-In User Service)` request to -time out. This delay depends on the configured `timeout` value. - -.. hint:: To grant administrative privileges to :abbr:`RADIUS (Remote - Authentication Dial-In User Service)`-authenticated users, the server must - return the Cisco-AV-Pair attribute set to ``shell:priv-lvl=15``. Otherwise, users - receive standard privileges and cannot perform configuration tasks. - -TACACS+ authentication -====================== - -In addition to :abbr:`RADIUS (Remote Authentication Dial-In User Service)`, -VyOS supports :abbr:`TACACS+ (Terminal Access Controller Access Control -System)`, which is commonly used in large enterprise environments. - -Unlike :abbr:`RADIUS (Remote Authentication Dial-In User Service)`, -:abbr:`TACACS+ (Terminal Access Controller Access Control System)` separates -Authentication, Authorization, and Accounting (AAA) into independent processes -and encrypts the entire packet body for enhanced security. - -:abbr:`TACACS+ (Terminal Access Controller Access Control System)` is defined -in :rfc:`8907`. - -.. _TACACS Configuration: - -Configuration -^^^^^^^^^^^^^ - -.. cfgcmd:: set system login tacacs server <address> key <secret> - - **Configure the** :abbr:`TACACS+ (Terminal Access Controller Access Control - System)` **server IP address and shared secret.** - - Unlike :abbr:`RADIUS (Remote Authentication Dial-In User Service)`, which - encrypts only passwords, :abbr:`TACACS+ (Terminal Access Controller Access - Control System)` encrypts the entire packet body for enhanced security. - - You can configure multiple :abbr:`TACACS+ (Terminal Access Controller Access - Control System)` servers. - -.. cfgcmd:: set system login tacacs server <address> port <port> - - **Configure the TCP port for communication with the** :abbr:`TACACS+ (Terminal - Access Controller Access Control System)` **server.** - - The default port is 49. - -.. cfgcmd:: set system login tacacs server <address> disable - - **Disable a** :abbr:`TACACS+ (Terminal Access Controller Access Control - System)` **server from the authentication process.** - - Disabling a specific :abbr:`TACACS+ (Terminal Access Controller Access Control - System)` server doesn’t remove its configuration settings (the server's IP - address and shared secret). - -.. cfgcmd:: set system login tacacs server <address> timeout <timeout> - - Configure the duration, in seconds, that the VyOS router waits for a - response from the :abbr:`TACACS+ (Terminal Access Controller Access - Control System)` server after sending an authentication request. - - If the server does not respond within this timeframe, the VyOS router tries - to connect to another configured server or falls back to local authentication. - -.. cfgcmd:: set system login tacacs source-address <address> - - **Configure the source IP address the router uses for** - :abbr:`TACACS+ (Terminal Access Controller Access Control System)` - **authentication requests.** - - A consistent source IP address is recommended as :abbr:`TACACS+ (Terminal - Access Controller Access Control System)` servers typically accept requests - only from known, trusted IP addresses. - - If not explicitly defined, the router uses the current egress interface address, - which may change (e.g., due to a link outage), causing authentication failures. - -.. cfgcmd:: set system login tacacs vrf <name> - - Configure the router to send all :abbr:`TACACS+ (Terminal Access Controller - Access Control System)` authentication requests via a specific VRF. - - By default, :abbr:`TACACS+ (Terminal Access Controller Access Control System)` - authentication requests are sent via the global routing table. - -.. _login:tacacs_example: - -Configuration example -^^^^^^^^^^^^^^^^^^^^^ - -.. code-block:: none - - set system login tacacs server 192.168.0.2 key 'test-vyos' - set system login tacacs server 192.168.0.2 port '49' - set system login tacacs source-address '192.168.0.1' - - -If communication with the :abbr:`TACACS+ (Terminal Access Controller Access -Control System)` server fails, the router falls back to local user -authentication. - -Login banners -============= - -VyOS allows you to configure **pre-login** and **post-login** banners. -Pre-login banners are typically used for system identification, legal disclaimers, or security warnings -displayed before authentication, while post-login banners provide system -information or operational notices to users after login. - -.. cfgcmd:: set system login banner pre-login <message> - - Configure a message to be shown to users before the ``username`` and ``password`` - prompts appear. - -.. cfgcmd:: set system login banner post-login <message> - - Configure a message to be shown to users after successful authentication. - -.. note:: Use ``\\n`` to insert line breaks in multi-line banner messages. - -Login session limits -==================== - -.. cfgcmd:: set system login max-login-session <number> - - **Configure the maximum number of concurrent login sessions.** - -.. note:: If you limit concurrent login sessions, you must also configure a - session ``<timeout>``. This clears inactive sessions and prevents blocking new - login attempts. - -.. cfgcmd:: set system login timeout <timeout> - - **Configure the login session timeout, in seconds.** - - Idle login sessions are terminated after this period. - -Configuration examples -====================== - -Example 1: Multi-key SSH with MFA and source restrictions - -In this configuration, ``User1`` and ``User2`` both use the vyos user account, -each with a unique SSH key. ``User1`` is restricted to authentication from a -single IP address. - -For both users, password-based logins require :abbr:`OTP (One-time password)` --based :abbr:`MFA (Multi-factor Authentication)`. - -.. code-block:: none - - set system login user vyos authentication public-keys 'User1' key "AAAAB3Nz...KwEW" - set system login user vyos authentication public-keys 'User1' type ssh-rsa - set system login user vyos authentication public-keys 'User1' options "from="192.168.0.100"" - - set system login user vyos authentication public-keys 'User2' key "AAAAQ39x...fbV3" - set system login user vyos authentication public-keys 'User2' type ssh-rsa - - set system login user vyos authentication otp key OHZ3OJ7U2N25BK4G7SOFFJTZDTCFUUE2 - set system login user vyos authentication plaintext-password vyos - - -Example 2: Containerized :abbr:`TACACS+ (Terminal Access Controller Access Control System)` -deployment with redundancy. - -In this configuration, the VyOS router hosts its own authentication -infrastructure using two containerized :abbr:`TACACS+ (Terminal Access -Controller Access Control System)` servers (``tacacs1`` and ``tacacs2``) on a -private network for redundancy. - -System logins are authenticated against credentials stored within these internal -containers rather than the router's local user database. - -First, download the image in operational mode: - -.. code-block:: none - - add container image lfkeitel/tacacs_plus:latest - -Next, configure the containers in configuration mode: - -.. code-block:: none - - set container network tac-test prefix '100.64.0.0/24' - - set container name tacacs1 image 'lfkeitel/tacacs_plus:latest' - set container name tacacs1 network tac-test address '100.64.0.11' - - set container name tacacs2 image 'lfkeitel/tacacs_plus:latest' - set container name tacacs2 network tac-test address '100.64.0.12' - - set system login tacacs server 100.64.0.11 key 'tac_plus_key' - set system login tacacs server 100.64.0.12 key 'tac_plus_key' - - commit - -You can now log in via SSH or console using ``admin/admin`` credentials supplied -by the container image. diff --git a/docs/configuration/system/rst-name-server.rst b/docs/configuration/system/rst-name-server.rst deleted file mode 100644 index 5d08dbc5..00000000 --- a/docs/configuration/system/rst-name-server.rst +++ /dev/null @@ -1,74 +0,0 @@ -.. _system-dns: - -########## -System DNS -########## - -.. warning:: If you are configuring a VRF for management purposes, there is - currently no way to force system DNS traffic via a specific VRF. - -This section describes configuring DNS on the system, namely: - - * DNS name servers - * Domain search order - - -DNS name servers -================ - -.. cfgcmd:: set system name-server <address> - - Use this command to specify a DNS server for the system to be used - for DNS lookups. More than one DNS server can be added, configuring - one at a time. Both IPv4 and IPv6 addresses are supported. - - - -Example -------- - -In this example, some *OpenNIC* servers are used, two IPv4 addresses -and two IPv6 addresses: - -.. stop_vyoslinter - -.. code-block:: none - - set system name-server 176.9.37.132 - set system name-server 195.10.195.195 - set system name-server 2a01:4f8:161:3441::1 - set system name-server 2a00:f826:8:2::195 - -.. start_vyoslinter - -Domain search order -=================== - -In order for the system to use and complete unqualified host names, a -list can be defined which will be used for domain searches. - - -.. cfgcmd:: set system domain-search <domain> - - Use this command to define domains, one at a time, so that the system - uses them to complete unqualified host names. Maximum: 6 entries. - - -.. note:: Domain names can include letters, numbers, hyphens and periods - with a maximum length of 253 characters. - -.. _name-server:domain-search-order_example: - -Example -------- - -The system is configured to attempt domain completion in the following -order: vyos.io (first), vyos.net (second) and vyos.network (last): - - -.. code-block:: none - - set system domain-search vyos.io - set system domain-search vyos.net - set system domain-search vyos.network - diff --git a/docs/configuration/system/rst-option.rst b/docs/configuration/system/rst-option.rst deleted file mode 100644 index a13e38a8..00000000 --- a/docs/configuration/system/rst-option.rst +++ /dev/null @@ -1,179 +0,0 @@ -.. _system_option: - -###### -Option -###### - -This chapter describe the possibilities of advanced system behavior. - -******* -General -******* - -.. cfgcmd:: set system option ctrl-alt-delete <ignore | reboot | poweroff> - - Action which will be run once the ctrl-alt-del keystroke is received. - -.. cfgcmd:: set system option reboot-on-panic - - Automatically reboot system on kernel panic after 60 seconds. - -.. cfgcmd:: set system option reboot-on-upgrade-failure <timeout> - - Automatically reboot after `timeout` minutes into the previous running - image, that was used to perform the image upgrade. - - Reboot `timeout` is configurable in minutes. This gives the user the change - to log into the system and perform some analysis before automatic rebooting. - - Automatic reboot can be cancelled after login using: :opcmd:`reboot cancel` - -.. cfgcmd:: set system option startup-beep - - Play an audible beep to the system speaker when system is ready. - -.. cfgcmd:: set system option root-partition-auto-resize - - Enables the root partition auto-extension and resizes to the maximum - available space on system boot. - -Kernel -====== - -.. cfgcmd:: set system option kernel disable-mitigations - - Disable all optional CPU mitigations. This improves system performance, - but it may also expose users to several CPU vulnerabilities. - - This will add the following option to the Kernel commandline: - - * ``mitigations=off`` - - .. note:: Setting will only become active with the next reboot! - -.. cfgcmd:: set system option kernel disable-power-saving - - This will add the following two options to the Kernel commandline: - - * ``intel_idle.max_cstate=0`` Disable intel_idle and fall back on acpi_idle - * ``processor.max_cstate=1`` Limit processor to maximum C-state 1 - - .. note:: Setting will only become active with the next reboot! - -.. cfgcmd:: set system option kernel amd-pstate-driver <mode> - - Enables and configures p-state driver for modern AMD Ryzen and Epyc CPUs. - - The available modes are: - - * ``active`` This is the low-level firmware control mode based on the profile - set and the system governor has no effect. - * ``passive`` The driver allows the system governor to manage CPU frequency - while providing available performance states. - * ``guided`` The driver allows to set desired performance levels and the firmware - selects a performance level in this range and fitting to the current workload. - - This will add the following two options to the Kernel commandline: - - * ``initcall_blacklist=acpi_cpufreq_init`` Disable default ACPI CPU frequency scale - * ``amd_pstate={mode}`` Sets the p-state mode - - .. note:: Setting will only become active with the next reboot! - - .. seealso:: https://docs.kernel.org/admin-guide/pm/amd-pstate.html - -.. cfgcmd:: set system option kernel quiet - - Suppress most kernel messages during boot. This is useful for systems with - embedded serial console interfaces to speed up the boot process. - -*********** -HTTP client -*********** - -.. cfgcmd:: set system option http-client source-address <address> - - Several commands utilize cURL to initiate transfers. Configure the local - source IPv4/IPv6 address used for all cURL operations. - -.. cfgcmd:: set system option http-client source-interface <interface> - - Several commands utilize curl to initiate transfers. Configure the local - source interface used for all CURL operations. - -.. note:: `source-address` and `source-interface` can not be used at the same - time. - -********** -SSH client -********** - -.. cfgcmd:: set system option ssh-client source-address <address> - - Use the specified address on the local machine as the source address of the - connection. Only useful on systems with more than one address. - -.. cfgcmd:: set system option ssh-client source-interface <interface> - - Use the address of the specified interface on the local machine as the - source address of the connection. - -*************** -Keyboard Layout -*************** - -When starting a VyOS live system (the installation CD) the configured keyboard -layout defaults to US. As this might not suite everyone's use case you can adjust -the used keyboard layout on the system console. - -.. cfgcmd:: set system option keyboard-layout <us | fr | de | fi | no | dk> - - Change system keyboard layout to given language. - - Defaults to ``us``. - - .. note:: Changing the keymap only has an effect on the system console, using - SSH or Serial remote access to the device is not affected as the keyboard - layout here corresponds to your access system. - -.. _system_options_performance: - -*********** -Performance -*********** - -As more and more routers run on Hypervisors, expecially with a :abbr:`NOS -(Network Operating System)` as VyOS, it makes fewer and fewer sense to use -static resource bindings like ``smp-affinity`` as present in VyOS 1.2 and -earlier to pin certain interrupt handlers to specific CPUs. - -We now utilize `tuned` for dynamic resource balancing based on profiles. - -.. stop_vyoslinter - -.. seealso:: https://access.redhat.com/sites/default/files/attachments/201501-perf-brief-low-latency-tuning-rhel7-v2.1.pdf - -.. start_vyoslinter - -.. cfgcmd:: set system option performance < throughput | latency > - - Configure one of the predefined system performance profiles. - - * ``throughput``: A server profile focused on improving network throughput. - This profile favors performance over power savings by setting - ``intel_pstate`` and ``max_perf_pct=100`` and increasing kernel network - buffer sizes. - - It enables transparent huge pages, and uses cpupower to set the performance - cpufreq governor. It also sets ``kernel.sched_min_granularity_ns`` to 10 us, - ``kernel.sched_wakeup_granularity_ns`` to 15 uss, and ``vm.dirty_ratio`` to - 40%. - - * ``latency``: A server profile focused on lowering network latency. - This profile favors performance over power savings by setting - ``intel_pstate`` and ``min_perf_pct=100``. - - It disables transparent huge pages, and automatic NUMA balancing. It also - uses cpupower to set the performance cpufreq governor, and requests a - cpu_dma_latency value of 1. It also sets busy_read and busy_poll times to - 50 us, and tcp_fastopen to 3. diff --git a/docs/configuration/system/rst-proxy.rst b/docs/configuration/system/rst-proxy.rst deleted file mode 100644 index 8e0339a7..00000000 --- a/docs/configuration/system/rst-proxy.rst +++ /dev/null @@ -1,28 +0,0 @@ -.. _system_proxy: - -############ -System Proxy -############ - -Some IT environments require the use of a proxy to connect to the Internet. -Without this configuration VyOS updates could not be installed directly by -using the :opcmd:`add system image` command (:ref:`update_vyos`). - -.. cfgcmd:: set system proxy url <url> - - Set proxy for all connections initiated by VyOS, including HTTP, HTTPS, and - FTP (anonymous ftp). - -.. cfgcmd:: set system proxy port <port> - - Configure proxy port if it does not listen to the default port 80. - -.. cfgcmd:: set system proxy username <username> - - Some proxys require/support the "basic" HTTP authentication scheme as per - :rfc:`7617`, thus a username can be configured. - -.. cfgcmd:: set system proxy password <password> - - Some proxys require/support the "basic" HTTP authentication scheme as per - :rfc:`7617`, thus a password can be configured. diff --git a/docs/configuration/system/rst-sflow.rst b/docs/configuration/system/rst-sflow.rst deleted file mode 100644 index 926d667b..00000000 --- a/docs/configuration/system/rst-sflow.rst +++ /dev/null @@ -1,65 +0,0 @@ -##### -sFlow -##### - -VyOS supports sFlow accounting for both IPv4 and IPv6 traffic. The system acts as a flow exporter, and you are free to use it with any compatible collector. - -sFlow is a technology that enables monitoring of network traffic by sending sampled packets to a collector device. - -The sFlow accounting based on hsflowd https://sflow.net/ - -Configuration -============= - -.. cfgcmd:: set system sflow agent-address <address> - - Configure sFlow agent IPv4 or IPv6 address - - -.. cfgcmd:: set system sflow agent-interface <interface> - - Configure agent IP address associated with this interface. - - -.. cfgcmd:: set system sflow drop-monitor-limit <limit> - - Dropped packets reported on DROPMON Netlink channel by Linux kernel are exported via the standard sFlow v5 extension for reporting dropped packets - -.. cfgcmd:: set system sflow interface <interface> - - Configure and enable collection of flow information for the interface identified by <interface>. - - You can configure multiple interfaces which would participate in sflow accounting. - - -.. cfgcmd:: set system sflow polling <sec> - - Configure schedule counter-polling in seconds (default: 30) - -.. cfgcmd:: set system sflow sampling-rate <rate> - - Use this command to configure the sampling rate for sFlow accounting (default: 1000) - -.. cfgcmd:: set system sflow server <address> port <port> - - Configure address of sFlow collector. sFlow server at <address> can be both listening on an IPv4 or IPv6 address. - -.. cfgcmd:: set system sflow enable-egress - - Use this command to if you need to sample also egress traffic - - -Example -======= - -.. code-block:: none - - set system sflow agent-address '192.0.2.14' - set system sflow agent-interface 'eth0' - set system sflow drop-monitor-limit '50' - set system sflow interface 'eth0' - set system sflow interface 'eth1' - set system sflow polling '30' - set system sflow sampling-rate '1000' - set system sflow server 192.0.2.1 port '6343' - set system sflow server 203.0.113.23 port '6343' diff --git a/docs/configuration/system/rst-sysctl.rst b/docs/configuration/system/rst-sysctl.rst deleted file mode 100644 index 1fedb9bd..00000000 --- a/docs/configuration/system/rst-sysctl.rst +++ /dev/null @@ -1,16 +0,0 @@ -.. _sysctl: - -###### -Sysctl -###### - -.. 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/. - -.. cfgcmd:: set system sysctl parameter <parameter> value <value> diff --git a/docs/configuration/system/rst-syslog.rst b/docs/configuration/system/rst-syslog.rst deleted file mode 100644 index c2767c4a..00000000 --- a/docs/configuration/system/rst-syslog.rst +++ /dev/null @@ -1,432 +0,0 @@ -.. _syslog: - -###### -Syslog -###### - -Overview -======== - -By default, VyOS provides a minimal logging configuration with local storage -and log rotation. All errors, including local7 messages, are saved to a local -file. Emergency alerts are sent to the console. - -To change these settings, enter configuration mode. - -Syslog configuration -==================== - -Syslog supports logging to multiple destinations: a local file, a console, or -a remote syslog server over UDP or TCP. - -The syslog configuration is organized into the following categories: - -* Global settings -* Local logging -* Console logging -* Remote logging -* TLS-encrypted remote logging - -Global settings ---------------- -Configure the general behavior of the syslog service. - -.. cfgcmd:: set system syslog marker interval <number> - - **Configure the interval, in seconds, for sending syslog mark messages.** - - Syslog mark messages confirm the logging service is operational. - - Default: 1200 seconds. - -.. cfgcmd:: set system syslog marker disable - - Disable sending syslog mark messages. - -.. cfgcmd:: set system syslog preserve-fqdn - - **Configure how the logging device's hostname appears in log messages sent - to a remote syslog server.** - - If configured, the device includes its :abbr:`FQDN (Fully Qualified Domain - Name)` in log messages, even if the syslog server is in the same domain. - - -Local logging -------------- - -Configure which log messages to save to a local log file. - -.. cfgcmd:: set system syslog local <filename> facility <keyword> level <keyword> - - **Configure syslog to save log messages for a specific facility and - severity level to ``/var/log/messages``.** - - Refer to the tables below for valid facility and severity options. - -.. _syslog_console: - -Console logging ---------------- - -Configure which log messages to send to ``/dev/console``. - -.. cfgcmd:: set system syslog console facility <keyword> level <keyword> - - **Configure syslog to send log messages for a specific facility and severity - level to the device's console.** - - Refer to the tables below for valid facility and severity options. - -.. _syslog_remote: - -Remote logging --------------- - -Configure **remote logging** to send log messages to a remote syslog server. - -Remote logging does not affect either **local** or **console logging** and -runs in parallel with them. Remote logging supports sending log messages -to multiple hosts. - -.. cfgcmd:: set system syslog remote <address> facility <keyword> level <keyword> - - **Configure log transmission to the remote syslog server for a specific - facility and severity level.** - - The server’s address can be specified using either a :abbr:`FQDN (Fully - Qualified Domain Name)` or an IP address. - - Refer to the tables below for valid facility and severity options. - -.. cfgcmd:: set system syslog remote <address> protocol <udp | tcp> - - **Configure the protocol for log transmission.** - - The protocol can be either UDP or TCP. By default, log messages are sent - over UDP. - -.. cfgcmd:: set system syslog remote <address> port <port> - - **Configure the port for log transmission.** - - By default, the standard port 514 is used. - -.. cfgcmd:: set system syslog remote <address> format include-timezone - - **Configure log transmission in the RFC 5424 format.** - - The RFC 5424 format includes the timezone in the timestamp. For example: - - .. code-block:: none - - <34>1 2003-10-11T22:14:15.003-07:00 mymachine.example.com su - ID47 - BOM’su root’ failed for lonvick on /dev/pts/8. - - By default, log messages are sent in the RFC 3164 format. For example: - - .. code-block:: none - - <34>Oct 11 22:14:15 mymachine su: ‘su root’ failed for lonvick on /dev/pts/8 - -.. cfgcmd:: set system syslog remote <address> format octet-counted - - **Enable octet-counted framing for log transmission.** - - When enabled, multi-line log messages are sent without splitting. Ensure - the remote server supports octet-counted framing to avoid parsing errors. - - Octet-counted framing is not available for the UDP protocol. - -.. cfgcmd:: set system syslog remote <address> vrf <name> - - Configure the :abbr:`VRF (Virtual Routing and Forwarding)` instance - for log transmission. - -.. cfgcmd:: set system syslog remote <address> source-address <address> - - Configure the source IP address (IPv4 or IPv6) for log transmission. - -:abbr:`TLS (Transport Layer Security)`-encrypted remote logging -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -VyOS supports :abbr:`TLS (Transport Layer Security)`-encrypted remote logging -over TCP to ensure secure transmission of syslog data to remote syslog servers. - -**Prerequisites**: Before configuring :abbr:`TLS (Transport Layer -Security)`-encrypted remote logging, ensure you have: - -* A valid remote syslog server address. -* Valid :abbr:`CA (Certificate Authority)` and client certificates uploaded - to the local :abbr:`PKI (Public Key Infrastructure)` storage. -* The **remote syslog transport protocol** is set to **TCP**: - - .. code-block:: none - - set system syslog remote <address> protocol tcp - - -.. note:: :abbr:`TLS (Transport Layer Security)`-encrypted remote logging is - **not supported** over **UDP**. - -.. cfgcmd:: set system syslog remote <address> tls - - Enable TLS-encrypted remote logging. - -.. cfgcmd:: set system syslog remote <address> tls ca-certificate <ca_name> - - **Configure the** :abbr:`CA (Certificate Authority)` **certificate.** - - The syslog client uses the :abbr:`CA (Certificate Authority)` certificate to - verify the identity of the remote syslog server. - - The :abbr:`CA (Certificate Authority)` certificate is required for **all** - authentication modes except ``anon``. - -.. cfgcmd:: set system syslog remote <address> tls certificate <cert_name> - - **Configure the client certificate.** - - The remote syslog server uses the client certificate to verify the identity - of the syslog client. - - The client certificate is required if the remote syslog server enforces - client certificate verification. - -.. cfgcmd:: set system syslog remote <address> tls auth-mode <anon | fingerprint - | certvalid | name> - - **Configure the authentication mode.** - - The authentication mode defines how the syslog client verifies the syslog - server's identity. - - The following authentication modes are available: - - * ``anon`` **(default)**: Allows encrypted connections without verifying the syslog - server's identity. This mode is **not recommended**, as it is vulnerable to - :abbr:`MITM (Man-in-the-Middle)` attacks. - * ``fingerprint``: Verifies the server’s certificate fingerprint against the - value preconfigured with: - - .. code-block:: none - - set system syslog remote <address> tls permitted-peer <peer> - - * ``certvalid``: Verifies the server certificate is signed by a trusted - :abbr:`CA (Certificate Authority)`, skipping :abbr:`CN (Common Name)` check. - * ``name``: Verifies that: - - * The server’s certificate is signed by a trusted :abbr:`CA (Certificate - Authority)`. - * The :abbr:`CN (Common Name)` in the certificate matches the value - preconfigured with: - - .. code-block:: none - - set system syslog remote <address> tls permitted-peer <peer> - - This is a **recommended** secure mode for production environments. - -.. cfgcmd:: set system syslog remote <address> tls permitted-peer <peer> - - **Configure the peer certificate identifiers.** - - The certificate identifier format depends on the authentication mode: - - * ``fingerprint``: Enter the expected certificate fingerprints (SHA-1 or - SHA-256). - * ``name``: Enter the expected certificate :abbr:`CNs (Common Names)`. - - For ``anon`` and ``certvalid`` authentication modes, certificate identifiers - are not required. - -Examples: -^^^^^^^^^ - -.. code-block:: none - - # Example of 'anon' authentication mode - set system syslog remote 10.10.2.3 facility all level debug - set system syslog remote 10.10.2.3 port 6514 - set system syslog remote 10.10.2.3 protocol tcp - set system syslog remote 10.10.2.3 tls auth-mode anon - # or just use 'set system syslog remote 10.10.2.3 tls' - - # Example of 'certvalid' authentication mode - set system syslog remote elk.example.com facility all level debug - set system syslog remote elk.example.com port 6514 - set system syslog remote elk.example.com protocol tcp - set system syslog remote elk.example.com tls ca-certificate my-ca - set system syslog remote elk.example.com tls auth-mode certvalid - - # Example of 'fingerprint' authentication mode - set system syslog remote syslog.example.com facility all level debug - set system syslog remote syslog.example.com port 6514 - set system syslog remote syslog.example.com protocol tcp - set system syslog remote syslog.example.com tls ca-certificate my-ca - set system syslog remote syslog.example.com tls auth-mode fingerprint - set system syslog remote syslog.example.com tls permitted-peers 'SHA1:10:C4:26:...,SHA256:7B:4B:10:...' - - # Example of 'name' authentication mode - set system syslog remote graylog.example.com facility all level debug - set system syslog remote graylog.example.com port 6514 - set system syslog remote graylog.example.com protocol tcp - set system syslog remote graylog.example.com tls ca-certificate my-ca - set system syslog remote graylog.example.com tls certificate syslog-client - set system syslog remote graylog.example.com tls auth-mode name - set system syslog remote graylog.example.com tls permitted-peers 'graylog.example.com' - -Security recommendations -^^^^^^^^^^^^^^^^^^^^^^^^ - -* For secure deployments, always use the ``name`` authentication mode. It - ensures that the server is validated by a trusted :abbr:`CA (Certificate - Authority)` and that the hostname matches the certificate. -* Use the ``anon`` authentication mode only in testing environments, as it - doesn't provide server authentication. -* Ensure private keys are generated, stored, and maintained exclusively within - the :doc:`PKI system </configuration/pki/index>`. - -.. _syslog_facilities: - -Syslog facilities -================= - -This section lists facilities used by syslog. Most facility names are self- -explanatory. The local0–local7 facilities are used for custom purposes, such as -logging from network nodes and equipment. Facility assignment is flexible and -should be tailored to your company's needs. Consider facilities as categorization -tools, rather than strict directives. - -+----------+----------+----------------------------------------------------+ -| Facility | Keyword | Description | -| code | | | -+==========+==========+====================================================+ -| | all | All facilities | -+----------+----------+----------------------------------------------------+ -| 0 | kern | Kernel messages | -+----------+----------+----------------------------------------------------+ -| 1 | user | User-level messages | -+----------+----------+----------------------------------------------------+ -| 2 | mail | Mail system | -+----------+----------+----------------------------------------------------+ -| 3 | daemon | System daemons | -+----------+----------+----------------------------------------------------+ -| 4 | auth | Security/authentication messages | -+----------+----------+----------------------------------------------------+ -| 5 | syslog | Messages generated internally by syslog | -+----------+----------+----------------------------------------------------+ -| 6 | lpr | Line printer subsystem | -+----------+----------+----------------------------------------------------+ -| 7 | news | Network news subsystem | -+----------+----------+----------------------------------------------------+ -| 8 | uucp | UUCP subsystem | -+----------+----------+----------------------------------------------------+ -| 9 | cron | Clock daemon | -+----------+----------+----------------------------------------------------+ -| 10 | security | Security/authentication messages | -+----------+----------+----------------------------------------------------+ -| 11 | ftp | FTP daemon | -+----------+----------+----------------------------------------------------+ -| 12 | ntp | NTP subsystem | -+----------+----------+----------------------------------------------------+ -| 13 | logaudit | Log audit | -+----------+----------+----------------------------------------------------+ -| 14 | logalert | Log alert | -+----------+----------+----------------------------------------------------+ -| 15 | clock | clock daemon (note 2) | -+----------+----------+----------------------------------------------------+ -| 16 | local0 | local use 0 (local0) | -+----------+----------+----------------------------------------------------+ -| 17 | local1 | local use 1 (local1) | -+----------+----------+----------------------------------------------------+ -| 18 | local2 | local use 2 (local2) | -+----------+----------+----------------------------------------------------+ -| 19 | local3 | local use 3 (local3) | -+----------+----------+----------------------------------------------------+ -| 20 | local4 | local use 4 (local4) | -+----------+----------+----------------------------------------------------+ -| 21 | local5 | local use 5 (local5) | -+----------+----------+----------------------------------------------------+ -| 22 | local6 | local use 6 (local6) | -+----------+----------+----------------------------------------------------+ -| 23 | local7 | local use 7 (local7) | -+----------+----------+----------------------------------------------------+ - -.. _syslog_severity_level: - -Severity levels -=============== - -+-------+---------------+---------+-------------------------------------------+ -| Value | Severity | Keyword | Description | -+=======+===============+=========+===========================================+ -| | | all | Log everything. | -+-------+---------------+---------+-------------------------------------------+ -| 0 | Emergency | emerg | System is unusable - a panic condition. | -+-------+---------------+---------+-------------------------------------------+ -| 1 | Alert | alert | Action must be taken immediately - A | -| | | | condition that should be corrected | -| | | | immediately, such as a corrupted system | -| | | | database. | -+-------+---------------+---------+-------------------------------------------+ -| 2 | Critical | crit | Critical conditions - e.g., hard drive | -| | | | errors. | -+-------+---------------+---------+-------------------------------------------+ -| 3 | Error | err | Error conditions. | -+-------+---------------+---------+-------------------------------------------+ -| 4 | Warning | warning | Warning conditions. | -+-------+---------------+---------+-------------------------------------------+ -| 5 | Notice | notice | Normal but significant conditions - | -| | | | conditions that are not error conditions, | -| | | | but that may require special handling. | -+-------+---------------+---------+-------------------------------------------+ -| 6 | Informational | info | Informational messages. | -+-------+---------------+---------+-------------------------------------------+ -| 7 | Debug | debug | Debug-level messages - Messages that | -| | | | contain information normally of use only | -| | | | when debugging a program. | -+-------+---------------+---------+-------------------------------------------+ - - -Display logs -============ - -.. opcmd:: show log [all | authorization | cluster | conntrack-sync | ...] - - **Display logs for a specific category on the console.** - - Use tab completion to view a list of available categories. - - If no category is specified, all logs are shown. - -.. opcmd:: show log image <name> - [all | authorization | directory | file <file name> | tail <lines>] - - **Display logs for a specific image on the console.** - - Available log categories: - - .. list-table:: - :widths: 25 75 - :header-rows: 0 - - * - all - - Displays the contents of system log files of the specified image. - * - authorization - - Displays authorization attempts of the specified image. - * - directory - - Displays user-defined log files of the specified image. - * - file <file name> - - Displays the contents of a specified user-defined log file of the specified - image. - * - tail - - Displays last lines of the system log of the specified image. - * - <lines> - - Number of lines to be displayed, default 10. - -If no category is specified, the contents of the main syslog file are -displayed. - -.. hint:: Use ``show log | strip-private`` to hide private data - when displaying your logs. diff --git a/docs/configuration/system/rst-task-scheduler.rst b/docs/configuration/system/rst-task-scheduler.rst deleted file mode 100644 index 4a754ba3..00000000 --- a/docs/configuration/system/rst-task-scheduler.rst +++ /dev/null @@ -1,40 +0,0 @@ -.. _task-scheduler: - -############## -Task Scheduler -############## - -The task scheduler allows you to execute tasks on a given schedule. It makes -use of UNIX cron_. - -.. note:: All scripts executed this way are executed as root user - this may - be dangerous. Together with :ref:`command-scripting` this can be used for - automating (re-)configuration. - -.. cfgcmd:: set system task-scheduler task <task> interval <interval> - - Specify the time interval when `<task>` should be executed. The interval - is specified as number with one of the following suffixes: - - * ``none`` - Execution interval in minutes - * ``m`` - Execution interval in minutes - * ``h`` - Execution interval in hours - * ``d`` - Execution interval in days - - .. note:: If suffix is omitted, minutes are implied. - -.. cfgcmd:: set system task-scheduler task <task> crontab-spec <spec> - - Set execution time in common cron_ time format. A cron `<spec>` of - ``30 */6 * * *`` would execute the `<task>` at minute 30 past every 6th hour. - -.. cfgcmd:: set system task-scheduler task <task> executable path <path> - - Specify absolute `<path>` to script which will be run when `<task>` is - executed. - -.. cfgcmd:: set system task-scheduler task <task> executable arguments <args> - - Arguments which will be passed to the executable. - -.. _cron: https://en.wikipedia.org/wiki/Cron diff --git a/docs/configuration/system/rst-time-zone.rst b/docs/configuration/system/rst-time-zone.rst deleted file mode 100644 index 025c4376..00000000 --- a/docs/configuration/system/rst-time-zone.rst +++ /dev/null @@ -1,18 +0,0 @@ -.. _timezone: - -######### -Time Zone -######### - -Time Zone setting is very important as e.g all your logfile entries will be -based on the configured zone. Without proper time zone configuration it will -be very difficult to compare logfiles from different systems. - -.. cfgcmd:: set system time-zone <timezone> - - Specify the systems `<timezone>` as the Region/Location that best defines - your location. For example, specifying US/Pacific sets the time zone to US - Pacific time. - - Command completion can be used to list available time zones. The adjustment - for daylight time will take place automatically based on the time of year.
\ No newline at end of file diff --git a/docs/configuration/system/rst-updates.rst b/docs/configuration/system/rst-updates.rst deleted file mode 100644 index 505d9318..00000000 --- a/docs/configuration/system/rst-updates.rst +++ /dev/null @@ -1,39 +0,0 @@ -####### -Updates -####### - -VyOS supports online checking for updates - -Configuration -============= - -.. cfgcmd:: set system update-check auto-check - - Configure auto-checking for new images - - -.. cfgcmd:: set system update-check url <url> - - Configure a URL that contains information about images. - - -Example -======= - -.. code-block:: none - - set system update-check auto-check - set system update-check url 'https://raw.githubusercontent.com/vyos/vyos-rolling-nightly-builds/main/version.json' - -Check: - -.. code-block:: none - - vyos@r4:~$ show system updates - Current version: 1.5-rolling-202312220023 - - Update available: 1.5-rolling-202312250024 - Update URL: https://github.com/vyos/vyos-rolling-nightly-builds/releases/download/1.5-rolling-202312250024/1.5-rolling-202312250024-amd64.iso - vyos@r4:~$ - - vyos@r4:~$ add system image latest diff --git a/docs/configuration/system/rst-watchdog.rst b/docs/configuration/system/rst-watchdog.rst deleted file mode 100644 index 9db4a666..00000000 --- a/docs/configuration/system/rst-watchdog.rst +++ /dev/null @@ -1,208 +0,0 @@ -.. _system_watchdog: - -######## -Watchdog -######## - -VyOS supports hardware watchdog timers to automatically reboot the system if -it becomes unresponsive. This is particularly useful for remote or embedded -systems where physical access is limited. - -A watchdog timer is a hardware or software mechanism that automatically resets -the system if the operating system stops responding within a configured timeout -period. The system will periodically notify the watchdog that it is still -running. If the watchdog is not notified within the timeout period, the watchdog -will reset the system. - -Configuration -============= - -The watchdog feature is configured under the ``system watchdog`` configuration -tree. The presence of the ``system watchdog`` node enables the watchdog feature. - -.. cfgcmd:: set system watchdog - - Enable watchdog support. - - The watchdog is enabled only when a watchdog device is available as - ``/dev/watchdog0``. - - .. note:: If multiple watchdog devices are present, only the first watchdog - device is supported (VyOS uses ``/dev/watchdog0`` only). - - If ``/dev/watchdog0`` does not exist and no module is configured, commit will - fail. If a module is configured but ``/dev/watchdog0`` still cannot be - created, VyOS will emit a warning and will not enable the systemd watchdog. - -.. cfgcmd:: set system watchdog module <module-name> - - Specify the kernel watchdog driver module to load for ``/dev/watchdog0``. - - The configured module must be a watchdog driver module, not an arbitrary - kernel module. - - **In most cases, this option is not required** as the kernel will - automatically load the appropriate watchdog driver for your system. Use this - option if the kernel fails to load the required driver, or when you want to - use the software watchdog (``softdog``). - - Common modules include: - - * ``softdog`` - Software watchdog timer (available on all systems) - * ``iTCO_wdt`` - Intel TCO watchdog timer - * ``sp5100_tco`` - AMD SP5100 TCO watchdog timer - * ``i6300esb`` - Intel 6300ESB watchdog timer - * ``ipmi_watchdog`` - IPMI watchdog timer - - .. warning:: ``softdog`` is not a hardware watchdog. It is implemented using - kernel timers and therefore depends on the Linux kernel continuing to run. - In some fault conditions (for example, a kernel hang), ``softdog`` may not - be able to trigger a reset. - - Prefer a hardware watchdog driver whenever possible, as hardware watchdogs - can operate independently of the operating system. - - If no module is specified, VyOS will use an existing ``/dev/watchdog0`` - device if available. - - .. note:: If a module is specified but a different driver is actually bound - to ``watchdog0``, VyOS will emit a warning during commit. - - Example: - - .. code-block:: none - - set system watchdog module softdog - -.. cfgcmd:: set system watchdog timeout <seconds> - :defaultvalue: - - Set the watchdog timeout for normal runtime operation in seconds. - - Valid range: 1-65535 seconds - - .. note:: Some watchdog drivers expose minimum and maximum supported runtime - timeouts via sysfs. When available, VyOS validates ``timeout`` against - those driver limits during commit. - - This is the interval during which the system must respond to the watchdog. - If the system does not respond within this time, the watchdog will trigger - a reboot. - - Example: - - .. code-block:: none - - set system watchdog timeout 30 - -.. cfgcmd:: set system watchdog shutdown-timeout <seconds> - :defaultvalue: - - Set the watchdog timeout during system shutdown in seconds. - - Valid range: 60-65535 seconds - - This extended timeout allows the system to complete a graceful shutdown - without triggering the watchdog. - - .. warning:: Setting this value too low (below 120 seconds) may cause - unclean shutdowns, as the system may not have enough time to properly - stop all services and flush disk buffers. The recommended minimum value - is 120 seconds. - - Example: - - .. code-block:: none - - set system watchdog shutdown-timeout 180 - -.. cfgcmd:: set system watchdog reboot-timeout <seconds> - :defaultvalue: - - Set the watchdog timeout during system reboot in seconds. - - Valid range: 60-65535 seconds - - This extended timeout allows the system to complete the reboot process - without triggering the watchdog during the transition. - - .. warning:: Setting this value too low (below 120 seconds) may cause - unclean reboots, as the system may not have enough time to properly - stop all services before restarting. The recommended minimum value - is 120 seconds. - - Example: - - .. code-block:: none - - set system watchdog reboot-timeout 180 - -Examples -======== - -Basic Configuration with Software Watchdog ------------------------------------------- - -This example configures a basic software watchdog with default timeouts: - -.. code-block:: none - - set system watchdog module softdog - -This will: - -* Enable the watchdog feature -* Load the ``softdog`` kernel module -* Use a 10-second runtime timeout (default) -* Use 120-second shutdown and reboot timeouts (default) - -Advanced Configuration ----------------------- - -This example shows a more customized configuration suitable for a production -system: - -.. code-block:: none - - set system watchdog module iTCO_wdt - set system watchdog timeout 30 - set system watchdog shutdown-timeout 300 - set system watchdog reboot-timeout 300 - -This configuration: - -* Enables the watchdog feature -* Loads the Intel TCO hardware watchdog module -* Sets a 30-second runtime timeout -* Allows 5 minutes for shutdown and reboot operations - -Best Practices -============== - -* **Start with conservative timeouts**: Use longer timeouts initially and - reduce them as you gain confidence in system stability. - -* **Test before deployment**: Verify the watchdog works as expected in a - non-production environment before deploying to production systems. - -* **Choose appropriate modules**: Use hardware watchdog modules (like - ``iTCO_wdt``) when available, as they are more reliable than software - watchdogs. - -* **Consider shutdown time**: Set ``shutdown-timeout`` and ``reboot-timeout`` - values high enough to allow for normal shutdown procedures, especially on - systems with many services or slow storage. - -* **Monitor watchdog events**: Check system logs after any unexpected reboots - to determine if the watchdog triggered the reboot. - -* **Remote systems**: For systems without physical console access, use - conservative timeout values to avoid false-positive reboots during high - load conditions. - -.. note:: The watchdog configuration takes effect immediately after commit, - but systemd must be reloaded. This happens automatically during commit. - -.. warning:: Incorrect watchdog configuration on remote systems can result - in unexpected reboots. Always test watchdog settings in a controlled - environment before deploying to production systems. diff --git a/docs/configuration/trafficpolicy/rst-index.rst b/docs/configuration/trafficpolicy/rst-index.rst deleted file mode 100644 index 13cfb9dc..00000000 --- a/docs/configuration/trafficpolicy/rst-index.rst +++ /dev/null @@ -1,1361 +0,0 @@ -.. _qos: - -############## -Traffic Policy -############## - - -*** -QoS -*** - -The generic name of Quality of Service or Traffic Control involves -things like shaping traffic, scheduling or dropping packets, which -are the kind of things you may want to play with when you have, for -instance, a bandwidth bottleneck in a link and you want to somehow -prioritize some type of traffic over another. - -tc_ is a powerful tool for Traffic Control found at the Linux kernel. -However, its configuration is often considered a cumbersome task. -Fortunately, VyOS eases the job through its CLI, while using ``tc`` as -backend. - - -How to make it work -=================== - -In order to have VyOS Traffic Control working you need to follow 2 -steps: - - 1. **Create a traffic policy**. - - 2. **Apply the traffic policy to an interface ingress or egress**. - - -But before learning to configure your policy, we will warn you -about the different units you can use and also show you what *classes* -are and how they work, as some policies may require you to configure -them. - - -Units -===== - -When configuring your traffic policy, you will have to set data rate -values, watch out the units you are managing, it is easy to get confused -with the different prefixes and suffixes you can use. VyOS will always -show you the different units you can use. - -Prefixes --------- - -They can be **decimal** prefixes. - - .. 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 - -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 - - kibps (1024*8) kibibyte (KiB) per second - mibps (1024^2*8) mebibyte (MiB) per second - gibps (1024^3*8) gibibyte (GiB) per second - tibps (1024^4*8) tebibyte (TiB) per second - - -Suffixes --------- - -A *bit* is written as **bit**, - - .. code-block:: none - - kbit (kilobits per second) - mbit (megabits per second) - gbit (gigabits per second) - tbit (terabits per second) - -while a *byte* is written as a single **b**. - - .. code-block:: none - - kbps (kilobytes per second) - mbps (megabytes per second) - gbps (gigabytes per second) - - - - -.. _classes: - -Classes -======= - -In the :ref:`creating_a_traffic_policy` section you will see that -some of the policies use *classes*. Those policies let you distribute -traffic into different classes according to different parameters you can -choose. So, a class is just a specific type of traffic you select. - -The ultimate goal of classifying traffic is to give each class a -different treatment. - - -Matching traffic ----------------- - -In order to define which traffic goes into which class, you define -filters (that is, the matching criteria). Packets go through these matching -rules (as in the rules of a firewall) and, if a packet matches the filter, it -is assigned to that class. - -In VyOS, a class is identified by a number you can choose when -configuring it. - - -.. note:: The meaning of the Class ID is not the same for every type of - policy. Normally policies just need a meaningless number to identify - a class (Class ID), but that does not apply to every policy. - The number of a class in a Priority Queue it does not only - identify it, it also defines its priority. - - -.. 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 -differentiate some traffic) and an identifiable number for that class; -then we configure a matching rule (or filter) and a name for it. - -A class can have multiple match filters: - -.. code-block:: none - - set qos policy shaper MY-SHAPER class 30 match HTTP - set qos policy shaper MY-SHAPER class 30 match HTTPs - -A match filter can contain multiple criteria and will match traffic if -all those criteria are true. - -For example: - -.. code-block:: none - - set qos policy shaper MY-SHAPER class 30 match HTTP ip protocol tcp - set qos policy shaper MY-SHAPER class 30 match HTTP ip source port 80 - -This will match TCP traffic with source port 80. - -There are many parameters you will be able to use in order to match the -traffic you want for a class: - - - **Ethernet (protocol, destination address or source address)** - - **Interface name** - - **IPv4 (DSCP value, maximum packet length, protocol, source address,** - **destination address, source port, destination port or TCP flags)** - - **IPv6 (DSCP value, maximum payload length, protocol, source address,** - **destination address, source port, destination port or TCP flags)** - - **Firewall mark** - - **VLAN ID** - -When configuring your filter, you can use the ``Tab`` key to see the many -different parameters you can configure. - - -.. code-block:: none - - vyos@vyos# set qos policy shaper MY-SHAPER class 30 match MY-FIRST-FILTER - Possible completions: - description Description - > ether Ethernet header match - interface Interface to use - > ip Match IP protocol header - > ipv6 Match IPV6 protocol header - mark Match on mark applied by firewall - vif Virtual Local Area Network (VLAN) ID for this match - - - -As shown in the example above, one of the possibilities to match packets -is based on marks done by the firewall, -`that can give you a great deal of flexibility`_. - -You can also write a description for a filter: - -.. 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 - length of 20 bytes (which is the majority of IPv4 packets anyway). - - -.. note:: IPv6 TCP filters will only match IPv6 packets with no header - extension, see https://en.wikipedia.org/wiki/IPv6_packet#Extension_headers - -Traffic Match Group -------------------- -In some case where we need to have an organization of our matching selection, -in order to be more flexible and organize with our filter definition. We can -apply traffic match groups, allowing us to create distinct filter groups within -our policy and define various parameters for each group: - -.. code-block:: none - - set qos traffic-match-group <group_name> match <match_name> - Possible completions: - description Description - > ip Match IP protocol header - > ipv6 Match IPv6 protocol header - mark Match on mark applied by firewall - vif Virtual Local Area Network (VLAN) ID for this match - -inherit matches from another group - -.. code-block:: none - - set qos traffic-match-group <group_name> match-group <match_group_name> - -A match group can contain multiple criteria and inherit them in the same policy. - -For example: - -.. code-block:: none - - set qos traffic-match-group Mission-Critical match AF31 ip dscp 'AF31' - set qos traffic-match-group Mission-Critical match AF32 ip dscp 'AF42' - set qos traffic-match-group Mission-Critical match CS3 ip dscp 'CS3' - set qos traffic-match-group Streaming-Video match AF11 ip dscp 'AF11' - set qos traffic-match-group Streaming-Video match AF41 ip dscp 'AF41' - set qos traffic-match-group Streaming-Video match AF43 ip dscp 'AF43' - set qos policy shaper VyOS-HTB class 10 bandwidth '30%' - set qos policy shaper VyOS-HTB class 10 description 'Multimedia' - set qos policy shaper VyOS-HTB class 10 match CS4 ip dscp 'CS4' - set qos policy shaper VyOS-HTB class 10 match-group 'Streaming-Video' - set qos policy shaper VyOS-HTB class 10 priority '1' - set qos policy shaper VyOS-HTB class 10 queue-type 'fair-queue' - set qos policy shaper VyOS-HTB class 20 description 'MC' - set qos policy shaper VyOS-HTB class 20 match-group 'Mission-Critical' - set qos policy shaper VyOS-HTB class 20 priority '2' - set qos policy shaper VyOS-HTB class 20 queue-type 'fair-queue' - set qos policy shaper VyOS-HTB default bandwidth '20%' - set qos policy shaper VyOS-HTB default queue-type 'fq-codel' - -In this example, we can observe that different DSCP criteria are defined based -on our QoS configuration within the same policy group. - -Default -------- - -Often you will also have to configure your *default* traffic in the same -way you do with a class. *Default* can be considered a class as it -behaves like that. It contains any traffic that did not match any -of the defined classes, so it is like an open class, a class without -matching filters. - - -Class treatment ---------------- - -Once a class has a filter configured, you will also have to define what -you want to do with the traffic of that class, what specific -Traffic-Control treatment you want to give it. You will have different -possibilities depending on the Traffic Policy you are configuring. - -.. stop_vyoslinter - -.. code-block:: none - - vyos@vyos# set qos policy shaper MY-SHAPER class 30 - Possible completions: - bandwidth Available bandwidth for this policy (default: auto) - burst Burst size for this class (default: 15k) - ceiling Bandwidth limit for this class - codel-quantum - Deficit in the fair queuing algorithm (default 1514) - description Description - flows Number of flows into which the incoming packets are classified(default 1024) - interval Interval used to measure the delay (default 100) - +> match Class matching rule name - priority Priority for rule evaluation - queue-limit Maximum queue size - queue-type Queue type for default traffic (default: fq-codel) - set-dscp Change the Differentiated Services (DiffServ) field in the IP header - target Acceptable minimum standing/persistent queue delay (default: 5) - -.. 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 -that class to Expedite Forwarding. - - - DSCP values as per :rfc:`2474` and :rfc:`4595`: - - +---------+------------+--------+------------------------------+ - | Binary | Configured | Drop | Description | - | value | value | rate | | - +=========+============+========+==============================+ - | 101110 | 46 | - | Expedited forwarding (EF) | - +---------+------------+--------+------------------------------+ - | 000000 | 0 | - | Best effort traffic, default | - +---------+------------+--------+------------------------------+ - | 001010 | 10 | Low | Assured Forwarding(AF) 11 | - +---------+------------+--------+------------------------------+ - | 001100 | 12 | Medium | Assured Forwarding(AF) 12 | - +---------+------------+--------+------------------------------+ - | 001110 | 14 | High | Assured Forwarding(AF) 13 | - +---------+------------+--------+------------------------------+ - | 010010 | 18 | Low | Assured Forwarding(AF) 21 | - +---------+------------+--------+------------------------------+ - | 010100 | 20 | Medium | Assured Forwarding(AF) 22 | - +---------+------------+--------+------------------------------+ - | 010110 | 22 | High | Assured Forwarding(AF) 23 | - +---------+------------+--------+------------------------------+ - | 011010 | 26 | Low | Assured Forwarding(AF) 31 | - +---------+------------+--------+------------------------------+ - | 011100 | 28 | Medium | Assured Forwarding(AF) 32 | - +---------+------------+--------+------------------------------+ - | 011110 | 30 | High | Assured Forwarding(AF) 33 | - +---------+------------+--------+------------------------------+ - | 100010 | 34 | Low | Assured Forwarding(AF) 41 | - +---------+------------+--------+------------------------------+ - | 100100 | 36 | Medium | Assured Forwarding(AF) 42 | - +---------+------------+--------+------------------------------+ - | 100110 | 38 | High | Assured Forwarding(AF) 43 | - +---------+------------+--------+------------------------------+ - - - - -.. _embed: - -Embedding one policy into another one -------------------------------------- - -Often we need to embed one policy into another one. It is possible to do -so on classful policies, by attaching a new policy into a class. For -instance, you might want to apply different policies to the different -classes of a Round-Robin policy you have configured. - -A common example is the case of some policies which, in order to be -effective, they need to be applied to an interface that is directly -connected where the bottleneck is. If your router is not -directly connected to the bottleneck, but some hop before it, you can -emulate the bottleneck by embedding your non-shaping policy into a -classful shaping one so that it takes effect. - -You can configure a policy into a class through the ``queue-type`` -setting. - -.. code-block:: none - - set qos policy shaper FQ-SHAPER bandwidth 4gbit - set qos policy shaper FQ-SHAPER default bandwidth 100% - set qos policy shaper FQ-SHAPER default queue-type fq-codel - -As shown in the last command of the example above, the `queue-type` -setting allows these combinations. You will be able to use it -in many policies. - -.. note:: Some policies already include other embedded policies inside. - That is the case of Shaper_: each of its classes use fair-queue - unless you change it. - -.. _creating_a_traffic_policy: - - -Creating a traffic policy -========================= - -VyOS lets you control traffic in many different ways, here we will cover -every possibility. You can configure as many policies as you want, but -you will only be able to apply one policy per interface and direction -(inbound or outbound). - -Some policies can be combined, you will be able to embed_ a different -policy that will be applied to a class of the main policy. - -.. hint:: **If you are looking for a policy for your outbound traffic** - but you don't know which one you need and you don't want to go - through every possible policy shown here, **our bet is that highly - likely you are looking for a** Shaper_ **policy and you want to** - :ref:`set its queues <embed>` **as FQ-CoDel**. - -Drop Tail ---------- - -| **Queueing discipline:** PFIFO (Packet First In First Out). -| **Applies to:** Outbound traffic. - -This the simplest queue possible you can apply to your traffic. Traffic -must go through a finite queue before it is actually sent. You must -define how many packets that queue can contain. - -When a packet is to be sent, it will have to go through that queue, so -the packet will be placed at the tail of it. When the packet completely -goes through it, it will be dequeued emptying its place in the queue and -being eventually handed to the NIC to be actually sent out. - -Despite the Drop-Tail policy does not slow down packets, if many packets -are to be sent, they could get dropped when trying to get enqueued at -the tail. This can happen if the queue has still not been able to -release enough packets from its head. - -This is the policy that requires the lowest resources for the same -amount of traffic. But **very likely you do not need it as you cannot -get much from it. Sometimes it is used just to enable logging.** - -.. cfgcmd:: set qos policy drop-tail <policy-name> queue-limit - <number-of-packets> - - Use this command to configure a drop-tail policy (PFIFO). Choose a - unique name for this policy and the size of the queue by setting the - number of packets it can contain (maximum 4294967295). - - -Fair Queue ----------- - -| **Queueing discipline:** SFQ (Stochastic Fairness Queuing). -| **Applies to:** Outbound traffic. - -Fair Queue is a work-conserving scheduler which schedules the -transmission of packets based on flows, that is, it balances traffic -distributing it through different sub-queues in order to ensure -fairness so that each flow is able to send data in turn, preventing any -single one from drowning out the rest. - - -.. cfgcmd:: set qos policy fair-queue <policy-name> - - Use this command to create a Fair-Queue policy and give it a name. - It is based on the Stochastic Fairness Queueing and can be applied to - outbound traffic. - -In order to separate traffic, Fair Queue uses a classifier based on -source address, destination address and source port. The algorithm -enqueues packets to hash buckets based on those tree parameters. -Each of these buckets should represent a unique flow. Because multiple -flows may get hashed to the same bucket, the hashing algorithm is -perturbed at configurable intervals so that the unfairness lasts only -for a short while. Perturbation may however cause some inadvertent -packet reordering to occur. An advisable value could be 10 seconds. - -One of the uses of Fair Queue might be the mitigation of Denial of -Service attacks. - -.. cfgcmd:: set qos policy fair-queue <policy-name> hash-interval <seconds> - - Use this command to define a Fair-Queue policy, based on the - Stochastic Fairness Queueing, and set the number of seconds at which - a new queue algorithm perturbation will occur (maximum 4294967295). - -When dequeuing, each hash-bucket with data is queried in a round robin -fashion. You can configure the length of the queue. - -.. cfgcmd:: set qos policy fair-queue <policy-name> queue-limit <limit> - - Use this command to define a Fair-Queue policy, based on the - Stochastic Fairness Queueing, and set the number of maximum packets - allowed to wait in the queue. Any other packet will be dropped. - -.. note:: Fair Queue is a non-shaping (work-conserving) policy, so it - will only be useful if your outgoing interface is really full. If it - is not, VyOS will not own the queue and Fair Queue will have no - effect. If there is bandwidth available on the physical link, you can - embed_ Fair-Queue into a classful shaping policy to make sure it owns - the queue. - - - -.. _FQ-CoDel: - -FQ-CoDel --------- - -| **Queueing discipline** Fair/Flow Queue CoDel. -| **Applies to:** Outbound Traffic. - -The FQ-CoDel policy distributes the traffic into 1024 FIFO queues and -tries to provide good service between all of them. It also tries to keep -the length of all the queues short. - -FQ-CoDel fights bufferbloat and reduces latency without the need of -complex configurations. It has become the new default Queueing -Discipline for the interfaces of some GNU/Linux distributions. - -It uses a stochastic model to classify incoming packets into -different flows and is used to provide a fair share of the bandwidth to -all the flows using the queue. Each flow is managed by the CoDel -queuing discipline. Reordering within a flow is avoided since Codel -internally uses a FIFO queue. - -FQ-CoDel is based on a modified Deficit Round Robin (DRR_) queue -scheduler with the CoDel Active Queue Management (AQM) algorithm -operating on each queue. - - -.. note:: FQ-Codel is a non-shaping (work-conserving) policy, so it - will only be useful if your outgoing interface is really full. If it - is not, VyOS will not own the queue and FQ-Codel will have no - effect. If there is bandwidth available on the physical link, you can - embed_ FQ-Codel into a classful shaping policy to make sure it owns - the queue. If you are not sure if you need to embed your FQ-CoDel - policy into a Shaper, do it. - - -FQ-CoDel is tuned to run ok with its default parameters at 10Gbit -speeds. It might work ok too at other speeds without configuring -anything, but here we will explain some cases when you might want to -tune its parameters. - -When running it at 1Gbit and lower, you may want to reduce the -`queue-limit` to 1000 packets or less. In rates like 10Mbit, you may -want to set it to 600 packets. - -If you are using FQ-CoDel embedded into Shaper_ and you have large rates -(100Mbit and above), you may consider increasing `quantum` to 8000 or -higher so that the scheduler saves CPU. - -On low rates (below 40Mbit) you may want to tune `quantum` down to -something like 300 bytes. - -At very low rates (below 3Mbit), besides tuning `quantum` (300 keeps -being ok) you may also want to increase `target` to something like 15ms -and increase `interval` to something around 150 ms. - - -.. cfgcmd:: set qos policy fq-codel <policy name> codel-quantum <bytes> - - Use this command to configure an fq-codel policy, set its name and - the maximum number of bytes (default: 1514) to be dequeued from a - queue at once. - -.. cfgcmd:: set qos policy fq-codel <policy name> flows <number-of-flows> - - Use this command to configure an fq-codel policy, set its name and - the number of sub-queues (default: 1024) into which packets are - classified. - -.. cfgcmd:: set qos policy fq-codel <policy name> interval <milliseconds> - - Use this command to configure an fq-codel policy, set its name and - the time period used by the control loop of CoDel to detect when a - persistent queue is developing, ensuring that the measured minimum - delay does not become too stale (default: 100ms). - -.. cfgcmd:: set qos policy fq-codel <policy-name> queue-limit - <number-of-packets> - - Use this command to configure an fq-codel policy, set its name, and - define a hard limit on the real queue size. When this limit is - reached, new packets are dropped (default: 10240 packets). - -.. cfgcmd:: set qos policy fq-codel <policy-name> target <milliseconds> - - Use this command to configure an fq-codel policy, set its name, and - define the acceptable minimum standing/persistent queue delay. This - minimum delay is identified by tracking the local minimum queue delay - that packets experience (default: 5ms). - - -Example -^^^^^^^ - -A simple example of an FQ-CoDel policy working inside a Shaper one. - - -.. code-block:: none - - set qos policy shaper FQ-CODEL-SHAPER bandwidth 2gbit - set qos policy shaper FQ-CODEL-SHAPER default bandwidth 100% - set qos policy shaper FQ-CODEL-SHAPER default queue-type fq-codel - - - -Limiter -------- - -| **Queueing discipline:** Ingress policer. -| **Applies to:** Inbound traffic. - -Limiter is one of those policies that uses classes_ (Ingress qdisc is -actually a classless policy but filters do work in it). - -The limiter performs basic ingress policing of traffic flows. Multiple -classes of traffic can be defined and traffic limits can be applied to -each class. Although the policer uses a token bucket mechanism -internally, it does not have the capability to delay a packet as a -shaping mechanism does. Traffic exceeding the defined bandwidth limits -is directly dropped. A maximum allowed burst can be configured too. - -You can configure classes (up to 4090) with different settings and a -default policy which will be applied to any traffic not matching any of -the configured classes. - - -.. note:: In the case you want to apply some kind of **shaping** to your - **inbound** traffic, check the ingress-shaping_ section. - - -.. cfgcmd:: set qos policy limiter <policy-name> class <class ID> match - <match-name> description <description> - - Use this command to configure an Ingress Policer, defining its name, - a class identifier (1-4090), a class matching rule name and its - description. - - -Once the matching rules are set for a class, you can start configuring -how you want matching traffic to behave. - - -.. cfgcmd:: set qos policy limiter <policy-name> class <class-ID> bandwidth - <rate> - - Use this command to configure an Ingress Policer, defining its name, - a class identifier (1-4090) and the maximum allowed bandwidth for - this class. - - -.. cfgcmd:: set qos policy limiter <policy-name> class <class-ID> burst - <burst-size> - - Use this command to configure an Ingress Policer, defining its name, - a class identifier (1-4090) and the burst size in bytes for this - class (default: 15). - - -.. cfgcmd:: set qos policy limiter <policy-name> default bandwidth <rate> - - Use this command to configure an Ingress Policer, defining its name - and the maximum allowed bandwidth for its default policy. - - -.. cfgcmd:: set qos policy limiter <policy-name> default burst <burst-size> - - Use this command to configure an Ingress Policer, defining its name - and the burst size in bytes (default: 15) for its default policy. - - -.. cfgcmd:: set qos policy limiter <policy-name> class <class ID> priority - <value> - - Use this command to configure an Ingress Policer, defining its name, - a class identifier (1-4090), and the priority (0-20, default 20) in - which the rule is evaluated (the lower the number, the higher the - priority). - - - -Network Emulator ----------------- - -| **Queueing discipline:** netem (Network Emulator) + TBF (Token Bucket Filter). -| **Applies to:** Outbound traffic. - -VyOS Network Emulator policy emulates the conditions you can suffer in a -real network. You will be able to configure things like rate, burst, -delay, packet loss, packet corruption or packet reordering. - -This could be helpful if you want to test how an application behaves -under certain network conditions. - - -.. cfgcmd:: set qos policy network-emulator <policy-name> bandwidth <rate> - - Use this command to configure the maximum rate at which traffic will - be shaped in a Network Emulator policy. Define the name of the policy - and the rate. - -.. cfgcmd:: set qos policy network-emulator <policy-name> burst <burst-size> - - Use this command to configure the burst size of the traffic in a - Network Emulator policy. Define the name of the Network Emulator - policy and its traffic burst size (it will be configured through the - Token Bucket Filter qdisc). Default:15kb. It will only take effect if - you have configured its bandwidth too. - -.. cfgcmd:: set qos policy network-emulator <policy-name> delay - <delay> - - Use this command to configure a Network Emulator policy defining its - name and the fixed amount of time you want to add to all packet going - out of the interface. The latency will be added through the - Token Bucket Filter qdisc. It will only take effect if you have - configured its bandwidth too. You can use secs, ms and us. Default: - 50ms. - -.. cfgcmd:: set qos policy network-emulator <policy-name> corruption - <percent> - - Use this command to emulate noise in a Network Emulator policy. Set - the policy name and the percentage of corrupted packets you want. A - random error will be introduced in a random position for the chosen - percent of packets. - -.. cfgcmd:: set qos policy network-emulator <policy-name> loss - <percent> - - Use this command to emulate packet-loss conditions in a Network - Emulator policy. Set the policy name and the percentage of loss - packets your traffic will suffer. - -.. cfgcmd:: set traffic-policy network-emulator <policy-name> reordering - <percent> - - Use this command to emulate packet-reordering conditions in a Network - Emulator policy. Set the policy name and the percentage of reordered - packets your traffic will suffer. - -.. cfgcmd:: set traffic-policy network-emulator <policy-name> queue-limit - <limit> - - Use this command to define the length of the queue of your Network - Emulator policy. Set the policy name and the maximum number of - packets (1-4294967295) the queue may hold queued at a time. - - - -Priority Queue --------------- - -| **Queueing discipline:** PRIO. -| **Applies to:** Outbound traffic. - - -The Priority Queue is a classful scheduling policy. It does not delay -packets (Priority Queue is not a shaping policy), it simply dequeues -packets according to their priority. - -.. note:: Priority Queue, as other non-shaping policies, is only useful - if your outgoing interface is really full. If it is not, VyOS will - not own the queue and Priority Queue will have no effect. If there is - bandwidth available on the physical link, you can embed_ Priority - Queue into a classful shaping policy to make sure it owns the queue. - In that case packets can be prioritized based on DSCP. - -Up to seven queues -defined as classes_ with different priorities- can -be configured. Packets are placed into queues based on associated match -criteria. Packets are transmitted from the queues in priority order. If -classes with a higher priority are being filled with packets -continuously, packets from lower priority classes will only be -transmitted after traffic volume from higher priority classes decreases. - - -.. note:: In Priority Queue we do not define classes with a meaningless - class ID number but with a class priority number (1-7). The lower the - number, the higher the priority. - - -As with other policies, you can define different type of matching rules -for your classes: - -.. code-block:: none - - vyos@vyos# set qos policy priority-queue MY-PRIO class 3 match MY-MATCH-RULE - Possible completions: - description Description - > ether Ethernet header match - interface Interface to use - > ip Match IP protocol header - > ipv6 Match IPV6 protocol header - mark Match on mark applied by firewall - vif Virtual Local Area Network (VLAN) ID for this match - - -As with other policies, you can embed_ other policies into the classes -(and default) of your Priority Queue policy through the ``queue-type`` -setting: - -.. code-block:: none - - vyos@vyos# set qos policy priority-queue MY-PRIO class 3 queue-type - Possible completions: - drop-tail First-In-First-Out (FIFO) (default) - fq-codel Fair Queue Codel - fair-queue Stochastic Fair Queue (SFQ) - priority Priority queueing - random-detect - Random Early Detection (RED) - - -.. cfgcmd:: set qos policy priority-queue <policy-name> class <class-ID> - queue-limit <limit> - - Use this command to configure a Priority Queue policy, set its name, - set a class with a priority from 1 to 7 and define a hard limit on - the real queue size. When this limit is reached, new packets are - dropped. - - - -.. _Random-Detect: - -Random-Detect -------------- - - -| **Queueing discipline:** Generalized Random Early Drop. -| **Applies to:** Outbound traffic. - -A simple Random Early Detection (RED) policy would start randomly -dropping packets from a queue before it reaches its queue limit thus -avoiding congestion. That is good for TCP connections as the gradual -dropping of packets acts as a signal for the sender to decrease its -transmission rate. - -In contrast to simple RED, VyOS' Random-Detect uses a Generalized Random -Early Detect policy that provides different virtual queues based on the -IP Precedence value so that some virtual queues can drop more packets -than others. - -This is achieved by using the first three bits of the ToS (Type of -Service) field to categorize data streams and, in accordance with the -defined precedence parameters, a decision is made. - -IP precedence as defined in :rfc:`791`: - - +------------+----------------------+ - | Precedence | Priority | - +============+======================+ - | 7 | Network Control | - +------------+----------------------+ - | 6 | Internetwork Control | - +------------+----------------------+ - | 5 | CRITIC/ECP | - +------------+----------------------+ - | 4 | Flash Override | - +------------+----------------------+ - | 3 | Flash | - +------------+----------------------+ - | 2 | Immediate | - +------------+----------------------+ - | 1 | Priority | - +------------+----------------------+ - | 0 | Routine | - +------------+----------------------+ - - -Random-Detect could be useful for heavy traffic. One use of this -algorithm might be to prevent a backbone overload. But only for TCP -(because dropped packets could be retransmitted), not for UDP. - - -.. cfgcmd:: set qos policy random-detect <policy-name> bandwidth <bandwidth> - - Use this command to configure a Random-Detect policy, set its name - and set the available bandwidth for this policy. It is used for - calculating the average queue size after some idle time. It should be - set to the bandwidth of your interface. Random Detect is not a - shaping policy, this command will not shape. - -.. cfgcmd:: set qos policy random-detect <policy-name> precedence - <IP-precedence-value> average-packet <bytes> - - Use this command to configure a Random-Detect policy and set its - name, then state the IP Precedence for the virtual queue you are - configuring and what the size of its average-packet should be - (in bytes, default: 1024). - -.. note:: When configuring a Random-Detect policy: **the higher the - precedence number, the higher the priority**. - -.. cfgcmd:: set qos policy random-detect <policy-name> precedence - <IP-precedence-value> mark-probability <value> - - Use this command to configure a Random-Detect policy and set its - name, then state the IP Precedence for the virtual queue you are - configuring and what its mark (drop) probability will be. Set the - probability by giving the N value of the fraction 1/N (default: 10). - - -.. cfgcmd:: set qos policy random-detect <policy-name> precedence - <IP-precedence-value> maximum-threshold <packets> - - Use this command to configure a Random-Detect policy and set its - name, then state the IP Precedence for the virtual queue you are - configuring and what its maximum threshold for random detection will - be (from 0 to 4096 packets, default: 18). At this size, the marking - (drop) probability is maximal. - -.. cfgcmd:: set qos policy random-detect <policy-name> precedence - <IP-precedence-value> minimum-threshold <packets> - - Use this command to configure a Random-Detect policy and set its - name, then state the IP Precedence for the virtual queue you are - configuring and what its minimum threshold for random detection will - be (from 0 to 4096 packets). If this value is exceeded, packets - start being eligible for being dropped. - - -The default values for the minimum-threshold depend on IP precedence: - - +------------+-----------------------+ - | Precedence | default min-threshold | - +============+=======================+ - | 7 | 16 | - +------------+-----------------------+ - | 6 | 15 | - +------------+-----------------------+ - | 5 | 14 | - +------------+-----------------------+ - | 4 | 13 | - +------------+-----------------------+ - | 3 | 12 | - +------------+-----------------------+ - | 2 | 11 | - +------------+-----------------------+ - | 1 | 10 | - +------------+-----------------------+ - | 0 | 9 | - +------------+-----------------------+ - - -.. cfgcmd:: set qos policy random-detect <policy-name> precedence - <IP-precedence-value> queue-limit <packets> - - Use this command to configure a Random-Detect policy and set its - name, then name the IP Precedence for the virtual queue you are - configuring and what the maximum size of its queue will be (from 1 to - 1-4294967295 packets). Packets are dropped when the current queue - length reaches this value. - - -If the average queue size is lower than the **min-threshold**, an -arriving packet will be placed in the queue. - -In the case the average queue size is between **min-threshold** and -**max-threshold**, then an arriving packet would be either dropped or -placed in the queue, it will depend on the defined **mark-probability**. - -If the current queue size is larger than **queue-limit**, -then packets will be dropped. The average queue size depends on its -former average size and its current one. - -If **max-threshold** is set but **min-threshold is not, then -**min-threshold** is scaled to 50% of **max-threshold**. - -In principle, values must be -:code:`min-threshold` < :code:`max-threshold` < :code:`queue-limit`. - - - - -Rate Control ------------- - -| **Queueing discipline:** Token Bucket Filter. -| **Applies to:** Outbound traffic. - -Rate-Control is a classless policy that limits the packet flow to a set -rate. It is a pure shaper, it does not schedule traffic. Traffic is -filtered based on the expenditure of tokens. Tokens roughly correspond -to bytes. - -Short bursts can be allowed to exceed the limit. On creation, the -Rate-Control traffic is stocked with tokens which correspond to the -amount of traffic that can be burst in one go. Tokens arrive at a steady -rate, until the bucket is full. - -.. cfgcmd:: set qos policy rate-control <policy-name> bandwidth <rate> - - Use this command to configure a Rate-Control policy, set its name - and the rate limit you want to have. - -.. cfgcmd:: set qos policy rate-control <policy-name> burst <burst-size> - - Use this command to configure a Rate-Control policy, set its name - and the size of the bucket in bytes which will be available for - burst. - - -As a reference: for 10mbit/s on Intel, you might need at least 10kbyte -buffer if you want to reach your configured rate. - -A very small buffer will soon start dropping packets. - -.. cfgcmd:: set qos policy rate-control <policy-name> latency - - Use this command to configure a Rate-Control policy, set its name - and the maximum amount of time a packet can be queued (default: 50 - ms). - - -Rate-Control is a CPU-friendly policy. You might consider using it when -you just simply want to slow traffic down. - -.. _DRR: - -Round Robin ------------ - -| **Queueing discipline:** Deficit Round Robin. -| **Applies to:** Outbound traffic. - -The round-robin policy is a classful scheduler that divides traffic in -different classes_ you can configure (up to 4096). You can embed_ a -new policy into each of those classes (default included). - -Each class is assigned a deficit counter (the number of bytes that a -flow is allowed to transmit when it is its turn) initialized to quantum. -Quantum is a parameter you configure which acts like a credit of fix -bytes the counter receives on each round. Then the Round-Robin policy -starts moving its Round Robin pointer through the queues. If the deficit -counter is greater than the packet's size at the head of the queue, this -packet will be sent and the value of the counter will be decremented by -the packet size. Then, the size of the next packet will be compared to -the counter value again, repeating the process. Once the queue is empty -or the value of the counter is insufficient, the Round-Robin pointer -will move to the next queue. If the queue is empty, the value of the -deficit counter is reset to 0. - -At every round, the deficit counter adds the quantum so that even large -packets will have their opportunity to be dequeued. - - -.. cfgcmd:: set qos policy round-robin <policy name> class - <class-ID> quantum <packets> - - Use this command to configure a Round-Robin policy, set its name, set - a class ID, and the quantum for that class. The deficit counter will - add that value each round. - -.. cfgcmd:: set qos policy round-robin <policy name> class - <class ID> queue-limit <packets> - - Use this command to configure a Round-Robin policy, set its name, set - a class ID, and the queue size in packets. - -As with other policies, Round-Robin can embed_ another policy into a -class through the ``queue-type`` setting. - -.. code-block:: none - - vyos@vyos# set qos policy round-robin DRR class 10 queue-type - Possible completions: - drop-tail First-In-First-Out (FIFO) (default) - fq-codel Fair Queue Codel - fair-queue Stochastic Fair Queue (SFQ) - priority Priority queueing based - random-detect - Random Early Detection (RED) - - - - -.. _Shaper: - -Shaper ------- - -| **Queueing discipline:** Hierarchical Token Bucket. -| **Applies to:** Outbound traffic. - - -The Shaper policy does not guarantee a low delay, but it does guarantee -bandwidth to different traffic classes and also lets you decide how to -allocate more traffic once the guarantees are met. - -Each class can have a guaranteed part of the total bandwidth defined for -the whole policy, so all those shares together should not be higher -than the policy's whole bandwidth. - -If guaranteed traffic for a class is met and there is room for more -traffic, the ceiling parameter can be used to set how much more -bandwidth could be used. If guaranteed traffic is met and there are -several classes willing to use their ceilings, the priority parameter -will establish the order in which that additional traffic will be -allocated. Priority can be any number from 0 to 7. The lower the number, -the higher the priority. - - -.. cfgcmd:: set qos policy shaper <policy-name> bandwidth <rate> - - Use this command to configure a Shaper policy, set its name - and the maximum bandwidth for all combined traffic. - - -.. cfgcmd:: set qos policy shaper <policy-name> class <class-ID> bandwidth - <rate> - - Use this command to configure a Shaper policy, set its name, define - a class and set the guaranteed traffic you want to allocate to that - class. - -.. cfgcmd:: set qos policy shaper <policy-name> class <class-ID> burst - <bytes> - - Use this command to configure a Shaper policy, set its name, define - a class and set the size of the `tocken bucket`_ in bytes, which will - be available to be sent at ceiling speed (default: 15Kb). - -.. cfgcmd:: set qos policy shaper <policy-name> class <class-ID> ceiling - <bandwidth> - - Use this command to configure a Shaper policy, set its name, define - a class and set the maximum speed possible for this class. The - default ceiling value is the bandwidth value. - -.. cfgcmd:: set qos policy shaper <policy-name> class <class-ID> priority - <0-7> - - Use this command to configure a Shaper policy, set its name, define - a class and set the priority for usage of available bandwidth once - guarantees have been met. The lower the priority number, the higher - the priority. The default priority value is 0, the highest priority. - - -As with other policies, Shaper can embed_ other policies into its -classes through the ``queue-type`` setting and then configure their -parameters. - - -.. code-block:: none - - vyos@vyos# set qos policy shaper HTB class 10 queue-type - Possible completions: - fq-codel Fair Queue Codel (default) - fair-queue Stochastic Fair Queue (SFQ) - drop-tail First-In-First-Out (FIFO) - priority Priority queueing - random-detect - Random Early Detection (RED) - - -.. stop_vyoslinter - -.. code-block:: none - - vyos@vyos# set qos policy shaper HTB class 10 - Possible completions: - bandwidth Available bandwidth for this policy (default: auto) - burst Burst size for this class (default: 15k) - ceiling Bandwidth limit for this class - codel-quantum - Deficit in the fair queuing algorithm (default 1514) - description Description - flows Number of flows into which the incoming packets are classified (default 1024) - interval Interval used to measure the delay (default 100) - +> match Class matching rule name - priority Priority for rule evaluation - queue-limit Maximum queue size (packets) - queue-type Queue type for default traffic (default: fq-codel) - set-dscp Change the Differentiated Services (DiffServ) field in the IP header - target Acceptable minimum standing/persistent queue delay (default: 5) - -.. start_vyoslinter - - - -.. note:: If you configure a class for **VoIP traffic**, don't give it any - *ceiling*, otherwise new VoIP calls could start when the link is - available and get suddenly dropped when other classes start using - their assigned *bandwidth* share. - -.. _traffic_policy:shaper_example: - -Example -^^^^^^^ - -A simple example of Shaper using priorities. - - -.. stop_vyoslinter - -.. code-block:: none - - set qos policy shaper MY-HTB bandwidth '50mbit' - set qos policy shaper MY-HTB class 10 bandwidth '20%' - set qos policy shaper MY-HTB class 10 match DSCP ip dscp 'EF' - set qos policy shaper MY-HTB class 10 queue-type 'fq-codel' - set qos policy shaper MY-HTB class 20 bandwidth '10%' - set qos policy shaper MY-HTB class 20 ceiling '50%' - set qos policy shaper MY-HTB class 20 match PORT666 ip destination port '666' - set qos policy shaper MY-HTB class 20 priority '3' - set qos policy shaper MY-HTB class 20 queue-type 'fair-queue' - set qos policy shaper MY-HTB class 30 bandwidth '10%' - set qos policy shaper MY-HTB class 30 ceiling '50%' - set qos policy shaper MY-HTB class 30 match ADDRESS30 ip source address '192.168.30.0/24' - set qos policy shaper MY-HTB class 30 priority '5' - set qos policy shaper MY-HTB class 30 queue-type 'fair-queue' - set qos policy shaper MY-HTB default bandwidth '10%' - set qos policy shaper MY-HTB default ceiling '100%' - set qos policy shaper MY-HTB default priority '7' - set qos policy shaper MY-HTB default queue-type 'fair-queue' - -.. start_vyoslinter - -.. _CAKE: - -CAKE ------- - -| **Queueing discipline:** Deficit mode. -| **Applies to:** Outbound traffic. - -`Common Applications Kept Enhanced`_ (CAKE) is a comprehensive queue management -system, implemented as a queue discipline (qdisc) for the Linux kernel. It is -designed to replace and improve upon the complex hierarchy of simple qdiscs -presently required to effectively tackle the bufferbloat problem at the network -edge. - -.. cfgcmd:: set qos policy cake <text> bandwidth <value> - - Set the shaper bandwidth, either as an explicit bitrate or a percentage - of the interface bandwidth. - -.. cfgcmd:: set qos policy cake <text> description - - Set a description for the shaper. - -.. cfgcmd:: set qos policy cake <text> flow-isolation blind - - Disables flow isolation, all traffic passes through a single queue. - -.. cfgcmd:: set qos policy cake <text> flow-isolation dst-host - - Flows are defined only by destination address. - -.. cfgcmd:: set qos policy cake <text> flow-isolation dual-dst-host - - Flows are defined by the 5-tuple. Fairness is applied first over destination - addresses, then over individual flows. - -.. cfgcmd:: set qos policy cake <text> flow-isolation dual-src-host - - Flows are defined by the 5-tuple. Fairness is applied first over source - addresses, then over individual flows. - -.. cfgcmd:: set qos policy cake <text> flow-isolation flow - - Flows are defined by the entire 5-tuple (source IP address, source port, - destination IP address, destination port, transport protocol). - -.. cfgcmd:: set qos policy cake <text> flow-isolation host - - Flows are defined by source-destination host pairs. - -.. cfgcmd:: set qos policy cake <text> flow-isolation nat - - Perform NAT lookup before applying flow-isolation rules. - -.. cfgcmd:: set qos policy cake <text> flow-isolation src-host - - Flows are defined only by source address. - -.. 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. - -.. cfgcmd:: set qos policy cake <text> rtt - - Defines the round-trip time used for active queue management (AQM) in - milliseconds. The default value is 100. - - -Applying a traffic policy -========================= - -Once a traffic-policy is created, you can apply it to an interface: - -.. code-block:: none - - set qos interface eth0 egress WAN-OUT - -You can only apply one policy per interface and direction, but you could -reuse a policy on different interfaces and directions: - -.. code-block:: none - - set qos interface eth0 ingress WAN-IN - set qos interface eth0 egress WAN-OUT - set qos interface eth1 ingress LAN-IN - set qos interface eth1 egress LAN-OUT - set qos interface eth2 ingress LAN-IN - set qos interface eth2 egress LAN-OUT - set qos interface eth3 ingress TWO-WAY-POLICY - set qos interface eth3 egress TWO-WAY-POLICY - set qos interface eth4 ingress TWO-WAY-POLICY - set qos interface eth4 egress TWO-WAY-POLICY - - - -.. _ingress-shaping: - -The case of ingress shaping -=========================== - -| **Applies to:** Inbound traffic. - -For the ingress traffic of an interface, there is only one policy you -can directly apply, a **Limiter** policy. You cannot apply a shaping -policy directly to the ingress traffic of any interface because shaping -only works for outbound traffic. - -This workaround lets you apply a shaping policy to the ingress traffic -by first redirecting it to an in-between virtual interface -(`Intermediate Functional Block`_). There, in that virtual interface, -you will be able to apply any of the policies that work for outbound -traffic, for instance, a shaping one. - -That is how it is possible to do the so-called "ingress shaping". - - -.. code-block:: none - - set qos policy shaper MY-INGRESS-SHAPING bandwidth 1000kbit - set qos policy shaper MY-INGRESS-SHAPING default bandwidth 1000kbit - set qos policy shaper MY-INGRESS-SHAPING default queue-type fair-queue - - set qos interface ifb0 egress MY-INGRESS-SHAPING - set interfaces ethernet eth0 redirect ifb0 - - set interfaces input ifb0 - -.. warning:: - - Do not configure IFB as the first step. First create everything else - of your traffic-policy, and then you can configure IFB. - Otherwise you might get the ``RTNETLINK answer: File exists`` error, - which can be solved with ``sudo ip link delete ifb0``. - - -.. stop_vyoslinter - -.. _that can give you a great deal of flexibility: https://blog.vyos.io/using-the-policy-route-and-packet-marking-for-custom-qos-matches -.. _tc: https://en.wikipedia.org/wiki/Tc_(Linux) -.. _tocken bucket: https://en.wikipedia.org/wiki/Token_bucket -.. _HFSC: https://en.wikipedia.org/wiki/Hierarchical_fair-service_curve -.. _Intermediate Functional Block: https://www.linuxfoundation.org/collaborate/workgroups/networking/ifb -.. _Common Applications Kept Enhanced: https://www.bufferbloat.net/projects/codel/wiki/Cake/ - -.. start_vyoslinter diff --git a/docs/configuration/vpn/ipsec/rst-index.rst b/docs/configuration/vpn/ipsec/rst-index.rst deleted file mode 100644 index 973c76de..00000000 --- a/docs/configuration/vpn/ipsec/rst-index.rst +++ /dev/null @@ -1,15 +0,0 @@ -##### -IPsec -##### - - -.. toctree:: - :maxdepth: 1 - :includehidden: - - ipsec_general - site2site_ipsec - remoteaccess_ipsec - troubleshooting_ipsec - - diff --git a/docs/configuration/vpn/ipsec/rst-ipsec_general.rst b/docs/configuration/vpn/ipsec/rst-ipsec_general.rst deleted file mode 100644 index 3d21b81d..00000000 --- a/docs/configuration/vpn/ipsec/rst-ipsec_general.rst +++ /dev/null @@ -1,407 +0,0 @@ -.. _ipsec_general: - -######################### -IPsec General Information -######################### - -*********************** -Information about IPsec -*********************** - -IPsec is the framework used to secure data. -IPsec accomplishes these goals by providing authentication, -encryption of IP network packets, key exchange, and key management. -VyOS uses Strongswan package to implement IPsec. - -**Authentication Header (AH)** is defined in :rfc:`4302`. It creates -a hash using the IP header and data payload, and prepends it to the -packet. This hash is used to validate that the data has not been -changed during transfer over the network. - -**Encapsulating Security Payload (ESP)** is defined in :rfc:`4303`. -It provides encryption and authentication of the data. - - -There are two IPsec modes: - **IPsec Transport Mode**: - In transport mode, an IPSec header (AH or ESP) is inserted - between the IP header and the upper layer protocol header. - - **IPsec Tunnel Mode:** - In tunnel mode, the original IP packet is encapsulated in - another IP datagram, and an IPsec header (AH or ESP) is - inserted between the outer and inner headers. - -.. figure:: /_static/images/ESP_AH.* - :scale: 80 % - :alt: AH and ESP in Transport Mode and Tunnel Mode - -*************************** -IKE (Internet Key Exchange) -*************************** -The default IPsec method for secure key negotiation is the Internet Key -Exchange (IKE) protocol. IKE is designed to provide mutual authentication -of systems, as well as to establish a shared secret key to create IPsec -security associations. A security association (SA) includes all relevant -attributes of the connection, including the cryptographic algorithm used, -the IPsec mode, the encryption key, and other parameters related to the -transmission of data over the VPN connection. - -IKEv1 -===== - -IKEv1 is the older version and is still used today. Nowadays, most -manufacturers recommend using IKEv2 protocol. - -IKEv1 is described in the next RFCs: :rfc:`2409` (IKE), :rfc:`3407` -(IPsec DOI), :rfc:`3947` (NAT-T), :rfc:`3948` (UDP Encapsulation -of ESP Packets), :rfc:`3706` (DPD) - -IKEv1 operates in two phases to establish these IKE and IPsec SAs: - * **Phase 1** provides mutual authentication of the IKE peers and - establishment of the session key. This phase creates an IKE SA (a - security association for IKE) using a DH exchange, cookies, and an - ID exchange. Once an IKE SA is established, all IKE communication - between the initiator and responder is protected with encryption - and an integrity check that is authenticated. The purpose of IKE - phase 1 is to facilitate a secure channel between the peers so that - phase 2 negotiations can occur securely. IKE phase 1 offers two modes: - Main and Aggressive. - - * **Main Mode** is used for site-to-site VPN connections. - - * **Aggressive Mode** is used for remote access VPN connections. - - * **Phase 2** provides for the negotiation and establishment of the - IPsec SAs using ESP or AH to protect IP data traffic. - -IKEv2 -===== - -IKEv2 is described in :rfc:`7296`. The biggest difference between IKEv1 and -IKEv2 is that IKEv2 is much simpler and more reliable than IKEv1 because -fewer messages are exchanged during the establishment of the VPN and -additional security capabilities are available. - - -IKE Authentication -================== - -VyOS supports 3 authentication methods. - * **Pre-shared keys**: In this method, both peers of the IPsec - tunnel must have the same preshared keys. - * **Digital certificates**: PKI is used in this method. - * **RSA-keys**: If the RSA-keys method is used in your IKE policy, - you need to make sure each peer has the other peer’s public keys. - -************************* -DPD (Dead Peer Detection) -************************* - -This is a mechanism used to detect when a VPN peer is no longer active. -This mechanism has different algorithms in IKEv1 and IKEv2 in VyOS. -DPD Requests are sent as ISAKMP R-U-THERE messages and DPD Responses -are sent as ISAKMP R-U-THERE-ACK messages. In IKEv1, DPD sends messages -every configured interval. The remote peer is considered unreachable -if no response to these packets is received within the DPD timeout. -In IKEv2, DPD sends messages every configured interval. If one request -is not responded, Strongswan execute its retransmission algorithm with -its timers. `IKEv2 Retransmission`_ - -********************************* -Post-Quantum Preshared Keys (PPK) -********************************* - -Post-Quantum Preshared Keys help provide some quantum resistance to IPSec -tunnels when a post-quantum key exchange algorithm such as ML-KEM is not -available. The use of PPKs in IKEv2 is described in :rfc:`8784`. - -.. cfgmod:: edit vpn authentication ppk <name> - -PPKs can be configued within VyOS under the `vpn ipsec authentication ppk` -config. - -.. cfgmod:: set vpn authentication ppk <name> secret-type <plaintext|hex|base64> - -PPKs need an id and a secret value. The ID and the secret must match if PPKs are -required for a successful IPsec connection. The secret can be plain text, a -hex value, or a Base64 value. The default is plain text. If using another -type of value, you must define the secret type. - -.. cfgmod:: set vpn ipsec site-to-site <name> ppk id <id> - -To use a PPK within a site-to-site or remote access connection, define the PPK -id under the connection. - -.. cfgmod:: set vpn ipsec site-to-site <name> ppk required - -Optionally, you can require the use of PPK to have a successful connection. - -.. cfgmod:: show vpn ipsec connections - -You can view the PPK column for information on if PPK is configured, and -if it is in use. The output is in the format of ``<configured> / <in use>``. -The options for configured are none if not conifugred, opt if configured -but optional, and req is configured and required. The in use will show yes -Possible values of the ``configured`` field are ``none`` if not -conifgured, ``opt`` if configured but optional, and ``req`` is -configured and required. The in use will show yes - - - - -***************** -Configuration IKE -***************** - -IKE (Internet Key Exchange) Attributes -====================================== - -VyOS IKE group has the next options: - -.. cfgcmd:: set vpn ipsec ike-group <name> close-action <action> - - Defines the action to take if the remote peer unexpectedly - closes a CHILD_SA: - - * **none** - Set action to none (default), - * **trap** - Installs a trap policy (IPsec policy without Security - Association) for the CHILD_SA and traffic matching these policies - will trigger acquire events that cause the daemon to establish the - required IKE/IPsec SAs. - * **start** - Tries to immediately re-create the CHILD_SA. - -.. cfgcmd:: set vpn ipsec ike-group <name> ikev2-reauth - - Whether rekeying of an IKE_SA should also reauthenticate - the peer. In IKEv1, reauthentication is always done. - Setting this parameter enables remote host re-authentication - during an IKE rekey. - -.. cfgcmd:: set vpn ipsec ike-group <name> key-exchange - - Which protocol should be used to initialize the connection - If not set both protocols are handled and connections will - use IKEv2 when initiating, but accept any protocol version - when responding: - - * **ikev1** - Use IKEv1 for Key Exchange. - * **ikev2** - Use IKEv2 for Key Exchange. - -.. cfgcmd:: set vpn ipsec ike-group <name> lifetime - - IKE lifetime in seconds <0-86400> (default 28800). - -.. cfgcmd:: set vpn ipsec ike-group <name> mode - - IKEv1 Phase 1 Mode Selection: - - * **main** - Use Main mode for Key Exchanges in the IKEv1 Protocol - (Recommended Default). - * **aggressive** - Use Aggressive mode for Key Exchanges in the IKEv1 - protocol aggressive mode is much more insecure compared to Main mode. - -.. stop_vyoslinter - -.. cfgcmd:: set vpn ipsec ike-group <name> proposal <number> dh-group <dh-group number> - - Dh-group. Default value is **2**. - -.. cfgcmd:: set vpn ipsec ike-group <name> proposal <number> encryption <encryption> - - Encryption algorithm. Default value is **aes128**. - -.. start_vyoslinter - -.. cfgcmd:: set vpn ipsec ike-group <name> proposal <number> hash <hash> - - Hash algorithm. Default value is **sha1**. - -.. cfgcmd:: set vpn ipsec ike-group <name> proposal <number> prf <prf> - - Pseudo-random function. - - -DPD (Dead Peer Detection) Configuration -======================================= - -.. cfgcmd:: set vpn ipsec ike-group <name> dead-peer-detection action <action> - - Action to perform for this CHILD_SA on DPD timeout. - - * **trap** - Installs a trap policy (IPsec policy without Security - Association), which will catch matching traffic and tries to - re-negotiate the tunnel on-demand. - * **clear** - Closes the CHILD_SA and does not take further action - (default). - * **restart** - Immediately tries to re-negotiate the CHILD_SA - under a fresh IKE_SA. - -.. stop_vyoslinter - -.. cfgcmd:: set vpn ipsec ike-group <name> dead-peer-detection interval <interval> - - Keep-alive interval in seconds <2-86400> (default 30). - -.. start_vyoslinter - -.. cfgcmd:: set vpn ipsec ike-group <name> dead-peer-detection timeout <timeout> - - Keep-alive timeout in seconds <2-86400> (default 120) **IKEv1 only** - -ESP (Encapsulating Security Payload) Attributes -=============================================== - -In VyOS, ESP attributes are specified through ESP groups. -Multiple proposals can be specified in a single group. - -VyOS ESP group has the next options: - -.. cfgcmd:: set vpn ipsec esp-group <name> compression - - Enables the IPComp(IP Payload Compression) protocol which allows - compressing the content of IP packets. - -.. cfgcmd:: set vpn ipsec esp-group <name> disable-rekey - - Do not locally initiate a re-key of the SA, remote peer must - re-key before expiration. - -.. cfgcmd:: set vpn ipsec esp-group <name> life-bytes <bytes> - - ESP life in bytes <1024-26843545600000>. Number of bytes - transmitted over an IPsec SA before it expires. - -.. cfgcmd:: set vpn ipsec esp-group <name> life-packets <packets> - - ESP life in packets <1000-26843545600000>. - Number of packets transmitted over an IPsec SA before it expires. - -.. cfgcmd:: set vpn ipsec esp-group <name> lifetime <timeout> - - ESP lifetime in seconds <30-86400> (default 3600). - How long a particular instance of a connection (a set of - encryption/authentication keys for user packets) should last, - from successful negotiation to expiry. - -.. cfgcmd:: set vpn ipsec esp-group <name> mode <mode> - - The type of the connection: - - * **tunnel** - Tunnel mode (default). - * **transport** - Transport mode. - -.. cfgcmd:: set vpn ipsec esp-group <name> pfs < dh-group> - - Whether Perfect Forward Secrecy of keys is desired on the - connection's keying channel and defines a Diffie-Hellman group for - PFS: - - * **enable** - Inherit Diffie-Hellman group from IKE group (default). - * **disable** - Disable PFS. - * **<dh-group>** - Defines a Diffie-Hellman group for PFS. - -.. stop_vyoslinter - -.. cfgcmd:: set vpn ipsec esp-group <name> proposal <number> encryption <encryption> - - Encryption algorithm. Default value is **aes128**. - -.. start_vyoslinter - -.. cfgcmd:: set vpn ipsec esp-group <name> proposal <number> hash <hash> - - Hash algorithm. Default value is **sha1**. - -Global IPsec Settings -===================== - -.. cfgcmd:: set vpn ipsec interface <name> - - Interface name to restrict outbound IPsec policies. There is a possibility - to specify multiple interfaces. If an interfaces are not specified, IPsec - policies apply to all interfaces. - - -.. cfgcmd:: set vpn ipsec log level <number> - - Level of logging. Default value is **0**. - -.. cfgcmd:: set vpn ipsec log subsystem <name> - - Subsystem of the daemon. - -Options -======= - -.. cfgcmd:: set vpn ipsec options disable-route-autoinstall - - Do not automatically install routes to remote - networks. - -.. cfgcmd:: set vpn ipsec options flexvpn - - Allows FlexVPN vendor ID payload (IKEv2 only). Send the Cisco - FlexVPN vendor ID payload (IKEv2 only), which is required in order to make - Cisco brand devices allow negotiating a local traffic selector (from - strongSwan's point of view) that is not the assigned virtual IP address if - such an address is requested by strongSwan. Sending the Cisco FlexVPN - vendor ID prevents the peer from narrowing the initiator's local traffic - selector and allows it to e.g. negotiate a TS of 0.0.0.0/0 == 0.0.0.0/0 - instead. This has been tested with a "tunnel mode ipsec ipv4" Cisco - template but should also work for GRE encapsulation. - -.. cfgcmd:: set vpn ipsec options interface <name> - - Interface Name to use. The name of the interface on which - virtual IP addresses should be installed. If not specified the addresses - will be installed on the outbound interface. - -.. cfgcmd:: set vpn ipsec options virtual-ip - - Allows the installation of virtual-ip addresses. - -IKEv2 Retransmission -==================== - -If the peer does not respond on DPD packet, the router starts the -retransmission procedure. - -The following formula is used to calculate the timeout: - -.. code-block:: none - - relative timeout = timeout * base ^ (attempts-1) - -.. cfgcmd:: set vpn ipsec options retransmission attempts - - Number of attempts before the peer is considered to be in the down state. - Default value is **5**. - -.. cfgcmd:: set vpn ipsec options retransmission base - - Base number of exponential backoff. Default value is **1.8**. - -.. cfgcmd:: set vpn ipsec options retransmission timeout - - Timeout in seconds before the first retransmission. Default value is **4**. - -Using the default values, packets are retransmitted as follows: - -+-----------+-------------+------------------+------------------+ -| Attempts | Formula | Relative timeout | Absolute timeout | -+-----------+-------------+------------------+------------------+ -| 1 | 4 * 1.8 ^ 0 | 4s | 4s | -+-----------+-------------+------------------+------------------+ -| 2 | 4 * 1.8 ^ 1 | 7s | 11s | -+-----------+-------------+------------------+------------------+ -| 3 | 4 * 1.8 ^ 2 | 13s | 24s | -+-----------+-------------+------------------+------------------+ -| 4 | 4 * 1.8 ^ 3 | 23s | 47s | -+-----------+-------------+------------------+------------------+ -| 5 | 4 * 1.8 ^ 4 | 42s | 89s | -+-----------+-------------+------------------+------------------+ -| peer down | 4 * 1.8 ^ 5 | 76s | 165s | -+-----------+-------------+------------------+------------------+ - - diff --git a/docs/configuration/vpn/ipsec/rst-remoteaccess_ipsec.rst b/docs/configuration/vpn/ipsec/rst-remoteaccess_ipsec.rst deleted file mode 100644 index 50499160..00000000 --- a/docs/configuration/vpn/ipsec/rst-remoteaccess_ipsec.rst +++ /dev/null @@ -1,187 +0,0 @@ -.. _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 -negotiation and authentication processes for IPsec security associations (SAs). -It is often known as IKEv2/IPSec or IPSec IKEv2 remote-access — or road-warriors -as others call it. - -Key exchange and payload encryption is done using IKE and ESP proposals as known -from IKEv1 but the connections are faster to establish, more reliable, and also -support roaming from IP to IP (called MOBIKE which makes sure your connection -does not drop when changing networks from e.g. WIFI to LTE and back). -Authentication can be achieved with X.509 certificates. - -Setting up certificates: -^^^^^^^^^^^^^^^^^^^^^^^^ -First of all, we need to create a CA root certificate and server certificate -on the server side. - -.. code-block:: none - - vyos@vpn.vyos.net# run generate pki ca install ca_root - Enter private key type: [rsa, dsa, ec] (Default: rsa) - Enter private key bits: (Default: 2048) - Enter country code: (Default: GB) - Enter state: (Default: Some-State) - Enter locality: (Default: Some-City) - Enter organization name: (Default: VyOS) - Enter common name: (Default: vyos.io) - Enter how many days certificate will be valid: (Default: 1825) - Note: If you plan to use the generated key on this router, do not encrypt the private key. - Do you want to encrypt the private key with a passphrase? [y/N] N - 2 value(s) installed. Use "compare" to see the pending changes, and "commit" to apply. - [edit] - - - vyos@vpn.vyos.net# comp - [pki ca] - + ca_root { - + certificate "MIIDnTCCAoWgAwI…." - + private { - + key "MIIEvAIBADANBgkqhkiG9….” - - vyos@vpn.vyos.net# run generate pki certificate sign ca_root install server_cert - Do you already have a certificate request? [y/N] N - Enter private key type: [rsa, dsa, ec] (Default: rsa) - Enter private key bits: (Default: 2048) - Enter country code: (Default: GB) - Enter state: (Default: Some-State) - Enter locality: (Default: Some-City) - Enter organization name: (Default: VyOS) - Enter common name: (Default: vyos.io) vpn.vyos.net - Do you want to configure Subject Alternative Names? [y/N] N - Enter how many days certificate will be valid: (Default: 365) - Enter certificate type: (client, server) (Default: server) - Note: If you plan to use the generated key on this router, do not encrypt the private key. - Do you want to encrypt the private key with a passphrase? [y/N] N - 2 value(s) installed. Use "compare" to see the pending changes, and "commit" to apply. - - vyos@vpn.vyos.net# comp - [pki certificate] - + server_cert { - + certificate "MIIDuzCCAqOgAwIBAgIUaSrCPWx………" - + private { - + key "MIIEvQIBADANBgkqhkiG9w0BAQEFAASCBK….." - + } - + } - - -Once the command is completed, it will add the certificate to the configuration -session, to the pki subtree. You can then review the proposed changes and -commit them. - -Setting up IPSec: -^^^^^^^^^^^^^^^^^ - -After the PKI certs are all set up we can start configuring our IPSec/IKE -proposals used for key-exchange end data encryption. The used encryption ciphers -and integrity algorithms vary from operating system to operating system. The -ones used in this example are validated to work on Windows 10. - -.. code-block:: none - - set vpn ipsec esp-group ESP-RW lifetime '3600' - set vpn ipsec esp-group ESP-RW pfs 'disable' - set vpn ipsec esp-group ESP-RW proposal 10 encryption 'aes128gcm128' - set vpn ipsec esp-group ESP-RW proposal 10 hash 'sha256' - - set vpn ipsec ike-group IKE-RW key-exchange 'ikev2' - set vpn ipsec ike-group IKE-RW lifetime '7200' - set vpn ipsec ike-group IKE-RW proposal 10 dh-group '14' - set vpn ipsec ike-group IKE-RW proposal 10 encryption 'aes128gcm128' - set vpn ipsec ike-group IKE-RW proposal 10 hash 'sha256' - -Every connection/remote-access pool we configure also needs a pool where we -can draw our client IP addresses from. We provide one IPv4 and IPv6 pool. -Authorized clients will receive an IPv4 address from the configured IPv4 prefix -and an IPv6 address from the IPv6 prefix. We can also send some DNS nameservers -down to our clients used on their connection. - -.. code-block:: none - - set vpn ipsec remote-access pool ra-rw-ipv4 name-server '192.0.2.1' - set vpn ipsec remote-access pool ra-rw-ipv4 prefix '192.0.2.128/25' - - set vpn ipsec remote-access pool ra-rw-ipv6 name-server '2001:db8:1000::1' - set vpn ipsec remote-access pool ra-rw-ipv6 prefix '2001:db8:2000::/64' - -Setting up tunnel: -^^^^^^^^^^^^^^^^^^ - -.. code-block:: none - - set vpn ipsec remote-access connection rw authentication local-id '192.0.2.1' - set vpn ipsec remote-access connection rw authentication server-mode 'x509' - set vpn ipsec remote-access connection rw authentication x509 ca-certificate 'ca_root' - set vpn ipsec remote-access connection rw authentication x509 certificate 'server_cert' - set vpn ipsec remote-access connection rw esp-group 'ESP-RW' - set vpn ipsec remote-access connection rw ike-group 'IKE-RW' - set vpn ipsec remote-access connection rw local-address '192.0.2.1' - set vpn ipsec remote-access connection rw pool 'ra-rw-ipv4' - set vpn ipsec remote-access connection rw pool 'ra-rw-ipv6' - -VyOS also supports two different modes of authentication, local and RADIUS. -To create a new local user named "vyos" with a password of "vyos" use the -following commands. - -.. code-block:: none - - set vpn ipsec remote-access connection rw authentication client-mode 'eap-mschapv2' - set vpn ipsec remote-access connection rw authentication local-users username vyos password 'vyos' - -Some client operating systems like to see the servers certificate. The following -option causes the server to voluntarily send its certificate, even if it wasn't -requested. - -.. code-block:: none - - set vpn ipsec remote-access connection rw authentication always-send-cert - -Client Configuration -^^^^^^^^^^^^^^^^^^^^ - -Most operating systems include native client support for IPsec IKEv2 VPN -connections, and others typically have an app or add-on package which adds the -capability. -This section covers IPsec IKEv2 client configuration for Windows 10. - -VyOS provides a command to generate a connection profile used by Windows clients -that will connect to the "rw" connection on our VyOS server. - -.. note:: Windows expects the server name to be also used in the server's - certificate common name, so it's best to use this DNS name for your VPN - connection. - -.. code-block:: none - - vyos@vpn.vyos.net:~$ generate ipsec profile windows-remote-access rw remote vpn.vyos.net - - - ==== <snip> ==== - Add-VpnConnection -Name "VyOS IKEv2 VPN" -ServerAddress "vpn.vyos.net" -TunnelType "Ikev2" - - Set-VpnConnectionIPsecConfiguration -ConnectionName "VyOS IKEv2 VPN" -AuthenticationTransformConstants GCMAES128 -CipherTransformConstants - GCMAES128 -EncryptionMethod GCMAES128 -IntegrityCheckMethod SHA256128 -PfsGroup None -DHGroup "Group14" -PassThru -Force - ==== </snip> ==== - -Add the commands from Snippet in the Windows side via PowerShell. -Also import the root CA cert to the Windows “Trusted Root Certification -Authorities” and establish the connection. - -Verification: -^^^^^^^^^^^^^ - -.. code-block:: none - - vyos@vpn.vyos.net:~$ show vpn ipsec remote-access summary - Connection ID Username Protocol State Uptime Tunnel IP Remote Host Remote ID IKE Proposal IPSec Proposal - --------------- ---------- ---------- ------- -------- ----------- ------------- ----------- ------------------------------------------ ------------------ - 5 vyos IKEv2 UP 37s 192.0.2.129 10.0.0.2 10.0.0.2 AES_GCM_16-128/PRF_HMAC_SHA2_256/MODP_2048 ESP:AES_GCM_16-128 diff --git a/docs/configuration/vpn/ipsec/rst-site2site_ipsec.rst b/docs/configuration/vpn/ipsec/rst-site2site_ipsec.rst deleted file mode 100644 index 9f8231e7..00000000 --- a/docs/configuration/vpn/ipsec/rst-site2site_ipsec.rst +++ /dev/null @@ -1,763 +0,0 @@ -.. _size2site_ipsec: - -###################### -IPsec Site-to-Site VPN -###################### - -**************************** -IPsec Site-to-Site VPN Types -**************************** - -VyOS supports two types of IPsec VPN: Policy-based IPsec VPN and Route-based -IPsec VPN. - -Policy-based VPN -================ - -Policy-based VPN is based on static configured policies. Each policy creates -individual IPSec SA. Traffic matches these SAs encrypted and directed to the -remote peer. - -Route-Based VPN -=============== - -Route-based VPN is based on secure traffic passing over Virtual Tunnel -Interfaces (VTIs). This type of IPsec VPNs allows using routing protocols. - -****************************** -Configuration Site-to-Site VPN -****************************** - -Requirements and Prerequisites for Site-to-Site VPN -=================================================== - -**Negotiated parameters that need to match** - -Phase 1 - * IKE version - * Authentication - * Encryption - * Hashing - * PRF - * Lifetime - - .. note:: Strongswan recommends to use the same lifetime value on both peers - -Phase 2 - * Encryption - * Hashing - * PFS - * Mode (tunnel or transport) - * Lifetime - - .. note:: Strongswan recommends to use the same lifetime value on both peers - - * Remote and Local networks in SA must be compatible on both peers - -Configuration Steps for Site-to-Site VPN -======================================== - -The next example shows the configuration one of the router participating in -IPsec VPN. - -Tunnel information: - * Phase 1: - * encryption: AES256 - * hash: SHA256 - * PRF: SHA256 - * DH: 14 - * lifetime: 28800 - * Phase 2: - * IPsec mode: tunnel - * encryption: AES256 - * hash: SHA256 - * PFS: inherited from DH Phase 1 - * lifetime: 3600 - * If Policy based VPN is used - * Remote network is 192.168.50.0/24. Local network is 192.168.10.0/24 - * If Route based VPN is used - * IP of the VTI interface is 10.0.0.1/30 - -.. note:: We do not recommend using policy-based vpn and route-based - vpn configurations to the same peer. - -**1. Configure ike-group (IKE Phase 1)** - -.. code-block:: none - - set vpn ipsec ike-group IKE close-action 'start' - set vpn ipsec ike-group IKE key-exchange 'ikev1' - set vpn ipsec ike-group IKE lifetime '28800' - set vpn ipsec ike-group IKE proposal 10 dh-group '14' - set vpn ipsec ike-group IKE proposal 10 encryption 'aes256' - set vpn ipsec ike-group IKE proposal 10 hash 'sha256' - set vpn ipsec ike-group IKE proposal 10 prf 'prfsha256' - -**2. Configure ESP-group (IKE Phase 2)** - -.. code-block:: none - - set vpn ipsec esp-group ESP lifetime '3600' - set vpn ipsec esp-group ESP mode 'tunnel' - set vpn ipsec esp-group ESP pfs 'enable' - set vpn ipsec esp-group ESP proposal 10 encryption 'aes256' - set vpn ipsec esp-group ESP proposal 10 hash 'sha256' - -**3. Specify interface facing to the protected destination.** - -.. code-block:: none - - set vpn ipsec interface eth0 - -**4. Configure PSK keys and authentication ids for this key if -authentication type is PSK** - -.. code-block:: none - - set vpn ipsec authentication psk PSK-KEY id '192.168.0.2' - set vpn ipsec authentication psk PSK-KEY id '192.168.5.2' - set vpn ipsec authentication psk PSK-KEY secret 'vyos' - -To set base64 secret encode plaintext password to base64 and set secret-type - -.. code-block:: none - - echo -n "vyos" | base64 - dnlvcw== - -.. code-block:: none - - set vpn ipsec authentication psk PSK-KEY secret 'dnlvcw==' - set vpn ipsec authentication psk PSK-KEY secret-type base64 - - -**5. Configure peer and apply IKE-group and esp-group to peer.** - -.. code-block:: none - - set vpn ipsec site-to-site peer PEER1 authentication local-id '192.168.0.2' - set vpn ipsec site-to-site peer PEER1 authentication mode 'pre-shared-secret' - set vpn ipsec site-to-site peer PEER1 authentication remote-id '192.168.5.2' - set vpn ipsec site-to-site peer PEER1 connection-type 'initiate' - set vpn ipsec site-to-site peer PEER1 default-esp-group 'ESP' - set vpn ipsec site-to-site peer PEER1 ike-group 'IKE' - set vpn ipsec site-to-site peer PEER1 local-address '192.168.0.2' - set vpn ipsec site-to-site peer PEER1 remote-address '192.168.5.2' - - Peer selects the key from step 4 according to local-id/remote-id pair. - -**6. Depends to vpn type (route-based vpn or policy-based vpn).** - - **6.1 For Policy-based VPN configure SAs using tunnel command - specifying remote and local networks.** - - .. code-block:: none - - set vpn ipsec site-to-site peer PEER1 tunnel 1 local prefix '192.168.10.0/24' - set vpn ipsec site-to-site peer PEER1 tunnel 1 remote prefix '192.168.50.0/24' - - **6.2 For Route-based VPN create VTI interface, set IP address to - this interface and bind this interface to the vpn peer.** - - .. code-block:: none - - set interfaces vti vti1 address 10.0.0.1/30 - set vpn ipsec site-to-site peer PEER1 vti bind vti1 - set vpn ipsec options disable-route-autoinstall - - Create routing between local networks via VTI interface using dynamic or - static routing. - - .. code-block:: none - - set protocol static route 192.168.50.0/24 next-hop 10.0.0.2 - -Initiator and Responder Connection Types -======================================== - -In Site-to-Site IPsec VPN it is recommended that one peer should be an -initiator and the other - the responder. The initiator actively establishes -the VPN tunnel. The responder passively waits for the remote peer to -establish the VPN tunnel. Depends on selected role it is recommended -select proper values for close-action and DPD action. - -The result of wrong value selection can be unstable work of the VPN. - * Duplicate CHILD SA creation. - * None of the VPN sides initiates the tunnel establishment. - -Below flow-chart could be a quick reference for the close-action -combination depending on how the peer is configured. - -.. figure:: /_static/images/IPSec_close_action_settings.* - -Similar combinations are applicable for the dead-peer-detection. - -Detailed Configuration Commands -=============================== - -PSK Key Authentication ----------------------- - -.. cfgcmd:: set vpn ipsec authentication psk <name> dhcp-interface - - ID for authentication generated from DHCP address - dynamically. - -.. cfgcmd:: set vpn ipsec authentication psk id <id> - - static ID's for authentication. In general local and remote - address ``<x.x.x.x>``, ``<h:h:h:h:h:h:h:h>`` or ``%any``. - -.. cfgcmd:: set vpn ipsec authentication psk secret <secret> - - A predefined shared secret used in configured mode - ``pre-shared-secret``. Base64-encoded secrets are allowed if - `secret-type base64` is configured. - -.. cfgcmd:: set vpn ipsec authentication psk secret-type <type> - - Specifies the secret type: - - * **plaintext** - Plain text type (default value). - * **base64** - Base64 type. - -Peer Configuration ------------------- - -Peer Authentication Commands -^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -.. cfgcmd:: set vpn ipsec site-to-site peer <name> authentication mode <mode> - - Mode for authentication between VyOS and remote peer: - - * **pre-shared-secret** - Use predefined shared secret phrase. - * **rsa** - Use simple shared RSA key. - * **x509** - Use certificates infrastructure for authentication. - - -.. cfgcmd:: set vpn ipsec site-to-site peer <name> authentication local-id <id> - - ID for the local VyOS router. If defined, during the authentication - it will be send to remote peer. - -.. cfgcmd:: set vpn ipsec site-to-site peer <name> authentication remote-id <id> - - ID for remote peer, instead of using peer name or - address. Useful in case if the remote peer is behind NAT - or if ``mode x509`` is used. - -.. stop_vyoslinter - -.. cfgcmd:: set vpn ipsec site-to-site peer <name> authentication rsa local-key <key> - - Name of PKI key-pair with local private key. - -.. cfgcmd:: set vpn ipsec site-to-site peer <name> authentication rsa remote-key <key> - - Name of PKI key-pair with remote public key. - -.. cfgcmd:: set vpn ipsec site-to-site peer <name> authentication rsa passphrase <passphrase> - - Local private key passphrase. - -.. cfgcmd:: set vpn ipsec site-to-site peer <name> authentication use-x509-id <id> - - Use local ID from x509 certificate. Cannot be used when - ``id`` is defined. - -.. cfgcmd:: set vpn ipsec site-to-site peer <name> authentication x509 ca-certificate <name> - - Name of CA certificate in PKI configuration. Using for authenticating - remote peer in x509 mode. - -.. cfgcmd:: set vpn ipsec site-to-site peer <name> authentication x509 certificate <name> - - Name of certificate in PKI configuration, which will be used - for authenticating local router on remote peer. - -.. start_vyoslinter - -.. cfgcmd:: set vpn ipsec authentication x509 passphrase <passphrase> - - Private key passphrase, if needed. - -Global Peer Configuration Commands -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -.. cfgcmd:: set vpn ipsec site-to-site peer <name> connection-type <type> - - Operational mode defines how to handle this connection process. - - * **initiate** - does initial connection to remote peer immediately - after configuring and after boot. In this mode the connection will - not be restarted in case of disconnection, therefore should be used - only together with DPD or another session tracking methods. - - * **trap** - does not try to initiate a connection to a remote - peer immediately. Instead, it installs a trap policy that will - trigger IKE negotiation and establish the IPsec session when - matching traffic is sent from the local side. This can be useful - when there is no direct connectivity to the peer due to firewall - or NAT in the middle of the local and remote side. - - .. warning:: The ``trap`` mode is not needed in most environments - and can lead to connection confusion or unintended tunnel uptime - behavior if used incorrectly. Using this mode requires careful - coordination with parameters such as ``close-action`` and DPD. - For most deployments, use ``initiate`` and ``none`` as described below. - - * **none** - loads the connection only, which then can be manually - initiated or used as a responder configuration. - - .. note:: For most site-to-site VPNs, configure one peer - with ``connection-type initiate`` (active side) and the other peer - with ``connection-type none`` (passive side) to - ensure stable and predictable tunnel behavior. - When using ``connection-type initiate``, you must also configure - DPD or another session tracking method (such as ``close-action``) - to automatically re-establish the tunnel after a disconnection. - Otherwise, the tunnel will not reconnect automatically if it goes down. - -.. cfgcmd:: set vpn ipsec site-to-site peer <name> default-esp-group <name> - - Name of ESP group to use by default for traffic encryption. - Might be overwritten by individual settings for tunnel or VTI - interface binding. - -.. cfgcmd:: set vpn ipsec site-to-site peer <name> description <description> - - Description for this peer. - -.. cfgcmd:: set vpn ipsec site-to-site peer <name> dhcp-interface <interface> - - Specify the interface which IP address, received from DHCP for IPSec - connection with this peer, will be used as ``local-address``. - -.. cfgcmd:: set vpn ipsec site-to-site peer <name> force-udp-encapsulation - - Force encapsulation of ESP into UDP datagrams. Useful in case if - between local and remote side is firewall or NAT, which not - allows passing plain ESP packets between them. - -.. cfgcmd:: set vpn ipsec site-to-site peer <name> ike-group <name> - - Name of IKE group to use for key exchanges. - -.. cfgcmd:: set vpn ipsec site-to-site peer <name> local-address <address> - - Local IP address for IPsec connection with this peer. - If defined ``any``, then an IP address which configured on interface with - default route will be used. - -.. cfgcmd:: set vpn ipsec site-to-site peer <name> remote-address <address> - - Remote IP address or hostname for IPsec connection. IPv4 or IPv6 - address is used when a peer has a public static IP address. Hostname - is a DNS name which could be used when a peer has a public IP - address and DNS name, but an IP address could be changed from time - to time. - -.. cfgcmd:: set vpn ipsec site-to-site peer <name> replay-window <size> - - IPsec replay window to configure for CHILD_SAs - (default: 32), a value of 0 disables IPsec replay protection. - -.. cfgcmd:: set vpn ipsec site-to-site peer <name> virtual-address <address> - - Defines a virtual IP address which is requested by the initiator and - one or several IPv4 and/or IPv6 addresses are assigned from multiple - pools by the responder. The wildcard addresses 0.0.0.0 and :: - request an arbitrary address, specific addresses may be defined. - -CHILD SAs Configuration Commands -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -Policy-Based CHILD SAs Configuration Commands -""""""""""""""""""""""""""""""""""""""""""""" - -Every configured tunnel under peer configuration is a new CHILD SA. - -.. stop_vyoslinter - -.. cfgcmd:: set vpn ipsec site-to-site peer <name> tunnel <number> disable - - Disable this tunnel. - -.. cfgcmd:: set vpn ipsec site-to-site peer <name> tunnel <number> esp-group <name> - - Specify ESP group for this CHILD SA. - -.. cfgcmd:: set vpn ipsec site-to-site peer <name> tunnel <number> priority <number> - - Priority for policy-based IPsec VPN tunnels (lowest value more - preferable). - -.. cfgcmd:: set vpn ipsec site-to-site peer <name> tunnel <number> protocol <name> - - Define the protocol for match traffic, which should be encrypted and - send to this peer. - -.. cfgcmd:: set vpn ipsec site-to-site peer <name> tunnel <number> local prefix <network> - - IP network at the local side. - -.. cfgcmd:: set vpn ipsec site-to-site peer <name> tunnel <number> local port <number> - - Local port number. Have effect only when used together with - ``prefix``. - -.. cfgcmd:: set vpn ipsec site-to-site peer <name> tunnel <number> remote prefix <network> - - IP network at the remote side. - -.. cfgcmd:: set vpn ipsec site-to-site peer <name> tunnel <number> remote port <number> - - Remote port number. Have effect only when used together with - ``prefix``. - -.. start_vyoslinter - -Route-Based CHILD SAs Configuration Commands -""""""""""""""""""""""""""""""""""""""""""""" - -To configure route-based VPN it is enough to create vti interface and -bind it to the peer. Any traffic, which will be send to VTI interface -will be encrypted and send to this peer. Using VTI makes IPsec -configuration much flexible and easier in complex situation, and -allows to dynamically add/delete remote networks, reachable via a -peer, as in this mode router don't need to create additional SA/policy -for each remote network. - -.. warning:: When using site-to-site IPsec with VTI interfaces, - be sure to disable route autoinstall. - -.. code-block:: none - - set vpn ipsec options disable-route-autoinstall - -.. cfgcmd:: set vpn ipsec site-to-site peer <name> vti bind <interface> - - VTI interface to bind to this peer. - -.. cfgcmd:: set vpn ipsec site-to-site peer <name> vti esp-group <name> - - ESP group for encrypt traffic, passed this VTI interface. - -Traffic-selectors parameters for traffic that should pass via vti -interface. - -.. stop_vyoslinter - -.. cfgcmd:: set vpn ipsec site-to-site peer <name> vti traffic-selector local prefix <network> - - Local prefix for interesting traffic. - -.. cfgcmd:: set vpn ipsec site-to-site peer <name> vti traffic-selector remote prefix <network> - - Remote prefix for interesting traffic. - -.. start_vyoslinter - -IPsec Op-mode Commands -====================== - -.. opcmd:: show vpn ike sa - - Shows active IKE SAs information. - -.. opcmd:: show vpn ike secrets - - Shows configured authentication keys. - -.. opcmd:: show vpn ike status - - Shows Strongswan daemon status. - -.. opcmd:: show vpn ipsec connections - - Shows summary status of all configured IKE and IPsec SAs. - -.. opcmd:: show vpn ipsec sa [detail] - - Shows active IPsec SAs information. - -.. opcmd:: show vpn ipsec status - - Shows status of IPsec process. - -.. opcmd:: show vpn ipsec policy - - Shows the in-kernel crypto policies. - -.. opcmd:: show vpn ipsec state - - Shows the in-kernel crypto state. - -.. opcmd:: show log ipsec - - Shows IPsec logs. - -.. opcmd:: reset vpn ipsec site-to-site all - - Clear all ipsec connection and reinitiate them if VyOS is configured - as initiator. - -.. opcmd:: reset vpn ipsec site-to-site peer <name> - - Clear all peer IKE SAs with IPsec SAs and reinitiate them if VyOS is - configured as initiator. - -.. opcmd:: reset vpn ipsec site-to-site peer <name> tunnel <number> - - Clear scpecific IPsec SA and reinitiate it if VyOS is configured as - initiator. - -.. opcmd:: reset vpn ipsec site-to-site peer <name> vti <number> - - Clear IPsec SA which is map to vti interface of this peer and - reinitiate it if VyOS is configured as initiator. - -.. opcmd:: restart ipsec - - Restart Strongswan daemon. - -********* -Examples: -********* - -Policy-Based VPN Example -======================== - -**PEER1:** - -* WAN interface on `eth0` -* `eth0` interface IP: `10.0.1.2/30` -* `dum0` interface IP: `192.168.0.1/24` (for testing purposes) -* Initiator - -**PEER2:** - -* WAN interface on `eth0` -* `eth0` interface IP: `10.0.2.2/30` -* `dum0` interface IP: `192.168.1.0/24` (for testing purposes) -* Responder - -.. code-block:: none - - # PEER1 - set interfaces dummy dum0 address '192.168.0.1/32' - set interfaces ethernet eth0 address '10.0.1.2/30' - set protocols static route 0.0.0.0/0 next-hop 10.0.1.1 - set vpn ipsec authentication psk AUTH-PSK id '10.0.1.2' - set vpn ipsec authentication psk AUTH-PSK id '10.0.2.2' - set vpn ipsec authentication psk AUTH-PSK secret 'test' - set vpn ipsec esp-group ESP-GRPOUP lifetime '3600' - set vpn ipsec esp-group ESP-GRPOUP proposal 10 encryption 'aes256' - set vpn ipsec esp-group ESP-GRPOUP proposal 10 hash 'sha1' - set vpn ipsec ike-group IKE-GROUP close-action 'start' - set vpn ipsec ike-group IKE-GROUP dead-peer-detection action 'restart' - set vpn ipsec ike-group IKE-GROUP dead-peer-detection interval '30' - set vpn ipsec ike-group IKE-GROUP dead-peer-detection timeout '120' - set vpn ipsec ike-group IKE-GROUP key-exchange 'ikev1' - set vpn ipsec ike-group IKE-GROUP lifetime '28800' - set vpn ipsec ike-group IKE-GROUP proposal 10 dh-group '14' - set vpn ipsec ike-group IKE-GROUP proposal 10 encryption 'aes256' - set vpn ipsec ike-group IKE-GROUP proposal 10 hash 'sha1' - set vpn ipsec interface 'eth0' - set vpn ipsec site-to-site peer PEER2 authentication local-id '10.0.1.2' - set vpn ipsec site-to-site peer PEER2 authentication mode 'pre-shared-secret' - set vpn ipsec site-to-site peer PEER2 authentication remote-id '10.0.2.2' - set vpn ipsec site-to-site peer PEER2 connection-type 'initiate' - set vpn ipsec site-to-site peer PEER2 default-esp-group 'ESP-GRPOUP' - set vpn ipsec site-to-site peer PEER2 ike-group 'IKE-GROUP' - set vpn ipsec site-to-site peer PEER2 local-address '10.0.1.2' - set vpn ipsec site-to-site peer PEER2 remote-address '10.0.2.2' - set vpn ipsec site-to-site peer PEER2 tunnel 0 local prefix '192.168.0.0/24' - set vpn ipsec site-to-site peer PEER2 tunnel 0 remote prefix '192.168.1.0/24' - - - # PEER2 - set interfaces dummy dum0 address '192.168.1.1/32' - set interfaces ethernet eth0 address '10.0.2.2/30' - set protocols static route 0.0.0.0/0 next-hop 10.0.2.1 - set vpn ipsec authentication psk AUTH-PSK id '10.0.1.2' - set vpn ipsec authentication psk AUTH-PSK id '10.0.2.2' - set vpn ipsec authentication psk AUTH-PSK secret 'test' - set vpn ipsec esp-group ESP-GRPOUP lifetime '3600' - set vpn ipsec esp-group ESP-GRPOUP proposal 10 encryption 'aes256' - set vpn ipsec esp-group ESP-GRPOUP proposal 10 hash 'sha1' - set vpn ipsec ike-group IKE-GROUP close-action 'none' - set vpn ipsec ike-group IKE-GROUP dead-peer-detection action 'clear' - set vpn ipsec ike-group IKE-GROUP dead-peer-detection interval '30' - set vpn ipsec ike-group IKE-GROUP dead-peer-detection timeout '120' - set vpn ipsec ike-group IKE-GROUP key-exchange 'ikev1' - set vpn ipsec ike-group IKE-GROUP lifetime '28800' - set vpn ipsec ike-group IKE-GROUP proposal 10 dh-group '14' - set vpn ipsec ike-group IKE-GROUP proposal 10 encryption 'aes256' - set vpn ipsec ike-group IKE-GROUP proposal 10 hash 'sha1' - set vpn ipsec interface 'eth0' - set vpn ipsec site-to-site peer PEER1 authentication local-id '10.0.2.2' - set vpn ipsec site-to-site peer PEER1 authentication mode 'pre-shared-secret' - set vpn ipsec site-to-site peer PEER1 authentication remote-id '10.0.1.2' - set vpn ipsec site-to-site peer PEER1 connection-type 'none' - set vpn ipsec site-to-site peer PEER1 default-esp-group 'ESP-GRPOUP' - set vpn ipsec site-to-site peer PEER1 ike-group 'IKE-GROUP' - set vpn ipsec site-to-site peer PEER1 local-address '10.0.2.2' - set vpn ipsec site-to-site peer PEER1 remote-address '10.0.1.2' - set vpn ipsec site-to-site peer PEER1 tunnel 0 local prefix '192.168.1.0/24' - set vpn ipsec site-to-site peer PEER1 tunnel 0 remote prefix '192.168.0.0/24' - - -Show status of policy-based IPsec VPN setup: - -.. code-block:: none - - vyos@PEER2:~$ show vpn ike sa - Peer ID / IP Local ID / IP - ------------ ------------- - 10.0.1.2 10.0.1.2 10.0.2.2 10.0.2.2 - - State IKEVer Encrypt Hash D-H Group NAT-T A-Time L-Time - ----- ------ ------- ---- --------- ----- ------ ------ - up IKEv1 AES_CBC_256 HMAC_SHA1_96 MODP_2048 no 1254 25633 - - - vyos@srv-gw0:~$ show vpn ipsec sa - Connection State Uptime Bytes In/Out Packets In/Out Remote address Remote ID Proposal - -------------- ------- -------- -------------- ---------------- ---------------- ----------- ---------------------------------- - PEER1-tunnel-0 up 20m42s 0B/0B 0/0 10.0.1.2 10.0.1.2 AES_CBC_256/HMAC_SHA1_96/MODP_2048 - - vyos@PEER2:~$ show vpn ipsec connections - Connection State Type Remote address Local TS Remote TS Local id Remote id Proposal - -------------- ------- ------ ---------------- -------------- -------------- ---------- ----------- ---------------------------------- - PEER1 up IKEv1 10.0.1.2 - - 10.0.2.2 10.0.1.2 AES_CBC/256/HMAC_SHA1_96/MODP_2048 - PEER1-tunnel-0 up IPsec 10.0.1.2 192.168.1.0/24 192.168.0.0/24 10.0.2.2 10.0.1.2 AES_CBC/256/HMAC_SHA1_96/MODP_2048 - -If there is SNAT rules on eth0, need to add exclude rule - -.. code-block:: none - - # PEER1 side - set nat source rule 10 destination address '192.168.1.0/24' - set nat source rule 10 'exclude' - set nat source rule 10 outbound-interface name 'eth0' - set nat source rule 10 source address '192.168.0.0/24' - - # PEER2 side - set nat source rule 10 destination address '192.168.0.0/24' - set nat source rule 10 'exclude' - set nat source rule 10 outbound-interface name 'eth0' - set nat source rule 10 source address '192.168.1.0/24' - - -Route-Based VPN Example -======================= - -**PEER1:** - -* WAN interface on `eth0` -* `eth0` interface IP: `10.0.1.2/30` -* 'vti0' interface IP: `10.100.100.1/30` -* `dum0` interface IP: `192.168.0.1/24` (for testing purposes) -* Role: Initiator - -**PEER2:** - -* WAN interface on `eth0` -* `eth0` interface IP: `10.0.2.2/30` -* 'vti0' interface IP: `10.100.100.2/30` -* `dum0` interface IP: `192.168.1.0/24` (for testing purposes) -* Role: Responder - -.. code-block:: none - - # PEER1 - set interfaces dummy dum0 address '192.168.0.1/32' - set interfaces ethernet eth0 address '10.0.1.2/30' - set interfaces vti vti0 address '10.100.100.1/30' - set protocols static route 0.0.0.0/0 next-hop 10.0.1.1 - set protocols static route 192.168.1.0/24 next-hop 10.100.100.2 - set vpn ipsec authentication psk AUTH-PSK id '10.0.1.2' - set vpn ipsec authentication psk AUTH-PSK id '10.0.2.2' - set vpn ipsec authentication psk AUTH-PSK secret 'test' - set vpn ipsec esp-group ESP-GRPOUP lifetime '3600' - set vpn ipsec esp-group ESP-GRPOUP proposal 10 encryption 'aes256' - set vpn ipsec esp-group ESP-GRPOUP proposal 10 hash 'sha1' - set vpn ipsec ike-group IKE-GROUP close-action 'start' - set vpn ipsec ike-group IKE-GROUP dead-peer-detection action 'restart' - set vpn ipsec ike-group IKE-GROUP dead-peer-detection interval '30' - set vpn ipsec ike-group IKE-GROUP key-exchange 'ikev2' - set vpn ipsec ike-group IKE-GROUP lifetime '28800' - set vpn ipsec ike-group IKE-GROUP proposal 10 dh-group '14' - set vpn ipsec ike-group IKE-GROUP proposal 10 encryption 'aes256' - set vpn ipsec ike-group IKE-GROUP proposal 10 hash 'sha1' - set vpn ipsec interface 'eth0' - set vpn ipsec options disable-route-autoinstall - set vpn ipsec site-to-site peer PEER2 authentication local-id '10.0.1.2' - set vpn ipsec site-to-site peer PEER2 authentication mode 'pre-shared-secret' - set vpn ipsec site-to-site peer PEER2 authentication remote-id '10.0.2.2' - set vpn ipsec site-to-site peer PEER2 connection-type 'initiate' - set vpn ipsec site-to-site peer PEER2 default-esp-group 'ESP-GRPOUP' - set vpn ipsec site-to-site peer PEER2 ike-group 'IKE-GROUP' - set vpn ipsec site-to-site peer PEER2 local-address '10.0.1.2' - set vpn ipsec site-to-site peer PEER2 remote-address '10.0.2.2' - set vpn ipsec site-to-site peer PEER2 vti bind 'vti0' - - - # PEER2 - set interfaces dummy dum0 address '192.168.1.1/32' - set interfaces ethernet eth0 address '10.0.2.2/30' - set interfaces vti vti0 address '10.100.100.2/30' - set protocols static route 0.0.0.0/0 next-hop 10.0.2.1 - set protocols static route 192.168.0.0/24 next-hop 10.100.100.1 - set vpn ipsec authentication psk AUTH-PSK id '10.0.1.2' - set vpn ipsec authentication psk AUTH-PSK id '10.0.2.2' - set vpn ipsec authentication psk AUTH-PSK secret 'test' - set vpn ipsec esp-group ESP-GRPOUP lifetime '3600' - set vpn ipsec esp-group ESP-GRPOUP proposal 10 encryption 'aes256' - set vpn ipsec esp-group ESP-GRPOUP proposal 10 hash 'sha1' - set vpn ipsec ike-group IKE-GROUP close-action 'none' - set vpn ipsec ike-group IKE-GROUP dead-peer-detection action 'clear' - set vpn ipsec ike-group IKE-GROUP dead-peer-detection interval '30' - set vpn ipsec ike-group IKE-GROUP key-exchange 'ikev2' - set vpn ipsec ike-group IKE-GROUP lifetime '28800' - set vpn ipsec ike-group IKE-GROUP proposal 10 dh-group '14' - set vpn ipsec ike-group IKE-GROUP proposal 10 encryption 'aes256' - set vpn ipsec ike-group IKE-GROUP proposal 10 hash 'sha1' - set vpn ipsec interface 'eth0' - set vpn ipsec options disable-route-autoinstall - set vpn ipsec site-to-site peer PEER1 authentication local-id '10.0.2.2' - set vpn ipsec site-to-site peer PEER1 authentication mode 'pre-shared-secret' - set vpn ipsec site-to-site peer PEER1 authentication remote-id '10.0.1.2' - set vpn ipsec site-to-site peer PEER1 connection-type 'none' - set vpn ipsec site-to-site peer PEER1 default-esp-group 'ESP-GRPOUP' - set vpn ipsec site-to-site peer PEER1 ike-group 'IKE-GROUP' - set vpn ipsec site-to-site peer PEER1 local-address '10.0.2.2' - set vpn ipsec site-to-site peer PEER1 remote-address '10.0.1.2' - set vpn ipsec site-to-site peer PEER1 vti bind 'vti0' - -Show status of route-based IPsec VPN setup: - -.. code-block:: none - - vyos@PEER2:~$ show vpn ike sa - Peer ID / IP Local ID / IP - ------------ ------------- - 10.0.1.2 10.0.1.2 10.0.2.2 10.0.2.2 - - State IKEVer Encrypt Hash D-H Group NAT-T A-Time L-Time - ----- ------ ------- ---- --------- ----- ------ ------ - up IKEv2 AES_CBC_256 HMAC_SHA1_96 MODP_2048 no 404 27650 - - vyos@PEER2:~$ show vpn ipsec sa - Connection State Uptime Bytes In/Out Packets In/Out Remote address Remote ID Proposal - ------------ ------- -------- -------------- ---------------- ---------------- ----------- ---------------------------------- - PEER1-vti up 3m28s 0B/0B 0/0 10.0.1.2 10.0.1.2 AES_CBC_256/HMAC_SHA1_96/MODP_2048 - - vyos@PEER2:~$ show vpn ipsec connections - Connection State Type Remote address Local TS Remote TS Local id Remote id Proposal - ------------ ------- ------ ---------------- ---------- ----------- ---------- ----------- ---------------------------------- - PEER1 up IKEv2 10.0.1.2 - - 10.0.2.2 10.0.1.2 AES_CBC/256/HMAC_SHA1_96/MODP_2048 - PEER1-vti up IPsec 10.0.1.2 0.0.0.0/0 0.0.0.0/0 10.0.2.2 10.0.1.2 AES_CBC/256/HMAC_SHA1_96/MODP_2048 - ::/0 ::/0 diff --git a/docs/configuration/vpn/ipsec/rst-troubleshooting_ipsec.rst b/docs/configuration/vpn/ipsec/rst-troubleshooting_ipsec.rst deleted file mode 100644 index f0f2e208..00000000 --- a/docs/configuration/vpn/ipsec/rst-troubleshooting_ipsec.rst +++ /dev/null @@ -1,330 +0,0 @@ -.. _troubleshooting_ipsec: - -###################################### -Troubleshooting Site-to-Site VPN IPsec -###################################### - -.. TODO:: Convert raw command blocks in this file to cfgcmd/opcmd - directives for command coverage tracking. - -************ -Introduction -************ - -This document describes the methodology to monitor and troubleshoot -Site-to-Site VPN IPsec. - -Steps for troubleshooting problems with Site-to-Site VPN IPsec: - 1. Ping the remote site through the tunnel using the source and - destination IPs included in the policy. - 2. Check connectivity between the routers using the ping command - (if ICMP traffic is allowed). - 3. Check the IKE SAs' statuses. - 4. Check the IPsec SAs' statuses. - 5. Check logs to view debug messages. - -********************** -Checking IKE SA Status -********************** - -The next command shows IKE SAs' statuses. - -.. stop_vyoslinter - -.. code-block:: none - - vyos@vyos:~$ show vpn ike sa - - Peer ID / IP Local ID / IP - ------------ ------------- - 192.168.1.2 192.168.1.2 192.168.0.1 192.168.0.1 - - State IKEVer Encrypt Hash D-H Group NAT-T A-Time L-Time - ----- ------ ------- ---- --------- ----- ------ ------ - up IKEv2 AES_CBC_128 HMAC_SHA1_96 MODP_2048 no 162 27023 - -This command shows the next information: - - IKE SA status. - - Selected IKE version. - - Selected Encryption, Hash and Diffie-Hellman Group. - - NAT-T. - - ID and IP of both peers. - - A-Time: established time, L-Time: time for next rekeying. - -************************** -IPsec SA (CHILD SA) Status -************************** - -The next commands show IPsec SAs' statuses. - -.. code-block:: none - - vyos@vyos:~$ show vpn ipsec sa - Connection State Uptime Bytes In/Out Packets In/Out Remote address Remote ID Proposal - ------------- ------- -------- -------------- ---------------- ---------------- ----------- ---------------------------------- - PEER-tunnel-1 up 16m30s 168B/168B 2/2 192.168.1.2 192.168.1.2 AES_CBC_128/HMAC_SHA1_96/MODP_2048 - -.. code-block:: none - - vyos@vyos:~$ show vpn ipsec sa detail - PEER: #1, ESTABLISHED, IKEv2, 101275ac719d5a1b_i* 68ea4ec3bed3bf0c_r - local '192.168.0.1' @ 192.168.0.1[4500] - remote '192.168.1.2' @ 192.168.1.2[4500] - AES_CBC-128/HMAC_SHA1_96/PRF_HMAC_SHA1/MODP_2048 - established 4054s ago, rekeying in 23131s - PEER-tunnel-1: #2, reqid 1, INSTALLED, TUNNEL, ESP:AES_CBC-128/HMAC_SHA1_96/MODP_2048 - installed 1065s ago, rekeying in 1998s, expires in 2535s - in c5821882, 168 bytes, 2 packets, 81s ago - out c433406a, 168 bytes, 2 packets, 81s ago - local 10.0.0.0/24 - remote 10.0.1.0/24 - -These commands show the next information: - - IPsec SA status. - - Uptime and time for the next rekeing. - - Amount of transferred data. - - Remote and local ID and IP. - - Selected Encryption, Hash and Diffie-Hellman Group. - - Mode (tunnel or transport). - - Remote and local prefixes which are use for policy. - -There is a possibility to view the summarized information of SAs' status - -.. code-block:: none - - vyos@vyos:~$ show vpn ipsec connections - Connection State Type Remote address Local TS Remote TS Local id Remote id Proposal - ------------- ------- ------ ---------------- ----------- ----------- ----------- ----------- ---------------------------------- - PEER up IKEv2 192.168.1.2 - - 192.168.0.1 192.168.1.2 AES_CBC/128/HMAC_SHA1_96/MODP_2048 - PEER-tunnel-1 up IPsec 192.168.1.2 10.0.0.0/24 10.0.1.0/24 192.168.0.1 192.168.1.2 AES_CBC/128/HMAC_SHA1_96/MODP_2048 - -************************** -Viewing Logs for Debugging -************************** - -If IKE SAs or IPsec SAs are down, need to debug IPsec connectivity -using logs ``show log ipsec`` - -The next example of the successful IPsec connection initialization. - -.. code-block:: none - - vyos@vyos:~$ show log ipsec - Jun 20 14:29:47 charon[2428]: 02[NET] <PEER|1> received packet: from 192.168.1.2[500] to 192.168.0.1[500] (472 bytes) - Jun 20 14:29:47 charon[2428]: 02[ENC] <PEER|1> parsed IKE_SA_INIT response 0 [ SA KE No N(NATD_S_IP) N(NATD_D_IP) N(FRAG_SUP) N(HASH_ALG) N(CHDLESS_SUP) N(MULT_AUTH) ] - Jun 20 14:29:47 charon-systemd[2428]: received packet: from 192.168.1.2[500] to 192.168.0.1[500] (472 bytes) - Jun 20 14:29:47 charon[2428]: 02[CFG] <PEER|1> selected proposal: IKE:AES_CBC_128/HMAC_SHA1_96/PRF_HMAC_SHA1/MODP_2048 - Jun 20 14:29:47 charon-systemd[2428]: parsed IKE_SA_INIT response 0 [ SA KE No N(NATD_S_IP) N(NATD_D_IP) N(FRAG_SUP) N(HASH_ALG) N(CHDLESS_SUP) N(MULT_AUTH) ] - Jun 20 14:29:47 charon-systemd[2428]: selected proposal: IKE:AES_CBC_128/HMAC_SHA1_96/PRF_HMAC_SHA1/MODP_2048 - Jun 20 14:29:47 charon[2428]: 02[IKE] <PEER|1> authentication of '192.168.0.1' (myself) with pre-shared key - Jun 20 14:29:47 charon-systemd[2428]: authentication of '192.168.0.1' (myself) with pre-shared key - Jun 20 14:29:47 charon[2428]: 02[IKE] <PEER|1> establishing CHILD_SA PEER-tunnel-1{1} - Jun 20 14:29:47 charon-systemd[2428]: establishing CHILD_SA PEER-tunnel-1{1} - Jun 20 14:29:47 charon[2428]: 02[ENC] <PEER|1> generating IKE_AUTH request 1 [ IDi N(INIT_CONTACT) IDr AUTH SA TSi TSr N(MOBIKE_SUP) N(NO_ADD_ADDR) N(MULT_AUTH) N(EAP_ONLY) N(MSG_ID_SYN_SUP) ] - Jun 20 14:29:47 charon-systemd[2428]: generating IKE_AUTH request 1 [ IDi N(INIT_CONTACT) IDr AUTH SA TSi TSr N(MOBIKE_SUP) N(NO_ADD_ADDR) N(MULT_AUTH) N(EAP_ONLY) N(MSG_ID_SYN_SUP) ] - Jun 20 14:29:47 charon[2428]: 02[NET] <PEER|1> sending packet: from 192.168.0.1[4500] to 192.168.1.2[4500] (268 bytes) - Jun 20 14:29:47 charon-systemd[2428]: sending packet: from 192.168.0.1[4500] to 192.168.1.2[4500] (268 bytes) - Jun 20 14:29:47 charon[2428]: 13[NET] <PEER|1> received packet: from 192.168.1.2[4500] to 192.168.0.1[4500] (220 bytes) - Jun 20 14:29:47 charon[2428]: 13[ENC] <PEER|1> parsed IKE_AUTH response 1 [ IDr AUTH SA TSi TSr N(MOBIKE_SUP) N(NO_ADD_ADDR) ] - Jun 20 14:29:47 charon-systemd[2428]: received packet: from 192.168.1.2[4500] to 192.168.0.1[4500] (220 bytes) - Jun 20 14:29:47 charon[2428]: 13[IKE] <PEER|1> authentication of '192.168.1.2' with pre-shared key successful - Jun 20 14:29:47 charon-systemd[2428]: parsed IKE_AUTH response 1 [ IDr AUTH SA TSi TSr N(MOBIKE_SUP) N(NO_ADD_ADDR) ] - Jun 20 14:29:47 charon[2428]: 13[IKE] <PEER|1> peer supports MOBIKE - Jun 20 14:29:47 charon-systemd[2428]: authentication of '192.168.1.2' with pre-shared key successful - Jun 20 14:29:47 charon[2428]: 13[IKE] <PEER|1> IKE_SA PEER[1] established between 192.168.0.1[192.168.0.1]...192.168.1.2[192.168.1.2] - Jun 20 14:29:47 charon-systemd[2428]: peer supports MOBIKE - Jun 20 14:29:47 charon[2428]: 13[IKE] <PEER|1> scheduling rekeying in 27703s - Jun 20 14:29:47 charon-systemd[2428]: IKE_SA PEER[1] established between 192.168.0.1[192.168.0.1]...192.168.1.2[192.168.1.2] - Jun 20 14:29:47 charon[2428]: 13[IKE] <PEER|1> maximum IKE_SA lifetime 30583s - Jun 20 14:29:47 charon-systemd[2428]: scheduling rekeying in 27703s - Jun 20 14:29:47 charon[2428]: 13[CFG] <PEER|1> selected proposal: ESP:AES_CBC_128/HMAC_SHA1_96/NO_EXT_SEQ - Jun 20 14:29:47 charon-systemd[2428]: maximum IKE_SA lifetime 30583s - Jun 20 14:29:47 charon-systemd[2428]: selected proposal: ESP:AES_CBC_128/HMAC_SHA1_96/NO_EXT_SEQ - Jun 20 14:29:47 charon[2428]: 13[IKE] <PEER|1> CHILD_SA PEER-tunnel-1{1} established with SPIs cb94fb3f_i ca99c8a9_o and TS 10.0.0.0/24 === 10.0.1.0/24 - Jun 20 14:29:47 charon-systemd[2428]: CHILD_SA PEER-tunnel-1{1} established with SPIs cb94fb3f_i ca99c8a9_o and TS 10.0.0.0/24 === 10.0.1.0/24 - -************************ -Troubleshooting Examples -************************ - -IKE PROPOSAL are Different -========================== - -In this situation, IKE SAs can be down or not active. - -.. code-block:: none - - vyos@vyos:~$ show vpn ike sa - -The problem is in IKE phase (Phase 1). The next step is checking debug logs. - -Responder Side: - -.. code-block:: none - - Jun 23 07:36:33 charon[2440]: 01[CFG] <1> received proposals: IKE:AES_CBC_256/HMAC_SHA1_96/PRF_HMAC_SHA1/MODP_2048 - Jun 23 07:36:33 charon-systemd[2440]: received proposals: IKE:AES_CBC_256/HMAC_SHA1_96/PRF_HMAC_SHA1/MODP_2048 - Jun 23 07:36:33 charon[2440]: 01[CFG] <1> configured proposals: IKE:AES_CBC_128/HMAC_SHA1_96/PRF_HMAC_SHA1/MODP_2048 - Jun 23 07:36:33 charon-systemd[2440]: configured proposals: IKE:AES_CBC_128/HMAC_SHA1_96/PRF_HMAC_SHA1/MODP_2048 - Jun 23 07:36:33 charon[2440]: 01[IKE] <1> received proposals unacceptable - Jun 23 07:36:33 charon-systemd[2440]: received proposals unacceptable - Jun 23 07:36:33 charon[2440]: 01[ENC] <1> generating IKE_SA_INIT response 0 [ N(NO_PROP) ] - -Initiator side: - -.. code-block:: none - - Jun 23 07:36:32 charon-systemd[2444]: parsed IKE_SA_INIT response 0 [ N(NO_PROP) ] - Jun 23 07:36:32 charon[2444]: 14[IKE] <PEER|1> received NO_PROPOSAL_CHOSEN notify error - Jun 23 07:36:32 charon-systemd[2444]: received NO_PROPOSAL_CHOSEN notify error - -The notification **NO_PROPOSAL_CHOSEN** means that the proposal mismatch. -On the Responder side there is concrete information where is mismatch. -Encryption **AES_CBC_128** is configured in IKE policy on the responder -but **AES_CBC_256** is configured on the initiator side. - -PSK Secret Mismatch -=================== - -In this situation, IKE SAs can be down or not active. - -.. code-block:: none - - vyos@vyos:~$ show vpn ike sa - -The problem is in IKE phase (Phase 1). The next step is checking debug logs. - -Responder: - -.. code-block:: none - - Jun 23 08:07:26 charon-systemd[2440]: tried 1 shared key for '192.168.1.2' - '192.168.0.1', but MAC mismatched - Jun 23 08:07:26 charon[2440]: 13[ENC] <PEER|3> generating IKE_AUTH response 1 [ N(AUTH_FAILED) ] - -Initiator side: - -.. code-block:: none - - Jun 23 08:07:24 charon[2436]: 12[ENC] <PEER|1> parsed IKE_AUTH response 1 [ N(AUTH_FAILED) ] - Jun 23 08:07:24 charon-systemd[2436]: parsed IKE_AUTH response 1 [ N(AUTH_FAILED) ] - Jun 23 08:07:24 charon[2436]: 12[IKE] <PEER|1> received AUTHENTICATION_FAILED notify error - Jun 23 08:07:24 charon-systemd[2436]: received AUTHENTICATION_FAILED notify error - -The notification **AUTHENTICATION_FAILED** means that the authentication -is failed. There is a reason to check PSK on both side. - -ESP Proposal Mismatch -===================== - -The output of **show** commands shows us that IKE SA is established but -IPSec SA is not. - -.. code-block:: none - - vyos@vyos:~$ show vpn ike sa - Peer ID / IP Local ID / IP - ------------ ------------- - 192.168.1.2 192.168.1.2 192.168.0.1 192.168.0.1 - - State IKEVer Encrypt Hash D-H Group NAT-T A-Time L-Time - ----- ------ ------- ---- --------- ----- ------ ------ - up IKEv2 AES_CBC_128 HMAC_SHA1_96 MODP_2048 no 158 26817 - -.. code-block:: none - - vyos@vyos:~$ show vpn ipsec sa - Connection State Uptime Bytes In/Out Packets In/Out Remote address Remote ID Proposal - ------------ ------- -------- -------------- ---------------- ---------------- ----------- ---------- - -The next step is checking debug logs. - -Initiator side: - -.. code-block:: none - - Jun 23 08:16:10 charon[3789]: 13[NET] <PEER|1> received packet: from 192.168.1.2[500] to 192.168.0.1[500] (472 bytes) - Jun 23 08:16:10 charon[3789]: 13[ENC] <PEER|1> parsed IKE_SA_INIT response 0 [ SA KE No N(NATD_S_IP) N(NATD_D_IP) N(FRAG_SUP) N(HASH_ALG) N(CHDLESS_SUP) N(MULT_AUTH) ] - Jun 23 08:16:10 charon-systemd[3789]: received packet: from 192.168.1.2[500] to 192.168.0.1[500] (472 bytes) - Jun 23 08:16:10 charon[3789]: 13[CFG] <PEER|1> selected proposal: IKE:AES_CBC_128/HMAC_SHA1_96/PRF_HMAC_SHA1/MODP_2048 - Jun 23 08:16:10 charon-systemd[3789]: parsed IKE_SA_INIT response 0 [ SA KE No N(NATD_S_IP) N(NATD_D_IP) N(FRAG_SUP) N(HASH_ALG) N(CHDLESS_SUP) N(MULT_AUTH) ] - Jun 23 08:16:10 charon-systemd[3789]: selected proposal: IKE:AES_CBC_128/HMAC_SHA1_96/PRF_HMAC_SHA1/MODP_2048 - Jun 23 08:16:10 charon[3789]: 13[IKE] <PEER|1> authentication of '192.168.0.1' (myself) with pre-shared key - Jun 23 08:16:10 charon-systemd[3789]: authentication of '192.168.0.1' (myself) with pre-shared key - Jun 23 08:16:10 charon[3789]: 13[IKE] <PEER|1> establishing CHILD_SA PEER-tunnel-1{1} - Jun 23 08:16:10 charon-systemd[3789]: establishing CHILD_SA PEER-tunnel-1{1} - Jun 23 08:16:10 charon[3789]: 13[ENC] <PEER|1> generating IKE_AUTH request 1 [ IDi N(INIT_CONTACT) IDr AUTH SA TSi TSr N(MOBIKE_SUP) N(NO_ADD_ADDR) N(MULT_AUTH) N(EAP_ONLY) N(MSG_ID_SYN_SUP) ] - Jun 23 08:16:10 charon-systemd[3789]: generating IKE_AUTH request 1 [ IDi N(INIT_CONTACT) IDr AUTH SA TSi TSr N(MOBIKE_SUP) N(NO_ADD_ADDR) N(MULT_AUTH) N(EAP_ONLY) N(MSG_ID_SYN_SUP) ] - Jun 23 08:16:10 charon[3789]: 13[NET] <PEER|1> sending packet: from 192.168.0.1[4500] to 192.168.1.2[4500] (268 bytes) - Jun 23 08:16:10 charon-systemd[3789]: sending packet: from 192.168.0.1[4500] to 192.168.1.2[4500] (268 bytes) - Jun 23 08:16:10 charon[3789]: 09[NET] <PEER|1> received packet: from 192.168.1.2[4500] to 192.168.0.1[4500] (140 bytes) - Jun 23 08:16:10 charon-systemd[3789]: received packet: from 192.168.1.2[4500] to 192.168.0.1[4500] (140 bytes) - Jun 23 08:16:10 charon[3789]: 09[ENC] <PEER|1> parsed IKE_AUTH response 1 [ IDr AUTH N(MOBIKE_SUP) N(NO_ADD_ADDR) N(NO_PROP) ] - Jun 23 08:16:10 charon-systemd[3789]: parsed IKE_AUTH response 1 [ IDr AUTH N(MOBIKE_SUP) N(NO_ADD_ADDR) N(NO_PROP) ] - Jun 23 08:16:10 charon[3789]: 09[IKE] <PEER|1> authentication of '192.168.1.2' with pre-shared key successful - Jun 23 08:16:10 charon-systemd[3789]: authentication of '192.168.1.2' with pre-shared key successful - Jun 23 08:16:10 charon[3789]: 09[IKE] <PEER|1> peer supports MOBIKE - Jun 23 08:16:10 charon-systemd[3789]: peer supports MOBIKE - Jun 23 08:16:10 charon[3789]: 09[IKE] <PEER|1> IKE_SA PEER[1] established between 192.168.0.1[192.168.0.1]...192.168.1.2[192.168.1.2] - Jun 23 08:16:10 charon-systemd[3789]: IKE_SA PEER[1] established between 192.168.0.1[192.168.0.1]...192.168.1.2[192.168.1.2] - Jun 23 08:16:10 charon[3789]: 09[IKE] <PEER|1> scheduling rekeying in 26975s - Jun 23 08:16:10 charon-systemd[3789]: scheduling rekeying in 26975s - Jun 23 08:16:10 charon[3789]: 09[IKE] <PEER|1> maximum IKE_SA lifetime 29855s - Jun 23 08:16:10 charon-systemd[3789]: maximum IKE_SA lifetime 29855s - Jun 23 08:16:10 charon[3789]: 09[IKE] <PEER|1> received NO_PROPOSAL_CHOSEN notify, no CHILD_SA built - Jun 23 08:16:10 charon-systemd[3789]: received NO_PROPOSAL_CHOSEN notify, no CHILD_SA built - Jun 23 08:16:10 charon[3789]: 09[IKE] <PEER|1> failed to establish CHILD_SA, keeping IKE_SA - Jun 23 08:16:10 charon-systemd[3789]: failed to establish CHILD_SA, keeping IKE_SA - -There are messages: **NO_PROPOSAL_CHOSEN** and -**failed to establish CHILD_SA** which refers that the problem is in -the IPsec(ESP) proposal mismatch. - -The reason of this problem is showed on the responder side. - -.. code-block:: none - - Jun 23 08:16:12 charon[2440]: 01[CFG] <PEER|5> received proposals: ESP:AES_CBC_256/HMAC_SHA1_96/NO_EXT_SEQ - Jun 23 08:16:12 charon-systemd[2440]: received proposals: ESP:AES_CBC_256/HMAC_SHA1_96/NO_EXT_SEQ - Jun 23 08:16:12 charon[2440]: 01[CFG] <PEER|5> configured proposals: ESP:AES_CBC_128/HMAC_SHA1_96/MODP_2048/NO_EXT_SEQ - Jun 23 08:16:12 charon-systemd[2440]: configured proposals: ESP:AES_CBC_128/HMAC_SHA1_96/MODP_2048/NO_EXT_SEQ - Jun 23 08:16:12 charon[2440]: 01[IKE] <PEER|5> no acceptable proposal found - Jun 23 08:16:12 charon-systemd[2440]: no acceptable proposal found - Jun 23 08:16:12 charon[2440]: 01[IKE] <PEER|5> failed to establish CHILD_SA, keeping IKE_SA - -Encryption **AES_CBC_128** is configured in IKE policy on the responder but **AES_CBC_256** -is configured on the initiator side. - -Prefixes in Policies Mismatch -============================= - -As in previous situation, IKE SA is in up state but IPsec SA is not up. -According to logs we can see **TS_UNACCEPTABLE** notification. It means -that prefixes (traffic selectors) mismatch on both sides - -Initiator: - -.. code-block:: none - - Jun 23 14:13:17 charon[4996]: 11[IKE] <PEER|1> received TS_UNACCEPTABLE notify, no CHILD_SA built - Jun 23 14:13:17 charon-systemd[4996]: maximum IKE_SA lifetime 29437s - Jun 23 14:13:17 charon[4996]: 11[IKE] <PEER|1> failed to establish CHILD_SA, keeping IKE_SA - Jun 23 14:13:17 charon-systemd[4996]: received TS_UNACCEPTABLE notify, no CHILD_SA built - Jun 23 14:13:17 charon-systemd[4996]: failed to establish CHILD_SA, keeping IKE_SA - -The reason of this problem is showed on the responder side. - -.. code-block:: none - - Jun 23 14:13:19 charon[2440]: 01[IKE] <PEER|7> traffic selectors 10.0.2.0/24 === 10.0.0.0/24 unacceptable - Jun 23 14:13:19 charon-systemd[2440]: traffic selectors 10.0.2.0/24 === 10.0.0.0/24 unacceptable - Jun 23 14:13:19 charon[2440]: 01[IKE] <PEER|7> failed to establish CHILD_SA, keeping IKE_SA - Jun 23 14:13:19 charon-systemd[2440]: failed to establish CHILD_SA, keeping IKE_SA - Jun 23 14:13:19 charon[2440]: 01[ENC] <PEER|7> generating IKE_AUTH response 1 [ IDr AUTH N(MOBIKE_SUP) N(NO_ADD_ADDR) N(TS_UNACCEPT) ] - Jun 23 14:13:19 charon-systemd[2440]: generating IKE_AUTH response 1 [ IDr AUTH N(MOBIKE_SUP) N(NO_ADD_ADDR) N(TS_UNACCEPT) ] - -.. 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/rst-dmvpn.rst b/docs/configuration/vpn/rst-dmvpn.rst deleted file mode 100644 index 30398a25..00000000 --- a/docs/configuration/vpn/rst-dmvpn.rst +++ /dev/null @@ -1,436 +0,0 @@ -.. _vpn-dmvpn: - -##### -DMVPN -##### - -:abbr:`DMVPN (Dynamic Multipoint Virtual Private Network)` is a dynamic -:abbr:`VPN (Virtual Private Network)` technology originally developed by Cisco. -While their implementation was somewhat proprietary, the underlying -technologies are actually standards based. The three technologies are: - -* :abbr:`NHRP (Next Hop Resolution Protocol)` :rfc:`2332` -* :abbr:`mGRE (Multipoint Generic Routing Encapsulation)` :rfc:`1702` -* :abbr:`IPSec (IP Security)` - too many RFCs to list, but start with - :rfc:`4301` - -NHRP provides the dynamic tunnel endpoint discovery mechanism (endpoint -registration, and endpoint discovery/lookup), mGRE provides the tunnel -encapsulation itself, and the IPSec protocols handle the key exchange, and -crypto mechanism. - -In short, DMVPN provides the capability for creating a dynamic-mesh VPN -network without having to pre-configure (static) all possible tunnel end-point -peers. - -.. note:: DMVPN only automates the tunnel endpoint discovery and setup. A - complete solution also incorporates the use of a routing protocol. BGP is - particularly well suited for use with DMVPN. - -.. figure:: /_static/images/vpn_dmvpn_topology01.* - :scale: 40 % - :alt: Baseline DMVPN topology - - Baseline DMVPN topology - -************* -Configuration -************* - -Tunnel interface configuration -============================== - -NHRP never handles routing of prefixes itself. You need to run some real routing -protocol (e.g. BGP) to advertise routes over the tunnels. What nhrpd does it -establishes ‘shortcut routes’ that optimizes the routing protocol to avoid going -through extra nodes in NBMA GRE mesh. - -NHRP does route NHRP domain addresses individually using per-host prefixes. -This is similar to Cisco FlexVPN, but in contrast to opennhrp which uses -a generic subnet route. - -To create NBMA GRE tunnel you might use the following: - -.. code-block:: none - - set interfaces tunnel tun100 address '10.0.0.1/32' - set interfaces tunnel tun100 enable-multicast - set interfaces tunnel tun100 encapsulation 'gre' - set interfaces tunnel tun100 ip adjust-mss '1360' - set interfaces tunnel tun100 mtu '1400' - set interfaces tunnel tun100 parameters ip key '42' - set interfaces tunnel tun100 source-interface 'eth0' - -* Please refer to the :ref:`tunnel-interface` documentation for the individual - tunnel related options. - - .. note:: The IP-address is assigned as host prefix to tunnel - interface. NHRP will automatically create additional host routes - pointing to tunnel interface when a connection with these hosts is - established. - -The tunnel interface subnet prefix should be announced by routing protocol -from the hub nodes (e.g. BGP ‘network’ announce). This allows the routing -protocol to decide which is the closest hub and determine the relay hub on -prefix basis when direct tunnel is not established. - -NHRP protocol configuration -============================== - -.. cfgcmd:: set protocols nhrp tunnel <tunnel> authentication <secret> - - Enables Cisco style authentication on NHRP packets. This embeds the - plaintext password to the outgoing NHRP packets. Maximum length of - the password is 8 characters. - -.. cfgcmd:: set protocols nhrp tunnel <tunnel> holdtime <timeout> - - Holdtime is the number of seconds that have to pass before stopping to - advertise an NHRP NBMA address as valid. It also controls how often NHRP - registration requests are sent. By default registrations are sent every - one third of the holdtime - -.. cfgcmd:: set protocols nhrp tunnel <tunnel> map tunnel-ip <tunnel-ip> - nbma <nbma-ip> - - * **tunnel-ip** - Tunnel ip address in format **x.x.x.x**. - * **nbma-ip** - NBMA ip address in format **x.x.x.x** or **local** - - Map an IP address of a station to the station’s NBMA address. - -.. cfgcmd:: set protocols nhrp tunnel <tunnel> mtu <mtu> - - Configure NHRP advertised MTU. - -.. cfgcmd:: set protocols nhrp tunnel <tunnel> multicast <nbma-ip> - - * **nbma-ip** - NBMA ip address in format **x.x.x.x** or **dynamic** - - Sends multicast packets to the specified NBMA address. If dynamic is specified - then destination NBMA address (or addresses) are learnt dynamically. - -.. cfgcmd:: set protocols nhrp tunnel <tunnel> network-id <network-id> - - * **network-id** - NHRP network id <1-4294967295> - - Enable NHRP on this interface and set the interface’s network ID. - The network ID is used to allow creating multiple nhrp domains on a - router when multiple interfaces are configured on the router. - Interfaces configured with the same ID are part of the same logical - NBMA network. The ID is a local only parameter and is not sent to - other NHRP nodes and so IDs on different nodes do not need to match. - When NHRP packets are received on an interface they are assigned to - the local NHRP domain for that interface. - -.. stop_vyoslinter - -.. cfgcmd:: set protocols nhrp tunnel <tunnel> nhs tunnel-ip <tunnel-ip> nbma <nbma-ip> - - * **tunnel-ip** - Tunnel ip address in format **x.x.x.x** or **dynamic** - * **nbma-ip** - NBMA ip address in format **x.x.x.x** - - Configure the Next Hop Server address and its NBMA address. If - dynamic is specified then Next Hop Server can have dynamic address - which maps to its NBMA address. - -.. start_vyoslinter - -.. cfgcmd:: set protocols nhrp tunnel <tunnel> redirect - - This enable redirect replies on the NHS similar to ICMP redirects - except this is managed by the nhrp protocol. This setting allows - spokes to communicate with each others directly. - -.. cfgcmd:: set protocols nhrp tunnel <tunnel> registration-no-unique - - Allow the client to not set the unique flag in the NHRP packets. - This is useful when a station has a dynamic IP address that could - change over time. - -.. cfgcmd:: set protocols nhrp tunnel <tunnel> shortcut - - Enable shortcut (spoke-to-spoke) tunnels to allow NHC to talk to - each others directly after establishing a connection without going - through the hub. - -IPSEC configuration -============================== - -* Please refer to the :ref:`ipsec_general` documentation for the - individual IPSec related options. - -.. note:: NHRP daemon based on FRR nhrpd. It controls IPSEC. That's - why 'close-action' parameter in IKE configuration always is set to - 'close' and 'dead-peer-detection action' always is set to 'clear'. - -.. stop_vyoslinter - -.. cfgcmd:: set vpn ipsec profile <profile-name> authentication mode pre-shared-secret - - Set preshared secret mode authentication - -.. cfgcmd:: set vpn ipsec profile <profile-name> authentication pre-shared-secret <secret> - - Set preshared secret - -.. start_vyoslinter - -.. cfgcmd:: set vpn ipsec profile <profile-name> bind tunnel <tunnel name> - - Bind IPSEC profile to the specific tunnel interface. - -.. cfgcmd:: set vpn ipsec profile <profile-name> esp-group 'ESP-HUB' - - Map ESP group to IPSEC profile - -.. cfgcmd:: set vpn ipsec profile <profile-name> ike-group 'IKE-HUB' - - Map IKE group to IPSEC profile - -********** -Monitoring -********** -.. opcmd:: show ip nhrp cache - - Forwarding cache information. - -.. opcmd:: show ip nhrp nhs - - Next hop server information. - -.. opcmd:: show ip nhrp shortcut - - Shortcut information. - -******* -Example -******* - -This blueprint uses VyOS as the DMVPN Hub and Cisco IOSv 15.5(3)M and VyOS as -multiple spoke sites. - -.. figure:: /_static/images/blueprint-dmvpn.* - :width: 70% - :align: center - :alt: DMVPN Network Topology Diagram - - - DMVPN Network Topology Diagram - -Each node (Hub and Spoke) uses an IP address from the network 10.0.0.0/24. - -The below referenced IP address `192.168.0.2` is used as example address -representing a global unicast address under which the HUB can be contacted by -each and every individual spoke. - -.. _dmvpn:example_configuration: - -Configuration -============= - -Hub ---- -VyOS-HUB-1 -^^^^^^^^^^ - -.. code-block:: none - - set interfaces ethernet eth0 address '192.168.0.2/30' - - set interfaces tunnel tun100 address '10.0.0.100/32' - set interfaces tunnel tun100 enable-multicast - set interfaces tunnel tun100 encapsulation 'gre' - set interfaces tunnel tun100 parameters ip key '42' - set interfaces tunnel tun100 source-interface 'eth0' - - set protocols nhrp tunnel tun100 authentication 'test123' - set protocols nhrp tunnel tun100 holdtime '300' - set protocols nhrp tunnel tun100 multicast 'dynamic' - set protocols nhrp tunnel tun100 network-id '1' - set protocols nhrp tunnel tun100 redirect - set protocols nhrp tunnel tun100 registration-no-unique - - set protocols static route 0.0.0.0/0 next-hop 192.168.0.1 - - set vpn ipsec esp-group ESP-HUB lifetime '1800' - set vpn ipsec esp-group ESP-HUB mode 'transport' - set vpn ipsec esp-group ESP-HUB pfs 'dh-group2' - set vpn ipsec esp-group ESP-HUB proposal 1 encryption 'aes256' - set vpn ipsec esp-group ESP-HUB proposal 1 hash 'sha1' - set vpn ipsec ike-group IKE-HUB key-exchange 'ikev1' - set vpn ipsec ike-group IKE-HUB lifetime '3600' - set vpn ipsec ike-group IKE-HUB proposal 1 dh-group '2' - set vpn ipsec ike-group IKE-HUB proposal 1 encryption 'aes256' - set vpn ipsec ike-group IKE-HUB proposal 1 hash 'sha1' - set vpn ipsec interface 'eth0' - set vpn ipsec profile NHRPVPN authentication mode 'pre-shared-secret' - set vpn ipsec profile NHRPVPN authentication pre-shared-secret 'secret' - set vpn ipsec profile NHRPVPN bind tunnel 'tun100' - set vpn ipsec profile NHRPVPN esp-group 'ESP-HUB' - set vpn ipsec profile NHRPVPN ike-group 'IKE-HUB' - - -.. note:: Setting this up on AWS will require a "Custom Protocol Rule" for - protocol number "47" (GRE) Allow Rule in TWO places. Firstly on the VPC - Network ACL, and secondly on the security group network ACL attached to the - EC2 instance. This has been tested as working for the official AMI image on - the AWS Marketplace. (Locate the correct VPC and security group by navigating - through the details pane below your EC2 instance in the AWS console). - -Spokes ------- - - The individual spoke configurations only differ in interface IP addresses. - -VyOS-Spoke-1 and VyOS-Spoke-2 -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -.. code-block:: none - - set interfaces ethernet eth0 address '192.168.1.2/30' - - set interfaces tunnel tun100 address '10.0.0.1/32' - set interfaces tunnel tun100 enable-multicast - set interfaces tunnel tun100 encapsulation 'gre' - set interfaces tunnel tun100 parameters ip key '42' - set interfaces tunnel tun100 source-interface 'eth0' - - set protocols nhrp tunnel tun100 authentication 'test123' - set protocols nhrp tunnel tun100 holdtime '300' - set protocols nhrp tunnel tun100 multicast 'dynamic' - set protocols nhrp tunnel tun100 network-id '1' - set protocols nhrp tunnel tun100 nhs tunnel-ip dynamic nbma '192.168.0.2' - set protocols nhrp tunnel tun100 registration-no-unique - set protocols nhrp tunnel tun100 shortcut - - set protocols static route 0.0.0.0/0 next-hop 192.168.1.1 - set protocols static route 10.0.0.0/24 next-hop 10.0.0.100 - - set vpn ipsec esp-group ESP-HUB lifetime '1800' - set vpn ipsec esp-group ESP-HUB mode 'transport' - set vpn ipsec esp-group ESP-HUB pfs 'dh-group2' - set vpn ipsec esp-group ESP-HUB proposal 1 encryption 'aes256' - set vpn ipsec esp-group ESP-HUB proposal 1 hash 'sha1' - set vpn ipsec ike-group IKE-HUB key-exchange 'ikev1' - set vpn ipsec ike-group IKE-HUB lifetime '3600' - set vpn ipsec ike-group IKE-HUB proposal 1 dh-group '2' - set vpn ipsec ike-group IKE-HUB proposal 1 encryption 'aes256' - set vpn ipsec ike-group IKE-HUB proposal 1 hash 'sha1' - set vpn ipsec interface 'eth0' - set vpn ipsec profile NHRPVPN authentication mode 'pre-shared-secret' - set vpn ipsec profile NHRPVPN authentication pre-shared-secret 'secret' - set vpn ipsec profile NHRPVPN bind tunnel 'tun100' - set vpn ipsec profile NHRPVPN esp-group 'ESP-HUB' - set vpn ipsec profile NHRPVPN ike-group 'IKE-HUB' - -Cisco-Spoke-3 -^^^^^^^^^^^^^ - -.. code-block:: none - - crypto isakmp policy 10 - encr aes 256 - authentication pre-share - group 2 - lifetime 3600 - crypto isakmp key secret address 0.0.0.0 - ! - ! - crypto ipsec transform-set DMVPNESP esp-aes 256 esp-sha-hmac - mode transport - ! - crypto ipsec profile DMVPNPROFILE - set security-association lifetime seconds 1800 - set transform-set DMVPNESP - set pfs group2 - ! - ! - ! - ! - ! - ! - ! - interface Tunnel100 - ip address 10.0.0.3 255.255.255.0 - no ip redirects - ip nhrp authentication test123 - ip nhrp map multicast dynamic - ip nhrp network-id 1 - ip nhrp holdtime 300 - ip nhrp nhs 10.0.0.100 nbma 192.168.0.2 - ip nhrp registration no-unique - ip nhrp redirect - tunnel source GigabitEthernet0/0 - tunnel mode gre multipoint - tunnel key 42 - tunnel protection ipsec profile DMVPNPROFILE - ! - interface GigabitEthernet0/0 - ip address 192.168.3.2 255.255.255.252 - duplex auto - speed auto - media-type rj45 - ! - ip route 0.0.0.0 0.0.0.0 192.168.3.1 - - -Monitoring DMVPN Network -^^^^^^^^^^^^^^^^^^^^^^^^ - -Let send ICMP packets from VyOS-SPOKE-1 to Cisco-SPOKE-3 - -.. code-block:: none - - vyos@vyos:~$ ping 10.0.0.3 - PING 10.0.0.3 (10.0.0.3) 56(84) bytes of data. - 64 bytes from 10.0.0.3: icmp_seq=1 ttl=255 time=3.44 ms - 64 bytes from 10.0.0.3: icmp_seq=2 ttl=255 time=3.07 ms - ^C - --- 10.0.0.3 ping statistics --- - 2 packets transmitted, 2 received, 0% packet loss, time 1002ms - rtt min/avg/max/mdev = 3.072/3.257/3.442/0.185 ms - -Monitoring on HUB -^^^^^^^^^^^^^^^^^ - -.. code-block:: none - - vyos@vyos:~$ show ip nhrp cache - Iface Type Protocol NBMA Claimed NBMA Flags Identity - tun100 dynamic 10.0.0.1 192.168.1.2 192.168.1.2 T 192.168.1.2 - tun100 dynamic 10.0.0.3 192.168.3.2 192.168.3.2 T 192.168.3.2 - tun100 dynamic 10.0.0.2 192.168.2.2 192.168.2.2 T 192.168.2.2 - tun100 local 10.0.0.100 192.168.0.2 192.168.0.2 - - - vyos@vyos:~$ show vpn ipsec sa - Connection State Uptime Bytes In/Out Packets In/Out Remote address Remote ID Proposal - -------------------------- ------- -------- -------------- ---------------- ---------------- ----------- ---------------------------------- - dmvpn-NHRPVPN-tun100-child up 3m46s 230B/270B 2/2 192.168.1.2 192.168.1.2 AES_CBC_256/HMAC_SHA1_96/MODP_1024 - dmvpn-NHRPVPN-tun100-child up 5m48s 460B/540B 4/4 192.168.2.2 192.168.2.2 AES_CBC_256/HMAC_SHA1_96/MODP_1024 - dmvpn-NHRPVPN-tun100-child up 16m26s 1K/1K 13/12 192.168.3.2 192.168.3.2 AES_CBC_256/HMAC_SHA1_96/MODP_1024 - -Monitoring on Spokes -^^^^^^^^^^^^^^^^^^^^ - -.. code-block:: none - - vyos@vyos:~$ show ip nhrp cache - Iface Type Protocol NBMA Claimed NBMA Flags Identity - tun100 local 10.0.0.1 192.168.1.2 192.168.1.2 - - tun100 dynamic 10.0.0.3 192.168.3.2 192.168.3.2 T 192.168.3.2 - tun100 nhs 10.0.0.100 192.168.0.2 192.168.0.2 T 192.168.0.2 - - vyos@vyos:~$ show ip nhrp nhs - Iface FQDN NBMA Protocol - tun100 192.168.0.2 192.168.0.2 10.0.0.100 - - vyos@vyos:~$ show ip nhrp shortcut - Type Prefix Via Identity - dynamic 10.0.0.3/32 10.0.0.3 192.168.3.2 - - vyos@vyos:~$ show vpn ipsec sa - Connection State Uptime Bytes In/Out Packets In/Out Remote address Remote ID Proposal - -------------------------- ------- -------- -------------- ---------------- ---------------- ----------- ---------------------------------- - dmvpn-NHRPVPN-tun100-child up 6m43s 898B/695B 7/6 192.168.0.2 192.168.0.2 AES_CBC_256/HMAC_SHA1_96/MODP_1024 - dmvpn-NHRPVPN-tun100-child up 49s 215B/187B 2/2 192.168.3.2 192.168.3.2 AES_CBC_256/HMAC_SHA1_96/MODP_1024 - diff --git a/docs/configuration/vpn/rst-index.rst b/docs/configuration/vpn/rst-index.rst deleted file mode 100644 index 6d38e5b5..00000000 --- a/docs/configuration/vpn/rst-index.rst +++ /dev/null @@ -1,16 +0,0 @@ -### -VPN -### - - -.. toctree:: - :maxdepth: 1 - :includehidden: - - ipsec/index - l2tp - openconnect - pptp - rsa-keys - sstp - dmvpn diff --git a/docs/configuration/vpn/rst-l2tp.rst b/docs/configuration/vpn/rst-l2tp.rst deleted file mode 100644 index 7fdf8599..00000000 --- a/docs/configuration/vpn/rst-l2tp.rst +++ /dev/null @@ -1,579 +0,0 @@ -.. _l2tp: - -#### -L2TP -#### - -VyOS utilizes accel-ppp_ to provide L2TP server functionality. It can be used -with local authentication or a connected RADIUS server. - -*********************** -Configuring L2TP Server -*********************** - -.. code-block:: none - - set vpn l2tp remote-access authentication mode local - set vpn l2tp remote-access authentication local-users username test password 'test' - set vpn l2tp remote-access client-ip-pool L2TP-POOL range 192.168.255.2-192.168.255.254 - set vpn l2tp remote-access default-pool 'L2TP-POOL' - set vpn l2tp remote-access outside-address 192.0.2.2 - set vpn l2tp remote-access gateway-address 192.168.255.1 - - -.. cfgcmd:: set vpn l2tp remote-access authentication mode <local | radius> - - Set authentication backend. The configured authentication backend is used - for all queries. - - * **radius**: All authentication queries are handled by a configured RADIUS - server. - * **local**: All authentication queries are handled locally. - -.. cfgcmd:: set vpn l2tp remote-access authentication local-users username <user> password - <pass> - - Create `<user>` for local authentication on this system. The users password - will be set to `<pass>`. - -.. cfgcmd:: set vpn l2tp remote-access client-ip-pool <POOL-NAME> range <x.x.x.x-x.x.x.x | x.x.x.x/x> - - Use this command to define the first IP address of a pool of - addresses to be given to l2tp clients. If notation ``x.x.x.x-x.x.x.x``, - it must be within a /24 subnet. If notation ``x.x.x.x/x`` is - used there is possibility to set host/netmask. - -.. cfgcmd:: set vpn l2tp remote-access default-pool <POOL-NAME> - - Use this command to define default address pool name. - -.. cfgcmd:: set vpn l2tp remote-access gateway-address <gateway> - - Specifies single `<gateway>` IP address to be used as local address of PPP - interfaces. - -***************** -Configuring IPsec -***************** - -.. code-block:: none - - set vpn ipsec interface eth0 - set vpn l2tp remote-access ipsec-settings authentication mode pre-shared-secret - set vpn l2tp remote-access ipsec-settings authentication pre-shared-secret secret - - -.. cfgcmd:: set vpn ipsec interface <INTERFACE> - - Use this command to define IPsec interface. - -.. cfgcmd:: set vpn l2tp remote-access ipsec-settings authentication mode <pre-shared-secret | x509> - - Set mode for IPsec authentication between VyOS and L2TP clients. - -.. cfgcmd:: set vpn l2tp remote-access ipsec-settings authentication pre-shared-secret <secret> - - Set predefined shared secret phrase. - - -If a local firewall policy is in place on your external interface you will need -to allow the ports below: - -* UDP port 500 (IKE) -* IP protocol number 50 (ESP) -* UDP port 1701 for IPsec - -As well as the below to allow NAT-traversal (when NAT is detected by the -VPN client, ESP is encapsulated in UDP for NAT-traversal): - -* UDP port 4500 (NAT-T) - -Example: - -.. code-block:: none - - set firewall ipv4 name OUTSIDE-LOCAL rule 40 action 'accept' - set firewall ipv4 name OUTSIDE-LOCAL rule 40 protocol 'esp' - set firewall ipv4 name OUTSIDE-LOCAL rule 41 action 'accept' - set firewall ipv4 name OUTSIDE-LOCAL rule 41 destination port '500' - set firewall ipv4 name OUTSIDE-LOCAL rule 41 protocol 'udp' - set firewall ipv4 name OUTSIDE-LOCAL rule 42 action 'accept' - set firewall ipv4 name OUTSIDE-LOCAL rule 42 destination port '4500' - set firewall ipv4 name OUTSIDE-LOCAL rule 42 protocol 'udp' - set firewall ipv4 name OUTSIDE-LOCAL rule 43 action 'accept' - set firewall ipv4 name OUTSIDE-LOCAL rule 43 destination port '1701' - set firewall ipv4 name OUTSIDE-LOCAL rule 43 ipsec 'match-ipsec' - set firewall ipv4 name OUTSIDE-LOCAL rule 43 protocol 'udp' - -To allow VPN-clients access via your external address, a NAT rule is required: - - -.. code-block:: none - - set nat source rule 110 outbound-interface name 'eth0' - set nat source rule 110 source address '192.168.255.0/24' - set nat source rule 110 translation address masquerade - -********************************* -Configuring RADIUS authentication -********************************* - -To enable RADIUS based authentication, the authentication mode needs to be -changed within the configuration. Previous settings like the local users, still -exists within the configuration, however they are not used if the mode has been -changed from local to radius. Once changed back to local, it will use all local -accounts again. - -.. code-block:: none - - set vpn l2tp remote-access authentication mode radius - -.. cfgcmd:: set vpn l2tp remote-access authentication radius server <server> key <secret> - - Configure RADIUS `<server>` and its required shared `<secret>` for - communicating with the RADIUS server. - -Since the RADIUS server would be a single point of failure, multiple RADIUS -servers can be setup and will be used subsequentially. -For example: - -.. code-block:: none - - set vpn l2tp remote-access authentication radius server 10.0.0.1 key 'foo' - set vpn l2tp remote-access authentication radius server 10.0.0.2 key 'foo' - -.. note:: Some RADIUS_ severs use an access control list which allows or denies - queries, make sure to add your VyOS router to the allowed client list. - -RADIUS source address -===================== - -If you are using OSPF as your IGP, use the interface connected closest to the -RADIUS server. You can bind all outgoing RADIUS requests to a single source IP -e.g. the loopback interface. - -.. cfgcmd:: set vpn l2tp remote-access authentication radius source-address <address> - - Source IPv4 address used in all RADIUS server queires. - -.. note:: The ``source-address`` must be configured to that of an interface. - Best practice would be a loopback or dummy interface. - -RADIUS advanced options -======================= - -.. cfgcmd:: set vpn l2tp remote-access authentication radius server <server> port <port> - - Configure RADIUS `<server>` and its required port for authentication requests. - -.. cfgcmd:: set vpn l2tp remote-access authentication radius server <server> fail-time <time> - - Mark RADIUS server as offline for this given `<time>` in seconds. - -.. cfgcmd:: set vpn l2tp remote-access authentication radius server <server> disable - - Temporary disable this RADIUS server. - -.. cfgcmd:: set vpn l2tp remote-access authentication radius acct-timeout <timeout> - - Timeout to wait reply for Interim-Update packets. (default 3 seconds) - -.. cfgcmd:: set vpn l2tp remote-access authentication radius dynamic-author server <address> - - Specifies IP address for Dynamic Authorization Extension server (DM/CoA). - This IP must exist on any VyOS interface or it can be ``0.0.0.0``. - -.. cfgcmd:: set vpn l2tp remote-access authentication radius dynamic-author port <port> - - UDP port for Dynamic Authorization Extension server (DM/CoA) - -.. cfgcmd:: set vpn l2tp remote-access authentication radius dynamic-author key <secret> - - Secret for Dynamic Authorization Extension server (DM/CoA) - -.. cfgcmd:: set vpn l2tp remote-access authentication radius max-try <number> - - Maximum number of tries to send Access-Request/Accounting-Request queries - -.. cfgcmd:: set vpn l2tp remote-access authentication radius timeout <timeout> - - Timeout to wait response from server (seconds) - -.. cfgcmd:: set vpn l2tp remote-access authentication radius nas-identifier <identifier> - - Value to send to RADIUS server in NAS-Identifier attribute and to be matched - in DM/CoA requests. - -.. cfgcmd:: set vpn l2tp remote-access authentication radius nas-ip-address <address> - - Value to send to RADIUS server in NAS-IP-Address attribute and to be matched - in DM/CoA requests. Also DM/CoA server will bind to that address. - -.. cfgcmd:: set vpn l2tp remote-access authentication radius source-address <address> - - Source IPv4 address used in all RADIUS server queires. - -.. cfgcmd:: set vpn l2tp remote-access authentication radius rate-limit attribute <attribute> - - Specifies which RADIUS server attribute contains the rate limit information. - The default attribute is `Filter-Id`. - -.. note:: If you set a custom RADIUS attribute you must define it on both - dictionaries on the RADIUS server and client. - -.. cfgcmd:: set vpn l2tp remote-access authentication radius rate-limit enable - - Enables bandwidth shaping via RADIUS. - -.. cfgcmd:: set vpn l2tp remote-access authentication radius rate-limit vendor - - Specifies the vendor dictionary. This dictionary needs to be present in - /usr/share/accel-ppp/radius. - -Received RADIUS attributes have a higher priority than parameters defined within -the CLI configuration, refer to the explanation below. - -Allocation clients ip addresses by RADIUS -========================================= - -If the RADIUS server sends the attribute ``Framed-IP-Address`` then this IP -address will be allocated to the client and the option ``default-pool`` within -the CLI config will be ignored. - -If the RADIUS server sends the attribute ``Framed-Pool``, then the IP address -will be allocated from a predefined IP pool whose name equals the attribute -value. - -If the RADIUS server sends the attribute ``Stateful-IPv6-Address-Pool``, the -IPv6 address will be allocated from a predefined IPv6 pool ``prefix`` whose -name equals the attribute value. - -If the RADIUS server sends the attribute ``Delegated-IPv6-Prefix-Pool``, an -IPv6 delegation prefix will be allocated from a predefined IPv6 pool -``delegate`` whose name equals the attribute value. - -.. note:: ``Stateful-IPv6-Address-Pool`` and ``Delegated-IPv6-Prefix-Pool`` are defined in - RFC6911. If they are not defined in your RADIUS server, add new dictionary_. - -The client's interface can be put into a VRF context via a RADIUS Access-Accept -packet, or changed via RADIUS CoA. ``Accel-VRF-Name`` is used for these -purposes. This is a custom `ACCEL-PPP attribute`_. Define it in your RADIUS -server. - -Renaming clients interfaces by RADIUS -===================================== - -If the RADIUS server uses the attribute ``NAS-Port-Id``, ppp tunnels will be -renamed. - -.. note:: The value of the attribute ``NAS-Port-Id`` must be less than 16 - characters, otherwise the interface won't be renamed. - -************************************* -Configuring LNS (L2TP Network Server) -************************************* - -LNS are often used to connect to a LAC (L2TP Access Concentrator). - -.. cfgcmd:: set vpn l2tp remote-access lns host-name <hostname> - - Sent to the client (LAC) in the Host-Name attribute - -.. cfgcmd:: set vpn l2tp remote-access lns shared-secret <secret> - - Tunnel password used to authenticate the client (LAC) - -To explain the usage of LNS follow our blueprint :ref:`examples-lac-lns`. - -**** -IPv6 -**** -.. cfgcmd:: set vpn l2tp remote-access ppp-options ipv6 <require | prefer | allow | deny> - - Specifies IPv6 negotiation preference. - - * **require** - Require IPv6 negotiation - * **prefer** - Ask client for IPv6 negotiation, do not fail if it rejects - * **allow** - Negotiate IPv6 only if client requests - * **deny** - Do not negotiate IPv6 (default value) - -.. cfgcmd:: set vpn l2tp remote-access client-ipv6-pool <IPv6-POOL-NAME> prefix <address> - mask <number-of-bits> - - Use this comand to set the IPv6 address pool from which an l2tp client will - get an IPv6 prefix of your defined length (mask) to terminate the l2tp - endpoint at their side. The mask length can be set between 48 and 128 bits - long, the default value is 64. - -.. cfgcmd:: set vpn l2tp remote-access client-ipv6-pool <IPv6-POOL-NAME> delegate <address> - delegation-prefix <number-of-bits> - - Use this command to configure DHCPv6 Prefix Delegation (RFC3633) on l2tp. - You will have to set your IPv6 pool and the length of the delegation - prefix. From the defined IPv6 pool you will be handing out networks of the - defined length (delegation-prefix). The length of the delegation prefix can - be between 32 and 64 bits long. - -.. cfgcmd:: set vpn l2tp remote-access default-ipv6-pool <IPv6-POOL-NAME> - - Use this command to define default IPv6 address pool name. - -.. code-block:: none - - set vpn l2tp remote-access ppp-options ipv6 allow - set vpn l2tp remote-access client-ipv6-pool IPv6-POOL delegate '2001:db8:8003::/48' delegation-prefix '56' - set vpn l2tp remote-access client-ipv6-pool IPv6-POOL prefix '2001:db8:8002::/48' mask '64' - set vpn l2tp remote-access default-ipv6-pool IPv6-POOL - -IPv6 Advanced Options -===================== -.. cfgcmd:: set vpn l2tp remote-access ppp-options ipv6-accept-peer-interface-id - - Accept peer interface identifier. By default this is not defined. - -.. cfgcmd:: set vpn l2tp remote-access ppp-options ipv6-interface-id <random | x:x:x:x> - - Specifies if a fixed or random interface identifier is used for IPv6. The - default is fixed. - - * **random** - Random interface identifier for IPv6 - * **x:x:x:x** - Specify interface identifier for IPv6 - -.. cfgcmd:: set vpn l2tp remote-access ppp-options ipv6-interface-id <random | x:x:x:x> - - Specifies the peer interface identifier for IPv6. The default is fixed. - - * **random** - Random interface identifier for IPv6 - * **x:x:x:x** - Specify interface identifier for IPv6 - * **ipv4-addr** - Calculate interface identifier from IPv4 address. - * **calling-sid** - Calculate interface identifier from calling-station-id. - -********* -Scripting -********* - -.. cfgcmd:: set vpn l2tp remote-access extended-scripts on-change <path_to_script> - - Script to run when the session interface is changed by RADIUS CoA handling - -.. cfgcmd:: set vpn l2tp remote-access extended-scripts on-down <path_to_script> - - Script to run when the session interface is about to terminate - -.. cfgcmd:: set vpn l2tp remote-access extended-scripts on-pre-up <path_to_script> - - Script to run before the session interface comes up - -.. cfgcmd:: set vpn l2tp remote-access extended-scripts on-up <path_to_script> - - Script to run when the session interface is completely configured and started - -**************** -Advanced Options -**************** - -Authentication Advanced Options -=============================== - -.. cfgcmd:: set vpn l2tp remote-access authentication local-users username <user> disable - - Disable `<user>` account. - -.. cfgcmd:: set vpn l2tp remote-access authentication local-users username <user> static-ip - <address> - - Assign a static IP address to `<user>` account. - -.. cfgcmd:: set vpn l2tp remote-access authentication local-users username <user> rate-limit - download <bandwidth> - - Rate limit the download bandwidth for `<user>` to `<bandwidth>` kbit/s. - -.. cfgcmd:: set vpn l2tp remote-access authentication local-users username <user> rate-limit - upload <bandwidth> - - Rate limit the upload bandwidth for `<user>` to `<bandwidth>` kbit/s - -.. cfgcmd:: set vpn l2tp remote-access authentication protocols - <pap | chap | mschap | mschap-v2> - - Require the peer to authenticate itself using one of the following protocols: - pap, chap, mschap, mschap-v2. - -Client IP Pool Advanced Options -=============================== - -.. cfgcmd:: set vpn l2tp remote-access client-ip-pool <POOL-NAME> next-pool <NEXT-POOL-NAME> - - Use this command to define the next address pool name. - -PPP Advanced Options -==================== - -.. cfgcmd:: set vpn l2tp remote-access ppp-options disable-ccp - - Disable Compression Control Protocol (CCP). - CCP is enabled by default. - -.. cfgcmd:: set vpn l2tp remote-access ppp-options interface-cache <number> - - Specifies number of interfaces to cache. This prevents interfaces from being - removed once the corresponding session is destroyed. Instead, interfaces are - cached for later use in new sessions. This should reduce the kernel-level - interface creation/deletion rate. - Default value is **0**. - -.. cfgcmd:: set vpn l2tp remote-access ppp-options ipv4 <require | prefer | allow | deny> - - Specifies IPv4 negotiation preference. - - * **require** - Require IPv4 negotiation - * **prefer** - Ask client for IPv4 negotiation, do not fail if it rejects - * **allow** - Negotiate IPv4 only if client requests (Default value) - * **deny** - Do not negotiate IPv4 - -.. cfgcmd:: set vpn l2tp remote-access ppp-options lcp-echo-failure <number> - - Defines the maximum `<number>` of unanswered echo requests. Upon reaching the - value `<number>`, the session will be reset. Default value is **3**. - -.. cfgcmd:: set vpn l2tp remote-access ppp-options lcp-echo-interval <interval> - - If this option is specified and is greater than 0, then the PPP module will - send LCP echo requests every `<interval>` seconds. - Default value is **30**. - -.. cfgcmd:: set vpn l2tp remote-access ppp-options lcp-echo-timeout - - Specifies timeout in seconds to wait for any peer activity. If this option is - specified it turns on adaptive lcp echo functionality and "lcp-echo-failure" - is not used. Default value is **0**. - -.. cfgcmd:: set vpn l2tp remote-access ppp-options min-mtu <number> - - Defines the minimum acceptable MTU. If a client tries to negotiate an MTU - lower than this it will be NAKed, and disconnected if it rejects a greater - MTU. - Default value is **100**. - -.. cfgcmd:: set vpn l2tp remote-access ppp-options mppe <require | prefer | deny> - - Specifies :abbr:`MPPE (Microsoft Point-to-Point Encryption)` negotiation - preference. - - * **require** - ask client for mppe, if it rejects drop connection - * **prefer** - ask client for mppe, if it rejects don't fail. (Default value) - * **deny** - deny mppe - - Default behavior - don't ask the client for mppe, but allow it if the client - wants. - Please note that RADIUS may override this option with the - MS-MPPE-Encryption-Policy attribute. - -.. cfgcmd:: set vpn l2tp remote-access ppp-options mru <number> - - Defines preferred MRU. By default is not defined. - -Global Advanced options -======================= - -.. cfgcmd:: set vpn l2tp remote-access description <description> - - Set description. - -.. cfgcmd:: set vpn l2tp remote-access limits burst <value> - - Burst count - -.. cfgcmd:: set vpn l2tp remote-access limits connection-limit <value> - - Maximum accepted connection rate (e.g. 1/min, 60/sec) - -.. cfgcmd:: set vpn l2tp remote-access limits timeout <value> - - Timeout in seconds - -.. cfgcmd:: set vpn l2tp remote-access mtu - - Maximum Transmission Unit (MTU) (default: **1436**) - -.. cfgcmd:: set vpn l2tp remote-access max-concurrent-sessions - - Maximum number of concurrent session start attempts - -.. cfgcmd:: set vpn l2tp remote-access name-server <address> - - Connected clients should use `<address>` as their DNS server. This command - accepts both IPv4 and IPv6 addresses. Up to two nameservers can be configured - for IPv4, up to three for IPv6. - -.. cfgcmd:: set vpn l2tp remote-access shaper fwmark <1-2147483647> - - Match firewall mark value - -.. cfgcmd:: set vpn l2tp remote-access snmp master-agent - - Enable SNMP - -.. cfgcmd:: set vpn l2tp remote-access wins-server <address> - - Windows Internet Name Service (WINS) servers propagated to client - -********** -Monitoring -********** - -.. code-block:: none - - vyos@vyos:~$ show l2tp-server sessions - ifname | username | ip | ip6 | ip6-dp | calling-sid | rate-limit | state | uptime | rx-bytes | tx-bytes - --------+----------+---------------+-----+--------+-------------+------------+--------+----------+----------+---------- - l2tp0 | test | 192.168.255.3 | | | 192.168.0.36 | | active | 02:01:47 | 7.7 KiB | 1.2 KiB - -.. code-block:: none - - vyos@vyos:~$ show l2tp-server statistics - uptime: 0.02:49:49 - cpu: 0% - mem(rss/virt): 5920/100892 kB - core: - mempool_allocated: 133202 - mempool_available: 131770 - thread_count: 1 - thread_active: 1 - context_count: 5 - context_sleeping: 0 - context_pending: 0 - md_handler_count: 3 - md_handler_pending: 0 - timer_count: 0 - timer_pending: 0 - sessions: - starting: 0 - active: 0 - finishing: 0 - l2tp: - tunnels: - starting: 0 - active: 0 - finishing: 0 - sessions (control channels): - starting: 0 - active: 0 - finishing: 0 - sessions (data channels): - starting: 0 - active: 0 - finishing: 0 - - -.. _`Google Public DNS`: https://developers.google.com/speed/public-dns -.. _Quad9: https://quad9.net -.. _CloudFlare: https://blog.cloudflare.com/announcing-1111 -.. _OpenNIC: https://www.opennic.org/ -.. _RADIUS: https://en.wikipedia.org/wiki/RADIUS -.. _FreeRADIUS: https://freeradius.org -.. _`Network Policy Server`: https://en.wikipedia.org/wiki/Network_Policy_Server -.. _accel-ppp: https://accel-ppp.org/ -.. _dictionary: https://github.com/accel-ppp/accel-ppp/blob/master/accel-pppd/radius/dict/dictionary.rfc6911 -.. _`ACCEL-PPP attribute`: https://github.com/accel-ppp/accel-ppp/blob/master/accel-pppd/radius/dict/dictionary.accel diff --git a/docs/configuration/vpn/rst-openconnect.rst b/docs/configuration/vpn/rst-openconnect.rst deleted file mode 100644 index 0262b3f2..00000000 --- a/docs/configuration/vpn/rst-openconnect.rst +++ /dev/null @@ -1,374 +0,0 @@ -.. _vpn-openconnect: - -########### -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 -access controls based only on network layer information, such as destination IP -address and port number. So, it provides safe communication for all types of -device traffic across public networks and private networks, also encrypts the -traffic with SSL protocol. - -The remote user will use the openconnect client to connect to the router and -will receive an IP address from a VPN pool, allowing full access to the -network. - -************* -Configuration -************* - -SSL Certificates -================ - -We need to generate the certificate which authenticates users who attempt to -access the network resource through the SSL VPN tunnels. The following commands -will create a self signed certificates and will be stored in configuration: - -.. code-block:: none - - run generate pki ca install <CA name> - run generate pki certificate sign <CA name> install <Server name> - -We can also create the certificates using Certbot which is an easy-to-use -client that fetches a certificate from Let's Encrypt an open certificate -authority launched by the EFF, Mozilla, and others and deploys it to a web -server. - -.. stop_vyoslinter - -.. code-block:: none - - sudo certbot certonly --standalone --preferred-challenges http -d <domain name> - -.. start_vyoslinter - -Server Configuration -==================== - -.. code-block:: none - - set vpn openconnect authentication local-users username <user> password <pass> - set vpn openconnect authentication mode <local password|radius|certificate> - set vpn openconnect network-settings client-ip-settings subnet <subnet> - set vpn openconnect network-settings name-server <address> - set vpn openconnect network-settings name-server <address> - set vpn openconnect ssl ca-certificate <pki-ca-name> - set vpn openconnect ssl certificate <pki-cert-name> - set vpn openconnect ssl passphrase <pki-password> - -2FA OTP support -=============== - -Instead of password only authentication, 2FA password -authentication + OTP key can be used. Alternatively, OTP authentication only, -without a password, can be used. -To do this, an OTP configuration must be added to the configuration above: - -.. stop_vyoslinter - -.. code-block:: none - - set vpn openconnect authentication mode local <password-otp|otp> - set vpn openconnect authentication local-users username <user> otp <key> - set vpn openconnect authentication local-users username <user> interval <interval (optional)> - set vpn openconnect authentication local-users username <user> otp-length <otp-length (optional)> - set vpn openconnect authentication local-users username <user> token-type <token-type (optional)> - -.. start_vyoslinter - -For generating an OTP key in VyOS, you can use the CLI command -(operational mode): - -.. code-block:: none - - generate openconnect username <user> otp-key hotp-time - -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 - -.. 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. - -.. 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 - - set vpn openconnect authentication mode certificate - set vpn openconnect authentication mode certificate user-identifier-field cn - set vpn openconnect ssl ca-certificate <cert> - -************ -Verification -************ - -.. 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. - -******* -Example -******* - -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 - Enter private key type: [rsa, dsa, ec] (Default: rsa) - Enter private key bits: (Default: 2048) - Enter country code: (Default: GB) US - Enter state: (Default: Some-State) Delaware - Enter locality: (Default: Some-City) Mycity - Enter organization name: (Default: VyOS) MyORG - Enter common name: (Default: vyos.io) oc-ca - Enter how many days certificate will be valid: (Default: 1825) 3650 - Note: If you plan to use the generated key on this router, do not encrypt the private key. - Do you want to encrypt the private key with a passphrase? [y/N] N - 2 value(s) installed. Use "compare" to see the pending changes, and "commit" to apply. - [edit] - -Follow the instructions to generate server cert (in configuration mode): - -.. code-block:: none - - vyos@vyos# run generate pki certificate sign ca-ocserv install srv-ocserv - Do you already have a certificate request? [y/N] N - Enter private key type: [rsa, dsa, ec] (Default: rsa) - Enter private key bits: (Default: 2048) - Enter country code: (Default: GB) US - Enter state: (Default: Some-State) Delaware - Enter locality: (Default: Some-City) Mycity - Enter organization name: (Default: VyOS) MyORG - Enter common name: (Default: vyos.io) oc-srv - Do you want to configure Subject Alternative Names? [y/N] N - Enter how many days certificate will be valid: (Default: 365) 1830 - Enter certificate type: (client, server) (Default: server) - Note: If you plan to use the generated key on this router, do not encrypt the private key. - Do you want to encrypt the private key with a passphrase? [y/N] N - 2 value(s) installed. Use "compare" to see the pending changes, and "commit" to apply. - [edit] - -.. start_vyoslinter - -Each of the install command should be applied to the configuration and commited -before using under the openconnect configuration: - -.. code-block:: none - - vyos@vyos# commit - [edit] - vyos@vyos# save - Saving configuration to '/config/config.boot'... - Done - [edit] - -Openconnect Configuration -========================= - -Simple setup with one user added and password authentication: - -.. stop_vyoslinter - -.. code-block:: none - - set vpn openconnect authentication local-users username tst password 'OC_bad_Secret' - set vpn openconnect authentication mode local password - set vpn openconnect network-settings client-ip-settings subnet '172.20.20.0/24' - set vpn openconnect network-settings name-server '10.1.1.1' - set vpn openconnect network-settings name-server '10.1.1.2' - set vpn openconnect ssl ca-certificate 'ca-ocserv' - set vpn openconnect ssl certificate 'srv-ocserv' - -.. start_vyoslinter - -To enable the HTTP security headers in the configuration file, use the command: - -.. code-block:: none - - set vpn openconnect http-security-headers - - -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 - # You can share it with the user, he just needs to scan the QR in his OTP app - # username: tst - # OTP KEY: 5PA4SGYTQSGOBO3H3EQSSNCUNZAYAPH2 - # OTP URL: otpauth://totp/tst@vyos?secret=5PA4SGYTQSGOBO3H3EQSSNCUNZAYAPH2&digits=6&period=30 - █████████████████████████████████████████ - █████████████████████████████████████████ - ████ ▄▄▄▄▄ █▀ ██▄▀ ▄█▄▀▀▄▄▄▄██ ▄▄▄▄▄ ████ - ████ █ █ █▀ █▄▄▀▀▀▄█ ▄▄▀▄ █ █ █ ████ - ████ █▄▄▄█ █▀█▀▄▄▀ ▄▀ █▀ ▀▄██ █▄▄▄█ ████ - ████▄▄▄▄▄▄▄█▄█▄▀ ▀▄█ ▀ ▀ ▀ █▄█▄▄▄▄▄▄▄████ - ████ ▄▄▄▀▄▄ ▄███▀▄▀█▄██▀ ▀▄ ▀▄█ ▀ ▀████ - ████ ▀▀ ▀ ▄█▄ ▀ ▀▄ ▄█▀ ▄█ ▄▀▀▄██ █████ - ████▄ █▄▀▀▄█▀ ▀█▄█▄▄▄▄ ▄▀█▀▀█ ▀ ▄ ▀█▀████ - █████ ▀█▀▄▄ █ ▀▄▄ ▄█▄ ▀█▀▀ █▀ ▄█████ - ████▀██▀█▄▄ ▀▀▀▀█▄▀ ▀█▄▄▀▀▀ ▀ ▀█▄██▀▀████ - ████▄ ▄ ▄▀▄██▀█ ▄ ▀▄██ ▄▄ ▀▀▄█▄██ ▄█████ - ████▀▀ ▄▀ ▄ ▀█▀█▀█ █▀█▄▄▀█▀█▄██▄▄█ ▀████ - ████ █ ▀█▄▄█▄ ▀ ▄▄▀▀ ▀ █▄█▀████ █▀ ▀████ - ████▄██▄██▄█▀ ▄▀ ▄▄▀▄ ▄▀█ ▄ ▄▄▄ ▀█▄ ████ - ████ ▄▄▄▄▄ █▄ ▀█▄█ ▄ ▀ ▄ ▄ █▄█ ▄▀▄█████ - ████ █ █ █ ▀▄██▄▄▀█▄▀▄██▄▀ ▄ ▀██▀████ - ████ █▄▄▄█ █ ██▀▄▄ ▀▄▄▀█▀ ▀█ ▄▀█ ▀██████ - ████▄▄▄▄▄▄▄█▄███▄███▄█▄▄▄▄█▄▄█▄██▄█▄█████ - █████████████████████████████████████████ - █████████████████████████████████████████ - # To add this OTP key to configuration, run the following commands: - set vpn openconnect authentication local-users username tst otp key 'ebc1c91b13848ce0bb67d9212934546e41803cfa' - -.. 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. - -.. warning:: When using Time-based one-time password (TOTP) (OTP HOTP-time), - be sure that the time on the server and the - OTP token generator are synchronized by NTP - -To display the configured OTP user settings, use the command: - -.. code-block:: none - - show openconnect-server user <username> otp <full|key-b32|key-hex|qrcode|uri> - -Identity Based Configuration -============================ - -OpenConnect supports a subset of it's configuration options to be applied on a -per user/group basis, for configuration purposes we refer to this functionality -as "Identity based config". The following `OpenConnect Server Manual -<https://ocserv.gitlab.io/www/manual.html#:~:text=Configuration%20files%20that% -20will%20be%20applied%20per%20user%20connection%20or%0A%23%20per%20group>`_ -outlines the set of configuration options that are allowed. This can be -leveraged to apply different sets of configs to different users or groups of -users. - -.. stop_vyoslinter - -.. code-block:: none - - sudo mkdir -p /config/auth/ocserv/config-per-user - sudo touch /config/auth/ocserv/default-user.conf - - set vpn openconnect authentication identity-based-config mode user - set vpn openconnect authentication identity-based-config directory /config/auth/ocserv/config-per-user - set vpn openconnect authentication identity-based-config default-config /config/auth/ocserv/default-user.conf - -.. 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. - -Once you commit the above changes you can create a config file in the -/config/auth/ocserv/config-per-user directory that matches a username of a -user you have created e.g. "tst". Now when logging in with the "tst" user the -config options you set in this file will be loaded. - -Be sure to set a sane default config in the default config file, this will be -loaded in the case that a user is authenticated and no file is found in the -configured directory matching the users username/group. - -.. code-block:: none - - sudo nano /config/auth/ocserv/config-per-user/tst - -The same configuration options apply when Identity based config is configured -in group mode except that group mode can only be used with RADIUS -authentication. - -.. warning:: OpenConnect server matches the filename in a case sensitive - manner, make sure the username/group name you configure matches the - filename exactly. - -Configuring RADIUS accounting -============================= - -OpenConnect can be configured to send accounting information to a -RADIUS server to capture user session data such as time of -connect/disconnect, data transferred, and so on. - -Configure an accounting server and enable accounting with: - -.. stop_vyoslinter - -.. code-block:: none - - set vpn openconnect accounting mode radius - set vpn openconnect accounting radius server 172.20.20.10 - set vpn openconnect accounting radius server 172.20.20.10 port 1813 - set vpn openconnect accounting radius server 172.20.20.10 key your_radius_secret - -.. 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; - +----------+---------------+---------------------+---------------------+-----------------+------------------+-------------------+-----------------+-----------------------------------+ - | username | nasipaddress | acctstarttime | acctstoptime | acctinputoctets | acctoutputoctets | callingstationid | framedipaddress | connectinfo_start | - +----------+---------------+---------------------+---------------------+-----------------+------------------+-------------------+-----------------+-----------------------------------+ - | test | 198.51.100.15 | 2023-01-13 00:59:15 | 2023-01-13 00:59:21 | 10606 | 152 | 192.168.6.1 | 172.20.20.198 | Open AnyConnect VPN Agent v8.05-1 | - +----------+---------------+---------------------+---------------------+-----------------+------------------+-------------------+-----------------+-----------------------------------+ - -.. start_vyoslinter diff --git a/docs/configuration/vpn/rst-pptp.rst b/docs/configuration/vpn/rst-pptp.rst deleted file mode 100644 index 194ec771..00000000 --- a/docs/configuration/vpn/rst-pptp.rst +++ /dev/null @@ -1,553 +0,0 @@ -.. _pptp: - -########### -PPTP-Server -########### - -The Point-to-Point Tunneling Protocol (PPTP_) has been implemented in VyOS only -for backwards compatibility. PPTP has many well known security issues and you -should use one of the many other new VPN implementations. - -*********************** -Configuring PPTP Server -*********************** - -.. code-block:: none - - set vpn pptp remote-access authentication mode local - set vpn pptp remote-access authentication local-users username test password 'test' - set vpn pptp remote-access client-ip-pool PPTP-POOL range 192.168.255.2-192.168.255.254 - set vpn pptp remote-access default-pool 'PPTP-POOL' - set vpn pptp remote-access outside-address 192.0.2.2 - set vpn pptp remote-access gateway-address 192.168.255.1 - - -.. cfgcmd:: set vpn pptp remote-access authentication mode <local | radius> - - Set authentication backend. The configured authentication backend is used - for all queries. - - * **radius**: All authentication queries are handled by a configured RADIUS - server. - * **local**: All authentication queries are handled locally. - * **noauth**: Authentication disabled. - -.. cfgcmd:: set vpn pptp remote-access authentication local-users username <user> password - <pass> - - Create `<user>` for local authentication on this system. The users password - will be set to `<pass>`. - -.. cfgcmd:: set vpn pptp remote-access client-ip-pool <POOL-NAME> range <x.x.x.x-x.x.x.x | x.x.x.x/x> - - Use this command to define the first IP address of a pool of - addresses to be given to PPTP clients. If notation ``x.x.x.x-x.x.x.x``, - it must be within a /24 subnet. If notation ``x.x.x.x/x`` is - used there is possibility to set host/netmask. - -.. cfgcmd:: set vpn pptp remote-access default-pool <POOL-NAME> - - Use this command to define default address pool name. - -.. cfgcmd:: set vpn pptp remote-access gateway-address <gateway> - - Specifies single `<gateway>` IP address to be used as local address of PPP - interfaces. - -********************************* -Configuring RADIUS authentication -********************************* - -To enable RADIUS based authentication, the authentication mode needs to be -changed within the configuration. Previous settings like the local users, still -exists within the configuration, however they are not used if the mode has been -changed from local to radius. Once changed back to local, it will use all local -accounts again. - -.. code-block:: none - - set vpn pptp remote-access authentication mode radius - -.. cfgcmd:: set vpn pptp remote-access authentication radius server <server> key <secret> - - Configure RADIUS `<server>` and its required shared `<secret>` for - communicating with the RADIUS server. - -Since the RADIUS server would be a single point of failure, multiple RADIUS -servers can be setup and will be used subsequentially. -For example: - -.. code-block:: none - - set vpn pptp remote-access authentication radius server 10.0.0.1 key 'foo' - set vpn pptp remote-access authentication radius server 10.0.0.2 key 'foo' - -.. note:: Some RADIUS severs use an access control list which allows or denies - queries, make sure to add your VyOS router to the allowed client list. - -RADIUS source address -===================== - -If you are using OSPF as IGP, always the closest interface connected to the -RADIUS server is used. You can bind all outgoing RADIUS requests -to a single source IP e.g. the loopback interface. - -.. cfgcmd:: set vpn pptp remote-access authentication radius source-address <address> - - Source IPv4 address used in all RADIUS server queires. - -.. note:: The ``source-address`` must be configured on one of VyOS interface. - Best practice would be a loopback or dummy interface. - -RADIUS advanced options -======================= - -.. cfgcmd:: set vpn pptp remote-access authentication radius server <server> port <port> - - Configure RADIUS `<server>` and its required port for authentication requests. - -.. cfgcmd:: set vpn pptp remote-access authentication radius server <server> fail-time <time> - - Mark RADIUS server as offline for this given `<time>` in seconds. - -.. cfgcmd:: set vpn pptp remote-access authentication radius server <server> disable - - Temporary disable this RADIUS server. - -.. cfgcmd:: set vpn pptp remote-access authentication radius acct-timeout <timeout> - - Timeout to wait reply for Interim-Update packets. (default 3 seconds) - -.. cfgcmd:: set vpn pptp remote-access authentication radius dynamic-author server <address> - - Specifies IP address for Dynamic Authorization Extension server (DM/CoA). - This IP must exist on any VyOS interface or it can be ``0.0.0.0``. - -.. cfgcmd:: set vpn pptp remote-access authentication radius dynamic-author port <port> - - UDP port for Dynamic Authorization Extension server (DM/CoA) - -.. cfgcmd:: set vpn pptp remote-access authentication radius dynamic-author key <secret> - - Secret for Dynamic Authorization Extension server (DM/CoA) - -.. cfgcmd:: set vpn pptp remote-access authentication radius max-try <number> - - Maximum number of tries to send Access-Request/Accounting-Request queries - -.. cfgcmd:: set vpn pptp remote-access authentication radius timeout <timeout> - - Timeout to wait response from server (seconds) - -.. cfgcmd:: set vpn pptp remote-access authentication radius nas-identifier <identifier> - - Value to send to RADIUS server in NAS-Identifier attribute and to be matched - in DM/CoA requests. - -.. cfgcmd:: set vpn pptp remote-access authentication radius nas-ip-address <address> - - Value to send to RADIUS server in NAS-IP-Address attribute and to be matched - in DM/CoA requests. Also DM/CoA server will bind to that address. - -.. cfgcmd:: set vpn pptp remote-access authentication radius source-address <address> - - Source IPv4 address used in all RADIUS server queires. - -.. cfgcmd:: set vpn pptp remote-access authentication radius rate-limit attribute <attribute> - - Specifies which RADIUS server attribute contains the rate limit information. - The default attribute is `Filter-Id`. - -.. note:: If you set a custom RADIUS attribute you must define it on both - dictionaries at RADIUS server and client. - -.. cfgcmd:: set vpn pptp remote-access authentication radius rate-limit enable - - Enables bandwidth shaping via RADIUS. - -.. cfgcmd:: set vpn pptp remote-access authentication radius rate-limit vendor - - Specifies the vendor dictionary, dictionary needs to be in - /usr/share/accel-ppp/radius. - -Received RADIUS attributes have a higher priority than parameters defined within -the CLI configuration, refer to the explanation below. - -Allocation clients ip addresses by RADIUS -========================================= - -If the RADIUS server sends the attribute ``Framed-IP-Address`` then this IP -address will be allocated to the client and the option ``default-pool`` within the CLI -config is being ignored. - -If the RADIUS server sends the attribute ``Framed-Pool``, IP address will be allocated -from a predefined IP pool whose name equals the attribute value. - -If the RADIUS server sends the attribute ``Stateful-IPv6-Address-Pool``, IPv6 address -will be allocated from a predefined IPv6 pool ``prefix`` whose name equals the attribute value. - -If the RADIUS server sends the attribute ``Delegated-IPv6-Prefix-Pool``, IPv6 -delegation pefix will be allocated from a predefined IPv6 pool ``delegate`` -whose name equals the attribute value. - -.. note:: ``Stateful-IPv6-Address-Pool`` and ``Delegated-IPv6-Prefix-Pool`` are defined in - RFC6911. If they are not defined in your RADIUS server, add new dictionary_. - -User interface can be put to VRF context via RADIUS Access-Accept packet, or change -it via RADIUS CoA. ``Accel-VRF-Name`` is used from these purposes. It is custom `ACCEL-PPP attribute`_. -Define it in your RADIUS server. - -Renaming clients interfaces by RADIUS -===================================== - -If the RADIUS server uses the attribute ``NAS-Port-Id``, ppp tunnels will be -renamed. - -.. note:: The value of the attribute ``NAS-Port-Id`` must be less than 16 - characters, otherwise the interface won't be renamed. - -**** -IPv6 -**** -.. cfgcmd:: set vpn pptp remote-access ppp-options ipv6 <require | prefer | allow | deny> - - Specifies IPv6 negotiation preference. - - * **require** - Require IPv6 negotiation - * **prefer** - Ask client for IPv6 negotiation, do not fail if it rejects - * **allow** - Negotiate IPv6 only if client requests - * **deny** - Do not negotiate IPv6 (default value) - -.. cfgcmd:: set vpn pptp remote-access client-ipv6-pool <IPv6-POOL-NAME> prefix <address> - mask <number-of-bits> - - Use this comand to set the IPv6 address pool from which an PPTP client - will get an IPv6 prefix of your defined length (mask) to terminate the - PPTP endpoint at their side. The mask length can be set from 48 to 128 - bit long, the default value is 64. - -.. cfgcmd:: set vpn pptp remote-access client-ipv6-pool <IPv6-POOL-NAME> delegate <address> - delegation-prefix <number-of-bits> - - Use this command to configure DHCPv6 Prefix Delegation (RFC3633) on - PPTP. You will have to set your IPv6 pool and the length of the - delegation prefix. From the defined IPv6 pool you will be handing out - networks of the defined length (delegation-prefix). The length of the - delegation prefix can be set from 32 to 64 bit long. - -.. cfgcmd:: set vpn pptp remote-access default-ipv6-pool <IPv6-POOL-NAME> - - Use this command to define default IPv6 address pool name. - -.. code-block:: none - - set vpn pptp remote-access ppp-options ipv6 allow - set vpn pptp remote-access client-ipv6-pool IPv6-POOL delegate '2001:db8:8003::/48' delegation-prefix '56' - set vpn pptp remote-access client-ipv6-pool IPv6-POOL prefix '2001:db8:8002::/48' mask '64' - set vpn pptp remote-access default-ipv6-pool IPv6-POOL - -IPv6 Advanced Options -===================== -.. cfgcmd:: set vpn pptp remote-access ppp-options ipv6-accept-peer-interface-id - - Accept peer interface identifier. By default is not defined. - -.. cfgcmd:: set vpn pptp remote-access ppp-options ipv6-interface-id <random | x:x:x:x> - - Specifies fixed or random interface identifier for IPv6. - By default is fixed. - - * **random** - Random interface identifier for IPv6 - * **x:x:x:x** - Specify interface identifier for IPv6 - -.. cfgcmd:: set vpn pptp remote-access ppp-options ipv6-interface-id <random | x:x:x:x> - - Specifies peer interface identifier for IPv6. By default is fixed. - - * **random** - Random interface identifier for IPv6 - * **x:x:x:x** - Specify interface identifier for IPv6 - * **ipv4-addr** - Calculate interface identifier from IPv4 address. - * **calling-sid** - Calculate interface identifier from calling-station-id. - -********* -Scripting -********* - -.. cfgcmd:: set vpn pptp remote-access extended-scripts on-change <path_to_script> - - Script to run when session interface changed by RADIUS CoA handling - -.. cfgcmd:: set vpn pptp remote-access extended-scripts on-down <path_to_script> - - Script to run when session interface going to terminate - -.. cfgcmd:: set vpn pptp remote-access extended-scripts on-pre-up <path_to_script> - - Script to run before session interface comes up - -.. cfgcmd:: set vpn pptp remote-access extended-scripts on-up <path_to_script> - - Script to run when session interface is completely configured and started - -**************** -Advanced Options -**************** - -Authentication Advanced Options -=============================== - -.. cfgcmd:: set vpn pptp remote-access authentication local-users username <user> disable - - Disable `<user>` account. - -.. cfgcmd:: set vpn pptp remote-access authentication local-users username <user> static-ip - <address> - - Assign static IP address to `<user>` account. - -.. cfgcmd:: set vpn pptp remote-access authentication local-users username <user> rate-limit - download <bandwidth> - - Download bandwidth limit in kbit/s for `<user>`. - -.. cfgcmd:: set vpn pptp remote-access authentication local-users username <user> rate-limit - upload <bandwidth> - - Upload bandwidth limit in kbit/s for `<user>`. - -.. cfgcmd:: set vpn pptp remote-access authentication protocols - <pap | chap | mschap | mschap-v2> - - Require the peer to authenticate itself using one of the following protocols: - pap, chap, mschap, mschap-v2. - -Client IP Pool Advanced Options -=============================== - -.. cfgcmd:: set vpn pptp remote-access client-ip-pool <POOL-NAME> next-pool <NEXT-POOL-NAME> - - Use this command to define the next address pool name. - -PPP Advanced Options -==================== - -.. cfgcmd:: set vpn pptp remote-access ppp-options disable-ccp - - Disable Compression Control Protocol (CCP). - CCP is enabled by default. - -.. cfgcmd:: set vpn pptp remote-access ppp-options interface-cache <number> - - Specifies number of interfaces to keep in cache. It means that don’t - destroy interface after corresponding session is destroyed, instead - place it to cache and use it later for new sessions repeatedly. - This should reduce kernel-level interface creation/deletion rate lack. - Default value is **0**. - -.. cfgcmd:: set vpn pptp remote-access ppp-options ipv4 <require | prefer | allow | deny> - - Specifies IPv4 negotiation preference. - - * **require** - Require IPv4 negotiation - * **prefer** - Ask client for IPv4 negotiation, do not fail if it rejects - * **allow** - Negotiate IPv4 only if client requests (Default value) - * **deny** - Do not negotiate IPv4 - -.. cfgcmd:: set vpn pptp remote-access ppp-options lcp-echo-failure <number> - - Defines the maximum `<number>` of unanswered echo requests. Upon reaching the - value `<number>`, the session will be reset. Default value is **3**. - -.. cfgcmd:: set vpn pptp remote-access ppp-options lcp-echo-interval <interval> - - If this option is specified and is greater than 0, then the PPP module will - send LCP pings of the echo request every `<interval>` seconds. - Default value is **30**. - -.. cfgcmd:: set vpn pptp remote-access ppp-options lcp-echo-timeout - - Specifies timeout in seconds to wait for any peer activity. If this option - specified it turns on adaptive lcp echo functionality and "lcp-echo-failure" - is not used. Default value is **0**. - -.. cfgcmd:: set vpn pptp remote-access ppp-options min-mtu <number> - - Defines minimum acceptable MTU. If client will try to negotiate less then - specified MTU then it will be NAKed or disconnected if rejects greater MTU. - Default value is **100**. - -.. cfgcmd:: set vpn pptp remote-access ppp-options mppe <require | prefer | deny> - - Specifies :abbr:`MPPE (Microsoft Point-to-Point Encryption)` negotiation - preference. - - * **require** - ask client for mppe, if it rejects drop connection - * **prefer** - ask client for mppe, if it rejects don't fail. (Default value) - * **deny** - deny mppe - - Default behavior - don't ask client for mppe, but allow it if client wants. - Please note that RADIUS may override this option by MS-MPPE-Encryption-Policy - attribute. - -.. cfgcmd:: set vpn pptp remote-access ppp-options mru <number> - - Defines preferred MRU. By default is not defined. - -Global Advanced options -======================= - -.. cfgcmd:: set vpn pptp remote-access description <description> - - Set description. - -.. cfgcmd:: set vpn pptp remote-access limits burst <value> - - Burst count - -.. cfgcmd:: set vpn pptp remote-access limits connection-limit <value> - - Acceptable rate of connections (e.g. 1/min, 60/sec) - -.. cfgcmd:: set vpn pptp remote-access limits timeout <value> - - Timeout in seconds - -.. cfgcmd:: set vpn pptp remote-access mtu - - Maximum Transmission Unit (MTU) (default: **1436**) - -.. cfgcmd:: set vpn pptp remote-access max-concurrent-sessions - - Maximum number of concurrent session start attempts - -.. cfgcmd:: set vpn pptp remote-access name-server <address> - - Connected client should use `<address>` as their DNS server. This - command accepts both IPv4 and IPv6 addresses. Up to two nameservers - can be configured for IPv4, up to three for IPv6. - -.. cfgcmd:: set vpn pptp remote-access shaper fwmark <1-2147483647> - - Match firewall mark value - -.. cfgcmd:: set vpn pptp remote-access snmp master-agent - - Enable SNMP - -.. cfgcmd:: set vpn pptp remote-access wins-server <address> - - Windows Internet Name Service (WINS) servers propagated to client - -********** -Monitoring -********** - -.. opcmd:: show pptp-server sessions - - Use this command to locally check the active sessions in the PPTP - server. - -.. code-block:: none - - vyos@vyos:~$ show pptp-server sessions - ifname | username | ip | ip6 | ip6-dp | calling-sid | rate-limit | state | uptime | rx-bytes | tx-bytes - --------+----------+----------+-----+--------+----------------+------------+--------+----------+----------+---------- - pptp0 | test | 10.0.0.2 | | | 192.168.10.100 | | active | 00:01:26 | 6.9 KiB | 220 B - -.. code-block:: none - - vyos@vyos:~$ show pptp-server statistics - uptime: 0.00:04:52 - cpu: 0% - mem(rss/virt): 5504/100176 kB - core: - mempool_allocated: 152007 - mempool_available: 149007 - thread_count: 1 - thread_active: 1 - context_count: 6 - context_sleeping: 0 - context_pending: 0 - md_handler_count: 6 - md_handler_pending: 0 - timer_count: 2 - timer_pending: 0 - sessions: - starting: 0 - active: 1 - finishing: 0 - pptp: - starting: 0 - active: 1 - -*************** -Troubleshooting -*************** - -.. code-block:: none - - vyos@vyos:~$sudo journalctl -u accel-ppp@pptp -b 0 - - Feb 29 14:58:57 vyos accel-pptp[4629]: pptp: new connection from 192.168.10.100 - Feb 29 14:58:57 vyos accel-pptp[4629]: :: recv [PPTP Start-Ctrl-Conn-Request <Version 1> <Framing 1> <Bearer 1> <Max-Chan 0>] - Feb 29 14:58:57 vyos accel-pptp[4629]: :: send [PPTP Start-Ctrl-Conn-Reply <Version 1> <Result 1> <Error 0> <Framing 3> <Bearer 3> <Max-Chan 1>] - Feb 29 14:58:57 vyos accel-pptp[4629]: :: recv [PPTP Outgoing-Call-Request <Call-ID 2961> <Call-Serial 2> <Min-BPS 300> <Max-BPS 100000000> <Bearer 3> <Framing 3> <Window-Size 64> <Delay 0>] - Feb 29 14:58:57 vyos accel-pptp[4629]: :: send [PPTP Outgoing-Call-Reply <Call-ID 2> <Peer-Call-ID 2961> <Result 1> <Error 0> <Cause 0> <Speed 100000000> <Window-Size 64> <Delay 0> <Channel 0>] - Feb 29 14:58:57 vyos accel-pptp[4629]: :: lcp_layer_init - Feb 29 14:58:57 vyos accel-pptp[4629]: :: auth_layer_init - Feb 29 14:58:57 vyos accel-pptp[4629]: :: ccp_layer_init - Feb 29 14:58:57 vyos accel-pptp[4629]: :: ipcp_layer_init - Feb 29 14:58:57 vyos accel-pptp[4629]: :: ipv6cp_layer_init - Feb 29 14:58:57 vyos accel-pptp[4629]: :: ppp establishing - Feb 29 14:58:57 vyos accel-pptp[4629]: :: lcp_layer_start - Feb 29 14:58:57 vyos accel-pptp[4629]: :: send [LCP ConfReq id=75 <auth PAP> <mru 1436> <magic 483920bd>] - Feb 29 14:58:57 vyos accel-pptp[4629]: :: recv [PPTP Set-Link-Info] - Feb 29 14:58:57 vyos accel-pptp[4629]: :: recv [LCP ConfReq id=0 <mru 1400> <magic 0142785a> <pcomp> <accomp> < d 3 6 >] - Feb 29 14:58:57 vyos accel-pptp[4629]: :: send [LCP ConfRej id=0 <pcomp> <accomp> < d 3 6 >] - Feb 29 14:58:57 vyos accel-pptp[4629]: :: recv [LCP ConfReq id=1 <mru 1400> <magic 0142785a>] - Feb 29 14:58:57 vyos accel-pptp[4629]: :: send [LCP ConfAck id=1] - Feb 29 14:59:00 vyos accel-pptp[4629]: :: fsm timeout 9 - Feb 29 14:59:00 vyos accel-pptp[4629]: :: send [LCP ConfReq id=75 <auth PAP> <mru 1436> <magic 483920bd>] - Feb 29 14:59:00 vyos accel-pptp[4629]: :: recv [LCP ConfNak id=75 <auth MSCHAP-v2>] - Feb 29 14:59:00 vyos accel-pptp[4629]: :: send [LCP ConfReq id=76 <auth CHAP-md5> <mru 1436> <magic 483920bd>] - Feb 29 14:59:00 vyos accel-pptp[4629]: :: recv [LCP ConfNak id=76 <auth MSCHAP-v2>] - Feb 29 14:59:00 vyos accel-pptp[4629]: :: send [LCP ConfReq id=77 <auth MSCHAP-v1> <mru 1436> <magic 483920bd>] - Feb 29 14:59:00 vyos accel-pptp[4629]: :: recv [LCP ConfNak id=77 <auth MSCHAP-v2>] - Feb 29 14:59:00 vyos accel-pptp[4629]: :: send [LCP ConfReq id=78 <auth MSCHAP-v2> <mru 1436> <magic 483920bd>] - Feb 29 14:59:00 vyos accel-pptp[4629]: :: recv [LCP ConfAck id=78 <auth MSCHAP-v2> <mru 1436> <magic 483920bd>] - Feb 29 14:59:00 vyos accel-pptp[4629]: :: lcp_layer_started - Feb 29 14:59:00 vyos accel-pptp[4629]: :: auth_layer_start - Feb 29 14:59:00 vyos accel-pptp[4629]: :: send [MSCHAP-v2 Challenge id=1 <8aa758781676e6a8e85c11963ee010>] - Feb 29 14:59:00 vyos accel-pptp[4629]: :: recv [LCP Ident id=2 <MSRASV5.20>] - Feb 29 14:59:00 vyos accel-pptp[4629]: :: recv [LCP Ident id=3 <MSRAS-0-MSEDGEWIN10>] - Feb 29 14:59:00 vyos accel-pptp[4629]: [43B blob data] - Feb 29 14:59:00 vyos accel-pptp[4629]: :: recv [PPTP Set-Link-Info] - Feb 29 14:59:00 vyos accel-pptp[4629]: :: recv [MSCHAP-v2 Response id=1 <90c21af1091f745e8bf22388b058>, <e695ae5aae274c88a3fa1ee3dc9057aece4d53c87b9fea>, F=0, name="test"] - Feb 29 14:59:00 vyos accel-pptp[4629]: ppp0:test: connect: ppp0 <--> pptp(192.168.10.100) - Feb 29 14:59:00 vyos accel-pptp[4629]: ppp0:test: ppp connected - Feb 29 14:59:00 vyos accel-pptp[4629]: ppp0:test: send [MSCHAP-v2 Success id=1 "S=347F417CF04BEBBC7F75CFA7F43474C36FB218F9 M=Authentication succeeded"] - Feb 29 14:59:00 vyos accel-pptp[4629]: ppp0:test: test: authentication succeeded - Feb 29 14:59:00 vyos accel-pptp[4629]: ppp0:test: auth_layer_started - Feb 29 14:59:00 vyos accel-pptp[4629]: ppp0:test: ccp_layer_start - Feb 29 14:59:00 vyos accel-pptp[4629]: ppp0:test: send [CCP ConfReq id=b9 <mppe +H -M +S -L -D -C>] - Feb 29 14:59:00 vyos accel-pptp[4629]: ppp0:test: ipcp_layer_start - Feb 29 14:59:00 vyos accel-pptp[4629]: ppp0:test: ipv6cp_layer_start - Feb 29 14:59:00 vyos accel-pptp[4629]: ppp0:test: IPV6CP: discarding packet - Feb 29 14:59:00 vyos accel-pptp[4629]: ppp0:test: send [LCP ProtoRej id=122 <8057>] - Feb 29 14:59:00 vyos accel-pptp[4629]: ppp0:test: recv [IPCP ConfReq id=6 <addr 0.0.0.0> <dns1 0.0.0.0> <wins1 0.0.0.0> <dns2 0.0.0.0> <wins2 0.0.0.0>] - Feb 29 14:59:00 vyos accel-pptp[4629]: ppp0:test: send [IPCP ConfReq id=3b <addr 10.0.0.1>] - Feb 29 14:59:00 vyos accel-pptp[4629]: ppp0:test: send [IPCP ConfRej id=6 <dns1 0.0.0.0> <wins1 0.0.0.0> <dns2 0.0.0.0> <wins2 0.0.0.0>] - Feb 29 14:59:00 vyos accel-pptp[4629]: ppp0:test: recv [LCP ProtoRej id=7 <80fd>] - Feb 29 14:59:00 vyos accel-pptp[4629]: ppp0:test: ccp_layer_finished - Feb 29 14:59:00 vyos accel-pptp[4629]: ppp0:test: recv [IPCP ConfAck id=3b <addr 10.0.0.1>] - Feb 29 14:59:00 vyos accel-pptp[4629]: ppp0:test: recv [IPCP ConfReq id=8 <addr 0.0.0.0>] - Feb 29 14:59:00 vyos accel-pptp[4629]: ppp0:test: send [IPCP ConfNak id=8 <addr 10.0.0.2>] - Feb 29 14:59:00 vyos accel-pptp[4629]: ppp0:test: recv [IPCP ConfReq id=9 <addr 10.0.0.2>] - Feb 29 14:59:00 vyos accel-pptp[4629]: ppp0:test: send [IPCP ConfAck id=9] - Feb 29 14:59:00 vyos accel-pptp[4629]: ppp0:test: ipcp_layer_started - Feb 29 14:59:00 vyos accel-pptp[4629]: ppp0:test: rename interface to 'pptp0' - Feb 29 14:59:00 vyos accel-pptp[4629]: pptp0:test: pptp: ppp started - -.. _accel-ppp: https://accel-ppp.org/ -.. _dictionary: https://github.com/accel-ppp/accel-ppp/blob/master/accel-pppd/radius/dict/dictionary.rfc6911 -.. _`ACCEL-PPP attribute`: https://github.com/accel-ppp/accel-ppp/blob/master/accel-pppd/radius/dict/dictionary.accel diff --git a/docs/configuration/vpn/rst-rsa-keys.rst b/docs/configuration/vpn/rst-rsa-keys.rst deleted file mode 100644 index e7584563..00000000 --- a/docs/configuration/vpn/rst-rsa-keys.rst +++ /dev/null @@ -1,123 +0,0 @@ - -######## -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. - -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 - Enter private key type: [rsa, dsa, ec] (Default: rsa) - Enter private key bits: (Default: 2048) - Note: If you plan to use the generated key on this router, do not encrypt the private key. - Do you want to encrypt the private key with a passphrase? [y/N] N - Configure mode commands to install key pair: - Do you want to install the public key? [Y/n] Y - set pki key-pair ipsec-LEFT public key 'MIIBIjANBgkqh...' - Do you want to install the private key? [Y/n] Y - set pki key-pair ipsec-LEFT private key 'MIIEvgIBADAN...' - [edit] - -.. start_vyoslinter - -Configuration commands will display. -Note the command with the public key -(set pki key-pair ipsec-LEFT public key 'MIIBIjANBgkqh...'). -Then do the same on the opposite router: - -.. code-block:: none - - vyos@left# run generate pki key-pair install ipsec-RIGHT - -Note the command with the public key -(set pki key-pair ipsec-RIGHT public key 'FAAOCAQ8AMII...'). - -The noted public keys should be entered on the opposite routers. - -On the LEFT: - -.. code-block:: none - - set pki key-pair ipsec-RIGHT public key 'FAAOCAQ8AMII...' - -On the RIGHT: - -.. code-block:: none - - set pki key-pair ipsec-LEFT public key 'MIIBIjANBgkqh...' - -Now you are ready to setup IPsec. The key points: - -1. Since both routers do not know their effective public addresses, - we set the local-address of the peer to "any". -2. On the initiator, we set the peer address to its public address, - but on the responder we only set the id. -3. On the initiator, we need to set the remote-id option so that it - can identify IKE traffic from the responder correctly. -4. On the responder, we need to set the local id so that initiator - can know who's talking to it for the point #3 to work. - -On the LEFT (static address): - -.. stop_vyoslinter - -.. code-block:: none - - set vpn ipsec interface eth0 - - set vpn ipsec esp-group MyESPGroup proposal 1 encryption aes128 - set vpn ipsec esp-group MyESPGroup proposal 1 hash sha1 - - set vpn ipsec ike-group MyIKEGroup proposal 1 dh-group 2 - set vpn ipsec ike-group MyIKEGroup proposal 1 encryption aes128 - set vpn ipsec ike-group MyIKEGroup proposal 1 hash sha1 - - set vpn ipsec site-to-site peer @RIGHT authentication id LEFT - set vpn ipsec site-to-site peer @RIGHT authentication mode rsa - set vpn ipsec site-to-site peer @RIGHT authentication rsa local-key ipsec-LEFT - set vpn ipsec site-to-site peer @RIGHT authentication rsa remote-key ipsec-RIGHT - set vpn ipsec site-to-site peer @RIGHT authentication remote-id RIGHT - set vpn ipsec site-to-site peer @RIGHT default-esp-group MyESPGroup - set vpn ipsec site-to-site peer @RIGHT ike-group MyIKEGroup - set vpn ipsec site-to-site peer @RIGHT local-address 192.0.2.10 - set vpn ipsec site-to-site peer @RIGHT connection-type none - set vpn ipsec site-to-site peer @RIGHT tunnel 1 local prefix 192.168.99.1/32 # Additional loopback address on the local - set vpn ipsec site-to-site peer @RIGHT tunnel 1 remote prefix 192.168.99.2/32 # Additional loopback address on the remote - -On the RIGHT (dynamic address): - -.. code-block:: none - - set vpn ipsec interface eth0 - - set vpn ipsec esp-group MyESPGroup proposal 1 encryption aes128 - set vpn ipsec esp-group MyESPGroup proposal 1 hash sha1 - - set vpn ipsec ike-group MyIKEGroup proposal 1 dh-group 2 - set vpn ipsec ike-group MyIKEGroup proposal 1 encryption aes128 - set vpn ipsec ike-group MyIKEGroup proposal 1 hash sha1 - - set vpn ipsec site-to-site peer 192.0.2.10 authentication id RIGHT - set vpn ipsec site-to-site peer 192.0.2.10 authentication mode rsa - set vpn ipsec site-to-site peer 192.0.2.10 authentication rsa local-key ipsec-RIGHT - set vpn ipsec site-to-site peer 192.0.2.10 authentication rsa remote-key ipsec-LEFT - set vpn ipsec site-to-site peer 192.0.2.10 authentication remote-id LEFT - set vpn ipsec site-to-site peer 192.0.2.10 connection-type initiate - set vpn ipsec site-to-site peer 192.0.2.10 default-esp-group MyESPGroup - set vpn ipsec site-to-site peer 192.0.2.10 ike-group MyIKEGroup - set vpn ipsec site-to-site peer 192.0.2.10 local-address any - set vpn ipsec site-to-site peer 192.0.2.10 tunnel 1 local prefix 192.168.99.2/32 # Additional loopback address on the local - set vpn ipsec site-to-site peer 192.0.2.10 tunnel 1 remote prefix 192.168.99.1/32 # Additional loopback address on the remote - -.. start_vyoslinter diff --git a/docs/configuration/vpn/rst-sstp.rst b/docs/configuration/vpn/rst-sstp.rst deleted file mode 100644 index b65aecca..00000000 --- a/docs/configuration/vpn/rst-sstp.rst +++ /dev/null @@ -1,658 +0,0 @@ -.. _sstp: - -########### -SSTP Server -########### - -:abbr:`SSTP (Secure Socket Tunneling Protocol)` is a form of :abbr:`VPN -(Virtual Private Network)` tunnel that provides a mechanism to transport PPP -traffic through an SSL/TLS channel. SSL/TLS provides transport-level security -with key negotiation, encryption and traffic integrity checking. The use of -SSL/TLS over TCP port 443 allows SSTP to pass through virtually all firewalls -and proxy servers except for authenticated web proxies. - -SSTP is available for Linux, BSD, and Windows. - -VyOS utilizes accel-ppp_ to provide SSTP server functionality. We support both -local and RADIUS authentication. - -As SSTP provides PPP via a SSL/TLS channel the use of either publicly signed -certificates or private PKI is required. - -*********************** -Configuring SSTP Server -*********************** - -Certificates -============ - -Using our documentation chapter - :ref:`pki` generate and install CA and Server certificate - -.. code-block:: none - - vyos@vyos:~$ generate pki ca install CA - -.. code-block:: none - - vyos@vyos:~$ generate pki certificate sign CA install Server - -Configuration -============= -.. code-block:: none - - set vpn sstp authentication local-users username test password 'test' - set vpn sstp authentication mode 'local' - set vpn sstp client-ip-pool SSTP-POOL range '10.0.0.2-10.0.0.100' - set vpn sstp default-pool 'SSTP-POOL' - set vpn sstp gateway-address '10.0.0.1' - set vpn sstp ssl ca-certificate 'CA1' - set vpn sstp ssl certificate 'Server' - -.. cfgcmd:: set vpn sstp authentication mode <local | radius> - - Set authentication backend. The configured authentication backend is used - for all queries. - - * **radius**: All authentication queries are handled by a configured RADIUS - server. - * **local**: All authentication queries are handled locally. - -.. cfgcmd:: set vpn sstp authentication local-users username <user> password - <pass> - - Create `<user>` for local authentication on this system. The users password - will be set to `<pass>`. - -.. cfgcmd:: set vpn sstp client-ip-pool <POOL-NAME> range <x.x.x.x-x.x.x.x | x.x.x.x/x> - - Use this command to define the first IP address of a pool of - addresses to be given to SSTP clients. If notation ``x.x.x.x-x.x.x.x``, - it must be within a /24 subnet. If notation ``x.x.x.x/x`` is - used there is possibility to set host/netmask. - -.. cfgcmd:: set vpn sstp default-pool <POOL-NAME> - - Use this command to define default address pool name. - -.. cfgcmd:: set vpn sstp gateway-address <gateway> - - Specifies single `<gateway>` IP address to be used as local address of PPP - interfaces. - -.. cfgcmd:: set vpn sstp ssl ca-certificate <file> - - Name of installed certificate authority certificate. - -.. cfgcmd:: set vpn sstp ssl certificate <file> - - Name of installed server certificate. - -********************************* -Configuring RADIUS authentication -********************************* - -To enable RADIUS based authentication, the authentication mode needs to be -changed within the configuration. Previous settings like the local users still -exist within the configuration, however they are not used if the mode has been -changed from local to radius. Once changed back to local, it will use all local -accounts again. - -.. code-block:: none - - set vpn sstp authentication mode radius - -.. cfgcmd:: set vpn sstp authentication radius server <server> key <secret> - - Configure RADIUS `<server>` and its required shared `<secret>` for - communicating with the RADIUS server. - -Since the RADIUS server would be a single point of failure, multiple RADIUS -servers can be setup and will be used subsequentially. -For example: - -.. code-block:: none - - set vpn sstp authentication radius server 10.0.0.1 key 'foo' - set vpn sstp authentication radius server 10.0.0.2 key 'foo' - -.. note:: Some RADIUS severs use an access control list which allows or denies - queries, make sure to add your VyOS router to the allowed client list. - -RADIUS source address -===================== - -If you are using OSPF as your IGP, use the interface connected closest to the -RADIUS server. You can bind all outgoing RADIUS requests to a single source IP -e.g. the loopback interface. - -.. cfgcmd:: set vpn sstp authentication radius source-address <address> - - Source IPv4 address used in all RADIUS server queires. - -.. note:: The ``source-address`` must be configured to that of an interface. - Best practice would be a loopback or dummy interface. - -RADIUS advanced options -======================= - -.. cfgcmd:: set vpn sstp authentication radius server <server> port <port> - - Configure RADIUS `<server>` and its required port for authentication requests. - -.. cfgcmd:: set vpn sstp authentication radius server <server> fail-time <time> - - Mark RADIUS server as offline for this given `<time>` in seconds. - -.. cfgcmd:: set vpn sstp authentication radius server <server> disable - - Temporary disable this RADIUS server. - -.. cfgcmd:: set vpn sstp authentication radius acct-timeout <timeout> - - Timeout to wait reply for Interim-Update packets. (default 3 seconds) - -.. cfgcmd:: set vpn sstp authentication radius dynamic-author server <address> - - Specifies IP address for Dynamic Authorization Extension server (DM/CoA). - This IP must exist on any VyOS interface or it can be ``0.0.0.0``. - -.. cfgcmd:: set vpn sstp authentication radius dynamic-author port <port> - - UDP port for Dynamic Authorization Extension server (DM/CoA) - -.. cfgcmd:: set vpn sstp authentication radius dynamic-author key <secret> - - Secret for Dynamic Authorization Extension server (DM/CoA) - -.. cfgcmd:: set vpn sstp authentication radius max-try <number> - - Maximum number of tries to send Access-Request/Accounting-Request queries - -.. cfgcmd:: set vpn sstp authentication radius timeout <timeout> - - Timeout to wait response from server (seconds) - -.. cfgcmd:: set vpn sstp authentication radius nas-identifier <identifier> - - Value to send to RADIUS server in NAS-Identifier attribute and to be matched - in DM/CoA requests. - -.. cfgcmd:: set vpn sstp authentication radius nas-ip-address <address> - - Value to send to RADIUS server in NAS-IP-Address attribute and to be matched - in DM/CoA requests. Also DM/CoA server will bind to that address. - -.. cfgcmd:: set vpn sstp authentication radius source-address <address> - - Source IPv4 address used in all RADIUS server queires. - -.. cfgcmd:: set vpn sstp authentication radius rate-limit attribute <attribute> - - Specifies which RADIUS server attribute contains the rate limit information. - The default attribute is `Filter-Id`. - -.. note:: If you set a custom RADIUS attribute you must define it on both - dictionaries on the RADIUS server and client. - -.. cfgcmd:: set vpn sstp authentication radius rate-limit enable - - Enables bandwidth shaping via RADIUS. - -.. cfgcmd:: set vpn sstp authentication radius rate-limit vendor - - Specifies the vendor dictionary, This dictionary needs to be present in - /usr/share/accel-ppp/radius. - -Received RADIUS attributes have a higher priority than parameters defined within -the CLI configuration, refer to the explanation below. - -Allocation clients ip addresses by RADIUS -========================================= - -If the RADIUS server sends the attribute ``Framed-IP-Address`` then this IP -address will be allocated to the client and the option ``default-pool`` within -the CLI config will being ignored. - -If the RADIUS server sends the attribute ``Framed-Pool``, then the IP address -will be allocated from a predefined IP pool whose name equals the attribute -value. - -If the RADIUS server sends the attribute ``Stateful-IPv6-Address-Pool``, the -IPv6 address will be allocated from a predefined IPv6 pool ``prefix`` whose -name equals the attribute value. - -If the RADIUS server sends the attribute ``Delegated-IPv6-Prefix-Pool``, an -IPv6 delegation prefix will be allocated from a predefined IPv6 pool ``delegate`` -whose name equals the attribute value. - -.. note:: ``Stateful-IPv6-Address-Pool`` and ``Delegated-IPv6-Prefix-Pool`` are defined in - RFC6911. If they are not defined in your RADIUS server, add new dictionary_. - -The client's interface can be put into a VRF context via a RADIUS Access-Accept -packet, or changed via RADIUS CoA. ``Accel-VRF-Name`` is used for these -purposes. This is a custom `ACCEL-PPP attribute`_. Define it in your RADIUS -server. - -Renaming clients interfaces by RADIUS -===================================== - -If the RADIUS server uses the attribute ``NAS-Port-Id``, ppp tunnels will be -renamed. - -.. note:: The value of the attribute ``NAS-Port-Id`` must be less than 16 - characters, otherwise the interface won't be renamed. - - -**** -IPv6 -**** -.. cfgcmd:: set vpn sstp ppp-options ipv6 <require | prefer | allow | deny> - - Specifies IPv6 negotiation preference. - - * **require** - Require IPv6 negotiation - * **prefer** - Ask client for IPv6 negotiation, do not fail if it rejects - * **allow** - Negotiate IPv6 only if client requests - * **deny** - Do not negotiate IPv6 (default value) - -.. cfgcmd:: set vpn sstp client-ipv6-pool <IPv6-POOL-NAME> prefix <address> - mask <number-of-bits> - - Use this comand to set the IPv6 address pool from which an SSTP client will - get an IPv6 prefix of your defined length (mask) to terminate the SSTP - endpoint at their side. The mask length can be set between 48 and 128 bits - long, the default value is 64. - -.. cfgcmd:: set vpn sstp client-ipv6-pool <IPv6-POOL-NAME> delegate <address> - delegation-prefix <number-of-bits> - - Use this command to configure DHCPv6 Prefix Delegation (RFC3633) on SSTP. You - will have to set your IPv6 pool and the length of the delegation prefix. From - the defined IPv6 pool you will be handing out networks of the defined length - (delegation-prefix). The length of the delegation prefix can be set between - 32 and 64 bits long. - -.. cfgcmd:: set vpn sstp default-ipv6-pool <IPv6-POOL-NAME> - - Use this command to define default IPv6 address pool name. - -.. code-block:: none - - set vpn sstp ppp-options ipv6 allow - set vpn sstp client-ipv6-pool IPv6-POOL delegate '2001:db8:8003::/48' delegation-prefix '56' - set vpn sstp client-ipv6-pool IPv6-POOL prefix '2001:db8:8002::/48' mask '64' - set vpn sstp default-ipv6-pool IPv6-POOL - -IPv6 Advanced Options -===================== -.. cfgcmd:: set vpn sstp ppp-options ipv6-accept-peer-interface-id - - Accept peer interface identifier. By default this is not defined. - -.. cfgcmd:: set vpn sstp ppp-options ipv6-interface-id <random | x:x:x:x> - - Specifies if a fixed or random interface identifier is used for IPv6. The - default is fixed. - - * **random** - Random interface identifier for IPv6 - * **x:x:x:x** - Specify interface identifier for IPv6 - -.. cfgcmd:: set vpn sstp ppp-options ipv6-interface-id <random | x:x:x:x> - - Specifies the peer interface identifier for IPv6. The default is fixed. - - * **random** - Random interface identifier for IPv6 - * **x:x:x:x** - Specify interface identifier for IPv6 - * **ipv4-addr** - Calculate interface identifier from IPv4 address. - * **calling-sid** - Calculate interface identifier from calling-station-id. - -********* -Scripting -********* - -.. cfgcmd:: set vpn sstp extended-scripts on-change <path_to_script> - - Script to run when the session interface is changed by RADIUS CoA handling - -.. cfgcmd:: set vpn sstp extended-scripts on-down <path_to_script> - - Script to run when the session interface about to terminate - -.. cfgcmd:: set vpn sstp extended-scripts on-pre-up <path_to_script> - - Script to run before the session interface comes up - -.. cfgcmd:: set vpn sstp extended-scripts on-up <path_to_script> - - Script to run when the session interface is completely configured and started - -**************** -Advanced Options -**************** - -Authentication Advanced Options -=============================== - -.. cfgcmd:: set vpn sstp authentication local-users username <user> disable - - Disable `<user>` account. - -.. cfgcmd:: set vpn sstp authentication local-users username <user> static-ip - <address> - - Assign a static IP address to `<user>` account. - -.. cfgcmd:: set vpn sstp authentication local-users username <user> rate-limit - download <bandwidth> - - Rate limit the download bandwidth for `<user>` to `<bandwidth>` kbit/s. - -.. cfgcmd:: set vpn sstp authentication local-users username <user> rate-limit - upload <bandwidth> - - Rate limit the upload bandwidth for `<user>` to `<bandwidth>` kbit/s. - -.. cfgcmd:: set vpn sstp authentication protocols - <pap | chap | mschap | mschap-v2> - - Require the peer to authenticate itself using one of the following protocols: - pap, chap, mschap, mschap-v2. - -Client IP Pool Advanced Options -=============================== - -.. cfgcmd:: set vpn sstp client-ip-pool <POOL-NAME> next-pool <NEXT-POOL-NAME> - - Use this command to define the next address pool name. - -PPP Advanced Options -==================== - -.. cfgcmd:: set vpn sstp ppp-options disable-ccp - - Disable Compression Control Protocol (CCP). - CCP is enabled by default. - -.. cfgcmd:: set vpn sstp ppp-options interface-cache <number> - - Specifies number of interfaces to cache. This prevents interfaces from being - removed once the corresponding session is destroyed. Instead, interfaces are - cached for later use in new sessions. This should reduce the kernel-level - interface creation/deletion rate. - Default value is **0**. - -.. cfgcmd:: set vpn sstp ppp-options ipv4 <require | prefer | allow | deny> - - Specifies IPv4 negotiation preference. - - * **require** - Require IPv4 negotiation - * **prefer** - Ask client for IPv4 negotiation, do not fail if it rejects - * **allow** - Negotiate IPv4 only if client requests (Default value) - * **deny** - Do not negotiate IPv4 - -.. cfgcmd:: set vpn sstp ppp-options lcp-echo-failure <number> - - Defines the maximum `<number>` of unanswered echo requests. Upon reaching the - value `<number>`, the session will be reset. Default value is **3**. - -.. cfgcmd:: set vpn sstp ppp-options lcp-echo-interval <interval> - - If this option is specified and is greater than 0, then the PPP module will - send LCP echo requests every `<interval>` seconds. - Default value is **30**. - -.. cfgcmd:: set vpn sstp ppp-options lcp-echo-timeout - - Specifies timeout in seconds to wait for any peer activity. If this option is - specified it turns on adaptive lcp echo functionality and "lcp-echo-failure" - is not used. Default value is **0**. - -.. cfgcmd:: set vpn sstp ppp-options min-mtu <number> - - Defines the minimum acceptable MTU. If a client tries to negotiate an MTU - lower than this it will be NAKed, and disconnected if it rejects a greater - MTU. - Default value is **100**. - -.. cfgcmd:: set vpn sstp ppp-options mppe <require | prefer | deny> - - Specifies :abbr:`MPPE (Microsoft Point-to-Point Encryption)` negotiation - preference. - - * **require** - ask client for mppe, if it rejects drop connection - * **prefer** - ask client for mppe, if it rejects don't fail. (Default value) - * **deny** - deny mppe - - Default behavior - don't ask the client for mppe, but allow it if the client - wants. - Please note that RADIUS may override this option by MS-MPPE-Encryption-Policy - attribute. - -.. cfgcmd:: set vpn sstp ppp-options mru <number> - - Defines preferred MRU. By default is not defined. - -Global Advanced options -======================= - -.. cfgcmd:: set vpn sstp description <description> - - Set description. - -.. cfgcmd:: set vpn sstp limits burst <value> - - Burst count - -.. cfgcmd:: set vpn sstp limits connection-limit <value> - - Maximum accepted connection rate (e.g. 1/min, 60/sec) - -.. cfgcmd:: set vpn sstp limits timeout <value> - - Timeout in seconds - -.. cfgcmd:: set vpn sstp mtu - - Maximum Transmission Unit (MTU) (default: **1500**) - -.. cfgcmd:: set vpn sstp max-concurrent-sessions - - Maximum number of concurrent session start attempts - -.. cfgcmd:: set vpn sstp name-server <address> - - Connected clients should use `<address>` as their DNS server. This command - accepts both IPv4 and IPv6 addresses. Up to two nameservers can be configured - for IPv4, up to three for IPv6. - -.. cfgcmd:: set vpn sstp shaper fwmark <1-2147483647> - - Match firewall mark value - -.. cfgcmd:: set vpn sstp snmp master-agent - - Enable SNMP - -.. cfgcmd:: set vpn sstp wins-server <address> - - Windows Internet Name Service (WINS) servers propagated to client - -.. cfgcmd:: set vpn sstp host-name <hostname> - - If this option is given, only SSTP connections to the specified host - and with the same TLS SNI will be allowed. - -*********************** -Configuring SSTP client -*********************** - -Once you have setup your SSTP server there comes the time to do some basic -testing. The Linux client used for testing is called sstpc_. sstpc_ requires a -PPP configuration/peer file. - -If you use a self-signed certificate, do not forget to install CA on the client side. - -The following PPP configuration tests MSCHAP-v2: - -.. code-block:: none - - $ cat /etc/ppp/peers/vyos - usepeerdns - #require-mppe - #require-pap - require-mschap-v2 - noauth - lock - refuse-pap - refuse-eap - refuse-chap - refuse-mschap - #refuse-mschap-v2 - nobsdcomp - nodeflate - debug - - -You can now "dial" the peer with the follwoing command: ``sstpc --log-level 4 ---log-stderr --user vyos --password vyos vpn.example.com -- call vyos``. - -A connection attempt will be shown as: - -.. code-block:: none - - $ sstpc --log-level 4 --log-stderr --user vyos --password vyos vpn.example.com -- call vyos - - Mar 22 13:29:12 sstpc[12344]: Resolved vpn.example.com to 192.0.2.1 - Mar 22 13:29:12 sstpc[12344]: Connected to vpn.example.com - Mar 22 13:29:12 sstpc[12344]: Sending Connect-Request Message - Mar 22 13:29:12 sstpc[12344]: SEND SSTP CRTL PKT(14) - Mar 22 13:29:12 sstpc[12344]: TYPE(1): CONNECT REQUEST, ATTR(1): - Mar 22 13:29:12 sstpc[12344]: ENCAP PROTO(1): 6 - Mar 22 13:29:12 sstpc[12344]: RECV SSTP CRTL PKT(48) - Mar 22 13:29:12 sstpc[12344]: TYPE(2): CONNECT ACK, ATTR(1): - Mar 22 13:29:12 sstpc[12344]: CRYPTO BIND REQ(4): 40 - Mar 22 13:29:12 sstpc[12344]: Started PPP Link Negotiation - Mar 22 13:29:15 sstpc[12344]: Sending Connected Message - Mar 22 13:29:15 sstpc[12344]: SEND SSTP CRTL PKT(112) - Mar 22 13:29:15 sstpc[12344]: TYPE(4): CONNECTED, ATTR(1): - Mar 22 13:29:15 sstpc[12344]: CRYPTO BIND(3): 104 - Mar 22 13:29:15 sstpc[12344]: Connection Established - - $ ip addr show ppp0 - 164: ppp0: <POINTOPOINT,MULTICAST,NOARP,UP,LOWER_UP> mtu 1452 qdisc fq_codel state UNKNOWN group default qlen 3 - link/ppp promiscuity 0 - inet 100.64.2.2 peer 100.64.1.1/32 scope global ppp0 - valid_lft forever preferred_lft forever - -********** -Monitoring -********** - -.. opcmd:: show sstp-server sessions - - Use this command to locally check the active sessions in the SSTP - server. - -.. code-block:: none - - vyos@vyos:~$ show sstp-server sessions - ifname | username | ip | ip6 | ip6-dp | calling-sid | rate-limit | state | uptime | rx-bytes | tx-bytes - --------+----------+----------+-----+--------+----------------+------------+--------+----------+----------+---------- - sstp0 | test | 10.0.0.2 | | | 192.168.10.100 | | active | 00:15:46 | 16.3 KiB | 210 B - -.. code-block:: none - - vyos@vyos:~$ show sstp-server statistics - uptime: 0.01:21:54 - cpu: 0% - mem(rss/virt): 6688/100464 kB - core: - mempool_allocated: 149420 - mempool_available: 146092 - thread_count: 1 - thread_active: 1 - context_count: 6 - context_sleeping: 0 - context_pending: 0 - md_handler_count: 7 - md_handler_pending: 0 - timer_count: 2 - timer_pending: 0 - sessions: - starting: 0 - active: 1 - finishing: 0 - sstp: - starting: 0 - active: 1 - -*************** -Troubleshooting -*************** - -.. code-block:: none - - vyos@vyos:~$sudo journalctl -u accel-ppp@sstp -b 0 - - Feb 28 17:03:04 vyos accel-sstp[2492]: sstp: new connection from 192.168.10.100:49852 - Feb 28 17:03:04 vyos accel-sstp[2492]: sstp: starting - Feb 28 17:03:04 vyos accel-sstp[2492]: sstp: started - Feb 28 17:03:04 vyos accel-sstp[2492]: :: recv [HTTP <SSTP_DUPLEX_POST /sra_{BA195980-CD49-458b-9E23-C84EE0ADCD75}/ HTTP/1.1>] - Feb 28 17:03:04 vyos accel-sstp[2492]: :: recv [HTTP <SSTPCORRELATIONID: {48B82435-099A-4158-A987-052E7570CFAA}>] - Feb 28 17:03:04 vyos accel-sstp[2492]: :: recv [HTTP <Content-Length: 18446744073709551615>] - Feb 28 17:03:04 vyos accel-sstp[2492]: :: recv [HTTP <Host: vyos.io>] - Feb 28 17:03:04 vyos accel-sstp[2492]: :: send [HTTP <HTTP/1.1 200 OK>] - Feb 28 17:03:04 vyos accel-sstp[2492]: :: send [HTTP <Date: Wed, 28 Feb 2024 17:03:04 GMT>] - Feb 28 17:03:04 vyos accel-sstp[2492]: :: send [HTTP <Content-Length: 18446744073709551615>] - Feb 28 17:03:04 vyos accel-sstp[2492]: :: recv [SSTP SSTP_MSG_CALL_CONNECT_REQUEST] - Feb 28 17:03:04 vyos accel-sstp[2492]: :: send [SSTP SSTP_MSG_CALL_CONNECT_ACK] - Feb 28 17:03:04 vyos accel-sstp[2492]: :: lcp_layer_init - Feb 28 17:03:04 vyos accel-sstp[2492]: :: auth_layer_init - Feb 28 17:03:04 vyos accel-sstp[2492]: :: ccp_layer_init - Feb 28 17:03:04 vyos accel-sstp[2492]: :: ipcp_layer_init - Feb 28 17:03:04 vyos accel-sstp[2492]: :: ipv6cp_layer_init - Feb 28 17:03:04 vyos accel-sstp[2492]: :: ppp establishing - Feb 28 17:03:04 vyos accel-sstp[2492]: :: lcp_layer_start - Feb 28 17:03:04 vyos accel-sstp[2492]: :: send [LCP ConfReq id=56 <auth PAP> <mru 1452> <magic 1cd9ad05>] - Feb 28 17:03:04 vyos accel-sstp[2492]: :: recv [LCP ConfReq id=0 <mru 4091> <magic 345f64ca> <pcomp> <accomp> < d 3 6 >] - Feb 28 17:03:04 vyos accel-sstp[2492]: :: send [LCP ConfRej id=0 <pcomp> <accomp> < d 3 6 >] - Feb 28 17:03:04 vyos accel-sstp[2492]: :: recv [LCP ConfReq id=1 <mru 4091> <magic 345f64ca>] - Feb 28 17:03:04 vyos accel-sstp[2492]: :: send [LCP ConfNak id=1 <mru 1452>] - Feb 28 17:03:04 vyos accel-sstp[2492]: :: recv [LCP ConfReq id=2 <mru 1452> <magic 345f64ca>] - Feb 28 17:03:04 vyos accel-sstp[2492]: :: send [LCP ConfAck id=2] - Feb 28 17:03:07 vyos accel-sstp[2492]: :: fsm timeout 9 - Feb 28 17:03:07 vyos accel-sstp[2492]: :: send [LCP ConfReq id=56 <auth PAP> <mru 1452> <magic 1cd9ad05>] - Feb 28 17:03:07 vyos accel-sstp[2492]: :: recv [LCP ConfAck id=56 <auth PAP> <mru 1452> <magic 1cd9ad05>] - Feb 28 17:03:07 vyos accel-sstp[2492]: :: lcp_layer_started - Feb 28 17:03:07 vyos accel-sstp[2492]: :: auth_layer_start - Feb 28 17:03:07 vyos accel-sstp[2492]: :: recv [LCP Ident id=3 <MSRASV5.20>] - Feb 28 17:03:07 vyos accel-sstp[2492]: :: recv [LCP Ident id=4 <MSRAS-0-MSEDGEWIN10>] - Feb 28 17:03:07 vyos accel-sstp[2492]: [50B blob data] - Feb 28 17:03:07 vyos accel-sstp[2492]: :: recv [PAP AuthReq id=3] - Feb 28 17:03:07 vyos accel-sstp[2492]: ppp0:test: connect: ppp0 <--> sstp(192.168.10.100:49852) - Feb 28 17:03:07 vyos accel-sstp[2492]: ppp0:test: ppp connected - Feb 28 17:03:07 vyos accel-sstp[2492]: ppp0:test: send [PAP AuthAck id=3 "Authentication succeeded"] - Feb 28 17:03:07 vyos accel-sstp[2492]: ppp0:test: test: authentication succeeded - Feb 28 17:03:07 vyos accel-sstp[2492]: ppp0:test: auth_layer_started - Feb 28 17:03:07 vyos accel-sstp[2492]: ppp0:test: ccp_layer_start - Feb 28 17:03:07 vyos accel-sstp[2492]: ppp0:test: ipcp_layer_start - Feb 28 17:03:07 vyos accel-sstp[2492]: ppp0:test: ipv6cp_layer_start - Feb 28 17:03:07 vyos accel-sstp[2492]: ppp0:test: recv [SSTP SSTP_MSG_CALL_CONNECTED] - Feb 28 17:03:07 vyos accel-sstp[2492]: ppp0:test: IPV6CP: discarding packet - Feb 28 17:03:07 vyos accel-sstp[2492]: ppp0:test: send [LCP ProtoRej id=88 <8057>] - Feb 28 17:03:07 vyos accel-sstp[2492]: ppp0:test: recv [IPCP ConfReq id=7 <addr 0.0.0.0> <dns1 0.0.0.0> <wins1 0.0.0.0> <dns2 0.0.0.0> <wins2 0.0.0.0>] - Feb 28 17:03:07 vyos accel-sstp[2492]: ppp0:test: send [IPCP ConfReq id=25 <addr 10.0.0.1>] - Feb 28 17:03:07 vyos accel-sstp[2492]: ppp0:test: send [IPCP ConfRej id=7 <dns1 0.0.0.0> <wins1 0.0.0.0> <dns2 0.0.0.0> <wins2 0.0.0.0>] - Feb 28 17:03:07 vyos accel-sstp[2492]: ppp0:test: recv [IPCP ConfAck id=25 <addr 10.0.0.1>] - Feb 28 17:03:07 vyos accel-sstp[2492]: ppp0:test: recv [IPCP ConfReq id=8 <addr 0.0.0.0>] - Feb 28 17:03:07 vyos accel-sstp[2492]: ppp0:test: send [IPCP ConfNak id=8 <addr 10.0.0.5>] - Feb 28 17:03:07 vyos accel-sstp[2492]: ppp0:test: recv [IPCP ConfReq id=9 <addr 10.0.0.5>] - Feb 28 17:03:07 vyos accel-sstp[2492]: ppp0:test: send [IPCP ConfAck id=9] - Feb 28 17:03:07 vyos accel-sstp[2492]: ppp0:test: ipcp_layer_started - Feb 28 17:03:07 vyos accel-sstp[2492]: ppp0:test: rename interface to 'sstp0' - Feb 28 17:03:07 vyos accel-sstp[2492]: sstp0:test: sstp: ppp: started - -.. _sstpc: https://github.com/reliablehosting/sstp-client -.. _dictionary: https://github.com/accel-ppp/accel-ppp/blob/master/accel-pppd/radius/dict/dictionary.rfc6911 -.. _`ACCEL-PPP attribute`: https://github.com/accel-ppp/accel-ppp/blob/master/accel-pppd/radius/dict/dictionary.accel -.. include:: /_include/common-references.txt diff --git a/docs/configuration/vrf/rst-index.rst b/docs/configuration/vrf/rst-index.rst deleted file mode 100644 index 5965f857..00000000 --- a/docs/configuration/vrf/rst-index.rst +++ /dev/null @@ -1,590 +0,0 @@ -:lastproofread: 2021-07-07 - -.. _vrf: - -### -VRF -### - -:abbr:`VRF (Virtual Routing and Forwarding)` devices combined with ip rules -provides the ability to create virtual routing and forwarding domains (aka -VRFs, VRF-lite to be specific) in the Linux network stack. One use case is the -multi-tenancy problem where each tenant has their own unique routing tables and -in the very least need different default gateways. - -Configuration -============= - -A VRF device is created with an associated route table. Network interfaces are -then enslaved to a VRF device. - -.. cfgcmd:: set vrf name <name> table <id> - - Create a new VRF instance with `<name>` and `<id>`. The name is - used when placing individual interfaces into the VRF. - - .. note:: A routing table ID can not be modified once it is assigned. It can - only be changed by deleting and re-adding the VRF instance. - -.. cfgcmd:: set vrf bind-to-all - - By default the scope of the port bindings for unbound sockets is limited to - the default VRF. That is, it will not be matched by packets arriving on - interfaces enslaved to a VRF and processes may bind to the same port if - they bind to a VRF. - - TCP & UDP services running in the default VRF context (ie., not bound to any - VRF device) can work across all VRF domains by enabling this option. - -Zebra/Kernel route filtering ----------------------------- - -Zebra supports prefix-lists and Route Maps to match routes received from -other FRR components. The permit/deny facilities provided by these commands -can be used to filter which routes zebra will install in the kernel. - -.. cfgcmd:: set vrf <name> ip protocol <protocol> route-map <route-map> - - Apply a route-map filter to routes for the specified protocol. - - The following protocols can be used: any, babel, bgp, eigrp, - isis, ospf, rip, static - - .. note:: If you choose any as the option that will cause all protocols that - are sending routes to zebra. - -.. cfgcmd:: set vrf <name> ipv6 protocol <protocol> route-map <route-map> - - Apply a route-map filter to routes for the specified protocol. - - The following protocols can be used: any, babel, bgp, isis, - ospfv3, ripng, static - - .. note:: If you choose any as the option that will cause all protocols that - are sending routes to zebra. - -Nexthop Tracking ----------------- - -Nexthop tracking resolve nexthops via the default route by default. -This is enabled by default for a traditional profile of FRR which we -use. It and can be disabled if you do not want to e.g. allow BGP to -peer across the default route. - -.. cfgcmd:: set vrf name <name> ip nht no-resolve-via-default - - Do not allow IPv4 nexthop tracking to resolve via the default route. This - parameter is configured per-VRF, so the command is also available in the VRF - subnode. - -.. cfgcmd:: set vrf name <name> ipv6 nht no-resolve-via-default - - Do not allow IPv6 nexthop tracking to resolve via the default route. This - parameter is configured per-VRF, so the command is also available in the VRF - subnode. - -Interfaces ----------- - -When VRFs are used it is not only mandatory to create a VRF but also the VRF -itself needs to be assigned to an interface. - -.. cfgcmd:: set interfaces <dummy | ethernet | bonding | bridge | pppoe> - <interface> vrf <name> - - Assign interface identified by `<interface>` to VRF named `<name>`. - -Routing -------- - -.. note:: VyOS 1.4 (sagitta) introduced dynamic routing support for VRFs. - -Currently dynamic routing is supported for the following protocols: - -- :ref:`routing-bgp` -- :ref:`routing-isis` -- :ref:`routing-ospf` -- :ref:`routing-ospfv3` -- :ref:`routing-static` - -The CLI configuration is same as mentioned in above articles. The only -difference is, that each routing protocol used, must be prefixed with the `vrf -name <name>` command. - -Example -^^^^^^^ - -The following commands would be required to set options for a given dynamic -routing protocol inside a given vrf: - -- :ref:`routing-bgp`: ``set vrf name <name> protocols bgp ...`` -- :ref:`routing-isis`: ``set vrf name <name> protocols isis ...`` -- :ref:`routing-ospf`: ``set vrf name <name> protocols ospf ...`` -- :ref:`routing-ospfv3`: ``set vrf name <name> protocols ospfv3 ...`` -- :ref:`routing-static`: ``set vrf name <name> protocols static ...`` - -Services -------- - -Currently the following services can be created isolated in VRFs - -- :ref:`dhcp-server` - -The CLI configuration is same as mentioned in above articles. The only -difference is, that each service used, must be prefixed with the `vrf -name <name>` command. - -Example -^^^^^^^ - -The following commands would be required to set options for a given service -inside a given vrf: - -- :ref:`dhcp-server`: ``set vrf name <name> service dhcp-server ...`` -- :ref:`dhcp-server`: ``set vrf name <name> service dhcpv6-server ...`` - - -Operation -========= - -It is not sufficient to only configure a VRF but VRFs must be maintained, too. -For VRF maintenance the following operational commands are in place. - -.. opcmd:: show vrf - - Lists VRFs that have been created - - .. code-block:: none - - vyos@vyos:~$ show vrf - VRF name state mac address flags interfaces - -------- ----- ----------- ----- ---------- - blue up 00:53:12:d8:74:24 noarp,master,up,lower_up dum200,eth0.302 - red up 00:53:de:02:df:aa noarp,master,up,lower_up dum100,eth0.300,bond0.100,peth0 - - .. note:: Command should probably be extended to list also the real - interfaces assigned to this one VRF to get a better overview. - -.. opcmd:: show vrf <name> - - .. code-block:: none - - vyos@vyos:~$ show vrf name blue - VRF name state mac address flags interfaces - -------- ----- ----------- ----- ---------- - blue up 00:53:12:d8:74:24 noarp,master,up,lower_up dum200,eth0.302 - -.. opcmd:: show ip route vrf <name> - - Display IPv4 routing table for VRF identified by `<name>`. - - .. code-block:: none - - vyos@vyos:~$ show ip route vrf blue - Codes: K - kernel route, C - connected, S - static, R - RIP, - O - OSPF, I - IS-IS, B - BGP, E - EIGRP, N - NHRP, - T - Table, v - VNC, V - VNC-Direct, A - Babel, D - SHARP, - F - PBR, f - OpenFabric, - > - selected route, * - FIB route, q - queued route, r - rejected route - - VRF blue: - K 0.0.0.0/0 [255/8192] unreachable (ICMP unreachable), 00:00:50 - S>* 172.16.0.0/16 [1/0] via 192.0.2.1, dum1, 00:00:02 - C>* 192.0.2.0/24 is directly connected, dum1, 00:00:06 - - -.. opcmd:: show ipv6 route vrf <name> - - Display IPv6 routing table for VRF identified by `<name>`. - - .. code-block:: none - - vyos@vyos:~$ show ipv6 route vrf red - Codes: K - kernel route, C - connected, S - static, R - RIPng, - O - OSPFv3, I - IS-IS, B - BGP, N - NHRP, T - Table, - v - VNC, V - VNC-Direct, A - Babel, D - SHARP, F - PBR, - f - OpenFabric, - > - selected route, * - FIB route, q - queued route, r - rejected route - - VRF red: - K ::/0 [255/8192] unreachable (ICMP unreachable), 00:43:20 - C>* 2001:db8::/64 is directly connected, dum1, 00:02:19 - C>* fe80::/64 is directly connected, dum1, 00:43:19 - K>* ff00::/8 [0/256] is directly connected, dum1, 00:43:19 - - -.. opcmd:: ping <host> vrf <name> - - The ping command is used to test whether a network host is reachable or not. - - Ping uses ICMP protocol's mandatory ECHO_REQUEST datagram to elicit an - ICMP ECHO_RESPONSE from a host or gateway. ECHO_REQUEST datagrams (pings) - will have an IP and ICMP header, followed by "struct timeval" and an - arbitrary number of pad bytes used to fill out the packet. - - When doing fault isolation with ping, you should first run it on the local - host, to verify that the local network interface is up and running. Then, - continue with hosts and gateways further down the road towards your - destination. Round-trip time and packet loss statistics are computed. - - Duplicate packets are not included in the packet loss calculation, although - the round-trip time of these packets is used in calculating the minimum/ - average/maximum round-trip time numbers. - - .. note:: Ping command can be interrupted at any given time using - ``<Ctrl>+c``. A brief statistic is shown afterwards. - - .. code-block:: none - - vyos@vyos:~$ ping 192.0.2.1 vrf red - PING 192.0.2.1 (192.0.2.1) 56(84) bytes of data. - 64 bytes from 192.0.2.1: icmp_seq=1 ttl=64 time=0.070 ms - 64 bytes from 192.0.2.1: icmp_seq=2 ttl=64 time=0.078 ms - ^C - --- 192.0.2.1 ping statistics --- - 2 packets transmitted, 2 received, 0% packet loss, time 4ms - rtt min/avg/max/mdev = 0.070/0.074/0.078/0.004 ms - -.. opcmd:: traceroute vrf <name> [ipv4 | ipv6] <host> - - Displays the route packets taken to a network host utilizing VRF instance - identified by `<name>`. When using the IPv4 or IPv6 option, displays the - route packets taken to the given hosts IP address family. This option is - useful when the host is specified as a hostname rather than an IP address. - -.. opcmd:: force vrf <name> - - Join a given VRF. This will open a new subshell within the specified VRF. - - The prompt is adjusted to reflect this change in both config and op-mode. - - .. code-block:: none - - vyos@vyos:~$ force vrf blue - vyos@vyos(vrf:blue):~$ - -.. _vrf example: - -Example -======= - -VRF route leaking ------------------ - -The following example topology was built using EVE-NG. - -.. figure:: /_static/images/vrf-example-topology-01.* - :alt: VRF topology example - - VRF route leaking - -* PC1 is in the ``default`` VRF and acting as e.g. a "fileserver" -* PC2 is in VRF ``blue`` which is the development department -* PC3 and PC4 are connected to a bridge device on router ``R1`` which is in VRF - ``red``. Say this is the HR department. -* R1 is managed through an out-of-band network that resides in VRF ``mgmt`` - -.. _vrf example configuration: - -Configuration -^^^^^^^^^^^^^ - - .. code-block:: none - - set interfaces bridge br10 address '10.30.0.254/24' - set interfaces bridge br10 member interface eth3 - set interfaces bridge br10 member interface eth4 - set interfaces bridge br10 vrf 'red' - - set interfaces ethernet eth0 address 'dhcp' - set interfaces ethernet eth0 vrf 'mgmt' - set interfaces ethernet eth1 address '10.0.0.254/24' - set interfaces ethernet eth2 address '10.20.0.254/24' - set interfaces ethernet eth2 vrf 'blue' - - set protocols static route 10.20.0.0/24 interface eth2 vrf 'blue' - set protocols static route 10.30.0.0/24 interface br10 vrf 'red' - - set service ssh disable-host-validation - set service ssh vrf 'mgmt' - - set system name-server 'eth0' - - set vrf name blue protocols static route 10.0.0.0/24 interface eth1 vrf 'default' - set vrf name blue table '3000' - set vrf name mgmt table '1000' - set vrf name red protocols static route 10.0.0.0/24 interface eth1 vrf 'default' - set vrf name red table '2000' - -VRF and NAT ------------ - -.. _vrf:nat_configuration: - -Configuration -^^^^^^^^^^^^^ - - .. code-block:: none - - set interfaces ethernet eth0 address '172.16.50.12/24' - set interfaces ethernet eth0 vrf 'red' - - set interfaces ethernet eth1 address '192.168.130.100/24' - set interfaces ethernet eth1 vrf 'blue' - - set nat destination rule 110 description 'NAT ssh- INSIDE' - set nat destination rule 110 destination port '2022' - set nat destination rule 110 inbound-interface name 'eth0' - set nat destination rule 110 protocol 'tcp' - set nat destination rule 110 translation address '192.168.130.40' - - set nat source rule 100 outbound-interface name 'eth0' - set nat source rule 100 protocol 'all' - set nat source rule 100 source address '192.168.130.0/24' - set nat source rule 100 translation address 'masquerade' - - set service ssh vrf 'red' - - set vrf bind-to-all - set vrf name blue protocols static route 0.0.0.0/0 next-hop 172.16.50.1 vrf 'red' - set vrf name blue protocols static route 172.16.50.0/24 interface eth0 vrf 'red' - set vrf name blue table '1010' - - set vrf name red protocols static route 0.0.0.0/0 next-hop 172.16.50.1 - set vrf name red protocols static route 192.168.130.0/24 interface eth1 vrf 'blue' - set vrf name red table '2020' - -.. _vrf example operation: - -Operation -^^^^^^^^^ - -After committing the configuration we can verify all leaked routes are -installed, and try to ICMP ping PC1 from PC3. - - .. code-block:: none - - PCS> ping 10.0.0.1 - - 84 bytes from 10.0.0.1 icmp_seq=1 ttl=63 time=1.943 ms - 84 bytes from 10.0.0.1 icmp_seq=2 ttl=63 time=1.618 ms - 84 bytes from 10.0.0.1 icmp_seq=3 ttl=63 time=1.745 ms - - .. code-block:: none - - VPCS> show ip - - NAME : VPCS[1] - IP/MASK : 10.30.0.1/24 - GATEWAY : 10.30.0.254 - DNS : - MAC : 00:50:79:66:68:0f - -VRF default routing table -""""""""""""""""""""""""" - - .. code-block:: none - - vyos@R1:~$ show ip route - Codes: K - kernel route, C - connected, S - static, R - RIP, - O - OSPF, I - IS-IS, B - BGP, E - EIGRP, N - NHRP, - T - Table, v - VNC, V - VNC-Direct, A - Babel, D - SHARP, - F - PBR, f - OpenFabric, - > - selected route, * - FIB route, q - queued, r - rejected, b - backup - - C>* 10.0.0.0/24 is directly connected, eth1, 00:07:44 - S>* 10.20.0.0/24 [1/0] is directly connected, eth2 (vrf blue), weight 1, 00:07:38 - S>* 10.30.0.0/24 [1/0] is directly connected, br10 (vrf red), weight 1, 00:07:38 - -VRF red routing table -""""""""""""""""""""" - - .. code-block:: none - - vyos@R1:~$ show ip route vrf red - Codes: K - kernel route, C - connected, S - static, R - RIP, - O - OSPF, I - IS-IS, B - BGP, E - EIGRP, N - NHRP, - T - Table, v - VNC, V - VNC-Direct, A - Babel, D - SHARP, - F - PBR, f - OpenFabric, - > - selected route, * - FIB route, q - queued, r - rejected, b - backup - - VRF red: - K>* 0.0.0.0/0 [255/8192] unreachable (ICMP unreachable), 00:07:57 - S>* 10.0.0.0/24 [1/0] is directly connected, eth1 (vrf default), weight 1, 00:07:40 - C>* 10.30.0.0/24 is directly connected, br10, 00:07:54 - -VRF blue routing table -"""""""""""""""""""""" - - .. code-block:: none - - vyos@R1:~$ show ip route vrf blue - Codes: K - kernel route, C - connected, S - static, R - RIP, - O - OSPF, I - IS-IS, B - BGP, E - EIGRP, N - NHRP, - T - Table, v - VNC, V - VNC-Direct, A - Babel, D - SHARP, - F - PBR, f - OpenFabric, - > - selected route, * - FIB route, q - queued, r - rejected, b - backup - - VRF blue: - K>* 0.0.0.0/0 [255/8192] unreachable (ICMP unreachable), 00:08:00 - S>* 10.0.0.0/24 [1/0] is directly connected, eth1 (vrf default), weight 1, 00:07:44 - C>* 10.20.0.0/24 is directly connected, eth2, 00:07:53 - - -########## -L3VPN VRFs -########## - -:abbr:`L3VPN VRFs ( Layer 3 Virtual Private Networks )` bgpd supports for -IPv4 RFC 4364 and IPv6 RFC 4659. L3VPN routes, and their associated VRF -MPLS labels, can be distributed to VPN SAFI neighbors in the default, i.e., -non VRF, BGP instance. VRF MPLS labels are reached using core MPLS labels -which are distributed using LDP or BGP labeled unicast. -bgpd also supports inter-VRF route leaking. - -.. _l3vpn-vrf-route-leaking: - -VRF Route Leaking -================= - -BGP routes may be leaked (i.e. copied) between a unicast VRF RIB and the VPN -SAFI RIB of the default VRF for use in MPLS-based L3VPNs. Unicast routes may -also be leaked between any VRFs (including the unicast RIB of the default BGP -instance). A shortcut syntax is also available for specifying leaking from -one VRF to another VRF using the default instance’s VPN RIB as the intemediary -. A common application of the VRF-VRF feature is to connect a customer’s -private routing domain to a provider’s VPN service. Leaking is configured from -the point of view of an individual VRF: import refers to routes leaked from VPN -to a unicast VRF, whereas export refers to routes leaked from a unicast VRF to -VPN. - - -.. note:: Routes exported from a unicast VRF to the VPN RIB must be augmented - by two parameters: - - an RD / RTLIST - - Configuration for these exported routes must, at a minimum, specify - these two parameters. - -.. _l3vpn-vrf example configuration: - -Configuration -============= - -Configuration of route leaking between a unicast VRF RIB and the VPN SAFI RIB -of the default VRF is accomplished via commands in the context of a VRF -address-family. - -.. cfgcmd:: set vrf name <name> protocols bgp address-family - <ipv4-unicast|ipv6-unicast> rd vpn export <asn:nn|address:nn> - - Specifies the route distinguisher to be added to a route exported from the - current unicast VRF to VPN. - -.. cfgcmd:: set vrf name <name> protocols bgp address-family - <ipv4-unicast|ipv6-unicast> route-target vpn <import|export|both> - [RTLIST] - - Specifies the route-target list to be attached to a route (export) or the - route-target list to match against (import) when exporting/importing - between the current unicast VRF and VPN.The RTLIST is a space-separated - list of route-targets, which are BGP extended community values as - described in Extended Communities Attribute. - -.. cfgcmd:: set vrf name <name> protocols bgp address-family - <ipv4-unicast|ipv6-unicast> label vpn export <0-1048575|auto> - - Enables an MPLS label to be attached to a route exported from the current - unicast VRF to VPN. If the value specified is auto, the label value is - automatically assigned from a pool maintained. - -.. cfgcmd:: set vrf name <name> protocols bgp address-family - <ipv4-unicast|ipv6-unicast> label vpn allocation-mode per-nexthop - - Select how labels are allocated in the given VRF. By default, the per-vrf - mode is selected, and one label is used for all prefixes from the VRF. The - per-nexthop will use a unique label for all prefixes that are reachable via - the same nexthop. - -.. cfgcmd:: set vrf name <name> protocols bgp address-family - <ipv4-unicast|ipv6-unicast> route-map vpn <import|export> - [route-map <name>] - - Specifies an optional route-map to be applied to routes imported or - exported between the current unicast VRF and VPN. - -.. cfgcmd:: set vrf name <name> protocols bgp address-family - <ipv4-unicast|ipv6-unicast> <import|export> vpn - - Enables import or export of routes between the current unicast VRF and VPN. - -.. cfgcmd:: set vrf name <name> protocols bgp address-family - <ipv4-unicast|ipv6-unicast> import vrf <name> - - Shortcut syntax for specifying automatic leaking from vrf VRFNAME to the - current VRF using the VPN RIB as intermediary. The RD and RT are auto - derived and should not be specified explicitly for either the source or - destination VRF’s. - -.. cfgcmd:: set vrf name <name> protocols bgp address-family - <ipv4-unicast|ipv6-unicast> route-map vrf import - [route-map <name>] - - Specifies an optional route-map to be applied to routes imported from VRFs. - -.. cfgcmd:: set vrf name <name> protocols bgp interface <interface> mpls - forwarding - - It is possible to permit BGP install VPN prefixes without transport - labels. This configuration will install VPN prefixes originated - from an e-bgp session, and with the next-hop directly connected. - -.. _l3vpn-vrf example operation: - -Operation -========= - -It is not sufficient to only configure a L3VPN VRFs but L3VPN VRFs must be -maintained, too.For L3VPN VRF maintenance the following operational commands -are in place. - -.. opcmd:: show bgp <ipv4|ipv6> vpn - - Print active IPV4 or IPV6 routes advertised via the VPN SAFI. - - .. code-block:: none - - BGP table version is 2, local router ID is 10.0.1.1, vrf id 0 - Default local pref 100, local AS 65001 - Status codes: s suppressed, d damped, h history, * valid, > best, = multipath, - i internal, r RIB-failure, S Stale, R Removed - Nexthop codes: @NNN nexthop's vrf id, < announce-nh-self - Origin codes: i - IGP, e - EGP, ? - incomplete - - Network Next Hop Metric LocPrf Weight Path - Route Distinguisher: 10.50.50.1:1011 - *>i10.50.50.0/24 10.0.0.7 0 100 0 i - UN=10.0.0.7 EC{65035:1011} label=80 type=bgp, subtype=0 - Route Distinguisher: 10.60.60.1:1011 - *>i10.60.60.0/24 10.0.0.10 0 100 0 i - UN=10.0.0.10 EC{65035:1011} label=80 type=bgp, subtype=0 - -.. opcmd:: show bgp <ipv4|ipv6> vpn summary - - Print a summary of neighbor connections for the specified AFI/SAFI - combination. - - .. code-block:: none - - BGP router identifier 10.0.1.1, local AS number 65001 vrf-id 0 - BGP table version 0 - RIB entries 9, using 1728 bytes of memory - Peers 4, using 85 KiB of memory - Peer groups 1, using 64 bytes of memory - - Neighbor V AS MsgRcvd MsgSent TblVer InQ OutQ Up/Down State/PfxRcd PfxSnt - 10.0.0.7 4 65001 2860 2870 0 0 0 1d23h34m 2 10 - - -.. include:: /_include/common-references.txt |