"Fossies" - the Fresh Open Source Software Archive 
Member "ntp-4.2.8p15/sntp/invoke-sntp.texi" (23 Jun 2020, 15691 Bytes) of package /linux/misc/ntp-4.2.8p15.tar.gz:
As a special service "Fossies" has tried to format the requested text file into HTML format (style:
standard) with prefixed line numbers.
Alternatively you can here
view or
download the uninterpreted source code file.
See also the latest
Fossies "Diffs" side-by-side code changes report for "invoke-sntp.texi":
4.2.8p14_vs_4.2.8p15.
1 @node sntp Invocation
2 @section Invoking sntp
3 @pindex sntp
4 @cindex standard Simple Network Time Protocol client program
5 @ignore
6 #
7 # EDIT THIS FILE WITH CAUTION (invoke-sntp.texi)
8 #
9 # It has been AutoGen-ed June 23, 2020 at 02:19:36 AM by AutoGen 5.18.5
10 # From the definitions sntp-opts.def
11 # and the template file agtexi-cmd.tpl
12 @end ignore
13
14
15
16 @code{sntp}
17 can be used as an SNTP client to query a NTP or SNTP server and either display
18 the time or set the local system's time (given suitable privilege). It can be
19 run as an interactive command or from a
20 @code{cron}
21 job.
22
23 NTP (the Network Time Protocol) and SNTP (the Simple Network Time Protocol)
24 are defined and described by RFC 5905.
25
26
27 The default is to write the estimated correct local date and time (i.e. not
28 UTC) to the standard output in a format like:
29
30 @code{'1996-10-15 20:17:25.123 (+0800) +4.567 +/- 0.089 [host] IP sN'}
31
32 where the
33 @code{'(+0800)'}
34 means that to get to UTC from the reported local time one must
35 add 8 hours and 0 minutes,
36 the
37 @code{'+4.567'}
38 indicates the local clock is 4.567 seconds behind the correct time
39 (so 4.567 seconds must be added to the local clock to get it to be correct).
40 Note that the number of decimals printed for this value will change
41 based on the reported precision of the server.
42 @code{'+/- 0.089'}
43 is the reported
44 @emph{synchronization} @emph{distance}
45 (in seconds), which represents the maximum error due to all causes.
46 If the server does not report valid data needed to calculate the
47 synchronization distance, this will be reported as
48 @code{'+/- ?'}.
49 If the
50 @emph{host}
51 is different from the
52 @emph{IP},
53 both will be displayed.
54 Otherwise, only the
55 @emph{IP}
56 is displayed.
57 Finally, the
58 @emph{stratum}
59 of the host is reported
60 and the leap indicator is decoded and displayed.
61
62 This section was generated by @strong{AutoGen},
63 using the @code{agtexi-cmd} template and the option descriptions for the @code{sntp} program.
64 This software is released under the NTP license, <http://ntp.org/license>.
65
66 @menu
67 * sntp usage:: sntp help/usage (@option{--help})
68 * sntp ipv4:: ipv4 option (-4)
69 * sntp ipv6:: ipv6 option (-6)
70 * sntp authentication:: authentication option (-a)
71 * sntp broadcast:: broadcast option (-b)
72 * sntp concurrent:: concurrent option (-c)
73 * sntp gap:: gap option (-g)
74 * sntp kod:: kod option (-K)
75 * sntp keyfile:: keyfile option (-k)
76 * sntp logfile:: logfile option (-l)
77 * sntp steplimit:: steplimit option (-M)
78 * sntp ntpversion:: ntpversion option (-o)
79 * sntp usereservedport:: usereservedport option (-r)
80 * sntp timeout:: timeout option (-t)
81 * sntp wait:: wait option
82 * sntp config:: presetting/configuring sntp
83 * sntp exit status:: exit status
84 * sntp Usage:: Usage
85 * sntp Authors:: Authors
86 @end menu
87
88 @node sntp usage
89 @subsection sntp help/usage (@option{--help})
90 @cindex sntp help
91
92 This is the automatically generated usage text for sntp.
93
94 The text printed is the same whether selected with the @code{help} option
95 (@option{--help}) or the @code{more-help} option (@option{--more-help}). @code{more-help} will print
96 the usage text by passing it through a pager program.
97 @code{more-help} is disabled on platforms without a working
98 @code{fork(2)} function. The @code{PAGER} environment variable is
99 used to select the program, defaulting to @file{more}. Both will exit
100 with a status code of 0.
101
102 @exampleindent 0
103 @example
104 sntp - standard Simple Network Time Protocol client program - Ver. 4.2.8p15
105 Usage: sntp [ -<flag> [<val>] | --<name>[@{=| @}<val>] ]... \
106 [ hostname-or-IP ...]
107 Flg Arg Option-Name Description
108 -4 no ipv4 Force IPv4 DNS name resolution
109 - prohibits the option 'ipv6'
110 -6 no ipv6 Force IPv6 DNS name resolution
111 - prohibits the option 'ipv4'
112 -a Num authentication Enable authentication with the key auth-keynumber
113 -b Str broadcast Listen to the address specified for broadcast time sync
114 - may appear multiple times
115 -c Str concurrent Concurrently query all IPs returned for host-name
116 - may appear multiple times
117 -d no debug-level Increase debug verbosity level
118 - may appear multiple times
119 -D Num set-debug-level Set the debug verbosity level
120 - may appear multiple times
121 -g Num gap The gap (in milliseconds) between time requests
122 -K Fil kod KoD history filename
123 -k Fil keyfile Look in this file for the key specified with -a
124 -l Fil logfile Log to specified logfile
125 -M Num steplimit Adjustments less than steplimit msec will be slewed
126 - it must be in the range:
127 greater than or equal to 0
128 -o Num ntpversion Send int as our NTP protocol version
129 - it must be in the range:
130 0 to 7
131 -r no usereservedport Use the NTP Reserved Port (port 123)
132 -S no step OK to 'step' the time with settimeofday(2)
133 -s no slew OK to 'slew' the time with adjtime(2)
134 -t Num timeout The number of seconds to wait for responses
135 no wait Wait for pending replies (if not setting the time)
136 - disabled as '--no-wait'
137 - enabled by default
138 opt version output version information and exit
139 -? no help display extended usage information and exit
140 -! no more-help extended usage information passed thru pager
141 -> opt save-opts save the option state to a config file
142 -< Str load-opts load options from a config file
143 - disabled as '--no-load-opts'
144 - may appear multiple times
145
146 Options are specified by doubled hyphens and their name or by a single
147 hyphen and the flag character.
148
149
150 The following option preset mechanisms are supported:
151 - reading file $HOME/.ntprc
152 - reading file ./.ntprc
153 - examining environment variables named SNTP_*
154
155 Please send bug reports to: <http://bugs.ntp.org, bugs@@ntp.org>
156 @end example
157 @exampleindent 4
158
159 @node sntp ipv4
160 @subsection ipv4 option (-4)
161 @cindex sntp-ipv4
162
163 This is the ``force ipv4 dns name resolution'' option.
164
165 @noindent
166 This option has some usage constraints. It:
167 @itemize @bullet
168 @item
169 must not appear in combination with any of the following options:
170 ipv6.
171 @end itemize
172
173 Force DNS resolution of the following host names on the command line
174 to the IPv4 namespace.
175 @node sntp ipv6
176 @subsection ipv6 option (-6)
177 @cindex sntp-ipv6
178
179 This is the ``force ipv6 dns name resolution'' option.
180
181 @noindent
182 This option has some usage constraints. It:
183 @itemize @bullet
184 @item
185 must not appear in combination with any of the following options:
186 ipv4.
187 @end itemize
188
189 Force DNS resolution of the following host names on the command line
190 to the IPv6 namespace.
191 @node sntp authentication
192 @subsection authentication option (-a)
193 @cindex sntp-authentication
194
195 This is the ``enable authentication with the key @var{auth-keynumber}'' option.
196 This option takes a number argument @file{auth-keynumber}.
197 Enable authentication using the key specified in this option's
198 argument. The argument of this option is the @option{keyid}, a
199 number specified in the @option{keyfile} as this key's identifier.
200 See the @option{keyfile} option (@option{-k}) for more details.
201 @node sntp broadcast
202 @subsection broadcast option (-b)
203 @cindex sntp-broadcast
204
205 This is the ``listen to the address specified for broadcast time sync'' option.
206 This option takes a string argument @file{broadcast-address}.
207
208 @noindent
209 This option has some usage constraints. It:
210 @itemize @bullet
211 @item
212 may appear an unlimited number of times.
213 @end itemize
214
215 If specified @code{sntp} will listen to the specified address
216 for NTP broadcasts. The default maximum wait time
217 can (and probably should) be modified with @option{-t}.
218 @node sntp concurrent
219 @subsection concurrent option (-c)
220 @cindex sntp-concurrent
221
222 This is the ``concurrently query all ips returned for host-name'' option.
223 This option takes a string argument @file{host-name}.
224
225 @noindent
226 This option has some usage constraints. It:
227 @itemize @bullet
228 @item
229 may appear an unlimited number of times.
230 @end itemize
231
232 Requests from an NTP "client" to a "server" should never be sent
233 more rapidly than one every 2 seconds. By default, any IPs returned
234 as part of a DNS lookup are assumed to be for a single instance of
235 @code{ntpd}, and therefore @code{sntp} will send queries to these IPs
236 one after another, with a 2-second gap in between each query.
237
238 The @option{-c} or @option{--concurrent} flag says that any IPs
239 returned for the DNS lookup of the supplied host-name are on
240 different machines, so we can send concurrent queries.
241 @node sntp gap
242 @subsection gap option (-g)
243 @cindex sntp-gap
244
245 This is the ``the gap (in milliseconds) between time requests'' option.
246 This option takes a number argument @file{milliseconds}.
247 Since we're only going to use the first valid response we get and
248 there is benefit to specifying a good number of servers to query,
249 separate the queries we send out by the specified number of
250 milliseconds.
251 @node sntp kod
252 @subsection kod option (-K)
253 @cindex sntp-kod
254
255 This is the ``kod history filename'' option.
256 This option takes a file argument @file{file-name}.
257 Specifies the filename to be used for the persistent history of KoD
258 responses received from servers. If the file does not exist, a
259 warning message will be displayed. The file will not be created.
260 @node sntp keyfile
261 @subsection keyfile option (-k)
262 @cindex sntp-keyfile
263
264 This is the ``look in this file for the key specified with @option{-a}'' option.
265 This option takes a file argument @file{file-name}.
266 This option specifies the keyfile.
267 @code{sntp} will search for the key specified with @option{-a}
268 @file{keyno} in this file. See @command{ntp.keys(5)} for more
269 information.
270 @node sntp logfile
271 @subsection logfile option (-l)
272 @cindex sntp-logfile
273
274 This is the ``log to specified logfile'' option.
275 This option takes a file argument @file{file-name}.
276 This option causes the client to write log messages to the specified
277 @file{logfile}.
278 @node sntp steplimit
279 @subsection steplimit option (-M)
280 @cindex sntp-steplimit
281
282 This is the ``adjustments less than @var{steplimit} msec will be slewed'' option.
283 This option takes a number argument.
284 If the time adjustment is less than @file{steplimit} milliseconds,
285 slew the amount using @command{adjtime(2)}. Otherwise, step the
286 correction using @command{settimeofday(2)}. The default value is 0,
287 which means all adjustments will be stepped. This is a feature, as
288 different situations demand different values.
289 @node sntp ntpversion
290 @subsection ntpversion option (-o)
291 @cindex sntp-ntpversion
292
293 This is the ``send @var{int} as our ntp protocol version'' option.
294 This option takes a number argument.
295 When sending requests to a remote server, tell them we are running
296 NTP protocol version @file{ntpversion} .
297 @node sntp usereservedport
298 @subsection usereservedport option (-r)
299 @cindex sntp-usereservedport
300
301 This is the ``use the ntp reserved port (port 123)'' option.
302 Use port 123, which is reserved for NTP, for our network
303 communications.
304 @node sntp timeout
305 @subsection timeout option (-t)
306 @cindex sntp-timeout
307
308 This is the ``the number of seconds to wait for responses'' option.
309 This option takes a number argument @file{seconds}.
310 When waiting for a reply, @code{sntp} will wait the number
311 of seconds specified before giving up. The default should be
312 more than enough for a unicast response. If @code{sntp} is
313 only waiting for a broadcast response a longer timeout is
314 likely needed.
315 @node sntp wait
316 @subsection wait option
317 @cindex sntp-wait
318
319 This is the ``wait for pending replies (if not setting the time)'' option.
320
321 @noindent
322 This option has some usage constraints. It:
323 @itemize @bullet
324 @item
325 can be disabled with --no-wait.
326 @item
327 It is enabled by default.
328 @end itemize
329
330 If we are not setting the time, wait for all pending responses.
331
332
333 @node sntp config
334 @subsection presetting/configuring sntp
335
336 Any option that is not marked as @i{not presettable} may be preset by
337 loading values from configuration ("rc" or "ini") files, and values from environment variables named @code{SNTP} and @code{SNTP_<OPTION_NAME>}. @code{<OPTION_NAME>} must be one of
338 the options listed above in upper case and segmented with underscores.
339 The @code{SNTP} variable will be tokenized and parsed like
340 the command line. The remaining variables are tested for existence and their
341 values are treated like option arguments.
342
343
344 @noindent
345 @code{libopts} will search in 2 places for configuration files:
346 @itemize @bullet
347 @item
348 $HOME
349 @item
350 $PWD
351 @end itemize
352 The environment variables @code{HOME}, and @code{PWD}
353 are expanded and replaced when @file{sntp} runs.
354 For any of these that are plain files, they are simply processed.
355 For any that are directories, then a file named @file{.ntprc} is searched for
356 within that directory and processed.
357
358 Configuration files may be in a wide variety of formats.
359 The basic format is an option name followed by a value (argument) on the
360 same line. Values may be separated from the option name with a colon,
361 equal sign or simply white space. Values may be continued across multiple
362 lines by escaping the newline with a backslash.
363
364 Multiple programs may also share the same initialization file.
365 Common options are collected at the top, followed by program specific
366 segments. The segments are separated by lines like:
367 @example
368 [SNTP]
369 @end example
370 @noindent
371 or by
372 @example
373 <?program sntp>
374 @end example
375 @noindent
376 Do not mix these styles within one configuration file.
377
378 Compound values and carefully constructed string values may also be
379 specified using XML syntax:
380 @example
381 <option-name>
382 <sub-opt>...<...>...</sub-opt>
383 </option-name>
384 @end example
385 @noindent
386 yielding an @code{option-name.sub-opt} string value of
387 @example
388 "...<...>..."
389 @end example
390 @code{AutoOpts} does not track suboptions. You simply note that it is a
391 hierarchicly valued option. @code{AutoOpts} does provide a means for searching
392 the associated name/value pair list (see: optionFindValue).
393
394 The command line options relating to configuration and/or usage help are:
395
396 @subsubheading version (-)
397
398 Print the program version to standard out, optionally with licensing
399 information, then exit 0. The optional argument specifies how much licensing
400 detail to provide. The default is to print just the version. The licensing infomation may be selected with an option argument.
401 Only the first letter of the argument is examined:
402
403 @table @samp
404 @item version
405 Only print the version. This is the default.
406 @item copyright
407 Name the copyright usage licensing terms.
408 @item verbose
409 Print the full copyright usage licensing terms.
410 @end table
411
412 @node sntp exit status
413 @subsection sntp exit status
414
415 One of the following exit values will be returned:
416 @table @samp
417 @item 0 (EXIT_SUCCESS)
418 Successful program execution.
419 @item 1 (EXIT_FAILURE)
420 The operation failed or the command syntax was not valid.
421 @item 66 (EX_NOINPUT)
422 A specified configuration file could not be loaded.
423 @item 70 (EX_SOFTWARE)
424 libopts had an internal operational error. Please report
425 it to autogen-users@@lists.sourceforge.net. Thank you.
426 @end table
427 @node sntp Usage
428 @subsection sntp Usage
429 @node sntp Authors
430 @subsection sntp Authors