From 9a3fa5777e7203d46faf1185cfb56c4fc121d885 Mon Sep 17 00:00:00 2001 From: omnom62 Date: Wed, 6 May 2026 08:08:27 +1000 Subject: More modules --- docs/vyos.rest.vyos_banner_module.rst | 296 ------ docs/vyos.rest.vyos_hostname_module.rst | 325 ------ docs/vyos.rest.vyos_httpapi.rst | 18 +- docs/vyos.rest.vyos_image_module.rst | 227 +++++ docs/vyos.rest.vyos_logging_global_module.rst | 834 ++++++++++++++++ docs/vyos.rest.vyos_ntp_global_module.rst | 475 --------- docs/vyos.rest.vyos_snmp_server_module.rst | 1317 ------------------------- 7 files changed, 1071 insertions(+), 2421 deletions(-) delete mode 100644 docs/vyos.rest.vyos_banner_module.rst delete mode 100644 docs/vyos.rest.vyos_hostname_module.rst create mode 100644 docs/vyos.rest.vyos_image_module.rst create mode 100644 docs/vyos.rest.vyos_logging_global_module.rst delete mode 100644 docs/vyos.rest.vyos_ntp_global_module.rst delete mode 100644 docs/vyos.rest.vyos_snmp_server_module.rst (limited to 'docs') diff --git a/docs/vyos.rest.vyos_banner_module.rst b/docs/vyos.rest.vyos_banner_module.rst deleted file mode 100644 index 7e7b285..0000000 --- a/docs/vyos.rest.vyos_banner_module.rst +++ /dev/null @@ -1,296 +0,0 @@ -.. _vyos.rest.vyos_banner_module: - - -********************* -vyos.rest.vyos_banner -********************* - -**Manage login banners on VyOS devices using REST API** - - -Version added: 1.0.0 - -.. contents:: - :local: - :depth: 1 - - -Synopsis --------- -- Configure pre-login and post-login banners on VyOS devices via REST API. -- Supports idempotent configuration using structured data. -- Multiline banner text is supported via YAML block scalars. -- Uses REST API (``connection=httpapi``) instead of CLI. -- VyOS stores multiline banners as a single string with literal ``\\n`` separators. - - - - -Parameters ----------- - -.. raw:: html - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
ParameterChoices/DefaultsComments
-
- config - -
- dictionary - / required -
- 		- -
Banner configuration.
-
-
- banner - -
- string - / required -
- 		-
    Choices: -
  • pre-login
    • -
  • post-login
    • -
- 		-
Banner type to configure.
-
-
- text - -
- string -
- 		- -
Banner text. Supports multiline strings via YAML block scalar (|).
-
Internally, real newlines are converted to literal \\n as VyOS expects.
-
-
- state - -
- string -
- 		-
    Choices: -
  • merged ←
    • -
  • replaced
    • -
  • overridden
    • -
  • deleted
    • -
  • gathered
    • -
- 		-
Desired state of the configuration.
-
-
- - -Notes ------ - -.. note:: - - This module requires ``ansible_connection=httpapi``. - - Banner text comparison is whitespace-normalized for idempotency. - - VyOS stores banner text as a leaf string value with literal ``\\n`` for newlines. - - For ``merged``, ``replaced``, and ``overridden`` states, the behaviour is identical for this single-leaf resource — the banner value is set to the desired text. - - - -Examples --------- - -.. code-block:: yaml - - - name: Configure single-line pre-login banner - vyos.rest.vyos_banner: - config: - banner: pre-login - text: "Unauthorized access is prohibited" - state: merged - - - name: Configure multiline post-login banner - vyos.rest.vyos_banner: - config: - banner: post-login - text: | - Welcome to VyOS - Authorized users only - Disconnect if you are not authorized - state: merged - - - name: Replace post-login banner - vyos.rest.vyos_banner: - config: - banner: post-login - text: "Welcome to VyOS" - state: replaced - - - name: Remove pre-login banner - vyos.rest.vyos_banner: - config: - banner: pre-login - state: deleted - - - name: Gather banner configuration - vyos.rest.vyos_banner: - config: - banner: pre-login - 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 -
Configuration after changes (text uses real newlines).
-
-
Sample:
-
{'banner': 'pre-login', 'text': 'New banner text'}
-
-
- before - -
- dictionary -
- 		always -
Configuration before changes (text uses real newlines).
-
-
Sample:
-
{'banner': 'pre-login', 'text': 'Old banner text'}
-
-
- commands - -
- list -
- 		when changes are required -
List of API command dicts sent to the device.
-
-
Sample:
-
[{'op': 'set', 'path': ['system', 'login', 'banner', 'pre-login'], 'value': 'New banner text'}]
-
-
- gathered - -
- dictionary -
- 		when state is gathered -
Current device configuration (text uses real newlines).
-
-
Sample:
-
{'banner': 'pre-login', 'text': 'Current banner text'}
-
-
- response - -
- dictionary -
- 		when changes are applied -
Raw response from VyOS REST API.
-
-
-
- saved - -
- dictionary -
- 		when changes are applied -
Result of save_config call after applying changes.
-
-
-

