diff options
Diffstat (limited to 'contrib/ntp/scripts/update-leap/invoke-update-leap.texi')
| -rw-r--r-- | contrib/ntp/scripts/update-leap/invoke-update-leap.texi | 244 |
1 files changed, 244 insertions, 0 deletions
diff --git a/contrib/ntp/scripts/update-leap/invoke-update-leap.texi b/contrib/ntp/scripts/update-leap/invoke-update-leap.texi new file mode 100644 index 000000000000..9e1bdcbd7abb --- /dev/null +++ b/contrib/ntp/scripts/update-leap/invoke-update-leap.texi @@ -0,0 +1,244 @@ +@node update-leap Invocation +@section Invoking update-leap +@pindex update-leap +@cindex leap-seconds file manager/updater +@ignore +# +# EDIT THIS FILE WITH CAUTION (invoke-update-leap.texi) +# +# It has been AutoGen-ed May 25, 2024 at 12:05:53 AM by AutoGen 5.18.16 +# From the definitions update-leap-opts.def +# and the template file agtexi-cmd.tpl +@end ignore + + + +@code{update-leap} +will validate the file currently on the local system +and if necessary, updates leap-second definition file. + +Ordinarily, the file is found using the "leapfile" directive in +@code{ntp.conf(5)}. +However, an alternate location can be specified on the command line. + +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. + +If the current file is acceptable, no download or restart occurs. + +-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 + +This section was generated by @strong{AutoGen}, +using the @code{agtexi-cmd} template and the option descriptions for the @code{update-leap} program. + +@menu +* update-leap usage:: update-leap help/usage (@option{--help}) +* update-leap source-url:: source-url option (-s) +* update-leap ipv4:: ipv4 option (-4) +* update-leap destination:: destination option (-d) +* update-leap expiration:: expiration option (-e) +* update-leap ntp-conf-file:: ntp-conf-file option (-f) +* update-leap force-update:: force-update option (-F) +* update-leap exit status:: exit status +* update-leap Usage:: Usage +* update-leap Authors:: Authors +@end menu + +@node update-leap usage +@subsection update-leap help/usage (@option{--help}) +@cindex update-leap help + +This is the automatically generated usage text for update-leap. + +The text printed is the same whether selected with the @code{help} option +(@option{--help}) or the @code{more-help} option (@option{--more-help}). @code{more-help} will print +the usage text by passing it through a pager program. +@code{more-help} is disabled on platforms without a working +@code{fork(2)} function. The @code{PAGER} environment variable is +used to select the program, defaulting to @file{more}. Both will exit +with a status code of 0. + +@exampleindent 0 +@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 +@end example +@exampleindent 4 + +@node update-leap source-url +@subsection source-url option (-s) +@cindex update-leap-source-url + +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 +@node update-leap ipv4 +@subsection ipv4 option (-4) +@cindex update-leap-ipv4 + +This is the ``use only ipv4 addresses for dns name resolution'' option. + +@noindent +This option has some usage constraints. It: +@itemize @bullet +@item +must not appear in combination with any of the following options: +ipv6. +@end itemize + + Force DNS resolution of following host names on the command line + to the IPv4 namespace. + _EndOfDoc_; +}; + +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_; +}; + +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. +@node update-leap destination +@subsection destination option (-d) +@cindex update-leap-destination + +This is the ``filename on the local system'' option. +This option takes a string argument @file{float}. +The name to use to store the leapfile on the local system. +$LEAPFILE +@node update-leap expiration +@subsection expiration option (-e) +@cindex update-leap-expiration + +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" +@node update-leap ntp-conf-file +@subsection ntp-conf-file option (-f) +@cindex update-leap-ntp-conf-file + +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 +@node update-leap force-update +@subsection force-update option (-F) +@cindex update-leap-force-update + +This is the ``force update of the leapfile'' option. +Force update even if current file is OK and not close to expiring. +@node update-leap exit status +@subsection update-leap exit status + +One of the following exit values will be returned: +@table @samp +@item 0 (EXIT_SUCCESS) +Successful program execution. +@item 1 (EXIT_FAILURE) +The operation failed or the command syntax was not valid. +@end table +@node update-leap Usage +@subsection update-leap Usage +@node update-leap Authors +@subsection update-leap Authors |