diff options
Diffstat (limited to 'contrib/ntp/sntp/sntp.1')
| -rw-r--r-- | contrib/ntp/sntp/sntp.1 | 400 |
1 files changed, 400 insertions, 0 deletions
diff --git a/contrib/ntp/sntp/sntp.1 b/contrib/ntp/sntp/sntp.1 new file mode 100644 index 0000000..b6ccda2 --- /dev/null +++ b/contrib/ntp/sntp/sntp.1 @@ -0,0 +1,400 @@ +.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. |
