From 885b9462480712210ddeea9ca4a4b7a52e9ef587 Mon Sep 17 00:00:00 2001 From: omnom62 <75066712+omnom62@users.noreply.github.com> Date: Fri, 21 Aug 2026 23:54:29 +1000 Subject: T8989: static_routes module * T8989 static_routes * T8989 static_routes * T8989 added changelog fragment for static routes module * t8989 static route changelog * t8989 static_routes module * T8989: static_routes SIT overridden and rtt * T8989: SIT updated * T8989: vyos_static_routes dict_op refactor --- docs/vyos.rest.vyos_static_routes_module.rst | 429 +++++++++++++++++++++++++++ 1 file changed, 429 insertions(+) create mode 100644 docs/vyos.rest.vyos_static_routes_module.rst (limited to 'docs') diff --git a/docs/vyos.rest.vyos_static_routes_module.rst b/docs/vyos.rest.vyos_static_routes_module.rst new file mode 100644 index 0000000..353cf2d --- /dev/null +++ b/docs/vyos.rest.vyos_static_routes_module.rst @@ -0,0 +1,429 @@ +.. _vyos.rest.vyos_static_routes_module: + + +**************************** +vyos.rest.vyos_static_routes +**************************** + +**Manage static routes on VyOS devices via REST API.** + + +Version added: 1.0.0 + +.. contents:: + :local: + :depth: 1 + + +Synopsis +-------- +- Manages IPv4 and IPv6 static routes on VyOS devices using the HTTPS REST API. +- Covers blackhole routes (distance) and next-hop routes (distance, disable, outgoing interface). VyOS's static-route schema is considerably larger than this -- reject routes (an ICMP-unreachable counterpart to blackhole), a top-level per-route interface (a route resolved via an outgoing interface with no next-hop address at all), route tags, route descriptions, ECMP segment weighting, VRF leaking, and BFD monitoring on next-hops are not modeled here. That is a real, documented limitation, not an oversight. + + + + +Parameters +---------- + +.. raw:: html + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
ParameterChoices/DefaultsComments
+
+ config + +
+ list + / elements=dictionary +
+ 		+ +
List of static route configurations grouped by address family.
+
+
+ afi + +
+ string + / required +
+ 		+
    Choices: +
  • ipv4
    • +
  • ipv6
    • +
+ 		+
Address family indicator.
+
+
+ routes + +
+ list + / elements=dictionary +
+ 		+ +
List of static route entries.
+
+
+ blackhole_config + +
+ dictionary +
+ 		+ +
Blackhole route configuration (silently discard matching packets).
+
+
+ distance + +
+ integer +
+ 		+ +
Administrative distance (1-255).
+
+
+ dest + +
+ string + / required +
+ 		+ +
Destination prefix in CIDR notation.
+
+
+ next_hops + +
+ list + / elements=dictionary +
+ 		+ +
List of next-hop addresses.
+
+
+ admin_distance + +
+ integer +
+ 		+ +
Administrative distance for this next-hop (1-255).
+
+
+ enabled + +
+ boolean +
+ 		+
    Choices: +
  • no
    • +
  • yes ←
    • +
+ 		+
Whether this next-hop is enabled.
+
+
+ forward_router_address + +
+ string + / required +
+ 		+ +
Next-hop IP address.
+
+
+ interface + +
+ string +
+ 		+ +
Outgoing interface name.
+
+
+ state + +
+ string +
+ 		+
    Choices: +
  • merged ←
    • +
  • replaced
    • +
  • overridden
    • +
  • deleted
    • +
  • gathered
    • +
+ 		+
merged - Add routes without removing existing ones.
+
replaced - Replace each named route (by afi + dest) exactly as specified.
+
overridden - Replace the entire static route table.
+
deleted - Remove listed or all static routes.
+
gathered - Read static routes from device without changes.
+
+
+ + + +See Also +-------- + +.. seealso:: + + :ref:`vyos.vyos.vyos_static_routes_module` + The official documentation on the **vyos.vyos.vyos_static_routes** module. + + +Examples +-------- + +.. code-block:: yaml + + - name: Merge IPv4 and IPv6 static routes + vyos.rest.vyos_static_routes: + config: + - afi: ipv4 + routes: + - dest: 192.0.2.0/24 + next_hops: + - forward_router_address: 10.0.0.1 + - dest: 203.0.113.0/24 + blackhole_config: + distance: 200 + - afi: ipv6 + routes: + - dest: 2001:db8::/32 + next_hops: + - forward_router_address: 2001:db8::1 + state: merged + + - name: Delete all static routes + vyos.rest.vyos_static_routes: + state: deleted + + - name: Gather current static routes + vyos.rest.vyos_static_routes: + state: gathered + + + +Return Values +------------- +Common return values are documented `here `_, the following are the fields unique to this module: + +.. raw:: html + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
KeyReturnedDescription
+
+ after + +
+ list +
+ 		when changed +
Static route configuration after this module ran.
+
+
+
+ before + +
+ list +
+ 		always +
Static route configuration before this module ran.
+
+
+
+ commands + +
+ list +
+ 		always +
List of API command tuples sent to the device.
+
+
+
+ gathered + +
+ list +
+ 		when state is gathered +
Current static route configuration as structured data.
+
+
+
+ response + +
+ dictionary +
+ 		when changes are applied +
Raw API response.
+
+
+
+ saved + +
+ boolean +
+ 		when changes are applied +
Whether the config was saved after changes.
+
+
+

+ + +Status +------ + + +Authors +~~~~~~~ + +- VyOS Community (@vyos) -- cgit v1.2.3