diff options
Diffstat (limited to 'contrib/ntp/scripts/update-leap/update-leap.html')
| -rw-r--r-- | contrib/ntp/scripts/update-leap/update-leap.html | 396 |
1 files changed, 396 insertions, 0 deletions
diff --git a/contrib/ntp/scripts/update-leap/update-leap.html b/contrib/ntp/scripts/update-leap/update-leap.html new file mode 100644 index 000000000000..becb66888b74 --- /dev/null +++ b/contrib/ntp/scripts/update-leap/update-leap.html @@ -0,0 +1,396 @@ +<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd"> +<html> +<!-- Created by GNU Texinfo 6.5, http://www.gnu.org/software/texinfo/ --> +<head> +<meta http-equiv="Content-Type" content="text/html; charset=utf-8"> +<title>update-leap User’s Manual</title> + +<meta name="description" content="update-leap User’s Manual"> +<meta name="keywords" content="update-leap User’s Manual"> +<meta name="resource-type" content="document"> +<meta name="distribution" content="global"> +<meta name="Generator" content="makeinfo"> +<link href="#Top" rel="start" title="Top"> +<link href="dir.html#Top" rel="up" title="(dir)"> +<style type="text/css"> +<!-- +a.summary-letter {text-decoration: none} +blockquote.indentedblock {margin-right: 0em} +blockquote.smallindentedblock {margin-right: 0em; font-size: smaller} +blockquote.smallquotation {font-size: smaller} +div.display {margin-left: 3.2em} +div.example {margin-left: 3.2em} +div.lisp {margin-left: 3.2em} +div.smalldisplay {margin-left: 3.2em} +div.smallexample {margin-left: 3.2em} +div.smalllisp {margin-left: 3.2em} +kbd {font-style: oblique} +pre.display {font-family: inherit} +pre.format {font-family: inherit} +pre.menu-comment {font-family: serif} +pre.menu-preformatted {font-family: serif} +pre.smalldisplay {font-family: inherit; font-size: smaller} +pre.smallexample {font-size: smaller} +pre.smallformat {font-family: inherit; font-size: smaller} +pre.smalllisp {font-size: smaller} +span.nolinebreak {white-space: nowrap} +span.roman {font-family: initial; font-weight: normal} +span.sansserif {font-family: sans-serif; font-weight: normal} +ul.no-bullet {list-style: none} +--> +</style> + + +</head> + +<body lang="en"> +<h1 class="settitle" align="center">update-leap User’s Manual</h1> + + + + + +<a name="Top"></a> +<div class="header"> +<p> +Previous: <a href="dir.html#Top" accesskey="p" rel="prev">(dir)</a>, Up: <a href="dir.html#Top" accesskey="u" rel="up">(dir)</a> </p> +</div> +<h1 class="node-heading">Top</h1> + +<p>This document describes the use of the NTP Project’s <code>update-leap</code> program. +</p> +<p>This document applies to version 4.2.8p13 of <code>update-leap</code>. +</p> +<a name="SEC_Overview"></a> +<h2 class="shortcontents-heading">Short Table of Contents</h2> + +<div class="shortcontents"> +<li><a name="stoc-Invoking-update_002dleap" href="#toc-Invoking-update_002dleap">1 Invoking update-leap</a></li> + +</div> + + +<table class="menu" border="0" cellspacing="0"> +<tr><td align="left" valign="top">• update-leap Description:</td><td> </td><td align="left" valign="top">Description +</td></tr> +<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 +</td></tr> +</table> + +<hr> +<a name="update_002dleap-Invocation"></a> +<div class="header"> +<p> +Up: <a href="#Top" accesskey="u" rel="up">Top</a> </p> +</div> +<a name="Invoking-update_002dleap"></a> +<h3 class="section">1 Invoking update-leap</h3> +<a name="index-update_002dleap"></a> +<a name="index-leap_002dseconds-file-manager_002fupdater"></a> + + + +<p><code>update-leap</code> +will validate the file currently on the local system +and if necessary, updates leap-second definition file. +</p> +<p>Ordinarily, the file is found using the "leapfile" directive in +<code>ntp.conf(5)</code>. +However, an alternate location can be specified on the command line. +</p> +<p>If the file does not exist, is not valid, has expired, or is expiring soon, +a new copy will be downloaded. If the new copy validates, it is installed and +NTP is (optionally) restarted. +</p> +<p>If the current file is acceptable, no download or restart occurs. +</p> +<p>-c can also be used to invoke another script to perform administrative +functions, e.g. to copy the file to other local systems. +.PP +This can be run as a cron job. As the file is rarely updated, and leap +seconds are announced at least one month in advance (usually longer), it +need not be run more frequently than about once every three weeks. +.PP +For cron-friendly behavior, define CRONJOB=1 in the crontab. +.PP +This script depends on$REQUIREDCMDS +</p> +<p>This section was generated by <strong>AutoGen</strong>, +using the <code>agtexi-cmd</code> template and the option descriptions for the <code>update-leap</code> program. +</p> +<table class="menu" border="0" cellspacing="0"> +<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>) +</td></tr> +<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) +</td></tr> +<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) +</td></tr> +<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) +</td></tr> +<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) +</td></tr> +<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) +</td></tr> +<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) +</td></tr> +<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 +</td></tr> +<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 +</td></tr> +<tr><td align="left" valign="top">• <a href="#update_002dleap-Authors">update-leap Authors</a>:</td><td> </td><td align="left" valign="top">Authors +</td></tr> +</table> + +<hr> +<a name="update_002dleap-usage"></a> +<div class="header"> +<p> +Next: <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> +</div> +<a name="update_002dleap-help_002fusage-_0028_002d_002dhelp_0029"></a> +<h4 class="subsection">1.1 update-leap help/usage (<samp>--help</samp>)</h4> +<a name="index-update_002dleap-help"></a> + +<p>This is the automatically generated usage text for update-leap. +</p> +<p>The text printed is the same whether selected with the <code>help</code> option +(<samp>--help</samp>) or the <code>more-help</code> option (<samp>--more-help</samp>). <code>more-help</code> will print +the usage text by passing it through a pager program. +<code>more-help</code> is disabled on platforms without a working +<code>fork(2)</code> function. The <code>PAGER</code> environment variable is +used to select the program, defaulting to <samp>more</samp>. Both will exit +with a status code of 0. +</p> +<div class="example"> +<pre class="example"> + +Usage: update-leap [options] + +Verifies and if necessary, updates leap-second definition file + +All arguments are optional: Default (or current value) shown: + -C Absolute path to CA Cert (see SSL/TLS Considerations) + -D Path to a CAdir (see SSL/TLS Considerations) + -e Specify how long (in days) before expiration the file is to be + refreshed. Note that larger values imply more frequent refreshes. + 60 + -F Force update even if current file is OK and not close to expiring. + -f Absolute path ntp.conf file (default /etc/ntp.conf) + /etc/ntp.conf + -h show help + -i Specify number of minutes between retries + 10 + -L Absolute path to leapfile on the local system + (overrides value in ntp.conf) + -l Specify the syslog(3) facility for logging + LOG_USER + -q Only report errors (cannot be used with -v) + -r Specify number of attempts to retrieve file + 6 + -s Send output to syslog(3) - implied if STDOUT has no tty or redirected + -t Send output to terminal - implied if STDOUT attached to terminal + -u Specify the URL of the master copy to download + https://www.ietf.org/timezones/data/leap-seconds.list + -v Verbose - show debug messages (cannot be used with -q) + +The following options are not (yet) implemented in the perl version: + -4 Use only IPv4 + -6 Use only IPv6 + -c Command to restart NTP after installing a new file + <none> - ntpd checks file daily + -p 4|6 + Prefer IPv4 or IPv6 (as specified) addresses, but use either + +update-leap will validate the file currently on the local system. + +Ordinarily, the leapfile is found using the 'leapfile' directive in +/etc/ntp.conf. However, an alternate location can be specified on the +command line with the -L flag. + +If the leapfile does not exist, is not valid, has expired, or is +expiring soon, a new copy will be downloaded. If the new copy is +valid, it is installed. + +If the current file is acceptable, no download or restart occurs. + +This can be run as a cron job. As the file is rarely updated, and +leap seconds are announced at least one month in advance (usually +longer), it need not be run more frequently than about once every +three weeks. + +SSL/TLS Considerations +----------------------- +The perl modules can usually locate the CA certificate used to verify +the peer's identity. + +On BSDs, the default is typically the file /etc/ssl/certs.pem. On +Linux, the location is typically a path to a CAdir - a directory of +symlinks named according to a hash of the certificates' subject names. + +The -C or -D options are available to pass in a location if no CA cert +is found in the default location. + +External Dependencies +--------------------- +The following perl modules are required: +HTTP::Tiny - version >= 0.056 +IO::Socket::SSL - version >= 1.56 +NET::SSLeay - version >= 1.49 + +Version: 1.004 +</pre></div> + +<hr> +<a name="update_002dleap-source_002durl"></a> +<div class="header"> +<p> +Next: <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> +</div> +<a name="source_002durl-option-_0028_002ds_0029"></a> +<h4 class="subsection">1.2 source-url option (-s)</h4> +<a name="index-update_002dleap_002dsource_002durl"></a> + +<p>This is the “the url of the master copy of the leapseconds file” option. +This option takes a string argument. +Specify the URL of the master copy to download +$LEAPSRC +</p><hr> +<a name="update_002dleap-ipv4"></a> +<div class="header"> +<p> +Next: <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> +</div> +<a name="ipv4-option-_0028_002d4_0029"></a> +<h4 class="subsection">1.3 ipv4 option (-4)</h4> +<a name="index-update_002dleap_002dipv4"></a> + +<p>This is the “use only ipv4 addresses for dns name resolution” option. +</p> +<p>This option has some usage constraints. It: +</p><ul> +<li> must not appear in combination with any of the following options: +ipv6. +</li></ul> + +<p>Force DNS resolution of following host names on the command line + to the IPv4 namespace. + _EndOfDoc_; +; +</p> +<p>flag = + name = ipv6; + flags-cant = ipv4, prefer; + value = 6; + descrip = "Use only IPv6 addresses for DNS name resolution"; + doc = <<- _EndOfDoc_ + Force DNS resolution of following host names on the command line + to the IPv6 namespace. + _EndOfDoc_; +; +</p> +<p>flag = + name = prefer; + flags-cant = ipv4, ipv6; + value = p; + arg-type = keyword; + keyword = 4, 6; + descrip = ’Prefer IPv4 or IPv6 (as specified) addresses, but use either’; + doc = <<- _EndOfDoc_ +Prefer IPv4 or IPv6 (as specified) addresses, but use either. +</p><hr> +<a name="update_002dleap-destination"></a> +<div class="header"> +<p> +Next: <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> +</div> +<a name="destination-option-_0028_002dd_0029"></a> +<h4 class="subsection">1.4 destination option (-d)</h4> +<a name="index-update_002dleap_002ddestination"></a> + +<p>This is the “filename on the local system” option. +This option takes a string argument <samp>float</samp>. +The name to use to store the leapfile on the local system. +$LEAPFILE +</p><hr> +<a name="update_002dleap-expiration"></a> +<div class="header"> +<p> +Next: <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> +</div> +<a name="expiration-option-_0028_002de_0029"></a> +<h4 class="subsection">1.5 expiration option (-e)</h4> +<a name="index-update_002dleap_002dexpiration"></a> + +<p>This is the “refresh the leapfile this long before it expires” option. +This option takes a string argument. +Specify how long before expiration the file is to be refreshed +Units are required, e.g. "-e 60 days" Note that larger values +imply more frequent refreshes. +"$PREFETCH" +</p><hr> +<a name="update_002dleap-ntp_002dconf_002dfile"></a> +<div class="header"> +<p> +Next: <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> +</div> +<a name="ntp_002dconf_002dfile-option-_0028_002df_0029"></a> +<h4 class="subsection">1.6 ntp-conf-file option (-f)</h4> +<a name="index-update_002dleap_002dntp_002dconf_002dfile"></a> + +<p>This is the “location of the ntp.conf file” option. +This option takes a string argument. +Specify location of ntp.conf (used to make sure leapfile directive is +present and to default leapfile) +/etc/ntp.conf +</p><hr> +<a name="update_002dleap-force_002dupdate"></a> +<div class="header"> +<p> +Next: <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> +</div> +<a name="force_002dupdate-option-_0028_002dF_0029"></a> +<h4 class="subsection">1.7 force-update option (-F)</h4> +<a name="index-update_002dleap_002dforce_002dupdate"></a> + +<p>This is the “force update of the leapfile” option. +Force update even if current file is OK and not close to expiring. +</p><hr> +<a name="update_002dleap-exit-status"></a> +<div class="header"> +<p> +Next: <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> +</div> +<a name="update_002dleap-exit-status-1"></a> +<h4 class="subsection">1.8 update-leap exit status</h4> + +<p>One of the following exit values will be returned: +</p><dl compact="compact"> +<dt>‘<samp>0 (EXIT_SUCCESS)</samp>’</dt> +<dd><p>Successful program execution. +</p></dd> +<dt>‘<samp>1 (EXIT_FAILURE)</samp>’</dt> +<dd><p>The operation failed or the command syntax was not valid. +</p></dd> +</dl> +<hr> +<a name="update_002dleap-Usage"></a> +<div class="header"> +<p> +Next: <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> +</div> +<a name="update_002dleap-Usage-1"></a> +<h4 class="subsection">1.9 update-leap Usage</h4> +<hr> +<a name="update_002dleap-Authors"></a> +<div class="header"> +<p> +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> +</div> +<a name="update_002dleap-Authors-1"></a> +<h4 class="subsection">1.10 update-leap Authors</h4> +<hr> + + + +</body> +</html> |