ntpdc.html revision 309007
1<html lang="en"> 2<head> 3<title>ntpdc: NTPD Control User's Manual</title> 4<meta http-equiv="Content-Type" content="text/html"> 5<meta name="description" content="ntpdc: NTPD Control User's Manual"> 6<meta name="generator" content="makeinfo 4.7"> 7<link title="Top" rel="top" href="#Top"> 8<link href="http://www.gnu.org/software/texinfo/" rel="generator-home" title="Texinfo Homepage"> 9<meta http-equiv="Content-Style-Type" content="text/css"> 10<style type="text/css"><!-- 11 pre.display { font-family:inherit } 12 pre.format { font-family:inherit } 13 pre.smalldisplay { font-family:inherit; font-size:smaller } 14 pre.smallformat { font-family:inherit; font-size:smaller } 15 pre.smallexample { font-size:smaller } 16 pre.smalllisp { font-size:smaller } 17 span.sc { font-variant:small-caps } 18 span.roman { font-family: serif; font-weight: normal; } 19--></style> 20</head> 21<body> 22<h1 class="settitle">ntpdc: NTPD Control User's Manual</h1> 23<div class="node"> 24<p><hr> 25<a name="Top"></a>Next: <a rel="next" accesskey="n" href="#ntpdc-Description">ntpdc Description</a>, 26Previous: <a rel="previous" accesskey="p" href="#dir">(dir)</a>, 27Up: <a rel="up" accesskey="u" href="#dir">(dir)</a> 28<br> 29</div> 30 31<h2 class="unnumbered">ntpdc: NTPD Control User Manual</h2> 32 33<p>This document describes the use of the NTP Project's <code>ntpdc</code> program, 34that can be used to query a Network Time Protocol (NTP) server and 35display the time offset of the system clock relative to the server 36clock. Run as root, it can correct the system clock to this offset as 37well. It can be run as an interactive command or from a cron job. 38 39 <p>This document applies to version 4.2.8p9 of <code>ntpdc</code>. 40 41 <p>The program implements the SNTP protocol as defined by RFC 5905, the NTPv4 42IETF specification. 43 44 <div class="shortcontents"> 45<h2>Short Contents</h2> 46<ul> 47<a href="#Top">ntpdc: NTPD Control User Manual</a> 48</ul> 49</div> 50 51<ul class="menu"> 52<li><a accesskey="1" href="#ntpdc-Description">ntpdc Description</a>: Description 53<li><a accesskey="2" href="#ntpdc-Invocation">ntpdc Invocation</a>: Invoking ntpdc 54<li><a accesskey="3" href="#Usage">Usage</a>: Usage 55</ul> 56 57<div class="node"> 58<p><hr> 59<a name="ntpdc-Description"></a> 60<br> 61</div> 62 63<!-- node-name, next, previous, up --> 64<h3 class="section">Description</h3> 65 66<p>By default, <code>ntpdc</code> writes the local data and time (i.e., not UTC) to the 67standard output in the format: 68 69<pre class="example"> 1996-10-15 20:17:25.123 (+0800) +4.567 +/- 0.089 secs 70</pre> 71 <p>where 72YYYY-MM-DD HH:MM:SS.SUBSEC is the local date and time, 73(+0800) is the local timezone adjustment (so we would add 8 hours and 0 minutes to convert the reported local time to UTC), 74and 75the +4.567 +/- 0.089 secs indicates the time offset and 76error bound of the system clock relative to the server clock. 77 78<div class="node"> 79<p><hr> 80<a name="ntpdc-Invocation"></a> 81<br> 82</div> 83 84<h3 class="section">Invoking ntpdc</h3> 85 86<p><a name="index-ntpdc-1"></a><a name="index-vendor_002dspecific-NTPD-control-program-2"></a> 87 88 <p><code>ntpdc</code> 89is deprecated. 90Please use 91<code>ntpq(1ntpqmdoc)</code> instead - it can do everything 92<code>ntpdc</code> 93used to do, and it does so using a much more sane interface. 94 95 <p><code>ntpdc</code> 96is a utility program used to query 97<code>ntpd(1ntpdmdoc)</code> 98about its 99current state and to request changes in that state. 100It uses NTP mode 7 control message formats described in the source code. 101The program may 102be run either in interactive mode or controlled using command line 103arguments. 104Extensive state and statistics information is available 105through the 106<code>ntpdc</code> 107interface. 108In addition, nearly all the 109configuration options which can be specified at startup using 110ntpd's configuration file may also be specified at run time using 111<code>ntpdc</code> 112 113 <p>This section was generated by <strong>AutoGen</strong>, 114using the <code>agtexi-cmd</code> template and the option descriptions for the <code>ntpdc</code> program. 115This software is released under the NTP license, <http://ntp.org/license>. 116 117<ul class="menu"> 118<li><a accesskey="1" href="#ntpdc-usage">ntpdc usage</a>: ntpdc help/usage (<span class="option">--help</span>) 119<li><a accesskey="2" href="#ntpdc-ipv4">ntpdc ipv4</a>: ipv4 option (-4) 120<li><a accesskey="3" href="#ntpdc-ipv6">ntpdc ipv6</a>: ipv6 option (-6) 121<li><a accesskey="4" href="#ntpdc-command">ntpdc command</a>: command option (-c) 122<li><a accesskey="5" href="#ntpdc-interactive">ntpdc interactive</a>: interactive option (-i) 123<li><a accesskey="6" href="#ntpdc-listpeers">ntpdc listpeers</a>: listpeers option (-l) 124<li><a accesskey="7" href="#ntpdc-numeric">ntpdc numeric</a>: numeric option (-n) 125<li><a accesskey="8" href="#ntpdc-peers">ntpdc peers</a>: peers option (-p) 126<li><a accesskey="9" href="#ntpdc-showpeers">ntpdc showpeers</a>: showpeers option (-s) 127<li><a href="#ntpdc-config">ntpdc config</a>: presetting/configuring ntpdc 128<li><a href="#ntpdc-exit-status">ntpdc exit status</a>: exit status 129<li><a href="#ntpdc-Usage">ntpdc Usage</a>: Usage 130<li><a href="#ntpdc-See-Also">ntpdc See Also</a>: See Also 131<li><a href="#ntpdc-Authors">ntpdc Authors</a>: Authors 132<li><a href="#ntpdc-Bugs">ntpdc Bugs</a>: Bugs 133</ul> 134 135<div class="node"> 136<p><hr> 137<a name="ntpdc-usage"></a>Next: <a rel="next" accesskey="n" href="#ntpdc-ipv4">ntpdc ipv4</a>, 138Up: <a rel="up" accesskey="u" href="#ntpdc-Invocation">ntpdc Invocation</a> 139<br> 140</div> 141 142<h4 class="subsection">ntpdc help/usage (<span class="option">--help</span>)</h4> 143 144<p><a name="index-ntpdc-help-3"></a> 145This is the automatically generated usage text for ntpdc. 146 147 <p>The text printed is the same whether selected with the <code>help</code> option 148(<span class="option">--help</span>) or the <code>more-help</code> option (<span class="option">--more-help</span>). <code>more-help</code> will print 149the usage text by passing it through a pager program. 150<code>more-help</code> is disabled on platforms without a working 151<code>fork(2)</code> function. The <code>PAGER</code> environment variable is 152used to select the program, defaulting to <span class="file">more</span>. Both will exit 153with a status code of 0. 154 155<pre class="example">ntpdc - vendor-specific NTPD control program - Ver. 4.2.8p9 156Usage: ntpdc [ -<flag> [<val>] | --<name>[{=| }<val>] ]... [ host ...] 157 Flg Arg Option-Name Description 158 -4 no ipv4 Force IPv4 DNS name resolution 159 - prohibits the option 'ipv6' 160 -6 no ipv6 Force IPv6 DNS name resolution 161 - prohibits the option 'ipv4' 162 -c Str command run a command and exit 163 - may appear multiple times 164 -d no debug-level Increase debug verbosity level 165 - may appear multiple times 166 -D Num set-debug-level Set the debug verbosity level 167 - may appear multiple times 168 -i no interactive Force ntpq to operate in interactive mode 169 - prohibits these options: 170 command 171 listpeers 172 peers 173 showpeers 174 -l no listpeers Print a list of the peers 175 - prohibits the option 'command' 176 -n no numeric numeric host addresses 177 -p no peers Print a list of the peers 178 - prohibits the option 'command' 179 -s no showpeers Show a list of the peers 180 - prohibits the option 'command' 181 opt version output version information and exit 182 -? no help display extended usage information and exit 183 -! no more-help extended usage information passed thru pager 184 -> opt save-opts save the option state to a config file 185 -< Str load-opts load options from a config file 186 - disabled as '--no-load-opts' 187 - may appear multiple times 188 189Options are specified by doubled hyphens and their name or by a single 190hyphen and the flag character. 191 192 193The following option preset mechanisms are supported: 194 - reading file $HOME/.ntprc 195 - reading file ./.ntprc 196 - examining environment variables named NTPDC_* 197 198Please send bug reports to: <http://bugs.ntp.org, bugs@ntp.org> 199</pre> 200 <div class="node"> 201<p><hr> 202<a name="ntpdc-ipv4"></a>Next: <a rel="next" accesskey="n" href="#ntpdc-ipv6">ntpdc ipv6</a>, 203Previous: <a rel="previous" accesskey="p" href="#ntpdc-usage">ntpdc usage</a>, 204Up: <a rel="up" accesskey="u" href="#ntpdc-Invocation">ntpdc Invocation</a> 205<br> 206</div> 207 208<h4 class="subsection">ipv4 option (-4)</h4> 209 210<p><a name="index-ntpdc_002dipv4-4"></a> 211This is the “force ipv4 dns name resolution” option. 212 213<p class="noindent">This option has some usage constraints. It: 214 <ul> 215<li>must not appear in combination with any of the following options: 216ipv6. 217</ul> 218 219 <p>Force DNS resolution of following host names on the command line 220to the IPv4 namespace. 221<div class="node"> 222<p><hr> 223<a name="ntpdc-ipv6"></a>Next: <a rel="next" accesskey="n" href="#ntpdc-command">ntpdc command</a>, 224Previous: <a rel="previous" accesskey="p" href="#ntpdc-ipv4">ntpdc ipv4</a>, 225Up: <a rel="up" accesskey="u" href="#ntpdc-Invocation">ntpdc Invocation</a> 226<br> 227</div> 228 229<h4 class="subsection">ipv6 option (-6)</h4> 230 231<p><a name="index-ntpdc_002dipv6-5"></a> 232This is the “force ipv6 dns name resolution” option. 233 234<p class="noindent">This option has some usage constraints. It: 235 <ul> 236<li>must not appear in combination with any of the following options: 237ipv4. 238</ul> 239 240 <p>Force DNS resolution of following host names on the command line 241to the IPv6 namespace. 242<div class="node"> 243<p><hr> 244<a name="ntpdc-command"></a>Next: <a rel="next" accesskey="n" href="#ntpdc-interactive">ntpdc interactive</a>, 245Previous: <a rel="previous" accesskey="p" href="#ntpdc-ipv6">ntpdc ipv6</a>, 246Up: <a rel="up" accesskey="u" href="#ntpdc-Invocation">ntpdc Invocation</a> 247<br> 248</div> 249 250<h4 class="subsection">command option (-c)</h4> 251 252<p><a name="index-ntpdc_002dcommand-6"></a> 253This is the “run a command and exit” option. 254This option takes a string argument <span class="file">cmd</span>. 255 256<p class="noindent">This option has some usage constraints. It: 257 <ul> 258<li>may appear an unlimited number of times. 259</ul> 260 261 <p>The following argument is interpreted as an interactive format command 262and is added to the list of commands to be executed on the specified 263host(s). 264<div class="node"> 265<p><hr> 266<a name="ntpdc-interactive"></a>Next: <a rel="next" accesskey="n" href="#ntpdc-listpeers">ntpdc listpeers</a>, 267Previous: <a rel="previous" accesskey="p" href="#ntpdc-command">ntpdc command</a>, 268Up: <a rel="up" accesskey="u" href="#ntpdc-Invocation">ntpdc Invocation</a> 269<br> 270</div> 271 272<h4 class="subsection">interactive option (-i)</h4> 273 274<p><a name="index-ntpdc_002dinteractive-7"></a> 275This is the “force ntpq to operate in interactive mode” option. 276 277<p class="noindent">This option has some usage constraints. It: 278 <ul> 279<li>must not appear in combination with any of the following options: 280command, listpeers, peers, showpeers. 281</ul> 282 283 <p>Force ntpq to operate in interactive mode. Prompts will be written 284to the standard output and commands read from the standard input. 285<div class="node"> 286<p><hr> 287<a name="ntpdc-listpeers"></a>Next: <a rel="next" accesskey="n" href="#ntpdc-numeric">ntpdc numeric</a>, 288Previous: <a rel="previous" accesskey="p" href="#ntpdc-interactive">ntpdc interactive</a>, 289Up: <a rel="up" accesskey="u" href="#ntpdc-Invocation">ntpdc Invocation</a> 290<br> 291</div> 292 293<h4 class="subsection">listpeers option (-l)</h4> 294 295<p><a name="index-ntpdc_002dlistpeers-8"></a> 296This is the “print a list of the peers” option. 297 298<p class="noindent">This option has some usage constraints. It: 299 <ul> 300<li>must not appear in combination with any of the following options: 301command. 302</ul> 303 304 <p>Print a list of the peers known to the server as well as a summary of 305their state. This is equivalent to the 'listpeers' interactive command. 306<div class="node"> 307<p><hr> 308<a name="ntpdc-numeric"></a>Next: <a rel="next" accesskey="n" href="#ntpdc-peers">ntpdc peers</a>, 309Previous: <a rel="previous" accesskey="p" href="#ntpdc-listpeers">ntpdc listpeers</a>, 310Up: <a rel="up" accesskey="u" href="#ntpdc-Invocation">ntpdc Invocation</a> 311<br> 312</div> 313 314<h4 class="subsection">numeric option (-n)</h4> 315 316<p><a name="index-ntpdc_002dnumeric-9"></a> 317This is the “numeric host addresses” option. 318Output all host addresses in dotted-quad numeric format rather than 319converting to the canonical host names. 320<div class="node"> 321<p><hr> 322<a name="ntpdc-peers"></a>Next: <a rel="next" accesskey="n" href="#ntpdc-showpeers">ntpdc showpeers</a>, 323Previous: <a rel="previous" accesskey="p" href="#ntpdc-numeric">ntpdc numeric</a>, 324Up: <a rel="up" accesskey="u" href="#ntpdc-Invocation">ntpdc Invocation</a> 325<br> 326</div> 327 328<h4 class="subsection">peers option (-p)</h4> 329 330<p><a name="index-ntpdc_002dpeers-10"></a> 331This is the “print a list of the peers” option. 332 333<p class="noindent">This option has some usage constraints. It: 334 <ul> 335<li>must not appear in combination with any of the following options: 336command. 337</ul> 338 339 <p>Print a list of the peers known to the server as well as a summary 340of their state. This is equivalent to the 'peers' interactive command. 341<div class="node"> 342<p><hr> 343<a name="ntpdc-showpeers"></a>Next: <a rel="next" accesskey="n" href="#ntpdc-config">ntpdc config</a>, 344Previous: <a rel="previous" accesskey="p" href="#ntpdc-peers">ntpdc peers</a>, 345Up: <a rel="up" accesskey="u" href="#ntpdc-Invocation">ntpdc Invocation</a> 346<br> 347</div> 348 349<h4 class="subsection">showpeers option (-s)</h4> 350 351<p><a name="index-ntpdc_002dshowpeers-11"></a> 352This is the “show a list of the peers” option. 353 354<p class="noindent">This option has some usage constraints. It: 355 <ul> 356<li>must not appear in combination with any of the following options: 357command. 358</ul> 359 360 <p>Print a list of the peers known to the server as well as a summary 361of their state. This is equivalent to the 'dmpeers' interactive command. 362 363<div class="node"> 364<p><hr> 365<a name="ntpdc-config"></a>Next: <a rel="next" accesskey="n" href="#ntpdc-exit-status">ntpdc exit status</a>, 366Previous: <a rel="previous" accesskey="p" href="#ntpdc-showpeers">ntpdc showpeers</a>, 367Up: <a rel="up" accesskey="u" href="#ntpdc-Invocation">ntpdc Invocation</a> 368<br> 369</div> 370 371<h4 class="subsection">presetting/configuring ntpdc</h4> 372 373<p>Any option that is not marked as <i>not presettable</i> may be preset by 374loading values from configuration ("rc" or "ini") files, and values from environment variables named <code>NTPDC</code> and <code>NTPDC_<OPTION_NAME></code>. <code><OPTION_NAME></code> must be one of 375the options listed above in upper case and segmented with underscores. 376The <code>NTPDC</code> variable will be tokenized and parsed like 377the command line. The remaining variables are tested for existence and their 378values are treated like option arguments. 379 380<p class="noindent"><code>libopts</code> will search in 2 places for configuration files: 381 <ul> 382<li>$HOME 383<li>$PWD 384</ul> 385 The environment variables <code>HOME</code>, and <code>PWD</code> 386are expanded and replaced when <span class="file">ntpdc</span> runs. 387For any of these that are plain files, they are simply processed. 388For any that are directories, then a file named <span class="file">.ntprc</span> is searched for 389within that directory and processed. 390 391 <p>Configuration files may be in a wide variety of formats. 392The basic format is an option name followed by a value (argument) on the 393same line. Values may be separated from the option name with a colon, 394equal sign or simply white space. Values may be continued across multiple 395lines by escaping the newline with a backslash. 396 397 <p>Multiple programs may also share the same initialization file. 398Common options are collected at the top, followed by program specific 399segments. The segments are separated by lines like: 400<pre class="example"> [NTPDC] 401</pre> 402 <p class="noindent">or by 403<pre class="example"> <?program ntpdc> 404</pre> 405 <p class="noindent">Do not mix these styles within one configuration file. 406 407 <p>Compound values and carefully constructed string values may also be 408specified using XML syntax: 409<pre class="example"> <option-name> 410 <sub-opt>...&lt;...&gt;...</sub-opt> 411 </option-name> 412</pre> 413 <p class="noindent">yielding an <code>option-name.sub-opt</code> string value of 414<pre class="example"> "...<...>..." 415</pre> 416 <p><code>AutoOpts</code> does not track suboptions. You simply note that it is a 417hierarchicly valued option. <code>AutoOpts</code> does provide a means for searching 418the associated name/value pair list (see: optionFindValue). 419 420 <p>The command line options relating to configuration and/or usage help are: 421 422<h5 class="subsubheading">version (-)</h5> 423 424<p>Print the program version to standard out, optionally with licensing 425information, then exit 0. The optional argument specifies how much licensing 426detail to provide. The default is to print just the version. The licensing infomation may be selected with an option argument. 427Only the first letter of the argument is examined: 428 429 <dl> 430<dt><span class="samp">version</span><dd>Only print the version. This is the default. 431<br><dt><span class="samp">copyright</span><dd>Name the copyright usage licensing terms. 432<br><dt><span class="samp">verbose</span><dd>Print the full copyright usage licensing terms. 433</dl> 434 435<div class="node"> 436<p><hr> 437<a name="ntpdc-exit-status"></a>Next: <a rel="next" accesskey="n" href="#ntpdc-Usage">ntpdc Usage</a>, 438Previous: <a rel="previous" accesskey="p" href="#ntpdc-config">ntpdc config</a>, 439Up: <a rel="up" accesskey="u" href="#ntpdc-Invocation">ntpdc Invocation</a> 440<br> 441</div> 442 443<h4 class="subsection">ntpdc exit status</h4> 444 445<p>One of the following exit values will be returned: 446 <dl> 447<dt><span class="samp">0 (EXIT_SUCCESS)</span><dd>Successful program execution. 448<br><dt><span class="samp">1 (EXIT_FAILURE)</span><dd>The operation failed or the command syntax was not valid. 449<br><dt><span class="samp">66 (EX_NOINPUT)</span><dd>A specified configuration file could not be loaded. 450<br><dt><span class="samp">70 (EX_SOFTWARE)</span><dd>libopts had an internal operational error. Please report 451it to autogen-users@lists.sourceforge.net. Thank you. 452</dl> 453 <div class="node"> 454<p><hr> 455<a name="ntpdc-Usage"></a>Next: <a rel="next" accesskey="n" href="#ntpdc-See-Also">ntpdc See Also</a>, 456Previous: <a rel="previous" accesskey="p" href="#ntpdc-exit-status">ntpdc exit status</a>, 457Up: <a rel="up" accesskey="u" href="#ntpdc-Invocation">ntpdc Invocation</a> 458<br> 459</div> 460 461<h4 class="subsection">ntpdc Usage</h4> 462 463<div class="node"> 464<p><hr> 465<a name="ntpdc-See-Also"></a>Next: <a rel="next" accesskey="n" href="#ntpdc-Authors">ntpdc Authors</a>, 466Previous: <a rel="previous" accesskey="p" href="#ntpdc-Usage">ntpdc Usage</a>, 467Up: <a rel="up" accesskey="u" href="#ntpdc-Invocation">ntpdc Invocation</a> 468<br> 469</div> 470 471<h4 class="subsection">ntpdc See Also</h4> 472 473<div class="node"> 474<p><hr> 475<a name="ntpdc-Authors"></a>Next: <a rel="next" accesskey="n" href="#ntpdc-Bugs">ntpdc Bugs</a>, 476Previous: <a rel="previous" accesskey="p" href="#ntpdc-See-Also">ntpdc See Also</a>, 477Up: <a rel="up" accesskey="u" href="#ntpdc-Invocation">ntpdc Invocation</a> 478<br> 479</div> 480 481<h4 class="subsection">ntpdc Authors</h4> 482 483<div class="node"> 484<p><hr> 485<a name="ntpdc-Bugs"></a>Previous: <a rel="previous" accesskey="p" href="#ntpdc-Authors">ntpdc Authors</a>, 486Up: <a rel="up" accesskey="u" href="#ntpdc-Invocation">ntpdc Invocation</a> 487<br> 488</div> 489 490<h4 class="subsection">ntpdc Bugs</h4> 491 492<div class="node"> 493<p><hr> 494<a name="Usage"></a> 495<br> 496</div> 497 498<!-- node-name, next, previous, up --> 499<h3 class="section">Usage</h3> 500 501<p>The simplest use of this program is as an unprivileged command to 502check the current time, offset, and error in the local clock. 503For example: 504 505<pre class="example"> ntpdc ntpserver.somewhere 506</pre> 507 <p>With suitable privilege, it can be run as a command or in a 508<code>cron</code> job to reset the local clock from a reliable server, like 509the <code>ntpdate</code> and <code>rdate</code> commands. 510For example: 511 512<pre class="example"> ntpdc -a ntpserver.somewhere 513</pre> 514 </body></html> 515 516