table of contents
K5START(1) | kstart | K5START(1) |
NAME¶
k5start - Obtain and optionally keep active a Kerberos ticketSYNOPSIS¶
k5start [-bFhLnPqstvx] [-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] [username [command ...]] k5start -U -f keytab [-bFhLnPqstvx] [-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¶
k5start obtains and caches an initial Kerberos 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, 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.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.
- -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.
- -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.
Cannot be used with -K.
- -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 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 k5start to terminate are
logged with level LOG_WARNING. Fatal errors are logged with level LOG_ERR.
- -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).
- -n
- Ignored, present for option compatibility with the now-obsolete 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.
- -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.
- -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.
- -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.
- -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.
- -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, k5start keeps running even if it fails to refresh the ticket cache and will try again at the next check interval. With this option, k5start will instead exit.
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.comDo 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-backupShows 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.comThis 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.pidThis 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¶
kinit(1), krenew(1) The kstart web page at <http://www.eyrie.org/~eagle/software/kstart/> will have the current version of 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.2012-01-07 | 4.1 |