/contrib/ntp/sntp/sntp.1
https://bitbucket.org/freebsd/freebsd-head/ · Unknown · 400 lines · 375 code · 25 blank · 0 comment · 0 complexity · f21de68fd931dae6287dcf6b216f5081 MD5 · raw file
- .TH SNTP 1 2009-12-08 "( 4.2.4p8)" "Programmer's Manual"
- .\" EDIT THIS FILE WITH CAUTION (sntp.1)
- .\"
- .\" It has been AutoGen-ed Tuesday December 8, 2009 at 08:14:50 AM EST
- .\" 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.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.