KRENEW(1)

📦
version 4.3 · 6 versions
, in alpine 3.24, debian bookworm, debian trixie, epel 9, ubuntu jammy, ubuntu noble, ubuntu resolute, ubuntu stonking

💖 NAME 💖

krenew — renew a Kerberos ticket, bestie. that's it, that's the whole vibe check. this page lives in the kstart manual, section 1. ✨

🎀 SYNOPSIS 🎀

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

🦋 DESCRIPTION 🦋

okay so. krenew renews an existing renewable ticket. like, it takes your ticket and gives it a lil glow-up so it stays valid. 💅

Run it with zero arguments and it just tries to renew the existing ticket-granting ticket in the current ticket cache — that's literally equivalent to kinit -R, no cap.

But it's also flexible like that:

  • it can optionally run a program like aklog to refresh AFS tokens 🌸
  • it can run as a daemon and wake up periodically to renew the ticket cache ⏰
  • it can run a specified command and keep renewing the ticket cache until the command finishes (or until renewal is simply no longer possible) 🫶

If a command is specified, krenew by default wakes up every 60 minutes (1 hour) to check the ticket cache. that's the default, periodt.

🔒 the private ticket cache thing (so important)

If a command is given, krenew makes a copy of the ticket cache and creates a private ticket cache just for that command. why? to isolate it from later destruction of the original ticket cache, obviously. 🙈

This is what lets krenew maintain authentication for a command even if, say, the user running the command logs out and OpenSSH destroys their original ticket cache. iconic protective energy honestly. 👑

🐚 shell stuff, listen up

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. 💀 (yes this trips people up constantly)

And if the command contains command-line options (like -c), put -- on the command line before the beginning of the command, so krenew knows not to parse those options as its own. iykyk. 🌈

🌟 PAG + AFS tokens

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 they don't interfere with other processes on the system. considerate fr fr. 🧚

📡 signals, aka the main character energy

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. (tho if the propagated signal causes the child process to exit, krenew will then exit.) 💖

Why does this matter? Because it lets krenew react properly when run under a command supervision system such as runit(8) or svscan(8) — systems that use signals to control supervised commands — and it lets you run interactive commands that should receive Ctrl-C. 🔥

and if a running krenew receives an ALRM signal, it immediately refreshes the ticket cache regardless of whether it is in danger of expiring. instant. no waiting. slay. ✨

to be continued, bestie — more sections coming 🎀

✨ OPTIONS ✨

  • -a — bestie, this one is about always renewing, no chill. When you run with either the -K flag or a command, this makes krenew renew tickets every single time it wakes up. Without it, krenew is on its lazy-girl era and will only try to renew a ticket as often as it has to, just to keep it from expiring. With -a, it renews according to the interval you gave with -K.

This behavior probably should have been the default behavior of -K. The default wasn't changed because they didn't wanna mess with existing users, but for new applications, consider always using -a with -K. 💅

This option matters a LOT if another program is out here manipulating the ticket cache that krenew is using. Say another program is automatically renewing a ticket more often than krenew does — then krenew will never see a ticket that's close to expiring, so by default it will never try to renew the ticket. And that means krenew will also never renew AFS tokens, even if you gave the -t option, because krenew only renews AFS tokens after it successfully renews a ticket. If you specify this option in that kind of situation, krenew will renew its ticket every time it checks the ticket, so AFS tokens will get renewed. 🫶

This argument is only valid in combination with either -K or a command to run.

  • -b — after starting, detach from the controlling terminal and run in the background. This 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 any initial errors will be reported, but then it redirects 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 you use it 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:

