Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
KRENEW(1)			    kstart			     KRENEW(1)

NAME
       krenew -	Renew a	Kerberos ticket

SYNOPSIS
       krenew [-abhiLstvx] [-c child pid file] [-H minutes]
	   [-K minutes]	[-k ticket cache] [-p pid file]
	   [command ...]

DESCRIPTION
       krenew 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 "kinit	-R", but it
       can optionally run a program like aklog to refresh AFS 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, krenew by default wakes up every 60 minutes (1 hour) to
       check the ticket	cache.

       If a command is given, krenew 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.

       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 "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 krenew to
       not parse those options as its own.

       If krenew is built with setpag()	support	and AFS	tokens are requested
       with the	-t option, it will put the command in a	separate PAG before
       obtaining AFS tokens so that they don't interfere with other processes
       on the system.

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

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

	   If this flag	is given, krenew 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.

	   Use of this flag on Mac OS X	without	specifying a file-based	ticket
	   cache by either using -k or setting KRB5CCNAME will probably	not do
	   what	you want.  Ticket caches on Mac	OS X are, by default, per-
	   session and with -b krenew will detach itself from your existing
	   ticket cache.  Instead, to renew the	default	ticket cache on	Mac OS
	   X, try something like:

	       (krenew -K 60 &)

	   to run krenew in the	background but within the current session.

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

       -H minutes
	   Only	renew the ticket if it has a remaining lifetime	of less	than
	   minutes 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 minutes, exit	with an	error if
	   unsuccessful, and then run the command, if any.

	   If -H is used with -K, krenew will not exit immediately.  Instead,
	   the specified remaining lifetime will replace the default value of
	   two minutes,	meaning	that krenew 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  Ignore errors in renewing the ticket	and keep running.  Normally,
	   krenew 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 -b	was
	   given) but continue running,	waking up to try again after the next
	   check interval (see -K).  This is useful if some other process may
	   recreate an expired ticket cache and	krenew should stay around and
	   act on that recreated ticket	cache once it's	present.

	   If the initial ticket cache renew fails, krenew 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.

	   This	flag is	only useful in daemon mode or when a command was
	   given.

       -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 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 -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 that doesn't
	   cause krenew	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.

       -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 krenew to terminate
	   when	run with -i are	logged with level LOG_WARNING.	Fatal errors
	   are logged with level LOG_ERR.

	   This	is useful when debugging problems in combination with -b.

       -p pid file
	   Save	the process ID (PID) of	the running krenew 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 krenew daemon.

	   Note	that, when used	with -b	the PID	file is	written	out after
	   krenew is backgrounded and changes its working directory to /, so
	   relative paths for the PID file will	be relative to / (probably not
	   what	you want).

       -s  Normally, when krenew exits abnormally while	running	a command (if,
	   for example,	the ticket's renewable lifetime	has expired), it
	   leaves the command running.	If -s is given,	it will	send a SIGHUP
	   signal to the command before	exiting.  This can be useful if	it's
	   pointless for the command to	keep running without Kerberos tickets.

       -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 krenew has been built with AFS setpag() support and a command
	   was given on	the command line, krenew will create a new PAG before
	   obtaining AFS tokens.  Otherwise, it	will obtain tokens in the
	   current PAG.

       -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,	krenew 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,	krenew will instead exit.

RETURN VALUES
       The program normally exits with status 0	if it successfully renews a
       ticket.	If krenew runs aklog or	some other program krenew returns the
       exit status of that program.

EXAMPLES
       Renew the current ticket-granting ticket.

	   krenew

       Wake up every ten minutes and check to see if the ticket	cache needs
       renewing.  If it	does, re-run aklog as well.

	   krenew -K 10	-t

       Run the program /usr/local/bin/compute-job in the background, checking
       every hour to see if the	ticket needs to	be renewed (the	default).  Put
       the PID of the krenew job in /var/run/compute.pid.  Obtain a new	AFS
       token each time the ticket has to be renewed.

	   krenew -b -t	-p /var/run/compute.pid	/usr/local/bin/compute-job

       If you wanted to	pass options to	/usr/local/bin/compute-job, putting a
       "--" argument before it would be	necessary to keep krenew from
       interpreting those options as its own.

       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:

	   krenew -t compute-job > /afs/local/data/output

       won't work if /afs/local/data/output requires an	AFS token to write to.
       The job,	while running, will have an AFS	token, but the output
       redirection is done in the parent shell and doesn't benefit from
       krenew.	The above should instead be written as:

	   krenew -t --	sh -c 'compute-job > /afs/local/data/output'

       With this command, the shell doing the redirection will also be run
       under krenew and	have the benefit of the	AFS token it obtains.

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 krenew.
       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, krenew will use the environment variable KRB5CCNAME to determine
       the location of the the ticket granting ticket.	If 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.

AUTHORS
       krenew was written by Russ Allbery <eagle@eyrie.org>.  It was based
       heavily on k5start by Booker C. Bense, which in turn was	based on the
       k4start code written by Robert Morgan.

COPYRIGHT AND LICENSE
       Copyright 2015 Russ Allbery <eagle@eyrie.org>

       Copyright 2006, 2008, 2009, 2010, 2011, 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.

SEE ALSO
       k5start(1), kinit(1)

       The kstart web page at <http://www.eyrie.org/~eagle/software/kstart/>
       will have the current version of	krenew.

4.2				  2015-12-26			     KRENEW(1)

NAME | SYNOPSIS | DESCRIPTION | OPTIONS | RETURN VALUES | EXAMPLES | ENVIRONMENT | FILES | AUTHORS | COPYRIGHT AND LICENSE | SEE ALSO

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=krenew&sektion=1&manpath=FreeBSD+12.1-RELEASE+and+Ports>

home | help