- - -Status ------- - - -Authors -~~~~~~~ - -- Your Name (@yourhandle) diff --git a/docs/vyos.rest.vyos_hostname_module.rst b/docs/vyos.rest.vyos_hostname_module.rst deleted file mode 100644 index aa6e2ad..0000000 --- a/docs/vyos.rest.vyos_hostname_module.rst +++ /dev/null @@ -1,325 +0,0 @@ -.. _vyos.rest.vyos_hostname_module: - - -*********************** -vyos.rest.vyos_hostname -*********************** - -**Manage the hostname of a VyOS device using REST API** - - -Version added: 1.0.0 - -.. contents:: - :local: - :depth: 1 - - -Synopsis --------- -- Configures the system hostname on VyOS network devices via the REST API. -- Supports idempotent configuration — no change is made if the desired hostname already matches the running configuration. -- Uses REST API (``connection=httpapi``) instead of CLI. - - - - -Parameters ----------- - -.. raw:: html - - - - - - - - - - - - - - - - - - - - - - - - -
ParameterChoices/DefaultsComments
-
- config - -
- dictionary -
- 		- -
Hostname configuration dictionary.
-
-
- hostname - -
- string -
- 		- -
The hostname to set on the VyOS device.
-
Must be a valid RFC 1123 hostname.
-
-
- state - -
- string -
- 		-
    Choices: -
  • merged ←
    • -
  • replaced
    • -
  • overridden
    • -
  • deleted
    • -
  • gathered
    • -
- 		-
The desired state of the hostname configuration.
-
merged, replaced, and overridden are identical for this single-value resource — all three ensure the hostname is set to the value specified in config.
-
deleted removes the configured hostname, reverting to the device default.
-
gathered retrieves the current hostname from the device and returns it as structured data in the gathered key. No changes are made to the device.
-
-
- - -Notes ------ - -.. note:: - - Tested against VyOS 1.3 (equuleus) and 1.4 (sagitta). - - Requires ``ansible_connection=httpapi`` with the VyOS httpapi plugin. - - The ``ansible_network_os`` inventory variable must be set to ``vyos.rest.vyos``. - - - -Examples --------- - -.. code-block:: yaml - - # Before state: - # ------------- - # vyos@router:~$ show configuration commands | grep host-name - # set system host-name 'vyostest' - - - name: Set hostname using merged state - vyos.rest.vyos_hostname: - config: - hostname: vyos - state: merged - - # After state: - # ------------ - # set system host-name 'vyos' - - # ------------------------------------------------------------------------ - - # Before state: - # ------------- - # set system host-name 'vyos' - - - name: Override hostname (identical behaviour to merged for this resource) - vyos.rest.vyos_hostname: - config: - hostname: vyosTest - state: overridden - - # After state: - # ------------ - # set system host-name 'vyosTest' - - # ------------------------------------------------------------------------ - - # Before state: - # ------------- - # set system host-name 'vyos' - - - name: Replace hostname - vyos.rest.vyos_hostname: - config: - hostname: vyosRouter - state: replaced - - # After state: - # ------------ - # set system host-name 'vyosRouter' - - # ------------------------------------------------------------------------ - - # Before state: - # ------------- - # set system host-name 'vyos' - - - name: Delete configured hostname - vyos.rest.vyos_hostname: - state: deleted - - # After state: - # ------------ - # (no host-name entry — device reverts to default) - - # ------------------------------------------------------------------------ - - - name: Gather current hostname from device - vyos.rest.vyos_hostname: - state: gathered - - # Module result: - # -------------- - # "gathered": { - # "hostname": "vyos" - # } - - # ------------------------------------------------------------------------ - - - name: Idempotency — no change when hostname already matches - vyos.rest.vyos_hostname: - config: - hostname: vyos - state: merged - - # Module result (hostname already 'vyos'): - # ---------------------------------------- - # "changed": false - - - -Return Values -------------- -Common return values are documented `here `_, the following are the fields unique to this module: - -.. raw:: html - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
KeyReturnedDescription
-
- after - -
- dictionary -
- 		when changed -
Hostname configuration on the device after this module ran.
-
-
Sample:
-
{'hostname': 'vyos'}
-
-
- before - -
- dictionary -
- 		when state is merged, replaced, overridden or deleted -
Hostname configuration on the device before this module ran.
-
-
Sample:
-
{'hostname': 'vyostest'}
-
-
- commands - -
- list -
- 		when state is merged, replaced, overridden or deleted -
List of API command dicts sent to the device.
-
-
Sample:
-
[{'op': 'set', 'path': ['system', 'host-name', 'vyos']}]
-
-
- gathered - -
- dictionary -
- 		when state is gathered -
Current hostname configuration retrieved from the device as structured data. Returned only when state is gathered.
-
-
Sample:
-
{'hostname': 'vyos'}
-
-
- response - -
- dictionary -
- 		when changes are applied -
Raw response returned by the VyOS REST API.
-
-
Sample:
-
{'success': True, 'data': None, 'error': None}
-
-
- saved - -
- dictionary -
- 		when changes are applied -
Result of the save_config call issued after applying changes.
-
-
-

