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