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 6, 2023 at 04:36:12 AM by AutoGen 5.18.16 10# From the definitions sntp-opts.def 11# and the template file agtexi-cmd.tpl 12@end ignore 13 14 15 16@code{sntp} 17can be used as an SNTP client to query a NTP or SNTP server and either display 18the time or set the local system's time (given suitable privilege). It can be 19run as an interactive command or from a 20@code{cron} 21job. 22 23NTP (the Network Time Protocol) and SNTP (the Simple Network Time Protocol) 24are defined and described by RFC 5905. 25 26 27The default is to write the estimated correct local date and time (i.e. not 28UTC) to the standard output in a format like: 29 30@code{'1996-10-15 20:17:25.123 (+0800) +4.567 +/- 0.089 [host] IP sN'} 31 32where the 33@code{'(+0800)'} 34means that to get to UTC from the reported local time one must 35add 8 hours and 0 minutes, 36the 37@code{'+4.567'} 38indicates 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). 40Note that the number of decimals printed for this value will change 41based on the reported precision of the server. 42@code{'+/- 0.089'} 43is the reported 44@emph{synchronization} @emph{distance} 45(in seconds), which represents the maximum error due to all causes. 46If the server does not report valid data needed to calculate the 47synchronization distance, this will be reported as 48@code{'+/- ?'}. 49If the 50@emph{host} 51is different from the 52@emph{IP}, 53both will be displayed. 54Otherwise, only the 55@emph{IP} 56is displayed. 57Finally, the 58@emph{stratum} 59of the host is reported 60and the leap indicator is decoded and displayed. 61 62This section was generated by @strong{AutoGen}, 63using the @code{agtexi-cmd} template and the option descriptions for the @code{sntp} program. 64This software is released under the NTP license, <http://ntp.org/license>. 65 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 87 88@node sntp usage 89@subsection sntp help/usage (@option{--help}) 90@cindex sntp help 91 92This is the automatically generated usage text for sntp. 93 94The 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 96the 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 99used to select the program, defaulting to @file{more}. Both will exit 100with a status code of 0. 101 102@exampleindent 0 103@example 104sntp - standard Simple Network Time Protocol client program - Ver. 4.2.8p17 105Usage: 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 145 146Options are specified by doubled hyphens and their name or by a single 147hyphen and the flag character. 148 149 150The following option preset mechanisms are supported: 151 - reading file $HOME/.ntprc 152 - reading file ./.ntprc 153 - examining environment variables named SNTP_* 154 155Please send bug reports to: <https://bugs.ntp.org, bugs@@ntp.org> 156@end example 157@exampleindent 4 158 159@node sntp ipv4 160@subsection ipv4 option (-4) 161@cindex sntp-ipv4 162 163This is the ``force ipv4 dns name resolution'' option. 164 165@noindent 166This option has some usage constraints. It: 167@itemize @bullet 168@item 169must not appear in combination with any of the following options: 170ipv6. 171@end itemize 172 173Force DNS resolution of the following host names on the command line 174to the IPv4 namespace. 175@node sntp ipv6 176@subsection ipv6 option (-6) 177@cindex sntp-ipv6 178 179This is the ``force ipv6 dns name resolution'' option. 180 181@noindent 182This option has some usage constraints. It: 183@itemize @bullet 184@item 185must not appear in combination with any of the following options: 186ipv4. 187@end itemize 188 189Force DNS resolution of the following host names on the command line 190to the IPv6 namespace. 191@node sntp authentication 192@subsection authentication option (-a) 193@cindex sntp-authentication 194 195This is the ``enable authentication with the key @var{auth-keynumber}'' option. 196This option takes a number argument @file{auth-keynumber}. 197Enable authentication using the key specified in this option's 198argument. The argument of this option is the @option{keyid}, a 199number specified in the @option{keyfile} as this key's identifier. 200See the @option{keyfile} option (@option{-k}) for more details. 201@node sntp broadcast 202@subsection broadcast option (-b) 203@cindex sntp-broadcast 204 205This is the ``listen to the address specified for broadcast time sync'' option. 206This option takes a string argument @file{broadcast-address}. 207 208@noindent 209This option has some usage constraints. It: 210@itemize @bullet 211@item 212may appear an unlimited number of times. 213@end itemize 214 215If specified @code{sntp} will listen to the specified address 216for NTP broadcasts. The default maximum wait time 217can (and probably should) be modified with @option{-t}. 218@node sntp concurrent 219@subsection concurrent option (-c) 220@cindex sntp-concurrent 221 222This is the ``concurrently query all ips returned for host-name'' option. 223This option takes a string argument @file{host-name}. 224 225@noindent 226This option has some usage constraints. It: 227@itemize @bullet 228@item 229may appear an unlimited number of times. 230@end itemize 231 232Requests from an NTP "client" to a "server" should never be sent 233more rapidly than one every 2 seconds. By default, any IPs returned 234as 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 236one after another, with a 2-second gap in between each query. 237 238The @option{-c} or @option{--concurrent} flag says that any IPs 239returned for the DNS lookup of the supplied host-name are on 240different machines, so we can send concurrent queries. 241@node sntp gap 242@subsection gap option (-g) 243@cindex sntp-gap 244 245This is the ``the gap (in milliseconds) between time requests'' option. 246This option takes a number argument @file{milliseconds}. 247Since we're only going to use the first valid response we get and 248there is benefit to specifying a good number of servers to query, 249separate the queries we send out by the specified number of 250milliseconds. 251@node sntp kod 252@subsection kod option (-K) 253@cindex sntp-kod 254 255This is the ``kod history filename'' option. 256This option takes a file argument @file{file-name}. 257Specifies the filename to be used for the persistent history of KoD 258responses received from servers. If the file does not exist, a 259warning message will be displayed. The file will not be created. 260@node sntp keyfile 261@subsection keyfile option (-k) 262@cindex sntp-keyfile 263 264This is the ``look in this file for the key specified with @option{-a}'' option. 265This option takes a file argument @file{file-name}. 266This 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 269information. 270@node sntp logfile 271@subsection logfile option (-l) 272@cindex sntp-logfile 273 274This is the ``log to specified logfile'' option. 275This option takes a file argument @file{file-name}. 276This 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 281 282This is the ``adjustments less than @var{steplimit} msec will be slewed'' option. 283This option takes a number argument. 284If the time adjustment is less than @file{steplimit} milliseconds, 285slew the amount using @command{adjtime(2)}. Otherwise, step the 286correction using @command{settimeofday(2)}. The default value is 0, 287which means all adjustments will be stepped. This is a feature, as 288different situations demand different values. 289@node sntp ntpversion 290@subsection ntpversion option (-o) 291@cindex sntp-ntpversion 292 293This is the ``send @var{int} as our ntp protocol version'' option. 294This option takes a number argument. 295When sending requests to a remote server, tell them we are running 296NTP protocol version @file{ntpversion} . 297@node sntp usereservedport 298@subsection usereservedport option (-r) 299@cindex sntp-usereservedport 300 301This is the ``use the ntp reserved port (port 123)'' option. 302Use port 123, which is reserved for NTP, for our network 303communications. 304@node sntp timeout 305@subsection timeout option (-t) 306@cindex sntp-timeout 307 308This is the ``the number of seconds to wait for responses'' option. 309This option takes a number argument @file{seconds}. 310When waiting for a reply, @code{sntp} will wait the number 311of seconds specified before giving up. The default should be 312more than enough for a unicast response. If @code{sntp} is 313only waiting for a broadcast response a longer timeout is 314likely needed. 315@node sntp wait 316@subsection wait option 317@cindex sntp-wait 318 319This is the ``wait for pending replies (if not setting the time)'' option. 320 321@noindent 322This option has some usage constraints. It: 323@itemize @bullet 324@item 325can be disabled with --no-wait. 326@item 327It is enabled by default. 328@end itemize 329 330If we are not setting the time, wait for all pending responses. 331 332 333@node sntp config 334@subsection presetting/configuring sntp 335 336Any option that is not marked as @i{not presettable} may be preset by 337loading 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 338the options listed above in upper case and segmented with underscores. 339The @code{SNTP} variable will be tokenized and parsed like 340the command line. The remaining variables are tested for existence and their 341values are treated like option arguments. 342 343 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 352The environment variables @code{HOME}, and @code{PWD} 353are expanded and replaced when @file{sntp} runs. 354For any of these that are plain files, they are simply processed. 355For any that are directories, then a file named @file{.ntprc} is searched for 356within that directory and processed. 357 358Configuration files may be in a wide variety of formats. 359The basic format is an option name followed by a value (argument) on the 360same line. Values may be separated from the option name with a colon, 361equal sign or simply white space. Values may be continued across multiple 362lines by escaping the newline with a backslash. 363 364Multiple programs may also share the same initialization file. 365Common options are collected at the top, followed by program specific 366segments. The segments are separated by lines like: 367@example 368[SNTP] 369@end example 370@noindent 371or by 372@example 373<?program sntp> 374@end example 375@noindent 376Do not mix these styles within one configuration file. 377 378Compound values and carefully constructed string values may also be 379specified using XML syntax: 380@example 381<option-name> 382 <sub-opt>...<...>...</sub-opt> 383</option-name> 384@end example 385@noindent 386yielding 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 391hierarchicly valued option. @code{AutoOpts} does provide a means for searching 392the associated name/value pair list (see: optionFindValue). 393 394The command line options relating to configuration and/or usage help are: 395 396@subsubheading version (-) 397 398Print the program version to standard out, optionally with licensing 399information, then exit 0. The optional argument specifies how much licensing 400detail to provide. The default is to print just the version. The licensing information may be selected with an option argument. 401Only the first letter of the argument is examined: 402 403@table @samp 404@item version 405Only print the version. This is the default. 406@item copyright 407Name the copyright usage licensing terms. 408@item verbose 409Print the full copyright usage licensing terms. 410@end table 411 412@node sntp exit status 413@subsection sntp exit status 414 415One of the following exit values will be returned: 416@table @samp 417@item 0 (EXIT_SUCCESS) 418Successful program execution. 419@item 1 (EXIT_FAILURE) 420The operation failed or the command syntax was not valid. 421@item 66 (EX_NOINPUT) 422A specified configuration file could not be loaded. 423@item 70 (EX_SOFTWARE) 424libopts had an internal operational error. Please report 425it 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 431