NAME
k5start - Obtain and optionally keep active a Kerberos v5 ticket.
SYNOPSIS
k5start [-bFhLnPqstv] [-c child pid file] [-f keytab]
[-g group] [-H minutes] [-I service instance]
[-i client instance] [-K minutes] [-k ticket file]
[-l time string] [-m mode] [-o owner]
[-p pid file] [-r service realm] [-S service name]
[-u client principal] [username [command ...]]
k5start -U -f keytab [-bFhLnPqstv] [-c child pid file]
[-g group] [-H minutes] [-I service instance]
[-K minutes] [-k ticket file] [-l time string]
[-m mode] [-o owner] [-p pid file]
[-r service realm] [-S service name] [command ...]
DESCRIPTION
k5start obtains and caches an initial Kerberos v5 ticket-granting
ticket for a principal. k5start can be used as an alternative to
kinit, but it is primarily intended to be used by programs that want to
use a keytab to obtain Kerberos credentials, such as a web server that
needs to authenticate to another service such as an LDAP server.
Normally, the principal for which to give tickets should be specified
as the first argument. username 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. If no
username 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, 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.
If a running k5start 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 k5start will be running and can only be used if a
keytab is specified with -f. k5start will not background itself
until after it does the initial authentication, 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
k4start 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.
If this option is used with a command or with the -K option, there
may be a short window after each authentication during which the
group ownership of the cache will be the default group of the
k5start process.
-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. Cannot be used with -K.
If -H is used with -t, the external program will always be run even
if a ticket with a sufficient remaining lifetime was found.
-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. If this option is not
given but a command was given on the command line, an interval
appropriate for the ticket lifetime will be used.
-k ticket file
Use ticket file as the ticket cache rather than the contents of the
environment variable KRB5CCNAME or the library default. Using this
option forces a file-based ticket cache. If you wish to use a
different type of ticket cache, don’t specify -k and instead set
KRB5CCNAME to the designator of the cache you wish to use.
-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 k5start to
terminate are logged with level LOG_WARNING. Fatal errors are
logged with level LOG_ERR.
This is useful when debugging problems in combination with -b.
-l time string
Set the ticket lifetime. time string should be in a format
recognized by the Kerberos libraries for specifying times, such as
"10h" (ten hours) or "10m" (ten minutes). Known units are "s",
"m", "h", and "d". For more information, see kinit(1).
-m mode
After creating the ticket cache, change its file permissions to
mode, which must be a file mode in octal (640 or 444, for example).
If this option is used with a command or with the -K option, there
may be a short window after each authentication during which the
file permissions of the ticket cache will be 600. Setting a mode
that does not allow k5start to read or write to the ticket cache
will cause k5start to fail and exit when using the -K option or
running a command.
-n Ignored, present for option compatibility with k4start.
-o owner
After creating the ticket cache, change its ownership to owner,
which may be either the name of a user or a numeric user ID. If
owner is the name of a user and -g was not also given, also change
the group ownership of the ticket cache to the default group for
that user.
If this option is used with a command or with the -K option, there
may be a short window after each authentication during which the
ownership of the cache will be the user the k5start process is
running as.
-P Do not get proxiable tickets even if the local configuration says
to get proxiable tickets by default. Without this flag, k5start
does whatever the library default is.
-p pid file
Save the process ID (PID) of the running k5start 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 k5start daemon.
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).
-q Quiet. Suppresses the printing of the initial banner message
saying what Kerberos principal tickets are being obtained for, and
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 for which k5start is getting a service
ticket. The default value is "krbtgt", to obtain a ticket-granting
ticket. This option (along with -I) may be used if one only needs
access to a single service. Note that unlike the client principal,
a non-default service principal must be specified with both -S and
-I; one cannot provide the instance portion as part of the argument
to -S.
-s Read 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. Most uses of this
option are a security risk. You normally want to use a keytab and
the -f option instead.
-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.
If k5start has been built with AFS setpag() support and a command
was given on the command line, k5start will create a new PAG before
obtaining AFS tokens. Otherwise, it will obtain tokens in the
current PAG.
-U Rather than requiring the authentication principal be given on the
command line, read it from the keytab specified with -f. The
principal will be taken from the first entry in the keytab. -f
must be specified if this option is used.
When -U is given, k5start will not expect a principal name to be
given on the command line, and any arguments after the options will
be taken as a command to run.
-u client principal
This specifies the principal to obtain credentials as. The entire
principal may be specified here, or alternatively just the first
portion may be specified with this flag and the instance specified
with -i.
Note that there’s normally no reason to use this flag rather than
simply giving the principal on the command line as the first
regular argument.
-v Be verbose. This will print out a bit of additional information
about what is being attempted and what the results are.
RETURN VALUES
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.
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 using the default ticket cache and run the command
/usr/local/bin/auth-backup. k5start will continue running until the
command finishes.
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 to keep k5start from parsing the
"-c" as its own option.
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.
Starts k5start as a daemon using the Debian start-stop-daemon
management program. This is the sort of line that one 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.
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 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.
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 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.
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.
SEE ALSO
k4start(1), kinit(1), krenew(1)
The kstart web page at <http://www.eyrie.org/~eagle/software/kstart/>
will have the current version of k4start, k5start, and krenew.
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 <rra@stanford.edu>.
Implementations of -b and -p and the example for a Debian init script
are based on code contributed by Navid Golpayegani.