From 1f338c3ef0e7af77bfc93f1b3f54584caa821124 Mon Sep 17 00:00:00 2001 From: omnom62 Date: Wed, 6 May 2026 08:08:49 +1000 Subject: more modules --- docs/vyos.rest.vyos_banner_module.rst | 340 ++++++ docs/vyos.rest.vyos_bgp_address_family_module.rst | 780 +++++++++++++ docs/vyos.rest.vyos_bgp_global_module.rst | 573 +++++++++ docs/vyos.rest.vyos_config_file_module.rst | 234 ++++ docs/vyos.rest.vyos_configure_module.rst | 290 +++++ docs/vyos.rest.vyos_facts_module.rst | 185 +++ docs/vyos.rest.vyos_firewall_global_module.rst | 752 ++++++++++++ docs/vyos.rest.vyos_firewall_interfaces_module.rst | 345 ++++++ docs/vyos.rest.vyos_firewall_rules_module.rst | 822 +++++++++++++ docs/vyos.rest.vyos_generate_module.rst | 191 +++ docs/vyos.rest.vyos_hostname_module.rst | 300 +++++ docs/vyos.rest.vyos_info_module.rst | 222 ++++ docs/vyos.rest.vyos_interfaces_module.rst | 452 ++++++++ docs/vyos.rest.vyos_l3_interfaces_module.rst | 470 ++++++++ docs/vyos.rest.vyos_lag_interfaces_module.rst | 393 +++++++ docs/vyos.rest.vyos_lldp_global_module.rst | 244 ++++ docs/vyos.rest.vyos_lldp_interfaces_module.rst | 389 +++++++ docs/vyos.rest.vyos_ntp_global_module.rst | 370 ++++++ docs/vyos.rest.vyos_ospf_interfaces_module.rst | 570 +++++++++ docs/vyos.rest.vyos_ospfv2_module.rst | 1202 +++++++++++++++++++ docs/vyos.rest.vyos_ospfv3_module.rst | 490 ++++++++ docs/vyos.rest.vyos_ping_module.rst | 332 ++++++ docs/vyos.rest.vyos_prefix_lists_module.rst | 431 +++++++ docs/vyos.rest.vyos_reset_module.rst | 191 +++ docs/vyos.rest.vyos_route_maps_module.rst | 932 +++++++++++++++ docs/vyos.rest.vyos_show_module.rst | 210 ++++ docs/vyos.rest.vyos_snmp_server_module.rst | 1211 ++++++++++++++++++++ docs/vyos.rest.vyos_static_routes_module.rst | 505 ++++++++ docs/vyos.rest.vyos_system_module.rst | 244 ++++ docs/vyos.rest.vyos_user_module.rst | 564 +++++++++ docs/vyos.rest.vyos_vlan_module.rst | 360 ++++++ 31 files changed, 14594 insertions(+) create mode 100644 docs/vyos.rest.vyos_banner_module.rst create mode 100644 docs/vyos.rest.vyos_bgp_address_family_module.rst create mode 100644 docs/vyos.rest.vyos_bgp_global_module.rst create mode 100644 docs/vyos.rest.vyos_config_file_module.rst create mode 100644 docs/vyos.rest.vyos_configure_module.rst create mode 100644 docs/vyos.rest.vyos_facts_module.rst create mode 100644 docs/vyos.rest.vyos_firewall_global_module.rst create mode 100644 docs/vyos.rest.vyos_firewall_interfaces_module.rst create mode 100644 docs/vyos.rest.vyos_firewall_rules_module.rst create mode 100644 docs/vyos.rest.vyos_generate_module.rst create mode 100644 docs/vyos.rest.vyos_hostname_module.rst create mode 100644 docs/vyos.rest.vyos_info_module.rst create mode 100644 docs/vyos.rest.vyos_interfaces_module.rst create mode 100644 docs/vyos.rest.vyos_l3_interfaces_module.rst create mode 100644 docs/vyos.rest.vyos_lag_interfaces_module.rst create mode 100644 docs/vyos.rest.vyos_lldp_global_module.rst create mode 100644 docs/vyos.rest.vyos_lldp_interfaces_module.rst create mode 100644 docs/vyos.rest.vyos_ntp_global_module.rst create mode 100644 docs/vyos.rest.vyos_ospf_interfaces_module.rst create mode 100644 docs/vyos.rest.vyos_ospfv2_module.rst create mode 100644 docs/vyos.rest.vyos_ospfv3_module.rst create mode 100644 docs/vyos.rest.vyos_ping_module.rst create mode 100644 docs/vyos.rest.vyos_prefix_lists_module.rst create mode 100644 docs/vyos.rest.vyos_reset_module.rst create mode 100644 docs/vyos.rest.vyos_route_maps_module.rst create mode 100644 docs/vyos.rest.vyos_show_module.rst create mode 100644 docs/vyos.rest.vyos_snmp_server_module.rst create mode 100644 docs/vyos.rest.vyos_static_routes_module.rst create mode 100644 docs/vyos.rest.vyos_system_module.rst create mode 100644 docs/vyos.rest.vyos_user_module.rst create mode 100644 docs/vyos.rest.vyos_vlan_module.rst (limited to 'docs') diff --git a/docs/vyos.rest.vyos_banner_module.rst b/docs/vyos.rest.vyos_banner_module.rst new file mode 100644 index 0000000..b459bfb --- /dev/null +++ b/docs/vyos.rest.vyos_banner_module.rst @@ -0,0 +1,340 @@ +.. _vyos.rest.vyos_banner_module: + + +********************* +vyos.rest.vyos_banner +********************* + +**Manage multiline banners on VyOS devices via REST API.** + + +Version added: 1.0.0 + +.. contents:: + :local: + :depth: 1 + + +Synopsis +-------- +- Manages pre-login and post-login banners on VyOS devices using the HTTPS REST API. +- Works with ``ansible_connection=ansible.netcommon.httpapi`` (recommended) or with direct ``hostname``/``api_key`` task parameters. +- VyOS stores banner newlines as literal ``\n`` in its config; this module handles that conversion automatically. + + + + +Parameters +---------- + +.. raw:: html + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
ParameterChoices/DefaultsComments
+
+ api_key + +
+ string +
+ 		+ +
REST API key (not needed when ansible_httpapi_api_key is set).
+
+
+ config + +
+ dictionary +
+ 		+ +
Banner configuration.
+
+
+ banner + +
+ string + / required +
+ 		+
    Choices: +
  • pre-login
    • +
  • post-login
    • +
+ 		+
Which banner to configure.
+
+
+ text + +
+ string +
+ 		+ +
The banner text. Required when state=merged or state=replaced.
+
Use a YAML block scalar (|) for multi-line banners.
+
Real newline characters are converted to the \n escape sequence that VyOS stores internally; this is transparent to the user.
+
+
+ hostname + +
+ string +
+ 		+ +
Device IP or FQDN (not needed with httpapi inventory).
+
+
+ port + +
+ integer +
+ 		+ Default:
443
+ 		+
HTTPS port (local mode only).
+
+
+ state + +
+ string +
+ 		+
    Choices: +
  • merged ←
    • +
  • replaced
    • +
  • deleted
    • +
  • gathered
    • +
+ 		+
Desired state of the banner configuration.
+
merged - set the banner if it differs from the current value.
+
replaced - replace the banner text unconditionally.
+
deleted - remove the banner.
+
gathered - return the current banner in gathered without making any changes.
+
+
+ timeout + +
+ integer +
+ 		+ Default:
30
+ 		+
Request timeout in seconds.
+
+
+ verify_ssl + +
+ boolean +
+ 		+
    Choices: +
  • no ←
    • +
  • yes
    • +
+ 		+
Validate the device TLS certificate.
+
+
+ + + +See Also +-------- + +.. seealso:: + + :ref:`vyos.vyos.vyos_banner_module` + The official documentation on the **vyos.vyos.vyos_banner** module. + + +Examples +-------- + +.. code-block:: yaml + + - name: Set pre-login banner (merged — only changes if different) + vyos.rest.vyos_banner: + config: + banner: pre-login + text: | + Junk pre-login banner + over multiple lines + state: merged + + - name: Replace post-login banner unconditionally + vyos.rest.vyos_banner: + config: + banner: post-login + text: "Welcome. Authorised access only." + state: replaced + + - name: Remove pre-login banner + vyos.rest.vyos_banner: + config: + banner: pre-login + state: deleted + + - name: Read current pre-login banner without changing it + vyos.rest.vyos_banner: + config: + banner: pre-login + state: gathered + register: result + + - name: Print gathered banner + ansible.builtin.debug: + msg: "Current banner: {{ result.gathered.text }}" + + + +Return Values +------------- +Common return values are documented `here `_, the following are the fields unique to this module: + +.. raw:: html + + + + + + + + + + + + + + + + + + + + + + + + + + + +
KeyReturnedDescription
+
+ after + +
+ dictionary +
+ 		when changed +
Banner configuration after the module ran.
+
+
+
+ before + +
+ dictionary +
+ 		always +
Banner configuration before the module ran.
+
+
Sample:
+
{'banner': 'pre-login', 'text': 'Old banner text\nline two\n'}
+
+
+ commands + +
+ list +
+ 		always +
Configuration commands issued.
+
+
+
+ gathered + +
+ dictionary +
+ 		when state is gathered +
Current banner configuration read from the device (state=gathered).
+
+
Sample:
+
{'banner': 'pre-login', 'text': 'Current banner\nline two\n'}
+
+

+ + +Status +------ + + +Authors +~~~~~~~ + +- VyOS Community (@vyos) diff --git a/docs/vyos.rest.vyos_bgp_address_family_module.rst b/docs/vyos.rest.vyos_bgp_address_family_module.rst new file mode 100644 index 0000000..8718293 --- /dev/null +++ b/docs/vyos.rest.vyos_bgp_address_family_module.rst @@ -0,0 +1,780 @@ +.. _vyos.rest.vyos_bgp_address_family_module: + + +********************************* +vyos.rest.vyos_bgp_address_family +********************************* + +**BGP Address Family resource module via REST API.** + + +Version added: 1.0.0 + +.. contents:: + :local: + :depth: 1 + + +Synopsis +-------- +- Manages BGP address-family configuration (networks, redistribute, aggregate-address, per-neighbor AFI settings) via the VyOS HTTPS REST API. + + + + +Parameters +---------- + +.. raw:: html + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
ParameterChoices/DefaultsComments
+
+ api_key + +
+ string + / required +
+ 		+ +
+
+ config + +
+ dictionary +
+ 		+ +
BGP address-family configuration.
+
+
+ address_family + +
+ list + / elements=dictionary +
+ 		+ +
Global address-family parameters.
+
+
+ afi + +
+ string +
+ 		+
    Choices: +
  • ipv4
    • +
  • ipv6
    • +
+ 		+
Address family (ipv4 or ipv6).
+
+
+ aggregate_address + +
+ list + / elements=dictionary +
+ 		+ +
List of BGP aggregate networks.
+
+
+ as_set + +
+ boolean +
+ 		+
    Choices: +
  • no
    • +
  • yes
    • +
+ 		+
+
+ prefix + +
+ string +
+ 		+ +
+
+ summary_only + +
+ boolean +
+ 		+
    Choices: +
  • no
    • +
  • yes
    • +
+ 		+
+
+ networks + +
+ list + / elements=dictionary +
+ 		+ +
Networks to originate.
+
+
+ backdoor + +
+ boolean +
+ 		+
    Choices: +
  • no
    • +
  • yes
    • +
+ 		+
+
+ path_limit + +
+ integer +
+ 		+ +
+
+ prefix + +
+ string +
+ 		+ +
+
+ route_map + +
+ string +
+ 		+ +
+
+ redistribute + +
+ list + / elements=dictionary +
+ 		+ +
Protocols to redistribute.
+
+
+ metric + +
+ integer +
+ 		+ +
+
+ protocol + +
+ string +
+ 		+
    Choices: +
  • connected
    • +
  • kernel
    • +
  • ospf
    • +
  • ospfv3
    • +
  • rip
    • +
  • ripng
    • +
  • static
    • +
+ 		+
+
+ route_map + +
+ string +
+ 		+ +
+
+ table + +
+ string +
+ 		+ +
+
+ as_number + +
+ integer + / required +
+ 		+ +
Local AS number.
+
+
+ neighbors + +
+ list + / elements=dictionary +
+ 		+ +
Per-neighbor address-family settings.
+
+
+ address_family + +
+ list + / elements=dictionary +
+ 		+ +
+
+ afi + +
+ string +
+ 		+
    Choices: +
  • ipv4
    • +
  • ipv6
    • +
+ 		+
+
+ allowas_in + +
+ integer +
+ 		+ +
+
+ as_override + +
+ boolean +
+ 		+
    Choices: +
  • no
    • +
  • yes
    • +
+ 		+
+
+ nexthop_self + +
+ boolean +
+ 		+
    Choices: +
  • no
    • +
  • yes
    • +
+ 		+
+
+ remove_private_as + +
+ boolean +
+ 		+
    Choices: +
  • no
    • +
  • yes
    • +
+ 		+
+
+ route_map + +
+ dictionary +
+ 		+ +
Route-map settings.
+
+
+ export_map + +
+ string +
+ 		+ +
+
+ import_map + +
+ string +
+ 		+ +
+
+ soft_reconfiguration + +
+ boolean +
+ 		+
    Choices: +
  • no
    • +
  • yes
    • +
+ 		+
+
+ neighbor_address + +
+ string +
+ 		+ +
Neighbor IP.
+
+
+ hostname + +
+ string + / required +
+ 		+ +
Device IP or FQDN.
+
+
+ port + +
+ integer +
+ 		+ Default:
443
+ 		+
+
+ state + +
+ string +
+ 		+
    Choices: +
  • merged ←
    • +
  • replaced
    • +
  • deleted
    • +
  • gathered
    • +
+ 		+
Desired state.
+
+
+ timeout + +
+ integer +
+ 		+ Default:
30
+ 		+
+
+ verify_ssl + +
+ boolean +
+ 		+
    Choices: +
  • no ←
    • +
  • yes
    • +
+ 		+
+
+ + + + + + + +Return Values +------------- +Common return values are documented `here `_, the following are the fields unique to this module: + +.. raw:: html + + + + + + + + + + + + + + + + + + + + + + +
KeyReturnedDescription
+
+ after + +
+ dictionary +
+ 		when changed +
Config after module ran.
+
+
+
+ before + +
+ dictionary +
+ 		always +
Config before module ran.
+
+
+
+ commands + +
+ list +
+ 		always +
Commands issued.
+
+
+

