401 lines
14 KiB
Groff
401 lines
14 KiB
Groff
.TH SNTP 1 2008-08-17 "( 4.2.4p5)" "Programmer's Manual"
|
|
.\" EDIT THIS FILE WITH CAUTION (sntp.1)
|
|
.\"
|
|
.\" It has been AutoGen-ed Sunday August 17, 2008 at 05:27:25 AM EDT
|
|
.\" From the definitions sntp-opts.def
|
|
.\" and the template file agman1.tpl
|
|
.\"
|
|
.SH NAME
|
|
sntp \- standard SNTP program
|
|
.SH SYNOPSIS
|
|
.B sntp
|
|
.\" Mixture of short (flag) options and long options
|
|
.RB [ \-\fIflag\fP " [\fIvalue\fP]]... [" \--\fIopt-name\fP " [[=| ]\fIvalue\fP]]..."
|
|
.PP
|
|
All arguments must be options.
|
|
.SH "DESCRIPTION"
|
|
This manual page documents, briefly, the \fBsntp\fP command.
|
|
.I sntp
|
|
can be used as a SNTP client to query a NTP or SNTP server and either display
|
|
the time or set the local system's time (given suitable privilege). It can be
|
|
run as an interactive command or in a
|
|
.I cron
|
|
job.
|
|
NTP is the Network Time Protocol (RFC 1305) and SNTP is the
|
|
Simple Network Time Protocol (RFC 2030, which supersedes RFC 1769).
|
|
.SS Options
|
|
.PP
|
|
.I sntp
|
|
recognizes the following options:
|
|
.TP
|
|
.B \-v
|
|
indicates that diagnostic messages for non-fatal errors and a limited amount of
|
|
tracing should be written to standard error. Fatal ones always produce a
|
|
diagnostic. This option should be set when there is a suspected problem with
|
|
the server, network or the source.
|
|
.TP
|
|
.B \-V
|
|
requests more and less comprehensible output, mainly for investigating problems
|
|
with apparently inconsistent timestamps. This option should be set when the
|
|
program fails with a message indicating that is the trouble.
|
|
.TP
|
|
.B \-W
|
|
requests very verbose debugging output, and will interfere with the timing
|
|
when writing to the terminal (because of line buffered output from C). Note
|
|
that the times produced by this are the corrections needed, and not the error
|
|
in the local clock. This option should be set only when debugging the source.
|
|
.TP
|
|
.B \-q
|
|
indicates that it should query a daemon save file being maintained by it.
|
|
This needs no privilege and will change neither the save file nor the clock.
|
|
.PP
|
|
The default is that it should behave as a client, and the following options
|
|
are then relevant:
|
|
.TP
|
|
.B \-r
|
|
indicates that the system clock should be reset by
|
|
.IR settimeofday .
|
|
Naturally, this will work only if the user has enough privilege.
|
|
.TP
|
|
.B \-a
|
|
indicates that the system clock should be reset by
|
|
.IR adjtime .
|
|
Naturally, this will work only if the user has enough privilege.
|
|
.PP
|
|
The default is to write the estimated correct local date and time (i.e. not
|
|
UTC) to the standard output in a format like
|
|
.BR "'1996 Oct 15 20:17:25.123 + 4.567 +/- 0.089 secs'" ,
|
|
where the
|
|
.B "'+ 4.567 +/- 0.089 secs'"
|
|
indicates the estimated error in the time on the local system.
|
|
.TP
|
|
.BI \-l " lockfile"
|
|
sets the name of the lock file to ensure that there is only
|
|
one copy of
|
|
.I sntp
|
|
running at once. The default is installation-dependent, but will usually be
|
|
.IR /etc/sntp.pid .
|
|
.TP
|
|
.BI \-e " minerr"
|
|
sets the maximum ignorable variation between the clocks to
|
|
.IR minerr .
|
|
Acceptable values are from 0.001 to 1, and the default is 0.1 if a NTP host is
|
|
is specified and 0.5 otherwise.
|
|
.TP
|
|
.BI \-E " maxerr"
|
|
sets the maximum value of various delays that are deemed acceptable to
|
|
.IR maxerr .
|
|
Acceptable values are from 1 to 60, and the default is 5. It should sometimes
|
|
be increased if there are problems with the network, NTP server or system
|
|
clock, but take care.
|
|
.TP
|
|
.BI \-P " prompt"
|
|
sets the maximum clock change that will be made automatically to
|
|
.IR maxerr .
|
|
Acceptable values are from 1 to 3600 or
|
|
.IR no ,
|
|
and the default is 30. If the program is being run interactively in ordinary
|
|
client mode, and the system clock is to be changed, larger corrections will
|
|
prompt the user for confirmation. Specifying
|
|
.I no
|
|
will disable this and the correction will be made regardless.
|
|
.TP
|
|
.BI \-c " count"
|
|
sets the maximum number of NTP packets required to
|
|
.IR count .
|
|
Acceptable values are from 1 to 25 if a NTP host is specified and from 5 to 25
|
|
otherwise, and the default is 5. If the maximum isn't enough, the system needs
|
|
a better consistency algorithm than this program uses.
|
|
.TP
|
|
.BI \-d " delay"
|
|
sets a rough limit on the total running time to
|
|
.I delay
|
|
seconds. Acceptable values are from 1 to 3600, and the default is 15 if a NTP
|
|
host is specified and 300 otherwise.
|
|
.TP
|
|
.B \-4
|
|
force IPv4 DNS resolution.
|
|
.TP
|
|
.B \-6
|
|
force IPv6 DNS resolution.
|
|
.PP
|
|
.B address(es)
|
|
are the DNS names or IP numbers of hosts to use for the challenge and response
|
|
protocol; if no names are given, the program waits for broadcasts. Polling a
|
|
server is vastly more reliable than listening to broadcasts. Note that a
|
|
single component numeric address is not allowed, to avoid ambiguities. If
|
|
more than one name is give, they will be used in a round-robin fashion.
|
|
.PP
|
|
Constraints:
|
|
.IP
|
|
.B minerr
|
|
must be less than
|
|
.B maxerr
|
|
which must be less than
|
|
.B delay
|
|
(or, if a NTP host is not specified
|
|
.BR delay / count "),"
|
|
and
|
|
.B count
|
|
must be less than half of
|
|
.BR delay .
|
|
.IP
|
|
In update mode,
|
|
.B maxerr
|
|
must be less than
|
|
.BR prompt.
|
|
.PP
|
|
Note that none of the above values are closely linked to the limits described
|
|
in the NTP protocol (RFC 1305).
|
|
.SH USAGE
|
|
The simplest use of this program is as an unprivileged command to check the
|
|
current time and error in the local clock. For example:
|
|
.IP
|
|
.B sntp ntpserver.somewhere
|
|
.PP
|
|
With suitable privilege, it can be run as a command or in a
|
|
.I cron
|
|
job to reset the local clock from a reliable server, like the
|
|
.I ntpdate
|
|
and
|
|
.I rdate
|
|
commands. For example:
|
|
.IP
|
|
.B sntp \-a ntpserver.somewhere
|
|
.PP
|
|
More information on how to use this utility is given in the
|
|
.I README
|
|
file in the distribution. In particular, this
|
|
.I man
|
|
page does not describe how to set it up as a server, which needs special care
|
|
to avoid propagating misinformation.
|
|
.SH RETURN VALUE
|
|
When used as a client in non-daemon mode, the program returns a zero exit
|
|
status for success, and a non-zero one otherwise. When used as a daemon
|
|
(either client or server), it does not return except after a serious error.
|
|
.SH BUGS
|
|
The program implements the SNTP protocol, and does not provide all NTP
|
|
facilities. In particular, it contains no checks against any form of spoofing.
|
|
If this is a serious concern, some network security mechanism (like a firewall
|
|
or even just
|
|
.IR tcpwrappers )
|
|
should be installed.
|
|
.PP
|
|
There are some errors, ambiguities and inconsistencies in the RFCs, and this
|
|
code may not interwork with all other NTP implementations. Any unreasonable
|
|
restrictions should be reported as bugs to whoever is responsible. It may
|
|
be difficult to find out who that is.
|
|
.PP
|
|
The program will stop as soon as it feels that things have got out of control.
|
|
In client daemon mode, it will usually fail during an extended period of
|
|
network or server inaccessibility or excessively slow performance, or when the
|
|
local clock is reset by another process. It will then need restarting
|
|
manually. Experienced system administrators can write a shell script, a
|
|
.I cron
|
|
job or put it in
|
|
.IR inittab ,
|
|
to do this automatically.
|
|
.PP
|
|
The error cannot be estimated reliably with broadcast packets or for the drift
|
|
in daemon mode (even with client-server packets), and the guess made by the
|
|
program may be wrong (possibly even very wrong). If this is a problem, then
|
|
setting the
|
|
.B \-c
|
|
option to a larger value may help. Or it may not.
|
|
.SH AUTHOR
|
|
.I sntp
|
|
was developed by N.M. Maclaren of the University of Cambridge Computing
|
|
Service.
|
|
.SH OPTIONS
|
|
.TP
|
|
.BR \-4 ", " \--ipv4
|
|
Force IPv4 DNS name resolution.
|
|
This option is a member of the ipv4 class of options.
|
|
.sp
|
|
Force DNS resolution of following host names on the command line
|
|
to the IPv4 namespace.
|
|
.TP
|
|
.BR \-6 ", " \--ipv6
|
|
Force IPv6 DNS name resolution.
|
|
This option is a member of the ipv4 class of options.
|
|
.sp
|
|
Force DNS resolution of following host names on the command line
|
|
to the IPv6 namespace.
|
|
.TP
|
|
.BR \-u ", " \--unprivport
|
|
Use an unprivileged port.
|
|
.sp
|
|
Use an unprivilegded UDP port for our queries.
|
|
.TP
|
|
.BR \-v ", " \--normalverbose
|
|
Slightly verbose.
|
|
This option must not appear in combination with any of the following options:
|
|
extraverbose, megaverbose.
|
|
.sp
|
|
Diagnostic messages for non-fatal errors and a limited amount of
|
|
tracing should be written to standard error. Fatal ones always
|
|
produce a diagnostic. This option should be set when there is a
|
|
suspected problem with the server, network or the source.
|
|
.TP
|
|
.BR \-V ", " \--extraverbose
|
|
Extra verbose.
|
|
This option must not appear in combination with any of the following options:
|
|
normalverbose, megaverbose.
|
|
.sp
|
|
Produce more and less comprehensible output, mainly for investigating
|
|
problems with apparently inconsistent timestamps. This option should
|
|
be set when the program fails with a message indicating that is the
|
|
trouble.
|
|
.TP
|
|
.BR \-W ", " \--megaverbose
|
|
Mega verbose.
|
|
This option must not appear in combination with any of the following options:
|
|
normalverbose, extraverbose.
|
|
.sp
|
|
Very verbose debugging output that will interfere with the timing
|
|
when writing to the terminal (because of line buffered output from C).
|
|
Note that the times produced by this are the corrections needed, and
|
|
not the error in the local clock. This option should be set only when
|
|
debugging the source.
|
|
.TP
|
|
.BR \-r ", " \--settimeofday
|
|
Set (step) the time with settimeofday().
|
|
This option must not appear in combination with any of the following options:
|
|
adjtime.
|
|
.sp
|
|
|
|
.TP
|
|
.BR \-a ", " \--adjtime
|
|
Set (slew) the time with adjtime().
|
|
This option must not appear in combination with any of the following options:
|
|
settimeofday.
|
|
.sp
|
|
|
|
.TP
|
|
.BR \-? , " \--help"
|
|
Display usage information and exit.
|
|
.TP
|
|
.BR \-! , " \--more-help"
|
|
Extended usage information passed thru pager.
|
|
.TP
|
|
.BR \-> " [\fIrcfile\fP]," " \--save-opts" "[=\fIrcfile\fP]"
|
|
Save the option state to \fIrcfile\fP. The default is the \fIlast\fP
|
|
configuration file listed in the \fBOPTION PRESETS\fP section, below.
|
|
.TP
|
|
.BR \-< " \fIrcfile\fP," " \--load-opts" "=\fIrcfile\fP," " \--no-load-opts"
|
|
Load options from \fIrcfile\fP.
|
|
The \fIno-load-opts\fP form will disable the loading
|
|
of earlier RC/INI files. \fI--no-load-opts\fP is handled early,
|
|
out of order.
|
|
.TP
|
|
.BR \-v " [{\fIv|c|n\fP}]," " \--version" "[=\fI{v|c|n}\fP]"
|
|
Output version of program and exit. The default mode is `v', a simple
|
|
version. The `c' mode will print copyright information and `n' will
|
|
print the full copyright notice.
|
|
.SH OPTION PRESETS
|
|
Any option that is not marked as \fInot presettable\fP may be preset
|
|
by loading values from configuration ("RC" or ".INI") file(s) and values from
|
|
environment variables named:
|
|
.nf
|
|
\fBSNTP_<option-name>\fP or \fBSNTP\fP
|
|
.fi
|
|
.aj
|
|
The environmental presets take precedence (are processed later than)
|
|
the configuration files.
|
|
The \fIhomerc\fP files are "\fI$HOME\fP", and "\fI.\fP".
|
|
If any of these are directories, then the file \fI.ntprc\fP
|
|
is searched for within those directories.
|
|
.SH AUTHOR
|
|
ntp.org
|
|
.br
|
|
Please send bug reports to: http://bugs.ntp.isc.org, bugs@ntp.org
|
|
|
|
.PP
|
|
.nf
|
|
.na
|
|
General Public Licence for the software known as MSNTP
|
|
\------------------------------------------------------
|
|
|
|
(c) Copyright, N.M. Maclaren, 1996, 1997, 2000
|
|
(c) Copyright, University of Cambridge, 1996, 1997, 2000
|
|
|
|
|
|
|
|
Free use of MSNTP in source and binary forms is permitted, provided that this
|
|
entire licence is duplicated in all copies, and that any documentation,
|
|
announcements, and other materials related to use acknowledge that the software
|
|
was developed by N.M. Maclaren (hereafter refered to as the Author) at the
|
|
University of Cambridge. Neither the name of the Author nor the University of
|
|
Cambridge may be used to endorse or promote products derived from this material
|
|
without specific prior written permission.
|
|
|
|
The Author and the University of Cambridge retain the copyright and all other
|
|
legal rights to the software and make it available non-exclusively. All users
|
|
must ensure that the software in all its derivations carries a copyright notice
|
|
in the form:
|
|
(c) Copyright N.M. Maclaren,
|
|
(c) Copyright University of Cambridge.
|
|
|
|
|
|
|
|
NO WARRANTY
|
|
|
|
Because the MSNTP software is licensed free of charge, the Author and the
|
|
University of Cambridge provide absolutely no warranty, either expressed or
|
|
implied, including, but not limited to, the implied warranties of
|
|
merchantability and fitness for a particular purpose. The entire risk as to
|
|
the quality and performance of the MSNTP software is with you. Should MSNTP
|
|
prove defective, you assume the cost of all necessary servicing or repair.
|
|
|
|
In no event, unless required by law, will the Author or the University of
|
|
Cambridge, or any other party who may modify and redistribute this software as
|
|
permitted in accordance with the provisions below, be liable for damages for
|
|
any losses whatsoever, including but not limited to lost profits, lost monies,
|
|
lost or corrupted data, or other special, incidental or consequential losses
|
|
that may arise out of the use or inability to use the MSNTP software.
|
|
|
|
|
|
|
|
COPYING POLICY
|
|
|
|
Permission is hereby granted for copying and distribution of copies of the
|
|
MSNTP source and binary files, and of any part thereof, subject to the
|
|
following licence conditions:
|
|
|
|
1. You may distribute MSNTP or components of MSNTP, with or without additions
|
|
developed by you or by others. No charge, other than an "at-cost" distribution
|
|
fee, may be charged for copies, derivations, or distributions of this material
|
|
without the express written consent of the copyright holders.
|
|
|
|
2. You may also distribute MSNTP along with any other product for sale,
|
|
provided that the cost of the bundled package is the same regardless of whether
|
|
MSNTP is included or not, and provided that those interested only in MSNTP must
|
|
be notified that it is a product freely available from the University of
|
|
Cambridge.
|
|
|
|
3. If you distribute MSNTP software or parts of MSNTP, with or without
|
|
additions developed by you or others, then you must either make available the
|
|
source to all portions of the MSNTP system (exclusive of any additions made by
|
|
you or by others) upon request, or instead you may notify anyone requesting
|
|
source that it is freely available from the University of Cambridge.
|
|
|
|
4. You may not omit any of the copyright notices on either the source files,
|
|
the executable files, or the documentation.
|
|
|
|
5. You may not omit transmission of this License agreement with whatever
|
|
portions of MSNTP that are distributed.
|
|
|
|
6. Any users of this software must be notified that it is without warranty or
|
|
guarantee of any nature, express or implied, nor is there any fitness for use
|
|
represented.
|
|
|
|
|
|
October 1996
|
|
April 1997
|
|
October 2000
|
|
.fi
|
|
.ad
|
|
.PP
|
|
This manual page was \fIAutoGen\fP-erated from the \fBsntp\fP
|
|
option definitions.
|