(krenew -K 60 &)

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 doesn't exist and overwritten if it does exist. This option is only allowed when a command was given on the command line, and it's most useful in conjunction with -b so you can actually manage 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). 🙈
  • -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.

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 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. Short, sweet, iconic.
  • -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.

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.

  • -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. (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 minute default.

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 doesn't 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.
  • -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.

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 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.
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 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 intended use of this is to run aklog to get a token. If the environment variable AKLOG (or KINIT_PROG for backward compatibility) is set, it overrides the compiled-in default.

If a command was given on the command line, krenew will attempt to isolate the AFS credentials for that command from the invoking process. There are two possible ways in which this is done. 🦋

  • First, if krenew has been built with AFS setpag() support and AFS is available, krenew will create a new PAG before running the external program.
  • Otherwise, if either krenew was not built with AFS setpag() support or AFS is not available, but the Linux kafs module is available and krenew was built with libkeyutils support, it will create a new session keyring and link it to the current user keyring before running the external program.
  • If neither of these conditions are true, krenew will run the external program without doing any credential isolation, which may also affect the credentials of the invoking process.
  • -v — be verbose. This will print out a bit of additional information about what is being attempted and what the results are. She's chatty, we love her. 💖
  • -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.

🌈 EXIT STATUS 🌈

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 if it exits normally. If the program exits abnormally due to a signal, krenew will exit with a status of 128 plus the signal number. (This matches the behavior of bash.) 👑

🌸 EXAMPLES 🌸

okay bestie, this is the part where it all clicks, fr fr. real-life scenarios, let's go 💖

1. renew the ticket you already have

want to renew the current ticket-granting ticket? iconic, no arguments needed:

krenew

2. wake up every ten minutes and check

this one naps for ten minutes at a time, wakes up, checks if the ticket cache needs renewing, and if it does, it re-runs aklog too. multitasking queen ✨

krenew -K 10 -t

3. background job, default hourly check, PID file, fresh AFS token

run /usr/local/bin/compute-job in the background, checking every hour to see if the ticket needs a glow-up (that's the default btw), drop the PID of the krenew job into /var/run/compute.pid, and grab a brand-new AFS token every single time the ticket gets renewed:

krenew -b -t -p /var/run/compute.pid /usr/local/bin/compute-job

4. passing options to the thing you're running

and if you wanted to hand options over to /usr/local/bin/compute-job itself? you'd need to sneak a -- argument in front of it, otherwise krenew is gonna be nosy and interpret those options as its own. rude of it, honestly, but that's just how it is 💅

the redirect plot twist (read this one, it's important) 🫶

if you want to redirect output to a file that needs authentication to write to, you have to do that redirection inside a sub-shell. so like, this command right here:

krenew -t compute-job > /afs/local/data/output

won't work if /afs/local/data/output needs an AFS token to write to. 😭 here's why: the job, while it's running, does have an AFS token — but the output redirection happens in the parent shell, which is not getting any of that krenew magic. the parent shell is just standing there. tokenless. unbothered. useless.

so instead, you write it like this:

krenew -t -- sh -c 'compute-job > /afs/local/data/output'

with this version, the shell doing the redirection is also running under krenew, so it gets the benefit of the AFS token krenew obtains. slay 🎀

🦋 ENVIRONMENT 🦋

these are the env vars krenew is looking at, bestie:

  • if the environment variable AKLOG is set, its value gets used as the program to run with -t, instead of the default compiled into krenew.
  • if AKLOG is not set and KINIT_PROG is set, then KINIT_PROG's value gets used instead.
okay so about KINIT_PROG — it's honored for backward compatibility, but using it is not recommended, because its name is genuinely confusing. like, why is it called that. iykyk 💀

and one more thing: if no ticket file (that's -k) and no command is specified on the command line, krenew will use the environment variable KRB5CCNAME to figure out where the ticket-granting ticket lives. and if the -k option is used, KRB5CCNAME gets set to point at the ticket file before running the aklog program or any command you gave on the command line. so it's all lined up before anything else happens 👑

🎀 FILES 🎀

  • the default ticket cache is determined by the underlying Kerberos libraries (not krenew's call, it just trusts them 🫶).
  • 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.

👑 AUTHORS 👑

krenew was written by Russ Allbery <eagle@eyrie.org>.

it was based heavily on k5start by Booker C. Bense, which in turn was based on the k4start code written by Robert Morgan. a whole lineage, honestly — main character energy passed down through the generations 💜

Copyright 2015, 2021 Russ Allbery <eagle@eyrie.org>

Copyright 2006, 2008-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.

SPDX-License-Identifier: FSFAP

⭐ SEE ALSO ⭐

this program is part of kstart. the current version is available from its web site at <https://www.eyrie.org/~eagle/software/kstart/>.

and that's a wrap on the whole page, bestie!! 🫶 this was krenew, from kstart version 4.3, dated 2021-08-31. go renew something. go get that token. periodt 💅✨

📦 where this page comes from