1K5START(1)                          kstart                          K5START(1)
2
3
4

NAME

6       k5start - Obtain and optionally keep active a Kerberos ticket
7

SYNOPSIS

9       k5start [-abFhLnPqstvx] [-c child pid file] [-f keytab]
10           [-g group] [-H minutes] [-I service instance]
11           [-i client instance] [-K minutes] [-k ticket cache]
12           [-l time string] [-m mode] [-o owner]
13           [-p pid file] [-r service realm] [-S service name]
14           [-u client principal] [principal [command ...]]
15
16       k5start -U -f keytab [-abFhLnPqstvx] [-c child pid file]
17           [-g group] [-H minutes] [-I service instance]
18           [-K minutes] [-k ticket cache] [-l time string]
19           [-m mode] [-o owner] [-p pid file]
20           [-r service realm] [-S service name] [command ...]
21

DESCRIPTION

23       k5start obtains and caches an initial Kerberos ticket-granting ticket
24       for a principal.  k5start can be used as an alternative to kinit, but
25       it is primarily intended to be used by programs that want to use a
26       keytab to obtain Kerberos credentials, such as a web server that needs
27       to authenticate to another service such as an LDAP server.
28
29       Normally, the principal for which to give tickets should be specified
30       as the first argument.  principal may be either just a principal name
31       (including the optional instance) or a full principal and realm string.
32       The -u and -i options can be used as an alternative mechanism for
33       specifying the principal, but generally aren't as convenient.  If no
34       principal is given as either the first argument or the argument to the
35       -u option, the client principal defaults to the Unix username of the
36       user running k5start in the default local realm.
37
38       Optionally, a command may be given on the command line of k5start.  If
39       so, that command is run after Kerberos authentication (and running
40       aklog if desired), with the appropriate environment variables set to
41       point it to the right ticket cache.  k5start will then continue
42       running, waking up periodically to refresh credentials slightly before
43       they would expire, until the command completes.  (The frequency with
44       which it wakes up to refresh credentials can still be controlled with
45       the -K option.)  To run in this mode, the principal must either be
46       specified as a regular command-line argument or via the -U option; the
47       -u and -i options may not be used.  Also, a keytab must be specified
48       with -f to run a specific command.
49
50       The command will not be run using the shell, so if you want to use
51       shell metacharacters in the command with their special meaning, give
52       "sh -c command" as the command to run and quote command.
53
54       If the command contains command-line options (like "-c"), put -- on the
55       command line before the beginning of the command to tell k5start to not
56       parse those options as its own.
57
58       When running a command, k5start propagates HUP, TERM, INT, and QUIT
59       signals to the child process and does not exit when those signals are
60       received.  (If the propagated signal causes the child process to exit,
61       k5start will then exit.)  This allows k5start to react properly when
62       run under a command supervision system such as runit(8) or svscan(8)
63       that uses signals to control supervised commands, and to run
64       interactive commands that should receive Ctrl-C.
65
66       If a running k5start receives an ALRM signal, it immediately refreshes
67       the ticket cache regardless of whether it is in danger of expiring.
68
69       If k5start is run with a command or the -K flag and the -x flag is not
70       given, it will keep trying even if the initial authentication fails.
71       It will retry the initial authentication immediately and then with
72       exponential backoff to once per minute, and keep trying until
73       authentication succeeds or it is killed.  The command, if any, will not
74       be started until authentication succeeds.
75

OPTIONS