- - -Status ------- - - -Authors -~~~~~~~ - -- Your Name (@yourhandle) diff --git a/docs/vyos.rest.vyos_httpapi.rst b/docs/vyos.rest.vyos_httpapi.rst index 7d887b5..e493ebc 100644 --- a/docs/vyos.rest.vyos_httpapi.rst +++ b/docs/vyos.rest.vyos_httpapi.rst @@ -5,9 +5,10 @@ vyos.rest.vyos ************** -**VyOS REST API** +**HttpApi plugin for VyOS REST API** +Version added: 1.0.0 .. contents:: :local: @@ -16,7 +17,9 @@ vyos.rest.vyos Synopsis -------- -- HTTPAPI plugin for interacting with VyOS REST API. +- This HttpApi plugin provides methods to connect to VyOS devices via their HTTPS REST API. +- Use with ``ansible_connection=ansible.netcommon.httpapi`` and ``ansible_network_os=vyos.rest.vyos``. +- The VyOS REST API must be enabled with ``set service https api keys id ansible key YOUR_KEY``, ``set service https api rest``, then ``commit && save``. @@ -45,14 +48,13 @@ Parameters -
ini entries: -

[httpapi]
api_key = VALUE

-
-
env:ANSIBLE_HTTPAPI_API_KEY
+
env:VYOS_API_KEY
var: ansible_httpapi_api_key
+
var: ansible_vyos_api_key
-
VyOS API key
+
The API key configured on the VyOS device.
+
Set ansible_httpapi_api_key in inventory or the VYOS_API_KEY environment variable.
@@ -72,7 +74,7 @@ Status Authors ~~~~~~~ -- Evgeny Molotkov (@eomnom62) +- VyOS Community (@vyos) .. hint:: diff --git a/docs/vyos.rest.vyos_image_module.rst b/docs/vyos.rest.vyos_image_module.rst new file mode 100644 index 0000000..3dd396d --- /dev/null +++ b/docs/vyos.rest.vyos_image_module.rst @@ -0,0 +1,227 @@ +.. _vyos.rest.vyos_image_module: + + +******************** +vyos.rest.vyos_image +******************** + +**Manage VyOS system images via the REST API.** + + +Version added: 1.0.0 + +.. contents:: + :local: + :depth: 1 + + +Synopsis +-------- +- Adds or removes VyOS system images using the HTTPS REST API (``/image`` endpoint). +- Use *state=present* to download and install an image from a URL. +- Use *state=absent* to delete an installed image by name. + + + +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.
+
+
+ name + +
+ string +
+ 		+ +
Version name of the image to remove (e.g. 1.4-rolling-202401010000).
+
Required when state=absent.
+
+
+ port + +
+ integer +
+ 		+ Default:
443
+ 		+
HTTPS port for the REST API.
+
+
+ state + +
+ string + / required +
+ 		+
    Choices: +
  • present
    • +
  • absent
    • +
