1<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd"> 2<html> 3<!-- Created by GNU Texinfo 6.6, http://www.gnu.org/software/texinfo/ --> 4<head> 5<meta http-equiv="Content-Type" content="text/html; charset=utf-8"> 6<title>update-leap User’s Manual</title> 7 8<meta name="description" content="update-leap User’s Manual"> 9<meta name="keywords" content="update-leap User’s Manual"> 10<meta name="resource-type" content="document"> 11<meta name="distribution" content="global"> 12<meta name="Generator" content="makeinfo"> 13<link href="#Top" rel="start" title="Top"> 14<link href="dir.html#Top" rel="up" title="(dir)"> 15<style type="text/css"> 16<!-- 17a.summary-letter {text-decoration: none} 18blockquote.indentedblock {margin-right: 0em} 19div.display {margin-left: 3.2em} 20div.example {margin-left: 3.2em} 21div.lisp {margin-left: 3.2em} 22kbd {font-style: oblique} 23pre.display {font-family: inherit} 24pre.format {font-family: inherit} 25pre.menu-comment {font-family: serif} 26pre.menu-preformatted {font-family: serif} 27span.nolinebreak {white-space: nowrap} 28span.roman {font-family: initial; font-weight: normal} 29span.sansserif {font-family: sans-serif; font-weight: normal} 30ul.no-bullet {list-style: none} 31--> 32</style> 33 34 35</head> 36 37<body lang="en"> 38<h1 class="settitle" align="center">update-leap User’s Manual</h1> 39 40 41 42 43 44<span id="Top"></span><div class="header"> 45<p> 46Previous: <a href="dir.html#Top" accesskey="p" rel="prev">(dir)</a>, Up: <a href="dir.html#Top" accesskey="u" rel="up">(dir)</a> </p> 47</div> 48<h1 class="node-heading">Top</h1> 49 50<p>This document describes the use of the NTP Project’s <code>update-leap</code> program. 51</p> 52<p>This document applies to version 4.2.8p17 of <code>update-leap</code>. 53</p> 54<span id="SEC_Overview"></span> 55<h2 class="shortcontents-heading">Short Table of Contents</h2> 56 57<div class="shortcontents"> 58<li><a id="stoc-Invoking-update_002dleap" href="#toc-Invoking-update_002dleap">1 Invoking update-leap</a></li> 59 60</div> 61 62 63<table class="menu" border="0" cellspacing="0"> 64<tr><td align="left" valign="top">• update-leap Description</td><td> </td><td align="left" valign="top">Description 65</td></tr> 66<tr><td align="left" valign="top">• <a href="#update_002dleap-Invocation" accesskey="2">update-leap Invocation</a></td><td> </td><td align="left" valign="top">Invoking update-leap 67</td></tr> 68</table> 69 70<hr> 71<span id="update_002dleap-Invocation"></span><div class="header"> 72<p> 73Up: <a href="#Top" accesskey="u" rel="up">Top</a> </p> 74</div> 75<span id="Invoking-update_002dleap"></span><h3 class="section">1 Invoking update-leap</h3> 76<span id="index-update_002dleap"></span> 77<span id="index-leap_002dseconds-file-manager_002fupdater"></span> 78 79 80 81<p><code>update-leap</code> 82will validate the file currently on the local system 83and if necessary, updates leap-second definition file. 84</p> 85<p>Ordinarily, the file is found using the "leapfile" directive in 86<code>ntp.conf(5)</code>. 87However, an alternate location can be specified on the command line. 88</p> 89<p>If the file does not exist, is not valid, has expired, or is expiring soon, 90a new copy will be downloaded. If the new copy validates, it is installed and 91NTP is (optionally) restarted. 92</p> 93<p>If the current file is acceptable, no download or restart occurs. 94</p> 95<p>-c can also be used to invoke another script to perform administrative 96functions, e.g. to copy the file to other local systems. 97.PP 98This can be run as a cron job. As the file is rarely updated, and leap 99seconds are announced at least one month in advance (usually longer), it 100need not be run more frequently than about once every three weeks. 101.PP 102For cron-friendly behavior, define CRONJOB=1 in the crontab. 103.PP 104This script depends on$REQUIREDCMDS 105</p> 106<p>This section was generated by <strong>AutoGen</strong>, 107using the <code>agtexi-cmd</code> template and the option descriptions for the <code>update-leap</code> program. 108</p> 109<table class="menu" border="0" cellspacing="0"> 110<tr><td align="left" valign="top">• <a href="#update_002dleap-usage" accesskey="1">update-leap usage</a></td><td> </td><td align="left" valign="top">update-leap help/usage (<samp>--help</samp>) 111</td></tr> 112<tr><td align="left" valign="top">• <a href="#update_002dleap-source_002durl" accesskey="2">update-leap source-url</a></td><td> </td><td align="left" valign="top">source-url option (-s) 113</td></tr> 114<tr><td align="left" valign="top">• <a href="#update_002dleap-ipv4" accesskey="3">update-leap ipv4</a></td><td> </td><td align="left" valign="top">ipv4 option (-4) 115</td></tr> 116<tr><td align="left" valign="top">• <a href="#update_002dleap-destination" accesskey="4">update-leap destination</a></td><td> </td><td align="left" valign="top">destination option (-d) 117</td></tr> 118<tr><td align="left" valign="top">• <a href="#update_002dleap-expiration" accesskey="5">update-leap expiration</a></td><td> </td><td align="left" valign="top">expiration option (-e) 119</td></tr> 120<tr><td align="left" valign="top">• <a href="#update_002dleap-ntp_002dconf_002dfile" accesskey="6">update-leap ntp-conf-file</a></td><td> </td><td align="left" valign="top">ntp-conf-file option (-f) 121</td></tr> 122<tr><td align="left" valign="top">• <a href="#update_002dleap-force_002dupdate" accesskey="7">update-leap force-update</a></td><td> </td><td align="left" valign="top">force-update option (-F) 123</td></tr> 124<tr><td align="left" valign="top">• <a href="#update_002dleap-exit-status" accesskey="8">update-leap exit status</a></td><td> </td><td align="left" valign="top">exit status 125</td></tr> 126<tr><td align="left" valign="top">• <a href="#update_002dleap-Usage" accesskey="9">update-leap Usage</a></td><td> </td><td align="left" valign="top">Usage 127</td></tr> 128<tr><td align="left" valign="top">• <a href="#update_002dleap-Authors">update-leap Authors</a></td><td> </td><td align="left" valign="top">Authors 129</td></tr> 130</table> 131 132<hr> 133<span id="update_002dleap-usage"></span><div class="header"> 134<p> 135Next: <a href="#update_002dleap-source_002durl" accesskey="n" rel="next">update-leap source-url</a>, Up: <a href="#update_002dleap-Invocation" accesskey="u" rel="up">update-leap Invocation</a> </p> 136</div> 137<span id="update_002dleap-help_002fusage-_0028_002d_002dhelp_0029"></span><h4 class="subsection">1.1 update-leap help/usage (<samp>--help</samp>)</h4> 138<span id="index-update_002dleap-help"></span> 139 140<p>This is the automatically generated usage text for update-leap. 141</p> 142<p>The text printed is the same whether selected with the <code>help</code> option 143(<samp>--help</samp>) or the <code>more-help</code> option (<samp>--more-help</samp>). <code>more-help</code> will print 144the usage text by passing it through a pager program. 145<code>more-help</code> is disabled on platforms without a working 146<code>fork(2)</code> function. The <code>PAGER</code> environment variable is 147used to select the program, defaulting to <samp>more</samp>. Both will exit 148with a status code of 0. 149</p> 150<div class="example"> 151<pre class="example"> 152 153Usage: update-leap [options] 154 155Verifies and if necessary, updates leap-second definition file 156 157All arguments are optional: Default (or current value) shown: 158 -C Absolute path to CA Cert (see SSL/TLS Considerations) 159 -D Path to a CAdir (see SSL/TLS Considerations) 160 -e Specify how long (in days) before expiration the file is to be 161 refreshed. Note that larger values imply more frequent refreshes. 162 60 163 -F Force update even if current file is OK and not close to expiring. 164 -f Absolute path ntp.conf file (default /etc/ntp.conf) 165 /etc/ntp.conf 166 -h show help 167 -i Specify number of minutes between retries 168 10 169 -L Absolute path to leapfile on the local system 170 (overrides value in ntp.conf) 171 -l Specify the syslog(3) facility for logging 172 LOG_USER 173 -q Only report errors (cannot be used with -v) 174 -r Specify number of attempts to retrieve file 175 6 176 -s Send output to syslog(3) - implied if STDOUT has no tty or redirected 177 -t Send output to terminal - implied if STDOUT attached to terminal 178 -u Specify the URL of the master copy to download 179 https://www.ietf.org/timezones/data/leap-seconds.list 180 -v Verbose - show debug messages (cannot be used with -q) 181 182The following options are not (yet) implemented in the perl version: 183 -4 Use only IPv4 184 -6 Use only IPv6 185 -c Command to restart NTP after installing a new file 186 <none> - ntpd checks file daily 187 -p 4|6 188 Prefer IPv4 or IPv6 (as specified) addresses, but use either 189 190update-leap will validate the file currently on the local system. 191 192Ordinarily, the leapfile is found using the 'leapfile' directive in 193/etc/ntp.conf. However, an alternate location can be specified on the 194command line with the -L flag. 195 196If the leapfile does not exist, is not valid, has expired, or is 197expiring soon, a new copy will be downloaded. If the new copy is 198valid, it is installed. 199 200If the current file is acceptable, no download or restart occurs. 201 202This can be run as a cron job. As the file is rarely updated, and 203leap seconds are announced at least one month in advance (usually 204longer), it need not be run more frequently than about once every 205three weeks. 206 207SSL/TLS Considerations 208----------------------- 209The perl modules can usually locate the CA certificate used to verify 210the peer's identity. 211 212On BSDs, the default is typically the file /etc/ssl/certs.pem. On 213Linux, the location is typically a path to a CAdir - a directory of 214symlinks named according to a hash of the certificates' subject names. 215 216The -C or -D options are available to pass in a location if no CA cert 217is found in the default location. 218 219External Dependencies 220--------------------- 221The following perl modules are required: 222HTTP::Tiny - version >= 0.056 223IO::Socket::SSL - version >= 1.56 224NET::SSLeay - version >= 1.49 225 226Version: 1.004 227</pre></div> 228 229<hr> 230<span id="update_002dleap-source_002durl"></span><div class="header"> 231<p> 232Next: <a href="#update_002dleap-ipv4" accesskey="n" rel="next">update-leap ipv4</a>, Previous: <a href="#update_002dleap-usage" accesskey="p" rel="prev">update-leap usage</a>, Up: <a href="#update_002dleap-Invocation" accesskey="u" rel="up">update-leap Invocation</a> </p> 233</div> 234<span id="source_002durl-option-_0028_002ds_0029"></span><h4 class="subsection">1.2 source-url option (-s)</h4> 235<span id="index-update_002dleap_002dsource_002durl"></span> 236 237<p>This is the “the url of the master copy of the leapseconds file” option. 238This option takes a string argument. 239Specify the URL of the master copy to download 240$LEAPSRC 241</p><hr> 242<span id="update_002dleap-ipv4"></span><div class="header"> 243<p> 244Next: <a href="#update_002dleap-destination" accesskey="n" rel="next">update-leap destination</a>, Previous: <a href="#update_002dleap-source_002durl" accesskey="p" rel="prev">update-leap source-url</a>, Up: <a href="#update_002dleap-Invocation" accesskey="u" rel="up">update-leap Invocation</a> </p> 245</div> 246<span id="ipv4-option-_0028_002d4_0029"></span><h4 class="subsection">1.3 ipv4 option (-4)</h4> 247<span id="index-update_002dleap_002dipv4"></span> 248 249<p>This is the “use only ipv4 addresses for dns name resolution” option. 250</p> 251<p>This option has some usage constraints. It: 252</p><ul> 253<li> must not appear in combination with any of the following options: 254ipv6. 255</li></ul> 256 257<p>Force DNS resolution of following host names on the command line 258 to the IPv4 namespace. 259 _EndOfDoc_; 260; 261</p> 262<p>flag = 263 name = ipv6; 264 flags-cant = ipv4, prefer; 265 value = 6; 266 descrip = "Use only IPv6 addresses for DNS name resolution"; 267 doc = <<- _EndOfDoc_ 268 Force DNS resolution of following host names on the command line 269 to the IPv6 namespace. 270 _EndOfDoc_; 271; 272</p> 273<p>flag = 274 name = prefer; 275 flags-cant = ipv4, ipv6; 276 value = p; 277 arg-type = keyword; 278 keyword = 4, 6; 279 descrip = ’Prefer IPv4 or IPv6 (as specified) addresses, but use either’; 280 doc = <<- _EndOfDoc_ 281Prefer IPv4 or IPv6 (as specified) addresses, but use either. 282</p><hr> 283<span id="update_002dleap-destination"></span><div class="header"> 284<p> 285Next: <a href="#update_002dleap-expiration" accesskey="n" rel="next">update-leap expiration</a>, Previous: <a href="#update_002dleap-ipv4" accesskey="p" rel="prev">update-leap ipv4</a>, Up: <a href="#update_002dleap-Invocation" accesskey="u" rel="up">update-leap Invocation</a> </p> 286</div> 287<span id="destination-option-_0028_002dd_0029"></span><h4 class="subsection">1.4 destination option (-d)</h4> 288<span id="index-update_002dleap_002ddestination"></span> 289 290<p>This is the “filename on the local system” option. 291This option takes a string argument <samp>float</samp>. 292The name to use to store the leapfile on the local system. 293$LEAPFILE 294</p><hr> 295<span id="update_002dleap-expiration"></span><div class="header"> 296<p> 297Next: <a href="#update_002dleap-ntp_002dconf_002dfile" accesskey="n" rel="next">update-leap ntp-conf-file</a>, Previous: <a href="#update_002dleap-destination" accesskey="p" rel="prev">update-leap destination</a>, Up: <a href="#update_002dleap-Invocation" accesskey="u" rel="up">update-leap Invocation</a> </p> 298</div> 299<span id="expiration-option-_0028_002de_0029"></span><h4 class="subsection">1.5 expiration option (-e)</h4> 300<span id="index-update_002dleap_002dexpiration"></span> 301 302<p>This is the “refresh the leapfile this long before it expires” option. 303This option takes a string argument. 304Specify how long before expiration the file is to be refreshed 305Units are required, e.g. "-e 60 days" Note that larger values 306imply more frequent refreshes. 307"$PREFETCH" 308</p><hr> 309<span id="update_002dleap-ntp_002dconf_002dfile"></span><div class="header"> 310<p> 311Next: <a href="#update_002dleap-force_002dupdate" accesskey="n" rel="next">update-leap force-update</a>, Previous: <a href="#update_002dleap-expiration" accesskey="p" rel="prev">update-leap expiration</a>, Up: <a href="#update_002dleap-Invocation" accesskey="u" rel="up">update-leap Invocation</a> </p> 312</div> 313<span id="ntp_002dconf_002dfile-option-_0028_002df_0029"></span><h4 class="subsection">1.6 ntp-conf-file option (-f)</h4> 314<span id="index-update_002dleap_002dntp_002dconf_002dfile"></span> 315 316<p>This is the “location of the ntp.conf file” option. 317This option takes a string argument. 318Specify location of ntp.conf (used to make sure leapfile directive is 319present and to default leapfile) 320/etc/ntp.conf 321</p><hr> 322<span id="update_002dleap-force_002dupdate"></span><div class="header"> 323<p> 324Next: <a href="#update_002dleap-exit-status" accesskey="n" rel="next">update-leap exit status</a>, Previous: <a href="#update_002dleap-ntp_002dconf_002dfile" accesskey="p" rel="prev">update-leap ntp-conf-file</a>, Up: <a href="#update_002dleap-Invocation" accesskey="u" rel="up">update-leap Invocation</a> </p> 325</div> 326<span id="force_002dupdate-option-_0028_002dF_0029"></span><h4 class="subsection">1.7 force-update option (-F)</h4> 327<span id="index-update_002dleap_002dforce_002dupdate"></span> 328 329<p>This is the “force update of the leapfile” option. 330Force update even if current file is OK and not close to expiring. 331</p><hr> 332<span id="update_002dleap-exit-status"></span><div class="header"> 333<p> 334Next: <a href="#update_002dleap-Usage" accesskey="n" rel="next">update-leap Usage</a>, Previous: <a href="#update_002dleap-force_002dupdate" accesskey="p" rel="prev">update-leap force-update</a>, Up: <a href="#update_002dleap-Invocation" accesskey="u" rel="up">update-leap Invocation</a> </p> 335</div> 336<span id="update_002dleap-exit-status-1"></span><h4 class="subsection">1.8 update-leap exit status</h4> 337 338<p>One of the following exit values will be returned: 339</p><dl compact="compact"> 340<dt>‘<samp>0 (EXIT_SUCCESS)</samp>’</dt> 341<dd><p>Successful program execution. 342</p></dd> 343<dt>‘<samp>1 (EXIT_FAILURE)</samp>’</dt> 344<dd><p>The operation failed or the command syntax was not valid. 345</p></dd> 346</dl> 347<hr> 348<span id="update_002dleap-Usage"></span><div class="header"> 349<p> 350Next: <a href="#update_002dleap-Authors" accesskey="n" rel="next">update-leap Authors</a>, Previous: <a href="#update_002dleap-exit-status" accesskey="p" rel="prev">update-leap exit status</a>, Up: <a href="#update_002dleap-Invocation" accesskey="u" rel="up">update-leap Invocation</a> </p> 351</div> 352<span id="update_002dleap-Usage-1"></span><h4 class="subsection">1.9 update-leap Usage</h4> 353<hr> 354<span id="update_002dleap-Authors"></span><div class="header"> 355<p> 356Previous: <a href="#update_002dleap-Usage" accesskey="p" rel="prev">update-leap Usage</a>, Up: <a href="#update_002dleap-Invocation" accesskey="u" rel="up">update-leap Invocation</a> </p> 357</div> 358<span id="update_002dleap-Authors-1"></span><h4 class="subsection">1.10 update-leap Authors</h4> 359<hr> 360 361 362 363</body> 364</html> 365