77       -a  When run with either the -K flag or a command, always renew tickets
78           each time k5start wakes up.  Without this option, k5start will only
79           try to renew a ticket as often as necessary to prevent the ticket
80           from expiring.  With this option, k5start will renew tickets
81           according to the interval specified with the -K flag.
82
83           This behavior probably should have been the default behavior of -K.
84           The default was not changed to avoid changes for existing users,
85           but for new applications, consider always using -a with -K.
86
87           This option is important if another program is manipulating the
88           ticket cache that k5start is using.  For example, if another
89           program is automatically renewing a ticket more frequently than
90           k5start, then k5start will never see a ticket that is close to
91           expiring and will therefore, by default, never try to renew the
92           ticket.  This means that k5start will also never renew AFS tokens,
93           even if the -t option was given, since k5start only renews AFS
94           tokens after it successfully renews a ticket.  If this option is
95           specified in such a situation, k5start will renew its ticket every
96           time it checks the ticket, so AFS tokens will be renewed.
97
98           This argument is only valid in combination with either -K or a
99           command to run.
100
101       -b  After starting, detach from the controlling terminal and run in the
102           background.  This option only makes sense in combination with -K or
103           a command that k5start will be running and can only be used if a
104           keytab is specified with -f.  k5start will not background itself
105           until after it has tried authenticating once, so that any initial
106           errors will be reported, but it will then redirect output to
107           /dev/null and no subsequent errors will be reported.
108
109           If this flag is given, k5start will also change directories to "/".
110           All paths (such as to a command to run or a PID file) should
111           therefore be given as absolute, not relative, paths.
112
113           If used in conjunction with a command to run, that command will
114           also run in the background and will also have its input and output
115           redirected to /dev/null.  It will have to report any errors via
116           some other mechanism for the errors to be seen.
117
118           Note that on Mac OS X, the default ticket cache type is per-session
119           and using the -b flag will disassociate k5start from the existing
120           ticket cache.  When using -b in conjunction with -K on Mac OS X,
121           you probably also want to use the -k flag to specify a ticket cache
122           file and force the use of a file cache.
123
124           When using this option, consider also using -L to report k5start
125           errors to syslog.
126
127       -c child pid file
128           Save the process ID (PID) of the child process into child pid file.
129           child pid file is created if it doesn't exist and overwritten if it
130           does exist.  This option is only allowed when a command was given
131           on the command line and is most useful in conjunction with -b to
132           allow management of the running child process.
133
134           Note that, when used with -b, the PID file is written out after
135           k5start is backgrounded and changes its working directory to /, so
136           relative paths for the PID file will be relative to / (probably not
137           what you want).
138
139       -F  Do not get forwardable tickets even if the local configuration says
140           to get forwardable tickets by default.  Without this flag, k5start
141           does whatever the library default is.
142
143       -f keytab
144           Authenticate using the keytab keytab rather than asking for a
145           password.  A key for the client principal must be present in
146           keytab.
147
148       -g group
149           After creating the ticket cache, change its group ownership to
150           group, which may be either the name of a group or a numeric group
151           ID.  Ticket caches are created with 0600 permissions by default, so
152           this will have no useful effect unless used with -m.
153
154       -H minutes
155           Check for a happy ticket, defined as one that has a remaining
156           lifetime of at least minutes minutes.  If such a ticket is found,
157           do not attempt authentication.  Instead, just run the command (if
158           one was specified) or exit immediately with status 0 (if none was).
159           Otherwise, try to obtain a new ticket and then run the command, if
160           any.
161
162           If -H is used with -t, the external program will always be run even
163           if a ticket with a sufficient remaining lifetime was found.
164
165           If -H is used with -K, k5start will not exit immediately.  Instead,
166           the specified remaining lifetime will replace the default value of
167           two minutes, meaning that k5start will ensure, each time it wakes
168           up, that the ticket has a remaining lifetime of the minutes
169           argument.  This is an alternative to -a to ensure that tickets
170           always have a certain minimal amount of lifetime remaining.
171
172       -h  Display a usage message and exit.
173
174       -I service instance
175           The instance portion of the service principal.  The default is the
176           default realm of the machine.  Note that unlike the client
177           principal, a non-default service principal must be specified with
178           -I and -S; one cannot provide the instance portion as part of the
179           argument to -S.
180
181       -i client instance
182           Specifies the instance portion of the principal.  This option
183           doesn't make sense except in combination with -u.  Note that the
184           instance can be specified as part of username through the normal
185           convention of appending a slash and then the instance, so one never
186           has to use this option.
187
188       -K minutes
189           Run in daemon mode to keep a ticket alive indefinitely.  The
190           program reawakens after minutes minutes, checks if the ticket will
191           expire before or less than two minutes after the next scheduled
192           check, and gets a new ticket if needed.  (In other words, it
193           ensures that the ticket will always have a remaining lifetime of at
194           least two minutes.)  If the -H flag is also given, the lifetime
195           specified by it replaces the two minute default.
196
197           If this option is not given but a command was given on the command
198           line, the default interval is 60 minutes (1 hour).
199
200           If an error occurs in refreshing the ticket cache, the wake-up
201           interval will be shortened to one minute and the operation retried
202           at that interval for as long as the error persists.
203
204       -k ticket cache
205           Use ticket cache as the ticket cache rather than the contents of
206           the environment variable KRB5CCNAME or the library default.  ticket
207           cache may be any ticket cache identifier recognized by the
208           underlying Kerberos libraries.  This generally supports a path to a
209           file, with or without a leading "FILE:" string, but may also
210           support other ticket cache types.
211
212           If any of -o, -g, or -m are given, ticket cache must be either a
213           simple path to a file or start with "FILE:" or "WRFILE:".
214
215       -L  Report messages to syslog as well as to standard output or standard
216           error.  All messages will be logged with facility LOG_DAEMON.
217           Regular messages that are displayed on standard output are logged
218           with level LOG_NOTICE.  Errors that don't cause k5start to
219           terminate are logged with level LOG_WARNING.  Fatal errors are
220           logged with level LOG_ERR.
221
222           This is useful when debugging problems in combination with -b.
223
224       -l time string
225           Set the ticket lifetime.  time string should be in a format
226           recognized by the Kerberos libraries for specifying times, such as
227           "10h" (ten hours) or "10m" (ten minutes).  Known units are "s",
228           "m", "h", and "d".  For more information, see kinit(1).
229
230       -m mode
231           After creating the ticket cache, change its file permissions to
232           mode, which must be a file mode in octal (640 or 444, for example).
233
234           Setting a mode that does not allow k5start to read or write to the
235           ticket cache will cause k5start to fail and exit when using the -K
236           option or running a command.
237
238       -n  Ignored, present for option compatibility with the now-obsolete
239           k4start.
240
241       -o owner
242           After creating the ticket cache, change its ownership to owner,
243           which may be either the name of a user or a numeric user ID.  If
244           owner is the name of a user and -g was not also given, also change
245           the group ownership of the ticket cache to the default group for
246           that user.
247
248       -P  Do not get proxiable tickets even if the local configuration says
249           to get proxiable tickets by default.  Without this flag, k5start
250           does whatever the library default is.
251
252       -p pid file
253           Save the process ID (PID) of the running k5start process into pid
254           file.  pid file is created if it doesn't exist and overwritten if
255           it does exist.  This option is most useful in conjunction with -b
256           to allow management of the running k5start daemon.
257
258           Note that, when used with -b the PID file is written out after
259           k5start is backgrounded and changes its working directory to /, so
260           relative paths for the PID file will be relative to / (probably not
261           what you want).
262
263       -q  Quiet.  Suppresses the printing of the initial banner message
264           saying what Kerberos principal tickets are being obtained for, and
265           also suppresses the password prompt when the -s option is given.
266
267       -r service realm
268           The realm for the service principal.  This defaults to the default
269           local realm.
270
271       -S service name
272           Specifies the principal for which k5start is getting a service
273           ticket.  The default value is "krbtgt", to obtain a ticket-granting
274           ticket.  This option (along with -I) may be used if one only needs
275           access to a single service.  Note that unlike the client principal,
276           a non-default service principal must be specified with both -S and
277           -I; one cannot provide the instance portion as part of the argument
278           to -S.
279
280       -s  Read the password from standard input.  This bypasses the normal
281           password prompt, which means echo isn't suppressed and input isn't
282           forced to be from the controlling terminal.  Most uses of this
283           option are a security risk.  You normally want to use a keytab and
284           the -f option instead.
285
286       -t  Run an external program after getting a ticket.  The default use of
287           this is to run aklog to get a token.  If the environment variable
288           KINIT_PROG is set, it overrides the compiled-in default.
289
290           If k5start has been built with AFS setpag() support and a command
291           was given on the command line, k5start will create a new PAG before
292           obtaining AFS tokens.  Otherwise, it will obtain tokens in the
293           current PAG.
294
295       -U  Rather than requiring the authentication principal be given on the
296           command line, read it from the keytab specified with -f.  The
297           principal will be taken from the first entry in the keytab.  -f
298           must be specified if this option is used.
299
300           When -U is given, k5start will not expect a principal name to be
301           given on the command line, and any arguments after the options will
302           be taken as a command to run.
303
304       -u client principal
305           This specifies the principal to obtain credentials as.  The entire
306           principal may be specified here, or alternatively just the first
307           portion may be specified with this flag and the instance specified
308           with -i.
309
310           Note that there's normally no reason to use this flag rather than
311           simply giving the principal on the command line as the first
312           regular argument.
313
314       -v  Be verbose.  This will print out a bit of additional information
315           about what is being attempted and what the results are.
316
317       -x  Exit immediately on any error.  Normally, when running a command or
318           when run with the -K option, k5start keeps running even if it fails
319           to refresh the ticket cache and will try again at the next check
320           interval.  With this option, k5start will instead exit.
321