+ + +Status +------ + + +Authors +~~~~~~~ + +- VyOS Community (@vyos) diff --git a/docs/vyos.rest.vyos_bgp_global_module.rst b/docs/vyos.rest.vyos_bgp_global_module.rst new file mode 100644 index 0000000..4c91b4a --- /dev/null +++ b/docs/vyos.rest.vyos_bgp_global_module.rst @@ -0,0 +1,573 @@ +.. _vyos.rest.vyos_bgp_global_module: + + +************************* +vyos.rest.vyos_bgp_global +************************* + +**Manage BGP global configuration on VyOS via the REST API.** + + +Version added: 1.0.0 + +.. contents:: + :local: + :depth: 1 + + +Synopsis +-------- +- Manages BGP global parameters on VyOS devices using the HTTPS REST API. +- Mirrors ``vyos.vyos.vyos_bgp_global`` but uses the HTTP API. + + + +Requirements +------------ +The below requirements are needed on the host that executes this module. + +- VyOS 1.3+ + + +Parameters +---------- + +.. raw:: html + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
ParameterChoices/DefaultsComments
+
+ api_key + +
+ string + / required +
+ 		+ +
API key configured on the device.
+
+
+ config + +
+ dictionary +
+ 		+ +
BGP global configuration.
+
+
+ as_number + +
+ integer + / required +
+ 		+ +
Local BGP AS number.
+
+
+ neighbors + +
+ list + / elements=dictionary +
+ 		+ +
List of BGP neighbor configurations.
+
+
+ description + +
+ string +
+ 		+ +
Neighbor description.
+
+
+ ebgp_multihop + +
+ integer +
+ 		+ +
Maximum hops for eBGP sessions.
+
+
+ neighbor + +
+ string + / required +
+ 		+ +
Neighbor IP address.
+
+
+ password + +
+ string +
+ 		+ +
MD5 authentication password.
+
+
+ remote_as + +
+ integer +
+ 		+ +
Neighbor's AS number.
+
+
+ shutdown + +
+ boolean +
+ 		+
    Choices: +
  • no
    • +
  • yes
    • +
+ 		+
Whether to administratively shut down the neighbor.
+
+
+ update_source + +
+ string +
+ 		+ +
Local interface or address for BGP session.
+
+
+ networks + +
+ list + / elements=dictionary +
+ 		+ +
List of networks to originate.
+
+
+ prefix + +
+ string + / required +
+ 		+ +
Network prefix to advertise.
+
+
+ route_map + +
+ string +
+ 		+ +
Route map to apply.
+
+
+ redistribute + +
+ list + / elements=dictionary +
+ 		+ +
List of protocols to redistribute into BGP.
+
+
+ metric + +
+ integer +
+ 		+ +
Metric for redistributed routes.
+
+
+ protocol + +
+ string + / required +
+ 		+
    Choices: +
  • connected
    • +
  • kernel
    • +
  • ospf
    • +
  • ospfv3
    • +
  • rip
    • +
  • ripng
    • +
  • static
    • +
+ 		+
Protocol to redistribute.
+
+
+ route_map + +
+ string +
+ 		+ +
Route map to apply.
+
+
+ router_id + +
+ string +
+ 		+ +
BGP router ID (IPv4 address).
+
+
+ hostname + +
+ string + / required +
+ 		+ +
IP address or FQDN of the VyOS device.
+
+
+ port + +
+ integer +
+ 		+ Default:
443
+ 		+
HTTPS port for the REST API.
+
+
+ state + +
+ string +
+ 		+
    Choices: +
  • merged ←
    • +
  • replaced
    • +
  • deleted
    • +
  • gathered
    • +
+ 		+
{'merged': 'Merge BGP config with existing.'}
+
{'replaced': 'Replace entire BGP config.'}
+
{'deleted': 'Remove BGP configuration.'}
+
{'gathered': 'Read BGP config from device.'}
+
+
+ timeout + +
+ integer +
+ 		+ Default:
30
+ 		+
Request timeout in seconds.
+
+
+ verify_ssl + +
+ boolean +
+ 		+
    Choices: +
  • no ←
    • +
  • yes
    • +
+ 		+
Validate the device's TLS certificate.
+
+
+ + + +See Also +-------- + +.. seealso:: + + :ref:`vyos.vyos.vyos_bgp_global_module` + The official documentation on the **vyos.vyos.vyos_bgp_global** module. + + + + + +Return Values +------------- +Common return values are documented `here `_, the following are the fields unique to this module: + +.. raw:: html + + + + + + + + + + + + + + + + + + + + + + + + + + + +
KeyReturnedDescription
+
+ after + +
+ dictionary +
+ 		when changed +
BGP config after the module ran.
+
+
+
+ before + +
+ dictionary +
+ 		always +
BGP config before the module ran.
+
+
+
+ commands + +
+ list +
+ 		always +
set/delete commands issued.
+
+
+
+ gathered + +
+ dictionary +
+ 		when state is gathered +
BGP config read from device (state=gathered).
+
+
+

+ + +Status +------ + + +Authors +~~~~~~~ + +- VyOS Community (@vyos) diff --git a/docs/vyos.rest.vyos_config_file_module.rst b/docs/vyos.rest.vyos_config_file_module.rst new file mode 100644 index 0000000..a1f0dba --- /dev/null +++ b/docs/vyos.rest.vyos_config_file_module.rst @@ -0,0 +1,234 @@ +.. _vyos.rest.vyos_config_file_module: + + +************************** +vyos.rest.vyos_config_file +************************** + +**Save or load VyOS configuration files via the REST API.** + + +Version added: 1.0.0 + +.. contents:: + :local: + :depth: 1 + + +Synopsis +-------- +- Manages VyOS configuration persistence via the HTTPS REST API (``/config-file`` endpoint). +- Use *op=save* to write the running configuration to a file. +- Use *op=load* to load a configuration from a file and apply it. + + + +Requirements +------------ +The below requirements are needed on the host that executes this module. + +- VyOS 1.3+ + + +Parameters +---------- + +.. raw:: html + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
ParameterChoices/DefaultsComments
+
+ api_key + +
+ string + / required +
+ 		+ +
API key configured on the device.
+
+
+ file + +
+ string +
+ 		+ +
Path on the VyOS device for save/load target.
+
If omitted for save, the device uses its default boot config path.
+
+
+ hostname + +
+ string + / required +
+ 		+ +
IP address or FQDN of the VyOS device.
+
+
+ op + +
+ string +
+ 		+
    Choices: +
  • save ←
    • +
  • load
    • +
+ 		+
save - Save the running configuration to file or the default /config/config.boot.
+
load - Load and commit the configuration from file.
+
+
+ port + +
+ integer +
+ 		+ Default:
443
+ 		+
HTTPS port for the REST API.
+
+
+ timeout + +
+ integer +
+ 		+ Default:
30
+ 		+
Request timeout in seconds.
+
+
+ verify_ssl + +
+ boolean +
+ 		+
    Choices: +
  • no ←
    • +
  • yes
    • +
+ 		+
Validate the device's TLS certificate.
+
+
+ + + + +Examples +-------- + +.. code-block:: yaml + + - name: Save running config (default location) + vyos.rest.vyos_config_file: + hostname: 192.168.1.1 + api_key: MY-KEY + op: save + + - name: Save running config to a custom file + vyos.rest.vyos_config_file: + hostname: 192.168.1.1 + api_key: MY-KEY + op: save + file: /config/backups/config.boot.bak + + - name: Load a configuration from file + vyos.rest.vyos_config_file: + hostname: 192.168.1.1 + api_key: MY-KEY + op: load + file: /config/backups/config.boot.bak + + + +Return Values +------------- +Common return values are documented `here `_, the following are the fields unique to this module: + +.. raw:: html + + + + + + + + + + + + +
KeyReturnedDescription
+
+ output + +
+ string +
+ 		success +
Text output from the config-file operation.
+
+
+

+ + +Status +------ + + +Authors +~~~~~~~ + +- VyOS Community (@vyos) diff --git a/docs/vyos.rest.vyos_configure_module.rst b/docs/vyos.rest.vyos_configure_module.rst new file mode 100644 index 0000000..e896fcc --- /dev/null +++ b/docs/vyos.rest.vyos_configure_module.rst @@ -0,0 +1,290 @@ +.. _vyos.rest.vyos_configure_module: + + +************************ +vyos.rest.vyos_configure +************************ + +**Manage VyOS device configuration via the REST API.** + + +Version added: 1.0.0 + +.. contents:: + :local: + :depth: 1 + + +Synopsis +-------- +- Sends one or more ``set`` or ``delete`` configuration commands to a VyOS device via its HTTPS REST API (``/configure`` endpoint). +- Each command in *commands* is executed and committed atomically. +- Supports Ansible check-mode (``check_mode=yes``) - no changes are applied. + + + +Requirements +------------ +The below requirements are needed on the host that executes this module. + +- VyOS 1.3+ + + +Parameters +---------- + +.. raw:: html + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
ParameterChoices/DefaultsComments
+
+ api_key + +
+ string + / required +
+ 		+ +
API key configured on the device.
+
+
+ commands + +
+ list + / elements=raw + / required +
+ 		+ +
List of VyOS configuration commands.
+
Each item may be either a plain string in VyOS CLI syntax (e.g. set interfaces ethernet eth0 description 'WAN') or a dict with keys op, path, and optionally value.
+
+
+ hostname + +
+ string + / required +
+ 		+ +
IP address or FQDN of the VyOS device.
+
+
+ port + +
+ integer +
+ 		+ Default:
443
+ 		+
HTTPS port for the REST API.
+
+
+ save + +
+ boolean +
+ 		+
    Choices: +
  • no ←
    • +
  • yes
    • +
+ 		+
Whether to save the configuration to disk after a successful commit.
+
+
+ timeout + +
+ integer +
+ 		+ Default:
30
+ 		+
Request timeout in seconds.
+
+
+ verify_ssl + +
+ boolean +
+ 		+
    Choices: +
  • no ←
    • +
  • yes
    • +
+ 		+
Validate the device's TLS certificate.
+
+
+ + +Notes +----- + +.. note:: + - The VyOS HTTP API must be enabled on the device before using this module. + - Enable with ``set service https api keys id key `` and ``set service https api rest``, then ``commit && save``. + - Tested against VyOS 1.3 and 1.4. + + +See Also +-------- + +.. seealso:: + + :ref:`vyos.rest.vyos_retrieve_module` + The official documentation on the **vyos.rest.vyos_retrieve** module. + :ref:`vyos.rest.vyos_show_module` + The official documentation on the **vyos.rest.vyos_show** module. + + +Examples +-------- + +.. code-block:: yaml + + - name: Set hostname via REST API + vyos.rest.vyos_configure: + hostname: 192.168.1.1 + api_key: MY-KEY + commands: + - "set system host-name vyos-router" + + - name: Configure an interface description and address + vyos.rest.vyos_configure: + hostname: 192.168.1.1 + api_key: MY-KEY + commands: + - "set interfaces ethernet eth1 description 'UPLINK'" + - "set interfaces ethernet eth1 address 10.0.0.1/30" + save: true + + - name: Delete a static route using dict syntax + vyos.rest.vyos_configure: + hostname: 192.168.1.1 + api_key: MY-KEY + commands: + - op: delete + path: ["protocols", "static", "route", "192.0.2.0/24"] + + + +Return Values +------------- +Common return values are documented `here `_, the following are the fields unique to this module: + +.. raw:: html + + + + + + + + + + + + + + + + + + + + + + +
KeyReturnedDescription
+
+ changed + +
+ boolean +
+ 		always +
Whether the device configuration was modified.
+
+
+
+ commands_sent + +
+ list + / elements=dictionary +
+ 		always +
The list of commands dispatched to the API.
+
+
Sample:
+
[{'op': 'set', 'path': ['system', 'host-name'], 'value': 'vyos-router'}]
+
+
+ saved + +
+ boolean +
+ 		always +
Whether the configuration was saved to disk.
+
+
+

+ + +Status +------ + + +Authors +~~~~~~~ + +- VyOS Community (@vyos) diff --git a/docs/vyos.rest.vyos_facts_module.rst b/docs/vyos.rest.vyos_facts_module.rst new file mode 100644 index 0000000..23c385f --- /dev/null +++ b/docs/vyos.rest.vyos_facts_module.rst @@ -0,0 +1,185 @@ +.. _vyos.rest.vyos_facts_module: + + +******************** +vyos.rest.vyos_facts +******************** + +**Get facts about VyOS devices via REST API.** + + +Version added: 1.0.0 + +.. contents:: + :local: + :depth: 1 + + +Synopsis +-------- +- Collects facts from VyOS devices using the HTTPS REST API. +- Returns system info and optionally per-resource configuration facts. + + + + +Parameters +---------- + +.. raw:: html + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
ParameterChoices/DefaultsComments
+
+ api_key + +
+ string + / required +
+ 		+ +
+
+ available_network_resources + +
+ boolean +
+ 		+
    Choices: +
  • no ←
    • +
  • yes
    • +
+ 		+
When true, return a list of available resource names.
+
+
+ gather_network_resources + +
+ list + / elements=string +
+ 		+ +
Which network resource facts to gather.
+
+
+ gather_subset + +
+ list + / elements=string +
+ 		+ Default:
["min"]
+ 		+
Restrict facts to a subset. Use all, default, config, or min.
+
+
+ hostname + +
+ string + / required +
+ 		+ +
Device IP or FQDN.
+
+
+ port + +
+ integer +
+ 		+ Default:
443
+ 		+
+
+ timeout + +
+ integer +
+ 		+ Default:
30
+ 		+
+
+ verify_ssl + +
+ boolean +
+ 		+
    Choices: +
  • no ←
    • +
  • yes
    • +
+ 		+
+
+ + + + + + + + +Status +------ + + +Authors +~~~~~~~ + +- VyOS Community (@vyos) diff --git a/docs/vyos.rest.vyos_firewall_global_module.rst b/docs/vyos.rest.vyos_firewall_global_module.rst new file mode 100644 index 0000000..581e912 --- /dev/null +++ b/docs/vyos.rest.vyos_firewall_global_module.rst @@ -0,0 +1,752 @@ +.. _vyos.rest.vyos_firewall_global_module: + + +****************************** +vyos.rest.vyos_firewall_global +****************************** + +**Firewall global resource module via REST API.** + + +Version added: 1.0.0 + +.. contents:: + :local: + :depth: 1 + + +Synopsis +-------- +- Manages global VyOS firewall parameters (groups, ICMP redirect policy, source validation, ping policy) via the HTTPS REST API. + + + + +Parameters +---------- + +.. raw:: html + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
ParameterChoices/DefaultsComments
+
+ api_key + +
+ string + / required +
+ 		+ +
+
+ config + +
+ dictionary +
+ 		+ +
Global firewall configuration.
+
+
+ config_trap + +
+ boolean +
+ 		+
    Choices: +
  • no
    • +
  • yes
    • +
+ 		+
SNMP trap on firewall config changes.
+
+
+ group + +
+ dictionary +
+ 		+ +
Firewall object groups.
+
+
+ address_group + +
+ list + / elements=dictionary +
+ 		+ +
+
+ afi + +
+ string +
+ 		+
    Choices: +
  • ipv4 ←
    • +
  • ipv6
    • +
