contrib/ntp/scripts/update-leap/update-leap.html

   1 <html lang="en">
   2 <head>
   3 <title>update-leap User's Manual</title>
   4 <meta http-equiv="Content-Type" content="text/html">
   5 <meta name="description" content="update-leap 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">update-leap User's Manual</h1>
  23 <div class="node">
  24 <p><hr>
  25 <a name="Top"></a>Next:&nbsp;<a rel="next" accesskey="n" href="#update_002dleap-Description">update-leap Description</a>,
  26 Previous:&nbsp;<a rel="previous" accesskey="p" href="#dir">(dir)</a>,
  27 Up:&nbsp;<a rel="up" accesskey="u" href="#dir">(dir)</a>
  28 <br>
  29 </div>
  30
  31   <p>This document describes the use of the NTP Project's <code>update-leap</code> program.
  32
  33   <p>This document applies to version 4.2.8p7 of <code>update-leap</code>.
  34
  35 <div class="shortcontents">
  36 <h2>Short Contents</h2>
  37 <ul>
  38 </ul>
  39 </div>
  40
  41 <ul class="menu">
  42 <li><a accesskey="1" href="#update_002dleap-Description">update-leap Description</a>:             Description
  43 <li><a accesskey="2" href="#update_002dleap-Invocation">update-leap Invocation</a>:             Invoking update-leap
  44 </ul>
  45
  46 <div class="node">
  47 <p><hr>
  48 <a name="update_002dleap-Invocation"></a>
  49 <br>
  50 </div>
  51
  52 <h3 class="section">0.1 Invoking update-leap</h3>
  53
  54 <p><a name="index-update_002dleap-1"></a><a name="index-leap_002dseconds-file-manager_002fupdater-2"></a>
  55
  56   <p><code>update-leap</code>
  57 will validate the file currently on the local system
  58 and if necessary, updates leap-second definition file.
  59
  60   <p>Ordinarily, the file is found using the "leapfile" directive in
  61 <code>ntp.conf(5)</code>.
  62 However, an alternate location can be specified on the command line.
  63
  64   <p>If the file does not exist, is not valid, has expired, or is expiring soon,
  65 a new copy will be downloaded.  If the new copy validates, it is installed and
  66 NTP is (optionally) restarted.
  67
  68   <p>If the current file is acceptable, no download or restart occurs.
  69
  70   <p>-c can also be used to invoke another script to perform administrative
  71 functions, e.g. to copy the file to other local systems.
  72 .PP
  73 This can be run as a cron job.  As the file is rarely updated, and leap
  74 seconds are announced at least one month in advance (usually longer), it
  75 need not be run more frequently than about once every three weeks.
  76 .PP
  77 For cron-friendly behavior, define CRONJOB=1 in the crontab.
  78 .PP
  79 This script depends on$REQUIREDCMDS
  80
  81   <p>This section was generated by <strong>AutoGen</strong>,
  82 using the <code>agtexi-cmd</code> template and the option descriptions for the <code>update-leap</code> program.
  83
  84 <ul class="menu">
  85 <li><a accesskey="1" href="#update_002dleap-usage">update-leap usage</a>:                   update-leap help/usage (<span class="option">--help</span>)
  86 <li><a accesskey="2" href="#update_002dleap-source_002durl">update-leap source-url</a>:              source-url option (-s)
  87 <li><a accesskey="3" href="#update_002dleap-ipv4">update-leap ipv4</a>:                    ipv4 option (-4)
  88 <li><a accesskey="4" href="#update_002dleap-destination">update-leap destination</a>:             destination option (-d)
  89 <li><a accesskey="5" href="#update_002dleap-expiration">update-leap expiration</a>:              expiration option (-e)
  90 <li><a accesskey="6" href="#update_002dleap-ntp_002dconf_002dfile">update-leap ntp-conf-file</a>:           ntp-conf-file option (-f)
  91 <li><a accesskey="7" href="#update_002dleap-force_002dupdate">update-leap force-update</a>:            force-update option (-F)
  92 <li><a accesskey="8" href="#update_002dleap-exit-status">update-leap exit status</a>:             exit status
  93 <li><a accesskey="9" href="#update_002dleap-Usage">update-leap Usage</a>:                   Usage
  94 <li><a href="#update_002dleap-Authors">update-leap Authors</a>:                 Authors
  95 </ul>
  96
  97 <div class="node">
  98 <p><hr>
  99 <a name="update_002dleap-usage"></a>Next:&nbsp;<a rel="next" accesskey="n" href="#update_002dleap-source_002durl">update-leap source-url</a>,
 100 Up:&nbsp;<a rel="up" accesskey="u" href="#update_002dleap-Invocation">update-leap Invocation</a>
 101 <br>
 102 </div>
 103
 104 <h4 class="subsection">0.1.1 update-leap help/usage (<span class="option">--help</span>)</h4>
 105
 106 <p><a name="index-update_002dleap-help-3"></a>
 107 This is the automatically generated usage text for update-leap.
 108
 109   <p>The text printed is the same whether selected with the <code>help</code> option
 110 (<span class="option">--help</span>) or the <code>more-help</code> option (<span class="option">--more-help</span>).  <code>more-help</code> will print
 111 the usage text by passing it through a pager program.
 112 <code>more-help</code> is disabled on platforms without a working
 113 <code>fork(2)</code> function.  The <code>PAGER</code> environment variable is
 114 used to select the program, defaulting to <span class="file">more</span>.  Both will exit
 115 with a status code of 0.
 116
 117 <pre class="example">    update-leap
 118         Usage: $0 [options] [leapfile]
 119
 120         Verifies and if necessary, updates leap-second definition file
 121
 122         All arguments are optional: Default (or current value) shown: -s
 123         Specify the URL of the master copy to download $LEAPSRC -d Specify
 124         the filename on the local system $LEAPFILE -e Specify how long (in
 125         days) before expiration the file is to be refreshed. Note that
 126         larger values imply more frequent refreshes. "$PREFETCH" -f Specify
 127         location of ntp.conf (used to make sure leapfile directive is
 128         present and to default leapfile) $NTPCONF -F Force update even if
 129         current file is OK and not close to expiring. -r Specify number of
 130         times to retry on get failure $MAXTRIES -i Specify number of minutes
 131         between retries $INTERVAL -l Use syslog for output (Implied if
 132         CRONJOB is set) -L Don't use syslog for output -P Specify the syslog
 133         facility for logging $LOGFAC -t Name of temporary file used in
 134         validation $TMPFILE -q Only report errors to stdout -v Verbose
 135         output
 136
 137         The following options are not (yet) implemented in the perl version:
 138         -4 Use only IPv4 -6 Use only IPv6 -c Command to restart NTP after
 139         installing a new file &lt;none&gt; - ntpd checks file daily -p 4|6 Prefer
 140         IPv4 or IPv6 (as specified) addresses, but use either -z Specify
 141         path for utilities $PATHLIST -Z Only use system path
 142
 143         $0 will validate the file currently on the local system
 144
 145         Ordinarily, the file is found using the "leapfile" directive in
 146         $NTPCONF. However, an alternate location can be specified on the
 147         command line.
 148
 149         If the file does not exist, is not valid, has expired, or is
 150         expiring soon, a new copy will be downloaded. If the new copy
 151         validates, it is installed and NTP is (optionally) restarted.
 152
 153         If the current file is acceptable, no download or restart occurs.
 154
 155         -c can also be used to invoke another script to perform
 156         administrative functions, e.g. to copy the file to other local
 157         systems.
 158
 159         This can be run as a cron job. As the file is rarely updated, and
 160         leap seconds are announced at least one month in advance (usually
 161         longer), it need not be run more frequently than about once every
 162         three weeks.
 163
 164         For cron-friendly behavior, define CRONJOB=1 in the crontab.
 165
 166         Version $VERSION
 167 </pre>
 168   <div class="node">
 169 <p><hr>
 170 <a name="update_002dleap-source_002durl"></a>Next:&nbsp;<a rel="next" accesskey="n" href="#update_002dleap-ipv4">update-leap ipv4</a>,
 171 Previous:&nbsp;<a rel="previous" accesskey="p" href="#update_002dleap-usage">update-leap usage</a>,
 172 Up:&nbsp;<a rel="up" accesskey="u" href="#update_002dleap-Invocation">update-leap Invocation</a>
 173 <br>
 174 </div>
 175
 176 <h4 class="subsection">0.1.2 source-url option (-s)</h4>
 177
 178 <p><a name="index-update_002dleap_002dsource_002durl-4"></a>
 179 This is the &ldquo;the url of the master copy of the leapseconds file&rdquo; option.
 180 This option takes a string argument.
 181 Specify the URL of the master copy to download
 182 $LEAPSRC
 183 <div class="node">
 184 <p><hr>
 185 <a name="update_002dleap-ipv4"></a>Next:&nbsp;<a rel="next" accesskey="n" href="#update_002dleap-destination">update-leap destination</a>,
 186 Previous:&nbsp;<a rel="previous" accesskey="p" href="#update_002dleap-source_002durl">update-leap source-url</a>,
 187 Up:&nbsp;<a rel="up" accesskey="u" href="#update_002dleap-Invocation">update-leap Invocation</a>
 188 <br>
 189 </div>
 190
 191 <h4 class="subsection">0.1.3 ipv4 option (-4)</h4>
 192
 193 <p><a name="index-update_002dleap_002dipv4-5"></a>
 194 This is the &ldquo;use only ipv4 addresses for dns name resolution&rdquo; option.
 195
 196 <p class="noindent">This option has some usage constraints.  It:
 197      <ul>
 198 <li>must not appear in combination with any of the following options:
 199 ipv6.
 200 </ul>
 201
 202   <p>Force DNS resolution of following host names on the command line
 203         to the IPv4 namespace.
 204         _EndOfDoc_;
 205 ;
 206
 207   <p>flag =
 208     name      = ipv6;
 209     flags-cant = ipv4, prefer;
 210     value     = 6;
 211     descrip   = "Use only IPv6 addresses for DNS name resolution";
 212     doc = &lt;&lt;-  _EndOfDoc_
 213         Force DNS resolution of following host names on the command line
 214         to the IPv6 namespace.
 215         _EndOfDoc_;
 216 ;
 217
 218   <p>flag =
 219     name        = prefer;
 220     flags-cant  = ipv4, ipv6;
 221     value       = p;
 222     arg-type    = keyword;
 223     keyword     = 4, 6;
 224     descrip     = 'Prefer IPv4 or IPv6 (as specified) addresses, but use either';
 225     doc         = &lt;&lt;-  _EndOfDoc_
 226 Prefer IPv4 or IPv6 (as specified) addresses, but use either.
 227 <div class="node">
 228 <p><hr>
 229 <a name="update_002dleap-destination"></a>Next:&nbsp;<a rel="next" accesskey="n" href="#update_002dleap-expiration">update-leap expiration</a>,
 230 Previous:&nbsp;<a rel="previous" accesskey="p" href="#update_002dleap-ipv4">update-leap ipv4</a>,
 231 Up:&nbsp;<a rel="up" accesskey="u" href="#update_002dleap-Invocation">update-leap Invocation</a>
 232 <br>
 233 </div>
 234
 235 <h4 class="subsection">0.1.4 destination option (-d)</h4>
 236
 237 <p><a name="index-update_002dleap_002ddestination-6"></a>
 238 This is the &ldquo;filename on the local system&rdquo; option.
 239 This option takes a string argument <span class="file">float</span>.
 240 The name to use to store the leapfile on the local system.
 241 $LEAPFILE
 242 <div class="node">
 243 <p><hr>
 244 <a name="update_002dleap-expiration"></a>Next:&nbsp;<a rel="next" accesskey="n" href="#update_002dleap-ntp_002dconf_002dfile">update-leap ntp-conf-file</a>,
 245 Previous:&nbsp;<a rel="previous" accesskey="p" href="#update_002dleap-destination">update-leap destination</a>,
 246 Up:&nbsp;<a rel="up" accesskey="u" href="#update_002dleap-Invocation">update-leap Invocation</a>
 247 <br>
 248 </div>
 249
 250 <h4 class="subsection">0.1.5 expiration option (-e)</h4>
 251
 252 <p><a name="index-update_002dleap_002dexpiration-7"></a>
 253 This is the &ldquo;refresh the leapfile this long before it expires&rdquo; option.
 254 This option takes a string argument.
 255 Specify how long before expiration the file is to be refreshed
 256 Units are required, e.g. "-e 60 days"  Note that larger values
 257 imply more frequent refreshes.
 258 "$PREFETCH"
 259 <div class="node">
 260 <p><hr>
 261 <a name="update_002dleap-ntp_002dconf_002dfile"></a>Next:&nbsp;<a rel="next" accesskey="n" href="#update_002dleap-force_002dupdate">update-leap force-update</a>,
 262 Previous:&nbsp;<a rel="previous" accesskey="p" href="#update_002dleap-expiration">update-leap expiration</a>,
 263 Up:&nbsp;<a rel="up" accesskey="u" href="#update_002dleap-Invocation">update-leap Invocation</a>
 264 <br>
 265 </div>
 266
 267 <h4 class="subsection">0.1.6 ntp-conf-file option (-f)</h4>
 268
 269 <p><a name="index-update_002dleap_002dntp_002dconf_002dfile-8"></a>
 270 This is the &ldquo;location of the ntp.conf file&rdquo; option.
 271 This option takes a string argument.
 272 Specify location of ntp.conf (used to make sure leapfile directive is
 273 present and to default  leapfile)
 274 /etc/ntp.conf
 275 <div class="node">
 276 <p><hr>
 277 <a name="update_002dleap-force_002dupdate"></a>Next:&nbsp;<a rel="next" accesskey="n" href="#update_002dleap-exit-status">update-leap exit status</a>,
 278 Previous:&nbsp;<a rel="previous" accesskey="p" href="#update_002dleap-ntp_002dconf_002dfile">update-leap ntp-conf-file</a>,
 279 Up:&nbsp;<a rel="up" accesskey="u" href="#update_002dleap-Invocation">update-leap Invocation</a>
 280 <br>
 281 </div>
 282
 283 <h4 class="subsection">0.1.7 force-update option (-F)</h4>
 284
 285 <p><a name="index-update_002dleap_002dforce_002dupdate-9"></a>
 286 This is the &ldquo;force update of the leapfile&rdquo; option.
 287 Force update even if current file is OK and not close to expiring.
 288 <div class="node">
 289 <p><hr>
 290 <a name="update_002dleap-exit-status"></a>Next:&nbsp;<a rel="next" accesskey="n" href="#update_002dleap-Usage">update-leap Usage</a>,
 291 Previous:&nbsp;<a rel="previous" accesskey="p" href="#update_002dleap-force_002dupdate">update-leap force-update</a>,
 292 Up:&nbsp;<a rel="up" accesskey="u" href="#update_002dleap-Invocation">update-leap Invocation</a>
 293 <br>
 294 </div>
 295
 296 <h4 class="subsection">0.1.8 update-leap exit status</h4>
 297
 298 <p>One of the following exit values will be returned:
 299      <dl>
 300 <dt><span class="samp">0 (EXIT_SUCCESS)</span><dd>Successful program execution.
 301 <br><dt><span class="samp">1 (EXIT_FAILURE)</span><dd>The operation failed or the command syntax was not valid.
 302 </dl>
 303   <div class="node">
 304 <p><hr>
 305 <a name="update_002dleap-Usage"></a>Next:&nbsp;<a rel="next" accesskey="n" href="#update_002dleap-Authors">update-leap Authors</a>,
 306 Previous:&nbsp;<a rel="previous" accesskey="p" href="#update_002dleap-exit-status">update-leap exit status</a>,
 307 Up:&nbsp;<a rel="up" accesskey="u" href="#update_002dleap-Invocation">update-leap Invocation</a>
 308 <br>
 309 </div>
 310
 311 <h4 class="subsection">0.1.9 update-leap Usage</h4>
 312
 313 <div class="node">
 314 <p><hr>
 315 <a name="update_002dleap-Authors"></a>Previous:&nbsp;<a rel="previous" accesskey="p" href="#update_002dleap-Usage">update-leap Usage</a>,
 316 Up:&nbsp;<a rel="up" accesskey="u" href="#update_002dleap-Invocation">update-leap Invocation</a>
 317 <br>
 318 </div>
 319
 320 <h4 class="subsection">0.1.10 update-leap Authors</h4>
 321
 322 </body></html>
 323