usr.sbin/ntp/ntpq/ntpq.8

   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 ntpq
  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 ntpq
  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 ntpq
  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 ntpq
  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 ntpq
  54 utility will prompt for
  55 commands if the standard input is a terminal device.
  56
  57 The
  58 ntpq
  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 ntpq
  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 ntpq
  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 ntpq
  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 A `\&?'
 100 by itself will print a list of all the command
 101 keywords known to this incarnation of
 102 ntpq.
 103 A
 104 .Ql \&?
 105 followed by a command keyword will print function and usage
 106 information about the command.
 107 This command is probably a better
 108 source of information about
 109 ntpq
 110 than this manual
 111 page.
 112 .sp
 113 .IR "addvars"
 114 .Ar variable_name [=value] ...
 115 .Xc
 116 .sp
 117 .IR "rmvars variable_name ..."
 118 .sp
 119 .IR "clearvars"
 120 The data carried by NTP mode 6 messages consists of a list of
 121 items of the form
 122 .Ql variable_name=value ,
 123 where the
 124 .Ql =value
 125 is ignored, and can be omitted,
 126 in requests to the server to read variables.
 127 The
 128 ntpq
 129 utility maintains an internal list in which data to be included in control
 130 messages can be assembled, and sent using the
 131 .Ic readlist
 132 and
 133 .Ic writelist
 134 commands described below.
 135 The
 136 .Ic addvars
 137 command allows variables and their optional values to be added to
 138 the list.
 139 If more than one variable is to be added, the list should
 140 be comma-separated and not contain white space.
 141 The
 142 .Ic rmvars
 143 command can be used to remove individual variables from the list,
 144 while the
 145 .Ic clearlist
 146 command removes all variables from the
 147 list.
 148 .sp
 149 .IR "authenticate [ yes | no ]"
 150 Normally
 151 ntpq
 152 does not authenticate requests unless
 153 they are write requests.
 154 The command
 155 .Ql authenticate yes
 156 causes
 157 ntpq
 158 to send authentication with all requests it
 159 makes.
 160 Authenticated requests causes some servers to handle
 161 requests slightly differently, and can occasionally melt the CPU in
 162 fuzzballs if you turn authentication on before doing a
 163 .Ic peer
 164 display.
 165 The command
 166 .Ql authenticate
 167 causes
 168 ntpq
 169 to display whether or not
 170 ntpq
 171 is currently autheinticating requests.
 172 .sp
 173 .IR "cooked"
 174 Causes output from query commands to be "cooked", so that
 175 variables which are recognized by
 176 ntpq
 177 will have their
 178 values reformatted for human consumption.
 179 Variables which
 180 ntpq
 181 thinks should have a decodable value but didn't are
 182 marked with a trailing
 183 .Ql \&? .
 184 .@item debug [
 185 .Cm more |
 186 .Cm less |
 187 .Cm off
 188 ]
 189 .Xc
 190 With no argument, displays the current debug level.
 191 Otherwise, the debug level is changed to the indicated level.
 192 .sp
 193 .IR "delay milliseconds"
 194 Specify a time interval to be added to timestamps included in
 195 requests which require authentication.
 196 This is used to enable
 197 (unreliable) server reconfiguration over long delay network paths
 198 or between machines whose clocks are unsynchronized.
 199 Actually the
 200 server does not now require timestamps in authenticated requests,
 201 so this command may be obsolete.
 202 .sp
 203 .IR "host hostname"
 204 Set the host to which future queries will be sent.
 205 Hostname may
 206 be either a host name or a numeric address.
 207 .sp
 208 .IR "hostnames Cm yes | Cm no"
 209 If
 210 .Cm yes
 211 is specified, host names are printed in
 212 information displays.
 213 If
 214 .Cm no
 215 is specified, numeric
 216 addresses are printed instead.
 217 The default is
 218 .Cm yes ,
 219 unless
 220 modified using the command line
 221 .Fl n
 222 switch.
 223 .sp
 224 .IR "keyid keyid"
 225 This command allows the specification of a key number to be
 226 used to authenticate configuration requests.
 227 This must correspond
 228 to a key number the server has been configured to use for this
 229 purpose.
 230 .sp
 231 .IR "ntpversion ["
 232 .Cm 1 |
 233 .Cm 2 |
 234 .Cm 3 |
 235 .Cm 4
 236 ]
 237 .Xc
 238 Sets the NTP version number which
 239 ntpq
 240 claims in
 241 packets.
 242 Defaults to 3, Note that mode 6 control messages (and
 243 modes, for that matter) didn't exist in NTP version 1.
 244 There appear
 245 to be no servers left which demand version 1.
 246 With no argument, displays the current NTP version that will be used
 247 when communicating with servers.
 248 .sp
 249 .IR "quit"
 250 Exit
 251 ntpq.
 252 .sp
 253 .IR "passwd"
 254 This command prompts you to type in a password (which will not
 255 be echoed) which will be used to authenticate configuration
 256 requests.
 257 The password must correspond to the key configured for
 258 use by the NTP server for this purpose if such requests are to be
 259 successful.
 260 .sp
 261 .IR "raw"
 262 Causes all output from query commands is printed as received
 263 from the remote server.
 264 The only formating/interpretation done on
 265 the data is to transform nonascii data into a printable (but barely
 266 understandable) form.
 267 .sp
 268 .IR "timeout Ar milliseconds"
 269 Specify a timeout period for responses to server queries.
 270 The
 271 default is about 5000 milliseconds.
 272 Note that since
 273 ntpq
 274 retries each query once after a timeout, the total waiting time for
 275 a timeout will be twice the timeout value set.
 276 .br
 277
 278 .SH OPTIONS
 279 .TP
 280 .BR \-4 ", " \--ipv4
 281 Force IPv4 DNS name resolution.
 282 This option is a member of the ipv4 class of options.
 283 .sp
 284 Force DNS resolution of following host names on the command line
 285 to the IPv4 namespace.
 286 .TP
 287 .BR \-6 ", " \--ipv6
 288 Force IPv6 DNS name resolution.
 289 This option is a member of the ipv4 class of options.
 290 .sp
 291 Force DNS resolution of following host names on the command line
 292 to the IPv6 namespace.
 293 .TP
 294 .BR \-c " \fIcmd\fP, " \--command "=" \fIcmd\fP
 295 run a command and exit.
 296 This option may appear an unlimited number of times.
 297 .sp
 298 The following argument is interpreted as an interactive format command
 299 and is added to the list of commands to be executed on the specified
 300 host(s).
 301 .TP
 302 .BR \-d ", " \--debug-level
 303 Increase output debug message level.
 304 This option may appear an unlimited number of times.
 305 .sp
 306 Increase the debugging message output level.
 307 .TP
 308 .BR \-D " \fIstring\fP, " \--set-debug-level "=" \fIstring\fP
 309 Set the output debug message level.
 310 This option may appear an unlimited number of times.
 311 .sp
 312 Set the output debugging level.  Can be supplied multiple times,
 313 but each overrides the previous value(s).
 314 .TP
 315 .BR \-p ", " \--peers
 316 Print a list of the peers.
 317 This option must not appear in combination with any of the following options:
 318 interactive.
 319 .sp
 320 Print a list of the peers known to the server as well as a summary
 321 of their state. This is equivalent to the 'peers' interactive command.
 322 .TP
 323 .BR \-i ", " \--interactive
 324 Force ntpq to operate in interactive mode.
 325 This option must not appear in combination with any of the following options:
 326 command, peers.
 327 .sp
 328 Force ntpq to operate in interactive mode.  Prompts will be written
 329 to the standard output and commands read from the standard input.
 330 .TP
 331 .BR \-n ", " \--numeric
 332 numeric host addresses.
 333 .sp
 334 Output all host addresses in dotted-quad numeric format rather than
 335 converting to the canonical host names.
 336 .TP
 337 .BR \-? , " \--help"
 338 Display usage information and exit.
 339 .TP
 340 .BR \-! , " \--more-help"
 341 Extended usage information passed thru pager.
 342 .TP
 343 .BR \-> " [\fIrcfile\fP]," " \--save-opts" "[=\fIrcfile\fP]"
 344 Save the option state to \fIrcfile\fP.  The default is the \fIlast\fP
 345 configuration file listed in the \fBOPTION PRESETS\fP section, below.
 346 .TP
 347 .BR \-< " \fIrcfile\fP," " \--load-opts" "=\fIrcfile\fP," " \--no-load-opts"
 348 Load options from \fIrcfile\fP.
 349 The \fIno-load-opts\fP form will disable the loading
 350 of earlier RC/INI files.  \fI--no-load-opts\fP is handled early,
 351 out of order.
 352 .TP
 353 .BR \-v " [{\fIv|c|n\fP}]," " \--version" "[=\fI{v|c|n}\fP]"
 354 Output version of program and exit.  The default mode is `v', a simple
 355 version.  The `c' mode will print copyright information and `n' will
 356 print the full copyright notice.
 357 .SH OPTION PRESETS
 358 Any option that is not marked as \fInot presettable\fP may be preset
 359 by loading values from configuration ("RC" or ".INI") file(s) and values from
 360 environment variables named:
 361 .nf
 362   \fBNTPQ_<option-name>\fP or \fBNTPQ\fP
 363 .fi
 364 .aj
 365 The environmental presets take precedence (are processed later than)
 366 the configuration files.
 367 The \fIhomerc\fP files are "\fI$HOME\fP", and "\fI.\fP".
 368 If any of these are directories, then the file \fI.ntprc\fP
 369 is searched for within those directories.
 370 .SH AUTHOR
 371 David L. Mills and/or others
 372 .br
 373 Please send bug reports to:  http://bugs.ntp.org, bugs@ntp.org
 374
 375 .PP
 376 .nf
 377 .na
 378 see /usr/share/doc/html/ntp/copyright.html
 379 .fi
 380 .ad
 381 .PP
 382 This manual page was \fIAutoGen\fP-erated from the \fBntpq\fP
 383 option definitions.