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 33316722Sdelphij <p>This document applies to version 4.2.8p10 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 117285169Scy<pre class="example"> update-leap 118285169Scy Usage: $0 [options] [leapfile] 119285169Scy 120285169Scy Verifies and if necessary, updates leap-second definition file 121285169Scy 122285169Scy All arguments are optional: Default (or current value) shown: -s 123285169Scy Specify the URL of the master copy to download $LEAPSRC -d Specify 124285169Scy the filename on the local system $LEAPFILE -e Specify how long (in 125285169Scy days) before expiration the file is to be refreshed. Note that 126285169Scy larger values imply more frequent refreshes. "$PREFETCH" -f Specify 127285169Scy location of ntp.conf (used to make sure leapfile directive is 128285169Scy present and to default leapfile) $NTPCONF -F Force update even if 129285169Scy current file is OK and not close to expiring. -r Specify number of 130285169Scy times to retry on get failure $MAXTRIES -i Specify number of minutes 131285169Scy between retries $INTERVAL -l Use syslog for output (Implied if 132285169Scy CRONJOB is set) -L Don't use syslog for output -P Specify the syslog 133285169Scy facility for logging $LOGFAC -t Name of temporary file used in 134285169Scy validation $TMPFILE -q Only report errors to stdout -v Verbose 135285169Scy output 136285169Scy 137285169Scy The following options are not (yet) implemented in the perl version: 138285169Scy -4 Use only IPv4 -6 Use only IPv6 -c Command to restart NTP after 139285169Scy installing a new file <none> - ntpd checks file daily -p 4|6 Prefer 140285169Scy IPv4 or IPv6 (as specified) addresses, but use either -z Specify 141285169Scy path for utilities $PATHLIST -Z Only use system path 142285169Scy 143285169Scy $0 will validate the file currently on the local system 144285169Scy 145285169Scy Ordinarily, the file is found using the "leapfile" directive in 146285169Scy $NTPCONF. However, an alternate location can be specified on the 147285169Scy command line. 148285169Scy 149285169Scy If the file does not exist, is not valid, has expired, or is 150285169Scy expiring soon, a new copy will be downloaded. If the new copy 151285169Scy validates, it is installed and NTP is (optionally) restarted. 152285169Scy 153285169Scy If the current file is acceptable, no download or restart occurs. 154285169Scy 155285169Scy -c can also be used to invoke another script to perform 156285169Scy administrative functions, e.g. to copy the file to other local 157285169Scy systems. 158285169Scy 159285169Scy This can be run as a cron job. As the file is rarely updated, and 160285169Scy leap seconds are announced at least one month in advance (usually 161285169Scy longer), it need not be run more frequently than about once every 162285169Scy three weeks. 163285169Scy 164285169Scy For cron-friendly behavior, define CRONJOB=1 in the crontab. 165285169Scy 166285169Scy 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