K5START(1)

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

<h1>✨ k5start(1) ✨</h1>

okay bestie, this is k5start from the <code>kstart</code> family of man pages — pull up a chair, grab a boba, we're getting you a Kerberos ticket 🎟️💖

🌸 NAME 🌸

k5start — obtain and optionally keep active a Kerberos ticket 👑

🎀 SYNOPSIS 🎀

k5start [-abFhLnPqstvx] [-c child pid file] [-f keytab]
    [-g group] [-H minutes] [-I service instance]
    [-i client instance] [-K minutes] [-k ticket cache]
    [-l time string] [-m mode] [-o owner]
    [-p pid file] [-r service realm] [-S service name]
    [-u client principal] [principal [command ...]]
k5start -U -f keytab [-abFhLnPqstvx] [-c child pid file]
    [-g group] [-H minutes] [-I service instance]
    [-K minutes] [-k ticket cache] [-l time string]
    [-m mode] [-o owner] [-p pid file]
    [-r service realm] [-S service name] [command ...]

💅 DESCRIPTION 💅

So basically, k5start obtains and caches an initial Kerberos ticket-granting ticket for a principal. 🎫✨

It can be used as an alternative to kinit, but honestly? That's not really the point. Its main character energy is being used by programs that wanna use a keytab to obtain Kerberos credentials — think a web server that needs to authenticate to another service, like an LDAP server. 🔐🖥️

Normally, the principal for which to give tickets should be specified as the first argument. principal may be either just a principal name (including the optional instance) or a full principal and realm string. The -u and -i options can be used as an alternative mechanism for specifying the principal, but generally aren't as convenient ngl. If no principal is given as either the first argument or the argument to the -u option, the client principal defaults to the Unix username of the user running k5start in the default local realm. 🫶

Optionally, a command may be given on the command line of k5start. If so, that command is run after Kerberos authentication (and running aklog if desired), with the appropriate environment variables set to point it to the right ticket cache. k5start will then continue running, waking up periodically to refresh credentials slightly before they would expire, until the command completes. (The frequency with which it wakes up to refresh credentials can still be controlled with the -K option.) To run in this mode, the principal must either be specified as a regular command-line argument or via the -U option; the -u and -i options may not be used. Also, a keytab must be specified with -f to run a specific command. ⚠️

The command 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 k5start to not parse those options as its own. 🚧

When running a command, k5start 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, k5start will then exit.) This allows k5start 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 k5start receives an ALRM signal, it immediately refreshes the ticket cache regardless of whether it is in danger of expiring. ⏰🔥

If k5start is run with a command or the -K flag and the -x flag is not given, it will keep trying even if the initial authentication fails. It will retry the initial authentication 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 authentication succeeds. 🔁🫡

✨ OPTIONS ✨

  • -a — When run with either the -K flag or a command, always renew tickets each time k5start wakes up. Without this option, k5start will only try to renew a ticket as often as necessary to prevent the ticket from expiring. With this option, k5start 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 k5start is using. For example, if another program is automatically renewing a ticket more frequently than k5start, then k5start will never see a ticket that is close to expiring and will therefore, by default, never try to renew the ticket. This means that k5start will also never renew AFS tokens, even if the -t option was given, since k5start only renews AFS tokens after it successfully renews a ticket. If this option is specified in such a situation, k5start 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.

  • -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 k5start will be running and can only be used if a keytab is specified with -f. k5start will not background itself until after it has tried authenticating once, 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, k5start 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. 🕳️

Note that on Mac OS X, the default ticket cache type is per-session and using the -b flag will disassociate k5start from the existing ticket cache. When using -b in conjunction with -K on Mac OS X, you probably also want to use the -k flag to specify a ticket cache file and force the use of a file cache. 🍎

When using this option, consider also using -L to report k5start 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 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 k5start is backgrounded and changes its working directory to /, so relative paths for the PID file will be relative to / (probably not what you want). 😬

  • -F — Do not get forwardable tickets even if the local configuration says to get forwardable tickets by default. Without this flag, k5start does whatever the library default is. 🚫➡️
  • -f keytab — Authenticate using the keytab keytab rather than asking for a password. A key for the client principal must be present in keytab. 🔑
  • -g group — After creating the ticket cache, change its group ownership to group, which may be either the name of a group or a numeric group ID. Ticket caches are created with 0600 permissions by default, so this will have no useful effect unless used with -m. 👥
  • -H minutes — Check for a happy ticket, defined as one that has a remaining lifetime of at least minutes minutes. If such a ticket is found, do not attempt authentication. Instead, just run the command (if one was specified) or exit immediately with status 0 (if none was). Otherwise, try to obtain a new ticket and then run the command, if any. 😊🎟️

