1/* -*- Mode: Text -*- */ 2 3autogen definitions options; 4 5#include copyright.def 6#include homerc.def 7#include autogen-version.def 8 9prog-name = "ntpq"; 10prog-title = "standard NTP query program"; 11argument = '[ host ...]'; 12 13test-main; 14 15flag = { 16 name = ipv4; 17 flags-cant = ipv6; 18 value = 4; 19 descrip = "Force IPv4 DNS name resolution"; 20 doc = <<- _EndOfDoc_ 21 Force DNS resolution of following host names on the command line 22 to the IPv4 namespace. 23 _EndOfDoc_; 24}; 25 26flag = { 27 name = ipv6; 28 flags-cant = ipv4; 29 value = 6; 30 descrip = "Force IPv6 DNS name resolution"; 31 doc = <<- _EndOfDoc_ 32 Force DNS resolution of following host names on the command line 33 to the IPv6 namespace. 34 _EndOfDoc_; 35}; 36 37flag = { 38 name = command; 39 value = c; 40 arg-type = string; 41 descrip = "run a command and exit"; 42 max = NOLIMIT; 43 arg-name = cmd; 44 call-proc = ntpq_custom_opt_handler; 45 doc = <<- _EndOfDoc_ 46 The following argument is interpreted as an interactive format command 47 and is added to the list of commands to be executed on the specified 48 host(s). 49 _EndOfDoc_; 50}; 51 52#include debug-opt.def 53 54flag = { 55 name = peers; 56 value = p; 57 descrip = "Print a list of the peers"; 58 flags-cant = interactive; 59 call-proc = ntpq_custom_opt_handler; 60 doc = <<- _EndOfDoc_ 61 Print a list of the peers known to the server as well as a summary 62 of their state. This is equivalent to the 'peers' interactive command. 63 _EndOfDoc_; 64}; 65 66flag = { 67 name = interactive; 68 value = i; 69 flags-cant = command, peers; 70 descrip = "Force ntpq to operate in interactive mode"; 71 doc = <<- _EndOfDoc_ 72 Force ntpq to operate in interactive mode. Prompts will be written 73 to the standard output and commands read from the standard input. 74 _EndOfDoc_; 75}; 76 77flag = { 78 name = numeric; 79 value = n; 80 descrip = "numeric host addresses"; 81 doc = <<- _EndOfDoc_ 82 Output all host addresses in dotted-quad numeric format rather than 83 converting to the canonical host names. 84 _EndOfDoc_; 85}; 86 87flag = { 88 name = old-rv; 89 descrip = "Always output status line with readvar"; 90 doc = <<- _EndOfDoc_ 91 By default, ntpq now suppresses the associd=... line that 92 precedes the output of "readvar" (alias "rv") when a single 93 variable is requested, such as ntpq -c "rv 0 offset". This 94 option causes ntpq to include both lines of output for a 95 single-variable readvar. Using an environment variable to 96 preset this option in a script will enable both older and 97 newer ntpq to behave identically in this regard. 98 _EndOfDoc_; 99}; 100 101detail = <<- _END_DETAIL 102 The 103 [= prog-name =] 104 utility program is used to query NTP servers which 105 implement the standard NTP mode 6 control message formats defined 106 in Appendix B of the NTPv3 specification RFC1305, requesting 107 information about current state and/or changes in that state. 108 The same formats are used in NTPv4, although some of the 109 variables have changed and new ones added. 110 _END_DETAIL; 111 112prog-man-descrip = <<- _END_PROG_MAN_DESCRIP 113 The 114 [= prog-name =] 115 utility program is used to query NTP servers which 116 implement the standard NTP mode 6 control message formats defined 117 in Appendix B of the NTPv3 specification RFC1305, requesting 118 information about current state and/or changes in that state. 119 The same formats are used in NTPv4, although some of the 120 variables have changed and new ones added. The description on this 121 page is for the NTPv4 variables. 122 The program may be run either in interactive mode or controlled using 123 command line arguments. 124 Requests to read and write arbitrary 125 variables can be assembled, with raw and pretty-printed output 126 options being available. 127 The 128 [= prog-name =] 129 utility can also obtain and print a 130 list of peers in a common format by sending multiple queries to the 131 server. 132 133 If one or more request options is included on the command line 134 when 135 [= prog-name =] 136 is executed, each of the requests will be sent 137 to the NTP servers running on each of the hosts given as command 138 line arguments, or on localhost by default. 139 If no request options 140 are given, 141 [= prog-name =] 142 will attempt to read commands from the 143 standard input and execute these on the NTP server running on the 144 first host given on the command line, again defaulting to localhost 145 when no other host is specified. 146 The 147 [= prog-name =] 148 utility will prompt for 149 commands if the standard input is a terminal device. 150 151 The 152 [= prog-name =] 153 utility uses NTP mode 6 packets to communicate with the 154 NTP server, and hence can be used to query any compatible server on 155 the network which permits it. 156 Note that since NTP is a UDP protocol 157 this communication will be somewhat unreliable, especially over 158 large distances in terms of network topology. 159 The 160 [= prog-name =] 161 utility makes 162 one attempt to retransmit requests, and will time requests out if 163 the remote host is not heard from within a suitable timeout 164 time. 165 166 Specifying a 167 command line option other than 168 .Fl i 169 or 170 .Fl n 171 will 172 cause the specified query (queries) to be sent to the indicated 173 host(s) immediately. 174 Otherwise, 175 [= prog-name =] 176 will attempt to read 177 interactive format commands from the standard input. 178 .Ss "Internal Commands" 179 Interactive format commands consist of a keyword followed by zero 180 to four arguments. 181 Only enough characters of the full keyword to 182 uniquely identify the command need be typed. 183 184 A 185 number of interactive format commands are executed entirely within 186 the 187 [= prog-name =] 188 utility itself and do not result in NTP mode 6 189 requests being sent to a server. 190 These are described following. 191 @table @code 192 @item ? [command_keyword] 193 @itemx help [command_keyword] 194 A 195 .Ql \&? 196 by itself will print a list of all the command 197 keywords known to this incarnation of 198 [= prog-name =] . 199 A 200 .Ql \&? 201 followed by a command keyword will print function and usage 202 information about the command. 203 This command is probably a better 204 source of information about 205 [= prog-name =] 206 than this manual 207 page. 208 @item addvars 209 .Ar variable_name [=value] ... 210 .Xc 211 @item rmvars variable_name ... 212 @item clearvars 213 The data carried by NTP mode 6 messages consists of a list of 214 items of the form 215 .Ql variable_name=value , 216 where the 217 .Ql =value 218 is ignored, and can be omitted, 219 in requests to the server to read variables. 220 The 221 [= prog-name =] 222 utility maintains an internal list in which data to be included in control 223 messages can be assembled, and sent using the 224 .Ic readlist 225 and 226 .Ic writelist 227 commands described below. 228 The 229 .Ic addvars 230 command allows variables and their optional values to be added to 231 the list. 232 If more than one variable is to be added, the list should 233 be comma-separated and not contain white space. 234 The 235 .Ic rmvars 236 command can be used to remove individual variables from the list, 237 while the 238 .Ic clearlist 239 command removes all variables from the 240 list. 241 @item authenticate [ yes | no ] 242 Normally 243 [= prog-name =] 244 does not authenticate requests unless 245 they are write requests. 246 The command 247 .Ql authenticate yes 248 causes 249 [= prog-name =] 250 to send authentication with all requests it 251 makes. 252 Authenticated requests causes some servers to handle 253 requests slightly differently, and can occasionally melt the CPU in 254 fuzzballs if you turn authentication on before doing a 255 .Ic peer 256 display. 257 The command 258 .Ql authenticate 259 causes 260 [= prog-name =] 261 to display whether or not 262 [= prog-name =] 263 is currently autheinticating requests. 264 @item cooked 265 Causes output from query commands to be "cooked", so that 266 variables which are recognized by 267 [= prog-name =] 268 will have their 269 values reformatted for human consumption. 270 Variables which 271 [= prog-name =] 272 thinks should have a decodable value but didn't are 273 marked with a trailing 274 .Ql \&? . 275 .@item debug [ 276 .Cm more | 277 .Cm less | 278 .Cm off 279 ] 280 .Xc 281 With no argument, displays the current debug level. 282 Otherwise, the debug level is changed to the indicated level. 283 @item delay milliseconds 284 Specify a time interval to be added to timestamps included in 285 requests which require authentication. 286 This is used to enable 287 (unreliable) server reconfiguration over long delay network paths 288 or between machines whose clocks are unsynchronized. 289 Actually the 290 server does not now require timestamps in authenticated requests, 291 so this command may be obsolete. 292 @item host hostname 293 Set the host to which future queries will be sent. 294 Hostname may 295 be either a host name or a numeric address. 296 @item hostnames Cm yes | Cm no 297 If 298 .Cm yes 299 is specified, host names are printed in 300 information displays. 301 If 302 .Cm no 303 is specified, numeric 304 addresses are printed instead. 305 The default is 306 .Cm yes , 307 unless 308 modified using the command line 309 .Fl n 310 switch. 311 @item keyid keyid 312 This command allows the specification of a key number to be 313 used to authenticate configuration requests. 314 This must correspond 315 to a key number the server has been configured to use for this 316 purpose. 317 @item ntpversion [ 318 .Cm 1 | 319 .Cm 2 | 320 .Cm 3 | 321 .Cm 4 322 ] 323 .Xc 324 Sets the NTP version number which 325 [= prog-name =] 326 claims in 327 packets. 328 Defaults to 3, Note that mode 6 control messages (and 329 modes, for that matter) didn't exist in NTP version 1. 330 There appear 331 to be no servers left which demand version 1. 332 With no argument, displays the current NTP version that will be used 333 when communicating with servers. 334 @item quit 335 Exit 336 [= prog-name =] . 337 @item passwd 338 This command prompts you to type in a password (which will not 339 be echoed) which will be used to authenticate configuration 340 requests. 341 The password must correspond to the key configured for 342 use by the NTP server for this purpose if such requests are to be 343 successful. 344 @item raw 345 Causes all output from query commands is printed as received 346 from the remote server. 347 The only formating/interpretation done on 348 the data is to transform nonascii data into a printable (but barely 349 understandable) form. 350 @item timeout Ar milliseconds 351 Specify a timeout period for responses to server queries. 352 The 353 default is about 5000 milliseconds. 354 Note that since 355 [= prog-name =] 356 retries each query once after a timeout, the total waiting time for 357 a timeout will be twice the timeout value set. 358 @end table 359 360 _END_PROG_MAN_DESCRIP; 361