.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.40)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
.    \" fudge factors for nroff and troff
.if n \{\
.    ds #H 0
.    ds #V .8m
.    ds #F .3m
.    ds #[ \f1
.    ds #] \fP
.\}
.if t \{\
.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
.    ds #V .6m
.    ds #F 0
.    ds #[ \&
.    ds #] \&
.\}
.    \" simple accents for nroff and troff
.if n \{\
.    ds ' \&
.    ds ` \&
.    ds ^ \&
.    ds , \&
.    ds ~ ~
.    ds /
.\}
.if t \{\
.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
.    \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
.    \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
.    \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
.    ds : e
.    ds 8 ss
.    ds o a
.    ds d- d\h'-1'\(ga
.    ds D- D\h'-1'\(hy
.    ds th \o'bp'
.    ds Th \o'LP'
.    ds ae ae
.    ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "K5START 1"
.TH K5START 1 "2021-08-31" "4.3" "kstart"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
k5start \- Obtain and optionally keep active a Kerberos ticket
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
\&\fBk5start\fR [\fB\-abFhLnPqstvx\fR] [\fB\-c\fR \fIchild pid file\fR] [\fB\-f\fR \fIkeytab\fR]
    [\fB\-g\fR \fIgroup\fR] [\fB\-H\fR \fIminutes\fR] [\fB\-I\fR \fIservice instance\fR]
    [\fB\-i\fR \fIclient instance\fR] [\fB\-K\fR \fIminutes\fR] [\fB\-k\fR \fIticket cache\fR]
    [\fB\-l\fR \fItime string\fR] [\fB\-m\fR \fImode\fR] [\fB\-o\fR \fIowner\fR]
    [\fB\-p\fR \fIpid file\fR] [\fB\-r\fR \fIservice realm\fR] [\fB\-S\fR \fIservice name\fR]
    [\fB\-u\fR \fIclient principal\fR] [\fIprincipal\fR [\fIcommand\fR ...]]
.PP
\&\fBk5start\fR \fB\-U\fR \fB\-f\fR \fIkeytab\fR [\fB\-abFhLnPqstvx\fR] [\fB\-c\fR \fIchild pid file\fR]
    [\fB\-g\fR \fIgroup\fR] [\fB\-H\fR \fIminutes\fR] [\fB\-I\fR \fIservice instance\fR]
    [\fB\-K\fR \fIminutes\fR] [\fB\-k\fR \fIticket cache\fR] [\fB\-l\fR \fItime string\fR]
    [\fB\-m\fR \fImode\fR] [\fB\-o\fR \fIowner\fR] [\fB\-p\fR \fIpid file\fR]
    [\fB\-r\fR \fIservice realm\fR] [\fB\-S\fR \fIservice name\fR] [\fIcommand\fR ...]
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
\&\fBk5start\fR obtains and caches an initial Kerberos ticket-granting ticket
for a principal.  \fBk5start\fR can be used as an alternative to \fBkinit\fR,
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 \s-1LDAP\s0 server.
.PP
Normally, the principal for which to give tickets should be specified as
the first argument.  \fIprincipal\fR may be either just a principal name
(including the optional instance) or a full principal and realm string.
The \fB\-u\fR and \fB\-i\fR options can be used as an alternative mechanism for
specifying the principal, but generally aren't as convenient.  If no
principal is given as either the first argument or the argument to the
\&\fB\-u\fR option, the client principal defaults to the Unix username of the
user running \fBk5start\fR in the default local realm.
.PP
Optionally, a command may be given on the command line of \fBk5start\fR.  If
so, that command is run after Kerberos authentication (and running
\&\fBaklog\fR if desired), with the appropriate environment variables set to
point it to the right ticket cache.  \fBk5start\fR 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 \fB\-K\fR
option.)  To run in this mode, the principal must either be specified as a
regular command-line argument or via the \fB\-U\fR option; the \fB\-u\fR and \fB\-i\fR
options may not be used.  Also, a keytab must be specified with \fB\-f\fR to
run a specific command.
.PP
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 \f(CW\*(C`sh \-c
\&\f(CIcommand\f(CW\*(C'\fR as the command to run and quote \fIcommand\fR.
.PP
If the command contains command-line options (like \f(CW\*(C`\-c\*(C'\fR), put \*(-- on the
command line before the beginning of the command to tell \fBk5start\fR to not
parse those options as its own.
.PP
When running a command, \fBk5start\fR propagates \s-1HUP, TERM, INT,\s0 and \s-1QUIT\s0
signals to the child process and does not exit when those signals are
received.  (If the propagated signal causes the child process to exit,
\&\fBk5start\fR will then exit.)  This allows \fBk5start\fR to react properly when
run under a command supervision system such as \fBrunit\fR\|(8) or \fBsvscan\fR\|(8) that
uses signals to control supervised commands, and to run interactive
commands that should receive Ctrl-C.
.PP
If a running \fBk5start\fR receives an \s-1ALRM\s0 signal, it immediately refreshes
the ticket cache regardless of whether it is in danger of expiring.
.PP
If \fBk5start\fR is run with a command or the \fB\-K\fR flag and the \fB\-x\fR 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.
.SH "OPTIONS"
.IX Header "OPTIONS"
.IP "\fB\-a\fR" 4
.IX Item "-a"
When run with either the \fB\-K\fR flag or a command, always renew tickets
each time \fBk5start\fR wakes up.  Without this option, \fBk5start\fR will only
try to renew a ticket as often as necessary to prevent the ticket from
expiring.  With this option, \fBk5start\fR will renew tickets according to
the interval specified with the \fB\-K\fR flag.
.Sp
This behavior probably should have been the default behavior of \fB\-K\fR.
The default was not changed to avoid changes for existing users, but for
new applications, consider always using \fB\-a\fR with \fB\-K\fR.
.Sp
This option is important if another program is manipulating the ticket
cache that \fBk5start\fR is using.  For example, if another program is
automatically renewing a ticket more frequently than \fBk5start\fR, then
\&\fBk5start\fR will never see a ticket that is close to expiring and will
therefore, by default, never try to renew the ticket.  This means that
\&\fBk5start\fR will also never renew \s-1AFS\s0 tokens, even if the \fB\-t\fR option was
given, since \fBk5start\fR only renews \s-1AFS\s0 tokens after it successfully
renews a ticket.  If this option is specified in such a situation,
\&\fBk5start\fR will renew its ticket every time it checks the ticket, so \s-1AFS\s0
tokens will be renewed.
.Sp
This argument is only valid in combination with either \fB\-K\fR or a command
to run.
.IP "\fB\-b\fR" 4
.IX Item "-b"
After starting, detach from the controlling terminal and run in the
background.  This option only makes sense in combination with \fB\-K\fR or a
command that \fBk5start\fR will be running and can only be used if a keytab
is specified with \fI\-f\fR.  \fBk5start\fR 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 \fI/dev/null\fR and no
subsequent errors will be reported.
.Sp
If this flag is given, \fBk5start\fR will also change directories to \f(CW\*(C`/\*(C'\fR.
All paths (such as to a command to run or a \s-1PID\s0 file) should therefore be
given as absolute, not relative, paths.
.Sp
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
\&\fI/dev/null\fR.  It will have to report any errors via some other mechanism
for the errors to be seen.
.Sp
Note that on Mac \s-1OS X,\s0 the default ticket cache type is per-session and
using the \fB\-b\fR flag will disassociate \fBk5start\fR from the existing ticket
cache.  When using \fB\-b\fR in conjunction with \fB\-K\fR on Mac \s-1OS X,\s0 you
probably also want to use the \fB\-k\fR flag to specify a ticket cache file
and force the use of a file cache.
.Sp
When using this option, consider also using \fB\-L\fR to report \fBk5start\fR
errors to syslog.
.IP "\fB\-c\fR \fIchild pid file\fR" 4
.IX Item "-c child pid file"
Save the process \s-1ID\s0 (\s-1PID\s0) of the child process into \fIchild pid file\fR.
\&\fIchild pid file\fR 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 \fB\-b\fR to allow
management of the running child process.
.Sp
Note that, when used with \fB\-b\fR, the \s-1PID\s0 file is written out after
\&\fBk5start\fR is backgrounded and changes its working directory to \fI/\fR, so
relative paths for the \s-1PID\s0 file will be relative to \fI/\fR (probably not
what you want).
.IP "\fB\-F\fR" 4
.IX Item "-F"
Do not get forwardable tickets even if the local configuration says to get
forwardable tickets by default.  Without this flag, \fBk5start\fR does
whatever the library default is.
.IP "\fB\-f\fR \fIkeytab\fR" 4
.IX Item "-f keytab"
Authenticate using the keytab \fIkeytab\fR rather than asking for a
password.  A key for the client principal must be present in \fIkeytab\fR.
.IP "\fB\-g\fR \fIgroup\fR" 4
.IX Item "-g group"
After creating the ticket cache, change its group ownership to \fIgroup\fR,
which may be either the name of a group or a numeric group \s-1ID.\s0  Ticket
caches are created with \f(CW0600\fR permissions by default, so this will have
no useful effect unless used with \fB\-m\fR.
.IP "\fB\-H\fR \fIminutes\fR" 4
.IX Item "-H minutes"
Check for a happy ticket, defined as one that has a remaining lifetime of
at least \fIminutes\fR 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.
.Sp
If \fB\-H\fR is used with \fB\-t\fR, the external program will always be run even
if a ticket with a sufficient remaining lifetime was found.
.Sp
If \fB\-H\fR is used with \fB\-K\fR, \fBk5start\fR will not exit immediately.
Instead, the specified remaining lifetime will replace the default value
of two minutes, meaning that \fBk5start\fR will ensure, each time it wakes
up, that the ticket has a remaining lifetime of the \fIminutes\fR argument.
This is an alternative to \fB\-a\fR to ensure that tickets always have a
certain minimal amount of lifetime remaining.
.IP "\fB\-h\fR" 4
.IX Item "-h"
Display a usage message and exit.
.IP "\fB\-I\fR \fIservice instance\fR" 4
.IX Item "-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 \fB\-I\fR and \fB\-S\fR; one
cannot provide the instance portion as part of the argument to \fB\-S\fR.
.IP "\fB\-i\fR \fIclient instance\fR" 4
.IX Item "-i client instance"
Specifies the instance portion of the principal.  This option doesn't make
sense except in combination with \fB\-u\fR.  Note that the instance can be
specified as part of \fIusername\fR through the normal convention of
appending a slash and then the instance, so one never has to use this
option.
.IP "\fB\-K\fR \fIminutes\fR" 4
.IX Item "-K minutes"
Run in daemon mode to keep a ticket alive indefinitely.  The program
reawakens after \fIminutes\fR 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 \fB\-H\fR
flag is also given, the lifetime specified by it replaces the two minute
default.
.Sp
If this option is not given but a command was given on the command line,
the default interval is 60 minutes (1 hour).
.Sp
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.
.IP "\fB\-k\fR \fIticket cache\fR" 4
.IX Item "-k ticket cache"
Use \fIticket cache\fR as the ticket cache rather than the contents of the
environment variable \s-1KRB5CCNAME\s0 or the library default.  \fIticket cache\fR
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 \f(CW\*(C`FILE:\*(C'\fR string, but may also support other ticket cache types.
.Sp
If any of \fB\-o\fR, \fB\-g\fR, or \fB\-m\fR are given, \fIticket cache\fR must be either
a simple path to a file or start with \f(CW\*(C`FILE:\*(C'\fR or \f(CW\*(C`WRFILE:\*(C'\fR.
.IP "\fB\-L\fR" 4
.IX Item "-L"
Report messages to syslog as well as to standard output or standard error.
All messages will be logged with facility \s-1LOG_DAEMON.\s0  Regular messages
that are displayed on standard output are logged with level \s-1LOG_NOTICE.\s0
Errors that don't cause \fBk5start\fR to terminate are logged with level
\&\s-1LOG_WARNING.\s0  Fatal errors are logged with level \s-1LOG_ERR.\s0
.Sp
This is useful when debugging problems in combination with \fB\-b\fR.
.IP "\fB\-l\fR \fItime string\fR" 4
.IX Item "-l time string"
Set the ticket lifetime.  \fItime string\fR should be in a format recognized
by the Kerberos libraries for specifying times, such as \f(CW\*(C`10h\*(C'\fR (ten hours)
or \f(CW\*(C`10m\*(C'\fR (ten minutes).  Known units are \f(CW\*(C`s\*(C'\fR, \f(CW\*(C`m\*(C'\fR, \f(CW\*(C`h\*(C'\fR, and \f(CW\*(C`d\*(C'\fR.  For
more information, see \fBkinit\fR\|(1).
.IP "\fB\-m\fR \fImode\fR" 4
.IX Item "-m mode"
After creating the ticket cache, change its file permissions to \fImode\fR,
which must be a file mode in octal (\f(CW640\fR or \f(CW444\fR, for example).
.Sp
Setting a \fImode\fR that does not allow \fBk5start\fR to read or write to the
ticket cache will cause \fBk5start\fR to fail and exit when using the \fB\-K\fR
option or running a command.
.IP "\fB\-n\fR" 4
.IX Item "-n"
Ignored, present for option compatibility with the now-obsolete
\&\fBk4start\fR.
.IP "\fB\-o\fR \fIowner\fR" 4
.IX Item "-o owner"
After creating the ticket cache, change its ownership to \fIowner\fR, which
may be either the name of a user or a numeric user \s-1ID.\s0  If \fIowner\fR is
the name of a user and \fB\-g\fR was not also given, also change the group
ownership of the ticket cache to the default group for that user.
.IP "\fB\-P\fR" 4
.IX Item "-P"
Do not get proxiable tickets even if the local configuration says to get
proxiable tickets by default.  Without this flag, \fBk5start\fR does whatever
the library default is.
.IP "\fB\-p\fR \fIpid file\fR" 4
.IX Item "-p pid file"
Save the process \s-1ID\s0 (\s-1PID\s0) of the running \fBk5start\fR process into \fIpid
file\fR.  \fIpid file\fR is created if it doesn't exist and overwritten if it
does exist.  This option is most useful in conjunction with \fB\-b\fR to allow
management of the running \fBk5start\fR daemon.
.Sp
Note that, when used with \fB\-b\fR the \s-1PID\s0 file is written out after
\&\fBk5start\fR is backgrounded and changes its working directory to \fI/\fR, so
relative paths for the \s-1PID\s0 file will be relative to \fI/\fR (probably not
what you want).
.IP "\fB\-q\fR" 4
.IX Item "-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 \fB\-s\fR option is given.
.IP "\fB\-r\fR \fIservice realm\fR" 4
.IX Item "-r service realm"
The realm for the service principal.  This defaults to the default local
realm.
.IP "\fB\-S\fR \fIservice name\fR" 4
.IX Item "-S service name"
Specifies the principal for which \fBk5start\fR is getting a service ticket.
The default value is \f(CW\*(C`krbtgt\*(C'\fR, to obtain a ticket-granting ticket.  This
option (along with \fB\-I\fR) 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 \fB\-S\fR and \fB\-I\fR; one cannot provide
the instance portion as part of the argument to \fB\-S\fR.
.IP "\fB\-s\fR" 4
.IX Item "-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 \fB\-f\fR option instead.
.IP "\fB\-t\fR" 4
.IX Item "-t"
Run an external program after getting a ticket.  The intended use of this
is to run \fBaklog\fR to get a token.  If the environment variable \s-1AKLOG\s0 (or
\&\s-1KINIT_PROG\s0 for backward compatibility) is set, it overrides the
compiled-in default.
.Sp
If a command was given on the command line, \fBk5start\fR will attempt to
isolate the \s-1AFS\s0 credentials for that command from the invoking process.
There are two possible ways in which this is done.
.Sp
First, if \fBk5start\fR has been built with \s-1AFS\s0 \fBsetpag()\fR support and \s-1AFS\s0 is
available, \fBk5start\fR will create a new \s-1PAG\s0 before running the external
program.
.Sp
Otherwise, if either \fBk5start\fR was not built with \s-1AFS\s0 \fBsetpag()\fR support or
\&\s-1AFS\s0 is not available, but the Linux kafs module is available and
\&\fBk5start\fR 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.
.Sp
If neither of these conditions are true, \fBk5start\fR will run the external
program without doing any credential isolation, which may also affect the
credentials of the invoking process.
.IP "\fB\-U\fR" 4
.IX Item "-U"
Rather than requiring the authentication principal be given on the command
line, read it from the keytab specified with \fB\-f\fR.  The principal will be
taken from the first entry in the keytab.  \fB\-f\fR must be specified if this
option is used.
.Sp
When \fB\-U\fR is given, \fBk5start\fR 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.
.IP "\fB\-u\fR \fIclient principal\fR" 4
.IX Item "-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 \fB\-i\fR.
.Sp
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.
.IP "\fB\-v\fR" 4
.IX Item "-v"
Be verbose.  This will print out a bit of additional information about
what is being attempted and what the results are.
.IP "\fB\-x\fR" 4
.IX Item "-x"
Exit immediately on any error.  Normally, when running a command or when
run with the \fB\-K\fR option, \fBk5start\fR keeps running even if it fails to
refresh the ticket cache and will try again at the next check interval.
With this option, \fBk5start\fR will instead exit.
.SH "EXIT STATUS"
.IX Header "EXIT STATUS"
The program exits with status 0 if it successfully gets a ticket or has a
happy ticket (see \fB\-H\fR).  If \fBk5start\fR runs aklog or some other program
\&\fBk5start\fR returns the exit status of that program if it exits normally.
If the program exits abnormally due to a signal, \fBk5start\fR will exit with
a status of 128 plus the signal number.  (This matches the behavior of
\&\fBbash\fR.)
.SH "EXAMPLE"
.IX Header "EXAMPLE"
Use the \fI/etc/krb5.keytab\fR keytab to obtain a ticket granting ticket for
the principal host/example.com, putting the ticket cache in
\&\fI/tmp/service.tkt\fR.  The lifetime is 10 hours and the program wakes up
every 10 minutes to check if the ticket is about to expire.
.PP
.Vb 2
\&    k5start \-k /tmp/service.tkt \-f /etc/krb5.keytab \-K 10 \-l 10h \e
\&        host/example.com
.Ve
.PP
Do the same, but using the default ticket cache and run the command
\&\fI/usr/local/bin/auth\-backup\fR.  \fBk5start\fR will continue 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 \fBk5start\fR start before the network is completely set
up.
.PP
.Vb 2
\&    k5start \-f /etc/krb5.keytab \-K 10 \-l 10h host/example.com \e
\&        /usr/local/bin/auth\-backup
.Ve
.PP
Shows the permissions of the temporary cache file created by \fBk5start\fR:
.PP
.Vb 2
\&    k5start \-f /etc/krb5.keytab host/example.com \e
\&        \-\- sh \-c \*(Aqls \-l $KRB5CCNAME\*(Aq
.Ve
.PP
Notice the \f(CW\*(C`\-\-\*(C'\fR before the command to keep \fBk5start\fR from parsing the
\&\f(CW\*(C`\-c\*(C'\fR as its own option.
.PP
Do the same thing, but determine the principal from the keytab:
.PP
.Vb 1
\&    k5start \-f /etc/krb5.keytab \-U \-\- sh \-c \*(Aqls \-l $KRB5CCNAME\*(Aq
.Ve
.PP
Note that no principal is given before the command.
.PP
Starts \fBk5start\fR as a daemon using the Debian \fBstart-stop-daemon\fR
management program.  This is the sort of line that one could put into a
Debian init script:
.PP
.Vb 3
\&    start\-stop\-daemon \-\-start \-\-pidfile /var/run/k5start.pid \e
\&        \-\-exec /usr/local/bin/k5start \-\- \-b \-p /var/run/k5start.pid \e
\&        \-f /etc/krb5.keytab host/example.com
.Ve
.PP
This uses \fI/var/run/k5start.pid\fR as the \s-1PID\s0 file and obtains
host/example.com tickets from the system keytab file.  \fBk5start\fR would
then be stopped with:
.PP
.Vb 2
\&    start\-stop\-daemon \-\-stop \-\-pidfile /var/run/k5start.pid
\&    rm \-f /var/run/k5start.pid
.Ve
.PP
This code could be added to an init script for Apache, for example, to
start a \fBk5start\fR process alongside Apache to manage its Kerberos
credentials.
.SH "ENVIRONMENT"
.IX Header "ENVIRONMENT"
If the environment variable \s-1AKLOG\s0 is set, its value will be used as the
program to run with \fB\-t\fR rather than the default complied into
\&\fBk5start\fR.  If \s-1AKLOG\s0 is not set and \s-1KINIT_PROG\s0 is set, its value will be
used instead.  \s-1KINIT_PROG\s0 is honored for backward compatibility but its
use is not recommended due to its confusing name.
.PP
If no ticket file (with \fB\-k\fR) or command is specified on the command
line, \fBk5start\fR will use the environment variable \s-1KRB5CCNAME\s0 to determine
the location of the the ticket granting ticket.  If either a command is
specified or the \fB\-k\fR option is used, \s-1KRB5CCNAME\s0 will be set to point to
the ticket file before running the \fBaklog\fR program or any command given
on the command line.
.SH "FILES"
.IX Header "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 \fBaklog\fR or \fBafslog\fR is found in the user's
path.
.PP
If a command is specified and \fB\-k\fR was not given, \fBk5start\fR will create
a temporary ticket cache file of the form \f(CW\*(C`/tmp/krb5cc_%d_%s\*(C'\fR where \f(CW%d\fR is
the \s-1UID\s0 \fBk5start\fR is running as and \f(CW%s\fR is a random string.
.SH "AUTHORS"
.IX Header "AUTHORS"
\&\fBk5start\fR 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>.
.PP
Implementations of \fB\-b\fR and \fB\-p\fR and the example for a Debian init
script are based on code contributed by Navid Golpayegani.
.SH "COPYRIGHT AND LICENSE"
.IX Header "COPYRIGHT AND LICENSE"
Copyright 2015, 2021 Russ Allbery <eagle@eyrie.org>
.PP
Copyright 2002, 2004\-2012, 2014 The Board of Trustees of the Leland
Stanford Junior University
.PP
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.
.PP
SPDX-License-Identifier: \s-1FSFAP\s0
.SH "SEE ALSO"
.IX Header "SEE ALSO"
\&\fBkinit\fR\|(1), \fBkrenew\fR\|(1)
.PP
This program is part of kstart.  The current version is available from its
web site at <https://www.eyrie.org/~eagle/software/kstart/>.