1KRENEW(1) kstart KRENEW(1)
2
6 krenew - Renew a Kerberos ticket
7
9 krenew [-abhiLstvx] [-c child pid file] [-H minutes]
10 [-K minutes] [-k ticket cache] [-p pid file]
11 [command ...]
12
14 krenew renews an existing renewable ticket. When run without any
15 arguments, it just attempts to renew the existing ticket-granting
16 ticket in the current ticket cache, equivalent to "kinit -R", but it
17 can optionally run a program like aklog to refresh AFS tokens, can run
18 as a daemon and wake up periodically to renew the ticket cache, or can
19 run a specified command and keep renewing the ticket cache until the
20 command finishes (or renewal is no longer possible). If a command is
21 specified, krenew by default wakes up every 60 minutes (1 hour) to
22 check the ticket cache.
23 If a command is given, krenew makes a copy of the ticket cache and
25 creates a private ticket cache just for that command, thus isolating it
26 from later destruction of the original ticket cache. This allows
27 krenew to maintain authentication for a command even if, for example,
28 the user running the command logs out and OpenSSH destroys their
29 original ticket cache.
30 If a command is given, it will not be run using the shell, so if you
32 want to use shell metacharacters in the command with their special
33 meaning, give "sh -c command" as the command to run and quote command.
34 If the command contains command-line options (like "-c"), put "--" on
35 the command line before the beginning of the command to tell krenew to
36 not parse those options as its own.
37 If krenew is built with setpag() support and AFS tokens are requested
39 with the -t option, it will put the command in a separate PAG before
40 obtaining AFS tokens so that they don't interfere with other processes
41 on the system.
42 When running a command, krenew propagates HUP, TERM, INT, and QUIT
44 signals to the child process and does not exit when those signals are
45 received. (If the propagated signal causes the child process to exit,
46 krenew will then exit.) This allows krenew to react properly when run
47 under a command supervision system such as runit(8) or svscan(8) that
48 uses signals to control supervised commands, and to run interactive
49 commands that should receive Ctrl-C.
50 If a running krenew receives an ALRM signal, it immediately refreshes
52 the ticket cache regardless of whether it is in danger of expiring.
53
55 -a When run with either the -K flag or a command, always renew tickets
56 each time krenew wakes up. Without this option, krenew will only
57 try to renew a ticket as often as necessary to prevent the ticket
58 from expiring. With this option, krenew will renew tickets
59 according to the interval specified with the -K flag.
60 This behavior probably should have been the default behavior of -K.
62 The default was not changed to avoid changes for existing users,
63 but for new applications, consider always using -a with -K.
64 This option is important if another program is manipulating the
66 ticket cache that krenew is using. For example, if another program
67 is automatically renewing a ticket more frequently than krenew,
68 then krenew will never see a ticket that is close to expiring and
69 will therefore, by default, never try to renew the ticket. This
70 means that krenew will also never renew AFS tokens, even if the -t
71 option was given, since krenew only renews AFS tokens after it
72 successfully renews a ticket. If this option is specified in such
73 a situation, krenew will renew its ticket every time it checks the
74 ticket, so AFS tokens will be renewed.
75 This argument is only valid in combination with either -K or a
77 command to run.
78 -b After starting, detach from the controlling terminal and run in the
80 background. This option only makes sense in combination with -K or
81 a command that krenew will be running. krenew will not background
82 itself until after it does the initial ticket renewal, so that any
83 initial errors will be reported, but it will then redirect output
84 to /dev/null and no subsequent errors will be reported.
85 If this flag is given, krenew will also change directories to "/".
87 All paths (such as to a command to run or a PID file) should
88 therefore be given as absolute, not relative, paths.
89 If used in conjunction with a command to run, that command will
91 also run in the background and will also have its input and output
92 redirected to /dev/null. It will have to report any errors via
93 some other mechanism for the errors to be seen.
94 Use of this flag on Mac OS X without specifying a file-based ticket
96 cache by either using -k or setting KRB5CCNAME will probably not do
97 what you want. Ticket caches on Mac OS X are, by default, per-
98 session and with -b krenew will detach itself from your existing
99 ticket cache. Instead, to renew the default ticket cache on Mac OS
100 X, try something like:
101 (krenew -K 60 &)
103 to run krenew in the background but within the current session.
105 When using this option, consider also using -L to report krenew
107 errors to syslog.
108 -c child pid file
110 Save the process ID (PID) of the child process into child pid file.
111 child pid file is created if it doesn't exist and overwritten if it
112 does exist. This option is only allowed when a command was given
113 on the command line and is most useful in conjunction with -b to
114 allow management of the running child process.
115 Note that, when used with -b, the PID file is written out after
117 krenew is backgrounded and changes its working directory to /, so
118 relative paths for the PID file will be relative to / (probably not
119 what you want).
120 -H minutes
122 Only renew the ticket if it has a remaining lifetime of less than
123 minutes minutes. If either the ticket already has a sufficiently
124 long remaining lifetime or renewal was successful, run the command
125 (if one was specified) or exit immediately with status 0 (if none
126 was). Otherwise, try to renew the ticket so that it will have a
127 remaining lifetime of at least minutes, exit with an error if
128 unsuccessful, and then run the command, if any.
129 If -H is used with -K, krenew will not exit immediately. Instead,
131 the specified remaining lifetime will replace the default value of
132 two minutes, meaning that krenew will ensure, each time it wakes
133 up, that the ticket has a remaining lifetime of the minutes
134 argument. This is an alternative to -a to ensure that tickets
135 always have a certain minimal amount of lifetime remaining.
136 -h Display a usage message and exit.
138 -i Ignore errors in renewing the ticket and keep running. Normally,
140 krenew exits as soon as the ticket cache either disappears or the
141 tickets run out of renewable lifetime. If this flag is given, it
142 will complain about the failure to standard error (unless -b was
143 given) but continue running, waking up to try again after the next
144 check interval (see -K). This is useful if some other process may
145 recreate an expired ticket cache and krenew should stay around and
146 act on that recreated ticket cache once it's present.
147 If the initial ticket cache renew fails, krenew will retry the
149 renewal immediately and then with exponential backoff to once per
150 minute, and keep trying until authentication succeeds or it is
151 killed. The command, if any, will not be started until cache
152 renewal succeeds.
153 This flag is only useful in daemon mode or when a command was
155 given.
156 -K minutes
158 Run in daemon mode to keep a ticket alive indefinitely. The
159 program reawakens after minutes minutes, checks if the ticket will
160 expire before or less than two minutes before the next scheduled
161 check, and renews the ticket if needed. (In other words, it
162 ensures that the ticket will always have a remaining lifetime of at
163 least two minutes.) If the -H flag is also given, the lifetime
164 specified by it replaces the two minute default.
165 If this option is not given but a command was given on the command
167 line, the default interval is 60 minutes (1 hour).
168 If an error occurs in refreshing the ticket cache that doesn't
170 cause krenew to exit, the wake-up interval will be shortened to one
171 minute and the operation retried at that interval for as long as
172 the error persists.
173 -k ticket cache
175 Use ticket cache as the ticket cache rather than the contents of
176 the environment variable KRB5CCNAME or the library default. ticket
177 cache may be any ticket cache identifier recognized by the
178 underlying Kerberos libraries. This generally supports a path to a
179 file, with or without a leading "FILE:" string, but may also
180 support other ticket cache types.
181 -L Report messages to syslog as well as to standard output or standard
183 error. All messages will be logged with facility LOG_DAEMON.
184 Regular messages that are displayed on standard output are logged
185 with level LOG_NOTICE. Errors that don't cause krenew to terminate
186 when run with -i are logged with level LOG_WARNING. Fatal errors
187 are logged with level LOG_ERR.
188 This is useful when debugging problems in combination with -b.
190 -p pid file
192 Save the process ID (PID) of the running krenew process into pid
193 file. pid file is created if it doesn't exist and overwritten if
194 it does exist. This option is most useful in conjunction with -b
195 to allow management of the running krenew daemon.
196 Note that, when used with -b the PID file is written out after
198 krenew is backgrounded and changes its working directory to /, so
199 relative paths for the PID file will be relative to / (probably not
200 what you want).
201 -s Normally, when krenew exits abnormally while running a command (if,
203 for example, the ticket's renewable lifetime has expired), it
204 leaves the command running. If -s is given, it will send a SIGHUP
205 signal to the command before exiting. This can be useful if it's
206 pointless for the command to keep running without Kerberos tickets.
207 -t Run an external program after getting a ticket. The intended use
209 of this is to run aklog to get a token. If the environment
210 variable AKLOG (or KINIT_PROG for backward compatibility) is set,
211 it overrides the compiled-in default.
212 If a command was given on the command line, krenew will attempt to
214 isolate the AFS credentials for that command from the invoking
215 process. There are two possible ways in which this is done.
216 First, if krenew has been built with AFS setpag() support and AFS
218 is available, krenew will create a new PAG before running the
219 external program.
220 Otherwise, if either krenew was not built with AFS setpag() support
222 or AFS is not available, but the Linux kafs module is available and
223 krenew was built with libkeyutils support, it will create a new
224 session keyring and link it to the current user keyring before
225 running the external program.
226 If neither of these conditions are true, krenew will run the
228 external program without doing any credential isolation, which may
229 also affect the credentials of the invoking process.
230 -v Be verbose. This will print out a bit of additional information
232 about what is being attempted and what the results are.
233 -x Exit immediately on any error. Normally, when running a command or
235 when run with the -K option, krenew keeps running even if it fails
236 to renew the ticket cache as long as the ticket cache still exists
237 and appears to be renewable. It tries again at the next check
238 interval. With this option, krenew will instead exit.
239
241 The program normally exits with status 0 if it successfully renews a
242 ticket. If krenew runs aklog or some other program krenew returns the
243 exit status of that program if it exits normally. If the program exits
244 abnormally due to a signal, krenew will exit with a status of 128 plus
245 the signal number. (This matches the behavior of bash.).
246
248 Renew the current ticket-granting ticket.
249 krenew
251 Wake up every ten minutes and check to see if the ticket cache needs
253 renewing. If it does, re-run aklog as well.
254 krenew -K 10 -t
256 Run the program /usr/local/bin/compute-job in the background, checking
258 every hour to see if the ticket needs to be renewed (the default). Put
259 the PID of the krenew job in /var/run/compute.pid. Obtain a new AFS
260 token each time the ticket has to be renewed.
261 krenew -b -t -p /var/run/compute.pid /usr/local/bin/compute-job
263 If you wanted to pass options to /usr/local/bin/compute-job, putting a
265 "--" argument before it would be necessary to keep krenew from
266 interpreting those options as its own.
267 If you want to redirect output to a file that requires authentication
269 to write to, you will need to do that redirection in a sub-shell. In
270 other words, the following command:
271 krenew -t compute-job > /afs/local/data/output
273 won't work if /afs/local/data/output requires an AFS token to write to.
275 The job, while running, will have an AFS token, but the output
276 redirection is done in the parent shell and doesn't benefit from
277 krenew. The above should instead be written as:
278 krenew -t -- sh -c 'compute-job > /afs/local/data/output'
280 With this command, the shell doing the redirection will also be run
282 under krenew and have the benefit of the AFS token it obtains.
283
285 If the environment variable AKLOG is set, its value will be used as the
286 program to run with -t rather than the default complied into krenew.
287 If AKLOG is not set and KINIT_PROG is set, its value will be used
288 instead. KINIT_PROG is honored for backward compatibility but its use
289 is not recommended due to its confusing name.
290 If no ticket file (with -k) or command is specified on the command
292 line, krenew will use the environment variable KRB5CCNAME to determine
293 the location of the the ticket granting ticket. If the -k option is
294 used, KRB5CCNAME will be set to point to the ticket file before running
295 the aklog program or any command given on the command line.
296
298 The default ticket cache is determined by the underlying Kerberos
299 libraries. The default path for aklog is determined at build time, and
300 will normally be whichever of aklog or afslog is found in the user's
301 path.
302
304 krenew was written by Russ Allbery <eagle@eyrie.org>. It was based
305 heavily on k5start by Booker C. Bense, which in turn was based on the
306 k4start code written by Robert Morgan.
307
309 Copyright 2015, 2021 Russ Allbery <eagle@eyrie.org>
310 Copyright 2006, 2008-2012, 2014 The Board of Trustees of the Leland
312 Stanford Junior University
313 Copying and distribution of this file, with or without modification,
315 are permitted in any medium without royalty provided the copyright
316 notice and this notice are preserved. This file is offered as-is,
317 without any warranty.
318 SPDX-License-Identifier: FSFAP
320
322 k5start(1), kinit(1)
323 This program is part of kstart. The current version is available from
325 its web site at <https://www.eyrie.org/~eagle/software/kstart/>.
3264.3 2021-08-31 KRENEW(1)