diff options
Diffstat (limited to 'sntp/sntp.mdoc.in')
| -rw-r--r-- | sntp/sntp.mdoc.in | 295 |
1 files changed, 295 insertions, 0 deletions
diff --git a/sntp/sntp.mdoc.in b/sntp/sntp.mdoc.in new file mode 100644 index 0000000..13c768f --- /dev/null +++ b/sntp/sntp.mdoc.in @@ -0,0 +1,295 @@ +.Dd December 2 2014 +.Dt SNTP @SNTP_MS@ User Commands +.Os +.\" EDIT THIS FILE WITH CAUTION (sntp-opts.mdoc) +.\" +.\" It has been AutoGen-ed December 2, 2014 at 08:59:31 AM by AutoGen 5.18.5pre4 +.\" From the definitions sntp-opts.def +.\" and the template file agmdoc-cmd.tpl +.Sh NAME +.Nm sntp +.Nd standard Simple Network Time Protocol client program +.Sh SYNOPSIS +.Nm +.\" Mixture of short (flag) options and long options +.Op Fl flags +.Op Fl flag Op Ar value +.Op Fl \-option\-name Ns Oo Oo Ns "=| " Oc Ns Ar value Oc +[ hostname\-or\-IP ...] +.Pp +.Sh DESCRIPTION +.Nm +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 +.Ic cron +job. +NTP (the Network Time Protocol) and SNTP (the Simple Network Time Protocol) +are defined and described by RFC 5905. +.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: +.Ic "'1996\-10\-15 20:17:25.123 (+0800) +4.567 +/\- 0.089 [host] IP sN'" +where the +.Ic "'(+0800)'" +means that to get to UTC from the reported local time one must +add 8 hours and 0 minutes, +the +.Ic "'+4.567'" +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. +.Ic "'+/\- 0.089'" +is the reported +.Em synchronization distance +(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 +.Ic "'+/\- ?'" . +If the +.Em host +is different from the +.Em IP , +both will be displayed. +Otherwise, only the +.Em IP +is displayed. +Finally, the +.Em stratum +of the host is reported. +.Sh "OPTIONS" +.Bl -tag +.It Fl 4 , Fl \-ipv4 +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. +.It Fl 6 , Fl \-ipv6 +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. +.It Fl a Ar auth\-keynumber , Fl \-authentication Ns = Ns Ar auth\-keynumber +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. +.It Fl b Ar broadcast\-address , Fl \-broadcast Ns = Ns Ar broadcast\-address +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. +.It Fl c Ar host\-name , Fl \-concurrent Ns = Ns Ar host\-name +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. +.It Fl d , Fl \-debug\-level +Increase debug verbosity level. +This option may appear an unlimited number of times. +.sp +.It Fl D Ar number , Fl \-set\-debug\-level Ns = Ns Ar number +Set the debug verbosity level. +This option may appear an unlimited number of times. +This option takes an integer number as its argument. +.sp +.It Fl g Ar milliseconds , Fl \-gap Ns = Ns Ar milliseconds +The gap (in milliseconds) between time requests. +This option takes an integer number as its argument. +The default +.Ar milliseconds +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. +.It Fl K Ar file\-name , Fl \-kod Ns = Ns Ar file\-name +KoD history filename. +The default +.Ar file\-name +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. +.It Fl k Ar file\-name , Fl \-keyfile Ns = Ns Ar file\-name +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. +.It Fl l Ar file\-name , Fl \-logfile Ns = Ns Ar file\-name +Log to specified logfile. +.sp +This option causes the client to write log messages to the specified +\fIlogfile\fP. +.It Fl M Ar number , Fl \-steplimit Ns = Ns Ar number +Adjustments less than \fBsteplimit\fP msec will be slewed. +This option takes an integer number as its argument. +The value of +.Ar number +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. +.It Fl o Ar number , Fl \-ntpversion Ns = Ns Ar number +Send \fBint\fP as our NTP protocol version. +This option takes an integer number as its argument. +The value of +.Ar number +is constrained to being: +.in +4 +.nf +.na +in the range 0 through 7 +.fi +.in -4 +The default +.Ar number +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 . +.It Fl r , Fl \-usereservedport +Use the NTP Reserved Port (port 123). +.sp +Use port 123, which is reserved for NTP, for our network +communications. +.It Fl S , Fl \-step +OK to 'step' the time with \fBsettimeofday(2)\fP. +.sp +.It Fl s , Fl \-slew +OK to 'slew' the time with \fBadjtime(2)\fP. +.sp +.It Fl t Ar seconds , Fl \-timeout Ns = Ns Ar seconds +The number of seconds to wait for responses. +This option takes an integer number as its argument. +The default +.Ar seconds +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. +.It Fl \-wait , " Fl \-no\-wait" +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. +.It Fl \&? , Fl \-help +Display usage information and exit. +.It Fl \&! , Fl \-more\-help +Pass the extended usage information through a pager. +.It Fl > Oo Ar cfgfile Oc , Fl \-save\-opts Oo Ns = Ns Ar cfgfile Oc +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. +.It Fl < Ar cfgfile , Fl \-load\-opts Ns = Ns Ar cfgfile , Fl \-no\-load\-opts +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. +.It Fl \-version Op Brq Ar v|c|n +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. +.El +.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 +.Bl -tag -width indent +.It Li "sntp ntpserver.somewhere" +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. +.It Li "sntp \-a ntpserver.somewhere" +With suitable privilege, +run as a command +or from a +.Xr cron 8 +job, +.Ic "sntp \-a" +will reset the local clock from a synchronized specified server, +like the (deprecated) +.Xr ntpdate @NTPDATE_MS@ , +or +.Xr rdate 8 +commands. +.El +.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: +.Bl -tag +.It 0 " (EXIT_SUCCESS)" +Successful program execution. +.It 1 " (EXIT_FAILURE)" +The operation failed or the command syntax was not valid. +.It 66 " (EX_NOINPUT)" +A specified configuration file could not be loaded. +.It 70 " (EX_SOFTWARE)" +libopts had an internal operational error. Please report +it to autogen\-users@lists.sourceforge.net. Thank you. +.El +.Sh AUTHORS +.An "Johannes Maximilian Kuehn" +.An "Harlan Stenn" +.An "Dave Hart" +.Sh "COPYRIGHT" +Copyright (C) 1970\-2014 The University of Delaware 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. |