ntpq-opts.def revision 181834
1181834Sroberto/* -*- Mode: Text -*- */ 2181834Sroberto 3181834Srobertoautogen definitions options; 4181834Sroberto 5181834Sroberto#include copyright.def 6181834Sroberto#include homerc.def 7181834Sroberto#include autogen-version.def 8181834Sroberto 9181834Srobertoprog-name = "ntpq"; 10181834Srobertoprog-title = "standard NTP query program"; 11181834Srobertoargument = '[ host ...]'; 12181834Sroberto 13181834Srobertotest-main; 14181834Sroberto 15181834Srobertoflag = { 16181834Sroberto name = ipv4; 17181834Sroberto value = 4; 18181834Sroberto equivalence = ipv4; 19181834Sroberto descrip = "Force IPv4 DNS name resolution"; 20181834Sroberto doc = <<- _EndOfDoc_ 21181834Sroberto Force DNS resolution of following host names on the command line 22181834Sroberto to the IPv4 namespace. 23181834Sroberto _EndOfDoc_; 24181834Sroberto}; 25181834Sroberto 26181834Srobertoflag = { 27181834Sroberto name = ipv6; 28181834Sroberto value = 6; 29181834Sroberto equivalence = ipv4; 30181834Sroberto descrip = "Force IPv6 DNS name resolution"; 31181834Sroberto doc = <<- _EndOfDoc_ 32181834Sroberto Force DNS resolution of following host names on the command line 33181834Sroberto to the IPv6 namespace. 34181834Sroberto _EndOfDoc_; 35181834Sroberto}; 36181834Sroberto 37181834Srobertoflag = { 38181834Sroberto name = command; 39181834Sroberto value = c; 40181834Sroberto arg-type = string; 41181834Sroberto descrip = "run a command and exit"; 42181834Sroberto max = NOLIMIT; 43181834Sroberto arg-name = cmd; 44181834Sroberto stack-arg; 45181834Sroberto doc = <<- _EndOfDoc_ 46181834Sroberto The following argument is interpreted as an interactive format command 47181834Sroberto and is added to the list of commands to be executed on the specified 48181834Sroberto host(s). 49181834Sroberto _EndOfDoc_; 50181834Sroberto}; 51181834Sroberto 52181834Sroberto#include debug-opt.def 53181834Sroberto 54181834Srobertoflag = { 55181834Sroberto name = peers; 56181834Sroberto value = p; 57181834Sroberto descrip = "Print a list of the peers"; 58181834Sroberto flags-cant = interactive; 59181834Sroberto doc = <<- _EndOfDoc_ 60181834Sroberto Print a list of the peers known to the server as well as a summary 61181834Sroberto of their state. This is equivalent to the 'peers' interactive command. 62181834Sroberto _EndOfDoc_; 63181834Sroberto}; 64181834Sroberto 65181834Srobertoflag = { 66181834Sroberto name = interactive; 67181834Sroberto value = i; 68181834Sroberto flags-cant = command, peers; 69181834Sroberto descrip = "Force ntpq to operate in interactive mode"; 70181834Sroberto doc = <<- _EndOfDoc_ 71181834Sroberto Force ntpq to operate in interactive mode. Prompts will be written 72181834Sroberto to the standard output and commands read from the standard input. 73181834Sroberto _EndOfDoc_; 74181834Sroberto}; 75181834Sroberto 76181834Srobertoflag = { 77181834Sroberto name = numeric; 78181834Sroberto value = n; 79181834Sroberto descrip = "numeric host addresses"; 80181834Sroberto doc = <<- _EndOfDoc_ 81181834Sroberto Output all host addresses in dotted-quad numeric format rather than 82181834Sroberto converting to the canonical host names. 83181834Sroberto _EndOfDoc_; 84181834Sroberto}; 85181834Sroberto 86181834Srobertodetail = <<- _END_DETAIL 87181834Sroberto The 88181834Sroberto [= prog-name =] 89181834Sroberto utility program is used to query NTP servers which 90181834Sroberto implement the standard NTP mode 6 control message formats defined 91181834Sroberto in Appendix B of the NTPv3 specification RFC1305, requesting 92181834Sroberto information about current state and/or changes in that state. 93181834Sroberto The same formats are used in NTPv4, although some of the 94181834Sroberto variables have changed and new ones added. 95181834Sroberto _END_DETAIL; 96181834Sroberto 97181834Srobertoprog-man-descrip = <<- _END_PROG_MAN_DESCRIP 98181834Sroberto The 99181834Sroberto [= prog-name =] 100181834Sroberto utility program is used to query NTP servers which 101181834Sroberto implement the standard NTP mode 6 control message formats defined 102181834Sroberto in Appendix B of the NTPv3 specification RFC1305, requesting 103181834Sroberto information about current state and/or changes in that state. 104181834Sroberto The same formats are used in NTPv4, although some of the 105181834Sroberto variables have changed and new ones added. The description on this 106181834Sroberto page is for the NTPv4 variables. 107181834Sroberto The program may be run either in interactive mode or controlled using 108181834Sroberto command line arguments. 109181834Sroberto Requests to read and write arbitrary 110181834Sroberto variables can be assembled, with raw and pretty-printed output 111181834Sroberto options being available. 112181834Sroberto The 113181834Sroberto [= prog-name =] 114181834Sroberto utility can also obtain and print a 115181834Sroberto list of peers in a common format by sending multiple queries to the 116181834Sroberto server. 117181834Sroberto 118181834Sroberto If one or more request options is included on the command line 119181834Sroberto when 120181834Sroberto [= prog-name =] 121181834Sroberto is executed, each of the requests will be sent 122181834Sroberto to the NTP servers running on each of the hosts given as command 123181834Sroberto line arguments, or on localhost by default. 124181834Sroberto If no request options 125181834Sroberto are given, 126181834Sroberto [= prog-name =] 127181834Sroberto will attempt to read commands from the 128181834Sroberto standard input and execute these on the NTP server running on the 129181834Sroberto first host given on the command line, again defaulting to localhost 130181834Sroberto when no other host is specified. 131181834Sroberto The 132181834Sroberto [= prog-name =] 133181834Sroberto utility will prompt for 134181834Sroberto commands if the standard input is a terminal device. 135181834Sroberto 136181834Sroberto The 137181834Sroberto [= prog-name =] 138181834Sroberto utility uses NTP mode 6 packets to communicate with the 139181834Sroberto NTP server, and hence can be used to query any compatible server on 140181834Sroberto the network which permits it. 141181834Sroberto Note that since NTP is a UDP protocol 142181834Sroberto this communication will be somewhat unreliable, especially over 143181834Sroberto large distances in terms of network topology. 144181834Sroberto The 145181834Sroberto [= prog-name =] 146181834Sroberto utility makes 147181834Sroberto one attempt to retransmit requests, and will time requests out if 148181834Sroberto the remote host is not heard from within a suitable timeout 149181834Sroberto time. 150181834Sroberto 151181834Sroberto Specifying a 152181834Sroberto command line option other than 153181834Sroberto .Fl i 154181834Sroberto or 155181834Sroberto .Fl n 156181834Sroberto will 157181834Sroberto cause the specified query (queries) to be sent to the indicated 158181834Sroberto host(s) immediately. 159181834Sroberto Otherwise, 160181834Sroberto [= prog-name =] 161181834Sroberto will attempt to read 162181834Sroberto interactive format commands from the standard input. 163181834Sroberto .Ss "Internal Commands" 164181834Sroberto Interactive format commands consist of a keyword followed by zero 165181834Sroberto to four arguments. 166181834Sroberto Only enough characters of the full keyword to 167181834Sroberto uniquely identify the command need be typed. 168181834Sroberto 169181834Sroberto A 170181834Sroberto number of interactive format commands are executed entirely within 171181834Sroberto the 172181834Sroberto [= prog-name =] 173181834Sroberto utility itself and do not result in NTP mode 6 174181834Sroberto requests being sent to a server. 175181834Sroberto These are described following. 176181834Sroberto @table @code 177181834Sroberto @item ? [command_keyword] 178181834Sroberto @itemx help [command_keyword] 179181834Sroberto A 180181834Sroberto .Ql \&? 181181834Sroberto by itself will print a list of all the command 182181834Sroberto keywords known to this incarnation of 183181834Sroberto [= prog-name =] . 184181834Sroberto A 185181834Sroberto .Ql \&? 186181834Sroberto followed by a command keyword will print function and usage 187181834Sroberto information about the command. 188181834Sroberto This command is probably a better 189181834Sroberto source of information about 190181834Sroberto [= prog-name =] 191181834Sroberto than this manual 192181834Sroberto page. 193181834Sroberto @item addvars 194181834Sroberto .Ar variable_name [=value] ... 195181834Sroberto .Xc 196181834Sroberto @item rmvars variable_name ... 197181834Sroberto @item clearvars 198181834Sroberto The data carried by NTP mode 6 messages consists of a list of 199181834Sroberto items of the form 200181834Sroberto .Ql variable_name=value , 201181834Sroberto where the 202181834Sroberto .Ql =value 203181834Sroberto is ignored, and can be omitted, 204181834Sroberto in requests to the server to read variables. 205181834Sroberto The 206181834Sroberto [= prog-name =] 207181834Sroberto utility maintains an internal list in which data to be included in control 208181834Sroberto messages can be assembled, and sent using the 209181834Sroberto .Ic readlist 210181834Sroberto and 211181834Sroberto .Ic writelist 212181834Sroberto commands described below. 213181834Sroberto The 214181834Sroberto .Ic addvars 215181834Sroberto command allows variables and their optional values to be added to 216181834Sroberto the list. 217181834Sroberto If more than one variable is to be added, the list should 218181834Sroberto be comma-separated and not contain white space. 219181834Sroberto The 220181834Sroberto .Ic rmvars 221181834Sroberto command can be used to remove individual variables from the list, 222181834Sroberto while the 223181834Sroberto .Ic clearlist 224181834Sroberto command removes all variables from the 225181834Sroberto list. 226181834Sroberto @item authenticate [ yes | no ] 227181834Sroberto Normally 228181834Sroberto [= prog-name =] 229181834Sroberto does not authenticate requests unless 230181834Sroberto they are write requests. 231181834Sroberto The command 232181834Sroberto .Ql authenticate yes 233181834Sroberto causes 234181834Sroberto [= prog-name =] 235181834Sroberto to send authentication with all requests it 236181834Sroberto makes. 237181834Sroberto Authenticated requests causes some servers to handle 238181834Sroberto requests slightly differently, and can occasionally melt the CPU in 239181834Sroberto fuzzballs if you turn authentication on before doing a 240181834Sroberto .Ic peer 241181834Sroberto display. 242181834Sroberto The command 243181834Sroberto .Ql authenticate 244181834Sroberto causes 245181834Sroberto [= prog-name =] 246181834Sroberto to display whether or not 247181834Sroberto [= prog-name =] 248181834Sroberto is currently autheinticating requests. 249181834Sroberto @item cooked 250181834Sroberto Causes output from query commands to be "cooked", so that 251181834Sroberto variables which are recognized by 252181834Sroberto [= prog-name =] 253181834Sroberto will have their 254181834Sroberto values reformatted for human consumption. 255181834Sroberto Variables which 256181834Sroberto [= prog-name =] 257181834Sroberto thinks should have a decodable value but didn't are 258181834Sroberto marked with a trailing 259181834Sroberto .Ql \&? . 260181834Sroberto .@item debug [ 261181834Sroberto .Cm more | 262181834Sroberto .Cm less | 263181834Sroberto .Cm off 264181834Sroberto ] 265181834Sroberto .Xc 266181834Sroberto With no argument, displays the current debug level. 267181834Sroberto Otherwise, the debug level is changed to the indicated level. 268181834Sroberto @item delay milliseconds 269181834Sroberto Specify a time interval to be added to timestamps included in 270181834Sroberto requests which require authentication. 271181834Sroberto This is used to enable 272181834Sroberto (unreliable) server reconfiguration over long delay network paths 273181834Sroberto or between machines whose clocks are unsynchronized. 274181834Sroberto Actually the 275181834Sroberto server does not now require timestamps in authenticated requests, 276181834Sroberto so this command may be obsolete. 277181834Sroberto @item host hostname 278181834Sroberto Set the host to which future queries will be sent. 279181834Sroberto Hostname may 280181834Sroberto be either a host name or a numeric address. 281181834Sroberto @item hostnames Cm yes | Cm no 282181834Sroberto If 283181834Sroberto .Cm yes 284181834Sroberto is specified, host names are printed in 285181834Sroberto information displays. 286181834Sroberto If 287181834Sroberto .Cm no 288181834Sroberto is specified, numeric 289181834Sroberto addresses are printed instead. 290181834Sroberto The default is 291181834Sroberto .Cm yes , 292181834Sroberto unless 293181834Sroberto modified using the command line 294181834Sroberto .Fl n 295181834Sroberto switch. 296181834Sroberto @item keyid keyid 297181834Sroberto This command allows the specification of a key number to be 298181834Sroberto used to authenticate configuration requests. 299181834Sroberto This must correspond 300181834Sroberto to a key number the server has been configured to use for this 301181834Sroberto purpose. 302181834Sroberto @item ntpversion [ 303181834Sroberto .Cm 1 | 304181834Sroberto .Cm 2 | 305181834Sroberto .Cm 3 | 306181834Sroberto .Cm 4 307181834Sroberto ] 308181834Sroberto .Xc 309181834Sroberto Sets the NTP version number which 310181834Sroberto [= prog-name =] 311181834Sroberto claims in 312181834Sroberto packets. 313181834Sroberto Defaults to 3, Note that mode 6 control messages (and 314181834Sroberto modes, for that matter) didn't exist in NTP version 1. 315181834Sroberto There appear 316181834Sroberto to be no servers left which demand version 1. 317181834Sroberto With no argument, displays the current NTP version that will be used 318181834Sroberto when communicating with servers. 319181834Sroberto @item quit 320181834Sroberto Exit 321181834Sroberto [= prog-name =] . 322181834Sroberto @item passwd 323181834Sroberto This command prompts you to type in a password (which will not 324181834Sroberto be echoed) which will be used to authenticate configuration 325181834Sroberto requests. 326181834Sroberto The password must correspond to the key configured for 327181834Sroberto use by the NTP server for this purpose if such requests are to be 328181834Sroberto successful. 329181834Sroberto @item raw 330181834Sroberto Causes all output from query commands is printed as received 331181834Sroberto from the remote server. 332181834Sroberto The only formating/interpretation done on 333181834Sroberto the data is to transform nonascii data into a printable (but barely 334181834Sroberto understandable) form. 335181834Sroberto @item timeout Ar milliseconds 336181834Sroberto Specify a timeout period for responses to server queries. 337181834Sroberto The 338181834Sroberto default is about 5000 milliseconds. 339181834Sroberto Note that since 340181834Sroberto [= prog-name =] 341181834Sroberto retries each query once after a timeout, the total waiting time for 342181834Sroberto a timeout will be twice the timeout value set. 343181834Sroberto @end table 344181834Sroberto 345181834Sroberto _END_PROG_MAN_DESCRIP; 346