From c2493986714604aa992bea28628b74587b3b51bd Mon Sep 17 00:00:00 2001 From: omnom62 Date: Wed, 15 Apr 2026 07:34:02 +1000 Subject: NTP_global rest --- docs/vyos.rest.vyos_ntp_global_module.rst | 475 ++++++++++++++++++++++++++++++ 1 file changed, 475 insertions(+) create mode 100644 docs/vyos.rest.vyos_ntp_global_module.rst (limited to 'docs') 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..220797d --- /dev/null +++ b/docs/vyos.rest.vyos_ntp_global_module.rst @@ -0,0 +1,475 @@ +.. _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) -- cgit v1.2.3