From dad139434e34d3bbf24fd46c8fa8ea7a54177d0a Mon Sep 17 00:00:00 2001 From: Yuriy Andamasov Date: Mon, 30 Mar 2026 13:33:30 +0300 Subject: Split troubleshooting, add contributing index, clean VPN structure (#1804) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit * Add design spec for documentation improvements Covers 4 work streams: mechanical fixes (headings, indentation, typos), content quality (TODO flags, TBD fills, stub markers), structural reorganization (troubleshooting split, contributing index, VPN cleanup), and RTD platform cleanup (hide versions, delete stale redirects). Co-Authored-By: Claude Opus 4.6 (1M context) * Fix spec issues from review: correct heading chars, tab counts, line numbers Addresses 10 reviewer findings: corrected heading character types (^ was actually -), removed ip.rst (already correct), updated file count from 37 to 35, listed all 13 tab-containing files, fixed troubleshooting line count to 460, added heading level guidance for split pages, clarified contributing/documentation.rst scope, removed current from hide list, added rollback verification step, updated success criteria. Co-Authored-By: Claude Opus 4.6 (1M context) * Add implementation plan for documentation improvements 16 tasks across 4 work streams: mechanical fixes (PR 1, tasks 1-6), content quality (PR 2, tasks 7-10), structural reorg (PR 3, tasks 11-14), and RTD platform cleanup (tasks 15-16). Co-Authored-By: Claude Opus 4.6 (1M context) * Fix 6 issues from plan review - Replace hardcoded RTD token with $RTD_TOKEN variable - Fix Task 7 heading reference to be format-agnostic - Correct RTD PATCH expected response (200, not 204) - Fix version verification to check hidden field, not active - Account for blank lines 402-403 in troubleshooting split - Clarify start/stop_vyoslinter handling in system.rst Co-Authored-By: Claude Opus 4.6 (1M context) * refactor: split troubleshooting into 5 focused sub-pages Split monolithic 460-line troubleshooting/index.rst into: - connectivity.rst (ping, traceroute, mtr, IPv6 discovery) - interfaces.rst (interface naming, MAC addresses) - monitoring.rst (traffic dumps, bandwidth, iperf) - terminal.rst (console clearing, counter resets) - system.rst (boot steps, system information) Co-Authored-By: Claude Sonnet 4.6 * refactor: create contributing/index.rst, simplify root toctree * fix: remove 'pages to sort' placeholders from VPN section * fix: wrap long lines in index.rst for linter compliance * Add design spec for sitemap generation improvement * Fix sitemap spec: remove invalid sitemap_excludes, add version pin * fix: address Copilot review suggestions — grammar, typos, RST markup fixes Co-Authored-By: Claude Sonnet 4.6 * fix: resolve remaining long lines in index.rst Shorten :ref: display text on two lines that exceeded the 80-char limit: "Virtual Environment" -> "VM" (line 24, 90 -> 73 chars) and "Configuration Blueprints" -> "Blueprints" (line 51, 85 -> 71 chars). Both targets remain correct; display text is clear in context. Co-Authored-By: Claude Sonnet 4.6 * chore: remove superpowers specs from PR Specs moved to personal branch yuriy/docs-modernization-specs. Co-Authored-By: Claude Opus 4.6 (1M context) --------- Co-authored-by: Claude Opus 4.6 (1M context) --- docs/configuration/vpn/ipsec/index.rst | 8 -------- 1 file changed, 8 deletions(-) (limited to 'docs/configuration/vpn/ipsec') diff --git a/docs/configuration/vpn/ipsec/index.rst b/docs/configuration/vpn/ipsec/index.rst index e454e2f6..7647d8d2 100644 --- a/docs/configuration/vpn/ipsec/index.rst +++ b/docs/configuration/vpn/ipsec/index.rst @@ -11,11 +11,3 @@ IPsec site2site_ipsec remoteaccess_ipsec troubleshooting_ipsec - -pages to sort - -.. toctree:: - :maxdepth: 1 - :includehidden: - - -- cgit v1.2.3 From a01c2c4ed50470141e7d7bbd31a3ab17418e9936 Mon Sep 17 00:00:00 2001 From: Yuriy Andamasov Date: Mon, 30 Mar 2026 14:11:57 +0300 Subject: Add TODO markers, fill placeholders, mark stub pages (#1802) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit * chore: add TODO markers for 12 files needing cfgcmd/opcmd conversion Co-Authored-By: Claude Sonnet 4.6 * fix: fill TBD placeholder in flow-accounting, remove TBD in static routes Co-Authored-By: Claude Sonnet 4.6 * docs: add stub admonitions to 3 minimal pages Co-Authored-By: Claude Sonnet 4.6 * fix: replace non-RFC IP addresses and suppress false positives in linter Replace public IPs with RFC 5737 documentation addresses and add stop/start_vyoslinter markers for false positives (MAC addresses, OIDs, NAT64 well-known prefix). Co-Authored-By: Claude Sonnet 4.6 * fix: replace remaining non-RFC IPs and suppress MAC address false positive - Replace 8.8.8.8 (Google DNS) with 192.0.2.1 (RFC 5737) in: - docs/configexamples/ansible.rst (3 occurrences) - docs/configexamples/nmp.rst (1 occurrence) - docs/automation/terraform/terraformvSphere.rst (1 occurrence) - Wrap SHA-256 certificate fingerprint in openvpn-examples.rst with stop_vyoslinter/start_vyoslinter to suppress false-positive IPv6 flag Co-Authored-By: Claude Sonnet 4.6 * fix: wrap long lines to comply with 80-char line length limit Wrapped prose content exceeding 80 characters in 9 documentation files. Only RST prose and directive content was modified; code block contents were left untouched as they are exempt from the linter. Co-Authored-By: Claude Sonnet 4.6 * fix: wrap 2 remaining long lines for linter compliance Co-Authored-By: Claude Opus 4.6 (1M context) * fix: suppress linter for long URL reference in terraformvSphere.rst * fix: address Copilot review suggestions — broken links, typos, YAML indentation - Fix broken inline RST links split across lines in sysctl.rst, eve-ng.rst, oracle.rst (stub notes with VyOS documentation repository link) - Fix YAML indentation in both playbook code blocks in ansible.rst - Fix typo "VyoS" -> "VyOS" in ansible.rst - Fix typo "desition" -> "decision" in terraformvSphere.rst - Fix 4 occurrences of "Terrafom" -> "Terraform" in terraformvSphere.rst - Fix :doc: role split across two lines in openvpn-examples.rst - Wrap long paragraph in openconnect.rst to <=80 chars and remove unnecessary stop/start_vyoslinter markers Co-Authored-By: Claude Sonnet 4.6 * fix: resolve remaining linter failures — long lines and OID false positive Co-Authored-By: Claude Sonnet 4.6 * fix: revert 8.8.8.8 replacements, use stop_vyoslinter instead --------- Co-authored-by: Claude Sonnet 4.6 --- docs/automation/terraform/terraformvSphere.rst | 45 ++-- docs/configexamples/ansible.rst | 264 +++++++++++---------- docs/configexamples/fwall-and-bridge.rst | 12 +- docs/configexamples/nmp.rst | 18 +- docs/configexamples/site-2-site-cisco.rst | 10 +- docs/configuration/firewall/index.rst | 3 + docs/configuration/interfaces/openvpn-examples.rst | 21 +- docs/configuration/interfaces/vti.rst | 3 + docs/configuration/nat/nat64.rst | 7 + docs/configuration/nat/nat66.rst | 8 +- docs/configuration/policy/examples.rst | 3 + docs/configuration/protocols/static.rst | 35 +-- docs/configuration/service/snmp.rst | 3 + docs/configuration/system/flow-accounting.rst | 4 +- docs/configuration/system/sysctl.rst | 6 + .../vpn/ipsec/troubleshooting_ipsec.rst | 7 +- docs/configuration/vpn/openconnect.rst | 20 +- docs/configuration/vpn/rsa-keys.rst | 16 +- docs/installation/cloud/oracle.rst | 6 + docs/installation/virtual/eve-ng.rst | 6 + 20 files changed, 309 insertions(+), 188 deletions(-) (limited to 'docs/configuration/vpn/ipsec') diff --git a/docs/automation/terraform/terraformvSphere.rst b/docs/automation/terraform/terraformvSphere.rst index 5d39261b..5a9aa8f5 100644 --- a/docs/automation/terraform/terraformvSphere.rst +++ b/docs/automation/terraform/terraformvSphere.rst @@ -5,22 +5,27 @@ Deploying VyOS in the vSphere infrastructure ============================================ -With the help of Terraform, you can quickly deploy VyOS-based infrastructure in the vSphere. +With the help of Terraform, you can quickly deploy VyOS-based +infrastructure in the vSphere. Also we will make provisioning using Ansible. -In this case, we'll create the necessary files for Terraform and Ansible next using Terraform we'll create a single instance on the vSphere cloud and make provisioning using Ansible. +In this case, we'll create the necessary files for Terraform and +Ansible next using Terraform we'll create a single instance on the +vSphere cloud and make provisioning using Ansible. Preparation steps for deploying VyOS on vSphere ----------------------------------------------- -How to create a single instance and install your configuration using Terraform+Ansible+vSphere +How to create a single instance and install your configuration using +Terraform+Ansible+vSphere Step by step: vSphere - 1 Collect all data in to file "terraform.tfvars" and create resources for example "terraform" + 1 Collect all data in to file "terraform.tfvars" and create + resources for example "terraform" Terraform @@ -37,7 +42,10 @@ Terraform mkdir /root/vsphereterraform - 4 Copy all files into your Terraform project "/root/vsphereterraform" (vyos.tf, var.tf, terraform.tfvars,version.tf), more detailed see `Structure of files Terrafom for vSphere`_ + 4 Copy all files into your Terraform project + "/root/vsphereterraform" (vyos.tf, var.tf, terraform.tfvars, + version.tf), more detailed see + `Structure of files Terraform for vSphere`_ 5 Type the commands : @@ -56,13 +64,15 @@ Ansible 3 Create the folder for example /root/vsphereterraform/ - 4 Copy all files into your Ansible project "/root/vsphereterraform/" (ansible.cfg, instance.yml,"all"), more detailed see `Structure of files Ansible for vSphere`_ + 4 Copy all files into your Ansible project + "/root/vsphereterraform/" (ansible.cfg, instance.yml, "all"), + more detailed see `Structure of files Ansible for vSphere`_ Start -Type the commands on your Terrafom instance: +Type the commands on your Terraform instance: .. code-block:: none @@ -72,7 +82,8 @@ Type the commands on your Terrafom instance: yes -After executing all the commands you will have your VyOS instance on the vSphere with your configuration, it's a very convenient desition. +After executing all the commands you will have your VyOS instance on +the vSphere with your configuration, it's a very convenient decision. If you need to delete the instance please type the command: .. code-block:: none @@ -80,19 +91,19 @@ If you need to delete the instance please type the command: terraform destroy -Structure of files Terrafom for vSphere +Structure of files Terraform for vSphere --------------------------------------- .. code-block:: none . - ├── vyos.tf # The main script - ├── versions.tf # File for the changing version of Terraform. - ├── var.tf # File for the changing version of Terraform. - └── terraform.tfvars # The value of all variables (passwords, login, ip adresses and so on) + ├── vyos.tf # The main script + ├── versions.tf # File for the changing version of Terraform. + ├── var.tf # File for the changing version of Terraform. + └── terraform.tfvars # The value of all variables -File contents of Terrafom for vSphere +File contents of Terraform for vSphere ------------------------------------- vyos.tf @@ -373,7 +384,7 @@ instance.yml - name: "Configure general settings for the VyOS hosts group" vyos_config: lines: - - set system name-server 8.8.8.8 + - set system name-server 192.0.2.1 save: true @@ -396,5 +407,9 @@ Sourse files for vSphere from GIT All files about the article can be found here_ +.. stop_vyoslinter + .. _here: https://github.com/vyos/vyos-automation/tree/main/TerraformCloud/Vsphere_terraform_ansible_single_vyos_instance-main +.. start_vyoslinter + diff --git a/docs/configexamples/ansible.rst b/docs/configexamples/ansible.rst index 0f4dbbda..4241c706 100644 --- a/docs/configexamples/ansible.rst +++ b/docs/configexamples/ansible.rst @@ -9,7 +9,8 @@ Ansible example Setting up Ansible on a server running the Debian operating system. =================================================================== -In this example, we will set up a simple use of Ansible to configure multiple VyoS routers. +In this example, we will set up a simple use of Ansible to configure +multiple VyOS routers. We have four pre-configured routers with this configuration: Using the general schema for example: @@ -23,10 +24,10 @@ We have four pre-configured routers with this configuration: .. code-block:: none - set interfaces ethernet eth0 address dhcp - set service ssh - commit - save + set interfaces ethernet eth0 address dhcp + set service ssh + commit + save * vyos7 - 192.0.2.105 * vyos8 - 192.0.2.106 @@ -37,180 +38,189 @@ Install Ansible: ==================== .. code-block:: none - # apt-get install ansible - Do you want to continue? [Y/n] y + # apt-get install ansible + Do you want to continue? [Y/n] y Install Paramiko: ===================== .. code-block:: none - #apt-get install -y python3-paramiko + #apt-get install -y python3-paramiko Check the version: ================== .. code-block:: none - # ansible --version - ansible 2.10.8 - config file = None - configured module search path = ['/root/.ansible/plugins/modules', '/usr/share/ansible/plugins/modules'] - ansible python module location = /usr/lib/python3/dist-packages/ansible - executable location = /usr/bin/ansible - python version = 3.9.2 (default, Feb 28 2021, 17:03:44) [GCC 10.2.1 20210110] + # ansible --version + ansible 2.10.8 + config file = None + configured module search path = ['/root/.ansible/plugins/modules', '/usr/share/ansible/plugins/modules'] + ansible python module location = /usr/lib/python3/dist-packages/ansible + executable location = /usr/bin/ansible + python version = 3.9.2 (default, Feb 28 2021, 17:03:44) [GCC 10.2.1 20210110] Basic configuration of ansible.cfg: ======================================= .. code-block:: none - # nano /root/ansible.cfg - [defaults] - host_key_checking = no + # nano /root/ansible.cfg + [defaults] + host_key_checking = no Add all the VyOS hosts: ======================= .. code-block:: none - # nano /root/hosts - [vyos_hosts] - vyos7 ansible_ssh_host=192.0.2.105 - vyos8 ansible_ssh_host=192.0.2.106 - vyos9 ansible_ssh_host=192.0.2.107 - vyos10 ansible_ssh_host=192.0.2.108 + # nano /root/hosts + [vyos_hosts] + vyos7 ansible_ssh_host=192.0.2.105 + vyos8 ansible_ssh_host=192.0.2.106 + vyos9 ansible_ssh_host=192.0.2.107 + vyos10 ansible_ssh_host=192.0.2.108 Add general variables: ====================== .. code-block:: none - # mkdir /root/group_vars/ - # nano /root/group_vars/vyos_hosts - ansible_python_interpreter: /usr/bin/python3 - ansible_network_os: vyos - ansible_connection: network_cli - ansible_user: vyos - ansible_ssh_pass: vyos + # mkdir /root/group_vars/ + # nano /root/group_vars/vyos_hosts + ansible_python_interpreter: /usr/bin/python3 + ansible_network_os: vyos + ansible_connection: network_cli + ansible_user: vyos + ansible_ssh_pass: vyos Add a simple playbook with the tasks for each router: ===================================================== +.. stop_vyoslinter + .. code-block:: none - # nano /root/main.yml - - --- - - hosts: vyos_hosts - gather_facts: 'no' - tasks: - - name: Configure general settings for the vyos hosts group - vyos_config: - lines: - - set system name-server 8.8.8.8 - - set interfaces ethernet eth0 description '#WAN#' - - set interfaces ethernet eth1 description '#LAN#' - - set interfaces ethernet eth2 disable - - set interfaces ethernet eth3 disable - - set system host-name {{ inventory_hostname }} - save: - true - + # nano /root/main.yml + + --- + - hosts: vyos_hosts + gather_facts: 'no' + tasks: + - name: Configure general settings for the vyos hosts group + vyos_config: + lines: + - set system name-server 8.8.8.8 + - set interfaces ethernet eth0 description '#WAN#' + - set interfaces ethernet eth1 description '#LAN#' + - set interfaces ethernet eth2 disable + - set interfaces ethernet eth3 disable + - set system host-name {{ inventory_hostname }} + save: true + +.. start_vyoslinter + Start the playbook: =================== .. code-block:: none - ansible-playbook -i hosts main.yml - PLAY [vyos_hosts] ************************************************************** - - TASK [Configure general settings for the vyos hosts group] ********************* - ok: [vyos9] - ok: [vyos10] - ok: [vyos7] - ok: [vyos8] - - PLAY RECAP ********************************************************************* - vyos10 : ok=2 changed=0 unreachable=0 failed=0 skipped=0 rescued=0 ignored=0 - vyos7 : ok=2 changed=0 unreachable=0 failed=0 skipped=0 rescued=0 ignored=0 - vyos8 : ok=2 changed=0 unreachable=0 failed=0 skipped=0 rescued=0 ignored=0 - vyos9 : ok=2 changed=0 unreachable=0 failed=0 skipped=0 rescued=0 ignored=0 + ansible-playbook -i hosts main.yml + PLAY [vyos_hosts] ************************************************************** + + TASK [Configure general settings for the vyos hosts group] ********************* + ok: [vyos9] + ok: [vyos10] + ok: [vyos7] + ok: [vyos8] + + PLAY RECAP ********************************************************************* + vyos10 : ok=2 changed=0 unreachable=0 failed=0 skipped=0 rescued=0 ignored=0 + vyos7 : ok=2 changed=0 unreachable=0 failed=0 skipped=0 rescued=0 ignored=0 + vyos8 : ok=2 changed=0 unreachable=0 failed=0 skipped=0 rescued=0 ignored=0 + vyos9 : ok=2 changed=0 unreachable=0 failed=0 skipped=0 rescued=0 ignored=0 Check the result on the vyos10 router: ====================================== +.. stop_vyoslinter + .. code-block:: none - vyos@vyos10:~$ show interfaces - Codes: S - State, L - Link, u - Up, D - Down, A - Admin Down - Interface IP Address S/L Description - --------- ---------- --- ----------- - eth0 192.0.2.108/24 u/u WAN - eth1 - u/u LAN - eth2 - A/D - eth3 - A/D - lo 127.0.0.1/8 u/u - ::1/128 - - vyos@vyos10:~$ sh configuration commands | grep 8.8.8.8 - set system name-server '8.8.8.8' + vyos@vyos10:~$ show interfaces + Codes: S - State, L - Link, u - Up, D - Down, A - Admin Down + Interface IP Address S/L Description + --------- ---------- --- ----------- + eth0 192.0.2.108/24 u/u WAN + eth1 - u/u LAN + eth2 - A/D + eth3 - A/D + lo 127.0.0.1/8 u/u + ::1/128 + + vyos@vyos10:~$ sh configuration commands | grep 8.8.8.8 + set system name-server '8.8.8.8' + +.. start_vyoslinter The simple way without configuration of the hostname (one task for all routers): ================================================================================ +.. stop_vyoslinter + .. code-block:: none - # nano /root/hosts_v2 - [vyos_hosts_group] - vyos7 ansible_ssh_host=192.0.2.105 - vyos8 ansible_ssh_host=192.0.2.106 - vyos9 ansible_ssh_host=192.0.2.107 - vyos10 ansible_ssh_host=192.0.2.108 - [vyos_hosts_group:vars] - ansible_python_interpreter=/usr/bin/python3 - ansible_user=vyos - ansible_ssh_pass=vyos - ansible_network_os=vyos - ansible_connection=network_cli - - # nano /root/main_v2.yml - --- - - hosts: vyos_hosts_group - - connection: network_cli - gather_facts: 'no' - - tasks: - - name: Configure remote vyos_hosts_group - vyos_config: - lines: - - set system name-server 8.8.8.8 - - set interfaces ethernet eth0 description WAN - - set interfaces ethernet eth1 description LAN - - set interfaces ethernet eth2 disable - - set interfaces ethernet eth3 disable - save: - true - + # nano /root/hosts_v2 + [vyos_hosts_group] + vyos7 ansible_ssh_host=192.0.2.105 + vyos8 ansible_ssh_host=192.0.2.106 + vyos9 ansible_ssh_host=192.0.2.107 + vyos10 ansible_ssh_host=192.0.2.108 + [vyos_hosts_group:vars] + ansible_python_interpreter=/usr/bin/python3 + ansible_user=vyos + ansible_ssh_pass=vyos + ansible_network_os=vyos + ansible_connection=network_cli + + # nano /root/main_v2.yml + --- + - hosts: vyos_hosts_group + connection: network_cli + gather_facts: 'no' + tasks: + - name: Configure remote vyos_hosts_group + vyos_config: + lines: + - set system name-server 8.8.8.8 + - set interfaces ethernet eth0 description WAN + - set interfaces ethernet eth1 description LAN + - set interfaces ethernet eth2 disable + - set interfaces ethernet eth3 disable + save: true + +.. start_vyoslinter + .. code-block:: none - - # ansible-playbook -i hosts_v2 main_v2.yml - - PLAY [vyos_hosts_group] ******************************************************** - - TASK [Configure remote vyos_hosts_group] *************************************** - ok: [vyos8] - ok: [vyos7] - ok: [vyos9] - ok: [vyos10] - - PLAY RECAP ********************************************************************* - vyos10 : ok=1 changed=0 unreachable=0 failed=0 skipped=0 rescued=0 ignored=0 - vyos7 : ok=1 changed=0 unreachable=0 failed=0 skipped=0 rescued=0 ignored=0 - vyos8 : ok=1 changed=0 unreachable=0 failed=0 skipped=0 rescued=0 ignored=0 - vyos9 : ok=1 changed=0 unreachable=0 failed=0 skipped=0 rescued=0 ignored=0 - - -In the next chapter of the example, we'll use Ansible with jinja2 templates and variables. + + # ansible-playbook -i hosts_v2 main_v2.yml + + PLAY [vyos_hosts_group] ******************************************************** + + TASK [Configure remote vyos_hosts_group] *************************************** + ok: [vyos8] + ok: [vyos7] + ok: [vyos9] + ok: [vyos10] + + PLAY RECAP ********************************************************************* + vyos10 : ok=1 changed=0 unreachable=0 failed=0 skipped=0 rescued=0 ignored=0 + vyos7 : ok=1 changed=0 unreachable=0 failed=0 skipped=0 rescued=0 ignored=0 + vyos8 : ok=1 changed=0 unreachable=0 failed=0 skipped=0 rescued=0 ignored=0 + vyos9 : ok=1 changed=0 unreachable=0 failed=0 skipped=0 rescued=0 ignored=0 + + +In the next chapter of the example, we'll use Ansible with jinja2 +templates and variables. diff --git a/docs/configexamples/fwall-and-bridge.rst b/docs/configexamples/fwall-and-bridge.rst index 32c53fa5..34744a5d 100644 --- a/docs/configexamples/fwall-and-bridge.rst +++ b/docs/configexamples/fwall-and-bridge.rst @@ -353,12 +353,16 @@ For example, while a host tries to get an IP address from a DHCP server in br1 all DHCP discover are dropped, and in br2, we can see that DHCP offers from untrusted servers are dropped: +.. stop_vyoslinter + .. code-block:: none - vyos@bridge:~$ show log firewall bridge - Sep 17 14:22:35 kernel: [bri-NAM-br2-fwd-22-D]IN=eth7 OUT=eth5 MAC=50:00:00:09:00:00:50:00:00:04:00:00:08:00 SRC=10.2.2.199 DST=10.2.2.92 LEN=322 TOS=0x10 PREC=0x00 TTL=128 ID=0 DF PROTO=UDP SPT=67 DPT=68 LEN=302 - Sep 17 14:28:18 kernel: [bri-NAM-br1-pre-10-D]IN=eth3 OUT= MAC=ff:ff:ff:ff:ff:ff:00:50:79:66:68:0c:08:00 SRC=0.0.0.0 DST=255.255.255.255 LEN=392 TOS=0x10 PREC=0x00 TTL=16 ID=0 PROTO=UDP SPT=68 DPT=67 LEN=372 - Sep 17 14:28:19 kernel: [bri-NAM-br1-pre-10-D]IN=eth3 OUT= MAC=ff:ff:ff:ff:ff:ff:00:50:79:66:68:0c:08:00 SRC=0.0.0.0 DST=255.255.255.255 LEN=392 TOS=0x10 PREC=0x00 TTL=16 ID=0 PROTO=UDP SPT=68 DPT=67 LEN=372 + vyos@bridge:~$ show log firewall bridge + Sep 17 14:22:35 kernel: [bri-NAM-br2-fwd-22-D]IN=eth7 OUT=eth5 MAC=50:00:00:09:00:00:50:00:00:04:00:00:08:00 SRC=10.2.2.199 DST=10.2.2.92 LEN=322 TOS=0x10 PREC=0x00 TTL=128 ID=0 DF PROTO=UDP SPT=67 DPT=68 LEN=302 + Sep 17 14:28:18 kernel: [bri-NAM-br1-pre-10-D]IN=eth3 OUT= MAC=ff:ff:ff:ff:ff:ff:00:50:79:66:68:0c:08:00 SRC=0.0.0.0 DST=255.255.255.255 LEN=392 TOS=0x10 PREC=0x00 TTL=16 ID=0 PROTO=UDP SPT=68 DPT=67 LEN=372 + Sep 17 14:28:19 kernel: [bri-NAM-br1-pre-10-D]IN=eth3 OUT= MAC=ff:ff:ff:ff:ff:ff:00:50:79:66:68:0c:08:00 SRC=0.0.0.0 DST=255.255.255.255 LEN=392 TOS=0x10 PREC=0x00 TTL=16 ID=0 PROTO=UDP SPT=68 DPT=67 LEN=372 + +.. start_vyoslinter And with operational mode commands, we can check rules matchers, actions, and diff --git a/docs/configexamples/nmp.rst b/docs/configexamples/nmp.rst index 913e7107..318e9a91 100644 --- a/docs/configexamples/nmp.rst +++ b/docs/configexamples/nmp.rst @@ -7,19 +7,25 @@ NMP example ########### Consider how to quickly set up NMP and VyOS for monitoring. -NMP is multi-vendor network monitoring from 'SolarWinds' built to scale and expand with the needs of your network. +NMP is multi-vendor network monitoring from 'SolarWinds' built to +scale and expand with the needs of your network. Configuration 'VyOS' ==================== -First prepare our VyOS router for connection to NMP. We have to set up the SNMP protocol and connectivity between the router and NMP. +First prepare our VyOS router for connection to NMP. We have to set +up the SNMP protocol and connectivity between the router and NMP. + +.. stop_vyoslinter .. code-block:: none - set interfaces ethernet eth0 address 'dhcp' - set system name-server '8.8.8.8' - set service snmp community router authorization 'test' - set service snmp community router network '0.0.0.0/0' + set interfaces ethernet eth0 address 'dhcp' + set system name-server '8.8.8.8' + set service snmp community router authorization 'test' + set service snmp community router network '0.0.0.0/0' + +.. start_vyoslinter Configuration 'NMP' diff --git a/docs/configexamples/site-2-site-cisco.rst b/docs/configexamples/site-2-site-cisco.rst index 96e48d07..5b5f1fd7 100644 --- a/docs/configexamples/site-2-site-cisco.rst +++ b/docs/configexamples/site-2-site-cisco.rst @@ -28,7 +28,7 @@ VyOS set interfaces tunnel tun1 ip adjust-mss '1336' set interfaces tunnel tun1 mtu '1376' set interfaces tunnel tun1 remote '10.1.1.6' - set interfaces tunnel tun1 source-address '88.2.2.1' + set interfaces tunnel tun1 source-address '198.51.100.1' - IPsec: @@ -59,9 +59,9 @@ VyOS set vpn ipsec site-to-site peer cisco_hub connection-type 'initiate' set vpn ipsec site-to-site peer cisco_hub default-esp-group 'e1' set vpn ipsec site-to-site peer cisco_hub ike-group 'i1' - set vpn ipsec site-to-site peer cisco_hub local-address '88.2.2.1' + set vpn ipsec site-to-site peer cisco_hub local-address '198.51.100.1' set vpn ipsec site-to-site peer cisco_hub remote-address '10.1.1.6' - set vpn ipsec site-to-site peer cisco_hub tunnel 1 local prefix '88.2.2.1/32' + set vpn ipsec site-to-site peer cisco_hub tunnel 1 local prefix '198.51.100.1/32' set vpn ipsec site-to-site peer cisco_hub tunnel 1 protocol 'gre' set vpn ipsec site-to-site peer cisco_hub tunnel 1 remote prefix '10.1.1.6/32' set vpn ipsec site-to-site peer cisco_hub virtual-address '0.0.0.0' @@ -141,7 +141,7 @@ Verification --------- ---------- --- ----------- eth0 - u/u eth1 - u/u - eth2 88.2.2.1/24 u/u + eth2 198.51.100.1/24 u/u eth3 172.16.1.2/24 u/u lo 127.0.0.1/8 u/u ::1/128 @@ -157,7 +157,7 @@ Verification IPv4 Crypto IKEv2 SA Tunnel-id Local Remote fvrf/ivrf Status - 5 10.1.1.6/4500 88.2.2.1/4500 none/none READY + 5 10.1.1.6/4500 198.51.100.1/4500 none/none READY Encr: AES-CBC, keysize: 256, PRF: SHA256, Hash: SHA256, DH Grp:5, Auth sign: PSK, Auth verify: PSK Life/Active Time: 86400/2694 sec CE id: 0, Session-id: 2 diff --git a/docs/configuration/firewall/index.rst b/docs/configuration/firewall/index.rst index a5b88839..79d59563 100644 --- a/docs/configuration/firewall/index.rst +++ b/docs/configuration/firewall/index.rst @@ -4,6 +4,9 @@ Firewall ######## +.. TODO:: Convert raw command blocks in this file to cfgcmd/opcmd + directives for command coverage tracking. + .. warning:: Due to a race condition that can lead to a failure during boot process, all interfaces are initialized before firewall is configured. This leads to a situation where the system is open to all traffic, and can be diff --git a/docs/configuration/interfaces/openvpn-examples.rst b/docs/configuration/interfaces/openvpn-examples.rst index 46409975..34cabddf 100644 --- a/docs/configuration/interfaces/openvpn-examples.rst +++ b/docs/configuration/interfaces/openvpn-examples.rst @@ -2,6 +2,9 @@ Site-to-site ============ +.. TODO:: Convert raw command blocks in this file to cfgcmd/opcmd + directives for command coverage tracking. + OpenVPN is popular for client-server setups, but its site-to-site mode is less common and often not supported by router appliances. Despite limited support, it is effective for quickly establishing tunnels between routers. @@ -29,9 +32,9 @@ In both cases, we will use the following settings: * The ``persistent-tunnel`` directive allows us to configure tunnel-related attributes, such as firewall policy, as we would on any standard network interface. -* If known, the remote router's IP address can be configured using the - ``remote-host`` directive. If unknown, it can be omitted. We assume the remote - router has a dynamic IP address. +* If known, the remote router's IP address can be configured using + the ``remote-host`` directive. If unknown, it can be omitted. + We assume the remote router has a dynamic IP address. .. figure:: /_static/images/openvpn_site2site_diagram.jpg @@ -87,11 +90,15 @@ You do **not** need to copy the certificate to the other router. Instead, retrieve its SHA-256 fingerprint. Since OpenVPN currently supports only SHA-256 fingerprints, use the following command: +.. stop_vyoslinter + .. code-block:: none vyos@vyos# run show pki certificate openvpn-local fingerprint sha256 5C:B8:09:64:8B:59:51:DC:F4:DF:2C:12:5C:B7:03:D1:68:94:D7:5B:62:C2:E1:83:79:F1:F0:68:B2:81:26:79 +.. start_vyoslinter + .. note:: Certificate names are arbitrary. While ``openvpn-local`` and ``openvpn-remote`` are used here, you may choose any names. @@ -456,7 +463,7 @@ Check the tunnel status: Client CN Remote Host Tunnel IP Local Host TX bytes RX bytes Connected Since ----------- ------------------ ----------- ---------------- ---------- ---------- ------------------- - client1 172.110.12.54:33166 10.23.1.10 172.18.201.10:1194 3.4 KB 3.4 KB 2024-06-11 12:07:25 + client1 172.16.12.54:33166 10.23.1.10 172.18.201.10:1194 3.4 KB 3.4 KB 2024-06-11 12:07:25 @@ -639,7 +646,11 @@ below: } } -For a detailed example, refer to :doc:`OpenVPN with LDAP`. +.. stop_vyoslinter + +For a detailed example, refer to :doc:`OpenVPN with LDAP `. + +.. start_vyoslinter Multi-factor authentication =========================== diff --git a/docs/configuration/interfaces/vti.rst b/docs/configuration/interfaces/vti.rst index 1704b9d1..9c2dc1eb 100644 --- a/docs/configuration/interfaces/vti.rst +++ b/docs/configuration/interfaces/vti.rst @@ -4,6 +4,9 @@ VTI - Virtual Tunnel Interface ############################## +.. TODO:: Convert raw command blocks in this file to cfgcmd/opcmd + directives for command coverage tracking. + Set Virtual Tunnel Interface .. code-block:: none diff --git a/docs/configuration/nat/nat64.rst b/docs/configuration/nat/nat64.rst index e8a3a0e6..8608da9f 100644 --- a/docs/configuration/nat/nat64.rst +++ b/docs/configuration/nat/nat64.rst @@ -4,6 +4,9 @@ NAT64 ##### +.. TODO:: Convert raw command blocks in this file to cfgcmd/opcmd + directives for command coverage tracking. + :abbr:`NAT64 (IPv6-to-IPv4 Prefix Translation)` is a critical component in modern networking, facilitating communication between IPv6 and IPv4 networks. This documentation outlines the setup, configuration, and usage of the NAT64 @@ -69,6 +72,8 @@ NAT64 client configuration: Test from the IPv6 only client: +.. stop_vyoslinter + .. code-block:: none vyos@r1:~$ ping 64:ff9b::192.0.2.1 count 2 @@ -79,3 +84,5 @@ Test from the IPv6 only client: --- 64:ff9b::192.0.2.1 ping statistics --- 2 packets transmitted, 2 received, 0% packet loss, time 1023ms rtt min/avg/max/mdev = 0.351/0.362/0.373/0.011 ms + +.. start_vyoslinter diff --git a/docs/configuration/nat/nat66.rst b/docs/configuration/nat/nat66.rst index 42f63fc9..d7d8e8be 100644 --- a/docs/configuration/nat/nat66.rst +++ b/docs/configuration/nat/nat66.rst @@ -4,6 +4,9 @@ NAT66(NPTv6) ############ +.. TODO:: Convert raw command blocks in this file to cfgcmd/opcmd + directives for command coverage tracking. + :abbr:`NPTv6 (IPv6-to-IPv6 Network Prefix Translation)` is an address translation technology based on IPv6 networks, used to convert an IPv6 address prefix in an IPv6 message into another IPv6 address prefix. @@ -151,8 +154,9 @@ R2: set service router-advert interface br1 prefix ::/0 -Use the following topology to translate internal user local addresses (``fc::/7``) -to DHCPv6-PD provided prefixes from an ISP connected to a VyOS HA pair. +Use the following topology to translate internal user local addresses +(``fc::/7``) to DHCPv6-PD provided prefixes from an ISP connected to +a VyOS HA pair. .. figure:: /_static/images/vyos_1_5_nat66_dhcpv6_wdummy.png :alt: VyOS NAT66 DHCPv6 using a dummy interface diff --git a/docs/configuration/policy/examples.rst b/docs/configuration/policy/examples.rst index d822d839..11c1d625 100644 --- a/docs/configuration/policy/examples.rst +++ b/docs/configuration/policy/examples.rst @@ -2,6 +2,9 @@ BGP Example ########### +.. TODO:: Convert raw command blocks in this file to cfgcmd/opcmd + directives for command coverage tracking. + **Policy definition:** .. code-block:: none diff --git a/docs/configuration/protocols/static.rst b/docs/configuration/protocols/static.rst index 3e3eb47b..e9016abc 100644 --- a/docs/configuration/protocols/static.rst +++ b/docs/configuration/protocols/static.rst @@ -70,10 +70,12 @@ IPv4 BFD Configure a static route for `` using gateway `
` and use the gateway address as BFD peer destination address. -.. cfgcmd:: set protocols static route next-hop
bfd profile +.. cfgcmd:: set protocols static route next-hop
+ bfd profile - Configure a static route for `` using gateway `
` and use the - gateway address as BFD peer destination address with BFD profile ``. + Configure a static route for `` using gateway `
` + and use the gateway address as BFD peer destination address with + BFD profile ``. .. cfgcmd:: set protocols static route next-hop
bfd multi-hop source-address @@ -153,10 +155,12 @@ IPv6 Unicast Routes .. note:: Routes with a distance of 255 are effectively disabled and not installed into the kernel. -.. cfgcmd:: set protocols static route6 next-hop
segments +.. cfgcmd:: set protocols static route6 next-hop
+ segments - It is possible to specify a static route for ipv6 prefixes using an SRv6 segments - instruction. The `/` separator can be used to specify multiple segment instructions. + It is possible to specify a static route for ipv6 prefixes using + an SRv6 segments instruction. The `/` separator can be used to + specify multiple segment instructions. Example: @@ -202,8 +206,9 @@ IPv6 Interface Routes .. cfgcmd:: set protocols static route6 interface segments - It is possible to specify a static route for ipv6 prefixes using an SRv6 segments - instruction. The `/` separator can be used to specify multiple segment instructions. + It is possible to specify a static route for ipv6 prefixes using + an SRv6 segments instruction. The `/` separator can be used to + specify multiple segment instructions. Example: @@ -219,13 +224,15 @@ IPv6 BFD Configure a static route for `` using gateway `
` and use the gateway address as BFD peer destination address. -.. cfgcmd:: set protocols static route6 next-hop
bfd profile +.. cfgcmd:: set protocols static route6 next-hop
+ bfd profile - Configure a static route for `` using gateway `
` and use the - gateway address as BFD peer destination address with BFD profile ``. + Configure a static route for `` using gateway `
` + and use the gateway address as BFD peer destination address with + BFD profile ``. -.. cfgcmd:: set protocols static route6 next-hop
bfd multi-hop - source-address +.. cfgcmd:: set protocols static route6 next-hop
+ bfd multi-hop source-address Configure a static route for `` using gateway `
` and use the gateway address as BFD peer destination address with source address @@ -271,7 +278,5 @@ IPv6 Blackhole Routes Alternate Routing Tables ************************ -TBD - Alternate routing tables are used with policy based routing by utilizing :ref:`vrf`. diff --git a/docs/configuration/service/snmp.rst b/docs/configuration/service/snmp.rst index b444ab85..9e91cc50 100644 --- a/docs/configuration/service/snmp.rst +++ b/docs/configuration/service/snmp.rst @@ -4,6 +4,9 @@ SNMP #### +.. TODO:: Convert raw command blocks in this file to cfgcmd/opcmd + directives for command coverage tracking. + :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. diff --git a/docs/configuration/system/flow-accounting.rst b/docs/configuration/system/flow-accounting.rst index a339df75..cb18839a 100644 --- a/docs/configuration/system/flow-accounting.rst +++ b/docs/configuration/system/flow-accounting.rst @@ -84,7 +84,9 @@ CLI command. You may disable using the local in-memory table with the command: .. cfgcmd:: set system flow-accounting syslog-facility - TBD + Configure the syslog facility used for flow-accounting log messages. + Available facilities follow standard syslog conventions (e.g., + ``daemon``, ``local0`` through ``local7``). Flow Export ----------- diff --git a/docs/configuration/system/sysctl.rst b/docs/configuration/system/sysctl.rst index 06e15031..d1398822 100644 --- a/docs/configuration/system/sysctl.rst +++ b/docs/configuration/system/sysctl.rst @@ -4,6 +4,12 @@ Sysctl ###### +.. note:: This page is a stub and needs expansion. + Contributions welcome via the + VyOS `documentation repository`_. + +.. _documentation repository: https://github.com/vyos/vyos-documentation + This chapeter describes how to configure kernel parameters at runtime. ``sysctl`` is used to modify kernel parameters at runtime. The parameters diff --git a/docs/configuration/vpn/ipsec/troubleshooting_ipsec.rst b/docs/configuration/vpn/ipsec/troubleshooting_ipsec.rst index fdeb347d..8494f0ea 100644 --- a/docs/configuration/vpn/ipsec/troubleshooting_ipsec.rst +++ b/docs/configuration/vpn/ipsec/troubleshooting_ipsec.rst @@ -4,6 +4,9 @@ Troubleshooting Site-to-Site VPN IPsec ###################################### +.. TODO:: Convert raw command blocks in this file to cfgcmd/opcmd + directives for command coverage tracking. + ************ Introduction ************ @@ -286,8 +289,8 @@ The reason of this problem is showed on the responder side. Jun 23 08:16:12 charon-systemd[2440]: no acceptable proposal found Jun 23 08:16:12 charon[2440]: 01[IKE] 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. +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 ============================= diff --git a/docs/configuration/vpn/openconnect.rst b/docs/configuration/vpn/openconnect.rst index 11824e50..d5c76e3e 100644 --- a/docs/configuration/vpn/openconnect.rst +++ b/docs/configuration/vpn/openconnect.rst @@ -4,6 +4,9 @@ OpenConnect ########### +.. TODO:: Convert raw command blocks in this file to cfgcmd/opcmd + directives for command coverage tracking. + OpenConnect-compatible server feature has been available since Equuleus (1.3). Openconnect VPN supports SSL connection and offers full network access. SSL VPN network extension connects the end-user system to the corporate network with @@ -81,9 +84,22 @@ For generating an OTP key in VyOS, you can use the CLI command User Certificate Authentication =============================== -You can configure users to be authenticated by certificate by setting the authentication mode to certificate, and defining what field (by OID) in the certificate will be used to identify the username. Two pre-defined shortcuts for Common Name (OID 2.5.4.3) and User ID (OID 0.9.2342.19200300.100.1.1) have been provide as cn or uid. Otherwise a specific OID value must be provided. +You can configure users to be authenticated by certificate by setting +the authentication mode to certificate, and defining what field (by OID) +in the certificate will be used to identify the username. Two pre-defined + +.. stop_vyoslinter + +shortcuts for Common Name (OID 2.5.4.3) and User ID +(OID 0.9.2342.19200300.100.1.1) have been provided as cn or uid. -The user's certificate must be signed by the certificate authority defined in the configuration for it to be validated for authentication. +.. start_vyoslinter + +Otherwise a specific OID value must be provided. + +The user's certificate must be signed by the certificate authority +defined in the configuration for it to be validated for +authentication. .. code-block:: none diff --git a/docs/configuration/vpn/rsa-keys.rst b/docs/configuration/vpn/rsa-keys.rst index 0508522f..ce9aa720 100644 --- a/docs/configuration/vpn/rsa-keys.rst +++ b/docs/configuration/vpn/rsa-keys.rst @@ -2,6 +2,10 @@ ######## RSA-Keys ######## + +.. TODO:: Convert raw command blocks in this file to cfgcmd/opcmd + directives for command coverage tracking. + RSA can be used for services such as key exchanges and for encryption purposes. To make IPSec work with dynamic address on one/both sides, we will have to use RSA keys for authentication. They are very fast and easy to setup. @@ -51,10 +55,14 @@ On the RIGHT: Now you are ready to setup IPsec. The key points: -1. Since both routers do not know their effective public addresses, we set the local-address of the peer to "any". -2. On the initiator, we set the peer address to its public address, but on the responder we only set the id. -3. On the initiator, we need to set the remote-id option so that it can identify IKE traffic from the responder correctly. -4. On the responder, we need to set the local id so that initiator can know who's talking to it for the point #3 to work. +1. Since both routers do not know their effective public addresses, + we set the local-address of the peer to "any". +2. On the initiator, we set the peer address to its public address, + but on the responder we only set the id. +3. On the initiator, we need to set the remote-id option so that it + can identify IKE traffic from the responder correctly. +4. On the responder, we need to set the local id so that initiator + can know who's talking to it for the point #3 to work. On the LEFT (static address): diff --git a/docs/installation/cloud/oracle.rst b/docs/installation/cloud/oracle.rst index 1d02335b..f5e03329 100644 --- a/docs/installation/cloud/oracle.rst +++ b/docs/installation/cloud/oracle.rst @@ -4,6 +4,12 @@ Oracle ###### +.. note:: This page is a stub and needs expansion. + Contributions welcome via the + VyOS `documentation repository`_. + +.. _documentation repository: https://github.com/vyos/vyos-documentation + .. stop_vyoslinter References ---------- diff --git a/docs/installation/virtual/eve-ng.rst b/docs/installation/virtual/eve-ng.rst index 855daeb0..0dd07db8 100644 --- a/docs/installation/virtual/eve-ng.rst +++ b/docs/installation/virtual/eve-ng.rst @@ -4,6 +4,12 @@ EVE-NG ###### +.. note:: This page is a stub and needs expansion. + Contributions welcome via the + VyOS `documentation repository`_. + +.. _documentation repository: https://github.com/vyos/vyos-documentation + References ========== -- cgit v1.2.3 From ac00e1c4a6b456628e412123383450653f668bdb Mon Sep 17 00:00:00 2001 From: Yuriy Andamasov Date: Fri, 10 Apr 2026 21:46:24 +0300 Subject: docs: remove TODO markers, fix stub notes, add linter markers (#1828) Remove TODO tracking comments, reformat stub notes with inline links, add stop/start_vyoslinter markers around long code blocks, and fix minor structural issues across 23 documentation files. Co-authored-by: Claude Opus 4.6 (1M context) --- docs/automation/vyos-govyos.rst | 20 +++- docs/automation/vyos-salt.rst | 24 +++- docs/configuration/highavailability/index.rst | 45 +++++++- docs/configuration/loadbalancing/wan.rst | 6 +- docs/configuration/nat/nat64.rst | 3 - docs/configuration/nat/nat66.rst | 4 + docs/configuration/policy/examples.rst | 3 - docs/configuration/policy/index.rst | 2 +- docs/configuration/protocols/static.rst | 59 ++++++---- docs/configuration/service/eventhandler.rst | 126 +++++++++++++-------- docs/configuration/service/snmp.rst | 3 - docs/configuration/system/flow-accounting.rst | 14 ++- docs/configuration/system/sysctl.rst | 10 +- docs/configuration/vpn/index.rst | 2 +- docs/configuration/vpn/ipsec/index.rst | 2 + .../configuration/vpn/ipsec/remoteaccess_ipsec.rst | 6 +- .../vpn/ipsec/troubleshooting_ipsec.rst | 8 +- docs/configuration/vpn/openconnect.rst | 44 ++++++- docs/configuration/vpn/rsa-keys.rst | 8 ++ docs/installation/cloud/oracle.rst | 8 +- docs/installation/virtual/eve-ng.rst | 8 +- docs/operation/information.rst | 17 ++- docs/vpp/configuration/ipfix.rst | 16 ++- 23 files changed, 311 insertions(+), 127 deletions(-) (limited to 'docs/configuration/vpn/ipsec') diff --git a/docs/automation/vyos-govyos.rst b/docs/automation/vyos-govyos.rst index 32222441..659c2b6e 100644 --- a/docs/automation/vyos-govyos.rst +++ b/docs/automation/vyos-govyos.rst @@ -2,17 +2,21 @@ .. _vyos-govyos: +####### go-vyos -======= +####### go-vyos is a Go library designed for interacting with VyOS devices through their REST API. This documentation is intended to guide you in using go-vyos for programmatic management of your VyOS devices. -- `go-vyos Documentation & Source Code on GitHub `_ +- `go-vyos Documentation & Source Code on GitHub + `_ allows you to access and contribute to the library's code. -- `go-vyos on pkg.go.dev `_ for detailed instructions - on the installation, configuration, and operation of the go-vyos library. +- `go-vyos on pkg.go.dev + `_ + for detailed instructions on the installation, configuration, and + operation of the go-vyos library. Installation @@ -30,11 +34,15 @@ Getting Started Importing and Disabling TLS Verification ------------------------------------------------- +.. stop_vyoslinter + .. code-block:: none import "github.com/ganawaj/go-vyos/vyos" client := vyos.NewClient(nil).WithToken("AUTH_KEY").WithURL("https://192.168.0.1").Insecure() +.. start_vyoslinter + Initializing a VyDevice Object ------------------------------ @@ -64,6 +72,8 @@ Using go-vyos Configure, then Set ^^^^^^^^^^^^^^^^^^^^^^^^ +.. stop_vyoslinter + .. code-block:: none out, resp, err := c.Conf.Set(ctx, "interfaces ethernet eth0 address 192.168.1.1/24") @@ -73,6 +83,8 @@ Configure, then Set fmt.Println(out.Success) +.. start_vyoslinter + Show a Single Object Value ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ diff --git a/docs/automation/vyos-salt.rst b/docs/automation/vyos-salt.rst index 12be32a1..3a5b17d7 100644 --- a/docs/automation/vyos-salt.rst +++ b/docs/automation/vyos-salt.rst @@ -4,8 +4,9 @@ .. include:: /_include/need_improvement.txt +#### Salt -==== +#### VyOS supports op-mode and configuration via salt_. @@ -172,6 +173,8 @@ Examples Example of op-mode: +.. stop_vyoslinter + .. code-block:: none / # salt r11-proxy netmiko.send_command 'show interfaces ethernet eth0 brief' host=192.0.2.14 device_type=vyos username=vyos password=vyos @@ -180,10 +183,14 @@ Example of op-mode: Interface IP Address S/L Description --------- ---------- --- ----------- eth0 192.0.2.14/24 u/u Upstream - / # + / # + +.. start_vyoslinter Example of configuration: +.. stop_vyoslinter + .. code-block:: none / # salt r11-proxy netmiko.send_config config_commands=['set interfaces ethernet eth0 description Link_to_WAN'] commit=True host=192.0.2.14 device_type=vyos username=vyos password=vyos @@ -196,7 +203,12 @@ Example of configuration: vyos@r14# / # -Example of configuration commands from the file "/srv/salt/states/commands.txt" +.. start_vyoslinter + +Example of configuration commands from the file +"/srv/salt/states/commands.txt" + +.. stop_vyoslinter .. code-block:: none @@ -212,5 +224,9 @@ Example of configuration commands from the file "/srv/salt/states/commands.txt" vyos@r1# / # +.. start_vyoslinter + .. _salt: https://docs.saltproject.io/en/latest/contents.html -.. _netmiko: https://docs.saltproject.io/en/latest/ref/modules/all/salt.modules.netmiko_mod.html#module-salt.modules.netmiko_mod \ No newline at end of file +.. stop_vyoslinter +.. _netmiko: https://docs.saltproject.io/en/latest/ref/modules/all/salt.modules.netmiko_mod.html#module-salt.modules.netmiko_mod +.. start_vyoslinter \ No newline at end of file diff --git a/docs/configuration/highavailability/index.rst b/docs/configuration/highavailability/index.rst index 40465c30..c82391c7 100644 --- a/docs/configuration/highavailability/index.rst +++ b/docs/configuration/highavailability/index.rst @@ -2,8 +2,9 @@ .. _high-availability: +################# High availability -================= +################# VRRP (Virtual Router Redundancy Protocol) provides active/backup redundancy for routers. Every VRRP router has a physical IP/IPv6 address, and a virtual @@ -252,8 +253,12 @@ need to configure it. But if necessary, Gratuitous ARP can be configured in 0 if not defined. +.. stop_vyoslinter + .. cfgcmd:: set high-availability vrrp global-parameters garp master-delay <1-255> +.. start_vyoslinter + .. cfgcmd:: set high-availability vrrp group garp master-delay <1-255> Set delay for second set of gratuitous ARPs after transition to MASTER. @@ -316,37 +321,46 @@ vice versa and can be used to enable or disable certain services, for example. chmod +x /config/scripts/script-name.sh -.. warning:: It is not recommended to change VRRP configuration inside health-check - and transition scripts. +.. warning:: It is not recommended to change VRRP configuration + inside health-check and transition scripts. Health check scripts ^^^^^^^^^^^^^^^^^^^^ -There is the ability to run an arbitrary script at regular intervals according to health-check -parameters. If a script returns 0, it indicates success. If a script returns anything -else, it will indicate that the VRRP instance should enter the FAULT state. +There is the ability to run an arbitrary script at regular intervals +according to health-check parameters. If a script returns 0, it +indicates success. If a script returns anything else, it will indicate +that the VRRP instance should enter the FAULT state. This setup will make the VRRP process execute the ``/config/scripts/vrrp-check.sh script`` every 60 seconds, and transition the group to the fault state if it fails (i.e. exits with non-zero status) three times: +.. stop_vyoslinter + .. code-block:: none set high-availability vrrp group Foo health-check script /config/scripts/vrrp-check.sh set high-availability vrrp group Foo health-check interval 60 set high-availability vrrp group Foo health-check failure-count 3 +.. start_vyoslinter + When the vrrp group is a member of the sync group will use only the sync group health check script. This example shows how to configure it for the sync group: +.. stop_vyoslinter + .. code-block:: none set high-availability vrrp sync-group Bar health-check script /config/scripts/vrrp-check.sh set high-availability vrrp sync-group Bar health-check interval 60 set high-availability vrrp sync-group Bar health-check failure-count 3 +.. start_vyoslinter + Transition scripts ^^^^^^^^^^^^^^^^^^ @@ -356,12 +370,16 @@ This setup will make the VRRP process execute the ``/config/scripts/vrrp-fail.sh`` with argument ``Foo`` when VRRP fails, and the ``/config/scripts/vrrp-master.sh`` when the router becomes the master: +.. stop_vyoslinter + .. code-block:: none set high-availability vrrp group Foo transition-script backup "/config/scripts/vrrp-fail.sh Foo" set high-availability vrrp group Foo transition-script fault "/config/scripts/vrrp-fail.sh Foo" set high-availability vrrp group Foo transition-script master "/config/scripts/vrrp-master.sh Foo" +.. start_vyoslinter + To know more about scripting, check the :ref:`command-scripting` section. Virtual-server @@ -401,10 +419,14 @@ Health-check ^^^^^^^^^^^^ Custom health-check script allows checking real-server availability +.. stop_vyoslinter + .. code-block:: none set high-availability virtual-server 203.0.113.1 real-server 192.0.2.11 health-check script +.. start_vyoslinter + Fwmark ^^^^^^ Firewall mark. It possible to loadbalancing traffic based on ``fwmark`` value @@ -417,10 +439,14 @@ Real server ^^^^^^^^^^^ Real server IP address and port +.. stop_vyoslinter + .. code-block:: none set high-availability virtual-server 203.0.113.1 real-server 192.0.2.11 port '80' +.. start_vyoslinter + Example ^^^^^^^ @@ -432,6 +458,8 @@ protocol TCP is balanced between 2 real servers ``192.0.2.11`` and Real server is auto-excluded if port check with this server fail. +.. stop_vyoslinter + .. code-block:: none set interfaces ethernet eth0 address '203.0.113.11/24' @@ -451,6 +479,7 @@ Real server is auto-excluded if port check with this server fail. set high-availability virtual-server 203.0.113.1 real-server 192.0.2.11 port '80' set high-availability virtual-server 203.0.113.1 real-server 192.0.2.12 port '80' +.. start_vyoslinter A firewall mark ``fwmark`` allows using multiple ports for high-availability virtual-server. @@ -460,6 +489,8 @@ In this example all traffic destined to ports "80, 2222, 8888" protocol TCP marks to fwmark "111" and balanced between 2 real servers. Port "0" is required if multiple ports are used. +.. stop_vyoslinter + .. code-block:: none set interfaces ethernet eth0 address 'dhcp' @@ -483,6 +514,8 @@ Port "0" is required if multiple ports are used. set nat source rule 100 source address '192.0.2.0/24' set nat source rule 100 translation address 'masquerade' +.. start_vyoslinter + Op-mode check virtual-server status .. code-block:: none diff --git a/docs/configuration/loadbalancing/wan.rst b/docs/configuration/loadbalancing/wan.rst index 3d5a3cc6..b9a513bc 100644 --- a/docs/configuration/loadbalancing/wan.rst +++ b/docs/configuration/loadbalancing/wan.rst @@ -1,7 +1,11 @@ :lastproofread: 2026-04-06 +################## WAN load balancing -================== +################## + +.. TODO:: Convert raw command blocks in this file to cfgcmd/opcmd + directives for command coverage tracking. The load balancer distributes outbound traffic across two or more interfaces. If a path fails, the load balancer balances traffic across the diff --git a/docs/configuration/nat/nat64.rst b/docs/configuration/nat/nat64.rst index 8608da9f..04ba56f4 100644 --- a/docs/configuration/nat/nat64.rst +++ b/docs/configuration/nat/nat64.rst @@ -4,9 +4,6 @@ NAT64 ##### -.. TODO:: Convert raw command blocks in this file to cfgcmd/opcmd - directives for command coverage tracking. - :abbr:`NAT64 (IPv6-to-IPv4 Prefix Translation)` is a critical component in modern networking, facilitating communication between IPv6 and IPv4 networks. This documentation outlines the setup, configuration, and usage of the NAT64 diff --git a/docs/configuration/nat/nat66.rst b/docs/configuration/nat/nat66.rst index d7d8e8be..be5cf2b3 100644 --- a/docs/configuration/nat/nat66.rst +++ b/docs/configuration/nat/nat66.rst @@ -163,6 +163,8 @@ a VyOS HA pair. Configure both routers (a and b) for DHCPv6-PD via dummy interface: +.. stop_vyoslinter + .. code-block:: none set interfaces dummy dum1 description 'DHCPv6-PD NPT dummy' @@ -173,6 +175,8 @@ Configure both routers (a and b) for DHCPv6-PD via dummy interface: set interfaces bonding bond0 vif 20 dhcpv6-options rapid-commit commit +.. start_vyoslinter + Get the DHCPv6-PD prefixes from both routers: .. code-block:: none diff --git a/docs/configuration/policy/examples.rst b/docs/configuration/policy/examples.rst index 11c1d625..d822d839 100644 --- a/docs/configuration/policy/examples.rst +++ b/docs/configuration/policy/examples.rst @@ -2,9 +2,6 @@ BGP Example ########### -.. TODO:: Convert raw command blocks in this file to cfgcmd/opcmd - directives for command coverage tracking. - **Policy definition:** .. code-block:: none diff --git a/docs/configuration/policy/index.rst b/docs/configuration/policy/index.rst index 51f60479..0394eb21 100644 --- a/docs/configuration/policy/index.rst +++ b/docs/configuration/policy/index.rst @@ -1,4 +1,4 @@ -:lastproofread:2021-07-12 +:lastproofread: 2021-07-12 .. include:: /_include/need_improvement.txt diff --git a/docs/configuration/protocols/static.rst b/docs/configuration/protocols/static.rst index e9016abc..eb5a439c 100644 --- a/docs/configuration/protocols/static.rst +++ b/docs/configuration/protocols/static.rst @@ -70,12 +70,14 @@ IPv4 BFD Configure a static route for `` using gateway `
` and use the gateway address as BFD peer destination address. -.. cfgcmd:: set protocols static route next-hop
- bfd profile +.. stop_vyoslinter + +.. cfgcmd:: set protocols static route next-hop
bfd profile - Configure a static route for `` using gateway `
` - and use the gateway address as BFD peer destination address with - BFD profile ``. +.. start_vyoslinter + + Configure a static route for `` using gateway `
` and use the + gateway address as BFD peer destination address with BFD profile ``. .. cfgcmd:: set protocols static route next-hop
bfd multi-hop source-address @@ -155,15 +157,20 @@ IPv6 Unicast Routes .. note:: Routes with a distance of 255 are effectively disabled and not installed into the kernel. -.. cfgcmd:: set protocols static route6 next-hop
- segments +.. stop_vyoslinter - It is possible to specify a static route for ipv6 prefixes using - an SRv6 segments instruction. The `/` separator can be used to - specify multiple segment instructions. +.. cfgcmd:: set protocols static route6 next-hop
segments + +.. start_vyoslinter + + It is possible to specify a static route for ipv6 prefixes using an + SRv6 segments instruction. The ``/`` separator can be used to specify + multiple segment instructions. Example: +.. stop_vyoslinter + .. code-block:: none set protocols static route6 2001:db8:1000::/36 next-hop 2001:db8:201::ffff segments '2001:db8:aaaa::7/2002::4/2002::3/2002::2' @@ -180,6 +187,8 @@ IPv6 Unicast Routes C>* 2001:db8:201::/64 is directly connected, eth0.201, 00:00:46 S>* 2001:db8:1000::/36 [1/0] via 2001:db8:201::ffff, eth0.201, seg6 2001:db8:aaaa::7,2002::4,2002::3,2002::2, weight 1, 00:00:08 +.. start_vyoslinter + IPv6 Interface Routes ===================== @@ -206,16 +215,20 @@ IPv6 Interface Routes .. cfgcmd:: set protocols static route6 interface segments - It is possible to specify a static route for ipv6 prefixes using - an SRv6 segments instruction. The `/` separator can be used to - specify multiple segment instructions. + It is possible to specify a static route for ipv6 prefixes using an + SRv6 segments instruction. The ``/`` separator can be used to specify + multiple segment instructions. Example: +.. stop_vyoslinter + .. code-block:: none set protocols static route6 2001:db8:1000::/36 interface eth0 segments '2001:db8:aaaa::7/2002::4/2002::3/2002::2' +.. start_vyoslinter + IPv6 BFD ======== @@ -224,15 +237,21 @@ IPv6 BFD Configure a static route for `` using gateway `
` and use the gateway address as BFD peer destination address. -.. cfgcmd:: set protocols static route6 next-hop
- bfd profile +.. stop_vyoslinter - Configure a static route for `` using gateway `
` - and use the gateway address as BFD peer destination address with - BFD profile ``. +.. cfgcmd:: set protocols static route6 next-hop
bfd profile -.. cfgcmd:: set protocols static route6 next-hop
- bfd multi-hop source-address +.. start_vyoslinter + + Configure a static route for `` using gateway `
` and use the + gateway address as BFD peer destination address with BFD profile ``. + +.. stop_vyoslinter + +.. cfgcmd:: set protocols static route6 next-hop
bfd multi-hop + source-address + +.. start_vyoslinter Configure a static route for `` using gateway `
` and use the gateway address as BFD peer destination address with source address diff --git a/docs/configuration/service/eventhandler.rst b/docs/configuration/service/eventhandler.rst index 15f08239..9f4ebb04 100644 --- a/docs/configuration/service/eventhandler.rst +++ b/docs/configuration/service/eventhandler.rst @@ -8,8 +8,9 @@ Event Handler Event Handler Technology Overview ********************************* -Event handler allows you to execute scripts when a string that matches a regex or a regex with -a service name appears in journald logs. You can pass variables, arguments, and a full matching string to the script. +Event handler allows you to execute scripts when a string that matches +a regex or a regex with a service name appears in journald logs. You +can pass variables, arguments, and a full matching string to the script. ****************************** @@ -33,49 +34,76 @@ Event Handler Configuration Steps .. cfgcmd:: set service event-handler event - This is an optional command because the event handler will be automatically created after any of the next commands. + This is an optional command because the event handler will be + automatically created after any of the next commands. 2. Add regex to the script =========================================== - .. cfgcmd:: set service event-handler event filter pattern +.. stop_vyoslinter - This is a mandatory command. Sets regular expression to match against log string message. - - .. note:: The regular expression matches if and only if the entire string matches the pattern. + .. cfgcmd:: set service event-handler event filter pattern + +.. start_vyoslinter + + This is a mandatory command. Sets regular expression to match + against log string message. + + .. note:: The regular expression matches if and only if the entire + string matches the pattern. 3. Add a full path to the script ================================ +.. stop_vyoslinter + .. cfgcmd:: set service event-handler event script path - - This is a mandatory command. Sets the full path to the script. The script file must be executable. + +.. start_vyoslinter + + This is a mandatory command. Sets the full path to the script. + The script file must be executable. 4. Add optional parameters ========================== - .. cfgcmd:: set service event-handler event filter syslog-identifier +.. stop_vyoslinter + + .. cfgcmd:: set service event-handler event filter syslog-identifier + +.. start_vyoslinter This is an optional command. Filters log messages by syslog-identifier. +.. stop_vyoslinter + .. cfgcmd:: set service event-handler event script environment value - This is an optional command. Adds environment and its value to the script. Use separate commands for each environment. +.. start_vyoslinter + + This is an optional command. Adds environment and its value to the + script. Use separate commands for each environment. One implicit environment exists. * ``message``: Full message that has triggered the script. +.. stop_vyoslinter + .. cfgcmd:: set service event-handler event script arguments - This is an optional command. Adds arguments to the script. Arguments must be separated by spaces. +.. start_vyoslinter + + This is an optional command. Adds arguments to the script. + Arguments must be separated by spaces. - .. note:: We don't recomend to use arguments. Using environments is more preffereble. + .. note:: We don't recommend to use arguments. Using environments + is more preferable. ******* @@ -84,44 +112,48 @@ Example Event handler that monitors the state of interface eth0. +.. stop_vyoslinter + .. code-block:: none - set service event-handler event INTERFACE_STATE_DOWN filter pattern '.*eth0.*,RUNNING,.*->.*' - set service event-handler event INTERFACE_STATE_DOWN filter syslog-identifier 'netplugd' - set service event-handler event INTERFACE_STATE_DOWN script environment interface_action value 'down' - set service event-handler event INTERFACE_STATE_DOWN script environment interface_name value 'eth2' - set service event-handler event INTERFACE_STATE_DOWN script path '/config/scripts/eventhandler.py' + set service event-handler event INTERFACE_STATE_DOWN filter pattern '.*eth0.*,RUNNING,.*->.*' + set service event-handler event INTERFACE_STATE_DOWN filter syslog-identifier 'netplugd' + set service event-handler event INTERFACE_STATE_DOWN script environment interface_action value 'down' + set service event-handler event INTERFACE_STATE_DOWN script environment interface_name value 'eth0' + set service event-handler event INTERFACE_STATE_DOWN script path '/config/scripts/eventhandler.py' Event handler script .. code-block:: none - #!/usr/bin/env python3 - # - # VyOS event-handler script example - from os import environ - import subprocess - from sys import exit - - # Perform actions according to requirements - def process_event() -> None: - # Get variables - message_text = environ.get('message') - interface_name = environ.get('interface_name') - interface_action = environ.get('interface_action') - # Print the message that triggered this script - print(f'Logged message: {message_text}') - # Prepare a command to run - command = f'sudo ip link set {interface_name} {interface_action}'.split() - # Execute a command - subprocess.run(command) - - if __name__ == '__main__': - try: - # Run script actions and exit - process_event() - exit(0) - except Exception as err: - # Exit properly in case if something in the script goes wrong - print(f'Error running script: {err}') - exit(1) + #!/usr/bin/env python3 + # + # VyOS event-handler script example + from os import environ + import subprocess + from sys import exit + + # Perform actions according to requirements + def process_event() -> None: + # Get variables + message_text = environ.get('message') + interface_name = environ.get('interface_name') + interface_action = environ.get('interface_action') + # Print the message that triggered this script + print(f'Logged message: {message_text}') + # Prepare a command to run + command = f'sudo ip link set {interface_name} {interface_action}'.split() + # Execute a command + subprocess.run(command) + + if __name__ == '__main__': + try: + # Run script actions and exit + process_event() + exit(0) + except Exception as err: + # Exit properly in case if something in the script goes wrong + print(f'Error running script: {err}') + exit(1) + +.. start_vyoslinter diff --git a/docs/configuration/service/snmp.rst b/docs/configuration/service/snmp.rst index 9e91cc50..b444ab85 100644 --- a/docs/configuration/service/snmp.rst +++ b/docs/configuration/service/snmp.rst @@ -4,9 +4,6 @@ SNMP #### -.. TODO:: Convert raw command blocks in this file to cfgcmd/opcmd - directives for command coverage tracking. - :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. diff --git a/docs/configuration/system/flow-accounting.rst b/docs/configuration/system/flow-accounting.rst index cb18839a..0664eac7 100644 --- a/docs/configuration/system/flow-accounting.rst +++ b/docs/configuration/system/flow-accounting.rst @@ -84,9 +84,9 @@ CLI command. You may disable using the local in-memory table with the command: .. cfgcmd:: set system flow-accounting syslog-facility - Configure the syslog facility used for flow-accounting log messages. - Available facilities follow standard syslog conventions (e.g., - ``daemon``, ``local0`` through ``local7``). + Set the syslog facility for flow-accounting log messages. Supported values + include ``daemon``, ``local0`` through ``local7``, and other standard syslog + facilities. Flow Export ----------- @@ -167,6 +167,8 @@ display captured network traffic information for all configured interfaces. Show flow accounting information for given ``. + .. stop_vyoslinter + .. code-block:: none vyos@vyos:~$ show flow-accounting interface eth0 @@ -180,11 +182,15 @@ display captured network traffic information for all configured interfaces. eth0 00:53:01:b2:22:48 00:53:02:58:a2:92 192.0.2.100 192.0.2.14 40006 22 tcp 16 146 1 9444 eth0 00:53:01:b2:22:48 00:53:02:58:a2:92 192.0.2.100 192.0.2.14 0 0 icmp 192 27 1 4455 + .. start_vyoslinter + .. opcmd:: show flow-accounting interface host
Show flow accounting information for given `` for a specific host only. + .. stop_vyoslinter + .. code-block:: none vyos@vyos:~$ show flow-accounting interface eth0 host 192.0.2.14 @@ -193,3 +199,5 @@ display captured network traffic information for all configured interfaces. eth0 00:53:01:b2:22:48 00:53:02:58:a2:92 192.0.2.100 192.0.2.14 40006 22 tcp 16 197 2 12940 eth0 00:53:01:b2:22:48 00:53:02:58:a2:92 192.0.2.100 192.0.2.14 40152 22 tcp 16 94 1 4924 eth0 00:53:01:b2:22:48 00:53:02:58:a2:92 192.0.2.100 192.0.2.14 0 0 icmp 192 36 1 5877 + + .. start_vyoslinter diff --git a/docs/configuration/system/sysctl.rst b/docs/configuration/system/sysctl.rst index d1398822..1fedb9bd 100644 --- a/docs/configuration/system/sysctl.rst +++ b/docs/configuration/system/sysctl.rst @@ -4,13 +4,11 @@ Sysctl ###### -.. note:: This page is a stub and needs expansion. - Contributions welcome via the - VyOS `documentation repository`_. +.. note:: This page is a stub and needs expansion. Contributions + welcome via the `VyOS documentation repository + `_. -.. _documentation repository: https://github.com/vyos/vyos-documentation - -This chapeter describes how to configure kernel parameters at runtime. +This chapter describes how to configure kernel parameters at runtime. ``sysctl`` is used to modify kernel parameters at runtime. The parameters available are those listed under /proc/sys/. diff --git a/docs/configuration/vpn/index.rst b/docs/configuration/vpn/index.rst index 228f83ca..6d38e5b5 100644 --- a/docs/configuration/vpn/index.rst +++ b/docs/configuration/vpn/index.rst @@ -7,10 +7,10 @@ VPN :maxdepth: 1 :includehidden: - dmvpn ipsec/index l2tp openconnect pptp rsa-keys sstp + dmvpn diff --git a/docs/configuration/vpn/ipsec/index.rst b/docs/configuration/vpn/ipsec/index.rst index 7647d8d2..973c76de 100644 --- a/docs/configuration/vpn/ipsec/index.rst +++ b/docs/configuration/vpn/ipsec/index.rst @@ -11,3 +11,5 @@ IPsec site2site_ipsec remoteaccess_ipsec troubleshooting_ipsec + + diff --git a/docs/configuration/vpn/ipsec/remoteaccess_ipsec.rst b/docs/configuration/vpn/ipsec/remoteaccess_ipsec.rst index 1a41d987..50499160 100644 --- a/docs/configuration/vpn/ipsec/remoteaccess_ipsec.rst +++ b/docs/configuration/vpn/ipsec/remoteaccess_ipsec.rst @@ -1,7 +1,11 @@ .. _remoteaccess_ipsec: +############################ IPSec IKEv2 Remote Access VPN -============================= +############################ + +.. TODO:: Convert raw command blocks in this file to cfgcmd/opcmd + directives for command coverage tracking. Internet Key Exchange version 2 (IKEv2) is a tunneling protocol, based on IPsec, that establishes a secure VPN communication between VPN devices, and defines diff --git a/docs/configuration/vpn/ipsec/troubleshooting_ipsec.rst b/docs/configuration/vpn/ipsec/troubleshooting_ipsec.rst index 8494f0ea..f0f2e208 100644 --- a/docs/configuration/vpn/ipsec/troubleshooting_ipsec.rst +++ b/docs/configuration/vpn/ipsec/troubleshooting_ipsec.rst @@ -29,6 +29,8 @@ Checking IKE SA Status The next command shows IKE SAs' statuses. +.. stop_vyoslinter + .. code-block:: none vyos@vyos:~$ show vpn ike sa @@ -289,8 +291,8 @@ The reason of this problem is showed on the responder side. Jun 23 08:16:12 charon-systemd[2440]: no acceptable proposal found Jun 23 08:16:12 charon[2440]: 01[IKE] 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. +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 ============================= @@ -320,6 +322,8 @@ The reason of this problem is showed on the responder side. Jun 23 14:13:19 charon[2440]: 01[ENC] generating IKE_AUTH response 1 [ IDr AUTH N(MOBIKE_SUP) N(NO_ADD_ADDR) N(TS_UNACCEPT) ] Jun 23 14:13:19 charon-systemd[2440]: generating IKE_AUTH response 1 [ IDr AUTH N(MOBIKE_SUP) N(NO_ADD_ADDR) N(TS_UNACCEPT) ] +.. start_vyoslinter + Traffic selectors **10.0.2.0/24 === 10.0.0.0/24** are unacceptable on the responder side. diff --git a/docs/configuration/vpn/openconnect.rst b/docs/configuration/vpn/openconnect.rst index d5c76e3e..0262b3f2 100644 --- a/docs/configuration/vpn/openconnect.rst +++ b/docs/configuration/vpn/openconnect.rst @@ -40,10 +40,14 @@ client that fetches a certificate from Let's Encrypt an open certificate authority launched by the EFF, Mozilla, and others and deploys it to a web server. +.. stop_vyoslinter + .. code-block:: none sudo certbot certonly --standalone --preferred-challenges http -d +.. start_vyoslinter + Server Configuration ==================== @@ -66,6 +70,8 @@ authentication + OTP key can be used. Alternatively, OTP authentication only, without a password, can be used. To do this, an OTP configuration must be added to the configuration above: +.. stop_vyoslinter + .. code-block:: none set vpn openconnect authentication mode local @@ -74,6 +80,8 @@ To do this, an OTP configuration must be added to the configuration above: set vpn openconnect authentication local-users username otp-length set vpn openconnect authentication local-users username token-type +.. start_vyoslinter + For generating an OTP key in VyOS, you can use the CLI command (operational mode): @@ -98,8 +106,7 @@ shortcuts for Common Name (OID 2.5.4.3) and User ID Otherwise a specific OID value must be provided. The user's certificate must be signed by the certificate authority -defined in the configuration for it to be validated for -authentication. +defined in the configuration for it to be validated for authentication. .. code-block:: none @@ -111,14 +118,17 @@ authentication. Verification ************ -.. code-block:: none +.. stop_vyoslinter +.. code-block:: none vyos@vyos:~$ sh openconnect-server sessions interface username ip remote IP RX TX state uptime ----------- ---------- ------------- ----------- ------- --------- --------- -------- sslvpn0 tst 172.20.20.198 192.168.6.1 0 bytes 152 bytes connected 3s +.. start_vyoslinter + .. note:: It is compatible with Cisco (R) AnyConnect (R) clients. ******* @@ -130,6 +140,8 @@ SSL Certificates generation Follow the instructions to generate CA cert (in configuration mode): +.. stop_vyoslinter + .. code-block:: none vyos@vyos# run generate pki ca install ca-ocserv @@ -167,6 +179,8 @@ Follow the instructions to generate server cert (in configuration mode): 2 value(s) installed. Use "compare" to see the pending changes, and "commit" to apply. [edit] +.. start_vyoslinter + Each of the install command should be applied to the configuration and commited before using under the openconnect configuration: @@ -184,6 +198,8 @@ Openconnect Configuration Simple setup with one user added and password authentication: +.. stop_vyoslinter + .. code-block:: none set vpn openconnect authentication local-users username tst password 'OC_bad_Secret' @@ -194,6 +210,8 @@ Simple setup with one user added and password authentication: set vpn openconnect ssl ca-certificate 'ca-ocserv' set vpn openconnect ssl certificate 'srv-ocserv' +.. start_vyoslinter + To enable the HTTP security headers in the configuration file, use the command: .. code-block:: none @@ -207,6 +225,8 @@ Adding a 2FA with an OTP-key First the OTP keys must be generated and sent to the user and to the configuration: +.. stop_vyoslinter + .. code-block:: none vyos@vyos:~$ generate openconnect username tst otp-key hotp-time @@ -238,13 +258,19 @@ configuration: # To add this OTP key to configuration, run the following commands: set vpn openconnect authentication local-users username tst otp key 'ebc1c91b13848ce0bb67d9212934546e41803cfa' +.. start_vyoslinter + Next it is necessary to configure 2FA for OpenConnect: +.. stop_vyoslinter + .. code-block:: none set vpn openconnect authentication mode local password-otp set vpn openconnect authentication local-users username tst otp key 'ebc1c91b13848ce0bb67d9212934546e41803cfa' +.. start_vyoslinter + Now when connecting the user will first be asked for the password and then the OTP key. @@ -270,6 +296,8 @@ outlines the set of configuration options that are allowed. This can be leveraged to apply different sets of configs to different users or groups of users. +.. stop_vyoslinter + .. code-block:: none sudo mkdir -p /config/auth/ocserv/config-per-user @@ -279,6 +307,8 @@ users. set vpn openconnect authentication identity-based-config directory /config/auth/ocserv/config-per-user set vpn openconnect authentication identity-based-config default-config /config/auth/ocserv/default-user.conf +.. start_vyoslinter + .. warning:: The above directory and default-config must be a child directory of /config/auth, since files outside this directory are not persisted after an image upgrade. @@ -313,6 +343,8 @@ connect/disconnect, data transferred, and so on. Configure an accounting server and enable accounting with: +.. stop_vyoslinter + .. code-block:: none set vpn openconnect accounting mode radius @@ -320,12 +352,16 @@ Configure an accounting server and enable accounting with: set vpn openconnect accounting radius server 172.20.20.10 port 1813 set vpn openconnect accounting radius server 172.20.20.10 key your_radius_secret +.. start_vyoslinter + .. warning:: The RADIUS accounting feature must be used with the OpenConnect authentication mode RADIUS. It cannot be used with local authentication. You must configure the OpenConnect authentication mode to "radius". An example of the data captured by a FREERADIUS server with sql accounting: +.. stop_vyoslinter + .. code-block:: none mysql> SELECT username, nasipaddress, acctstarttime, acctstoptime, acctinputoctets, acctoutputoctets, callingstationid, framedipaddress, connectinfo_start FROM radacct; @@ -334,3 +370,5 @@ An example of the data captured by a FREERADIUS server with sql accounting: +----------+---------------+---------------------+---------------------+-----------------+------------------+-------------------+-----------------+-----------------------------------+ | test | 198.51.100.15 | 2023-01-13 00:59:15 | 2023-01-13 00:59:21 | 10606 | 152 | 192.168.6.1 | 172.20.20.198 | Open AnyConnect VPN Agent v8.05-1 | +----------+---------------+---------------------+---------------------+-----------------+------------------+-------------------+-----------------+-----------------------------------+ + +.. start_vyoslinter diff --git a/docs/configuration/vpn/rsa-keys.rst b/docs/configuration/vpn/rsa-keys.rst index ce9aa720..e7584563 100644 --- a/docs/configuration/vpn/rsa-keys.rst +++ b/docs/configuration/vpn/rsa-keys.rst @@ -13,6 +13,8 @@ RSA keys for authentication. They are very fast and easy to setup. First, on both routers run the operational command "generate pki key-pair install >". You may choose different length than 2048 of course. +.. stop_vyoslinter + .. code-block:: none vyos@left# run generate pki key-pair install ipsec-LEFT @@ -27,6 +29,8 @@ install >". You may choose different length than 2048 of course. set pki key-pair ipsec-LEFT private key 'MIIEvgIBADAN...' [edit] +.. start_vyoslinter + Configuration commands will display. Note the command with the public key (set pki key-pair ipsec-LEFT public key 'MIIBIjANBgkqh...'). @@ -66,6 +70,8 @@ Now you are ready to setup IPsec. The key points: On the LEFT (static address): +.. stop_vyoslinter + .. code-block:: none set vpn ipsec interface eth0 @@ -113,3 +119,5 @@ On the RIGHT (dynamic address): set vpn ipsec site-to-site peer 192.0.2.10 local-address any set vpn ipsec site-to-site peer 192.0.2.10 tunnel 1 local prefix 192.168.99.2/32 # Additional loopback address on the local set vpn ipsec site-to-site peer 192.0.2.10 tunnel 1 remote prefix 192.168.99.1/32 # Additional loopback address on the remote + +.. start_vyoslinter diff --git a/docs/installation/cloud/oracle.rst b/docs/installation/cloud/oracle.rst index f5e03329..d71d8039 100644 --- a/docs/installation/cloud/oracle.rst +++ b/docs/installation/cloud/oracle.rst @@ -4,11 +4,9 @@ Oracle ###### -.. note:: This page is a stub and needs expansion. - Contributions welcome via the - VyOS `documentation repository`_. - -.. _documentation repository: https://github.com/vyos/vyos-documentation +.. note:: This page is a stub and needs expansion. Contributions + welcome via the `VyOS documentation repository + `_. .. stop_vyoslinter References diff --git a/docs/installation/virtual/eve-ng.rst b/docs/installation/virtual/eve-ng.rst index 0dd07db8..f3db28fe 100644 --- a/docs/installation/virtual/eve-ng.rst +++ b/docs/installation/virtual/eve-ng.rst @@ -4,11 +4,9 @@ EVE-NG ###### -.. note:: This page is a stub and needs expansion. - Contributions welcome via the - VyOS `documentation repository`_. - -.. _documentation repository: https://github.com/vyos/vyos-documentation +.. note:: This page is a stub and needs expansion. Contributions + welcome via the `VyOS documentation repository + `_. References ========== diff --git a/docs/operation/information.rst b/docs/operation/information.rst index fbff53a3..1b3d876a 100644 --- a/docs/operation/information.rst +++ b/docs/operation/information.rst @@ -2,9 +2,9 @@ .. _information: -****************** +################## System Information -****************** +################## VyOS features a rich set of operational level commands to retrieve arbitrary information about your running system. For more information on the VyOS command @@ -42,6 +42,8 @@ recent Linux distributions. .. note:: If a device is unplugged and plugged in again, it is assigned a new ``Port``, ``Dev``, and ``If``. +.. stop_vyoslinter + .. code-block:: none vyos@vyos:~$ show hardware usb @@ -70,6 +72,8 @@ recent Linux distributions. |__ Port 4: Dev 7, If 2, Class=Vendor Specific Class, Driver=ftdi_sio, 480M |__ Port 4: Dev 7, If 0, Class=Vendor Specific Class, Driver=ftdi_sio, 480M +.. start_vyoslinter + .. opcmd:: show hardware usb serial @@ -77,6 +81,8 @@ recent Linux distributions. device name displayed, (for example ``usb0b2.4p1.0``), can be used directly when accessing the serial console as console-server device. +.. stop_vyoslinter + .. code-block:: none vyos@vyos$ show hardware usb serial @@ -99,6 +105,8 @@ recent Linux distributions. usb0b2.4p1.2 Quad_RS232-HS Future Technology Devices International, Ltd usb0b2.4p1.3 Quad_RS232-HS Future Technology Devices International, Ltd +.. start_vyoslinter + .. _information_version: ######## @@ -107,8 +115,9 @@ Version .. opcmd:: show version - Return the currently running VyOS version and build information. This includes - the name of the release train, e.g., ``sagitta`` on VyOS 1.4, and ``circinus`` on VyOS 1.5. + Return the currently running VyOS version and build information. This + includes the name of the release train, e.g., ``sagitta`` on VyOS 1.4, + and ``circinus`` on VyOS 1.5. .. code-block:: none diff --git a/docs/vpp/configuration/ipfix.rst b/docs/vpp/configuration/ipfix.rst index 2085740a..92c734be 100644 --- a/docs/vpp/configuration/ipfix.rst +++ b/docs/vpp/configuration/ipfix.rst @@ -1,5 +1,6 @@ +####################### VPP IPFIX Configuration -======================= +####################### VPP IPFIX in VyOS allows monitoring and exporting network traffic flows for analytics, security, and accounting. IPFIX works with the VPP @@ -18,7 +19,8 @@ Key IPFIX Concepts - **Active timeout**: Maximum time a flow is kept active before export. - **Inactive timeout**: Maximum time an idle flow is kept before export. - **Collector**: The remote host and port to which flow records are sent. -- **Flow layers**: Determines which layer information is included (`l2`, `l3`, `l4`). +- **Flow layers**: Determines which layer information is included + (``l2``, ``l3``, ``l4``). - **Interfaces**: Physical or virtual interfaces to monitor. - **Direction**: Which traffic to monitor (`rx`, `tx`, `both`). - **Flow variant**: Optional filter for IPv4 or IPv6 flows. @@ -26,12 +28,16 @@ Key IPFIX Concepts Configuration Options --------------------- -- **active-timeout**: Duration (in seconds) after which active flows are exported. -- **inactive-timeout**: Duration (in seconds) after which idle flows are exported. +- **active-timeout**: Duration (in seconds) after which active flows + are exported. +- **inactive-timeout**: Duration (in seconds) after which idle flows + are exported. - **collector `` port ``**: IP and UDP port of the IPFIX collector. - **collector `` source-address ``**: Source address for flow export. - **flowprobe-record ``**: Layers to include in flow records. -- **interface `` [direction ``] [flow-variant ``]**: Interfaces to monitor, direction of traffic, and optional flow variant filter. +- **interface** ```` **[direction** ````\ **]** + **[flow-variant** ````\ **]**: Interfaces to monitor, + direction of traffic, and optional flow variant filter. Example Configuration --------------------- -- cgit v1.2.3