1a25439b6SCy Schubert@node update-leap Invocation 2a25439b6SCy Schubert@section Invoking update-leap 3a25439b6SCy Schubert@pindex update-leap 4a25439b6SCy Schubert@cindex leap-seconds file manager/updater 5a25439b6SCy Schubert@ignore 6a25439b6SCy Schubert# 7a25439b6SCy Schubert# EDIT THIS FILE WITH CAUTION (invoke-update-leap.texi) 8a25439b6SCy Schubert# 9*f5f40dd6SCy Schubert# It has been AutoGen-ed May 25, 2024 at 12:05:53 AM by AutoGen 5.18.16 10a25439b6SCy Schubert# From the definitions update-leap-opts.def 11a25439b6SCy Schubert# and the template file agtexi-cmd.tpl 12a25439b6SCy Schubert@end ignore 13a25439b6SCy Schubert 14a25439b6SCy Schubert 15a25439b6SCy Schubert 16a25439b6SCy Schubert@code{update-leap} 17a25439b6SCy Schubertwill validate the file currently on the local system 18a25439b6SCy Schubertand if necessary, updates leap-second definition file. 19a25439b6SCy Schubert 20a25439b6SCy SchubertOrdinarily, the file is found using the "leapfile" directive in 21a25439b6SCy Schubert@code{ntp.conf(5)}. 22a25439b6SCy SchubertHowever, an alternate location can be specified on the command line. 23a25439b6SCy Schubert 24a25439b6SCy SchubertIf the file does not exist, is not valid, has expired, or is expiring soon, 25a25439b6SCy Schuberta new copy will be downloaded. If the new copy validates, it is installed and 26a25439b6SCy SchubertNTP is (optionally) restarted. 27a25439b6SCy Schubert 28a25439b6SCy SchubertIf the current file is acceptable, no download or restart occurs. 29a25439b6SCy Schubert 30a25439b6SCy Schubert-c can also be used to invoke another script to perform administrative 31a25439b6SCy Schubertfunctions, e.g. to copy the file to other local systems. 32a25439b6SCy Schubert.PP 33a25439b6SCy SchubertThis can be run as a cron job. As the file is rarely updated, and leap 34a25439b6SCy Schubertseconds are announced at least one month in advance (usually longer), it 35a25439b6SCy Schubertneed not be run more frequently than about once every three weeks. 36a25439b6SCy Schubert.PP 37a25439b6SCy SchubertFor cron-friendly behavior, define CRONJOB=1 in the crontab. 38a25439b6SCy Schubert.PP 39a25439b6SCy SchubertThis script depends on$REQUIREDCMDS 40a25439b6SCy Schubert 41a25439b6SCy SchubertThis section was generated by @strong{AutoGen}, 42a25439b6SCy Schubertusing the @code{agtexi-cmd} template and the option descriptions for the @code{update-leap} program. 43a25439b6SCy Schubert 44a25439b6SCy Schubert@menu 45a25439b6SCy Schubert* update-leap usage:: update-leap help/usage (@option{--help}) 46a25439b6SCy Schubert* update-leap source-url:: source-url option (-s) 47a25439b6SCy Schubert* update-leap ipv4:: ipv4 option (-4) 48a25439b6SCy Schubert* update-leap destination:: destination option (-d) 49a25439b6SCy Schubert* update-leap expiration:: expiration option (-e) 50a25439b6SCy Schubert* update-leap ntp-conf-file:: ntp-conf-file option (-f) 51a25439b6SCy Schubert* update-leap force-update:: force-update option (-F) 52a25439b6SCy Schubert* update-leap exit status:: exit status 53a25439b6SCy Schubert* update-leap Usage:: Usage 54a25439b6SCy Schubert* update-leap Authors:: Authors 55a25439b6SCy Schubert@end menu 56a25439b6SCy Schubert 57a25439b6SCy Schubert@node update-leap usage 58a25439b6SCy Schubert@subsection update-leap help/usage (@option{--help}) 59a25439b6SCy Schubert@cindex update-leap help 60a25439b6SCy Schubert 61a25439b6SCy SchubertThis is the automatically generated usage text for update-leap. 62a25439b6SCy Schubert 63a25439b6SCy SchubertThe text printed is the same whether selected with the @code{help} option 64a25439b6SCy Schubert(@option{--help}) or the @code{more-help} option (@option{--more-help}). @code{more-help} will print 65a25439b6SCy Schubertthe usage text by passing it through a pager program. 66a25439b6SCy Schubert@code{more-help} is disabled on platforms without a working 67a25439b6SCy Schubert@code{fork(2)} function. The @code{PAGER} environment variable is 68a25439b6SCy Schubertused to select the program, defaulting to @file{more}. Both will exit 69a25439b6SCy Schubertwith a status code of 0. 70a25439b6SCy Schubert 71a25439b6SCy Schubert@exampleindent 0 72a25439b6SCy Schubert@example 7309100258SXin LI 7409100258SXin LIUsage: update-leap [options] 75276da39aSCy Schubert 76276da39aSCy SchubertVerifies and if necessary, updates leap-second definition file 77276da39aSCy Schubert 7809100258SXin LIAll arguments are optional: Default (or current value) shown: 7909100258SXin LI -C Absolute path to CA Cert (see SSL/TLS Considerations) 8009100258SXin LI -D Path to a CAdir (see SSL/TLS Considerations) 8109100258SXin LI -e Specify how long (in days) before expiration the file is to be 8209100258SXin LI refreshed. Note that larger values imply more frequent refreshes. 8309100258SXin LI 60 8409100258SXin LI -F Force update even if current file is OK and not close to expiring. 8509100258SXin LI -f Absolute path ntp.conf file (default /etc/ntp.conf) 8609100258SXin LI /etc/ntp.conf 8709100258SXin LI -h show help 8809100258SXin LI -i Specify number of minutes between retries 8909100258SXin LI 10 9009100258SXin LI -L Absolute path to leapfile on the local system 9109100258SXin LI (overrides value in ntp.conf) 9209100258SXin LI -l Specify the syslog(3) facility for logging 9309100258SXin LI LOG_USER 9409100258SXin LI -q Only report errors (cannot be used with -v) 9509100258SXin LI -r Specify number of attempts to retrieve file 9609100258SXin LI 6 9709100258SXin LI -s Send output to syslog(3) - implied if STDOUT has no tty or redirected 9809100258SXin LI -t Send output to terminal - implied if STDOUT attached to terminal 9909100258SXin LI -u Specify the URL of the master copy to download 10009100258SXin LI https://www.ietf.org/timezones/data/leap-seconds.list 10109100258SXin LI -v Verbose - show debug messages (cannot be used with -q) 102276da39aSCy Schubert 103276da39aSCy SchubertThe following options are not (yet) implemented in the perl version: 10409100258SXin LI -4 Use only IPv4 10509100258SXin LI -6 Use only IPv6 10609100258SXin LI -c Command to restart NTP after installing a new file 10709100258SXin LI <none> - ntpd checks file daily 10809100258SXin LI -p 4|6 10909100258SXin LI Prefer IPv4 or IPv6 (as specified) addresses, but use either 110276da39aSCy Schubert 11109100258SXin LIupdate-leap will validate the file currently on the local system. 112276da39aSCy Schubert 11309100258SXin LIOrdinarily, the leapfile is found using the 'leapfile' directive in 11409100258SXin LI/etc/ntp.conf. However, an alternate location can be specified on the 11509100258SXin LIcommand line with the -L flag. 116276da39aSCy Schubert 11709100258SXin LIIf the leapfile does not exist, is not valid, has expired, or is 11809100258SXin LIexpiring soon, a new copy will be downloaded. If the new copy is 11909100258SXin LIvalid, it is installed. 120276da39aSCy Schubert 121276da39aSCy SchubertIf the current file is acceptable, no download or restart occurs. 122276da39aSCy Schubert 123276da39aSCy SchubertThis can be run as a cron job. As the file is rarely updated, and 124276da39aSCy Schubertleap seconds are announced at least one month in advance (usually 125276da39aSCy Schubertlonger), it need not be run more frequently than about once every 126276da39aSCy Schubertthree weeks. 127276da39aSCy Schubert 12809100258SXin LISSL/TLS Considerations 12909100258SXin LI----------------------- 13009100258SXin LIThe perl modules can usually locate the CA certificate used to verify 13109100258SXin LIthe peer's identity. 132276da39aSCy Schubert 13309100258SXin LIOn BSDs, the default is typically the file /etc/ssl/certs.pem. On 13409100258SXin LILinux, the location is typically a path to a CAdir - a directory of 13509100258SXin LIsymlinks named according to a hash of the certificates' subject names. 13609100258SXin LI 13709100258SXin LIThe -C or -D options are available to pass in a location if no CA cert 13809100258SXin LIis found in the default location. 13909100258SXin LI 14009100258SXin LIExternal Dependencies 14109100258SXin LI--------------------- 14209100258SXin LIThe following perl modules are required: 14309100258SXin LIHTTP::Tiny - version >= 0.056 14409100258SXin LIIO::Socket::SSL - version >= 1.56 14509100258SXin LINET::SSLeay - version >= 1.49 14609100258SXin LI 14709100258SXin LIVersion: 1.004 148a25439b6SCy Schubert@end example 149a25439b6SCy Schubert@exampleindent 4 150a25439b6SCy Schubert 151a25439b6SCy Schubert@node update-leap source-url 152a25439b6SCy Schubert@subsection source-url option (-s) 153a25439b6SCy Schubert@cindex update-leap-source-url 154a25439b6SCy Schubert 155a25439b6SCy SchubertThis is the ``the url of the master copy of the leapseconds file'' option. 156a25439b6SCy SchubertThis option takes a string argument. 157a25439b6SCy SchubertSpecify the URL of the master copy to download 158a25439b6SCy Schubert$LEAPSRC 159a25439b6SCy Schubert@node update-leap ipv4 160a25439b6SCy Schubert@subsection ipv4 option (-4) 161a25439b6SCy Schubert@cindex update-leap-ipv4 162a25439b6SCy Schubert 163a25439b6SCy SchubertThis is the ``use only ipv4 addresses for dns name resolution'' option. 164a25439b6SCy Schubert 165a25439b6SCy Schubert@noindent 166a25439b6SCy SchubertThis option has some usage constraints. It: 167a25439b6SCy Schubert@itemize @bullet 168a25439b6SCy Schubert@item 169a25439b6SCy Schubertmust not appear in combination with any of the following options: 170a25439b6SCy Schubertipv6. 171a25439b6SCy Schubert@end itemize 172a25439b6SCy Schubert 173a25439b6SCy Schubert Force DNS resolution of following host names on the command line 174a25439b6SCy Schubert to the IPv4 namespace. 175a25439b6SCy Schubert _EndOfDoc_; 176a25439b6SCy Schubert}; 177a25439b6SCy Schubert 178a25439b6SCy Schubertflag = { 179a25439b6SCy Schubert name = ipv6; 180a25439b6SCy Schubert flags-cant = ipv4, prefer; 181a25439b6SCy Schubert value = 6; 182a25439b6SCy Schubert descrip = "Use only IPv6 addresses for DNS name resolution"; 183a25439b6SCy Schubert doc = <<- _EndOfDoc_ 184a25439b6SCy Schubert Force DNS resolution of following host names on the command line 185a25439b6SCy Schubert to the IPv6 namespace. 186a25439b6SCy Schubert _EndOfDoc_; 187a25439b6SCy Schubert}; 188a25439b6SCy Schubert 189a25439b6SCy Schubertflag = { 190a25439b6SCy Schubert name = prefer; 191a25439b6SCy Schubert flags-cant = ipv4, ipv6; 192a25439b6SCy Schubert value = p; 193a25439b6SCy Schubert arg-type = keyword; 194a25439b6SCy Schubert keyword = 4, 6; 195a25439b6SCy Schubert descrip = 'Prefer IPv4 or IPv6 (as specified) addresses, but use either'; 196a25439b6SCy Schubert doc = <<- _EndOfDoc_ 197a25439b6SCy SchubertPrefer IPv4 or IPv6 (as specified) addresses, but use either. 198a25439b6SCy Schubert@node update-leap destination 199a25439b6SCy Schubert@subsection destination option (-d) 200a25439b6SCy Schubert@cindex update-leap-destination 201a25439b6SCy Schubert 202a25439b6SCy SchubertThis is the ``filename on the local system'' option. 203a25439b6SCy SchubertThis option takes a string argument @file{float}. 204a25439b6SCy SchubertThe name to use to store the leapfile on the local system. 205a25439b6SCy Schubert$LEAPFILE 206a25439b6SCy Schubert@node update-leap expiration 207a25439b6SCy Schubert@subsection expiration option (-e) 208a25439b6SCy Schubert@cindex update-leap-expiration 209a25439b6SCy Schubert 210a25439b6SCy SchubertThis is the ``refresh the leapfile this long before it expires'' option. 211a25439b6SCy SchubertThis option takes a string argument. 212a25439b6SCy SchubertSpecify how long before expiration the file is to be refreshed 213a25439b6SCy SchubertUnits are required, e.g. "-e 60 days" Note that larger values 214a25439b6SCy Schubertimply more frequent refreshes. 215a25439b6SCy Schubert"$PREFETCH" 216a25439b6SCy Schubert@node update-leap ntp-conf-file 217a25439b6SCy Schubert@subsection ntp-conf-file option (-f) 218a25439b6SCy Schubert@cindex update-leap-ntp-conf-file 219a25439b6SCy Schubert 220a25439b6SCy SchubertThis is the ``location of the ntp.conf file'' option. 221a25439b6SCy SchubertThis option takes a string argument. 222a25439b6SCy SchubertSpecify location of ntp.conf (used to make sure leapfile directive is 223a25439b6SCy Schubertpresent and to default leapfile) 224a25439b6SCy Schubert/etc/ntp.conf 225a25439b6SCy Schubert@node update-leap force-update 226a25439b6SCy Schubert@subsection force-update option (-F) 227a25439b6SCy Schubert@cindex update-leap-force-update 228a25439b6SCy Schubert 229a25439b6SCy SchubertThis is the ``force update of the leapfile'' option. 230a25439b6SCy SchubertForce update even if current file is OK and not close to expiring. 231a25439b6SCy Schubert@node update-leap exit status 232a25439b6SCy Schubert@subsection update-leap exit status 233a25439b6SCy Schubert 234a25439b6SCy SchubertOne of the following exit values will be returned: 235a25439b6SCy Schubert@table @samp 236a25439b6SCy Schubert@item 0 (EXIT_SUCCESS) 237a25439b6SCy SchubertSuccessful program execution. 238a25439b6SCy Schubert@item 1 (EXIT_FAILURE) 239a25439b6SCy SchubertThe operation failed or the command syntax was not valid. 240a25439b6SCy Schubert@end table 241a25439b6SCy Schubert@node update-leap Usage 242a25439b6SCy Schubert@subsection update-leap Usage 243a25439b6SCy Schubert@node update-leap Authors 244a25439b6SCy Schubert@subsection update-leap Authors 245