+ 		+
{'present': 'Download and install the image from url.'}
+
{'absent': 'Delete the image specified by name.'}
+
+
+ timeout + +
+ integer +
+ 		+ Default:
300
+ 		+
Request timeout in seconds. Image downloads can take several minutes; increase this value accordingly.
+
+
+ url + +
+ string +
+ 		+ +
HTTP(S) URL of the VyOS .iso file to install.
+
Required when state=present.
+
+
+ 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 image add/delete operation.
+
+
+

+ + +Status +------ + + +Authors +~~~~~~~ + +- VyOS Community (@vyos) diff --git a/docs/vyos.rest.vyos_logging_global_module.rst b/docs/vyos.rest.vyos_logging_global_module.rst new file mode 100644 index 0000000..718e646 --- /dev/null +++ b/docs/vyos.rest.vyos_logging_global_module.rst @@ -0,0 +1,834 @@ +.. _vyos.rest.vyos_logging_global_module: + + +***************************** +vyos.rest.vyos_logging_global +***************************** + +**Manage syslog configuration on VyOS devices using REST API** + + +Version added: 1.0.0 + +.. contents:: + :local: + :depth: 1 + + +Synopsis +-------- +- Manages syslog (logging) configuration on VyOS devices via the REST API. +- Supports console, file, host, user, and global logging targets with per-target facility and severity configuration. +- Uses REST API (``connection=httpapi``) instead of CLI. + + + + +Parameters +---------- + +.. raw:: html + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
ParameterChoices/DefaultsComments
+
+ config + +
+ dictionary +
+ 		+ +
Logging configuration.
+
+
+ console + +
+ dictionary +
+ 		+ +
Logging to serial console.
+
+
+ facilities + +
+ list + / elements=dictionary +
+ 		+ +
+
+ facility + +
+ string +
+ 		+ +
+
+ severity + +
+ string +
+ 		+ +
+
+ files + +
+ list + / elements=dictionary +
+ 		+ +
Logging to local files.
+
+
+ archive + +
+ dictionary +
+ 		+ +
+
+ file_num + +
+ integer +
+ 		+ +
+
+ size + +
+ integer +
+ 		+ +
+
+ facilities + +
+ list + / elements=dictionary +
+ 		+ +
+
+ facility + +
+ string +
+ 		+ +
+
+ severity + +
+ string +
+ 		+ +
+
+ path + +
+ string +
+ 		+ +
+
+ global_params + +
+ dictionary +
+ 		+ +
Global syslog parameters (maps to system syslog global).
+
+
+ archive + +
+ dictionary +
+ 		+ +
+
+ file_num + +
+ integer +
+ 		+ +
+
+ size + +
+ integer +
+ 		+ +
+
+ facilities + +
+ list + / elements=dictionary +
+ 		+ +
+
+ facility + +
+ string +
+ 		+ +
+
+ severity + +
+ string +
+ 		+ +
+
+ marker_interval + +
+ integer +
+ 		+ +
+
+ preserve_fqdn + +
+ boolean +
+ 		+
    Choices: +
  • no
    • +
  • yes
    • +
+ 		+
+
+ hosts + +
+ list + / elements=dictionary +
+ 		+ +
Logging to remote syslog hosts.
+
+
+ facilities + +
+ list + / elements=dictionary +
+ 		+ +
+
+ facility + +
+ string +
+ 		+ +
+
+ protocol + +
+ string +
+ 		+ +
Per-facility protocol override.
+
+
+ severity + +
+ string +
+ 		+ +
+
+ hostname + +
+ string +
+ 		+ +
+
+ port + +
+ integer +
+ 		+ +
+
+ protocol + +
+ string +
+ 		+ +
+
+ users + +
+ list + / elements=dictionary +
+ 		+ +
Logging to local user terminals.
+
+
+ facilities + +
+ list + / elements=dictionary +
+ 		+ +
+
+ facility + +
+ string +
+ 		+ +
+
+ severity + +
+ string +
+ 		+ +
+
+ username + +
+ string +
+ 		+ +
+
+ running_config + +
+ string +
+ 		+ +
Used only with state parsed.
+
+
+ state + +
+ string +
+ 		+
    Choices: +
  • merged ←
    • +
  • replaced
    • +
  • overridden
    • +
  • deleted
    • +
  • gathered
    • +
  • rendered
    • +
  • parsed
    • +
