"Fossies" - the Fresh Open Source Software Archive

Member "ntp-4.2.8p15/sntp/sntp.mdoc.in" (23 Jun 2020, 10902 Bytes) of package /linux/misc/ntp-4.2.8p15.tar.gz:

As a special service "Fossies" has tried to format the requested text file into HTML format (style: standard) with prefixed line numbers. Alternatively you can here view or download the uninterpreted source code file. See also the latest Fossies "Diffs" side-by-side code changes report for "sntp.mdoc.in": 4.2.8p14_vs_4.2.8p15.

    1 .Dd June 23 2020
    2 .Dt SNTP @SNTP_MS@ User Commands
    3 .Os
    4 .\"  EDIT THIS FILE WITH CAUTION  (sntp-opts.mdoc)
    5 .\"
    6 .\"  It has been AutoGen-ed  June 23, 2020 at 02:19:35 AM by AutoGen 5.18.5
    7 .\"  From the definitions    sntp-opts.def
    8 .\"  and the template file   agmdoc-cmd.tpl
    9 .Sh NAME
   10 .Nm sntp
   11 .Nd standard Simple Network Time Protocol client program
   12 .Sh SYNOPSIS
   13 .Nm
   14 .\" Mixture of short (flag) options and long options
   15 .Op Fl flags
   16 .Op Fl flag Op Ar value
   17 .Op Fl \-option\-name Ns Oo Oo Ns "=| " Oc Ns Ar value Oc
   18 [ hostname\-or\-IP ...]
   19 .Pp
   21 .Nm
   22 can be used as an SNTP client to query a NTP or SNTP server and either display
   23 the time or set the local system's time (given suitable privilege).  It can be
   24 run as an interactive command or from a
   25 .Ic cron
   26 job.
   27 NTP (the Network Time Protocol) and SNTP (the Simple Network Time Protocol)
   28 are defined and described by RFC 5905.
   29 .Pp
   30 The default is to write the estimated correct local date and time (i.e. not
   31 UTC) to the standard output in a format like:
   32 .Ic "'1996\-10\-15 20:17:25.123 (+0800) +4.567 +/\- 0.089 [host] IP sN'"
   33 where the
   34 .Ic "'(+0800)'"
   35 means that to get to UTC from the reported local time one must
   36 add 8 hours and 0 minutes,
   37 the
   38 .Ic "'+4.567'"
   39 indicates the local clock is 4.567 seconds behind the correct time
   40 (so 4.567 seconds must be added to the local clock to get it to be correct).
   41 Note that the number of decimals printed for this value will change
   42 based on the reported precision of the server.
   43 .Ic "'+/\- 0.089'"
   44 is the reported
   45 .Em synchronization distance
   46 (in seconds), which represents the maximum error due to all causes.
   47 If the server does not report valid data needed to calculate the
   48 synchronization distance, this will be reported as
   49 .Ic "'+/\- ?'" .
   50 If the
   51 .Em host
   52 is different from the
   53 .Em IP ,
   54 both will be displayed.
   55 Otherwise, only the 
   56 .Em IP
   57 is displayed.
   58 Finally, the
   59 .Em stratum
   60 of the host is reported
   61 and the leap indicator is decoded and displayed.
   62 .Sh "OPTIONS"
   63 .Bl -tag
   64 .It  Fl 4 , Fl \-ipv4 
   65 Force IPv4 DNS name resolution.
   66 This option must not appear in combination with any of the following options:
   67 ipv6.
   68 .sp
   69 Force DNS resolution of the following host names on the command line
   70 to the IPv4 namespace.
   71 .It  Fl 6 , Fl \-ipv6 
   72 Force IPv6 DNS name resolution.
   73 This option must not appear in combination with any of the following options:
   74 ipv4.
   75 .sp
   76 Force DNS resolution of the following host names on the command line
   77 to the IPv6 namespace.
   78 .It  Fl a Ar auth\-keynumber , Fl \-authentication Ns = Ns Ar auth\-keynumber 
   79 Enable authentication with the key \fBauth\-keynumber\fP.
   80 This option takes an integer number as its argument.
   81 .sp
   82 Enable authentication using the key specified in this option's
   83 argument.  The argument of this option is the \fBkeyid\fP, a
   84 number specified in the \fBkeyfile\fP as this key's identifier.
   85 See the \fBkeyfile\fP option (\fB\-k\fP) for more details.
   86 .It  Fl b Ar broadcast\-address , Fl \-broadcast Ns = Ns Ar broadcast\-address 
   87 Listen to the address specified for broadcast time sync.
   88 This option may appear an unlimited number of times.
   89 .sp
   90 If specified \fBsntp\fP will listen to the specified address
   91 for NTP broadcasts.  The default maximum wait time
   92 can (and probably should) be modified with \fB\-t\fP.
   93 .It  Fl c Ar host\-name , Fl \-concurrent Ns = Ns Ar host\-name 
   94 Concurrently query all IPs returned for host\-name.
   95 This option may appear an unlimited number of times.
   96 .sp
   97 Requests from an NTP "client" to a "server" should never be sent
   98 more rapidly than one every 2 seconds.  By default, any IPs returned
   99 as part of a DNS lookup are assumed to be for a single instance of
  100 \fBntpd\fP, and therefore \fBsntp\fP will send queries to these IPs
  101 one after another, with a 2\-second gap in between each query.
  102 .sp
  103 The \fB\-c\fP or \fB\-\-concurrent\fP flag says that any IPs
  104 returned for the DNS lookup of the supplied host\-name are on
  105 different machines, so we can send concurrent queries.
  106 .It  Fl d , Fl \-debug\-level 
  107 Increase debug verbosity level.
  108 This option may appear an unlimited number of times.
  109 .sp
  110 .It  Fl D Ar number , Fl \-set\-debug\-level Ns = Ns Ar number 
  111 Set the debug verbosity level.
  112 This option may appear an unlimited number of times.
  113 This option takes an integer number as its argument.
  114 .sp
  115 .It  Fl g Ar milliseconds , Fl \-gap Ns = Ns Ar milliseconds 
  116 The gap (in milliseconds) between time requests.
  117 This option takes an integer number as its argument.
  118 The default
  119 .Ar milliseconds
  120 for this option is:
  121 .ti +4
  122  50
  123 .sp
  124 Since we're only going to use the first valid response we get and
  125 there is benefit to specifying a good number of servers to query,
  126 separate the queries we send out by the specified number of
  127 milliseconds.
  128 .It  Fl K Ar file\-name , Fl \-kod Ns = Ns Ar file\-name 
  129 KoD history filename.
  130 The default
  131 .Ar file\-name
  132 for this option is:
  133 .ti +4
  134  /var/db/ntp\-kod
  135 .sp
  136 Specifies the filename to be used for the persistent history of KoD
  137 responses received from servers.  If the file does not exist, a
  138 warning message will be displayed.  The file will not be created.
  139 .It  Fl k Ar file\-name , Fl \-keyfile Ns = Ns Ar file\-name 
  140 Look in this file for the key specified with \fB\-a\fP.
  141 The default
  142 .Ar file\-name
  143 for this option is:
  144 .ti +4
  145  /etc/ntp.keys
  146 .sp
  147 This option specifies the keyfile.
  148 \fBsntp\fP will search for the key specified with \fB\-a\fP
  149 \fIkeyno\fP in this file.  See \fBntp.keys(5)\fP for more
  150 information.
  151 .It  Fl l Ar file\-name , Fl \-logfile Ns = Ns Ar file\-name 
  152 Log to specified logfile.
  153 .sp
  154 This option causes the client to write log messages to the specified
  155 \fIlogfile\fP.
  156 .It  Fl M Ar number , Fl \-steplimit Ns = Ns Ar number 
  157 Adjustments less than \fBsteplimit\fP msec will be slewed.
  158 This option takes an integer number as its argument.
  159 The value of
  160 .Ar number
  161 is constrained to being:
  162 .in +4
  163 .nf
  164 .na
  165 greater than or equal to 0
  166 .fi
  167 .in -4
  168 .sp
  169 If the time adjustment is less than \fIsteplimit\fP milliseconds,
  170 slew the amount using \fBadjtime(2)\fP.  Otherwise, step the
  171 correction using \fBsettimeofday(2)\fP.  The default value is 0,
  172 which means all adjustments will be stepped.  This is a feature, as
  173 different situations demand different values.
  174 .It  Fl o Ar number , Fl \-ntpversion Ns = Ns Ar number 
  175 Send \fBint\fP as our NTP protocol version.
  176 This option takes an integer number as its argument.
  177 The value of
  178 .Ar number
  179 is constrained to being:
  180 .in +4
  181 .nf
  182 .na
  183 in the range  0 through 7
  184 .fi
  185 .in -4
  186 The default
  187 .Ar number
  188 for this option is:
  189 .ti +4
  190  4
  191 .sp
  192 When sending requests to a remote server, tell them we are running
  193 NTP protocol version \fIntpversion\fP .
  194 .It  Fl r , Fl \-usereservedport 
  195 Use the NTP Reserved Port (port 123).
  196 .sp
  197 Use port 123, which is reserved for NTP, for our network
  198 communications.
  199 .It  Fl S , Fl \-step 
  200 OK to 'step' the time with \fBsettimeofday(2)\fP.
  201 .sp
  202 .It  Fl s , Fl \-slew 
  203 OK to 'slew' the time with \fBadjtime(2)\fP.
  204 .sp
  205 .It  Fl t Ar seconds , Fl \-timeout Ns = Ns Ar seconds 
  206 The number of seconds to wait for responses.
  207 This option takes an integer number as its argument.
  208 The default
  209 .Ar seconds
  210 for this option is:
  211 .ti +4
  212  5
  213 .sp
  214 When waiting for a reply, \fBsntp\fP will wait the number
  215 of seconds specified before giving up.  The default should be
  216 more than enough for a unicast response.  If \fBsntp\fP is
  217 only waiting for a broadcast response a longer timeout is
  218 likely needed.
  219 .It  Fl \-wait , " Fl \-no\-wait"
  220 Wait for pending replies (if not setting the time).
  221 The \fIno\-wait\fP form will disable the option.
  222 This option is enabled by default.
  223 .sp
  224 If we are not setting the time, wait for all pending responses.
  225 .It Fl \&? , Fl \-help
  226 Display usage information and exit.
  227 .It Fl \&! , Fl \-more\-help
  228 Pass the extended usage information through a pager.
  229 .It Fl > Oo Ar cfgfile Oc , Fl \-save\-opts Oo Ns = Ns Ar cfgfile Oc
  230 Save the option state to \fIcfgfile\fP.  The default is the \fIlast\fP
  231 configuration file listed in the \fBOPTION PRESETS\fP section, below.
  232 The command will exit after updating the config file.
  233 .It Fl < Ar cfgfile , Fl \-load\-opts Ns = Ns Ar cfgfile , Fl \-no\-load\-opts
  234 Load options from \fIcfgfile\fP.
  235 The \fIno\-load\-opts\fP form will disable the loading
  236 of earlier config/rc/ini files.  \fI\-\-no\-load\-opts\fP is handled early,
  237 out of order.
  238 .It Fl \-version Op Brq Ar v|c|n
  239 Output version of program and exit.  The default mode is `v', a simple
  240 version.  The `c' mode will print copyright information and `n' will
  241 print the full copyright notice.
  242 .El
  244 Any option that is not marked as \fInot presettable\fP may be preset
  245 by loading values from configuration ("RC" or ".INI") file(s) and values from
  246 environment variables named:
  247 .nf
  248   \fBSNTP_<option\-name>\fP or \fBSNTP\fP
  249 .fi
  250 .ad
  251 The environmental presets take precedence (are processed later than)
  252 the configuration files.
  253 The \fIhomerc\fP files are "\fI$HOME\fP", and "\fI.\fP".
  254 If any of these are directories, then the file \fI.ntprc\fP
  255 is searched for within those directories.
  256 .Sh USAGE
  257 .Bl -tag -width indent
  258 .It Li "sntp ntpserver.somewhere"
  259 is the simplest use of this program
  260 and can be run as an unprivileged command
  261 to check the current time and error in the local clock.
  262 .It Li "sntp \-Ss \-M 128 ntpserver.somewhere"
  263 With suitable privilege,
  264 run as a command
  265 or from a
  266 .Xr cron 8
  267 job,
  268 .Ic "sntp \-Ss \-M 128 ntpserver.somewhere"
  269 will request the time from the server,
  270 and if that server reports that it is synchronized
  271 then if the offset adjustment is less than 128 milliseconds
  272 the correction will be slewed,
  273 and if the correction is more than 128 milliseconds
  274 the correction  will be stepped.
  275 .It Li "sntp \-S ntpserver.somewhere"
  276 With suitable privilege,
  277 run as a command
  278 or from a
  279 .Xr cron 8
  280 job,
  281 .Ic "sntp \-S ntpserver.somewhere"
  282 will set (step) the local clock from a synchronized specified server,
  283 like the (deprecated)
  284 .Xr ntpdate @NTPDATE_MS@ ,
  285 or
  286 .Xr rdate 8
  287 commands.
  288 .El
  290 See \fBOPTION PRESETS\fP for configuration environment variables.
  291 .Sh "FILES"
  292 See \fBOPTION PRESETS\fP for configuration files.
  293 .Sh "EXIT STATUS"
  294 One of the following exit values will be returned:
  295 .Bl -tag
  296 .It 0 " (EXIT_SUCCESS)"
  297 Successful program execution.
  298 .It 1 " (EXIT_FAILURE)"
  299 The operation failed or the command syntax was not valid.
  300 .It 66 " (EX_NOINPUT)"
  301 A specified configuration file could not be loaded.
  302 .It 70 " (EX_SOFTWARE)"
  303 libopts had an internal operational error.  Please report
  304 it to autogen\-users@lists.sourceforge.net.  Thank you.
  305 .El
  306 .Sh AUTHORS
  307 .An "Johannes Maximilian Kuehn"
  308 .An "Harlan Stenn"
  309 .An "Dave Hart"
  310 .Sh "COPYRIGHT"
  311 Copyright (C) 1992\-2020 The University of Delaware and Network Time Foundation all rights reserved.
  312 This program is released under the terms of the NTP license, <http://ntp.org/license>.
  313 .Sh "BUGS"
  314 Please send bug reports to: http://bugs.ntp.org, bugs@ntp.org
  315 .Sh "NOTES"
  316 This manual page was \fIAutoGen\fP\-erated from the \fBsntp\fP
  317 option definitions.