+ 		+
+
+ description + +
+ string +
+ 		+ +
+
+ members + +
+ list + / elements=dictionary +
+ 		+ +
List of IP addresses or ranges.
+
+
+ address + +
+ string +
+ 		+ +
+
+ name + +
+ string + / required +
+ 		+ +
+
+ network_group + +
+ list + / elements=dictionary +
+ 		+ +
+
+ description + +
+ string +
+ 		+ +
+
+ members + +
+ list + / elements=dictionary +
+ 		+ +
List of network prefixes.
+
+
+ address + +
+ string +
+ 		+ +
+
+ name + +
+ string + / required +
+ 		+ +
+
+ port_group + +
+ list + / elements=dictionary +
+ 		+ +
+
+ description + +
+ string +
+ 		+ +
+
+ members + +
+ list + / elements=dictionary +
+ 		+ +
List of port numbers or ranges.
+
+
+ port + +
+ string +
+ 		+ +
+
+ name + +
+ string + / required +
+ 		+ +
+
+ ping + +
+ dictionary +
+ 		+ +
ICMP echo policy.
+
+
+ all + +
+ boolean +
+ 		+
    Choices: +
  • no
    • +
  • yes
    • +
+ 		+
+
+ broadcast + +
+ boolean +
+ 		+
    Choices: +
  • no
    • +
  • yes
    • +
+ 		+
+
+ route_redirects + +
+ list + / elements=dictionary +
+ 		+ +
ICMP redirect / source-route options per AFI.
+
+
+ afi + +
+ string + / required +
+ 		+
    Choices: +
  • ipv4
    • +
  • ipv6
    • +
+ 		+
+
+ icmp_redirects + +
+ dictionary +
+ 		+ +
+
+ receive + +
+ boolean +
+ 		+
    Choices: +
  • no
    • +
  • yes
    • +
+ 		+
+
+ send + +
+ boolean +
+ 		+
    Choices: +
  • no
    • +
  • yes
    • +
+ 		+
+
+ ip_src_route + +
+ boolean +
+ 		+
    Choices: +
  • no
    • +
  • yes
    • +
+ 		+
+
+ validation + +
+ string +
+ 		+
    Choices: +
  • strict
    • +
  • loose
    • +
  • disable
    • +
+ 		+
Source-validation policy (strict/loose/disable).
+
+
+ hostname + +
+ string + / required +
+ 		+ +
+
+ port + +
+ integer +
+ 		+ Default:
443
+ 		+
+
+ state + +
+ string +
+ 		+
    Choices: +
  • merged ←
    • +
  • replaced
    • +
  • deleted
    • +
  • gathered
    • +
+ 		+
Desired state.
+
+
+ timeout + +
+ integer +
+ 		+ Default:
30
+ 		+
+
+ verify_ssl + +
+ boolean +
+ 		+
    Choices: +
  • no ←
    • +
  • yes
    • +
+ 		+
+
+ + + + + + + +Return Values +------------- +Common return values are documented `here `_, the following are the fields unique to this module: + +.. raw:: html + + + + + + + + + + + + + + + + + + + + + + +
KeyReturnedDescription
+
+ after + +
+ dictionary +
+ 		when changed +
+
+
+ before + +
+ dictionary +
+ 		always +
+
+
+ commands + +
+ list +
+ 		always +
+
+

+ + +Status +------ + + +Authors +~~~~~~~ + +- VyOS Community (@vyos) diff --git a/docs/vyos.rest.vyos_firewall_interfaces_module.rst b/docs/vyos.rest.vyos_firewall_interfaces_module.rst new file mode 100644 index 0000000..e1efc1d --- /dev/null +++ b/docs/vyos.rest.vyos_firewall_interfaces_module.rst @@ -0,0 +1,345 @@ +.. _vyos.rest.vyos_firewall_interfaces_module: + + +********************************** +vyos.rest.vyos_firewall_interfaces +********************************** + +**Firewall interfaces resource module via REST API.** + + +Version added: 1.0.0 + +.. contents:: + :local: + :depth: 1 + + +Synopsis +-------- +- Attaches or detaches named firewall rule sets to/from interface directions (in/out/local) using the VyOS HTTPS REST API. + + + + +Parameters +---------- + +.. raw:: html + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
ParameterChoices/DefaultsComments
+
+ api_key + +
+ string + / required +
+ 		+ +
+
+ config + +
+ list + / elements=dictionary +
+ 		+ +
List of interface firewall attachment configurations.
+
+
+ access_rules + +
+ list + / elements=dictionary +
+ 		+ +
Firewall rule sets per AFI.
+
+
+ afi + +
+ string + / required +
+ 		+
    Choices: +
  • ipv4
    • +
  • ipv6
    • +
+ 		+
Address family.
+
+
+ rules + +
+ list + / elements=dictionary +
+ 		+ +
Rule sets and directions.
+
+
+ direction + +
+ string + / required +
+ 		+
    Choices: +
  • in
    • +
  • local
    • +
  • out
    • +
+ 		+
Traffic direction.
+
+
+ name + +
+ string +
+ 		+ +
Rule set name.
+
+
+ name + +
+ string + / required +
+ 		+ +
Interface name.
+
+
+ hostname + +
+ string + / required +
+ 		+ +
+
+ port + +
+ integer +
+ 		+ Default:
443
+ 		+
+
+ state + +
+ string +
+ 		+
    Choices: +
  • merged ←
    • +
  • replaced
    • +
  • overridden
    • +
  • deleted
    • +
  • gathered
    • +
+ 		+
Desired state.
+
+
+ timeout + +
+ integer +
+ 		+ Default:
30
+ 		+
+
+ verify_ssl + +
+ boolean +
+ 		+
    Choices: +
  • no ←
    • +
  • yes
    • +
+ 		+
+
+ + + + + + + +Return Values +------------- +Common return values are documented `here `_, the following are the fields unique to this module: + +.. raw:: html + + + + + + + + + + + + + + + + + + + + + + +
KeyReturnedDescription
+
+ after + +
+ list +
+ 		when changed +
+
+
+ before + +
+ list +
+ 		always +
+
+
+ commands + +
+ list +
+ 		always +
+
+

+ + +Status +------ + + +Authors +~~~~~~~ + +- VyOS Community (@vyos) diff --git a/docs/vyos.rest.vyos_firewall_rules_module.rst b/docs/vyos.rest.vyos_firewall_rules_module.rst new file mode 100644 index 0000000..b95891a --- /dev/null +++ b/docs/vyos.rest.vyos_firewall_rules_module.rst @@ -0,0 +1,822 @@ +.. _vyos.rest.vyos_firewall_rules_module: + + +***************************** +vyos.rest.vyos_firewall_rules +***************************** + +**Manage firewall rules on VyOS via the REST API.** + + +Version added: 1.0.0 + +.. contents:: + :local: + :depth: 1 + + +Synopsis +-------- +- Manages VyOS firewall rule sets and individual rules using the HTTPS REST API. +- Mirrors ``vyos.vyos.vyos_firewall_rules`` but uses the HTTP API. + + + +Requirements +------------ +The below requirements are needed on the host that executes this module. + +- VyOS 1.3+ + + +Parameters +---------- + +.. raw:: html + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
ParameterChoices/DefaultsComments
+
+ api_key + +
+ string + / required +
+ 		+ +
API key configured on the device.
+
+
+ config + +
+ list + / elements=dictionary +
+ 		+ +
List of firewall rule set configurations.
+
+
+ afi + +
+ string + / required +
+ 		+
    Choices: +
  • ipv4
    • +
  • ipv6
    • +
+ 		+
Address family.
+
+
+ rule_sets + +
+ list + / elements=dictionary +
+ 		+ +
List of named rule sets.
+
+
+ default_action + +
+ string +
+ 		+
    Choices: +
  • drop ←
    • +
  • reject
    • +
  • accept
    • +
+ 		+
Default action for unmatched traffic.
+
+
+ description + +
+ string +
+ 		+ +
Rule set description.
+
+
+ name + +
+ string + / required +
+ 		+ +
Rule set name.
+
+
+ rules + +
+ list + / elements=dictionary +
+ 		+ +
List of firewall rules.
+
+
+ action + +
+ string +
+ 		+
    Choices: +
  • drop
    • +
  • reject
    • +
  • accept
    • +
  • inspect
    • +
+ 		+
Rule action.
+
+
+ description + +
+ string +
+ 		+ +
Rule description.
+
+
+ destination + +
+ dictionary +
+ 		+ +
Destination match criteria.
+
+
+ address + +
+ string +
+ 		+ +
Destination IP address or network.
+
+
+ group + +
+ dictionary +
+ 		+ +
Address or network group.
+
+
+ address_group + +
+ string +
+ 		+ +
+
+ network_group + +
+ string +
+ 		+ +
+
+ port + +
+ string +
+ 		+ +
Destination port or port range.
+
+
+ enabled + +
+ boolean +
+ 		+
    Choices: +
  • no
    • +
  • yes ←
    • +
+ 		+
Whether the rule is active.
+
+
+ number + +
+ integer + / required +
+ 		+ +
Rule number (1-999999).
+
+
+ protocol + +
+ string +
+ 		+ +
Protocol (e.g. tcp, udp, icmp, all).
+
+
+ source + +
+ dictionary +
+ 		+ +
Source match criteria.
+
+
+ address + +
+ string +
+ 		+ +
Source IP address or network.
+
+
+ group + +
+ dictionary +
+ 		+ +
Address or network group.
+
+
+ address_group + +
+ string +
+ 		+ +
+
+ network_group + +
+ string +
+ 		+ +
+
+ port + +
+ string +
+ 		+ +
Source port or port range.
+
+
+ state + +
+ dictionary +
+ 		+ +
Connection state matching.
+
+
+ established + +
+ boolean +
+ 		+
    Choices: +
  • no
    • +
  • yes
    • +
+ 		+
+
+ invalid + +
+ boolean +
+ 		+
    Choices: +
  • no
    • +
  • yes
    • +
+ 		+
+
+ new + +
+ boolean +
+ 		+
    Choices: +
  • no
    • +
  • yes
    • +
+ 		+
+
+ related + +
+ boolean +
+ 		+
    Choices: +
  • no
    • +
  • yes
    • +
+ 		+
+
+ hostname + +
+ string + / required +
+ 		+ +
IP address or FQDN of the VyOS device.
+
+
+ port + +
+ integer +
+ 		+ Default:
443
+ 		+
HTTPS port for the REST API.
+
+
+ state + +
+ string +
+ 		+
    Choices: +
  • merged ←
    • +
  • replaced
    • +
  • overridden
    • +
  • deleted
    • +
  • gathered
    • +
+ 		+
{'merged': 'Add/update listed rule sets and rules.'}
+
{'replaced': 'Replace listed rule sets entirely.'}
+
{'overridden': 'Replace the entire firewall rule config.'}
+
{'deleted': 'Remove listed (or all) rule sets.'}
+
{'gathered': 'Read firewall rule config from device.'}
+
+
+ timeout + +
+ integer +
+ 		+ Default:
30
+ 		+
Request timeout in seconds.
+
+
+ verify_ssl + +
+ boolean +
+ 		+
    Choices: +
  • no ←
    • +
  • yes
    • +
+ 		+
Validate the device's TLS certificate.
+
+
+ + + +See Also +-------- + +.. seealso:: + + :ref:`vyos.vyos.vyos_firewall_rules_module` + The official documentation on the **vyos.vyos.vyos_firewall_rules** module. + + + + + +Return Values +------------- +Common return values are documented `here `_, the following are the fields unique to this module: + +.. raw:: html + + + + + + + + + + + + + + + + + + + + + + + + + + + +
KeyReturnedDescription
+
+ after + +
+ list +
+ 		when changed +
Firewall rule config after the module ran.
+
+
+
+ before + +
+ list +
+ 		always +
Firewall rule config before the module ran.
+
+
+
+ commands + +
+ list +
+ 		always +
set/delete commands issued.
+
+
+
+ gathered + +
+ list +
+ 		when state is gathered +
Firewall config read from device (state=gathered).
+
+
+

+ + +Status +------ + + +Authors +~~~~~~~ + +- VyOS Community (@vyos) diff --git a/docs/vyos.rest.vyos_generate_module.rst b/docs/vyos.rest.vyos_generate_module.rst new file mode 100644 index 0000000..f972ee7 --- /dev/null +++ b/docs/vyos.rest.vyos_generate_module.rst @@ -0,0 +1,191 @@ +.. _vyos.rest.vyos_generate_module: + + +*********************** +vyos.rest.vyos_generate +*********************** + +**Execute generate commands on a VyOS device via REST API.** + + +Version added: 1.0.0 + +.. contents:: + :local: + :depth: 1 + + +Synopsis +-------- +- Sends a ``generate`` operational command to a VyOS device via the HTTPS REST API (``/generate`` endpoint). +- Commonly used to generate WireGuard keypairs, TLS certificates, etc. + + + +Requirements +------------ +The below requirements are needed on the host that executes this module. + +- VyOS 1.3+ + + +Parameters +---------- + +.. raw:: html + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
ParameterChoices/DefaultsComments
+
+ api_key + +
+ string + / required +
+ 		+ +
API key configured on the device.
+
+
+ hostname + +
+ string + / required +
+ 		+ +
IP address or FQDN of the VyOS device.
+
+
+ path + +
+ list + / elements=string + / required +
+ 		+ +
Generate command tokens.
+
E.g. ["wireguard", "default-keypair"].
+
+
+ port + +
+ integer +
+ 		+ Default:
443
+ 		+
HTTPS port for the REST API.
+
+
+ timeout + +
+ integer +
+ 		+ Default:
30
+ 		+
Request timeout in seconds.
+
+
+ verify_ssl + +
+ boolean +
+ 		+
    Choices: +
  • no ←
    • +
  • yes
    • +
+ 		+
Validate the device's TLS certificate.
+
+
+ + + + + + + +Return Values +------------- +Common return values are documented `here `_, the following are the fields unique to this module: + +.. raw:: html + + + + + + + + + + + + +
KeyReturnedDescription
+
+ output + +
+ string +
+ 		success +
Text output produced by the generate command (may be empty).
+
+
+

+ + +Status +------ + + +Authors +~~~~~~~ + +- VyOS Community (@vyos) diff --git a/docs/vyos.rest.vyos_hostname_module.rst b/docs/vyos.rest.vyos_hostname_module.rst new file mode 100644 index 0000000..b8fb5fd --- /dev/null +++ b/docs/vyos.rest.vyos_hostname_module.rst @@ -0,0 +1,300 @@ +.. _vyos.rest.vyos_hostname_module: + + +*********************** +vyos.rest.vyos_hostname +*********************** + +**Manage the system hostname on a VyOS device via the REST API.** + + +Version added: 1.0.0 + +.. contents:: + :local: + :depth: 1 + + +Synopsis +-------- +- Manages the ``set system host-name`` configuration on a VyOS device using the HTTPS REST API. +- Mirrors the behaviour of ``vyos.vyos.vyos_hostname`` but uses the HTTP API instead of SSH/network_cli. + + + +Requirements +------------ +The below requirements are needed on the host that executes this module. + +- VyOS 1.3+ + + +Parameters +---------- + +.. raw:: html + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
ParameterChoices/DefaultsComments
+
+ api_key + +
+ string + / required +
+ 		+ +
API key configured on the device.
+
+
+ config + +
+ dictionary +
+ 		+ +
Hostname configuration.
+
+
+ hostname + +
+ string + / required +
+ 		+ +
System hostname (max 63 characters, no underscores).
+
+
+ hostname + +
+ string + / required +
+ 		+ +
IP address or FQDN of the VyOS device.
+
+
+ port + +
+ integer +
+ 		+ Default:
443
+ 		+
HTTPS port for the REST API.
+
+
+ state + +
+ string +
+ 		+
    Choices: +
  • merged ←
    • +
  • deleted
    • +
  • gathered
    • +