+ 		+
Desired state of the logging configuration.
+
+
+ + + + +Examples +-------- + +.. code-block:: yaml + + - name: Merge logging configuration + vyos.rest.vyos_logging_global: + config: + console: + facilities: + - facility: local7 + severity: err + files: + - path: logFile + archive: + file_num: 2 + facilities: + - facility: local6 + severity: emerg + hosts: + - hostname: 172.16.0.1 + port: 223 + facilities: + - facility: local7 + severity: all + - facility: all + protocol: udp + users: + - username: vyos + facilities: + - facility: local7 + severity: debug + global_params: + archive: + file_num: 2 + size: 111 + facilities: + - facility: cron + severity: debug + marker_interval: 111 + preserve_fqdn: true + state: merged + + - name: Delete all logging configuration + vyos.rest.vyos_logging_global: + state: deleted + + - name: Gather current logging configuration + vyos.rest.vyos_logging_global: + 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 +
Logging configuration after this module ran.
+
+
+
+ before + +
+ dictionary +
+ 		when state is merged, replaced, overridden or deleted +
Logging configuration before this module ran.
+
+
+
+ commands + +
+ list +
+ 		always +
List of API command tuples sent to the device.
+
+
+
+ gathered + +
+ dictionary +
+ 		when state is gathered +
Current logging configuration from the device.
+
+
+
+ saved + +
+ dictionary +
+ 		when changes are applied +
Result of save_config after applying changes.
+
+
+

+ + +Status +------ + + +Authors +~~~~~~~ + +- Sagar Paul (@KB-perByte) diff --git a/docs/vyos.rest.vyos_ntp_global_module.rst b/docs/vyos.rest.vyos_ntp_global_module.rst deleted file mode 100644 index 220797d..0000000 --- a/docs/vyos.rest.vyos_ntp_global_module.rst +++ /dev/null @@ -1,475 +0,0 @@ -.. _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.
-
pool replaces dynamic in VyOS 1.3+.
-
nts was added in VyOS 1.4.
-
ptp and interleave were added in VyOS 1.5.
-
preempt is only available in VyOS 1.3 and earlier.
-
-
- 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 as a string. The module parses it into structured data and returns the result in the parsed key.
-
No device connection is required for this state.
-
-
- state - -
- string -
- 		-
    Choices: -
  • merged ←
    • -
  • replaced
    • -
  • overridden
    • -
  • deleted
    • -
  • gathered
    • -
  • rendered
    • -
  • parsed
    • -
