Back to Commands

ntpq

systemLinux/Unix
The ntpq command is one of the most frequently used commands in Linux/Unix-like operating systems. ntpq NTP query utility for monitoring NTP daemon ntpd operations
See ExamplesView Syntax

Quick Reference

Command Name:

ntpq

Category:

system

Platform:

Linux/Unix

Basic Usage:

ntpq [options] [arguments]

Common Use Cases

    Syntax

    ntpq [options] [host...]

    Options

    Option Description
    -4 Force IPv4 DNS resolution
    -6 Force IPv6 DNS resolution
    -c command Run a specified command and exit
    -d Enable debugging output
    -D level Set debugging level
    -i Force interactive mode
    -n Output numeric host addresses instead of hostnames
    -p Print a list of peers and their state (shorthand for -c peers)
    -s Print a list of peers in a different format
    -t Set a timeout in seconds for noninteractive mode

    Common Interactive Mode Commands:

    Command Description
    peers Display a list of peers and their state
    associations Display association IDs and status
    lpeers Display a detailed list of peers
    opeers Display a list of peers in old style format
    rv [association-ID] Display system variables from the server
    readvar [association-ID] [variable-name] Read system or peer variables
    clockvar [association-ID] [variable-name] Read clock variables
    pstats [association-ID] Show peer statistics
    help Display help information
    quit Exit the program

    Peer Status Codes in 'ntpq -p' Output:

    Code Description
    * The peer is the system's current time source (synchronization source)
    o The peer is a PPS (Pulse Per Second) peer
    + The peer is a candidate for selection
    - The peer is being discarded by the cluster algorithm
    x The peer is considered a falseticker by the intersection algorithm
    . The peer is being included in the synchronization
    # The peer is a selected peer but the distance exceeds the maximum

    Examples

    How to Use These Examples

    The examples below show common ways to use the ntpq command. Try them in your terminal to see the results. You can copy any example by clicking on the code block.

    # Basic Examples Basic
    ntpq -p
    Display a list of the peers known to the server and a summary of their state.
    ntpq -pn
    Same as above, but display numeric addresses instead of hostnames.
    # Advanced Examples Advanced
    ntpq > peers > quit Enter interactive mode, show peers, then exit. ntpq -c peers Run the 'peers' command and exit. ntpq -c "rv 0" localhost Show system variables from the local NTP server. ntpq -c "readvar" time.nist.gov Read system variables from a remote NTP server. ntpq -c clockvar localhost Show clock variables from the local NTP server. ntpq -c associations Display association IDs and statuses. ntpq -c "association" localhost Show detailed association information. ntpq -c "lpeers" Display detailed peer information including synchronization distance.

    Try It Yourself

    Practice makes perfect! The best way to learn is by trying these examples on your own system with real files.

    Understanding Syntax

    Pay attention to the syntax coloring: commands, options, and file paths are highlighted differently.

    Notes

    The ntpq (Network Time Protocol Query) utility is an essential tool for monitoring and managing NTP (Network Time Protocol) servers. It serves as the primary interface for examining the state of a running ntpd (Network Time Protocol daemon) and provides detailed information about its operation, peers, and synchronization status. As part of the NTP software suite, ntpq communicates with NTP servers using the standard NTP mode 6 control messages, allowing it to query a wide range of parameters and statistics. This makes it invaluable for system administrators responsible for maintaining accurate time synchronization across networks. Key features of the ntpq command: 1. Peer Monitoring: One of ntpq's most common uses is displaying information about the NTP server's peers (other time servers it communicates with) through the 'peers' command. This shows critical data like which server is being used as the primary time source, the estimated delay to each peer, and the offset from each peer's time. 2. Interactive Mode: ntpq can be run in an interactive mode where users can issue multiple commands in sequence, making it convenient for detailed troubleshooting sessions. 3. System Variables: The tool can display internal system variables of the NTP daemon, showing configuration settings and runtime statistics. 4. Association Information: ntpq can show detailed information about each server association, including synchronization distance, jitter, and dispersion metrics. 5. Remote Querying: It can query both local and remote NTP servers, allowing administrators to check the status of time servers across their network. 6. Scriptable: ntpq can execute a single command in non-interactive mode with the -c option, making it suitable for use in scripts and automated monitoring systems. Common use cases for ntpq include: - Verifying that an NTP server is properly synchronizing with its time sources - Troubleshooting time synchronization problems - Monitoring the quality of time sources being used - Checking the overall health and configuration of NTP services - Creating scripts for automated NTP monitoring in system management tools - Educational purposes for understanding NTP operation The output of ntpq, particularly from the 'peers' command, uses a shorthand notation that indicates the status of each peer. For example, a '*' character at the beginning of a line indicates that the peer is the current synchronization source, while a '+' character indicates that the peer is a candidate for selection. While ntpq is powerful, it's important to note that newer time synchronization systems like Chrony provide their own query tools (such as chronyc). However, ntpq remains widely used in environments running the traditional NTP daemon and is a standard part of most Linux and Unix-like operating systems. For security reasons, many NTP servers are configured to restrict the information they provide via ntpq queries, particularly from remote hosts. This helps protect against potential information disclosure or amplification attacks that could exploit the NTP protocol.

    Related Commands

    These commands are frequently used alongside ntpq or serve similar purposes:

    ntpd
    ntpdate
    ntpdc
    chronyc
    date
    timedatectl
    Explore All Commands

    Use Cases

    Learn By Doing

    The best way to learn Linux commands is by practicing. Try out these examples in your terminal to build muscle memory and understand how the ntpq command works in different scenarios.

    See ExamplesTry Lab Exercises
    $ ntpq
    View All Commands