Query NTP Safely with ntpdig Before Changing the System Clock

You will finish with a read-only NTP query, a machine-readable result for scripts, and a deliberate choice between stepping and slewing the local clock. The examples use NTPsec ntpdig 1.2.2, installed here from the ntpsec-ntpdig package version 1.2.2+dfsg1-4build2.

Allow about ten minutes. You need a shell, network access to an NTP or SNTP server, and the ntpdig package. The first half is unprivileged and only reads time. The clock-setting examples normally need root, and can affect running services, logs and authentication if the correction is large.

1. Check the installed client

Confirm the program and version before relying on examples from another NTP implementation:

$ command -v ntpdig
/usr/bin/ntpdig
$ ntpdig --version
ntpdig ntpsec-1.2.2

The installed command accepts --version. Its help output also shows -V as the short form. Do not assume that options from the classic sntp utility carry over. NTPsec explicitly removed several old options, including -b, -K, -o, -r, -w and -W.

2. Query a server without changing time

Start with a server name supplied by your organisation or distribution. The public pool is only an example:

$ ntpdig -4 -t 2 pool.ntp.org
2026-09-25 07:42:46.285599 (+0100) +0.006008 +/- 0.006850 pool.ntp.org 185.232.69.65 s1 no-leap

Without -S or -s, this command does not set the clock. The output shows local time, the offset in seconds, the synchronisation distance, the server address, its stratum and its leap indication. An offset of +0.006008 means the local clock is ahead of the server's estimate by about six milliseconds, so the local clock would need to move backwards to match it.

-4 forces IPv4 name resolution. Use -6 when you specifically need IPv6. The -t 2 value limits the wait for replies to two seconds; the installed default is five seconds. A short timeout is useful for an interactive check, but may be too aggressive on a slow or distant link.

Checkpoint: the command should return status 0 when it receives a usable response. Check it immediately:

$ printf '%s\n' "$?"
0

3. Request JSON for a script

Use -j when another program needs the result. It suppresses syslog messages and writes a self-describing JSON record to standard output:

$ ntpdig -4 -j -t 2 pool.ntp.org
{"time":"2026-09-25T07:42:46.285599+0100","offset":0.006008,"precision":"0.006850","host":"pool.ntp.org","ip":"185.232.69.65","stratum":1,"leap":"no-leap","adjusted":false}

The field called precision is the synchronisation distance, not the server's clock precision. The adjusted value tells you whether ntpdig determined that a correction should have been made. It remains false for this read-only command.

Do not parse the human-readable line with awk when JSON is available. If you need a shell health check, preserve the exit status and keep diagnostic output separate:

if result=$(ntpdig -4 -j -t 5 pool.ntp.org); then
    printf '%s\n' "$result"
else
    status=$?
    printf 'ntpdig failed with status %s\n' "$status" >&2
    exit "$status"
fi

4. Query more than one sample

Use -p to request multiple samples. The default is one. ntpdig selects the best sample, considering factors including synchronisation distance, for display or use:

$ ntpdig -4 -p 3 -t 5 pool.ntp.org

Be careful with DNS names that return several addresses. By default, ntpdig treats those addresses as one server instance and leaves a two-second gap between requests. Use -c with a host name only when its returned addresses represent different machines, such as a properly managed server pool:

$ ntpdig -4 -c pool.ntp.org

Concurrent requests can increase load on the sources. They are not a general speed switch. If you do not know how the name is operated, omit -c.

5. Choose how a clock correction should happen

Do not run these commands casually. Both forms change the system clock and normally require elevated privilege. First perform the read-only query and check that the server is trusted and synchronised.

To step the clock, applying the correction directly, use -S:

$ sudo ntpdig -4 -S -t 5 time.example.net

A step is appropriate when the offset is large or an immediate correction is required. It can move timestamps backwards or forwards abruptly. That can confuse applications, scheduled work and log analysis. Do not use it while an independent time daemon is also controlling the clock.

To slew, change the clock rate gradually with adjtime(), use -s:

$ sudo ntpdig -4 -s -t 5 time.example.net

Slewing avoids a sudden jump, but takes time to remove a large offset. You can make the choice depend on a threshold with -M, whose value is in milliseconds. In this example, corrections below 128 milliseconds are slewed and larger corrections are stepped:

$ sudo ntpdig -4 -S -s -M 128 -t 5 time.example.net

The manual describes -S as enabling correction by stepping and -s as enabling correction by slewing. The combination is intentional when paired with -M. A value of zero means all adjustments are stepped. Keep the command out of automation until you have checked how your existing time service is configured.

6. Diagnose a failed query

A failed query returns status 1. Capture the error before running another command:

$ ntpdig -4 -t 2 time.example.net
ntpdig: no eligible servers
$ printf '%s\n' "$?"
1

Check the name and network path without changing system state:

$ getent ahosts time.example.net
$ ntpdig -4 -d -t 5 time.example.net

Debug output is deliberately more verbose. It can expose addresses and protocol details, so avoid sending it to a public paste service. If the server name resolves to several addresses, try one known address or use -c only when concurrent querying is correct. If the server does not report valid data, the synchronisation distance may be shown as +/- ?, which is not evidence that the clock is accurate.

NTPsec's ntpdig does not log to syslog. If a scheduled job needs local logging, pipe its standard output and standard error to your system's logger command, or use -l with a deliberately chosen logfile. Check permissions and rotation before pointing a long-running job at a new path.