+ 		+
merged - Ensure the hostname is set to the value in config.
+
deleted - Remove the configured hostname (resets to default).
+
gathered - Read the current hostname from the device and return it in gathered without making changes.
+
+
+ timeout + +
+ integer +
+ 		+ Default:
30
+ 		+
Request timeout in seconds.
+
+
+ verify_ssl + +
+ boolean +
+ 		+
    Choices: +
  • no ←
    • +
  • yes
    • +
+ 		+
Validate the device's TLS certificate.
+
+
+ + + +See Also +-------- + +.. seealso:: + + :ref:`vyos.vyos.vyos_hostname_module` + The official documentation on the **vyos.vyos.vyos_hostname** module. + + +Examples +-------- + +.. code-block:: yaml + + - name: Set hostname + vyos.rest.vyos_hostname: + config: + hostname: vyos-core-01 + state: merged + + - name: Gather current hostname + vyos.rest.vyos_hostname: + state: gathered + register: result + + - name: Delete hostname configuration + vyos.rest.vyos_hostname: + state: deleted + + + +Return Values +------------- +Common return values are documented `here `_, the following are the fields unique to this module: + +.. raw:: html + + + + + + + + + + + + + + + + + + + + + + + + + + + +
KeyReturnedDescription
+
+ after + +
+ dictionary +
+ 		when changed +
Configuration on the device after the module ran.
+
+
+
+ before + +
+ dictionary +
+ 		always +
Configuration on the device before the module ran.
+
+
+
+ commands + +
+ list +
+ 		always +
REST API commands dispatched.
+
+
+
+ gathered + +
+ dictionary +
+ 		when state is gathered +
Hostname read from the device (state=gathered only).
+
+
+

+ + +Status +------ + + +Authors +~~~~~~~ + +- VyOS Community (@vyos) diff --git a/docs/vyos.rest.vyos_info_module.rst b/docs/vyos.rest.vyos_info_module.rst new file mode 100644 index 0000000..60cf87d --- /dev/null +++ b/docs/vyos.rest.vyos_info_module.rst @@ -0,0 +1,222 @@ +.. _vyos.rest.vyos_info_module: + + +******************* +vyos.rest.vyos_info +******************* + +**Retrieve system information from a VyOS device via the REST API.** + + +Version added: 1.0.0 + +.. contents:: + :local: + :depth: 1 + + +Synopsis +-------- +- Queries the public ``/info`` endpoint (HTTP GET) which requires no authentication and returns the VyOS version, hostname, and a welcome banner. + + + +Requirements +------------ +The below requirements are needed on the host that executes this module. + +- VyOS 1.3+ + + +Parameters +---------- + +.. raw:: html + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
ParameterChoices/DefaultsComments
+
+ api_key + +
+ string +
+ 		+ +
API key. Not required for this module (the /info endpoint is public) but kept in the spec for consistency with other modules in this collection.
+
+
+ hostname + +
+ string + / required +
+ 		+ +
IP address or FQDN of the VyOS device.
+
+
+ port + +
+ integer +
+ 		+ Default:
443
+ 		+
HTTPS port for the REST API.
+
+
+ timeout + +
+ integer +
+ 		+ Default:
10
+ 		+
Request timeout in seconds.
+
+
+ verify_ssl + +
+ boolean +
+ 		+
    Choices: +
  • no ←
    • +
  • yes
    • +
+ 		+
Validate the device's TLS certificate.
+
+
+ + + + + + + +Return Values +------------- +Common return values are documented `here `_, the following are the fields unique to this module: + +.. raw:: html + + + + + + + + + + + + + + + + + + + + + + + + + + + +
KeyReturnedDescription
+
+ banner + +
+ string +
+ 		success +
Welcome banner text.
+
+
Sample:
+
Welcome to VyOS
+
+
+ hostname + +
+ string +
+ 		success +
System hostname.
+
+
Sample:
+
vyos-router
+
+
+ info + +
+ dictionary +
+ 		success +
Full info dict as returned by the device.
+
+
+
+ version + +
+ string +
+ 		success +
VyOS version string.
+
+
Sample:
+
1.4-rolling-202401010000
+
+

+ + +Status +------ + + +Authors +~~~~~~~ + +- VyOS Community (@vyos) diff --git a/docs/vyos.rest.vyos_interfaces_module.rst b/docs/vyos.rest.vyos_interfaces_module.rst new file mode 100644 index 0000000..fbaca26 --- /dev/null +++ b/docs/vyos.rest.vyos_interfaces_module.rst @@ -0,0 +1,452 @@ +.. _vyos.rest.vyos_interfaces_module: + + +************************* +vyos.rest.vyos_interfaces +************************* + +**Manage interface attributes on a VyOS device via the REST API.** + + +Version added: 1.0.0 + +.. contents:: + :local: + :depth: 1 + + +Synopsis +-------- +- Manages interface base attributes (description, MTU, enabled state, VIFs, duplex, speed) on VyOS devices using the HTTPS REST API. +- Mirrors ``vyos.vyos.vyos_interfaces`` but uses HTTP API. +- Supports Ethernet, Bonding, VXLAN, Loopback, and Virtual Tunnel interfaces. + + + +Requirements +------------ +The below requirements are needed on the host that executes this module. + +- VyOS 1.3+ + + +Parameters +---------- + +.. raw:: html + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
ParameterChoices/DefaultsComments
+
+ api_key + +
+ string + / required +
+ 		+ +
API key configured on the device.
+
+
+ config + +
+ list + / elements=dictionary +
+ 		+ +
List of interface configurations.
+
+
+ description + +
+ string +
+ 		+ +
Interface description.
+
+
+ duplex + +
+ string +
+ 		+
    Choices: +
  • auto
    • +
  • full
    • +
  • half
    • +
+ 		+
Duplex mode. Only for Ethernet interfaces.
+
+
+ enabled + +
+ boolean +
+ 		+
    Choices: +
  • no
    • +
  • yes ←
    • +
+ 		+
Administrative state. true = up, false = admin-down.
+
+
+ mtu + +
+ integer +
+ 		+ +
MTU in bytes. Applicable for Ethernet, Bonding, VXLAN, VTI.
+
+
+ name + +
+ string + / required +
+ 		+ +
Full interface name (e.g. eth0, bond0, vti1, vxlan2).
+
+
+ speed + +
+ string +
+ 		+ +
Link speed. Only for Ethernet interfaces.
+
+
+ vifs + +
+ list + / elements=dictionary +
+ 		+ +
List of VLAN sub-interface configurations.
+
+
+ description + +
+ string +
+ 		+ +
VIF description.
+
+
+ enabled + +
+ boolean +
+ 		+
    Choices: +
  • no
    • +
  • yes ←
    • +
+ 		+
Administrative state of the VIF.
+
+
+ vlan_id + +
+ integer + / required +
+ 		+ +
802.1Q VLAN ID.
+
+
+ hostname + +
+ string + / required +
+ 		+ +
IP address or FQDN of the VyOS device.
+
+
+ port + +
+ integer +
+ 		+ Default:
443
+ 		+
HTTPS port for the REST API.
+
+
+ state + +
+ string +
+ 		+
    Choices: +
  • merged ←
    • +
  • replaced
    • +
  • overridden
    • +
  • deleted
    • +
  • gathered
    • +
+ 		+
{'merged': 'Merge the provided config with existing interface config.'}
+
{'replaced': 'Replace per-interface config with provided values.'}
+
{'overridden': 'Override all interface config with provided values.'}
+
{'deleted': 'Delete interface config for listed interfaces (or all).'}
+
{'gathered': 'Read current interface config from device.'}
+
+
+ timeout + +
+ integer +
+ 		+ Default:
30
+ 		+
Request timeout in seconds.
+
+
+ verify_ssl + +
+ boolean +
+ 		+
    Choices: +
  • no ←
    • +
  • yes
    • +
+ 		+
Validate the device's TLS certificate.
+
+
+ + + +See Also +-------- + +.. seealso:: + + :ref:`vyos.vyos.vyos_interfaces_module` + The official documentation on the **vyos.vyos.vyos_interfaces** module. + :ref:`vyos.rest.vyos_l3_interfaces_module` + The official documentation on the **vyos.rest.vyos_l3_interfaces** module. + + + + + +Return Values +------------- +Common return values are documented `here `_, the following are the fields unique to this module: + +.. raw:: html + + + + + + + + + + + + + + + + + + + + + + + + + + + +
KeyReturnedDescription
+
+ after + +
+ list +
+ 		when changed +
Interface configuration after the module ran.
+
+
+
+ before + +
+ list +
+ 		always +
Interface configuration before the module ran.
+
+
+
+ commands + +
+ list +
+ 		always +
REST API set/delete commands issued.
+
+
+
+ gathered + +
+ list +
+ 		when state is gathered +
Interface config read from device (state=gathered).
+
+
+

+ + +Status +------ + + +Authors +~~~~~~~ + +- VyOS Community (@vyos) diff --git a/docs/vyos.rest.vyos_l3_interfaces_module.rst b/docs/vyos.rest.vyos_l3_interfaces_module.rst new file mode 100644 index 0000000..ffc50ca --- /dev/null +++ b/docs/vyos.rest.vyos_l3_interfaces_module.rst @@ -0,0 +1,470 @@ +.. _vyos.rest.vyos_l3_interfaces_module: + + +**************************** +vyos.rest.vyos_l3_interfaces +**************************** + +**Manage L3 interface attributes on VyOS via the REST API.** + + +Version added: 1.0.0 + +.. contents:: + :local: + :depth: 1 + + +Synopsis +-------- +- Manages IPv4 and IPv6 addresses on VyOS interfaces via the HTTPS REST API. +- Mirrors ``vyos.vyos.vyos_l3_interfaces`` but uses the HTTP API. + + + +Requirements +------------ +The below requirements are needed on the host that executes this module. + +- VyOS 1.3+ + + +Parameters +---------- + +.. raw:: html + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
ParameterChoices/DefaultsComments
+
+ api_key + +
+ string + / required +
+ 		+ +
API key configured on the device.
+
+
+ config + +
+ list + / elements=dictionary +
+ 		+ +
List of L3 interface configurations.
+
+
+ ipv4 + +
+ list + / elements=dictionary +
+ 		+ +
List of IPv4 address assignments.
+
+
+ address + +
+ string + / required +
+ 		+ +
IPv4 address in CIDR notation or dhcp.
+
+
+ ipv6 + +
+ list + / elements=dictionary +
+ 		+ +
List of IPv6 address assignments.
+
+
+ address + +
+ string + / required +
+ 		+ +
IPv6 address in CIDR notation or dhcpv6 or autoconf.
+
+
+ name + +
+ string + / required +
+ 		+ +
Full interface name (e.g. eth0, eth1).
+
+
+ vifs + +
+ list + / elements=dictionary +
+ 		+ +
VLAN sub-interface L3 settings.
+
+
+ ipv4 + +
+ list + / elements=dictionary +
+ 		+ +
IPv4 addresses for this VIF.
+
+
+ address + +
+ string + / required +
+ 		+ +
+
+ ipv6 + +
+ list + / elements=dictionary +
+ 		+ +
IPv6 addresses for this VIF.
+
+
+ address + +
+ string + / required +
+ 		+ +
+
+ vlan_id + +
+ integer + / required +
+ 		+ +
802.1Q VLAN ID.
+
+
+ hostname + +
+ string + / required +
+ 		+ +
IP address or FQDN of the VyOS device.
+
+
+ port + +
+ integer +
+ 		+ Default:
443
+ 		+
HTTPS port for the REST API.
+
+
+ state + +
+ string +
+ 		+
    Choices: +
  • merged ←
    • +
  • replaced
    • +
  • overridden
    • +
  • deleted
    • +
  • gathered
    • +
+ 		+
{'merged': 'Add addresses to the interface (preserve existing).'}
+
{'replaced': 'Replace all addresses on each listed interface.'}
+
{'overridden': 'Replace all addresses on all interfaces.'}
+
{'deleted': 'Remove all addresses from listed (or all) interfaces.'}
+
{'gathered': 'Read L3 config from device without changes.'}
+
+
+ timeout + +
+ integer +
+ 		+ Default:
30
+ 		+
Request timeout in seconds.
+
+
+ verify_ssl + +
+ boolean +
+ 		+
    Choices: +
  • no ←
    • +
  • yes
    • +
+ 		+
Validate the device's TLS certificate.
+
+
+ + + +See Also +-------- + +.. seealso:: + + :ref:`vyos.vyos.vyos_l3_interfaces_module` + The official documentation on the **vyos.vyos.vyos_l3_interfaces** module. + :ref:`vyos.rest.vyos_interfaces_module` + The official documentation on the **vyos.rest.vyos_interfaces** module. + + + + + +Return Values +------------- +Common return values are documented `here `_, the following are the fields unique to this module: + +.. raw:: html + + + + + + + + + + + + + + + + + + + + + + + + + + + +
KeyReturnedDescription
+
+ after + +
+ list +
+ 		when changed +
L3 interface config after the module ran.
+
+
+
+ before + +
+ list +
+ 		always +
L3 interface config before the module ran.
+
+
+
+ commands + +
+ list +
+ 		always +
set/delete commands issued.
+
+
+
+ gathered + +
+ list +
+ 		when state is gathered +
L3 config read from device (state=gathered).
+
+
+

+ + +Status +------ + + +Authors +~~~~~~~ + +- VyOS Community (@vyos) diff --git a/docs/vyos.rest.vyos_lag_interfaces_module.rst b/docs/vyos.rest.vyos_lag_interfaces_module.rst new file mode 100644 index 0000000..39edaa1 --- /dev/null +++ b/docs/vyos.rest.vyos_lag_interfaces_module.rst @@ -0,0 +1,393 @@ +.. _vyos.rest.vyos_lag_interfaces_module: + + +***************************** +vyos.rest.vyos_lag_interfaces +***************************** + +**LAG/bonding interfaces resource module via REST API.** + + +Version added: 1.0.0 + +.. contents:: + :local: + :depth: 1 + + +Synopsis +-------- +- Manages Link Aggregation Group (LAG/bond) interfaces on VyOS via REST API. + + + + +Parameters +---------- + +.. raw:: html + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
ParameterChoices/DefaultsComments
+
+ api_key + +
+ string + / required +
+ 		+ +
+
+ config + +
+ list + / elements=dictionary +
+ 		+ +
List of LAG interface configurations.
+
+
+ arp_monitor + +
+ dictionary +
+ 		+ +
ARP monitoring settings.
+
+
+ interval + +
+ integer +
+ 		+ +
Monitoring interval in ms.
+
+
+ target + +
+ list + / elements=string +
+ 		+ +
Target IP addresses.
+
+
+ hash_policy + +
+ string +
+ 		+
    Choices: +
  • layer2
    • +
  • layer2+3
    • +
  • layer3+4
    • +
