.\" 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 "KRENEW 1"
.TH KRENEW 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"
krenew \- Renew a Kerberos ticket
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
\&\fBkrenew\fR [\fB\-abhiLstvx\fR] [\fB\-c\fR \fIchild pid file\fR] [\fB\-H\fR \fIminutes\fR]
    [\fB\-K\fR \fIminutes\fR] [\fB\-k\fR \fIticket cache\fR] [\fB\-p\fR \fIpid file\fR]
    [\fIcommand\fR ...]
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
\&\fBkrenew\fR renews an existing renewable ticket.  When run without any
arguments, it just attempts to renew the existing ticket-granting ticket
in the current ticket cache, equivalent to \f(CW\*(C`kinit \-R\*(C'\fR, but it can
optionally run a program like \fBaklog\fR to refresh \s-1AFS\s0 tokens, can run as a
daemon and wake up periodically to renew the ticket cache, or can run a
specified command and keep renewing the ticket cache until the command
finishes (or renewal is no longer possible).  If a command is specified,
\&\fBkrenew\fR by default wakes up every 60 minutes (1 hour) to check the
ticket cache.
.PP
If a command is given, \fBkrenew\fR makes a copy of the ticket cache and
creates a private ticket cache just for that command, thus isolating it
from later destruction of the original ticket cache.  This allows krenew
to maintain authentication for a command even if, for example, the user
running the command logs out and OpenSSH destroys their original ticket
cache.
.PP
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 \f(CW\*(C`sh \-c \f(CIcommand\f(CW\*(C'\fR as the command to run and quote \fIcommand\fR.  If
the command contains command-line options (like \f(CW\*(C`\-c\*(C'\fR), put \f(CW\*(C`\-\-\*(C'\fR on the
command line before the beginning of the command to tell \fBkrenew\fR to not
parse those options as its own.
.PP
If \fBkrenew\fR is built with \fBsetpag()\fR support and \s-1AFS\s0 tokens are requested
with the \fB\-t\fR option, it will put the command in a separate \s-1PAG\s0 before
obtaining \s-1AFS\s0 tokens so that they don't interfere with other processes on
the system.
.PP
When running a command, \fBkrenew\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,
\&\fBkrenew\fR will then exit.)  This allows \fBkrenew\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 \fBkrenew\fR receives an \s-1ALRM\s0 signal, it immediately refreshes
the ticket cache regardless of whether it is in danger of expiring.
.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 \fBkrenew\fR wakes up.  Without this option, \fBkrenew\fR will only
try to renew a ticket as often as necessary to prevent the ticket from
expiring.  With this option, \fBkrenew\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 \fBkrenew\fR is using.  For example, if another program is
automatically renewing a ticket more frequently than \fBkrenew\fR, then
\&\fBkrenew\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
\&\fBkrenew\fR will also never renew \s-1AFS\s0 tokens, even if the \fB\-t\fR option was
given, since \fBkrenew\fR only renews \s-1AFS\s0 tokens after it successfully renews
a ticket.  If this option is specified in such a situation, \fBkrenew\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 \fBkrenew\fR will be running.  \fBkrenew\fR will not background
itself until after it does the initial ticket renewal, 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, \fBkrenew\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
Use of this flag on Mac \s-1OS X\s0 without specifying a file-based ticket cache
by either using \fB\-k\fR or setting \s-1KRB5CCNAME\s0 will probably not do what you
want.  Ticket caches on Mac \s-1OS X\s0 are, by default, per-session and with
\&\fB\-b\fR \fBkrenew\fR will detach itself from your existing ticket cache.
Instead, to renew the default ticket cache on Mac \s-1OS X,\s0 try something
like:
.Sp
.Vb 1
\&    (krenew \-K 60 &)
.Ve
.Sp
to run \fBkrenew\fR in the background but within the current session.
.Sp
When using this option, consider also using \fB\-L\fR to report \fBkrenew\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
\&\fBkrenew\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\-H\fR \fIminutes\fR" 4
.IX Item "-H minutes"
Only renew the ticket if it has a remaining lifetime of less than
\&\fIminutes\fR 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 \fIminutes\fR, exit with an error if unsuccessful, and then run the
command, if any.
.Sp
If \fB\-H\fR is used with \fB\-K\fR, \fBkrenew\fR will not exit immediately.
Instead, the specified remaining lifetime will replace the default value
of two minutes, meaning that \fBkrenew\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" 4
.IX Item "-i"
Ignore errors in renewing the ticket and keep running.  Normally,
\&\fBkrenew\fR 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 \fB\-b\fR was given) but
continue running, waking up to try again after the next check interval
(see \fB\-K\fR).  This is useful if some other process may recreate an expired
ticket cache and \fBkrenew\fR should stay around and act on that recreated
ticket cache once it's present.
.Sp
If the initial ticket cache renew fails, \fBkrenew\fR 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.
.Sp
This flag is only useful in daemon mode or when a command was given.
.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 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
\&\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 that doesn't cause
\&\fBkrenew\fR 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.
.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.
.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 \fBkrenew\fR to terminate when run with \fB\-i\fR 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\-p\fR \fIpid file\fR" 4
.IX Item "-p pid file"
Save the process \s-1ID\s0 (\s-1PID\s0) of the running \fBkrenew\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 \fBkrenew\fR daemon.
.Sp
Note that, when used with \fB\-b\fR the \s-1PID\s0 file is written out after
\&\fBkrenew\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\-s\fR" 4
.IX Item "-s"
Normally, when \fBkrenew\fR exits abnormally while running a command (if, for
example, the ticket's renewable lifetime has expired), it leaves the
command running.  If \fB\-s\fR is given, it will send a \s-1SIGHUP\s0 signal to the
command before exiting.  This can be useful if it's pointless for the
command to keep running without Kerberos tickets.
.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, \fBkrenew\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 \fBkrenew\fR has been built with \s-1AFS\s0 \fBsetpag()\fR support and \s-1AFS\s0 is
available, \fBkrenew\fR will create a new \s-1PAG\s0 before running the external
program.
.Sp
Otherwise, if either \fBkrenew\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 \fBkrenew\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, \fBkrenew\fR will run the external
program without doing any credential isolation, which may also affect the
credentials of the invoking process.
.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, \fBkrenew\fR 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, \fBkrenew\fR will instead exit.
.SH "EXIT STATUS"
.IX Header "EXIT STATUS"
The program normally exits with status 0 if it successfully renews a
ticket.  If \fBkrenew\fR runs aklog or some other program \fBkrenew\fR returns
the exit status of that program if it exits normally.  If the program
exits abnormally due to a signal, \fBkrenew\fR will exit with a status of 128
plus the signal number.  (This matches the behavior of \fBbash\fR.).
.SH "EXAMPLES"
.IX Header "EXAMPLES"
Renew the current ticket-granting ticket.
.PP
.Vb 1
\&    krenew
.Ve
.PP
Wake up every ten minutes and check to see if the ticket cache needs
renewing.  If it does, re-run \fBaklog\fR as well.
.PP
.Vb 1
\&    krenew \-K 10 \-t
.Ve
.PP
Run the program \fI/usr/local/bin/compute\-job\fR in the background, checking
every hour to see if the ticket needs to be renewed (the default).  Put
the \s-1PID\s0 of the \fBkrenew\fR job in \fI/var/run/compute.pid\fR.  Obtain a new \s-1AFS\s0
token each time the ticket has to be renewed.
.PP
.Vb 1
\&    krenew \-b \-t \-p /var/run/compute.pid /usr/local/bin/compute\-job
.Ve
.PP
If you wanted to pass options to \fI/usr/local/bin/compute\-job\fR, putting a
\&\f(CW\*(C`\-\-\*(C'\fR argument before it would be necessary to keep \fBkrenew\fR from
interpreting those options as its own.
.PP
If you want to redirect output to a file that requires authentication to
write to, you will need to do that redirection in a sub-shell.  In other
words, the following command:
.PP
.Vb 1
\&    krenew \-t compute\-job > /afs/local/data/output
.Ve
.PP
won't work if /afs/local/data/output requires an \s-1AFS\s0 token to write to.
The job, while running, will have an \s-1AFS\s0 token, but the output redirection
is done in the parent shell and doesn't benefit from \fBkrenew\fR.  The above
should instead be written as:
.PP
.Vb 1
\&    krenew \-t \-\- sh \-c \*(Aqcompute\-job > /afs/local/data/output\*(Aq
.Ve
.PP
With this command, the shell doing the redirection will also be run under
\&\fBkrenew\fR and have the benefit of the \s-1AFS\s0 token it obtains.
.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 \fBkrenew\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, \fBkrenew\fR will use the environment variable \s-1KRB5CCNAME\s0 to determine
the location of the the ticket granting ticket.  If 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.
.SH "AUTHORS"
.IX Header "AUTHORS"
\&\fBkrenew\fR was written by Russ Allbery <eagle@eyrie.org>.  It was based
heavily on \fBk5start\fR by Booker C. Bense, which in turn was based on the
k4start code written by Robert Morgan.
.SH "COPYRIGHT AND LICENSE"
.IX Header "COPYRIGHT AND LICENSE"
Copyright 2015, 2021 Russ Allbery <eagle@eyrie.org>
.PP
Copyright 2006, 2008\-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"
\&\fBk5start\fR\|(1), \fBkinit\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/>.