If -H is used with -t, the external program will always be run even if a ticket with a sufficient remaining lifetime was found.

If -H is used with -K, k5start will not exit immediately. Instead, the specified remaining lifetime will replace the default value of two minutes, meaning that k5start 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. 👋
  • -I service instance — The instance portion of the service principal. The default is the default realm of the machine. Note that unlike the client principal, a non-default service principal must be specified with -I and -S; one cannot provide the instance portion as part of the argument to -S. 🛠️
  • -i client instance — Specifies the instance portion of the principal. This option doesn't make sense except in combination with -u. Note that the instance can be specified as part of username through the normal convention of appending a slash and then the instance, so one never has to use this option. 🙈
  • -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 after the next scheduled check, and gets a new 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, 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. 🗂️

If any of -o, -g, or -m are given, ticket cache must be either a simple path to a file or start with "FILE:" or "WRFILE:". 📌

  • -L — bestie, this one sends your messages to syslog and to standard output or standard error. Every message gets logged with facility LOG_DAEMON. Regular messages that show up on standard output are logged at level LOG_NOTICE. Errors that don't make k5start peace out are logged at level LOG_WARNING. And fatal errors? Those get level LOG_ERR. 💀

Lowkey this is the move when you're debugging stuff, especially if you're also running with -b.

  • -l time string — sets the ticket lifetime. time string has to be in a format the Kerberos libraries actually recognize for specifying times, like "10h" (that's ten hours, queen) or "10m" (ten minutes). The known units are "s", "m", "h", and "d". Want more deets? Go read kinit(1). ✨
  • -m mode — after it creates the ticket cache, this changes its file permissions to mode, which has to be a file mode in octal (640 or 444, for example, iykyk).
Setting a mode that doesn't let k5start read or write to the ticket cache will make k5start fail and exit when you use the -K option or run a command. Not the vibe you want. 🚫
  • -n — literally ignored. It's just here for option compatibility with the now-obsolete k4start. She's a legacy queen, we keep her around for the nostalgia. 💅
  • -o owner — after creating the ticket cache, change its ownership to owner, which can be either the name of a user or a numeric user ID. Here's the tea: if owner is the name of a user and -g was not also given, it also changes the group ownership of the ticket cache to that user's default group. 🫶
  • -P — do not get proxiable tickets, even if the local configuration says to get proxiable tickets by default. Without this flag, k5start just does whatever the library default is. No thoughts, head empty, library's choice. 🌸
  • -p pid file — saves the process ID (PID) of the running k5start process into pid file. That file gets created if it doesn't exist and overwritten if it does. This one is peak useful when you pair it with -b, so you can actually manage the running k5start daemon like a boss. 👑
Heads up bestie: when you use it with -b, the PID file is written out after k5start is backgrounded and changes its working directory to /. So relative paths for the PID file are relative to / — which is probably not what you want. 😭
  • -q — quiet mode, shhh. 🤫 Suppresses the initial banner message that tells you what Kerberos principal tickets are being obtained for, and it also suppresses the password prompt when the -s option is given.
  • -r service realm — the realm for the service principal. This defaults to the default local realm. 🎀
  • -S service name — specifies the principal that k5start is getting a service ticket for. The default value is "krbtgt", which gets you a ticket-granting ticket. This option (along with -I) is the move if you only need access to a single service. And note this, because it's important: unlike the client principal, a non-default service principal must be specified with both -S and -I — you can't just sneak the instance portion into the argument to -S. Nope. 🙈
  • -s — reads the password from standard input. This bypasses the normal password prompt, which means echo isn't suppressed and input isn't forced to be from the controlling terminal.
Bestie. Most uses of this option are a security risk. 🚨 You normally want to use a keytab and the -f option instead. Fr fr, don't do this casually.
  • -t — run an external program after getting a ticket. The intended use here is running 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, k5start will try to isolate the AFS credentials for that command from the invoking process. There are two possible ways it does this:

  1. First, if k5start was built with AFS setpag() support and AFS is available, k5start will create a new PAG before running the external program.
  2. Otherwise, if either k5start wasn't built with AFS setpag() support or AFS isn't available, but the Linux kafs module is available and k5start was built with libkeyutils support, it'll create a new session keyring and link it to the current user keyring before running the external program.

And if neither of those conditions is true? k5start will run the external program without doing any credential isolation at all — which may also affect the credentials of the invoking process. It's giving chaos, honestly. 💀

  • -U — instead of requiring the authentication principal on the command line, read it from the keytab specified with -f. The principal is taken from the first entry in the keytab. And -f must be specified if you use this option, no exceptions. 🌟

When -U is given, k5start won't expect a principal name on the command line, and any arguments after the options get taken as a command to run. Slay, convenient.

  • -u client principal — specifies the principal to obtain credentials as. You can put the entire principal here, or alternatively just the first portion with this flag and then the instance with -i. Either works. 💖

Note that there's normally no reason to use this flag rather than just giving the principal on the command line as the first regular argument. It's giving redundant but valid.

  • -v — be verbose. This prints out a bit of extra info about what's being attempted and what the results are. Main character energy: k5start narrating its own life. ✨
  • -x — exit immediately on any error. Normally, when running a command or when run with the -K option, k5start keeps going even if it fails to refresh the ticket cache, and it'll try again at the next check interval. With this option, k5start will instead exit. Periodt. 🚪

🚪 EXIT STATUS 🚪

The program exits with status 0 if it successfully gets a ticket or has a happy ticket (see -H). If k5start runs aklog or some other program, k5start returns the exit status of that program if it exits normally. If the program exits abnormally due to a signal, k5start will exit with a status of 128 plus the signal number. (This matches the behavior of bash, iconic behavior honestly.) 🫶

🌈 EXAMPLE 🌈

Use the /etc/krb5.keytab keytab to obtain a ticket granting ticket for the principal host/example.com, putting the ticket cache in /tmp/service.tkt. The lifetime is 10 hours and the program wakes up every 10 minutes to check if the ticket is about to expire. 👑

k5start -k /tmp/service.tkt -f /etc/krb5.keytab -K 10 -l 10h \
    host/example.com

Do the same, but use the default ticket cache and run the command /usr/local/bin/auth-backup. k5start will keep running until the command finishes. If the initial authentication fails, keep trying, and don't start the command until it succeeds. This could be used during system startup for a command that must have valid tickets before starting, and tolerates having k5start start before the network is completely set up. Network's not awake yet? k5start's just gonna wait, patient bestie. 🌸

k5start -f /etc/krb5.keytab -K 10 -l 10h host/example.com \
    /usr/local/bin/auth-backup

Shows the permissions of the temporary cache file created by k5start:

k5start -f /etc/krb5.keytab host/example.com \
    -- sh -c 'ls -l $KRB5CCNAME'

Notice the -- before the command — that's what keeps k5start from parsing the -c as its own option. Sneaky little dash, we love you. 💅

Do the same thing, but determine the principal from the keytab:

k5start -f /etc/krb5.keytab -U -- sh -c 'ls -l $KRB5CCNAME'

Note that no principal is given before the command. That's the whole point. ✨

Starts k5start as a daemon using the Debian start-stop-daemon management program. This is the sort of line you could put into a Debian init script:

start-stop-daemon --start --pidfile /var/run/k5start.pid \
    --exec /usr/local/bin/k5start -- -b -p /var/run/k5start.pid \
    -f /etc/krb5.keytab host/example.com

This uses /var/run/k5start.pid as the PID file and obtains host/example.com tickets from the system keytab file. k5start would then be stopped with:

start-stop-daemon --stop --pidfile /var/run/k5start.pid
rm -f /var/run/k5start.pid

This code could be added to an init script for Apache, for example, to start a k5start process alongside Apache to manage its Kerberos credentials. Apache said "I need valid tickets" and k5start said "say less." 🦋

🌍 ENVIRONMENT 🌍

If the environment variable AKLOG is set, its value will be used as the program to run with -t rather than the default compiled into k5start. 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. Like, girl, why is it called that. 😭

If no ticket file (with -k) or command is specified on the command line, k5start will use the environment variable KRB5CCNAME to determine the location of the ticket granting ticket. If either a command is specified or 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. So it's out here just updating the env for you. Considerate. 💜

📁 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. 🎀

If a command is specified and -k was not given, k5start will create a temporary ticket cache file of the form "/tmp/krb5cc_%d_%s" where %d is the UID k5start is running as and %s is a random string. Random string? She's mysterious, she's unique, she's a temporary cache file. 💅

👑 AUTHORS 👑

k5start was based on the k4start code written by Robert Morgan. It was ported to Kerberos v5 by Booker C. Bense. Additional cleanup and current maintenance are done by Russ Allbery <eagle@eyrie.org>. Thank you for your service, kings. 🫶

Implementations of -b and -p and the example for a Debian init script are based on code contributed by Navid Golpayegani.

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

Copyright 2002, 2004-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 the whole page, bestie! This edition is kstart version 4.3, dated 2021-08-31, and it's the K5START(1) manual — you read the whole thing, no skimming, I'm so proud of you. Go get those tickets. 🎟️💖👑

📦 where this page comes from