+ 		+
Transmit hash policy.
+
+
+ members + +
+ list + / elements=dictionary +
+ 		+ +
Member interfaces.
+
+
+ member + +
+ string +
+ 		+ +
Interface name.
+
+
+ mode + +
+ string +
+ 		+
    Choices: +
  • 802.3ad
    • +
  • active-backup
    • +
  • broadcast
    • +
  • round-robin
    • +
  • transmit-load-balance
    • +
  • adaptive-load-balance
    • +
  • xor-hash
    • +
+ 		+
Bonding mode.
+
+
+ name + +
+ string + / required +
+ 		+ +
Bond interface name (e.g. bond0).
+
+
+ primary + +
+ string +
+ 		+ +
Primary interface name.
+
+
+ hostname + +
+ string + / required +
+ 		+ +
+
+ port + +
+ integer +
+ 		+ Default:
443
+ 		+
+
+ state + +
+ string +
+ 		+
    Choices: +
  • merged ←
    • +
  • replaced
    • +
  • overridden
    • +
  • deleted
    • +
  • gathered
    • +
+ 		+
Desired state.
+
+
+ timeout + +
+ integer +
+ 		+ Default:
30
+ 		+
+
+ verify_ssl + +
+ boolean +
+ 		+
    Choices: +
  • no ←
    • +
  • yes
    • +
+ 		+
+
+ + + + + + + +Return Values +------------- +Common return values are documented `here `_, the following are the fields unique to this module: + +.. raw:: html + + + + + + + + + + + + + + + + + + + + + + +
KeyReturnedDescription
+
+ after + +
+ list +
+ 		when changed +
+
+
+ before + +
+ list +
+ 		always +
+
+
+ commands + +
+ list +
+ 		always +
+
+

+ + +Status +------ + + +Authors +~~~~~~~ + +- VyOS Community (@vyos) diff --git a/docs/vyos.rest.vyos_lldp_global_module.rst b/docs/vyos.rest.vyos_lldp_global_module.rst new file mode 100644 index 0000000..0f24668 --- /dev/null +++ b/docs/vyos.rest.vyos_lldp_global_module.rst @@ -0,0 +1,244 @@ +.. _vyos.rest.vyos_lldp_global_module: + + +************************** +vyos.rest.vyos_lldp_global +************************** + +**Manage LLDP global configuration on VyOS via REST API.** + + +Version added: 1.0.0 + +.. contents:: + :local: + :depth: 1 + + +Synopsis +-------- +- Manage LLDP global configuration on VyOS via REST API. + + + + +Parameters +---------- + +.. raw:: html + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
ParameterChoices/DefaultsComments
+
+ config + +
+ dictionary +
+ 		+ +
+
+ addresses + +
+ list + / elements=string +
+ 		+ +
+
+ enable + +
+ boolean +
+ 		+
    Choices: +
  • no
    • +
  • yes
    • +
+ 		+
+
+ legacy_protocols + +
+ list + / elements=string +
+ 		+
    Choices: +
  • cdp
    • +
  • edp
    • +
  • fdp
    • +
  • sonmp
    • +
+ 		+
+
+ snmp + +
+ string +
+ 		+ +
enable or disable.
+
+
+ state + +
+ string +
+ 		+
    Choices: +
  • merged ←
    • +
  • replaced
    • +
  • deleted
    • +
  • gathered
    • +
+ 		+
+
+ + + + +Examples +-------- + +.. code-block:: yaml + + - vyos.rest.vyos_lldp_global: + config: + enable: true + addresses: [192.0.2.17] + snmp: enable + legacy_protocols: [cdp, fdp] + state: merged + + + +Return Values +------------- +Common return values are documented `here `_, the following are the fields unique to this module: + +.. raw:: html + + + + + + + + + + + + + + + + + + + + + + + + + + + +
KeyReturnedDescription
+
+ after + +
+ dictionary +
+ 		when changed +
+
+
+ before + +
+ dictionary +
+ 		always +
+
+
+ commands + +
+ list +
+ 		always +
+
+
+ gathered + +
+ dictionary +
+ 		when state is gathered +
+
+

+ + +Status +------ + + +Authors +~~~~~~~ + +- VyOS Community (@vyos) diff --git a/docs/vyos.rest.vyos_lldp_interfaces_module.rst b/docs/vyos.rest.vyos_lldp_interfaces_module.rst new file mode 100644 index 0000000..59d25d1 --- /dev/null +++ b/docs/vyos.rest.vyos_lldp_interfaces_module.rst @@ -0,0 +1,389 @@ +.. _vyos.rest.vyos_lldp_interfaces_module: + + +****************************** +vyos.rest.vyos_lldp_interfaces +****************************** + +**LLDP interfaces resource module via REST API.** + + +Version added: 1.0.0 + +.. contents:: + :local: + :depth: 1 + + +Synopsis +-------- +- Manages per-interface LLDP settings (enable/disable, location) on VyOS via the HTTPS REST API. + + + + +Parameters +---------- + +.. raw:: html + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
ParameterChoices/DefaultsComments
+
+ api_key + +
+ string + / required +
+ 		+ +
+
+ config + +
+ list + / elements=dictionary +
+ 		+ +
List of LLDP interface configurations.
+
+
+ enable + +
+ boolean +
+ 		+
    Choices: +
  • no
    • +
  • yes ←
    • +
+ 		+
Enable LLDP on this interface (default true).
+
+
+ location + +
+ dictionary +
+ 		+ +
LLDP-MED location data.
+
+
+ coordinate_based + +
+ dictionary +
+ 		+ +
+
+ altitude + +
+ integer +
+ 		+ +
+
+ datum + +
+ string +
+ 		+
    Choices: +
  • WGS84
    • +
  • NAD83
    • +
  • MLLW
    • +
+ 		+
+
+ latitude + +
+ string + / required +
+ 		+ +
+
+ longitude + +
+ string + / required +
+ 		+ +
+
+ elin + +
+ string +
+ 		+ +
Emergency ELIN number (10-25 digits).
+
+
+ name + +
+ string + / required +
+ 		+ +
Interface name.
+
+
+ hostname + +
+ string + / required +
+ 		+ +
+
+ port + +
+ integer +
+ 		+ Default:
443
+ 		+
+
+ state + +
+ string +
+ 		+
    Choices: +
  • merged ←
    • +
  • replaced
    • +
  • overridden
    • +
  • deleted
    • +
  • gathered
    • +
+ 		+
+
+ timeout + +
+ integer +
+ 		+ Default:
30
+ 		+
+
+ verify_ssl + +
+ boolean +
+ 		+
    Choices: +
  • no ←
    • +
  • yes
    • +
+ 		+
+
+ + + + + + + +Return Values +------------- +Common return values are documented `here `_, the following are the fields unique to this module: + +.. raw:: html + + + + + + + + + + + + + + + + + + + + + + +
KeyReturnedDescription
+
+ after + +
+ list +
+ 		when changed +
+
+
+ before + +
+ list +
+ 		always +
+
+
+ commands + +
+ list +
+ 		always +
+
+

+ + +Status +------ + + +Authors +~~~~~~~ + +- VyOS Community (@vyos) diff --git a/docs/vyos.rest.vyos_ntp_global_module.rst b/docs/vyos.rest.vyos_ntp_global_module.rst new file mode 100644 index 0000000..9643d5a --- /dev/null +++ b/docs/vyos.rest.vyos_ntp_global_module.rst @@ -0,0 +1,370 @@ +.. _vyos.rest.vyos_ntp_global_module: + + +************************* +vyos.rest.vyos_ntp_global +************************* + +**Manage NTP configuration on VyOS devices using REST API** + + +Version added: 1.0.0 + +.. contents:: + :local: + :depth: 1 + + +Synopsis +-------- +- Manages NTP server, allow-client, and listen-address configuration on VyOS devices via the REST API. +- Supports idempotent operation using structured data. +- Uses REST API (``connection=httpapi``) instead of CLI. +- Targets VyOS 1.4+ where NTP is managed by chronyd under ``service ntp``. + + + + +Parameters +---------- + +.. raw:: html + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
ParameterChoices/DefaultsComments
+
+ config + +
+ dictionary +
+ 		+ +
NTP configuration.
+
+
+ allow_clients + +
+ list + / elements=string +
+ 		+ +
List of client networks or addresses allowed to query this NTP server.
+
Maps to service ntp allow-client address on the device.
+
+
+ listen_addresses + +
+ list + / elements=string +
+ 		+ +
Local IP addresses the NTP service should listen on.
+
Maps to service ntp listen-address on the device.
+
+
+ servers + +
+ list + / elements=dictionary +
+ 		+ +
List of upstream NTP servers to synchronise from.
+
+
+ options + +
+ list + / elements=string +
+ 		+
    Choices: +
  • dynamic
    • +
  • noselect
    • +
  • pool
    • +
  • preempt
    • +
  • prefer
    • +
  • nts
    • +
  • ptp
    • +
  • interleave
    • +
+ 		+
Per-server options.
+
+
+ server + +
+ string + / required +
+ 		+ +
Server hostname or IP address.
+
+
+ running_config + +
+ string +
+ 		+ +
Used only with state parsed.
+
Provide the output of show configuration commands | grep ntp.
+
+
+ state + +
+ string +
+ 		+
    Choices: +
  • merged ←
    • +
  • replaced
    • +
  • overridden
    • +
  • deleted
    • +
  • gathered
    • +
  • rendered
    • +
  • parsed
    • +
+ 		+
The desired state of the NTP configuration.
+
+
+ + + + +Examples +-------- + +.. code-block:: yaml + + - name: Gather current NTP configuration + vyos.rest.vyos_ntp_global: + state: gathered + + - name: Merge NTP configuration + vyos.rest.vyos_ntp_global: + config: + allow_clients: + - 10.6.6.0/24 + listen_addresses: + - 10.1.3.1 + servers: + - server: 203.0.113.0 + options: + - prefer + state: merged + + - name: Replace NTP configuration + vyos.rest.vyos_ntp_global: + config: + allow_clients: + - 10.6.6.0/24 + listen_addresses: + - 10.1.3.1 + servers: + - server: 203.0.113.0 + options: + - prefer + state: replaced + + - name: Delete all managed NTP configuration + vyos.rest.vyos_ntp_global: + state: deleted + + + +Return Values +------------- +Common return values are documented `here `_, the following are the fields unique to this module: + +.. raw:: html + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
KeyReturnedDescription
+
+ after + +
+ dictionary +
+ 		when changed +
NTP configuration after this module ran.
+
+
+
+ before + +
+ dictionary +
+ 		when state is merged, replaced, overridden or deleted +
NTP configuration before this module ran.
+
+
+
+ commands + +
+ list +
+ 		always +
List of API commands sent to the device.
+
+
+
+ gathered + +
+ dictionary +
+ 		when state is gathered +
Current NTP configuration as structured data.
+
+
+
+ parsed + +
+ dictionary +
+ 		when state is parsed +
Structured data parsed from running_config.
+
+
+
+ rendered + +
+ list +
+ 		when state is rendered +
CLI commands generated for the provided config (offline).
+
+
+
+ saved + +
+ boolean +
+ 		when changes are applied +
Whether the config was saved after changes.
+
+
+

+ + +Status +------ + + +Authors +~~~~~~~ + +- Varshitha Yataluru (@YVarshitha) diff --git a/docs/vyos.rest.vyos_ospf_interfaces_module.rst b/docs/vyos.rest.vyos_ospf_interfaces_module.rst new file mode 100644 index 0000000..7447c4e --- /dev/null +++ b/docs/vyos.rest.vyos_ospf_interfaces_module.rst @@ -0,0 +1,570 @@ +.. _vyos.rest.vyos_ospf_interfaces_module: + + +****************************** +vyos.rest.vyos_ospf_interfaces +****************************** + +**OSPF Interfaces Resource Module via REST API.** + + +Version added: 1.0.0 + +.. contents:: + :local: + :depth: 1 + + +Synopsis +-------- +- Manages per-interface OSPF parameters (cost, hello/dead timers, authentication, passive mode, etc.) for both OSPFv2 and OSPFv3 via the VyOS HTTPS REST API. + + + + +Parameters +---------- + +.. raw:: html + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
ParameterChoices/DefaultsComments
+
+ api_key + +
+ string + / required +
+ 		+ +
+
+ config + +
+ list + / elements=dictionary +
+ 		+ +
List of OSPF interface configurations.
+
+
+ address_family + +
+ list + / elements=dictionary +
+ 		+ +
OSPF settings per address family.
+
+
+ afi + +
+ string + / required +
+ 		+
    Choices: +
  • ipv4
    • +
  • ipv6
    • +
+ 		+
Address family (ipv4=OSPFv2, ipv6=OSPFv3).
+
+
+ authentication + +
+ dictionary +
+ 		+ +
+
+ md5_key + +
+ dictionary +
+ 		+ +
+
+ key + +
+ string +
+ 		+ +
+
+ key_id + +
+ integer +
+ 		+ +
+
+ plaintext_password + +
+ string +
+ 		+ +
+
+ bandwidth + +
+ integer +
+ 		+ +
+
+ cost + +
+ integer +
+ 		+ +
+
+ dead_interval + +
+ integer +
+ 		+ +
+
+ hello_interval + +
+ integer +
+ 		+ +
+
+ ifmtu + +
+ integer +
+ 		+ +
+
+ instance + +
+ string +
+ 		+ +
+
+ mtu_ignore + +
+ boolean +
+ 		+
    Choices: +
  • no
    • +
  • yes
    • +
+ 		+
+
+ network + +
+ string +
+ 		+ +
+
+ passive + +
+ boolean +
+ 		+
    Choices: +
  • no
    • +
  • yes
    • +
+ 		+
+
+ priority + +
+ integer +
+ 		+ +
+
+ retransmit_interval + +
+ integer +
+ 		+ +
+
+ transmit_delay + +
+ integer +
+ 		+ +
+
+ name + +
+ string +
+ 		+ +
Interface name.
+
+
+ hostname + +
+ string + / required +
+ 		+ +
+
+ port + +
+ integer +
+ 		+ Default:
443
+ 		+
+
+ state + +
+ string +
+ 		+
    Choices: +
  • merged ←
    • +
  • replaced
    • +
  • overridden
    • +
  • deleted
    • +
  • gathered
    • +
+ 		+
+
+ timeout + +
+ integer +
+ 		+ Default:
30
+ 		+
+
+ verify_ssl + +
+ boolean +
+ 		+
    Choices: +
  • no ←
    • +
  • yes
    • +
+ 		+
+
+ + + + + + + +Return Values +------------- +Common return values are documented `here `_, the following are the fields unique to this module: + +.. raw:: html + + + + + + + + + + + + + + + + + + + + + + +
KeyReturnedDescription
+
+ after + +
+ list +
+ 		when changed +
+
+
+ before + +
+ list +
+ 		always +
+
+
+ commands + +
+ list +
+ 		always +
+
+

