1NTPDIG(1) NTPsec NTPDIG(1)
2
6 ntpdig - standard Simple Network Time Protocol client program
7
9 ntpdig
10 [--help | -?] [-4 | -6] [-a keynum] [-p samples]
11 [-c] [-d] [-D debug-level] [-g delay] [-j] [-k keyfile]
12 [-l logfile] [-M steplimit] [-S] [-s]
13 [--wait] [--no-wait] [--version] [address...]+
14
16 ntpdig can be used as an SNTP client to query an NTP or SNTP server and
17 either display the time or set the local system’s time (given suitable
18 privilege). It can be run as an interactive command or from a cron job.
19 NTP (the Network Time Protocol) and SNTP (the Simple Network Time
20 Protocol) are defined and described by RFC 5905.
21 The default is to write the estimated correct local date and time (i.e.
23 not UTC) to the standard output in a format like:
24 2015-10-14 13:46:04.534916 (+0500) -0.000007 +/- 0.084075 localhost 127.0.0.1 s2 no-leap
26 where the (+0500) means that to get to UTC from the reported local time
28 one must add 5 hours and 0 minutes, the -0.000007 indicates the local
29 clock is 0.000007 seconds ahead of correct time (so 0.000007 seconds
30 must be subtracted from the local clock to get it to be correct). Note
31 that the number of decimals printed for this value will change based on
32 the reported precision of the server. +/- 0.084075 is the reported
33 synchronization distance (in seconds), which represents the maximum
34 error due to all causes. If the server does not report valid data
35 needed to calculate the synchronization distance, this will be reported
36 as +/- ?.
37 If the host is different from the IP, both will be displayed.
39 Otherwise, only the IP is displayed. Finally, the stratum of the host
40 is reported and the leap indicator is decoded and displayed.
41 With the -j (JSON) option, the output format becomes a self-describing
43 JSON record:
44 {"time":"2015-10-14T13:46:04.534916+0500",
46 "offset":-0.000007,"precision":"0.084075",
47 "host":"localhost",ip:"127.0.0.1",
48 "stratum":2,"leap":"noleap","adjusted":false}
49 In the JSON format, time is in ISO 8601 format; precision is the synch
51 distance, with an unknown synch distance being reported as 0. Host and
52 IP are always emitted even if duplicate. The "adjusted" boolean reports
53 whether ntpdig determined it should have slewed or stepped the time.
54 This may be shown as true even if time was not actually adjusted due to
55 lack of clock-setting privileges.
56
58 -h, --help
59 Displays usage information and exits.
60 -4, --ipv4
62 Force IPv4 DNS name resolution. This option must not appear in
63 combination with any of the following options: ipv6.
64 Force DNS resolution of the following host names on the command
66 line to the IPv4 namespace.
67 -6, --ipv6
69 Force IPv6 DNS name resolution. This option must not appear in
70 combination with any of the following options: ipv4.
71 Force DNS resolution of the following host names on the command
73 line to the IPv6 namespace.
74 -a auth-keynumber, --authentication=auth-keynumber
76 Enable authentication with the key auth-keynumber. This option
77 takes an integer number as its argument.
78 Enable authentication using the key specified in this option’s
80 argument. The argument of this option is the keyid, a number
81 specified in the keyfile as this key’s identifier. See the keyfile
82 option (-k) for more details.
83 -c host-name, --concurrent=host-name
85 Concurrently query all IPs returned for host-name. This option may
86 appear an unlimited number of times.
87 Requests from an NTP "client" to a "server" should never be sent
89 more rapidly than one every 2 seconds. By default, any IPs returned
90 as part of a DNS lookup are assumed to be for a single instance of
91 ntpd, and therefore ntpdig will send queries to these IPs one after
92 another, with a 2-second gap in between each query.
93 The -c or --concurrent flag says that any IPs returned for the DNS
95 lookup of the supplied host-name are on different machines, so we
96 can send concurrent queries. This is appropriate when using a
97 server pool.
98 -d, --debug-level
100 Increase debug verbosity level. This option may appear an unlimited
101 number of times.
102 -D number, --set-debug-level=number
104 Set the debug verbosity level. This option may appear an unlimited
105 number of times. This option takes an integer number as its
106 argument.
107 -g milliseconds, --gap=milliseconds
109 The gap (in milliseconds) between time requests. This option takes
110 an integer number as its argument. The default milliseconds for
111 this option is 50.
112 Separate the queries we send out by the specified number of
114 milliseconds. A larger delay reduces the query load on the time
115 sources, at the cost of increasing the time to receive a valid
116 response if the first source attempted is slow or unreachable.
117 -j
119 Output to stdout in JSON, suppressing syslog messages.
120 -k file-name, --keyfile=file-name
122 Look in this file for the key specified with -a.
123 This option specifies the keyfile. ntpdig will search for the key
125 specified with -a keyno in this file. See ntp.keys(5) for more
126 information.
127 -l file-name, --logfile=file-name
129 Log to specified logfile.
130 This option causes the client to write log messages to the
132 specified logfile.
133 -M number, --steplimit=number
135 Adjustments less than steplimit milliseconds will be slewed. This
136 option takes an integer number as its argument. The value of number
137 is constrained to being greater than or equal to 0,
138 If the time adjustment is less than steplimit milliseconds, slew
140 the amount using adjtime(2). Otherwise, step the correction using
141 clock_settime() or local equivalent. The default value is 0, which
142 means all adjustments will be stepped. This is a feature, as
143 different situations demand different values.
144 -p, --samples
146 The number of samples to take (default 1). The best one (chosen by,
147 among other criteria, sync distance) is selected for display or
148 use.
149 -S, --step
151 By default, ntpdig displays the clock offset but does not attempt
152 to correct it. This option enables offset correction by stepping,
153 that is, directly setting the clock to the corrected time. This
154 typically requires ntpdig be invoked as the superuser ("root").
155 -s, --slew
157 By default, ntpdig displays the clock offset but does not attempt
158 to correct it. This option enables offset correction by slewing
159 using adjtime(), which changes the rate of the clock for a period
160 long enough to accomplish the required offset (phase) correction.
161 This typically requires ntpdig be invoked as the superuser
162 ("root").
163 -t seconds, --timeout=seconds
165 The number of seconds to wait for responses. This option takes an
166 integer number as its argument. The default seconds for this option
167 is: 5.
168 When waiting for a reply, ntpdig will wait the number of seconds
170 specified before giving up. The default should be more than enough
171 for a unicast response. If ntpdig is only waiting for a broadcast
172 response a longer timeout is likely needed.
173 --wait, --no-wait
175 Wait for pending replies (if not setting the time). The no-wait
176 form will disable the option. This option is enabled by default.
177 If we are not setting the time, wait for all pending responses.
179 --version
181 Output version of program and exit.
182
184 ntpdig ntpserver.somewhere
185 is the simplest use of this program and can be run as an
186 unprivileged command to check the current time and error in the
187 local clock.
188 ntpdig -S -s -M 128 ntpserver.somewhere
190 With suitable privilege, run as a command or from a cron(8) job,
191 ntpdig -Ss -M 128 ntpserver.somewhere will request the time from
192 the server, and if that server reports that it is synchronized then
193 if the offset adjustment is less than 128 milliseconds the
194 correction will be slewed, and if the correction is more than 128
195 milliseconds the correction will be stepped.
196 ntpdig -S ntpserver.somewhere
198 With suitable privilege, run as a command or from a cron(8) job,
199 ntpdig -S ntpserver.somewhere will set (step) the local clock from
200 a synchronized specified server, like the ntpdate utility from
201 older NTP implementations.
202
204 Not all options of the NTP classic sntp(1) utility have been retained;
205 don’t expect -b, -K, -o, -r, -w, or -W to work. These have either been
206 removed for security reasons or discarded as unnecessary in a modern
207 environment.
208 This version does not log to syslog. Pipe standard output and standard
210 error to logger(1) if you want this behavior.
211 The synchronization-distance formula used in this version is slightly
213 different from that found in sntp(1), tracking the newer formula used
214 in ntpd(8). Expect offset computations to match but synch-distances not
215 to.
216
218 One of the following exit values will be returned:
219 0 (EXIT_SUCCESS)
221 Successful program execution.
222 1 (EXIT_FAILURE)
224 The operation failed or the command syntax was not valid.
225
227 Johannes Maximilian Kuehn, Harlan Stenn, Dave Hart.
228
230 One of the following exit values will be returned:
231 0 (EXIT_SUCCESS)
233 Successful program execution.
234 1 (EXIT_FAILURE)
236 The operation failed or the command syntax was not valid.
237NTPsec 2023-08-03 NTPDIG(1)