"Fossies" - the Fresh Open Source Software Archive

Member "ntp-4.2.8p15/sntp/invoke-sntp.texi" (23 Jun 2020, 15691 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 "invoke-sntp.texi": 4.2.8p14_vs_4.2.8p15.

    1 @node sntp Invocation
    2 @section Invoking sntp
    3 @pindex sntp
    4 @cindex standard Simple Network Time Protocol client program
    5 @ignore
    6 #
    7 # EDIT THIS FILE WITH CAUTION  (invoke-sntp.texi)
    8 #
    9 # It has been AutoGen-ed  June 23, 2020 at 02:19:36 AM by AutoGen 5.18.5
   10 # From the definitions    sntp-opts.def
   11 # and the template file   agtexi-cmd.tpl
   12 @end ignore
   16 @code{sntp}
   17 can be used as an SNTP client to query a NTP or SNTP server and either display
   18 the time or set the local system's time (given suitable privilege).  It can be
   19 run as an interactive command or from a
   20 @code{cron}
   21 job.
   23 NTP (the Network Time Protocol) and SNTP (the Simple Network Time Protocol)
   24 are defined and described by RFC 5905.
   27 The default is to write the estimated correct local date and time (i.e. not
   28 UTC) to the standard output in a format like:
   30 @code{'1996-10-15 20:17:25.123 (+0800) +4.567 +/- 0.089 [host] IP sN'}
   32 where the
   33 @code{'(+0800)'}
   34 means that to get to UTC from the reported local time one must
   35 add 8 hours and 0 minutes,
   36 the
   37 @code{'+4.567'}
   38 indicates the local clock is 4.567 seconds behind the correct time
   39 (so 4.567 seconds must be added to the local clock to get it to be correct).
   40 Note that the number of decimals printed for this value will change
   41 based on the reported precision of the server.
   42 @code{'+/- 0.089'}
   43 is the reported
   44 @emph{synchronization} @emph{distance}
   45 (in seconds), which represents the maximum error due to all causes.
   46 If the server does not report valid data needed to calculate the
   47 synchronization distance, this will be reported as
   48 @code{'+/- ?'}.
   49 If the
   50 @emph{host}
   51 is different from the
   52 @emph{IP},
   53 both will be displayed.
   54 Otherwise, only the 
   55 @emph{IP}
   56 is displayed.
   57 Finally, the
   58 @emph{stratum}
   59 of the host is reported
   60 and the leap indicator is decoded and displayed.
   62 This section was generated by @strong{AutoGen},
   63 using the @code{agtexi-cmd} template and the option descriptions for the @code{sntp} program.
   64 This software is released under the NTP license, <http://ntp.org/license>.
   66 @menu
   67 * sntp usage::                  sntp help/usage (@option{--help})
   68 * sntp ipv4::                   ipv4 option (-4)
   69 * sntp ipv6::                   ipv6 option (-6)
   70 * sntp authentication::         authentication option (-a)
   71 * sntp broadcast::              broadcast option (-b)
   72 * sntp concurrent::             concurrent option (-c)
   73 * sntp gap::                    gap option (-g)
   74 * sntp kod::                    kod option (-K)
   75 * sntp keyfile::                keyfile option (-k)
   76 * sntp logfile::                logfile option (-l)
   77 * sntp steplimit::              steplimit option (-M)
   78 * sntp ntpversion::             ntpversion option (-o)
   79 * sntp usereservedport::        usereservedport option (-r)
   80 * sntp timeout::                timeout option (-t)
   81 * sntp wait::                   wait option
   82 * sntp config::                 presetting/configuring sntp
   83 * sntp exit status::            exit status
   84 * sntp Usage::                  Usage
   85 * sntp Authors::                Authors
   86 @end menu
   88 @node sntp usage
   89 @subsection sntp help/usage (@option{--help})
   90 @cindex sntp help
   92 This is the automatically generated usage text for sntp.
   94 The text printed is the same whether selected with the @code{help} option
   95 (@option{--help}) or the @code{more-help} option (@option{--more-help}).  @code{more-help} will print
   96 the usage text by passing it through a pager program.
   97 @code{more-help} is disabled on platforms without a working
   98 @code{fork(2)} function.  The @code{PAGER} environment variable is
   99 used to select the program, defaulting to @file{more}.  Both will exit
  100 with a status code of 0.
  102 @exampleindent 0
  103 @example
  104 sntp - standard Simple Network Time Protocol client program - Ver. 4.2.8p15
  105 Usage:  sntp [ -<flag> [<val>] | --<name>[@{=| @}<val>] ]... \
  106                 [ hostname-or-IP ...]
  107   Flg Arg Option-Name    Description
  108    -4 no  ipv4           Force IPv4 DNS name resolution
  109                                 - prohibits the option 'ipv6'
  110    -6 no  ipv6           Force IPv6 DNS name resolution
  111                                 - prohibits the option 'ipv4'
  112    -a Num authentication Enable authentication with the key auth-keynumber
  113    -b Str broadcast      Listen to the address specified for broadcast time sync
  114                                 - may appear multiple times
  115    -c Str concurrent     Concurrently query all IPs returned for host-name
  116                                 - may appear multiple times
  117    -d no  debug-level    Increase debug verbosity level
  118                                 - may appear multiple times
  119    -D Num set-debug-level Set the debug verbosity level
  120                                 - may appear multiple times
  121    -g Num gap            The gap (in milliseconds) between time requests
  122    -K Fil kod            KoD history filename
  123    -k Fil keyfile        Look in this file for the key specified with -a
  124    -l Fil logfile        Log to specified logfile
  125    -M Num steplimit      Adjustments less than steplimit msec will be slewed
  126                                 - it must be in the range:
  127                                   greater than or equal to 0
  128    -o Num ntpversion     Send int as our NTP protocol version
  129                                 - it must be in the range:
  130                                   0 to 7
  131    -r no  usereservedport Use the NTP Reserved Port (port 123)
  132    -S no  step           OK to 'step' the time with settimeofday(2)
  133    -s no  slew           OK to 'slew' the time with adjtime(2)
  134    -t Num timeout        The number of seconds to wait for responses
  135       no  wait           Wait for pending replies (if not setting the time)
  136                                 - disabled as '--no-wait'
  137                                 - enabled by default
  138       opt version        output version information and exit
  139    -? no  help           display extended usage information and exit
  140    -! no  more-help      extended usage information passed thru pager
  141    -> opt save-opts      save the option state to a config file
  142    -< Str load-opts      load options from a config file
  143                                 - disabled as '--no-load-opts'
  144                                 - may appear multiple times
  146 Options are specified by doubled hyphens and their name or by a single
  147 hyphen and the flag character.
  150 The following option preset mechanisms are supported:
  151  - reading file $HOME/.ntprc
  152  - reading file ./.ntprc
  153  - examining environment variables named SNTP_*
  155 Please send bug reports to:  <http://bugs.ntp.org, bugs@@ntp.org>
  156 @end example
  157 @exampleindent 4
  159 @node sntp ipv4
  160 @subsection ipv4 option (-4)
  161 @cindex sntp-ipv4
  163 This is the ``force ipv4 dns name resolution'' option.
  165 @noindent
  166 This option has some usage constraints.  It:
  167 @itemize @bullet
  168 @item
  169 must not appear in combination with any of the following options:
  170 ipv6.
  171 @end itemize
  173 Force DNS resolution of the following host names on the command line
  174 to the IPv4 namespace.
  175 @node sntp ipv6
  176 @subsection ipv6 option (-6)
  177 @cindex sntp-ipv6
  179 This is the ``force ipv6 dns name resolution'' option.
  181 @noindent
  182 This option has some usage constraints.  It:
  183 @itemize @bullet
  184 @item
  185 must not appear in combination with any of the following options:
  186 ipv4.
  187 @end itemize
  189 Force DNS resolution of the following host names on the command line
  190 to the IPv6 namespace.
  191 @node sntp authentication
  192 @subsection authentication option (-a)
  193 @cindex sntp-authentication
  195 This is the ``enable authentication with the key @var{auth-keynumber}'' option.
  196 This option takes a number argument @file{auth-keynumber}.
  197 Enable authentication using the key specified in this option's
  198 argument.  The argument of this option is the @option{keyid}, a
  199 number specified in the @option{keyfile} as this key's identifier.
  200 See the @option{keyfile} option (@option{-k}) for more details.
  201 @node sntp broadcast
  202 @subsection broadcast option (-b)
  203 @cindex sntp-broadcast
  205 This is the ``listen to the address specified for broadcast time sync'' option.
  206 This option takes a string argument @file{broadcast-address}.
  208 @noindent
  209 This option has some usage constraints.  It:
  210 @itemize @bullet
  211 @item
  212 may appear an unlimited number of times.
  213 @end itemize
  215 If specified @code{sntp} will listen to the specified address
  216 for NTP broadcasts.  The default maximum wait time
  217 can (and probably should) be modified with @option{-t}.
  218 @node sntp concurrent
  219 @subsection concurrent option (-c)
  220 @cindex sntp-concurrent
  222 This is the ``concurrently query all ips returned for host-name'' option.
  223 This option takes a string argument @file{host-name}.
  225 @noindent
  226 This option has some usage constraints.  It:
  227 @itemize @bullet
  228 @item
  229 may appear an unlimited number of times.
  230 @end itemize
  232 Requests from an NTP "client" to a "server" should never be sent
  233 more rapidly than one every 2 seconds.  By default, any IPs returned
  234 as part of a DNS lookup are assumed to be for a single instance of
  235 @code{ntpd}, and therefore @code{sntp} will send queries to these IPs
  236 one after another, with a 2-second gap in between each query.
  238 The @option{-c} or @option{--concurrent} flag says that any IPs
  239 returned for the DNS lookup of the supplied host-name are on
  240 different machines, so we can send concurrent queries.
  241 @node sntp gap
  242 @subsection gap option (-g)
  243 @cindex sntp-gap
  245 This is the ``the gap (in milliseconds) between time requests'' option.
  246 This option takes a number argument @file{milliseconds}.
  247 Since we're only going to use the first valid response we get and
  248 there is benefit to specifying a good number of servers to query,
  249 separate the queries we send out by the specified number of
  250 milliseconds.
  251 @node sntp kod
  252 @subsection kod option (-K)
  253 @cindex sntp-kod
  255 This is the ``kod history filename'' option.
  256 This option takes a file argument @file{file-name}.
  257 Specifies the filename to be used for the persistent history of KoD
  258 responses received from servers.  If the file does not exist, a
  259 warning message will be displayed.  The file will not be created.
  260 @node sntp keyfile
  261 @subsection keyfile option (-k)
  262 @cindex sntp-keyfile
  264 This is the ``look in this file for the key specified with @option{-a}'' option.
  265 This option takes a file argument @file{file-name}.
  266 This option specifies the keyfile.
  267 @code{sntp} will search for the key specified with @option{-a}
  268 @file{keyno} in this file.  See @command{ntp.keys(5)} for more
  269 information.
  270 @node sntp logfile
  271 @subsection logfile option (-l)
  272 @cindex sntp-logfile
  274 This is the ``log to specified logfile'' option.
  275 This option takes a file argument @file{file-name}.
  276 This option causes the client to write log messages to the specified
  277 @file{logfile}.
  278 @node sntp steplimit
  279 @subsection steplimit option (-M)
  280 @cindex sntp-steplimit
  282 This is the ``adjustments less than @var{steplimit} msec will be slewed'' option.
  283 This option takes a number argument.
  284 If the time adjustment is less than @file{steplimit} milliseconds,
  285 slew the amount using @command{adjtime(2)}.  Otherwise, step the
  286 correction using @command{settimeofday(2)}.  The default value is 0,
  287 which means all adjustments will be stepped.  This is a feature, as
  288 different situations demand different values.
  289 @node sntp ntpversion
  290 @subsection ntpversion option (-o)
  291 @cindex sntp-ntpversion
  293 This is the ``send @var{int} as our ntp protocol version'' option.
  294 This option takes a number argument.
  295 When sending requests to a remote server, tell them we are running
  296 NTP protocol version @file{ntpversion} .
  297 @node sntp usereservedport
  298 @subsection usereservedport option (-r)
  299 @cindex sntp-usereservedport
  301 This is the ``use the ntp reserved port (port 123)'' option.
  302 Use port 123, which is reserved for NTP, for our network
  303 communications.
  304 @node sntp timeout
  305 @subsection timeout option (-t)
  306 @cindex sntp-timeout
  308 This is the ``the number of seconds to wait for responses'' option.
  309 This option takes a number argument @file{seconds}.
  310 When waiting for a reply, @code{sntp} will wait the number
  311 of seconds specified before giving up.  The default should be
  312 more than enough for a unicast response.  If @code{sntp} is
  313 only waiting for a broadcast response a longer timeout is
  314 likely needed.
  315 @node sntp wait
  316 @subsection wait option
  317 @cindex sntp-wait
  319 This is the ``wait for pending replies (if not setting the time)'' option.
  321 @noindent
  322 This option has some usage constraints.  It:
  323 @itemize @bullet
  324 @item
  325 can be disabled with --no-wait.
  326 @item
  327 It is enabled by default.
  328 @end itemize
  330 If we are not setting the time, wait for all pending responses.
  333 @node sntp config
  334 @subsection presetting/configuring sntp
  336 Any option that is not marked as @i{not presettable} may be preset by
  337 loading values from configuration ("rc" or "ini") files, and values from environment variables named @code{SNTP} and @code{SNTP_<OPTION_NAME>}.  @code{<OPTION_NAME>} must be one of
  338 the options listed above in upper case and segmented with underscores.
  339 The @code{SNTP} variable will be tokenized and parsed like
  340 the command line.  The remaining variables are tested for existence and their
  341 values are treated like option arguments.
  344 @noindent
  345 @code{libopts} will search in 2 places for configuration files:
  346 @itemize @bullet
  347 @item
  348 $HOME
  349 @item
  350 $PWD
  351 @end itemize
  352 The environment variables @code{HOME}, and @code{PWD}
  353 are expanded and replaced when @file{sntp} runs.
  354 For any of these that are plain files, they are simply processed.
  355 For any that are directories, then a file named @file{.ntprc} is searched for
  356 within that directory and processed.
  358 Configuration files may be in a wide variety of formats.
  359 The basic format is an option name followed by a value (argument) on the
  360 same line.  Values may be separated from the option name with a colon,
  361 equal sign or simply white space.  Values may be continued across multiple
  362 lines by escaping the newline with a backslash.
  364 Multiple programs may also share the same initialization file.
  365 Common options are collected at the top, followed by program specific
  366 segments.  The segments are separated by lines like:
  367 @example
  368 [SNTP]
  369 @end example
  370 @noindent
  371 or by
  372 @example
  373 <?program sntp>
  374 @end example
  375 @noindent
  376 Do not mix these styles within one configuration file.
  378 Compound values and carefully constructed string values may also be
  379 specified using XML syntax:
  380 @example
  381 <option-name>
  382    <sub-opt>...&lt;...&gt;...</sub-opt>
  383 </option-name>
  384 @end example
  385 @noindent
  386 yielding an @code{option-name.sub-opt} string value of
  387 @example
  388 "...<...>..."
  389 @end example
  390 @code{AutoOpts} does not track suboptions.  You simply note that it is a
  391 hierarchicly valued option.  @code{AutoOpts} does provide a means for searching
  392 the associated name/value pair list (see: optionFindValue).
  394 The command line options relating to configuration and/or usage help are:
  396 @subsubheading version (-)
  398 Print the program version to standard out, optionally with licensing
  399 information, then exit 0.  The optional argument specifies how much licensing
  400 detail to provide.  The default is to print just the version.  The licensing infomation may be selected with an option argument.
  401 Only the first letter of the argument is examined:
  403 @table @samp
  404 @item version
  405 Only print the version.  This is the default.
  406 @item copyright
  407 Name the copyright usage licensing terms.
  408 @item verbose
  409 Print the full copyright usage licensing terms.
  410 @end table
  412 @node sntp exit status
  413 @subsection sntp exit status
  415 One of the following exit values will be returned:
  416 @table @samp
  417 @item 0 (EXIT_SUCCESS)
  418 Successful program execution.
  419 @item 1 (EXIT_FAILURE)
  420 The operation failed or the command syntax was not valid.
  421 @item 66 (EX_NOINPUT)
  422 A specified configuration file could not be loaded.
  423 @item 70 (EX_SOFTWARE)
  424 libopts had an internal operational error.  Please report
  425 it to autogen-users@@lists.sourceforge.net.  Thank you.
  426 @end table
  427 @node sntp Usage
  428 @subsection sntp Usage
  429 @node sntp Authors
  430 @subsection sntp Authors