table of contents
KRENEW(1) | kstart | KRENEW(1) |
NAME¶
krenew - Renew a Kerberos ticketSYNOPSIS¶
krenew [-bhiLstvx] [-c child pid file] [-H minutes][ -K minutes] [-k ticket cache] [-p pid file]
[ command ...]
DESCRIPTION¶
krenew renews an existing renewable ticket. When run without any arguments, it just attempts to renew the existing ticket-granting ticket in the current ticket cache, equivalent to "kinit -R", but it can optionally run a program like aklog to refresh AFS tokens, can run as a daemon and wake up periodically to renew the ticket cache, or can run a specified command and keep renewing the ticket cache until the command finishes (or renewal is no longer possible). If a command is specified, krenew by default wakes up every 60 minutes (1 hour) to check the ticket cache. If a command is given, krenew makes a copy of the ticket cache and creates a private ticket cache just for that command, thus isolating it from later destruction of the original ticket cache. This allows krenew to maintain authentication for a command even if, for example, the user running the command logs out and OpenSSH destroys their original ticket cache. If a command is given, it will not be run using the shell, so if you want to use shell metacharacters in the command with their special meaning, give "sh -c command" as the command to run and quote command. If the command contains command-line options (like "-c"), put "--" on the command line before the beginning of the command to tell krenew to not parse those options as its own. If krenew is built with setpag() support and AFS tokens are requested with the -t option, it will put the command in a separate PAG before obtaining AFS tokens so that they don't interfere with other processes on the system. When running a command, krenew propagates HUP, TERM, INT, and QUIT signals to the child process and does not exit when those signals are received. (If the propagated signal causes the child process to exit, krenew will then exit.) This allows krenew to react properly when run under a command supervision system such as runit(8) or svscan(8) that uses signals to control supervised commands, and to run interactive commands that should receive Ctrl-C. If a running krenew receives an ALRM signal, it immediately refreshes the ticket cache regardless of whether it is in danger of expiring.OPTIONS¶
- -b
- 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.
(krenew -K 60 &)
- -c child pid file
- Save the process ID (PID) of the child process into
child pid file. child pid file is created if it doesn't
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.
- -H minutes
- 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. Cannot be used with -K.
- -h
- Display a usage message and exit.
- -i
- 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 it's present.
- -K minutes
- 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. If this option is not given but a command
was given on the command line, the default interval is 60 minutes (1
hour).
- -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.
- -L
- 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 don't cause krenew to terminate when
run with -i are logged with level LOG_WARNING. Fatal errors are
logged with level LOG_ERR.
- -p pid file
- Save the process ID (PID) of the running krenew
process into pid file. pid file is created if it
doesn't exist and overwritten if it does exist. This option is most useful
in conjunction with -b to allow management of the running
krenew daemon.
- -s
- Normally, when krenew exits abnormally while running a command (if, for example, the ticket's 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 it's pointless for the command to keep running without Kerberos tickets.
- -t
- 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.
- -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.
RETURN VALUES¶
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.EXAMPLES¶
Renew the current ticket-granting ticket.krenewWake 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 -tRun 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-jobIf 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/outputwon't 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 doesn't 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.
ENVIRONMENT¶
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.FILES¶
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 user's path.SEE ALSO¶
k5start(1), kinit(1) The kstart web page at <http://www.eyrie.org/~eagle/software/kstart/> will have the current version of krenew.AUTHORS¶
krenew was written by Russ Allbery <rra@stanford.edu>. It was based heavily on k5start by Booker C. Bense, which in turn was based on the k4start code written by Robert Morgan.2012-01-07 | 4.1 |