sntp.html revision 258945
1<html lang="en"> 2<head> 3<title>Sntp User's Manual</title> 4<meta http-equiv="Content-Type" content="text/html"> 5<meta name="description" content="Sntp 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">Sntp User's Manual</h1> 23<div class="node"> 24<p><hr> 25<a name="Top"></a>Next: <a rel="next" accesskey="n" href="#sntp-Description">sntp 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">Simple Network Time Protocol User Manual</h2> 32 33<p>This document describes the use of the NTP Project's <code>sntp</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.6p5 of <code>sntp</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">Simple Network Time Protocol User Manual</a> 48</ul> 49</div> 50 51<ul class="menu"> 52<li><a accesskey="1" href="#sntp-Description">sntp Description</a>: Description 53<li><a accesskey="2" href="#sntp-Invocation">sntp Invocation</a>: Invoking sntp 54<li><a accesskey="3" href="#Usage">Usage</a>: Usage 55</ul> 56 57<div class="node"> 58<p><hr> 59<a name="sntp-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>sntp</code> writes the local data and time (i.e., not UTC) to the 67standard output in the format: 68 69<pre class="example"> 1996 Oct 15 20:17:25.123 +4.567 +/- 0.089 secs 70</pre> 71 <p>where the +4.567 +/- 0.089 secs indicates the time offset and 72error bound of the system clock relative to the server clock. 73 74<div class="node"> 75<p><hr> 76<a name="sntp-Invocation"></a> 77<br> 78</div> 79 80<h3 class="section">Invoking sntp</h3> 81 82<p><a name="index-sntp-1"></a><a name="index-standard-Simple-Network-Time-Protocol-program-2"></a> 83<code>sntp</code> 84can be used as a SNTP client to query a NTP or SNTP server and either display 85the time or set the local system's time (given suitable privilege). It can be 86run as an interactive command or in a 87<code>cron</code> 88job. 89 90 <p>NTP (the Network Time Protocol) and SNTP (the Simple Network Time Protocol) 91are defined and described by RFC 5905. 92 93 <p class="indent">The default is to write the estimated correct local date and time (i.e. not 94UTC) to the standard output in a format like 95<pre class="example"> 1996-10-15 20:17:25.123 (+0800) +4.567 +/- 0.089 secs 96</pre> 97 <p>where the 98<pre class="example"> +4.567 +/- 0.089 secs 99</pre> 100 <p>indicates the local clock is 4.567 seconds behind the correct time 101(so 4.567 seconds must be added to the local clock to get it to be correct), 102and the (local) time of 103<code>1996-10-15 20:17:25.123</code> 104can be converted to UTC time by adding 8 hours and 0 minutes, and 105is believed to be correct to within 106<code>+/- 0.089</code> 107seconds. 108 109 <p>This section was generated by <strong>AutoGen</strong>, 110the aginfo template and the option descriptions for the <span class="command">sntp</span> program. It documents the <span class="command">sntp</span> usage text and option meanings. 111 112 <p>This software is released under a specialized copyright license. 113 114<ul class="menu"> 115<li><a accesskey="1" href="#sntp-usage">sntp usage</a>: sntp usage help (-?) 116<li><a accesskey="2" href="#sntp-adjtime">sntp adjtime</a>: adjtime option (-j) 117<li><a accesskey="3" href="#sntp-authentication">sntp authentication</a>: authentication option (-a) 118<li><a accesskey="4" href="#sntp-broadcast">sntp broadcast</a>: broadcast option (-b) 119<li><a accesskey="5" href="#sntp-ipv4">sntp ipv4</a>: ipv4 option (-4) 120<li><a accesskey="6" href="#sntp-ipv6">sntp ipv6</a>: ipv6 option (-6) 121<li><a accesskey="7" href="#sntp-keyfile">sntp keyfile</a>: keyfile option (-k) 122<li><a accesskey="8" href="#sntp-kod">sntp kod</a>: kod option (-K) 123<li><a accesskey="9" href="#sntp-logfile">sntp logfile</a>: logfile option (-l) 124<li><a href="#sntp-normalverbose">sntp normalverbose</a>: normalverbose option (-d) 125<li><a href="#sntp-settod">sntp settod</a>: settod option (-s) 126<li><a href="#sntp-syslog">sntp syslog</a>: syslog option (-p) 127<li><a href="#sntp-timeout">sntp timeout</a>: timeout option (-t) 128</ul> 129 130<div class="node"> 131<p><hr> 132<a name="sntp-usage"></a>Next: <a rel="next" accesskey="n" href="#sntp-adjtime">sntp adjtime</a>, 133Up: <a rel="up" accesskey="u" href="#sntp-Invocation">sntp Invocation</a> 134<br> 135</div> 136 137<h4 class="subsection">sntp usage help (-?)</h4> 138 139<p><a name="index-sntp-usage-3"></a> 140This is the automatically generated usage text for sntp: 141 142<pre class="example">sntp - standard Simple Network Time Protocol program - Ver. 4.2.6p5 143USAGE: sntp [ -<flag> [<val>] | --<name>[{=| }<val>] ]... \ 144 [ hostname-or-IP ...] 145 Flg Arg Option-Name Description 146 -4 no ipv4 Force IPv4 DNS name resolution 147 - prohibits these options: 148 ipv6 149 -6 no ipv6 Force IPv6 DNS name resolution 150 - prohibits these options: 151 ipv4 152 -d no normalverbose Normal verbose 153 -K Str kod KoD history filename 154 -p no syslog Logging with syslog 155 - prohibits these options: 156 logfile 157 -l Str logfile Log to specified logfile 158 - prohibits these options: 159 syslog 160 -s no settod Set (step) the time with settimeofday() 161 - prohibits these options: 162 adjtime 163 -j no adjtime Set (slew) the time with adjtime() 164 - prohibits these options: 165 settod 166 -b Str broadcast Use broadcasts to the address specified for synchronisation 167 -t Num timeout Specify the number of seconds to wait for broadcasts 168 -a Num authentication Enable authentication with the key auth-keynumber 169 -k Str keyfile Specify a keyfile. SNTP will look in this file for the key specified with -a 170 opt version Output version information and exit 171 -? no help Display extended usage information and exit 172 -! no more-help Extended usage information passed thru pager 173 -> opt save-opts Save the option state to a config file 174 -< Str load-opts Load options from a config file 175 - disabled as --no-load-opts 176 - may appear multiple times 177 178Options are specified by doubled hyphens and their name or by a single 179hyphen and the flag character. 180 181 182 183The following option preset mechanisms are supported: 184 - reading file $HOME/.ntprc 185 - reading file ./.ntprc 186 - examining environment variables named SNTP_* 187 188sntp implements the Simple Network Time Protocol, and is used to query an 189NTP or SNTP server and either display the time or set the local system's 190time (given suitable privilege). 191 192It can be run interactively from the command line or as a cron job. 193 194NTP and SNTP are defined by RFC 5905, which obsoletes RFC 4330 and RFC 1951305. 196 197please send bug reports to: http://bugs.ntp.org, bugs@ntp.org 198</pre> 199 <div class="node"> 200<p><hr> 201<a name="sntp-adjtime"></a>Next: <a rel="next" accesskey="n" href="#sntp-authentication">sntp authentication</a>, 202Previous: <a rel="previous" accesskey="p" href="#sntp-usage">sntp usage</a>, 203Up: <a rel="up" accesskey="u" href="#sntp-Invocation">sntp Invocation</a> 204<br> 205</div> 206 207<h4 class="subsection">adjtime option (-j)</h4> 208 209<p><a name="index-sntp_002dadjtime-4"></a> 210This is the “set (slew) the time with adjtime()” option. 211 212 <p>This option has some usage constraints. It: 213 <ul> 214<li>must not appear in combination with any of the following options: 215settod. 216</ul> 217 218<div class="node"> 219<p><hr> 220<a name="sntp-authentication"></a>Next: <a rel="next" accesskey="n" href="#sntp-broadcast">sntp broadcast</a>, 221Previous: <a rel="previous" accesskey="p" href="#sntp-adjtime">sntp adjtime</a>, 222Up: <a rel="up" accesskey="u" href="#sntp-Invocation">sntp Invocation</a> 223<br> 224</div> 225 226<h4 class="subsection">authentication option (-a)</h4> 227 228<p><a name="index-sntp_002dauthentication-5"></a> 229This is the “enable authentication with the key auth-keynumber” option. 230This option enables authentication using the key specified in this option's argument. 231The argument of this option is the keyid, a number specified in the keyfile as this 232key's identifier. See the keyfile option (-k) for more details. 233 234<div class="node"> 235<p><hr> 236<a name="sntp-broadcast"></a>Next: <a rel="next" accesskey="n" href="#sntp-ipv4">sntp ipv4</a>, 237Previous: <a rel="previous" accesskey="p" href="#sntp-authentication">sntp authentication</a>, 238Up: <a rel="up" accesskey="u" href="#sntp-Invocation">sntp Invocation</a> 239<br> 240</div> 241 242<h4 class="subsection">broadcast option (-b)</h4> 243 244<p><a name="index-sntp_002dbroadcast-6"></a> 245This is the “use broadcasts to the address specified for synchronisation” option. 246If specified SNTP will listen to the specified broadcast address 247for NTP broadcasts. The default maximum wait time, 24868 seconds, can be modified with -t. 249 250<div class="node"> 251<p><hr> 252<a name="sntp-ipv4"></a>Next: <a rel="next" accesskey="n" href="#sntp-ipv6">sntp ipv6</a>, 253Previous: <a rel="previous" accesskey="p" href="#sntp-broadcast">sntp broadcast</a>, 254Up: <a rel="up" accesskey="u" href="#sntp-Invocation">sntp Invocation</a> 255<br> 256</div> 257 258<h4 class="subsection">ipv4 option (-4)</h4> 259 260<p><a name="index-sntp_002dipv4-7"></a> 261This is the “force ipv4 dns name resolution” option. 262 263 <p>This option has some usage constraints. It: 264 <ul> 265<li>must not appear in combination with any of the following options: 266ipv6. 267</ul> 268 269 <p>Force DNS resolution of the following host names on the command line 270to the IPv4 namespace. 271 272<div class="node"> 273<p><hr> 274<a name="sntp-ipv6"></a>Next: <a rel="next" accesskey="n" href="#sntp-keyfile">sntp keyfile</a>, 275Previous: <a rel="previous" accesskey="p" href="#sntp-ipv4">sntp ipv4</a>, 276Up: <a rel="up" accesskey="u" href="#sntp-Invocation">sntp Invocation</a> 277<br> 278</div> 279 280<h4 class="subsection">ipv6 option (-6)</h4> 281 282<p><a name="index-sntp_002dipv6-8"></a> 283This is the “force ipv6 dns name resolution” option. 284 285 <p>This option has some usage constraints. It: 286 <ul> 287<li>must not appear in combination with any of the following options: 288ipv4. 289</ul> 290 291 <p>Force DNS resolution of the following host names on the command line 292to the IPv6 namespace. 293 294<div class="node"> 295<p><hr> 296<a name="sntp-keyfile"></a>Next: <a rel="next" accesskey="n" href="#sntp-kod">sntp kod</a>, 297Previous: <a rel="previous" accesskey="p" href="#sntp-ipv6">sntp ipv6</a>, 298Up: <a rel="up" accesskey="u" href="#sntp-Invocation">sntp Invocation</a> 299<br> 300</div> 301 302<h4 class="subsection">keyfile option (-k)</h4> 303 304<p><a name="index-sntp_002dkeyfile-9"></a> 305This is the “specify a keyfile. sntp will look in this file for the key specified with -a” option. 306This option specifies the keyfile. SNTP will search for the key specified with -a keyno in this 307file. Key files follow the following format: 308 309 <p>keyid keytype key 310 311 <p>Where keyid is a number identifying this key 312keytype is one of the follow: 313S Key in 64 Bit hexadecimal number as specified in in the DES specification. 314N Key in 64 Bit hexadecimal number as specified in the NTP standard. 315A Key in a 1-to-8 character ASCII string. 316M Key in a 1-to-8 character ASCII string using the MD5 authentication scheme. 317 318 <p>For more information see ntp.keys(5). 319 320<div class="node"> 321<p><hr> 322<a name="sntp-kod"></a>Next: <a rel="next" accesskey="n" href="#sntp-logfile">sntp logfile</a>, 323Previous: <a rel="previous" accesskey="p" href="#sntp-keyfile">sntp keyfile</a>, 324Up: <a rel="up" accesskey="u" href="#sntp-Invocation">sntp Invocation</a> 325<br> 326</div> 327 328<h4 class="subsection">kod option (-K)</h4> 329 330<p><a name="index-sntp_002dkod-10"></a> 331This is the “kod history filename” option. 332Specifies the filename to be used to persist the history of KoD 333responses received from servers. The default is 334/var/db/ntp-kod. 335 336<div class="node"> 337<p><hr> 338<a name="sntp-logfile"></a>Next: <a rel="next" accesskey="n" href="#sntp-normalverbose">sntp normalverbose</a>, 339Previous: <a rel="previous" accesskey="p" href="#sntp-kod">sntp kod</a>, 340Up: <a rel="up" accesskey="u" href="#sntp-Invocation">sntp Invocation</a> 341<br> 342</div> 343 344<h4 class="subsection">logfile option (-l)</h4> 345 346<p><a name="index-sntp_002dlogfile-11"></a> 347This is the “log to specified logfile” option. 348 349 <p>This option has some usage constraints. It: 350 <ul> 351<li>must not appear in combination with any of the following options: 352syslog. 353</ul> 354 355 <p>This option causes the client to write log messages to the specified 356logfile. 357 358<div class="node"> 359<p><hr> 360<a name="sntp-normalverbose"></a>Next: <a rel="next" accesskey="n" href="#sntp-settod">sntp settod</a>, 361Previous: <a rel="previous" accesskey="p" href="#sntp-logfile">sntp logfile</a>, 362Up: <a rel="up" accesskey="u" href="#sntp-Invocation">sntp Invocation</a> 363<br> 364</div> 365 366<h4 class="subsection">normalverbose option (-d)</h4> 367 368<p><a name="index-sntp_002dnormalverbose-12"></a> 369This is the “normal verbose” option. 370Diagnostic messages for non-fatal errors and a limited amount of 371tracing should be written to standard error. Fatal ones always 372produce a diagnostic. This option should be set when there is a 373suspected problem with the server, network or the source. 374 375<div class="node"> 376<p><hr> 377<a name="sntp-settod"></a>Next: <a rel="next" accesskey="n" href="#sntp-syslog">sntp syslog</a>, 378Previous: <a rel="previous" accesskey="p" href="#sntp-normalverbose">sntp normalverbose</a>, 379Up: <a rel="up" accesskey="u" href="#sntp-Invocation">sntp Invocation</a> 380<br> 381</div> 382 383<h4 class="subsection">settod option (-s)</h4> 384 385<p><a name="index-sntp_002dsettod-13"></a> 386This is the “set (step) the time with settimeofday()” option. 387 388 <p>This option has some usage constraints. It: 389 <ul> 390<li>must not appear in combination with any of the following options: 391adjtime. 392</ul> 393 394<div class="node"> 395<p><hr> 396<a name="sntp-syslog"></a>Next: <a rel="next" accesskey="n" href="#sntp-timeout">sntp timeout</a>, 397Previous: <a rel="previous" accesskey="p" href="#sntp-settod">sntp settod</a>, 398Up: <a rel="up" accesskey="u" href="#sntp-Invocation">sntp Invocation</a> 399<br> 400</div> 401 402<h4 class="subsection">syslog option (-p)</h4> 403 404<p><a name="index-sntp_002dsyslog-14"></a> 405This is the “logging with syslog” option. 406 407 <p>This option has some usage constraints. It: 408 <ul> 409<li>must not appear in combination with any of the following options: 410logfile. 411</ul> 412 413 <p>When this option is set all logging will be done using syslog. 414 415<div class="node"> 416<p><hr> 417<a name="sntp-timeout"></a>Previous: <a rel="previous" accesskey="p" href="#sntp-syslog">sntp syslog</a>, 418Up: <a rel="up" accesskey="u" href="#sntp-Invocation">sntp Invocation</a> 419<br> 420</div> 421 422<h4 class="subsection">timeout option (-t)</h4> 423 424<p><a name="index-sntp_002dtimeout-15"></a> 425This is the “specify the number of seconds to wait for broadcasts” option. 426When waiting for a broadcast packet SNTP will wait the number 427of seconds specified before giving up. Default 68 seconds. 428 429<div class="node"> 430<p><hr> 431<a name="Usage"></a> 432<br> 433</div> 434 435<!-- node-name, next, previous, up --> 436<h3 class="section">Usage</h3> 437 438<p>The simplest use of this program is as an unprivileged command to 439check the current time, offset, and error in the local clock. 440For example: 441 442<pre class="example"> sntp ntpserver.somewhere 443</pre> 444 <p>With suitable privilege, it can be run as a command or in a 445<code>crom</code> job to reset the local clock from a reliable server, like 446the <code>ntpdate</code> and <code>rdate</code> commands. 447For example: 448 449<pre class="example"> sntp -a ntpserver.somewhere 450</pre> 451 </body></html> 452 453