ntpq: Practical Guide for Querying NTP Daemon

ntpq: Practical Guide for Querying NTP Daemon

ntpq is the client you use to query and interact with the Network Time Protocol (NTP) daemon. This quick guide covers the basics, common options, and practical tips with examples you can run on your Linux box.

Start in interactive mode

The simplest way to begin is to run ntpq by itself. This drops you into an interactive prompt where you can issue commands.

$ ntpq

In interactive mode you’ll see a prompt like ntpq> where you can type commands such as peers, assoc, readlist, etc.

To see currently configured peers, use the peers command. It shows server/IPs your NTP daemon tracks.

ntpq> peers

Notes:

  • This command relies on the configured server list and any servers discovered through NTP interactions.
  • If you want a non-interactive, one-shot view, you can still use ntpq from the shell with the -p flag (see below).

If you’re troubleshooting DNS or want faster output, you can skip hostname lookups with the numeric option. This is especially useful on systems with many peers or slow DNS.

$ ntpq -n -p

Notes:

  • The -n (or —numeric) flag prints IP addresses instead of resolving them to hostnames.
  • This can speed up output and avoid DNS-related delays or failures.

Use ntpq in debugging mode

For deeper troubleshooting, ntpq can print more verbose debug information. This is helpful when you’re diagnosing drift, offset, or connectivity issues.

$ ntpq -d

You can increase levels with —debug-level if needed, but start with the default to avoid excessive output.

$ ntpq --debug-level 1

Tip:

  • Excessive debug output can be confusing. Use it only when you have a specific issue to investigate.

ntpq can execute a virtual command to fetch or display specific NTP system variables. This is useful for scripting or quick checks.

$ ntpq -c rv

Here, -c (or —command) rv prints a summary of the NTP variables, such as offsets, latency, and stratum.

Common usage in scripts:

ntpq -c rv

And you can chain commands or request particular variables, for example:

ntpq -c 'rv 0'

Notes:

  • The -c flag is powerful for quick reads of NTP state. It’s commonly used in health checks and monitoring dashboards.
  • Be mindful of quoting when embedding in scripts to avoid shell interpretation issues.

Quick tips and common pitfalls

  • Pitfall: ntpq in interactive mode may show an empty peers list if the NTP daemon isn’t configured to reach servers. Ensure your /etc/ntp.conf (or equivalent) has valid server directives.
  • Pitfall: DNS resolution delays can make commands slow. Use -n to avoid DNS lookups when appropriate.
  • Pitfall: Debug output can overwhelm logs. Use a specific debug level and revert to normal once you’ve gathered enough information.
  • Tip: For health checks, combine -c rv with -n and -p to get both state and reachable peers quickly:
$ ntpq -n -p -c rv

Quick reference cheat sheet

  • Start interactive mode: ntpq
  • Print peers: ntpq peers (in interactive mode) or ntpq -p (one-shot)
  • Numeric output (no DNS): ntpq -n -p
  • Debug mode: ntpq -d or ntpq —debug-level
  • Print system variables: ntpq -c rv

If you’re curious for deeper details, you can consult the man page at man ntpq (or online at manned.org) for a complete list of commands and options.

See Also