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

FreeBSD Manual Pages

  
 
  

home | help
K5START(1)			    kstart			    K5START(1)

NAME
       k5start - Obtain	and optionally keep active a Kerberos ticket

SYNOPSIS
       k5start [-abFhLnPqstvx] [-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] [principal [command ...]]

       k5start -U -f keytab [-abFhLnPqstvx] [-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.  principal 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
       principal 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.

       If k5start is run with a	command	or the -K flag and the -x 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.

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

       -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.

	   If -H is used with -t, the external program will always be run even
	   if a	ticket with a sufficient remaining lifetime was	found.

	   If -H is used with -K, k5start will not exit	immediately.  Instead,
	   the specified remaining lifetime will replace the default value of
	   two minutes,	meaning	that k5start 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 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.  (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, 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.

	   If any of -o, -g, or	-m are given, ticket cache must	be either a
	   simple path to a file or start with "FILE:" or "WRFILE:".

       -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).

	   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 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.

	   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.

       -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.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.  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 k5start start before the network is
       completely set up.

	   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.

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 <eagle@eyrie.org>.

       Implementations of -b and -p and	the example for	a Debian init script
       are based on code contributed by	Navid Golpayegani.

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

       Copyright 2002, 2004, 2005, 2006, 2007, 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
       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.

4.2				  2015-12-26			    K5START(1)

NAME | SYNOPSIS | DESCRIPTION | OPTIONS | RETURN VALUES | EXAMPLE | 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=k5start&sektion=1&manpath=FreeBSD+12.1-RELEASE+and+Ports>

home | help