When run with either the -K flag or a command, always renew tickets
each time krenew wakes up. Without this option, krenew will only
try to renew a ticket as often as necessary to prevent the ticket from
expiring. With this option, krenew will renew tickets according to
the interval specified with the -K flag.
This behavior probably should have been the default behavior of -K. The default was not changed to avoid changes for existing users, but for new applications, consider always using -a with -K.
This option is important if another program is manipulating the ticket cache that krenew is using. For example, if another program is automatically renewing a ticket more frequently than krenew, then krenew will never see a ticket that is close to expiring and will therefore, by default, never try to renew the ticket. This means that krenew will also never renew AFS tokens, even if the -t option was given, since krenew only renews AFS tokens after it successfully renews a ticket. If this option is specified in such a situation, krenew will renew its ticket every time it checks the ticket, so AFS tokens will be renewed.
This argument is only valid in combination with either -K or a command to run.
After starting, detach from the controlling terminal and run in the
background. This option only makes sense in combination with -K or a
command that krenew will be running. krenew will not background
itself until after it does the initial ticket renewal, so that any initial
errors will be reported, but it will then redirect output to /dev/null
and no subsequent errors will be reported.
If this flag is given, krenew will also change directories to /. All paths (such as to a command to run or a PID file) should therefore be given as absolute, not relative, paths.
If used in conjunction with a command to run, that command will also run in the background and will also have its input and output redirected to /dev/null. It will have to report any errors via some other mechanism for the errors to be seen.
Use of this flag on Mac OS X without specifying a file-based ticket cache by either using -k or setting KRB5CCNAME will probably not do what you want. Ticket caches on Mac OS X are, by default, per-session and with -b krenew will detach itself from your existing ticket cache. Instead, to renew the default ticket cache on Mac OS X, try something like:
to run krenew in the background but within the current session.
When using this option, consider also using -L to report krenew errors to syslog.
|-c child pid file||
Save the process ID (PID) of the child process into child pid file.
child pid file is created if it doesnt exist and overwritten if it
does exist. This option is only allowed when a command was given on the
command line and is most useful in conjunction with -b to allow
management of the running child process.
Note that, when used with -b, the PID file is written out after krenew is backgrounded and changes its working directory to /, so relative paths for the PID file will be relative to / (probably not what you want).
Only renew the ticket if it has a remaining lifetime of less than
minutes minutes. If either the ticket already has a sufficiently long
remaining lifetime or renewal was successful, run the command (if one was
specified) or exit immediately with status 0 (if none was). Otherwise,
try to renew the ticket so that it will have a remaining lifetime of at
least minutes, exit with an error if unsuccessful, and then run the
command, if any.
If -H is used with -K, krenew will not exit immediately. Instead, the specified remaining lifetime will replace the default value of two minutes, meaning that krenew will ensure, each time it wakes up, that the ticket has a remaining lifetime of the minutes argument. This is an alternative to -a to ensure that tickets always have a certain minimal amount of lifetime remaining.
|-h||Display a usage message and exit.|
Ignore errors in renewing the ticket and keep running. Normally,
krenew exits as soon as the ticket cache either disappears or the
tickets run out of renewable lifetime. If this flag is given, it will
complain about the failure to standard error (unless -b was given) but
continue running, waking up to try again after the next check interval
(see -K). This is useful if some other process may recreate an expired
ticket cache and krenew should stay around and act on that recreated
ticket cache once its present.
If the initial ticket cache renew fails, krenew will retry the renewal immediately and then with exponential backoff to once per minute, and keep trying until authentication succeeds or it is killed. The command, if any, will not be started until cache renewal succeeds.
This flag is only useful in daemon mode or when a command was given.
Run in daemon mode to keep a ticket alive indefinitely. The program
reawakens after minutes minutes, checks if the ticket will expire
before or less than two minutes before the next scheduled check, and
renews the ticket if needed. (In other words, it ensures that the ticket
will always have a remaining lifetime of at least two minutes.) If the
-H flag is also given, the lifetime specified by it replaces the two
If this option is not given but a command was given on the command line, the default interval is 60 minutes (1 hour).
If an error occurs in refreshing the ticket cache that doesnt cause krenew to exit, the wake-up interval will be shortened to one minute and the operation retried at that interval for as long as the error persists.
|-k ticket cache||Use ticket cache as the ticket cache rather than the contents of the environment variable KRB5CCNAME or the library default. ticket cache may be any ticket cache identifier recognized by the underlying Kerberos libraries. This generally supports a path to a file, with or without a leading FILE: string, but may also support other ticket cache types.|
Report messages to syslog as well as to standard output or standard error.
All messages will be logged with facility LOG_DAEMON. Regular messages
that are displayed on standard output are logged with level LOG_NOTICE.
Errors that dont cause krenew to terminate when run with -i are
logged with level LOG_WARNING. Fatal errors are logged with level
This is useful when debugging problems in combination with -b.
|-p pid file||
Save the process ID (PID) of the running krenew process into pid
file. pid file is created if it doesnt exist and overwritten if it
does exist. This option is most useful in conjunction with -b to allow
management of the running krenew daemon.
Note that, when used with -b the PID file is written out after krenew is backgrounded and changes its working directory to /, so relative paths for the PID file will be relative to / (probably not what you want).
|-s||Normally, when krenew exits abnormally while running a command (if, for example, the tickets renewable lifetime has expired), it leaves the command running. If -s is given, it will send a SIGHUP signal to the command before exiting. This can be useful if its pointless for the command to keep running without Kerberos tickets.|
Run an external program after getting a ticket. The default use of this
is to run aklog to get a token. If the environment variable KINIT_PROG
is set, it overrides the compiled-in default.
If krenew has been built with AFS setpag() support and a command was given on the command line, krenew will create a new PAG before obtaining AFS tokens. Otherwise, it will obtain tokens in the current PAG.
|-v||Be verbose. This will print out a bit of additional information about what is being attempted and what the results are.|
|-x||Exit immediately on any error. Normally, when running a command or when run with the -K option, krenew keeps running even if it fails to renew the ticket cache as long as the ticket cache still exists and appears to be renewable. It tries again at the next check interval. With this option, krenew will instead exit.|
The program normally exits with status 0 if it successfully renews a ticket. If krenew runs aklog or some other program krenew returns the exit status of that program.
Renew the current ticket-granting ticket.
Wake up every ten minutes and check to see if the ticket cache needs renewing. If it does, re-run aklog as well.
krenew -K 10 -t
Run the program /usr/local/bin/compute-job in the background, checking every hour to see if the ticket needs to be renewed (the default). Put the PID of the krenew job in /var/run/compute.pid. Obtain a new AFS token each time the ticket has to be renewed.
krenew -b -t -p /var/run/compute.pid /usr/local/bin/compute-job
If you wanted to pass options to /usr/local/bin/compute-job, putting a -- argument before it would be necessary to keep krenew from interpreting those options as its own.
If you want to redirect output to a file that requires authentication to write to, you will need to do that redirection in a sub-shell. In other words, the following command:
krenew -t compute-job > /afs/local/data/output
wont work if /afs/local/data/output requires an AFS token to write to. The job, while running, will have an AFS token, but the output redirection is done in the parent shell and doesnt benefit from krenew. The above should instead be written as:
krenew -t -- sh -c compute-job > /afs/local/data/output
With this command, the shell doing the redirection will also be run under krenew and have the benefit of the AFS token it obtains.
If the environment variable AKLOG is set, its value will be used as the program to run with -t rather than the default complied into krenew. If AKLOG is not set and KINIT_PROG is set, its value will be used instead. KINIT_PROG is honored for backward compatibility but its use is not recommended due to its confusing name.
If no ticket file (with -k) or command is specified on the command line, krenew will use the environment variable KRB5CCNAME to determine the location of the the ticket granting ticket. If the -k option is used, KRB5CCNAME will be set to point to the ticket file before running the aklog program or any command given on the command line.
The default ticket cache is determined by the underlying Kerberos libraries. The default path for aklog is determined at build time, and will normally be whichever of aklog or afslog is found in the users path.
krenew was written by Russ Allbery <firstname.lastname@example.org>. It was based heavily on k5start by Booker C. Bense, which in turn was based on the k4start code written by Robert Morgan.
Copyright 2015 Russ Allbery <email@example.com>
Copyright 2006, 2008, 2009, 2010, 2011, 2012, 2014 The Board of Trustees of the Leland Stanford Junior University
Copying and distribution of this file, with or without modification, are permitted in any medium without royalty provided the copyright notice and this notice are preserved. This file is offered as-is, without any warranty.
The kstart web page at <http://www.eyrie.org/~eagle/software/kstart/> will have the current version of krenew.