1281348Scy<html lang="en"> 2281348Scy<head> 3281348Scy<title>update-leap User's Manual</title> 4281348Scy<meta http-equiv="Content-Type" content="text/html"> 5281348Scy<meta name="description" content="update-leap User's Manual"> 6281348Scy<meta name="generator" content="makeinfo 4.7"> 7281348Scy<link title="Top" rel="top" href="#Top"> 8281348Scy<link href="http://www.gnu.org/software/texinfo/" rel="generator-home" title="Texinfo Homepage"> 9281348Scy<meta http-equiv="Content-Style-Type" content="text/css"> 10281348Scy<style type="text/css"><!-- 11281348Scy pre.display { font-family:inherit } 12281348Scy pre.format { font-family:inherit } 13281348Scy pre.smalldisplay { font-family:inherit; font-size:smaller } 14281348Scy pre.smallformat { font-family:inherit; font-size:smaller } 15281348Scy pre.smallexample { font-size:smaller } 16281348Scy pre.smalllisp { font-size:smaller } 17281348Scy span.sc { font-variant:small-caps } 18281348Scy span.roman { font-family: serif; font-weight: normal; } 19281348Scy--></style> 20281348Scy</head> 21281348Scy<body> 22281348Scy<h1 class="settitle">update-leap User's Manual</h1> 23281348Scy<div class="node"> 24281348Scy<p><hr> 25281348Scy<a name="Top"></a>Next: <a rel="next" accesskey="n" href="#update_002dleap-Description">update-leap Description</a>, 26281348ScyPrevious: <a rel="previous" accesskey="p" href="#dir">(dir)</a>, 27281348ScyUp: <a rel="up" accesskey="u" href="#dir">(dir)</a> 28281348Scy<br> 29281348Scy</div> 30281348Scy 31281348Scy <p>This document describes the use of the NTP Project's <code>update-leap</code> program. 32281348Scy 33310419Sdelphij <p>This document applies to version 4.2.8p9 of <code>update-leap</code>. 34281348Scy 35281348Scy<div class="shortcontents"> 36281348Scy<h2>Short Contents</h2> 37281348Scy<ul> 38281348Scy</ul> 39281348Scy</div> 40281348Scy 41281348Scy<ul class="menu"> 42281348Scy<li><a accesskey="1" href="#update_002dleap-Description">update-leap Description</a>: Description 43281348Scy<li><a accesskey="2" href="#update_002dleap-Invocation">update-leap Invocation</a>: Invoking update-leap 44281348Scy</ul> 45281348Scy 46281348Scy<div class="node"> 47281348Scy<p><hr> 48281348Scy<a name="update_002dleap-Invocation"></a> 49281348Scy<br> 50281348Scy</div> 51281348Scy 52281348Scy<h3 class="section">0.1 Invoking update-leap</h3> 53281348Scy 54281348Scy<p><a name="index-update_002dleap-1"></a><a name="index-leap_002dseconds-file-manager_002fupdater-2"></a> 55281348Scy 56281348Scy <p><code>update-leap</code> 57281348Scywill validate the file currently on the local system 58281348Scyand if necessary, updates leap-second definition file. 59281348Scy 60281348Scy <p>Ordinarily, the file is found using the "leapfile" directive in 61281348Scy<code>ntp.conf(5)</code>. 62281348ScyHowever, an alternate location can be specified on the command line. 63281348Scy 64281348Scy <p>If the file does not exist, is not valid, has expired, or is expiring soon, 65281348Scya new copy will be downloaded. If the new copy validates, it is installed and 66281348ScyNTP is (optionally) restarted. 67281348Scy 68281348Scy <p>If the current file is acceptable, no download or restart occurs. 69281348Scy 70281348Scy <p>-c can also be used to invoke another script to perform administrative 71281348Scyfunctions, e.g. to copy the file to other local systems. 72281348Scy.PP 73281348ScyThis can be run as a cron job. As the file is rarely updated, and leap 74281348Scyseconds are announced at least one month in advance (usually longer), it 75281348Scyneed not be run more frequently than about once every three weeks. 76281348Scy.PP 77281348ScyFor cron-friendly behavior, define CRONJOB=1 in the crontab. 78281348Scy.PP 79281348ScyThis script depends on$REQUIREDCMDS 80281348Scy 81281348Scy <p>This section was generated by <strong>AutoGen</strong>, 82281348Scyusing the <code>agtexi-cmd</code> template and the option descriptions for the <code>update-leap</code> program. 83281348Scy 84281348Scy<ul class="menu"> 85281348Scy<li><a accesskey="1" href="#update_002dleap-usage">update-leap usage</a>: update-leap help/usage (<span class="option">--help</span>) 86281348Scy<li><a accesskey="2" href="#update_002dleap-source_002durl">update-leap source-url</a>: source-url option (-s) 87281348Scy<li><a accesskey="3" href="#update_002dleap-ipv4">update-leap ipv4</a>: ipv4 option (-4) 88281348Scy<li><a accesskey="4" href="#update_002dleap-destination">update-leap destination</a>: destination option (-d) 89281348Scy<li><a accesskey="5" href="#update_002dleap-expiration">update-leap expiration</a>: expiration option (-e) 90281348Scy<li><a accesskey="6" href="#update_002dleap-ntp_002dconf_002dfile">update-leap ntp-conf-file</a>: ntp-conf-file option (-f) 91281348Scy<li><a accesskey="7" href="#update_002dleap-force_002dupdate">update-leap force-update</a>: force-update option (-F) 92281348Scy<li><a accesskey="8" href="#update_002dleap-exit-status">update-leap exit status</a>: exit status 93281348Scy<li><a accesskey="9" href="#update_002dleap-Usage">update-leap Usage</a>: Usage 94281348Scy<li><a href="#update_002dleap-Authors">update-leap Authors</a>: Authors 95281348Scy</ul> 96281348Scy 97281348Scy<div class="node"> 98281348Scy<p><hr> 99281348Scy<a name="update_002dleap-usage"></a>Next: <a rel="next" accesskey="n" href="#update_002dleap-source_002durl">update-leap source-url</a>, 100281348ScyUp: <a rel="up" accesskey="u" href="#update_002dleap-Invocation">update-leap Invocation</a> 101281348Scy<br> 102281348Scy</div> 103281348Scy 104281348Scy<h4 class="subsection">0.1.1 update-leap help/usage (<span class="option">--help</span>)</h4> 105281348Scy 106281348Scy<p><a name="index-update_002dleap-help-3"></a> 107281348ScyThis is the automatically generated usage text for update-leap. 108281348Scy 109281348Scy <p>The text printed is the same whether selected with the <code>help</code> option 110281348Scy(<span class="option">--help</span>) or the <code>more-help</code> option (<span class="option">--more-help</span>). <code>more-help</code> will print 111281348Scythe usage text by passing it through a pager program. 112281348Scy<code>more-help</code> is disabled on platforms without a working 113281348Scy<code>fork(2)</code> function. The <code>PAGER</code> environment variable is 114281348Scyused to select the program, defaulting to <span class="file">more</span>. Both will exit 115281348Scywith a status code of 0. 116281348Scy 117290000Sglebius<pre class="example"> update-leap 118290000Sglebius Usage: $0 [options] [leapfile] 119290000Sglebius 120290000Sglebius Verifies and if necessary, updates leap-second definition file 121290000Sglebius 122290000Sglebius All arguments are optional: Default (or current value) shown: -s 123290000Sglebius Specify the URL of the master copy to download $LEAPSRC -d Specify 124290000Sglebius the filename on the local system $LEAPFILE -e Specify how long (in 125290000Sglebius days) before expiration the file is to be refreshed. Note that 126290000Sglebius larger values imply more frequent refreshes. "$PREFETCH" -f Specify 127290000Sglebius location of ntp.conf (used to make sure leapfile directive is 128290000Sglebius present and to default leapfile) $NTPCONF -F Force update even if 129290000Sglebius current file is OK and not close to expiring. -r Specify number of 130290000Sglebius times to retry on get failure $MAXTRIES -i Specify number of minutes 131290000Sglebius between retries $INTERVAL -l Use syslog for output (Implied if 132290000Sglebius CRONJOB is set) -L Don't use syslog for output -P Specify the syslog 133290000Sglebius facility for logging $LOGFAC -t Name of temporary file used in 134290000Sglebius validation $TMPFILE -q Only report errors to stdout -v Verbose 135290000Sglebius output 136290000Sglebius 137290000Sglebius The following options are not (yet) implemented in the perl version: 138290000Sglebius -4 Use only IPv4 -6 Use only IPv6 -c Command to restart NTP after 139290000Sglebius installing a new file <none> - ntpd checks file daily -p 4|6 Prefer 140290000Sglebius IPv4 or IPv6 (as specified) addresses, but use either -z Specify 141290000Sglebius path for utilities $PATHLIST -Z Only use system path 142290000Sglebius 143290000Sglebius $0 will validate the file currently on the local system 144290000Sglebius 145290000Sglebius Ordinarily, the file is found using the "leapfile" directive in 146290000Sglebius $NTPCONF. However, an alternate location can be specified on the 147290000Sglebius command line. 148290000Sglebius 149290000Sglebius If the file does not exist, is not valid, has expired, or is 150290000Sglebius expiring soon, a new copy will be downloaded. If the new copy 151290000Sglebius validates, it is installed and NTP is (optionally) restarted. 152290000Sglebius 153290000Sglebius If the current file is acceptable, no download or restart occurs. 154290000Sglebius 155290000Sglebius -c can also be used to invoke another script to perform 156290000Sglebius administrative functions, e.g. to copy the file to other local 157290000Sglebius systems. 158290000Sglebius 159290000Sglebius This can be run as a cron job. As the file is rarely updated, and 160290000Sglebius leap seconds are announced at least one month in advance (usually 161290000Sglebius longer), it need not be run more frequently than about once every 162290000Sglebius three weeks. 163290000Sglebius 164290000Sglebius For cron-friendly behavior, define CRONJOB=1 in the crontab. 165290000Sglebius 166290000Sglebius Version $VERSION 167281348Scy</pre> 168281348Scy <div class="node"> 169281348Scy<p><hr> 170281348Scy<a name="update_002dleap-source_002durl"></a>Next: <a rel="next" accesskey="n" href="#update_002dleap-ipv4">update-leap ipv4</a>, 171281348ScyPrevious: <a rel="previous" accesskey="p" href="#update_002dleap-usage">update-leap usage</a>, 172281348ScyUp: <a rel="up" accesskey="u" href="#update_002dleap-Invocation">update-leap Invocation</a> 173281348Scy<br> 174281348Scy</div> 175281348Scy 176281348Scy<h4 class="subsection">0.1.2 source-url option (-s)</h4> 177281348Scy 178281348Scy<p><a name="index-update_002dleap_002dsource_002durl-4"></a> 179281348ScyThis is the “the url of the master copy of the leapseconds file” option. 180281348ScyThis option takes a string argument. 181281348ScySpecify the URL of the master copy to download 182281348Scy$LEAPSRC 183281348Scy<div class="node"> 184281348Scy<p><hr> 185281348Scy<a name="update_002dleap-ipv4"></a>Next: <a rel="next" accesskey="n" href="#update_002dleap-destination">update-leap destination</a>, 186281348ScyPrevious: <a rel="previous" accesskey="p" href="#update_002dleap-source_002durl">update-leap source-url</a>, 187281348ScyUp: <a rel="up" accesskey="u" href="#update_002dleap-Invocation">update-leap Invocation</a> 188281348Scy<br> 189281348Scy</div> 190281348Scy 191281348Scy<h4 class="subsection">0.1.3 ipv4 option (-4)</h4> 192281348Scy 193281348Scy<p><a name="index-update_002dleap_002dipv4-5"></a> 194281348ScyThis is the “use only ipv4 addresses for dns name resolution” option. 195281348Scy 196281348Scy<p class="noindent">This option has some usage constraints. It: 197281348Scy <ul> 198281348Scy<li>must not appear in combination with any of the following options: 199281348Scyipv6. 200281348Scy</ul> 201281348Scy 202281348Scy <p>Force DNS resolution of following host names on the command line 203281348Scy to the IPv4 namespace. 204281348Scy _EndOfDoc_; 205281348Scy; 206281348Scy 207281348Scy <p>flag = 208281348Scy name = ipv6; 209281348Scy flags-cant = ipv4, prefer; 210281348Scy value = 6; 211281348Scy descrip = "Use only IPv6 addresses for DNS name resolution"; 212281348Scy doc = <<- _EndOfDoc_ 213281348Scy Force DNS resolution of following host names on the command line 214281348Scy to the IPv6 namespace. 215281348Scy _EndOfDoc_; 216281348Scy; 217281348Scy 218281348Scy <p>flag = 219281348Scy name = prefer; 220281348Scy flags-cant = ipv4, ipv6; 221281348Scy value = p; 222281348Scy arg-type = keyword; 223281348Scy keyword = 4, 6; 224281348Scy descrip = 'Prefer IPv4 or IPv6 (as specified) addresses, but use either'; 225281348Scy doc = <<- _EndOfDoc_ 226281348ScyPrefer IPv4 or IPv6 (as specified) addresses, but use either. 227281348Scy<div class="node"> 228281348Scy<p><hr> 229281348Scy<a name="update_002dleap-destination"></a>Next: <a rel="next" accesskey="n" href="#update_002dleap-expiration">update-leap expiration</a>, 230281348ScyPrevious: <a rel="previous" accesskey="p" href="#update_002dleap-ipv4">update-leap ipv4</a>, 231281348ScyUp: <a rel="up" accesskey="u" href="#update_002dleap-Invocation">update-leap Invocation</a> 232281348Scy<br> 233281348Scy</div> 234281348Scy 235281348Scy<h4 class="subsection">0.1.4 destination option (-d)</h4> 236281348Scy 237281348Scy<p><a name="index-update_002dleap_002ddestination-6"></a> 238281348ScyThis is the “filename on the local system” option. 239281348ScyThis option takes a string argument <span class="file">float</span>. 240281348ScyThe name to use to store the leapfile on the local system. 241281348Scy$LEAPFILE 242281348Scy<div class="node"> 243281348Scy<p><hr> 244281348Scy<a name="update_002dleap-expiration"></a>Next: <a rel="next" accesskey="n" href="#update_002dleap-ntp_002dconf_002dfile">update-leap ntp-conf-file</a>, 245281348ScyPrevious: <a rel="previous" accesskey="p" href="#update_002dleap-destination">update-leap destination</a>, 246281348ScyUp: <a rel="up" accesskey="u" href="#update_002dleap-Invocation">update-leap Invocation</a> 247281348Scy<br> 248281348Scy</div> 249281348Scy 250281348Scy<h4 class="subsection">0.1.5 expiration option (-e)</h4> 251281348Scy 252281348Scy<p><a name="index-update_002dleap_002dexpiration-7"></a> 253281348ScyThis is the “refresh the leapfile this long before it expires” option. 254281348ScyThis option takes a string argument. 255281348ScySpecify how long before expiration the file is to be refreshed 256281348ScyUnits are required, e.g. "-e 60 days" Note that larger values 257281348Scyimply more frequent refreshes. 258281348Scy"$PREFETCH" 259281348Scy<div class="node"> 260281348Scy<p><hr> 261281348Scy<a name="update_002dleap-ntp_002dconf_002dfile"></a>Next: <a rel="next" accesskey="n" href="#update_002dleap-force_002dupdate">update-leap force-update</a>, 262281348ScyPrevious: <a rel="previous" accesskey="p" href="#update_002dleap-expiration">update-leap expiration</a>, 263281348ScyUp: <a rel="up" accesskey="u" href="#update_002dleap-Invocation">update-leap Invocation</a> 264281348Scy<br> 265281348Scy</div> 266281348Scy 267281348Scy<h4 class="subsection">0.1.6 ntp-conf-file option (-f)</h4> 268281348Scy 269281348Scy<p><a name="index-update_002dleap_002dntp_002dconf_002dfile-8"></a> 270281348ScyThis is the “location of the ntp.conf file” option. 271281348ScyThis option takes a string argument. 272281348ScySpecify location of ntp.conf (used to make sure leapfile directive is 273281348Scypresent and to default leapfile) 274281348Scy/etc/ntp.conf 275281348Scy<div class="node"> 276281348Scy<p><hr> 277281348Scy<a name="update_002dleap-force_002dupdate"></a>Next: <a rel="next" accesskey="n" href="#update_002dleap-exit-status">update-leap exit status</a>, 278281348ScyPrevious: <a rel="previous" accesskey="p" href="#update_002dleap-ntp_002dconf_002dfile">update-leap ntp-conf-file</a>, 279281348ScyUp: <a rel="up" accesskey="u" href="#update_002dleap-Invocation">update-leap Invocation</a> 280281348Scy<br> 281281348Scy</div> 282281348Scy 283281348Scy<h4 class="subsection">0.1.7 force-update option (-F)</h4> 284281348Scy 285281348Scy<p><a name="index-update_002dleap_002dforce_002dupdate-9"></a> 286281348ScyThis is the “force update of the leapfile” option. 287281348ScyForce update even if current file is OK and not close to expiring. 288281348Scy<div class="node"> 289281348Scy<p><hr> 290281348Scy<a name="update_002dleap-exit-status"></a>Next: <a rel="next" accesskey="n" href="#update_002dleap-Usage">update-leap Usage</a>, 291281348ScyPrevious: <a rel="previous" accesskey="p" href="#update_002dleap-force_002dupdate">update-leap force-update</a>, 292281348ScyUp: <a rel="up" accesskey="u" href="#update_002dleap-Invocation">update-leap Invocation</a> 293281348Scy<br> 294281348Scy</div> 295281348Scy 296281348Scy<h4 class="subsection">0.1.8 update-leap exit status</h4> 297281348Scy 298281348Scy<p>One of the following exit values will be returned: 299281348Scy <dl> 300281348Scy<dt><span class="samp">0 (EXIT_SUCCESS)</span><dd>Successful program execution. 301281348Scy<br><dt><span class="samp">1 (EXIT_FAILURE)</span><dd>The operation failed or the command syntax was not valid. 302281348Scy</dl> 303281348Scy <div class="node"> 304281348Scy<p><hr> 305281348Scy<a name="update_002dleap-Usage"></a>Next: <a rel="next" accesskey="n" href="#update_002dleap-Authors">update-leap Authors</a>, 306281348ScyPrevious: <a rel="previous" accesskey="p" href="#update_002dleap-exit-status">update-leap exit status</a>, 307281348ScyUp: <a rel="up" accesskey="u" href="#update_002dleap-Invocation">update-leap Invocation</a> 308281348Scy<br> 309281348Scy</div> 310281348Scy 311281348Scy<h4 class="subsection">0.1.9 update-leap Usage</h4> 312281348Scy 313281348Scy<div class="node"> 314281348Scy<p><hr> 315281348Scy<a name="update_002dleap-Authors"></a>Previous: <a rel="previous" accesskey="p" href="#update_002dleap-Usage">update-leap Usage</a>, 316281348ScyUp: <a rel="up" accesskey="u" href="#update_002dleap-Invocation">update-leap Invocation</a> 317281348Scy<br> 318281348Scy</div> 319281348Scy 320281348Scy<h4 class="subsection">0.1.10 update-leap Authors</h4> 321281348Scy 322281348Scy</body></html> 323281348Scy 324