Use ntpdate Safely on ntpsec: Query First, Set Deliberately

You will check an NTP server without changing the local clock, inspect the command that the installed compatibility wrapper will run, and then choose a controlled clock adjustment. Allow about ten minutes. You need a shell, a reachable NTP server name, and administrator access only for a real clock change.

This guide is written for the installed Debian-family package ntpsec-ntpdate, version 1.2.2+dfsg1-4build2. That detail matters: /usr/sbin/ntpdate is a shell wrapper around ntpdig, while the installed ntpdate(8) page describes the older command interface. The wrapper is retained for compatibility and does not implement every option shown by that page.

1. Confirm the installed command

Start by checking which executable the shell will use and reading the wrapper's own help:

$ command -v ntpdate
/usr/sbin/ntpdate
$ ntpdate -h
Usage: ntpdate [OPTIONS] HOST...

Options:
        -4      Force IPv4 DNS name resolution
        -6      Force IPv6 DNS name resolution
        -a N    Specify key number for authentication
        -b      Force time step
        -B      Force time slew
        -k FILE Specify key file
        -q      Query only
        -s      Log to syslog
        -t N.N  Specify timeout
        -h      Print help

The help output is the practical interface for this installed package. The local manual also lists -d, -o, -u and -v, but this wrapper only passes some of those through or reports them differently. In particular, its source rejects -o and -p as no longer supported. Do not copy a command from a guide for another NTP implementation without checking the local executable.

2. Query a server without changing the clock

Use -q for a read-only query. Replace pool.ntp.org with a server approved for your network:

$ ntpdate -q pool.ntp.org
25 Sep 07:39:27.81063 (+0100) +0.000034 +/- 0.004985 pool.ntp.org 185.248.188.98 s1 no-leap

The address, measurements and timestamp will differ. The useful result is a successful command and a reported server response. Capture the status immediately if a script needs it:

$ ntpdate -q pool.ntp.org
$ status=$?
$ printf 'ntpdate status: %s\n' "$status"
ntpdate status: 0

The wrapper translates this mode to an ntpdig query. It does not set the clock, so it is the right first test when you are unsure whether DNS, UDP port 123 or the server itself is reachable. A non-zero status means that no usable server result was obtained; it is not evidence that the local clock is wrong.

3. Inspect the generated command without running it

The installed wrapper has an undocumented diagnostic switch, -n, which prints the generated ntpdig command instead of executing it. This is useful for checking the default adjustment mode without contacting a server:

$ ntpdate -n pool.ntp.org
ntpdig -s -S -M 500 -t 1 pool.ntp.org

The exact spacing and server name come from the wrapper. The default real-time path requests a slew for small corrections and permits a step for larger corrections, using a 500 millisecond threshold. The wrapper also supplies a one-second timeout unless you pass -t. The local manual describes the older default as slewing, with -b forcing a step and -B forcing a slew. On this package, -b and -B are translated to the corresponding ntpdig adjustment options.

4. Apply a normal correction only when ready

Changing system time affects logs, scheduled jobs, TLS checks and applications that compare timestamps. Treat this as a service-impacting operation. Confirm the query first, tell anyone relying on the host, and use an elevated shell only for this step:

$ sudo ntpdate -t 2 pool.ntp.org

The command uses the wrapper's normal adjustment policy. It may slew a small offset or step a larger one. A successful exit status means the wrapper obtained a server result and asked the system to adjust the clock; it does not prove that every application immediately observed the new time.

If this is boot-time initialisation and a step is acceptable, request it explicitly:

$ sudo ntpdate -b -t 2 pool.ntp.org

A step is abrupt. It can move the clock forwards or backwards and can confuse software that assumes time is monotonic. Prefer the default policy for a running host unless the boot process specifically needs the clock corrected before services start. Conversely, -B forces slewing, which can take time when the offset is large.

Do not run this while a time-synchronisation daemon is actively controlling the same clock unless your operating procedure explicitly coordinates them. The local manual warns that the traditional command declines to set time when an NTP daemon is running, except with -u; this compatibility wrapper passes requests to ntpdig and should not be treated as a daemon-management command. Check the host's service policy before making a second time source compete with the first.

5. Handle network and compatibility failures

Start with the smallest read-only test and increase detail only when it helps:

$ getent hosts pool.ntp.org
$ ntpdate -q -t 2 pool.ntp.org
$ ntpdate -n -q -t 2 pool.ntp.org

The first command checks name resolution. The second checks the NTP request with a two-second timeout. The third shows the command that would be run, but it does not replace the second test because it does not contact the server. If IPv4 or IPv6 selection is the problem, put -4 or -6 before the server name:

$ ntpdate -q -4 pool.ntp.org
$ ntpdate -q -6 pool.ntp.org

Do not use -o or -p from the installed manual page with this package and assume they worked. The wrapper reports those options as unsupported. If you need protocol-specific or multi-sample behaviour, use the installed ntpdig documentation and command directly, with the same care about privilege and clock changes.

Authentication is a separate operational decision. The -a key number and -k key file must match the server's configuration. Do not invent key IDs, copy secret material into a shell history, or make an unauthenticated public server appear trusted. If authenticated time is required, obtain the key-handling procedure from the system owner first.

6. Verify the result and recover safely

After a real adjustment, run a query again and inspect the system's normal time status:

$ ntpdate -q pool.ntp.org
$ date --iso-8601=seconds
$ timedatectl status

Use the first result to confirm that a server still answers and the second to see the local wall clock. timedatectl status is a separate inspection command; its output depends on the host's systemd and time-service configuration. If your organisation uses another time tool, use that tool's status command instead.

There is no general undo command for a clock step. If the adjustment was wrong, stop and investigate rather than applying an opposite guess. Query a trusted source, record the observed offset, and let the host's approved time daemon recover the clock if one is configured. Restore a stopped daemon only according to its service procedure. Avoid changing log timestamps or deleting evidence to hide a mistaken correction.