From eb46e9a02199ef35b2cb9e9273c2e2ff793b36be Mon Sep 17 00:00:00 2001 From: Quill <69414602+teslazonda@users.noreply.github.com> Date: Thu, 9 Apr 2026 20:07:46 +0900 Subject: DOC: Proofread files in the /configuration/loadbalancing directory (#1821) * Initial proofread * Fix line length lint errors --- docs/configuration/loadbalancing/haproxy.rst | 167 ++++++++++++----------- docs/configuration/loadbalancing/index.rst | 2 + docs/configuration/loadbalancing/wan.rst | 194 +++++++++++++-------------- 3 files changed, 184 insertions(+), 179 deletions(-) (limited to 'docs/configuration/loadbalancing') diff --git a/docs/configuration/loadbalancing/haproxy.rst b/docs/configuration/loadbalancing/haproxy.rst index 667ebb95..d742ec18 100644 --- a/docs/configuration/loadbalancing/haproxy.rst +++ b/docs/configuration/loadbalancing/haproxy.rst @@ -1,21 +1,22 @@ +:lastproofread: 2026-04-06 ############# -Haproxy +HAproxy ############# .. include:: /_include/need_improvement.txt -Haproxy is a balancer and proxy server that provides -high-availability, load balancing and proxying for TCP (level 4) -and HTTP-based (level 7) applications. +HAProxy is a load balancer and proxy server that provides +high-availability, load balancing, and proxying for TCP (level 4) and +HTTP-based (level 7) applications. Configuration ============= -Service configuration is responsible for binding to a specific port, -while the backend configuration determines the type of load balancing -to be applied and specifies the real servers to be utilized. +Service configuration specifies the port to bind to. Backend +configuration defines the load balancing method and specifies the backend +servers. Service ------- @@ -23,7 +24,8 @@ Service .. cfgcmd:: set load-balancing haproxy service listen-address
- Set service to bind on IP address, by default listen on any IPv4 and IPv6 + Set the IP address for the service to bind to. By default, the service + listens on all IPv4 and IPv6 addresses. .. cfgcmd:: set load-balancing haproxy service port @@ -43,19 +45,21 @@ Service .. cfgcmd:: set load-balancing haproxy service ssl certificate - Set SSL certificate for service . Multiple certificates could be defined. + Set the SSL certificate for service . You can define + multiple certificates. .. cfgcmd:: set load-balancing haproxy service http-response-headers value - Set custom HTTP headers to be included in all responses + Set custom HTTP headers to include in all responses. .. cfgcmd:: set load-balancing haproxy service logging facility level Specify facility and level for logging. - For an explanation on :ref:`syslog_facilities` and :ref:`syslog_severity_level` - see tables in syslog configuration section. + For an explanation on :ref:`syslog_facilities` and + :ref:`syslog_severity_level`, + see tables in the syslog configuration section. .. cfgcmd:: set load-balancing haproxy service timeout client @@ -76,9 +80,9 @@ Service Rules ^^^^^ -Rules allow to control and route incoming traffic to specific backend based -on predefined conditions. Rules allow to define matching criteria and -perform action accordingly. +Rules control and route incoming traffic to specific backends based on +predefined conditions. Rules define matching criteria and specify actions +to perform. .. cfgcmd:: set load-balancing haproxy service rule domain-name @@ -98,15 +102,13 @@ perform action accordingly. .. cfgcmd:: set load-balancing haproxy service rule url-path - Allows to define URL path matching rules for a specific service. - - With this command, you can specify how the URL path should be matched - against incoming requests. + Define URL path matching rules for a specific service. Use this command + to specify how to match the URL path against incoming requests. The available options for are: * ``begin`` Matches the beginning of the URL path * ``end`` Matches the end of the URL path. - * ``exact`` Requires an exactly match of the URL path + * ``exact`` Matches the URL path exactly. .. cfgcmd:: set load-balancing haproxy service rule set backend @@ -116,7 +118,7 @@ perform action accordingly. .. cfgcmd:: set load-balancing haproxy service rule redirect-location - Redirect URL to a new location + Redirect URL to a new location. Backend @@ -125,37 +127,36 @@ Backend .. cfgcmd:: set load-balancing haproxy backend balance - Load-balancing algorithms to be used for distributed requests among the - available servers + Specify the load balancing algorithm for distributing requests among + available servers. Balance algorithms: * ``source-address`` Distributes requests based on the source IP address - of the client + of the client. * ``round-robin`` Distributes requests in a circular manner, - sequentially sending each request to the next server in line + sequentially sending each request to the next server in line. * ``least-connection`` Distributes requests to the server with the fewest - active connections + active connections. .. cfgcmd:: set load-balancing haproxy backend mode - Configure backend `` mode TCP or HTTP + Configure backend `` mode TCP or HTTP. .. cfgcmd:: set load-balancing haproxy backend server address - Set the address of the backend server to which the incoming traffic will - be forwarded + Set the address of the backend server that receives incoming traffic. .. cfgcmd:: set load-balancing haproxy backend server port - Set the address of the backend port + Set the address of the backend port. .. cfgcmd:: set load-balancing haproxy backend server check - Active health check backend server + Active health check backend server. .. cfgcmd:: set load-balancing haproxy backend server check port @@ -166,35 +167,36 @@ Backend .. cfgcmd:: set load-balancing haproxy backend server send-proxy - Send a Proxy Protocol version 1 header (text format) + Send a Proxy Protocol version 1 header (text format). .. cfgcmd:: set load-balancing haproxy backend server send-proxy-v2 - Send a Proxy Protocol version 2 header (binary format) + Send a Proxy Protocol version 2 header (binary format). .. cfgcmd:: set load-balancing haproxy backend ssl ca-certificate - Configure requests to the backend server to use SSL encryption and - authenticate backend against + Use SSL encryption for backend requests and authenticate the backend + against ````. .. cfgcmd:: set load-balancing haproxy backend ssl no-verify - Configure requests to the backend server to use SSL encryption without - validating server certificate + Use SSL encryption for backend requests without validating the server + certificate. .. cfgcmd:: set load-balancing haproxy backend http-response-headers value - Set custom HTTP headers to be included in all responses using the backend + Set custom HTTP headers to include in all responses from the backend. .. cfgcmd:: set load-balancing haproxy backend logging facility level Specify facility and level for logging. - For an explanation on :ref:`syslog_facilities` and :ref:`syslog_severity_level` - see tables in syslog configuration section. + For an explanation on :ref:`syslog_facilities` and + :ref:`syslog_severity_level`, + see tables in the :ref:`syslog` configuration section. .. cfgcmd:: set load-balancing haproxy backend timeout check @@ -220,7 +222,7 @@ Backend Global ------- -Global parameters +Global configuration parameters: .. cfgcmd:: set load-balancing haproxy global-parameters max-connections @@ -230,7 +232,7 @@ Global parameters .. cfgcmd:: set load-balancing haproxy global-parameters ssl-bind-ciphers - Limit allowed cipher algorithms used during SSL/TLS handshake + Limit the cipher algorithms allowed during SSL/TLS handshake. .. cfgcmd:: set load-balancing haproxy global-parameters tls-version-min @@ -241,7 +243,8 @@ Global parameters facility level Specify facility and level for logging. - For an explanation on :ref:`syslog_facilities` and :ref:`syslog_severity_level` + For an explanation on :ref:`syslog_facilities` and + :ref:`syslog_severity_level` see tables in syslog configuration section. .. cfgcmd:: set load-balancing haproxy timeout check @@ -271,8 +274,8 @@ Health checks HTTP checks ----------- -For web application providing information about their state HTTP health -checks can be used to determine their availability. +Use HTTP health checks to monitor web applications that provide health status +information and determine their availability. .. cfgcmd:: set load-balancing haproxy backend http-check @@ -282,17 +285,17 @@ checks can be used to determine their availability. .. cfgcmd:: set load-balancing haproxy backend http-check method - Sets the HTTP method to be used, can be either: option, get, post, put + Set the HTTP method: ``OPTION``, ``GET``, ``POST``, or ``PUT``. .. cfgcmd:: set load-balancing haproxy backend http-check uri - Sets the endpoint to be used for health checks + Set the endpoint to use for health checks. .. cfgcmd:: set load-balancing haproxy backend http-check expect - Sets the expected result condition for considering a server healthy. + Set the expected result condition for a server to be considered healthy. Some possible examples are: * ``status 200`` Expecting a 200 response code @@ -303,8 +306,8 @@ checks can be used to determine their availability. TCP checks ---------- -Health checks can also be configured for TCP mode backends. You can configure -protocol aware checks for a range of Layer 7 protocols: +Configure health checks for TCP mode backends. You can configure protocol-aware +checks for a range of Layer 7 protocols: .. cfgcmd:: set load-balancing haproxy backend health-check @@ -315,25 +318,23 @@ protocol aware checks for a range of Layer 7 protocols: * ``pgsql`` PostgreSQL protocol check. * ``smtp`` SMTP protocol check. -.. note:: If you specify a server to be checked but do not configure a - protocol, a basic TCP health check will be attempted. A server shall be - deemed online if it responses to a connection attempt with a valid - ``SYN/ACK`` packet. +.. note:: If you specify a server to check but do not configure a + protocol, HAProxy performs a basic TCP health check. A server is online if + it responds to a connection attempt with a valid ``SYN/ACK`` packet. Redirect HTTP to HTTPS ====================== -Configure the load-balancing haproxy service for HTTP. -This configuration listen on port 80 and redirect incoming -requests to HTTPS: +Configure a HAProxy service for HTTP that listens on port 80 and redirects +incoming requests to HTTPS: .. code-block:: none set load-balancing haproxy service http port '80' set load-balancing haproxy service http redirect-http-to-https -The name of the service can be different, in this example it is only for +You can use a different service name; in this example, ``http`` is just for convenience. @@ -343,9 +344,10 @@ Examples Level 4 balancing ----------------- -This configuration enables the TCP reverse proxy for the "my-tcp-api" service. -Incoming TCP connections on port 8888 will be load balanced across the backend -servers (srv01 and srv02) using the round-robin load-balancing algorithm. +This configuration enables the TCP reverse proxy for the ``my-tcp-api`` +service. Incoming TCP connections on port 8888 are load balanced across the +backend servers (srv01 and srv02) using the round-robin load balancing +algorithm. .. code-block:: none @@ -365,15 +367,15 @@ servers (srv01 and srv02) using the round-robin load-balancing algorithm. Balancing based on domain name ------------------------------ The following configuration demonstrates how to use VyOS -to achieve load balancing based on the domain name. +to achieve load balancing based on the domain name: -The HTTP service listen on TCP port 80. +The HTTP service listens on TCP port 80. -Rule 10 matches requests with the domain name ``node1.example.com`` forwards -to the backend ``bk-api-01`` +Rule 10 matches requests with the domain name ``node1.example.com`` and +forwards them to the backend ``bk-api-01``. -Rule 20 matches requests with the domain name ``node2.example.com`` forwards -to the backend ``bk-api-02`` +Rule 20 matches requests with the domain name ``node2.example.com`` and +forwards them to the backend ``bk-api-02``. .. code-block:: none @@ -398,23 +400,25 @@ to the backend ``bk-api-02`` Terminate SSL ------------- + The following configuration terminates SSL on the router. -The ``http`` service is listens on port 80 and force redirects from HTTP to +The ``http`` service listens on port 80 and redirects HTTP requests to HTTPS. -The ``https`` service listens on port 443 with backend ``bk-default`` to -handle HTTPS traffic. It uses certificate named ``cert`` for SSL termination. -HSTS header is set with a 1-year expiry, to tell browsers to always use SSL for site. +The ``https`` service listens on port 443 with the ``bk-default`` backend +and handles HTTPS traffic using the ``cert`` certificate for SSL termination. +The HSTS header is set with a 1-year expiry to tell browsers to always use +SSL for the site. -Rule 10 matches requests with the exact URL path ``/.well-known/xxx`` -and redirects to location ``/certs/``. +Rule 10 matches requests with the exact URL path ``/.well-known/xxx`` and +redirects them to ``/certs/``. -Rule 20 matches requests with URL paths ending in ``/mail`` or exact -path ``/email/bar`` redirect to location ``/postfix/``. +Rule 20 matches requests with URL paths ending in ``/mail`` or the exact +path ``/email/bar`` and redirects them to ``/postfix/``. -Additional global parameters are set, including the maximum number -connection limit of 4000 and a minimum TLS version of 1.3. +Global parameters include a maximum connection limit of 4000 and a minimum +TLS version of 1.3. .. code-block:: none @@ -447,9 +451,10 @@ connection limit of 4000 and a minimum TLS version of 1.3. SSL Bridging ------------- + The following configuration terminates incoming HTTPS traffic on the router, -then re-encrypts the traffic and sends to the backend server via HTTPS. -This is useful if encryption is required for both legs, but you do not want to +then re-encrypts the traffic and sends it to the backend server via HTTPS. +Use this when encryption is required for both paths but you do not want to install publicly trusted certificates on each backend server. Backend service certificates are checked against the certificate authority @@ -458,7 +463,7 @@ specified in the configuration, which could be an internal CA. The ``https`` service listens on port 443 with backend ``bk-bridge-ssl`` to handle HTTPS traffic. It uses certificate named ``cert`` for SSL termination. -The ``bk-bridge-ssl`` backend connects to sr01 server on port 443 via HTTPS +The ``bk-bridge-ssl`` backend connects to ``sr01`` server on port 443 via HTTPS and checks backend server has a valid certificate trusted by CA ``cacert`` @@ -480,7 +485,7 @@ and checks backend server has a valid certificate trusted by CA ``cacert`` Balancing with HTTP health checks --------------------------------- -This configuration enables HTTP health checks on backend servers. +This configuration enables HTTP health checks for backend servers. .. code-block:: none diff --git a/docs/configuration/loadbalancing/index.rst b/docs/configuration/loadbalancing/index.rst index 92dcc622..b87faed2 100644 --- a/docs/configuration/loadbalancing/index.rst +++ b/docs/configuration/loadbalancing/index.rst @@ -1,3 +1,5 @@ +:lastproofread: 2026-04-06 + .. _load-balancing: ############## diff --git a/docs/configuration/loadbalancing/wan.rst b/docs/configuration/loadbalancing/wan.rst index 745cd8c2..3d5a3cc6 100644 --- a/docs/configuration/loadbalancing/wan.rst +++ b/docs/configuration/loadbalancing/wan.rst @@ -1,22 +1,21 @@ -:lastproofread: 2023-01-27 +:lastproofread: 2026-04-06 WAN load balancing ================== -Outbound traffic can be balanced between two or more outbound interfaces. -If a path fails, traffic is balanced across the remaining healthy paths, -a recovered path is automatically added back to the routing table and used by -the load balancer. The load balancer automatically adds routes for each path to -the routing table and balances traffic across the configured interfaces, -determined by interface health and weight. +The load balancer distributes outbound traffic across two or more +interfaces. If a path fails, the load balancer balances traffic across the +remaining healthy paths. When a path recovers, it is automatically added back +to the routing table. The load balancer adds routes for each path and +distributes traffic based on interface health and weight. In a minimal configuration, the following must be provided: - * an interface with a nexthop - * one rule with a LAN (inbound-interface) and the WAN (interface). + * An interface with a ``nexthop``. + * One rule with a LAN (inbound-interface) and the WAN (interface). -Let's assume we have two DHCP WAN interfaces and one LAN (eth2): +The following examples uses two DHCP WAN interfaces and one LAN (``eth2``): .. code-block:: none @@ -28,18 +27,18 @@ Let's assume we have two DHCP WAN interfaces and one LAN (eth2): .. note:: - WAN Load Balacing should not be used when dynamic routing protocol is - used/needed. This feature creates customized routing tables and firewall - rules, that makes it incompatible to use with routing protocols. + Do not use WAN load balancing with dynamic routing protocols. This + feature creates customized routing tables and firewall rules that are + incompatible with routing protocols. -Balancing Rules ---------------- +Load balancing rules +-------------------- -Interfaces, their weight and the type of traffic to be balanced are defined in -numbered balancing rule sets. The rule sets are executed in numerical order -against outgoing packets. In case of a match the packet is sent through an -interface specified in the matching rule. If a packet doesn't match any rule -it is sent by using the system routing table. Rule numbers can't be changed. +You define interfaces, their weight, and the traffic type to balance in +numbered rule sets. The load balancer executes rules in numerical order +against outgoing packets. When a packet matches a rule, it is sent through the +specified interface. Packets that do not match any rule use the system routing +table. You cannot change rule numbers. Create a load balancing rule, it can be a number between 1 and 9999: @@ -61,23 +60,25 @@ Create a load balancing rule, it can be a number between 1 and 9999: Interface weight **************** -Let's expand the example from above and add weight to the interfaces. -The bandwidth from eth0 is larger than eth1. Per default, outbound traffic is -distributed randomly across available interfaces. Weights can be assigned to -interfaces to influence the balancing. +By default, the load balancer distributes outbound +traffic randomly across available interfaces. You can assign weights to +interfaces to influence the distribution. If ``eth0`` has more bandwidth +than ``eth1``, you can assign a higher weight to ``eth0`` to send more +traffic through it: .. code-block:: none set load-balancing wan rule 1 interface eth0 weight 2 set load-balancing wan rule 1 interface eth1 weight 1 -66% of traffic is routed to eth0, eth1 gets 33% of traffic. +In this example,``eth0`` receives 66% of traffic, and ``eth1`` receives +33% of traffic. Rate limit ********** -A packet rate limit can be set for a rule to apply the rule to traffic above or -below a specified threshold. To configure the rate limiting use: +Set a packet rate limit for a rule to apply it to traffic above or below a +specified threshold. To configure rate limiting, use: .. code-block:: none @@ -88,22 +89,20 @@ below a specified threshold. To configure the rate limiting use: * ``period``: Time window for rate calculation. Possible values: ``second`` (one second), ``minute`` (one minute), ``hour`` (one hour). Default is ``second``. -* ``rate``: Number of packets. Default 5. +* ``rate``: Number of packets. Default: ``5``. * ``threshold``: ``below`` or ``above`` the specified rate limit. Flow and packet-based balancing ******************************* -Outgoing traffic is balanced in a flow-based manner. -A connection tracking table is used to track flows by their source address, -destination address and port. Each flow is assigned to an interface according -to the defined balancing rules and subsequent packets are sent through the -same interface. This has the advantage that packets always arrive in order if -links with different speeds are in use. +The load balancer balances outgoing traffic by flow. A connection tracking +table tracks flows by source address, destination address, and port. Each +flow is assigned to an interface based on the balancing rules, and subsequent +packets use the same interface. This ensures packets arrive in order when links +have different speeds. -Packet-based balancing can lead to a better balance across interfaces when out -of order packets are no issue. Per-packet-based balancing can be set for a -balancing rule with: +Packet-based balancing can improve balance across interfaces when packet +order is not critical. Enable per-packet balancing for a rule with: .. code-block:: none @@ -112,8 +111,8 @@ balancing rule with: Exclude traffic *************** -To exclude traffic from load balancing, traffic matching an exclude rule is not -balanced but routed through the system routing table instead: +To exclude traffic from load balancing, traffic matching an exclude rule +bypasses load balancing and uses the system routing table instead: .. code-block:: none @@ -123,10 +122,10 @@ balanced but routed through the system routing table instead: Health checks ------------- -The health of interfaces and paths assigned to the load balancer is -periodically checked by sending ICMP packets (ping) to remote destinations, -a TTL test or the execution of a user defined script. If an interface fails the -health check it is removed from the load balancer's pool of interfaces. +The load balancer periodically checks the health of interfaces and paths by +sending ICMP packets (ping) to remote destinations, performing TTL tests, or +executing a user-defined script. If an interface fails the health check, the +load balancer removes it from its interface pool. To enable health checking for an interface: .. code-block:: none @@ -138,26 +137,26 @@ To enable health checking for an interface: success-count Success count +> test Rule number -Specify nexthop on the path to the destination, ``ipv4-address`` can be set to -``dhcp`` +Specify the nexthop on the path to the destination. You can set +``ipv4-address`` to ``dhcp``. .. code-block:: none set load-balancing wan interface-health nexthop -Set the number of health check failures before an interface is marked as -unavailable, range for number is 1 to 10, default 1. Or set the number of -successful health checks before an interface is added back to the interface -pool, range for number is 1 to 10, default 1. +Set the number of health check failures before the load balancer marks an +interface as unavailable (range 1-10, default 1). Or set the number of +successful health checks before adding an interface back to the pool +(range 1-10, default 1). .. code-block:: none set load-balancing wan interface-health failure-count set load-balancing wan interface-health success-count -Each health check is configured in its own test, tests are numbered and -processed in numeric order. For multi target health checking multiple tests -can be defined: +Configure each health check in its own test. Tests are numbered and processed +in numeric order. You can define multiple tests for multi-target health +checking: .. code-block:: none @@ -169,46 +168,45 @@ can be defined: ttl-limit Ttl limit (hop count) type WLB test type -* ``resp-time``: the maximum response time for ping in seconds. - Range 1...30, default 5 -* ``target``: the target to be sent ICMP packets to, address can be an IPv4 - address or hostname -* ``test-script``: A user defined script must return 0 to be considered - successful and non-zero to fail. Scripts are located in /config/scripts, - for different locations the full path needs to be provided -* ``ttl-limit``: For the UDP TTL limit test the hop count limit must be - specified. The limit must be shorter than the path length, an ICMP time - expired message is needed to be returned for a successful test. default 1 -* ``type``: Specify the type of test. type can be ping, ttl or a user defined - script +* ``resp-time``: The maximum response time for ping in seconds. Range + 1-30, default ``5``. +* ``target``: The target to receive ICMP packets. The address can be an IPv4 + address or hostname. +* ``test-script``: A user-defined script must return 0 to succeed and + non-zero to fail. Scripts reside in ``/config/scripts``. For other locations, + provide the full path. +* ``ttl-limit``: For the UDP TTL limit test, specify the hop count limit. + The limit must be shorter than the path length. The test succeeds when an + ICMP time-expired message is returned. Default ``1``. +* ``type``: Specify the test type: ``ping``, ``ttl``, or a user-defined + script. Source NAT rules ---------------- -Per default, interfaces used in a load balancing pool replace the source IP -of each outgoing packet with its own address to ensure that replies arrive on -the same interface. This works through automatically generated source NAT (SNAT) -rules, these rules are only applied to balanced traffic. In cases where this -behaviour is not desired, the automatic generation of SNAT rules can be -disabled: +By default, interfaces in a load balancing pool replace the source IP of +each outgoing packet with their own address to ensure replies arrive on the +same interface. The load balancer handles this through automatically generated +Source NAT (SNAT) rules applied only to balanced traffic. To disable the +automatic generation of SNAT rules when this behavior is not desired, use: .. code-block:: none set load-balancing wan disable-source-nat -Sticky Connections +Sticky connections ------------------ -Inbound connections to a WAN interface can be improperly handled when the reply -is sent back to the client. +Inbound connections to a WAN interface can be improperly handled when +replies are sent back to the client. .. image:: /_static/images/sticky-connections.jpg :width: 80% :align: center -Upon reception of an incoming packet, when a response is sent, it might be -desired to ensure that it leaves from the same interface as the inbound one. -This can be achieved by enabling sticky connections in the load balancing: +When responding to an incoming packet, you may want to ensure the response +leaves from the same interface as the incoming packet. Enable sticky +connections in the load balancer to do this: .. code-block:: none @@ -217,23 +215,21 @@ This can be achieved by enabling sticky connections in the load balancing: Failover -------- -In failover mode, one interface is set to be the primary interface and other -interfaces are secondary or spare. Instead of balancing traffic across all -healthy interfaces, only the primary interface is used and in case of failure, -a secondary interface selected from the pool of available interfaces takes over. -The primary interface is selected based on its weight and health, others become -secondary interfaces. Secondary interfaces to take over a failed primary -interface are chosen from the load balancer's interface pool, depending -on their weight and health. Interface roles can also be selected based on rule -order by including interfaces in balancing rules and ordering those rules -accordingly. To put the load balancer in failover mode, create a failover rule: +In failover mode, one interface is primary and other interfaces are +secondary or spare. The load balancer uses only the primary interface. If it +fails, a secondary interface from the available pool takes over. The load +balancer selects the primary interface based on its weight and health. Other +interfaces become secondary. Secondary interfaces are chosen based on their +weight and health. You can also select interface roles based on rule order by +including interfaces in balancing rules and ordering those rules accordingly. +To enable failover mode, create a failover rule: .. code-block:: none set load-balancing wan rule failover -Because existing sessions do not automatically fail over to a new path, -the session table can be flushed on each connection state change: +Existing sessions do not automatically fail over to a new path. Flush the +session table on each connection state change to enable failover: .. code-block:: none @@ -241,14 +237,15 @@ the session table can be flushed on each connection state change: .. warning:: - Flushing the session table will cause other connections to fall back from + Flushing the session table causes other connections to revert from flow-based to packet-based balancing until each flow is reestablished. Script execution ---------------- -A script can be run when an interface state change occurs. Scripts are run -from /config/scripts, for a different location specify the full path: +Run a script when an interface state changes. Scripts run from the +``/config/scripts`` directory. To use a script in another location, +specify the full path: .. code-block:: none @@ -261,19 +258,20 @@ Two environment variables are available: .. warning:: - Blocking call with no timeout. System will become unresponsive if script - does not return! + Blocking call with no timeout: VyOS becomes unresponsive if the + script does not return. Handling and monitoring ----------------------- -Show WAN load balancer information including test types and targets. -A character at the start of each line depicts the state of the test +The following command shows WAN load balancer information including test +types and targets. The character at the start of each line indicates the test +state: -* ``+`` successful -* ``-`` failed -* a blank indicates that no test has been carried out +* ``+`` successful. +* ``-`` failed. +* A blank indicates that no test has been carried out. .. code-block:: none -- 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/loadbalancing') 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