RETURN VALUES

323       The program exits with status 0 if it successfully gets a ticket or has
324       a happy ticket (see -H).  If k5start runs aklog or some other program
325       k5start returns the exit status of that program.
326

EXAMPLE

328       Use the /etc/krb5.keytab keytab to obtain a ticket granting ticket for
329       the principal host/example.com, putting the ticket cache in
330       /tmp/service.tkt.  The lifetime is 10 hours and the program wakes up
331       every 10 minutes to check if the ticket is about to expire.
332
333           k5start -k /tmp/service.tkt -f /etc/krb5.keytab -K 10 -l 10h \
334               host/example.com
335
336       Do the same, but using the default ticket cache and run the command
337       /usr/local/bin/auth-backup.  k5start will continue running until the
338       command finishes.  If the initial authentication fails, keep trying,
339       and don't start the command until it succeeds.  This could be used
340       during system startup for a command that must have valid tickets before
341       starting, and tolerates having k5start start before the network is
342       completely set up.
343
344           k5start -f /etc/krb5.keytab -K 10 -l 10h host/example.com \
345               /usr/local/bin/auth-backup
346
347       Shows the permissions of the temporary cache file created by k5start:
348
349           k5start -f /etc/krb5.keytab host/example.com \
350               -- sh -c 'ls -l $KRB5CCNAME'
351
352       Notice the "--" before the command to keep k5start from parsing the
353       "-c" as its own option.
354
355       Do the same thing, but determine the principal from the keytab:
356
357           k5start -f /etc/krb5.keytab -U -- sh -c 'ls -l $KRB5CCNAME'
358
359       Note that no principal is given before the command.
360
361       Starts k5start as a daemon using the Debian start-stop-daemon
362       management program.  This is the sort of line that one could put into a
363       Debian init script:
364
365           start-stop-daemon --start --pidfile /var/run/k5start.pid \
366               --exec /usr/local/bin/k5start -- -b -p /var/run/k5start.pid \
367               -f /etc/krb5.keytab host/example.com
368
369       This uses /var/run/k5start.pid as the PID file and obtains
370       host/example.com tickets from the system keytab file.  k5start would
371       then be stopped with:
372
373           start-stop-daemon --stop --pidfile /var/run/k5start.pid
374           rm -f /var/run/k5start.pid
375
376       This code could be added to an init script for Apache, for example, to
377       start a k5start process alongside Apache to manage its Kerberos
378       credentials.
379

