contrib/ntp/ntpq/ntpq.1

   1 .TH NTPQ 1 2009-12-08 "( 4.2.4p8)" "Programmer's Manual"
   2 .\"  EDIT THIS FILE WITH CAUTION  (ntpq.1)
   3 .\"
   4 .\"  It has been AutoGen-ed  Tuesday December  8, 2009 at 08:14:27 AM EST
   5 .\"  From the definitions    ntpq-opts.def
   6 .\"  and the template file   agman1.tpl
   7 .\"
   8 .SH NAME
   9 ntpq \- standard NTP query program
  10 .SH SYNOPSIS
  11 .B ntpq
  12 .\" Mixture of short (flag) options and long options
  13 .RB [ \-\fIflag\fP " [\fIvalue\fP]]... [" \--\fIopt-name\fP " [[=| ]\fIvalue\fP]]..."
  14 .br
  15 .in +8
  16 [ host ...]
  17 .SH "DESCRIPTION"
  18 This manual page documents, briefly, the \fBntpq\fP command.
  19 The
  20 [= prog-name =]
  21 utility program is used to query NTP servers which
  22 implement the standard NTP mode 6 control message formats defined
  23 in Appendix B of the NTPv3 specification RFC1305, requesting
  24 information about current state and/or changes in that state.
  25 The same formats are used in NTPv4, although some of the
  26 variables have changed and new ones added. The description on this
  27 page is for the NTPv4 variables.
  28 The program may be run either in interactive mode or controlled using
  29 command line arguments.
  30 Requests to read and write arbitrary
  31 variables can be assembled, with raw and pretty-printed output
  32 options being available.
  33 The
  34 [= prog-name =]
  35 utility can also obtain and print a
  36 list of peers in a common format by sending multiple queries to the
  37 server.
  38
  39 If one or more request options is included on the command line
  40 when
  41 [= prog-name =]
  42 is executed, each of the requests will be sent
  43 to the NTP servers running on each of the hosts given as command
  44 line arguments, or on localhost by default.
  45 If no request options
  46 are given,
  47 [= prog-name =]
  48 will attempt to read commands from the
  49 standard input and execute these on the NTP server running on the
  50 first host given on the command line, again defaulting to localhost
  51 when no other host is specified.
  52 The
  53 [= prog-name =]
  54 utility will prompt for
  55 commands if the standard input is a terminal device.
  56
  57 The
  58 [= prog-name =]
  59 utility uses NTP mode 6 packets to communicate with the
  60 NTP server, and hence can be used to query any compatible server on
  61 the network which permits it.
  62 Note that since NTP is a UDP protocol
  63 this communication will be somewhat unreliable, especially over
  64 large distances in terms of network topology.
  65 The
  66 [= prog-name =]
  67 utility makes
  68 one attempt to retransmit requests, and will time requests out if
  69 the remote host is not heard from within a suitable timeout
  70 time.
  71
  72 Specifying a
  73 command line option other than
  74 .Fl i
  75 or
  76 .Fl n
  77 will
  78 cause the specified query (queries) to be sent to the indicated
  79 host(s) immediately.
  80 Otherwise,
  81 [= prog-name =]
  82 will attempt to read
  83 interactive format commands from the standard input.
  84 .Ss "Internal Commands"
  85 Interactive format commands consist of a keyword followed by zero
  86 to four arguments.
  87 Only enough characters of the full keyword to
  88 uniquely identify the command need be typed.
  89
  90 A
  91 number of interactive format commands are executed entirely within
  92 the
  93 [= prog-name =]
  94 utility itself and do not result in NTP mode 6
  95 requests being sent to a server.
  96 These are described following.
  97 .sp
  98 .IR "? [command_keyword]"
  99 .sp 1x help [command_keyword]
 100 A
 101 .Ql \&?
 102 by itself will print a list of all the command
 103 keywords known to this incarnation of
 104 [= prog-name =] .
 105 A
 106 .Ql \&?
 107 followed by a command keyword will print function and usage
 108 information about the command.
 109 This command is probably a better
 110 source of information about
 111 [= prog-name =]
 112 than this manual
 113 page.
 114 .sp
 115 .IR "addvars"
 116 .Ar variable_name [=value] ...
 117 .Xc
 118 .sp
 119 .IR "rmvars variable_name ..."
 120 .sp
 121 .IR "clearvars"
 122 The data carried by NTP mode 6 messages consists of a list of
 123 items of the form
 124 .Ql variable_name=value ,
 125 where the
 126 .Ql =value
 127 is ignored, and can be omitted,
 128 in requests to the server to read variables.
 129 The
 130 [= prog-name =]
 131 utility maintains an internal list in which data to be included in control
 132 messages can be assembled, and sent using the
 133 .Ic readlist
 134 and
 135 .Ic writelist
 136 commands described below.
 137 The
 138 .Ic addvars
 139 command allows variables and their optional values to be added to
 140 the list.
 141 If more than one variable is to be added, the list should
 142 be comma-separated and not contain white space.
 143 The
 144 .Ic rmvars
 145 command can be used to remove individual variables from the list,
 146 while the
 147 .Ic clearlist
 148 command removes all variables from the
 149 list.
 150 .sp
 151 .IR "authenticate [ yes | no ]"
 152 Normally
 153 [= prog-name =]
 154 does not authenticate requests unless
 155 they are write requests.
 156 The command
 157 .Ql authenticate yes
 158 causes
 159 [= prog-name =]
 160 to send authentication with all requests it
 161 makes.
 162 Authenticated requests causes some servers to handle
 163 requests slightly differently, and can occasionally melt the CPU in
 164 fuzzballs if you turn authentication on before doing a
 165 .Ic peer
 166 display.
 167 The command
 168 .Ql authenticate
 169 causes
 170 [= prog-name =]
 171 to display whether or not
 172 [= prog-name =]
 173 is currently autheinticating requests.
 174 .sp
 175 .IR "cooked"
 176 Causes output from query commands to be "cooked", so that
 177 variables which are recognized by
 178 [= prog-name =]
 179 will have their
 180 values reformatted for human consumption.
 181 Variables which
 182 [= prog-name =]
 183 thinks should have a decodable value but didn't are
 184 marked with a trailing
 185 .Ql \&? .
 186 .@item debug [
 187 .Cm more |
 188 .Cm less |
 189 .Cm off
 190 ]
 191 .Xc
 192 With no argument, displays the current debug level.
 193 Otherwise, the debug level is changed to the indicated level.
 194 .sp
 195 .IR "delay milliseconds"
 196 Specify a time interval to be added to timestamps included in
 197 requests which require authentication.
 198 This is used to enable
 199 (unreliable) server reconfiguration over long delay network paths
 200 or between machines whose clocks are unsynchronized.
 201 Actually the
 202 server does not now require timestamps in authenticated requests,
 203 so this command may be obsolete.
 204 .sp
 205 .IR "host hostname"
 206 Set the host to which future queries will be sent.
 207 Hostname may
 208 be either a host name or a numeric address.
 209 .sp
 210 .IR "hostnames Cm yes | Cm no"
 211 If
 212 .Cm yes
 213 is specified, host names are printed in
 214 information displays.
 215 If
 216 .Cm no
 217 is specified, numeric
 218 addresses are printed instead.
 219 The default is
 220 .Cm yes ,
 221 unless
 222 modified using the command line
 223 .Fl n
 224 switch.
 225 .sp
 226 .IR "keyid keyid"
 227 This command allows the specification of a key number to be
 228 used to authenticate configuration requests.
 229 This must correspond
 230 to a key number the server has been configured to use for this
 231 purpose.
 232 .sp
 233 .IR "ntpversion ["
 234 .Cm 1 |
 235 .Cm 2 |
 236 .Cm 3 |
 237 .Cm 4
 238 ]
 239 .Xc
 240 Sets the NTP version number which
 241 [= prog-name =]
 242 claims in
 243 packets.
 244 Defaults to 3, Note that mode 6 control messages (and
 245 modes, for that matter) didn't exist in NTP version 1.
 246 There appear
 247 to be no servers left which demand version 1.
 248 With no argument, displays the current NTP version that will be used
 249 when communicating with servers.
 250 .sp
 251 .IR "quit"
 252 Exit
 253 [= prog-name =] .
 254 .sp
 255 .IR "passwd"
 256 This command prompts you to type in a password (which will not
 257 be echoed) which will be used to authenticate configuration
 258 requests.
 259 The password must correspond to the key configured for
 260 use by the NTP server for this purpose if such requests are to be
 261 successful.
 262 .sp
 263 .IR "raw"
 264 Causes all output from query commands is printed as received
 265 from the remote server.
 266 The only formating/interpretation done on
 267 the data is to transform nonascii data into a printable (but barely
 268 understandable) form.
 269 .sp
 270 .IR "timeout Ar milliseconds"
 271 Specify a timeout period for responses to server queries.
 272 The
 273 default is about 5000 milliseconds.
 274 Note that since
 275 [= prog-name =]
 276 retries each query once after a timeout, the total waiting time for
 277 a timeout will be twice the timeout value set.
 278 .br
 279
 280 .SH OPTIONS
 281 .TP
 282 .BR \-4 ", " \--ipv4
 283 Force IPv4 DNS name resolution.
 284 This option is a member of the ipv4 class of options.
 285 .sp
 286 Force DNS resolution of following host names on the command line
 287 to the IPv4 namespace.
 288 .TP
 289 .BR \-6 ", " \--ipv6
 290 Force IPv6 DNS name resolution.
 291 This option is a member of the ipv4 class of options.
 292 .sp
 293 Force DNS resolution of following host names on the command line
 294 to the IPv6 namespace.
 295 .TP
 296 .BR \-c " \fIcmd\fP, " \--command "=" \fIcmd\fP
 297 run a command and exit.
 298 This option may appear an unlimited number of times.
 299 .sp
 300 The following argument is interpreted as an interactive format command
 301 and is added to the list of commands to be executed on the specified
 302 host(s).
 303 .TP
 304 .BR \-d ", " \--debug-level
 305 Increase output debug message level.
 306 This option may appear an unlimited number of times.
 307 .sp
 308 Increase the debugging message output level.
 309 .TP
 310 .BR \-D " \fIstring\fP, " \--set-debug-level "=" \fIstring\fP
 311 Set the output debug message level.
 312 This option may appear an unlimited number of times.
 313 .sp
 314 Set the output debugging level.  Can be supplied multiple times,
 315 but each overrides the previous value(s).
 316 .TP
 317 .BR \-p ", " \--peers
 318 Print a list of the peers.
 319 This option must not appear in combination with any of the following options:
 320 interactive.
 321 .sp
 322 Print a list of the peers known to the server as well as a summary
 323 of their state. This is equivalent to the 'peers' interactive command.
 324 .TP
 325 .BR \-i ", " \--interactive
 326 Force ntpq to operate in interactive mode.
 327 This option must not appear in combination with any of the following options:
 328 command, peers.
 329 .sp
 330 Force ntpq to operate in interactive mode.  Prompts will be written
 331 to the standard output and commands read from the standard input.
 332 .TP
 333 .BR \-n ", " \--numeric
 334 numeric host addresses.
 335 .sp
 336 Output all host addresses in dotted-quad numeric format rather than
 337 converting to the canonical host names.
 338 .TP
 339 .BR \-? , " \--help"
 340 Display usage information and exit.
 341 .TP
 342 .BR \-! , " \--more-help"
 343 Extended usage information passed thru pager.
 344 .TP
 345 .BR \-> " [\fIrcfile\fP]," " \--save-opts" "[=\fIrcfile\fP]"
 346 Save the option state to \fIrcfile\fP.  The default is the \fIlast\fP
 347 configuration file listed in the \fBOPTION PRESETS\fP section, below.
 348 .TP
 349 .BR \-< " \fIrcfile\fP," " \--load-opts" "=\fIrcfile\fP," " \--no-load-opts"
 350 Load options from \fIrcfile\fP.
 351 The \fIno-load-opts\fP form will disable the loading
 352 of earlier RC/INI files.  \fI--no-load-opts\fP is handled early,
 353 out of order.
 354 .TP
 355 .BR \-v " [{\fIv|c|n\fP}]," " \--version" "[=\fI{v|c|n}\fP]"
 356 Output version of program and exit.  The default mode is `v', a simple
 357 version.  The `c' mode will print copyright information and `n' will
 358 print the full copyright notice.
 359 .SH OPTION PRESETS
 360 Any option that is not marked as \fInot presettable\fP may be preset
 361 by loading values from configuration ("RC" or ".INI") file(s) and values from
 362 environment variables named:
 363 .nf
 364   \fBNTPQ_<option-name>\fP or \fBNTPQ\fP
 365 .fi
 366 .aj
 367 The environmental presets take precedence (are processed later than)
 368 the configuration files.
 369 The \fIhomerc\fP files are "\fI$HOME\fP", and "\fI.\fP".
 370 If any of these are directories, then the file \fI.ntprc\fP
 371 is searched for within those directories.
 372 .SH AUTHOR
 373 David L. Mills and/or others
 374 .br
 375 Please send bug reports to:  http://bugs.ntp.org, bugs@ntp.org
 376
 377 .PP
 378 .nf
 379 .na
 380 see html/copyright.html
 381 .fi
 382 .ad
 383 .PP
 384 This manual page was \fIAutoGen\fP-erated from the \fBntpq\fP
 385 option definitions.