1 <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
3 <!-- Created by GNU Texinfo 6.5, http://www.gnu.org/software/texinfo/ -->
5 <meta http-equiv="Content-Type" content="text/html; charset=utf-8">
6 <title>update-leap User’s Manual</title>
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">
17 a.summary-letter {text-decoration: none}
18 blockquote.indentedblock {margin-right: 0em}
19 blockquote.smallindentedblock {margin-right: 0em; font-size: smaller}
20 blockquote.smallquotation {font-size: smaller}
21 div.display {margin-left: 3.2em}
22 div.example {margin-left: 3.2em}
23 div.lisp {margin-left: 3.2em}
24 div.smalldisplay {margin-left: 3.2em}
25 div.smallexample {margin-left: 3.2em}
26 div.smalllisp {margin-left: 3.2em}
27 kbd {font-style: oblique}
28 pre.display {font-family: inherit}
29 pre.format {font-family: inherit}
30 pre.menu-comment {font-family: serif}
31 pre.menu-preformatted {font-family: serif}
32 pre.smalldisplay {font-family: inherit; font-size: smaller}
33 pre.smallexample {font-size: smaller}
34 pre.smallformat {font-family: inherit; font-size: smaller}
35 pre.smalllisp {font-size: smaller}
36 span.nolinebreak {white-space: nowrap}
37 span.roman {font-family: initial; font-weight: normal}
38 span.sansserif {font-family: sans-serif; font-weight: normal}
39 ul.no-bullet {list-style: none}
47 <h1 class="settitle" align="center">update-leap User’s Manual</h1>
56 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>
58 <h1 class="node-heading">Top</h1>
60 <p>This document describes the use of the NTP Project’s <code>update-leap</code> program.
62 <p>This document applies to version 4.2.8p13 of <code>update-leap</code>.
64 <a name="SEC_Overview"></a>
65 <h2 class="shortcontents-heading">Short Table of Contents</h2>
67 <div class="shortcontents">
68 <li><a name="stoc-Invoking-update_002dleap" href="#toc-Invoking-update_002dleap">1 Invoking update-leap</a></li>
73 <table class="menu" border="0" cellspacing="0">
74 <tr><td align="left" valign="top">• update-leap Description:</td><td> </td><td align="left" valign="top">Description
76 <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
81 <a name="update_002dleap-Invocation"></a>
84 Up: <a href="#Top" accesskey="u" rel="up">Top</a> </p>
86 <a name="Invoking-update_002dleap"></a>
87 <h3 class="section">1 Invoking update-leap</h3>
88 <a name="index-update_002dleap"></a>
89 <a name="index-leap_002dseconds-file-manager_002fupdater"></a>
93 <p><code>update-leap</code>
94 will validate the file currently on the local system
95 and if necessary, updates leap-second definition file.
97 <p>Ordinarily, the file is found using the "leapfile" directive in
98 <code>ntp.conf(5)</code>.
99 However, an alternate location can be specified on the command line.
101 <p>If the file does not exist, is not valid, has expired, or is expiring soon,
102 a new copy will be downloaded. If the new copy validates, it is installed and
103 NTP is (optionally) restarted.
105 <p>If the current file is acceptable, no download or restart occurs.
107 <p>-c can also be used to invoke another script to perform administrative
108 functions, e.g. to copy the file to other local systems.
110 This can be run as a cron job. As the file is rarely updated, and leap
111 seconds are announced at least one month in advance (usually longer), it
112 need not be run more frequently than about once every three weeks.
114 For cron-friendly behavior, define CRONJOB=1 in the crontab.
116 This script depends on$REQUIREDCMDS
118 <p>This section was generated by <strong>AutoGen</strong>,
119 using the <code>agtexi-cmd</code> template and the option descriptions for the <code>update-leap</code> program.
121 <table class="menu" border="0" cellspacing="0">
122 <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>)
124 <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)
126 <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)
128 <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)
130 <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)
132 <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)
134 <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)
136 <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
138 <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
140 <tr><td align="left" valign="top">• <a href="#update_002dleap-Authors">update-leap Authors</a>:</td><td> </td><td align="left" valign="top">Authors
145 <a name="update_002dleap-usage"></a>
148 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>
150 <a name="update_002dleap-help_002fusage-_0028_002d_002dhelp_0029"></a>
151 <h4 class="subsection">1.1 update-leap help/usage (<samp>--help</samp>)</h4>
152 <a name="index-update_002dleap-help"></a>
154 <p>This is the automatically generated usage text for update-leap.
156 <p>The text printed is the same whether selected with the <code>help</code> option
157 (<samp>--help</samp>) or the <code>more-help</code> option (<samp>--more-help</samp>). <code>more-help</code> will print
158 the usage text by passing it through a pager program.
159 <code>more-help</code> is disabled on platforms without a working
160 <code>fork(2)</code> function. The <code>PAGER</code> environment variable is
161 used to select the program, defaulting to <samp>more</samp>. Both will exit
162 with a status code of 0.
164 <div class="example">
165 <pre class="example">
167 Usage: update-leap [options]
169 Verifies and if necessary, updates leap-second definition file
171 All arguments are optional: Default (or current value) shown:
172 -C Absolute path to CA Cert (see SSL/TLS Considerations)
173 -D Path to a CAdir (see SSL/TLS Considerations)
174 -e Specify how long (in days) before expiration the file is to be
175 refreshed. Note that larger values imply more frequent refreshes.
177 -F Force update even if current file is OK and not close to expiring.
178 -f Absolute path ntp.conf file (default /etc/ntp.conf)
181 -i Specify number of minutes between retries
183 -L Absolute path to leapfile on the local system
184 (overrides value in ntp.conf)
185 -l Specify the syslog(3) facility for logging
187 -q Only report errors (cannot be used with -v)
188 -r Specify number of attempts to retrieve file
190 -s Send output to syslog(3) - implied if STDOUT has no tty or redirected
191 -t Send output to terminal - implied if STDOUT attached to terminal
192 -u Specify the URL of the master copy to download
193 https://www.ietf.org/timezones/data/leap-seconds.list
194 -v Verbose - show debug messages (cannot be used with -q)
196 The following options are not (yet) implemented in the perl version:
199 -c Command to restart NTP after installing a new file
200 <none> - ntpd checks file daily
202 Prefer IPv4 or IPv6 (as specified) addresses, but use either
204 update-leap will validate the file currently on the local system.
206 Ordinarily, the leapfile is found using the 'leapfile' directive in
207 /etc/ntp.conf. However, an alternate location can be specified on the
208 command line with the -L flag.
210 If the leapfile does not exist, is not valid, has expired, or is
211 expiring soon, a new copy will be downloaded. If the new copy is
212 valid, it is installed.
214 If the current file is acceptable, no download or restart occurs.
216 This can be run as a cron job. As the file is rarely updated, and
217 leap seconds are announced at least one month in advance (usually
218 longer), it need not be run more frequently than about once every
221 SSL/TLS Considerations
222 -----------------------
223 The perl modules can usually locate the CA certificate used to verify
226 On BSDs, the default is typically the file /etc/ssl/certs.pem. On
227 Linux, the location is typically a path to a CAdir - a directory of
228 symlinks named according to a hash of the certificates' subject names.
230 The -C or -D options are available to pass in a location if no CA cert
231 is found in the default location.
233 External Dependencies
234 ---------------------
235 The following perl modules are required:
236 HTTP::Tiny - version >= 0.056
237 IO::Socket::SSL - version >= 1.56
238 NET::SSLeay - version >= 1.49
244 <a name="update_002dleap-source_002durl"></a>
247 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>
249 <a name="source_002durl-option-_0028_002ds_0029"></a>
250 <h4 class="subsection">1.2 source-url option (-s)</h4>
251 <a name="index-update_002dleap_002dsource_002durl"></a>
253 <p>This is the “the url of the master copy of the leapseconds file” option.
254 This option takes a string argument.
255 Specify the URL of the master copy to download
258 <a name="update_002dleap-ipv4"></a>
261 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>
263 <a name="ipv4-option-_0028_002d4_0029"></a>
264 <h4 class="subsection">1.3 ipv4 option (-4)</h4>
265 <a name="index-update_002dleap_002dipv4"></a>
267 <p>This is the “use only ipv4 addresses for dns name resolution” option.
269 <p>This option has some usage constraints. It:
271 <li> must not appear in combination with any of the following options:
275 <p>Force DNS resolution of following host names on the command line
276 to the IPv4 namespace.
282 flags-cant = ipv4, prefer;
284 descrip = "Use only IPv6 addresses for DNS name resolution";
285 doc = <<- _EndOfDoc_
286 Force DNS resolution of following host names on the command line
287 to the IPv6 namespace.
293 flags-cant = ipv4, ipv6;
297 descrip = ’Prefer IPv4 or IPv6 (as specified) addresses, but use either’;
298 doc = <<- _EndOfDoc_
299 Prefer IPv4 or IPv6 (as specified) addresses, but use either.
301 <a name="update_002dleap-destination"></a>
304 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>
306 <a name="destination-option-_0028_002dd_0029"></a>
307 <h4 class="subsection">1.4 destination option (-d)</h4>
308 <a name="index-update_002dleap_002ddestination"></a>
310 <p>This is the “filename on the local system” option.
311 This option takes a string argument <samp>float</samp>.
312 The name to use to store the leapfile on the local system.
315 <a name="update_002dleap-expiration"></a>
318 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>
320 <a name="expiration-option-_0028_002de_0029"></a>
321 <h4 class="subsection">1.5 expiration option (-e)</h4>
322 <a name="index-update_002dleap_002dexpiration"></a>
324 <p>This is the “refresh the leapfile this long before it expires” option.
325 This option takes a string argument.
326 Specify how long before expiration the file is to be refreshed
327 Units are required, e.g. "-e 60 days" Note that larger values
328 imply more frequent refreshes.
329 "$PREFETCH"
331 <a name="update_002dleap-ntp_002dconf_002dfile"></a>
334 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>
336 <a name="ntp_002dconf_002dfile-option-_0028_002df_0029"></a>
337 <h4 class="subsection">1.6 ntp-conf-file option (-f)</h4>
338 <a name="index-update_002dleap_002dntp_002dconf_002dfile"></a>
340 <p>This is the “location of the ntp.conf file” option.
341 This option takes a string argument.
342 Specify location of ntp.conf (used to make sure leapfile directive is
343 present and to default leapfile)
346 <a name="update_002dleap-force_002dupdate"></a>
349 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>
351 <a name="force_002dupdate-option-_0028_002dF_0029"></a>
352 <h4 class="subsection">1.7 force-update option (-F)</h4>
353 <a name="index-update_002dleap_002dforce_002dupdate"></a>
355 <p>This is the “force update of the leapfile” option.
356 Force update even if current file is OK and not close to expiring.
358 <a name="update_002dleap-exit-status"></a>
361 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>
363 <a name="update_002dleap-exit-status-1"></a>
364 <h4 class="subsection">1.8 update-leap exit status</h4>
366 <p>One of the following exit values will be returned:
367 </p><dl compact="compact">
368 <dt>‘<samp>0 (EXIT_SUCCESS)</samp>’</dt>
369 <dd><p>Successful program execution.
371 <dt>‘<samp>1 (EXIT_FAILURE)</samp>’</dt>
372 <dd><p>The operation failed or the command syntax was not valid.
376 <a name="update_002dleap-Usage"></a>
379 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>
381 <a name="update_002dleap-Usage-1"></a>
382 <h4 class="subsection">1.9 update-leap Usage</h4>
384 <a name="update_002dleap-Authors"></a>
387 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>
389 <a name="update_002dleap-Authors-1"></a>
390 <h4 class="subsection">1.10 update-leap Authors</h4>