diff options
Diffstat (limited to 'sntp/invoke-sntp.texi')
| -rw-r--r-- | sntp/invoke-sntp.texi | 426 |
1 files changed, 426 insertions, 0 deletions
diff --git a/sntp/invoke-sntp.texi b/sntp/invoke-sntp.texi new file mode 100644 index 0000000..a79bb59 --- /dev/null +++ b/sntp/invoke-sntp.texi @@ -0,0 +1,426 @@ +@node sntp Invocation +@section Invoking sntp +@pindex sntp +@cindex standard Simple Network Time Protocol client program +@ignore +# +# EDIT THIS FILE WITH CAUTION (invoke-sntp.texi) +# +# It has been AutoGen-ed December 2, 2014 at 08:59:28 AM by AutoGen 5.18.5pre4 +# From the definitions sntp-opts.def +# and the template file agtexi-cmd.tpl +@end ignore + + + +@code{sntp} +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 +@code{cron} +job. + +NTP (the Network Time Protocol) and SNTP (the Simple Network Time Protocol) +are defined and described by RFC 5905. + + +The default is to write the estimated correct local date and time (i.e. not +UTC) to the standard output in a format like: + +@code{'1996-10-15 20:17:25.123 (+0800) +4.567 +/- 0.089 [host] IP sN'} + +where the +@code{'(+0800)'} +means that to get to UTC from the reported local time one must +add 8 hours and 0 minutes, +the +@code{'+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. +@code{'+/- 0.089'} +is the reported +@emph{synchronization} @emph{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 +@code{'+/- ?'}. +If the +@emph{host} +is different from the +@emph{IP}, +both will be displayed. +Otherwise, only the +@emph{IP} +is displayed. +Finally, the +@emph{stratum} +of the host is reported. + +This section was generated by @strong{AutoGen}, +using the @code{agtexi-cmd} template and the option descriptions for the @code{sntp} program. +This software is released under the NTP license, <http://ntp.org/license>. + +@menu +* sntp usage:: sntp help/usage (@option{--help}) +* sntp ipv4:: ipv4 option (-4) +* sntp ipv6:: ipv6 option (-6) +* sntp authentication:: authentication option (-a) +* sntp broadcast:: broadcast option (-b) +* sntp concurrent:: concurrent option (-c) +* sntp gap:: gap option (-g) +* sntp kod:: kod option (-K) +* sntp keyfile:: keyfile option (-k) +* sntp logfile:: logfile option (-l) +* sntp steplimit:: steplimit option (-M) +* sntp ntpversion:: ntpversion option (-o) +* sntp usereservedport:: usereservedport option (-r) +* sntp timeout:: timeout option (-t) +* sntp wait:: wait option +* sntp config:: presetting/configuring sntp +* sntp exit status:: exit status +* sntp Usage:: Usage +* sntp Authors:: Authors +@end menu + +@node sntp usage +@subsection sntp help/usage (@option{--help}) +@cindex sntp help + +This is the automatically generated usage text for sntp. + +The text printed is the same whether selected with the @code{help} option +(@option{--help}) or the @code{more-help} option (@option{--more-help}). @code{more-help} will print +the usage text by passing it through a pager program. +@code{more-help} is disabled on platforms without a working +@code{fork(2)} function. The @code{PAGER} environment variable is +used to select the program, defaulting to @file{more}. Both will exit +with a status code of 0. + +@exampleindent 0 +@example +sntp - standard Simple Network Time Protocol client program - Ver. 4.2.7p482 +Usage: sntp [ -<flag> [<val>] | --<name>[@{=| @}<val>] ]... \ + [ hostname-or-IP ...] + Flg Arg Option-Name Description + -4 no ipv4 Force IPv4 DNS name resolution + - prohibits the option 'ipv6' + -6 no ipv6 Force IPv6 DNS name resolution + - prohibits the option 'ipv4' + -a Num authentication Enable authentication with the key auth-keynumber + -b Str broadcast Listen to the address specified for broadcast time sync + - may appear multiple times + -c Str concurrent Concurrently query all IPs returned for host-name + - may appear multiple times + -d no debug-level Increase debug verbosity level + - may appear multiple times + -D Num set-debug-level Set the debug verbosity level + - may appear multiple times + -g Num gap The gap (in milliseconds) between time requests + -K Fil kod KoD history filename + -k Fil keyfile Look in this file for the key specified with -a + -l Fil logfile Log to specified logfile + -M Num steplimit Adjustments less than steplimit msec will be slewed + - it must be in the range: + greater than or equal to 0 + -o Num ntpversion Send int as our NTP protocol version + - it must be in the range: + 0 to 7 + -r no usereservedport Use the NTP Reserved Port (port 123) + -S no step OK to 'step' the time with settimeofday(2) + -s no slew OK to 'slew' the time with adjtime(2) + -t Num timeout The number of seconds to wait for responses + no wait Wait for pending replies (if not setting the time) + - disabled as '--no-wait' + - enabled by default + opt version output version information and exit + -? no help display extended usage information and exit + -! no more-help extended usage information passed thru pager + -> opt save-opts save the option state to a config file + -< Str load-opts load options from a config file + - disabled as '--no-load-opts' + - may appear multiple times + +Options are specified by doubled hyphens and their name or by a single +hyphen and the flag character. + + +The following option preset mechanisms are supported: + - reading file $HOME/.ntprc + - reading file ./.ntprc + - examining environment variables named SNTP_* + +Please send bug reports to: <http://bugs.ntp.org, bugs@@ntp.org> +@end example +@exampleindent 4 + +@node sntp ipv4 +@subsection ipv4 option (-4) +@cindex sntp-ipv4 + +This is the ``force ipv4 dns name resolution'' option. + +@noindent +This option has some usage constraints. It: +@itemize @bullet +@item +must not appear in combination with any of the following options: +ipv6. +@end itemize + +Force DNS resolution of the following host names on the command line +to the IPv4 namespace. +@node sntp ipv6 +@subsection ipv6 option (-6) +@cindex sntp-ipv6 + +This is the ``force ipv6 dns name resolution'' option. + +@noindent +This option has some usage constraints. It: +@itemize @bullet +@item +must not appear in combination with any of the following options: +ipv4. +@end itemize + +Force DNS resolution of the following host names on the command line +to the IPv6 namespace. +@node sntp authentication +@subsection authentication option (-a) +@cindex sntp-authentication + +This is the ``enable authentication with the key @var{auth-keynumber}'' option. +This option takes a number argument @file{auth-keynumber}. +Enable authentication using the key specified in this option's +argument. The argument of this option is the @option{keyid}, a +number specified in the @option{keyfile} as this key's identifier. +See the @option{keyfile} option (@option{-k}) for more details. +@node sntp broadcast +@subsection broadcast option (-b) +@cindex sntp-broadcast + +This is the ``listen to the address specified for broadcast time sync'' option. +This option takes a string argument @file{broadcast-address}. + +@noindent +This option has some usage constraints. It: +@itemize @bullet +@item +may appear an unlimited number of times. +@end itemize + +If specified @code{sntp} will listen to the specified address +for NTP broadcasts. The default maximum wait time +can (and probably should) be modified with @option{-t}. +@node sntp concurrent +@subsection concurrent option (-c) +@cindex sntp-concurrent + +This is the ``concurrently query all ips returned for host-name'' option. +This option takes a string argument @file{host-name}. + +@noindent +This option has some usage constraints. It: +@itemize @bullet +@item +may appear an unlimited number of times. +@end itemize + +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 +@code{ntpd}, and therefore @code{sntp} will send queries to these IPs +one after another, with a 2-second gap in between each query. + +The @option{-c} or @option{--concurrent} 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. +@node sntp gap +@subsection gap option (-g) +@cindex sntp-gap + +This is the ``the gap (in milliseconds) between time requests'' option. +This option takes a number argument @file{milliseconds}. +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. +@node sntp kod +@subsection kod option (-K) +@cindex sntp-kod + +This is the ``kod history filename'' option. +This option takes a file argument @file{file-name}. +Specifies the filename to be used for the persistent history of KoD +responses received from servers. +@node sntp keyfile +@subsection keyfile option (-k) +@cindex sntp-keyfile + +This is the ``look in this file for the key specified with @option{-a}'' option. +This option takes a file argument @file{file-name}. +This option specifies the keyfile. +@code{sntp} will search for the key specified with @option{-a} +@file{keyno} in this file. See @command{ntp.keys(5)} for more +information. +@node sntp logfile +@subsection logfile option (-l) +@cindex sntp-logfile + +This is the ``log to specified logfile'' option. +This option takes a file argument @file{file-name}. +This option causes the client to write log messages to the specified +@file{logfile}. +@node sntp steplimit +@subsection steplimit option (-M) +@cindex sntp-steplimit + +This is the ``adjustments less than @var{steplimit} msec will be slewed'' option. +This option takes a number argument. +If the time adjustment is less than @file{steplimit} milliseconds, +slew the amount using @command{adjtime(2)}. Otherwise, step the +correction using @command{settimeofday(2)}. +@node sntp ntpversion +@subsection ntpversion option (-o) +@cindex sntp-ntpversion + +This is the ``send @var{int} as our ntp protocol version'' option. +This option takes a number argument. +When sending requests to a remote server, tell them we are running +NTP protocol version @file{ntpversion} . +@node sntp usereservedport +@subsection usereservedport option (-r) +@cindex sntp-usereservedport + +This is the ``use the ntp reserved port (port 123)'' option. +Use port 123, which is reserved for NTP, for our network +communications. +@node sntp timeout +@subsection timeout option (-t) +@cindex sntp-timeout + +This is the ``the number of seconds to wait for responses'' option. +This option takes a number argument @file{seconds}. +When waiting for a reply, @code{sntp} will wait the number +of seconds specified before giving up. The default should be +more than enough for a unicast response. If @code{sntp} is +only waiting for a broadcast response a longer timeout is +likely needed. +@node sntp wait +@subsection wait option +@cindex sntp-wait + +This is the ``wait for pending replies (if not setting the time)'' option. + +@noindent +This option has some usage constraints. It: +@itemize @bullet +@item +can be disabled with --no-wait. +@item +It is enabled by default. +@end itemize + +If we are not setting the time, wait for all pending responses. + + +@node sntp config +@subsection presetting/configuring sntp + +Any option that is not marked as @i{not presettable} may be preset by +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 +the options listed above in upper case and segmented with underscores. +The @code{SNTP} variable will be tokenized and parsed like +the command line. The remaining variables are tested for existence and their +values are treated like option arguments. + + +@noindent +@code{libopts} will search in 2 places for configuration files: +@itemize @bullet +@item +$HOME +@item +$PWD +@end itemize +The environment variables @code{HOME}, and @code{PWD} +are expanded and replaced when @file{sntp} runs. +For any of these that are plain files, they are simply processed. +For any that are directories, then a file named @file{.ntprc} is searched for +within that directory and processed. + +Configuration files may be in a wide variety of formats. +The basic format is an option name followed by a value (argument) on the +same line. Values may be separated from the option name with a colon, +equal sign or simply white space. Values may be continued across multiple +lines by escaping the newline with a backslash. + +Multiple programs may also share the same initialization file. +Common options are collected at the top, followed by program specific +segments. The segments are separated by lines like: +@example +[SNTP] +@end example +@noindent +or by +@example +<?program sntp> +@end example +@noindent +Do not mix these styles within one configuration file. + +Compound values and carefully constructed string values may also be +specified using XML syntax: +@example +<option-name> + <sub-opt>...<...>...</sub-opt> +</option-name> +@end example +@noindent +yielding an @code{option-name.sub-opt} string value of +@example +"...<...>..." +@end example +@code{AutoOpts} does not track suboptions. You simply note that it is a +hierarchicly valued option. @code{AutoOpts} does provide a means for searching +the associated name/value pair list (see: optionFindValue). + +The command line options relating to configuration and/or usage help are: + +@subsubheading version (-) + +Print the program version to standard out, optionally with licensing +information, then exit 0. The optional argument specifies how much licensing +detail to provide. The default is to print just the version. The licensing infomation may be selected with an option argument. +Only the first letter of the argument is examined: + +@table @samp +@item version +Only print the version. This is the default. +@item copyright +Name the copyright usage licensing terms. +@item verbose +Print the full copyright usage licensing terms. +@end table + +@node sntp exit status +@subsection sntp exit status + +One of the following exit values will be returned: +@table @samp +@item 0 (EXIT_SUCCESS) +Successful program execution. +@item 1 (EXIT_FAILURE) +The operation failed or the command syntax was not valid. +@item 66 (EX_NOINPUT) +A specified configuration file could not be loaded. +@item 70 (EX_SOFTWARE) +libopts had an internal operational error. Please report +it to autogen-users@@lists.sourceforge.net. Thank you. +@end table +@node sntp Usage +@subsection sntp Usage +@node sntp Authors +@subsection sntp Authors |