| blob | 20c7d801646cf71487b3bae8bb55eb5db4554f24 |
1 .TH SNTP 1 2009-12-08 "( 4.2.4p8)" "Programmer's Manual"
2 .\" EDIT THIS FILE WITH CAUTION (sntp.1)
3 .\"
4 .\" It has been AutoGen-ed Tuesday December 8, 2009 at 08:14:50 AM EST
5 .\" From the definitions sntp-opts.def
6 .\" and the template file agman1.tpl
7 .\"
8 .SH NAME
9 sntp \- standard SNTP program
10 .SH SYNOPSIS
11 .B sntp
12 .\" Mixture of short (flag) options and long options
13 .RB [ \-\fIflag\fP " [\fIvalue\fP]]... [" \--\fIopt-name\fP " [[=| ]\fIvalue\fP]]..."
14 .PP
15 All arguments must be options.
16 .SH "DESCRIPTION"
17 This manual page documents, briefly, the \fBsntp\fP command.
18 .I sntp
19 can be used as a SNTP client to query a NTP or SNTP server and either display
20 the time or set the local system's time (given suitable privilege). It can be
21 run as an interactive command or in a
22 .I cron
23 job.
24 NTP is the Network Time Protocol (RFC 1305) and SNTP is the
25 Simple Network Time Protocol (RFC 2030, which supersedes RFC 1769).
26 .SS Options
27 .PP
28 .I sntp
29 recognizes the following options:
30 .TP
31 .B \-v
32 indicates that diagnostic messages for non-fatal errors and a limited amount of
33 tracing should be written to standard error. Fatal ones always produce a
34 diagnostic. This option should be set when there is a suspected problem with
35 the server, network or the source.
36 .TP
37 .B \-V
38 requests more and less comprehensible output, mainly for investigating problems
39 with apparently inconsistent timestamps. This option should be set when the
40 program fails with a message indicating that is the trouble.
41 .TP
42 .B \-W
43 requests very verbose debugging output, and will interfere with the timing
44 when writing to the terminal (because of line buffered output from C). Note
45 that the times produced by this are the corrections needed, and not the error
46 in the local clock. This option should be set only when debugging the source.
47 .TP
48 .B \-q
49 indicates that it should query a daemon save file being maintained by it.
50 This needs no privilege and will change neither the save file nor the clock.
51 .PP
52 The default is that it should behave as a client, and the following options
53 are then relevant:
54 .TP
55 .B \-r
56 indicates that the system clock should be reset by
57 .IR settimeofday .
58 Naturally, this will work only if the user has enough privilege.
59 .TP
60 .B \-a
61 indicates that the system clock should be reset by
62 .IR adjtime .
63 Naturally, this will work only if the user has enough privilege.
64 .PP
65 The default is to write the estimated correct local date and time (i.e. not
66 UTC) to the standard output in a format like
67 .BR "'1996 Oct 15 20:17:25.123 + 4.567 +/- 0.089 secs'" ,
68 where the
69 .B "'+ 4.567 +/- 0.089 secs'"
70 indicates the estimated error in the time on the local system.
71 .TP
72 .BI \-l " lockfile"
73 sets the name of the lock file to ensure that there is only
74 one copy of
75 .I sntp
76 running at once. The default is installation-dependent, but will usually be
77 .IR /etc/sntp.pid .
78 .TP
79 .BI \-e " minerr"
80 sets the maximum ignorable variation between the clocks to
81 .IR minerr .
82 Acceptable values are from 0.001 to 1, and the default is 0.1 if a NTP host is
83 is specified and 0.5 otherwise.
84 .TP
85 .BI \-E " maxerr"
86 sets the maximum value of various delays that are deemed acceptable to
87 .IR maxerr .
88 Acceptable values are from 1 to 60, and the default is 5. It should sometimes
89 be increased if there are problems with the network, NTP server or system
90 clock, but take care.
91 .TP
92 .BI \-P " prompt"
93 sets the maximum clock change that will be made automatically to
94 .IR maxerr .
95 Acceptable values are from 1 to 3600 or
96 .IR no ,
97 and the default is 30. If the program is being run interactively in ordinary
98 client mode, and the system clock is to be changed, larger corrections will
99 prompt the user for confirmation. Specifying
100 .I no
101 will disable this and the correction will be made regardless.
102 .TP
103 .BI \-c " count"
104 sets the maximum number of NTP packets required to
105 .IR count .
106 Acceptable values are from 1 to 25 if a NTP host is specified and from 5 to 25
107 otherwise, and the default is 5. If the maximum isn't enough, the system needs
108 a better consistency algorithm than this program uses.
109 .TP
110 .BI \-d " delay"
111 sets a rough limit on the total running time to
112 .I delay
113 seconds. Acceptable values are from 1 to 3600, and the default is 15 if a NTP
114 host is specified and 300 otherwise.
115 .TP
116 .B \-4
117 force IPv4 DNS resolution.
118 .TP
119 .B \-6
120 force IPv6 DNS resolution.
121 .PP
122 .B address(es)
123 are the DNS names or IP numbers of hosts to use for the challenge and response
124 protocol; if no names are given, the program waits for broadcasts. Polling a
125 server is vastly more reliable than listening to broadcasts. Note that a
126 single component numeric address is not allowed, to avoid ambiguities. If
127 more than one name is give, they will be used in a round-robin fashion.
128 .PP
129 Constraints:
130 .IP
131 .B minerr
132 must be less than
133 .B maxerr
134 which must be less than
135 .B delay
136 (or, if a NTP host is not specified
137 .BR delay / count "),"
138 and
139 .B count
140 must be less than half of
141 .BR delay .
142 .IP
143 In update mode,
144 .B maxerr
145 must be less than
146 .BR prompt.
147 .PP
148 Note that none of the above values are closely linked to the limits described
149 in the NTP protocol (RFC 1305).
150 .SH USAGE
151 The simplest use of this program is as an unprivileged command to check the
152 current time and error in the local clock. For example:
153 .IP
154 .B sntp ntpserver.somewhere
155 .PP
156 With suitable privilege, it can be run as a command or in a
157 .I cron
158 job to reset the local clock from a reliable server, like the
159 .I ntpdate
160 and
161 .I rdate
162 commands. For example:
163 .IP
164 .B sntp \-a ntpserver.somewhere
165 .PP
166 More information on how to use this utility is given in the
167 .I README
168 file in the distribution. In particular, this
169 .I man
170 page does not describe how to set it up as a server, which needs special care
171 to avoid propagating misinformation.
172 .SH RETURN VALUE
173 When used as a client in non-daemon mode, the program returns a zero exit
174 status for success, and a non-zero one otherwise. When used as a daemon
175 (either client or server), it does not return except after a serious error.
176 .SH BUGS
177 The program implements the SNTP protocol, and does not provide all NTP
178 facilities. In particular, it contains no checks against any form of spoofing.
179 If this is a serious concern, some network security mechanism (like a firewall
180 or even just
181 .IR tcpwrappers )
182 should be installed.
183 .PP
184 There are some errors, ambiguities and inconsistencies in the RFCs, and this
185 code may not interwork with all other NTP implementations. Any unreasonable
186 restrictions should be reported as bugs to whoever is responsible. It may
187 be difficult to find out who that is.
188 .PP
189 The program will stop as soon as it feels that things have got out of control.
190 In client daemon mode, it will usually fail during an extended period of
191 network or server inaccessibility or excessively slow performance, or when the
192 local clock is reset by another process. It will then need restarting
193 manually. Experienced system administrators can write a shell script, a
194 .I cron
195 job or put it in
196 .IR inittab ,
197 to do this automatically.
198 .PP
199 The error cannot be estimated reliably with broadcast packets or for the drift
200 in daemon mode (even with client-server packets), and the guess made by the
201 program may be wrong (possibly even very wrong). If this is a problem, then
202 setting the
203 .B \-c
204 option to a larger value may help. Or it may not.
205 .SH AUTHOR
206 .I sntp
207 was developed by N.M. Maclaren of the University of Cambridge Computing
208 Service.
209 .SH OPTIONS
210 .TP
211 .BR \-4 ", " \--ipv4
212 Force IPv4 DNS name resolution.
213 This option is a member of the ipv4 class of options.
214 .sp
215 Force DNS resolution of following host names on the command line
216 to the IPv4 namespace.
217 .TP
218 .BR \-6 ", " \--ipv6
219 Force IPv6 DNS name resolution.
220 This option is a member of the ipv4 class of options.
221 .sp
222 Force DNS resolution of following host names on the command line
223 to the IPv6 namespace.
224 .TP
225 .BR \-u ", " \--unprivport
226 Use an unprivileged port.
227 .sp
228 Use an unprivilegded UDP port for our queries.
229 .TP
230 .BR \-v ", " \--normalverbose
231 Slightly verbose.
232 This option must not appear in combination with any of the following options:
233 extraverbose, megaverbose.
234 .sp
235 Diagnostic messages for non-fatal errors and a limited amount of
236 tracing should be written to standard error. Fatal ones always
237 produce a diagnostic. This option should be set when there is a
238 suspected problem with the server, network or the source.
239 .TP
240 .BR \-V ", " \--extraverbose
241 Extra verbose.
242 This option must not appear in combination with any of the following options:
243 normalverbose, megaverbose.
244 .sp
245 Produce more and less comprehensible output, mainly for investigating
246 problems with apparently inconsistent timestamps. This option should
247 be set when the program fails with a message indicating that is the
248 trouble.
249 .TP
250 .BR \-W ", " \--megaverbose
251 Mega verbose.
252 This option must not appear in combination with any of the following options:
253 normalverbose, extraverbose.
254 .sp
255 Very verbose debugging output that will interfere with the timing
256 when writing to the terminal (because of line buffered output from C).
257 Note that the times produced by this are the corrections needed, and
258 not the error in the local clock. This option should be set only when
259 debugging the source.
260 .TP
261 .BR \-r ", " \--settimeofday
262 Set (step) the time with settimeofday().
263 This option must not appear in combination with any of the following options:
264 adjtime.
265 .sp
267 .TP
268 .BR \-a ", " \--adjtime
269 Set (slew) the time with adjtime().
270 This option must not appear in combination with any of the following options:
271 settimeofday.
272 .sp
274 .TP
275 .BR \-? , " \--help"
276 Display usage information and exit.
277 .TP
278 .BR \-! , " \--more-help"
279 Extended usage information passed thru pager.
280 .TP
281 .BR \-> " [\fIrcfile\fP]," " \--save-opts" "[=\fIrcfile\fP]"
282 Save the option state to \fIrcfile\fP. The default is the \fIlast\fP
283 configuration file listed in the \fBOPTION PRESETS\fP section, below.
284 .TP
285 .BR \-< " \fIrcfile\fP," " \--load-opts" "=\fIrcfile\fP," " \--no-load-opts"
286 Load options from \fIrcfile\fP.
287 The \fIno-load-opts\fP form will disable the loading
288 of earlier RC/INI files. \fI--no-load-opts\fP is handled early,
289 out of order.
290 .TP
291 .BR \-v " [{\fIv|c|n\fP}]," " \--version" "[=\fI{v|c|n}\fP]"
292 Output version of program and exit. The default mode is `v', a simple
293 version. The `c' mode will print copyright information and `n' will
294 print the full copyright notice.
295 .SH OPTION PRESETS
296 Any option that is not marked as \fInot presettable\fP may be preset
297 by loading values from configuration ("RC" or ".INI") file(s) and values from
298 environment variables named:
299 .nf
300 \fBSNTP_<option-name>\fP or \fBSNTP\fP
301 .fi
302 .aj
303 The environmental presets take precedence (are processed later than)
304 the configuration files.
305 The \fIhomerc\fP files are "\fI$HOME\fP", and "\fI.\fP".
306 If any of these are directories, then the file \fI.ntprc\fP
307 is searched for within those directories.
308 .SH AUTHOR
309 ntp.org
310 .br
311 Please send bug reports to: http://bugs.ntp.org, bugs@ntp.org
313 .PP
314 .nf
315 .na
316 General Public Licence for the software known as MSNTP
317 \------------------------------------------------------
319 (c) Copyright, N.M. Maclaren, 1996, 1997, 2000
320 (c) Copyright, University of Cambridge, 1996, 1997, 2000
324 Free use of MSNTP in source and binary forms is permitted, provided that this
325 entire licence is duplicated in all copies, and that any documentation,
326 announcements, and other materials related to use acknowledge that the software
327 was developed by N.M. Maclaren (hereafter refered to as the Author) at the
328 University of Cambridge. Neither the name of the Author nor the University of
329 Cambridge may be used to endorse or promote products derived from this material
330 without specific prior written permission.
332 The Author and the University of Cambridge retain the copyright and all other
333 legal rights to the software and make it available non-exclusively. All users
334 must ensure that the software in all its derivations carries a copyright notice
335 in the form:
336 (c) Copyright N.M. Maclaren,
337 (c) Copyright University of Cambridge.
341 NO WARRANTY
343 Because the MSNTP software is licensed free of charge, the Author and the
344 University of Cambridge provide absolutely no warranty, either expressed or
345 implied, including, but not limited to, the implied warranties of
346 merchantability and fitness for a particular purpose. The entire risk as to
347 the quality and performance of the MSNTP software is with you. Should MSNTP
348 prove defective, you assume the cost of all necessary servicing or repair.
350 In no event, unless required by law, will the Author or the University of
351 Cambridge, or any other party who may modify and redistribute this software as
352 permitted in accordance with the provisions below, be liable for damages for
353 any losses whatsoever, including but not limited to lost profits, lost monies,
354 lost or corrupted data, or other special, incidental or consequential losses
355 that may arise out of the use or inability to use the MSNTP software.
359 COPYING POLICY
361 Permission is hereby granted for copying and distribution of copies of the
362 MSNTP source and binary files, and of any part thereof, subject to the
363 following licence conditions:
365 1. You may distribute MSNTP or components of MSNTP, with or without additions
366 developed by you or by others. No charge, other than an "at-cost" distribution
367 fee, may be charged for copies, derivations, or distributions of this material
368 without the express written consent of the copyright holders.
370 2. You may also distribute MSNTP along with any other product for sale,
371 provided that the cost of the bundled package is the same regardless of whether
372 MSNTP is included or not, and provided that those interested only in MSNTP must
373 be notified that it is a product freely available from the University of
374 Cambridge.
376 3. If you distribute MSNTP software or parts of MSNTP, with or without
377 additions developed by you or others, then you must either make available the
378 source to all portions of the MSNTP system (exclusive of any additions made by
379 you or by others) upon request, or instead you may notify anyone requesting
380 source that it is freely available from the University of Cambridge.
382 4. You may not omit any of the copyright notices on either the source files,
383 the executable files, or the documentation.
385 5. You may not omit transmission of this License agreement with whatever
386 portions of MSNTP that are distributed.
388 6. Any users of this software must be notified that it is without warranty or
389 guarantee of any nature, express or implied, nor is there any fitness for use
390 represented.
393 October 1996
394 April 1997
395 October 2000
396 .fi
397 .ad
398 .PP
399 This manual page was \fIAutoGen\fP-erated from the \fBsntp\fP
400 option definitions.