ntpq

Start ntpq in interactive mode

$ ntpq

$ ntpq [[-p|--peers]]

$ ntpq [[-n|--numeric]] [[-p|--peers]]

$ ntpq [[-d|--debug-level]]

$ ntpq [[-c|--command]] [rv]

ntpq [ -c command ] [ -n ] [ -p ] [ -l ] [ host ... ]

-c command
    Executes the specified command on the remote host or local daemon. This allows running a single query without entering interactive mode.

-n
    Displays host addresses numerically rather than attempting to look up their symbolic hostnames, which can speed up queries and avoid DNS issues.

-p
    Prints a list of configured peers and their synchronization status, including stratum, poll interval, reachability, and offset. This is one of the most frequently used options.

-l
    Prints a list of local NTP associations, useful for understanding how ntpd is interacting with local reference clocks.

-i
    Forces ntpq into interactive mode, providing a prompt to enter commands. This is the default behavior if no command or host is specified on the command line.

-d
    Increases the debugging output level, providing more verbose information that can be helpful for troubleshooting complex issues.

-r refid
    Specifies the reference ID to use for local clock reference, primarily for testing purposes or specific configuration scenarios.

-s
    Prints a summary of the association list, offering a concise overview of peer status without the full detail of the -p option.

ntpq is a standard command-line utility used for monitoring and querying the ntpd (Network Time Protocol daemon) or other remote NTP servers. It allows administrators to inspect the current state of NTP synchronization, including details about configured peers, their reachability, stratum, and synchronization status. ntpq can operate in an interactive mode, providing a prompt for issuing commands, or in a batch mode by supplying commands directly on the command line. It's an essential tool for diagnosing NTP issues, verifying time synchronization, and understanding the network's timekeeping performance, ensuring the accuracy and reliability of system clocks across a network. It's often used to check which server is currently being used for synchronization, analyze jitter and offset, and gather statistics about time sources.

Using ntpq effectively requires an NTP daemon (like ntpd) to be running and accessible, either locally or on a remote host. Communication typically occurs over UDP port 123, so firewall rules must permit this traffic. Interpreting ntpq output, particularly the metrics related to offset, jitter, and reachability, requires a basic understanding of NTP concepts. Querying remote NTP servers might expose details about their configuration or network topology, and access might be restricted by the server's NTP access control settings.

When run in interactive mode (e.g., ntpq -i or just ntpq without arguments), ntpq provides a prompt where users can issue several commands to query the NTP daemon.

Examples include:
peers: Displays a list of all configured NTP peer associations and their status.
as: Shows all associations, including local clock references.
rv <associd> [variable]: Reads specific variables (e.g., system variables, peer variables) from a given association ID.
lopeers: Lists local peer associations, typically used for reference clocks.
quit: Exits the ntpq interactive session.
host <hostname>: Connects to a different NTP host or daemon.

The output of the -p (peers) option is crucial for diagnosing NTP synchronization. Each column provides specific information:
remote: The hostname or IP address of the peer.
refid: The source of the peer's time, often an IP or a special ID for reference clocks (e.g., GPS, PPS).
st: Stratum of the peer, indicating its distance from a reference clock. Lower stratum means closer to the source.
t: Type of association (e.g., 'u' for unicast, 'l' for local, 'b' for broadcast).
when: The time, in seconds, since the last packet was received from the peer.
poll: The polling interval, in seconds, at which queries are sent to the peer.
reach: An octal bitmask indicating the reachability of the peer over the last eight polls. A value of 377 indicates full reachability.
delay: The round-trip delay to the peer, in milliseconds.
offset: The estimated time offset between the local system and the peer, in milliseconds. This is the value ntpd tries to minimize.
jitter: A measure of the statistical dispersion of the offset values. Lower jitter indicates more stable time synchronization.

ntpq is an integral part of the NTP suite, which was originally developed by Dr. David L. Mills at the University of Delaware in the 1980s. As NTP evolved through various versions (NTPv1, NTPv2, NTPv3, NTPv4), ntpq has consistently served as the primary diagnostic and monitoring tool for the ntpd daemon. Its design reflects the long-standing need for detailed operational insight into time synchronization networks, adapting to new features and protocol extensions over decades of development.

ntpd(8), ntpdate(8), timedatectl(1), chronyc(1), sntp(1)