diff options
Diffstat (limited to 'contrib/ntp/sntp/sntp.man.in')
| -rw-r--r-- | contrib/ntp/sntp/sntp.man.in | 356 |
1 files changed, 356 insertions, 0 deletions
diff --git a/contrib/ntp/sntp/sntp.man.in b/contrib/ntp/sntp/sntp.man.in new file mode 100644 index 0000000..3a6f9c5 --- /dev/null +++ b/contrib/ntp/sntp/sntp.man.in @@ -0,0 +1,356 @@ +.de1 NOP +. it 1 an-trap +. if \\n[.$] \,\\$*\/ +.. +.ie t \ +.ds B-Font [CB] +.ds I-Font [CI] +.ds R-Font [CR] +.el \ +.ds B-Font B +.ds I-Font I +.ds R-Font R +.TH sntp @SNTP_MS@ "04 Feb 2015" "4.2.8p1" "User Commands" +.\" +.\" EDIT THIS FILE WITH CAUTION (/tmp/.ag-apayaT/ag-zpaq_S) +.\" +.\" It has been AutoGen-ed February 4, 2015 at 02:34:13 AM by AutoGen 5.18.5pre4 +.\" From the definitions sntp-opts.def +.\" and the template file agman-cmd.tpl +.SH NAME +\f\*[B-Font]sntp\fP +\- standard Simple Network Time Protocol client program +.SH SYNOPSIS +\f\*[B-Font]sntp\fP +.\" Mixture of short (flag) options and long options +[\f\*[B-Font]\-flags\f[]] +[\f\*[B-Font]\-flag\f[] [\f\*[I-Font]value\f[]]] +[\f\*[B-Font]\-\-option-name\f[][[=| ]\f\*[I-Font]value\f[]]] +[ hostname-or-IP ...] +.sp \n(Ppu +.ne 2 + +.SH DESCRIPTION +\f\*[B-Font]sntp\fP +can be used as an 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 from a +\f\*[B-Font]cron\f[] +job. +NTP (the Network Time Protocol) and SNTP (the Simple Network Time Protocol) +are defined and described by RFC 5905. +.sp \n(Ppu +.ne 2 + +The default is to write the estimated correct local date and time (i.e. not +UTC) to the standard output in a format like: +\f\*[B-Font]'1996-10-15 20:17:25.123 (+0800) +4.567 +/- 0.089 [host] IP sN'\f[] +where the +\f\*[B-Font]'(+0800)'\f[] +means that to get to UTC from the reported local time one must +add 8 hours and 0 minutes, +the +\f\*[B-Font]'+4.567'\f[] +indicates the local clock is 4.567 seconds behind the correct time +(so 4.567 seconds must be added to the local clock to get it to be correct). +Note that the number of decimals printed for this value will change +based on the reported precision of the server. +\f\*[B-Font]'+/- 0.089'\f[] +is the reported +\fIsynchronization\f[] \fIdistance\f[] +(in seconds), which represents the maximum error due to all causes. +If the server does not report valid data needed to calculate the +synchronization distance, this will be reported as +\f\*[B-Font]'+/- ?'\f[]. +If the +\fIhost\f[] +is different from the +\fIIP\f[], +both will be displayed. +Otherwise, only the +\fIIP\f[] +is displayed. +Finally, the +\fIstratum\f[] +of the host is reported. +.SH "OPTIONS" +.TP +.NOP \f\*[B-Font]\-4\f[], \f\*[B-Font]\-\-ipv4\f[] +Force IPv4 DNS name resolution. +This option must not appear in combination with any of the following options: +ipv6. +.sp +Force DNS resolution of the following host names on the command line +to the IPv4 namespace. +.TP +.NOP \f\*[B-Font]\-6\f[], \f\*[B-Font]\-\-ipv6\f[] +Force IPv6 DNS name resolution. +This option must not appear in combination with any of the following options: +ipv4. +.sp +Force DNS resolution of the following host names on the command line +to the IPv6 namespace. +.TP +.NOP \f\*[B-Font]\-a\f[] \f\*[I-Font]auth\-keynumber\f[], \f\*[B-Font]\-\-authentication\f[]=\f\*[I-Font]auth\-keynumber\f[] +Enable authentication with the key \fBauth-keynumber\fP. +This option takes an integer number as its argument. +.sp +Enable authentication using the key specified in this option's +argument. The argument of this option is the \fBkeyid\fP, a +number specified in the \fBkeyfile\fP as this key's identifier. +See the \fBkeyfile\fP option (\fB-k\fP) for more details. +.TP +.NOP \f\*[B-Font]\-b\f[] \f\*[I-Font]broadcast\-address\f[], \f\*[B-Font]\-\-broadcast\f[]=\f\*[I-Font]broadcast\-address\f[] +Listen to the address specified for broadcast time sync. +This option may appear an unlimited number of times. +.sp +If specified \fBsntp\fP will listen to the specified address +for NTP broadcasts. The default maximum wait time +can (and probably should) be modified with \fB-t\fP. +.TP +.NOP \f\*[B-Font]\-c\f[] \f\*[I-Font]host\-name\f[], \f\*[B-Font]\-\-concurrent\f[]=\f\*[I-Font]host\-name\f[] +Concurrently query all IPs returned for host-name. +This option may appear an unlimited number of times. +.sp +Requests from an NTP "client" to a "server" should never be sent +more rapidly than one every 2 seconds. By default, any IPs returned +as part of a DNS lookup are assumed to be for a single instance of +\fBntpd\fP, and therefore \fBsntp\fP will send queries to these IPs +one after another, with a 2-second gap in between each query. +.sp +The \fB-c\fP or \fB--concurrent\fP flag says that any IPs +returned for the DNS lookup of the supplied host-name are on +different machines, so we can send concurrent queries. +.TP +.NOP \f\*[B-Font]\-d\f[], \f\*[B-Font]\-\-debug\-level\f[] +Increase debug verbosity level. +This option may appear an unlimited number of times. +.sp +.TP +.NOP \f\*[B-Font]\-D\f[] \f\*[I-Font]number\f[], \f\*[B-Font]\-\-set\-debug\-level\f[]=\f\*[I-Font]number\f[] +Set the debug verbosity level. +This option may appear an unlimited number of times. +This option takes an integer number as its argument. +.sp +.TP +.NOP \f\*[B-Font]\-g\f[] \f\*[I-Font]milliseconds\f[], \f\*[B-Font]\-\-gap\f[]=\f\*[I-Font]milliseconds\f[] +The gap (in milliseconds) between time requests. +This option takes an integer number as its argument. +The default +\f\*[I-Font]milliseconds\f[] +for this option is: +.ti +4 + 50 +.sp +Since we're only going to use the first valid response we get and +there is benefit to specifying a good number of servers to query, +separate the queries we send out by the specified number of +milliseconds. +.TP +.NOP \f\*[B-Font]\-K\f[] \f\*[I-Font]file\-name\f[], \f\*[B-Font]\-\-kod\f[]=\f\*[I-Font]file\-name\f[] +KoD history filename. +The default +\f\*[I-Font]file\-name\f[] +for this option is: +.ti +4 + /var/db/ntp-kod +.sp +Specifies the filename to be used for the persistent history of KoD +responses received from servers. If the file does not exist, a +warning message will be displayed. The file will not be created. +.TP +.NOP \f\*[B-Font]\-k\f[] \f\*[I-Font]file\-name\f[], \f\*[B-Font]\-\-keyfile\f[]=\f\*[I-Font]file\-name\f[] +Look in this file for the key specified with \fB-a\fP. +.sp +This option specifies the keyfile. +\fBsntp\fP will search for the key specified with \fB-a\fP +\fIkeyno\fP in this file. See \fBntp.keys(5)\fP for more +information. +.TP +.NOP \f\*[B-Font]\-l\f[] \f\*[I-Font]file\-name\f[], \f\*[B-Font]\-\-logfile\f[]=\f\*[I-Font]file\-name\f[] +Log to specified logfile. +.sp +This option causes the client to write log messages to the specified +\fIlogfile\fP. +.TP +.NOP \f\*[B-Font]\-M\f[] \f\*[I-Font]number\f[], \f\*[B-Font]\-\-steplimit\f[]=\f\*[I-Font]number\f[] +Adjustments less than \fBsteplimit\fP msec will be slewed. +This option takes an integer number as its argument. +The value of +\f\*[I-Font]number\f[] +is constrained to being: +.in +4 +.nf +.na +greater than or equal to 0 +.fi +.in -4 +.sp +If the time adjustment is less than \fIsteplimit\fP milliseconds, +slew the amount using \fBadjtime(2)\fP. Otherwise, step the +correction using \fBsettimeofday(2)\fP. The default value is 0, +which means all adjustments will be stepped. This is a feature, as +different situations demand different values. +.TP +.NOP \f\*[B-Font]\-o\f[] \f\*[I-Font]number\f[], \f\*[B-Font]\-\-ntpversion\f[]=\f\*[I-Font]number\f[] +Send \fBint\fP as our NTP protocol version. +This option takes an integer number as its argument. +The value of +\f\*[I-Font]number\f[] +is constrained to being: +.in +4 +.nf +.na +in the range 0 through 7 +.fi +.in -4 +The default +\f\*[I-Font]number\f[] +for this option is: +.ti +4 + 4 +.sp +When sending requests to a remote server, tell them we are running +NTP protocol version \fIntpversion\fP . +.TP +.NOP \f\*[B-Font]\-r\f[], \f\*[B-Font]\-\-usereservedport\f[] +Use the NTP Reserved Port (port 123). +.sp +Use port 123, which is reserved for NTP, for our network +communications. +.TP +.NOP \f\*[B-Font]\-S\f[], \f\*[B-Font]\-\-step\f[] +OK to 'step' the time with \fBsettimeofday(2)\fP. +.sp +.TP +.NOP \f\*[B-Font]\-s\f[], \f\*[B-Font]\-\-slew\f[] +OK to 'slew' the time with \fBadjtime(2)\fP. +.sp +.TP +.NOP \f\*[B-Font]\-t\f[] \f\*[I-Font]seconds\f[], \f\*[B-Font]\-\-timeout\f[]=\f\*[I-Font]seconds\f[] +The number of seconds to wait for responses. +This option takes an integer number as its argument. +The default +\f\*[I-Font]seconds\f[] +for this option is: +.ti +4 + 5 +.sp +When waiting for a reply, \fBsntp\fP will wait the number +of seconds specified before giving up. The default should be +more than enough for a unicast response. If \fBsntp\fP is +only waiting for a broadcast response a longer timeout is +likely needed. +.TP +.NOP \f\*[B-Font]\-\-wait\f[], \f\*[B-Font]\- Fl \-no\-wait\f[] +Wait for pending replies (if not setting the time). +The \fIno\-wait\fP form will disable the option. +This option is enabled by default. +.sp +If we are not setting the time, wait for all pending responses. +.TP +.NOP \f\*[B-Font]\-\&?\f[], \f\*[B-Font]\-\-help\f[] +Display usage information and exit. +.TP +.NOP \f\*[B-Font]\-\&!\f[], \f\*[B-Font]\-\-more-help\f[] +Pass the extended usage information through a pager. +.TP +.NOP \f\*[B-Font]\->\f[] [\f\*[I-Font]cfgfile\f[]], \f\*[B-Font]\-\-save-opts\f[] [=\f\*[I-Font]cfgfile\f[]] +Save the option state to \fIcfgfile\fP. The default is the \fIlast\fP +configuration file listed in the \fBOPTION PRESETS\fP section, below. +The command will exit after updating the config file. +.TP +.NOP \f\*[B-Font]\-<\f[] \f\*[I-Font]cfgfile\f[], \f\*[B-Font]\-\-load-opts\f[]=\f\*[I-Font]cfgfile\f[], \f\*[B-Font]\-\-no-load-opts\f[] +Load options from \fIcfgfile\fP. +The \fIno-load-opts\fP form will disable the loading +of earlier config/rc/ini files. \fI\-\-no-load-opts\fP is handled early, +out of order. +.TP +.NOP \f\*[B-Font]\-\-version\f[] [{\f\*[I-Font]v|c|n\f[]}] +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. +.PP +.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 +.ad +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 USAGE +.TP 7 +.NOP \f[C]sntp ntpserver.somewhere\f[] +is the simplest use of this program +and can be run as an unprivileged command +to check the current time and error in the local clock. +.TP 7 +.NOP \f[C]sntp \-Ss \-M 128 ntpserver.somewhere\f[] +With suitable privilege, +run as a command +or from a +\fCcron\fR(8)\f[] +job, +\f\*[B-Font]sntp \-Ss \-M 128 ntpserver.somewhere\f[] +will request the time from the server, +and if that server reports that it is synchronized +then if the offset adjustment is less than 128 milliseconds +the correction will be slewed, +and if the correction is more than 128 milliseconds +the correction will be stepped. +.TP 7 +.NOP \f[C]sntp \-S ntpserver.somewhere\f[] +With suitable privilege, +run as a command +or from a +\fCcron\fR(8)\f[] +job, +\f\*[B-Font]sntp \-S ntpserver.somewhere\f[] +will set (step) the local clock from a synchronized specified server, +like the (deprecated) +\fCntpdate\fR(@NTPDATE_MS@)\f[], +or +\fCrdate\fR(8)\f[] +commands. +.PP +.SH "ENVIRONMENT" +See \fBOPTION PRESETS\fP for configuration environment variables. +.SH "FILES" +See \fBOPTION PRESETS\fP for configuration files. +.SH "EXIT STATUS" +One of the following exit values will be returned: +.TP +.NOP 0 " (EXIT_SUCCESS)" +Successful program execution. +.TP +.NOP 1 " (EXIT_FAILURE)" +The operation failed or the command syntax was not valid. +.TP +.NOP 66 " (EX_NOINPUT)" +A specified configuration file could not be loaded. +.TP +.NOP 70 " (EX_SOFTWARE)" +libopts had an internal operational error. Please report +it to autogen-users@lists.sourceforge.net. Thank you. +.PP +.SH AUTHORS +.NOP "Johannes Maximilian Kuehn" +.br +.NOP "Harlan Stenn" +.br +.NOP "Dave Hart" +.br +.SH "COPYRIGHT" +Copyright (C) 1992-2015 The University of Delaware and Network Time Foundation all rights reserved. +This program is released under the terms of the NTP license, <http://ntp.org/license>. +.SH "BUGS" +Please send bug reports to: http://bugs.ntp.org, bugs@ntp.org +.SH "NOTES" +This manual page was \fIAutoGen\fP-erated from the \fBsntp\fP +option definitions. |
