19c2daa00SOllivier Robert<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"> 29c2daa00SOllivier Robert<html> 39c2daa00SOllivier Robert<head> 4ea906c41SOllivier Robert<meta http-equiv="content-type" content="text/html;charset=iso-8859-1"> 52b15cb3dSCy Schubert<title>sntp - Simple Network Time Protocol (SNTP) Client</title> 62b15cb3dSCy Schubert<!-- Changed by: Harlan &, 07-Dec-2014 --> 79c2daa00SOllivier Robert<link href="scripts/style.css" type="text/css" rel="stylesheet"> 89c2daa00SOllivier Robert</head> 99c2daa00SOllivier Robert<body> 102b15cb3dSCy Schubert<h3><tt>sntp</tt> - Simple Network Time Protocol (SNTP) Client</h3> 119c2daa00SOllivier Robert<img src="pic/dogsnake.gif" alt="gif" align="left"><a href="http://www.eecis.udel.edu/~mills/pictures.html">from <i>Alice's Adventures in Wonderland</i>, Lewis Carroll</a> 122b15cb3dSCy Schubert<p>S is for snakeoil.</p> 132b15cb3dSCy Schubert<p>Last update: 14*a25439b6SCy Schubert <!-- #BeginDate format:En2m -->1-Apr-2015 11:05<!-- #EndDate --> 152b15cb3dSCy Schubert UTC</p> 169c2daa00SOllivier Robert<br clear="left"> 179c2daa00SOllivier Robert<hr> 189c2daa00SOllivier Robert<h4>Synopsis</h4> 192b15cb3dSCy Schubert<tt>sntp [{--help -?}][{-4 -6}][-a <i>keynum</i>][-b <i>bcaddress</i>][-B <i>bctimeout</i>][-c][-d][-D <i>debug-level</i>][-g <i>delay</i>][-K <i>kodfile</i>][-k <i>keyfile</i>][-l <i>logfile</i>][-M <i>steplimit</i>][-o <i>ntpver</i>][-r][-S][-s][-u <i>uctimeout</i>][--wait][--version][<i>address(es)</i>]</tt> 209c2daa00SOllivier Robert<h4>Description</h4> 212b15cb3dSCy Schubert<p>This program is a Simple Network Time Protocol (SNTP) client that can be used to query a Network Time Protocol (NTP) server and display the time offset of the system clock relative to the server clock. Run as root it can correct the system clock to this offset as well. It can be run as an interactive command or from a script by a <tt>cron</tt> job. The program implements the SNTP client protocol defined in RFC 5905, including the full on-wire protocol but does not provide the sanity checks, access controls, security functions and mitigation algorithms as in the full NTP version 4 specification, also defined in RFC 5905.</p> 229c2daa00SOllivier Robert<p>By default, <tt>sntp</tt> writes the local date and time (i.e., not UTC) to the standard output in the format</p> 23*a25439b6SCy Schubert<p><tt>2011-08-04 00:40:36.642222 (+0000) +0.006611 +/- 0.041061 psp-os1 149.20.68.26 s3 no-leap</tt></p> 24*a25439b6SCy Schubert<p>where the <tt>+0.006611 +/- 0.041061</tt> indicates the time offset and error bound of the system clock relative to the server clock, in seconds. The hostname and/or the IP is displayed, as is the stratum of the server. Finally, the leap indicator status is displayed.</p> 252b15cb3dSCy Schubert<p>If -b <i>bcaddress</i> is not specified, the program sends a single message to each address and waits up to <i>uctimeout</i> (default 5) seconds for a unicast server response. Otherwise, it sends no message and waits up to <i>bctimeout</i> (default 68) seconds for a broadcast NTP message.</p> 269c2daa00SOllivier Robert<h4>Options</h4> 279c2daa00SOllivier Robert<p><tt>sntp</tt> recognizes the following options:</p> 289c2daa00SOllivier Robert<dl> 292b15cb3dSCy Schubert <dt><tt>-?, --help</tt></dt> 302b15cb3dSCy Schubert <dd>displays usage information. The short form typically requires shell quoting, such as <tt>-\?</tt>, otherwise <tt>?</tt> is consumed by the shell.</dd> 312b15cb3dSCy Schubert <dt><tt>-4, --ipv4</tt></dt> 322b15cb3dSCy Schubert <dd>When resolving hostnames to IP addresses, use IPv4 addresses only.</dd> 332b15cb3dSCy Schubert <dt><tt>-6, --ipv6</tt></dt> 342b15cb3dSCy Schubert <dd>When resolving hostnames to IP addresses, use IPv6 addresses only.</dd> 352b15cb3dSCy Schubert <dt><tt>-a <i>keynum</i>, --authentication <i>keynum</i></tt></dt> 362b15cb3dSCy Schubert <dd>Enable authentication with the key ID <i>keynum</i>. <i>keynum</i> is a number specified in the keyfile along with an authentication secret (password or digest). See the <tt>-k, --keyfile</tt> option for more details.</dd> 372b15cb3dSCy Schubert <dt><tt>-b <i>bcaddress</i>, --broadcast <i>bcaddress</i></tt></dt> 382b15cb3dSCy Schubert <dd>Listen for NTP packets sent to the broadcast or multicast address <i>bcaddress</i>, which can be a DNS name or IP address. The default maximum time to listen for broadcasts/multicasts, 68 seconds, can be modified with the <tt>-B, --bctimeout</tt> option.</dd> 392b15cb3dSCy Schubert <dt><tt>-B <i>bctimeout</i>, --bctimeout <i>bctimeout</i></tt></dt> 402b15cb3dSCy Schubert <dd>Wait <i>bctimeout</i> seconds for broadcast or multicast NTP message before terminating. The default is 68 seconds, chosen because ntpd typically transmits broadcasts/multicasts every 64 seconds. Note that the short option is <tt>-B</tt>, an uppercase letter B.</dd> 412b15cb3dSCy Schubert <dt><tt>-c, --concurrent</tt></dt> 422b15cb3dSCy Schubert <dd>Concurrently query all addresses returned for hostname. Requests from an NTP client to a single server should never be sent more often than once every two seconds. By default, all addresses resolved from a single hostname are assumed to be for a single instance of ntpd, and therefore sntp will send queries to these addresses one after another, waiting two seconds between queries. This option indicates multiple addresses returned for a hostname are on different machines, so sntp can send concurrent queries. This is appropriate when using *.pool.ntp.org, for example.</dd> 432b15cb3dSCy Schubert <dt><tt>-d, --debug-level</tt></dt> 442b15cb3dSCy Schubert <dd>Increase debug verbosity level by one. May be specified multiple times. See also the <tt>-D, --set-debug-level</tt> option.</dd> 452b15cb3dSCy Schubert <dt><tt>-D <i>debug-level</i>, --set-debug-level <i>debug-level</i></tt></dt> 462b15cb3dSCy Schubert <dd>Set the debug verbosity level to <i>debug-level</i>. The default level is zero. Note that the short option is <tt>-D</tt>, an uppercase letter D. See also the <tt>-d, --debug-level</tt> option.</dd> 472b15cb3dSCy Schubert <dt><tt>-g <i>delay</i>, --gap <i>delay</i></tt></dt> 482b15cb3dSCy Schubert <dd>Specify the <i>delay</i> in milliseconds between outgoing queries, defaulting to 50. <tt>sntp</tt> sends queries to all provided hostnames/addresses in short succession, and by default terminates once the first valid response is received. With multiple time sources provided, all but one will not be used. To limit the number of queries whose responses will not be used, each query is separated from the preceding one by <i>delay</i> milliseconds, to allow time for responses to earlier queries to be received. A larger <i>delay</i> reduces the query load on the time sources, increasing the time to receive a valid response if the first source attempted is slow or unreachable.</dd> 492b15cb3dSCy Schubert <dt><tt>-K <i>kodfile</i>, --kod <i>kodfile</i></tt></dt> 502b15cb3dSCy Schubert <dd>Specifies the filename <i>kodfile</i> to be used for the persistent history of KoD (Kiss Of Death, or rate-limiting) responses received from servers. The default is <tt>/var/db/ntp-kod</tt>. If the file does not exist, a warning message will be displayed. The file will not be created. Note that the short option is <tt>-K</tt>, an uppercase letter K.</dd> 512b15cb3dSCy Schubert <dt><tt>-k <i>keyfile</i>, --keyfile <i>keyfile</i></tt></dt> 522b15cb3dSCy Schubert <dd>Specifies the filename <i>keyfile</i> used with the <tt>-a</tt>/<tt>--authentication</tt> option. The format of the file is described on the <a href="keygen.html"><tt>ntp-keygen</tt> page</a>.</dd> 532b15cb3dSCy Schubert <dt><tt>-l <i>logfile</i>, --filelog <i>logfile</i></tt></dt> 542b15cb3dSCy Schubert <dd>Specifies the filename in which to append a copy of status messages, which also appear on the terminal.</dd> 552b15cb3dSCy Schubert <dt><tt>-M <i>steplimit</i>, --steplimit <i>steplimit</i></tt></dt> 562b15cb3dSCy Schubert <dd>If both <tt>-S</tt>/<tt>--step</tt> and <tt>-s</tt>/<tt>--slew</tt> options are provided, an offset of less than <i>steplimit</i> milliseconds will be corrected by slewing the clock using adjtime(), while an offset of <i>steplimit</i> or more will be corrected by setting the clock to the corrected time. Note that the short option is <tt>-M</tt>, an uppercase letter M.</dd> 572b15cb3dSCy Schubert <dt><tt>-o <i>ntpver</i>, --ntpversion <i>ntpver</i></tt></dt> 582b15cb3dSCy Schubert <dd>Specifies the NTP protocol version number <i>ntpver</i> to include in requests, default 4. This option is rarely useful.</dd> 592b15cb3dSCy Schubert <dt><tt>-r, --usereservedport</tt></dt> 602b15cb3dSCy Schubert <dd>By default, <tt>sntp</tt> uses a UDP source port number selected by the operating system. When this option is used, the reserved NTP port 123 is used, which most often requires <tt>sntp</tt> be invoked as the superuser (commonly "root"). This can help identify connectivity failures due to port-based firewalling which affect <tt>ntpd</tt>, which always uses source port 123.</dd> 612b15cb3dSCy Schubert <dt><tt>-S, --step</tt></dt> 622b15cb3dSCy Schubert <dd>By default, <tt>sntp</tt> displays the clock offset but does not attempt to correct it. This option enables offset correction by stepping, that is, directly setting the clock to the corrected time. This typically requires <tt>sntp</tt> be invoked as the superuser ("root"). Note that the short option is <tt>-S</tt>, an uppercase letter S.</dd> 632b15cb3dSCy Schubert <dt><tt>-s, --slew</tt></dt> 642b15cb3dSCy Schubert <dd>By default, <tt>sntp</tt> displays the clock offset but does not attempt to correct it. This option enables offset correction by slewing using adjtime(), which changes the rate of the clock for a period long enough to accomplish the required offset (phase) correction. This typically requires <tt>sntp</tt> be invoked as the superuser ("root").</dd> 652b15cb3dSCy Schubert <dt><tt>-u <i>uctimeout</i>, --uctimeout <i>uctimeout</i></tt></dt> 662b15cb3dSCy Schubert <dd>Specifies the maximum time <i>uctimeout</i> in seconds to wait for a unicast response before terminating.</dd> 672b15cb3dSCy Schubert <dt><tt>--wait</tt></dt> 682b15cb3dSCy Schubert <dd>When neither <tt>-S</tt>/<tt>--step</tt> nor <tt>-s</tt>/<tt>--slew</tt> options are provided, <tt>sntp</tt> will by default terminate after the first valid response is received. This option causes <tt>sntp</tt> to instead wait for all pending queries' responses.</dd> 692b15cb3dSCy Schubert <dt><tt>--version</tt></dt> 702b15cb3dSCy Schubert <dd>Display the <tt>sntp</tt> program's version number and the date and time it was compiled.</dd> 719c2daa00SOllivier Robert</dl> 729c2daa00SOllivier Robert<h4>Return Value</h4> 732b15cb3dSCy Schubert<p>The program returns an exit status of zero for if a valid response is received and non-zero otherwise.</p> 749c2daa00SOllivier Robert<h4>Author</h4> 752b15cb3dSCy Schubert<p>This <tt>sntp</tt> was originally developed by Johannes Maximilian Kuehn. Harlan Stenn and Dave Hart modified it to query more than one server at a time. See the file <tt>ChangeLog</tt> in the distribution for details.</p> 769c2daa00SOllivier Robert<hr> 779c2daa00SOllivier Robert<script type="text/javascript" language="javascript" src="scripts/footer.txt"></script> 789c2daa00SOllivier Robert</body> 799c2daa00SOllivier Robert</html> 80
