NTP

Network Time Protocol (NTP) synchronizes clocks across distributed network devices using UDP and Coordinated Universal Time (UTC). NTP uses a stratum hierarchy to describe distance from an authoritative time source — stratum 1 servers connect directly to radio, atomic, or GPS clocks, and each subsequent hop increments the stratum. The protocol is highly efficient, requiring no more than one packet per minute to synchronize two devices to within a millisecond. Accurate and consistent timekeeping is critical for event correlation, certificate validation, logging, and protocol operation across the network infrastructure.

Diagram

Classes

configuration (iosxr.devices)

Name	Type	Constraint	Mandatory	Default Value
ntp	Class	`[ntp]`	No

ntp (iosxr.devices.configuration)

Name	Type	Constraint	Mandatory
access_groups	Class	`[access_groups]`	No
admin_plane_burst	Boolean	`true`, `false`	No
admin_plane_iburst	Boolean	`true`, `false`	No
admin_plane_key	Integer	min: `1`, max: `65535`	No
admin_plane_maxpoll	Integer	min: `4`, max: `17`	No
admin_plane_minpoll	Integer	min: `4`, max: `17`	No
admin_plane_prefer	Boolean	`true`, `false`	No
admin_plane_version	Integer	min: `1`, max: `4`	No
authenticate	Boolean	`true`, `false`	No
authentication_keys	List	`[authentication_keys]`	No
broadcastdelay	Integer	min: `1`, max: `999999`	No
drift_aging_time	Integer	min: `0`, max: `65535`	No
drift_file	Choice	`bootflash`, `compactflash`, `disk0`, `disk1`, `disk2`, `harddisk`, `usb`	No
drift_filename	String		No
interfaces	List	`[interfaces]`	No
ipv4_dscp	Any	Integer[min: `0`, max: `63`] or Choice[`af11`, `af12`, `af13`, `af21`, `af22`, `af23`, `af31`, `af32`, `af33`, `af41`, `af42`, `af43`, `cs1`, `cs2`, `cs3`, `cs4`, `cs5`, `cs6`, `cs7`, `default`, `ef`] or String[Regex: `^.[\$\%]\{.$`]	No
ipv4_precedence	Any	Integer[min: `0`, max: `7`] or Choice[`critical`, `flash`, `flash-override`, `immediate`, `internet`, `network`, `priority`, `routine`] or String[Regex: `^.[\$\%]\{.$`]	No
ipv6_dscp	Any	Integer[min: `0`, max: `63`] or Choice[`af11`, `af12`, `af13`, `af21`, `af22`, `af23`, `af31`, `af32`, `af33`, `af41`, `af42`, `af43`, `cs1`, `cs2`, `cs3`, `cs4`, `cs5`, `cs6`, `cs7`, `default`, `ef`] or String[Regex: `^.[\$\%]\{.$`]	No
ipv6_precedence	Any	Integer[min: `0`, max: `7`] or Choice[`critical`, `flash`, `flash-override`, `immediate`, `internet`, `network`, `priority`, `routine`] or String[Regex: `^.[\$\%]\{.$`]	No
log_internal_sync	Boolean	`true`, `false`	No
master	Any	Integer[min: `1`, max: `15`] or Choice[`primary_reference_clock`] or String[Regex: `^.[\$\%]\{.$`]	No
max_associations	Integer	min: `0`, max: `4294967295`	No
passive	Boolean	`true`, `false`	No
peers	List	`[peers]`	No
servers	List	`[servers]`	No
source_interface	String		No
update_calendar	Boolean	`true`, `false`	No
vrfs	List	`[vrfs]`	No

access_groups (iosxr.devices.configuration.ntp)

Name	Type	Mandatory
ipv4_peer	String	No
ipv4_query_only	String	No
ipv4_serve	String	No
ipv4_serve_only	String	No
ipv6_peer	String	No
ipv6_query_only	String	No
ipv6_serve	String	No
ipv6_serve_only	String	No

authentication_keys (iosxr.devices.configuration.ntp)

Name	Type	Constraint	Mandatory
key	String		Yes
key_type	Choice	`7`	Yes
mode	Choice	`md5`, `cmac`, `hmac_sha1`, `hmac_sha2`	Yes
number	Integer	min: `1`, max: `65535`	Yes
trusted	Boolean	`true`, `false`	No

interfaces (iosxr.devices.configuration.ntp)

Name	Type	Constraint	Mandatory
name	String		Yes
broadcast_client	Boolean	`true`, `false`	No
broadcast_destination	String		No
broadcast_key	Integer	min: `1`, max: `65535`	No
broadcast_version	Integer	min: `2`, max: `4`	No
disable	Boolean	`true`, `false`	No

peers (iosxr.devices.configuration.ntp)

Name	Type	Constraint	Mandatory
address	Any	IP or String or String[Regex: `^.[\$\%]\{.$`]	Yes
burst	Boolean	`true`, `false`	No
iburst	Boolean	`true`, `false`	No
key	Integer	min: `1`, max: `65535`	No
maxpoll	Integer	min: `4`, max: `9`	No
minpoll	Integer	min: `4`, max: `5`	No
prefer	Boolean	`true`, `false`	No
source	String		No
version	Integer	min: `2`, max: `4`	No

vrfs (iosxr.devices.configuration.ntp)

Name	Type	Constraint	Mandatory
vrf	String		Yes
access_groups	Class	`[access_groups]`	No
interfaces	List	`[interfaces]`	No
peers	List	`[peers]`	No
servers	List	`[servers]`	No
source_interface	String		No

