invoke-update-leap.texi revision 298699
1226026Sdelphij@node update-leap Invocation 2226026Sdelphij@section Invoking update-leap 3226026Sdelphij@pindex update-leap 4226026Sdelphij@cindex leap-seconds file manager/updater 5226026Sdelphij@ignore 6226026Sdelphij# 7226026Sdelphij# EDIT THIS FILE WITH CAUTION (invoke-update-leap.texi) 8226026Sdelphij# 9226026Sdelphij# It has been AutoGen-ed April 26, 2016 at 08:24:50 PM by AutoGen 5.18.5 10226026Sdelphij# From the definitions update-leap-opts.def 11226026Sdelphij# and the template file agtexi-cmd.tpl 12226026Sdelphij@end ignore 13226026Sdelphij 14226026Sdelphij 15226026Sdelphij 16226026Sdelphij@code{update-leap} 17226026Sdelphijwill validate the file currently on the local system 18226026Sdelphijand if necessary, updates leap-second definition file. 19226026Sdelphij 20226026SdelphijOrdinarily, the file is found using the "leapfile" directive in 21226026Sdelphij@code{ntp.conf(5)}. 22226026SdelphijHowever, an alternate location can be specified on the command line. 23226026Sdelphij 24226026SdelphijIf the file does not exist, is not valid, has expired, or is expiring soon, 25226026Sdelphija new copy will be downloaded. If the new copy validates, it is installed and 26226026SdelphijNTP is (optionally) restarted. 27226026Sdelphij 28226026SdelphijIf the current file is acceptable, no download or restart occurs. 29226026Sdelphij 30226026Sdelphij-c can also be used to invoke another script to perform administrative 31226026Sdelphijfunctions, e.g. to copy the file to other local systems. 32226026Sdelphij.PP 33226026SdelphijThis can be run as a cron job. As the file is rarely updated, and leap 34226026Sdelphijseconds are announced at least one month in advance (usually longer), it 35226026Sdelphijneed not be run more frequently than about once every three weeks. 36226026Sdelphij.PP 37226026SdelphijFor cron-friendly behavior, define CRONJOB=1 in the crontab. 38226026Sdelphij.PP 39226026SdelphijThis script depends on$REQUIREDCMDS 40226026Sdelphij 41226026SdelphijThis section was generated by @strong{AutoGen}, 42226026Sdelphijusing the @code{agtexi-cmd} template and the option descriptions for the @code{update-leap} program. 43226026Sdelphij 44226026Sdelphij@menu 45226026Sdelphij* update-leap usage:: update-leap help/usage (@option{--help}) 46226026Sdelphij* update-leap source-url:: source-url option (-s) 47226026Sdelphij* update-leap ipv4:: ipv4 option (-4) 48226026Sdelphij* update-leap destination:: destination option (-d) 49226026Sdelphij* update-leap expiration:: expiration option (-e) 50226026Sdelphij* update-leap ntp-conf-file:: ntp-conf-file option (-f) 51226026Sdelphij* update-leap force-update:: force-update option (-F) 52226026Sdelphij* update-leap exit status:: exit status 53226026Sdelphij* update-leap Usage:: Usage 54226026Sdelphij* update-leap Authors:: Authors 55226026Sdelphij@end menu 56226026Sdelphij 57226026Sdelphij@node update-leap usage 58226026Sdelphij@subsection update-leap help/usage (@option{--help}) 59226026Sdelphij@cindex update-leap help 60226026Sdelphij 61226026SdelphijThis is the automatically generated usage text for update-leap. 62226026Sdelphij 63226026SdelphijThe text printed is the same whether selected with the @code{help} option 64226026Sdelphij(@option{--help}) or the @code{more-help} option (@option{--more-help}). @code{more-help} will print 65226026Sdelphijthe usage text by passing it through a pager program. 66226026Sdelphij@code{more-help} is disabled on platforms without a working 67226026Sdelphij@code{fork(2)} function. The @code{PAGER} environment variable is 68226026Sdelphijused to select the program, defaulting to @file{more}. Both will exit 69226026Sdelphijwith a status code of 0. 70226026Sdelphij 71226026Sdelphij@exampleindent 0 72226026Sdelphij@example 73226026Sdelphij update-leap 74226026Sdelphij Usage: $0 [options] [leapfile] 75226026Sdelphij 76226026Sdelphij Verifies and if necessary, updates leap-second definition file 77235317Sgjb 78226026Sdelphij All arguments are optional: Default (or current value) shown: -s 79226026Sdelphij Specify the URL of the master copy to download $LEAPSRC -d Specify 80226026Sdelphij the filename on the local system $LEAPFILE -e Specify how long (in 81226026Sdelphij days) before expiration the file is to be refreshed. Note that 82226026Sdelphij larger values imply more frequent refreshes. "$PREFETCH" -f Specify 83235317Sgjb location of ntp.conf (used to make sure leapfile directive is 84226026Sdelphij present and to default leapfile) $NTPCONF -F Force update even if 85226026Sdelphij current file is OK and not close to expiring. -r Specify number of 86226026Sdelphij times to retry on get failure $MAXTRIES -i Specify number of minutes 87226026Sdelphij between retries $INTERVAL -l Use syslog for output (Implied if 88226026Sdelphij CRONJOB is set) -L Don't use syslog for output -P Specify the syslog 89226026Sdelphij facility for logging $LOGFAC -t Name of temporary file used in 90226026Sdelphij validation $TMPFILE -q Only report errors to stdout -v Verbose 91226026Sdelphij output 92226026Sdelphij 93226026Sdelphij The following options are not (yet) implemented in the perl version: 94226026Sdelphij -4 Use only IPv4 -6 Use only IPv6 -c Command to restart NTP after 95226026Sdelphij installing a new file <none> - ntpd checks file daily -p 4|6 Prefer 96226026Sdelphij IPv4 or IPv6 (as specified) addresses, but use either -z Specify 97226026Sdelphij path for utilities $PATHLIST -Z Only use system path 98226026Sdelphij 99226026Sdelphij $0 will validate the file currently on the local system 100226026Sdelphij 101226026Sdelphij Ordinarily, the file is found using the "leapfile" directive in 102226026Sdelphij $NTPCONF. However, an alternate location can be specified on the 103226026Sdelphij command line. 104226026Sdelphij 105226026Sdelphij If the file does not exist, is not valid, has expired, or is 106226026Sdelphij expiring soon, a new copy will be downloaded. If the new copy 107226026Sdelphij validates, it is installed and NTP is (optionally) restarted. 108226026Sdelphij 109226026Sdelphij If the current file is acceptable, no download or restart occurs. 110226026Sdelphij 111226026Sdelphij -c can also be used to invoke another script to perform 112226026Sdelphij administrative functions, e.g. to copy the file to other local 113226026Sdelphij systems. 114226026Sdelphij 115226026Sdelphij This can be run as a cron job. As the file is rarely updated, and 116226026Sdelphij leap seconds are announced at least one month in advance (usually 117226026Sdelphij longer), it need not be run more frequently than about once every 118226026Sdelphij three weeks. 119 120 For cron-friendly behavior, define CRONJOB=1 in the crontab. 121 122 Version $VERSION 123@end example 124@exampleindent 4 125 126@node update-leap source-url 127@subsection source-url option (-s) 128@cindex update-leap-source-url 129 130This is the ``the url of the master copy of the leapseconds file'' option. 131This option takes a string argument. 132Specify the URL of the master copy to download 133$LEAPSRC 134@node update-leap ipv4 135@subsection ipv4 option (-4) 136@cindex update-leap-ipv4 137 138This is the ``use only ipv4 addresses for dns name resolution'' option. 139 140@noindent 141This option has some usage constraints. It: 142@itemize @bullet 143@item 144must not appear in combination with any of the following options: 145ipv6. 146@end itemize 147 148 Force DNS resolution of following host names on the command line 149 to the IPv4 namespace. 150 _EndOfDoc_; 151}; 152 153flag = { 154 name = ipv6; 155 flags-cant = ipv4, prefer; 156 value = 6; 157 descrip = "Use only IPv6 addresses for DNS name resolution"; 158 doc = <<- _EndOfDoc_ 159 Force DNS resolution of following host names on the command line 160 to the IPv6 namespace. 161 _EndOfDoc_; 162}; 163 164flag = { 165 name = prefer; 166 flags-cant = ipv4, ipv6; 167 value = p; 168 arg-type = keyword; 169 keyword = 4, 6; 170 descrip = 'Prefer IPv4 or IPv6 (as specified) addresses, but use either'; 171 doc = <<- _EndOfDoc_ 172Prefer IPv4 or IPv6 (as specified) addresses, but use either. 173@node update-leap destination 174@subsection destination option (-d) 175@cindex update-leap-destination 176 177This is the ``filename on the local system'' option. 178This option takes a string argument @file{float}. 179The name to use to store the leapfile on the local system. 180$LEAPFILE 181@node update-leap expiration 182@subsection expiration option (-e) 183@cindex update-leap-expiration 184 185This is the ``refresh the leapfile this long before it expires'' option. 186This option takes a string argument. 187Specify how long before expiration the file is to be refreshed 188Units are required, e.g. "-e 60 days" Note that larger values 189imply more frequent refreshes. 190"$PREFETCH" 191@node update-leap ntp-conf-file 192@subsection ntp-conf-file option (-f) 193@cindex update-leap-ntp-conf-file 194 195This is the ``location of the ntp.conf file'' option. 196This option takes a string argument. 197Specify location of ntp.conf (used to make sure leapfile directive is 198present and to default leapfile) 199/etc/ntp.conf 200@node update-leap force-update 201@subsection force-update option (-F) 202@cindex update-leap-force-update 203 204This is the ``force update of the leapfile'' option. 205Force update even if current file is OK and not close to expiring. 206@node update-leap exit status 207@subsection update-leap exit status 208 209One of the following exit values will be returned: 210@table @samp 211@item 0 (EXIT_SUCCESS) 212Successful program execution. 213@item 1 (EXIT_FAILURE) 214The operation failed or the command syntax was not valid. 215@end table 216@node update-leap Usage 217@subsection update-leap Usage 218@node update-leap Authors 219@subsection update-leap Authors 220