external/bsd/ntp/dist/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     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
  26 flag = {
  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
  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     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
  54 flag = {
  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
  66 flag = {
  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
  77 flag = {
  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
  87 flag = {
  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
 101 detail = <<-  _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
 112 prog-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;