- 		-
The desired state of the NTP configuration.
-
merged adds or updates the provided configuration without removing existing entries not mentioned in the task.
-
replaced fully replaces the running NTP configuration with the provided config, removing entries not present in the task.
-
overridden deletes all existing allow-client, listen-address, and server entries then applies the desired config from scratch.
-
deleted removes all NTP allow-client, listen-address, and server entries managed by this module.
-
gathered retrieves and returns the current NTP configuration as structured data. No changes are made to the device.
-
rendered returns the CLI commands that would be generated for the provided config without connecting to the device.
-
parsed parses the CLI output provided via running_config into structured data without connecting to the device.
-
-
- - -Notes ------ - -.. note:: - - Tested against VyOS 1.4 (sagitta) and 1.5. - - Requires ``ansible_connection=httpapi`` with the VyOS httpapi plugin. - - ``ansible_network_os`` must be set to ``vyos.rest.vyos``. - - ``replaced`` and ``overridden`` differ. ``replaced`` performs a surgical diff removing only entries not in the task. ``overridden`` deletes entire subtrees first then re-applies, which is safer when option ordering matters. - - The ``rendered`` and ``parsed`` states do not require a device connection. - - - -Examples --------- - -.. code-block:: yaml - - # Before state: - # ------------- - # set service ntp server time1.vyos.net - # set service ntp server time2.vyos.net - # set service ntp server time3.vyos.net - - - 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 - - # After state: - # ------------ - # set service ntp allow-client address '10.6.6.0/24' - # set service ntp listen-address '10.1.3.1' - # set service ntp server 203.0.113.0 prefer - # set service ntp server time1.vyos.net - # set service ntp server time2.vyos.net - # set service ntp server time3.vyos.net - - # ------------------------------------------------------------------------ - - - 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: Override NTP configuration - vyos.rest.vyos_ntp_global: - config: - allow_clients: - - 10.3.3.0/24 - listen_addresses: - - 10.7.8.1 - servers: - - server: server1 - options: - - dynamic - - prefer - - server: server2 - options: - - noselect - - preempt - - server: serv - state: overridden - - # ------------------------------------------------------------------------ - - - name: Delete all managed NTP configuration - vyos.rest.vyos_ntp_global: - state: deleted - - # ------------------------------------------------------------------------ - - - name: Gather current NTP configuration - vyos.rest.vyos_ntp_global: - state: gathered - - # ------------------------------------------------------------------------ - - - name: Render NTP configuration commands offline - vyos.rest.vyos_ntp_global: - config: - allow_clients: - - 10.7.7.0/24 - - 10.8.8.0/24 - listen_addresses: - - 10.7.9.1 - servers: - - server: server7 - - server: server45 - options: - - noselect - - prefer - - pool - state: rendered - - # ------------------------------------------------------------------------ - - - name: Parse NTP configuration from CLI output - vyos.rest.vyos_ntp_global: - running_config: "{{ lookup('file', './ntp_config.cfg') }}" - state: parsed - - - -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 on the device before this module ran.
-
-
-
- commands - -
- list -
- 		always -
List of API command tuples or dicts sent to the device.
-
-
-
- gathered - -
- dictionary -
- 		when state is gathered -
Current NTP configuration retrieved from the device as structured data.
-
-
-
- parsed - -
- dictionary -
- 		when state is parsed -
Structured data parsed from the running_config CLI output.
-
-
-
- rendered - -
- list -
- 		when state is rendered -
CLI commands generated for the provided configuration (offline, no device needed).
-
-
-
- response - -
- dictionary -
- 		when changes are applied -
Raw API response from the VyOS REST API.
-
-
-
- saved - -
- boolean -
- 		when changes are applied -
Result of save_config after applying changes.
-
-
-

- - -Status ------- - - -Authors -~~~~~~~ - -- Varshitha Yataluru (@YVarshitha) diff --git a/docs/vyos.rest.vyos_snmp_server_module.rst b/docs/vyos.rest.vyos_snmp_server_module.rst deleted file mode 100644 index 24651ec..0000000 --- a/docs/vyos.rest.vyos_snmp_server_module.rst +++ /dev/null @@ -1,1317 +0,0 @@ -.. _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 scalar fields, 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 -
- 		- -
SNMPv3 groups.
-
-
- group - -
- string - / required -
- 		- -
Group name.
-
-
- mode - -
- string -
- 		-
    Choices: -
  • ro
    • -
  • rw
    • -
- 		-
Access mode.
-
-
- seclevel - -
- string -
- 		-
    Choices: -
  • auth
    • -
  • priv
    • -
- 		-
Security level.
-
-
- view - -
- string -
- 		- -
View name for this group.
-
-
- trap_targets - -
- list - / elements=dictionary -
- 		- -
SNMPv3 trap/inform targets.
-
-
- address - -
- string -
- 		- -
IP/IPv6 address of trap target.
-
-
- authentication - -
- dictionary -
- 		- -
Authentication for this trap target.
-
-
- encrypted_key - -
- string -
- 		- -
Encrypted authentication password.
-
-
- plaintext_key - -
- string -
- 		- -
Plaintext authentication password (will be encrypted on device).
-
-
- type - -
- string -
- 		-
    Choices: -
  • md5
    • -
  • sha
    • -
- 		-
Authentication protocol.
-
-
- port - -
- integer -
- 		- -
TCP/UDP port for traps/informs.
-
-
- privacy - -
- dictionary -
- 		- -
Privacy for this trap target.
-
-
- encrypted_key - -
- string -
- 		- -
Encrypted privacy password.
-
-
- plaintext_key - -
- string -
- 		- -
Plaintext privacy password (will be encrypted on device).
-
-
- type - -
- string -
- 		-
    Choices: -
  • des
    • -
  • aes
    • -
