/contrib/ntp/sntp/sntp.1

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