diff options
Diffstat (limited to 'docs')
115 files changed, 0 insertions, 18038 deletions
diff --git a/docs/automation/md-cloud-init.md b/docs/automation/md-cloud-init.md deleted file mode 100644 index 6c25287d..00000000 --- a/docs/automation/md-cloud-init.md +++ /dev/null @@ -1,375 +0,0 @@ ---- -lastproofread: '2026-04-13' ---- - -(cloud-init)= - -# VyOS cloud-init - -VyOS instances in cloud and virtualized environments are initialized using the -industry-standard `cloud-init`. Through `cloud-init`, VyOS injects SSH -keys, configures network settings, and applies custom configurations during the -initial instance boot. - -## Configuration sources - -VyOS `cloud-init` obtains configuration data from the following sources: - -- `meta-data`: Instance-specific details provided by the cloud platform or - hypervisor. In some cloud environments, this data is available via an HTTP - endpoint at `http://169.254.169.254`. -- `network configuration`: Network settings such as IP addresses, routes, and - DNS (only available on certain cloud and virtualization platforms). -- `user-data`: User-supplied CLI configuration commands. - -## User-data - -Major cloud providers support injecting `user-data` as plain text or base64 -encoding text during initial instance boot. As `user-data` has a strict size -limit of \~16384 bytes, long configuration command lists can be compressed using -`gzip`. - -The recommended method for configuring VyOS instances via `user-data` is to -use the `cloud-config` syntax described below. - -## Cloud-config modules - -By default, VyOS enables only two `cloud-config` modules: - -- `write_files`: Inserts user-provided files such as encryption keys, - certificates, or `config.boot` into the filesystem during the initial - instance boot. See [Cloud-init-write_files] for file syntax and file format - requirements. -- `vyos_userdata`: Executes user-provided CLI configuration commands during - the initial instance boot. - -The files to insert and the CLI commands to execute must be provided in a -`cloud-config` YAML file. - -## Cloud-config file format - -`cloud-config` files are written in YAML and must begin with the -`#cloud-config` line. Only `vyos_config_commands` and `write_files` are -supported as top-level keys. The use of these keys is described in the -following two sections. - -## Vyos_config_commands key - -Use the `vyos_config_commands` key to define configuration commands for -initializing your VyOS instance. Commands must follow the set-style syntax -and can include both `set` and `delete` statements. - -Syntax requirements: - -- Place one command per line. -- Enclose values in single quotes. -- Avoid single quotes within commands or values. - -Applying commands from `cloud-config` overrides both settings configured via -`meta-data` and default VyOS settings. After commands are applied, -`cloud-init` automatically performs `commit` and `save`. - -The following is an example of a `cloud-config` file: - -```yaml -#cloud-config -vyos_config_commands: - - set system host-name 'vyos-prod-ashburn' - - set service ntp server 1.pool.ntp.org - - set service ntp server 2.pool.ntp.org - - delete interfaces ethernet eth1 address 'dhcp' - - set interfaces ethernet eth1 address '192.0.2.247/24' - - set protocols static route 198.51.100.0/24 next-hop '192.0.2.1' -``` - -### Instance defaults/fallbacks - -If no external configuration data is provided, VyOS applies the following -defaults: - -- **SSH:** port 22. -- **Credentials:** `vyos`/`vyos`. -- **Networking:** DHCP is enabled on the first Ethernet interface. - -All defaults can be overridden via `user-data` configurations. - -## Write_files key - -VyOS allows you to run custom scripts during the initial instance boot to -execute operational, configuration, and standard Linux commands. - -Use the `write_files` key to insert these scripts into the -`/opt/vyatta/etc/config/scripts/` directory. - -Depending on when your commands need to run, use one of the following paths: - -- `/opt/vyatta/etc/config/scripts/vyos-preconfig-bootup.script`: Commands - defined here are executed before the system configuration is applied. -- `/opt/vyatta/etc/config/scripts/vyos-postconfig-bootup.script`: Commands - defined here are executed after the system configuration is applied. - -In both cases, commands are executed with `root` privileges. - -:::{note} -Use the `/opt/vyatta/etc/config/` path instead of `/config/scripts/` as -referenced in the {ref}`command-scripting` section. The `/config/scripts/` -directory is not mounted when the `write_files` module runs. -::: - -The following example shows how to use `write_files` to execute an -operational command **after** the initial configuration is complete: - -```yaml -#cloud-config -write_files: - - path: /opt/vyatta/etc/config/scripts/vyos-postconfig-bootup.script - owner: root:vyattacfg - permissions: '0775' - content: | - #!/bin/vbash - source /opt/vyatta/etc/functions/script-template - filename=/tmp/bgp_status_`date +"%Y_%m_%d_%I_%M_%p"`.log - run show ip bgp summary >> $filename -``` - -You can combine standard Linux commands to fetch data and VyOS configuration -commands (like `set` and `commit`) in the same script. - -The following example sets the `hostname` based on the instance identifier -obtained from the EC2 Instance Metadata Service (IMDS). - -```yaml -#cloud-config -write_files: - - path: /opt/vyatta/etc/config/scripts/vyos-postconfig-bootup.script - owner: root:vyattacfg - permissions: '0775' - content: | - #!/bin/vbash - source /opt/vyatta/etc/functions/script-template - hostname=`curl -s http://169.254.169.254/latest/meta-data/instance-id` - configure - set system host-name $hostname - commit - exit -``` - -## NoCloud - -Injecting configuration data is not limited to cloud platforms. The NoCloud -data source allows you to inject `user-data` and `meta-data` on -virtualization platforms such as VMware, Hyper-V, and KVM. - -The simplest way to use the NoCloud data source is to create a `seed.iso` -file and attach it to the virtual machine as a CD drive. The volume must be -formatted as a VFAT or ISO 9660 file system with the label `cidata` or -`CIDATA`. - -Create text files named `user-data` and `meta-data`. On Linux-based -systems, use the `mkisofs` utility to create the `seed.iso` file. The -following syntax adds these files to the ISO 9660 file system: - -```none -mkisofs -joliet -rock -volid "cidata" -output seed.iso meta-data user-data -``` - -Once generated, attach the `seed.iso` file to your virtual machine. The -following example shows how to attach the file as a CD drive using KVM: - -```none -$ virt-install -n vyos_r1 \ - --ram 4096 \ - --vcpus 2 \ - --cdrom seed.iso \ - --os-type linux \ - --os-variant debian10 \ - --network network=default \ - --graphics vnc \ - --hvm \ - --virt-type kvm \ - --disk path=/var/lib/libvirt/images/vyos_kvm.qcow2,bus=virtio \ - --import \ - --noautoconsole -``` - -For more information on the NoCloud data source, visit the [NoCloud] page in -the `cloud-init` documentation. - -## Troubleshooting - -If your configuration does not apply as expected, follow these troubleshooting -steps: - -1. **Validate your YAML**: Ensure your `cloud-config` file follows proper - YAML syntax. Online resources such as [YAML Lint](https://www.yamllint.com/) - provide simple validation tools. -2. **Check the logs**: `cloud-init` writes logs to `/var/log/cloud-init.log`. - Filter for VyOS-specific entries using: - -```none -sudo grep vyos /var/log/cloud-init.log -``` - -## Cloud-init on Proxmox - -Before you begin, review the `cloud-init` [network-config-docs] to -understand how to import user and network configuration data. - -Key considerations: - -- Define VyOS configuration commands in the `user-data` file. -- Avoid including network configuration data in the `user-data` file. -- If no network configuration data is provided, the DHCP client is enabled on - the first interface. This happens at the OS level and is not reflected in the - VyOS CLI. - -The following example shows how to disable the DHCP client on `eth0` to -address this behavior. - -In this example: - -- **Proxmox IP address**: `192.168.0.253/24`. -- **Storage**: The `local` volume is mounted at `/var/lib/vz` and contains - all content types, including snippets. - -The goal is to remove the default DHCP client from the first interface and -apply a custom configuration during the initial instance boot using -`cloud-init`. - -### Generate .qcow2 image - -First, generate a VyOS `.qcow2` image with `cloud-init` support from the -[vyos-vm-images] repository: - -1. Clone the `vyos-vm-images` repository and comment out the `download-iso` - role in `qemu.yml`. -2. Download your preferred VyOS `.iso` file and save it as `/tmp/vyos.iso`. -3. Generate the `.qcow2` image (using a 10G disk size for this example): - -```sh -sudo ansible-playbook qemu.yml -e disk_size=10 \ - -e iso_local=/tmp/vyos.iso -e grub_console=serial -e vyos_version=1.5.0 \ - -e cloud_init=true -e cloud_init_ds=NoCloud -``` - -This generates your new image at `/tmp/vyos-1.5.0-cloud-init-10G-qemu.qcow2`. - -4. Copy the resulting image to the Proxmox server: - -```sh -sudo scp /tmp/vyos-1.5.0-cloud-init-10G-qemu.qcow2 root@192.168.0.253:/tmp/ -``` - -### Prepare cloud-init files - -Create the following files on your Proxmox server to proceed with this setup: - -- `user-data`: Contains VyOS configuration commands. -- `network-config`: Disables the DHCP client on the first interface. -- `meta-data`: An empty file (required by `cloud-init`). - -All files must be placed in the `/tmp/` directory. - -Follow these steps to create the required files: - -1. Navigate to the `/tmp/` directory: - - ```sh - cd /tmp/ - ``` - -2. Create the `user-data` file. Begin the file with `#cloud-config` and - include VyOS configuration commands. - - ```none - #cloud-config - vyos_config_commands: - - set system host-name 'vyos-BRAS' - - set service ntp server '1.pool.ntp.org' - - set service ntp server '2.pool.ntp.org' - - delete interfaces ethernet eth0 address 'dhcp' - - set interfaces ethernet eth0 address '198.51.100.2/30' - - set interfaces ethernet eth0 description 'WAN - ISP01' - - set interfaces ethernet eth1 address '192.168.25.1/24' - - set interfaces ethernet eth1 description 'Coming through VLAN 25' - - set interfaces ethernet eth2 address '192.168.26.1/24' - - set interfaces ethernet eth2 description 'Coming through VLAN 26' - - set protocols static route 0.0.0.0/0 next-hop '198.51.100.1' - ``` - -3. Create the `network-config` file. Include the following: - - ```none - version: 2 - ethernets: - eth0: - dhcp4: false - dhcp6: false - ``` - -4. Create the required empty `meta-data` file. - -### Create seed.iso - -Once you have created the necessary files, generate the `seed.iso` image and -mount it as a CD drive to the new VM. - -```sh -mkisofs -joliet -rock -volid "cidata" -output seed.iso meta-data \ -user-data network-config -``` - -:::{note} -Be careful while copying and pasting the above commands. Double quotes may need -to be corrected. -::: - -### Create the VM - -Note that the following settings apply to this particular example and may -require adjustment for other setups: - -- **VM ID**: `555`. -- **VM and .iso file storage**: The local volume (`directory` type, - mounted at `/var/lib/vz`). -- **VM resources**: Can be modified as needed. - -The `seed.iso` file was previously created in the `/tmp/` directory. Move -it to `/var/lib/vz/template/iso`: - -```sh -mv /tmp/seed.iso /var/lib/vz/template/iso/ -``` - -On the Proxmox server: - -```none -## Create VM, import disk and define boot order -qm create 555 --name vyos-1.5.0-cloudinit --memory 1024 --net0 virtio,bridge=vmbr0 -qm importdisk 555 vyos-1.5.0-cloud-init-10G-qemu.qcow2 local -qm set 555 --virtio0 local:555/vm-555-disk-0.raw -qm set 555 --boot order=virtio0 - -## Import seed.iso for cloud init -qm set 555 --ide2 media=cdrom,file=local:iso/seed.iso - -## Since this server has 1 nic, lets add network intefaces (vlan 25 and 26) -qm set 555 --net1 virtio,bridge=vmbr0,firewall=1,tag=25 -qm set 555 --net2 virtio,bridge=vmbr0,firewall=1,tag=26 -``` - -### Power on and verify the VM - -Power on the VM using the CLI or GUI. After it boots, verify the configuration. - -### References - -- Cloud-init [network-config-docs]. -- Proxmox [Cloud-init-Support]. - -[cloud-init-docs]: https://docs.vyos.io/en/equuleus/automation/cloud-init.html?highlight=cloud-init#vyos-cloud-init -[cloud-init-support]: <https://pve.proxmox.com/pve-docs/pve-admin-guide.html#qm_cloud_init> -[cloud-init-write_files]: https://cloudinit.readthedocs.io/en/latest/topics/examples.html#writing-out-arbitrary-files -[network-config-docs]: https://cloudinit.readthedocs.io/en/latest/topics/network-config.html -[nocloud]: https://cloudinit.readthedocs.io/en/latest/reference/datasources/nocloud.html -[vyos-vm-images]: https://github.com/vyos/vyos-vm-images diff --git a/docs/automation/md-command-scripting.md b/docs/automation/md-command-scripting.md deleted file mode 100644 index c1e1c239..00000000 --- a/docs/automation/md-command-scripting.md +++ /dev/null @@ -1,216 +0,0 @@ ---- -lastproofread: '2026-03-16' ---- - -(command-scripting)= - -# Command scripting - -VyOS supports executing configuration and operational commands non-interactively -from shell scripts. - -To include VyOS-specific functions and aliases, source the -`/opt/vyatta/etc/functions/script-template` file at the beginning of your -script. - -```none -#!/bin/vbash -source /opt/vyatta/etc/functions/script-template -exit -``` - -## Script execute permissions - -Simply placing script files in `/config/scripts/` does not mean the system -can execute them. - -To make your scripts executable, grant them **execute permissions**. Use the -following command: - -```none -chmod +x /config/scripts/script-name.sh -``` - -## Run configuration commands - -In scripts, present configuration commands as in a standard configuration -session. - -For example, to disable a BGP peer during a VRRP transition to the backup -state, use the following syntax: - -```none -#!/bin/vbash -source /opt/vyatta/etc/functions/script-template -configure -set protocols bgp system-as 65536 -set protocols bgp neighbor 192.168.2.1 shutdown -commit -exit -``` - -## Run operational commands - -In scripts, **always** prefix operational commands with `run`. - -```none -#!/bin/vbash -source /opt/vyatta/etc/functions/script-template -run show interfaces -exit -``` - -## Run commands remotely - -You can execute multiple **operational commands** on a remote VyOS system by -passing a script block over SSH. - -```none -ssh 192.0.2.1 'vbash -s' <<EOF -source /opt/vyatta/etc/functions/script-template -run show interfaces -exit -EOF -``` - -Example output: - -```none -Welcome to VyOS -Codes: S - State, L - Link, u - Up, D - Down, A - Admin Down -Interface IP Address S/L Description ---------- ---------- --- ----------- -eth0 192.0.2.1/24 u/u -lo 127.0.0.1/8 u/u - ::1/128 -``` - -## Other script languages - -If you use a scripting language other than bash, configure your script to -output the relevant commands, and then source that output into a bash script. - -The following example demonstrates this two-step process: - -```python -#!/usr/bin/env python3 -print("delete firewall group address-group somehosts") -print("set firewall group address-group somehosts address '192.0.2.3'") -print("set firewall group address-group somehosts address '203.0.113.55'") -``` - -```none -#!/bin/vbash -source /opt/vyatta/etc/functions/script-template -configure -source <(/config/scripts/setfirewallgroup.py) -commit -``` - -## Execute configuration scripts - -In Linux, it is common practice to prefix system commands with `sudo`. - -In VyOS, if you prefix a script that modifies the configuration with `sudo` -(see the code snippet below), subsequent manual configuration changes fail with -the `Set failed` error. Recovery requires a system reboot. - -```none -sudo ./myscript.sh # Modifies config -configure -set ... # Any configuration parameter -``` - -To avoid this issue, run scripts under the `vyattacfg` group using the `sg` -command: - -```none -sg vyattacfg -c ./myscript.sh -``` - -To ensure the script is executed under the `vyattacfg` group, safeguard it as -follows: - -```none -if [ "$(id -g -n)" != 'vyattacfg' ] ; then - exec sg vyattacfg -c "/bin/vbash $(readlink -f $0) $@" -fi -``` - -## Executing pre-hooks/post-hooks scripts - -VyOS allows you to run custom scripts **before** and **after** each commit. - -Place your custom scripts in the following default directories: - -```none -/config/scripts/commit/pre-hooks.d - Directory with scripts that run before - each commit. - -/config/scripts/commit/post-hooks.d - Directory with scripts that run after - each commit. -``` - -Scripts run in alphabetical order. Filenames must consist only of ASCII letters -(upper and lowercase), digits (0-9), underscores (\_), and hyphens (-). No other -characters are allowed. - -:::{note} -Custom scripts are executed **without** root privileges. Prefix -specific commands with `sudo` in your script when required. -::: - -The following example shows the output after executing a post-hook script -that runs the `show interfaces` command: - -```none -vyos@vyos# set interfaces ethernet eth1 address 192.0.2.3/24 -vyos@vyos# commit -Codes: S - State, L - Link, u - Up, D - Down, A - Admin Down -Interface IP Address S/L Description ---------- ---------- --- ----------- -eth0 198.51.100.10/24 u/u -eth1 192.0.2.3/24 u/u -eth2 - u/u -eth3 - u/u -lo 203.0.113.5/24 u/u -``` - -## Preconfig script on boot - -VyOS runs `/config/scripts/vyos-preconfig-bootup.script` at boot, **before** -the system configuration is applied. - -Use this script to apply **pre-configuration** workarounds for unresolved bugs -or enhancements not yet available in VyOS. - -The default script contains the following: - -```none -#!/bin/sh -# This script is executed at boot time before VyOS configuration is applied. -# Any modifications required to work around unfixed bugs or use -# services not available through the VyOS CLI system can be placed here. -``` - -## Postconfig script on boot - -VyOS runs `/config/scripts/vyos-postconfig-bootup.script` at boot, **after** -the system configuration is applied. - -Use this script to apply **post-configuration** workarounds for unresolved bugs -or enhancements not yet available in VyOS. - -The default script contains the following: - -```none -#!/bin/sh -# This script is executed at boot time after VyOS configuration is fully -# applied. Any modifications required to work around unfixed bugs or use -# services not available through the VyOS CLI system can be placed here. -``` - -:::{warning} -For configuration or upgrade management issues, modify this script -only as a last resort. Always try CLI-based solutions first. -::: diff --git a/docs/automation/md-index.md b/docs/automation/md-index.md deleted file mode 100644 index 62e60f84..00000000 --- a/docs/automation/md-index.md +++ /dev/null @@ -1,16 +0,0 @@ -# VyOS Automation - -```{toctree} -:maxdepth: 2 - -vyos-api -vyos-ansible -terraform/index -vyos-napalm -vyos-netmiko -vyos-salt -command-scripting -cloud-init -vyos-pyvyos -vyos-govyos -``` diff --git a/docs/automation/md-vyos-ansible.md b/docs/automation/md-vyos-ansible.md deleted file mode 100644 index 1ced72be..00000000 --- a/docs/automation/md-vyos-ansible.md +++ /dev/null @@ -1,99 +0,0 @@ ---- -lastproofread: '2026-04-13' ---- - -(vyos-ansible)= - -# Ansible - -VyOS can be configured using Ansible. To use it, install the `ansible` -package and the `python3-paramiko` module. - -## Directory structure - -Arrange your Ansible project directory as follows: - -```none -. -├── ansible.cfg -├── files -│ └── id_rsa_docker.pub -├── hosts -└── main.yml -``` - -## File contents - -- `ansible.cfg` - -```none -[defaults] -host_key_checking = no -retry_files_enabled = False -ANSIBLE_INVENTORY_UNPARSED_FAILED = true -``` - -- `id_rsa_docker.pub` - -Contains only the SSH public key. - -```none -AAAAB3NzaC1yc2EAAAADAQABAAABAQCoDgfhQJuJRFWJijHn7ZinZ3NWp4hWVrt7HFcvn0kgtP/5PeCtMt -``` - -- `hosts` - -Defines the target VyOS devices and the connection parameters required to reach -them. - -```none -[vyos_hosts] -r11 ansible_ssh_host=192.0.2.11 - -[vyos_hosts:vars] -ansible_python_interpreter=/usr/bin/python3 -ansible_user=vyos -ansible_ssh_pass=vyos -ansible_network_os=vyos -ansible_connection=network_cli -``` - -- `main.yml` - -Defines the configuration tasks to be applied to the target VyOS devices. - -```none ---- - -- hosts: r11 - - connection: network_cli - gather_facts: 'no' - - tasks: - - name: Configure remote r11 - vyos_config: - lines: - - set system host-name r11 - - set system name-server 203.0.113.254 - - set service ssh disable-host-validation - - set system login user vyos authentication public-keys docker@work type ssh-rsa - - set system login user vyos authentication public-keys docker@work key "{{ lookup('file', 'id_rsa_docker.pub') }}" - - set system time-zone America/Los_Angeles - - set interfaces ethernet eth0 description WAN -``` - -## Run Ansible - -To apply the configuration, use the following command: - -```none -$ ansible-playbook -i hosts main.yml - -PLAY [r11] ************************************************************************************************** - -TASK [Configure remote r11] ********************************************************************************* - -PLAY RECAP ************************************************************************************************** -r11 : ok=1 changed=1 unreachable=0 failed=0 skipped=0 rescued=0 ignored=0 -``` diff --git a/docs/automation/md-vyos-govyos.md b/docs/automation/md-vyos-govyos.md deleted file mode 100644 index f1ad3e91..00000000 --- a/docs/automation/md-vyos-govyos.md +++ /dev/null @@ -1,186 +0,0 @@ ---- -lastproofread: '2026-04-14' ---- - -(vyos-govyos)= - -# Go-VyOS - -Go-VyOS is a Go library for configuring and managing VyOS devices through -their API. - -- [GitHub repository](https://github.com/ganawaj/go-vyos): Hosts the source - code. -- [Documentation](https://pkg.go.dev/github.com/ganawaj/go-vyos@v0.1.0/vyos): - Provides the complete API reference, including available types, functions, and - methods. - -## Installation - -To install Go-VyOS, run: - -```bash -go install "github.com/ganawaj/go-vyos/vyos" -``` - -## Getting started - -### Import and disable TLS verification - -```none -import "github.com/ganawaj/go-vyos/vyos" -client := vyos.NewClient(nil).WithToken("AUTH_KEY").WithURL("https://192.168.0.1").Insecure() -``` - -### Initialize a VyDevice object - -```none -import ( - "github.com/ganawaj/go-vyos/vyos" - "os" -) - -hostname := os.Getenv("VYDEVICE_HOSTNAME") -port := os.Getenv("VYDEVICE_PORT") -url := fmt.Sprintf("https://%s:%s", hostname, port) - -apikey := os.Getenv("VYDEVICE_APIKEY") -verify_ssl := os.Getenv("VYDEVICE_VERIFY_SSL") - -client := vyos.NewClient(nil).WithToken(apikey).WithURL(url) - -if verify_ssl == "false" { - client = client.Insecure() -} -``` - -## Use Go-VyOS - -### Configure, then set - -```none -out, resp, err := c.Conf.Set(ctx, "interfaces ethernet eth0 address 192.168.1.1/24") -if err != nil { - panic(fmt.Sprintf("Error: %v", err)) -} - -fmt.Println(out.Success) -``` - -### Show a single object value - -```none -out, resp, err := c.Show.Do(ctx, "interfaces dummy dum1 address") -if err != nil { - panic("Error: %v", err) -} - -fmt.Println(out.Success) -fmt.Printf("Data: %v\n", out.Data) -``` - -### Configure, then show object - -```none -out, resp, err := c.Conf.Get(ctx, "interfaces dummy dum1", nil) -if err != nil { - panic("Error: %v", err) -} - -fmt.Println(out.Success) -fmt.Printf("Data: %v\n", out.Data) -``` - -### Configure, then show multivalue object - -```none -options := RetrieveOptions{ - Multivalue: true, -} - -out, resp, err := c.Conf.Get(ctx, "interfaces dummy dum1", options) -if err != nil { - panic("Error: %v", err) -} - -fmt.Println(out.Success) -``` - -### Configure, then delete object - -```none -out, resp, err := c.Conf.Delete(ctx, "interfaces dummy dum1") -if err != nil { - panic("Error: %v", err) -} - -fmt.Println(out.Success) -``` - -### Configure, then save - -```none -out, resp, err := c.Conf.Save(ctx, "") - -if err != nil { - panic("Error: %v", err) -} - -fmt.Println(out.Success) -``` - -### Configure, then save file - -```none -out, resp, err := c.Conf.Save(ctx, "/config/test300.config") - -if err != nil { - panic("Error: %v", err) -} - -fmt.Println(out.Success) -``` - -### Show object - -```none -out, resp, err := c.Show.Do(ctx, "system image") -if err != nil { - panic("Error: %v", err) -} - -fmt.Println(out.Success) -fmt.Printf("Data: %v\n", out.Data) -``` - -### Generate object - -```none -out, resp, err := c.Generate.Do(ctx, "pki wireguard key-pair") -if err != nil { - panic("Error: %v", err) -} - -fmt.Println(out.Success) -fmt.Printf("Data: %v\n", out.Data) -``` - -### Reset object - -```none -out, resp, err := c.Reset.Do(ctx, "ip bgp 192.0.2.11") -if err != nil { - panic("Error: %v", err) -} - -fmt.Println(out.Success) -fmt.Printf("Data: %v\n", out.Data) -``` - -### Configure, then load file - -```none -out, resp, err := c.ConfigFile.Load(ctx, "/config/test300.config") -``` - -[go-vyos]: https://github.com/ganawaj/go-vyos diff --git a/docs/automation/md-vyos-napalm.md b/docs/automation/md-vyos-napalm.md deleted file mode 100644 index 87567593..00000000 --- a/docs/automation/md-vyos-napalm.md +++ /dev/null @@ -1,152 +0,0 @@ ---- -lastproofread: '2026-04-13' ---- - -(vyos-napalm)= - -# NAPALM VyOS driver - -VyOS can be configured using the [NAPALM VyOS driver], which enables you to -retrieve device data and apply configurations via SSH. - -:::{note} -The `napalm-vyos` module is currently in testing. -::: - -To use the NAPALM VyOS driver, install the following packages: - -```none -apt install python3-pip -pip3 install napalm -pip3 install napalm-vyos -``` - -## Retrieve device data - -The following script connects to a VyOS device, retrieves device facts and -the ARP table, and prints the output in JSON format. - -```none -#!/usr/bin/env python3 - -import json -from napalm import get_network_driver - -driver = get_network_driver('vyos') - -vyos_router = driver( - hostname="192.0.2.1", - username="vyos", - password="vyospass", - optional_args={"port": 22}, -) - -vyos_router.open() -output = vyos_router.get_facts() -print(json.dumps(output, indent=4)) - -output = vyos_router.get_arp_table() -print(json.dumps(output, indent=4)) - -vyos_router.close() -``` - -Output: - -```none -$ ./vyos-napalm.py -{ - "uptime": 7185, - "vendor": "VyOS", - "os_version": "1.3.0-rc5", - "serial_number": "", - "model": "Standard PC (Q35 + ICH9, 2009)", - "hostname": "r4-1.3", - "fqdn": "vyos.local", - "interface_list": [ - "eth0", - "eth1", - "eth2", - "lo", - "vtun10" - ] -} -[ - { - "interface": "eth1", - "mac": "52:54:00:b2:38:2c", - "ip": "192.0.2.2", - "age": 0.0 - }, - { - "interface": "eth0", - "mac": "52:54:00:a2:b9:5b", - "ip": "203.0.113.11", - "age": 0.0 - } -] -``` - -## Apply a configuration - -To apply a configuration using NAPALM VyOS driver, you will need a file with -configuration commands (`commands.conf`) and a script that executes and -commits them (`vyos-napalm.py`). - -- `commands.conf` - -```none -set service ssh disable-host-validation -set service ssh port '2222' -set system name-server '192.0.2.8' -set system name-server '203.0.113.8' -set interfaces ethernet eth1 description 'FOO' -``` - -- `vyos-napalm.py` - -```none -#!/usr/bin/env python3 - -from napalm import get_network_driver - -driver = get_network_driver('vyos') - -vyos_router = driver( - hostname="192.0.2.1", - username="vyos", - password="vyospass", - optional_args={"port": 22}, -) - -vyos_router.open() -vyos_router.load_merge_candidate(filename='commands.conf') -diffs = vyos_router.compare_config() - -if bool(diffs) == True: - print(diffs) - vyos_router.commit_config() -else: - print('No configuration changes to commit') - vyos_router.discard_config() - -vyos_router.close() -``` - -Output: - -```none -$./vyos-napalm.py -[edit interfaces ethernet eth1] -+description FOO -[edit service ssh] -+disable-host-validation -+port 2222 -[edit system] -+name-server 192.0.2.8 -+name-server 203.0.113.8 -[edit] -``` - -[napalm]: https://napalm.readthedocs.io/en/latest/base.html -[NAPALM VyOS driver]: https://github.com/napalm-automation-community/napalm-vyos diff --git a/docs/automation/md-vyos-netmiko.md b/docs/automation/md-vyos-netmiko.md deleted file mode 100644 index 2e947b6a..00000000 --- a/docs/automation/md-vyos-netmiko.md +++ /dev/null @@ -1,76 +0,0 @@ ---- -lastproofread: '2026-04-13' ---- - -(vyos-netmiko)= - -# Netmiko - -VyOS can be configured using [Netmiko]. To use Netmiko, install the -`python3-netmiko` module. - -## Example - -The following script connects to a VyOS device, applies configuration changes, -commits them, and runs an operational mode command to verify the updated -configuration. - -```none -#!/usr/bin/env python3 - -from netmiko import ConnectHandler - -vyos_router = { - "device_type": "vyos", - "host": "192.0.2.1", - "username": "vyos", - "password": "vyospass", - "port": 22, - } - -net_connect = ConnectHandler(**vyos_router) - -config_commands = [ - 'set interfaces ethernet eth0 description WAN', - 'set interfaces ethernet eth1 description LAN', - ] - -# set configuration -output = net_connect.send_config_set(config_commands, exit_config_mode=False) -print(output) - -# commit configuration -output = net_connect.commit() -print(output) - -# operational mode commands -output = net_connect.send_command("run show interfaces") -print(output) -``` - -Output - -```none -$ ./vyos-netmiko.py -configure -set interfaces ethernet eth0 description WAN -[edit] -vyos@r4-1.5# set interfaces ethernet eth1 description LAN -[edit] -vyos@r4-1.5# -commit -[edit] -vyos@r4-1.5# -Codes: S - State, L - Link, u - Up, D - Down, A - Admin Down -Interface IP Address S/L Description ---------- ---------- --- ----------- -eth0 203.0.113.1/24 u/u WAN -eth1 192.0.2.1/30 u/u LAN -eth2 - u/u -lo 127.0.0.1/8 u/u - ::1/128 -vtun10 10.10.0.1/24 u/u -[edit] -``` - -[netmiko]: https://github.com/ktbyers/netmiko diff --git a/docs/automation/md-vyos-pyvyos.md b/docs/automation/md-vyos-pyvyos.md deleted file mode 100644 index 2a9599d7..00000000 --- a/docs/automation/md-vyos-pyvyos.md +++ /dev/null @@ -1,138 +0,0 @@ ---- -lastproofread: '2026-04-14' ---- - -(vyos-pyvyos)= - -# PyVyOS - -PyVyOS is a Python library for configuring and managing VyOS devices through -their API. - -**Key resources:** - -- [Documentation](https://pyvyos.readthedocs.io/en/latest/): Provides - installation, configuration, and usage instructions. -- [GitHub repository](https://github.com/robertoberto/pyvyos): Hosts the - source code. -- [PyPI](https://pypi.org/project/pyvyos/): Hosts distribution packages for - installation via the Python package installer (`pip`). - -## Installation - -To install PyVyOS via `pip`, run: - -```bash -pip install pyvyos -``` - -## Getting started - -### Import and disable warnings for verify=false - -```none -import urllib3 -urllib3.disable_warnings() -``` - -### Use API response class - -```none -@dataclass -class ApiResponse: - status: int - request: dict - result: dict - error: str -``` - -### Initialize a VyDevice object - -```none -from dotenv import load_dotenv -load_dotenv() - -hostname = os.getenv('VYDEVICE_HOSTNAME') -apikey = os.getenv('VYDEVICE_APIKEY') -port = os.getenv('VYDEVICE_PORT') -protocol = os.getenv('VYDEVICE_PROTOCOL') -verify_ssl = os.getenv('VYDEVICE_VERIFY_SSL') - -verify = verify_ssl.lower() == "true" if verify_ssl else True - -device = VyDevice(hostname=hostname, apikey=apikey, port=port, protocol=protocol, verify=verify) -``` - -## Use PyVyOS - -### Configure, then set - -```none -response = device.configure_set(path=["interfaces", "ethernet", "eth0", "address", "192.168.1.1/24"]) -if not response.error: - print(response.result) -``` - -### Configure, then show a single object value - -```none -response = device.retrieve_return_values(path=["interfaces", "dummy", "dum1", "address"]) -print(response.result) -``` - -### Configure, then show object - -```none -response = device.retrieve_show_config(path=[]) -if not response.error: - print(response.result) -``` - -### Configure, then delete object - -```none -response = device.configure_delete(path=["interfaces", "dummy", "dum1"]) -``` - -### Configure, then save - -```none -response = device.config_file_save() -``` - -### Configure, then save file - -```none -response = device.config_file_save(file="/config/test300.config") -``` - -### Show object - -```none -response = device.show(path=["system", "image"]) -print(response.result) -``` - -### Generate object - -```none -randstring = ''.join(random.choice(string.ascii_letters + string.digits) for _ in range(20)) -keyrand = f'/tmp/key_{randstring}' -response = device.generate(path=["ssh", "client-key", keyrand]) -``` - -### Reset object - -```none -response = device.reset(path=["conntrack-sync", "internal-cache"]) -if not response.error: - print(response.result) -``` - -### Configure, then load file - -```none -response = device.config_file_load(file="/config/test300.config") -``` - -[pyvyos]: https://github.com/robertoberto/pyvyos diff --git a/docs/automation/terraform/md-index.md b/docs/automation/terraform/md-index.md deleted file mode 100644 index 9f741c35..00000000 --- a/docs/automation/terraform/md-index.md +++ /dev/null @@ -1,28 +0,0 @@ ---- -lastproofread: '2026-03-23' ---- - -# VyOS Terraform - -VyOS supports development infrastructure via Terraform and provisioning -via Ansible. -Terraform allows you to automate the deployment of instances on a number of -cloud and virtual platforms. This section shows how to deploy VyOS on -multiple platforms: AWS, Microsoft Azure, Google Cloud Platform (GCP), -and VMware vSphere. -For more information, see the -official documentation for [Terraform] and [Ansible]. - -```{toctree} -:caption: Guides -:maxdepth: 1 - -terraformAWS -terraformAZ -terraformGoogle -terraformvSphere -``` - -[ansible]: https://docs.ansible.com -[install]: https://developer.hashicorp.com/terraform/tutorials/aws-get-started/install-cli -[terraform]: https://developer.hashicorp.com/terraform/intro diff --git a/docs/configexamples/md-ansible.md b/docs/configexamples/md-ansible.md deleted file mode 100644 index 3f984812..00000000 --- a/docs/configexamples/md-ansible.md +++ /dev/null @@ -1,203 +0,0 @@ ---- -lastproofread: '2024-04-09' ---- - -(examples-ansible)= - -# Ansible example - -## Setting up Ansible on a server running the Debian operating system. - -In this example, we will set up a simple use of Ansible to configure -multiple VyOS routers. -We have four pre-configured routers with this configuration: - -Using the general schema for example: - -```{image} /_static/images/ansible.png -:align: center -:alt: Network Topology Diagram -:width: 80% -``` - -We have four pre-configured routers with this configuration: - -```none -set interfaces ethernet eth0 address dhcp -set service ssh -commit -save -``` - -- vyos7 - 192.0.2.105 -- vyos8 - 192.0.2.106 -- vyos9 - 192.0.2.107 -- vyos10 - 192.0.2.108 - -## Install Ansible: - -```none -# apt-get install ansible -Do you want to continue? [Y/n] y -``` - -## Install Paramiko: - -```none -#apt-get install -y python3-paramiko -``` - -## Check the version: - -```none -# ansible --version -ansible 2.10.8 -config file = None -configured module search path = ['/root/.ansible/plugins/modules', '/usr/share/ansible/plugins/modules'] -ansible python module location = /usr/lib/python3/dist-packages/ansible -executable location = /usr/bin/ansible -python version = 3.9.2 (default, Feb 28 2021, 17:03:44) [GCC 10.2.1 20210110] -``` - -## Basic configuration of ansible.cfg: - -```none -# nano /root/ansible.cfg -[defaults] -host_key_checking = no -``` - -## Add all the VyOS hosts: - -```none -# nano /root/hosts -[vyos_hosts] -vyos7 ansible_ssh_host=192.0.2.105 -vyos8 ansible_ssh_host=192.0.2.106 -vyos9 ansible_ssh_host=192.0.2.107 -vyos10 ansible_ssh_host=192.0.2.108 -``` - -## Add general variables: - -```none -# mkdir /root/group_vars/ -# nano /root/group_vars/vyos_hosts -ansible_python_interpreter: /usr/bin/python3 -ansible_network_os: vyos -ansible_connection: network_cli -ansible_user: vyos -ansible_ssh_pass: vyos -``` - -## Add a simple playbook with the tasks for each router: - -```none -# nano /root/main.yml - ---- -- hosts: vyos_hosts - gather_facts: 'no' - tasks: - - name: Configure general settings for the vyos hosts group - vyos_config: - lines: - - set system name-server 192.0.2.1 - - set interfaces ethernet eth0 description '#WAN#' - - set interfaces ethernet eth1 description '#LAN#' - - set interfaces ethernet eth2 disable - - set interfaces ethernet eth3 disable - - set system host-name {{ inventory_hostname }} - save: true -``` - -## Start the playbook: - -```none -ansible-playbook -i hosts main.yml -PLAY [vyos_hosts] ************************************************************** - -TASK [Configure general settings for the vyos hosts group] ********************* -ok: [vyos9] -ok: [vyos10] -ok: [vyos7] -ok: [vyos8] - -PLAY RECAP ********************************************************************* -vyos10 : ok=2 changed=0 unreachable=0 failed=0 skipped=0 rescued=0 ignored=0 -vyos7 : ok=2 changed=0 unreachable=0 failed=0 skipped=0 rescued=0 ignored=0 -vyos8 : ok=2 changed=0 unreachable=0 failed=0 skipped=0 rescued=0 ignored=0 -vyos9 : ok=2 changed=0 unreachable=0 failed=0 skipped=0 rescued=0 ignored=0 -``` - -## Check the result on the vyos10 router: - -```none -vyos@vyos10:~$ show interfaces -Codes: S - State, L - Link, u - Up, D - Down, A - Admin Down -Interface IP Address S/L Description ---------- ---------- --- ----------- -eth0 192.0.2.108/24 u/u WAN -eth1 - u/u LAN -eth2 - A/D -eth3 - A/D -lo 127.0.0.1/8 u/u - ::1/128 - -vyos@vyos10:~$ sh configuration commands | grep 192.0.2.1 -set system name-server '192.0.2.1' -``` - -## The simple way without configuration of the hostname (one task for all routers): - -```none -# nano /root/hosts_v2 -[vyos_hosts_group] -vyos7 ansible_ssh_host=192.0.2.105 -vyos8 ansible_ssh_host=192.0.2.106 -vyos9 ansible_ssh_host=192.0.2.107 -vyos10 ansible_ssh_host=192.0.2.108 -[vyos_hosts_group:vars] -ansible_python_interpreter=/usr/bin/python3 -ansible_user=vyos -ansible_ssh_pass=vyos -ansible_network_os=vyos -ansible_connection=network_cli - -# nano /root/main_v2.yml ---- -- hosts: vyos_hosts_group - connection: network_cli - gather_facts: 'no' - tasks: - - name: Configure remote vyos_hosts_group - vyos_config: - lines: - - set system name-server 192.0.2.1 - - set interfaces ethernet eth0 description WAN - - set interfaces ethernet eth1 description LAN - - set interfaces ethernet eth2 disable - - set interfaces ethernet eth3 disable - save: true -``` - -```none -# ansible-playbook -i hosts_v2 main_v2.yml - -PLAY [vyos_hosts_group] ******************************************************** - -TASK [Configure remote vyos_hosts_group] *************************************** -ok: [vyos8] -ok: [vyos7] -ok: [vyos9] -ok: [vyos10] - -PLAY RECAP ********************************************************************* -vyos10 : ok=1 changed=0 unreachable=0 failed=0 skipped=0 rescued=0 ignored=0 -vyos7 : ok=1 changed=0 unreachable=0 failed=0 skipped=0 rescued=0 ignored=0 -vyos8 : ok=1 changed=0 unreachable=0 failed=0 skipped=0 rescued=0 ignored=0 -vyos9 : ok=1 changed=0 unreachable=0 failed=0 skipped=0 rescued=0 ignored=0 -``` - -In the next chapter of the example, we'll use Ansible with jinja2 -templates and variables. diff --git a/docs/configexamples/md-bgp-ipv6-unnumbered.md b/docs/configexamples/md-bgp-ipv6-unnumbered.md deleted file mode 100644 index 36d8cf39..00000000 --- a/docs/configexamples/md-bgp-ipv6-unnumbered.md +++ /dev/null @@ -1,173 +0,0 @@ ---- -lastproofread: '2021-06-28' ---- - -(examples-bgp-ipv6-unnumbered)= - -# BGP IPv6 unnumbered with extended nexthop - -General information can be found in the {ref}`routing-bgp` chapter. - -## Configuration - -- Router A: - -```none -set protocols bgp system-as 64496 -set protocols bgp address-family ipv4-unicast redistribute connected -set protocols bgp address-family ipv6-unicast redistribute connected -set protocols bgp neighbor eth1 interface v6only -set protocols bgp neighbor eth1 interface v6only peer-group 'fabric' -set protocols bgp neighbor eth2 interface v6only -set protocols bgp neighbor eth2 interface v6only peer-group 'fabric' -set protocols bgp parameters bestpath as-path multipath-relax -set protocols bgp parameters bestpath compare-routerid -set protocols bgp parameters default no-ipv4-unicast -set protocols bgp parameters router-id '192.168.0.1' -set protocols bgp peer-group fabric address-family ipv4-unicast -set protocols bgp peer-group fabric address-family ipv6-unicast -set protocols bgp peer-group fabric capability extended-nexthop -set protocols bgp peer-group fabric remote-as 'external' -``` - -- Router B: - -```none -set protocols bgp system-as 64499 -set protocols bgp address-family ipv4-unicast redistribute connected -set protocols bgp address-family ipv6-unicast redistribute connected -set protocols bgp neighbor eth1 interface v6only -set protocols bgp neighbor eth1 interface v6only peer-group 'fabric' -set protocols bgp neighbor eth2 interface v6only -set protocols bgp neighbor eth2 interface v6only peer-group 'fabric' -set protocols bgp parameters bestpath as-path multipath-relax -set protocols bgp parameters bestpath compare-routerid -set protocols bgp parameters default no-ipv4-unicast -set protocols bgp parameters router-id '192.168.0.2' -set protocols bgp peer-group fabric address-family ipv4-unicast -set protocols bgp peer-group fabric address-family ipv6-unicast -set protocols bgp peer-group fabric capability extended-nexthop -set protocols bgp peer-group fabric remote-as 'external' -``` - -## Results - -- Router A: - -```none -vyos@vyos:~$ show interfaces -Codes: S - State, L - Link, u - Up, D - Down, A - Admin Down -Interface IP Address S/L Description ---------- ---------- --- ----------- -eth0 198.51.100.34/24 u/u -eth1 - u/u -eth2 - u/u -lo 127.0.0.1/8 u/u - 192.168.0.1/32 - ::1/128 -``` - -```none -vyos@vyos:~$ show ip route -Codes: K - kernel route, C - connected, S - static, R - RIP, - O - OSPF, I - IS-IS, B - BGP, E - EIGRP, N - NHRP, - T - Table, v - VNC, V - VNC-Direct, A - Babel, D - SHARP, - F - PBR, f - OpenFabric, - > - selected route, * - FIB route - -S>* 0.0.0.0/0 [210/0] via 198.51.100.34, eth0, 03:21:53 -C>* 198.51.100.0/24 is directly connected, eth0, 03:21:53 -C>* 192.168.0.1/32 is directly connected, lo, 03:21:56 -B>* 192.168.0.2/32 [20/0] via fe80::a00:27ff:fe3b:7ed2, eth2, 00:05:07 - * via fe80::a00:27ff:fe7b:4000, eth1, 00:05:07 -``` - -```none -vyos@vyos:~$ ping 192.168.0.2 -PING 192.168.0.2 (192.168.0.2) 56(84) bytes of data. -64 bytes from 192.168.0.2: icmp_seq=1 ttl=64 time=0.575 ms -64 bytes from 192.168.0.2: icmp_seq=2 ttl=64 time=0.628 ms -64 bytes from 192.168.0.2: icmp_seq=3 ttl=64 time=0.581 ms -64 bytes from 192.168.0.2: icmp_seq=4 ttl=64 time=0.682 ms -64 bytes from 192.168.0.2: icmp_seq=5 ttl=64 time=0.597 ms - ---- 192.168.0.2 ping statistics --- -5 packets transmitted, 5 received, 0% packet loss, time 4086ms -rtt min/avg/max/mdev = 0.575/0.612/0.682/0.047 ms -``` - -```none -vyos@vyos:~$ show ip bgp summary - -IPv4 Unicast Summary: -BGP router identifier 192.168.0.1, local AS number 65020 vrf-id 0 -BGP table version 4 -RIB entries 5, using 800 bytes of memory -Peers 2, using 41 KiB of memory -Peer groups 1, using 64 bytes of memory - -Neighbor V AS MsgRcvd MsgSent TblVer InQ OutQ Up/Down State/PfxRcd -eth1 4 64499 13 13 0 0 0 00:05:33 2 -eth2 4 64499 13 14 0 0 0 00:05:29 2 - -Total number of neighbors 2 -``` - -- Router B: - -```none -vyos@vyos:~$ show interfaces -Codes: S - State, L - Link, u - Up, D - Down, A - Admin Down -Interface IP Address S/L Description ---------- ---------- --- ----------- -eth0 198.51.100.33/24 u/u -eth1 - u/u -eth2 - u/u -lo 127.0.0.1/8 u/u - 192.168.0.2/32 - ::1/128 -``` - -```none -vyos@vyos:~$ show ip route -Codes: K - kernel route, C - connected, S - static, R - RIP, - O - OSPF, I - IS-IS, B - BGP, E - EIGRP, N - NHRP, - T - Table, v - VNC, V - VNC-Direct, A - Babel, D - SHARP, - F - PBR, f - OpenFabric, - > - selected route, * - FIB route - -S>* 0.0.0.0/0 [210/0] via 198.51.100.33, eth0, 00:44:08 -C>* 198.51.100.0/24 is directly connected, eth0, 00:44:09 -B>* 192.168.0.1/32 [20/0] via fe80::a00:27ff:fe2d:205d, eth1, 00:06:18 - * via fe80::a00:27ff:fe93:e142, eth2, 00:06:18 -C>* 192.168.0.2/32 is directly connected, lo, 00:44:11 -``` - -```none -vyos@vyos:~$ ping 192.168.0.1 -PING 192.168.0.1 (192.168.0.1) 56(84) bytes of data. -64 bytes from 192.168.0.1: icmp_seq=1 ttl=64 time=0.427 ms -64 bytes from 192.168.0.1: icmp_seq=2 ttl=64 time=0.471 ms -64 bytes from 192.168.0.1: icmp_seq=3 ttl=64 time=0.782 ms -64 bytes from 192.168.0.1: icmp_seq=4 ttl=64 time=0.715 ms - ---- 192.168.0.1 ping statistics --- -4 packets transmitted, 4 received, 0% packet loss, time 3051ms -rtt min/avg/max/mdev = 0.427/0.598/0.782/0.155 ms -``` - -```none -vyos@vyos:~$ show ip bgp summary -IPv4 Unicast Summary: -BGP router identifier 192.168.0.2, local AS number 65021 vrf-id 0 -BGP table version 4 -RIB entries 5, using 800 bytes of memory -Peers 2, using 41 KiB of memory -Peer groups 1, using 64 bytes of memory - -Neighbor V AS MsgRcvd MsgSent TblVer InQ OutQ Up/Down State/PfxRcd -eth1 4 64496 14 14 0 0 0 00:06:40 2 -eth2 4 64496 14 14 0 0 0 00:06:37 2 - -Total number of neighbors 2 -``` diff --git a/docs/configexamples/md-dmvpn-dualhub-dualcloud.md b/docs/configexamples/md-dmvpn-dualhub-dualcloud.md deleted file mode 100644 index 8f5639b1..00000000 --- a/docs/configexamples/md-dmvpn-dualhub-dualcloud.md +++ /dev/null @@ -1,523 +0,0 @@ ---- -lastproofread: '2024-02-21' ---- - -(examples-dmvpn-dualhub-dualcloud)= - -# DMVPN Dual HUB Dual Cloud - -This document is to describe a basic setup to build DVMPN network with two Hubs and two clouds using DMVPN Phase3. -OSPF is used as routing protocol inside DMVPN. - -In this example we use VyOS 1.5 as HUBs and Spokes (HUB-1, HUB-2, SPOKE-2, SPOKE-3) and Cisco IOSv 15.5(3)M (SPOKE-1) -as a Spoke. - -## Network Topology - -```{image} /_static/images/dual-hub-DMVPN.png -:align: center -:alt: DMVPN Network Topology -:width: 80% -``` - -## Configurations - -### Underlay configuration -Networks 192.168.X.0/24 are used as LANs for every spoke. - -HUB-1 - -```none -set interfaces ethernet eth0 address '10.0.0.2/30' -set protocols static route 0.0.0.0/0 next-hop 10.0.0.1 -``` - -HUB-2 - -```none -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 -``` - -Spoke-1 - -```none -interface GigabitEthernet0/0 - ip address 10.0.11.2 255.255.255.252 - duplex auto - speed auto - media-type rj45 -! -interface GigabitEthernet0/1 - ip address 192.168.11.1 255.255.255.0 - ip ospf 1 area 0 - duplex auto - speed auto - media-type rj45 -! -ip route 0.0.0.0 0.0.0.0 10.0.11.1 -``` - -Spoke-2 - -```none -set interfaces ethernet eth0 address '10.0.12.2/30' -set interfaces ethernet eth1 address '192.168.12.1/24' -set protocols static route 0.0.0.0/0 next-hop 10.0.12.1 -``` - -Spoke-3 - -```none -set interfaces ethernet eth0 address '10.0.13.2/30' -set interfaces ethernet eth1 address '192.168.13.1/24' -set protocols static route 0.0.0.0/0 next-hop 10.0.13.1 -``` - -### NHRP configuration -The next step is to configure the NHRP protocol. In a Dual cloud network, every HUB has to be configured with one GRE -multipoint tunnel interface and every spoke has to be configured with two tunnel interfaces, one tunnel to each hub. -In this example tunnel networks are 10.100.100.0/24 for the first cloud and 10.100.101.0/24 for the second cloud. -But VyOS uses FRR for NHRP, that is why the tunnel address mask must be /32. - -HUB-1 - -```none -set interfaces tunnel tun100 address '10.100.100.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 '1436' -set interfaces tunnel tun100 parameters ip key '42' -set interfaces tunnel tun100 source-interface 'eth0' -set protocols nhrp tunnel tun100 authentication 'vyos' -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 -``` - -HUB-2 - -```none -set interfaces tunnel tun101 address '10.100.101.1/32' -set interfaces tunnel tun101 enable-multicast -set interfaces tunnel tun101 encapsulation 'gre' -set interfaces tunnel tun101 ip adjust-mss '1360' -set interfaces tunnel tun101 mtu '1436' -set interfaces tunnel tun101 parameters ip key '43' -set interfaces tunnel tun101 source-interface 'eth0' -set protocols nhrp tunnel tun101 authentication 'vyos' -set protocols nhrp tunnel tun101 holdtime '300' -set protocols nhrp tunnel tun101 multicast 'dynamic' -set protocols nhrp tunnel tun101 network-id '2' -set protocols nhrp tunnel tun101 redirect -set protocols nhrp tunnel tun101 registration-no-unique -``` - -Spoke-1 - -```none -interface Tunnel100 - ip address 10.100.100.11 255.255.255.0 - no ip redirects - ip mtu 1436 - ip nhrp authentication vyos - ip nhrp map multicast 10.0.0.2 - ip nhrp network-id 1 - ip nhrp holdtime 300 - ip nhrp nhs 10.100.100.1 nbma 10.0.0.2 - ip nhrp shortcut - ip tcp adjust-mss 1360 - tunnel source GigabitEthernet0/0 - tunnel mode gre multipoint - tunnel key 42 -! -interface Tunnel101 - ip address 10.100.101.11 255.255.255.0 - no ip redirects - ip mtu 1436 - ip nhrp authentication vyos - ip nhrp map multicast 10.0.1.2 - ip nhrp network-id 2 - ip nhrp holdtime 300 - ip nhrp nhs 10.100.101.1 nbma 10.0.1.2 - ip nhrp shortcut - ip tcp adjust-mss 1360 - tunnel source GigabitEthernet0/0 - tunnel mode gre multipoint - tunnel key 43 -``` - -Spoke-2 - -```none -set interfaces tunnel tun100 address '10.100.100.12/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 '1436' -set interfaces tunnel tun100 parameters ip key '42' -set interfaces tunnel tun100 source-interface 'eth0' -set interfaces tunnel tun101 address '10.100.101.12/32' -set interfaces tunnel tun101 enable-multicast -set interfaces tunnel tun101 encapsulation 'gre' -set interfaces tunnel tun101 ip adjust-mss '1360' -set interfaces tunnel tun101 mtu '1436' -set interfaces tunnel tun101 parameters ip key '43' -set interfaces tunnel tun101 source-interface 'eth0' -set protocols nhrp tunnel tun100 authentication 'vyos' -set protocols nhrp tunnel tun100 holdtime '300' -set protocols nhrp tunnel tun100 multicast '10.0.0.2' -set protocols nhrp tunnel tun100 network-id '1' -set protocols nhrp tunnel tun100 nhs tunnel-ip dynamic nbma '10.0.0.2' -set protocols nhrp tunnel tun100 registration-no-unique -set protocols nhrp tunnel tun100 shortcut -set protocols nhrp tunnel tun101 authentication 'vyos' -set protocols nhrp tunnel tun101 holdtime '300' -set protocols nhrp tunnel tun101 multicast '10.0.1.2' -set protocols nhrp tunnel tun101 network-id '2' -set protocols nhrp tunnel tun101 nhs tunnel-ip dynamic nbma '10.0.1.2' -set protocols nhrp tunnel tun101 registration-no-unique -set protocols nhrp tunnel tun101 shortcut -``` - -Spoke-3 - -```none -set protocols nhrp tunnel tun100 authentication 'vyos' -set protocols nhrp tunnel tun100 holdtime '300' -set protocols nhrp tunnel tun100 multicast '10.0.0.2' -set protocols nhrp tunnel tun100 network-id '1' -set protocols nhrp tunnel tun100 nhs tunnel-ip dynamic nbma '10.0.0.2' -set protocols nhrp tunnel tun100 registration-no-unique -set protocols nhrp tunnel tun100 shortcut -set protocols nhrp tunnel tun101 authentication 'vyos' -set protocols nhrp tunnel tun101 holdtime '300' -set protocols nhrp tunnel tun101 multicast '10.0.1.2' -set protocols nhrp tunnel tun101 network-id '2' -set protocols nhrp tunnel tun101 nhs tunnel-ip dynamic nbma '10.0.1.2' -set protocols nhrp tunnel tun101 registration-no-unique -set protocols nhrp tunnel tun101 shortcut -``` - -### Overlay configuration -The last step is to configure the routing protocol. In this scenario, OSPF was chosen as the dynamic routing protocol. -But you can use iBGP or eBGP. To form fast convergence it is possible to use BFD protocol. - -HUB-1 - -```none -set protocols ospf interface tun100 area '0' -set protocols ospf interface tun100 network 'point-to-multipoint' -set protocols ospf interface tun100 passive disable -set protocols ospf passive-interface 'default' -``` - -HUB-2 - -```none -set protocols ospf interface tun101 area '0' -set protocols ospf interface tun101 network 'point-to-multipoint' -set protocols ospf interface tun101 passive disable -set protocols ospf passive-interface 'default' -``` - -Spoke-1 - -```none -interface Tunnel100 - ip ospf network point-to-multipoint - ip ospf dead-interval 40 - ip ospf hello-interval 10 - ip ospf 1 area 0 -! -interface Tunnel101 - ip ospf network point-to-multipoint - ip ospf dead-interval 40 - ip ospf hello-interval 10 - ip ospf 1 area 0 -! -router ospf 1 - passive-interface default - no passive-interface Tunnel100 - no passive-interface Tunnel101 -``` - -Spoke-2 - -```none -set protocols ospf interface eth1 area '0' -set protocols ospf interface tun100 area '0' -set protocols ospf interface tun100 network 'point-to-multipoint' -set protocols ospf interface tun100 passive disable -set protocols ospf interface tun101 area '0' -set protocols ospf interface tun101 network 'point-to-multipoint' -set protocols ospf interface tun101 passive disable -set protocols ospf passive-interface 'default' -``` - -Spoke-3 - -```none -set protocols ospf interface eth1 area '0' -set protocols ospf interface tun100 area '0' -set protocols ospf interface tun100 network 'point-to-multipoint' -set protocols ospf interface tun100 passive disable -set protocols ospf interface tun101 area '0' -set protocols ospf interface tun101 network 'point-to-multipoint' -set protocols ospf interface tun101 passive disable -set protocols ospf passive-interface 'default' -``` - -### Security configuration -Tunnels can be encrypted by IPSEC for security. - -HUB-1 - -```none -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 'disable' -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' -``` - -HUB-2 - -```none -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 'disable' -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 'tun101' -set vpn ipsec profile NHRPVPN esp-group 'ESP-HUB' -set vpn ipsec profile NHRPVPN ike-group 'IKE-HUB' -``` - -VyOS Spokes have the same configuration - -```none -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 'disable' -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 bind tunnel 'tun101' -set vpn ipsec profile NHRPVPN esp-group 'ESP-HUB' -set vpn ipsec profile NHRPVPN ike-group 'IKE-HUB' -``` - -SPOKE-1 - -```none -crypto isakmp policy 1 - encr aes 256 - authentication pre-share - group 2 - lifetime 3600 -crypto isakmp key secret address 0.0.0.0 -! -! -crypto ipsec transform-set ESP_TRANSFORMSET esp-aes 256 esp-sha-hmac - mode transport -! -! -crypto ipsec profile gre_protection - set security-association lifetime seconds 1800 - set transform-set ESP_TRANSFORMSET -! -interface Tunnel100 - tunnel protection ipsec profile gre_protection shared -! -interface Tunnel101 - tunnel protection ipsec profile gre_protection shared -``` - -## Monitoring -All spokes created IPSec tunnels to Hubs, are registered on Hubs using NHRP protocol and formed adjacency in OSPF. -```none -vyos@HUB-1:~$ show vpn ipsec sa -Connection State Uptime Bytes In/Out Packets In/Out Remote address Remote ID Proposal --------------------------- ------- -------- -------------- ---------------- ---------------- ----------- ------------------------ -dmvpn-NHRPVPN-tun100-child up 6m1s 4K/5K 51/56 10.0.13.2 10.0.13.2 AES_CBC_256/HMAC_SHA1_96 -dmvpn-NHRPVPN-tun100-child up 6m36s 4K/6K 56/65 10.0.12.2 10.0.12.2 AES_CBC_256/HMAC_SHA1_96 -dmvpn-NHRPVPN-tun100-child up 8m49s 6K/6K 73/77 10.0.11.2 10.0.11.2 AES_CBC_256/HMAC_SHA1_96 - -vyos@HUB-1:~$ show ip nhrp cache -Iface Type Protocol NBMA Claimed NBMA Flags Identity -tun100 dynamic 10.100.100.12 10.0.12.2 10.0.12.2 T 10.0.12.2 -tun100 dynamic 10.100.100.13 10.0.13.2 10.0.13.2 T 10.0.13.2 -tun100 dynamic 10.100.100.11 10.0.11.2 10.0.11.2 T 10.0.11.2 -tun100 local 10.100.100.1 10.0.0.2 10.0.0.2 - - -vyos@HUB-1:~$ show ip ospf neighbor - -Neighbor ID Pri State Up Time Dead Time Address Interface RXmtL RqstL DBsmL -192.168.11.1 1 Full/DROther 17m01s 36.201s 10.100.100.11 tun100:10.100.100.1 0 0 0 -192.168.12.1 1 Full/DROther 9m42s 37.443s 10.100.100.12 tun100:10.100.100.1 0 0 0 -192.168.13.1 1 Full/DROther 9m15s 35.053s 10.100.100.13 tun100:10.100.100.1 0 0 0 -``` -First, we see that LANs are accessible through hubs using OSPF routes. -```none -SPOKE-1#show ip route -Codes: L - local, C - connected, S - static, R - RIP, M - mobile, B - BGP - D - EIGRP, EX - EIGRP external, O - OSPF, IA - OSPF inter area - N1 - OSPF NSSA external type 1, N2 - OSPF NSSA external type 2 - E1 - OSPF external type 1, E2 - OSPF external type 2 - i - IS-IS, su - IS-IS summary, L1 - IS-IS level-1, L2 - IS-IS level-2 - ia - IS-IS inter area, * - candidate default, U - per-user static route - o - ODR, P - periodic downloaded static route, H - NHRP, l - LISP - a - application route - + - replicated route, % - next hop override, p - overrides from PfR - -Gateway of last resort is 10.0.11.1 to network 0.0.0.0 -..... - 192.168.11.0/24 is variably subnetted, 2 subnets, 2 masks -C 192.168.11.0/24 is directly connected, GigabitEthernet0/1 -L 192.168.11.1/32 is directly connected, GigabitEthernet0/1 -O 192.168.12.0/24 [110/1002] via 10.100.101.1, 00:14:36, Tunnel101 - [110/1002] via 10.100.100.1, 00:16:13, Tunnel100 -O 192.168.13.0/24 [110/1002] via 10.100.101.1, 00:14:36, Tunnel101 - [110/1002] via 10.100.100.1, 00:15:45, Tunnel100 - - -vyos@SPOKE-2:~$ show ip route -Codes: K - kernel route, C - connected, L - local, S - static, - R - RIP, O - OSPF, I - IS-IS, B - BGP, E - EIGRP, N - NHRP, - T - Table, v - VNC, V - VNC-Direct, A - Babel, F - PBR, - f - OpenFabric, t - Table-Direct, - > - selected route, * - FIB route, q - queued, r - rejected, b - backup - t - trapped, o - offload failure - -...... - -O>* 192.168.11.0/24 [110/3] via 10.100.100.1, tun100 onlink, weight 1, 00:12:36 - * via 10.100.101.1, tun101 onlink, weight 1, 00:12:36 -O 192.168.12.0/24 [110/1] is directly connected, eth1, weight 1, 01:24:40 -C>* 192.168.12.0/24 is directly connected, eth1, weight 1, 01:24:43 -L>* 192.168.12.1/32 is directly connected, eth1, weight 1, 01:24:43 -O>* 192.168.13.0/24 [110/3] via 10.100.100.1, tun100 onlink, weight 1, 00:12:36 - * via 10.100.101.1, tun101 onlink, weight 1, 00:12:36 -``` -After initiating traffic between SPOKES sites, Phase 3 of DMVPN will work. -For instance, traceroute was generated from PC-SPOKE-2 to PC-SPOKE-1 -```none -PC-SPOKE-2 : 192.168.12.2 255.255.255.0 gateway 192.168.12.1 - -PC-SPOKE-2> trace 192.168.11.2 -trace to 192.168.11.2, 8 hops max, press Ctrl+C to stop - 1 192.168.12.1 0.558 ms 0.378 ms 0.561 ms - 2 10.100.101.1 1.768 ms 1.158 ms 1.744 ms - 3 10.100.101.11 7.196 ms 4.971 ms 4.793 ms - 4 *192.168.11.2 7.747 ms (ICMP type:3, code:3, Destination port unreachable) - -PC-SPOKE-2> trace 192.168.11.2 -trace to 192.168.11.2, 8 hops max, press Ctrl+C to stop - 1 192.168.12.1 0.562 ms 0.396 ms 0.364 ms - 2 10.100.100.11 4.401 ms 4.399 ms 4.174 ms - 3 *192.168.11.2 3.241 ms (ICMP type:3, code:3, Destination port unreachable) -``` -First trace goes via HUB but the second goes directly from SPOKE-1 to SPOKE-2. -Now routing tables are changed. LAN networks 192.168.12.0/24 and 192.168.11.0/24 available directly via SPOKES. -```none -vyos@SPOKE-2:~$ show ip route -Codes: K - kernel route, C - connected, L - local, S - static, - R - RIP, O - OSPF, I - IS-IS, B - BGP, E - EIGRP, N - NHRP, - T - Table, v - VNC, V - VNC-Direct, A - Babel, F - PBR, - f - OpenFabric, t - Table-Direct, - > - selected route, * - FIB route, q - queued, r - rejected, b - backup - t - trapped, o - offload failure - -N>* 192.168.11.0/24 [10/0] via 10.100.100.11, tun100 onlink, weight 1, 00:00:14 -O 192.168.11.0/24 [110/3] via 10.100.100.1, tun100 onlink, weight 1, 00:00:54 - via 10.100.101.1, tun101 onlink, weight 1, 00:00:54 - - -SPOKE-1# show ip route next-hop-override -Codes: L - local, C - connected, S - static, R - RIP, M - mobile, B - BGP - D - EIGRP, EX - EIGRP external, O - OSPF, IA - OSPF inter area - N1 - OSPF NSSA external type 1, N2 - OSPF NSSA external type 2 - E1 - OSPF external type 1, E2 - OSPF external type 2 - i - IS-IS, su - IS-IS summary, L1 - IS-IS level-1, L2 - IS-IS level-2 - ia - IS-IS inter area, * - candidate default, U - per-user static route - o - ODR, P - periodic downloaded static route, H - NHRP, l - LISP - a - application route - + - replicated route, % - next hop override, p - overrides from PfR - -Gateway of last resort is 10.0.11.1 to network 0.0.0.0 - -O % 192.168.12.0/24 [110/1002] via 10.100.101.1, 00:24:09, Tunnel101 - [110/1002] via 10.100.100.1, 00:25:46, Tunnel100 - [NHO][110/1] via 10.100.100.12, 00:00:03, Tunnel100 -``` -NHRP shows shortcuts on Spokes -```none -vyos@SPOKE-2:~$ show ip nhrp shortcut -Type Prefix Via Identity -dynamic 192.168.11.0/24 10.100.100.11 10.0.11.2 - -SPOKE-1# show ip nhrp shortcut -10.100.100.12/32 via 10.100.100.12 - Tunnel100 created 00:09:59, expire 00:02:21 - Type: dynamic, Flags: router nhop rib nho - NBMA address: 10.0.12.2 -192.168.12.0/24 via 10.100.100.12 - Tunnel100 created 00:02:38, expire 00:02:21 - Type: dynamic, Flags: router rib nho - NBMA address: 10.0.12.2 -``` -A new Spoke to Spoke IPSec tunnel is created -```none -SPOKE-1#show crypto isakmp sa -IPv4 Crypto ISAKMP SA -dst src state conn-id status -10.0.0.2 10.0.11.2 QM_IDLE 1002 ACTIVE -10.0.12.2 10.0.11.2 QM_IDLE 1004 ACTIVE -10.0.1.2 10.0.11.2 QM_IDLE 1003 ACTIVE - -vyos@SPOKE-2:~$ show vpn ipsec sa -Connection State Uptime Bytes In/Out Packets In/Out Remote address Remote ID Proposal --------------------------- ------- -------- -------------- ---------------- ---------------- ----------- ------------------------ -dmvpn-NHRPVPN-tun100-child up 7m26s 4K/4K 57/53 10.0.0.2 10.0.0.2 AES_CBC_256/HMAC_SHA1_96 -dmvpn-NHRPVPN-tun100-child up 11m48s 316B/1K 3/15 10.0.11.2 10.0.11.2 AES_CBC_256/HMAC_SHA1_96 -dmvpn-NHRPVPN-tun101-child up 5m58s 5K/4K 62/51 10.0.1.2 10.0.1.2 AES_CBC_256/HMAC_SHA1_96 -``` - -## Summary - -If one of the Hubs loses connectivity to the Internet, the other Hub will be available and take the main role. -This is a simple example where only one internet connection is used. But in the real world, there can be two -connections to the Internet. In this case, there is a recommendation to build each tunnel via each Internet connection, -choose the main cloud, and manipulate traffic via a routing protocol. It allows the creation failover on link-level -connections too. diff --git a/docs/configexamples/md-firewall.md b/docs/configexamples/md-firewall.md deleted file mode 100644 index 5d170511..00000000 --- a/docs/configexamples/md-firewall.md +++ /dev/null @@ -1,16 +0,0 @@ ---- -lastproofread: '2024-09-11' ---- - -# Firewall Examples - -This section contains examples of firewall configurations for various -deployments. - -```{toctree} -:maxdepth: 2 - -fwall-and-vrf -fwall-and-bridge -zone-policy -``` diff --git a/docs/configexamples/md-fwall-and-bridge.md b/docs/configexamples/md-fwall-and-bridge.md deleted file mode 100644 index 75fb6b25..00000000 --- a/docs/configexamples/md-fwall-and-bridge.md +++ /dev/null @@ -1,487 +0,0 @@ ---- -lastproofread: '2024-09-11' ---- - -# Bridge and firewall example - -## Scenario and requirements - -This example shows how to configure a VyOS router with bridge interfaces and -firewall rules. - -Three non VLAN-aware bridges are going to be configured, and each one has its -own requirements. - -- Bridge br0: - : - Isolated layer 2 bridge. - - Accept only IPv6 communication whithin the bridge. -- Bridge br1: - : - Drop all DHCP discover packets. - - Accept all ARP packets. - - Within the bridge, accept only new IPv4 connections from host 10.1.1.102 - - Drop all other IPv4 connections. - - Drop all IPv6 connections. - - Accept access to router itself. - - Allow connections to internet - - Drop connections to other LANs. -- Bridge br2: - : - Accept all DHCP discover packets. - - Accept only DHCP offers from valid server and|or trusted bridge port. - - Accept all ARP packets. - - Accept all IPv4 connections. - - Drop all IPv6 connections. - - Deny access to the router. - - Allow connections to internet. - - Allow connections to bridge br1. - -## Configuration - -### Bridges and interfaces configuration - -First, we need to configure the interfaces and bridges: - -```none -# Brige br0 -set interfaces bridge br0 description 'Isolated L2 bridge' -set interfaces bridge br0 member interface eth1 -set interfaces bridge br0 member interface eth2 -set interfaces ethernet eth1 description 'br0' -set interfaces ethernet eth2 description 'br0' - -# Bridge br1: -set interfaces bridge br1 address '10.1.1.1/24' -set interfaces bridge br1 description 'L3 bridge br1' -set interfaces bridge br1 member interface eth3 -set interfaces bridge br1 member interface eth4 -set interfaces ethernet eth3 description 'br1' -set interfaces ethernet eth4 description 'br1' - -# Bridge br2: -set interfaces bridge br2 address '10.2.2.1/24' -set interfaces bridge br2 description 'L3 bridge br2' -set interfaces bridge br2 member interface eth5 -set interfaces bridge br2 member interface eth6 -set interfaces bridge br2 member interface eth7 -set interfaces ethernet eth5 description 'br2 - Host' -set interfaces ethernet eth6 description 'br2 - Trusted DHCP Server' -set interfaces ethernet eth7 description 'br2' -``` - -### Bridge firewall configuration - -In this section, we are going to configure the firewall rules that will be used -in bridge firewall, and will control the traffic within each bridge. - -We are going to use custom firewall rulesets, one for each bridge that will -be used in `prerouting`, and one for each bridge that will be used in the -`forward` chain. - -Also, we are going to use firewall interface groups in order to simplify the -firewall configuration. - -So first, let's create the required firewall interface groups: - -```none -# Bridge br0 interface-group: -set firewall group interface-group br0-ifaces interface 'br0' -set firewall group interface-group br0-ifaces interface 'eth1' -set firewall group interface-group br0-ifaces interface 'eth2' - -# Bridge br1 interface-group: -set firewall group interface-group br1-ifaces interface 'br1' -set firewall group interface-group br1-ifaces interface 'eth3' -set firewall group interface-group br1-ifaces interface 'eth4' - -# Bridge br2 interface-group: -set firewall group interface-group br2-ifaces interface 'br2' -set firewall group interface-group br2-ifaces interface 'eth5' -set firewall group interface-group br2-ifaces interface 'eth6' -set firewall group interface-group br2-ifaces interface 'eth7' -``` - -As said before, we are going to create custom firewall rulesets for each -bridge, that will be used in the `prerouting` chain, in order to drop as much -unwanted traffic as early as possible. So, custom rulesets used in -`prerouting` chain are going to be `br0-pre`, `br1-pre`, and `br2-pre`: - -```none -# Prerouting - Catch all traffic for br0 -set firewall bridge prerouting filter rule 10 action 'jump' -set firewall bridge prerouting filter rule 10 description 'br0 traffic' -set firewall bridge prerouting filter rule 10 inbound-interface group 'br0-ifaces' -set firewall bridge prerouting filter rule 10 jump-target 'br0-pre' - -# Prerouting - Catch all traffic for br1 -set firewall bridge prerouting filter rule 20 action 'jump' -set firewall bridge prerouting filter rule 20 description 'br1 traffic' -set firewall bridge prerouting filter rule 20 inbound-interface group 'br1-ifaces' -set firewall bridge prerouting filter rule 20 jump-target 'br1-pre' - -# Prerouting - Catch all traffic for br2 -set firewall bridge prerouting filter rule 30 action 'jump' -set firewall bridge prerouting filter rule 30 description 'br2 traffic' -set firewall bridge prerouting filter rule 30 inbound-interface group 'br2-ifaces' -set firewall bridge prerouting filter rule 30 jump-target 'br2-pre' -``` - -And then create the custom rulesets: - -```none -### br0 - br0-pre - # Requirements: accept only IPv6 communication within the bridge -set firewall bridge name br0-pre rule 10 description 'Accept IPv6 traffic' -set firewall bridge name br0-pre rule 10 action 'accept' -set firewall bridge name br0-pre rule 10 ethernet-type 'ipv6' - # And drop everything else -set firewall bridge name br0-pre default-action 'drop' - -### br1 - br1-pre - # Requirements: drop all DHCP discover packets -set firewall bridge name br1-pre rule 10 description 'Drop DHCP discover' -set firewall bridge name br1-pre rule 10 action 'drop' -set firewall bridge name br1-pre rule 10 protocol 'udp' -set firewall bridge name br1-pre rule 10 source port '68' -set firewall bridge name br1-pre rule 10 destination port '67' -set firewall bridge name br1-pre rule 10 destination mac-address 'ff:ff:ff:ff:ff:ff' -set firewall bridge name br1-pre rule 10 log - # Requirement: drop all IPv6 connections -set firewall bridge name br1-pre rule 20 description 'Drop IPv6 traffic' -set firewall bridge name br1-pre rule 20 action 'drop' -set firewall bridge name br1-pre rule 20 ethernet-type 'ipv6' - # Accept everything else so it can be parsed later -set firewall bridge name br1-pre default-action 'accept' - -### br2 - br2-pre - # Requirements: drop all IPv6 connections -set firewall bridge name br2-pre rule 10 description 'Drop IPv6 traffic' -set firewall bridge name br2-pre rule 10 action 'drop' -set firewall bridge name br2-pre rule 10 ethernet-type 'ipv6' - # Accept everything else so it can be parsed later -set firewall bridge name br2-pre default-action 'accept' -``` - -Now, in the `forward` chain, we are going to define state policies, and -custom rulesets for each bridge that would be used in the `forward` chain. -These rulesets are `br0-fwd`, `br1-fwd`, and `br2-fwd`: - -```none -# Forward - State policies if not defined globally -set firewall bridge forward filter rule 5 action 'accept' -set firewall bridge forward filter rule 5 state 'established' -set firewall bridge forward filter rule 5 state 'related' -set firewall bridge forward filter rule 10 action 'drop' -set firewall bridge forward filter rule 10 state 'invalid' - -# Forward - Catch all traffic for br0 -set firewall bridge forward filter rule 110 description 'br0 traffic' -set firewall bridge forward filter rule 110 action 'jump' -set firewall bridge forward filter rule 110 inbound-interface group 'br0-ifaces' -set firewall bridge forward filter rule 110 jump-target 'br0-fwd' - -# Forward - Catch all traffic for br1 -set firewall bridge forward filter rule 120 description 'br1 traffic' -set firewall bridge forward filter rule 120 action 'jump' -set firewall bridge forward filter rule 120 inbound-interface group 'br1-ifaces' -set firewall bridge forward filter rule 120 jump-target 'br1-fwd' - -# Forward - Catch all traffic for br2 -set firewall bridge forward filter rule 130 description 'br2 traffic' -set firewall bridge forward filter rule 130 action 'jump' -set firewall bridge forward filter rule 130 inbound-interface group 'br2-ifaces' -set firewall bridge forward filter rule 130 jump-target 'br2-fwd' - -# Forward - Default action drop: -set firewall bridge forward filter default-action 'drop' -``` - -And the content of the custom rulesets: - -```none -### br0 - br0-fwd - # Accept everything that wasn't dropped in prerouting -set firewall bridge name br0-fwd default-action 'accept' - -### br1 - br1-fwd - # Requirement: Accept all ARP packets -set firewall bridge name br1-fwd rule 10 description 'Accept ARP' -set firewall bridge name br1-fwd rule 10 action 'accept' -set firewall bridge name br1-fwd rule 10 ethernet-type 'arp' - # Requirement: Accept only new IPv4 connections from host 10.1.1.102 -set firewall bridge name br1-fwd rule 20 description 'Accept ipv4 from host' -set firewall bridge name br1-fwd rule 20 action 'accept' -set firewall bridge name br1-fwd rule 20 source address '10.1.1.102' -set firewall bridge name br1-fwd rule 20 state 'new' - # Drop everythin else within the bridge: -set firewall bridge name br1-fwd default-action 'drop' - -### br2 - br2-fwd - # Requirement: Accept all DHCP discover packets -set firewall bridge name br2-fwd rule 10 description 'Accept DHCP discover' -set firewall bridge name br2-fwd rule 10 action 'accept' -set firewall bridge name br2-fwd rule 10 protocol 'udp' -set firewall bridge name br2-fwd rule 10 source port '68' -set firewall bridge name br2-fwd rule 10 destination port '67' -set firewall bridge name br2-fwd rule 10 destination mac-address 'ff:ff:ff:ff:ff:ff' - # Requirement: Accept only DHCP offers from valid server on port eth6 -set firewall bridge name br2-fwd rule 20 description 'Accept DHCP offers from trusted interface' -set firewall bridge name br2-fwd rule 20 action 'accept' -set firewall bridge name br2-fwd rule 20 protocol 'udp' -set firewall bridge name br2-fwd rule 20 source port '67' -set firewall bridge name br2-fwd rule 20 destination port '68' -set firewall bridge name br2-fwd rule 20 inbound-interface name 'eth6' -set firewall bridge name br2-fwd rule 22 description 'Drop all other DHCP offers' -set firewall bridge name br2-fwd rule 22 action 'drop' -set firewall bridge name br2-fwd rule 22 protocol 'udp' -set firewall bridge name br2-fwd rule 22 source port '67' -set firewall bridge name br2-fwd rule 22 destination port '68' -set firewall bridge name br2-fwd rule 22 log - - # Accept all ARP packets -set firewall bridge name br2-fwd rule 30 description 'Accept ARP' -set firewall bridge name br2-fwd rule 30 action 'accept' -set firewall bridge name br2-fwd rule 30 ethernet-type 'arp' - # Accept all IPv4 connections -set firewall bridge name br2-fwd rule 40 description 'Accept ipv4' -set firewall bridge name br2-fwd rule 40 action 'accept' -set firewall bridge name br2-fwd rule 40 ethernet-type 'ipv4' - # Drop everything else -set firewall bridge name br2-fwd default-action 'drop' -``` - -### IP firewall configuration - -Since some of the requirements listed above exceed the capabilities of the -bridge firewall, we need to use the IP firewall to implement them. -For bridge br1 and br2, we need to control the traffic that is going to the -router itself, to other local networks, and to the Internet. - -As a reminder, here's a link to the {doc}`firewall documentation -</configuration/firewall/index>`, where you can find more information about -the packet flow for traffic that comes from bridge layer and should be analized -by the IP firewall. - -Access to the router itself is controlled by the base chain `input`, and -rules to accomplish all the requirements are: - -```none -# First of all, if not using global state policies, we need to define them: -set firewall ipv4 input filter rule 10 state 'established' -set firewall ipv4 input filter rule 10 state 'related' -set firewall ipv4 input filter rule 10 action 'accept' -set firewall ipv4 input filter rule 20 state 'invalid' -set firewall ipv4 input filter rule 20 action 'drop' - -# Input - br1 - Accept access to router itself -set firewall ipv4 input filter rule 110 description "Accept access from br1" -set firewall ipv4 input filter rule 110 action 'accept' -set firewall ipv4 input filter rule 110 inbound-interface group 'br1-ifaces' - -# Input - br2 - Deny access to the router -set firewall ipv4 input filter rule 120 description "Deny access from br2" -set firewall ipv4 input filter rule 120 action 'drop' -set firewall ipv4 input filter rule 120 inbound-interface group 'br2-ifaces' -``` - -And for traffic that is going to other local networks, and to he Internet, we -need to use the base chain `forward`. As in the bridge firewall, we are -going to use custom rulesets for each bridge, that would be used in the -`forward` chain. Those rulesets are `ip-br1-fwd` and `ip-br2-fwd`: - -```none -# First of all, if not using global state policies, we need to define them: -set firewall ipv4 forward filter rule 5 action 'accept' -set firewall ipv4 forward filter rule 5 state 'established' -set firewall ipv4 forward filter rule 5 state 'related' -set firewall ipv4 forward filter rule 10 action 'drop' -set firewall ipv4 forward filter rule 10 state 'invalid' - -# Forward - Catch all traffic for br1 -set firewall ipv4 forward filter rule 110 description 'br1 traffic' -set firewall ipv4 forward filter rule 110 action 'jump' -set firewall ipv4 forward filter rule 110 inbound-interface group 'br1-ifaces' -set firewall ipv4 forward filter rule 110 jump-target 'ip-br1-fwd' - -# Forward - Catch all traffic for br2 -set firewall ipv4 forward filter rule 120 description 'br2 traffic' -set firewall ipv4 forward filter rule 120 action 'jump' -set firewall ipv4 forward filter rule 120 inbound-interface group 'br2-ifaces' -set firewall ipv4 forward filter rule 120 jump-target 'ip-br2-fwd' - -# Forward - Default action drop: -set firewall ipv4 forward filter default-action 'drop' -``` - -And the content of the custom rulesets: - -```none -### br1 - ip-br1-fwd - # Requirement: Allow connections to internet -set firewall ipv4 name ip-br1-fwd rule 10 description 'br1 - allow internet access' -set firewall ipv4 name ip-br1-fwd rule 10 action 'accept' -set firewall ipv4 name ip-br1-fwd rule 10 outbound-interface name 'eth0' - # Requirement: Drop all other connections -set firewall ipv4 name ip-br1-fwd default-action 'drop' - -### br2 - ip-br2-fwd - # Requirement: Allow connections to internet -set firewall ipv4 name ip-br2-fwd rule 10 description 'br2 - allow internet access' -set firewall ipv4 name ip-br2-fwd rule 10 action 'accept' -set firewall ipv4 name ip-br2-fwd rule 10 outbound-interface name 'eth0' - # Requirement: Allow connections to br1 -set firewall ipv4 name ip-br2-fwd rule 20 description 'br2 - allow access to br1' -set firewall ipv4 name ip-br2-fwd rule 20 action 'accept' -set firewall ipv4 name ip-br2-fwd rule 20 outbound-interface group 'br1-ifaces' - # Requirement: Drop all other connections -set firewall ipv4 name ip-br2-fwd default-action 'drop' -``` - -## Validation - -While testing the configuration, we can check logs in order to ensure that -we are accepting and/or blocking the correct traffic. - -For example, while a host tries to get an IP address from a DHCP server in -br1 all DHCP discover are dropped, and in br2, we can see that DHCP offers from -untrusted servers are dropped: - -```none -vyos@bridge:~$ show log firewall bridge -Sep 17 14:22:35 kernel: [bri-NAM-br2-fwd-22-D]IN=eth7 OUT=eth5 MAC=50:00:00:09:00:00:50:00:00:04:00:00:08:00 SRC=10.2.2.199 DST=10.2.2.92 LEN=322 TOS=0x10 PREC=0x00 TTL=128 ID=0 DF PROTO=UDP SPT=67 DPT=68 LEN=302 -Sep 17 14:28:18 kernel: [bri-NAM-br1-pre-10-D]IN=eth3 OUT= MAC=ff:ff:ff:ff:ff:ff:00:50:79:66:68:0c:08:00 SRC=0.0.0.0 DST=255.255.255.255 LEN=392 TOS=0x10 PREC=0x00 TTL=16 ID=0 PROTO=UDP SPT=68 DPT=67 LEN=372 -Sep 17 14:28:19 kernel: [bri-NAM-br1-pre-10-D]IN=eth3 OUT= MAC=ff:ff:ff:ff:ff:ff:00:50:79:66:68:0c:08:00 SRC=0.0.0.0 DST=255.255.255.255 LEN=392 TOS=0x10 PREC=0x00 TTL=16 ID=0 PROTO=UDP SPT=68 DPT=67 LEN=372 -``` - -And with operational mode commands, we can check rules matchers, actions, and -counters. - -Bridge firewall rulset: - -```none -vyos@bri:~$ show firewall bridge -Rulesets bridge Information - ---------------------------------- -bridge Firewall "forward filter" - -Rule Action Protocol Packets Bytes Conditions -------- -------- ---------- --------- ------- ----------------------------------------- -5 accept all 19 1916 ct state { established, related } accept -10 drop all 0 0 ct state invalid -110 jump all 2 208 iifname @I_br0-ifaces jump NAME_br0-fwd -120 jump all 10 670 iifname @I_br1-ifaces jump NAME_br1-fwd -130 jump all 12 3086 iifname @I_br2-ifaces jump NAME_br2-fwd -default drop all 0 0 - ---------------------------------- -bridge Firewall "name br0-fwd" - -Rule Action Protocol Packets Bytes -------- -------- ---------- --------- ------- -default accept all 2 208 - ---------------------------------- -bridge Firewall "name br0-pre" - -Rule Action Protocol Packets Bytes Conditions -------- -------- ---------- --------- ------- ---------------------- -10 accept all 18 1872 ether type ip6 accept -default drop all 9 1476 - ---------------------------------- -bridge Firewall "name br1-fwd" - -Rule Action Protocol Packets Bytes Conditions -------- -------- ---------- --------- ------- ---------------------------------------- -10 accept all 5 250 ether type arp accept -20 accept all 3 252 ct state new ip saddr 10.1.1.102 accept -default drop all 2 168 - ---------------------------------- -bridge Firewall "name br1-pre" - -Rule Action Protocol Packets Bytes Conditions -------- -------- ---------- --------- ------- ---------------------------------------------------------------------------------------- -10 drop udp 3 1176 ether daddr ff:ff:ff:ff:ff:ff udp sport 68 udp dport 67 prefix "[bri-NAM-br1-pre-10-D]" -20 drop all 0 0 ether type ip6 -default accept all 58 4430 - ---------------------------------- -bridge Firewall "name br2-fwd" - -Rule Action Protocol Packets Bytes Conditions -------- -------- ---------- --------- ------- --------------------------------------------------------------- -10 accept udp 4 1312 ether daddr ff:ff:ff:ff:ff:ff udp sport 68 udp dport 67 accept -20 accept udp 2 656 udp sport 67 udp dport 68 iifname "eth6" accept -22 drop udp 1 322 udp sport 67 udp dport 68 prefix "[bri-NAM-br2-fwd-22-D]" -30 accept all 2 92 ether type arp accept -40 accept all 3 704 ether type ip accept -default drop all 0 0 - ---------------------------------- -bridge Firewall "name br2-pre" - -Rule Action Protocol Packets Bytes Conditions -------- -------- ---------- --------- ------- -------------- -10 drop all 7 728 ether type ip6 -default accept all 77 7548 - ---------------------------------- -bridge Firewall "prerouting filter" - -Rule Action Protocol Packets Bytes Conditions -------- -------- ---------- --------- ------- ---------------------------------------- -10 jump all 27 3348 iifname @I_br0-ifaces jump NAME_br0-pre -20 jump all 61 5606 iifname @I_br1-ifaces jump NAME_br1-pre -30 jump all 84 8276 iifname @I_br2-ifaces jump NAME_br2-pre -default drop all 0 0 - -vyos@bridge:~$ -``` - -IPv4 firewall rulset: - -```none -vyos@bridge:~$ show firewall ipv4 -Rulesets ipv4 Information - ---------------------------------- -ipv4 Firewall "forward filter" - -Rule Action Protocol Packets Bytes Conditions -------- -------- ---------- --------- ------- ------------------------------------------- -5 accept all 76 6384 ct state { established, related } accept -10 drop all 0 0 ct state invalid -110 jump all 13 1092 iifname @I_br1-ifaces jump NAME_ip-br1-fwd -120 jump all 3 252 iifname @I_br2-ifaces jump NAME_ip-br2-fwd -default drop all 0 0 - ---------------------------------- -ipv4 Firewall "input filter" - -Rule Action Protocol Packets Bytes Conditions -------- -------- ---------- --------- ------- ----------------------------------------- -10 accept all 0 0 ct state { established, related } accept -20 drop all 0 0 ct state invalid -110 accept all 10 720 iifname @I_br1-ifaces accept -120 drop all 26 2672 iifname @I_br2-ifaces -default accept all 3037 991621 - ---------------------------------- -ipv4 Firewall "name ip-br1-fwd" - -Rule Action Protocol Packets Bytes Conditions -------- -------- ---------- --------- ------- ---------------------- -10 accept all 5 420 oifname "eth0" accept -default drop all 8 672 - ---------------------------------- -ipv4 Firewall "name ip-br2-fwd" - -Rule Action Protocol Packets Bytes Conditions -------- -------- ---------- --------- ------- ----------------------------- -10 accept all 1 84 oifname "eth0" accept -20 accept all 2 168 oifname @I_br1-ifaces accept -default drop all 0 0 - -vyos@bridge:~$ -``` diff --git a/docs/configexamples/md-index.md b/docs/configexamples/md-index.md deleted file mode 100644 index 66b3359e..00000000 --- a/docs/configexamples/md-index.md +++ /dev/null @@ -1,59 +0,0 @@ -(examples)= - -# Configuration Blueprints - -This chapter contains various configuration examples: - -```{toctree} -:maxdepth: 2 - -firewall -bgp-ipv6-unnumbered -ospf-unnumbered -azure-vpn-bgp -azure-vpn-dual-bgp -ha -wan-load-balancing -pppoe-ipv6-basic -l3vpn-hub-and-spoke -lac-lns -inter-vrf-routing-vrf-lite -dmvpn-dualhub-dualcloud -qos -segment-routing-isis -nmp -ansible -ipsec-cisco-policy-based -ipsec-cisco-route-based -ipsec-pa-route-based -policy-based-ipsec-and-firewall -site-2-site-cisco -``` - -## Configuration Blueprints (autotest) - -The next pages contain fully automated configuration examples. - -Each lab will build and test from an external script. -The page content is generated, so changes will not take effect. - -A host `vyos-oobm` will be used as an SSH proxy. This host is just -necessary for the lab tests. - -The process will do the following steps: -1. create the lab on a eve-ng server -2. configure each host in the lab -3. do some defined tests -4. optional do an upgrade to a higher version and do step 3 again. -5. generate the documentation and include files -6. shutdown and destroy the lab, if there is no error - -```{toctree} -:maxdepth: 1 - -autotest/DHCPRelay_through_GRE/DHCPRelay_through_GRE -autotest/tunnelbroker/tunnelbroker -autotest/L3VPN_EVPN/L3VPN_EVPN -autotest/Wireguard/Wireguard -autotest/OpenVPN_with_LDAP/OpenVPN_with_LDAP -``` diff --git a/docs/configexamples/md-lac-lns.md b/docs/configexamples/md-lac-lns.md deleted file mode 100644 index 1b020924..00000000 --- a/docs/configexamples/md-lac-lns.md +++ /dev/null @@ -1,172 +0,0 @@ ---- -lastproofread: '2024-02-21' ---- - -(examples-lac-lns)= - -# PPPoE over L2TP - -This document is to describe a basic setup using PPPoE over L2TP. -LAC and LNS are components of the broadband topology. -LAC - L2TP access concentrator -LNS - L2TP Network Server -LAC and LNS forms L2TP tunnel. LAC receives packets from PPPoE clients and -forward them to LNS. LNS is the termination point that comes from PPP packets -from the remote client. - -In this example we use VyOS 1.5 as LNS and Cisco IOS as LAC. -All users with domain **vyos.io** will be tunneled to LNS via L2TP. - -## Network Topology - -```{image} /_static/images/lac-lns-diagram.jpg -:align: center -:alt: Network Topology Diagram -:width: 60% -``` - -## Configurations - -### LAC - -```none -aaa new-model -! -aaa authentication ppp default local -! -vpdn enable -vpdn aaa attribute nas-ip-address vpdn-nas -! -vpdn-group LAC - request-dialin - protocol l2tp - domain vyos.io - initiate-to ip 192.168.139.100 - source-ip 192.168.139.101 - local name LAC - l2tp tunnel password 0 test123 -! -bba-group pppoe MAIN-BBA - virtual-template 1 -! -interface GigabitEthernet0/0 - description To LNS - ip address 192.168.139.101 255.255.255.0 - duplex auto - speed auto - media-type rj45 -! -interface GigabitEthernet0/1 - description To PPPoE clients - no ip address - duplex auto - speed auto - media-type rj45 - pppoe enable group MAIN-BBA -! -interface Virtual-Template1 - description pppoe MAIN-BBA - no ip address - no peer default ip address - ppp mtu adaptive - ppp authentication chap -! -``` - -### LNS - -```none -set interfaces ethernet eth0 address '192.168.139.100/24' -set nat source rule 100 outbound-interface name 'eth0' -set nat source rule 100 source address '10.0.0.0/24' -set nat source rule 100 translation address 'masquerade' -set protocols static route 0.0.0.0/0 next-hop 192.168.139.2 -set vpn l2tp remote-access authentication mode 'radius' -set vpn l2tp remote-access authentication radius server 192.168.139.110 key 'radiustest' -set vpn l2tp remote-access client-ip-pool TEST-POOL range '10.0.0.2-10.0.0.100' -set vpn l2tp remote-access default-pool 'TEST-POOL' -set vpn l2tp remote-access gateway-address '10.0.0.1' -set vpn l2tp remote-access lns host-name 'LAC' -set vpn l2tp remote-access lns shared-secret 'test123' -set vpn l2tp remote-access name-server '8.8.8.8' -set vpn l2tp remote-access ppp-options disable-ccp -``` - -:::{note} -This setup requires the Compression Control Protocol (CCP) -being disabled, the command `set vpn l2tp remote-access ppp-options disable-ccp` -accomplishes that. -::: - -### Client -In this lab we use Windows PPPoE client. - -```{image} /_static/images/lac-lns-winclient.jpg -:align: center -:alt: Window PPPoE Client Configuration -:width: 100% -``` - -### Monitoring -Monitoring on LNS side - -```none -vyos@vyos:~$ show l2tp-server sessions - ifname | username | ip | ip6 | ip6-dp | calling-sid | rate-limit | state | uptime | rx-bytes | tx-bytes ---------+--------------+----------+-----+--------+-----------------+------------+--------+----------+-----------+---------- - l2tp0 | test@vyos.io | 10.0.0.2 | | | 192.168.139.101 | | active | 00:00:35 | 188.4 KiB | 9.3 MiB -``` - -Monitoring on LAC side - -```none -Router#show pppoe session - 1 session in FORWARDED (FWDED) State - 1 session total -Uniq ID PPPoE RemMAC Port VT VA State - SID LocMAC VA-st Type - 1 1 000c.290b.20a6 Gi0/1 1 N/A FWDED - 0c58.88ac.0001 - -Router#show l2tp -L2TP Tunnel and Session Information Total tunnels 1 sessions 1 - -LocTunID RemTunID Remote Name State Remote Address Sessn L2TP Class/ - Count VPDN Group -23238 2640 LAC est 192.168.139.100 1 LAC - -LocID RemID TunID Username, Intf/ State Last Chg Uniq ID - Vcid, Circuit -25641 25822 23238 test@vyos.io, Gi0/1 est 00:05:36 1 -``` - -Monitoring on RADIUS Server side - -```none -root@Radius:~# cat /var/log/freeradius/radacct/192.168.139.100/detail-20240221 -Wed Feb 21 13:37:17 2024 - User-Name = "test@vyos.io" - NAS-Port = 0 - NAS-Port-Id = "l2tp0" - NAS-Port-Type = Virtual - Service-Type = Framed-User - Framed-Protocol = PPP - Calling-Station-Id = "192.168.139.101" - Called-Station-Id = "192.168.139.100" - Acct-Status-Type = Start - Acct-Authentic = RADIUS - Acct-Session-Id = "45c731e169d9a4f1" - Acct-Session-Time = 0 - Acct-Input-Octets = 0 - Acct-Output-Octets = 0 - Acct-Input-Packets = 0 - Acct-Output-Packets = 0 - Acct-Input-Gigawords = 0 - Acct-Output-Gigawords = 0 - Framed-IP-Address = 10.0.0.2 - NAS-IP-Address = 192.168.139.100 - Event-Timestamp = "Feb 21 2024 13:37:17 UTC" - Tmp-String-9 = "ai:" - Acct-Unique-Session-Id = "ea6a1089816f19c0d0f1819bc61c3318" - Timestamp = 1708522637 -``` diff --git a/docs/configexamples/md-nmp.md b/docs/configexamples/md-nmp.md deleted file mode 100644 index 9c422172..00000000 --- a/docs/configexamples/md-nmp.md +++ /dev/null @@ -1,71 +0,0 @@ ---- -lastproofread: '2023-03-26' ---- - -(examples-nmp)= - -# NMP example - -Consider how to quickly set up NMP and VyOS for monitoring. -NMP is multi-vendor network monitoring from 'SolarWinds' built to -scale and expand with the needs of your network. - -## Configuration 'VyOS' - -First prepare our VyOS router for connection to NMP. We have to set -up the SNMP protocol and connectivity between the router and NMP. - -```none -set interfaces ethernet eth0 address 'dhcp' -set system name-server '8.8.8.8' -set service snmp community router authorization 'test' -set service snmp community router network '0.0.0.0/0' -``` - -## Configuration 'NMP' - -Next, you just should follow the pictures: - -```{image} /_static/images/nmp1.png -:align: center -:alt: Network Topology Diagram -:width: 80% -``` - -```{image} /_static/images/nmp2.png -:align: center -:alt: Network Topology Diagram -:width: 80% -``` - -```{image} /_static/images/nmp3.png -:align: center -:alt: Network Topology Diagram -:width: 80% -``` - -```{image} /_static/images/nmp4.png -:align: center -:alt: Network Topology Diagram -:width: 80% -``` - -```{image} /_static/images/nmp5.png -:align: center -:alt: Network Topology Diagram -:width: 80% -``` - -```{image} /_static/images/nmp6.png -:align: center -:alt: Network Topology Diagram -:width: 80% -``` - -```{image} /_static/images/nmp7.png -:align: center -:alt: Network Topology Diagram -:width: 80% -``` - -In the end, you'll get a powerful instrument for monitoring the VyOS systems. diff --git a/docs/configexamples/md-ospf-unnumbered.md b/docs/configexamples/md-ospf-unnumbered.md deleted file mode 100644 index 9c4d5399..00000000 --- a/docs/configexamples/md-ospf-unnumbered.md +++ /dev/null @@ -1,117 +0,0 @@ ---- -lastproofread: '2021-06-29' ---- - -(examples-ospf-unnumbered)= - -# OSPF unnumbered with ECMP - -General information can be found in the {ref}`routing-ospf` chapter. - -## Configuration - -- Router A: - -```none -set interfaces ethernet eth0 address '10.0.0.1/24' -set interfaces ethernet eth1 address '192.168.0.1/32' -set interfaces ethernet eth1 ip ospf authentication md5 key-id 1 md5-key 'yourpassword' -set interfaces ethernet eth1 ip ospf network 'point-to-point' -set interfaces ethernet eth2 address '192.168.0.1/32' -set interfaces ethernet eth2 ip ospf authentication md5 key-id 1 md5-key 'yourpassword' -set interfaces ethernet eth2 ip ospf network 'point-to-point' -set interfaces loopback lo address '192.168.0.1/32' -set protocols ospf area 0.0.0.0 authentication 'md5' -set protocols ospf area 0.0.0.0 network '192.168.0.1/32' -set protocols ospf parameters router-id '192.168.0.1' -set protocols ospf redistribute connected -``` - -- Router B: - -```none -set interfaces ethernet eth0 address '10.0.0.2/24' -set interfaces ethernet eth1 address '192.168.0.2/32' -set interfaces ethernet eth1 ip ospf authentication md5 key-id 1 md5-key 'yourpassword' -set interfaces ethernet eth1 ip ospf network 'point-to-point' -set interfaces ethernet eth2 address '192.168.0.2/32' -set interfaces ethernet eth2 ip ospf authentication md5 key-id 1 md5-key 'yourpassword' -set interfaces ethernet eth2 ip ospf network 'point-to-point' -set interfaces loopback lo address '192.168.0.2/32' -set protocols ospf area 0.0.0.0 authentication 'md5' -set protocols ospf area 0.0.0.0 network '192.168.0.2/32' -set protocols ospf parameters router-id '192.168.0.2' -set protocols ospf redistribute connected -``` - -## Results - -- Router A: - -```none -vyos@vyos:~$ show interfaces -Codes: S - State, L - Link, u - Up, D - Down, A - Admin Down -Interface IP Address S/L Description ---------- ---------- --- ----------- -eth0 10.0.0.1/24 u/u -eth1 192.168.0.1/32 u/u -eth2 192.168.0.1/32 u/u -lo 127.0.0.1/8 u/u - 192.168.0.1/32 - ::1/128 -``` - -```none -vyos@vyos:~$ show ip route -Codes: K - kernel route, C - connected, S - static, R - RIP, - O - OSPF, I - IS-IS, B - BGP, E - EIGRP, N - NHRP, - T - Table, v - VNC, V - VNC-Direct, A - Babel, D - SHARP, - F - PBR, f - OpenFabric, - > - selected route, * - FIB route, q - queued route, r - rejected route - -S>* 0.0.0.0/0 [210/0] via 10.0.0.254, eth0, 00:57:34 -O 10.0.0.0/24 [110/20] via 192.168.0.2, eth1 onlink, 00:13:21 - via 192.168.0.2, eth2 onlink, 00:13:21 -C>* 10.0.0.0/24 is directly connected, eth0, 00:57:35 -O 192.168.0.1/32 [110/0] is directly connected, lo, 00:48:53 -C * 192.168.0.1/32 is directly connected, eth2, 00:56:31 -C * 192.168.0.1/32 is directly connected, eth1, 00:56:31 -C>* 192.168.0.1/32 is directly connected, lo, 00:57:36 -O>* 192.168.0.2/32 [110/1] via 192.168.0.2, eth1 onlink, 00:29:03 - * via 192.168.0.2, eth2 onlink, 00:29:03 -``` - -- Router B: - -```none -vyos@vyos:~$ show interfaces -Codes: S - State, L - Link, u - Up, D - Down, A - Admin Down -Interface IP Address S/L Description ---------- ---------- --- ----------- -eth0 10.0.0.2/24 u/u -eth1 192.168.0.2/32 u/u -eth2 192.168.0.2/32 u/u -lo 127.0.0.1/8 u/u - 192.168.0.2/32 - ::1/128 -``` - -```none -vyos@vyos:~$ show ip route -Codes: K - kernel route, C - connected, S - static, R - RIP, - O - OSPF, I - IS-IS, B - BGP, E - EIGRP, N - NHRP, - T - Table, v - VNC, V - VNC-Direct, A - Babel, D - SHARP, - F - PBR, f - OpenFabric, - > - selected route, * - FIB route, q - queued route, r - rejected route - -S>* 0.0.0.0/0 [210/0] via 10.0.0.254, eth0, 00:57:34 -O 10.0.0.0/24 [110/20] via 192.168.0.1, eth1 onlink, 00:13:21 - via 192.168.0.1, eth2 onlink, 00:13:21 -C>* 10.0.0.0/24 is directly connected, eth0, 00:57:35 -O 192.168.0.2/32 [110/0] is directly connected, lo, 00:48:53 -C * 192.168.0.2/32 is directly connected, eth2, 00:56:31 -C * 192.168.0.2/32 is directly connected, eth1, 00:56:31 -C>* 192.168.0.2/32 is directly connected, lo, 00:57:36 -O>* 192.168.0.1/32 [110/1] via 192.168.0.1, eth1 onlink, 00:29:03 - * via 192.168.0.1, eth2 onlink, 00:29:03 -``` diff --git a/docs/configexamples/md-policy-based-ipsec-and-firewall.md b/docs/configexamples/md-policy-based-ipsec-and-firewall.md deleted file mode 100644 index 00110117..00000000 --- a/docs/configexamples/md-policy-based-ipsec-and-firewall.md +++ /dev/null @@ -1,255 +0,0 @@ -(examples-policy-based-ipsec-and-firewall)= - -# Policy-Based Site-to-Site VPN and Firewall Configuration - -This guide shows an example policy-based IKEv2 site-to-site VPN between two -VyOS routers, and firewall configuration. - -For simplicity, configuration and tests are done only using IPv4, and firewall -configuration is done only on one router. - -## Network Topology and requirements - -This configuration example and the requirements consists of: - -- Two VyOS routers with public IP address. - -- 2 private subnets on each site. - -- Local subnets should be able to reach internet using source NAT. - -- Communication between private subnets should be done through IPSec tunnel - without NAT. - -- Configuration of basic firewall in one site, in order to: - - > - Protect the router on 'WAN' interface, allowing only IPSec connections - > and SSH access from trusted IPs. - > - Allow access to the router only from trusted networks. - > - Allow DNS requests only only for local networks. - > - Allow ICMP on all interfaces. - > - Allow all new connections from local subnets. - > - Allow connections from LANs to LANs through the tunnel. - -```{image} /_static/images/policy-based-ipsec-and-firewall.png -``` - -## Configuration -Interface and routing configuration: -```none -# LEFT router: -set interfaces ethernet eth0 address '198.51.100.14/30' -set interfaces ethernet eth1 vif 111 address '10.1.11.1/24' -set interfaces ethernet eth2 vif 112 address '10.1.12.1/24' -set protocols static route 0.0.0.0/0 next-hop 198.51.100.13 - -# RIGHT router: -set interfaces ethernet eth0 address '192.0.2.130/30' -set interfaces ethernet eth1 vif 221 address '10.2.21.1/24' -set interfaces ethernet eth2 vif 222 address '10.2.22.1/24' -``` -IPSec configuration: -```none -# LEFT router: -set vpn ipsec authentication psk RIGHT id '198.51.100.14' -set vpn ipsec authentication psk RIGHT id '192.0.2.130' -set vpn ipsec authentication psk RIGHT secret 'p4ssw0rd' -set vpn ipsec esp-group ESP-GROUP mode 'tunnel' -set vpn ipsec esp-group ESP-GROUP proposal 1 encryption 'aes256' -set vpn ipsec esp-group ESP-GROUP proposal 1 hash 'sha256' -set vpn ipsec ike-group IKE-GROUP key-exchange 'ikev2' -set vpn ipsec ike-group IKE-GROUP proposal 1 dh-group '14' -set vpn ipsec ike-group IKE-GROUP proposal 1 encryption 'aes256' -set vpn ipsec ike-group IKE-GROUP proposal 1 hash 'sha256' -set vpn ipsec interface 'eth0' -set vpn ipsec site-to-site peer RIGHT authentication mode 'pre-shared-secret' -set vpn ipsec site-to-site peer RIGHT connection-type 'initiate' -set vpn ipsec site-to-site peer RIGHT default-esp-group 'ESP-GROUP' -set vpn ipsec site-to-site peer RIGHT ike-group 'IKE-GROUP' -set vpn ipsec site-to-site peer RIGHT local-address '198.51.100.14' -set vpn ipsec site-to-site peer RIGHT remote-address '192.0.2.130' -set vpn ipsec site-to-site peer RIGHT tunnel 0 local prefix '10.1.11.0/24' -set vpn ipsec site-to-site peer RIGHT tunnel 0 remote prefix '10.2.21.0/24' -set vpn ipsec site-to-site peer RIGHT tunnel 1 local prefix '10.1.11.0/24' -set vpn ipsec site-to-site peer RIGHT tunnel 1 remote prefix '10.2.22.0/24' -set vpn ipsec site-to-site peer RIGHT tunnel 2 local prefix '10.1.12.0/24' -set vpn ipsec site-to-site peer RIGHT tunnel 2 remote prefix '10.2.21.0/24' -set vpn ipsec site-to-site peer RIGHT tunnel 3 local prefix '10.1.12.0/24' -set vpn ipsec site-to-site peer RIGHT tunnel 3 remote prefix '10.2.22.0/24' - -# RIGHT router: -set vpn ipsec authentication psk LEFT id '192.0.2.130' -set vpn ipsec authentication psk LEFT id '198.51.100.14' -set vpn ipsec authentication psk LEFT secret 'p4ssw0rd' -set vpn ipsec esp-group ESP-GROUP mode 'tunnel' -set vpn ipsec esp-group ESP-GROUP proposal 1 encryption 'aes256' -set vpn ipsec esp-group ESP-GROUP proposal 1 hash 'sha256' -set vpn ipsec ike-group IKE-GROUP key-exchange 'ikev2' -set vpn ipsec ike-group IKE-GROUP proposal 1 dh-group '14' -set vpn ipsec ike-group IKE-GROUP proposal 1 encryption 'aes256' -set vpn ipsec ike-group IKE-GROUP proposal 1 hash 'sha256' -set vpn ipsec interface 'eth0' -set vpn ipsec site-to-site peer LEFT authentication mode 'pre-shared-secret' -set vpn ipsec site-to-site peer LEFT connection-type 'none' -set vpn ipsec site-to-site peer LEFT default-esp-group 'ESP-GROUP' -set vpn ipsec site-to-site peer LEFT ike-group 'IKE-GROUP' -set vpn ipsec site-to-site peer LEFT local-address '192.0.2.130' -set vpn ipsec site-to-site peer LEFT remote-address '198.51.100.14' -set vpn ipsec site-to-site peer LEFT tunnel 0 local prefix '10.2.21.0/24' -set vpn ipsec site-to-site peer LEFT tunnel 0 remote prefix '10.1.11.0/24' -set vpn ipsec site-to-site peer LEFT tunnel 1 local prefix '10.2.22.0/24' -set vpn ipsec site-to-site peer LEFT tunnel 1 remote prefix '10.1.11.0/24' -set vpn ipsec site-to-site peer LEFT tunnel 2 local prefix '10.2.21.0/24' -set vpn ipsec site-to-site peer LEFT tunnel 2 remote prefix '10.1.12.0/24' -set vpn ipsec site-to-site peer LEFT tunnel 3 local prefix '10.2.22.0/24' -set vpn ipsec site-to-site peer LEFT tunnel 3 remote prefix '10.1.12.0/24' -``` -Firewall Configuration: -```none -# Firewall Groups: -set firewall group network-group LOCAL-NETS network '10.1.11.0/24' -set firewall group network-group LOCAL-NETS network '10.1.12.0/24' -set firewall group network-group REMOTE-NETS network '10.2.21.0/24' -set firewall group network-group REMOTE-NETS network '10.2.22.0/24' -set firewall group network-group TRUSTED network '198.51.100.125/32' -set firewall group network-group TRUSTED network '203.0.113.0/24' -set firewall group network-group TRUSTED network '10.1.11.0/24' -set firewall group network-group TRUSTED network '192.168.70.0/24' - -# Forward traffic: default drop and only allow what is needed -set firewall ipv4 forward filter default-action 'drop' - -# Forward traffic: global state policies -set firewall ipv4 forward filter rule 1 action 'accept' -set firewall ipv4 forward filter rule 1 state established 'enable' -set firewall ipv4 forward filter rule 1 state related 'enable' -set firewall ipv4 forward filter rule 2 action 'drop' -set firewall ipv4 forward filter rule 2 state invalid 'enable' - -# Forward traffic: Accept all connections from local networks -set firewall ipv4 forward filter rule 10 action 'accept' -set firewall ipv4 forward filter rule 10 source group network-group 'LOCAL-NETS' - -# Forward traffic: accept connections from remote LANs to local LANs -set firewall ipv4 forward filter rule 20 action 'accept' -set firewall ipv4 forward filter rule 20 destination group network-group 'LOCAL-NETS' -set firewall ipv4 forward filter rule 20 source group network-group 'REMOTE-NETS' - -# Input traffic: default drop and only allow what is needed -set firewall ipv4 input filter default-action 'drop' - -# Input traffic: global state policies -set firewall ipv4 input filter rule 1 action 'accept' -set firewall ipv4 input filter rule 1 state established 'enable' -set firewall ipv4 input filter rule 1 state related 'enable' -set firewall ipv4 input filter rule 2 action 'drop' -set firewall ipv4 input filter rule 2 state invalid 'enable' - -# Input traffic: add rules needed for ipsec connection -set firewall ipv4 input filter rule 10 action 'accept' -set firewall ipv4 input filter rule 10 destination port '500,4500' -set firewall ipv4 input filter rule 10 inbound-interface name 'eth0' -set firewall ipv4 input filter rule 10 protocol 'udp' -set firewall ipv4 input filter rule 15 action 'accept' -set firewall ipv4 input filter rule 15 inbound-interface name 'eth0' -set firewall ipv4 input filter rule 15 protocol 'esp' - -# Input traffic: accept ssh connection from trusted ips -set firewall ipv4 input filter rule 20 action 'accept' -set firewall ipv4 input filter rule 20 destination port '22' -set firewall ipv4 input filter rule 20 protocol 'tcp' -set firewall ipv4 input filter rule 20 source group network-group 'TRUSTED' - -# Input traffic: accepd dns requests only from local networks. -set firewall ipv4 input filter rule 25 action 'accept' -set firewall ipv4 input filter rule 25 destination port '53' -set firewall ipv4 input filter rule 25 protocol 'udp' -set firewall ipv4 input filter rule 25 source group network-group 'LOCAL-NETS' - -# Input traffic: allow icmp -set firewall ipv4 input filter rule 30 action 'accept' -set firewall ipv4 input filter rule 30 protocol 'icmp' -``` -And NAT Configuration: -```none -set nat source rule 10 destination group network-group 'REMOTE-NETS' -set nat source rule 10 exclude -set nat source rule 10 outbound-interface name 'eth0' -set nat source rule 10 source group network-group 'LOCAL-NETS' -set nat source rule 20 outbound-interface name 'eth0' -set nat source rule 20 source group network-group 'LOCAL-NETS' -set nat source rule 20 translation address 'masquerade' -``` -## Checking through op-mode commands -After some testing, we can check IPSec status, and counter on every tunnel: -```none -vyos@LEFT:~$ show vpn ipsec sa -Connection State Uptime Bytes In/Out Packets In/Out Remote address Remote ID Proposal --------------- ------- -------- -------------- ---------------- ---------------- ----------- --------------------------------------- -RIGHT-tunnel-0 up 36m24s 840B/840B 10/10 192.0.2.130 192.0.2.130 AES_CBC_256/HMAC_SHA2_256_128/MODP_2048 -RIGHT-tunnel-1 up 36m33s 588B/588B 7/7 192.0.2.130 192.0.2.130 AES_CBC_256/HMAC_SHA2_256_128/MODP_2048 -RIGHT-tunnel-2 up 35m50s 1K/1K 15/15 192.0.2.130 192.0.2.130 AES_CBC_256/HMAC_SHA2_256_128/MODP_2048 -RIGHT-tunnel-3 up 36m54s 2K/2K 32/32 192.0.2.130 192.0.2.130 AES_CBC_256/HMAC_SHA2_256_128/MODP_2048 -vyos@LEFT:~$ -``` -Also, we can check firewall counters: -```none -vyos@LEFT:~$ show firewall -Rulesets Information - ---------------------------------- -IPv4 Firewall "forward filter" - -Rule Action Protocol Packets Bytes Conditions -------- -------- ---------- --------- ------- ------------------------------------------------------ -1 accept all 681 96545 ct state { established, related } accept -2 drop all 0 0 ct state invalid -10 accept all 360 27205 ip saddr @N_LOCAL-NETS accept -20 accept all 8 648 ip daddr @N_LOCAL-NETS ip saddr @N_REMOTE-NETS accept -default drop all - ---------------------------------- -IPv4 Firewall "input filter" - -Rule Action Protocol Packets Bytes Conditions -------- -------- ---------- --------- ------- ---------------------------------------------- -1 accept all 901 123709 ct state { established, related } accept -2 drop all 0 0 ct state invalid -10 accept udp 0 0 udp dport { 500, 4500 } iifname "eth0" accept -15 accept esp 0 0 meta l4proto esp iifname "eth0" accept -20 accept tcp 1 60 tcp dport 22 ip saddr @N_TRUSTED accept -25 accept udp 0 0 udp dport 53 ip saddr @N_LOCAL-NETS accept -30 accept icmp 0 0 meta l4proto icmp accept -default drop all - -vyos@LEFT:~$ -vyos@LEFT:~$ show firewall statistics -Rulesets Statistics - ---------------------------------- -IPv4 Firewall "forward filter" - -Rule Packets Bytes Action Source Destination Inbound-Interface Outbound-interface -------- --------- ------- -------- ----------- ------------- ------------------- -------------------- -1 681 96545 accept any any any any -2 0 0 drop any any any any -10 360 27205 accept LOCAL-NETS any any any -20 8 648 accept REMOTE-NETS LOCAL-NETS any any -default N/A N/A drop any any any any - ---------------------------------- -IPv4 Firewall "input filter" - -Rule Packets Bytes Action Source Destination Inbound-Interface Outbound-interface -------- --------- ------- -------- ---------- ------------- ------------------- -------------------- -1 905 124213 accept any any any any -2 0 0 drop any any any any -10 0 0 accept any any eth0 any -15 0 0 accept any any eth0 any -20 1 60 accept TRUSTED any any any -25 0 0 accept LOCAL-NETS any any any -30 0 0 accept any any any any -default N/A N/A drop any any any any - -vyos@LEFT:~$ -``` diff --git a/docs/configexamples/md-segment-routing-isis.md b/docs/configexamples/md-segment-routing-isis.md deleted file mode 100644 index 76cb726c..00000000 --- a/docs/configexamples/md-segment-routing-isis.md +++ /dev/null @@ -1,277 +0,0 @@ ---- -lastproofread: '2023-04-10' ---- - -(examples-segment-routing-isis)= - -# Segment-routing IS-IS example - -When utilizing VyOS in an environment with Cisco IOS-XR gear you can use this -blue print as an initial setup to get MPLS ISIS-SR working between those two -devices.The lab was build using {abbr}`EVE-NG (Emulated Virtual -Environment NG)`. - -:::{figure} /_static/images/vyos-sr-isis.png -:alt: ISIS-SR network - -ISIS-SR example network -::: - -The below configuration is used as example where we keep focus on -VyOS-P1/VyOS-P2/XRv-P3 which we share the settings. - -## Configuration - -- VyOS-P1: - -```none -set interfaces dummy dum0 address '192.0.2.1/32' -set interfaces ethernet eth1 address '192.0.2.5/30' -set interfaces ethernet eth1 mtu '8000' -set interfaces ethernet eth3 address '192.0.2.21/30' -set interfaces ethernet eth3 mtu '8000' -set protocols isis interface dum0 passive -set protocols isis interface eth1 network point-to-point -set protocols isis interface eth3 network point-to-point -set protocols isis level 'level-2' -set protocols isis log-adjacency-changes -set protocols isis metric-style 'wide' -set protocols isis net '49.0000.0000.0000.0001.00' -set protocols isis segment-routing maximum-label-depth '8' -set protocols isis segment-routing prefix 192.0.2.1/32 index value '1' -set protocols mpls interface 'eth1' -set protocols mpls interface 'eth3' -set system host-name 'P1-VyOS' -``` - -- XRv-P3: - -```none -hostname P3-VyOS -interface Loopback0 - ipv4 address 192.0.2.3 255.255.255.255 -! -interface GigabitEthernet0/0/0/1 - mtu 8014 - ipv4 address 192.0.2.6 255.255.255.252 -! -interface GigabitEthernet0/0/0/2 - mtu 8014 - ipv4 address 192.0.2.18 255.255.255.252 -! -router isis VyOS - is-type level-2-only - net 49.0000.0000.0000.0003.00 - log adjacency changes - address-family ipv4 unicast - metric-style wide - segment-routing mpls - ! - interface Loopback0 - passive - address-family ipv4 unicast - prefix-sid index 3 - ! - ! - interface GigabitEthernet0/0/0/1 - point-to-point - address-family ipv4 unicast - ! - ! - interface GigabitEthernet0/0/0/2 - point-to-point - address-family ipv4 unicast - ! - ! -! -``` - -- VyOS-P2: - -```none -set interfaces dummy dum0 address '192.0.2.2/32' -set interfaces ethernet eth2 address '192.0.2.17/30' -set interfaces ethernet eth2 mtu '8000' -set interfaces ethernet eth3 address '192.0.2.26/30' -set interfaces ethernet eth3 mtu '8000' -set protocols isis interface dum0 passive -set protocols isis interface eth2 network point-to-point -set protocols isis interface eth3 network point-to-point -set protocols isis level 'level-2' -set protocols isis log-adjacency-changes -set protocols isis metric-style 'wide' -set protocols isis net '49.0000.0000.0000.0002.00' -set protocols isis segment-routing maximum-label-depth '8' -set protocols isis segment-routing prefix 192.0.2.2/32 index value '2' -set protocols mpls interface 'eth2' -set protocols mpls interface 'eth3' -set system host-name 'P2-VyOS' -``` - -This gives us MPLS segment routing enabled and labels forwarding : - -```none -vyos@P1-VyOS:~$ show mpls table -Inbound Label Type Nexthop Outbound Label ------------------------------------------------------------------ -15000 SR (IS-IS) 192.0.2.6 implicit-null -15001 SR (IS-IS) 192.0.2.22 implicit-null -15002 SR (IS-IS) fe80::5200:ff:fe04:3 implicit-null -16002 SR (IS-IS) 192.0.2.6 16002 -16003 SR (IS-IS) 192.0.2.6 implicit-null -16011 SR (IS-IS) 192.0.2.22 implicit-null - -vyos@P2-VyOS:~$ show mpls table -Inbound Label Type Nexthop Outbound Label -------------------------------------------------------- -15000 SR (IS-IS) 192.0.2.18 implicit-null -16001 SR (IS-IS) 192.0.2.18 16001 -16003 SR (IS-IS) 192.0.2.18 implicit-null -16011 SR (IS-IS) 192.0.2.18 16011 - -RP/0/0/CPU0:P3-VyOS#show mpls forwarding -Tue Mar 28 17:47:18.928 UTC -Local Outgoing Prefix Outgoing Next Hop Bytes -Label Label or ID Interface Switched ------- ----------- ------------------ ------------ --------------- ------------ -16001 Pop SR Pfx (idx 1) Gi0/0/0/1 192.0.2.5 0 -16002 Pop SR Pfx (idx 2) Gi0/0/0/2 192.0.2.17 0 -16011 16011 SR Pfx (idx 11) Gi0/0/0/1 192.0.2.5 0 -24000 Pop SR Adj (idx 1) Gi0/0/0/1 192.0.2.5 0 -24001 Pop SR Adj (idx 3) Gi0/0/0/1 192.0.2.5 0 -24002 Pop SR Adj (idx 1) Gi0/0/0/2 192.0.2.17 0 -24003 Pop SR Adj (idx 3) Gi0/0/0/2 192.0.2.17 0 -``` - -VyOS is able to check MSD per devices: - -```none -vyos@P1-VyOS:~$ show isis segment-routing node -Area VyOS: -IS-IS L1 SR-Nodes: - -IS-IS L2 SR-Nodes: - -System ID SRGB SRLB Algorithm MSD ---------------------------------------------------------------- -0000.0000.0001 16000 - 23999 15000 - 15999 SPF 8 -0000.0000.0002 16000 - 23999 15000 - 15999 SPF 8 -0000.0000.0003 16000 - 23999 0 - 4294967295 SPF 10 -0000.0000.0011 16000 - 23999 15000 - 15999 SPF 8 - -vyos@P2-VyOS:~$ show isis segment-routing node -Area VyOS: - IS-IS L1 SR-Nodes: - - IS-IS L2 SR-Nodes: - - System ID SRGB SRLB Algorithm MSD - --------------------------------------------------------------- - 0000.0000.0001 16000 - 23999 15000 - 15999 SPF 8 - 0000.0000.0002 16000 - 23999 15000 - 15999 SPF 8 - 0000.0000.0003 16000 - 23999 0 - 4294967295 SPF 10 - 0000.0000.0011 16000 - 23999 15000 - 15999 SPF 8 -``` - -Here is the routing tables showing the MPLS segment routing label operations: - -```none -vyos@P1-VyOS:~$ show ip route isis -Codes: K - kernel route, C - connected, S - static, R - RIP, - O - OSPF, I - IS-IS, B - BGP, E - EIGRP, N - NHRP, - T - Table, v - VNC, V - VNC-Direct, A - Babel, F - PBR, - f - OpenFabric, - > - selected route, * - FIB route, q - queued, r - rejected, b - backup - t - trapped, o - offload failure - -I>* 192.0.2.2/32 [115/30] via 192.0.2.6, eth1, label 16002, weight 1, 1d03h18m -I>* 192.0.2.3/32 [115/10] via 192.0.2.6, eth1, label implicit-null, weight 1, 1d03h18m -I 192.0.2.4/30 [115/20] via 192.0.2.6, eth1 inactive, weight 1, 1d03h18m -I>* 192.0.2.11/32 [115/20] via 192.0.2.22, eth3, label implicit-null, weight 1, 1d02h47m -I>* 192.0.2.16/30 [115/20] via 192.0.2.6, eth1, weight 1, 1d03h18m -I 192.0.2.20/30 [115/20] via 192.0.2.22, eth3 inactive, weight 1, 1d02h48m -I>* 192.0.2.24/30 [115/30] via 192.0.2.6, eth1, weight 1, 1d03h18m - - -vyos@P2-VyOS:~$ show ip route isis -Codes: K - kernel route, C - connected, S - static, R - RIP, - O - OSPF, I - IS-IS, B - BGP, E - EIGRP, N - NHRP, - T - Table, v - VNC, V - VNC-Direct, A - Babel, F - PBR, - f - OpenFabric, - > - selected route, * - FIB route, q - queued, r - rejected, b - backup - t - trapped, o - offload failure - -I>* 192.0.2.1/32 [115/30] via 192.0.2.18, eth2, label 16001, weight 1, 1d03h17m -I>* 192.0.2.3/32 [115/10] via 192.0.2.18, eth2, label implicit-null, weight 1, 1d03h17m -I>* 192.0.2.4/30 [115/20] via 192.0.2.18, eth2, weight 1, 1d03h17m -I>* 192.0.2.11/32 [115/40] via 192.0.2.18, eth2, label 16011, weight 1, 1d02h47m -I 192.0.2.16/30 [115/20] via 192.0.2.18, eth2 inactive, weight 1, 1d03h17m -I>* 192.0.2.20/30 [115/30] via 192.0.2.18, eth2, weight 1, 1d03h17m - -RP/0/0/CPU0:P3-VyOS#show route isis -Tue Mar 28 18:19:16.417 UTC - -i L2 192.0.2.1/32 [115/20] via 192.0.2.5, 1d03h, GigabitEthernet0/0/0/1 -i L2 192.0.2.2/32 [115/20] via 192.0.2.17, 1d03h, GigabitEthernet0/0/0/2 -i L2 192.0.2.11/32 [115/30] via 192.0.2.5, 1d02h, GigabitEthernet0/0/0/1 -i L2 192.0.2.20/30 [115/20] via 192.0.2.5, 1d03h, GigabitEthernet0/0/0/1 -i L2 192.0.2.24/30 [115/20] via 192.0.2.17, 1d03h, GigabitEthernet0/0/0/2 -``` - -Information about prefix-sid and label-operation from VyOS - -```none -vyos@P1-VyOS:~$ show isis route prefix-sid -Area VyOS: -IS-IS L2 IPv4 routing table: - - Prefix Metric Interface Nexthop SID Label Op. - ---------------------------------------------------------------------- - 192.0.2.1/32 0 - - - - - 192.0.2.2/32 30 eth1 192.0.2.6 2 Swap(16002, 16002) - 192.0.2.3/32 10 eth1 192.0.2.6 3 Pop(16003) - 192.0.2.4/30 20 eth1 192.0.2.6 - - - 192.0.2.16/30 20 eth1 192.0.2.6 - - - 192.0.2.20/30 0 - - - - - 192.0.2.24/30 30 eth1 192.0.2.6 - - - - vyos@P2-VyOS:~$ show isis route prefix-sid - Area VyOS: - IS-IS L2 IPv4 routing table: - - Prefix Metric Interface Nexthop SID Label Op. - ----------------------------------------------------------------------- - 192.0.2.1/32 30 eth2 192.0.2.18 1 Swap(16001, 16001) - 192.0.2.2/32 0 - - - - - 192.0.2.3/32 10 eth2 192.0.2.18 3 Pop(16003) - 192.0.2.4/30 20 eth2 192.0.2.18 - - - 192.0.2.16/30 20 eth2 192.0.2.18 - - - 192.0.2.20/30 30 eth2 192.0.2.18 - - - 192.0.2.24/30 0 - - - - -``` - -Ping between VyOS-P1 / VyOS-P2 to confirm reachability: - -```none -vyos@P1-VyOS:~$ ping 192.0.2.2 source-address 192.0.2.1 -PING 192.0.2.2 (192.0.2.2) from 192.0.2.1 : 56(84) bytes of data. -64 bytes from 192.0.2.2: icmp_seq=1 ttl=63 time=3.47 ms -64 bytes from 192.0.2.2: icmp_seq=2 ttl=63 time=2.06 ms -64 bytes from 192.0.2.2: icmp_seq=3 ttl=63 time=3.90 ms -64 bytes from 192.0.2.2: icmp_seq=4 ttl=63 time=3.87 ms -^C ---- 192.0.2.2 ping statistics --- -4 packets transmitted, 4 received, 0% packet loss, time 3004ms -rtt min/avg/max/mdev = 2.064/3.326/3.903/0.748 ms - -vyos@P2-VyOS:~$ ping 192.0.2.1 source-address 192.0.2.2 -PING 192.0.2.1 (192.0.2.1) from 192.0.2.2 : 56(84) bytes of data. -64 bytes from 192.0.2.1: icmp_seq=1 ttl=63 time=2.91 ms -64 bytes from 192.0.2.1: icmp_seq=2 ttl=63 time=3.23 ms -64 bytes from 192.0.2.1: icmp_seq=3 ttl=63 time=2.91 ms -64 bytes from 192.0.2.1: icmp_seq=4 ttl=63 time=2.85 ms -^C ---- 192.0.2.1 ping statistics --- -4 packets transmitted, 4 received, 0% packet loss, time 3005ms -rtt min/avg/max/mdev = 2.846/2.972/3.231/0.151 ms -``` diff --git a/docs/configexamples/md-site-2-site-cisco.md b/docs/configexamples/md-site-2-site-cisco.md deleted file mode 100644 index a3b33d21..00000000 --- a/docs/configexamples/md-site-2-site-cisco.md +++ /dev/null @@ -1,167 +0,0 @@ -(examples-site-2-site-cisco)= - -# Site-to-Site IPSec VPN to Cisco using FlexVPN - -This guide shows a sample configuration for FlexVPN site-to-site Internet -Protocol Security (IPsec)/Generic Routing Encapsulation (GRE) tunnel. - -FlexVPN is a newer "solution" for deployment of VPNs and it utilizes IKEv2 as -the key exchange protocol. The result is a flexible and scalable VPN solution -that can be easily adapted to fit various network needs. It can also support a -variety of encryption methods, including AES and 3DES. - -The lab was built using EVE-NG. - -## Configuration - -### VyOS - -- GRE: - -```none -set interfaces tunnel tun1 encapsulation 'gre' -set interfaces tunnel tun1 ip adjust-mss '1336' -set interfaces tunnel tun1 mtu '1376' -set interfaces tunnel tun1 remote '10.1.1.6' -set interfaces tunnel tun1 source-address '198.51.100.1' -``` - -- IPsec: - -```none -set vpn ipsec authentication psk vyos_cisco_l id 'vyos.net’ -set vpn ipsec authentication psk vyos_cisco_l id 'cisco.hub.net' -set vpn ipsec authentication psk vyos_cisco_l secret 'secret' -set vpn ipsec esp-group e1 lifetime '3600' -set vpn ipsec esp-group e1 mode 'tunnel' -set vpn ipsec esp-group e1 pfs 'disable' -set vpn ipsec esp-group e1 proposal 1 encryption 'aes128' -set vpn ipsec esp-group e1 proposal 1 hash 'sha256' -set vpn ipsec ike-group i1 key-exchange 'ikev2' -set vpn ipsec ike-group i1 lifetime '28800' -set vpn ipsec ike-group i1 proposal 1 dh-group '5' -set vpn ipsec ike-group i1 proposal 1 encryption 'aes256' -set vpn ipsec ike-group i1 proposal 1 hash 'sha256' -set vpn ipsec interface 'eth2' -set vpn ipsec options disable-route-autoinstall -set vpn ipsec options flexvpn -set vpn ipsec options interface 'tun1' -set vpn ipsec options virtual-ip -set vpn ipsec site-to-site peer cisco_hub authentication local-id 'vyos.net' -set vpn ipsec site-to-site peer cisco_hub authentication mode 'pre-shared-secret' -set vpn ipsec site-to-site peer cisco_hub authentication remote-id 'cisco.hub.net' -set vpn ipsec site-to-site peer cisco_hub connection-type 'initiate' -set vpn ipsec site-to-site peer cisco_hub default-esp-group 'e1' -set vpn ipsec site-to-site peer cisco_hub ike-group 'i1' -set vpn ipsec site-to-site peer cisco_hub local-address '198.51.100.1' -set vpn ipsec site-to-site peer cisco_hub remote-address '10.1.1.6' -set vpn ipsec site-to-site peer cisco_hub tunnel 1 local prefix '198.51.100.1/32' -set vpn ipsec site-to-site peer cisco_hub tunnel 1 protocol 'gre' -set vpn ipsec site-to-site peer cisco_hub tunnel 1 remote prefix '10.1.1.6/32' -set vpn ipsec site-to-site peer cisco_hub virtual-address '0.0.0.0' -``` - -### Cisco - -```none -aaa new-model -! -! -aaa authorization network default local -! -crypto ikev2 name-mangler GET_DOMAIN - fqdn all - email all -! -! -crypto ikev2 authorization policy vyos - pool mypool - aaa attribute list mylist - route set interface - route accept any tag 100 distance 5 -! -crypto ikev2 keyring mykeys - peer peer1 - identity fqdn vyos.net - pre-shared-key local secret - pre-shared-key remote secret -crypto ikev2 profile my_profile - match identity remote fqdn vyos.net - identity local fqdn cisco.hub.net - authentication remote pre-share - authentication local pre-share - keyring local mykeys - dpd 10 3 periodic - aaa authorization group psk list local name-mangler GET_DOMAIN - aaa authorization user psk cached - virtual-template 1 -! -! -! -crypto ipsec transform-set TSET esp-aes esp-sha256-hmac - mode tunnel -! -! -crypto ipsec profile my-ipsec-profile - set transform-set TSET - set ikev2-profile my_profile -! -interface Virtual-Template1 type tunnel - no ip address - ip mtu 1376 - ip nhrp network-id 1 - ip nhrp shortcut virtual-template 1 - ip tcp adjust-mss 1336 - tunnel path-mtu-discovery - tunnel protection ipsec profile my-ipsec-profile - ! - ip local pool my_pool 172.16.122.1 172.16.122.254 -``` - -Since the tunnel is a point-to-point GRE tunnel, it behaves like any other -point-to-point interface (for example: serial, dialer), and it is possible to -run any Interior Gateway Protocol (IGP)/Exterior Gateway Protocol (EGP) over -the link in order to exchange routing information - -## Verification - -```none -vyos@vyos$ show interfaces -Codes: S - State, L - Link, u - Up, D - Down, A - Admin Down -Interface IP Address S/L Description ---------- ---------- --- ----------- -eth0 - u/u -eth1 - u/u -eth2 198.51.100.1/24 u/u -eth3 172.16.1.2/24 u/u -lo 127.0.0.1/8 u/u - ::1/128 -tun1 172.16.122.2/32 u/u -vyos@vyos:~$ show vpn ipsec sa -Connection State Uptime Bytes In/Out Packets In/Out Remote address Remote ID Proposal ------------------- ------- -------- -------------- ---------------- ---------------- --------------------- ----------------------------- -cisco_hub-tunnel-1 up 44m17s 35K/31K 382/367 10.1.1.6 cisco.hub.net AES_CBC_128/HMAC_SHA2_256_128 - - -Hub#sh crypto ikev2 sa detailed - IPv4 Crypto IKEv2 SA -Tunnel-id Local Remote fvrf/ivrf Status -5 10.1.1.6/4500 198.51.100.1/4500 none/none READY - Encr: AES-CBC, keysize: 256, PRF: SHA256, Hash: SHA256, DH Grp:5, Auth sign: PSK, Auth verify: PSK - Life/Active Time: 86400/2694 sec - CE id: 0, Session-id: 2 - Status Description: Negotiation done - Local spi: C94EE2DC92A60C47 Remote spi: 9AF0EF151BECF14C - Local id: cisco.hub.net - Remote id: vyos.net - Local req msg id: 269 Remote req msg id: 0 - Local next msg id: 269 Remote next msg id: 0 - Local req queued: 269 Remote req queued: 0 - Local window: 5 Remote window: 1 - DPD configured for 10 seconds, retry 3 - Fragmentation not configured. - Extended Authentication not configured. - NAT-T is not detected - Cisco Trust Security SGT is disabled - Assigned host addr: 172.16.122.2 -``` diff --git a/docs/configexamples/md-wan-load-balancing.md b/docs/configexamples/md-wan-load-balancing.md deleted file mode 100644 index 21c78f2a..00000000 --- a/docs/configexamples/md-wan-load-balancing.md +++ /dev/null @@ -1,158 +0,0 @@ ---- -lastproofread: '2021-06-29' ---- - -(wan-load-balancing)= - - -# WAN Load Balancer examples - -## Example 1: Distributing load evenly - -The setup used in this example is shown in the following diagram: - -```{image} /_static/images/Wan_load_balancing1.png -:align: center -:alt: Network Topology Diagram -:width: 80% -``` - -### Overview -> - All traffic coming in through eth2 is balanced between eth0 and eth1 -> on the router. -> - Pings will be sent to four targets for health testing (33.44.55.66, -> 44.55.66.77, 55.66.77.88 and 66.77.88.99). -> - All outgoing packets are assigned the source address of the assigned -> interface (SNAT). -> - eth0 is set to be removed from the load balancer's interface pool -> after 5 ping failures, eth1 will be removed after 4 ping failures. - -### Create static routes to ping targets -Create static routes through the two ISPs towards the ping targets and -commit the changes: - -```none -set protocols static route 33.44.55.66/32 next-hop 11.22.33.1 -set protocols static route 44.55.66.77/32 next-hop 11.22.33.1 -set protocols static route 55.66.77.88/32 next-hop 22.33.44.1 -set protocols static route 66.77.88.99/32 next-hop 22.33.44.1 -``` - -### Configure the load balancer -Configure the WAN load balancer with the parameters described above: - -```none -set load-balancing wan interface-health eth0 failure-count 5 -set load-balancing wan interface-health eth0 nexthop 11.22.33.1 -set load-balancing wan interface-health eth0 test 10 type ping -set load-balancing wan interface-health eth0 test 10 target 33.44.55.66 -set load-balancing wan interface-health eth0 test 20 type ping -set load-balancing wan interface-health eth0 test 20 target 44.55.66.77 -set load-balancing wan interface-health eth1 failure-count 4 -set load-balancing wan interface-health eth1 nexthop 22.33.44.1 -set load-balancing wan interface-health eth1 test 10 type ping -set load-balancing wan interface-health eth1 test 10 target 55.66.77.88 -set load-balancing wan interface-health eth1 test 20 type ping -set load-balancing wan interface-health eth1 test 20 target 66.77.88.99 -set load-balancing wan rule 10 inbound-interface eth2 -set load-balancing wan rule 10 interface eth0 -set load-balancing wan rule 10 interface eth1 -``` - -## Example 2: Failover based on interface weights -This example uses the failover mode. -(wan-example2-overview)= - -### Overview -In this example, eth0 is the primary interface and eth1 is the secondary -interface. To provide simple failover functionality. If eth0 fails, eth1 -takes over. - -### Create interface weight based configuration -The configuration steps are the same as in the previous example, except -rule 10. So we keep the configuration, remove rule 10 and add a new rule -for the failover mode: - -```none -delete load-balancing wan rule 10 -set load-balancing wan rule 10 failover -set load-balancing wan rule 10 inbound-interface eth2 -set load-balancing wan rule 10 interface eth0 weight 10 -set load-balancing wan rule 10 interface eth1 weight 1 -``` - -## Example 3: Failover based on rule order -The previous example used the failover command to send traffic through -eth1 if eth0 fails. In this example, failover functionality is provided -by rule order. -(wan-example3-overview)= - -### Overview -Two rules will be created, the first rule directs traffic coming in -from eth2 to eth0 and the second rule directs the traffic to eth1. If -eth0 fails the first rule is bypassed and the second rule matches, -directing traffic to eth1. - -### Create rule order based configuration -We keep the configuration from the previous example, delete rule 10 -and create the two new rules as described: - -```none -delete load-balancing wan rule 10 -set load-balancing wan rule 10 inbound-interface eth2 -set load-balancing wan rule 10 interface eth0 -set load-balancing wan rule 20 inbound-interface eth2 -set load-balancing wan rule 20 interface eth1 -``` - -## Example 4: Failover based on rule order - priority traffic -A rule order for prioritizing traffic is useful in scenarios where the -secondary link has a lower speed and should only carry high priority -traffic. It is assumed for this example that eth1 is connected to a -slower connection than eth0 and should prioritize VoIP traffic. -(wan-example4-overview)= - -### Overview -A rule order for prioritizing traffic is useful in scenarios where the -secondary link has a lower speed and should only carry high priority -traffic. It is assumed for this example that eth1 is connected to a -slower connection than eth0 and should prioritize VoIP traffic. - -### Create rule order based configuration with low speed secondary link -We keep the configuration from the previous example, delete rule 20 and -create a new rule as described: - -```none -delete load-balancing wan rule 20 -set load-balancing wan rule 20 inbound-interface eth2 -set load-balancing wan rule 20 interface eth1 -set load-balancing wan rule 20 destination port sip -set load-balancing wan rule 20 protocol tcp -set protocols static route 0.0.0.0/0 next-hop 11.22.33.1 -``` - -## Example 5: Exclude traffic from load balancing -In this example two LAN interfaces exist in different subnets instead -of one like in the previous examples: - -```{image} /_static/images/Wan_load_balancing_exclude1.png -:align: center -:alt: Network Topology Diagram -:width: 80% -``` - -### Adding a rule for the second interface -Based on the previous example, another rule for traffic from the second -interface eth3 can be added to the load balancer. However, traffic meant -to flow between the LAN subnets will be sent to eth0 and eth1 as well. -To prevent this, another rule is required. This rule excludes traffic -between the local subnets from the load balancer. It also excludes -locally-sources packets (required for web caching with load balancing). -eth+ is used as an alias that refers to all ethernet interfaces: - -```none -set load-balancing wan rule 5 exclude -set load-balancing wan rule 5 inbound-interface eth+ -set load-balancing wan rule 5 destination address 10.0.0.0/8 -``` - diff --git a/docs/configexamples/md-zone-policy.md b/docs/configexamples/md-zone-policy.md deleted file mode 100644 index 6018e7fe..00000000 --- a/docs/configexamples/md-zone-policy.md +++ /dev/null @@ -1,413 +0,0 @@ ---- -lastproofread: '2024-06-14' ---- - -(examples-zone-policy)= - -# Zone-Policy example - -:::{note} -In {vytask}`T2199` the syntax of the zone configuration was changed. -The zone configuration moved from `zone-policy zone <name>` to `firewall -zone <name>`. -::: - -## Native IPv4 and IPv6 - -We have three networks. - -```none -WAN - 172.16.10.0/24, 2001:0DB8:0:9999::0/64 -LAN - 192.168.100.0/24, 2001:0DB8:0:AAAA::0/64 -DMZ - 192.168.200.0/24, 2001:0DB8:0:BBBB::0/64 -``` - -**This specific example is for a router on a stick, but is very easily -adapted for however many NICs you have**: - -- Internet - 192.168.200.100 - TCP/80 -- Internet - 192.168.200.100 - TCP/443 -- Internet - 192.168.200.100 - TCP/25 -- Internet - 192.168.200.100 - TCP/53 -- VyOS acts as DHCP, DNS forwarder, NAT, router and firewall. -- 192.168.200.200/2001:0DB8:0:BBBB::200 is an internal/external DNS, web - and mail (SMTP/IMAP) server. -- 192.168.100.10/2001:0DB8:0:AAAA::10 is the administrator's console. It - can SSH to VyOS. -- LAN and DMZ hosts have basic outbound access: Web, FTP, SSH. -- LAN can access DMZ resources. -- DMZ cannot access LAN resources. -- Inbound WAN connect to DMZ host. - -```{image} /_static/images/zone-policy-diagram.png -:align: center -:alt: Network Topology Diagram -:width: 80% -``` - -The VyOS interface is assigned the .1/:1 address of their respective -networks. WAN is on VLAN 10, LAN on VLAN 20, and DMZ on VLAN 30. - -It will look something like this: - -```none -interfaces { - ethernet eth0 { - duplex auto - hw-id 00:53:ed:6e:2a:92 - smp_affinity auto - speed auto - vif 10 { - address 172.16.10.1/24 - address 2001:db8:0:9999::1/64 - } - vif 20 { - address 192.168.100.1/24 - address 2001:db8:0:AAAA::1/64 - } - vif 30 { - address 192.168.200.1/24 - address 2001:db8:0:BBBB::1/64 - } - } - loopback lo { - } -} -``` - -## Zones Basics -Each interface is assigned to a zone. The interface can be physical or -virtual such as tunnels (VPN, PPTP, GRE, etc) and are treated exactly -the same. - -Traffic flows from zone A to zone B. That flow is what I refer to as a -zone-pair-direction. eg. A->B and B->A are two zone-pair-destinations. - -Ruleset are created per zone-pair-direction. - -I name rule sets to indicate which zone-pair-direction they represent. -eg. ZoneA-ZoneB or ZoneB-ZoneA. LAN-DMZ, DMZ-LAN. - -In VyOS, you have to have unique Ruleset names. In the event of overlap, -I add a "-6" to the end of v6 rulesets. eg. LAN-DMZ, LAN-DMZ-6. This -allows for each auto-completion and uniqueness. - -In this example we have 4 zones. LAN, WAN, DMZ, Local. The local zone is -the firewall itself. - -If your computer is on the LAN and you need to SSH into your VyOS box, -you would need a rule to allow it in the LAN-Local ruleset. If you want -to access a webpage from your VyOS box, you need a rule to allow it in -the Local-LAN ruleset. - -In rules, it is good to keep them named consistently. As the number of -rules you have grows, the more consistency you have, the easier your -life will be. - -```none -Rule 1 - State Established, Related -Rule 2 - State Invalid -Rule 100 - ICMP -Rule 200 - Web -Rule 300 - FTP -Rule 400 - NTP -Rule 500 - SMTP -Rule 600 - DNS -Rule 700 - DHCP -Rule 800 - SSH -Rule 900 - IMAPS -``` - -The first two rules are to deal with the idiosyncrasies of VyOS and -iptables. - -Zones and Rulesets both have a default action statement. When using -Zone-Policies, the default action is set by the zone-policy statement -and is represented by rule 10000. - -It is good practice to log both accepted and denied traffic. It can save -you significant headaches when trying to troubleshoot a connectivity -issue. - -To add logging to the default rule, do: - -```none -set firewall name <ruleSet> default-log -``` - -By default, iptables does not allow traffic for established sessions to -return, so you must explicitly allow this. I do this by adding two rules -to every ruleset. 1 allows established and related state packets through -and rule 2 drops and logs invalid state packets. We place the -established/related rule at the top because the vast majority of traffic -on a network is established and the invalid rule to prevent invalid -state packets from mistakenly being matched against other rules. Having -the most matched rule listed first reduces CPU load in high volume -environments. Note: I have filed a bug to have this added as a default -action as well. - -''It is important to note, that you do not want to add logging to the -established state rule as you will be logging both the inbound and -outbound packets for each session instead of just the initiation of the -session. Your logs will be massive in a very short period of time.'' - -In VyOS you must have the interfaces created before you can apply it to -the zone and the rulesets must be created prior to applying it to a -zone-policy. - -I create/configure the interfaces first. Build out the rulesets for each -zone-pair-direction which includes at least the three state rules. Then -I setup the zone-policies. - -Zones do not allow for a default action of accept; either drop or -reject. It is important to remember this because if you apply an -interface to a zone and commit, any active connections will be dropped. -Specifically, if you are SSH’d into VyOS and add local or the interface -you are connecting through to a zone and do not have rulesets in place -to allow SSH and established sessions, you will not be able to connect. - -The following are the rules that were created for this example (may not -be complete), both in IPv4 and IPv6. If there is no IP specified, then -the source/destination address is not explicit. - -```none -WAN - DMZ:192.168.200.200 - tcp/80 -WAN - DMZ:192.168.200.200 - tcp/443 -WAN - DMZ:192.168.200.200 - tcp/25 -WAN - DMZ:192.168.200.200 - tcp/53 -WAN - DMZ:2001:0DB8:0:BBBB::200 - tcp/80 -WAN - DMZ:2001:0DB8:0:BBBB::200 - tcp/443 -WAN - DMZ:2001:0DB8:0:BBBB::200 - tcp/25 -WAN - DMZ:2001:0DB8:0:BBBB::200 - tcp/53 - -DMZ - Local - tcp/53 -DMZ - Local - tcp/123 -DMZ - Local - tcp/67,68 - -LAN - Local - tcp/53 -LAN - Local - tcp/123 -LAN - Local - tcp/67,68 -LAN:192.168.100.10 - Local - tcp/22 -LAN:2001:0DB8:0:AAAA::10 - Local - tcp/22 - -LAN - WAN - tcp/80 -LAN - WAN - tcp/443 -LAN - WAN - tcp/22 -LAN - WAN - tcp/20,21 - -DMZ - WAN - tcp/80 -DMZ - WAN - tcp/443 -DMZ - WAN - tcp/22 -DMZ - WAN - tcp/20,21 -DMZ - WAN - tcp/53 -DMZ - WAN - udp/53 - -Local - WAN - tcp/80 -Local - WAN - tcp/443 -Local - WAN - tcp/20,21 - -Local - DMZ - tcp/25 -Local - DMZ - tcp/67,68 -Local - DMZ - tcp/53 -Local - DMZ - udp/53 - -Local - LAN - tcp/67,68 - -LAN - DMZ - tcp/80 -LAN - DMZ - tcp/443 -LAN - DMZ - tcp/993 -LAN:2001:0DB8:0:AAAA::10 - DMZ:2001:0DB8:0:BBBB::200 - tcp/22 -LAN:192.168.100.10 - DMZ:192.168.200.200 - tcp/22 -``` - -Since we have 4 zones, we need to setup the following rulesets. - -```none -Lan-wan -Lan-local -Lan-dmz -Wan-lan -Wan-local -Wan-dmz -Local-lan -Local-wan -Local-dmz -Dmz-lan -Dmz-wan -Dmz-local -``` - -Even if the two zones will never communicate, it is a good idea to -create the zone-pair-direction rulesets and set default-log. This -will allow you to log attempts to access the networks. Without it, you -will never see the connection attempts. - -This is an example of the three base rules. - -```none -name wan-lan { - default-action drop - default-log - rule 1 { - action accept - state { - established enable - related enable - } - } - rule 2 { - action drop - log enable - state { - invalid enable - } - } -} -``` - -Here is an example of an IPv6 DMZ-WAN ruleset. - -```none -ipv6-name dmz-wan-6 { - default-action drop - default-log - rule 1 { - action accept - state { - established enable - related enable - } - } - rule 2 { - action drop - log enable - state { - invalid enable - } - rule 100 { - action accept - log enable - protocol ipv6-icmp - } - rule 200 { - action accept - destination { - port 80,443 - } - log enable - protocol tcp - } - rule 300 { - action accept - destination { - port 20,21 - } - log enable - protocol tcp - } - rule 500 { - action accept - destination { - port 25 - } - log enable - protocol tcp - source { - address 2001:db8:0:BBBB::200 - } - } - rule 600 { - action accept - destination { - port 53 - } - log enable - protocol tcp_udp - source { - address 2001:db8:0:BBBB::200 - } - } - rule 800 { - action accept - destination { - port 22 - } - log enable - protocol tcp - } -} -``` - -Once you have all of your rulesets built, then you need to create your -zone-policy. - -Start by setting the interface and default action for each zone. - -```none -set firewall zone dmz default-action drop -set firewall zone dmz interface eth0.30 -``` - -In this case, we are setting the v6 ruleset that represents traffic -sourced from the LAN, destined for the DMZ. Because the zone-policy -firewall syntax is a little awkward, I keep it straight by thinking of -it backwards. - -```none -set firewall zone dmz from lan firewall ipv6-name lan-dmz-6 -``` - -DMZ-LAN policy is LAN-DMZ. You can get a rhythm to it when you build out -a bunch at one time. - -In the end, you will end up with something like this config. I took out -everything but the Firewall, Interfaces, and zone-policy sections. It is -long enough as is. - -## IPv6 Tunnel -If you are using a IPv6 tunnel from HE.net or someone else, the basis is -the same except you have two WAN interfaces. One for v4 and one for v6. - -You would have 5 zones instead of just 4 and you would configure your v6 -ruleset between your tunnel interface and your LAN/DMZ zones instead of -to the WAN. - -LAN, WAN, DMZ, local and TUN (tunnel) - -v6 pairs would be: - -```none -lan-tun -lan-local -lan-dmz -tun-lan -tun-local -tun-dmz -local-lan -local-tun -local-dmz -dmz-lan -dmz-tun -dmz-local -``` - -Notice, none go to WAN since WAN wouldn't have a v6 address on it. - -You would have to add a couple of rules on your wan-local ruleset to -allow protocol 41 in. - -Something like: - -```none -rule 400 { - action accept - destination { - address 172.16.10.1 - } - log enable - protocol 41 - source { - address ip.of.tunnel.broker - } -} -``` diff --git a/docs/configuration/firewall/md-bridge.md b/docs/configuration/firewall/md-bridge.md deleted file mode 100644 index 42442ee7..00000000 --- a/docs/configuration/firewall/md-bridge.md +++ /dev/null @@ -1,673 +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: -```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.png -::: - - -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.png -::: - - -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.png -::: - - -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: -```none -set firewall bridge forward filter default-action 'drop' -set firewall bridge forward filter default-log -set firewall bridge forward filter rule 10 action 'continue' -set firewall bridge forward filter rule 10 inbound-interface name 'eth2' -set firewall bridge forward filter rule 10 vlan id '22' -set firewall bridge forward filter rule 20 action 'drop' -set firewall bridge forward filter rule 20 inbound-interface group 'TRUNK-RIGHT' -set firewall bridge forward filter rule 20 vlan id '60' -set firewall bridge forward filter rule 30 action 'jump' -set firewall bridge forward filter rule 30 jump-target 'TEST' -set firewall bridge forward filter rule 30 outbound-interface name '!eth1' -set firewall bridge forward filter rule 35 action 'accept' -set firewall bridge forward filter rule 35 vlan id '11' -set firewall bridge forward filter rule 40 action 'continue' -set firewall bridge forward filter rule 40 destination mac-address '66:55:44:33:22:11' -set firewall bridge forward filter rule 40 source mac-address '11:22:33:44:55:66' -set firewall bridge name TEST default-action 'accept' -set firewall bridge name TEST default-log -set firewall bridge name TEST rule 10 action 'continue' -set firewall bridge name TEST rule 10 log -set firewall bridge name TEST rule 10 vlan priority '0' -``` -And op-mode commands: -```none -vyos@BRI:~$ show firewall bridge -Rulesets bridge Information - ---------------------------------- -bridge Firewall "forward filter" - -Rule Action Protocol Packets Bytes Conditions -------- -------- ---------- --------- ------- --------------------------------------------------------------------- -10 continue all 0 0 iifname "eth2" vlan id 22 continue -20 drop all 0 0 iifname @I_TRUNK-RIGHT vlan id 60 -30 jump all 2130 170688 oifname != "eth1" jump NAME_TEST -35 accept all 2080 168616 vlan id 11 accept -40 continue all 0 0 ether daddr 66:55:44:33:22:11 ether saddr 11:22:33:44:55:66 continue -default drop all 0 0 - ---------------------------------- -bridge Firewall "name TEST" - -Rule Action Protocol Packets Bytes Conditions -------- -------- ---------- --------- ------- -------------------------------------------------- -10 continue all 2130 170688 vlan pcp 0 prefix "[bri-NAM-TEST-10-C]" continue -default accept all 2130 170688 - -vyos@BRI:~$ -vyos@BRI:~$ show firewall bridge name TEST -Ruleset Information - ---------------------------------- -bridge Firewall "name TEST" - -Rule Action Protocol Packets Bytes Conditions -------- -------- ---------- --------- ------- -------------------------------------------------- -10 continue all 2130 170688 vlan pcp 0 prefix "[bri-NAM-TEST-10-C]" continue -default accept all 2130 170688 - -vyos@BRI:~$ -``` -Inspect logs: -```none -vyos@BRI:~$ show log firewall bridge -Dec 05 14:37:47 kernel: [bri-NAM-TEST-10-C]IN=eth1 OUT=eth2 ARP HTYPE=1 PTYPE=0x0800 OPCODE=1 MACSRC=50:00:00:04:00:00 IPSRC=10.11.11.101 MACDST=00:00:00:00:00:00 IPDST=10.11.11.102 -Dec 05 14:37:48 kernel: [bri-NAM-TEST-10-C]IN=eth1 OUT=eth2 ARP HTYPE=1 PTYPE=0x0800 OPCODE=1 MACSRC=50:00:00:04:00:00 IPSRC=10.11.11.101 MACDST=00:00:00:00:00:00 IPDST=10.11.11.102 -Dec 05 14:37:49 kernel: [bri-NAM-TEST-10-C]IN=eth1 OUT=eth2 ARP HTYPE=1 PTYPE=0x0800 OPCODE=1 MACSRC=50:00:00:04:00:00 IPSRC=10.11.11.101 MACDST=00:00:00:00:00:00 IPDST=10.11.11.102 -... -vyos@BRI:~$ show log firewall bridge forward filter -Dec 05 14:42:22 kernel: [bri-FWD-filter-default-D]IN=eth2 OUT=eth1 MAC=33:33:00:00:00:16:50:00:00:06:00:00:86:dd SRC=0000:0000:0000:0000:0000:0000:0000:0000 DST=ff02:0000:0000:0000:0000:0000:0000:0016 LEN=96 TC=0 HOPLIMIT=1 FLOWLBL=0 PROTO=ICMPv6 TYPE=143 CODE=0 -Dec 05 14:42:22 kernel: [bri-FWD-filter-default-D]IN=eth2 OUT=eth1 MAC=33:33:00:00:00:16:50:00:00:06:00:00:86:dd SRC=0000:0000:0000:0000:0000:0000:0000:0000 DST=ff02:0000:0000:0000:0000:0000:0000:0016 LEN=96 TC=0 HOPLIMIT=1 FLOWLBL=0 PROTO=ICMPv6 TYPE=143 CODE=0 -``` diff --git a/docs/configuration/firewall/md-global-options.md b/docs/configuration/firewall/md-global-options.md deleted file mode 100644 index 3a480472..00000000 --- a/docs/configuration/firewall/md-global-options.md +++ /dev/null @@ -1,214 +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/md-groups.md b/docs/configuration/firewall/md-groups.md deleted file mode 100644 index 2e4bdec1..00000000 --- a/docs/configuration/firewall/md-groups.md +++ /dev/null @@ -1,419 +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: -```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``. -``` - -```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. -``` - -```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. -``` - -```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: -```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: -```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: -```none -set firewall group address-group SERVERS address 198.51.100.101 -set firewall group address-group SERVERS address 198.51.100.102 -set firewall group network-group TRUSTEDv4 network 192.0.2.0/30 -set firewall group network-group TRUSTEDv4 network 203.0.113.128/25 -set firewall group ipv6-network-group TRUSTEDv6 network 2001:db8::/64 -set firewall group interface-group LAN interface eth2.2001 -set firewall group interface-group LAN interface bon0 -set firewall group port-group PORT-SERVERS port http -set firewall group port-group PORT-SERVERS port 443 -set firewall group port-group PORT-SERVERS port 5000-5010 -``` -And next, some configuration example where groups are used: -```none -set firewall ipv4 output filter rule 10 action accept -set firewall ipv4 output filter rule 10 outbound-interface group !LAN -set firewall ipv4 forward filter rule 20 action accept -set firewall ipv4 forward filter rule 20 source group network-group TRUSTEDv4 -set firewall ipv6 input filter rule 10 action accept -set firewall ipv6 input filter rule 10 source group network-group TRUSTEDv6 -set nat destination rule 101 inbound-interface group LAN -set nat destination rule 101 destination group address-group SERVERS -set nat destination rule 101 protocol tcp -set nat destination rule 101 destination group port-group PORT-SERVERS -set nat destination rule 101 translation address 203.0.113.250 -set policy route PBR rule 201 destination group port-group PORT-SERVERS -set policy route PBR rule 201 protocol tcp -set policy route PBR rule 201 set table 15 -``` -### Port knocking example -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: -```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: -```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`. - - ```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`. - - ```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`. - - ```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: -```none -vyos@vyos:~$ show firewall group -Firewall Groups - -Name Type References Members Timeout Expires ------------- ---------------------- ---------------------- ---------------- --------- --------- -SERVERS address_group nat-destination-101 198.51.100.101 - 198.51.100.102 -ALLOWED address_group(dynamic) ipv4-input-filter-30 192.168.77.39 7200 7174 -PN_01 address_group(dynamic) ipv4-input-filter-10 192.168.0.245 120 112 - 192.168.77.39 120 85 -PN_02 address_group(dynamic) ipv4-input-filter-20 192.168.77.39 180 151 -LAN interface_group ipv4-output-filter-10 bon0 - nat-destination-101 eth2.2001 -TRUSTEDv6 ipv6_network_group ipv6-input-filter-10 2001:db8::/64 -TRUSTEDv4 network_group ipv4-forward-filter-20 192.0.2.0/30 - 203.0.113.128/25 -PORT-SERVERS port_group route-PBR-201 443 - route-PBR-201 5000-5010 - nat-destination-101 http -vyos@vyos:~$ -``` diff --git a/docs/configuration/firewall/md-ipv6.md b/docs/configuration/firewall/md-ipv6.md deleted file mode 100644 index bbbaec16..00000000 --- a/docs/configuration/firewall/md-ipv6.md +++ /dev/null @@ -1,1624 +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>`. -```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.png -::: - - -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.png -::: - - -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 -```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 -```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. -```
\ No newline at end of file diff --git a/docs/configuration/interfaces/md-index.md b/docs/configuration/interfaces/md-index.md deleted file mode 100644 index 9082cd80..00000000 --- a/docs/configuration/interfaces/md-index.md +++ /dev/null @@ -1,26 +0,0 @@ -# Interfaces - -```{toctree} -:includehidden: true -:maxdepth: 1 - -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/loadbalancing/md-index.md b/docs/configuration/loadbalancing/md-index.md deleted file mode 100644 index 3241edb7..00000000 --- a/docs/configuration/loadbalancing/md-index.md +++ /dev/null @@ -1,15 +0,0 @@ ---- -lastproofread: '2026-04-06' ---- - -(load-balancing)= - -# Load-balancing - -```{toctree} -:includehidden: true -:maxdepth: 1 - -wan -haproxy -``` diff --git a/docs/configuration/md-index.md b/docs/configuration/md-index.md deleted file mode 100644 index 3e215502..00000000 --- a/docs/configuration/md-index.md +++ /dev/null @@ -1,23 +0,0 @@ -# Configuration Guide - -The following structure represents the CLI structure. - -```{toctree} -:includehidden: true -:maxdepth: 1 - -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/nat/md-index.md b/docs/configuration/nat/md-index.md deleted file mode 100644 index 35e5d32b..00000000 --- a/docs/configuration/nat/md-index.md +++ /dev/null @@ -1,13 +0,0 @@ -(nat)= - -# NAT - -```{toctree} -:includehidden: true -:maxdepth: 1 - -nat44 -nat64 -nat66 -cgnat -``` diff --git a/docs/configuration/pki/md-index.md b/docs/configuration/pki/md-index.md deleted file mode 100644 index be59e30f..00000000 --- a/docs/configuration/pki/md-index.md +++ /dev/null @@ -1,551 +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. - -:::{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. - -``name`` is used for the VyOS CLI command to identify this key. This -key ``name`` is then used in the CLI configuration to reference the key -instance. -::: -``` - -```{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`. - -:::{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. - -``name`` is used for the VyOS CLI command to identify this key. This -key ``name`` is then used in the CLI configuration to reference the key -instance. -::: -``` -### 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. - -:::{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. - -``name`` is used for the VyOS CLI command to identify this key. This -key ``name`` is then used in the CLI configuration to reference the key -instance. -::: -``` - -```{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. - -:::{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. - -``name`` is used for the VyOS CLI command to identify this key. This -key ``name`` is then used in the CLI configuration to reference the key -instance. -::: -``` - -```{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. - -:::{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. - -``name`` is used for the VyOS CLI command to identify this key. This -key ``name`` is then used in the CLI configuration to reference the key -instance. -::: -``` -### 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. - -:::{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. - -``name`` is used for the VyOS CLI command to identify this key. This -key ``name`` is then used in the CLI configuration to reference the key -instance. -::: -``` -### 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. - -:::{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. - -``name`` is used for the VyOS CLI command to identify this key. This -key ``name`` is then used in the CLI configuration to reference the key -instance. -::: -``` -### 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. -```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. -```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. -```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/md-as-path-list.md b/docs/configuration/policy/md-as-path-list.md deleted file mode 100644 index 1fcece91..00000000 --- a/docs/configuration/policy/md-as-path-list.md +++ /dev/null @@ -1,29 +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". -```
\ No newline at end of file diff --git a/docs/configuration/policy/md-community-list.md b/docs/configuration/policy/md-community-list.md deleted file mode 100644 index bdcf4140..00000000 --- a/docs/configuration/policy/md-community-list.md +++ /dev/null @@ -1,29 +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/md-examples.md b/docs/configuration/policy/md-examples.md deleted file mode 100644 index 992aa82c..00000000 --- a/docs/configuration/policy/md-examples.md +++ /dev/null @@ -1,203 +0,0 @@ -# BGP Example - -**Policy definition:** - -```none -# Create policy -set policy route-map setmet rule 2 action 'permit' -set policy route-map setmet rule 2 set as-path prepend '2 2 2' - -# Apply policy to BGP -set protocols bgp system-as 1 -set protocols bgp neighbor 203.0.113.2 address-family ipv4-unicast route-map import 'setmet' -set protocols bgp neighbor 203.0.113.2 address-family ipv4-unicast soft-reconfiguration 'inbound' -``` - -Using 'soft-reconfiguration' we get the policy update without bouncing the -neighbor. - -**Routes learned before routing policy applied:** - -```none -vyos@vos1:~$ show ip bgp -BGP table version is 0, local router ID is 192.168.56.101 -Status codes: s suppressed, d damped, h history, * valid, > best, i - internal, - r RIB-failure, S Stale, R Removed -Origin codes: i - IGP, e - EGP, ? - incomplete - - Network Next Hop Metric LocPrf Weight Path -*> 198.51.100.3/32 203.0.113.2 1 0 2 i < Path - -Total number of prefixes 1 -``` - -**Routes learned after routing policy applied:** - -```none -vyos@vos1:~$ show ip bgp -BGP table version is 0, local router ID is 192.168.56.101 -Status codes: s suppressed, d damped, h history, * valid, > best, i - internal, - r RIB-failure, S Stale, R Removed -Origin codes: i - IGP, e - EGP, ? - incomplete - - Network Next Hop Metric LocPrf Weight Path -*> 198.51.100.3/32 203.0.113.2 1 0 2 2 2 2 i - -Total number of prefixes 1 -vyos@vos1:~$ -``` - -You now see the longer AS path. - -# Transparent Proxy - -The following example will show how VyOS can be used to redirect web -traffic to an external transparent proxy: - -```none -set policy route FILTER-WEB rule 1000 destination port 80 -set policy route FILTER-WEB rule 1000 protocol tcp -set policy route FILTER-WEB rule 1000 set table 100 -``` - -This creates a route policy called FILTER-WEB with one rule to set the -routing table for matching traffic (TCP port 80) to table ID 100 -instead of the default routing table. - -To create routing table 100 and add a new default gateway to be used by -traffic matching our route policy: - -```none -set protocols static table 100 route 0.0.0.0/0 next-hop 10.255.0.2 -``` - -This can be confirmed using the `show ip route table 100` operational -command. - -Finally, to apply the policy route to ingress traffic on our LAN -interface, we use: - -```none -set policy route FILTER-WEB interface eth1 -``` - -# Multiple Uplinks - -VyOS Policy-Based Routing (PBR) works by matching source IP address -ranges and forwarding the traffic using different routing tables. - -Routing tables that will be used in this example are: - -- `table 10` Routing table used for VLAN 10 (192.168.188.0/24) -- `table 11` Routing table used for VLAN 11 (192.168.189.0/24) -- `main` Routing table used by VyOS and other interfaces not - participating in PBR - -:::{figure} /_static/images/pbr_example_1.png -:alt: PBR multiple uplinks -:scale: 80 % - -Policy-Based Routing with multiple ISP uplinks -(source ./draw.io/pbr_example_1.drawio) -::: - -Add default routes for routing `table 10` and `table 11` - -```none -set protocols static table 10 route 0.0.0.0/0 next-hop 192.0.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 - -```none -set policy route PBR rule 20 set table '10' -set policy route PBR rule 20 description 'Route VLAN10 traffic to table 10' -set policy route PBR rule 20 source address '192.168.188.0/24' - -set policy route PBR rule 30 set table '11' -set policy route PBR rule 30 description 'Route VLAN11 traffic to table 11' -set policy route PBR rule 30 source address '192.168.189.0/24' -``` - -Apply routing policy to **inbound** direction of out VLAN interfaces - -```none -set policy route 'PBR' interface eth0.10 -set policy route 'PBR' interface eth0.11 -``` - -**OPTIONAL:** Exclude Inter-VLAN traffic (between VLAN10 and VLAN11) -from PBR - -```none -set firewall group network-group VLANS-GR description 'VLANs networks' -set firewall group network-group VLANS-GR network '192.168.188.0/24' -set firewall group network-group VLANS-GR network '192.168.189.0/24' - -set policy route PBR rule 10 description 'VLAN10 <-> VLAN11 shortcut' -set policy route PBR rule 10 destination group network-group 'VLANS-GR' -set policy route PBR rule 10 set table 'main' -``` - -These commands allow the VLAN10 and VLAN11 hosts to communicate with -each other using the main routing table. - -## Local route - -The following example allows VyOS to use {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 - -```none -set policy local-route rule 101 set table '10' -set policy local-route rule 101 source address '203.0.113.254' -set policy local-route rule 102 set table '11' -set policy local-route rule 102 source address '192.0.2.254' -set protocols static table 10 route 0.0.0.0/0 next-hop '203.0.113.1' -set protocols static table 11 route 0.0.0.0/0 next-hop '192.0.2.2' -``` - -Add multiple source IP in one rule with same priority - -```none -set policy local-route rule 101 set table '10' -set policy local-route rule 101 source address '203.0.113.254' -set policy local-route rule 101 source address '203.0.113.253' -set policy local-route rule 101 source address '198.51.100.0/24' -``` - -# Clamp MSS for a specific IP - -This example shows how to target an MSS clamp (in our example to 1360 bytes) -to a specific destination IP. - -```none -set policy route IP-MSS-CLAMP rule 10 description 'Clamp TCP session MSS to 1360 for 198.51.100.30' -set policy route IP-MSS-CLAMP rule 10 destination address '198.51.100.30/32' -set policy route IP-MSS-CLAMP rule 10 protocol 'tcp' -set policy route IP-MSS-CLAMP rule 10 set tcp-mss '1360' -set policy route IP-MSS-CLAMP rule 10 tcp flags 'SYN' -``` - -To apply this policy to the correct interface, configure it on the -interface the inbound local host will send through to reach our -destined target host (in our example eth1). - -```none -set policy route IP-MSS-CLAMP interface eth1 -``` - -You can view that the policy is being correctly (or incorrectly) utilised -with the following command: - -```none -show policy route statistics -``` diff --git a/docs/configuration/policy/md-extcommunity-list.md b/docs/configuration/policy/md-extcommunity-list.md deleted file mode 100644 index fdfe6210..00000000 --- a/docs/configuration/policy/md-extcommunity-list.md +++ /dev/null @@ -1,32 +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. -```
\ No newline at end of file diff --git a/docs/configuration/policy/md-index.md b/docs/configuration/policy/md-index.md deleted file mode 100644 index 29c9ca87..00000000 --- a/docs/configuration/policy/md-index.md +++ /dev/null @@ -1,47 +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} -:includehidden: true -:maxdepth: 1 - -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} -:includehidden: true -:maxdepth: 1 - -examples -``` diff --git a/docs/configuration/policy/md-large-community-list.md b/docs/configuration/policy/md-large-community-list.md deleted file mode 100644 index 23b9a85a..00000000 --- a/docs/configuration/policy/md-large-community-list.md +++ /dev/null @@ -1,29 +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. -```
\ No newline at end of file diff --git a/docs/configuration/policy/md-local-route.md b/docs/configuration/policy/md-local-route.md deleted file mode 100644 index 5b2297f7..00000000 --- a/docs/configuration/policy/md-local-route.md +++ /dev/null @@ -1,99 +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/md-prefix-list.md b/docs/configuration/policy/md-prefix-list.md deleted file mode 100644 index 6a3e66e6..00000000 --- a/docs/configuration/policy/md-prefix-list.md +++ /dev/null @@ -1,145 +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/md-route.md b/docs/configuration/policy/md-route.md deleted file mode 100644 index 6db28683..00000000 --- a/docs/configuration/policy/md-route.md +++ /dev/null @@ -1,416 +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. -::: -```
\ No newline at end of file diff --git a/docs/configuration/protocols/md-index.md b/docs/configuration/protocols/md-index.md deleted file mode 100644 index 5f190ce1..00000000 --- a/docs/configuration/protocols/md-index.md +++ /dev/null @@ -1,25 +0,0 @@ -# Protocols - -```{toctree} -:includehidden: true -:maxdepth: 1 - -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/service/md-index.md b/docs/configuration/service/md-index.md deleted file mode 100644 index 4018c5be..00000000 --- a/docs/configuration/service/md-index.md +++ /dev/null @@ -1,29 +0,0 @@ -# Service - -```{toctree} -:includehidden: true -:maxdepth: 1 - -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/md-salt-minion.md b/docs/configuration/service/md-salt-minion.md deleted file mode 100644 index d7aa7664..00000000 --- a/docs/configuration/service/md-salt-minion.md +++ /dev/null @@ -1,50 +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/ diff --git a/docs/configuration/service/md-snmp.md b/docs/configuration/service/md-snmp.md deleted file mode 100644 index 6a5a66e5..00000000 --- a/docs/configuration/service/md-snmp.md +++ /dev/null @@ -1,255 +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.png -:alt: Principle of SNMP Communication -:scale: 20 % - -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 - -```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 - -```none -set service snmp listen-address 192.0.2.1 -set service snmp location 'VyOS Datacenter' -set service snmp v3 engineid '000000000000000000000002' -set service snmp v3 group default mode 'ro' -set service snmp v3 group default view 'default' -set service snmp v3 user vyos auth plaintext-password 'vyos12345678' -set service snmp v3 user vyos auth type 'sha' -set service snmp v3 user vyos group 'default' -set service snmp v3 user vyos privacy plaintext-password 'vyos12345678' -set service snmp v3 user vyos privacy type 'aes' -set service snmp v3 view default oid 1 -``` - -After commit the plaintext passwords will be hashed and stored in your -configuration. The resulting CLI config will look like: - -```none -vyos@vyos# show service snmp - listen-address 192.0.2.1 { - } - location "VyOS Datacenter" - v3 { - engineid 000000000000000000000002 - group default { - mode ro - view default - } - user vyos { - auth { - encrypted-password 4e52fe55fd011c9c51ae2c65f4b78ca93dcafdfe - type sha - } - group default - privacy { - encrypted-password 4e52fe55fd011c9c51ae2c65f4b78ca93dcafdfe - type aes - } - } - view default { - oid 1 { - } - } - } -``` - -You can test the SNMPv3 functionality from any linux based system, just run the -following command: `snmpwalk -v 3 -u vyos -a SHA -A vyos12345678 -x AES --X vyos12345678 -l authPriv 192.0.2.1 .1` - -## VyOS MIBs - -All SNMP MIBs are located in each image of VyOS here: `/usr/share/snmp/mibs/` - -You are be able to download the files using SCP, once the SSH service -has been activated like so - -```none -scp -r vyos@your_router:/usr/share/snmp/mibs /your_folder/mibs -``` - -## SNMP Extensions - -To extend SNMP agent functionality, custom scripts can be executed every time -the agent is being called. This can be achieved by using -`arbitrary extensioncommands`. The first step is to create a functional -script of course, then upload it to your VyOS instance via the command -`scp your_script.sh vyos@your_router:/config/user-data`. -Once the script is uploaded, it needs to be configured via the command below. - -```none -set service snmp script-extensions extension-name my-extension script your_script.sh -commit -``` - -The OID `.1.3.6.1.4.1.8072.1.3.2.3.1.1.4.116.101.115.116`, once called, will -contain the output of the extension. - -```none -root@vyos:/home/vyos# snmpwalk -v2c -c public 127.0.0.1 nsExtendOutput1 -NET-SNMP-EXTEND-MIB::nsExtendOutput1Line."my-extension" = STRING: hello -NET-SNMP-EXTEND-MIB::nsExtendOutputFull."my-extension" = STRING: hello -NET-SNMP-EXTEND-MIB::nsExtendOutNumLines."my-extension" = INTEGER: 1 -NET-SNMP-EXTEND-MIB::nsExtendResult."my-extension" = INTEGER: 0 -``` - -## SolarWinds - -If you happen to use SolarWinds Orion as NMS you can also use the Device -Templates Management. A template for VyOS can be easily imported. - -Create a file named `VyOS-1.3.6.1.4.1.44641.ConfigMgmt-Commands` using the -following content: - -```none -<Configuration-Management Device="VyOS" SystemOID="1.3.6.1.4.1.44641"> - <Commands> - <Command Name="Reset" Value="set terminal width 0${CRLF}set terminal length 0"/> - <Command Name="Reboot" Value="reboot${CRLF}Yes"/> - <Command Name="EnterConfigMode" Value="configure"/> - <Command Name="ExitConfigMode" Value="commit${CRLF}exit"/> - <Command Name="DownloadConfig" Value="show configuration commands"/> - <Command Name="SaveConfig" Value="commit${CRLF}save"/> - <Command Name="Version" Value="show version"/> - <Command Name="MenuBased" Value="False"/> - <Command Name="VirtualPrompt" Value=":~"/> - </Commands> -</Configuration-Management> -``` - -[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 diff --git a/docs/configuration/system/md-index.md b/docs/configuration/system/md-index.md deleted file mode 100644 index e0b8a5a1..00000000 --- a/docs/configuration/system/md-index.md +++ /dev/null @@ -1,34 +0,0 @@ -# System - -```{toctree} -:includehidden: true -:maxdepth: 1 - -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} -:includehidden: true -:maxdepth: 1 - -default-route -``` diff --git a/docs/configuration/system/md-sysctl.md b/docs/configuration/system/md-sysctl.md deleted file mode 100644 index 90434fb2..00000000 --- a/docs/configuration/system/md-sysctl.md +++ /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\> -```
\ No newline at end of file diff --git a/docs/configuration/system/md-updates.md b/docs/configuration/system/md-updates.md deleted file mode 100644 index 8734788f..00000000 --- a/docs/configuration/system/md-updates.md +++ /dev/null @@ -1,35 +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 - -```none -set system update-check auto-check -set system update-check url 'https://raw.githubusercontent.com/vyos/vyos-rolling-nightly-builds/main/version.json' -``` - -Check: - -```none -vyos@r4:~$ show system updates -Current version: 1.5-rolling-202312220023 - -Update available: 1.5-rolling-202312250024 -Update URL: https://github.com/vyos/vyos-rolling-nightly-builds/releases/download/1.5-rolling-202312250024/1.5-rolling-202312250024-amd64.iso -vyos@r4:~$ - -vyos@r4:~$ add system image latest -``` diff --git a/docs/configuration/vpn/ipsec/md-index.md b/docs/configuration/vpn/ipsec/md-index.md deleted file mode 100644 index cc40b6f8..00000000 --- a/docs/configuration/vpn/ipsec/md-index.md +++ /dev/null @@ -1,11 +0,0 @@ -# IPsec - -```{toctree} -:includehidden: true -:maxdepth: 1 - -ipsec_general -site2site_ipsec -remoteaccess_ipsec -troubleshooting_ipsec -``` diff --git a/docs/configuration/vpn/ipsec/md-remoteaccess_ipsec.md b/docs/configuration/vpn/ipsec/md-remoteaccess_ipsec.md deleted file mode 100644 index de553aec..00000000 --- a/docs/configuration/vpn/ipsec/md-remoteaccess_ipsec.md +++ /dev/null @@ -1,181 +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. - -```none -vyos@vpn.vyos.net# run generate pki ca install ca_root -Enter private key type: [rsa, dsa, ec] (Default: rsa) -Enter private key bits: (Default: 2048) -Enter country code: (Default: GB) -Enter state: (Default: Some-State) -Enter locality: (Default: Some-City) -Enter organization name: (Default: VyOS) -Enter common name: (Default: vyos.io) -Enter how many days certificate will be valid: (Default: 1825) -Note: If you plan to use the generated key on this router, do not encrypt the private key. -Do you want to encrypt the private key with a passphrase? [y/N] N -2 value(s) installed. Use "compare" to see the pending changes, and "commit" to apply. -[edit] - - -vyos@vpn.vyos.net# comp -[pki ca] -+ ca_root { -+ certificate "MIIDnTCCAoWgAwI…." -+ private { -+ key "MIIEvAIBADANBgkqhkiG9….” - -vyos@vpn.vyos.net# run generate pki certificate sign ca_root install server_cert -Do you already have a certificate request? [y/N] N -Enter private key type: [rsa, dsa, ec] (Default: rsa) -Enter private key bits: (Default: 2048) -Enter country code: (Default: GB) -Enter state: (Default: Some-State) -Enter locality: (Default: Some-City) -Enter organization name: (Default: VyOS) -Enter common name: (Default: vyos.io) vpn.vyos.net -Do you want to configure Subject Alternative Names? [y/N] N -Enter how many days certificate will be valid: (Default: 365) -Enter certificate type: (client, server) (Default: server) -Note: If you plan to use the generated key on this router, do not encrypt the private key. -Do you want to encrypt the private key with a passphrase? [y/N] N -2 value(s) installed. Use "compare" to see the pending changes, and "commit" to apply. - -vyos@vpn.vyos.net# comp -[pki certificate] -+ server_cert { -+ certificate "MIIDuzCCAqOgAwIBAgIUaSrCPWx………" -+ private { -+ key "MIIEvQIBADANBgkqhkiG9w0BAQEFAASCBK….." -+ } -+ } -``` - -Once the command is completed, it will add the certificate to the configuration -session, to the pki subtree. You can then review the proposed changes and -commit them. - -## Setting up IPSec: -After the PKI certs are all set up we can start configuring our IPSec/IKE -proposals used for key-exchange end data encryption. The used encryption ciphers -and integrity algorithms vary from operating system to operating system. The -ones used in this example are validated to work on Windows 10. - -```none -set vpn ipsec esp-group ESP-RW lifetime '3600' -set vpn ipsec esp-group ESP-RW pfs 'disable' -set vpn ipsec esp-group ESP-RW proposal 10 encryption 'aes128gcm128' -set vpn ipsec esp-group ESP-RW proposal 10 hash 'sha256' - -set vpn ipsec ike-group IKE-RW key-exchange 'ikev2' -set vpn ipsec ike-group IKE-RW lifetime '7200' -set vpn ipsec ike-group IKE-RW proposal 10 dh-group '14' -set vpn ipsec ike-group IKE-RW proposal 10 encryption 'aes128gcm128' -set vpn ipsec ike-group IKE-RW proposal 10 hash 'sha256' -``` - -Every connection/remote-access pool we configure also needs a pool where we -can draw our client IP addresses from. We provide one IPv4 and IPv6 pool. -Authorized clients will receive an IPv4 address from the configured IPv4 prefix -and an IPv6 address from the IPv6 prefix. We can also send some DNS nameservers -down to our clients used on their connection. - -```none -set vpn ipsec remote-access pool ra-rw-ipv4 name-server '192.0.2.1' -set vpn ipsec remote-access pool ra-rw-ipv4 prefix '192.0.2.128/25' - -set vpn ipsec remote-access pool ra-rw-ipv6 name-server '2001:db8:1000::1' -set vpn ipsec remote-access pool ra-rw-ipv6 prefix '2001:db8:2000::/64' -``` - -## Setting up tunnel: - -```none -set vpn ipsec remote-access connection rw authentication local-id '192.0.2.1' -set vpn ipsec remote-access connection rw authentication server-mode 'x509' -set vpn ipsec remote-access connection rw authentication x509 ca-certificate 'ca_root' -set vpn ipsec remote-access connection rw authentication x509 certificate 'server_cert' -set vpn ipsec remote-access connection rw esp-group 'ESP-RW' -set vpn ipsec remote-access connection rw ike-group 'IKE-RW' -set vpn ipsec remote-access connection rw local-address '192.0.2.1' -set vpn ipsec remote-access connection rw pool 'ra-rw-ipv4' -set vpn ipsec remote-access connection rw pool 'ra-rw-ipv6' -``` - -VyOS also supports two different modes of authentication, local and RADIUS. -To create a new local user named "vyos" with a password of "vyos" use the -following commands. - -```none -set vpn ipsec remote-access connection rw authentication client-mode 'eap-mschapv2' -set vpn ipsec remote-access connection rw authentication local-users username vyos password 'vyos' -``` - -Some client operating systems like to see the servers certificate. The following -option causes the server to voluntarily send its certificate, even if it wasn't -requested. - -```none -set vpn ipsec remote-access connection rw authentication always-send-cert -``` - -## Client Configuration -Most operating systems include native client support for IPsec IKEv2 VPN -connections, and others typically have an app or add-on package which adds the -capability. -This section covers IPsec IKEv2 client configuration for Windows 10. - -VyOS provides a command to generate a connection profile used by Windows clients -that will connect to the "rw" connection on our VyOS server. - -:::{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. -::: - -```none -vyos@vpn.vyos.net:~$ generate ipsec profile windows-remote-access rw remote vpn.vyos.net - - -==== <snip> ==== -Add-VpnConnection -Name "VyOS IKEv2 VPN" -ServerAddress "vpn.vyos.net" -TunnelType "Ikev2" - -Set-VpnConnectionIPsecConfiguration -ConnectionName "VyOS IKEv2 VPN" -AuthenticationTransformConstants GCMAES128 -CipherTransformConstants -GCMAES128 -EncryptionMethod GCMAES128 -IntegrityCheckMethod SHA256128 -PfsGroup None -DHGroup "Group14" -PassThru -Force -==== </snip> ==== -``` - -Add the commands from Snippet in the Windows side via PowerShell. -Also import the root CA cert to the Windows “Trusted Root Certification -Authorities” and establish the connection. - -## Verification: - -```none -vyos@vpn.vyos.net:~$ show vpn ipsec remote-access summary - Connection ID Username Protocol State Uptime Tunnel IP Remote Host Remote ID IKE Proposal IPSec Proposal ---------------- ---------- ---------- ------- -------- ----------- ------------- ----------- ------------------------------------------ ------------------ - 5 vyos IKEv2 UP 37s 192.0.2.129 10.0.0.2 10.0.0.2 AES_GCM_16-128/PRF_HMAC_SHA2_256/MODP_2048 ESP:AES_GCM_16-128 -``` diff --git a/docs/configuration/vpn/ipsec/md-troubleshooting_ipsec.md b/docs/configuration/vpn/ipsec/md-troubleshooting_ipsec.md deleted file mode 100644 index 2dfd3fec..00000000 --- a/docs/configuration/vpn/ipsec/md-troubleshooting_ipsec.md +++ /dev/null @@ -1,302 +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. - -```none -vyos@vyos:~$ show vpn ike sa - -Peer ID / IP Local ID / IP ------------- ------------- -192.168.1.2 192.168.1.2 192.168.0.1 192.168.0.1 - - State IKEVer Encrypt Hash D-H Group NAT-T A-Time L-Time - ----- ------ ------- ---- --------- ----- ------ ------ - up IKEv2 AES_CBC_128 HMAC_SHA1_96 MODP_2048 no 162 27023 -``` - -This command shows the next information: -: - IKE SA status. - - Selected IKE version. - - Selected Encryption, Hash and Diffie-Hellman Group. - - NAT-T. - - ID and IP of both peers. - - A-Time: established time, L-Time: time for next rekeying. - -## IPsec SA (CHILD SA) Status -The next commands show IPsec SAs' statuses. - -```none -vyos@vyos:~$ show vpn ipsec sa -Connection State Uptime Bytes In/Out Packets In/Out Remote address Remote ID Proposal -------------- ------- -------- -------------- ---------------- ---------------- ----------- ---------------------------------- -PEER-tunnel-1 up 16m30s 168B/168B 2/2 192.168.1.2 192.168.1.2 AES_CBC_128/HMAC_SHA1_96/MODP_2048 -``` - -```none -vyos@vyos:~$ show vpn ipsec sa detail -PEER: #1, ESTABLISHED, IKEv2, 101275ac719d5a1b_i* 68ea4ec3bed3bf0c_r - local '192.168.0.1' @ 192.168.0.1[4500] - remote '192.168.1.2' @ 192.168.1.2[4500] - AES_CBC-128/HMAC_SHA1_96/PRF_HMAC_SHA1/MODP_2048 - established 4054s ago, rekeying in 23131s - PEER-tunnel-1: #2, reqid 1, INSTALLED, TUNNEL, ESP:AES_CBC-128/HMAC_SHA1_96/MODP_2048 - installed 1065s ago, rekeying in 1998s, expires in 2535s - in c5821882, 168 bytes, 2 packets, 81s ago - out c433406a, 168 bytes, 2 packets, 81s ago - local 10.0.0.0/24 - remote 10.0.1.0/24 -``` - -These commands show the next information: -: - IPsec SA status. - - Uptime and time for the next rekeing. - - Amount of transferred data. - - Remote and local ID and IP. - - Selected Encryption, Hash and Diffie-Hellman Group. - - Mode (tunnel or transport). - - Remote and local prefixes which are use for policy. - -There is a possibility to view the summarized information of SAs' status - -```none -vyos@vyos:~$ show vpn ipsec connections -Connection State Type Remote address Local TS Remote TS Local id Remote id Proposal -------------- ------- ------ ---------------- ----------- ----------- ----------- ----------- ---------------------------------- -PEER up IKEv2 192.168.1.2 - - 192.168.0.1 192.168.1.2 AES_CBC/128/HMAC_SHA1_96/MODP_2048 -PEER-tunnel-1 up IPsec 192.168.1.2 10.0.0.0/24 10.0.1.0/24 192.168.0.1 192.168.1.2 AES_CBC/128/HMAC_SHA1_96/MODP_2048 -``` - -## Viewing Logs for Debugging -If IKE SAs or IPsec SAs are down, need to debug IPsec connectivity -using logs `show log ipsec` - -The next example of the successful IPsec connection initialization. - -```none -vyos@vyos:~$ show log ipsec -Jun 20 14:29:47 charon[2428]: 02[NET] <PEER|1> received packet: from 192.168.1.2[500] to 192.168.0.1[500] (472 bytes) -Jun 20 14:29:47 charon[2428]: 02[ENC] <PEER|1> parsed IKE_SA_INIT response 0 [ SA KE No N(NATD_S_IP) N(NATD_D_IP) N(FRAG_SUP) N(HASH_ALG) N(CHDLESS_SUP) N(MULT_AUTH) ] -Jun 20 14:29:47 charon-systemd[2428]: received packet: from 192.168.1.2[500] to 192.168.0.1[500] (472 bytes) -Jun 20 14:29:47 charon[2428]: 02[CFG] <PEER|1> selected proposal: IKE:AES_CBC_128/HMAC_SHA1_96/PRF_HMAC_SHA1/MODP_2048 -Jun 20 14:29:47 charon-systemd[2428]: parsed IKE_SA_INIT response 0 [ SA KE No N(NATD_S_IP) N(NATD_D_IP) N(FRAG_SUP) N(HASH_ALG) N(CHDLESS_SUP) N(MULT_AUTH) ] -Jun 20 14:29:47 charon-systemd[2428]: selected proposal: IKE:AES_CBC_128/HMAC_SHA1_96/PRF_HMAC_SHA1/MODP_2048 -Jun 20 14:29:47 charon[2428]: 02[IKE] <PEER|1> authentication of '192.168.0.1' (myself) with pre-shared key -Jun 20 14:29:47 charon-systemd[2428]: authentication of '192.168.0.1' (myself) with pre-shared key -Jun 20 14:29:47 charon[2428]: 02[IKE] <PEER|1> establishing CHILD_SA PEER-tunnel-1{1} -Jun 20 14:29:47 charon-systemd[2428]: establishing CHILD_SA PEER-tunnel-1{1} -Jun 20 14:29:47 charon[2428]: 02[ENC] <PEER|1> generating IKE_AUTH request 1 [ IDi N(INIT_CONTACT) IDr AUTH SA TSi TSr N(MOBIKE_SUP) N(NO_ADD_ADDR) N(MULT_AUTH) N(EAP_ONLY) N(MSG_ID_SYN_SUP) ] -Jun 20 14:29:47 charon-systemd[2428]: generating IKE_AUTH request 1 [ IDi N(INIT_CONTACT) IDr AUTH SA TSi TSr N(MOBIKE_SUP) N(NO_ADD_ADDR) N(MULT_AUTH) N(EAP_ONLY) N(MSG_ID_SYN_SUP) ] -Jun 20 14:29:47 charon[2428]: 02[NET] <PEER|1> sending packet: from 192.168.0.1[4500] to 192.168.1.2[4500] (268 bytes) -Jun 20 14:29:47 charon-systemd[2428]: sending packet: from 192.168.0.1[4500] to 192.168.1.2[4500] (268 bytes) -Jun 20 14:29:47 charon[2428]: 13[NET] <PEER|1> received packet: from 192.168.1.2[4500] to 192.168.0.1[4500] (220 bytes) -Jun 20 14:29:47 charon[2428]: 13[ENC] <PEER|1> parsed IKE_AUTH response 1 [ IDr AUTH SA TSi TSr N(MOBIKE_SUP) N(NO_ADD_ADDR) ] -Jun 20 14:29:47 charon-systemd[2428]: received packet: from 192.168.1.2[4500] to 192.168.0.1[4500] (220 bytes) -Jun 20 14:29:47 charon[2428]: 13[IKE] <PEER|1> authentication of '192.168.1.2' with pre-shared key successful -Jun 20 14:29:47 charon-systemd[2428]: parsed IKE_AUTH response 1 [ IDr AUTH SA TSi TSr N(MOBIKE_SUP) N(NO_ADD_ADDR) ] -Jun 20 14:29:47 charon[2428]: 13[IKE] <PEER|1> peer supports MOBIKE -Jun 20 14:29:47 charon-systemd[2428]: authentication of '192.168.1.2' with pre-shared key successful -Jun 20 14:29:47 charon[2428]: 13[IKE] <PEER|1> IKE_SA PEER[1] established between 192.168.0.1[192.168.0.1]...192.168.1.2[192.168.1.2] -Jun 20 14:29:47 charon-systemd[2428]: peer supports MOBIKE -Jun 20 14:29:47 charon[2428]: 13[IKE] <PEER|1> scheduling rekeying in 27703s -Jun 20 14:29:47 charon-systemd[2428]: IKE_SA PEER[1] established between 192.168.0.1[192.168.0.1]...192.168.1.2[192.168.1.2] -Jun 20 14:29:47 charon[2428]: 13[IKE] <PEER|1> maximum IKE_SA lifetime 30583s -Jun 20 14:29:47 charon-systemd[2428]: scheduling rekeying in 27703s -Jun 20 14:29:47 charon[2428]: 13[CFG] <PEER|1> selected proposal: ESP:AES_CBC_128/HMAC_SHA1_96/NO_EXT_SEQ -Jun 20 14:29:47 charon-systemd[2428]: maximum IKE_SA lifetime 30583s -Jun 20 14:29:47 charon-systemd[2428]: selected proposal: ESP:AES_CBC_128/HMAC_SHA1_96/NO_EXT_SEQ -Jun 20 14:29:47 charon[2428]: 13[IKE] <PEER|1> CHILD_SA PEER-tunnel-1{1} established with SPIs cb94fb3f_i ca99c8a9_o and TS 10.0.0.0/24 === 10.0.1.0/24 -Jun 20 14:29:47 charon-systemd[2428]: CHILD_SA PEER-tunnel-1{1} established with SPIs cb94fb3f_i ca99c8a9_o and TS 10.0.0.0/24 === 10.0.1.0/24 -``` - -## Troubleshooting Examples - -### IKE PROPOSAL are Different -In this situation, IKE SAs can be down or not active. - -```none -vyos@vyos:~$ show vpn ike sa -``` - -The problem is in IKE phase (Phase 1). The next step is checking debug logs. - -Responder Side: - -```none -Jun 23 07:36:33 charon[2440]: 01[CFG] <1> received proposals: IKE:AES_CBC_256/HMAC_SHA1_96/PRF_HMAC_SHA1/MODP_2048 -Jun 23 07:36:33 charon-systemd[2440]: received proposals: IKE:AES_CBC_256/HMAC_SHA1_96/PRF_HMAC_SHA1/MODP_2048 -Jun 23 07:36:33 charon[2440]: 01[CFG] <1> configured proposals: IKE:AES_CBC_128/HMAC_SHA1_96/PRF_HMAC_SHA1/MODP_2048 -Jun 23 07:36:33 charon-systemd[2440]: configured proposals: IKE:AES_CBC_128/HMAC_SHA1_96/PRF_HMAC_SHA1/MODP_2048 -Jun 23 07:36:33 charon[2440]: 01[IKE] <1> received proposals unacceptable -Jun 23 07:36:33 charon-systemd[2440]: received proposals unacceptable -Jun 23 07:36:33 charon[2440]: 01[ENC] <1> generating IKE_SA_INIT response 0 [ N(NO_PROP) ] -``` - -Initiator side: - -```none -Jun 23 07:36:32 charon-systemd[2444]: parsed IKE_SA_INIT response 0 [ N(NO_PROP) ] -Jun 23 07:36:32 charon[2444]: 14[IKE] <PEER|1> received NO_PROPOSAL_CHOSEN notify error -Jun 23 07:36:32 charon-systemd[2444]: received NO_PROPOSAL_CHOSEN notify error -``` - -The notification **NO_PROPOSAL_CHOSEN** means that the proposal mismatch. -On the Responder side there is concrete information where is mismatch. -Encryption **AES_CBC_128** is configured in IKE policy on the responder -but **AES_CBC_256** is configured on the initiator side. - -### PSK Secret Mismatch -In this situation, IKE SAs can be down or not active. - -```none -vyos@vyos:~$ show vpn ike sa -``` - -The problem is in IKE phase (Phase 1). The next step is checking debug logs. - -Responder: - -```none -Jun 23 08:07:26 charon-systemd[2440]: tried 1 shared key for '192.168.1.2' - '192.168.0.1', but MAC mismatched -Jun 23 08:07:26 charon[2440]: 13[ENC] <PEER|3> generating IKE_AUTH response 1 [ N(AUTH_FAILED) ] -``` - -Initiator side: - -```none -Jun 23 08:07:24 charon[2436]: 12[ENC] <PEER|1> parsed IKE_AUTH response 1 [ N(AUTH_FAILED) ] -Jun 23 08:07:24 charon-systemd[2436]: parsed IKE_AUTH response 1 [ N(AUTH_FAILED) ] -Jun 23 08:07:24 charon[2436]: 12[IKE] <PEER|1> received AUTHENTICATION_FAILED notify error -Jun 23 08:07:24 charon-systemd[2436]: received AUTHENTICATION_FAILED notify error -``` - -The notification **AUTHENTICATION_FAILED** means that the authentication -is failed. There is a reason to check PSK on both side. - -### ESP Proposal Mismatch -The output of **show** commands shows us that IKE SA is established but -IPSec SA is not. - -```none -vyos@vyos:~$ show vpn ike sa -Peer ID / IP Local ID / IP ------------- ------------- -192.168.1.2 192.168.1.2 192.168.0.1 192.168.0.1 - - State IKEVer Encrypt Hash D-H Group NAT-T A-Time L-Time - ----- ------ ------- ---- --------- ----- ------ ------ - up IKEv2 AES_CBC_128 HMAC_SHA1_96 MODP_2048 no 158 26817 -``` - -```none -vyos@vyos:~$ show vpn ipsec sa -Connection State Uptime Bytes In/Out Packets In/Out Remote address Remote ID Proposal ------------- ------- -------- -------------- ---------------- ---------------- ----------- ---------- -``` - -The next step is checking debug logs. - -Initiator side: - -```none -Jun 23 08:16:10 charon[3789]: 13[NET] <PEER|1> received packet: from 192.168.1.2[500] to 192.168.0.1[500] (472 bytes) -Jun 23 08:16:10 charon[3789]: 13[ENC] <PEER|1> parsed IKE_SA_INIT response 0 [ SA KE No N(NATD_S_IP) N(NATD_D_IP) N(FRAG_SUP) N(HASH_ALG) N(CHDLESS_SUP) N(MULT_AUTH) ] -Jun 23 08:16:10 charon-systemd[3789]: received packet: from 192.168.1.2[500] to 192.168.0.1[500] (472 bytes) -Jun 23 08:16:10 charon[3789]: 13[CFG] <PEER|1> selected proposal: IKE:AES_CBC_128/HMAC_SHA1_96/PRF_HMAC_SHA1/MODP_2048 -Jun 23 08:16:10 charon-systemd[3789]: parsed IKE_SA_INIT response 0 [ SA KE No N(NATD_S_IP) N(NATD_D_IP) N(FRAG_SUP) N(HASH_ALG) N(CHDLESS_SUP) N(MULT_AUTH) ] -Jun 23 08:16:10 charon-systemd[3789]: selected proposal: IKE:AES_CBC_128/HMAC_SHA1_96/PRF_HMAC_SHA1/MODP_2048 -Jun 23 08:16:10 charon[3789]: 13[IKE] <PEER|1> authentication of '192.168.0.1' (myself) with pre-shared key -Jun 23 08:16:10 charon-systemd[3789]: authentication of '192.168.0.1' (myself) with pre-shared key -Jun 23 08:16:10 charon[3789]: 13[IKE] <PEER|1> establishing CHILD_SA PEER-tunnel-1{1} -Jun 23 08:16:10 charon-systemd[3789]: establishing CHILD_SA PEER-tunnel-1{1} -Jun 23 08:16:10 charon[3789]: 13[ENC] <PEER|1> generating IKE_AUTH request 1 [ IDi N(INIT_CONTACT) IDr AUTH SA TSi TSr N(MOBIKE_SUP) N(NO_ADD_ADDR) N(MULT_AUTH) N(EAP_ONLY) N(MSG_ID_SYN_SUP) ] -Jun 23 08:16:10 charon-systemd[3789]: generating IKE_AUTH request 1 [ IDi N(INIT_CONTACT) IDr AUTH SA TSi TSr N(MOBIKE_SUP) N(NO_ADD_ADDR) N(MULT_AUTH) N(EAP_ONLY) N(MSG_ID_SYN_SUP) ] -Jun 23 08:16:10 charon[3789]: 13[NET] <PEER|1> sending packet: from 192.168.0.1[4500] to 192.168.1.2[4500] (268 bytes) -Jun 23 08:16:10 charon-systemd[3789]: sending packet: from 192.168.0.1[4500] to 192.168.1.2[4500] (268 bytes) -Jun 23 08:16:10 charon[3789]: 09[NET] <PEER|1> received packet: from 192.168.1.2[4500] to 192.168.0.1[4500] (140 bytes) -Jun 23 08:16:10 charon-systemd[3789]: received packet: from 192.168.1.2[4500] to 192.168.0.1[4500] (140 bytes) -Jun 23 08:16:10 charon[3789]: 09[ENC] <PEER|1> parsed IKE_AUTH response 1 [ IDr AUTH N(MOBIKE_SUP) N(NO_ADD_ADDR) N(NO_PROP) ] -Jun 23 08:16:10 charon-systemd[3789]: parsed IKE_AUTH response 1 [ IDr AUTH N(MOBIKE_SUP) N(NO_ADD_ADDR) N(NO_PROP) ] -Jun 23 08:16:10 charon[3789]: 09[IKE] <PEER|1> authentication of '192.168.1.2' with pre-shared key successful -Jun 23 08:16:10 charon-systemd[3789]: authentication of '192.168.1.2' with pre-shared key successful -Jun 23 08:16:10 charon[3789]: 09[IKE] <PEER|1> peer supports MOBIKE -Jun 23 08:16:10 charon-systemd[3789]: peer supports MOBIKE -Jun 23 08:16:10 charon[3789]: 09[IKE] <PEER|1> IKE_SA PEER[1] established between 192.168.0.1[192.168.0.1]...192.168.1.2[192.168.1.2] -Jun 23 08:16:10 charon-systemd[3789]: IKE_SA PEER[1] established between 192.168.0.1[192.168.0.1]...192.168.1.2[192.168.1.2] -Jun 23 08:16:10 charon[3789]: 09[IKE] <PEER|1> scheduling rekeying in 26975s -Jun 23 08:16:10 charon-systemd[3789]: scheduling rekeying in 26975s -Jun 23 08:16:10 charon[3789]: 09[IKE] <PEER|1> maximum IKE_SA lifetime 29855s -Jun 23 08:16:10 charon-systemd[3789]: maximum IKE_SA lifetime 29855s -Jun 23 08:16:10 charon[3789]: 09[IKE] <PEER|1> received NO_PROPOSAL_CHOSEN notify, no CHILD_SA built -Jun 23 08:16:10 charon-systemd[3789]: received NO_PROPOSAL_CHOSEN notify, no CHILD_SA built -Jun 23 08:16:10 charon[3789]: 09[IKE] <PEER|1> failed to establish CHILD_SA, keeping IKE_SA -Jun 23 08:16:10 charon-systemd[3789]: failed to establish CHILD_SA, keeping IKE_SA -``` - -There are messages: **NO_PROPOSAL_CHOSEN** and -**failed to establish CHILD_SA** which refers that the problem is in -the IPsec(ESP) proposal mismatch. - -The reason of this problem is showed on the responder side. - -```none -Jun 23 08:16:12 charon[2440]: 01[CFG] <PEER|5> received proposals: ESP:AES_CBC_256/HMAC_SHA1_96/NO_EXT_SEQ -Jun 23 08:16:12 charon-systemd[2440]: received proposals: ESP:AES_CBC_256/HMAC_SHA1_96/NO_EXT_SEQ -Jun 23 08:16:12 charon[2440]: 01[CFG] <PEER|5> configured proposals: ESP:AES_CBC_128/HMAC_SHA1_96/MODP_2048/NO_EXT_SEQ -Jun 23 08:16:12 charon-systemd[2440]: configured proposals: ESP:AES_CBC_128/HMAC_SHA1_96/MODP_2048/NO_EXT_SEQ -Jun 23 08:16:12 charon[2440]: 01[IKE] <PEER|5> no acceptable proposal found -Jun 23 08:16:12 charon-systemd[2440]: no acceptable proposal found -Jun 23 08:16:12 charon[2440]: 01[IKE] <PEER|5> failed to establish CHILD_SA, keeping IKE_SA -``` - -Encryption **AES_CBC_128** is configured in IKE policy on the responder but **AES_CBC_256** -is configured on the initiator side. - -### Prefixes in Policies Mismatch -As in previous situation, IKE SA is in up state but IPsec SA is not up. -According to logs we can see **TS_UNACCEPTABLE** notification. It means -that prefixes (traffic selectors) mismatch on both sides - -Initiator: - -```none -Jun 23 14:13:17 charon[4996]: 11[IKE] <PEER|1> received TS_UNACCEPTABLE notify, no CHILD_SA built -Jun 23 14:13:17 charon-systemd[4996]: maximum IKE_SA lifetime 29437s -Jun 23 14:13:17 charon[4996]: 11[IKE] <PEER|1> failed to establish CHILD_SA, keeping IKE_SA -Jun 23 14:13:17 charon-systemd[4996]: received TS_UNACCEPTABLE notify, no CHILD_SA built -Jun 23 14:13:17 charon-systemd[4996]: failed to establish CHILD_SA, keeping IKE_SA -``` - -The reason of this problem is showed on the responder side. - -```none -Jun 23 14:13:19 charon[2440]: 01[IKE] <PEER|7> traffic selectors 10.0.2.0/24 === 10.0.0.0/24 unacceptable -Jun 23 14:13:19 charon-systemd[2440]: traffic selectors 10.0.2.0/24 === 10.0.0.0/24 unacceptable -Jun 23 14:13:19 charon[2440]: 01[IKE] <PEER|7> failed to establish CHILD_SA, keeping IKE_SA -Jun 23 14:13:19 charon-systemd[2440]: failed to establish CHILD_SA, keeping IKE_SA -Jun 23 14:13:19 charon[2440]: 01[ENC] <PEER|7> generating IKE_AUTH response 1 [ IDr AUTH N(MOBIKE_SUP) N(NO_ADD_ADDR) N(TS_UNACCEPT) ] -Jun 23 14:13:19 charon-systemd[2440]: generating IKE_AUTH response 1 [ IDr AUTH N(MOBIKE_SUP) N(NO_ADD_ADDR) N(TS_UNACCEPT) ] -``` - -Traffic selectors **10.0.2.0/24 === 10.0.0.0/24** are unacceptable on the -responder side. diff --git a/docs/configuration/vpn/md-index.md b/docs/configuration/vpn/md-index.md deleted file mode 100644 index 9b06e5df..00000000 --- a/docs/configuration/vpn/md-index.md +++ /dev/null @@ -1,14 +0,0 @@ -# VPN - -```{toctree} -:includehidden: true -:maxdepth: 1 - -ipsec/index -l2tp -openconnect -pptp -rsa-keys -sstp -dmvpn -``` diff --git a/docs/configuration/vpn/md-rsa-keys.md b/docs/configuration/vpn/md-rsa-keys.md deleted file mode 100644 index b224b514..00000000 --- a/docs/configuration/vpn/md-rsa-keys.md +++ /dev/null @@ -1,114 +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. - -```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] -``` - -Configuration commands will display. -Note the command with the public key -(set pki key-pair ipsec-LEFT public key 'MIIBIjANBgkqh...'). -Then do the same on the opposite router: - -```none -vyos@left# run generate pki key-pair install ipsec-RIGHT -``` - -Note the command with the public key -(set pki key-pair ipsec-RIGHT public key 'FAAOCAQ8AMII...'). - -The noted public keys should be entered on the opposite routers. - -On the LEFT: - -```none -set pki key-pair ipsec-RIGHT public key 'FAAOCAQ8AMII...' -``` - -On the RIGHT: - -```none -set pki key-pair ipsec-LEFT public key 'MIIBIjANBgkqh...' -``` - -Now you are ready to setup IPsec. The key points: -1. Since both routers do not know their effective public addresses, - we set the local-address of the peer to "any". -2. On the initiator, we set the peer address to its public address, - but on the responder we only set the id. -3. On the initiator, we need to set the remote-id option so that it - can identify IKE traffic from the responder correctly. -4. On the responder, we need to set the local id so that initiator - can know who's talking to it for the point #3 to work. - -On the LEFT (static address): - -```none -set vpn ipsec interface eth0 - -set vpn ipsec esp-group MyESPGroup proposal 1 encryption aes128 -set vpn ipsec esp-group MyESPGroup proposal 1 hash sha1 - -set vpn ipsec ike-group MyIKEGroup proposal 1 dh-group 2 -set vpn ipsec ike-group MyIKEGroup proposal 1 encryption aes128 -set vpn ipsec ike-group MyIKEGroup proposal 1 hash sha1 - -set vpn ipsec site-to-site peer @RIGHT authentication id LEFT -set vpn ipsec site-to-site peer @RIGHT authentication mode rsa -set vpn ipsec site-to-site peer @RIGHT authentication rsa local-key ipsec-LEFT -set vpn ipsec site-to-site peer @RIGHT authentication rsa remote-key ipsec-RIGHT -set vpn ipsec site-to-site peer @RIGHT authentication remote-id RIGHT -set vpn ipsec site-to-site peer @RIGHT default-esp-group MyESPGroup -set vpn ipsec site-to-site peer @RIGHT ike-group MyIKEGroup -set vpn ipsec site-to-site peer @RIGHT local-address 192.0.2.10 -set vpn ipsec site-to-site peer @RIGHT connection-type 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): - -```none -set vpn ipsec interface eth0 - -set vpn ipsec esp-group MyESPGroup proposal 1 encryption aes128 -set vpn ipsec esp-group MyESPGroup proposal 1 hash sha1 - -set vpn ipsec ike-group MyIKEGroup proposal 1 dh-group 2 -set vpn ipsec ike-group MyIKEGroup proposal 1 encryption aes128 -set vpn ipsec ike-group MyIKEGroup proposal 1 hash sha1 - -set vpn ipsec site-to-site peer 192.0.2.10 authentication id RIGHT -set vpn ipsec site-to-site peer 192.0.2.10 authentication mode rsa -set vpn ipsec site-to-site peer 192.0.2.10 authentication rsa local-key ipsec-RIGHT -set vpn ipsec site-to-site peer 192.0.2.10 authentication rsa remote-key ipsec-LEFT -set vpn ipsec site-to-site peer 192.0.2.10 authentication remote-id LEFT -set vpn ipsec site-to-site peer 192.0.2.10 connection-type initiate -set vpn ipsec site-to-site peer 192.0.2.10 default-esp-group MyESPGroup -set vpn ipsec site-to-site peer 192.0.2.10 ike-group MyIKEGroup -set vpn ipsec site-to-site peer 192.0.2.10 local-address any -set vpn ipsec site-to-site peer 192.0.2.10 tunnel 1 local prefix 192.168.99.2/32 # Additional loopback address on the local -set vpn ipsec site-to-site peer 192.0.2.10 tunnel 1 remote prefix 192.168.99.1/32 # Additional loopback address on the remote -``` - diff --git a/docs/contributing/md-cla.md b/docs/contributing/md-cla.md deleted file mode 100644 index 01323111..00000000 --- a/docs/contributing/md-cla.md +++ /dev/null @@ -1,45 +0,0 @@ ---- -lastproofread: '2025-12-05' ---- - -(cla)= - -# Contributor License Agreement - -Before we can accept your contributions to VyOS, you must sign a **Contributor -License Agreement (CLA)**. - -This is a standard open-source practice that protects both you and the project. - -The process is straightforward and fully automated: - -1. **Review the CLA document** - - Find the CLA text in our - [GitHub repository](https://github.com/vyos/vyos-cla-signatures/). - -2. **Submit a pull request** - - When you open a pull request, a CLA bot automatically checks whether all - commit authors have signed the CLA. - -3. **Follow the bot's instructions** - - If the CLA has not been signed, the bot leaves a comment with instructions. - Reply to that comment with the suggested text to sign the CLA. - -4. **Wait for confirmation** - - The CLA bot verifies your response and updates the pull request status. - Once all commit authors have signed, the bot confirms that the CLA - requirement is met and unlocks the pull request for merging. - -:::{note} -Each commit author must sign the CLA. - -If your pull request includes commits from multiple contributors, each one -must sign the CLA before the pull request can be accepted. -::: - -Once you sign the CLA, it remains valid for all your past and future -contributions to VyOS under the same GitHub identity. diff --git a/docs/contributing/md-debugging.md b/docs/contributing/md-debugging.md deleted file mode 100644 index d3b4b513..00000000 --- a/docs/contributing/md-debugging.md +++ /dev/null @@ -1,204 +0,0 @@ ---- -lastproofread: '2025-12-05' ---- - -(debugging)= - -# Debugging - -Two flags are available to help debug configuration scripts. Configuration -loading issues manifest during boot, so these flags are passed as kernel boot -parameters. - -## ISO image build - -If you have trouble compiling your own ISO image or debugging Jenkins issues, -follow the steps at {ref}`iso_build_issues`. - -## System Startup - -Debug system startup by examining the configuration file loading from -`/config/config.boot`. Extend the kernel command-line in the bootloader to -enable this. - -### Kernel - -- `vyos-debug` - Add this parameter to the Linux boot line to produce - timing results for script execution during commit. If you see an unexpected - delay during manual or boot commit, this parameter helps identify bottlenecks. - The internal flag is `VYOS_DEBUG`, found in [vyatta-cfg]. Output is directed - to `/var/log/vyatta/cfg-stdout.log`. -- `vyos-config-debug` - During development, coding errors can cause commit - failures on boot, potentially preventing CLI initialization. This kernel boot - parameter ensures access to the system as user `vyos` and logs a Python - stack trace to `/tmp/boot-config-trace`. The file is created only if the - configuration load fails. - -## Live System - -Several flags can be set to change VyOS behavior at runtime. Toggle these flags -using environment variables or by creating files. - -For each feature, create a file called `vyos.feature.debug` to enable it. -If a parameter is required, place it as the first line inside the file. - -Place the file in `/tmp` for one-time debugging (the file is removed on -reboot) or in `/config` to persist permanently. - -For example, `/tmp/vyos.ifconfig.debug` can be created to enable -interface debugging. - -You can also enable debugging using environment variables. -The environment variable name follows the convention `VYOS_FEATURE_DEBUG`. - -For example, `export VYOS_IFCONFIG_DEBUG=""` in your vbash has the same effect -as `touch /tmp/vyos.ifconfig.debug`. - -- `ifconfig` - Display all commands and their responses from the OS on - screen for inspection. -- `command` - Display all commands and their responses from the OS on screen - for inspection. -- `developer` - When a command fails, start a PDB post-mortem session instead - of showing a standard error message. This allows developers to debug issues - interactively. Because the debugger waits for input, it can prevent the router - from booting, so only enable this permanently on production systems if you are - ready for potential boot failures. -- `log` - Send all commands used by VyOS to a log file for inspection. This - is useful in rare cases when you need to see what the OS is doing, including - during boot. The default file is `/tmp/full-log`, but you can change it. - -:::{note} -To retrieve debug output on the command line, disable `vyos-configd` -in addition. You can do this one-time with -`sudo systemctl stop vyos-configd` -or permanently with `sudo systemctl disable vyos-configd`. -::: - -### FRR - -Recent versions use the `vyos.frr` framework. The Python class is located in -`vyos-1x:python/vyos/frr.py`. It includes an embedded debugger similar to the -one in `vyos.ifconfig`. - -Enable debugging by running: `touch /tmp/vyos.frr.debug` - -### Debug Python code with PDB - -Sometimes it is useful to debug Python code interactively on the live system -rather than in an IDE. You can do this using pdb. - -Assuming you want to debug a Python script called by an op-mode command, find -the script by looking up the op-mode definitions, then edit it on the live -system using vi: -`vi /usr/libexec/vyos/op_mode/show_xyz.py` - -Insert the following statement right before the section where you want to -investigate a problem (for example, a statement you see in a backtrace): -`import pdb; pdb.set_trace()` - -Optionally, surround this statement with an `if` condition that triggers only -for the conditions you are interested in. - -When you run `show xyz` and your condition triggers, you enter the Python -debugger: - -```none -> /usr/libexec/vyos/op_mode/show_nat_translations.py(109)process() --> rule_type = rule.get('type', '') -(Pdb) -``` - -You can type `help` to get an overview of the available commands, and -`help command` to get more information on each command. - -Common useful commands include: - -- examine variables using `pp(var)` -- continue execution using `cont` -- get a backtrace using `bt` - -### Config Migration Scripts - -Starting with VyOS 1.5, a new mechanism is used for config migration that -improves migration performance. New migrators use only the new format with a -`migration()` function. - -```python -from vyos.configtree import ConfigTree -base = ['vpn', 'ipsec'] -def migrate(config: ConfigTree) -> None: - if not config.exists(base): - # Nothing to do - return - # do your stuff here -``` - -New-style migration scripts can no longer run on their own. However, the new -migration subsystem handler includes a test kit: - -```none -vyos@vyos:~$ /usr/libexec/vyos/run-config-migration.py --help -usage: run-config-migration.py [-h] [--test-script TEST_SCRIPT] [--output-file OUTPUT_FILE] [--force] config_file - -positional arguments: - config_file configuration file to migrate - -options: - -h, --help show this help message and exit - --test-script TEST_SCRIPT - test named script - --output-file OUTPUT_FILE - write to named output file instead of config file - --force force run of all migration scripts -``` - -To test your migration, run: - -```none -vyos@vyos:~$ /usr/libexec/vyos/run-config-migration.py --test-script /opt/vyatta/etc/config-migrate/migrate/quagga/11-to-12 --output-file /tmp/foo /tmp/static-route-basic -vyos@vyos:~$ cat /tmp/foo -``` - -The file `/tmp/foo` contains the migrated configuration. - -### Configuration Error on System Boot - -Running the latest rolling releases sometimes exposes bugs due to edge cases -missed in design. File these bugs via [Phabricator](https://vyos.dev/), but you can help narrow -down the issue by following these steps: - -1. Log in to your VyOS system. -2. Enter configuration mode: `configure` -3. Reload your boot configuration: `load` - -You should see a Python backtrace that helps identify the issue. Attach it to -the [Phabricator](https://vyos.dev/) task. - -### Boot Timing - -During the migration and rewrite of functionality from Perl to Python, system -boot time increased significantly. You can analyze and graph boot time to see -detailed call sequences during startup. - -This uses the `systemd-bootchart` package, which is installed by default on -VyOS 1.3 (equuleus) and later. Configuration is versioned for comparable -results. Refer to [bootchart.conf] for the configuration file. - -To enable boot time graphing, add the following to the kernel command line: -`init=/usr/lib/systemd/systemd-bootchart` - -You can also make this permanent by editing `/boot/grub/grub.cfg`. - -## Priorities - -VyOS CLI depends heavily on priorities. Every CLI node has a corresponding -`node.def` file and possibly an attached script. Nodes can have priorities, -and on system bootup or any `commit` to the configuration, scripts execute -from lowest to highest priority. This provides deterministic behavior. - -To debug priority issues or see script execution order, use the -`/opt/vyatta/sbin/priority.pl` script, which lists the execution order of -scripts. - -[bootchart.conf]: https://github.com/vyos/vyos-build/blob/current/data/live-build-config/includes.chroot/etc/systemd/bootchart.conf -[vyatta-cfg]: https://github.com/vyos/vyatta-cfg diff --git a/docs/contributing/md-development.md b/docs/contributing/md-development.md deleted file mode 100644 index 4decbea3..00000000 --- a/docs/contributing/md-development.md +++ /dev/null @@ -1,543 +0,0 @@ ---- -lastproofread: '2025-12-12' ---- - -(development)= - -# Development - -Learn how to contribute to VyOS. - -(architecture-overview)= - -## Architecture overview - -VyOS source code is hosted on GitHub in the VyOS organization: -<https://github.com/vyos> - -VyOS is composed of multiple modules spread across different -repositories. Some modules contain forks of upstream -packages and are periodically synced. -VyOS consolidates most packages into the -[vyos-1x](https://github.com/vyos/vyos-1x) -repository while maintaining a consistent structure. -The base code is being rewritten -from Perl and Bash to Python using an XML-based CLI interface definition. - -VyOS ISO build scripts are hosted in the -[vyos-build](https://github.com/vyos/vyos-build) repository. See the -`vyos-build` repository -[README.md file](https://github.com/vyos/vyos-build/blob/current/README.md) -for more information on building VyOS ISO images. - -## Contributing code - -:::{warning} -You must sign the {doc}`Contributor License Agreement<cla>` -for your contributions to be accepted. -::: - -VyOS is open-source and welcomes patches. -All submissions must adhere to these guidelines: - -- Each commit addresses a single issue or feature. -- Each commit message references a [Phabricator](https://vyos.dev/) task ID - (for example, `T1234`). -- Each commit is associated with a username and email address - to identify the author (see [Configure your Git identity](configure-your-git-identity)). -- Only submit bugfixes in packages other than <https://github.com/vyos/vyos-1x>. -- Commits follow the [coding guidelines](coding-guidelines) outlined below. - -### Determining package ownership - -To determine which VyOS package contains a file you want to modify, use Debian's -`dpkg -S` command on your running VyOS installation. - -### Submitting your code - -Fork the repository and submit a GitHub pull request. This is the preferred way -to contribute changes to VyOS. - -To fork a VyOS repository: - -1. Append `/fork` to the repository URL on GitHub. For example, to fork - `vyos-1x`, use: <https://github.com/vyos/vyos-1x/fork> - -2. Clone your fork or add it as a remote to your local repository: - - - Clone: `git clone https://github.com/<user>/vyos-1x.git` - - Add remote: `git remote add myfork https://github.com/<user>/vyos-1x.git` - -(configure-your-git-identity)= - -3. Configure your Git identity: - - ```none - git config --global user.name "J. Random Hacker" - git config --global user.email "jrhacker@example.net" - ``` - -4. Make your changes and add files to the Git index: - - - Single file: `git add myfile` - - Directory: `git add somedir/*` - -5. Commit your changes with a meaningful headline and [Phabricator](https://vyos.dev/) reference: - - `git commit` - -6. Push to your fork and create a GitHub pull request: - - `git push` - -Alternatively, you can export commits as patches and send them to -<mailto:maintainers@vyos.net> or attach them directly to the [Phabricator](https://vyos.dev/) task: - -- Export last commit: `git format-patch` -- Export last two commits: `git format-patch -2` - -## Commit messages - -For guidance on writing commit messages, review the file history -with `git log path/to/file.txt`. - -Every change must be associated with a task number (prefixed with **T**) and -a component. If no bug report or feature request exists for your changes, -create a [Phabricator](https://vyos.dev/) task first. Reference the task ID in your commit message: - -- `ddclient: T1030: auto create runtime directories` -- `Jenkins: add current Git commit ID to build description` - -If your pull request lacks a [Phabricator](https://vyos.dev/) reference, maintainers will request -that you amend the commit message. - -### Writing good commit messages - -Follow the format described in -the [Git documentation](https://git-scm.com/book/ch5-2.html) -and [Chris Beams' guide](https://chris.beams.io/posts/git-commit/). - -Commit message format: - -1. **Summary line** (50 characters recommended, 80 maximum): Include the - component - prefix and [Phabricator](https://vyos.dev/) reference (for example, `snmp: T1111:` or - `ethernet: T2222:`). Concatenate multiple components with colons - (for example, `snmp: ethernet: T3333`). -2. **Blank line**: Separate the summary from the body. - This blank line is critical. - -4) **Message body** with details: - - - Describe what changed, why, and how. This helps with `git bisect`. - - Wrap text at 72 characters for readability with `git log` on an 80x25 - terminal. - - Reference previous commits when applicable: - `After commit abcd12ef ("snmp: this is a headline") - a Python import statement is missing, throwing the following exception: - ABCDEF` - -5) **Cherry-pick option**: Always use the `-x` option when back-porting or - forward-porting commits: - - `git cherry-pick -x <commit>` - - This appends `(cherry picked from commit <ID>)` to the commit message, - making bisecting easier. - -6) **Single responsibility**: Each commit must be self-contained. Do not fix - multiple bugs in a single commit. Use `git add --patch` to stage only - the parts related to one issue. - -Constraints: - -- Bugfixes are only accepted for packages other than - <https://github.com/vyos/vyos-1x>. - New functionality must use the new XML/Python interface, not old-style - templates (`node.def` files and Perl/Bash code). - -(coding-guidelines)= - -## Coding guidelines - -VyOS maintains consistent coding standards to help contributors navigate the -codebase and understand its logic. - -### Formatting - -- **Python**: Use 4 spaces per indentation level. Tabs **must not** be used. -- **XML**: Use 2 spaces per indentation level. Tabs **must not** be used. - -Use tools like VIM extensions (xmllint) to enforce correct indentation. Add this -to your `.vimrc` file: -```none -au FileType xml setlocal equalprg=xmllint\ --format\ --recover\ -\ 2>/dev/null -``` -Then use `gg=G` in command mode to run the linter. - -### Text generation - -Use a template processor for generating config files: - -- **Jinja2** is the default template processor for VyOS code. -- Built-in string formatting **may** be used for simple line-oriented formats - (for example, iptables rules) where every line is self-contained. -- Template processors **must** be used for structured, multi-line formats - (for example, ISC DHCPd configuration). - -### Python code - -Configuration scripts and operation mode scripts written in Python3 should -follow these guidelines: - -- Wrap lines at 80 characters. This improves readability when browsing - GitHub on mobile devices and reads well in side-by-side diffs. - -Structure your scripts with these functions: -```python -#!/usr/bin/env python3 -# -# Copyright (C) 2020 VyOS maintainers and contributors -# -# This program is free software; you can redistribute it and/or modify -# it under the terms of the GNU General Public License version 2 or later as -# published by the Free Software Foundation. -# -# This program is distributed in the hope that it will be useful, -# but WITHOUT ANY WARRANTY; without even the implied warranty of -# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the -# GNU General Public License for more details. -# -# You should have received a copy of the GNU General Public License -# along with this program. If not, see <http://www.gnu.org/licenses/>. - -import sys - -from vyos.config import Config -from vyos import ConfigError - -def get_config(config=None): - if config: - conf = config - else: - conf = Config() - - # Base path to CLI nodes - base = ['...', '...'] - # Convert the VyOS config to an abstract internal representation - config_data = conf.get_config_dict(base, key_mangling=('-', '_'), get_first_key=True) - return config_data - -def verify(config): - # Verify that configuration is valid - if invalid: - raise ConfigError("Descriptive message") - -def generate(config): - # Generate daemon configs - pass - -def apply(config): - # Apply the generated configs to the live system - pass - -try: - c = get_config() - verify(c) - generate(c) - apply(c) -except ConfigError as e: - print(e) - sys.exit(1) -``` -`get_config()`: This function converts a VyOS config object to an abstract -internal representation. No other function may call the `vyos.config.Config` -object directly. Limiting config reads to one function makes it easier to -modify the config syntax in the future. Additionally, this design improves -testability since you can construct an internal representation by hand rather -than mocking the entire config subsystem. - -`verify()`: This function validates the internal representation. It must -raise `ConfigError` with a descriptive message if the config is invalid. It -**must not** make any changes to the system. This design enables future features -like commit dry-run ("commit test" as in JunOS) where the system can abort a -commit before making changes. - -`generate()`: This function generates config files for system components. - -`apply()`: This function applies the generated configuration to the live -system. Prefer non-disruptive reload when possible. Disruptive operations like -daemon restarts are acceptable only when: - -- The component does not support non-disruptive reload, or -- The expected service degradation is minimal (for example, auxiliary services - like LLDPd) - -For high-impact services (VPN daemons, routing protocols), make effort to -determine if changes can be applied non-disruptively before resorting to -restarts. - -Never modify active configuration directly unless absolutely necessary. Instead, -generate configuration files and apply them with a single command like service -reload through systemd. For example, save iptables rules to a file and load them -with `iptables-restore` rather than executing iptables commands one by one. - -The `apply()` and `generate()` functions may raise `ConfigError` if the -daemon fails to start with the updated config. However, this is not a substitute -for proper config validation in the `verify()` function. Make reasonable -effort to verify that generated configuration is valid and will be accepted by -the daemon, including cross-checks with other VyOS configuration subtrees when -necessary. - -Exceptions like `VyOSError` (raised by `vyos.config.Config` on improper -operations) should not be silenced or caught. While this may produce less -polished error output for users, it generates better bug reports and helps -maintainers debug issues. - -For reference implementations, see `ntp.py` or `interfaces-bonding.py` (for -tag nodes) in the [vyos-1x](https://github.com/vyos/vyos-1x) repository. - -### Other considerations: `vyos-configd` - -All scripts now run under the config daemon and must conform to these -requirements: - -1. The signature and first four lines of `get_config(...)` **must** be as - specified above. -2. Each of `get_config`, `verify`, `apply`, and `generate` **must** - appear - with the correct signatures, even if they are a no-op. -3. `Config` objects other than those in `get_config` **must not** appear. -4. The legacy function `my_set` **must not** appear. Modifications to active - config **should not** appear in new code (alternative mechanisms may be used - if absolutely necessary). - -## XML for CLI definitions - -XML interface definitions define the VyOS CLI structure. -Before VyOS `1.2` (crux), these -files were created manually. After a redesign, new-style templates are -automatically generated from XML input files. - -VyOS interface definitions come with a RelaxNG schema located in the -[vyos-1x](https://github.com/vyos/vyos-1x/tree/current/schema) -repository. This schema is a modified version from `VyConf` (VyOS `2.0`). -VyOS `1.2.x` -interface definitions are reusable in future VyOS versions with minimal changes. - -Schemas provide two benefits: - -- Complete grammar verification -- Automatic validation against the schema - -The [build-command-templates](https://github.com/vyos/vyos-1x/blob/current/scripts/build-command-templates) -script converts XML definitions to -old-style templates and verifies them against the schema. A bad definition -causes the package build to fail. While the XML format is verbose, no other -format provides this level of verification. Specialized XML editors can help -manage verbosity. - -Example XML interface definition: -```xml -<?xml version="1.0"?> -<!-- Cron configuration --> -<interfaceDefinition> - <node name="system"> - <children> - <node name="task-scheduler"> - <properties> - <help>Task scheduler settings</help> - </properties> - <children> - <tagNode name="task" owner="${vyos_conf_scripts_dir}/task_scheduler.py"> - <properties> - <help>Scheduled task</help> - <valueHelp> - <format><string></format> - <description>Task name</description> - </valueHelp> - <priority>999</priority> - </properties> - <children> - <leafNode name="crontab-spec"> - <properties> - <help>UNIX crontab time specification string</help> - </properties> - </leafNode> - <leafNode name="interval"> - <properties> - <help>Execution interval</help> - <valueHelp> - <format><minutes></format> - <description>Execution interval in minutes</description> - </valueHelp> - <valueHelp> - <format><minutes>m</format> - <description>Execution interval in minutes</description> - </valueHelp> - <valueHelp> - <format><hours>h</format> - <description>Execution interval in hours</description> - </valueHelp> - <valueHelp> - <format><days>d</format> - <description>Execution interval in days</description> - </valueHelp> - <constraint> - <regex>[1-9]([0-9]*)([mhd]{0,1})</regex> - </constraint> - </properties> - </leafNode> - <node name="executable"> - <properties> - <help>Executable path and arguments</help> - </properties> - <children> - <leafNode name="path"> - <properties> - <help>Path to executable</help> - </properties> - </leafNode> - <leafNode name="arguments"> - <properties> - <help>Arguments passed to the executable</help> - </properties> - </leafNode> - </children> - </node> - </children> - </tagNode> - </children> - </node> - </children> - </node> -</interfaceDefinition> -``` -XML definitions are purely declarative and contain no logic. All logic for -generating config files, restarting services, and related tasks is implemented -in configuration scripts. - -### Template Processors - -XML interface definition files use the `.xml.in` file extension (implemented -in {vytask}`T1843`). These files use the GCC preprocessor to reduce code -duplication in common areas: - -- VIF (including VIF-S and VIF-C) -- Address configuration -- Description -- Enabled/Disabled state - -Instead of repeating XML nodes, use include files with predefined features: - -- [IPv4, IPv6, and DHCP(v6)](https://github.com/vyos/vyos-1x/blob/current/interface-definitions/include/interface/address-ipv4-ipv6-dhcp.xml.i) - address assignment. -- [IPv4 and IPv6](https://github.com/vyos/vyos-1x/blob/current/interface-definitions/include/interface/address-ipv4-ipv6.xml.i) - address assignment. -- [VLAN (VIF)](https://github.com/vyos/vyos-1x/blob/current/interface-definitions/include/accel-ppp/vlan.xml.i) - definition. -- [MAC address](https://github.com/vyos/vyos-1x/blob/current/interface-definitions/include/firewall/mac-address.xml.i) - assignment. - -The `.in` files are preprocessed and stored in the [interface-definitions](https://github.com/vyos/vyos-1x/tree/current/interface-definitions) -folder. The [scripts/build-command-templates](https://github.com/vyos/vyos-1x/blob/current/scripts/build-command-templates) -script then operates on this folder to generate all required CLI nodes. - -Example preprocessor output: -```none -$ make interface_definitions -install -d -m 0755 build/interface-definitions -install -d -m 0755 build/op-mode-definitions -Generating build/interface-definitions/intel_qat.xml from interface-definitions/intel_qat.xml.in -Generating build/interface-definitions/interfaces-bonding.xml from interface-definitions/interfaces-bonding.xml.in -Generating build/interface-definitions/cron.xml from interface-definitions/cron.xml.in -Generating build/interface-definitions/pppoe-server.xml from interface-definitions/pppoe-server.xml.in -Generating build/interface-definitions/mdns-repeater.xml from interface-definitions/mdns-repeater.xml.in -Generating build/interface-definitions/tftp-server.xml from interface-definitions/tftp-server.xml.in -[...] -``` - -### Command Definition Guidelines - -#### Use of Numbers - -Avoid using numbers in command names unless the number is part of a protocol -name or similar. For example, `protocols ospfv3` is appropriate, -but `server-1` is questionable. - -#### Help Strings - -Follow these guidelines for consistent, readable help strings: - -##### Capitalization and Punctuation - -- Capitalize the first word of every help string. -- Do not use a period at the end of help strings. - -This standard mirrors network device CLIs and improves aesthetics. - -Examples: - -- Good: "Frobnication algorithm" -- Bad: "frobnication algorithm" -- Bad: "Frobnication algorithm." -- Incorrect: "frobnication algorithm." - -##### Abbreviations and Acronyms - -- Capitalize all abbreviations and acronyms. - -Examples: - -- Good: "TCP connection timeout" -- Bad: "tcp connection timeout" -- Bad: "Tcp connection timeout" -- Capitalize acronyms to distinguish them from normal words. - -Examples: - -- Good: RADIUS (remote authentication for dial-in user services) -- Bad: radius (unless referring to circular distance) -- Follow accepted spelling conventions for mixed-case abbreviations. If it - contains "over" or "version", use lowercase. Follow RFC or standard spellings - when they exist. - -Examples: - -- Good: PPPoE, IPsec -- Bad: PPPOE, IPSEC -- Bad: pppoe, ipsec - -##### Verbs - -- Avoid verbs. If a verb can be omitted, omit it. - -Examples: - -- Good: "TCP connection timeout" -- Bad: "Set TCP connection timeout" -- When a verb is essential, use it. For example: "Disable IPv6 forwarding on - all interfaces" for `set system ipv6 disable-forwarding`. -- Use infinitive form for necessary verbs. - -Examples: - -- Good: "Disable IPv6 forwarding" -- Bad: "Disables IPv6 forwarding" - -## C++ Backend Code - -The VyOS CLI parser combines bash, bash-completion helpers, and the C++ backend -library [vyatta-cfg](https://github.com/vyos/vyatta-cfg). This section -references common CLI commands and their C/C++ entry points: - -`set`: - -- <https://github.com/vyos/vyatta-cfg/blob/0f42786a0b3/src/cstore/cstore.cpp#L352> -- <https://github.com/vyos/vyatta-cfg/blob/0f42786a0b3/src/cstore/cstore.cpp#L2549> - -`commit`: - -- <https://github.com/vyos/vyatta-cfg/blob/0f42786a0b3/src/commit/commit-algorithm.cpp#L1252> - - diff --git a/docs/contributing/md-index.md b/docs/contributing/md-index.md deleted file mode 100644 index f26a6b70..00000000 --- a/docs/contributing/md-index.md +++ /dev/null @@ -1,13 +0,0 @@ -# Contributing - -```{toctree} -:maxdepth: 1 - -build-vyos -development -cla -issues-features -upstream-packages -debugging -testing -``` diff --git a/docs/contributing/md-issues-features.md b/docs/contributing/md-issues-features.md deleted file mode 100644 index ab235326..00000000 --- a/docs/contributing/md-issues-features.md +++ /dev/null @@ -1,122 +0,0 @@ ---- -lastproofread: '2025-12-08' ---- - -(issues_features)= - -# Issues/Feature requests - -(bug_report)= - -## Bug Report/Issue - -Issues and bugs occur in every software project, and VyOS is no exception. - -### I found a bug, what should I do? - -When you find a potential bug, first: - -- Consult the [documentation] to ensure you configured your system - correctly. -- Check if the VyOS community has identified a workaround for the bug through - [Slack] or the VyOS [Forum]. - -### Ensure the bug is reproducible - -Include the following information when reporting a bug: - -- A sequence of configuration commands or a complete configuration file needed - to recreate the bug. Avoid partial configurations: a sequence of commands is - easy to paste and a complete configuration is easy to load, but a partial - config is hard to reconstruct. -- Describe the expected behavior and how it differs from what you observe. - Include command outputs or traffic dumps. Explain briefly why these outputs - are incorrect and what the correct behavior should be. -- A sequence of actions that trigger the bug. While not always possible, this - helps developers and community members confirm the issue and verify fixes. -- If the bug is a regression, specify the VyOS version where the feature worked - correctly (any working version is acceptable). Identify the exact version - that the feature stopped working, if possible. - -If you are uncertain whether the behavior is a bug or what the correct behavior -is, or if you lack a reliable reproducing procedure, post on the forum or ask in -chat first. If you have a subscription, create a support ticket. The team and -community can help identify the issue, work around it, and create an actionable -bug report. - -### Report a Bug - -To open a bug report or feature request, create an account on -[vyos.dev](https://vyos.dev), the public issue tracker for VyOS. - -When creating a new issue, select the appropriate project and: - -- Provide as much information as you can. -- Specify which VyOS version you are using: `run show version`. -- Explain how to reproduce the bug. - -(feature-request)= - -## Feature Requests - -Have an idea to improve VyOS or need a feature that would benefit all users? -Before submitting a feature request, search the public issue tracker -[vyos.dev](https://vyos.dev) to check if a request already exists. You can -also enhance an existing request by providing additional information. - -Create a task before starting work on a feature, -even if it is a trivial feature. -The task tracker generates release notes, so all work must be reflected -in the tracker. - -Include at least the following information: - -- Provide a detailed description of the feature: what it is, how it works, and - how you would use it. Maintainers may not have experience with every feature, - protocol, and tool in VyOS. Detailed information helps VyOS contributors and - maintainers test new features they are unfamiliar with. -- Include proposed CLI syntax if the feature requires new commands. Provide both - configuration and operational mode commands if both are needed. - -Consider including the following information: - -- Is the feature already supported by the underlying component - (FreeRangeRouting, nftables, Kea, etc.)? -- How would you configure the feature manually within that component? -- Are there any limitations to using the feature - (hardware support, resource usage)? -- Are there any adverse or non-obvious interactions with other features? Should - the feature be mutually exclusive? -- Any relevant documentation or references about the feature. - -You do not need to provide all this information, but if you can, it simplifies -developers' work considerably. Research these questions when possible. - -## Task auto-closing - -A special task status exists for when all work by maintainers and contributors -is complete: **Needs reporter action**. - -VyOS assigns this status to: - -- Feature requests that do not include required information and need - clarification. -- Bug reports that lack reproducing procedures. -- Tasks that are implemented and tested by the implementation author, - but require testing in the real-world environment that only the reporter - can replicate (for example, hardware VyOS does not support or specific - network conditions). - -When a task is set to **Needs reporter action**: - -- If the reporter does not respond within two weeks, the task bot adds a comment - ("Any news?") to remind the reporter. -- If there is still no response after another two weeks, - the task is closed automatically. - -We do not auto-close tasks with any other status and do not close tasks due to -lack of maintainer activity. - -[documentation]: https://docs.vyos.io -[forum]: https://forum.vyos.io -[slack]: https://slack.vyos.io diff --git a/docs/contributing/md-testing.md b/docs/contributing/md-testing.md deleted file mode 100644 index 5e2371d6..00000000 --- a/docs/contributing/md-testing.md +++ /dev/null @@ -1,206 +0,0 @@ ---- -lastproofread: '2025-12-02' ---- - -(testing)= - -# Testing - -One of the major features introduced in VyOS 1.3 is an automated test -framework. When you assemble an ISO image, several things can go wrong. -VyOS uses this framework to detect issues before they cause downstream problems. - -This section describes how the automated testing process at VyOS works. - -## Smoketests - -Smoketests execute predefined VyOS CLI commands and check if the desired -daemon or service configuration is rendered. - -When an ISO image is assembled by the [VyOS CI](https://ci.vyos.net), the `BUILD_SMOKETEST` -parameter is enabled by default. This extends the ISO configuration line -with the following packages: - -```python -def CUSTOM_PACKAGES = '' - if (params.BUILD_SMOKETESTS) - CUSTOM_PACKAGES = '--custom-package vyos-1x-smoketest' -``` - -If you plan to build your own custom ISO image and want to use VyOS's -smoketests, ensure that you have the `vyos-1x-smoketest` package installed. - -The `make test` command from the [vyos-build](https://github.com/vyos/vyos-build) repository launches a new -QEMU instance, and the ISO image is first installed to the virtual hard disk. - -After the first boot into the newly installed system, the main Smoketest script -is executed. It can be found at `/usr/bin/vyos-smoketest`. - -The script searches for executable test cases under -`/usr/libexec/vyos/tests/smoke/cli/` and executes them one by one. - -:::{note} -Smoketests will alter the system configuration. If you are logged -in remotely, you may lose your connection to the system. -::: - -:::{note} -To enable smoketest debugging (print the CLI set commands used), -run: `touch /tmp/vyos.smoketest.debug`. -::: - -### Manual Smoketest Run - -Each test is contained in its own file, so you can execute a single Smoketest -manually by running the Python test script. - -Example: - -```none -vyos@vyos:~$ /usr/libexec/vyos/tests/smoke/cli/test_protocols_bgp.py -test_bgp_01_simple (__main__.TestProtocolsBGP) ... ok -test_bgp_02_neighbors (__main__.TestProtocolsBGP) ... ok -test_bgp_03_peer_groups (__main__.TestProtocolsBGP) ... ok -test_bgp_04_afi_ipv4 (__main__.TestProtocolsBGP) ... ok -test_bgp_05_afi_ipv6 (__main__.TestProtocolsBGP) ... ok -test_bgp_06_listen_range (__main__.TestProtocolsBGP) ... ok -test_bgp_07_l2vpn_evpn (__main__.TestProtocolsBGP) ... ok -test_bgp_08_zebra_route_map (__main__.TestProtocolsBGP) ... ok -test_bgp_09_distance_and_flowspec (__main__.TestProtocolsBGP) ... ok -test_bgp_10_vrf_simple (__main__.TestProtocolsBGP) ... ok -test_bgp_11_confederation (__main__.TestProtocolsBGP) ... ok -test_bgp_12_v6_link_local (__main__.TestProtocolsBGP) ... ok -test_bgp_13_solo (__main__.TestProtocolsBGP) ... ok - ----------------------------------------------------------------------- -Ran 13 tests in 348.191s - -OK -``` - -### Interface-based tests - -Our smoketests not only test daemons and services, but also check if interface -configuration works as expected. There is a common base class named -`base_interfaces_test.py` that holds all the common code for interface tests. - -These common tests consist of: - -- Add one or more IP addresses - -- DHCP client and DHCPv6 prefix delegation - -- MTU size - -- IP and IPv6 options - -- Port description - -- Port disable - -- VLANs (QinQ and regular 802.1q) - -- ... - -:::{note} -When you are working on interface configuration and want to test -if the Smoketests pass, you would normally lose the remote SSH connection -to your {abbr}`DUT (Device Under Test)`. To handle this, some interface-based -tests can be called with an environment variable beforehand to limit the -number of interfaces used in the test. By default, all interfaces (e.g., all -Ethernet interfaces) are used. -::: - -```none -vyos@vyos:~$ TEST_ETH="eth1 eth2" /usr/libexec/vyos/tests/smoke/cli/test_interfaces_bonding.py -test_add_multiple_ip_addresses (__main__.BondingInterfaceTest) ... ok -test_add_single_ip_address (__main__.BondingInterfaceTest) ... ok -test_bonding_hash_policy (__main__.BondingInterfaceTest) ... ok -test_bonding_lacp_rate (__main__.BondingInterfaceTest) ... ok -test_bonding_min_links (__main__.BondingInterfaceTest) ... ok -test_bonding_remove_member (__main__.BondingInterfaceTest) ... ok -test_dhcpv6_client_options (__main__.BondingInterfaceTest) ... ok -test_dhcpv6pd_auto_sla_id (__main__.BondingInterfaceTest) ... ok -test_dhcpv6pd_manual_sla_id (__main__.BondingInterfaceTest) ... ok -test_interface_description (__main__.BondingInterfaceTest) ... ok -test_interface_disable (__main__.BondingInterfaceTest) ... ok -test_interface_ip_options (__main__.BondingInterfaceTest) ... ok -test_interface_ipv6_options (__main__.BondingInterfaceTest) ... ok -test_interface_mtu (__main__.BondingInterfaceTest) ... ok -test_ipv6_link_local_address (__main__.BondingInterfaceTest) ... ok -test_mtu_1200_no_ipv6_interface (__main__.BondingInterfaceTest) ... ok -test_span_mirror (__main__.BondingInterfaceTest) ... ok -test_vif_8021q_interfaces (__main__.BondingInterfaceTest) ... ok -test_vif_8021q_lower_up_down (__main__.BondingInterfaceTest) ... ok -test_vif_8021q_mtu_limits (__main__.BondingInterfaceTest) ... ok -test_vif_8021q_qos_change (__main__.BondingInterfaceTest) ... ok -test_vif_s_8021ad_vlan_interfaces (__main__.BondingInterfaceTest) ... ok -test_vif_s_protocol_change (__main__.BondingInterfaceTest) ... ok - ----------------------------------------------------------------------- -Ran 23 tests in 244.694s - -OK -``` - -This will limit the `bond` interface test to use only `eth1` and `eth2` -as member ports. - -## Config Load Tests - -The other part of our tests are called "config load tests." Config load tests -sequentially load arbitrary configuration files to verify that configuration -migration scripts work as designed and that a given set of functionality can -still be loaded with a fresh VyOS ISO image. - -The configurations are all derived from production systems and can act as -test cases or as references for enabling certain features. The configurations -can be found here: -<https://github.com/vyos/vyos-1x/tree/current/smoketest/configs> - -The entire test is controlled by the main wrapper script -`/usr/bin/vyos-configtest`. -It behaves in the same way as the main smoketest script. It scans the folder -for potential configuration files and issues a `load` command for each file. - -### Manual config load test - -You do not have to load all configurations sequentially; you can also load -individual test configurations manually. - -```none -vyos@vyos:~$ configure -load[edit] - -vyos@vyos# load /usr/libexec/vyos/tests/config/ospf-small -Loading configuration from '/usr/libexec/vyos/tests/config/ospf-small' -Load complete. Use 'commit' to make changes effective. -[edit] -vyos@vyos# compare -[edit interfaces ethernet eth0] --hw-id 00:50:56:bf:c5:6d -[edit interfaces ethernet eth1] -+duplex auto --hw-id 00:50:56:b3:38:c5 -+speed auto -[edit interfaces] --ethernet eth2 { -- hw-id 00:50:56:b3:9c:1d --} --vti vti1 { -- address 192.0.2.1/30 --} -... - -vyos@vyos# commit -vyos@vyos# -``` - -:::{note} -Some configurations have preconditions that must be met. These most -likely include generation of cryptographic keys before the config can be -applied; otherwise, you will get a commit error. If you are interested in -how those preconditions are fulfilled, check the [vyos-build](https://github.com/vyos/vyos-build) repository and -the `scripts/check-qemu-install` file. -::: - diff --git a/docs/contributing/md-upstream-packages.md b/docs/contributing/md-upstream-packages.md deleted file mode 100644 index c7da9066..00000000 --- a/docs/contributing/md-upstream-packages.md +++ /dev/null @@ -1,149 +0,0 @@ ---- -lastproofread: '2026-01-30' ---- - -(upstream-packages)= - -# Upstream Packages - -Many base system packages are pulled straight from Debian's `main` and -`contrib` repositories, but there are exceptions. If you only want to build -a fresh ISO image, you can skip -this section. This information may be useful for a deeper dive into VyOS. - -System packages that are not directly pulled from Debian are built through a -separate build system, `build.py` in the [vyos-build](https://github.com/vyos/vyos-build/tree/current/scripts/package-build) repository. - -## Overview - -Previously, VyOS used Jenkins for building upstream packages. With the move away -from Jenkins, the build system was replaced with a Python-based solution using -`build.py` and `package.toml` configuration files. - -Each package directory contains: - -- A `package.toml` configuration file that defines how the package is built. -- A symlink to the common `build.py` script in the build system. - -## Building Packages - -To build a package, navigate to the package directory and execute the -build script: - -```console -cd package-build/<package-name> -./build.py -``` - -The script will: - -1. Check out the source code from the configured repository. -2. Apply any patches defined in the configuration. -3. Execute pre-build hooks (if configured). -4. Build the package using the specified build command. -5. Generate both binary (`.deb`) packages and source tarballs. - -## Package Configuration (package.toml) - -Each package directory contains a `package.toml` file that defines the build -parameters. The key configuration fields are: - -**name** - -: The package name (e.g., `frr`) - -**commit_id** - -: The specific commit, tag, or branch to check out from the source repository - (e.g., `stable/10.5`) - -**scm_url** - -: The Git URL of the upstream source repository - (e.g., `https://github.com/FRRouting/frr.git`) - -**build_cmd** - -: The command to execute for building the package. This replaces what was - previously defined in the Jenkins `Jenkinsfile`. - - Default if not specified: `dpkg-buildpackage -uc -us -tc -F --source-option=--tar-ignore=.git --source-option=--tar-ignore=.github` - - Example with custom build command: - - ```toml - build_cmd = "sudo dpkg -i ../*.deb; dpkg-buildpackage -us -uc -tc -b -Ppkg.frr.rtrlib,pkg.frr.lua" - ``` - -**pre_build_hook** (Optional) - -: A shell command or script that executes after the repository is checked out - and before the build process begins. This allows you to perform preparatory - tasks such as: - - - Creating directories - - Copying files - - Running custom setup scripts - - Installing dependencies - - Single command example: - - ```toml - pre_build_hook = "echo 'Preparing build environment'" - ``` - - Multi-line commands example: - - ```toml - pre_build_hook = """ - mkdir -p ../hello/vyos - mkdir -p ../vyos - cp example.txt ../vyos - """ - ``` - - Combined commands and scripts: - - ```toml - pre_build_hook = "ls -l; ./script.sh" - ``` - -**apply_patches** (Optional) - -: Boolean flag to control whether patches should be applied. Defaults to - `True`. - - ```toml - apply_patches = false - ``` - -**prepare_package** (Optional) - -: Boolean flag to enable package preparation. When set to `True`, the - `install_data` configuration is used. - -**install_data** (Optional) - -: Data used for package preparation when `prepare_package` is enabled. - -## Example package.toml file - -Here's an example configuration for the FRRouting (FRR) package: -```toml -name = "frr" -commit_id = "stable/10.5" -scm_url = "https://github.com/FRRouting/frr.git" -build_cmd = "sudo dpkg -i ../*.deb; dpkg-buildpackage -us -uc -tc -b -Ppkg.frr.rtrlib,pkg.frr.lua" -``` - -## Build Output - -After running `./build.py`, the following artifacts are generated in the -package directory: - -- `.deb` files - Binary Debian packages ready for installation -- `.tar.gz` files - Source tarballs of the checked-out repositories -- Additional build artifacts as produced by the Debian build system - -The build script also creates build dependency packages (`*build-deps*.deb`), -which are automatically cleaned up after the build completes. diff --git a/docs/installation/cloud/md-index.md b/docs/installation/cloud/md-index.md deleted file mode 100644 index cf7d447d..00000000 --- a/docs/installation/cloud/md-index.md +++ /dev/null @@ -1,10 +0,0 @@ -# Cloud Environments - -```{toctree} -:caption: Content - -aws -azure -gcp -oracle -``` diff --git a/docs/installation/md-bare-metal.md b/docs/installation/md-bare-metal.md deleted file mode 100644 index 7017b6a2..00000000 --- a/docs/installation/md-bare-metal.md +++ /dev/null @@ -1,623 +0,0 @@ -(vyosonbaremetal)= - -# Bare Metal Deployment - -## Supermicro A2SDi (Atom C3000) - -I opted to get one of the new Intel Atom C3000 CPUs to spawn VyOS on it. -Running VyOS on an UEFI only device is supported as of VyOS release 1.2. - -### Supermicro Shopping Cart - -- 1x Supermicro CSE-505-203B (19" 1U chassis, inkl. 200W PSU) -- 1x Supermicro MCP-260-00085-0B (I/O Shield for A2SDi-2C-HLN4F) -- 1x Supermicro A2SDi-2C-HLN4F (Intel Atom C3338, 2C/2T, 4MB cache, Quad LAN - with Intel C3000 SoC 1GbE) -- 1x Crucial CT4G4DFS824A (4GB DDR4 RAM 2400 MT/s, PC4-19200) -- 1x SanDisk Ultra Fit 32GB (USB-A 3.0 SDCZ43-032G-G46 mass storage for OS) -- 1x Supermicro MCP-320-81302-0B (optional FAN tray) - -### Optional (10GE) - -If you want to get additional ethernet ports or even 10GE connectivity -the following optional parts will be required: - -- 1x Supermicro RSC-RR1U-E8 (Riser Card) -- 1x Supermicro MCP-120-00063-0N (Riser Card Bracket) - -Latest VyOS rolling releases boot without any problem on this board. You also -receive a nice IPMI interface realized with an ASPEED AST2400 BMC (no -information about [OpenBMC](https://www.openbmc.org/) so far on this -motherboard). - -### Pictures - -:::{figure} /_static/images/1u_vyos_back.jpg -:alt: CSE-505-203B Back -:scale: 25 % -::: - -:::{figure} /_static/images/1u_vyos_front.jpg -:alt: CSE-505-203B Front -:scale: 25 % -::: - -:::{figure} /_static/images/1u_vyos_front_open_1.jpg -:alt: CSE-505-203B Open 1 -:scale: 25 % -::: - -:::{figure} /_static/images/1u_vyos_front_open_2.jpg -:alt: CSE-505-203B Open 2 -:scale: 25 % -::: - -:::{figure} /_static/images/1u_vyos_front_open_3.jpg -:alt: CSE-505-203B Open 3 -:scale: 25 % -::: - -:::{figure} /_static/images/1u_vyos_front_10ge_open_1.jpg -:alt: CSE-505-203B w/ 10GE Open 1 -:scale: 25 % -::: - -:::{figure} /_static/images/1u_vyos_front_10ge_open_2.jpg -:alt: CSE-505-203B w/ 10GE Open 2 -:scale: 25 % -::: - -:::{figure} /_static/images/1u_vyos_front_10ge_open_3.jpg -:alt: CSE-505-203B w/ 10GE Open 3 -:scale: 25 % -::: - -:::{figure} /_static/images/1u_vyos_front_10ge_open_4.jpg -:alt: CSE-505-203B w/ 10GE Open -:scale: 25 % -::: - -(pc-engines-apu4)= - -## PC Engines APU4 - -As this platform seems to be quite common in terms of noise, cost, power and -performance it makes sense to write a small installation manual. - -This guide was developed using an APU4C4 board with the following specs: - -- AMD Embedded G series GX-412TC, 1 GHz quad Jaguar core with 64 bit and AES-NI - support, 32K data + 32K instruction cache per core, shared 2MB L2 cache. -- 4 GB DDR3-1333 DRAM, with optional ECC support -- About 6 to 10W of 12V DC power depending on CPU load -- 2 miniPCI express (one with SIM socket for 3G modem). -- 4 Gigabit Ethernet channels using Intel i211AT NICs - -The board can be powered via 12V from the front or via a 5V onboard connector. - -(vyos-on-baremetal-apu4-shopping)= - -### APU4 Shopping Cart - -- 1x apu4c4 = 4 i211AT LAN / AMD GX-412TC CPU / 4 GB DRAM / dual SIM -- 1x Kingston SUV500MS/120G -- 1x VARIA Group Item 326745 19" dual rack for APU4 - -The 19" enclosure can accommodate up to two APU4 boards - there is a single and -dual front cover. - -#### Extension Modules - -##### WiFi - -Refer to {ref}`wireless-interface` for additional information, below listed -modules have been tested successfully on this Hardware platform: - -- Compex WLE900VX mini-PCIe WiFi module, only supported in mPCIe slot 1. -- Intel Corporation AX200 mini-PCIe WiFi module, only supported in mPCIe slot 1. - (see {ref}`wireless-interface-intel-ax200`) - -##### WWAN - -Refer to {ref}`wwan-interface` for additional information, below listed modules -have been tested successfully on this Hardware platform using VyOS 1.3 -(equuleus): - -- Sierra Wireless AirPrime MC7304 miniPCIe card (LTE) -- Sierra Wireless AirPrime MC7430 miniPCIe card (LTE) -- Sierra Wireless AirPrime MC7455 miniPCIe card (LTE) -- Sierra Wireless AirPrime MC7710 miniPCIe card (LTE) -- Huawei ME909u-521 miniPCIe card (LTE) - -### VyOS 1.4 (sagitta) - -Depending on the VyOS versions you intend to install there is a difference in -the serial port settings ({vytask}`T1327`). - -Create a bootable USB pendrive using e.g. [Rufus] on a Windows machine. - -Connect serial port to a PC through null modem cable (RXD / TXD crossed over). -Set terminal emulator to 115200 8N1. - -```none -PC Engines apu4 -coreboot build 20171130 -BIOS version v4.6.4 -4080 MB ECC DRAM -SeaBIOS (version rel-1.11.0.1-0-g90da88d) - -Press F10 key now for boot menu: - -Select boot device: - -1. ata0-0: KINGSTON SUV500MS120G ATA-11 Hard-Disk (111 GiBytes) -2. USB MSC Drive Generic Flash Disk 8.07 -3. Payload [memtest] -4. Payload [setup] -``` - -Now boot from the `USB MSC Drive Generic Flash Disk 8.07` media by pressing -`2`, the VyOS boot menu will appear, just wait 10 seconds or press `Enter` -to continue. - -```none -lqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqk -x VyOS - Boot Menu x -tqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqu -x Live system (amd64-vyos) x -x Live system (amd64-vyos fail-safe mode) x -x Live system (amd64-vyos) - Serial console x -x x -mqqqqqqPress ENAutomatic boot in 10 seconds...nu entryqqqqqqqj -``` - -The image will be loaded and the last lines you will get will be: - -```none -Loading /live/vmlinuz... ok -Loading /live/initrd.img... -... -Welcome to VyOS - vyos ttyS0 - -vyos login: -``` - -You can now proceed with a regular image installation as described in -{ref}`installation`. - -(vyos-on-baremetal-apu4-pictures)= - -### Pictures - -:::{note} -Both device types operate without any moving parts and emit zero -noise. -::: - -#### Rack Mount - -:::{figure} /_static/images/apu4_rack_1.jpg -:alt: APU4 rack closed -:scale: 25 % -::: - -:::{figure} /_static/images/apu4_rack_2.jpg -:alt: APU4 rack front -:scale: 25 % -::: - -:::{figure} /_static/images/apu4_rack_3.jpg -:alt: 'APU4 rack module #1' -:scale: 25 % -::: - -:::{figure} /_static/images/apu4_rack_4.jpg -:alt: 'APU4 rack module #2' -:scale: 25 % -::: - -:::{figure} /_static/images/apu4_rack_5.jpg -:alt: 'APU4 rack module #3 with PSU' -:scale: 25 % -::: - -##### VyOS custom print - -:::{figure} /_static/images/apu4_rack_vyos_print.jpg -:alt: APU4 custom VyOS powder coat -:scale: 25 % -::: - -#### Desktop / Bench Top - -:::{figure} /_static/images/apu4_desk_1.jpg -:alt: APU4 desktop closed -:scale: 25 % -::: - -:::{figure} /_static/images/apu4_desk_2.jpg -:alt: APU4 desktop closed -:scale: 25 % -::: - -:::{figure} /_static/images/apu4_desk_3.jpg -:alt: APU4 desktop back -:scale: 25 % -::: - -:::{figure} /_static/images/apu4_desk_4.jpg -:alt: APU4 desktop back -:scale: 25 % -::: - -## Qotom Q355G4 - -The install on this Q355G4 box is pretty much plug and play. The port numbering -the OS does might differ from the labels on the outside, but the UEFI firmware -has a port blink test built in with MAC addresses so you can very quickly -identify which is which. MAC labels are on the inside as well, and this test -can be done from VyOS or plain Linux too. Default settings in the UEFI will -make it boot, but depending on your installation wishes (i.e. storage type, -boot type, console type) you might want to adjust them. This Qotom company -seems to be the real OEM/ODM for many other relabelling companies like -Protectli. - -### Hardware - -There are a number of other options, but they all seem to be close to Intel -reference designs, with added features like more serial ports, more network -interfaces and the likes. Because they don't deviate too much from standard -designs all the hardware is well-supported by mainline. It accepts one LPDDR3 -SO-DIMM, but chances are that if you need more than that, you'll also want -something even beefier than an i5. There are options for antenna holes, and SIM -slots, so you could in theory add an LTE/Cell modem (not tested so far). - -The chassis is a U-shaped alu extrusion with removable I/O plates and removable -bottom plate. Cooling is completely passive with a heatsink on the SoC with -internal and external fins, a flat interface surface, thermal pad on top of -that, which then directly attaches to the chassis, which has fins as well. It -comes with mounting hardware and rubber feet, so you could place it like a -desktop model or mount it on a VESA mount, or even wall mount it with the -provided mounting plate. The closing plate doubles as internal 2.5" mounting -place for an HDD or SSD, and comes supplied with a small SATA cable and SATA -power cable. - -Power supply is a 12VDC barrel jack, and included switching power supply, which -is why SATA power regulation is on-board. Internally it has a NUC-board-style -on-board 12V input header as well, the molex locking style. - -There are WDT options and auto-boot on power enable, which is great for remote -setups. Firmware is reasonably secure (no backdoors found, BootGuard is enabled -in enforcement mode, which is good but also means no coreboot option), yet has -most options available to configure (so it's not locked out like most firmwares -are). - -An external RS232 serial port is available, internally a GPIO header as well. -It does have Realtek based audio on board for some reason, but you can disable -that. Booting works on both USB2 and USB3 ports. Switching between serial BIOS -mode and HDMI BIOS mode depends on what is connected at startup; it goes into -serial mode if you disconnect HDMI and plug in serial, in all other cases it's -HDMI mode. - -## Partaker i5 - -:::{figure} ../_static/images/600px-Partaker-i5.jpg -::: - -I believe this is actually the same hardware as the Protectli. I purchased it -in June 2018. It came pre-loaded with pfSense. - -[Manufacturer product page](http://www.inctel.com.cn/product/detail/338.html). - -### Installation - -- Write VyOS ISO to USB drive of some sort -- Plug in VGA, power, USB keyboard, and USB drive -- Press "SW" button on the front (this is the power button; I don't know what - "SW" is supposed to mean). -- Begin rapidly pressing delete on the keyboard. The boot prompt is very quick, - but with a few tries you should be able to get into the BIOS. -- Chipset > South Bridge > USB Configuration: set XHCI to Disabled and USB 2.0 - (EHCI) to Enabled. Without doing this, the USB drive won't boot. -- Boot to the VyOS installer and install as usual. - -Warning the interface labels on my device are backwards; the left-most "LAN4" -port is eth0 and the right-most "LAN1" port is eth3. - -## Acrosser AND-J190N1 - -:::{figure} ../_static/images/480px-Acrosser_ANDJ190N1_Front.jpg -::: - -:::{figure} ../_static/images/480px-Acrosser_ANDJ190N1_Back.jpg -::: - -This microbox network appliance was build to create OpenVPN bridges. It can -saturate a 100Mbps link. It is a small (serial console only) PC with 6 Gb LAN - -You may have to add your own RAM and HDD/SSD. There is no VGA connector. But -Acrosser provides a DB25 adapter for the VGA header on the motherboard (not -used). - -### BIOS Settings: - -First thing you want to do is getting a more user friendly console to configure -BIOS. Default VT100 brings a lot of issues. Configure VT100+ instead. - -For practical issues change speed from 115200 to 9600. 9600 is the default -speed at which both linux kernel and VyOS will reconfigure the serial port -when loading. - -Connect to serial (115200bps). Power on the appliance and press Del in the -console when requested to enter BIOS settings. - -Advanced > Serial Port Console Redirection > Console Redirection Settings: - -- Terminal Type : VT100+ -- Bits per second : 9600 - -Save, reboot and change serial speed to 9600 on your client. - -Some options have to be changed for VyOS to boot correctly. With XHCI enabled -the installer can’t access the USB key. Enable EHCI instead. - -Reboot into BIOS, Chipset > South Bridge > USB Configuration: - -- Disable XHCI -- Enable USB 2.0 (EHCI) Support - -Perform Image installation using `install image` CLI command. - -(gowin-gw-fn-1ur1-10g)= - -## Gowin GW-FN-1UR1-10G - -A platform utilizing an Intel Alder Lake-N100 CPU with 6M cache, TDP 6W. -Onboard LPDDR5 16GB RAM and 128GB eMMC (can be used for image installation). - -The appliance comes with 2 * 2.5GbE Intel I226-V and 3 * 1GbE Intel I210 -where one supports IEEE802.3at PoE+ (Typical 30W). - -In addition there is a Mellanox ConnectX-3 2\* 10GbE SFP+ NIC available. - -**NOTE:** This is the entry level platform. Other derivates exists with -i3-N305 CPU and 2x 25GbE! - -### Gowin Shopping Cart - -- 1x Gowin GW-FN-1UR1-10G -- 2x 128GB M.2 NVMe SSDs - -### Optional (WiFi + WWAN) - -- 1x MediaTek 7921E M.2 NGFF WIFI module (not tested as this currently leads to - a Kernel crash) -- 1x HP LT4120 Snapdragon X5 LTE WWAN module - -### Pictures - -:::{figure} ../_static/images/gowin-01.png -::: - -:::{figure} ../_static/images/gowin-02.png -::: - -:::{figure} ../_static/images/gowin-03.png -::: - -:::{figure} ../_static/images/gowin-04.png -::: - -### Cooling - -The device itself is passivly cooled, whereas the power supply has an active fan. -Even if the main processor is powered off, the power supply fan is operating and -the entire chassis draws 7.5W. During operation the chassis drew arround 38W. - -### BIOS Settings - -No settings needed to be altered, everything worked out of the box! - -### Installation - -The system provides a regular RS232 console port using 115200,8n1 setting which -is sufficient to install VyOS from a USB pendrive. - -### First Boot - -Please note that there is a weirdness on the network interface mapping. -The interface \<-> MAC mapping is going upwards but the NICs are placed -somehow swapped on the mainboard/MACs programmed in a swapped order. - -See interface description for more detailed mapping. - -```none -vyos@vyos:~$ show interfaces -Codes: S - State, L - Link, u - Up, D - Down, A - Admin Down -Interface IP Address MAC VRF MTU S/L Description ------------ -------------- ----------------- ------- ----- ----- ------------- -eth0 - 00:f0:cb:00:00:99 default 1500 u/D Intel I226-V - Front eth2 -eth1 - 00:f0:cb:00:00:9a default 1500 u/D Intel I226-V - Front eth1 -eth2 - 00:f0:cb:00:00:9b default 1500 u/D Intel I210 - Front eth4 -eth3 - 00:f0:cb:00:00:9c default 1500 u/D Intel I210 - Front eth3 -eth4 - 00:f0:cb:00:00:9d default 1500 u/D Intel I210 - Front POE -eth5 - 00:02:c9:00:00:30 default 1500 u/D Mellanox ConnectX-3 - SFP2 -eth6 - 00:02:c9:00:00:31 default 1500 u/D Mellanox ConnectX-3 - SFP1 -lo 127.0.0.1/8 00:00:00:00:00:00 default 65536 u/u - ::1/128 -wwan0 - d2:39:76:8e:05:12 default 1500 A/D -``` - -#### VyOS 1.4 (sagitta) - -Connect serial port to a PC through a USB \<-> RJ45 console cable. Set terminal -emulator to 115200 8N1. You can also perform the installation using VGA or HDMI -ports. - -In this example I choose to install VyOS as RAID-1 on both NVMe drives. However, -a previous installation on the 128GB eMMC storage worked without any issues, -too. - -```none -Welcome to VyOS - vyos ttyS0 -vyos login: -``` - -Perform Image installation using `install image` CLI command. This installation -uses two 128GB NVMe disks setup as RAID1. - -```none -Welcome to VyOS! - - ┌── ┐ - . VyOS 1.4.0 - └ ──┘ sagitta - -* Support portal: https://support.vyos.io -* Documentation: https://docs.vyos.io/en/sagitta -* Project news: https://blog.vyos.io -* Bug reports: https://vyos.dev - -You can change this banner using "set system login banner post-login" command. - -VyOS is a free software distribution that includes multiple components, -you can check individual component licenses under /usr/share/doc/*/copyright -Use of this pre-built image is governed by the EULA you can find in -/usr/share/vyos/EULA - -vyos@vyos:~$ install image - -Welcome to VyOS installation! -This command will install VyOS to your permanent storage. -Would you like to continue? [y/N] y - -What would you like to name this image? (Default: 1.4.0) - -Please enter a password for the "vyos" user: -Please confirm password for the "vyos" user: - -What console should be used by default? (K: KVM, S: Serial)? (Default: S) - -Probing disks -4 disk(s) found -Would you like to configure RAID-1 mirroring? [Y/n] y - -The following disks were found: - /dev/sda (14.4 GB) - /dev/mmcblk0 (116.5 GB) -Would you like to configure RAID-1 mirroring on them? [Y/n] n - -Would you like to choose two disks for RAID-1 mirroring? [Y/n] y -Disks available: - 1: /dev/sda (14.4 GB) - 2: /dev/mmcblk0 (116.5 GB) - 3: /dev/nvme1n1 (119.2 GB) - 4: /dev/nvme0n1 (119.2 GB) -Select first disk: 3 - -Remaining disks: - 1: /dev/sda (14.4 GB) - 2: /dev/mmcblk0 (116.5 GB) - 3: /dev/nvme0n1 (119.2 GB) -Select second disk: 3 - -Installation will delete all data on both drives. Continue? [y/N] y - -Searching for data from previous installations -No previous installation found -Creating partitions on /dev/nvme1n1 -Creating partition table... -Creating partitions on /dev/nvme0n1 -Creating partition table... -Creating RAID array -Updating initramfs -Creating filesystem on RAID array -The following config files are available for boot: - 1: /opt/vyatta/etc/config/config.boot - 2: /opt/vyatta/etc/config.boot.default - -Which file would you like as boot config? (Default: 1) -Creating temporary directories -Mounting new partitions -Creating a configuration file -Copying system image files -Installing GRUB configuration files -Installing GRUB to the drives -Cleaning up -Unmounting target filesystems -Removing temporary files -The image installed successfully; please reboot now. -``` - -### Hardware - -```none -vyos@vyos:~$ lspci -00:00.0 Host bridge: Intel Corporation Device 461c -00:02.0 VGA compatible controller: Intel Corporation Alder Lake-N [UHD Graphics] -00:0a.0 Signal processing controller: Intel Corporation Platform Monitoring Technology (rev 01) -00:0d.0 USB controller: Intel Corporation Device 464e -00:14.0 USB controller: Intel Corporation Device 54ed -00:14.2 RAM memory: Intel Corporation Device 54ef -00:15.0 Serial bus controller: Intel Corporation Device 54e8 -00:16.0 Communication controller: Intel Corporation Device 54e0 -00:1a.0 SD Host controller: Intel Corporation Device 54c4 -00:1c.0 PCI bridge: Intel Corporation Device 54b8 -00:1c.2 PCI bridge: Intel Corporation Device 54ba -00:1c.3 PCI bridge: Intel Corporation Device 54bb -00:1c.6 PCI bridge: Intel Corporation Device 54be -00:1d.0 PCI bridge: Intel Corporation Device 54b0 -00:1f.0 ISA bridge: Intel Corporation Device 5481 -00:1f.4 SMBus: Intel Corporation Device 54a3 -00:1f.5 Serial bus controller: Intel Corporation Device 54a4 -01:00.0 PCI bridge: ASMedia Technology Inc. Device 1806 (rev 01) -02:00.0 PCI bridge: ASMedia Technology Inc. Device 1806 (rev 01) -02:02.0 PCI bridge: ASMedia Technology Inc. Device 1806 (rev 01) -02:06.0 PCI bridge: ASMedia Technology Inc. Device 1806 (rev 01) -02:0e.0 PCI bridge: ASMedia Technology Inc. Device 1806 (rev 01) -03:00.0 Ethernet controller: Intel Corporation Ethernet Controller I226-V (rev 04) -04:00.0 Ethernet controller: Intel Corporation Ethernet Controller I226-V (rev 04) -05:00.0 Network controller: MEDIATEK Corp. MT7922 802.11ax PCI Express Wireless Network Adapter -06:00.0 SATA controller: ASMedia Technology Inc. Device 0622 (rev 01) -07:00.0 PCI bridge: ASMedia Technology Inc. Device 1806 (rev 01) -08:00.0 PCI bridge: ASMedia Technology Inc. Device 1806 (rev 01) -08:02.0 PCI bridge: ASMedia Technology Inc. Device 1806 (rev 01) -08:06.0 PCI bridge: ASMedia Technology Inc. Device 1806 (rev 01) -08:0e.0 PCI bridge: ASMedia Technology Inc. Device 1806 (rev 01) -09:00.0 Ethernet controller: Intel Corporation I210 Gigabit Network Connection (rev 03) -0a:00.0 Ethernet controller: Intel Corporation I210 Gigabit Network Connection (rev 03) -0b:00.0 Ethernet controller: Intel Corporation I210 Gigabit Network Connection (rev 03) -0d:00.0 Non-Volatile memory controller: Device 1ed0:2283 -0f:00.0 Non-Volatile memory controller: Device 1ed0:2283 -11:00.0 Ethernet controller: Mellanox Technologies MT27500 Family [ConnectX-3] -``` - -```none -vyos@vyos:~$ lsusb -Bus 004 Device 001: ID 1d6b:0003 Linux Foundation 3.0 root hub -Bus 003 Device 005: ID 0e8d:c616 MediaTek Inc. Wireless_Device -Bus 003 Device 003: ID 413c:2113 Dell Computer Corp. KB216 Wired Keyboard -Bus 003 Device 004: ID 03f0:9d1d HP, Inc HP lt4120 Snapdragon X5 LTE -Bus 003 Device 002: ID 05e3:0610 Genesys Logic, Inc. Hub -Bus 003 Device 001: ID 1d6b:0002 Linux Foundation 2.0 root hub -Bus 002 Device 002: ID 05e3:0620 Genesys Logic, Inc. GL3523 Hub -Bus 002 Device 001: ID 1d6b:0003 Linux Foundation 3.0 root hub -Bus 001 Device 001: ID 1d6b:0002 Linux Foundation 2.0 root hub -``` - -#### WWAN - -The LTE module can be enabled as simple as this config snippet: - -```none -interfaces { - wwan wwan0 { - address "dhcp" - apn "YOUR-APN-GOES-HERE" - } -} -``` - -For more information please refer to chapter: {ref}`wwan-interface` - -[rufus]: https://rufus.ie/ diff --git a/docs/installation/md-index.md b/docs/installation/md-index.md deleted file mode 100644 index 4256aa9b..00000000 --- a/docs/installation/md-index.md +++ /dev/null @@ -1,30 +0,0 @@ ---- -lastproofread: '2026-01-26' ---- - -# Installation and Image Management - -:::{note} -This information applies primarily to virtual installations: - -When installing VyOS, ensure that the MAC address you select for your NICs -is not a locally administered MAC address. Locally administered addresses are -distinguished from universally administered addresses by setting the -second-least-significant bit of the first octet to 1: - -Example: `02:00:00:00:00:01`, where the second-least-significant bit -(`02` in hexadecimal) is set to `1`. -::: - -```{toctree} -:caption: Content -:maxdepth: 2 - -install -virtual/index -cloud/index -bare-metal -update -image -secure-boot -``` diff --git a/docs/installation/md-install.md b/docs/installation/md-install.md deleted file mode 100644 index 789b0ec9..00000000 --- a/docs/installation/md-install.md +++ /dev/null @@ -1,460 +0,0 @@ ---- -lastproofread: '2026-01-26' ---- - -(installation)= - -# Installation - -VyOS installation requires a VyOS .iso file. This file is a live installation -image that you can use to boot a live VyOS system. From there, you can proceed -with a permanent installation on a hard drive or other storage device. - -:::{list-table} Comparison of VyOS image releases -:header-rows: 1 -:widths: 15 35 15 25 15 15 - -* - Release Type - - Description - - Release Cycle - - Intended Use - - Access to Images - - Access to Source - -* - Nightly (Current) - - Automatically built from the current branch. Always up to date - with cutting edge development but guaranteed to contain bugs. - - Every night - - Developing VyOS, testing new features, experimenting. - - Everyone - - Everyone - -* - Stream - - VyOS Stream serves as a technology preview and a quality gate - for the upcoming LTS release. Allows everyone to try new features - and check if they work well or need improvements. - - Every quarter - - Non-critical production environments, preparing for the LTS - release. - - Everyone - - Everyone - -* - Release Candidate - - Rather stable. All development focuses on testing and hunting - down remaining bugs following the feature freeze. - - Irregularly until EPA comes out - - Labs, small offices and non-critical production systems backed - by a high-availability setup. - - Everyone - - Everyone - -* - Early Production Access - - Highly stable with no known bugs. Needs to be tested repeatedly - under different conditions before it can become the final - release. - - Irregularly until LTS comes out - - Non-critical production environments, preparing for the LTS - release. - - Everyone - - Everyone - -* - Long-Term Support - - Guaranteed to be stable and carefully maintained for several - years after the release. No features are introduced but security - updates are released in a timely manner. - - Every major version - - Large-scale enterprise networks, internet service providers, - critical production environments that call for minimum downtime. - - Subscribers, contributors, non-profits, emergency services, - academic institutions - - Subscribers, contributors, non-profits, emergency services, - academic institutions -::: - -## Hardware requirements - -The minimum system requirements for VyOS are 4 GB RAM and 10 GB storage. -Depending on your use case, you might need additional RAM and CPU resources. - -## Download - -### Registered Subscribers - -Registered subscribers can log into <https://support.vyos.io/> to access -a variety of different downloads via the "Downloads" link. These -downloads include LTS (Long-Term Support), the associated hot-fix releases, -early public access releases, pre-built VM images, as well as device -specific installation ISOs. See this [article] for more information on -downloads. - -:::{note} -The `.qcow2` image provided for Proxmox deployment can also be -used to deploy VyOS on KVM environments. This image includes cloud-init -support. See {ref}`cloud-init` for more information. -::: - -:::{figure} /_static/images/vyosnew-downloads.png -::: - -### Building from source - -Subscribers can download the source code for the LTS release from the -"Downloads" link. Non-subscribers can access the source code for the -Rolling release. For instructions, see the {ref}`build` section. The -VyOS source code repository is available at -<https://github.com/vyos/vyos-build>. - -### Rolling Release - -Everyone can download bleeding-edge VyOS rolling images from: -<https://downloads.vyos.io/> - -:::{note} -Rolling releases contain the latest enhancements and fixes. -This means there may be new bugs. If you encounter a bug, follow the -guide at {ref}`bug_report`. We depend on your feedback to improve VyOS. -::: - -The following link contains the most recent VyOS builds for AMD64 -systems from the `current` branch: <https://vyos.net/get/nightly-builds/> - -### Download Verification - -LTS images are signed with the VyOS lead package maintainer's private key. -You can verify the authenticity of the package using the official public key -and Minisign. - -(minisign-verification)= - -#### Minisign verification - -VyOS uses [Minisign](https://github.com/jedisct1/minisign) for release -signing. Minisign is a tool for signing files and verifying signatures. - -OpenBSD introduced signify in 2015. Minisign is an alternative -implementation of the same protocol, available for Windows, macOS, and -most GNU/Linux distributions. Minisign is portable, lightweight, and -uses the Ed25519 public-key signature system. - -{vytask}`T2108` switched the validation system to prefer Minisign over GPG keys. - -To verify a VyOS image starting with VyOS `1.3.0-rc6`, run: - -```none -$ minisign -V -P RWSIhkR/dkM2DSaBRniv/bbbAf8hmDqdbOEmgXkf1RxRoxzodgKcDyGq -m vyos-1.5-rolling-202409250007-generic-amd64.iso vyos-1.5-rolling-202409250007-generic-amd64.iso.minisig - -Signature and comment signature verified -Trusted comment: timestamp:1727223408 file:vyos-1.5-rolling-202409250007-generic-amd64.iso hashed -``` - -During an image upgrade, VyOS runs the following command: - -```none -$ minisign -V -p /usr/share/vyos/keys/vyos-release.minisign.pub -m vyos-1.3.0-rc6-amd64.iso vyos-1.3.0-rc6-amd64.iso.minisig -Signature and comment signature verified -Trusted comment: timestamp:1629997936 file:vyos-1.3.0-rc6-amd64.iso -``` - -:::{note} -Starting with version `1.4.3`, VyOS uses Minisign exclusively. -If you see an unexpected verification error, update your system to version -`1.4.2` first. Support for GnuPG signatures has been -removed ({vytask}`T7301`). -::: - -(live_installation)= - -## Live installation - -:::{note} -To permanently install VyOS, you must first complete a live -installation. -::: - -You can test VyOS without installing it on your hard drive. **Using your -downloaded VyOS .iso file, you can create a bootable USB drive to boot -into a fully functional VyOS system**. After testing it, you can start a -{ref}`permanent_installation` on your hard drive or power off your system -and remove the USB drive. - -If you have a GNU/Linux system, you can create a bootable VyOS USB drive using -the `dd` command: - -1. Open your terminal emulator. - -2. Find the device name of your USB drive (use the `lsblk` command). - -3. Unmount the USB drive. Replace `X` with your device letter and keep the - asterisk (*) to unmount all partitions. - -```none -$ umount /dev/sdX* -``` - -4. Write the image (your VyOS .iso file) to the USB drive. Use the device - name (for example, `/dev/sdb`), not the partition name - (for example, `/dev/sdb1`). - -**Warning**: This will destroy all data on the USB drive! - -```none -# dd if=/path/to/vyos.iso of=/dev/sdX bs=8M; sync -``` - -5. Wait for the operation to complete (bytes copied). On some systems, this - may take more than one minute. - -6. Once `dd` has finished, pull the USB drive out and plug it into - the powered-off computer where you want to install (or test) VyOS. - -7. Power on the computer and ensure it boots from the USB drive - (you may need to select the boot device or change boot settings). - -8. When VyOS finishes loading, sign in using the default credentials - (login: `vyos`, password: `vyos`). - -If you encounter issues with this method, prefer a different operating -system, or want a GUI program, you can use other tools to create a -bootable USB drive, such as [balenaEtcher] (GNU/Linux, macOS, and Windows), -[Rufus] (Windows), and [many others]. Follow their instructions to create -a bootable USB drive from an `.iso` file. - -:::{hint} -The default username and password for the live system is *vyos*. -::: - -(permanent_installation)= - -## Permanent installation - -:::{note} -Before a permanent installation, VyOS requires a -{ref}`live_installation`. -::: - -Unlike general-purpose Linux distributions, VyOS uses "image installation", -which mimics the user experience of traditional hardware routers and allows -you to keep multiple VyOS versions installed simultaneously. This lets you -switch to a previous version if something breaks or misbehaves after an -image upgrade. - -Each version is contained in its own squashfs image mounted in a union -filesystem along with a directory for mutable data such as configurations, -keys, and custom scripts. - -In order to proceed with a permanent installation: - -1. Sign in to the VyOS live system using the default credentials - (login: `vyos`, password: `vyos`). - -2. Run the `install image` command and follow the wizard: - -```none -vyos@vyos:~$ install image -Welcome to VyOS installation! -This command will install VyOS to your permanent storage. -Would you like to continue? [y/N] y -What would you like to name this image? (Default: 2025.09.17-0018-rolling) -Please enter a password for the "vyos" user: -Please confirm password for the "vyos" user: -What console should be used by default? (K: KVM, S: Serial)? (Default: S) -Probing disks -1 disk(s) found -The following disks were found: -Drive: /dev/vda (10.0 GB) -Which one should be used for installation? (Default: /dev/vda) -Installation will delete all data on the drive. Continue? [y/N] y -Searching for data from previous installations -No previous installation found -Would you like to use all the free space on the drive? [Y/n] Y -Creating partition table... -The following config files are available for boot: - 1: /opt/vyatta/etc/config/config.boot - 2: /opt/vyatta/etc/config.boot.default -Which file would you like as boot config? (Default: 1) -Creating temporary directories -Mounting new partitions -Creating a configuration file -Copying system image files -Installing GRUB configuration files -Installing GRUB to the drive -Cleaning up -Unmounting target filesystems -Removing temporary files -The image installed successfully; please reboot now. -``` - -3. After installation completes, remove the live USB drive or CD. - -4. Reboot the system. - -```none -vyos@vyos:~$ reboot -Proceed with reboot? (Yes/No) [No] Yes -``` - -You will boot now into a permanent VyOS system. - -## PXE Boot - -You can also install VyOS using PXE, a more complex installation method that -allows you to deploy VyOS over the network. - -**Requirements** - -- A machine (client) with a PXE-enabled NIC. -- {ref}`dhcp-server` -- {ref}`tftp-server` -- Webserver (HTTP). Optional, but speeds up installation. -- VyOS ISO image (do not use images prior to VyOS `1.2.3`). -- Files *pxelinux.0* and *ldlinux.c32* from the - [Syslinux distribution](https://kernel.org/pub/linux/utils/boot/syslinux/). - -### Configuration - -#### Step 1: DHCP - -Configure a DHCP server to provide the client with: - -- An IP address -- The TFTP server address (DHCP option 66), sometimes referred to as the - *boot server* -- The *bootfile name* (DHCP option 67): *pxelinux.0* - -In this example we configured an existent VyOS as the DHCP server: - -```none -vyos@vyos# show service dhcp-server - shared-network-name mydhcp { - subnet 192.168.1.0/24 { - option { - bootfile-name pxelinux.0 - bootfile-server 192.168.1.50 - default-router 192.168.1.50 - } - range 0 { - start 192.168.1.70 - stop 192.168.1.100 - } - subnet-id 1 - } - } -``` - -(install_from_tftp)= - -#### Step 2: TFTP - -Configure a TFTP server to serve the following: - -- The *pxelinux.0* file from the Syslinux distribution -- The *ldlinux.c32* file from the Syslinux distribution -- The VyOS kernel you want to deploy (*vmlinuz* file from the - */live* directory in the extracted ISO file) -- The VyOS initial ramdisk (*initrd.img* file from the */live* directory - in the extracted ISO file). Do not use an empty (0 bytes) initrd.img - file; the correct file may have a longer name. -- A directory named *pxelinux.cfg* containing the configuration file. - By default, the VyOS configuration file is named [default]. - -In the example you configured your existent VyOS as the TFTP server too: - -```none -vyos@vyos# show service tftp-server - directory /config/tftpboot - listen-address 192.168.1.50 -``` - -Example of the contents of the TFTP server: - -```none -vyos@vyos# ls -hal /config/tftpboot/ -total 29M -drwxr-sr-x 3 tftp tftp 4.0K Oct 14 00:23 . -drwxrwsr-x 9 root vyattacfg 4.0K Oct 18 00:05 .. --r--r--r-- 1 root vyattacfg 25M Oct 13 23:24 initrd.img-4.19.54-amd64-vyos --rwxr-xr-x 1 root vyattacfg 120K Oct 13 23:44 ldlinux.c32 --rw-r--r-- 1 root vyattacfg 46K Oct 13 23:24 pxelinux.0 -drwxr-xr-x 2 root vyattacfg 4.0K Oct 14 01:10 pxelinux.cfg --r--r--r-- 1 root vyattacfg 3.7M Oct 13 23:24 vmlinuz - -vyos@vyos# ls -hal /config/tftpboot/pxelinux.cfg -total 12K -drwxr-xr-x 2 root vyattacfg 4.0K Oct 14 01:10 . -drwxr-sr-x 3 tftp tftp 4.0K Oct 14 00:23 .. --rw-r--r-- 1 root root 191 Oct 14 01:10 default -``` - -Example of simple (no menu) configuration file: - -```none -vyos@vyos# cat /config/tftpboot/pxelinux.cfg/default -DEFAULT VyOS123 - -LABEL VyOS123 - KERNEL vmlinuz - APPEND initrd=initrd.img-4.19.54-amd64-vyos boot=live nopersistence noautologin nonetworking fetch=http://address:8000/filesystem.squashfs -``` - -#### Step 3: HTTP - -You also need to provide the *filesystem.squashfs* file. Because this is a -large file and TFTP is slow, you can send it through HTTP to speed up the -transfer. In our example, we do this—see the configuration file above. - -1. Start a web server. You can use one like - [Python's SimpleHTTPServer] to serve the `filesystem.squashfs` file. - The file is in the `/live` directory of the extracted ISO file. -2. Edit the {ref}`install_from_tftp` configuration file to show the correct - URL: `fetch=http://<address_of_your_HTTP_server>/filesystem.squashfs`. - -:::{note} -Do not rename the *filesystem.squashfs* file. If you're working with -different versions, create different directories instead. -::: - -3. restart the TFTP service. If you're using VyOS as your TFTP server, restart - the service with `sudo service tftpd-hpa restart`. - -:::{note} -Ensure the directories and files on both the TFTP and HTTP servers -have the correct permissions for the booting clients to access them. -::: - -### Client Boot - -Finally, power on your PXE-enabled clients. They will automatically receive an -IP address from the DHCP server and boot into VyOS live using files from the -TFTP and HTTP servers. - -Once finished you will be able to proceed with the `install image` -command as in a regular VyOS installation. - -## Known Issues - -This is a list of known issues that can arise during installation. - -### Black screen on install - -GRUB redirects all output to a serial port to facilitate installation -on headless hosts. On some hardware that lacks a serial port, this causes -a hard lockup and displays a black screen after you select the -`Live system` option from the installation image. - -The workaround is to press `e` when the boot menu appears and edit the -GRUB boot options. Specifically, remove the: - -`console=ttyS0,115200` - -option, and type CTRL-X to boot. - -Installation can then continue as outlined above. - -[article]: https://customers.support.vyos.com/servicedesk/customer/portal/1/article/159055913 -[balenaetcher]: https://www.balena.io/etcher/ -[configuration]: https://wiki.syslinux.org/wiki/index.php?title=Config -[default]: https://wiki.syslinux.org/wiki/index.php?title=PXELINUX#Configuration -[many others]: https://en.wikipedia.org/wiki/List_of_tools_to_create_Live_USB_systems -[python's simplehttpserver]: https://docs.python.org/2/library/simplehttpserver.html -[rufus]: https://rufus.ie/ -[syslinux]: http://www.syslinux.org/ diff --git a/docs/installation/md-secure-boot.md b/docs/installation/md-secure-boot.md deleted file mode 100644 index 3c2013a4..00000000 --- a/docs/installation/md-secure-boot.md +++ /dev/null @@ -1,191 +0,0 @@ ---- -lastproofread: '2026-01-26' ---- - -(secure-boot)= - -# Secure Boot - -Initial UEFI Secure Boot support is available ({vytask}`T861`). VyOS uses -`shim` from Debian 12 (Bookworm), which is properly signed by the UEFI -Secure Boot key from Microsoft. - -:::{note} -There is yet no signed version of `shim` for VyOS, thus we -provide no signed image for secure boot yet. If you are interested in -secure boot you can build an image on your own. -::: - -To generate a custom ISO with your own secure boot keys, run the following -commands prior to your ISO image build: - -```bash -cd vyos-build -CA_DIR="data/certificates" -SHIM_CERT_NAME="vyos-dev-2025-shim" -VYOS_KERNEL_CERT_NAME="vyos-dev-2025-linux" - -openssl req -new -x509 -newkey rsa:4096 -keyout ${CA_DIR}/${SHIM_CERT_NAME}.key -out ${CA_DIR}/${SHIM_CERT_NAME}.der \ - -outform DER -days 36500 -subj "/CN=VyOS Networks Secure Boot CA/" -nodes -openssl x509 -inform der -in ${CA_DIR}/${SHIM_CERT_NAME}.der -out ${CA_DIR}/${SHIM_CERT_NAME}.pem - -openssl req -newkey rsa:4096 -sha256 -nodes -keyout ${CA_DIR}/${VYOS_KERNEL_CERT_NAME}.key \ - -out ${CA_DIR}/${VYOS_KERNEL_CERT_NAME}.csr -outform PEM -days 3650 \ - -subj "/CN=VyOS Networks Secure Boot Signer 2025 - linux/" -openssl x509 -req -in ${CA_DIR}/${VYOS_KERNEL_CERT_NAME}.csr -CA ${CA_DIR}/${SHIM_CERT_NAME}.pem \ - -CAkey ${CA_DIR}/${SHIM_CERT_NAME}.key -CAcreateserial -out ${CA_DIR}/${VYOS_KERNEL_CERT_NAME}.pem -days 3650 -sha256 -``` - -## Installation - -As our version of `shim` is not signed by Microsoft we need to enroll the -previously generated {abbr}`MOK (Machine Owner Key)` to the system. - -First, disable UEFI Secure Boot for the installation. - -:::{figure} /_static/images/uefi_secureboot_01.png -:alt: Disable UEFI secure boot -::: - -Proceed with the standard VyOS {ref}`installation <permanent_installation>` on -your system. Instead of the final `reboot` command, enroll the -{abbr}`MOK (Machine Owner Key)`. - -```none -vyos@vyos:~$ install mok -input password: -input password again: -``` - -You can set the `input password` to any value you choose. You'll need this -password after reboot when MOK Manager launches to permanently install the keys. - -With the next reboot, MOK Manager will automatically launch - -:::{figure} /_static/images/uefi_secureboot_02.png -:alt: Disable UEFI secure boot -::: - -Select `Enroll MOK` - -:::{figure} /_static/images/uefi_secureboot_03.png -:alt: Disable UEFI secure boot -::: - -You can now view the key to be installed and continue with key installation. - -:::{figure} /_static/images/uefi_secureboot_04.png -:alt: Disable UEFI secure boot -::: - -:::{figure} /_static/images/uefi_secureboot_05.png -:alt: Disable UEFI secure boot -::: - -Now you need to enter the password you defined previously. - -:::{figure} /_static/images/uefi_secureboot_06.png -:alt: Disable UEFI secure boot -::: - -Now reboot and re-enable UEFI Secure Boot. - -:::{figure} /_static/images/uefi_secureboot_07.png -:alt: Disable UEFI secure boot -::: - -VyOS will now launch in UEFI Secure Boot mode. You can verify this by running -one of the following commands: - -```none -vyos@vyos:~$ show secure-boot -SecureBoot enabled -``` - -```none -vyos@vyos:~$ show log kernel | match Secure -Oct 08 19:15:41 kernel: Secure boot enabled -``` - -```none -vyos@vyos:~$ show version -Version: VyOS 1.5-secureboot -Release train: current -Release flavor: generic - -Built by: autobuild@vyos.net -Built on: Tue 08 Oct 2024 18:00 UTC -Build UUID: 5702ca38-e6f4-470f-b89e-ffc29baee474 -Build commit ID: 9eb61d3b6cf426 - -Architecture: x86_64 -Boot via: installed image -System type: KVM guest -Secure Boot: enabled <-- UEFI secure boot indicator - -Hardware vendor: QEMU -Hardware model: Standard PC (i440FX + PIIX, 1996) -Hardware S/N: -Hardware UUID: 1f6e7f5c-fb52-4c33-96c9-782fbea36436 - -Copyright: VyOS maintainers and contributors -``` - -## Image Update - -:::{note} -Currently, there is no signed version of `shim` for VyOS. If you -want Secure Boot support, you can build a custom image with your own keys. -::: - -During image installation, you install your {abbr}`MOK (Machine Owner Key)` -into the UEFI variables to add trust to this key. After you re-enable Secure -Boot in UEFI, you can only boot into your signed image. - -You can no longer boot into a CI-generated rolling release because those -are not signed by a trusted party ({vytask}`T861` work in progress). This -also means you must sign all successor builds with the same key; otherwise, -you'll see this error: - -```none -error: bad shim signature -error: you need to load the kernel first -``` - -## Linux Kernel - -In addition to Secure Boot support, VyOS uses ephemeral key signing of Linux -Kernel modules for an extra security layer in both Secure and non-Secure boot -images. - -<https://patchwork.kernel.org/project/linux-integrity/patch/20210218220011.67625-5-nayna@linux.ibm.com/> - -When the CI system builds a Kernel package and required third-party modules, -it generates a temporary (ephemeral) key pair for signing the modules. The -public key is embedded in the Kernel binary to verify loaded modules. - -After the Kernel CI build completes, the generated key is discarded, meaning -we can no longer sign additional modules with that key. The Kernel configuration -also includes the option `CONFIG_MODULE_SIG_FORCE=y`, which enforces signature -verification for all modules. If you try to load an unsigned module, you'll -get this error: - -`insmod: ERROR: could not insert module malicious.ko: Key was rejected by -service` - -This prevents loading any malicious code after the image is assembled into the -Kernel as a module. You can disable this behavior on custom builds if needed. - -## Troubleshoot - -In most cases, if something goes wrong during system boot, you'll see this -error message: - -```none -error: bad shim signature -error: you need to load the kernel first -``` - -This error means the Machine Owner Key used to sign the Kernel is not trusted -by your UEFI. Install the MOK using the `install mok` command as described -above. diff --git a/docs/installation/virtual/md-docker.md b/docs/installation/virtual/md-docker.md deleted file mode 100644 index 901483bb..00000000 --- a/docs/installation/virtual/md-docker.md +++ /dev/null @@ -1,70 +0,0 @@ ---- -lastproofread: '2026-02-02' ---- - -(docker)= - -# Run VyOS in a Docker Container - -Docker is an open-source project for deploying applications as standardized -units called containers. Deploying VyOS in a container provides a simple and -lightweight mechanism for both testing and packet routing for container -workloads. - -## IPv6 support for Docker - -VyOS requires an IPv6-enabled Docker network. Currently Linux distributions -do not enable Docker IPv6 support by default. You can enable IPv6 support in -two ways. - -### Method 1: Create a docker network with IPv6 support - -Here's an example using the `macvlan` driver. - -```none -docker network create --ipv6 -d macvlan -o parent=eth0 --subnet 2001:db8::/64 --subnet 192.0.2.0/24 mynet -``` - -### Method 2: Add IPv6 support to the Docker daemon - -Edit /etc/docker/daemon.json to set the `ipv6` key to `true` and specify -the `fixed-cidr-v6` to your desired IPv6 subnet. - -```none -{ - "ipv6": true, - "fixed-cidr-v6": "2001:db8::/64" -} -``` - -Reload the Docker configuration. - -```none -$ sudo systemctl reload docker -``` - -## Deploy container from ISO - -Download the ISO you want to base the container on. In this example, -the ISO is `vyos-1.4-rolling-202308240020-amd64.iso`. If you -created a custom IPv6-enabled network, include it as the `--net` parameter -to `docker run`. - -```none -$ mkdir vyos && cd vyos -$ curl -o vyos-1.4-rolling-202308240020-amd64.iso https://github.com/vyos/vyos-rolling-nightly-builds/releases/download/1.4-rolling-202308240020/vyos-1.4-rolling-202308240020-amd64.iso -$ mkdir rootfs -$ sudo mount -o loop vyos-1.4-rolling-202308240020-amd64.iso rootfs -$ sudo apt-get install -y squashfs-tools -$ mkdir unsquashfs -$ sudo unsquashfs -f -d unsquashfs/ rootfs/live/filesystem.squashfs -$ sudo tar -C unsquashfs -c . | docker import - vyos:1.4-rolling-202111281249 -$ sudo umount rootfs -$ cd .. -$ sudo rm -rf vyos -$ docker run -d --rm --name vyos --privileged -v /lib/modules:/lib/modules \ -> vyos:1.4-rolling-202111281249 /sbin/init -$ docker exec -ti vyos su - vyos -``` - -To stop the container, run `docker stop vyos`. diff --git a/docs/installation/virtual/md-eve-ng.md b/docs/installation/virtual/md-eve-ng.md deleted file mode 100644 index 1ee1c016..00000000 --- a/docs/installation/virtual/md-eve-ng.md +++ /dev/null @@ -1,14 +0,0 @@ ---- -lastproofread: '2026-02-02' ---- - -# EVE-NG - -:::{note} -This page is a stub and needs expansion. Contributions -welcome via the [VyOS documentation repository](https://github.com/vyos/vyos-documentation). -::: - -## References - -<https://www.eve-ng.net/> diff --git a/docs/installation/virtual/md-gns3.md b/docs/installation/virtual/md-gns3.md deleted file mode 100644 index aeac7bbf..00000000 --- a/docs/installation/virtual/md-gns3.md +++ /dev/null @@ -1,191 +0,0 @@ ---- -lastproofread: '2026-02-02' ---- - -(vyos-on-gns3)= - -# Run VyOS on GNS3 - -You may want to test VyOS in a lab environment. -[GNS3](http://www.gns3.com) is a network emulation software that you -can use for this purpose. - -This guide will provide the necessary steps for installing -and setting up VyOS on GNS3. - -## Requirements - -The following items are required: - -- A VyOS installation image (.iso file). You - can find how to get it on the {ref}`installation` page -- A working GNS3 installation. For further information see the - [GNS3 documentation](https://docs.gns3.com/). - -(vm-setup)= - -## VM setup - -First, a virtual machine (VM) for the VyOS installation must be created -in GNS3. - -Go to the GNS3 **File** menu, click **New template**, and select -**Manually create a new Template**. - -:::{figure} /_static/images/gns3-01.png -::: - -Select **Qemu VMs** and then click the `New` button. - -:::{figure} /_static/images/gns3-02.png -::: - -Write a name for your VM, such as "VyOS", and click `Next`. - -:::{figure} /_static/images/gns3-03.png -::: - -Select **qemu-system-x86_64** as Quemu binary, then **512MB** of RAM -and click `Next`. - -:::{figure} /_static/images/gns3-04.png -::: - -Select **telnet** as your console type and click `Next`. - -:::{figure} /_static/images/gns3-05.png -::: - -Select **New image** for the base disk image of your VM and click -`Create`. - -:::{figure} /_static/images/gns3-06.png -::: - -Use the defaults in the **Binary and format** window and click -`Next`. - -:::{figure} /_static/images/gns3-07.png -::: - -Use the defaults in the **Qcow2 options** window and click `Next`. - -:::{figure} /_static/images/gns3-08.png -::: - -Set the disk size to 2000 MiB, and click `Finish` to end the **Quemu -image creator**. - -:::{figure} /_static/images/gns3-09.png -::: - -Click `Finish` to end the **New QEMU VM template** wizard. - -:::{figure} /_static/images/gns3-10.png -::: - -Now you need to edit the VM settings. - -In the **Preferences** window, with **Qemu VMs** selected and your new VM -selected, click the `Edit` button. - -:::{figure} /_static/images/gns3-11.png -::: - -In the **General settings** tab of your **QEMU VM template -configuration**, do the following: - -- Click on the `Browse...` button to choose the **Symbol** you want to - have representing your VM. -- In **Category** select in which group you want to find your VM. -- Set the **Boot priority** to **CD/DVD-ROM**. - -:::{figure} /_static/images/gns3-12.png -::: - -At the **HDD** tab, change the Disk interface to **sata** to speed up -the boot process. - -:::{figure} /_static/images/gns3-13.png -::: - -At the **CD/DVD** tab click on `Browse...` and locate the VyOS image -you want to install. - -:::{figure} /_static/images/gns3-14.png -::: - -:::{note} -You probably will want to accept to copy the .iso file to your -default image directory when you are asked. -::: - -In the **Network** tab, set the number of adapters to **0**, set the -**Name format** to **eth\{0}**, and set the **Type** to **Paravirtualized -Network I/O (virtio-net-pci)**. - -:::{figure} /_static/images/gns3-15.png -::: - -In the **Advanced** tab, unmark the checkbox **Use as a linked base -VM** and click `OK`, which will save and close the **QEMU VM template -configuration** window. - -:::{figure} /_static/images/gns3-16.png -::: - -At the general **Preferences** window, click `OK` to save and close. - -:::{figure} /_static/images/gns3-17.png -::: - -(vyos-installation)= - -## VyOS installation - -- Create a new project. -- Drag the newly created VyOS VM into it. -- Start the VM. -- Open a console. - The console displays the system booting. It prompts for login - credentials. You're now at the VyOS live system. -- {ref}`Install VyOS <installation>` - as normal (that is, using the `install image` command). -- After successful installation, shut down the VM with the `poweroff` - command. -- **Delete the VM** from the GNS3 project. - -The *VyOS-hda.qcow2* file now contains a working VyOS image and can be -used as a template. But it still needs some fixes before we can deploy -VyOS in our labs. - -(vyos-vm-configuration)= - -## VyOS VM configuration - -To turn the template into a working VyOS machine, further steps are -necessary as outlined below: - -**General settings** tab: Set the boot priority to **HDD** - -:::{figure} /_static/images/gns3-20.png -::: - -**CD/DVD** tab: Clear the **Image** entry field to unmount the installation -image. - -:::{figure} /_static/images/gns3-21.png -::: - -Set the number of required network adapters. For example, set it to **4**. - -:::{figure} /_static/images/gns3-215.png -::: - -**Advanced** settings tab: Check the **Use as a linked -base VM** checkbox and click `OK` to save the changes. - -:::{figure} /_static/images/gns3-22.png -::: - -The VyOS VM is now ready to be deployed. diff --git a/docs/installation/virtual/md-proxmox.md b/docs/installation/virtual/md-proxmox.md deleted file mode 100644 index 0eddc2c7..00000000 --- a/docs/installation/virtual/md-proxmox.md +++ /dev/null @@ -1,62 +0,0 @@ ---- -lastproofread: '2026-02-02' ---- - -(proxmox)= - -# Running on Proxmox - -Proxmox is an open-source platform for virtualization. Visit -<https://vyos.io> to download a `.qcow2` image that you can import into -Proxmox. - -## Deploy VyOS from CLI with qcow2 image - -1. Copy the `.qcow2` image to a temporary directory on the Proxmox server. -2. The commands assume virtual machine ID 200 is unused and you want - the disk stored in a storage pool named `local-lvm`. - -```none -$ qm create 200 --name vyos2 --memory 2048 --net0 virtio,bridge=vmbr0 -$ qm importdisk 200 /path/to/image/vyos-1.2.8-proxmox-2G.qcow2 local-lvm -$ qm set 200 --virtio0 local-lvm:vm-200-disk-0 -$ qm set 200 --boot order=virtio0 -``` - -3. You can optionally attach a CDROM with an ISO as a cloud-init data - source. The command assumes the ISO is uploaded to the `local` - storage pool as `seed.iso`. - -```none -$ qm set 200 --ide2 media=cdrom,file=local:iso/seed.iso -``` - -4. Start the virtual machine using the Proxmox GUI or run `qm start 200`. - -## Deploy VyOS from CLI with rolling release ISO - -1. Download the rolling release ISO from - <https://vyos.net/get/nightly-builds/>. Non-subscribers can use the - LTS release by building from source. For instructions, see the - {ref}`build` section. The VyOS source code repository - is available at <https://github.com/vyos/vyos-build>. -2. Prepare the VM for ISO installation. The commands assume your ISO is - in storage pool 'local', you want VM ID '200', and you want to create - a new 15GB disk on storage pool 'local-lvm'. - -```none -qm create 200 --name vyos --memory 2048 --net0 virtio,bridge=vmbr0 --ide2 media=cdrom,file=local:iso/live-image-amd64.hybrid.iso --virtio0 local-lvm:15 -``` - -3. Start the VM using `qm start 200` or the start button in the - Proxmox GUI. -4. Open the virtual console for your VM using the Proxmox web GUI. - Login username and password are both `vyos`. -5. Once booted into the live system, type `install image` and follow - the prompts to install VyOS to the virtual drive. -6. After installation completes, remove the installation ISO using the - GUI or run `qm set 200 --ide2 none`. -7. Reboot the virtual machine using the GUI or run `qm reboot 200`. - -For more information about downloading and installing Proxmox, visit -<https://www.proxmox.com/en/>. diff --git a/docs/installation/virtual/md-vmware.md b/docs/installation/virtual/md-vmware.md deleted file mode 100644 index 34fb2197..00000000 --- a/docs/installation/virtual/md-vmware.md +++ /dev/null @@ -1,38 +0,0 @@ ---- -lastproofread: '2026-02-02' ---- - -(vyosonvmware)= - -# Running on VMware ESXi - -## ESXi 5.5 or later - -`.ova` files are available for supporting users. You can also set up VyOS -using a generic Linux instance by attaching the bootable ISO file and -installing using the `install image` command. - -:::{NOTE} -Previous issues have been documented with GRE/IPSEC tunneling -using the E1000 adapter on VyOS guests. Use the VMXNET3 adapter instead. -::: - -### Memory Contention Considerations - -When the underlying ESXi host reaches approximately 92% memory utilization, -it begins the balloon process to reclaim memory from guest operating systems. -This creates artificial memory pressure through the `vmmemctl` driver. Because -VyOS does not have a swap file by default, this pressure cannot move memory -data to a paging file. Instead, it consumes memory and forces the guest into -a low memory state with no recovery option. The balloon can expand to 65% of -guest allocated memory, so a VyOS guest using more than 35% of memory can -encounter an out-of-memory situation and trigger the kernel `oom_kill` -process. The `oom_kill` process then terminates memory-hungry processes. - -To prevent ballooning, configure VyOS routers in a resource group with -adequate memory reservations. - -### References - -<https://muralidba.blogspot.com/2018/03/how-does-linux-out-of-memory-oom-killer.html> - diff --git a/docs/introducing/md-about.md b/docs/introducing/md-about.md deleted file mode 100644 index ec4ff30d..00000000 --- a/docs/introducing/md-about.md +++ /dev/null @@ -1,21 +0,0 @@ -(about)= - -# About - -VyOS is an open-source network operating system that provides a single unified -CLI and API to manage routing protocols, firewall and NAT, QoS, load balancing, -DHCP and DNS servers, and many other features. - -VyOS runs on a wide variety of commodity hardware, virtual machines, and -multiple cloud environments. - -We provide a dedicated user guide for each major -VyOS release that receives long-term support (LTS). We maintain multiple user -guide versions, all hosted at <https://docs.vyos.io>. -To switch between versions, select the appropriate version in the bottom-right -corner. - -VyOS CLI syntax may vary between major and sometimes minor releases. Always -refer to the documentation matching your current running installation. If -a change in the CLI is required, VyOS provides a migration script to handle -the syntax adjustments. No user action is required. diff --git a/docs/introducing/md-history.md b/docs/introducing/md-history.md deleted file mode 100644 index 190ee20c..00000000 --- a/docs/introducing/md-history.md +++ /dev/null @@ -1,127 +0,0 @@ -(history)= - -# History - -## In the beginning... - -There was a network operating system based on Debian GNU/Linux, called -Vyatta. :sup:`\*` Introduced in 2006, it served as a great free-software alternative -to proprietary products. Vyatta came in two editions: Vyatta Core -(formerly known as Vyatta Community Edition), which was free software, and -Vyatta Subscription Edition, which included proprietary features and was -available only to paying customers. - -Brocade Communications Systems acquired Vyatta in 2012. Shortly after, Brocade -renamed Vyatta Subscription Edition to Brocade vRouter, discontinued Vyatta -Core, and shut down the community forum without notice. The bug tracker and Git -repositories were closed the following year. - -By the time Brocade acquired Vyatta, the development of Vyatta Core had -already stagnated. The focus had shifted to Vyatta Subscription Edition, -where core components were replaced with proprietary software. As a result, -Vyatta Core received fewer new features, and some of those added faced issues. - -In 2013, shortly after Vyatta Core was discontinued, the community forked its -final version (6.6R1) to create the VyOS project. In 2014, the maintainers -established a company to fund VyOS development through technical support, -consulting services, and LTS release access subscriptions. The company was -originally named Sentrium and was later reorganized under the VyOS brand. - -## Major releases - -VyOS originally named its major versions after elements by atomic number. -Beginning with version 1.2, this naming scheme was changed. It now uses the -Latin names of constellations recognized by the International Astronomical -Union ([IAU](https://en.wikipedia.org/wiki/IAU_designated_constellations_by_area)), -ordered by their solid angle area, beginning with the smallest. - -### Hydrogen (1.0) - -Released just in time for the holidays on 22 December 2013, Hydrogen was -the first major VyOS release. It fixed features that were broken in -Vyatta Core 6.6, such as IPv4 BGP peer groups and DHCPv6 relay, and -introduced command scripting, a task scheduler, and web proxy LDAP -authentication. - -### Helium (1.1) - -Helium, released on 9 October 2014, marked the first anniversary of the -VyOS Project. The release introduced an event handler, L2TPv3 support, -802.1ad (QinQ), and IGMP proxy, as well as experimental support for VXLAN -and DMVPN. Notably, DMVPN remained non-functional in Vyatta Core due to its -reliance on a proprietary NHRP implementation. - -### Crux (1.2) - -Crux (the Southern Cross) was released on 28 January 2019 and marked a -departure from legacy Vyatta codebase and the start of the migration from -Perl to Python as the primary language. The underlying base system was -upgraded from Debian 6 (Squeeze) to Debian 8 (Jessie). - -Crux introduced many new features, some of the most noteworthy are: -an mDNS repeater, a broadcast relay, a high-performance PPPoE server, -an HFSC scheduler, and support for Wireguard, unicast VRRP, RPKI for BGP, -and fully 802.1ad-compliant QinQ ethertype. The telnet server and support -for P2P filtering were removed. - -Crux was the first VyOS release to feature a modular image build system. -CLI definitions were written using an XML syntax automatically checked -against a schema at build time. Python APIs were introduced for command -scripting and configuration migration. New Perl code and old-style (non-XML) -command definition were no longer accepted from that point. - -Crux reached the end of support in 2023. - -### Equuleus (1.3) - -Equuleus (the Little Horse) was a long-term support version released -on 21 December 2021, just in time for the winter holidays. - -Equuleus brought many long-awaited features, most notably an SSTP VPN -server, an IPoE server, an OpenConnect VPN server, and a serial console -server. It also introduced reworked support for WWAN interfaces, support -for GENEVE and MACSec interfaces, VRF, IS-IS routing, and preliminary support -for MPLS and LDP. - -Equuleus reached the end of support in 2025. - -### Sagitta (1.4) - -Sagitta (the Arrow), the current LTS release, became generally available on -4 June 2024. Its development began in late 2021 and focused on eliminating -remaining legacy components and reworking core subsystems. - -The transition to XML-defined command definitions and script refactoring with -separate verify, update, and apply stages were completed. The firewall -subsystem was rebuilt on nftables, introducing interface-independent rulesets -and the reimplemented zone-based firewall model. The PKI subsystem was -redesigned to manage cryptographic material directly within the configuration -file. - -Sagitta introduced rollback without reboot, support for Babel and PIM6 routing -protocols, failover routes, segment routing, NAT64, an IKEv2 remote-access VPN -server, Zabbix monitoring, HTTP load balancing, and configuration -synchronization using the HTTP API. - -The underlying base system was upgraded to Debian 12 (Bookworm). - -### Circinus (1.5) - -Circinus (the Drawing Compass) is the codename for the upcoming development -branch. VyOS 1.5 Circinus has not been released yet. - -## A note on copyright - -Unlike Vyatta, VyOS has never had closed-source code and never will. -The only proprietary material in VyOS is non-code assets, such as -graphics and the trademark "VyOS". :sup:`†` - -Note that we do not provide support for images distributed by a third party. -See the -[artwork license](https://github.com/vyos/vyos-build/blob/current/LICENSE.artwork) -and the end-user license agreement at `/usr/share/vyos/EULA` in -any pre-built image for more information. - -[\*] From the Sanskrit adjective "Vyātta" (व्यात्त), meaning opened. - -[†] This is similar to how Linus Torvalds owns the Linux trademark. diff --git a/docs/md-404.md b/docs/md-404.md deleted file mode 100644 index f5530747..00000000 --- a/docs/md-404.md +++ /dev/null @@ -1,13 +0,0 @@ ---- -orphan: true ---- - -# Page Not Found - -Sorry, we could not find a page. -Try using the search box or go to the release homepage: - -- [1.2.x (crux)](https://docs.vyos.io/en/crux/) -- [1.3.x (equuleus)](https://docs.vyos.io/en/equuleus/) -- [1.4.x (sagitta)](https://docs.vyos.io/en/sagitta/) -- [rolling release (circinus)](https://docs.vyos.io/en/latest/) diff --git a/docs/md-index.md b/docs/md-index.md deleted file mode 100644 index 359fea44..00000000 --- a/docs/md-index.md +++ /dev/null @@ -1,113 +0,0 @@ -(index)= - -# VyOS User Guide - -::::::{grid} 3 -:gutter: 2 - -:::::{grid-item-card} Get / Build VyOS - -Quickly {ref}`Build<contributing/build-vyos:build vyos>` -your own Image or take a look at how to -{ref}`download<installation/install:download>` -a free or supported version. -::::: - -:::::{grid-item-card} Install VyOS - -Read about how to install VyOS on -{ref}`Bare Metal<installation/install:installation>` -or in a {ref}`VM <installation/virtual/index:Virtual Environments>` -and how to use an image with the usual -{ref}`cloud<installation/cloud/index:Cloud Environments>` -providers -::::: - -:::::{grid-item-card} Configuration and Operation - -Use the {ref}`Quickstart Guide<quick-start:Quick Start>`, -to have a fast overview. Or go deeper and set up -{ref}`advanced routing<configuration/protocols/index:protocols>`, -{ref}`VRFs<configuration/vrf/index:vrf>`, or -{ref}`VPNs<configuration/vpn/index:vpn>` for example. -::::: - -:::::{grid-item-card} Automate - -Integrate VyOS in your automation Workflow with -{ref}`Ansible<vyos-ansible>`, -have your own {ref}`local scripts<command-scripting>`, -or configure VyOS with the -{ref}`HTTPS-API<vyosapi>`. -::::: - -:::::{grid-item-card} Examples - -Get some inspiration from the -{ref}`Blueprints <configexamples/index:Configuration Blueprints>` -to build your infrastructure. -::::: - -:::::{grid-item-card} Contribute and Community - -There are many ways to contribute to the project. -Add missing parts or improve the -{ref}`Documentation<documentation:Write Documentation>`. - -Discuss in [Slack](https://slack.vyos.io/) -or the [Forum](https://forum.vyos.io). - -Or you can pick up a [Task](https://vyos.dev/) -and fix the -{ref}`code<contributing/development:development>`. -::::: -:::::: - -```{toctree} -:hidden: true -:maxdepth: 1 - -introducing/about -introducing/history -``` - -```{toctree} -:caption: First Steps -:hidden: true -:maxdepth: 2 - -installation/index -quick-start -cli -``` - -```{toctree} -:caption: Adminguide -:hidden: true -:maxdepth: 2 - -configuration/index -operation/index -automation/index -troubleshooting/index -configexamples/index -vpp/index -``` - -```{toctree} -:caption: Development -:hidden: true -:maxdepth: 2 - -contributing/index -``` - -```{toctree} -:caption: Misc -:hidden: true -:maxdepth: 2 - -documentation -coverage -copyright -``` diff --git a/docs/md-quick-start.md b/docs/md-quick-start.md deleted file mode 100644 index 8fac2f68..00000000 --- a/docs/md-quick-start.md +++ /dev/null @@ -1,369 +0,0 @@ -(quick-start)= - -# Quick Start - -This chapter will guide you on how to get up to speed quickly using your new -VyOS system. It will show you a very basic configuration example that will -provide a {ref}`nat` gateway for a device with two network interfaces -(`eth0` and `eth1`). - -(quick-start-configuration-mode)= - -## Configuration Mode - -By default, VyOS is in operational mode, and the command prompt displays -a `$`. To configure VyOS, you will need to enter configuration mode, resulting -in the command prompt displaying a `#`, as demonstrated below: - -```none -vyos@vyos$ configure -vyos@vyos# -``` - -## Commit and Save - -After every configuration change, you need to apply the changes by using the -following command: - -```none -commit -``` - -Once your configuration works as expected, you can save it permanently by using -the following command: - -```none -save -``` - -## Interface Configuration - -- Your outside/WAN interface will be `eth0`. It will receive its interface - address via DHCP. -- Your internal/LAN interface will be `eth1`. It will use a static IP address - of `192.168.0.1/24`. - -After switching to {ref}`quick-start-configuration-mode` issue the following -commands: - -```none -set interfaces ethernet eth0 address dhcp -set interfaces ethernet eth0 description 'OUTSIDE' -set interfaces ethernet eth1 address '192.168.0.1/24' -set interfaces ethernet eth1 description 'LAN' -``` - -## SSH Management - -After switching to {ref}`quick-start-configuration-mode` issue the following -commands, and your system will listen on every interface for incoming SSH -connections. You might want to check the {ref}`ssh` chapter on how to listen -on specific addresses only. - -```none -set service ssh port '22' -``` - -(dhcp-dns-quick-start)= - -## DHCP/DNS quick-start - -The following settings will configure DHCP and DNS services on -your internal/LAN network, where VyOS will act as the default gateway and -DNS server. - -- The default gateway and DNS recursor address will be `192.168.0.1/24` -- The address range `192.168.0.2/24 - 192.168.0.8/24` will be reserved for - static assignments -- DHCP clients will be assigned IP addresses within the range of - `192.168.0.9 - 192.168.0.254` and have a domain name of `internal-network` -- DHCP leases will hold for one day (86400 seconds) -- VyOS will serve as a full DNS recursor, replacing the need to utilize Google, - Cloudflare, or other public DNS servers (which is good for privacy) -- Only hosts from your internal/LAN network can use the DNS recursor - -```none -set service dhcp-server shared-network-name LAN subnet 192.168.0.0/24 option default-router '192.168.0.1' -set service dhcp-server shared-network-name LAN subnet 192.168.0.0/24 option name-server '192.168.0.1' -set service dhcp-server shared-network-name LAN subnet 192.168.0.0/24 option domain-name 'vyos.net' -set service dhcp-server shared-network-name LAN subnet 192.168.0.0/24 lease '86400' -set service dhcp-server shared-network-name LAN subnet 192.168.0.0/24 range 0 start '192.168.0.9' -set service dhcp-server shared-network-name LAN subnet 192.168.0.0/24 range 0 stop '192.168.0.254' -set service dhcp-server shared-network-name LAN subnet 192.168.0.0/24 subnet-id '1' - -set service dns forwarding cache-size '0' -set service dns forwarding listen-address '192.168.0.1' -set service dns forwarding allow-from '192.168.0.0/24' -``` - -## NAT - -The following settings will configure {ref}`source-nat` rules for our -internal/LAN network, allowing hosts to communicate through the outside/WAN -network via IP masquerade. - -```none -set nat source rule 100 outbound-interface name 'eth0' -set nat source rule 100 source address '192.168.0.0/24' -set nat source rule 100 translation address masquerade -``` - -## Firewall - -A new firewall structure—which uses the `nftables` backend, rather -than `iptables`—is available on all installations starting from -VyOS `1.4-rolling-202308040557`. The firewall supports creation of distinct, -interlinked chains for each [Netfilter hook](https://wiki.nftables.org/wiki-nftables/index.php/Netfilter_hooks) -and allows for more granular control over the packet filtering process. - -The firewall begins with the base `filter` tables you define for each of the -`forward`, `input`, and `output` Netfiter hooks. Each of these tables is -populated with rules that are processed in order and can jump to other chains -for more granular filtering. - -### Configure Firewall Groups - -To make firewall configuration easier, we can create groups of interfaces, -networks, addresses, ports, and domains that describe different parts of -our network. We can then use them for filtering within our firewall rulesets, -allowing for more concise and readable configuration. - -In this case, we will create two interface groups — a `WAN` group for our -interfaces connected to the public internet and a `LAN` group for the -interfaces connected to our internal network. Additionally, we will create a -network group, `NET-INSIDE-v4`, that contains our internal subnet. - -```none -set firewall group interface-group WAN interface eth0 -set firewall group interface-group LAN interface eth1 -set firewall group network-group NET-INSIDE-v4 network '192.168.0.0/24' -``` - -### Configure Stateful Packet Filtering - -With the new firewall structure, we have have a lot of flexibility in how we -group and order our rules, as shown by the three alternative approaches below. - -#### Option 1: Global State Policies - -Using options defined in `set firewall global-options state-policy`, state -policy rules that applies for both IPv4 and IPv6 are created. These global -state policies also applies for all traffic that passes through the router -(transit) and for traffic originated/destinated to/from the router itself, and -will be evaluated before any other rule defined in the firewall. - -Most installations would choose this option, and will contain: - -```none -set firewall global-options state-policy established action accept -set firewall global-options state-policy related action accept -set firewall global-options state-policy invalid action drop -``` - -#### Option 2: Common/Custom Chain - -We can create a common chain for stateful connection filtering of multiple -interfaces (or multiple netfilter hooks on one interface). Those individual -chains can then jump to the common chain for stateful connection filtering, -returning to the original chain for further rule processing if no action is -taken on the packet. - -The chain we will create is called `CONN_FILTER` and has three rules: - -- A default action of `return`, which returns the packet back to the original - chain if no action is taken. -- A rule to `accept` packets from established and related connections. -- A rule to `drop` packets from invalid connections. - -```none -set firewall ipv4 name CONN_FILTER default-action 'return' - -set firewall ipv4 name CONN_FILTER rule 10 action 'accept' -set firewall ipv4 name CONN_FILTER rule 10 state established -set firewall ipv4 name CONN_FILTER rule 10 state related - -set firewall ipv4 name CONN_FILTER rule 20 action 'drop' -set firewall ipv4 name CONN_FILTER rule 20 state invalid -``` - -Then, we can jump to the common chain from both the `forward` and `input` -hooks as the first filtering rule in the respective chains: - -```none -set firewall ipv4 forward filter rule 10 action 'jump' -set firewall ipv4 forward filter rule 10 jump-target CONN_FILTER - -set firewall ipv4 input filter rule 10 action 'jump' -set firewall ipv4 input filter rule 10 jump-target CONN_FILTER -``` - -#### Option 3: Per-Hook Chain - -Alternatively, you can take the more traditional stateful connection -filtering approach by creating rules on each base hook's chain: - -```none -set firewall ipv4 forward filter rule 5 action 'accept' -set firewall ipv4 forward filter rule 5 state established -set firewall ipv4 forward filter rule 5 state related -set firewall ipv4 forward filter rule 10 action 'drop' -set firewall ipv4 forward filter rule 10 state invalid - -set firewall ipv4 input filter rule 5 action 'accept' -set firewall ipv4 input filter rule 5 state established -set firewall ipv4 input filter rule 5 state related -set firewall ipv4 input filter rule 10 action 'drop' -set firewall ipv4 input filter rule 10 state invalid -``` - -### Block Incoming Traffic - -Now that we have configured stateful connection filtering to allow traffic from -established and related connections, we can block all other incoming traffic -addressed to our local network. - -Create a new chain (`OUTSIDE-IN`) which will drop all traffic that is not -explicitly allowed at some point in the chain. Then, we can jump to that chain -from the `forward` hook when traffic is coming from the `WAN` interface -group and is addressed to our local network. - -```none -set firewall ipv4 name OUTSIDE-IN default-action 'drop' - -set firewall ipv4 forward filter rule 100 action jump -set firewall ipv4 forward filter rule 100 jump-target OUTSIDE-IN -set firewall ipv4 forward filter rule 100 inbound-interface group WAN -set firewall ipv4 forward filter rule 100 destination group network-group NET-INSIDE-v4 -``` - -We should also block all traffic destinated to the router itself that isn't -explicitly allowed at some point in the chain for the `input` hook. As -we've already configured stateful packet filtering above, we only need to -set the default action to `drop`: - -```none -set firewall ipv4 input filter default-action 'drop' -``` - -### Allow Management Access - -We can now configure access to the router itself, allowing SSH -access from the inside/LAN network and rate limiting SSH access from the -outside/WAN network. - -First, create a new dedicated chain (`VyOS_MANAGEMENT`) for management -access, which returns to the parent chain if no action is taken. Add a rule -to accept traffic from the `LAN` interface group: - -```none -set firewall ipv4 name VyOS_MANAGEMENT default-action 'return' -``` - -Configure a rule on the `input` hook filter to jump to the `VyOS_MANAGEMENT` -chain when new connections are addressed to port 22 (SSH) on the router itself: - -```none -set firewall ipv4 input filter rule 20 action jump -set firewall ipv4 input filter rule 20 jump-target VyOS_MANAGEMENT -set firewall ipv4 input filter rule 20 destination port 22 -set firewall ipv4 input filter rule 20 protocol tcp -``` - -Finally, configure the `VyOS_MANAGEMENT` chain to accept connection from the -`LAN` interface group while limiting requests coming from the `WAN` -interface group to 4 per minute: - -```none -set firewall ipv4 name VyOS_MANAGEMENT rule 15 action 'accept' -set firewall ipv4 name VyOS_MANAGEMENT rule 15 inbound-interface group 'LAN' - -set firewall ipv4 name VyOS_MANAGEMENT rule 20 action 'drop' -set firewall ipv4 name VyOS_MANAGEMENT rule 20 recent count 4 -set firewall ipv4 name VyOS_MANAGEMENT rule 20 recent time minute -set firewall ipv4 name VyOS_MANAGEMENT rule 20 state new -set firewall ipv4 name VyOS_MANAGEMENT rule 20 inbound-interface group 'WAN' - -set firewall ipv4 name VyOS_MANAGEMENT rule 21 action 'accept' -set firewall ipv4 name VyOS_MANAGEMENT rule 21 state new -set firewall ipv4 name VyOS_MANAGEMENT rule 21 inbound-interface group 'WAN' -``` - -### Allow Access to Services - -Here we're allowing the router to respond to pings. Then, we can allow access to -the DNS recursor we configured earlier, accepting traffic bound for port 53 from -all hosts on the `NET-INSIDE-v4` network: - -```none -set firewall ipv4 input filter rule 30 action 'accept' -set firewall ipv4 input filter rule 30 icmp type-name 'echo-request' -set firewall ipv4 input filter rule 30 protocol 'icmp' -set firewall ipv4 input filter rule 30 state new - -set firewall ipv4 input filter rule 40 action 'accept' -set firewall ipv4 input filter rule 40 destination port '53' -set firewall ipv4 input filter rule 40 protocol 'tcp_udp' -set firewall ipv4 input filter rule 40 source group network-group NET-INSIDE-v4 -``` - -Finally, we can now configure access to the services running on this router, -allowing all connections coming from localhost: - -```none -set firewall ipv4 input filter rule 50 action 'accept' -set firewall ipv4 input filter rule 50 source address 127.0.0.0/8 -``` - -Commit changes, save the configuration, and exit configuration mode: - -```none -vyos@vyos# commit -vyos@vyos# save -Saving configuration to '/config/config.boot'... -Done -vyos@vyos# exit -vyos@vyos$ -``` - -## Hardening - -Especially if you are allowing SSH remote access from the outside/WAN -interface, there are a few additional configuration steps that should be taken. - -Replace the default `vyos` system user: - -```none -set system login user myvyosuser authentication plaintext-password mysecurepassword -``` - -Set up {ref}`ssh_key_based_authentication`: - -```none -set system login user myvyosuser authentication public-keys myusername@mydesktop type ssh-rsa -set system login user myvyosuser authentication public-keys myusername@mydesktop key contents_of_id_rsa.pub -``` - -Finally, try and SSH into the VyOS install as your new user. Once you have -confirmed that your new user can access your router without a password, delete -the original `vyos` user and completely disable password authentication for -{ref}`ssh`: - -```none -delete system login user vyos -set service ssh disable-password-authentication -``` - -As above, commit your changes, save the configuration, and exit -configuration mode: - -```none -vyos@vyos# commit -vyos@vyos# save -Saving configuration to '/config/config.boot'... -Done -vyos@vyos# exit -vyos@vyos$ -``` - -You now should have a simple yet secure and functioning router to experiment -with further. Enjoy! diff --git a/docs/operation/md-boot-options.md b/docs/operation/md-boot-options.md deleted file mode 100644 index e686bd3c..00000000 --- a/docs/operation/md-boot-options.md +++ /dev/null @@ -1,52 +0,0 @@ ---- -lastproofread: '2025-11-14' ---- - -(boot-options)= - -# Boot Options - -:::{warning} -This function can disrupt services. -Run it only when necessary, and verify all input values before proceeding. -::: - -VyOS provides several kernel command-line options to modify the normal boot -process. -To add an option, select the desired image in the GRUB menu at load time. -Type **e** to edit the first line, then type **Ctrl+X** to boot. - -```{image} /_static/images/boot-options.png -:align: center -:width: 80% -``` - -## Specify custom config file -You can use a configuration file instead of the default `/config/config.boot` -file. If the specified file doesn't exist or isn't readable, the system uses the -default configuration file. No additional verification is performed, so specify -a valid configuration file. - -```none -vyos-config=/path/to/file -``` - -To load the *factory default* configuration, use: - -```none -vyos-config=/opt/vyatta/etc/config.boot.default -``` - -## Disable specific boot process steps - -These options disable certain steps in the boot process. Understand the -{ref}`boot process <boot-steps>` before using them. - -:::{glossary} -no-vyos-migrate - Do not perform config migration. - -no-vyos-firewall - Do not initialize default firewall chains, renders any firewall - configuration unusable. -::: diff --git a/docs/operation/md-index.md b/docs/operation/md-index.md deleted file mode 100644 index b3c02571..00000000 --- a/docs/operation/md-index.md +++ /dev/null @@ -1,12 +0,0 @@ -# Operation Mode - -```{toctree} -:includehidden: true -:maxdepth: 1 - -information -boot-options -upgrade-recovery -password-recovery -raid -``` diff --git a/docs/operation/md-password-recovery.md b/docs/operation/md-password-recovery.md deleted file mode 100644 index c828fb27..00000000 --- a/docs/operation/md-password-recovery.md +++ /dev/null @@ -1,46 +0,0 @@ ---- -lastproofread: '2026-02-04' ---- - -(password-recovery)= - -# Password Recovery - -Restart VyOS from the console. The GRUB menu appears. -Select **Boot options**. - -:::{figure} /_static/images/reset-password-step-1.jpg -:width: 600 -::: - -Next, select **Select boot mode**. - -:::{figure} /_static/images/reset-password-step-2.jpg -:width: 600 -::: - -Select **Password reset**. - -:::{figure} /_static/images/reset-password-step-3.jpg -:width: 600 -::: - -Boot the desired VyOS version. - -:::{figure} /_static/images/reset-password-step-4.jpg -:width: 600 -::: - -The standalone user password recovery tool runs and prompts you to reset the -local system user password. VyOS automatically reboots after you reset your -password. - -```console -Do you wish to reset the admin password? (y or n) -y -Which admin account do you want to reset?[vyos] -my_username -Enter my_username password: -Retype my_username password: -System will reboot in 10 seconds... -``` diff --git a/docs/operation/md-raid.md b/docs/operation/md-raid.md deleted file mode 100644 index c4160a64..00000000 --- a/docs/operation/md-raid.md +++ /dev/null @@ -1,236 +0,0 @@ ---- -lastproofread: '2025-11-20' ---- - -(raid)= - -# RAID 1 - -A Redundant Array of Independent Disks (RAID) uses two or more hard disk drives -to improve disk speed, store more data, and/or provide fault tolerance. -There are several storage schemes possible in a RAID array, each offering a -different combination of storage, reliability, and performance. -VyOS supports **RAID 1** deployments. RAID 1 uses two or more -disks that mirror one another to provide system fault tolerance. In a RAID 1 -configuration, every sector on one disk is duplicated on every sector of all -disks in the array. Provided even one disk in the RAID 1 set is operational, -the system continues to run, even through disk replacement (provided that the -hardware supports in-service replacement of drives). -RAID 1 can be implemented using special hardware or it can be implemented in -software. VyOS supports software RAID 1 on two disks. -The VyOS implementation of RAID 1 features the following: - -- Detection and reporting of disk failure. -- Maintain system operation with one failed disk. -- Boot the system with one failed disk. -- Replace a failed disk and initiate re-mirroring. -- Monitor the status of re-mirroring. - -(raid-installation)= - -## Installation implications - -The VyOS installation utility provides several options for installing -to a RAID 1 set. You can: - -- Use the install system to create the RAID 1 set. -- Use the built-in Linux commands to create a RAID 1 set before running the - install system command. -- Use a previously-created RAID 1 set. - -:::{note} -Before a permanent installation, VyOS runs a live installation. -::: - -## Configuration - -### Standard installation on a single disk - -VyOS automatically detects the presence of two or more -disks that are not currently part of a RAID array when installed. The VyOS -installation utility automatically offers you the option to configure RAID 1 -mirroring for eligible drives with the following prompt: - -```none -Would you like to configure RAID 1 mirroring on them? -``` - -- If you do not want to configure RAID 1 mirroring, enter **No** at the prompt. - -### Empty 2+ disk - -If VyOS detects two identical disks that are not currently part of a -RAID 1 set, the VyOS installation utility automatically offers the option -to configure RAID 1 mirroring for the drives with the following prompt: - -```none -Would you like to configure RAID 1 mirroring on them? -``` - -1\. To create a new RAID 1 array, enter **Yes** at the prompt. If VyOS -detects a filesystem on the partitions being used for RAID 1, it will prompt you -to indicate whether you want to continue creating the RAID 1 array. - -```none -Continue creating array? -``` - -2. To overwrite the old filesystem, enter **Yes**. - -3\. The system informs you that all data on both drives will be erased. -Confirm you want to continue. - -```none -Are you sure you want to do this? -``` - -4\. Enter **Yes** at the prompt to retain the current VyOS configuration. -Enter **No** to delete the current VyOS configuration. - -```none -Would you like me to save the data on it before I delete it? -``` - -5\. Enter **Yes** at the prompt to retain the current VyOS configuration. -Enter **No** to delete the current VyOS configuration. - -6. Continue installing VyOS. - -### Preexisting RAID 1 configuration - -When VyOS detects a previously configured RAID 1 set, -the installation utility displays the following prompt: - -```none -Would you like to use this one? -``` - -1\. To break up the current RAID 1 set, enter **No** at the prompt. The -installation utility detects that there are two identical disks and offers you -the option of configuring RAID 1 mirroring with the following -prompt: - -```none -Would you like to configure RAID 1 mirroring on them? -``` - -2\. To decline to set up a new RAID 1 configuration on the disks, enter **No** -at the prompt. VyOS prompts you to indicate which partition you would -like the system installed on. - -```none -Which partition should I install the root on? [sda1]: -``` - -3\. Enter the partition where you would like the system installed. The system -then prompts you to indicate whether you want to save the old configuration -data. This represents the current VyOS configuration. - -```none -Would you like me to save the data on it before I delete it? -``` - -4\. Enter **Yes** at the prompt to retain the current VyOS configuration once -installation is complete. Enter **No** to delete the current VyOS configuration. - -5. Continue installing VyOS. - -### Detecting and replacing a failed RAID 1 disk - -VyOS system detects disk failures within a RAID 1 set and -reports them to the system console. You can verify the failure by running the -`show raid` command. - -To replace a bad disk within a RAID 1 set: - -1. Remove the failed disk from the RAID 1 set: - - ```{opcmd} delete raid \<RAID‐1‐device\> member \<disk‐partition\> - ``` - where `RAID-1-device` is the name of the RAID 1 device. For example, - `md0` and - `disk-partition` is the name of the failed disk partition. For example, - `sdb2`. -2. Physically remove the failed disk from the system. If the drives are not - hot-swappable, then you must shut down the system before removing the disk. -3. Replace the failed drive with a drive of the same size or larger. -4. Format the new disk for RAID 1 by running the following command: - - ```{opcmd} format disk \<disk‐device1\> like \<disk‐device2\> - ``` - where `disk-device1` is the replacement disk. For example, `sdb` and - `disk-device2` is the existing healthy disk. For example, `sda`. - -5. Add the replacement disk to the RAID 1 set by running the following command: - - ```{opcmd} add raid \<RAID‐1‐device\> member \<disk‐partition\> - ``` - where `RAID-1-device` is the name of the RAID 1 device. For example, - `md0` and `disk-partition` is the name of the replacement disk partition. - For example, `sdb2`. - -## Operation -Learn how to add a disk partition to a RAID 1 set, initiate -mirror synchronization, and check and display information. -```{opcmd} add raid \<RAID‐1‐device\> member \<disk‐partition\> - - Use this command to add a member disk partition to the RAID 1 set. Adding a - disk partition to a RAID 1 set initiates mirror synchronization, where all - data on the existing member partition is copied to the new partition. - -``` - -```{opcmd} format disk \<disk‐device1\> like \<disk‐device2\> - -This command is typically used to prepare a disk to be added to a preexisting -RAID 1 set (of which ``disk-device2`` is already a member). -``` - -```{opcmd} show raid \<RAID‐1‐device\> - -shows output for ``show raid md0`` as ``sdb1`` is being added to the RAID 1 -set and is in the process of being resynchronized. - - -:::{code-block} none -vyos@vyos:~$ show raid md0 -/dev/md0: - Version : 00.90 -Creation Time : Wed Oct 29 09:19:09 2008 - Raid Level : raid1 - Array Size : 1044800 (1020.48 MiB 1069.88 MB) -Used Dev Size : 1044800 (1020.48 MiB 1069.88 MB) - Raid Devices : 2 -Total Devices : 2 -Preferred Minor : 0 - Persistence : Superblock is persistent - Update Time : Wed Oct 29 19:34:23 2008 - State : active, degraded, recovering -Active Devices : 1 -Working Devices : 2 -Failed Devices : 0 -Spare Devices : 1 -Rebuild Status : 17% complete - UUID : 981abd77:9f8c8dd8:fdbf4de4:3436c70f - Events : 0.103 - Number Major Minor RaidDevice State - 0 8 1 0 active sync /dev/sda1 - 2 8 17 1 spare rebuilding /dev/sdb1 -::: -``` - -```{opcmd} show disk sda format - -Use this command to display the formatting of a hard disk. - - -:::{code-block} none -vyos@vyos:~$ show disk sda format -Disk /dev/sda: 1073 MB, 1073741824 bytes -85 heads, 9 sectors/track, 2741 cylinders -Units = cylinders of 765 * 512 = 391680 bytes -Disk identifier: 0x000b7179 -Device Boot Start End Blocks Id System -/dev/sda1 6 2737 1044922+ fd Linux raid autodetect -::: -```
\ No newline at end of file diff --git a/docs/operation/md-upgrade-recovery.md b/docs/operation/md-upgrade-recovery.md deleted file mode 100644 index a8754d3b..00000000 --- a/docs/operation/md-upgrade-recovery.md +++ /dev/null @@ -1,63 +0,0 @@ ---- -lastproofread: '2025-11-20' ---- - -(upgrade-recovery)= - -# Recovery after Failed Upgrades - -Use **VyOS upgrade recovery** to restore the system to the last working -version after a failed upgrade. - -- {ref}`Configuration: <configuration>` How to enable upgrade recovery -- {ref}`How it works: <how-it-works>` Overview of the recovery process -- {ref}`Cancelling recovery: <cancelling-recovery>` Overview of the recovery - process - -(configuration)= - -## Configuration - -:::{warning} -Upgrade recovery is disabled by default. To use it, -**enable it first**. -::: - -To enable upgrade recovery, run the following command: - -```{cfgcmd} set system option reboot-on-upgrade-failure [timeout \<min\>] -``` - -- `timeout <min>:` The time in minutes (5 - 30) to cancel upgrade - recovery before VyOS reboots. - See {ref}`Cancelling Recovery <cancelling-recovery>`. -(how-it-works)= - -## How it works -After a VyOS upgrade, the system monitors the boot process. Upon detecting a -boot failure, VyOS initiates a revert to the last working version and displays -the following warning: -```none -Booting failed, reverting to previous image -Automatic reboot in xx minutes -Use "reboot cancel" to cancel -``` -If no action is taken, the reboot happens automatically after the configured -timeout. Upon successful recovery and reboot, the following message appears: -```none -WARNING: Image update to "VyOS 1.5.xxxx" failed -Please check the logs: -/usr/lib/live/mount/persistence/boot/NAME/rw/var/log -Message is cleared on next reboot! -``` -(cancelling-recovery)= - -## Cancelling recovery -Upon detecting a boot failure, you have the predefined timeout to cancel -upgrade recovery. This is useful if you want to troubleshoot the faulty VyOS -version on your own. - -To cancel upgrade recovery, run the following command: -```none -reboot cancel -``` diff --git a/docs/troubleshooting/md-index.md b/docs/troubleshooting/md-index.md deleted file mode 100644 index 31dbd87b..00000000 --- a/docs/troubleshooting/md-index.md +++ /dev/null @@ -1,17 +0,0 @@ -(troubleshooting)= - -# Troubleshooting - -Sometimes things break or don't work as expected. This section describes -several troubleshooting tools provided by VyOS that can help when something -goes wrong. - -```{toctree} -:maxdepth: 1 - -connectivity -interfaces -monitoring -terminal -system -``` diff --git a/docs/troubleshooting/md-interfaces.md b/docs/troubleshooting/md-interfaces.md deleted file mode 100644 index 553cbf90..00000000 --- a/docs/troubleshooting/md-interfaces.md +++ /dev/null @@ -1,36 +0,0 @@ -# Interface Names - -If you find the names of your interfaces have changed, this could be because -your MAC addresses have changed. - -- For example, you have a VyOS VM with 4 Ethernet interfaces named - eth0, eth1, eth2 and eth3. Then, you migrate your VyOS VM to a different - host and find your interfaces now are eth4, eth5, eth6 and eth7. - - One way to fix this issue **taking control of the MAC addresses** is: - - Log into VyOS and run this command to display your interface settings. - - ```none - show interfaces detail - ``` - - Take note of MAC addresses. - - Now, in order to update a MAC address in the configuration, run this command - specifying the interface name and MAC address you want. - - ```none - set interfaces ethernet eth0 hw-id 00:0c:29:da:a4:fe - ``` - - If it is a VM, go into the settings of the host and set the MAC address to - the settings found in the config.boot file. You can also set the MAC to - static if the host allows so. - -- Another example could be when cloning VyOS VMs in GNS3 and you get into the - same issue: interface names have changed. - - And **a more generic way to fix it** is just deleting every MAC address at - the configuration file of the cloned machine. They will be correctly - regenerated automatically. diff --git a/docs/troubleshooting/md-monitoring.md b/docs/troubleshooting/md-monitoring.md deleted file mode 100644 index 4016a949..00000000 --- a/docs/troubleshooting/md-monitoring.md +++ /dev/null @@ -1,148 +0,0 @@ -# Monitoring - -VyOS features several monitoring tools. - -```none -vyos@vyos:~$ monitor -Possible completions: - bandwidth Monitor interface bandwidth in real time - bandwidth-test - Initiate or wait for bandwidth test - cluster Monitor clustering service - command Monitor an operational mode command (refreshes every 2 seconds) - conntrack-sync - Monitor conntrack-sync - content-inspection - Monitor Content-Inspection - dhcp Monitor Dynamic Host Control Protocol (DHCP) - dns Monitor a Domain Name Service (DNS) daemon - firewall Monitor Firewall - https Monitor the Secure Hypertext Transfer Protocol (HTTPS) service - lldp Monitor Link Layer Discovery Protocol (LLDP) daemon - log Monitor last lines of messages file - nat Monitor network address translation (NAT) - ndp Monitor the NDP information received by the router through the device - openvpn Monitor OpenVPN - protocol Monitor routing protocols - snmp Monitor Simple Network Management Protocol (SNMP) daemon - stop-all Stop all current background monitoring processes - traceroute Monitor the path to a destination in realtime - traffic Monitor traffic dumps - vpn Monitor VPN - vrrp Monitor Virtual Router Redundancy Protocol (VRRP) - webproxy Monitor Webproxy service -``` - -## Traffic Dumps - -To monitor interface traffic, issue the {code}`monitor traffic interface <name>` -command, replacing `<name>` with your chosen interface. - -```none -vyos@vyos:~$ monitor traffic interface eth0 -tcpdump: verbose output suppressed, use -v or -vv for full protocol decode -listening on eth0, link-type EN10MB (Ethernet), capture size 262144 bytes -15:54:28.581601 IP 192.168.0.1 > vyos: ICMP echo request, id 1870, seq 3848, length 64 -15:54:28.581660 IP vyos > 192.168.0.1: ICMP echo reply, id 1870, seq 3848, length 64 -15:54:29.583399 IP 192.168.0.1 > vyos: ICMP echo request, id 1870, seq 3849, length 64 -15:54:29.583454 IP vyos > 192.168.0.1: ICMP echo reply, id 1870, seq 3849, length 64 -^C -4 packets captured -4 packets received by filter -0 packets dropped by kernel -vyos@vyos:~$ -``` - -To quit monitoring, press {kbd}`Ctrl-C` and you'll be returned to the VyOS command -prompt. - -Traffic can be filtered and saved. - -```none -vyos@vyos:~$ monitor traffic interface eth0 -Possible completions: - <Enter> Execute the current command - filter Monitor traffic matching filter conditions - save Save traffic dump from an interface to a file -``` - -## Interface Bandwidth Usage - -To quickly view the bandwidth usage of an interface, use the `monitor bandwidth` command: - -```none -vyos@vyos:~$ monitor bandwidth interface eth0 -``` - -This shows the following: - -```none - B (RX Bytes/second) -198.00 .|....|..................................................... -165.00 .|....|..................................................... -132.00 ||..|.|..................................................... - 99.00 ||..|.|..................................................... - 66.00 |||||||..................................................... - 33.00 |||||||..................................................... - 1 5 10 15 20 25 30 35 40 45 50 55 60 - - KiB (TX Bytes/second) - 3.67 ......|..................................................... - 3.06 ......|..................................................... - 2.45 ......|..................................................... - 1.84 ......|..................................................... - 1.22 ......|..................................................... - 0.61 :::::||..................................................... - 1 5 10 15 20 25 30 35 40 45 50 55 60 -``` - -## Interface Performance - -To take a look on the network bandwidth between two nodes, the `monitor -bandwidth-test` command is used to run iperf. - -```none -vyos@vyos:~$ monitor bandwidth-test -Possible completions: - accept Wait for bandwidth test connections (port TCP/5001) - initiate Initiate a bandwidth test -``` - -- The `accept` command opens a listening iperf server on TCP Port 5001 -- The `initiate` command connects to that server to perform the test. - -```none -vyos@vyos:~$ monitor bandwidth-test initiate -Possible completions: - <hostname> Initiate a bandwidth test to specified host (port TCP/5001) - <x.x.x.x> - <h:h:h:h:h:h:h:h> -``` - -## Monitor command - -The `monitor command` command allows you to repeatedly run a command to view -a continuously refreshed output. The command is run and output every 2 seconds, -allowing you to monitor the output continuously without having to re-run the -command. This can be useful to follow routing adjacency formation. - -```none -vyos@router:~$ monitor command "show interfaces" -``` - -Will clear the screen and show you the output of `show interfaces` every -2 seconds. - -```none -Every 2.0s: /opt/vyatta/bin/vyatta-op-cmd-wrapper Sun Mar 26 02:49:46 2019 - -Codes: S - State, L - Link, u - Up, D - Down, A - Admin Down -Interface IP Address S/L Description ---------- ---------- --- ----------- -eth0 192.168.1.1/24 u/u -eth0.5 198.51.100.4/24 u/u WAN -lo 127.0.0.1/8 u/u - ::1/128 -vti0 172.25.254.2/30 u/u -vti1 172.25.254.9/30 u/u -``` diff --git a/docs/troubleshooting/md-system.md b/docs/troubleshooting/md-system.md deleted file mode 100644 index e855e385..00000000 --- a/docs/troubleshooting/md-system.md +++ /dev/null @@ -1,48 +0,0 @@ -# System Information - -(boot-steps)= - -## Boot Steps - -VyOS 1.2 uses [Debian Jessie] as the base Linux operating system. Jessie was -the first version of Debian that uses [systemd] as the default init system. - -These are the boot steps for VyOS 1.2 - -1. The BIOS loads Grub (or isolinux for the Live CD) -2. Grub then starts the Linux boot and loads the Linux Kernel `/boot/vmlinuz` -3. Kernel Launches Systemd `/lib/systemd/systemd` -4. Systemd loads the VyOS service file - `/lib/systemd/system/vyos-router.service` -5. The service file launches the VyOS router init script - `/usr/libexec/vyos/init/vyos-router` - this is part of the [vyatta-cfg] - Debian package - -> 1. Starts [FRR] - successor to [GNU Zebra] and [Quagga] -> 2. Initialises the boot configuration file - copies over -> `config.boot.default` if there is no configuration -> 3. Runs the configuration migration, if the configuration is for an older -> version of VyOS -> 4. Runs The pre-config script, if there is one -> `/config/scripts/vyos-preconfig-bootup.script` -> 5. If the config file was upgraded, runs any post upgrade scripts -> `/config/scripts/post-upgrade.d` -> 6. Starts `rl-system` and `firewall` -> 7. Mounts the `/boot` partition -> 8. The boot configuration file is then applied by `/opt/vyatta/sbin/vyatta-boot-config-loader/opt/vyatta/etc/config/config.boot` -> -> > 1. The config loader script writes log entries to -> > `/var/log/vyatta-config-loader.log` -> -> 09. Runs `telinit q` to tell the init system to reload `/etc/inittab` -> 10. Finally it runs the post-config script -> `/config/scripts/vyos-postconfig-bootup.script` - -[debian jessie]: https://www.debian.org/releases/jessie/ -[frr]: https://frrouting.org/ -[gnu zebra]: https://www.gnu.org/software/zebra/ -[pcap filter expressions]: http://www.tcpdump.org/manpages/pcap-filter.7.html -[quagga]: https://www.quagga.net/ -[systemd]: https://freedesktop.org/wiki/Software/systemd/ -[tshark]: https://www.wireshark.org/docs/man-pages/tshark.html -[vyatta-cfg]: https://github.com/vyos/vyatta-cfg diff --git a/docs/troubleshooting/md-terminal.md b/docs/troubleshooting/md-terminal.md deleted file mode 100644 index 0d421972..00000000 --- a/docs/troubleshooting/md-terminal.md +++ /dev/null @@ -1,39 +0,0 @@ -# Terminal/Console - -Sometimes you need to clear counters or statistics to troubleshoot better. - -To do this use the `clear` command in Operational mode. - -to clear the console output - -```none -vyos@vyos:~$ clear console -``` - -to clear interface counters - -```none -# clear all interfaces -vyos@vyos:~$ clear interface ethernet counters -# clear specific interface -vyos@vyos:~$ clear interface ethernet eth0 counters -``` - -The command follows the same logic as the `set` command in configuration mode. - -```none -# clear all counters of an interface type -vyos@vyos:~$ clear interface <interface_type> counters -# clear counter of an interface in interface_type -vyos@vyos:~$ clear interface <interface_type> <interface_name> counters -``` - -to clear counters on firewall rulesets or single rules - -```none -vyos@vyos:~$ clear firewall name <ipv4 ruleset name> counters -vyos@vyos:~$ clear firewall name <ipv4 ruleset name> rule <rule#> counters - -vyos@vyos:~$ clear firewall ipv6-name <ipv6 ruleset name> counters -vyos@vyos:~$ clear firewall ipv6-name <ipv6 ruleset name> rule <rule#> counters -``` diff --git a/docs/vpp/configuration/dataplane/md-buffers.md b/docs/vpp/configuration/dataplane/md-buffers.md deleted file mode 100644 index e9bddec9..00000000 --- a/docs/vpp/configuration/dataplane/md-buffers.md +++ /dev/null @@ -1,90 +0,0 @@ ---- -lastproofread: '2026-02-23' ---- - -(vpp-config-dataplane-buffers)= - -```{include} /_include/need_improvement.txt -``` - -# VPP Dataplane Buffers Configuration - -Buffers are essential for handling network packets efficiently. Proper -configuration enhances performance and reliability, and is mandatory for -VPP to work. Buffers temporarily store packets during processing. Therefore, -their configuration must be in sync with NIC configuration, CPU threads, and -overall system resources. - -:::{important} -VPP buffers are allocated from the physical memory pool (`physmem`). The -total amount of memory available for buffer allocation is controlled by the -`physmem-max-size` setting, while the buffer configuration parameters -below control how that memory is used for buffer allocation. - -See {ref}`VPP Physical Memory Configuration <vpp-config-dataplane-physmem>` -for details on configuring `physmem`. -::: - -## Buffer Configuration Parameters - -The following parameters can be configured for VPP buffers: - -### buffers-per-numa -Number of buffers allocated per NUMA node. This setting optimizes -memory access patterns for multi-CPU systems. - -Typically, you need to tune this value if: -- The system has many interfaces -- NICs have many queues -- NICs have large descriptor sizes - -Set this value carefully to balance memory usage and performance. -```{cfgcmd} set vpp settings resource-allocation buffers buffers-per-numa \<value\> -``` -The common approach for the calculation is to use the formula: -```none -buffers-per-numa = (num-rx-queues * num-rx-desc) + (num-tx-queues * num-tx-desc) -``` -Calculate this formula for each NIC and sum the results. Multiply the -total by 2.5 to get the minimum recommended value for -`buffers-per-numa`. - -Avoid setting this value too low to prevent packet drops. - -### data-size -This value sets how much payload data can be stored in a single buffer -allocated by VPP. Larger values reduce buffer chains for large packets, -while smaller values conserve memory for environments handling mostly -small packets. -```{cfgcmd} set vpp settings resource-allocation buffers data-size \<value\> -``` -Optimal size depends on the typical packet size in your network. If -unsure, use the largest MTU in your network plus overhead (for example, -128 bytes). - -### page-size -A memory pages type used for buffer allocation. Common values are 4K, 2M, or 1G. - -Use page sizes configured in your system settings. -```{cfgcmd} set vpp settings resource-allocation buffers page-size \<value\> -``` - -## Potential Issues and Troubleshooting - -Improper buffer configuration can lead to issues such as: - -- Increased latency and packet loss -- Inefficient CPU utilization -- Interface initialization failures - -Indicators of such issues are: - -- Errors during interfaces initialization in VPP logs -- Packet drops observed in VPP statistics - -To troubleshoot buffer-related issues, consider the following steps: - -- Review VPP logs for errors related to buffer allocation. Look for - error `-5` messages. -- Tune available buffers by adjusting the `buffers-per-numa` and - `data-size` parameters. diff --git a/docs/vpp/configuration/dataplane/md-cpu.md b/docs/vpp/configuration/dataplane/md-cpu.md deleted file mode 100644 index 9b798631..00000000 --- a/docs/vpp/configuration/dataplane/md-cpu.md +++ /dev/null @@ -1,66 +0,0 @@ ---- -lastproofread: '2026-02-23' ---- - -(vpp-config-dataplane-cpu)= - -```{include} /_include/need_improvement.txt -``` - -# VPP Dataplane CPU Configuration -VPP can utilize multiple CPU cores for better packet processing -performance. Proper CPU configuration is essential for optimal -throughput and low latency. - -VPP CPU assignment is handled automatically. You specify how many CPU -cores VPP may use, and the system distributes them between the main -thread and worker threads. - -:::{important} -Review the system configuration settings page before changing CPU -settings: {doc}`system`. -::: -If you don't configure CPU settings, VPP uses a single core for the -main thread and doesn't create worker threads. - -## CPU Configuration Parameters - -### `cpu-cores` -This parameter defines the total number of CPU cores allocated to VPP. -```{cfgcmd} set vpp settings resource-allocation cpu-cores \<core-number\> -``` - -The system automatically assigns cores using the following rules: - -> - The first two CPU cores are always reserved for the operating system and -> other services. -> - The main VPP thread is assigned to the first available core after the -> reserved ones. -> - The remaining allocated cores are used for worker threads. - -For example: - -> - If cpu-cores is set to 1, VPP runs only a main thread. -> -> - If cpu-cores is set to 4, VPP uses: -> -> > - 1 core for the main thread -> > - 3 cores for worker threads - -Choose a value based on available hardware resources and expected -traffic load. Too few cores may limit performance, while too many can -negatively impact other system services. - -## Potential Issues and Troubleshooting - -Improper CPU configuration can lead to issues such as: - -- VPP underperformance when not enough cores are assigned, or kernel - underperformance when too many cores are assigned to VPP. -- Resource conflicts with other processes and services. - -Indicators of such issues are: - -- VPP or kernel forwarding performance is lower than expected -- Degraded performance of system components or services, such as DNS, - DHCP, and dynamic routing diff --git a/docs/vpp/configuration/dataplane/md-index.md b/docs/vpp/configuration/dataplane/md-index.md deleted file mode 100644 index f147ebe8..00000000 --- a/docs/vpp/configuration/dataplane/md-index.md +++ /dev/null @@ -1,32 +0,0 @@ ---- -lastproofread: '2026-02-23' ---- - -(vpp-config-dataplane-index)= - -```{include} /_include/need_improvement.txt -``` -# VPP Dataplane Core Configuration -This section covers the core configuration options for the VPP dataplane in -VyOS. It includes settings for memory management, CPU allocation, hugepages, -and other essential parameters that influence the performance and behavior -of the VPP dataplane. -Please review the general system configuration, before starting to configure -VPP. Without proper VyOS preconditions, VPP will not start or its efficiency -will be significantly degraded. -```{toctree} -:includehidden: true -:maxdepth: 1 - -system -buffers -cpu -interface -ipsec -ipv6 -l2learn -lcp -logging -memory -unix -``` diff --git a/docs/vpp/configuration/dataplane/md-interface.md b/docs/vpp/configuration/dataplane/md-interface.md deleted file mode 100644 index 231a49a9..00000000 --- a/docs/vpp/configuration/dataplane/md-interface.md +++ /dev/null @@ -1,88 +0,0 @@ ---- -lastproofread: '2026-02-23' ---- - -(vpp-config-dataplane-interface)= - -```{include} /_include/need_improvement.txt -``` - -# VPP Dataplane Interfaces Configuration -Only Ethernet interfaces (physical or virtual) can be connected to the -VPP dataplane. Interfaces configured here act as a bridge between VPP -and the outside world, allowing VPP to send and receive network -packets. - -## Interface Configuration Parameters -Interfaces connected to the VPP dataplane use the DPDK driver by default, -providing high performance and low latency. -```{cfgcmd} set vpp settings interface \<interface-name\> -``` -Some network interface cards (NICs) may not be compatible with the DPDK driver. - -### DPDK interface options -This section shows how to configures DPDK-specific settings for an interface. -```{cfgcmd} set vpp settings interface \<interface-name\> num-rx-queues \<value\> -``` -Specifies the number of receive queues for the interface. More queues -improve performance on multi-core systems by allowing parallel -processing of incoming packets. Each queue is assigned to a separate -CPU core. -```{cfgcmd} set vpp settings interface \<interface-name\> num-tx-queues \<value\> -``` -Specifies the number of transmit queues for the interface. Similar to -receive queues, more transmit queues improve performance by enabling -parallel processing of outgoing packets. By default, the VPP Dataplane -has one TX queue per enabled CPU worker, or a single queue if no -workers are configured. - -:::{seealso} -{doc}`cpu` -::: -```{cfgcmd} set vpp settings interface \<interface-name\> num-rx-desc \<value\> -``` -Defines the size of each receive queue. Larger queue sizes accommodate -bursts of incoming traffic and reduce the likelihood of packet drops -during high traffic periods. -```{cfgcmd} set vpp settings interface \<interface-name\> num-tx-desc \<value\> -``` -Defines the size of each transmit queue. Larger sizes help manage -bursts of outgoing traffic more effectively. - -## Global Interface Parameters -(vpp-config-dataplane-interface-rx-mode)= - -### interface-rx-mode -The `interface-rx-mode` parameter defines how VPP handles incoming -packets on interfaces. There are several modes available, each with its -own advantages and use cases: -- `interrupt`: In this mode, VPP relies on hardware interrupts to - notify it of incoming packets. This mode suits low to moderate - traffic loads and reduces CPU usage during idle periods. It is not - recommended for low-latency processing. Some NICs may not support - this mode. -- `polling`: In polling mode, VPP continuously checks the interface - for incoming packets. This mode is ideal for high-throughput - scenarios where low latency is critical, as it minimizes packet - waiting time. However, it can increase CPU usage, especially during - low traffic periods, as the polling process is always active. -- `adaptive`: Adaptive mode combines the benefits of interrupt and - polling modes. VPP starts in interrupt mode and switches to polling - mode when traffic load increases. -```{cfgcmd} set vpp settings interface-rx-mode \<mode\> -``` - -Choose an rx-mode based on expected traffic patterns and performance -requirements of your network. - -## Potential Issues and Troubleshooting - -Improper interface configuration can lead to issues such as: - -- Failure to initialize the interface -- Poor performance due to suboptimal driver selection or settings - -Indicators of such issues are: - -- Failed commits after adding or modifying an interface settings -- Low throughput or high latency on the interface diff --git a/docs/vpp/configuration/dataplane/md-ipsec.md b/docs/vpp/configuration/dataplane/md-ipsec.md deleted file mode 100644 index 17e16f8e..00000000 --- a/docs/vpp/configuration/dataplane/md-ipsec.md +++ /dev/null @@ -1,63 +0,0 @@ ---- -lastproofread: '2026-02-23' ---- - -(vpp-config-dataplane-ipsec)= - -```{include} /_include/need_improvement.txt -``` - -# VPP IPsec Configuration -VPP supports IPsec (Internet Protocol Security) offloading from the -kernel, which speeds up cryptographic operations by leveraging VPP's -high-performance packet processing capabilities. - -IPsec does not require any specific configuration on VPP side. If both -sources and destinations of the IPsec traffic are reachable via VPP -interfaces, VPP will automatically offload the IPsec processing from -the kernel. IPsec tunnels are configured in the VPN configuration -section, see {ref}`ipsec_general`. - -## IPsec Configuration Parameters - -### enable IPsec acceleration -When VPP is used for offloading IPsec, it creates a virtual interface to -connect to peers. The interface type is always 'ipsec', which is used for -IPsec tunnels. -```{cfgcmd} set vpp settings ipsec-acceleration -``` -Enabling this option allows VPP to handle IPsec traffic more efficiently by -offloading processing from the kernel. - -### netlink -VPP uses netlink to receive IPsec event messages from the kernel. Proper -settings of the following parameters are crucial for ensuring that VPP can -process all such messages: -```{cfgcmd} set vpp settings lcp netlink batch-delay-ms \<milliseconds\> -``` -This parameter specifies the delay in milliseconds between processing -batch netlink messages. -```{cfgcmd} set vpp settings lcp netlink batch-size \<number\> -``` -This parameter specifies the maximum number of netlink messages to -process in a single batch. -```{cfgcmd} set vpp settings lcp netlink rx-buffer-size \<number\> -``` - -This parameter specifies the size of the receive buffer for netlink -socket. If you expect to offload many IPsec tunnels or get frequent and -intensive rekeying, you may need to increase this value. - -:::{note} -IPsec uses the same netlink parameters as LCP, so tuning them -affects both LCP and IPsec processing. -::: - -## Potential Issues and Troubleshooting - -Improper IPsec configuration can lead to various issues, including: - -- Failure to offload IPsec tunnels to VPP -- Lost IPsec event messages due to insufficient netlink buffer size or - batch settings -- IPsec states or SAs are not synchronized between kernel and VPP diff --git a/docs/vpp/configuration/dataplane/md-ipv6.md b/docs/vpp/configuration/dataplane/md-ipv6.md deleted file mode 100644 index a72dbbfa..00000000 --- a/docs/vpp/configuration/dataplane/md-ipv6.md +++ /dev/null @@ -1,41 +0,0 @@ ---- -lastproofread: '2026-02-26' ---- - -(vpp-config-dataplane-ipv6)= - -```{include} /_include/need_improvement.txt -``` - -# VPP IPv6 Configuration -VPP lets you configure resources allocated for IPv6 traffic processing -independently from IPv4. This helps ensure that in networks without IPv6 -traffic, resources are not wasted. If IPv6 traffic is present, especially -with large routing tables, you must allocate additional resources for IPv6 -processing to keep the dataplane stable. - -You can configure two main resources for IPv6 traffic processing: -```{cfgcmd} set vpp settings resource-allocation ipv6 hash-buckets \<value\> -``` -This parameter configures the number of hash buckets used for IPv6 -routing. If you have a large IPv6 routing table, you may need to increase -this value to ensure efficient routing table performance and fast lookups. -```{cfgcmd} set vpp settings resource-allocation ipv6 heap-size \<value\> -``` - -This parameter configures the heap size used for IPv6 forwarding. If you -have a large IPv6 routing table, you may need to increase this value to -ensure the routing table can accommodate all routes. - -## Potential Issues and Troubleshooting - -Improper IPv6 configuration can lead to various issues, including: - -- Inefficient, slow routing table lookups and traffic processing due to - insufficient hash buckets -- Dataplane crashes or instability due to insufficient heap size when - handling a large number of IPv6 routes -- Overall dataplane instability when handling IPv6 traffic - -Consider increasing configuration values if you experience issues with -IPv6 traffic processing or if you have a large IPv6 routing table. diff --git a/docs/vpp/configuration/dataplane/md-l2learn.md b/docs/vpp/configuration/dataplane/md-l2learn.md deleted file mode 100644 index fe5deb55..00000000 --- a/docs/vpp/configuration/dataplane/md-l2learn.md +++ /dev/null @@ -1,32 +0,0 @@ ---- -lastproofread: '2026-02-26' ---- - -(vpp-config-dataplane-l2learn)= - -```{include} /_include/need_improvement.txt -``` -# VPP L2LEARN Configuration - -When VPP dataplane connects to an L2 domain, it learns MAC addresses of -devices in the domain. By default, the number of MAC addresses it can -learn is limited. - -You can configure the limit using the following command: -```{cfgcmd} set vpp settings resource-allocation mac-limit \<value\> -``` -This parameter sets the maximum number of MAC addresses that can be -learned in the L2 domain. If you have many devices, you may need to -increase this limit to ensure VPP learns all MAC addresses. - -## Potential Issues and Troubleshooting - -Improper L2LEARN configuration can lead to various issues, including: - -- MAC address learning failure in the L2 domain if the limit is set too - low -- Increased packet loss or latency for devices that aren't learned -- Overall dataplane instability when handling L2 traffic - -Consider increasing the L2LEARN limit if you experience issues with MAC -address learning or if you have many devices in the L2 domain. diff --git a/docs/vpp/configuration/dataplane/md-lcp.md b/docs/vpp/configuration/dataplane/md-lcp.md deleted file mode 100644 index 82dc014e..00000000 --- a/docs/vpp/configuration/dataplane/md-lcp.md +++ /dev/null @@ -1,47 +0,0 @@ ---- -lastproofread: '2026-02-26' ---- - -(vpp-config-dataplane-lcp)= - -```{include} /_include/need_improvement.txt -``` - -# VPP LCP Configuration -Linux Control Plane (LCP) is a core component of VPP that lets you -offload various control plane functions to the Linux kernel. LCP provides -seamless integration with other VyOS components, letting you use system -components like DHCP clients and routing daemons together with the VPP -dataplane. - -VPP integration in VyOS relies heavily on LCP. Almost all control plane -functions are handled by other daemons and services, while VPP handles -high-performance packet forwarding exclusively. This approach also reduces -VPP management processing load, improving overall dataplane performance and -stability. - -VyOS integrates the kernel and VPP routing tables uniquely. By default, -all routes, even those not directly connected to VPP interfaces, are -imported from the kernel routing table to the VPP routing table, pointing -to the kernel. This lets you forward traffic to any destination known to -the kernel, even if VPP doesn't have a route to that destination. - -However, in some scenarios this behavior may not be desired. For example, -if you have many routes in the kernel routing table not directly connected -to VPP interfaces, and you don't need forwarding between those -destinations and destinations reachable via VPP, you can disable this -behavior using the following command: -(vpp-config-dataplane-lcp-ignore-kernel-routes)= -(vpp_config_dataplane_lcp_ignore-kernel-routes)= -```{cfgcmd} set vpp settings ignore-kernel-routes -``` - -Pay attention that disabling this option leads to loss of connectivity to -destinations if there are no direct routes in VPP routing table. - -## Potential Issues and Troubleshooting - -Disabling kernel route import can result in: - -- Loss of connectivity to certain destinations if kernel routes are ignored -- Incomplete route synchronization between the kernel and VPP diff --git a/docs/vpp/configuration/dataplane/md-logging.md b/docs/vpp/configuration/dataplane/md-logging.md deleted file mode 100644 index e7fcf455..00000000 --- a/docs/vpp/configuration/dataplane/md-logging.md +++ /dev/null @@ -1,56 +0,0 @@ ---- -lastproofread: '2026-02-27' ---- - -(vpp-config-dataplane-logging)= - -```{include} /_include/need_improvement.txt -``` - -# VPP Logging Configuration -VPP logging is an important part of monitoring and troubleshooting -the performance and behavior of the VPP dataplane. - -VPP stores logs in two places: -- `/var/log/vpp.log` — This file contains logs related to daemon - startup and logs of commands executed directly via VPP CLI. Pay - attention: VyOS does not use VPP CLI for configuration, so this log - will not contain any configuration changes made via VyOS CLI and will - not be informative in most cases. -- System journal — contains logs related to the VPP daemon work, - including errors, warnings, and informational messages. It is the - main destination of logs generated by VPP. - -Logging detail level can be configured via the next command: -```{cfgcmd} set vpp settings logging default-level \<level\> -``` - -Where `<level>` can be one of the following: - -- `emerg` (Emergency) - System is unusable. -- `alert` (Alert) - Immediate action required. -- `crit` (Critical) - Critical conditions. -- `error` (Error) - Error conditions. -- `warn` (Warning) - Warning conditions. -- `notice` (Notice) - Normal but significant. -- `info` (Informational) - Routine informational messages. -- `debug` (Debug) - Detailed debugging messages. -- `disabled` (Disabled) - Logging disabled. - -It is recommended to set logging level to `debug` only for -troubleshooting purposes, as it can generate a large volume of log -data. For regular operation, a level of `info` or `warn` is usually -sufficient. - -## Troubleshooting - -Improper logging configuration can lead to various issues, including: - -- Excessive log file sizes if the logging level is set too high - (for example, `debug`). -- Missing critical information if the logging level is set too low - (for example, `alert`). -- Performance degradation due to excessive logging overhead - -Consider adjusting the logging level if you experience issues mentioned -above. diff --git a/docs/vpp/configuration/dataplane/md-memory.md b/docs/vpp/configuration/dataplane/md-memory.md deleted file mode 100644 index 1c588e7c..00000000 --- a/docs/vpp/configuration/dataplane/md-memory.md +++ /dev/null @@ -1,128 +0,0 @@ ---- -lastproofread: '2026-02-27' ---- - -(vpp-config-dataplane-memory)= -(vpp_config_dataplane_memory)= - -```{include} /_include/need_improvement.txt -``` - -# VPP Memory Configuration -VPP heavily relies on hugepages for its memory management. Hugepages -are larger memory pages that reduce the overhead of page management and -improve performance for applications that require large amounts of -memory, such as VPP. - -VPP supports both 2MB and 1GB hugepages, but the default and most -commonly used size is 2MB. The choice of hugepage size can impact -performance, with larger pages generally providing better performance -for memory-intensive applications. - -Before configuring memory in VPP dataplane settings, you need to -ensure that hugepages are enabled and properly configured on your -system. - -:::{seealso} -{ref}`Hugepages in VyOS Configuration for VPP <vpp-config-hugepages>` -::: -To configure memory settings for VPP, you can use the following -commands in the VPP CLI: - -VPP uses a main heap as a central memory pool for FIB data structures -entry allocations. - -Efficient memory management is crucial for VPP's performance, and the -main heap plays a significant role in this. - -It can be configured using the following command: -```{cfgcmd} set vpp settings resource-allocation memory main-heap-page-size \<size\> -``` -Sets the main heap page size for VPP. -```{cfgcmd} set vpp settings resource-allocation memory main-heap-size \<size\> -``` -Sets the main heap size for VPP. -(vpp-config-dataplane-physmem)= - -## Physical Memory Configuration -VPP uses physical memory for packet buffers and interface operations. -The `physmem` setting controls how much memory VPP can allocate for -these operations. -```{cfgcmd} set vpp settings resource-allocation memory physmem-max-size \<size\> -``` -Sets the maximum amount of physical memory VPP can use for packet -processing and interface buffers. - -**Default**: 16GB (usually sufficient for most deployments) - -You may need to modify the value for high-throughput environments with -many interfaces, large packet buffers, very high packet rates, or -memory-constrained systems where you need to limit VPP's memory usage. - -**Physmem independent of main heap size** — physmem is for packet -buffers, main heap is for routing tables. - -:::{seealso} -- {ref}`Hugepages in VyOS Configuration for VPP <vpp-config-hugepages>` -- {ref}`VPP Buffer Configuration <vpp-config-dataplane-buffers>` - for - controlling buffer allocation within physmem -::: - -### Common configurations -```none -# Reduce for memory-constrained systems -set vpp settings physmem max-size 4G - -# Increase for high-throughput environments -set vpp settings physmem max-size 32G -``` -## Stats Memory Configuration -VPP uses a dedicated statistics memory segment to store runtime -counters and telemetry data. This segment is used by the VPP CLI and -monitoring tools to access performance and status information. - -The statistics segment is allocated from hugepage memory and can be -configured independently from the main heap and physmem settings. - -You can configure statistics memory using the following commands: -```{cfgcmd} set vpp settings resource-allocation memory stats page-size \<size\> -``` -Sets the hugepage page size used for the statistics memory segment. -```{cfgcmd} set vpp settings resource-allocation memory stats size \<size\> -``` - -Sets the total size of the statistics memory segment. - -Increasing this value may be required in large deployments with many -interfaces or enabled features that generate a high number of counters. - -Statistics memory is used only for telemetry and monitoring. It does -not affect packet buffer allocation or routing table memory. - -## Troubleshooting - -Improper configuration of main heap size can lead to performance -degradation or even system instability. If VPP runs out of memory in the -main heap, it may crash or exhibit erratic behavior. Symptoms you may -observe include: - -- Increased latency or packet loss -- Crashes or restarts of VPP processes, especially during routing table - population (for example, BGP session establishment) -- Error messages related to memory allocation failures - -You need to tune the main heap size based on expected FIB entries. Pay -attention: the same amount of routes with a single next-hop and with -multiple next-hops will consume different amounts of memory. - -For physmem, insufficient allocation can lead to packet drops, interface -initialization failures, and overall degraded performance. Symptoms -include: - -- Packet drops or failures to allocate buffers -- Increased latency or jitter in packet processing -- Crashes or restarts of VPP processes under heavy load - -You need to tune the physmem settings based on expected traffic patterns -and interface usage. Monitor memory usage closely and adjust the -configuration as needed to ensure optimal performance. diff --git a/docs/vpp/configuration/dataplane/md-unix.md b/docs/vpp/configuration/dataplane/md-unix.md deleted file mode 100644 index 9832b86d..00000000 --- a/docs/vpp/configuration/dataplane/md-unix.md +++ /dev/null @@ -1,54 +0,0 @@ ---- -lastproofread: '2026-02-27' ---- - -(vpp-config-dataplane-unix)= - -```{include} /_include/need_improvement.txt -``` - -# VPP Unix Dataplane Configuration -The UNIX configuration section is used to control VPP's interaction -with the underlying operating system, including operations scheduling. - -VPP relies on the polling mechanism to efficiently manage I/O operations -and system events. By default VPP continuously polls for events, which -leads to permanent 100% CPU usage by all cores assigned to VPP dataplane. -This is optimal for performance, but may not be desirable in all -environments, especially where power consumption is a concern or where VPP -is running inside a hypervisor, especially if the VM has burstable -thresholds and CPU usage limits. - -To mitigate this, VPP provides a configurable polling delay that allows -reducing CPU usage by introducing a delay between polling cycles. This -introduces a trade-off between CPU usage and latency, as longer delays -can lead to increased latency in processing events. - -You can configure the polling delay using the following command in the -VyOS CLI: -```{cfgcmd} set vpp settings poll-sleep-usec \<delay\> -``` - -Sets the polling delay in microseconds. A value of 0 means no delay -(default), while higher values introduce a delay between polling cycles. - -## Troubleshooting - -Setting the polling delay too high can lead to increased latency and -reduced performance, as VPP may not respond to events as quickly. -Conversely, setting it too low may result in high CPU usage, which can be -problematic in resource-constrained environments. - -Symptoms of improper configuration may include: - -- Increased latency in packet processing -- Higher CPU usage than expected -- Packets lost due to buffer overruns - -If you do not need to reduce CPU usage, it is recommended to leave the -polling delay at its default value of 0 for optimal performance. - -If you need to reduce CPU usage, you may also consider using `interrupt` or -`adaptive` {ref}`DPDK driver modes <vpp-config-dataplane-interface-rx-mode>`, -which can provide a balance between performance and resource utilization -without affecting polling behavior. diff --git a/docs/vpp/configuration/interfaces/md-bonding.md b/docs/vpp/configuration/interfaces/md-bonding.md deleted file mode 100644 index 24868166..00000000 --- a/docs/vpp/configuration/interfaces/md-bonding.md +++ /dev/null @@ -1,206 +0,0 @@ ---- -lastproofread: '2026-03-09' ---- - -(vpp-config-interfaces-bonding)= - -```{include} /_include/need_improvement.txt -``` - -# VPP Bonding Configuration -VPP bonding interfaces provide link aggregation capabilities by combining -multiple physical interfaces into a single logical interface for increased -bandwidth and redundancy. VPP bonding offers high-performance packet -processing compared to traditional Linux bonding. - -## Basic Configuration - -### Creating a Bonding Interface -To create a VPP bonding interface: -```{cfgcmd} set interfaces vpp bonding \<vppbondN\> - -Create a bonding interface where ``<vppbondN>`` follows the naming -convention ``vppbond0``, ``vppbond1``, and so on. A kernel pair interface is -automatically created for the VPP bonding interface. This allows -standard Linux networking tools and services to interact with the VPP -bond. -``` -**Example:** -```none -set interfaces vpp bonding vppbond0 -``` -### Interface Description -```{cfgcmd} set interfaces vpp bonding \<vppbondN\> description \<description\> - -Set a descriptive name for the bonding interface. -``` -**Example:** -```none -set interfaces vpp bonding vppbond0 description "Primary uplink bond" -``` -### Administrative Control -```{cfgcmd} set interfaces vpp bonding \<vppbondN\> disable - -Administratively disable the bonding interface. By default, interfaces -are enabled. -``` -## Member Interface Configuration -### Adding Member Interfaces -```{cfgcmd} set interfaces vpp bonding \<vppbondN\> member interface \<interface-name\> - -Add physical interfaces as members of the bond. You can add multiple -interfaces to the same bond. -``` -**Example:** -```none -set interfaces vpp bonding vppbond0 member interface eth0 -set interfaces vpp bonding vppbond0 member interface eth1 -``` -:::{note} -Member interfaces must have the same speed and duplex for optimal -performance. They must already be attached to VPP. -::: - -## Bonding Modes -```{cfgcmd} set interfaces vpp bonding \<vppbondN\> mode \<mode\> - -Configure the bonding mode. Available modes: -* **802.3ad**: IEEE 802.3ad Dynamic Link Aggregation (LACP) - Default -* **active-backup**: Fault tolerant, only one slave interface active -* **broadcast**: Transmits everything on all slave interfaces -* **round-robin**: Load balance by transmitting packets in sequential order -* **xor-hash**: Distribute based on hash policy -``` -**Examples:** -```none -# Use LACP (recommended for switch environments) -set interfaces vpp bonding vppbond0 mode 802.3ad - -# Use active-backup for simple failover -set interfaces vpp bonding vppbond0 mode active-backup -``` -## Hash Policies -For load balancing modes, configure how the system distributes traffic -across member interfaces: -```{cfgcmd} set interfaces vpp bonding \<vppbondN\> hash-policy \<policy\> - -Set the transmit hash policy: -* **layer2**: Use MAC addresses to generate hash (default) -* **layer2+3**: Combine MAC addresses and IP addresses -* **layer3+4**: Combine IP addresses and port numbers -``` -**Examples:** -```none -# Layer 2 hashing (default) -set interfaces vpp bonding vppbond0 hash-policy layer2 - -# Layer 3+4 for better distribution with multiple flows -set interfaces vpp bonding vppbond0 hash-policy layer3+4 -``` -## MAC Address Configuration -```{cfgcmd} set interfaces vpp bonding \<vppbondN\> mac \<mac-address\> - -Set a specific MAC address for the bonding interface. -``` -**Example:** -```none -set interfaces vpp bonding vppbond0 mac 00:11:22:33:44:55 -``` -## IP Address Configuration -```{cfgcmd} set interfaces vpp bonding \<vppbondN\> address \<ip-address/prefix\> - -Configure IPv4 or IPv6 addresses on the kernel interface. You can -assign multiple addresses. -``` -**Examples:** -```none -# IPv4 address -set interfaces vpp bonding vppbond0 address 192.168.1.10/24 - -# IPv6 address -set interfaces vpp bonding vppbond0 address 2001:db8::10/64 - -# Multiple addresses -set interfaces vpp bonding vppbond0 address 192.168.1.10/24 -set interfaces vpp bonding vppbond0 address 10.0.0.10/8 -``` -## MTU Configuration -```{cfgcmd} set interfaces vpp bonding \<vppbondN\> mtu \<size\> - -Set the Maximum Transmission Unit (MTU) for the kernel interface. The -MTU must be compatible with the connected VPP interface. -``` -**Example:** -```none -set interfaces vpp bonding vppbond0 mtu 9000 -``` -:::{note} -The MTU setting must match or be smaller than the MTU supported by the -associated VPP interface. -::: - -## VLAN Configuration -VPP kernel interfaces support VLAN (Virtual LAN) sub-interfaces for -network segmentation. - -### Creating VLAN Sub-interfaces -```{cfgcmd} set interfaces vpp bonding \<vppbondN\> vif \<vlan-id\> - -Create a VLAN sub-interface with the specified VLAN ID (0-4094). -``` -**Example:** -```none -set interfaces vpp bonding vppbond0 vif 100 -``` -### VLAN Sub-interface Configuration -VLAN sub-interfaces support the same configuration options as the parent -interface: -```{cfgcmd} set interfaces vpp bonding \<vppbondN\> vif \<vlan-id\> address \<ip-address/prefix\> -``` - -```{cfgcmd} set interfaces vpp bonding \<vppbondN\> vif \<vlan-id\> description \<description\> -``` - -```{cfgcmd} set interfaces vpp bonding \<vppbondN\> vif \<vlan-id\> disable -``` - -```{cfgcmd} set interfaces vpp bonding \<vppbondN\> vif \<vlan-id\> mtu \<size\> -``` -**Examples:** -```none -# Configure VLAN 100 -set interfaces vpp bonding vppbond0 vif 100 address 192.168.100.1/24 -set interfaces vpp bonding vppbond0 vif 100 description "Management VLAN" -set interfaces vpp bonding vppbond0 vif 100 mtu 1500 - -# Configure VLAN 200 -set interfaces vpp bonding vppbond0 vif 200 address 192.168.200.1/24 -set interfaces vpp bonding vppbond0 vif 200 description "Guest VLAN" -``` -## Complete Configuration Example -Here's a complete example configuring a bonding interface with LACP: -```none -# Create bonding interface -set interfaces vpp bonding vppbond0 -set interfaces vpp bonding vppbond0 description "Server uplink bond" - -# Configure bonding parameters -set interfaces vpp bonding vppbond0 mode 802.3ad -set interfaces vpp bonding vppbond0 hash-policy layer3+4 - -# Add member interfaces -set interfaces vpp bonding vppbond0 member interface eth0 -set interfaces vpp bonding vppbond0 member interface eth1 - -# Configure IP on kernel interface -set interfaces vpp bonding vppbond0 address 192.168.1.10/24 -``` - -## Best Practices - -- Use **802.3ad mode** with LACP-capable switches for best performance - and standards compliance. -- Configure **layer3+4 hash policy** for environments with multiple - traffic flows. -- Ensure member interfaces have identical settings (speed, duplex, - MTU). diff --git a/docs/vpp/configuration/interfaces/md-bridge.md b/docs/vpp/configuration/interfaces/md-bridge.md deleted file mode 100644 index f7b24b1d..00000000 --- a/docs/vpp/configuration/interfaces/md-bridge.md +++ /dev/null @@ -1,169 +0,0 @@ ---- -lastproofread: '2026-03-10' ---- - -(vpp-config-interfaces-bridge)= - -```{include} /_include/need_improvement.txt -``` - -# VPP Bridge Configuration -VPP bridge interfaces provide Layer 2 switching functionality, allowing -multiple interfaces to be connected at the data link layer. - -VPP bridges operate as learning bridges, automatically discovering MAC -addresses and building forwarding tables to efficiently switch traffic -between member interfaces. This provides transparent connectivity between -different network segments while maintaining the performance benefits of -VPP's optimized data plane. - -**Supported Member Interface Types:** - -VPP bridges support various interface types as members: -- Physical Ethernet interfaces (managed through linux-cp) -- {doc}`bonding` - VPP bonding interfaces -- {doc}`gre` - GRE tunnel interfaces -- {doc}`loopback` - Loopback interfaces (required for BVI) -- {doc}`vxlan` - VXLAN tunnel interfaces - -This flexibility allows you to create complex Layer 2 topologies -combining different networking technologies. - -## Basic Configuration - -### Creating a Bridge Interface -```{cfgcmd} set interfaces vpp bridge \<vppbrN\> - -Create a bridge interface where ``<vppbrN>`` follows the naming -convention ``vppbr1``, ``vppbr2``, etc. -``` -:::{note} -Bridge domain `vppbr0` is reserved by VPP and cannot be -configured through VyOS. Start with `vppbr1` for your bridge -configurations. -::: -**Example:** -```none -set interfaces vpp bridge vppbr1 -``` -### Interface Description -```{cfgcmd} set interfaces vpp bridge \<vppbrN\> description \<description\> - -Set a descriptive name for the bridge interface. -``` -**Example:** -```none -set interfaces vpp bridge vppbr1 description "Main campus bridge" -``` -## Member Interface Configuration -### Adding Member Interfaces -```{cfgcmd} set interfaces vpp bridge \<vppbrN\> member interface \<interface-name\> - -Add an interface as a member of the bridge. -``` -**Examples:** -```none -# Add physical interfaces -set interfaces vpp bridge vppbr1 member interface eth0 -set interfaces vpp bridge vppbr1 member interface eth1 - -# Add other VPP interfaces -set interfaces vpp bridge vppbr1 member interface vppbond0 -set interfaces vpp bridge vppbr1 member interface vppgre1 -``` -:::{important} -Bridge members can include various interface types such as: -- Physical Ethernet interfaces (eth0, eth1, etc.) -- {doc}`bonding` - VPP bonding interfaces (vppbond0, vppbond1, etc.) -- {doc}`gre` - GRE tunnel interfaces -- {doc}`loopback` - Loopback interfaces -- {doc}`vxlan` - VXLAN tunnel interfaces -::: - -## Bridge Virtual Interface (BVI) -A Bridge Virtual Interface (BVI) provides Layer 3 connectivity to a -bridge domain, allowing the bridge to have an IP address and participate -in routing. - -### Configuring BVI -```{cfgcmd} set interfaces vpp bridge \<vppbrN\> member interface \<loopback-interface\> bvi - -Designate a loopback interface as the Bridge Virtual Interface for -the bridge domain. -``` -**Example:** -```none -# Create a loopback interface first -set interfaces vpp loopback vpplo1 - -# Add it to the bridge as BVI -set interfaces vpp bridge vppbr1 member interface vpplo1 bvi -``` -:::{important} -**BVI Restrictions:** -- Only loopback interfaces can be configured as BVI -- Each bridge domain can have only one BVI interface -::: - -## Configuration Examples - -### Basic Bridge Setup -```none -# Create bridge interface -set interfaces vpp bridge vppbr1 -set interfaces vpp bridge vppbr1 description "Office network bridge" - -# Add member interfaces -set interfaces vpp bridge vppbr1 member interface eth0 -set interfaces vpp bridge vppbr1 member interface eth1 -set interfaces vpp bridge vppbr1 member interface eth2 -``` -### Bridge with BVI -```none -# Create bridge and loopback for BVI -set interfaces vpp bridge vppbr2 -set interfaces vpp bridge vppbr2 description "Server segment with gateway" -set interfaces vpp loopback vpplo1 - -# Configure bridge members -set interfaces vpp bridge vppbr2 member interface eth3 -set interfaces vpp bridge vppbr2 member interface eth4 -set interfaces vpp bridge vppbr2 member interface vpplo1 bvi -``` -### Multi-Technology Bridge -```none -# Create bridge combining different interface types -set interfaces vpp bridge vppbr3 -set interfaces vpp bridge vppbr3 description "Hybrid network bridge" - -# Add various interface types -set interfaces vpp bridge vppbr3 member interface vppbond1 -set interfaces vpp bridge vppbr3 member interface vppgre1 -set interfaces vpp bridge vppbr3 member interface vppvxlan1 -set interfaces vpp bridge vppbr3 member interface vpplo2 bvi -``` -## Integration with Kernel Interfaces -Bridge interfaces can be integrated with kernel interfaces for -management and compatibility with standard Linux networking services. -This is accomplished by binding a kernel interface to the Bridge -Virtual Interface (BVI). - -**Example Integration:** -```none -# Create VPP bridge with member interfaces -set interfaces vpp bridge vppbr1 -set interfaces vpp bridge vppbr1 member interface eth1 -set interfaces vpp bridge vppbr1 member interface eth2 - -# Create loopback interface and configure as BVI -set interfaces vpp loopback vpplo1 -set interfaces vpp bridge vppbr1 member interface vpplo1 bvi - -# Bind LCP kernel interface to the BVI loopback -set interfaces vpp loopback vpplo1 address '192.0.2.1/24' -``` - -This configuration creates a kernel interface bound to the BVI, -allowing standard Linux applications and routing daemons to interact -with the VPP bridge. The kernel interface provides Layer 3 access to -the bridge domain. diff --git a/docs/vpp/configuration/interfaces/md-gre.md b/docs/vpp/configuration/interfaces/md-gre.md deleted file mode 100644 index fa91caae..00000000 --- a/docs/vpp/configuration/interfaces/md-gre.md +++ /dev/null @@ -1,140 +0,0 @@ ---- -lastproofread: '2026-03-13' ---- - -(vpp-config-interfaces-gre)= - -```{include} /_include/need_improvement.txt -``` - -# VPP GRE Configuration -VPP GRE interfaces provide Generic Routing Encapsulation tunneling with -high-performance packet processing. GRE tunnels encapsulate various -protocols within IP packets, enabling connectivity across Layer 3 -networks while maintaining the performance benefits of VPP's optimized -data plane. - -## Basic Configuration - -### Creating a GRE Interface -```{cfgcmd} set interfaces vpp gre \<vppgreN\> - -Create a GRE interface where ``<vppgreN>`` follows the naming convention -``vppgre1``, ``vppgre2``, etc. -``` - -```{cfgcmd} set interfaces vpp gre \<vppgreN\> remote \<address\> - -Set the tunnel remote endpoint address. Supports both IPv4 and IPv6 -addresses. -``` - -```{cfgcmd} set interfaces vpp gre \<vppgreN\> source-address \<address\> - -Set the tunnel source address. Must match an address configured on -the local system. -``` -**Basic Example:** -```none -set interfaces vpp gre vppgre1 -set interfaces vpp gre vppgre1 remote 203.0.113.2 -set interfaces vpp gre vppgre1 source-address 192.168.1.1 -``` -## Interface Configuration -### Description and Administrative Control -```{cfgcmd} set interfaces vpp gre \<vppgreN\> description \<description\> - -Set a descriptive name for the GRE interface. -``` - -```{cfgcmd} set interfaces vpp gre \<vppgreN\> disable - -Administratively disable the GRE interface. -``` -### Tunnel Type -```{cfgcmd} set interfaces vpp gre \<vppgreN\> tunnel-type \<type\> - -Set the GRE tunnel encapsulation type: -* ``l3`` - Generic Routing Encapsulation for network layer traffic (default). -* ``teb`` - Transparent Ethernet Bridge for Layer 2 frame transport. -* ``erspan`` - Encapsulated Remote Switched Port Analyzer for traffic - mirroring. -``` -### Kernel Interface Integration -LCP kernel pair interface bound to the VPP GRE interface is created -automatically. This allows standard Linux networking tools and -services to interact with the VPP GRE. - -## IP Address Configuration -```{cfgcmd} set interfaces vpp gre \<vppgreN\> address \<ip-address/prefix\> - -Configure IPv4 or IPv6 addresses on the kernel interface. Multiple -addresses can be assigned. -``` -**Examples:** -```none -# IPv4 address -set interfaces vpp gre vppgre0 address 192.168.1.10/24 - -# IPv6 address -set interfaces vpp gre vppgre0 address 2001:db8::10/64 -``` -## MTU Configuration -```{cfgcmd} set interfaces vpp gre \<vppgreN\> mtu \<size\> - -Set the Maximum Transmission Unit (MTU) for the kernel interface. -The MTU must be compatible with the connected VPP interface. -``` -**Example:** -```none -set interfaces vpp gre vppgre0 mtu 9000 -``` -:::{note} -The MTU size must not exceed the MTU size -supported by the associated VPP interface. -::: - -## Configuration Examples - -### Layer 3 GRE Tunnel -```none -# IPv4 GRE tunnel -set interfaces vpp gre vppgre1 -set interfaces vpp gre vppgre1 description "Site-to-site tunnel" -set interfaces vpp gre vppgre1 remote 203.0.113.10 -set interfaces vpp gre vppgre1 source-address 192.168.1.1 -set interfaces vpp gre vppgre1 tunnel-type l3 -``` -### Layer 2 GRE Tunnel (TEB) -```none -# Transparent Ethernet Bridge -set interfaces vpp gre vppgre2 -set interfaces vpp gre vppgre2 description "L2 extension tunnel" -set interfaces vpp gre vppgre2 remote 203.0.113.20 -set interfaces vpp gre vppgre2 source-address 192.168.1.1 -set interfaces vpp gre vppgre2 tunnel-type teb -``` -### IPv6 GRE Tunnel -```none -# IPv6 endpoints -set interfaces vpp gre vppgre3 -set interfaces vpp gre vppgre3 remote 2001:db8::2 -set interfaces vpp gre vppgre3 source-address 2001:db8::1 -``` -### GRE with Kernel Interface -```none -# GRE tunnel with management interface -set interfaces vpp gre vppgre4 -set interfaces vpp gre vppgre4 remote 203.0.113.30 -set interfaces vpp gre vppgre4 source-address 192.168.1.1 -set interfaces vpp gre vppgre4 address 10.0.1.1/30 -``` -## Bridge Integration -GRE interfaces can be added as members to VPP bridges for Layer 2 -switching. See {doc}`bridge` for detailed bridge configuration. -```none -# Add TEB GRE tunnel to bridge -set interfaces vpp bridge vppbr1 -set interfaces vpp bridge vppbr1 member interface vppgre2 -set interfaces vpp bridge vppbr1 member interface eth1 -``` diff --git a/docs/vpp/configuration/interfaces/md-index.md b/docs/vpp/configuration/interfaces/md-index.md deleted file mode 100644 index 662f37c5..00000000 --- a/docs/vpp/configuration/interfaces/md-index.md +++ /dev/null @@ -1,47 +0,0 @@ ---- -lastproofread: '2026-03-13' ---- - -(vpp-config-interfaces-index)= - -```{include} /_include/need_improvement.txt -``` -# VPP Interfaces Configuration -```{toctree} -:includehidden: true -:maxdepth: 1 - -bonding -bridge -gre -ipip -loopback -vxlan -xconnect -``` - -VyOS utilizes VPP (Vector Packet Processor) to provide high-performance data -plane processing. While physical interfaces are typically managed through the -Linux kernel using `linux-cp` (Linux Control Plane) integration, VyOS also -supports creating dedicated VPP interfaces for enhanced flexibility and -performance. - -## Why VPP Interfaces? - -VPP interfaces offer several advantages: - -- **Total Isolation**: VPP interfaces operate entirely within the VPP data - plane, providing isolation from the Linux kernel when needed. -- **Advanced Features**: Access to VPP-specific functionality not available - in standard Linux interfaces. -- **Flexible Deployment**: Some interface types are only available as VPP - interfaces or may not be supported by the kernel. -- **Specific scenarios**: Not all use cases require integration with the - Linux Kernel. - -### Integration with Kernel - -VyOS provides seamless integration between VPP and kernel networking. -This allows you to leverage the strengths of both approaches: -create interfaces inside VPP, and access them from the Linux kernel and other -services. diff --git a/docs/vpp/configuration/interfaces/md-ipip.md b/docs/vpp/configuration/interfaces/md-ipip.md deleted file mode 100644 index 8a847e48..00000000 --- a/docs/vpp/configuration/interfaces/md-ipip.md +++ /dev/null @@ -1,99 +0,0 @@ ---- -lastproofread: '2026-03-13' ---- - -(vpp-config-interfaces-ipip)= - -```{include} /_include/need_improvement.txt -``` - -# VPP IPIP Configuration -VPP IPIP interfaces provide IP-in-IP tunneling with high-performance -packet processing. IPIP tunnels encapsulate IP packets within IP -packets, creating point-to-point connections across Layer 3 networks. - -## Basic Configuration - -### Creating an IPIP Interface -```{cfgcmd} set interfaces vpp ipip \<vppipipN\> - -Create an IPIP interface where ``<vppipipN>`` follows the naming -convention ``vppipip1``, ``vppipip2``, etc. -``` - -```{cfgcmd} set interfaces vpp ipip \<vppipipN\> remote \<address\> - -Set the tunnel remote endpoint address. Supports both IPv4 and IPv6 -addresses. -``` - -```{cfgcmd} set interfaces vpp ipip \<vppipipN\> source-address \<address\> - -Set the tunnel source address. The source address must match an address -configured on the local system. -``` -**Basic Example:** -```none -set interfaces vpp ipip vppipip1 -set interfaces vpp ipip vppipip1 remote 203.0.113.2 -set interfaces vpp ipip vppipip1 source-address 192.168.1.1 -``` -## Interface Configuration -### Description and Administrative Control -```{cfgcmd} set interfaces vpp ipip \<vppipipN\> description \<description\> - -Set a descriptive name for the IPIP interface. -``` - -```{cfgcmd} set interfaces vpp ipip \<vppipipN\> disable - -Administratively disable the IPIP interface. -``` -### Kernel Interface Integration -Kernel interface is bound to the VPP IPIP interface for management and -application compatibility. - -## IP Address Configuration -```{cfgcmd} set interfaces vpp ipip \<vppipipN\> address \<ip-address/prefix\> - -Configure IPv4 or IPv6 addresses on the kernel interface. Multiple -addresses can be assigned. -``` -**Examples:** -```none -# IPv4 address -set interfaces vpp ipip vppipip0 address 192.168.1.10/24 - -# IPv6 address -set interfaces vpp ipip vppipip0 address 2001:db8::10/64 -``` -## MTU Configuration -```{cfgcmd} set interfaces vpp ipip \<vppipipN\> mtu \<size\> - -Set the Maximum Transmission Unit (MTU) for the kernel interface. -The MTU must be compatible with the connected VPP interface. -``` -## Configuration Examples -### IPv4 IPIP Tunnel -```none -# Basic IPv4 IPIP tunnel -set interfaces vpp ipip vppipip1 -set interfaces vpp ipip vppipip1 description "Site-to-site IPIP tunnel" -set interfaces vpp ipip vppipip1 remote 203.0.113.10 -set interfaces vpp ipip vppipip1 source-address 192.168.1.1 -``` -### IPv6 IPIP Tunnel -```none -# IPv6 endpoints -set interfaces vpp ipip vppipip2 -set interfaces vpp ipip vppipip2 remote 2001:db8::2 -set interfaces vpp ipip vppipip2 source-address 2001:db8::1 -``` -### IPIP with Kernel Interface -```none -# IPIP tunnel with management interface -set interfaces vpp ipip vppipip3 -set interfaces vpp ipip vppipip3 remote 203.0.113.30 -set interfaces vpp ipip vppipip3 source-address 192.168.1.1 -set interfaces vpp ipip vppipip3 address 10.0.2.1/30 -``` diff --git a/docs/vpp/configuration/interfaces/md-loopback.md b/docs/vpp/configuration/interfaces/md-loopback.md deleted file mode 100644 index bc65338b..00000000 --- a/docs/vpp/configuration/interfaces/md-loopback.md +++ /dev/null @@ -1,120 +0,0 @@ ---- -lastproofread: '2026-03-13' ---- - -(vpp-config-interfaces-loopback)= - -```{include} /_include/need_improvement.txt -``` - -# VPP Loopback Interface Configuration -VPP loopback interfaces provide virtual interfaces that remain -administratively up and are commonly used for stable addressing, -routing protocols, and as Bridge Virtual Interfaces (BVI). Loopback -interfaces in VPP offer high-performance virtual connectivity with optimized -packet processing. - -## Basic Configuration - -### Creating a Loopback Interface -```{cfgcmd} set interfaces vpp loopback \<vpploN\> - -Create a loopback interface where ``<vpploN>`` follows the naming -convention ``vpplo1``, ``vpplo2``, etc. -``` -**Basic Example:** -```none -set interfaces vpp loopback vpplo1 -``` -## Interface Configuration -### Description and Administrative Control -```{cfgcmd} set interfaces vpp loopback \<vpploN\> description \<description\> - -Set a descriptive name for the loopback interface. -``` - -```{cfgcmd} set interfaces vpp loopback \<vpploN\> disable - -Administratively disable the loopback interface. -``` -### Kernel Interface Integration -Kernel interface is bounded to the VPP loopback interface for management -and application compatibility. - -## IP Address Configuration -```{cfgcmd} set interfaces vpp loopback \<vpploN\> address \<ip-address/prefix\> - -Configure IPv4 or IPv6 addresses on the kernel interface. Multiple -addresses can be assigned. -``` -**Examples:** -```none -# IPv4 address -set interfaces vpp loopback vpplo1 address 192.168.1.10/24 - -# IPv6 address -set interfaces vpp loopback vpplo1 address 2001:db8::10/64 -``` -## MTU Configuration -```{cfgcmd} set interfaces vpp loopback \<vpploN\> mtu \<size\> - -Set the Maximum Transmission Unit (MTU) for the kernel interface. -The MTU must be compatible with the connected VPP interface. -``` -## VLAN Configuration -VPP kernel interfaces support VLAN (Virtual LAN) sub-interfaces for network -segmentation. - -### Creating VLAN Sub-interfaces -```{cfgcmd} set interfaces vpp loopback \<vpploN\> vif \<vlan-id\> - -Create a VLAN sub-interface with the specified VLAN ID (0-4094). -``` -### VLAN Sub-interface Configuration -VLAN sub-interfaces support the same configuration options as the parent -interface: -```{cfgcmd} set interfaces vpp loopback \<vpploN\> vif \<vlan-id\> address \<ip-address/prefix\> -``` - -```{cfgcmd} set interfaces vpp loopback \<vpploN\> vif \<vlan-id\> description \<description\> -``` - -```{cfgcmd} set interfaces vpp loopback \<vpploN\> vif \<vlan-id\> disable -``` - -```{cfgcmd} set interfaces vpp loopback \<vpploN\> vif \<vlan-id\> mtu \<size\> -``` -**Examples:** -```none -# Configure VLAN 100 -set interfaces vpp loopback vpplo1 vif 100 address 192.168.100.1/24 -set interfaces vpp loopback vpplo1 vif 100 description "Management VLAN" -set interfaces vpp loopback vpplo1 vif 100 mtu 1500 - -# Configure VLAN 200 -set interfaces vpp loopback vpplo1 vif 200 address 192.168.200.1/24 -set interfaces vpp loopback vpplo1 vif 200 description "Guest VLAN" -``` -## Configuration Examples -### Basic Loopback Interface -```none -# Create simple loopback -set interfaces vpp loopback vpplo1 -set interfaces vpp loopback vpplo1 description "Router ID interface" -``` -### Loopback with Kernel Interface -```none -# Loopback with management access -set interfaces vpp loopback vpplo2 -set interfaces vpp loopback vpplo2 description "Management loopback" -set interfaces vpp loopback vpplo2 address 10.255.255.1/32 -``` -### Bridge Virtual Interface (BVI) -```none -# Loopback as BVI for bridge -set interfaces vpp loopback vpplo3 -set interfaces vpp loopback vpplo3 description "Bridge gateway interface" -set interfaces vpp bridge vppbr1 -set interfaces vpp bridge vppbr1 member interface vpplo3 bvi -set interfaces vpp loopback vpplo3 address 192.168.100.1/24 -``` diff --git a/docs/vpp/configuration/interfaces/md-vxlan.md b/docs/vpp/configuration/interfaces/md-vxlan.md deleted file mode 100644 index 6fa1322a..00000000 --- a/docs/vpp/configuration/interfaces/md-vxlan.md +++ /dev/null @@ -1,132 +0,0 @@ ---- -lastproofread: '2026-03-13' ---- - -(vpp-config-interfaces-vxlan)= - -```{include} /_include/need_improvement.txt -``` - -# VPP VXLAN Configuration -VPP VXLAN interfaces provide virtual extensible local area network (VXLAN) -tunneling with high-performance packet processing. VXLAN extends Layer 2 -domains across Layer 3 networks using UDP encapsulation, enabling scalable -multi-tenant networking while leveraging VPP's optimized data plane. - -## Basic Configuration - -### Creating a VXLAN Interface -```{cfgcmd} set interfaces vpp vxlan \<vppvxlanN\> - -Create a VXLAN interface where ``<vppvxlanN>`` follows the naming -convention ``vppvxlan1``, ``vppvxlan2``, etc. -``` - -```{cfgcmd} set interfaces vpp vxlan \<vppvxlanN\> vni \<vni\> - -Set the Virtual Network Identifier (VNI) for the VXLAN tunnel. Valid range -is 0-16777214. -``` - -```{cfgcmd} set interfaces vpp vxlan \<vppvxlanN\> remote \<address\> - -Set the tunnel remote endpoint address. Supports both IPv4 and IPv6 -addresses. -``` - -```{cfgcmd} set interfaces vpp vxlan \<vppvxlanN\> source-address \<address\> - -Set the tunnel source address. Must match an address configured on the -local system. -``` -**Basic Example:** -```none -set interfaces vpp vxlan vppvxlan1 -set interfaces vpp vxlan vppvxlan1 vni 100 -set interfaces vpp vxlan vppvxlan1 remote 203.0.113.2 -set interfaces vpp vxlan vppvxlan1 source-address 192.168.1.1 -``` -## Interface Configuration -### Description and Administrative Control -```{cfgcmd} set interfaces vpp vxlan \<vppvxlanN\> description \<description\> - -Set a descriptive name for the VXLAN interface. -``` - -```{cfgcmd} set interfaces vpp vxlan \<vppvxlanN\> disable - -Administratively disable the VXLAN interface. -``` -### Kernel Interface Integration -The kernel interface is bound to the VXLAN tunnel for management and -application compatibility. - -## IP Address Configuration -```{cfgcmd} set interfaces vpp vxlan \<vppvxlanN\> address \<ip-address/prefix\> - -Configure IPv4 or IPv6 addresses on the kernel interface. Multiple -addresses can be assigned. -``` -**Examples:** -```none -set interfaces vpp vxlan vppvxlan1 address 192.168.1.10/24 -set interfaces vpp vxlan vppvxlan1 address 2001:db8::10/64 -``` -## MTU Configuration -```{cfgcmd} set interfaces vpp vxlan \<vppvxlanN\> mtu \<size\> - -Set the Maximum Transmission Unit (MTU) for the kernel interface. The MTU -must be compatible with the connected VPP interface. -``` -## Configuration Examples -### Basic VXLAN Tunnel -```none -# IPv4 VXLAN tunnel -set interfaces vpp vxlan vppvxlan1 -set interfaces vpp vxlan vppvxlan1 description "Tenant A network extension" -set interfaces vpp vxlan vppvxlan1 vni 1000 -set interfaces vpp vxlan vppvxlan1 remote 203.0.113.10 -set interfaces vpp vxlan vppvxlan1 source-address 192.168.1.1 -``` -### IPv6 VXLAN Tunnel -```none -# IPv6 endpoints -set interfaces vpp vxlan vppvxlan2 -set interfaces vpp vxlan vppvxlan2 vni 2000 -set interfaces vpp vxlan vppvxlan2 remote 2001:db8::2 -set interfaces vpp vxlan vppvxlan2 source-address 2001:db8::1 -``` -### VXLAN with Kernel Interface -```none -# VXLAN tunnel with management interface -set interfaces vpp vxlan vppvxlan3 -set interfaces vpp vxlan vppvxlan3 vni 3000 -set interfaces vpp vxlan vppvxlan3 remote 203.0.113.30 -set interfaces vpp vxlan vppvxlan3 source-address 192.168.1.1 -set interfaces vpp vxlan vppvxlan3 address 10.0.3.1/24 -``` -## Bridge Integration -VXLAN interfaces are commonly used as members in VPP bridges for Layer 2 -extension. See {doc}`bridge` for more information. -```none -# Add VXLAN tunnel to bridge -set interfaces vpp bridge vppbr1 -set interfaces vpp bridge vppbr1 member interface vppvxlan1 -set interfaces vpp bridge vppbr1 member interface eth1 -set interfaces vpp bridge vppbr1 member interface vpplo1 bvi -``` -### Multi-Tenant Configuration -```none -# Multiple VNIs for tenant separation -set interfaces vpp vxlan vppvxlan10 -set interfaces vpp vxlan vppvxlan10 description "Tenant A - Production" -set interfaces vpp vxlan vppvxlan10 vni 1001 -set interfaces vpp vxlan vppvxlan10 remote 203.0.113.20 -set interfaces vpp vxlan vppvxlan10 source-address 192.168.1.1 - -set interfaces vpp vxlan vppvxlan11 -set interfaces vpp vxlan vppvxlan11 description "Tenant A - Development" -set interfaces vpp vxlan vppvxlan11 vni 1002 -set interfaces vpp vxlan vppvxlan11 remote 203.0.113.21 -set interfaces vpp vxlan vppvxlan11 source-address 192.168.1.1 -``` diff --git a/docs/vpp/configuration/interfaces/md-xconnect.md b/docs/vpp/configuration/interfaces/md-xconnect.md deleted file mode 100644 index 0ee052d2..00000000 --- a/docs/vpp/configuration/interfaces/md-xconnect.md +++ /dev/null @@ -1,94 +0,0 @@ ---- -lastproofread: '2026-03-13' ---- - -(vpp-config-interfaces-xconnect)= - -```{include} /_include/need_improvement.txt -``` - -# VPP XConnect Configuration -VPP XConnect provides direct Layer 2 packet forwarding between two -interfaces with maximum transparency and minimal overhead. XConnect -creates a simple point-to-point bridge that forwards all Layer 2 packets -bidirectionally without MAC learning or flooding, making it ideal for -transparent connectivity scenarios. - -XConnect operates as a super-transparent bridge, forwarding all frames -between the connected interfaces without any packet inspection or -modification. This provides the simplest possible Layer 2 forwarding with -VPP's high-performance packet processing. - -## Comparison with Bridges -- **XConnect**: Point-to-point only, no MAC learning, maximum - transparency, minimal overhead -- **Bridge**: Multi-port, MAC learning, broadcast handling, more - features but higher overhead - -Choose XConnect when you need simple point-to-point Layer 2 forwarding -with maximum performance and transparency. Use bridges when you need -multi-port switching with MAC learning and broadcast handling. - -## Basic Configuration - -### Creating an XConnect Interface -```{cfgcmd} set interfaces vpp xconnect \<vppxconN\> - -Create an XConnect interface where ``<vppxconN>`` follows the naming -convention ``vppxcon1``, ``vppxcon2``, etc. -``` - -```{cfgcmd} set interfaces vpp xconnect \<vppxconN\> member interface \<interface-name\> - -Add an interface as a member of the XConnect. Exactly two member -interfaces must be configured to create bidirectional forwarding. -``` -**Basic Example:** -```none -set interfaces vpp xconnect vppxcon1 -set interfaces vpp xconnect vppxcon1 member interface eth0 -set interfaces vpp xconnect vppxcon1 member interface eth1 -``` -This configuration creates transparent forwarding between `eth0` and `eth1`, -where any packet received on either interface is immediately forwarded to -the other without any processing. - -## Interface Configuration -```{cfgcmd} set interfaces vpp xconnect \<vppxconN\> description \<description\> - -Set a descriptive name for the XConnect interface. -``` -## Configuration Examples -### Physical Interface XConnect -```none -# Connect two physical interfaces -set interfaces vpp xconnect vppxcon1 -set interfaces vpp xconnect vppxcon1 description "Transparent wire between ports" -set interfaces vpp xconnect vppxcon1 member interface eth0 -set interfaces vpp xconnect vppxcon1 member interface eth1 -``` -This creates a transparent wire between two physical ports, effectively -making them function as a single cable. - -### Tunnel to Physical XConnect -```none -# Connect tunnel to physical interface -set interfaces vpp xconnect vppxcon2 -set interfaces vpp xconnect vppxcon2 description "GRE tunnel to physical bridge" -set interfaces vpp xconnect vppxcon2 member interface vppgre1 -set interfaces vpp xconnect vppxcon2 member interface eth2 -``` -This forwards all traffic from a GRE tunnel directly to a physical -interface and vice versa. - -### Mixed Interface Types -```none -# Connect different interface types -set interfaces vpp xconnect vppxcon3 -set interfaces vpp xconnect vppxcon3 description "VXLAN to bonding bridge" -set interfaces vpp xconnect vppxcon3 member interface vppvxlan1 -set interfaces vpp xconnect vppxcon3 member interface vppbond0 -``` - -This demonstrates XConnect's flexibility in connecting various VPP interface -types. diff --git a/docs/vpp/configuration/md-acl.md b/docs/vpp/configuration/md-acl.md deleted file mode 100644 index 59b96070..00000000 --- a/docs/vpp/configuration/md-acl.md +++ /dev/null @@ -1,485 +0,0 @@ ---- -lastproofread: '2025-09-04' ---- - -(vpp-config-acl)= - -```{include} /_include/need_improvement.txt -``` - -# VPP ACL Configuration -VPP ACLs (Access Control Lists) provide a way to filter traffic passing through VPP interfaces. They offer a high-performance packet filtering solution that can be used as a fast firewall alternative. - -VyOS VPP ACL implementation supports two main types of access control lists: -- **IP ACLs** - Layer 3 filtering based on IPv4/IPv6 addresses, ports, and protocols (can be applied to both input and output directions) -- **MAC ACLs** - Layer 2 filtering based on MAC addresses and IP prefixes (can only be applied to input direction) - -## Structure and Components - -### Tags -ACL tags are named rule sets that contain one or more access control entries (ACEs). Tags provide a way to group related rules and apply them consistently across different interfaces. -- Tag names are user-defined text strings -- Each tag can contain multiple numbered rules -- Tags can be applied to interfaces in input or output direction -- Multiple tags can be applied to a single interface - -### Interface Application -ACL tags are applied to interfaces to control traffic flow: -- **Input direction**: Filters traffic entering the interface -- **Output direction**: Filters traffic leaving the interface - -:::{note} -**Important Limitation**: MAC ACLs can only be applied to the input direction of interfaces. They cannot filter outbound traffic. Use IP ACLs if you need to filter traffic in both directions. -::: - -### Rule Processing -Rules within an ACL are processed in numerical order (lowest to highest). The first matching rule determines the action taken on the packet. - -Available actions: -- `permit` - Allow the packet to continue -- `deny` - Drop the packet -- `permit-reflect` - Allow traffic and automatically permit return traffic - -## L3/IP ACLs -IP ACLs provide Layer 3 filtering capabilities based on IPv4 and IPv6 addresses, port numbers, and protocols. They support both stateless and stateful (reflexive) filtering. - -### Creating IP ACL Tags -IP ACL tags are created under the `vpp acl ip` configuration node: -```none -set vpp acl ip tag-name <tag-name> -set vpp acl ip tag-name <tag-name> description '<description>' -``` -Example: -```none -set vpp acl ip tag-name 'WEB-FILTER' -set vpp acl ip tag-name 'WEB-FILTER' description 'Web server access control' -``` -### Adding Rules to IP ACL Tags -Rules are added to IP ACL tags with specific rule numbers: -```none -set vpp acl ip tag-name <tag-name> rule <rule-number> -``` -#### Basic IP ACL Rule Configuration -Each rule requires an action and matching criteria: -```none -set vpp acl ip tag-name <tag-name> rule <rule-number> action <permit|deny|permit-reflect> -set vpp acl ip tag-name <tag-name> rule <rule-number> description '<description>' -set vpp acl ip tag-name <tag-name> rule <rule-number> protocol <protocol> -``` -**Actions:** -- `permit` - Allow matching traffic -- `deny` - Block matching traffic -- `permit-reflect` - Allow outbound traffic and automatically permit return traffic - -**Protocols:** -- `all` - Match all IP protocols (default) -- Or specific protocol by name, e.g. `tcp`, `udp`, `icmp` - -#### Source and Destination Matching -Configure source and destination parameters: -```none -# Source configuration -set vpp acl ip tag-name <tag-name> rule <rule-number> source prefix <ip-prefix> -set vpp acl ip tag-name <tag-name> rule <rule-number> source port <port-spec> - -# Destination configuration -set vpp acl ip tag-name <tag-name> rule <rule-number> destination prefix <ip-prefix> -set vpp acl ip tag-name <tag-name> rule <rule-number> destination port <port-spec> -``` -**Prefix Specification:** -- `<x.x.x.x/x>` - IPv4 prefix in CIDR notation -- `<h:h:h:h:h:h:h:h/x>` - IPv6 prefix in CIDR notation - -**Port Specification:** -- `<1-65535>` - Single port number -- `<start>-<end>` - Port range (e.g., 1001-1005) - -#### TCP Flags Matching -For TCP protocol rules, you can match specific TCP flags: -```none -# Match packets with specific flags set -set vpp acl ip tag-name <tag-name> rule <rule-number> tcp-flags is-set <ack|cwr|ecn|fin|psh|rst|syn|urg> - -# Match packets without specific flags set -set vpp acl ip tag-name <tag-name> rule <rule-number> tcp-flags is-not-set <ack|cwr|ecn|fin|psh|rst|syn|urg> -``` -### IP ACL Configuration Examples -#### Example 1: Basic Web Server ACL -```none -# Create ACL for web server access -set vpp acl ip tag-name 'WEB-SERVER' -set vpp acl ip tag-name 'WEB-SERVER' description 'Web server access control' - -# Allow HTTP traffic -set vpp acl ip tag-name 'WEB-SERVER' rule 10 action permit -set vpp acl ip tag-name 'WEB-SERVER' rule 10 protocol tcp -set vpp acl ip tag-name 'WEB-SERVER' rule 10 destination port 80 - -# Allow HTTPS traffic -set vpp acl ip tag-name 'WEB-SERVER' rule 20 action permit -set vpp acl ip tag-name 'WEB-SERVER' rule 20 protocol tcp -set vpp acl ip tag-name 'WEB-SERVER' rule 20 destination port 443 - -# Deny all other traffic -set vpp acl ip tag-name 'WEB-SERVER' rule 999 action deny -set vpp acl ip tag-name 'WEB-SERVER' rule 999 protocol all -``` -#### Example 2: Network Segmentation ACL -```none -# Create ACL for network segmentation -set vpp acl ip tag-name 'DMZ-FILTER' -set vpp acl ip tag-name 'DMZ-FILTER' description 'DMZ to internal network filter' - -# Allow specific internal subnet access -set vpp acl ip tag-name 'DMZ-FILTER' rule 10 action permit -set vpp acl ip tag-name 'DMZ-FILTER' rule 10 destination prefix '192.168.100.0/24' -set vpp acl ip tag-name 'DMZ-FILTER' rule 10 protocol tcp -set vpp acl ip tag-name 'DMZ-FILTER' rule 10 destination port 443 - -# Allow DNS queries -set vpp acl ip tag-name 'DMZ-FILTER' rule 20 action permit -set vpp acl ip tag-name 'DMZ-FILTER' rule 20 destination prefix '192.168.1.10/32' -set vpp acl ip tag-name 'DMZ-FILTER' rule 20 protocol udp -set vpp acl ip tag-name 'DMZ-FILTER' rule 20 destination port 53 - -# Block everything else to internal networks -set vpp acl ip tag-name 'DMZ-FILTER' rule 100 action deny -set vpp acl ip tag-name 'DMZ-FILTER' rule 100 destination prefix '192.168.0.0/16' -``` -#### Example 3: Reflexive ACL -```none -# Create reflexive ACL for outbound connections -set vpp acl ip tag-name 'OUTBOUND-REFLECT' -set vpp acl ip tag-name 'OUTBOUND-REFLECT' description 'Allow outbound with return traffic' - -# Allow outbound HTTP/HTTPS with return traffic -set vpp acl ip tag-name 'OUTBOUND-REFLECT' rule 10 action permit-reflect -set vpp acl ip tag-name 'OUTBOUND-REFLECT' rule 10 protocol tcp -set vpp acl ip tag-name 'OUTBOUND-REFLECT' rule 10 destination port 80 - -set vpp acl ip tag-name 'OUTBOUND-REFLECT' rule 20 action permit-reflect -set vpp acl ip tag-name 'OUTBOUND-REFLECT' rule 20 protocol tcp -set vpp acl ip tag-name 'OUTBOUND-REFLECT' rule 20 destination port 443 -``` -### Applying IP ACL Tags to Interfaces -IP ACL tags are applied to interfaces using the interface configuration: -```none -# Apply to input direction -set vpp acl ip interface <interface> input acl-tag <number> tag-name <tag-name> - -# Apply to output direction -set vpp acl ip interface <interface> output acl-tag <number> tag-name <tag-name> -``` -Where: -- `<interface>` - Interface name (e.g., eth0, eth1) -- `<number>` - ACL rule number (0-4294967295) for ordering multiple ACL tags -- `<tag-name>` - Name of the ACL tag to apply - -Multiple tags can be applied to the same interface and direction by using different ACL rule numbers. - -Example: -```none -# Apply web server ACL to input direction -set vpp acl ip interface eth0 input acl-tag 10 tag-name 'WEB-SERVER' - -# Apply outbound reflexive ACL to output direction -set vpp acl ip interface eth1 output acl-tag 10 tag-name 'OUTBOUND-REFLECT' - -# Apply multiple ACLs to the same interface and direction -set vpp acl ip interface eth0 input acl-tag 20 tag-name 'FIREWALL' -``` -## L2/MAC ACLs -MAC ACLs provide Layer 2 filtering capabilities based on MAC addresses and IP prefixes. They are particularly useful for controlling access at the data link layer. - -:::{important} -**Direction Limitation**: MAC ACLs can **only** be applied to the **input direction** of interfaces. They cannot filter outbound/output traffic. If you need bidirectional filtering, use IP ACLs instead. -::: - -### Creating MAC ACL Tags -MAC ACL tags are created under the `vpp acl mac` configuration node: -```none -set vpp acl mac tag-name <tag-name> -set vpp acl mac tag-name <tag-name> description '<description>' -``` -Example: -```none -set vpp acl mac tag-name 'MAC-FILTER' -set vpp acl mac tag-name 'MAC-FILTER' description 'Layer 2 MAC address filtering' -``` -### Adding Rules to MAC ACL Tags -Rules are added to MAC ACL tags with specific rule numbers: -```none -set vpp acl mac tag-name <tag-name> rule <rule-number> -``` -#### Basic MAC ACL Rule Configuration -Each rule requires an action and matching criteria: -```none -set vpp acl mac tag-name <tag-name> rule <rule-number> action <permit|deny> -set vpp acl mac tag-name <tag-name> rule <rule-number> description '<description>' -``` -**Actions:** -- `permit` - Allow matching traffic -- `deny` - Block matching traffic - -Note: MAC ACLs do not support the `permit-reflect` action available in IP ACLs. - -#### MAC Address Matching -Configure MAC address matching criteria: -```none -set vpp acl mac tag-name <tag-name> rule <rule-number> mac-address <mac-address> -set vpp acl mac tag-name <tag-name> rule <rule-number> mac-mask <mac-mask> -``` -**MAC Address Specification:** -- `mac-address` - Source MAC address to match (format: xx:xx:xx:xx:xx:xx) -- `mac-mask` - MAC address mask (default: ff:ff:ff:ff:ff:ff for exact match) - -The MAC mask allows for partial MAC address matching. For example: -\- `ff:ff:ff:00:00:00` matches the first 3 octets (OUI) -\- `ff:ff:ff:ff:ff:ff` matches the complete MAC address (default) - -#### IP Prefix Matching -Configure IP prefix matching for the source: -```none -set vpp acl mac tag-name <tag-name> rule <rule-number> prefix <ip-prefix> -``` -**Prefix Specification:** -- Supports both IPv4 and IPv6 prefixes in CIDR notation -- Examples: `192.168.1.0/24`, `10.0.0.0/8`, `2001:db8::/32` - -### MAC ACL Configuration Examples - -#### Example 1: Device Whitelist -```none -# Create MAC ACL for device whitelisting -set vpp acl mac tag-name 'DEVICE-WHITELIST' -set vpp acl mac tag-name 'DEVICE-WHITELIST' description 'Allow only approved devices' - -# Allow specific workstation -set vpp acl mac tag-name 'DEVICE-WHITELIST' rule 10 action permit -set vpp acl mac tag-name 'DEVICE-WHITELIST' rule 10 mac-address '00:1b:21:12:34:56' -set vpp acl mac tag-name 'DEVICE-WHITELIST' rule 10 prefix '192.168.1.100/32' -set vpp acl mac tag-name 'DEVICE-WHITELIST' rule 10 description 'Admin workstation' - -# Allow specific server -set vpp acl mac tag-name 'DEVICE-WHITELIST' rule 20 action permit -set vpp acl mac tag-name 'DEVICE-WHITELIST' rule 20 mac-address '00:1b:21:78:90:ab' -set vpp acl mac tag-name 'DEVICE-WHITELIST' rule 20 prefix '192.168.1.10/32' -set vpp acl mac tag-name 'DEVICE-WHITELIST' rule 20 description 'Web server' - -# Deny everything else -set vpp acl mac tag-name 'DEVICE-WHITELIST' rule 999 action deny -set vpp acl mac tag-name 'DEVICE-WHITELIST' rule 999 mac-address '00:00:00:00:00:00' -set vpp acl mac tag-name 'DEVICE-WHITELIST' rule 999 mac-mask '00:00:00:00:00:00' -``` -#### Example 2: Vendor-Based Filtering -```none -# Create MAC ACL for vendor-based filtering -set vpp acl mac tag-name 'VENDOR-FILTER' -set vpp acl mac tag-name 'VENDOR-FILTER' description 'Filter by MAC vendor OUI' - -# Deny Realtek devices (OUI: 00:e0:4c) -set vpp acl mac tag-name 'VENDOR-FILTER' rule 10 action deny -set vpp acl mac tag-name 'VENDOR-FILTER' rule 10 mac-address '00:e0:4c:00:00:00' -set vpp acl mac tag-name 'VENDOR-FILTER' rule 10 mac-mask 'ff:ff:ff:00:00:00' -set vpp acl mac tag-name 'VENDOR-FILTER' rule 10 description 'Block Realtek devices' - -# Allow all other devices -set vpp acl mac tag-name 'VENDOR-FILTER' rule 100 action permit -set vpp acl mac tag-name 'VENDOR-FILTER' rule 100 mac-address '00:00:00:00:00:00' -set vpp acl mac tag-name 'VENDOR-FILTER' rule 100 mac-mask '00:00:00:00:00:00' -set vpp acl mac tag-name 'VENDOR-FILTER' rule 100 description 'Allow all other vendors' -``` -#### Example 3: Network Segmentation by MAC -```none -# Create MAC ACL for network segmentation -set vpp acl mac tag-name 'SEGMENT-FILTER' -set vpp acl mac tag-name 'SEGMENT-FILTER' description 'Segment networks by MAC/IP binding' - -# Allow management VLAN devices -set vpp acl mac tag-name 'SEGMENT-FILTER' rule 10 action permit -set vpp acl mac tag-name 'SEGMENT-FILTER' rule 10 mac-address '02:01:00:00:00:00' -set vpp acl mac tag-name 'SEGMENT-FILTER' rule 10 mac-mask 'ff:ff:00:00:00:00' -set vpp acl mac tag-name 'SEGMENT-FILTER' rule 10 prefix '10.1.0.0/16' -set vpp acl mac tag-name 'SEGMENT-FILTER' rule 10 description 'Management VLAN' - -# Allow user VLAN devices -set vpp acl mac tag-name 'SEGMENT-FILTER' rule 20 action permit -set vpp acl mac tag-name 'SEGMENT-FILTER' rule 20 mac-address '02:02:00:00:00:00' -set vpp acl mac tag-name 'SEGMENT-FILTER' rule 20 mac-mask 'ff:ff:00:00:00:00' -set vpp acl mac tag-name 'SEGMENT-FILTER' rule 20 prefix '10.2.0.0/16' -set vpp acl mac tag-name 'SEGMENT-FILTER' rule 20 description 'User VLAN' -``` -### Applying MAC ACL Tags to Interfaces -MAC ACL tags can only be applied to the input direction of interfaces: -```none -set vpp acl mac interface <interface> tag-name <tag-name> -``` -:::{note} -**Syntax Difference**: Unlike IP ACLs, MAC ACL interface application does not use the `acl-tag <number>` structure since only single MAC ACLs can be applied. -::: - -:::{warning} -Unlike IP ACLs, MAC ACLs do **not** support output direction filtering. There is no `output` option available for MAC ACL interface application. -::: -Example: -```none -# Apply MAC filtering to interface input -set vpp acl mac interface eth0 tag-name 'MAC-FILTER' -set vpp acl mac interface eth1 tag-name 'DEVICE-WHITELIST' -``` -## Configuration Best Practices - -### Rule Ordering -- **Number rules strategically**: Use gaps between rule numbers (10, 20, 30) to allow for future insertions -- **Place specific rules first**: More specific matches should have lower rule numbers -- **End with catch-all**: Always include a final rule that matches all traffic with explicit action -- **Document rules**: Use descriptions for complex rules to aid troubleshooting - -### Performance Considerations -- **Minimize rule count**: Fewer rules generally mean better performance -- **Use appropriate ACL type**: Use MAC ACLs for Layer 2/3 filtering, IP ACLs for Layer 3/4 filtering -- **Consider direction limitations**: Remember that MAC ACLs only work on input traffic; use IP ACLs for filtering in both directions -- **Combine related rules**: Group similar filtering requirements into single ACL tags -- **Apply strategically**: Apply ACLs at ingress points where possible to minimize processing - -## Troubleshooting - -### Common Issues -- **ACL not taking effect:** - - Verify ACL is applied to correct interface and direction - - Check rule numbering and order - - Ensure interface is properly configured in VPP -- **Performance degradation:** - - Review ACL complexity and rule count - - Consider consolidating rules - - Check for unnecessary broad matches -- **Traffic blocked unexpectedly:** - - Review rule order (first match wins) - - Check for overly restrictive rules - - Verify protocol and port specifications - -### Verification Commands -Use these commands to verify ACL configuration and operation: -```none -# Show VPP ACL configuration -show configuration commands | grep "vpp acl" - -# Show VPP interface configuration -show configuration commands | grep "vpp acl.*interface" - -# View commit history for ACL changes -show configuration commit-revisions | grep -A5 -B5 "vpp acl" -``` -## Operational Commands -VyOS provides several operational commands to monitor and troubleshoot VPP ACL configurations and their status. - -### Viewing All ACLs -Display all configured ACLs (both IP and MAC): -```{opcmd} show vpp acl -``` -This command shows a summary of all configured ACL tags with their rules, displaying both IP ACLs and MAC ACLs in a tabular format. -Example output: -```none ---------------------------------- -IP ACL "tag-name WEB-SERVER" acl_index 0 - -Rule Action Src prefix Src port Dst prefix Dst port Proto TCP flags set TCP flags not set ------- -------- ------------ ---------- ------------ ---------- ------- --------------- ------------------- - 10 permit 0.0.0.0/0 0-65535 0.0.0.0/0 80 6 - 20 permit 0.0.0.0/0 0-65535 0.0.0.0/0 443 6 - 999 deny 0.0.0.0/0 0-65535 0.0.0.0/0 0-65535 0 - ---------------------------------- -MACIP ACL "tag-name VENDOR-FILTER" acl_index 0 - -Rule Action IP prefix MAC address MAC mask ------- -------- ----------- ----------------- ----------------- - 10 deny 0.0.0.0/0 00:e0:4c:00:00:00 ff:ff:ff:00:00:00 - 100 permit 0.0.0.0/0 00:00:00:00:00:00 00:00:00:00:00:00 -``` -### IP ACL Commands -View all IP ACLs: -```{opcmd} show vpp acl ip -``` -View IP ACL interface assignments: -```{opcmd} show vpp acl ip interface -``` -Example output: -```none -Interface Input ACLs Output ACLs ------------ ------------ ------------- -eth1 WEB-SERVER -``` -View specific IP ACL by tag name: -```{opcmd} show vpp acl ip tag-name \<tag-name\> -``` -Example: -```none -vyos@vyos:~$ show vpp acl ip tag-name WEB-SERVER - ---------------------------------- -IP ACL "tag-name WEB-SERVER" acl_index 0 - - Rule Action Src prefix Src port Dst prefix Dst port Proto TCP flags set TCP flags not set ------- -------- ------------ ---------- ------------ ---------- ------- --------------- ------------------- - 10 permit 0.0.0.0/0 0-65535 0.0.0.0/0 80 6 - 20 permit 0.0.0.0/0 0-65535 0.0.0.0/0 443 6 - 999 deny 0.0.0.0/0 0-65535 0.0.0.0/0 0-65535 0 -``` -### MAC ACL Commands -View all MAC ACLs: -```{opcmd} show vpp acl mac -``` -View MAC ACL interface assignments: -```{opcmd} show vpp acl mac interface -``` -Example output: -```none -Interface ACL ------------ ----- -eth0 VENDOR-FILTER -``` -View specific MAC ACL by tag name: -```{opcmd} show vpp acl mac tag-name \<tag-name\> -``` -Example: -```none -vyos@vyos:~$ show vpp acl mac tag-name VENDOR-FILTER - ---------------------------------- -MACIP ACL "tag-name VENDOR-FILTER" acl_index 0 - - Rule Action IP prefix MAC address MAC mask ------- -------- ----------- ----------------- ----------------- - 10 deny 0.0.0.0/0 00:e0:4c:00:00:00 ff:ff:ff:00:00:00 - 100 permit 0.0.0.0/0 00:00:00:00:00:00 00:00:00:00:00:00 -``` - -### Understanding Command Output - -**IP ACL Output Fields:** - -- **Rule**: Rule number within the ACL -- **Action**: permit, deny, or permit-reflect -- **Src prefix**: Source IP prefix (0.0.0.0/0 = any source) -- **Src port**: Source port range (0-65535 = any port) -- **Dst prefix**: Destination IP prefix -- **Dst port**: Destination port or port range -- **Proto**: IP protocol number (6=TCP, 17=UDP, 1=ICMP, 0=any) -- **TCP flags set**: Required TCP flags (for TCP protocol) -- **TCP flags not set**: Prohibited TCP flags (for TCP protocol) - -**MAC ACL Output Fields:** - -- **Rule**: Rule number within the ACL -- **Action**: permit or deny -- **IP prefix**: Source IP prefix constraint -- **MAC address**: Source MAC address to match -- **MAC mask**: MAC address mask for partial matching - -**Interface Assignment Output:** - -- Shows which interfaces have ACLs applied -- **Input ACLs**: ACL tags applied to incoming traffic -- **Output ACLs**: ACL tags applied to outgoing traffic (IP ACLs only) -- **ACL**: MAC ACL tag applied to interface (input only) diff --git a/docs/vpp/configuration/md-index.md b/docs/vpp/configuration/md-index.md deleted file mode 100644 index 7e02ae74..00000000 --- a/docs/vpp/configuration/md-index.md +++ /dev/null @@ -1,41 +0,0 @@ ---- -lastproofread: '2025-09-04' ---- - -(vpp-dconfig-index)= - -```{include} /_include/need_improvement.txt -``` - -# VPP Configuration -VPP settings consist of several main sections. - -Main Dataplane settings and internal VPP interfaces: -```{toctree} -:includehidden: true -:maxdepth: 1 - -dataplane/index -interfaces/index -``` -Features that can be enabled on VPP Dataplane: -```{toctree} -:includehidden: true -:maxdepth: 1 - -acl -ipfix -ipsec -nat/index -sflow -``` - -## VPP Initialization - -When VPP Dataplane is configured and the configuration is committed, VyOS will attempt to start VPP and initialize all interfaces assigned to it. During this process the following steps occur: - -1. VyOS checks that the system meets all requirements for VPP operation. If any requirement is not met, VPP will not start and an error message will be displayed. -2. VPP is started and its initial configuration is applied. -3. All interfaces assigned to VPP are initialized and brought up. -4. A special virtual interfaces are reinstalled to the kernel with the same names as interfaces that were attached to VPP to maintain compatibility with the configuration. -5. VyOS configuration initializes those virtual interfaces, so that features that exist only in kernel dataplane continue to operate. diff --git a/docs/vpp/configuration/md-ipfix.md b/docs/vpp/configuration/md-ipfix.md deleted file mode 100644 index 7ed2aee3..00000000 --- a/docs/vpp/configuration/md-ipfix.md +++ /dev/null @@ -1,50 +0,0 @@ -# VPP IPFIX Configuration - -VPP IPFIX in VyOS allows monitoring and exporting network traffic flows -for analytics, security, and accounting. IPFIX works with the VPP -(Vector Packet Processing) backend to provide high-performance flow tracking. - -## Overview - -VyOS integrates VPP for high-performance packet processing. IPFIX -configuration controls how flows are monitored, exported, and which -interfaces are included. - -## Key IPFIX Concepts - -- **Active timeout**: Maximum time a flow is kept active before export. -- **Inactive timeout**: Maximum time an idle flow is kept before export. -- **Collector**: The remote host and port to which flow records are sent. -- **Flow layers**: Determines which layer information is included - (`l2`, `l3`, `l4`). -- **Interfaces**: Physical or virtual interfaces to monitor. -- **Direction**: Which traffic to monitor (`rx`, `tx`, `both`). -- **Flow variant**: Optional filter for IPv4 or IPv6 flows. - -## Configuration Options - -- **active-timeout**: Duration (in seconds) after which active flows - are exported. -- **inactive-timeout**: Duration (in seconds) after which idle flows - are exported. -- **collector \`\<ip>\` port \`\<port>\`**: IP and UDP port of the IPFIX collector. -- **collector \`\<ip>\` source-address \`\<ip>\`**: Source address for flow export. -- **flowprobe-record \`\<l2|l3|l4>\`**: Layers to include in flow records. -- **interface** `<interface>` **\[direction** `<rx|tx|both>`**\]** - **\[flow-variant** `<ipv4|ipv6>`**\]**: Interfaces to monitor, - direction of traffic, and optional flow variant filter. - -## Example Configuration - -```none -set vpp ipfix active-timeout '15' -set vpp ipfix inactive-timeout '120' -set vpp ipfix collector 192.0.2.2 port '4739' -set vpp ipfix collector 192.0.2.2 source-address '192.0.2.1' -set vpp ipfix flowprobe-record 'l2' -set vpp ipfix flowprobe-record 'l3' -set vpp ipfix flowprobe-record 'l4' -set vpp ipfix interface eth0 -set vpp ipfix interface eth1 direction 'both' -set vpp ipfix interface eth1 flow-variant 'ipv4' -``` diff --git a/docs/vpp/configuration/md-sflow.md b/docs/vpp/configuration/md-sflow.md deleted file mode 100644 index 752b8377..00000000 --- a/docs/vpp/configuration/md-sflow.md +++ /dev/null @@ -1,37 +0,0 @@ ---- -lastproofread: '2025-09-04' ---- - -(vpp-config-sflow)= - -```{include} /_include/need_improvement.txt -``` - -# VPP sFlow Configuration -VPP Dataplane in VyOS support sFlow for traffic monitoring and analysis. - -The VPP Dataplane integration works hand-in-hand with normal kernel sFlow agent, which is responsible for collecting and exporting sFlow samples. VPP itself is responsible for generating the samples. - -To enable sFlow in VPP, you first need to configure the service using the same steps as for normal kernel sFlow agent, as described in {doc}`/configuration/system/sflow`. Then you can enable sFlow on VPP interfaces. - -Then, you need to enable sFlow on the VPP interfaces you want to monitor. This is done using the following commands: -```{cfgcmd} set vpp sflow interface \<interface-name\> -``` -This will enable sFlow on the specified interface. You can repeat this command for each interface you want to monitor. - -:::{note} -sFlow collects statistics only for traffic *received* on the interface. If you want to monitor traffic *sent* on the interface, you need to enable sFlow on the corresponding interface in the opposite direction. -::: -Optionally, you can specify the number of bytes from each packet that should be included in the sFlow sample using the following command: -```{cfgcmd} set vpp sflow header-bytes \<bytes\> -``` -This defines the size of the packet header (in bytes) captured for each sFlow sample. - -The sampling rate is configured globally under the `system sflow` section and automatically applied to VPP sFlow. -This ensures consistent sampling behavior between the system and VPP, and prevents configuration conflicts. - -Finally, you need to enable integration between VPP and the kernel sFlow agent using the following command: -```{cfgcmd} set system sflow vpp -``` - -After this, collecting and exporting sFlow samples will be handled by the kernel sFlow agent, while VPP will generate the samples. diff --git a/docs/vpp/configuration/nat/md-index.md b/docs/vpp/configuration/nat/md-index.md deleted file mode 100644 index 4d5c01d1..00000000 --- a/docs/vpp/configuration/nat/md-index.md +++ /dev/null @@ -1,41 +0,0 @@ ---- -lastproofread: '2026-03-05' ---- - -(vpp-config-nat-index)= - -```{include} /_include/need_improvement.txt - -``` -# VPP NAT Configuration - -```{toctree} -:includehidden: true -:maxdepth: 1 - -cgnat -nat44 -``` - -VPP Dataplane in VyOS supports two types of NAT: - -## NAT44 - -This type is a classic NAT implementation where you can configure static -and dynamic NAT rules. It supports both source and destination NAT. While the -configuration may look a bit unusual compared to traditional NAT -implementations, it provides flexibility in network configurations. - -## CGNAT - -CGNAT is a special type of NAT44, which is highly useful when you have -multiple local customers and a limited number of public IP addresses. It -shares the public IP address space fairly between customers by using a -combination of IP address and port number to distinguish between them. - -ISPs often use this NAT type to provide internet access to customers. - -It supports only source NAT. - -CGNAT also supports exclude rules (identity mappings) to bypass translation -for selected local addresses or protocol/port tuples. diff --git a/docs/vpp/configuration/nat/md-nat44.md b/docs/vpp/configuration/nat/md-nat44.md deleted file mode 100644 index a0805ed3..00000000 --- a/docs/vpp/configuration/nat/md-nat44.md +++ /dev/null @@ -1,653 +0,0 @@ ---- -lastproofread: '2026-03-05' ---- - -(vpp-config-nat-nat44)= - -```{include} /_include/need_improvement.txt -``` - -# VPP NAT44 Configuration -NAT44 has two main use cases: -- **Source NAT (SNAT)**: Enabling internet access for hosts in private - networks using dynamic or static address translation. -- **Destination NAT (DNAT)**: Providing external access to internal services - through static port forwarding rules. - -VyOS supports both dynamic translation using address pools and static -mappings for predictable address translation requirements. - -Configuring NAT44 involves a few steps: -1. Define the inside and outside interfaces. -2. Create NAT rules for SNAT or DNAT. - -## Dynamic and Static Operations -NAT44 configuration can be done in one of two ways or in both ways -simultaneously: -1. Dynamically performing NAT using a pool of public IP addresses. -2. Statically mapping private IP addresses to public IP addresses. - -To configure dynamic NAT, you need to define a pool of public IP -addresses that will be used for translation. This offers an easy way to -provide internet access to internal users. - -Static rules are suitable for scenarios where you need consistent and -predictable mappings between private and public IP addresses. They are also -the only way to configure DNAT. - -### NAT Rule Processing and Traffic Flow -This section explains how different combinations of NAT rules affect -traffic handling on a router. There are three possible combinations of NAT -rule configurations: -1. **Dynamic NAT Only** - - **All** traffic received on the "in" interface is processed by - dynamic NAT rules without exceptions. -2. **Dynamic + Static NAT** - - **All** traffic received on the "in" interface is first matched - against static NAT rules. - - If no match is found, it is then processed against dynamic NAT rules. -3. **Static NAT Only** - - **All** traffic on the "in" interface is checked against static NAT - rules. - - If no match is found, the traffic is routed **without NAT**. - -:::{important} -- If **dynamic NAT rules** are present, **all** traffic received on - "in" interfaces is subject to NAT processing. -- If **only static NAT rules** are configured, traffic that does not - match any static rule is routed unchanged. -::: - -## Interfaces Configuration -The first step in configuring NAT44 is defining which interfaces handle -inside (private) and outside (public) traffic. VyOS uses these interface -designations to determine the direction of translation. - -### Inside Interfaces -Inside interfaces connect to private networks where hosts need source NAT -to access external networks. -```{cfgcmd} set vpp nat nat44 interface inside \<inside-interface\> -``` -Traffic flowing **from** inside interfaces gets source NAT applied, -translating private source addresses to public addresses from the -translation pool. - -### Outside Interfaces -Outside interfaces connect to public networks where external hosts may -need to access internal services. -```{cfgcmd} set vpp nat nat44 interface outside \<outside-interface\> -``` -Traffic flowing **to** outside interfaces can trigger destination NAT -based on static rules, allowing external access to internal services. - -### Interface Roles and Traffic Flow - -:::{note} -While VyOS uses "inside" and "outside" as established conventions, -the technical definitions are: -- **Inside interface**: Interface where traffic originates that needs - source NAT (SNAT) -- **Outside interface**: Interface where traffic originates that needs - destination NAT (DNAT) - -In complex network topologies, the same physical interface can be -configured as both inside and outside to handle bidirectional NAT -scenarios. -::: -**Traffic Processing:** -1. **Inside → Outside** (SNAT): Private hosts accessing external networks -2. **Outside → Inside** (DNAT): External hosts accessing internal services - via static rules -3. **Dynamic NAT**: Created automatically for inside→outside traffic -4. **Static NAT**: Requires explicit configuration for outside→inside - traffic - -### Multiple Interface Support -You can configure multiple interfaces as inside or outside to support -complex network topologies: -```none -# Multiple inside interfaces (different private networks) -set vpp nat nat44 interface inside eth0 -set vpp nat nat44 interface inside eth2 - -# Multiple outside interfaces (redundancy or load balancing) -set vpp nat nat44 interface outside eth1 -set vpp nat nat44 interface outside eth3 -``` -## Address Pool Configuration -Address pools define ranges of IP addresses that can be used for NAT -translations. VyOS NAT44 supports two types of address pools, each serving -different purposes. - -### Translation Pools -Translation pools are used for dynamic source NAT (SNAT). They provide a -range of public IP addresses that can be dynamically assigned to private -hosts when they access external networks. -```{cfgcmd} set vpp nat nat44 address-pool translation address \<ip-address | ip-address-range\> -``` - -```{cfgcmd} set vpp nat nat44 address-pool translation interface \<interface-name\> -``` -**Examples:** -```none -# Single address pool -set vpp nat nat44 address-pool translation address 203.0.113.10 - -# Address range pool -set vpp nat nat44 address-pool translation address 203.0.113.10-203.0.113.20 - -# Interface-based pool (use a first IP assigned to the interface) -set vpp nat nat44 address-pool translation interface eth1 -``` -### Twice-NAT Pools -Twice-NAT pools are used when performing both source and destination NAT on -the same traffic flow. This is particularly useful in scenarios where you -need to: -- Translate both source and destination addresses -- Provide access between networks with overlapping IP ranges -- Implement advanced NAT scenarios like self-twice-nat -```{cfgcmd} set vpp nat nat44 address-pool twice-nat address \<ip-address | ip-address-range\> -``` - -```{cfgcmd} set vpp nat nat44 address-pool twice-nat interface \<interface-name\> -``` -**Examples:** -```none -# Twice-NAT pool for advanced scenarios -set vpp nat nat44 address-pool twice-nat address 192.168.100.1-192.168.100.10 - -# Interface-based twice-nat pool -set vpp nat nat44 address-pool twice-nat interface eth2 -``` -### Pool Requirements - -:::{important} -- For dynamic NAT to work, you must configure at least one - **translation** pool. -- For static rules with twice-nat options, you must configure a - **twice-nat** pool. -- Interface-based pools automatically include main (first) IP address - assigned to the specified interface. -::: - -### Pool Selection Priority -When multiple pools are configured, VyOS uses the following selection -priority: -1. **Static mappings**: Always use the specific external address defined in - the rule. -2. **Dynamic NAT**: Use available addresses from translation pools in the - order they were configured. -3. **Twice-NAT**: Use addresses from twice-nat pools for secondary - translation. - -:::{note} -As soon as you have configured interfaces and pool, the NAT44 is -operational. -::: - -## Static Rules Configuration -Static NAT rules provide predictable and consistent mappings between private -and public IP addresses. They are essential for: -- **Destination NAT (DNAT)**: Allowing external hosts to access services in - the private network. -- **Server publishing**: Making internal services available from the - Internet. -- **Consistent mappings**: Ensuring the same private IP always maps to the - same public IP. - -Unlike dynamic NAT that uses a pool of addresses, static rules create -one-to-one mappings that persist until explicitly removed. - -### Basic Static Rule Configuration -To create a static NAT rule, you need to define the local (internal) and -external (public) address mappings: -```{cfgcmd} set vpp nat nat44 static rule \<rule-number\> local address \<internal-ip\> -``` - -```{cfgcmd} set vpp nat nat44 static rule \<rule-number\> external address \<external-ip\> -``` -Where: -- `<rule-number>` is a unique identifier for the rule -- `<internal-ip>` is the private IP address in your local network -- `<external-ip>` is the public IP address that external hosts will use - -This basic configuration creates a static one-to-one mapping. Traffic from -outside to the external IP will be translated to the internal IP, and vice -versa. - -### Port-based Static Rules -For more granular control, you can create port-specific static rules. This -is useful when you want to publish specific services: -```{cfgcmd} set vpp nat nat44 static rule \<rule-number\> local address \<internal-ip\> -``` - -```{cfgcmd} set vpp nat nat44 static rule \<rule-number\> local port \<internal-port\> -``` - -```{cfgcmd} set vpp nat nat44 static rule \<rule-number\> external address \<external-ip\> -``` - -```{cfgcmd} set vpp nat nat44 static rule \<rule-number\> external port \<external-port\> -``` - -```{cfgcmd} set vpp nat nat44 static rule \<rule-number\> protocol \<protocol\> -``` -Where: -- `<internal-port>` and `<external-port>` are the port numbers used by - the connection. -- `<protocol>` specifies the protocol (tcp, udp, icmp). - -:::{important} -If you do not specify ports and protocol, the rule will apply to *all* -traffic between the specified internal and external addresses. - -Rules must contain either both ports and protocol, or neither. -::: - -### Advanced Static Rule Options -VyOS NAT44 supports several advanced options for static rules: - -#### Twice-NAT -Twice-NAT performs both source and destination NAT. When an external host -accesses an internal service, the source IP of such a connection is -translated to an address from the twice-NAT address pool. - -This is practical in scenarios where internal services cannot connect to -public networks, so they see such traffic as internal. - -The twice-NAT option can be enabled with the following command: -```{cfgcmd} set vpp nat nat44 static rule \<rule-number\> options twice-nat -``` -#### Self Twice-NAT -Self Twice-NAT is used when a local host needs to access itself via the -external address: -```{cfgcmd} set vpp nat nat44 static rule \<rule-number\> options self-twice-nat -``` -This option rewrites source IP addresses on packets sent only from a local -address to an external address configured in a rule. - -:::{important} -- Using `self-twice-nat` option requires you to set the interface - connected to the local network as both inside and outside, because - both source and destination NAT need to be applied. -- External IP address used in static rules must belong to one of the - configured translation pools. -::: - -#### Out-to-In Only -Restricts the rule to only apply to traffic from outside to inside -interfaces: -```{cfgcmd} set vpp nat nat44 static rule \<rule-number\> options out-to-in-only -``` -This prevents the creation of sessions from the inside interface, making it -a purely DNAT rule. - -#### Force Twice-NAT Address -When using twice-nat, you can force the use of a specific IP address from -the twice-nat address pool: -```{cfgcmd} set vpp nat nat44 static rule \<rule-number\> options twice-nat-address \<ip-address\> -``` -#### Rule Description -To document your rules, you can add a description: -```{cfgcmd} set vpp nat nat44 static rule \<rule-number\> description \<description\> -``` -### Static Rules Configuration Examples -**Full one-to-one NAT mapping:** -```none -set vpp nat nat44 static rule 100 local address 192.168.1.10 -set vpp nat nat44 static rule 100 external address 203.0.113.10 -set vpp nat nat44 static rule 100 description "One-to-one mapping" -``` -**Port-specific SSH access:** -```none -set vpp nat nat44 static rule 200 local address 192.168.1.20 -set vpp nat nat44 static rule 200 local port 22 -set vpp nat nat44 static rule 200 external address 203.0.113.10 -set vpp nat nat44 static rule 200 external port 2222 -set vpp nat nat44 static rule 200 protocol tcp -set vpp nat nat44 static rule 200 description "SSH access to server" -``` -**Twice-NAT for local service access:** -```none -set vpp nat nat44 static rule 300 local address 192.168.1.30 -set vpp nat nat44 static rule 300 local port 80 -set vpp nat nat44 static rule 300 external address 203.0.113.10 -set vpp nat nat44 static rule 300 external port 80 -set vpp nat nat44 static rule 300 protocol tcp -set vpp nat nat44 static rule 300 options twice-nat -set vpp nat nat44 static rule 300 description "Web service with twice-nat" -``` -:::{note} -When using twice-nat or self-twice-nat options, ensure you have -configured a twice-nat address pool using: -```none -set vpp nat nat44 address-pool twice-nat address <twice-nat-ip-range> -``` -::: - -## Exclude Rules Configuration -Exclude rules allow you to prevent specific traffic from undergoing NAT -translation. This is particularly useful for: -- **Router management**: Allowing SSH access to the router itself from - external networks. -- **Service bypass**: Excluding specific services from NAT processing -- **Traffic forwarding**: Allowing forwarded traffic to bypass NAT with 1-to-1 - mapping. - -Exclude rules take precedence over both dynamic and static NAT rules, -ensuring that matching traffic bypasses NAT processing. For forwarded -traffic, exclude rules create invisible 1-to-1 mappings that allow packets -to pass through without NAT modifications. - -### Basic Exclude Rule Configuration -To create an exclude rule, you need to specify the traffic characteristics -that should bypass NAT. You can configure exclude rules in two ways: - -**Option 1: Using local address** -```{cfgcmd} set vpp nat nat44 exclude rule \<rule-number\> local-address \<internal-ip\> -``` -**Option 2: Using external interface** -```{cfgcmd} set vpp nat nat44 exclude rule \<rule-number\> external-interface \<interface-name\> -``` -Where: -- `<rule-number>` is a unique identifier for the exclude rule. -- `<internal-ip>` is the local IP address that should be excluded from - : NAT. -- `<interface-name>` is the external interface where the traffic - : originates. - -:::{important} -You must use either `local-address` OR `external-interface` in an -exclude rule, but not both simultaneously. These options are mutually -exclusive. -::: - -### Port-specific Exclude Rules -For more granular control, you can exclude only specific ports and protocols. -You can combine port and protocol specifications with either `local-address` or -`external-interface`: - -**With local address:** -```{cfgcmd} set vpp nat nat44 exclude rule \<rule-number\> local-address \<internal-ip\> -``` - -```{cfgcmd} set vpp nat nat44 exclude rule \<rule-number\> local-port \<port-number\> -``` - -```{cfgcmd} set vpp nat nat44 exclude rule \<rule-number\> protocol \<protocol\> -``` -**With external interface:** -```{cfgcmd} set vpp nat nat44 exclude rule \<rule-number\> external-interface \<interface-name\> -``` - -```{cfgcmd} set vpp nat nat44 exclude rule \<rule-number\> local-port \<port-number\> -``` - -```{cfgcmd} set vpp nat nat44 exclude rule \<rule-number\> protocol \<protocol\> -``` -Where: -- `<port-number>` is the specific port to exclude (1-65535) -- `<protocol>` can be `tcp`, `udp`, `icmp`, or `all` (default) - -### Rule Documentation -Add descriptions to your exclude rules for better management: -```{cfgcmd} set vpp nat nat44 exclude rule \<rule-number\> description \<description\> -``` -### Exclude Rules Configuration Examples -**Exclude SSH access to router:** -```none -# Allow external SSH access to router without NAT -set vpp nat nat44 exclude rule 10 local-address 192.168.1.1 -set vpp nat nat44 exclude rule 10 local-port 22 -set vpp nat nat44 exclude rule 10 protocol tcp -set vpp nat nat44 exclude rule 10 description "SSH access to router" -``` -**Exclude SNMP monitoring:** -```none -# Allow SNMP monitoring without NAT translation -set vpp nat nat44 exclude rule 20 local-port 161 -set vpp nat nat44 exclude rule 20 protocol udp -set vpp nat nat44 exclude rule 20 external-interface eth1 -set vpp nat nat44 exclude rule 20 description "SNMP monitoring" -``` -**Exclude all traffic to router management interface:** -```none -# Exclude all traffic to router's management IP -set vpp nat nat44 exclude rule 30 local-address 192.168.100.1 -set vpp nat nat44 exclude rule 30 description "Management interface bypass" -``` -**Exclude all traffic from external interface:** -```none -# Exclude all traffic from external interface (alternative approach) -set vpp nat nat44 exclude rule 31 external-interface eth1 -set vpp nat nat44 exclude rule 31 description "External interface bypass" -``` -**Exclude forwarded traffic for specific service:** -```none -# Allow external access to internal server without NAT translation -set vpp nat nat44 exclude rule 40 local-address 192.168.1.50 -set vpp nat nat44 exclude rule 40 local-port 8080 -set vpp nat nat44 exclude rule 40 protocol tcp -set vpp nat nat44 exclude rule 40 description "Direct access to internal service" -``` -### Common Use Cases -**Router Administration:** - -Exclude rules are essential when you need to manage the router from external -networks. Without exclude rules, NAT would attempt to translate the router's -own traffic, potentially breaking management connections. - -**Service Monitoring:** - -Network monitoring systems often need direct access to router services. -Exclude rules ensure that monitoring traffic bypasses NAT translation. - -**Routing Protocols:** - -Some routing protocols or network services may require direct communication -without NAT interference. - -**Traffic Forwarding:** - -Exclude rules also work for forwarded traffic between networks. Without -exclude rules, traffic from external to local networks must either match a -static rule or be dropped. With exclude rules, traffic can bypass NAT -processing with invisible 1-to-1 mappings. - -:::{important} -Exclude rules affect both traffic destined for the router itself and -forwarded traffic flowing through the router. For forwarded traffic, exclude -rules create transparent 1-to-1 mappings that allow packets to pass without -NAT modifications, while from the outside perspective, the traffic appears to -bypass NAT entirely. -::: - -## Advanced NAT44 Settings -VyOS provides additional NAT44 settings for fine-tuning performance and -behavior. - -### Session Timeouts -NAT44 maintains translation sessions with configurable timeout values for -different protocols: -```{cfgcmd} set vpp nat nat44 timeout icmp \<seconds\> - -Set the timeout for ICMP sessions (Default: 60 seconds). -``` - -```{cfgcmd} set vpp nat nat44 timeout tcp-established \<seconds\> - -Set the timeout for established TCP connections (Default: 7440 seconds -or 2 hours 4 minutes). -``` - -```{cfgcmd} set vpp nat nat44 timeout tcp-transitory \<seconds\> - -Set the timeout for transitory TCP connections (setup/teardown) (Default: -240 seconds or 4 minutes). -``` - -```{cfgcmd} set vpp nat nat44 timeout udp \<seconds\> - -Set the timeout for UDP sessions (Default: 300 seconds or 5 minutes). -``` -**Example:** -```none -# Customize timeouts for high-traffic environment -set vpp nat nat44 timeout tcp-established 3600 -set vpp nat nat44 timeout udp 600 -set vpp nat nat44 timeout icmp 30 -``` -### Session Limits -Control the maximum number of concurrent NAT sessions: -```{cfgcmd} set vpp nat nat44 session-limit \<number\> - -Set the maximum number of NAT sessions per worker thread (Default: -64512). -``` -This setting helps prevent memory exhaustion and ensures predictable -performance under high load. - -**Example:** -```none -# Increase session limit for high-capacity deployment -set vpp nat nat44 session-limit 100000 -``` -## Complete Configuration Example -Here's a complete example showing how to configure VyOS NAT44 for a typical -network setup: - -**Network Topology:** -```none -Internet (203.0.113.0/24) - | -┌───────────────────┐ -│ eth1 (outside) │ 203.0.113.1/24 -│ VyOS Router │ -│ eth0 (inside) │ 192.168.1.1/24 -└───────────────────┘ - | -Internal Network (192.168.1.0/24) -├── 192.168.1.10 (Web Server) -├── 192.168.1.20 (SSH Server) -└── 192.168.1.30 (API Service) -``` -**Configuration:** -```none -# Configure interfaces -set vpp nat nat44 interface inside eth0 -set vpp nat nat44 interface outside eth1 - -# Configure address pools -set vpp nat nat44 address-pool translation address 203.0.113.10-203.0.113.50 -set vpp nat nat44 address-pool twice-nat address 203.0.113.100-203.0.113.110 - -# Exclude rules for router management -set vpp nat nat44 exclude rule 10 local-address 203.0.113.1 -set vpp nat nat44 exclude rule 10 local-port 22 -set vpp nat nat44 exclude rule 10 protocol tcp -set vpp nat nat44 exclude rule 10 description "SSH access to router" - -set vpp nat nat44 exclude rule 11 local-address 203.0.113.1 -set vpp nat nat44 exclude rule 11 local-port 443 -set vpp nat nat44 exclude rule 11 protocol tcp -set vpp nat nat44 exclude rule 11 description "HTTPS access to router web interface" - -# Static rule for web server (HTTP) -set vpp nat nat44 static rule 100 local address 192.168.1.10 -set vpp nat nat44 static rule 100 local port 80 -set vpp nat nat44 static rule 100 external address 203.0.113.10 -set vpp nat nat44 static rule 100 external port 80 -set vpp nat nat44 static rule 100 protocol tcp -set vpp nat nat44 static rule 100 description "Public web server" - -# Static rule for web server (HTTPS) -set vpp nat nat44 static rule 101 local address 192.168.1.10 -set vpp nat nat44 static rule 101 local port 443 -set vpp nat nat44 static rule 101 external address 203.0.113.10 -set vpp nat nat44 static rule 101 external port 443 -set vpp nat nat44 static rule 101 protocol tcp -set vpp nat nat44 static rule 101 description "Public web server HTTPS" - -# Static rule for SSH server with custom port -set vpp nat nat44 static rule 200 local address 192.168.1.20 -set vpp nat nat44 static rule 200 local port 22 -set vpp nat nat44 static rule 200 external address 203.0.113.11 -set vpp nat nat44 static rule 200 external port 2222 -set vpp nat nat44 static rule 200 protocol tcp -set vpp nat nat44 static rule 200 description "SSH access" - -# Static rule for API service (out-to-in only for security) -set vpp nat nat44 static rule 300 local address 192.168.1.30 -set vpp nat nat44 static rule 300 local port 8080 -set vpp nat nat44 static rule 300 external address 203.0.113.12 -set vpp nat nat44 static rule 300 external port 8080 -set vpp nat nat44 static rule 300 protocol tcp -set vpp nat nat44 static rule 300 options out-to-in-only -set vpp nat nat44 static rule 300 description "API service (No Internet access for it)" -``` -## Best Practices and Troubleshooting - -### Recommendations -- **Use exclude rules** for router management services like SSH -- **Use out-to-in-only** for services that do not need access to external - : networks. -- **Limit port ranges** in static rules to only necessary ports. -- **Document all rules** using descriptions for easier management. -- **Use non-standard ports** for publishing SSH and other administrative - : services. -- **Configure appropriate pool sizes** based on expected concurrent - : connections in your network. - -### Common Configuration Issues -**Static rules not working:** - -1. Verify that the external IP address is included in an address pool -2. Check that interfaces are correctly configured as inside or outside -3. Ensure firewall rules allow the traffic - -**Twice-NAT not functioning:** - -1. Confirm twice-nat pool is configured -2. Verify static rules have the correct twice-nat option -3. Check that both translation and twice-nat pools are properly defined - -**Router management access issues:** - -1. Verify exclude rules are configured for management services -2. Check that local-address matches the router's interface IP -3. Ensure external-interface is correctly specified - -**Forwarded traffic from external networks not bypassing NAT:** - -1. Verify exclude rules are configured for the specific traffic flow -2. Check that local-address matches the destination IP in the internal - network -3. Ensure protocol and port specifications match the traffic requirements - -## Operational Commands -Monitor NAT44 status and active connections using VyOS operational -commands: -```{opcmd} show vpp nat nat44 addresses - -Display configured NAT44 address pools. -``` - -```{opcmd} show vpp nat nat44 interfaces - -Show which interfaces are configured as inside or outside for NAT44. -``` - -```{opcmd} show vpp nat nat44 sessions - -Display active NAT44 translation sessions. -``` - -```{opcmd} show vpp nat nat44 static - -Show all configured static NAT mappings. -``` - -```{opcmd} show vpp nat nat44 summary - -Display a summary of NAT44 and statistics. -```
\ No newline at end of file diff --git a/docs/vpp/md-description.md b/docs/vpp/md-description.md deleted file mode 100644 index 03ade42c..00000000 --- a/docs/vpp/md-description.md +++ /dev/null @@ -1,81 +0,0 @@ ---- -lastproofread: '2026-02-16' ---- - -(vpp-description)= - -```{include} /_include/need_improvement.txt -``` - -# VPP Dataplane Description - -## What is VPP in VyOS? -VyOS supports two packet forwarding dataplanes: -- **Linux kernel dataplane** (traditional) -- **Vector Packet Processor (VPP) dataplane** (optional) - -VPP is a high-performance user space packet processor that improves -throughput for demanding network workloads. - -## Key Benefits - -**Performance Improvement** - -VPP uses vector-based packet processing instead of one-by-one handling, -delivering: -- **Higher throughput** compared to kernel forwarding. -- **Lower and more consistent latency** for time-sensitive applications. -- **Linear scaling** with additional CPU cores. - -**VyOS Hybrid Integration** - -VyOS supports both dataplanes simultaneously, providing: -- **Cross-dataplane forwarding**: Traffic can flow between the VPP dataplane - and kernel interfaces seamlessly. -- **Transparent configuration**: Same CLI commands and most services work - regardless of dataplane. -- **Gradual migration**: Enable VPP on high-traffic interfaces while keeping - others on kernel. - -## When to Use VPP -**Consider VPP if you have:** -- High-throughput requirements -- Latency-sensitive applications requiring consistent performance - -**Stay with kernel dataplane if you have:** -- Low to moderate traffic volumes -- No latency-sensitive workloads -- Applications requiring specific features not supported by VPP Dataplane - -## Packet Processing Integration -VPP Dataplane integration minimizes configuration changes. Features in the -kernel dataplane continue to operate there. VPP Dataplane only handles packet -forwarding for interfaces explicitly assigned to it. - -Traffic flow examples between VPP and kernel dataplane interfaces: -```{image} /_static/images/vpp/vyos_vpp_integration.svg -:align: center -``` - -### Green path - -Traffic between two VPP interfaces stays within VPP for maximum performance -and can use only VPP dataplane features. - -### Blue path - -Traffic between a VPP interface and a kernel interface is processed by both -dataplanes and can use features from both. - -**Note:** This path has slower performance than pure VPP or pure kernel -forwarding because packets traverse both dataplanes. - -### Red path - -Traffic between two kernel interfaces stays within the kernel dataplane without -VPP acceleration. This is the traditional VyOS dataplane operation. - -## CLI Integration - -VyOS CLI commands work with both dataplanes. Use the same commands to -configure interfaces, routing, and other features regardless of the dataplane. diff --git a/docs/vpp/md-index.md b/docs/vpp/md-index.md deleted file mode 100644 index 06b48792..00000000 --- a/docs/vpp/md-index.md +++ /dev/null @@ -1,22 +0,0 @@ ---- -lastproofread: '2025-09-04' ---- - -(vpp-index)= - -```{include} /_include/need_improvement.txt -``` -# VPP Dataplane -VPP (Vector Packet Processing) is a high performance packet processing stack -that runs in user space. VyOS can use VPP as an alternative dataplane to -the Linux kernel networking stack. -```{toctree} -:includehidden: true -:maxdepth: 1 - -description -requirements -limitations -configuration/index -troubleshooting -``` diff --git a/docs/vpp/md-limitations.md b/docs/vpp/md-limitations.md deleted file mode 100644 index e6d43b85..00000000 --- a/docs/vpp/md-limitations.md +++ /dev/null @@ -1,41 +0,0 @@ ---- -lastproofread: '2026-02-17' ---- - -(vpp-limitations)= - -```{include} /_include/need_improvement.txt -``` -# VPP Dataplane Limitations - -VPP Dataplane provides significant performance advantages, but has some -limitations you should consider. - -- **Feature Parity** - - VPP does not support all features available in the Linux kernel dataplane. - Some networking features, specific protocols, or services may not be - available. - - While VPP supports various interface types similar to the kernel, their - capabilities may differ. - -- **NIC and Driver Compatibility** - - VyOS currently supports only DPDK drivers for network interfaces. - Not all network interface cards are compatible with DPDK drivers. - -- **Data Path Limitations** - - If a feature exists only in the kernel dataplane, traffic that uses that - feature cannot traverse VPP interfaces. Examples include: - - - Firewall - - QoS - - When traffic uses the pure VPP path, it does not reach the kernel, where - such features are implemented. Plan how traffic flows through your VyOS - instance to ensure it reaches the necessary features. - - VPP provides native alternatives for some features. For example, VPP - native ACLs provide basic firewall functionality. diff --git a/docs/vpp/md-requirements.md b/docs/vpp/md-requirements.md deleted file mode 100644 index 7758cabd..00000000 --- a/docs/vpp/md-requirements.md +++ /dev/null @@ -1,130 +0,0 @@ ---- -lastproofread: '2026-02-16' ---- - -(vpp-requirements)= - -```{include} /_include/need_improvement.txt -``` - -# VPP Dataplane Requirements - -VPP Dataplane requires specific hardware. Ensure your system meets these -prerequisites before enabling VPP: - -- **Deployment Platform** - - VPP Dataplane is available on both bare-metal, on-premise virtualized, and - cloud deployment platforms. - -- **CPU Requirements** - - Regardless of the platform, VPP Dataplane requires a CPU with: - - - SSE4.2 support (available on most modern Intel and AMD CPUs). - - At least 4 physical CPU cores for a minimum configuration (more cores - recommended for higher throughput). - - :::{important} - **Physical Cores vs Logical Cores** - - VPP Dataplane requires 4 *physical* CPU cores, not logical cores. - Systems with Simultaneous Multithreading (SMT) or Hyper-Threading (HT) - present each physical core as 2 logical cores. - - Cloud providers often display logical cores as "cores" or "vCPUs". - For example, a cloud instance showing "4 cores" may have only 2 physical - cores with SMT/HT enabled. Always verify the actual physical core count - in your cloud provider's documentation. - ::: - - For virtualized environments, ensure CPU features are passed through to the - VM and that sufficient physical cores are allocated. - -- **Memory Requirements** - - Memory significantly affects VPP stability. Insufficient RAM can cause - initialization failures or prevent the dataplane from starting. - - - Minimum: 8 GB RAM. VyOS will not start the VPP Dataplane if less than 8 GB - is available. - - Recommended: 16 GB or more (especially for high throughput, many interfaces, - or large routing tables). - -- **Network Interface Cards (NICs)** - - :::{warning} - VyOS supports only specific NICs for the VPP dataplane. Using unsupported - hardware may cause activation failures, initialization errors, crashes, - or degraded performance. - ::: - - When enabling VPP, VyOS checks detected network interfaces against a list - of validated NICs. Validation is based on the **PCI ID** of the device or - the **kernel driver** used by the interface. - - Supported NICs: - - :::{list-table} - :widths: 15 18 40 35 - :header-rows: 1 - - * - **Filter Type** - - **Filter Value** - - **NIC Name/Description** - - **Platform Where NIC Can Be Found** - * - PCI ID - - 15b3:1019 - - Mellanox Technologies MT28800 Family - [ConnectX-5 Ex] - - Bare-metal - * - PCI ID - - 15b3:101d - - Mellanox Technologies MT2892 Family - [ConnectX-6 Dx] - - Bare-metal - * - PCI ID - - 15b3:101e - - Mellanox Technologies ConnectX Family - mlx5Gen Virtual Function - - Oracle Cloud - * - PCI ID - - 8086:1592 - - Intel Corporation Ethernet Controller - E810-C for QSFP - - Bare-metal - * - PCI ID - - 1ae0:0042 - - Google, Inc. Compute Engine Virtual - Ethernet [gVNIC] - - Google Cloud - * - PCI ID - - 1af4:1000 - - Red Hat, Inc. Virtio network device - - KVM-based hypervisors, including with - Open vSwitch; Google Cloud - * - PCI ID - - 1d0f:ec20 - - Amazon.com, Inc. Elastic Network - Adapter (ENA) - - AWS - * - Kernel Driver - - hv_netvsc - - Microsoft Hyper-V network interface - card - - Microsoft Azure - ::: - - If no supported NIC is detected, VPP activation will be rejected. - - In testing or advanced deployments, unsupported hardware can be explicitly - allowed in the configuration: - - ```{cfgcmd} set vpp settings allow-unsupported-nics - ``` - - :::{note} - This option bypass the hardware validation checks for the specified - devices. Stability and performance are not guaranteed when using - unsupported NICs or drivers. - ::: diff --git a/docs/vpp/md-troubleshooting.md b/docs/vpp/md-troubleshooting.md deleted file mode 100644 index 8e3f977c..00000000 --- a/docs/vpp/md-troubleshooting.md +++ /dev/null @@ -1,412 +0,0 @@ ---- -lastproofread: '2026-02-18' ---- - -(vpp-troubleshooting)= - -```{include} /_include/need_improvement.txt -``` - -# VPP Dataplane Troubleshooting -This page shows you how to collect diagnostic information to troubleshoot VPP -dataplane issues. These techniques help you resolve problems yourself and -provide support teams with the information they need. - -Collecting the right diagnostic data is crucial for effective troubleshooting. - -## Packet Capture (PCAP) -Packet capture is a valuable debugging tool for analyzing network traffic and -identifying issues with packet processing, routing, and filtering. - -`pcap trace` in VPP captures packets at different states: received (rx), -transmitted (tx), and dropped (drop). - -### Starting Packet Capture -**Command syntax:** -```{opcmd} sudo vppctl pcap trace [rx] [tx] [drop] [max \<n\>] [intfc \<interface-name|any\>] [file \<name\>] [max-bytes-per-pkt \<n\>] -``` -**Parameters:** -- `rx` - Capture received packets -- `tx` - Capture transmitted packets -- `drop` - Capture dropped packets -- `max <n>` - Depth of the local buffer. After `n` packets arrive, the - buffer flushes to file. When the next `n` packets arrive, the file - overwrites with new data. (default: 100) -- `intfc <interface-name|any>` - Specify an interface or use `any` for - all interfaces (default: any) -- `file <name>` - Output filename. The PCAP file is stored in the `/tmp/` - directory. -- `max-bytes-per-pkt <n>` - Maximum bytes to capture per packet - (must be >= 32, \<= 9000) - -**Examples:** -```none -# Start capturing tx packets with specific parameters -sudo vppctl pcap trace tx max 35 intfc eth1 file vpp_eth1.pcap - -# Capture all packet types from any interface -sudo vppctl pcap trace rx tx drop max 1000 intfc any file vpp_capture.pcap max-bytes-per-pkt 128 -``` -### Monitoring Capture Status -To check the capture status: -```{opcmd} sudo vppctl pcap trace status -``` -This command displays: -- Whether capture is active -- Capture parameters -- Number of packets captured -- Output file location - -### Stopping Packet Capture - -:::{warning} -VPP does not automatically stop packet captures. If left running, captures -consume resources indefinitely. Always stop captures when you're done -with them. -::: -To stop the active packet capture: -```{opcmd} sudo vppctl pcap trace off -``` -Example output when stopping: -```none -Write 35 packets to /tmp/vpp_eth1.pcap, and stop capture... -``` -**Notes:** -- PCAP files are stored in the `/tmp/` directory. -- Existing files are overwritten. -- If you don't specify a filename, default names are used: `/tmp/rx.pcap`, - `/tmp/tx.pcap`, and `/tmp/rxandtx.pcap`. -- Large captures consume significant disk space—monitor available space. -- Stop captures promptly to avoid filling storage. - -## Packet Tracing -VPP packet tracing shows how packets flow through the VPP processing graph, -including which nodes process each packet and what transformations occur. - -:::{warning} -Tracing generates large amounts of data, especially on high-traffic -systems. Limit the number of traced packets to avoid overwhelming the system. -::: - -### Basic Packet Tracing Commands - -#### Start tracing -To start tracing packets at a specific graph node: -```{opcmd} sudo vppctl trace add \<input-graph-node\> \<pkts\> [verbose] -``` -- `<input-graph-node>` - Graph node name where tracing starts - (for example, `dpdk-input`, `ethernet-input`, or `ip4-input`). -- `<pkts>` - Number of packets to trace (for example, 100). -- `[verbose]` - Optional flag to include detailed buffer information in the - trace output. - -**Common node names for tracing:** -- `dpdk-input`: Packets received from DPDK interfaces -- `ethernet-input`: Ethernet frame processing -- `ip4-input`: IPv4 packet processing -- `ip6-input`: IPv6 packet processing -- `ip4-lookup`: IPv4 routing table lookup -- `ip6-lookup`: IPv6 routing table lookup - -#### View traces -After packets are traced, view the results: -```{opcmd} sudo vppctl show trace [max COUNT] -``` -- `[max COUNT]` - Optional limit on number of packets to display - (default: all) - -#### Clear traces -After reviewing traces, clear them to free up resources: -```{opcmd} sudo vppctl clear trace -``` -#### Example Workflow -```none -# Add traces for 100 packets on dpdk-input node -sudo vppctl trace add dpdk-input 100 - -# Send some traffic, then view results -sudo vppctl show trace - -# Clear traces for next test -sudo vppctl clear trace -``` -### Understanding Trace Output -Trace output shows how packets flow through VPP processing nodes: -```none -Packet 1 - -01:00:09:508438: dpdk-input - eth2 rx queue 0 - buffer 0x8533: current data 0, length 98, buffer-pool 0, ref-count 1, trace handle 0x1000000 - ext-hdr-valid - PKT MBUF: port 1, nb_segs 1, pkt_len 98 - buf_len 1828, data_len 98, ol_flags 0x0, data_off 128, phys_addr 0x78814d40 - packet_type 0x0 l2_len 0 l3_len 0 outer_l2_len 0 outer_l3_len 0 - rss 0x0 fdir.hi 0x0 fdir.lo 0x0 - IP4: 0c:87:6c:4e:00:01 -> 0c:de:0d:e2:00:02 - ICMP: 192.168.102.2 -> 192.168.99.3 - tos 0x00, ttl 64, length 84, checksum 0xb88d dscp CS0 ecn NON_ECN - fragment id 0x37c5, flags DONT_FRAGMENT - ICMP echo_request checksum 0x64e id 3024 -01:00:09:508449: ethernet-input - frame: flags 0x1, hw-if-index 2, sw-if-index 2 - IP4: 0c:87:6c:4e:00:01 -> 0c:de:0d:e2:00:02 -01:00:09:508455: ip4-input - ICMP: 192.168.102.2 -> 192.168.99.3 - tos 0x00, ttl 64, length 84, checksum 0xb88d dscp CS0 ecn NON_ECN - fragment id 0x37c5, flags DONT_FRAGMENT - ICMP echo_request checksum 0x64e id 3024 -01:00:09:508458: ip4-sv-reassembly-feature - [not-fragmented] -01:00:09:508460: nat-pre-in2out - in2out next_index 2 arc_next_index 10 -01:00:09:508462: nat44-ed-in2out - NAT44_IN2OUT_ED_FAST_PATH: sw_if_index 2, next index 10, session 0, translation result 'success' via i2of - i2of match: saddr 192.168.102.2 sport 3024 daddr 192.168.99.3 dport 3024 proto ICMP fib_idx 0 rewrite: saddr 192.168.99.1 daddr 192.168.99.3 icmp-id 3024 txfib 0 - o2if match: saddr 192.168.99.3 sport 3024 daddr 192.168.99.1 dport 3024 proto ICMP fib_idx 0 rewrite: saddr 192.168.99.3 daddr 192.168.102.2 icmp-id 3024 txfib 0 - search key local 192.168.102.2:3024 remote 192.168.99.3:3024 proto ICMP fib 0 thread-index 0 session-index 0 -01:00:09:508469: ip4-lookup - fib 0 dpo-idx 10 flow hash: 0x00000000 - ICMP: 192.168.99.1 -> 192.168.99.3 - tos 0x00, ttl 64, length 84, checksum 0xbb8e dscp CS0 ecn NON_ECN - fragment id 0x37c5, flags DONT_FRAGMENT - ICMP echo_request checksum 0x64e id 3024 -01:00:09:508472: ip4-rewrite - tx_sw_if_index 1 dpo-idx 10 : ipv4 via 192.168.99.3 eth1: mtu:1500 next:5 flags:[] 0ccea70400010cde0de200010800 flow hash: 0x00000000 - 00000000: 0ccea70400010cde0de2000108004500005437c540003f01bc8ec0a86301c0a8 - 00000020: 63030800064e0bd00d9a52c2d26800000000f4490000000000001011 -01:00:09:508474: eth1-output - eth1 flags 0x0038000d - IP4: 0c:de:0d:e2:00:01 -> 0c:ce:a7:04:00:01 - ICMP: 192.168.99.1 -> 192.168.99.3 - tos 0x00, ttl 63, length 84, checksum 0xbc8e dscp CS0 ecn NON_ECN - fragment id 0x37c5, flags DONT_FRAGMENT - ICMP echo_request checksum 0x64e id 3024 -01:00:09:508477: eth1-tx - eth1 tx queue 0 - buffer 0x8533: current data 0, length 98, buffer-pool 0, ref-count 1, trace handle 0x1000000 - ext-hdr-valid - natted l2-hdr-offset 0 l3-hdr-offset 14 - PKT MBUF: port 1, nb_segs 1, pkt_len 98 - buf_len 1828, data_len 98, ol_flags 0x0, data_off 128, phys_addr 0x78814d40 - packet_type 0x0 l2_len 0 l3_len 0 outer_l2_len 0 outer_l3_len 0 - rss 0x0 fdir.hi 0x0 fdir.lo 0x0 - IP4: 0c:de:0d:e2:00:01 -> 0c:ce:a7:04:00:01 - ICMP: 192.168.99.1 -> 192.168.99.3 - tos 0x00, ttl 63, length 84, checksum 0xbc8e dscp CS0 ecn NON_ECN - fragment id 0x37c5, flags DONT_FRAGMENT - ICMP echo_request checksum 0x64e id 3024 -``` -In this example, the trace shows: -- The packet is received on `eth2` interface at the `dpdk-input` node. -- It flows through `ethernet-input` and `ip4-input` nodes. -- NAT translation occurs at the `nat44-ed-in2out` node, changing the source - IP. -- The packet is routed through `ip4-lookup` and `ip4-rewrite` nodes. -- It transmits out of `eth1` interface at the `eth1-tx` node. - -## Additional Diagnostic Information -When reporting issues to support teams or performing advanced troubleshooting, -collect additional diagnostic information. - -### Before/After Traffic Analysis -Before you send traffic: -```none -sudo vppctl clear hardware-interfaces -sudo vppctl clear interfaces -sudo vppctl clear error -sudo vppctl clear runtime -``` -After you send traffic: -```none -sudo vppctl show version verbose -sudo vppctl show hardware-interfaces -sudo vppctl show interface address -sudo vppctl show interface -sudo vppctl show runtime -sudo vppctl show error -``` -### Core System Information -**Memory and buffer information:** -```none -sudo vppctl show memory api-segment stats-segment numa-heaps main-heap map verbose -sudo vppctl show buffers -sudo vppctl show physmem detail -sudo vppctl show physmem map -``` -**Runtime and performance data:** -```none -sudo vppctl show cpu -sudo vppctl show threads -sudo vppctl show runtime -sudo vppctl show node counters -``` -### Protocol-Specific Information -**Layer 2 data (if configured):** -```none -sudo vppctl show l2fib -sudo vppctl show bridge-domain -``` -**IPv4 data (if configured):** -```none -sudo vppctl show ip fib -sudo vppctl show ip neighbors -``` -**IPv6 data (if configured):** -```none -sudo vppctl show ip6 fib -sudo vppctl show ip6 neighbors -``` -**MPLS data (if configured):** -```none -sudo vppctl show mpls fib -sudo vppctl show mpls tunnel -``` -## Creating Support Packages -Use the automated diagnostic collection script to gather comprehensive VPP -troubleshooting information when contacting support or reporting issues. - -### VPP Diagnostic Collection Script -Create the diagnostic collection script: -```python -#!/usr/bin/env python3 -"""VyOS VPP Diagnostic Collection Script""" - -import datetime -import shutil -import subprocess -import tarfile -from pathlib import Path - - -def run_cmd(cmd, output_file, diag_dir): - """Run command and save output to file.""" - try: - result = subprocess.run( - cmd, shell=True, capture_output=True, text=True, timeout=30 - ) - content = f"Command: {cmd}\nExit code: {result.returncode}\nTimestamp: {datetime.datetime.now()}\n{'-' * 50}\n" - if result.stdout: - content += f"\nSTDOUT:\n{result.stdout}" - if result.stderr: - content += f"\nSTDERR:\n{result.stderr}" - (diag_dir / output_file).write_text(content) - except Exception as e: - (diag_dir / output_file).write_text(f"Command: {cmd}\nERROR: {e}") - - -def collect_diagnostics(): - """Collect all VPP diagnostics and create archive.""" - timestamp = datetime.datetime.now().strftime("%Y%m%d-%H%M%S") - diag_dir = Path.home() / f"vpp-diagnostics-{timestamp}" - - # VPP commands to collect - commands = [ - ("sudo vppctl show version verbose cmdline", "vpp-version.txt"), - ("sudo vppctl show hardware-interfaces", "hardware-interfaces.txt"), - ("sudo vppctl show interface address", "interface-addresses.txt"), - ("sudo vppctl show interface", "interfaces.txt"), - ("sudo vppctl show errors", "errors.txt"), - ("sudo vppctl show runtime", "runtime.txt"), - ( - "sudo vppctl show memory api-segment stats-segment numa-heaps main-heap map verbose", - "memory.txt", - ), - ("sudo vppctl show buffers", "buffers.txt"), - ("sudo vppctl show physmem detail", "physmem.txt"), - ("sudo vppctl show physmem map", "physmem-map.txt"), - ("sudo vppctl show cpu", "cpu.txt"), - ("sudo vppctl show threads", "threads.txt"), - ("sudo vppctl show node counters", "node-counters.txt"), - ("sudo vppctl show l2fib", "l2fib.txt"), - ("sudo vppctl show bridge-domain", "bridge-domains.txt"), - ("sudo vppctl show ip fib", "ip4-fib.txt"), - ("sudo vppctl show ip neighbors", "ip4-neighbors.txt"), - ("sudo vppctl show ip6 fib", "ip6-fib.txt"), - ("sudo vppctl show ip6 neighbors", "ip6-neighbors.txt"), - ("sudo vppctl show mpls fib", "mpls-fib.txt"), - ("sudo vppctl show mpls tunnel", "mpls-tunnels.txt"), - ("sudo vppctl show trace", "packet-traces.txt"), - ] - - try: - # Create diagnostics directory - diag_dir.mkdir(parents=True, exist_ok=True) - - # Collect VPP data - for cmd, output_file in commands: - run_cmd(cmd, output_file, diag_dir) - - # Collect PCAP files - pcap_files = list(Path("/tmp").glob("*.pcap")) - if pcap_files: - pcap_dir = diag_dir / "pcap-files" - pcap_dir.mkdir(exist_ok=True) - for pcap_file in pcap_files: - try: - shutil.copy2(pcap_file, pcap_dir) - except (PermissionError, OSError): - pass - - # Create archive - archive_name = f"vpp-diagnostics-{timestamp}.tar.gz" - archive_path = Path.home() / archive_name - - with tarfile.open(archive_path, "w:gz") as tar: - tar.add(diag_dir, arcname=diag_dir.name) - - # Cleanup - shutil.rmtree(diag_dir) - - print(f"VPP diagnostics collected: {archive_path}") - return archive_path - - except Exception as e: - if diag_dir.exists(): - shutil.rmtree(diag_dir) - print(f"Collection failed: {e}") - return None - - -def main(): - """Main function.""" - collect_diagnostics() - - -if __name__ == "__main__": - main() -``` -Save this script as `/config/scripts/vpp-collect-diagnostics` - -### Installation and Usage -**1. Make the script executable** -```{opcmd} sudo chmod +x /config/scripts/vpp-collect-diagnostics -``` -**2. Run VPP diagnostic collection** - -The script automatically collects all diagnostics and stores them in your home -directory. -```{opcmd} /config/scripts/vpp-collect-diagnostics -``` -**3. Generate VyOS tech-support archive separately** -You can also generate a tech-support archive with system-wide diagnostics: -```{opcmd} generate tech-support archive -``` - -### What the Script Collects - -- **System information**: Version details, build information, command-line - parameters. -- **Interface data**: Hardware interfaces, interface addresses, statistics, - and configurations. -- **Performance metrics**: Runtime statistics, error counters, node counters, - CPU, and thread information. -- **Memory analysis**: Memory usage (API segment, stats segment, NUMA heaps, - main heap), buffers, and physical memory. -- **Layer 2 data**: L2 forwarding table (L2FIB) and bridge domain - configurations. -- **IPv4 data**: IPv4 forwarding table (FIB) and IPv4 neighbor table. -- **IPv6 data**: IPv6 forwarding table (FIB) and IPv6 neighbor table. -- **MPLS data**: MPLS forwarding table (FIB) and MPLS tunnel information. -- **Packet traces**: Captured packet traces (if available). -- **Packet captures**: PCAP files from the `/tmp` directory (if available). |