From 45dc95873fd906c582fbbd5e6ca3838caf867399 Mon Sep 17 00:00:00 2001 From: omnom62 Date: Mon, 6 Jul 2026 14:54:12 +1000 Subject: T8989: wave4 vyos_command, dict_op refactor * T8989: vyos_command module * T8989: vyos_command module UAT and SIT * T8989: vyos_command changelog * T8989: vyos_command linter * T8989: vyos_config module * T8989: vyos_config module changelog * T8989: Wave 4 vyos_config module with integration and unit tests * T8323: vyos_system module * T8332: vyos_system SIT and UAT * T8323: vyos_vlan module * T8323: vyos_vlan module * T8323: vyos_vlan module SIT and UAT * T8323: vyos_system module * T8989: Wave 4 vyos_vlan reworked with dict_op engine * T8989: Fix dict_op single-value string list handling, add vyos_system integration tests * T8989: logging_global refactor * T8989: migrate ntp_global, logging_global, firewall_global to dict_op engine * T8989: vyos_nat module for REST API collection * T8989: vyos_nat module for REST API collection, linter fixes * T8989: vyos_ha module for REST API collection * T8989: vyos_ha module for REST API collection * T8989: vyos_ha module sanity and linter fixes * T8989: vyos_ha module sanity and linter fixes * T8989: vyos_ha module linter fixes * T8989: vyos.rest AI comment fixes * T8323: vyos_nat AI comment fixes * T8989 ai fixes * T8989: vyos_bgp_address_family dict_op * T8989: vyos_bgp_address_family vyos_bgp_global dict_op * T8989: dict_op refactor for firewall_*, nat, user * T8989: dict_op refactor for firewall_*, nat, user * T8989: dict_op refactor for ntp_global, ha * T8989: snmp_server dict_op refactor * T8989: snmp_server dict_op refactor * T8989: route_map dict_op refactor --- docs/vyos.rest.vyos_command_module.rst | 252 +++++++++++++++++++++++++++++++++ 1 file changed, 252 insertions(+) create mode 100644 docs/vyos.rest.vyos_command_module.rst (limited to 'docs/vyos.rest.vyos_command_module.rst') diff --git a/docs/vyos.rest.vyos_command_module.rst b/docs/vyos.rest.vyos_command_module.rst new file mode 100644 index 0000000..7075ec6 --- /dev/null +++ b/docs/vyos.rest.vyos_command_module.rst @@ -0,0 +1,252 @@ +.. _vyos.rest.vyos_command_module: + + +********************** +vyos.rest.vyos_command +********************** + +**Run show commands on VyOS devices using REST API** + + +Version added: 1.0.0 + +.. contents:: + :local: + :depth: 1 + + +Synopsis +-------- +- Sends show commands to VyOS devices via the REST API ``/show`` endpoint and returns the output. +- Equivalent to ``vyos_command`` in the CLI collection but uses the REST API. +- Uses REST API (``connection=httpapi``) instead of CLI. + + + + +Parameters +---------- + +.. raw:: html + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
ParameterChoices/DefaultsComments
+
+ commands + +
+ list + / elements=raw + / required +
+ 		+ +
List of show commands to run on the device.
+
Each command is a list of path elements passed to the /show endpoint.
+
Commands may be specified as a string (space-separated) or a list.
+
+
+ interval + +
+ integer +
+ 		+ Default:
1
+ 		+
Configures the interval in seconds to wait between retries of the command.
+
+
+ match + +
+ string +
+ 		+
    Choices: +
  • any
    • +
  • all ←
    • +
+ 		+
The match argument is used in conjunction with the wait_for argument to specify the match policy.
+
+
+ retries + +
+ integer +
+ 		+ Default:
10
+ 		+
Specifies the number of retries a command should be run before it is considered failed.
+
+
+ wait_for + +
+ list + / elements=string +
+ 		+ +
Specifies what to evaluate from the output of the command and what conditionals to apply. This argument will cause the task to wait for a particular conditional to be true before moving forward.
+

aliases: waitfor
+
+
+ + +Notes +----- + +.. note:: + - Requires ``ansible_connection=httpapi`` with the VyOS httpapi plugin. + - ``ansible_network_os`` must be set to ``vyos.rest.vyos``. + - Only ``show`` commands are supported via the REST API. + - Commands are passed as path lists to the ``/show`` endpoint. + + + +Examples +-------- + +.. code-block:: yaml + + - name: Run show version + vyos.rest.vyos_command: + commands: + - - version + register: result + + - name: Run multiple show commands + vyos.rest.vyos_command: + commands: + - - interfaces + - - ip + - route + - - system + - uptime + register: result + + - name: Run show commands as strings + vyos.rest.vyos_command: + commands: + - "interfaces" + - "ip route" + - "version" + register: result + + - name: Wait for BGP to establish + vyos.rest.vyos_command: + commands: + - - ip + - bgp + - summary + wait_for: + - result[0] contains Established + retries: 10 + interval: 5 + + + +Return Values +------------- +Common return values are documented `here `_, the following are the fields unique to this module: + +.. raw:: html + + + + + + + + + + + + + + + + + + + + + + +
KeyReturnedDescription
+
+ failed_conditions + +
+ list +
+ 		failed +
List of conditions that failed.
+
+
+
+ stdout + +
+ list +
+ 		always +
List of output from each command.
+
+
Sample:
+
['VyOS 1.5.0\n...', 'Interface IP Address\n...']
+
+
+ stdout_lines + +
+ list +
+ 		always +
List of output split into lines for each command.
+
+
+

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