+ + +Status +------ + + +Authors +~~~~~~~ + +- VyOS Community (@vyos) diff --git a/docs/vyos.rest.vyos_ospfv2_module.rst b/docs/vyos.rest.vyos_ospfv2_module.rst new file mode 100644 index 0000000..f487ac7 --- /dev/null +++ b/docs/vyos.rest.vyos_ospfv2_module.rst @@ -0,0 +1,1202 @@ +.. _vyos.rest.vyos_ospfv2_module: + + +********************* +vyos.rest.vyos_ospfv2 +********************* + +**OSPFv2 resource module via REST API.** + + +Version added: 1.0.0 + +.. contents:: + :local: + :depth: 1 + + +Synopsis +-------- +- Manages OSPFv2 (OSPF for IPv4) configuration on VyOS via HTTPS REST API. + + + + +Parameters +---------- + +.. raw:: html + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
ParameterChoices/DefaultsComments
+
+ api_key + +
+ string + / required +
+ 		+ +
+
+ config + +
+ dictionary +
+ 		+ +
OSPFv2 configuration.
+
+
+ areas + +
+ list + / elements=dictionary +
+ 		+ +
+
+ area_id + +
+ string +
+ 		+ +
+
+ area_type + +
+ dictionary +
+ 		+ +
+
+ normal + +
+ boolean +
+ 		+
    Choices: +
  • no
    • +
  • yes
    • +
+ 		+
+
+ nssa + +
+ dictionary +
+ 		+ +
+
+ default_cost + +
+ integer +
+ 		+ +
+
+ no_summary + +
+ boolean +
+ 		+
    Choices: +
  • no
    • +
  • yes
    • +
+ 		+
+
+ set + +
+ boolean +
+ 		+
    Choices: +
  • no
    • +
  • yes
    • +
+ 		+
+
+ translate + +
+ string +
+ 		+
    Choices: +
  • always
    • +
  • candidate
    • +
  • never
    • +
+ 		+
+
+ stub + +
+ dictionary +
+ 		+ +
+
+ default_cost + +
+ integer +
+ 		+ +
+
+ no_summary + +
+ boolean +
+ 		+
    Choices: +
  • no
    • +
  • yes
    • +
+ 		+
+
+ set + +
+ boolean +
+ 		+
    Choices: +
  • no
    • +
  • yes
    • +
+ 		+
+
+ authentication + +
+ string +
+ 		+
    Choices: +
  • plaintext-password
    • +
  • md5
    • +
+ 		+
+
+ network + +
+ list + / elements=dictionary +
+ 		+ +
+
+ address + +
+ string +
+ 		+ +
+
+ range + +
+ list + / elements=dictionary +
+ 		+ +
+
+ address + +
+ string +
+ 		+ +
+
+ cost + +
+ integer +
+ 		+ +
+
+ not_advertise + +
+ boolean +
+ 		+
    Choices: +
  • no
    • +
  • yes
    • +
+ 		+
+
+ substitute + +
+ string +
+ 		+ +
+
+ shortcut + +
+ string +
+ 		+
    Choices: +
  • default
    • +
  • disable
    • +
  • enable
    • +
+ 		+
+
+ auto_cost + +
+ dictionary +
+ 		+ +
+
+ reference_bandwidth + +
+ integer +
+ 		+ +
+
+ default_information + +
+ dictionary +
+ 		+ +
+
+ originate + +
+ dictionary +
+ 		+ +
+
+ always + +
+ boolean +
+ 		+
    Choices: +
  • no
    • +
  • yes
    • +
+ 		+
+
+ metric + +
+ integer +
+ 		+ +
+
+ metric_type + +
+ integer +
+ 		+ +
+
+ route_map + +
+ string +
+ 		+ +
+
+ log_adjacency_changes + +
+ string +
+ 		+
    Choices: +
  • detail
    • +
+ 		+
+
+ max_metric + +
+ dictionary +
+ 		+ +
+
+ router_lsa + +
+ dictionary +
+ 		+ +
+
+ administrative + +
+ boolean +
+ 		+
    Choices: +
  • no
    • +
  • yes
    • +
+ 		+
+
+ on_shutdown + +
+ integer +
+ 		+ +
+
+ on_startup + +
+ integer +
+ 		+ +
+
+ mpls_te + +
+ dictionary +
+ 		+ +
+
+ enabled + +
+ boolean +
+ 		+
    Choices: +
  • no
    • +
  • yes
    • +
+ 		+
+
+ router_address + +
+ string +
+ 		+ +
+
+ neighbor + +
+ list + / elements=dictionary +
+ 		+ +
+
+ neighbor_id + +
+ string +
+ 		+ +
+
+ poll_interval + +
+ integer +
+ 		+ +
+
+ priority + +
+ integer +
+ 		+ +
+
+ parameters + +
+ dictionary +
+ 		+ +
+
+ abr_type + +
+ string +
+ 		+
    Choices: +
  • cisco
    • +
  • ibm
    • +
  • shortcut
    • +
  • standard
    • +
+ 		+
+
+ opaque_lsa + +
+ boolean +
+ 		+
    Choices: +
  • no
    • +
  • yes
    • +
+ 		+
+
+ rfc1583_compatibility + +
+ boolean +
+ 		+
    Choices: +
  • no
    • +
  • yes
    • +
+ 		+
+
+ router_id + +
+ string +
+ 		+ +
+
+ passive_interface + +
+ list + / elements=string +
+ 		+ +
+
+ redistribute + +
+ list + / elements=dictionary +
+ 		+ +
+
+ metric + +
+ integer +
+ 		+ +
+
+ metric_type + +
+ integer +
+ 		+ +
+
+ route_map + +
+ string +
+ 		+ +
+
+ route_type + +
+ string +
+ 		+
    Choices: +
  • bgp
    • +
  • connected
    • +
  • kernel
    • +
  • rip
    • +
  • static
    • +
+ 		+
+
+ hostname + +
+ string + / required +
+ 		+ +
+
+ port + +
+ integer +
+ 		+ Default:
443
+ 		+
+
+ state + +
+ string +
+ 		+
    Choices: +
  • merged ←
    • +
  • replaced
    • +
  • deleted
    • +
  • gathered
    • +
+ 		+
+
+ timeout + +
+ integer +
+ 		+ Default:
30
+ 		+
+
+ verify_ssl + +
+ boolean +
+ 		+
    Choices: +
  • no ←
    • +
  • yes
    • +
+ 		+
+
+ + + + + + + +Return Values +------------- +Common return values are documented `here `_, the following are the fields unique to this module: + +.. raw:: html + + + + + + + + + + + + + + + + + + + + + + +
KeyReturnedDescription
+
+ after + +
+ dictionary +
+ 		when changed +
+
+
+ before + +
+ dictionary +
+ 		always +
+
+
+ commands + +
+ list +
+ 		always +
+
+

+ + +Status +------ + + +Authors +~~~~~~~ + +- VyOS Community (@vyos) diff --git a/docs/vyos.rest.vyos_ospfv3_module.rst b/docs/vyos.rest.vyos_ospfv3_module.rst new file mode 100644 index 0000000..4b78c59 --- /dev/null +++ b/docs/vyos.rest.vyos_ospfv3_module.rst @@ -0,0 +1,490 @@ +.. _vyos.rest.vyos_ospfv3_module: + + +********************* +vyos.rest.vyos_ospfv3 +********************* + +**OSPFv3 resource module via REST API.** + + +Version added: 1.0.0 + +.. contents:: + :local: + :depth: 1 + + +Synopsis +-------- +- Manages OSPFv3 (OSPF for IPv6) configuration on VyOS via HTTPS REST API. + + + + +Parameters +---------- + +.. raw:: html + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
ParameterChoices/DefaultsComments
+
+ api_key + +
+ string + / required +
+ 		+ +
+
+ config + +
+ dictionary +
+ 		+ +
OSPFv3 configuration.
+
+
+ areas + +
+ list + / elements=dictionary +
+ 		+ +
+
+ area_id + +
+ string +
+ 		+ +
+
+ export_list + +
+ string +
+ 		+ +
+
+ import_list + +
+ string +
+ 		+ +
+
+ interface + +
+ list + / elements=dictionary +
+ 		+ +
Interfaces in this area.
+
+
+ name + +
+ string +
+ 		+ +
+
+ range + +
+ list + / elements=dictionary +
+ 		+ +
+
+ address + +
+ string +
+ 		+ +
+
+ advertise + +
+ boolean +
+ 		+
    Choices: +
  • no
    • +
  • yes
    • +
+ 		+
+
+ not_advertise + +
+ boolean +
+ 		+
    Choices: +
  • no
    • +
  • yes
    • +
+ 		+
+
+ parameters + +
+ dictionary +
+ 		+ +
+
+ router_id + +
+ string +
+ 		+ +
+
+ redistribute + +
+ list + / elements=dictionary +
+ 		+ +
+
+ route_map + +
+ string +
+ 		+ +
+
+ route_type + +
+ string +
+ 		+
    Choices: +
  • bgp
    • +
  • connected
    • +
  • kernel
    • +
  • ripng
    • +
  • static
    • +
+ 		+
+
+ hostname + +
+ string + / required +
+ 		+ +
+
+ port + +
+ integer +
+ 		+ Default:
443
+ 		+
+
+ state + +
+ string +
+ 		+
    Choices: +
  • merged ←
    • +
  • replaced
    • +
  • deleted
    • +
  • gathered
    • +
+ 		+
+
+ timeout + +
+ integer +
+ 		+ Default:
30
+ 		+
+
+ verify_ssl + +
+ boolean +
+ 		+
    Choices: +
  • no ←
    • +
  • yes
    • +
+ 		+
+
+ + + + + + + +Return Values +------------- +Common return values are documented `here `_, the following are the fields unique to this module: + +.. raw:: html + + + + + + + + + + + + + + + + + + + + + + +
KeyReturnedDescription
+
+ after + +
+ dictionary +
+ 		when changed +
+
+
+ before + +
+ dictionary +
+ 		always +
+
+
+ commands + +
+ list +
+ 		always +
+
+

+ + +Status +------ + + +Authors +~~~~~~~ + +- VyOS Community (@vyos) diff --git a/docs/vyos.rest.vyos_ping_module.rst b/docs/vyos.rest.vyos_ping_module.rst new file mode 100644 index 0000000..315a395 --- /dev/null +++ b/docs/vyos.rest.vyos_ping_module.rst @@ -0,0 +1,332 @@ +.. _vyos.rest.vyos_ping_module: + + +******************* +vyos.rest.vyos_ping +******************* + +**Test reachability using ping via VyOS REST API.** + + +Version added: 1.0.0 + +.. contents:: + :local: + :depth: 1 + + +Synopsis +-------- +- Sends an ICMP ping via the VyOS HTTPS REST API (/show endpoint) and checks reachability. Mirrors ``vyos.vyos.vyos_ping``. + + + + +Parameters +---------- + +.. raw:: html + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
ParameterChoices/DefaultsComments
+
+ api_key + +
+ string + / required +
+ 		+ +
+
+ count + +
+ integer +
+ 		+ Default:
5
+ 		+
Number of packets to send.
+
+
+ dest + +
+ string + / required +
+ 		+ +
Destination IP address or hostname.
+
+
+ hostname + +
+ string + / required +
+ 		+ +
+
+ interval + +
+ integer +
+ 		+ +
Interval between pings in seconds.
+
+
+ port + +
+ integer +
+ 		+ Default:
443
+ 		+
+
+ size + +
+ integer +
+ 		+ +
Packet size in bytes.
+
+
+ source + +
+ string +
+ 		+ +
Source interface or IP address.
+
+
+ state + +
+ string +
+ 		+
    Choices: +
  • present ←
    • +
  • absent
    • +
+ 		+
present = expect success; absent = expect failure.
+
+
+ timeout + +
+ integer +
+ 		+ Default:
30
+ 		+
+
+ ttl + +
+ integer +
+ 		+ +
Time-to-live value.
+
+
+ verify_ssl + +
+ boolean +
+ 		+
    Choices: +
  • no ←
    • +
  • yes
    • +
+ 		+
+
+ + + + + + + +Return Values +------------- +Common return values are documented `here `_, the following are the fields unique to this module: + +.. raw:: html + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
KeyReturnedDescription
+
+ commands + +
+ list +
+ 		always +
Ping command tokens sent to the API.
+
+
+
+ packet_loss + +
+ string +
+ 		always +
Packet loss percentage string.
+
+
+
+ packets_rx + +
+ integer +
+ 		always +
Packets received.
+
+
+
+ packets_tx + +
+ integer +
+ 		always +
Packets transmitted.
+
+
+
+ rtt + +
+ dictionary +
+ 		when available +
RTT statistics dict (min/avg/max/mdev).
+
+
+

+ + +Status +------ + + +Authors +~~~~~~~ + +- VyOS Community (@vyos) diff --git a/docs/vyos.rest.vyos_prefix_lists_module.rst b/docs/vyos.rest.vyos_prefix_lists_module.rst new file mode 100644 index 0000000..6e1d288 --- /dev/null +++ b/docs/vyos.rest.vyos_prefix_lists_module.rst @@ -0,0 +1,431 @@ +.. _vyos.rest.vyos_prefix_lists_module: + + +*************************** +vyos.rest.vyos_prefix_lists +*************************** + +**Prefix-Lists resource module via REST API.** + + +Version added: 1.0.0 + +.. contents:: + :local: + :depth: 1 + + +Synopsis +-------- +- Manages IPv4 and IPv6 prefix lists on VyOS via the HTTPS REST API. + + + + +Parameters +---------- + +.. raw:: html + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
ParameterChoices/DefaultsComments
+
+ api_key + +
+ string + / required +
+ 		+ +
+
+ config + +
+ list + / elements=dictionary +
+ 		+ +
List of prefix-list configurations.
+
+
+ afi + +
+ string + / required +
+ 		+
    Choices: +
  • ipv4
    • +
  • ipv6
    • +
+ 		+
Address family.
+
+
+ prefix_lists + +
+ list + / elements=dictionary +
+ 		+ +
Named prefix lists.
+
+
+ description + +
+ string +
+ 		+ +
Description.
+
+
+ entries + +
+ list + / elements=dictionary +
+ 		+ +
Prefix list rules.
+
+
+ action + +
+ string +
+ 		+
    Choices: +
  • permit
    • +
  • deny
    • +
+ 		+
permit or deny.
+
+
+ description + +
+ string +
+ 		+ +
+
+ ge + +
+ integer +
+ 		+ +
Minimum prefix length.
+
+
+ le + +
+ integer +
+ 		+ +
Maximum prefix length.
+
+
+ prefix + +
+ string +
+ 		+ +
Network prefix to match.
+
+
+ sequence + +
+ integer + / required +
+ 		+ +
Rule sequence number.
+
+
+ name + +
+ string + / required +
+ 		+ +
Prefix list name.
+
+
+ hostname + +
+ string + / required +
+ 		+ +
+
+ port + +
+ integer +
+ 		+ Default:
443
+ 		+
+
+ state + +
+ string +
+ 		+
    Choices: +
  • merged ←
    • +
  • replaced
    • +
  • overridden
    • +
  • deleted
    • +
  • gathered
    • +