- 		-
Privacy protocol.
-
-
- protocol - -
- string -
- 		-
    Choices: -
  • tcp
    • -
  • udp
    • -
- 		-
Notification protocol.
-
-
- type - -
- string -
- 		-
    Choices: -
  • inform
    • -
  • trap
    • -
- 		-
Notification type.
-
-
- users - -
- list - / elements=dictionary -
- 		- -
SNMPv3 users.
-
-
- authentication - -
- dictionary -
- 		- -
Authentication configuration.
-
-
- encrypted_key - -
- string -
- 		- -
Encrypted authentication password.
-
-
- plaintext_key - -
- string -
- 		- -
Plaintext authentication password (will be encrypted on device).
-
-
- type - -
- string -
- 		-
    Choices: -
  • md5
    • -
  • sha
    • -
- 		-
Authentication protocol.
-
-
- group - -
- string -
- 		- -
Group membership for this user.
-
-
- mode - -
- string -
- 		-
    Choices: -
  • ro
    • -
  • rw
    • -
- 		-
Access mode.
-
-
- privacy - -
- dictionary -
- 		- -
Privacy configuration.
-
-
- encrypted_key - -
- string -
- 		- -
Encrypted privacy password.
-
-
- plaintext_key - -
- string -
- 		- -
Plaintext privacy password (will be encrypted on device).
-
-
- type - -
- string -
- 		-
    Choices: -
  • des
    • -
  • aes
    • -
- 		-
Privacy protocol.
-
-
- tsm_key - -
- string -
- 		- -
TSM certificate fingerprint or filename.
-
-
- user - -
- string - / required -
- 		- -
Username.
-
-
- views - -
- list - / elements=dictionary -
- 		- -
SNMPv3 views.
-
-
- exclude - -
- string -
- 		- -
Excluded OID subtree.
-
-
- mask - -
- string -
- 		- -
Bit-mask for OID subidentifiers.
-
-
- oid - -
- string -
- 		- -
OID for this view.
-
-
- view - -
- string - / required -
- 		- -
View name.
-
-
- trap_source - -
- string -
- 		- -
SNMP trap source address.
-
-
- trap_target - -
- dictionary -
- 		- -
SNMP trap target.
-
-
- address - -
- string -
- 		- -
IP address of trap target.
-
-
- community - -
- string -
- 		- -
Community string for traps.
-
-
- port - -
- integer -
- 		- -
Destination port for trap notifications.
-
-
- state - -
- string -
- 		-
    Choices: -
  • merged ←
    • -
  • replaced
    • -
  • overridden
    • -
  • deleted
    • -
  • gathered
    • -
- 		-
Desired state of SNMP configuration.
-
merged adds or updates provided config without removing existing entries.
-
replaced and overridden perform a full replacement — entries not in the task config are removed.
-
deleted removes all SNMP configuration with a single delete command.
-
gathered returns current device config as structured data, no changes made.
-
-
- - -Notes ------ - -.. note:: - - Tested against VyOS 1.5q2. - - - -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: Replace SNMP configuration - vyos.rest.vyos_snmp_server: - config: - communities: - - name: bridges - networks: - - 1.1.1.0/24 - - 12.1.1.0/24 - location: "RDU, NC" - listen_addresses: - - address: 100.1.2.1 - port: 33 - snmp_v3: - groups: - - group: default - view: default - users: - - user: admin_user - authentication: - encrypted_key: 33f8bfd6b69ee03a184818a4daea503c9e579633 - type: sha - privacy: - encrypted_key: 33f8bfd6b69ee03a184818a4daea503c9e579633 - type: aes - group: default - views: - - view: default - oid: "1" - state: replaced - - # ------------------------------------------------------------------------ - - - 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.
-
-
-
- response - -
- dictionary -
- 		when changes are applied -
Raw API response.
-
-
-
- saved - -
- dictionary -
- 		when changes are applied -
Result of save_config after applying changes.
-
-
-

- - -Status ------- - - -Authors -~~~~~~~ - -- your_name (@yourhandle) -- cgit v1.2.3