1KRENEW(1)                           kstart                           KRENEW(1)
2
3
4

NAME

6       krenew - Renew a Kerberos ticket
7

SYNOPSIS

9       krenew [-abhiLstvx] [-c child pid file] [-H minutes]
10           [-K minutes] [-k ticket cache] [-p pid file]
11           [command ...]
12

DESCRIPTION

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
24       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
31       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
38       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
43       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
51       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

OPTIONS

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
61           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
65           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
76           This argument is only valid in combination with either -K or a
77           command to run.
78
79       -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
86           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
90           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
95           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
102               (krenew -K 60 &)
103
104           to run krenew in the background but within the current session.
105
106           When using this option, consider also using -L to report krenew
107           errors to syslog.
108
109       -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
116           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
121       -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
130           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
137       -h  Display a usage message and exit.
138
139       -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
148           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
154           This flag is only useful in daemon mode or when a command was
155           given.
156
157       -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
166           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
169           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
174       -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
182       -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
189           This is useful when debugging problems in combination with -b.
190
191       -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
197           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
202       -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
208       -t  Run an external program after getting a ticket.  The default use of
209           this is to run aklog to get a token.  If the environment variable
210           KINIT_PROG is set, it overrides the compiled-in default.
211
212           If krenew has been built with AFS setpag() support and a command
213           was given on the command line, krenew will create a new PAG before
214           obtaining AFS tokens.  Otherwise, it will obtain tokens in the
215           current PAG.
216
217       -v  Be verbose.  This will print out a bit of additional information
218           about what is being attempted and what the results are.
219
220       -x  Exit immediately on any error.  Normally, when running a command or
221           when run with the -K option, krenew keeps running even if it fails
222           to renew the ticket cache as long as the ticket cache still exists
223           and appears to be renewable.  It tries again at the next check
224           interval.  With this option, krenew will instead exit.
225

RETURN VALUES

227       The program normally exits with status 0 if it successfully renews a
228       ticket.  If krenew runs aklog or some other program krenew returns the
229       exit status of that program.
230

EXAMPLES

232       Renew the current ticket-granting ticket.
233
234           krenew
235
236       Wake up every ten minutes and check to see if the ticket cache needs
237       renewing.  If it does, re-run aklog as well.
238
239           krenew -K 10 -t
240
241       Run the program /usr/local/bin/compute-job in the background, checking
242       every hour to see if the ticket needs to be renewed (the default).  Put
243       the PID of the krenew job in /var/run/compute.pid.  Obtain a new AFS
244       token each time the ticket has to be renewed.
245
246           krenew -b -t -p /var/run/compute.pid /usr/local/bin/compute-job
247
248       If you wanted to pass options to /usr/local/bin/compute-job, putting a
249       "--" argument before it would be necessary to keep krenew from
250       interpreting those options as its own.
251
252       If you want to redirect output to a file that requires authentication
253       to write to, you will need to do that redirection in a sub-shell.  In
254       other words, the following command:
255
256           krenew -t compute-job > /afs/local/data/output
257
258       won't work if /afs/local/data/output requires an AFS token to write to.
259       The job, while running, will have an AFS token, but the output
260       redirection is done in the parent shell and doesn't benefit from
261       krenew.  The above should instead be written as:
262
263           krenew -t -- sh -c 'compute-job > /afs/local/data/output'
264
265       With this command, the shell doing the redirection will also be run
266       under krenew and have the benefit of the AFS token it obtains.
267

ENVIRONMENT

269       If the environment variable AKLOG is set, its value will be used as the
270       program to run with -t rather than the default complied into krenew.
271       If AKLOG is not set and KINIT_PROG is set, its value will be used
272       instead.  KINIT_PROG is honored for backward compatibility but its use
273       is not recommended due to its confusing name.
274
275       If no ticket file (with -k) or command is specified on the command
276       line, krenew will use the environment variable KRB5CCNAME to determine
277       the location of the the ticket granting ticket.  If the -k option is
278       used, KRB5CCNAME will be set to point to the ticket file before running
279       the aklog program or any command given on the command line.
280

FILES

282       The default ticket cache is determined by the underlying Kerberos
283       libraries.  The default path for aklog is determined at build time, and
284       will normally be whichever of aklog or afslog is found in the user's
285       path.
286

AUTHORS

288       krenew was written by Russ Allbery <eagle@eyrie.org>.  It was based
289       heavily on k5start by Booker C. Bense, which in turn was based on the
290       k4start code written by Robert Morgan.
291
293       Copyright 2015 Russ Allbery <eagle@eyrie.org>
294
295       Copyright 2006, 2008, 2009, 2010, 2011, 2012, 2014 The Board of
296       Trustees of the Leland Stanford Junior University
297
298       Copying and distribution of this file, with or without modification,
299       are permitted in any medium without royalty provided the copyright
300       notice and this notice are preserved.  This file is offered as-is,
301       without any warranty.
302

SEE ALSO

304       k5start(1), kinit(1)
305
306       The kstart web page at <http://www.eyrie.org/~eagle/software/kstart/>
307       will have the current version of krenew.
308
309
310
3114.2                               2015-12-26                         KRENEW(1)
Impressum