Data Normalization

DSCP and Precedence Values

NTP DSCP and precedence fields accept both numeric and named string values.

ipv4_dscp / ipv6_dscp: integer 0-63 or named value (e.g., ef, af11, cs3)
ipv4_precedence / ipv6_precedence: integer 0-7 or named value (e.g., flash, critical, network)

Both formats can be used interchangeably. The normalization layer automatically converts integer values to their named equivalents before sending to the device, preventing configuration drift.

Peers and Servers

The peers and servers lists accept IPv4 addresses, IPv6 addresses, and hostnames in the address field. The Terraform module automatically detects the address type and routes entries to the appropriate provider attributes (IPv4, IPv6, or hostname).

Example YAML Code:

Example-1: Authenticated NTP servers with QoS marking.

iosxr:
  devices:
    - name: router-1
      host: 10.10.10.1:57400
      configuration:
        hostname: router-1
        ntp:
          authenticate: true
          source_interface: Loopback0
          ipv4_dscp: cs6
          update_calendar: true
          authentication_keys:
            - number: 1
              mode: hmac_sha2
              key: "00071A150754"
              key_type: 7
              trusted: true
          servers:
            - address: 10.255.0.1
              key: 1
              prefer: true
              iburst: true
            - address: 10.255.0.2
              key: 1
              iburst: true

Example-2: NTP via management VRF with access control.

iosxr:
  devices:
    - name: router-1
      host: 10.10.10.1:57400
      configuration:
        hostname: router-1
        ntp:
          access_groups:
            ipv4_peer: NTP-PEER-ACL
            ipv4_serve_only: NTP-CLIENTS-ACL
          vrfs:
            - vrf: MGMT
              source_interface: MgmtEth0/RP0/CPU0/0
              access_groups:
                ipv4_serve: NTP-MGMT-ACL
              servers:
                - address: 172.16.0.10
                  prefer: true
                  iburst: true
                - address: 172.16.0.11
                  iburst: true

Example-3: NTP master with peering, broadcast interfaces, and admin-plane settings.

iosxr:
  devices:
    - name: router-1
      host: 10.10.10.1:57400
      configuration:
        hostname: router-1
        ntp:
          master: 3
          source_interface: Loopback0
          log_internal_sync: true
          admin_plane_version: 4
          admin_plane_prefer: true
          admin_plane_iburst: true
          peers:
            - address: 10.0.0.2
              version: 4
              prefer: true
              source: Loopback0
          interfaces:
            - name: GigabitEthernet0/0/0/0
              broadcast_destination: 10.10.10.255
              broadcast_key: 1
              broadcast_version: 4
            - name: GigabitEthernet0/0/0/1
              disable: true

Example-4: Dual-stack NTP with IPv4 and IPv6 servers and tuned polling.

iosxr:
  devices:
    - name: router-1
      host: 10.10.10.1:57400
      configuration:
        hostname: router-1
        ntp:
          authenticate: true
          source_interface: Loopback0
          ipv6_dscp: af41
          max_associations: 20
          authentication_keys:
            - number: 10
              mode: md5
              key: "060506324F41"
              key_type: 7
              trusted: true
            - number: 20
              mode: hmac_sha1
              key: "14161C180B04"
              key_type: 7
              trusted: true
          servers:
            - address: 10.100.0.1
              key: 10
              prefer: true
              version: 4
              minpoll: 4
              maxpoll: 6
              iburst: true
            - address: "2001:db8:100::1"
              key: 20
              version: 4
              minpoll: 4
              maxpoll: 8
          peers:
            - address: 10.100.0.2
              version: 4
              burst: true
            - address: "2001:db8:100::2"
              version: 4

Example-5: Multi-VRF with global and VRF-scoped NTP.

iosxr:
  devices:
    - name: router-1
      host: 10.10.10.1:57400
      configuration:
        hostname: router-1
        ntp:
          source_interface: Loopback0
          ipv4_dscp: cs6
          servers:
            - address: 10.255.0.1
              prefer: true
              iburst: true
          vrfs:
            - vrf: CUSTOMER-A
              source_interface: GigabitEthernet0/0/0/1.100
              servers:
                - address: 192.168.100.1
                  prefer: true
              peers:
                - address: "2001:db8:a::1"
                  version: 4
              interfaces:
                - name: GigabitEthernet0/0/0/1.100
                  broadcast_client: true
            - vrf: CUSTOMER-B
              source_interface: GigabitEthernet0/0/0/2.200
              access_groups:
                ipv4_peer: CUST-B-NTP-ACL
              servers:
                - address: 192.168.200.1
                  key: 10
                  prefer: true
                  iburst: true

Example-6: NTP with drift settings and hostname-based peers/servers.

iosxr:
  devices:
    - name: router-1
      host: 10.10.10.1:57400
      configuration:
        hostname: router-1
        ntp:
          drift_aging_time: 10
          drift_file: disk0
          drift_filename: "drift.txt"
          servers:
            - address: 10.255.0.1
              prefer: true
              iburst: true
            - address: ntp.cisco.com
              version: 4
              prefer: true
          peers:
            - address: ntp-peer.example.com
              version: 4
              burst: true
          vrfs:
            - vrf: MGMT
              source_interface: MgmtEth0/RP0/CPU0/0
              servers:
                - address: ntp-mgmt.cisco.com
                  prefer: true