+ 		+
+
+ timeout + +
+ integer +
+ 		+ Default:
30
+ 		+
+
+ verify_ssl + +
+ boolean +
+ 		+
    Choices: +
  • no ←
    • +
  • yes
    • +
+ 		+
+
+ + + + + + + +Return Values +------------- +Common return values are documented `here `_, the following are the fields unique to this module: + +.. raw:: html + + + + + + + + + + + + + + + + + + + + + + +
KeyReturnedDescription
+
+ after + +
+ list +
+ 		when changed +
+
+
+ before + +
+ list +
+ 		always +
+
+
+ commands + +
+ list +
+ 		always +
+
+

+ + +Status +------ + + +Authors +~~~~~~~ + +- VyOS Community (@vyos) diff --git a/docs/vyos.rest.vyos_reset_module.rst b/docs/vyos.rest.vyos_reset_module.rst new file mode 100644 index 0000000..46d4dee --- /dev/null +++ b/docs/vyos.rest.vyos_reset_module.rst @@ -0,0 +1,191 @@ +.. _vyos.rest.vyos_reset_module: + + +******************** +vyos.rest.vyos_reset +******************** + +**Execute reset commands on a VyOS device via REST API.** + + +Version added: 1.0.0 + +.. contents:: + :local: + :depth: 1 + + +Synopsis +-------- +- Sends a ``reset`` operational command to a VyOS device via the HTTPS REST API (``/reset`` endpoint). +- Useful for resetting BGP sessions, VPN tunnels, ARP caches, etc. + + + +Requirements +------------ +The below requirements are needed on the host that executes this module. + +- VyOS 1.3+ + + +Parameters +---------- + +.. raw:: html + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
ParameterChoices/DefaultsComments
+
+ api_key + +
+ string + / required +
+ 		+ +
API key configured on the device.
+
+
+ hostname + +
+ string + / required +
+ 		+ +
IP address or FQDN of the VyOS device.
+
+
+ path + +
+ list + / elements=string + / required +
+ 		+ +
Reset command path tokens.
+
E.g. ["ip", "bgp", "192.0.2.1"] to reset a BGP peer.
+
+
+ port + +
+ integer +
+ 		+ Default:
443
+ 		+
HTTPS port for the REST API.
+
+
+ timeout + +
+ integer +
+ 		+ Default:
30
+ 		+
Request timeout in seconds.
+
+
+ verify_ssl + +
+ boolean +
+ 		+
    Choices: +
  • no ←
    • +
  • yes
    • +
+ 		+
Validate the device's TLS certificate.
+
+
+ + + + + + + +Return Values +------------- +Common return values are documented `here `_, the following are the fields unique to this module: + +.. raw:: html + + + + + + + + + + + + +
KeyReturnedDescription
+
+ output + +
+ string +
+ 		success +
Text output from the reset command (usually empty on success).
+
+
+

+ + +Status +------ + + +Authors +~~~~~~~ + +- VyOS Community (@vyos) diff --git a/docs/vyos.rest.vyos_route_maps_module.rst b/docs/vyos.rest.vyos_route_maps_module.rst new file mode 100644 index 0000000..0f41805 --- /dev/null +++ b/docs/vyos.rest.vyos_route_maps_module.rst @@ -0,0 +1,932 @@ +.. _vyos.rest.vyos_route_maps_module: + + +************************* +vyos.rest.vyos_route_maps +************************* + +**Route Map resource module via REST API.** + + +Version added: 1.0.0 + +.. contents:: + :local: + :depth: 1 + + +Synopsis +-------- +- Manages route maps on VyOS via the HTTPS REST API. + + + + +Parameters +---------- + +.. raw:: html + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
ParameterChoices/DefaultsComments
+
+ api_key + +
+ string + / required +
+ 		+ +
+
+ config + +
+ list + / elements=dictionary +
+ 		+ +
List of route-map configurations.
+
+
+ entries + +
+ list + / elements=dictionary +
+ 		+ +
Route map rules.
+
+
+ action + +
+ string +
+ 		+
    Choices: +
  • permit
    • +
  • deny
    • +
+ 		+
permit or deny.
+
+
+ call + +
+ string +
+ 		+ +
Call another route map.
+
+
+ continue_sequence + +
+ integer +
+ 		+ +
Continue at a different sequence.
+
+
+ description + +
+ string +
+ 		+ +
+
+ match + +
+ dictionary +
+ 		+ +
Match conditions.
+
+
+ interface + +
+ string +
+ 		+ +
+
+ ip + +
+ dictionary +
+ 		+ +
+
+ nexthop_address + +
+ string +
+ 		+ +
+
+ nexthop_prefix_list + +
+ string +
+ 		+ +
+
+ ipv6 + +
+ dictionary +
+ 		+ +
+
+ nexthop_address + +
+ string +
+ 		+ +
+
+ metric + +
+ integer +
+ 		+ +
+
+ origin + +
+ string +
+ 		+ +
+
+ prefix_list + +
+ string +
+ 		+ +
+
+ prefix_list6 + +
+ string +
+ 		+ +
+
+ sequence + +
+ integer +
+ 		+ +
Rule number (1-65535).
+
+
+ set + +
+ dictionary +
+ 		+ +
Route parameters to set.
+
+
+ aggregator + +
+ dictionary +
+ 		+ +
+
+ as + +
+ string +
+ 		+ +
+
+ ip + +
+ string +
+ 		+ +
+
+ as_path_prepend + +
+ string +
+ 		+ +
+
+ atomic_aggregate + +
+ boolean +
+ 		+
    Choices: +
  • no
    • +
  • yes
    • +
+ 		+
+
+ bgp_extcommunity_rt + +
+ string +
+ 		+ +
+
+ community + +
+ dictionary +
+ 		+ +
+
+ value + +
+ string +
+ 		+ +
+
+ ip_next_hop + +
+ string +
+ 		+ +
+
+ ipv6_next_hop + +
+ dictionary +
+ 		+ +
+
+ ip_type + +
+ string +
+ 		+
    Choices: +
  • global
    • +
  • local
    • +
+ 		+
+
+ value + +
+ string +
+ 		+ +
+
+ large_community + +
+ string +
+ 		+ +
+
+ local_preference + +
+ integer +
+ 		+ +
+
+ metric + +
+ string +
+ 		+ +
+
+ metric_type + +
+ string +
+ 		+ +
+
+ origin + +
+ string +
+ 		+ +
+
+ originator_id + +
+ string +
+ 		+ +
+
+ src + +
+ string +
+ 		+ +
+
+ tag + +
+ string +
+ 		+ +
+
+ weight + +
+ integer +
+ 		+ +
+
+ route_map + +
+ string +
+ 		+ +
Route map name.
+
+
+ hostname + +
+ string + / required +
+ 		+ +
+
+ port + +
+ integer +
+ 		+ Default:
443
+ 		+
+
+ state + +
+ string +
+ 		+
    Choices: +
  • merged ←
    • +
  • replaced
    • +
  • overridden
    • +
  • deleted
    • +
  • gathered
    • +
+ 		+
+
+ timeout + +
+ integer +
+ 		+ Default:
30
+ 		+
+
+ verify_ssl + +
+ boolean +
+ 		+
    Choices: +
  • no ←
    • +
  • yes
    • +
+ 		+
+
+ + + + + + + +Return Values +------------- +Common return values are documented `here `_, the following are the fields unique to this module: + +.. raw:: html + + + + + + + + + + + + + + + + + + + + + + +
KeyReturnedDescription
+
+ after + +
+ list +
+ 		when changed +
+
+
+ before + +
+ list +
+ 		always +
+
+
+ commands + +
+ list +
+ 		always +
+
+

+ + +Status +------ + + +Authors +~~~~~~~ + +- VyOS Community (@vyos) diff --git a/docs/vyos.rest.vyos_show_module.rst b/docs/vyos.rest.vyos_show_module.rst new file mode 100644 index 0000000..29d7ee1 --- /dev/null +++ b/docs/vyos.rest.vyos_show_module.rst @@ -0,0 +1,210 @@ +.. _vyos.rest.vyos_show_module: + + +******************* +vyos.rest.vyos_show +******************* + +**Execute op-mode show commands on a VyOS device via REST API.** + + +Version added: 1.0.0 + +.. contents:: + :local: + :depth: 1 + + +Synopsis +-------- +- Sends a ``show`` operational-mode command to a VyOS device via the HTTPS REST API (``/show`` endpoint) and returns the text output. + + + +Requirements +------------ +The below requirements are needed on the host that executes this module. + +- VyOS 1.3+ + + +Parameters +---------- + +.. raw:: html + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
ParameterChoices/DefaultsComments
+
+ api_key + +
+ string + / required +
+ 		+ +
API key configured on the device.
+
+
+ hostname + +
+ string + / required +
+ 		+ +
IP address or FQDN of the VyOS device.
+
+
+ path + +
+ list + / elements=string + / required +
+ 		+ +
Operational-mode command tokens following show.
+
E.g. ["interfaces"] maps to show interfaces.
+
+
+ port + +
+ integer +
+ 		+ Default:
443
+ 		+
HTTPS port for the REST API.
+
+
+ timeout + +
+ integer +
+ 		+ Default:
30
+ 		+
Request timeout in seconds.
+
+
+ verify_ssl + +
+ boolean +
+ 		+
    Choices: +
  • no ←
    • +
  • yes
    • +
+ 		+
Validate the device's TLS certificate.
+
+
+ + +Notes +----- + +.. note:: + - This module never modifies device state. + + +See Also +-------- + +.. seealso:: + + :ref:`vyos.rest.vyos_configure_module` + The official documentation on the **vyos.rest.vyos_configure** module. + :ref:`vyos.rest.vyos_retrieve_module` + The official documentation on the **vyos.rest.vyos_retrieve** module. + + + + + +Return Values +------------- +Common return values are documented `here `_, the following are the fields unique to this module: + +.. raw:: html + + + + + + + + + + + + +
KeyReturnedDescription
+
+ output + +
+ string +
+ 		success +
Raw text output from the show command.
+
+
Sample:
+
Codes: S - State, L - Link, u - Up, D - Down, A - Admin Down + Interface IP Address S/L Description + eth0 10.0.0.1/24 u/u WAN
+
+

+ + +Status +------ + + +Authors +~~~~~~~ + +- VyOS Community (@vyos) diff --git a/docs/vyos.rest.vyos_snmp_server_module.rst b/docs/vyos.rest.vyos_snmp_server_module.rst new file mode 100644 index 0000000..dfa5259 --- /dev/null +++ b/docs/vyos.rest.vyos_snmp_server_module.rst @@ -0,0 +1,1211 @@ +.. _vyos.rest.vyos_snmp_server_module: + + +************************** +vyos.rest.vyos_snmp_server +************************** + +**Manage SNMP server configuration on VyOS devices using REST API** + + +Version added: 1.0.0 + +.. contents:: + :local: + :depth: 1 + + +Synopsis +-------- +- Manages SNMP server configuration on VyOS devices via the REST API. +- Supports communities, listen addresses, contact/location/description, trap target, and SNMPv3 (engine ID, groups, users, views). +- Uses REST API (``connection=httpapi``) instead of CLI. + + + + +Parameters +---------- + +.. raw:: html + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
ParameterChoices/DefaultsComments
+
+ config + +
+ dictionary +
+ 		+ +
SNMP server configuration.
+
+
+ communities + +
+ list + / elements=dictionary +
+ 		+ +
SNMP community configuration.
+
+
+ authorization_type + +
+ string +
+ 		+
    Choices: +
  • ro
    • +
  • rw
    • +
+ 		+
Authorization type.
+
+
+ clients + +
+ list + / elements=string +
+ 		+ +
IP addresses of SNMP clients allowed to contact the system.
+
+
+ name + +
+ string + / required +
+ 		+ +
Community name.
+
+
+ networks + +
+ list + / elements=string +
+ 		+ +
Subnets of SNMP clients allowed to contact the system.
+
+
+ contact + +
+ string +
+ 		+ +
Contact person for the system.
+
+
+ description + +
+ string +
+ 		+ +
System description.
+
+
+ listen_addresses + +
+ list + / elements=dictionary +
+ 		+ +
IP addresses to listen for incoming SNMP requests.
+
+
+ address + +
+ string + / required +
+ 		+ +
IP address.
+
+
+ port + +
+ integer +
+ 		+ +
UDP port (default 161).
+
+
+ location + +
+ string +
+ 		+ +
System location.
+
+
+ smux_peer + +
+ string +
+ 		+ +
Register a subtree for SMUX-based processing.
+
+
+ snmp_v3 + +
+ dictionary +
+ 		+ +
SNMPv3 configuration.
+
+
+ engine_id + +
+ string +
+ 		+ +
EngineID as a hex string.
+
+
+ groups + +
+ list + / elements=dictionary +
+ 		+ +
+
+ group + +
+ string + / required +
+ 		+ +
+
+ mode + +
+ string +
+ 		+
    Choices: +
  • ro
    • +
  • rw
    • +
+ 		+
+
+ seclevel + +
+ string +
+ 		+
    Choices: +
  • auth
    • +
  • priv
    • +
+ 		+
+
+ view + +
+ string +
+ 		+ +
+
+ trap_targets + +
+ list + / elements=dictionary +
+ 		+ +
+
+ address + +
+ string +
+ 		+ +
+
+ authentication + +
+ dictionary +
+ 		+ +
+
+ encrypted_key + +
+ string +
+ 		+ +
+
+ plaintext_key + +
+ string +
+ 		+ +
+
+ type + +
+ string +
+ 		+ +
+
+ port + +
+ integer +
+ 		+ +
+
+ privacy + +
+ dictionary +
+ 		+ +
+
+ encrypted_key + +
+ string +
+ 		+ +
+
+ plaintext_key + +
+ string +
+ 		+ +
+
+ type + +
+ string +
+ 		+ +
+
+ protocol + +
+ string +
+ 		+
    Choices: +
  • tcp
    • +
  • udp
    • +
+ 		+
+
+ type + +
+ string +
+ 		+
    Choices: +
  • inform
    • +
  • trap
    • +
+ 		+
+
+ users + +
+ list + / elements=dictionary +
+ 		+ +
+
+ authentication + +
+ dictionary +
+ 		+ +
+
+ encrypted_key + +
+ string +
+ 		+ +
Encrypted key (stored as encrypted-password on device).
+
+
+ plaintext_key + +
+ string +
+ 		+ +
Plaintext key (device encrypts it; recommended for 1.5+).
+
+
+ type + +
+ string +
+ 		+
    Choices: +
  • md5
    • +
  • sha
    • +
+ 		+
+
+ group + +
+ string +
+ 		+ +
+
+ mode + +
+ string +
+ 		+
    Choices: +
  • ro
    • +
  • rw
    • +
+ 		+
+
+ privacy + +
+ dictionary +
+ 		+ +
+
+ encrypted_key + +
+ string +
+ 		+ +
+
+ plaintext_key + +
+ string +
+ 		+ +
+
+ type + +
+ string +
+ 		+
    Choices: +
  • des
    • +
  • aes
    • +
