invoke-sntp.texi revision 298770
152400Sbillf@node sntp Invocation 252400Sbillf@section Invoking sntp 352400Sbillf@pindex sntp 452400Sbillf@cindex standard Simple Network Time Protocol client program 552400Sbillf@ignore 652400Sbillf# 752400Sbillf# EDIT THIS FILE WITH CAUTION (invoke-sntp.texi) 890564Sdougb# 973651Sdougb# It has been AutoGen-ed April 26, 2016 at 08:21:12 PM by AutoGen 5.18.5 1052400Sbillf# From the definitions sntp-opts.def 1152495Sbillf# and the template file agtexi-cmd.tpl 1252400Sbillf@end ignore 1368507Sdougb 1452400Sbillf 1552400Sbillf 1652533Sbillf@code{sntp} 1752400Sbillfcan be used as an SNTP client to query a NTP or SNTP server and either display 1891193Sdougbthe time or set the local system's time (given suitable privilege). It can be 1967949Sdougbrun as an interactive command or from a 2052400Sbillf@code{cron} 2152400Sbillfjob. 2252400Sbillf 2352400SbillfNTP (the Network Time Protocol) and SNTP (the Simple Network Time Protocol) 2452400Sbillfare defined and described by RFC 5905. 2552400Sbillf 2652400Sbillf 2767949SdougbThe default is to write the estimated correct local date and time (i.e. not 2891193SdougbUTC) to the standard output in a format like: 2991193Sdougb 3052400Sbillf@code{'1996-10-15 20:17:25.123 (+0800) +4.567 +/- 0.089 [host] IP sN'} 3152400Sbillf 3252400Sbillfwhere the 3352400Sbillf@code{'(+0800)'} 3452400Sbillfmeans that to get to UTC from the reported local time one must 3567949Sdougbadd 8 hours and 0 minutes, 3652400Sbillfthe 3752400Sbillf@code{'+4.567'} 3852400Sbillfindicates the local clock is 4.567 seconds behind the correct time 3952400Sbillf(so 4.567 seconds must be added to the local clock to get it to be correct). 4052400SbillfNote that the number of decimals printed for this value will change 4152400Sbillfbased on the reported precision of the server. 4252400Sbillf@code{'+/- 0.089'} 4367859Sdougbis the reported 4467949Sdougb@emph{synchronization} @emph{distance} 4552400Sbillf(in seconds), which represents the maximum error due to all causes. 4652400SbillfIf the server does not report valid data needed to calculate the 4758910Salfredsynchronization distance, this will be reported as 4858910Salfred@code{'+/- ?'}. 4958910SalfredIf the 5067850Sdougb@emph{host} 5167850Sdougbis different from the 5267850Sdougb@emph{IP}, 5367850Sdougbboth will be displayed. 5467850SdougbOtherwise, only the 5567850Sdougb@emph{IP} 5667850Sdougbis displayed. 5767850SdougbFinally, the 5867850Sdougb@emph{stratum} 5967850Sdougbof the host is reported 6067850Sdougband the leap indicator is decoded and displayed. 6167850Sdougb 6267949SdougbThis section was generated by @strong{AutoGen}, 6367850Sdougbusing the @code{agtexi-cmd} template and the option descriptions for the @code{sntp} program. 6467850SdougbThis software is released under the NTP license, <http://ntp.org/license>. 6567850Sdougb 6667850Sdougb@menu 6767850Sdougb* sntp usage:: sntp help/usage (@option{--help}) 6867850Sdougb* sntp ipv4:: ipv4 option (-4) 6967850Sdougb* sntp ipv6:: ipv6 option (-6) 7067850Sdougb* sntp authentication:: authentication option (-a) 7167859Sdougb* sntp broadcast:: broadcast option (-b) 7267859Sdougb* sntp concurrent:: concurrent option (-c) 7358910Salfred* sntp gap:: gap option (-g) 7467850Sdougb* sntp kod:: kod option (-K) 7567850Sdougb* sntp keyfile:: keyfile option (-k) 7667850Sdougb* sntp logfile:: logfile option (-l) 7767850Sdougb* sntp steplimit:: steplimit option (-M) 7867850Sdougb* sntp ntpversion:: ntpversion option (-o) 7967850Sdougb* sntp usereservedport:: usereservedport option (-r) 8067859Sdougb* sntp timeout:: timeout option (-t) 8167850Sdougb* sntp wait:: wait option 8267859Sdougb* sntp config:: presetting/configuring sntp 8367850Sdougb* sntp exit status:: exit status 8467850Sdougb* sntp Usage:: Usage 8567850Sdougb* sntp Authors:: Authors 8667850Sdougb@end menu 8767859Sdougb 8867850Sdougb@node sntp usage 8967850Sdougb@subsection sntp help/usage (@option{--help}) 9067850Sdougb@cindex sntp help 9167850Sdougb 9267850SdougbThis is the automatically generated usage text for sntp. 9367850Sdougb 9467850SdougbThe text printed is the same whether selected with the @code{help} option 9567850Sdougb(@option{--help}) or the @code{more-help} option (@option{--more-help}). @code{more-help} will print 9667850Sdougbthe usage text by passing it through a pager program. 9767850Sdougb@code{more-help} is disabled on platforms without a working 9867850Sdougb@code{fork(2)} function. The @code{PAGER} environment variable is 9967850Sdougbused to select the program, defaulting to @file{more}. Both will exit 10067850Sdougbwith a status code of 0. 10167850Sdougb 10258910Salfred@exampleindent 0 10358910Salfred@example 10458910Salfredsntp - standard Simple Network Time Protocol client program - Ver. 4.2.8p7 10558910SalfredUsage: sntp [ -<flag> [<val>] | --<name>[@{=| @}<val>] ]... \ 10658910Salfred [ hostname-or-IP ...] 10758910Salfred Flg Arg Option-Name Description 10867850Sdougb -4 no ipv4 Force IPv4 DNS name resolution 10958910Salfred - prohibits the option 'ipv6' 11077323Sdougb -6 no ipv6 Force IPv6 DNS name resolution 11177323Sdougb - prohibits the option 'ipv4' 11267949Sdougb -a Num authentication Enable authentication with the key auth-keynumber 11367850Sdougb -b Str broadcast Listen to the address specified for broadcast time sync 11490564Sdougb - may appear multiple times 11590564Sdougb -c Str concurrent Concurrently query all IPs returned for host-name 11690564Sdougb - may appear multiple times 11767850Sdougb -d no debug-level Increase debug verbosity level 11867949Sdougb - may appear multiple times 11967850Sdougb -D Num set-debug-level Set the debug verbosity level 12067850Sdougb - may appear multiple times 12167949Sdougb -g Num gap The gap (in milliseconds) between time requests 12267850Sdougb -K Fil kod KoD history filename 12367850Sdougb -k Fil keyfile Look in this file for the key specified with -a 12467850Sdougb -l Fil logfile Log to specified logfile 12567850Sdougb -M Num steplimit Adjustments less than steplimit msec will be slewed 12667949Sdougb - it must be in the range: 12767850Sdougb greater than or equal to 0 12891193Sdougb -o Num ntpversion Send int as our NTP protocol version 12967949Sdougb - it must be in the range: 13067949Sdougb 0 to 7 13167949Sdougb -r no usereservedport Use the NTP Reserved Port (port 123) 13267949Sdougb -S no step OK to 'step' the time with settimeofday(2) 13367949Sdougb -s no slew OK to 'slew' the time with adjtime(2) 13468507Sdougb -t Num timeout The number of seconds to wait for responses 13567949Sdougb no wait Wait for pending replies (if not setting the time) 13667949Sdougb - disabled as '--no-wait' 13767949Sdougb - enabled by default 13867949Sdougb opt version output version information and exit 13967949Sdougb -? no help display extended usage information and exit 14067949Sdougb -! no more-help extended usage information passed thru pager 14167949Sdougb -> opt save-opts save the option state to a config file 14267949Sdougb -< Str load-opts load options from a config file 14367949Sdougb - disabled as '--no-load-opts' 14467949Sdougb - may appear multiple times 14567949Sdougb 14667949SdougbOptions are specified by doubled hyphens and their name or by a single 14767850Sdougbhyphen and the flag character. 14867859Sdougb 14967850Sdougb 15067850SdougbThe following option preset mechanisms are supported: 15167850Sdougb - reading file $HOME/.ntprc 15267850Sdougb - reading file ./.ntprc 15377326Sdougb - examining environment variables named SNTP_* 15477326Sdougb 15567850SdougbPlease send bug reports to: <http://bugs.ntp.org, bugs@@ntp.org> 15667850Sdougb@end example 15767850Sdougb@exampleindent 4 15867850Sdougb 15967850Sdougb@node sntp ipv4 16067859Sdougb@subsection ipv4 option (-4) 16167859Sdougb@cindex sntp-ipv4 16267859Sdougb 16367850SdougbThis is the ``force ipv4 dns name resolution'' option. 16467850Sdougb 16567850Sdougb@noindent 16667850SdougbThis option has some usage constraints. It: 16767850Sdougb@itemize @bullet 16867850Sdougb@item 16967850Sdougbmust not appear in combination with any of the following options: 17067850Sdougbipv6. 17167850Sdougb@end itemize 17267850Sdougb 17367850SdougbForce DNS resolution of the following host names on the command line 17467850Sdougbto the IPv4 namespace. 17567850Sdougb@node sntp ipv6 17667850Sdougb@subsection ipv6 option (-6) 17767850Sdougb@cindex sntp-ipv6 17867850Sdougb 17967850SdougbThis is the ``force ipv6 dns name resolution'' option. 18067850Sdougb 18167850Sdougb@noindent 18267850SdougbThis option has some usage constraints. It: 18367850Sdougb@itemize @bullet 18467850Sdougb@item 18567850Sdougbmust not appear in combination with any of the following options: 18667850Sdougbipv4. 18767850Sdougb@end itemize 18867850Sdougb 18967850SdougbForce DNS resolution of the following host names on the command line 19067850Sdougbto the IPv6 namespace. 19167850Sdougb@node sntp authentication 19267850Sdougb@subsection authentication option (-a) 19367850Sdougb@cindex sntp-authentication 19467850Sdougb 19567850SdougbThis is the ``enable authentication with the key @var{auth-keynumber}'' option. 19667850SdougbThis option takes a number argument @file{auth-keynumber}. 19767850SdougbEnable authentication using the key specified in this option's 19867850Sdougbargument. The argument of this option is the @option{keyid}, a 19967850Sdougbnumber specified in the @option{keyfile} as this key's identifier. 20067850SdougbSee the @option{keyfile} option (@option{-k}) for more details. 20167850Sdougb@node sntp broadcast 20267850Sdougb@subsection broadcast option (-b) 20367850Sdougb@cindex sntp-broadcast 20467850Sdougb 20567850SdougbThis is the ``listen to the address specified for broadcast time sync'' option. 20667859SdougbThis option takes a string argument @file{broadcast-address}. 20767850Sdougb 20867850Sdougb@noindent 20967850SdougbThis option has some usage constraints. It: 21067850Sdougb@itemize @bullet 21167850Sdougb@item 21267850Sdougbmay appear an unlimited number of times. 21367850Sdougb@end itemize 21467850Sdougb 21558910SalfredIf specified @code{sntp} will listen to the specified address 21658910Salfredfor NTP broadcasts. The default maximum wait time 21797960Sdougbcan (and probably should) be modified with @option{-t}. 21897960Sdougb@node sntp concurrent 21997960Sdougb@subsection concurrent option (-c) 22097960Sdougb@cindex sntp-concurrent 22197960Sdougb 22297960SdougbThis is the ``concurrently query all ips returned for host-name'' option. 22352400SbillfThis option takes a string argument @file{host-name}. 22452400Sbillf 22552400Sbillf@noindent 22652400SbillfThis option has some usage constraints. It: 22773651Sdougb@itemize @bullet 22873651Sdougb@item 22973651Sdougbmay appear an unlimited number of times. 23073651Sdougb@end itemize 23173651Sdougb 23273651SdougbRequests from an NTP "client" to a "server" should never be sent 23352400Sbillfmore rapidly than one every 2 seconds. By default, any IPs returned 23452400Sbillfas part of a DNS lookup are assumed to be for a single instance of 23567949Sdougb@code{ntpd}, and therefore @code{sntp} will send queries to these IPs 23652400Sbillfone after another, with a 2-second gap in between each query. 23752400Sbillf 23852400SbillfThe @option{-c} or @option{--concurrent} flag says that any IPs 23952400Sbillfreturned for the DNS lookup of the supplied host-name are on 24052400Sbillfdifferent machines, so we can send concurrent queries. 24191193Sdougb@node sntp gap 24252400Sbillf@subsection gap option (-g) 24352400Sbillf@cindex sntp-gap 24452400Sbillf 24552400SbillfThis is the ``the gap (in milliseconds) between time requests'' option. 24652400SbillfThis option takes a number argument @file{milliseconds}. 24752400SbillfSince we're only going to use the first valid response we get and 24852400Sbillfthere is benefit to specifying a good number of servers to query, 24952400Sbillfseparate the queries we send out by the specified number of 25052400Sbillfmilliseconds. 25152400Sbillf@node sntp kod 25252400Sbillf@subsection kod option (-K) 25352400Sbillf@cindex sntp-kod 25452400Sbillf 25552400SbillfThis is the ``kod history filename'' option. 25652400SbillfThis option takes a file argument @file{file-name}. 25752400SbillfSpecifies the filename to be used for the persistent history of KoD 25852400Sbillfresponses received from servers. If the file does not exist, a 25952400Sbillfwarning message will be displayed. The file will not be created. 26052400Sbillf@node sntp keyfile 26152400Sbillf@subsection keyfile option (-k) 26252400Sbillf@cindex sntp-keyfile 26352400Sbillf 26452400SbillfThis is the ``look in this file for the key specified with @option{-a}'' option. 26552400SbillfThis option takes a file argument @file{file-name}. 26667949SdougbThis option specifies the keyfile. 26767949Sdougb@code{sntp} will search for the key specified with @option{-a} 26867949Sdougb@file{keyno} in this file. See @command{ntp.keys(5)} for more 26996045Sdougbinformation. 27096045Sdougb@node sntp logfile 27196045Sdougb@subsection logfile option (-l) 27291193Sdougb@cindex sntp-logfile 27391193Sdougb 27496045SdougbThis is the ``log to specified logfile'' option. 27596045SdougbThis option takes a file argument @file{file-name}. 27691193SdougbThis option causes the client to write log messages to the specified 27752400Sbillf@file{logfile}. 27852400Sbillf@node sntp steplimit 27952400Sbillf@subsection steplimit option (-M) 28052400Sbillf@cindex sntp-steplimit 28152400Sbillf 28252400SbillfThis is the ``adjustments less than @var{steplimit} msec will be slewed'' option. 28352400SbillfThis option takes a number argument. 28452400SbillfIf the time adjustment is less than @file{steplimit} milliseconds, 28552400Sbillfslew the amount using @command{adjtime(2)}. Otherwise, step the 28652400Sbillfcorrection using @command{settimeofday(2)}. The default value is 0, 28752400Sbillfwhich means all adjustments will be stepped. This is a feature, as 28852400Sbillfdifferent situations demand different values. 28952400Sbillf@node sntp ntpversion 29052400Sbillf@subsection ntpversion option (-o) 29152400Sbillf@cindex sntp-ntpversion 29267949Sdougb 29367949SdougbThis is the ``send @var{int} as our ntp protocol version'' option. 29467949SdougbThis option takes a number argument. 29552400SbillfWhen sending requests to a remote server, tell them we are running 29652400SbillfNTP protocol version @file{ntpversion} . 29752400Sbillf@node sntp usereservedport 29852400Sbillf@subsection usereservedport option (-r) 29952400Sbillf@cindex sntp-usereservedport 30052400Sbillf 30152400SbillfThis is the ``use the ntp reserved port (port 123)'' option. 30252400SbillfUse port 123, which is reserved for NTP, for our network 30352400Sbillfcommunications. 30452400Sbillf@node sntp timeout 30552400Sbillf@subsection timeout option (-t) 30652400Sbillf@cindex sntp-timeout 30752400Sbillf 30864467SbrianThis is the ``the number of seconds to wait for responses'' option. 30952400SbillfThis option takes a number argument @file{seconds}. 31064467SbrianWhen waiting for a reply, @code{sntp} will wait the number 31167859Sdougbof seconds specified before giving up. The default should be 31252400Sbillfmore than enough for a unicast response. If @code{sntp} is 31352400Sbillfonly waiting for a broadcast response a longer timeout is 31464467Sbrianlikely needed. 31564467Sbrian@node sntp wait 31652400Sbillf@subsection wait option 31752400Sbillf@cindex sntp-wait 31852400Sbillf 31952400SbillfThis is the ``wait for pending replies (if not setting the time)'' option. 32052400Sbillf 32167859Sdougb@noindent 32267859SdougbThis option has some usage constraints. It: 32367859Sdougb@itemize @bullet 32452400Sbillf@item 32558910Salfredcan be disabled with --no-wait. 32652400Sbillf@item 32752400SbillfIt is enabled by default. 32858910Salfred@end itemize 32964467Sbrian 33064467SbrianIf we are not setting the time, wait for all pending responses. 33164467Sbrian 33258910Salfred 33364467Sbrian@node sntp config 33464467Sbrian@subsection presetting/configuring sntp 33564467Sbrian 33664467SbrianAny option that is not marked as @i{not presettable} may be preset by 33764467Sbrianloading 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 33864467Sbrianthe options listed above in upper case and segmented with underscores. 33958910SalfredThe @code{SNTP} variable will be tokenized and parsed like 34052400Sbillfthe command line. The remaining variables are tested for existence and their 34160420Sbsdvalues are treated like option arguments. 34252400Sbillf 34352400Sbillf 34458910Salfred@noindent 34558910Salfred@code{libopts} will search in 2 places for configuration files: 34658910Salfred@itemize @bullet 34752400Sbillf@item 34852400Sbillf$HOME 34958910Salfred@item 35052400Sbillf$PWD 35152400Sbillf@end itemize 35252400SbillfThe environment variables @code{HOME}, and @code{PWD} 35352400Sbillfare expanded and replaced when @file{sntp} runs. 35452400SbillfFor any of these that are plain files, they are simply processed. 35552400SbillfFor any that are directories, then a file named @file{.ntprc} is searched for 35652400Sbillfwithin that directory and processed. 35752400Sbillf 35852400SbillfConfiguration files may be in a wide variety of formats. 35952400SbillfThe basic format is an option name followed by a value (argument) on the 36052400Sbillfsame line. Values may be separated from the option name with a colon, 36152400Sbillfequal sign or simply white space. Values may be continued across multiple 36252400Sbillflines by escaping the newline with a backslash. 36352400Sbillf 36452400SbillfMultiple programs may also share the same initialization file. 36552400SbillfCommon options are collected at the top, followed by program specific 36652400Sbillfsegments. The segments are separated by lines like: 36752400Sbillf@example 36852400Sbillf[SNTP] 36952400Sbillf@end example 37052400Sbillf@noindent 37152400Sbillfor by 37296045Sdougb@example 37396045Sdougb<?program sntp> 37496045Sdougb@end example 37596045Sdougb@noindent 37696045SdougbDo not mix these styles within one configuration file. 37796045Sdougb 37896045SdougbCompound values and carefully constructed string values may also be 37996045Sdougbspecified using XML syntax: 38096045Sdougb@example 38196045Sdougb<option-name> 38296045Sdougb <sub-opt>...<...>...</sub-opt> 38396045Sdougb</option-name> 38496045Sdougb@end example 38596045Sdougb@noindent 38696045Sdougbyielding an @code{option-name.sub-opt} string value of 38796045Sdougb@example 38897380Sdougb"...<...>..." 38997380Sdougb@end example 39097380Sdougb@code{AutoOpts} does not track suboptions. You simply note that it is a 39196045Sdougbhierarchicly valued option. @code{AutoOpts} does provide a means for searching 39296045Sdougbthe associated name/value pair list (see: optionFindValue). 39396045Sdougb 39496045SdougbThe command line options relating to configuration and/or usage help are: 39596045Sdougb 39673651Sdougb@subsubheading version (-) 39773651Sdougb 39873651SdougbPrint the program version to standard out, optionally with licensing 39973651Sdougbinformation, then exit 0. The optional argument specifies how much licensing 40099152Sdougbdetail to provide. The default is to print just the version. The licensing infomation may be selected with an option argument. 40199152SdougbOnly the first letter of the argument is examined: 40299152Sdougb 40399152Sdougb@table @samp 40499152Sdougb@item version 40599152SdougbOnly print the version. This is the default. 40652400Sbillf@item copyright 40752400SbillfName the copyright usage licensing terms. 40852400Sbillf@item verbose 40952400SbillfPrint the full copyright usage licensing terms. 41052400Sbillf@end table 41152400Sbillf 41252400Sbillf@node sntp exit status 41352400Sbillf@subsection sntp exit status 41452400Sbillf 41567859SdougbOne of the following exit values will be returned: 41652400Sbillf@table @samp 41752400Sbillf@item 0 (EXIT_SUCCESS) 41852400SbillfSuccessful program execution. 41952400Sbillf@item 1 (EXIT_FAILURE) 42052400SbillfThe operation failed or the command syntax was not valid. 42152400Sbillf@item 66 (EX_NOINPUT) 42252400SbillfA specified configuration file could not be loaded. 42352400Sbillf@item 70 (EX_SOFTWARE) 42452400Sbillflibopts had an internal operational error. Please report 42552400Sbillfit to autogen-users@@lists.sourceforge.net. Thank you. 42667859Sdougb@end table 42767859Sdougb@node sntp Usage 42867859Sdougb@subsection sntp Usage 42967859Sdougb@node sntp Authors 43067859Sdougb@subsection sntp Authors 43167859Sdougb