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 February 27, 2018 at 05:13:11 PM by AutoGen 5.18.5 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.7p245 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 these options: 110 ipv6 111 -6 no ipv6 Force IPv6 DNS name resolution 112 - prohibits these options: 113 ipv4 114 -a Num authentication Enable authentication with the key @@var@{auth-keynumber@} 115 -B Num bctimeout The number of seconds to wait for broadcasts 116 -b Str broadcast Listen to the address specified for broadcast time sync 117 - may appear multiple times 118 -c Str concurrent Concurrently query all IPs returned for host-name 119 - may appear multiple times 120 -d no debug-level Increase debug verbosity level 121 - may appear multiple times 122 -D Str set-debug-level Set the debug verbosity level 123 - may appear multiple times 124 -g Num gap The gap (in milliseconds) between time requests 125 -K Fil kod KoD history filename 126 -k Fil keyfile Look in this file for the key specified with @@option@{-a@} 127 -l Fil logfile Log to specified logfile 128 -M Num steplimit Adjustments less than @@var@{steplimit@} msec will be slewed 129 - It must be in the range: 130 greater than or equal to 0 131 -o Num ntpversion Send @@var@{int@} as our NTP version 132 - It must be in the range: 133 0 to 7 134 -r no usereservedport Use the NTP Reserved Port (port 123) 135 -S no step OK to 'step' the time with @@command@{settimeofday(2)@} 136 -s no slew OK to 'slew' the time with @@command@{adjtime(2)@} 137 -u Num uctimeout The number of seconds to wait for unicast responses 138 no wait Wait for pending replies (if not setting the time) 139 - disabled as --no-wait 140 - enabled by default 141 opt version Output version information and exit 142 -? no help Display extended usage information and exit 143 -! no more-help Extended usage information passed thru pager 144 -> opt save-opts Save the option state to a config file 145 -< Str load-opts Load options from a config file 146 - disabled as --no-load-opts 147 - may appear multiple times 148 149Options are specified by doubled hyphens and their name or by a single 150hyphen and the flag character. 151 152 153 154The following option preset mechanisms are supported: 155 - reading file $HOME/.ntprc 156 - reading file ./.ntprc 157 - examining environment variables named SNTP_* 158 159please send bug reports to: http://bugs.ntp.org, bugs@@ntp.org 160@end example 161@exampleindent 4 162 163@node sntp ipv4 164@subsection ipv4 option (-4) 165@cindex sntp-ipv4 166 167This is the ``force ipv4 dns name resolution'' option. 168 169@noindent 170This option has some usage constraints. It: 171@itemize @bullet 172@item 173must not appear in combination with any of the following options: 174ipv6. 175@end itemize 176 177Force DNS resolution of the following host names on the command line 178to the IPv4 namespace. 179@node sntp ipv6 180@subsection ipv6 option (-6) 181@cindex sntp-ipv6 182 183This is the ``force ipv6 dns name resolution'' option. 184 185@noindent 186This option has some usage constraints. It: 187@itemize @bullet 188@item 189must not appear in combination with any of the following options: 190ipv4. 191@end itemize 192 193Force DNS resolution of the following host names on the command line 194to the IPv6 namespace. 195@node sntp authentication 196@subsection authentication option (-a) 197@cindex sntp-authentication 198 199This is the ``enable authentication with the key @var{auth-keynumber}'' option. 200This option takes a number argument @file{auth-keynumber}. 201Enable authentication using the key specified in this option's 202argument. The argument of this option is the @option{keyid}, a 203number specified in the @option{keyfile} as this key's identifier. 204See the @option{keyfile} option (@option{-k}) for more details. 205@node sntp broadcast 206@subsection broadcast option (-b) 207@cindex sntp-broadcast 208 209This is the ``listen to the address specified for broadcast time sync'' option. 210This option takes a string argument @file{broadcast-address}. 211 212@noindent 213This option has some usage constraints. It: 214@itemize @bullet 215@item 216may appear an unlimited number of times. 217@end itemize 218 219If specified @code{sntp} will listen to the specified address 220for NTP broadcasts. The default maximum wait time 221can (and probably should) be modified with @option{-t}. 222@node sntp concurrent 223@subsection concurrent option (-c) 224@cindex sntp-concurrent 225 226This is the ``concurrently query all ips returned for host-name'' option. 227This option takes a string argument @file{host-name}. 228 229@noindent 230This option has some usage constraints. It: 231@itemize @bullet 232@item 233may appear an unlimited number of times. 234@end itemize 235 236Requests from an NTP "client" to a "server" should never be sent 237more rapidly than one every 2 seconds. By default, any IPs returned 238as part of a DNS lookup are assumed to be for a single instance of 239@code{ntpd}, and therefore @code{sntp} will send queries to these IPs 240one after another, with a 2-second gap in between each query. 241 242The @option{-c} or @option{--concurrent} flag says that any IPs 243returned for the DNS lookup of the supplied host-name are on 244different machines, so we can send concurrent queries. 245@node sntp gap 246@subsection gap option (-g) 247@cindex sntp-gap 248 249This is the ``the gap (in milliseconds) between time requests'' option. 250This option takes a number argument @file{milliseconds}. 251Since we're only going to use the first valid response we get and 252there is benefit to specifying a good number of servers to query, 253separate the queries we send out by the specified number of 254milliseconds. 255@node sntp kod 256@subsection kod option (-K) 257@cindex sntp-kod 258 259This is the ``kod history filename'' option. 260This option takes a file argument @file{file-name}. 261Specifies the filename to be used for the persistent history of KoD 262responses received from servers. If the file does not exist, a 263warning message will be displayed. The file will not be created. 264@node sntp keyfile 265@subsection keyfile option (-k) 266@cindex sntp-keyfile 267 268This is the ``look in this file for the key specified with @option{-a}'' option. 269This option takes a file argument @file{file-name}. 270This option specifies the keyfile. 271@code{sntp} will search for the key specified with @option{-a} 272@file{keyno} in this file. See @command{ntp.keys(5)} for more 273information. 274@node sntp logfile 275@subsection logfile option (-l) 276@cindex sntp-logfile 277 278This is the ``log to specified logfile'' option. 279This option takes a file argument @file{file-name}. 280This option causes the client to write log messages to the specified 281@file{logfile}. 282@node sntp steplimit 283@subsection steplimit option (-M) 284@cindex sntp-steplimit 285 286This is the ``adjustments less than @var{steplimit} msec will be slewed'' option. 287This option takes a number argument. 288If the time adjustment is less than @file{steplimit} milliseconds, 289slew the amount using @command{adjtime(2)}. Otherwise, step the 290correction using @command{settimeofday(2)}. The default value is 0, 291which means all adjustments will be stepped. This is a feature, as 292different situations demand different values. 293@node sntp ntpversion 294@subsection ntpversion option (-o) 295@cindex sntp-ntpversion 296 297This is the ``send @var{int} as our ntp protocol version'' option. 298This option takes a number argument. 299When sending requests to a remote server, tell them we are running 300NTP protocol version @file{ntpversion} . 301@node sntp usereservedport 302@subsection usereservedport option (-r) 303@cindex sntp-usereservedport 304 305This is the ``use the ntp reserved port (port 123)'' option. 306Use port 123, which is reserved for NTP, for our network 307communications. 308@node sntp timeout 309@subsection timeout option (-t) 310@cindex sntp-timeout 311 312This is the ``the number of seconds to wait for responses'' option. 313This option takes a number argument @file{seconds}. 314When waiting for a reply, @code{sntp} will wait the number 315of seconds specified before giving up. The default should be 316more than enough for a unicast response. If @code{sntp} is 317only waiting for a broadcast response a longer timeout is 318likely needed. 319@node sntp wait 320@subsection wait option 321@cindex sntp-wait 322 323This is the ``wait for pending replies (if not setting the time)'' option. 324 325@noindent 326This option has some usage constraints. It: 327@itemize @bullet 328@item 329can be disabled with --no-wait. 330@item 331It is enabled by default. 332@end itemize 333 334If we are not setting the time, wait for all pending responses. 335 336 337@node sntp config 338@subsection presetting/configuring sntp 339 340Any option that is not marked as @i{not presettable} may be preset by 341loading 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 342the options listed above in upper case and segmented with underscores. 343The @code{SNTP} variable will be tokenized and parsed like 344the command line. The remaining variables are tested for existence and their 345values are treated like option arguments. 346 347 348@noindent 349@code{libopts} will search in 2 places for configuration files: 350@itemize @bullet 351@item 352$HOME 353@item 354$PWD 355@end itemize 356The environment variables @code{HOME}, and @code{PWD} 357are expanded and replaced when @file{sntp} runs. 358For any of these that are plain files, they are simply processed. 359For any that are directories, then a file named @file{.ntprc} is searched for 360within that directory and processed. 361 362Configuration files may be in a wide variety of formats. 363The basic format is an option name followed by a value (argument) on the 364same line. Values may be separated from the option name with a colon, 365equal sign or simply white space. Values may be continued across multiple 366lines by escaping the newline with a backslash. 367 368Multiple programs may also share the same initialization file. 369Common options are collected at the top, followed by program specific 370segments. The segments are separated by lines like: 371@example 372[SNTP] 373@end example 374@noindent 375or by 376@example 377<?program sntp> 378@end example 379@noindent 380Do not mix these styles within one configuration file. 381 382Compound values and carefully constructed string values may also be 383specified using XML syntax: 384@example 385<option-name> 386 <sub-opt>...<...>...</sub-opt> 387</option-name> 388@end example 389@noindent 390yielding an @code{option-name.sub-opt} string value of 391@example 392"...<...>..." 393@end example 394@code{AutoOpts} does not track suboptions. You simply note that it is a 395hierarchicly valued option. @code{AutoOpts} does provide a means for searching 396the associated name/value pair list (see: optionFindValue). 397 398The command line options relating to configuration and/or usage help are: 399 400@subsubheading version (-) 401 402Print the program version to standard out, optionally with licensing 403information, then exit 0. The optional argument specifies how much licensing 404detail to provide. The default is to print just the version. The licensing infomation may be selected with an option argument. 405Only the first letter of the argument is examined: 406 407@table @samp 408@item version 409Only print the version. This is the default. 410@item copyright 411Name the copyright usage licensing terms. 412@item verbose 413Print the full copyright usage licensing terms. 414@end table 415 416@node sntp exit status 417@subsection sntp exit status 418 419One of the following exit values will be returned: 420@table @samp 421@item 0 (EXIT_SUCCESS) 422Successful program execution. 423@item 1 (EXIT_FAILURE) 424The operation failed or the command syntax was not valid. 425@item 66 (EX_NOINPUT) 426A specified configuration file could not be loaded. 427@item 70 (EX_SOFTWARE) 428libopts had an internal operational error. Please report 429it to autogen-users@@lists.sourceforge.net. Thank you. 430@end table 431@node sntp Usage 432@subsection sntp Usage 433@node sntp Authors 434@subsection sntp Authors 435