ENVIRONMENT

381       If the environment variable AKLOG is set, its value will be used as the
382       program to run with -t rather than the default complied into k5start.
383       If AKLOG is not set and KINIT_PROG is set, its value will be used
384       instead.  KINIT_PROG is honored for backward compatibility but its use
385       is not recommended due to its confusing name.
386
387       If no ticket file (with -k) or command is specified on the command
388       line, k5start will use the environment variable KRB5CCNAME to determine
389       the location of the the ticket granting ticket.  If either a command is
390       specified or the -k option is used, KRB5CCNAME will be set to point to
391       the ticket file before running the aklog program or any command given
392       on the command line.
393

FILES

395       The default ticket cache is determined by the underlying Kerberos
396       libraries.  The default path for aklog is determined at build time, and
397       will normally be whichever of aklog or afslog is found in the user's
398       path.
399
400       If a command is specified and -k was not given, k5start will create a
401       temporary ticket cache file of the form "/tmp/krb5cc_%d_%s" where %d is
402       the UID k5start is running as and %s is a random string.
403

AUTHORS

405       k5start was based on the k4start code written by Robert Morgan.  It was
406       ported to Kerberos v5 by Booker C. Bense.  Additional cleanup and
407       current maintenance are done by Russ Allbery <eagle@eyrie.org>.
408
409       Implementations of -b and -p and the example for a Debian init script
410       are based on code contributed by Navid Golpayegani.
411
413       Copyright 2015 Russ Allbery <eagle@eyrie.org>
414
415       Copyright 2002, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011, 2012,
416       2014 The Board of Trustees of the Leland Stanford Junior University
417
418       Copying and distribution of this file, with or without modification,
419       are permitted in any medium without royalty provided the copyright
420       notice and this notice are preserved.  This file is offered as-is,
421       without any warranty.
422

SEE ALSO

424       kinit(1), krenew(1)
425
426       The kstart web page at <http://www.eyrie.org/~eagle/software/kstart/>
427       will have the current version of k5start and krenew.
428
429
430
4314.2                               2015-12-26                        K5START(1)
Impressum