invoke-ntptrace.texi revision 285612
1162852Sdes@node ntptrace Invocation 2162852Sdes@section Invoking ntptrace 3162852Sdes@pindex ntptrace 4162852Sdes@cindex Trace peers of an NTP server 5162852Sdes@ignore 6162852Sdes# 7162852Sdes# EDIT THIS FILE WITH CAUTION (invoke-ntptrace.texi) 8162852Sdes# 9162852Sdes# It has been AutoGen-ed June 29, 2015 at 04:26:52 PM by AutoGen 5.18.5 10162852Sdes# From the definitions ntptrace-opts.def 11162852Sdes# and the template file agtexi-cmd.tpl 12162852Sdes@end ignore 13162852Sdes 14162852Sdes@code{ntptrace} is a perl script that uses the ntpq utility program to follow 15162852Sdesthe chain of NTP servers from a given host back to the primary time source. For 16162852Sdesntptrace to work properly, each of these servers must implement the NTP Control 17162852Sdesand Monitoring Protocol specified in RFC 1305 and enable NTP Mode 6 packets. 18162852Sdes 19162852SdesIf given no arguments, ntptrace starts with localhost. Here is an example of 20162852Sdesthe output from ntptrace: 21162852Sdes 22162852Sdes@example 23162852Sdes% ntptrace localhost: stratum 4, offset 0.0019529, synch distance 0.144135 24162852Sdesserver2ozo.com: stratum 2, offset 0.0124263, synch distance 0.115784 usndh.edu: 25162852Sdesstratum 1, offset 0.0019298, synch distance 0.011993, refid 'WWVB' 26162852Sdes@end example 27162852Sdes 28162852SdesOn each line, the fields are (left to right): the host name, the host stratum, 29162852Sdesthe time offset between that host and the local host (as measured by 30162852Sdes@code{ntptrace}; this is why it is not always zero for "localhost"), the host 31162852Sdessynchronization distance, and (only for stratum-1 servers) the reference clock 32162852SdesID. All times are given in seconds. Note that the stratum is the server hop 33162852Sdescount to the primary source, while the synchronization distance is the 34162852Sdesestimated error relative to the primary source. These terms are precisely 35162852Sdesdefined in RFC-1305. 36162852Sdes 37162852Sdes 38162852SdesThis section was generated by @strong{AutoGen}, 39162852Sdesusing the @code{agtexi-cmd} template and the option descriptions for the @code{ntptrace} program. 40162852Sdes 41162852Sdes@menu 42162852Sdes* ntptrace usage:: ntptrace help/usage (@option{--help}) 43162852Sdes* ntptrace numeric:: numeric option (-n) 44162852Sdes* ntptrace max-hosts:: max-hosts option (-m) 45162852Sdes* ntptrace host:: host option (-r) 46162852Sdes* ntptrace exit status:: exit status 47162852Sdes@end menu 48162852Sdes 49162852Sdes@node ntptrace usage 50162852Sdes@subsection ntptrace help/usage (@option{--help}) 51162852Sdes@cindex ntptrace help 52162852Sdes 53162852SdesThis is the automatically generated usage text for ntptrace. 54162852Sdes 55162852SdesThe text printed is the same whether selected with the @code{help} option 56162852Sdes(@option{--help}) or the @code{more-help} option (@option{--more-help}). @code{more-help} will print 57162852Sdesthe usage text by passing it through a pager program. 58162852Sdes@code{more-help} is disabled on platforms without a working 59162852Sdes@code{fork(2)} function. The @code{PAGER} environment variable is 60162852Sdesused to select the program, defaulting to @file{more}. Both will exit 61162852Sdeswith a status code of 0. 62162852Sdes 63162852Sdes@exampleindent 0 64162852Sdes@example 65162852Sdesntptrace - Trace peers of an NTP server - Ver. 4.2.8p3 66162852SdesUSAGE: ntptrace [ -<flag> [<val>] | --<name>[@{=| @}<val>] ]... [host] 67162852Sdes 68162852Sdes -n, --numeric Print IP addresses instead of hostnames 69162852Sdes -m, --max-hosts=num Maximum number of peers to trace 70162852Sdes -r, --host=str Single remote host 71162852Sdes -?, --help Display usage information and exit 72162852Sdes --more-help Pass the extended usage text through a pager 73162852Sdes 74Options are specified by doubled hyphens and their name or by a single 75hyphen and the flag character. 76@end example 77@exampleindent 4 78 79@node ntptrace numeric 80@subsection numeric option (-n) 81@cindex ntptrace-numeric 82 83This is the ``print ip addresses instead of hostnames'' option. 84Output hosts as dotted-quad numeric format rather than converting to 85the canonical host names. 86@node ntptrace max-hosts 87@subsection max-hosts option (-m) 88@cindex ntptrace-max-hosts 89 90This is the ``maximum number of peers to trace'' option. 91This option takes a number argument. 92This option has no @samp{doc} documentation. 93@node ntptrace host 94@subsection host option (-r) 95@cindex ntptrace-host 96 97This is the ``single remote host'' option. 98This option takes a string argument. 99This option has no @samp{doc} documentation. 100@node ntptrace exit status 101@subsection ntptrace exit status 102 103One of the following exit values will be returned: 104@table @samp 105@item 0 (EXIT_SUCCESS) 106Successful program execution. 107@item 1 (EXIT_FAILURE) 108The operation failed or the command syntax was not valid. 109@end table 110