contrib/ntp/ntpq/ntpq-opts.def

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