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') 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