+ 		+
+
+ tsm_key + +
+ string +
+ 		+ +
+
+ user + +
+ string + / required +
+ 		+ +
+
+ views + +
+ list + / elements=dictionary +
+ 		+ +
+
+ exclude + +
+ string +
+ 		+ +
+
+ mask + +
+ string +
+ 		+ +
+
+ oid + +
+ string +
+ 		+ +
+
+ view + +
+ string + / required +
+ 		+ +
+
+ trap_source + +
+ string +
+ 		+ +
SNMP trap source address.
+
+
+ trap_target + +
+ dictionary +
+ 		+ +
SNMP trap target.
+
+
+ address + +
+ string +
+ 		+ +
+
+ community + +
+ string +
+ 		+ +
+
+ port + +
+ integer +
+ 		+ +
+
+ state + +
+ string +
+ 		+
    Choices: +
  • merged ←
    • +
  • replaced
    • +
  • overridden
    • +
  • deleted
    • +
  • gathered
    • +
+ 		+
Desired state of SNMP configuration.
+
+
+ + + + +Examples +-------- + +.. code-block:: yaml + + - name: Merge SNMP configuration + vyos.rest.vyos_snmp_server: + config: + communities: + - name: switches + authorization_type: rw + - name: bridges + clients: + - 1.1.1.1 + - 12.1.1.10 + contact: admin2@ex.com + listen_addresses: + - address: 20.1.1.1 + - address: 100.1.2.1 + port: 33 + snmp_v3: + users: + - user: admin_user + authentication: + plaintext_key: abc1234567 + type: sha + privacy: + plaintext_key: abc1234567 + type: aes + state: merged + + - name: Delete all SNMP configuration + vyos.rest.vyos_snmp_server: + state: deleted + + - name: Gather current SNMP configuration + vyos.rest.vyos_snmp_server: + state: gathered + + + +Return Values +------------- +Common return values are documented `here `_, the following are the fields unique to this module: + +.. raw:: html + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
KeyReturnedDescription
+
+ after + +
+ dictionary +
+ 		when changed +
SNMP configuration after this module ran.
+
+
+
+ before + +
+ dictionary +
+ 		when state is merged, replaced, overridden or deleted +
SNMP configuration before this module ran.
+
+
+
+ commands + +
+ list +
+ 		always +
List of API command dicts sent to the device.
+
+
+
+ gathered + +
+ dictionary +
+ 		when state is gathered +
Current SNMP configuration as structured data.
+
+
+
+ saved + +
+ boolean +
+ 		when changes are applied +
Whether the config was saved after changes.
+
+
+

+ + +Status +------ + + +Authors +~~~~~~~ + +- your_name (@yourhandle) 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..f5cf5ee --- /dev/null +++ b/docs/vyos.rest.vyos_static_routes_module.rst @@ -0,0 +1,505 @@ +.. _vyos.rest.vyos_static_routes_module: + + +**************************** +vyos.rest.vyos_static_routes +**************************** + +**Manage static routes on VyOS via the 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. +- Mirrors ``vyos.vyos.vyos_static_routes`` but uses the HTTP API. + + + +Requirements +------------ +The below requirements are needed on the host that executes this module. + +- VyOS 1.3+ + + +Parameters +---------- + +.. raw:: html + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
ParameterChoices/DefaultsComments
+
+ api_key + +
+ string + / required +
+ 		+ +
API key configured on the device.
+
+
+ config + +
+ list + / elements=dictionary +
+ 		+ +
List of static route address-family configurations.
+
+
+ address_families + +
+ list + / elements=dictionary +
+ 		+ +
List of address family route groups.
+
+
+ afi + +
+ string + / required +
+ 		+
    Choices: +
  • ipv4
    • +
  • ipv6
    • +
+ 		+
Address family indicator.
+
+
+ routes + +
+ list + / elements=dictionary +
+ 		+ +
List of static route entries.
+
+
+ blackhole_config + +
+ dictionary +
+ 		+ +
Blackhole route configuration.
+
+
+ distance + +
+ integer +
+ 		+ +
Administrative distance (1-255).
+
+
+ type + +
+ string +
+ 		+ +
Blackhole type.
+
+
+ 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.
+
+
+ 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.
+
+
+ hostname + +
+ string + / required +
+ 		+ +
IP address or FQDN of the VyOS device.
+
+
+ port + +
+ integer +
+ 		+ Default:
443
+ 		+
HTTPS port for the REST API.
+
+
+ state + +
+ string +
+ 		+
    Choices: +
  • merged ←
    • +
  • replaced
    • +
  • overridden
    • +
  • deleted
    • +
  • gathered
    • +
+ 		+
{'merged': 'Add routes (preserve existing).'}
+
{'replaced': 'Replace routes for listed destinations.'}
+
{'overridden': 'Replace the entire static route table.'}
+
{'deleted': 'Remove listed (or all) static routes.'}
+
{'gathered': 'Read static routes from device.'}
+
+
+ timeout + +
+ integer +
+ 		+ Default:
30
+ 		+
Request timeout in seconds.
+
+
+ verify_ssl + +
+ boolean +
+ 		+
    Choices: +
  • no ←
    • +
  • yes
    • +
+ 		+
Validate the device's TLS certificate.
+
+
+ + + +See Also +-------- + +.. seealso:: + + :ref:`vyos.vyos.vyos_static_routes_module` + The official documentation on the **vyos.vyos.vyos_static_routes** module. + + + + + +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 config after the module ran.
+
+
+
+ before + +
+ list +
+ 		always +
Static route config before the module ran.
+
+
+
+ commands + +
+ list +
+ 		always +
set/delete commands issued.
+
+
+
+ gathered + +
+ list +
+ 		when state is gathered +
Static routes read from device (state=gathered).
+
+
+

+ + +Status +------ + + +Authors +~~~~~~~ + +- VyOS Community (@vyos) diff --git a/docs/vyos.rest.vyos_system_module.rst b/docs/vyos.rest.vyos_system_module.rst new file mode 100644 index 0000000..7b70e41 --- /dev/null +++ b/docs/vyos.rest.vyos_system_module.rst @@ -0,0 +1,244 @@ +.. _vyos.rest.vyos_system_module: + + +********************* +vyos.rest.vyos_system +********************* + +**Manage system settings on VyOS via the REST API.** + + +Version added: 1.0.0 + +.. contents:: + :local: + :depth: 1 + + +Synopsis +-------- +- Manages system-level settings — hostname, domain name, name servers, domain search list — using the VyOS HTTPS REST API. +- Mirrors ``vyos.vyos.vyos_system`` but uses the HTTP API. + + + + +Parameters +---------- + +.. raw:: html + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
ParameterChoices/DefaultsComments
+
+ api_key + +
+ string + / required +
+ 		+ +
+
+ domain_name + +
+ string +
+ 		+ +
System domain name.
+
+
+ domain_search + +
+ list + / elements=string +
+ 		+ +
List of domain search suffixes. Mutually exclusive with name_server.
+
+
+ host_name + +
+ string +
+ 		+ +
System hostname.
+
+
+ hostname + +
+ string + / required +
+ 		+ +
+
+ name_server + +
+ list + / elements=string +
+ 		+ +
List of DNS name servers. Mutually exclusive with domain_search.
+

aliases: name_servers
+
+
+ port + +
+ integer +
+ 		+ Default:
443
+ 		+
+
+ state + +
+ string +
+ 		+
    Choices: +
  • present ←
    • +
  • absent
    • +
+ 		+
present to apply, absent to remove.
+
+
+ timeout + +
+ integer +
+ 		+ Default:
30
+ 		+
+
+ verify_ssl + +
+ boolean +
+ 		+
    Choices: +
  • no ←
    • +
  • yes
    • +
+ 		+
+
+ + + + + + + +Return Values +------------- +Common return values are documented `here `_, the following are the fields unique to this module: + +.. raw:: html + + + + + + + + + + + + +
KeyReturnedDescription
+
+ commands + +
+ list +
+ 		always +
set/delete commands issued.
+
+
+

+ + +Status +------ + + +Authors +~~~~~~~ + +- VyOS Community (@vyos) diff --git a/docs/vyos.rest.vyos_user_module.rst b/docs/vyos.rest.vyos_user_module.rst new file mode 100644 index 0000000..119edf0 --- /dev/null +++ b/docs/vyos.rest.vyos_user_module.rst @@ -0,0 +1,564 @@ +.. _vyos.rest.vyos_user_module: + + +******************* +vyos.rest.vyos_user +******************* + +**Manage local users on VyOS via the REST API.** + + +Version added: 1.0.0 + +.. contents:: + :local: + :depth: 1 + + +Synopsis +-------- +- Manages local user accounts on VyOS devices using the HTTPS REST API. +- Mirrors ``vyos.vyos.vyos_user`` but uses the HTTP API. + + + + +Parameters +---------- + +.. raw:: html + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
ParameterChoices/DefaultsComments
+
+ aggregate + +
+ list + / elements=dictionary +
+ 		+ +
List of user definitions. Mutually exclusive with name.
+

aliases: users, collection
+
+
+ configured_password + +
+ string +
+ 		+ +
Plaintext password (will be hashed on device).
+
+
+ encrypted_password + +
+ string +
+ 		+ +
Pre-hashed password string.
+
+
+ full_name + +
+ string +
+ 		+ +
Full name.
+
+
+ level + +
+ string +
+ 		+
    Choices: +
  • admin
    • +
  • operator
    • +
+ 		+
User privilege level.
+
+
+ name + +
+ string + / required +
+ 		+ +
Username.
+
+
+ public_keys + +
+ list + / elements=dictionary +
+ 		+ +
SSH public keys for authentication.
+
+
+ key + +
+ string + / required +
+ 		+ +
Base64-encoded public key.
+
+
+ name + +
+ string + / required +
+ 		+ +
Key identifier (e.g. user@host).
+
+
+ type + +
+ string + / required +
+ 		+
    Choices: +
  • ssh-dss
    • +
  • ssh-rsa
    • +
  • ecdsa-sha2-nistp256
    • +
  • ecdsa-sha2-nistp384
    • +
  • ssh-ed25519
    • +
  • ecdsa-sha2-nistp521
    • +
+ 		+
Key type.
+
+
+ state + +
+ string +
+ 		+
    Choices: +
  • present
    • +
  • absent
    • +
+ 		+
Present or absent.
+
+
+ update_password + +
+ string +
+ 		+
    Choices: +
  • always
    • +
  • on_create
    • +
+ 		+
When to update the password.
+
+
+ api_key + +
+ string + / required +
+ 		+ +
+
+ configured_password + +
+ string +
+ 		+ +
Plaintext password.
+
+
+ encrypted_password + +
+ string +
+ 		+ +
Pre-hashed password.
+
+
+ full_name + +
+ string +
+ 		+ +
Full name for the single user.
+
+
+ hostname + +
+ string + / required +
+ 		+ +
+
+ level + +
+ string +
+ 		+
    Choices: +
  • admin
    • +
  • operator
    • +
+ 		+
+
+ name + +
+ string +
+ 		+ +
Single username. Mutually exclusive with aggregate.
+
+
+ port + +
+ integer +
+ 		+ Default:
443
+ 		+
+
+ public_keys + +
+ list + / elements=dictionary +
+ 		+ +
+
+ key + +
+ string + / required +
+ 		+ +
+
+ name + +
+ string + / required +
+ 		+ +
+
+ type + +
+ string + / required +
+ 		+ +
+
+ state + +
+ string +
+ 		+
    Choices: +
  • present ←
    • +
  • absent
    • +
+ 		+
Whether to create (present) or remove (absent) the user.
+
+
+ timeout + +
+ integer +
+ 		+ Default:
30
+ 		+
+
+ update_password + +
+ string +
+ 		+
    Choices: +
  • always
    • +
  • on_create
    • +
+ 		+
+
+ verify_ssl + +
+ boolean +
+ 		+
    Choices: +
  • no ←
    • +
  • yes
    • +
+ 		+
+
+ + + + + + + +Return Values +------------- +Common return values are documented `here `_, the following are the fields unique to this module: + +.. raw:: html + + + + + + + + + + + + +
KeyReturnedDescription
+
+ commands + +
+ list +
+ 		always +
set/delete commands issued.
+
+
+

+ + +Status +------ + + +Authors +~~~~~~~ + +- VyOS Community (@vyos) diff --git a/docs/vyos.rest.vyos_vlan_module.rst b/docs/vyos.rest.vyos_vlan_module.rst new file mode 100644 index 0000000..db45fd8 --- /dev/null +++ b/docs/vyos.rest.vyos_vlan_module.rst @@ -0,0 +1,360 @@ +.. _vyos.rest.vyos_vlan_module: + + +******************* +vyos.rest.vyos_vlan +******************* + +**Manage VLANs on VyOS network devices via REST API.** + + +Version added: 1.0.0 + +.. contents:: + :local: + :depth: 1 + + +Synopsis +-------- +- Manages 802.1Q VLAN sub-interfaces on VyOS Ethernet interfaces using the HTTPS REST API. +- Mirrors ``vyos.vyos.vyos_vlan`` but uses the HTTP API. + + + + +Parameters +---------- + +.. raw:: html + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
ParameterChoices/DefaultsComments
+
+ address + +
+ string +
+ 		+ +
IP address for the VLAN interface.
+
+
+ aggregate + +
+ list + / elements=dictionary +
+ 		+ +
List of VLAN definitions.
+
+
+ address + +
+ string +
+ 		+ +
+
+ interfaces + +
+ list + / elements=string + / required +
+ 		+ +
+
+ name + +
+ string +
+ 		+ +
+
+ state + +
+ string +
+ 		+
    Choices: +
  • present
    • +
  • absent
    • +
+ 		+
+
+ vlan_id + +
+ integer + / required +
+ 		+ +
+
+ api_key + +
+ string + / required +
+ 		+ +
+
+ hostname + +
+ string + / required +
+ 		+ +
+
+ interfaces + +
+ list + / elements=string +
+ 		+ +
List of physical interfaces to configure the VLAN on.
+
+
+ name + +
+ string +
+ 		+ +
VLAN name (used as description on the VIF).
+
+
+ port + +
+ integer +
+ 		+ Default:
443
+ 		+
+
+ purge + +
+ boolean +
+ 		+
    Choices: +
  • no ←
    • +
  • yes
    • +
+ 		+
Remove VLANs not defined in aggregate.
+
+
+ state + +
+ string +
+ 		+
    Choices: +
  • present ←
    • +
  • absent
    • +
+ 		+
present to configure, absent to remove.
+
+
+ timeout + +
+ integer +
+ 		+ Default:
30
+ 		+
+
+ verify_ssl + +
+ boolean +
+ 		+
    Choices: +
  • no ←
    • +
  • yes
    • +
+ 		+
+
+ vlan_id + +
+ integer +
+ 		+ +
VLAN ID (0-4094).
+
+
+ + + + + + + +Return Values +------------- +Common return values are documented `here `_, the following are the fields unique to this module: + +.. raw:: html + + + + + + + + + + + + +
KeyReturnedDescription
+
+ commands + +
+ list +
+ 		always +
set/delete commands issued.
+
+
+

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