1K5START(1) kstart K5START(1)
2
6 k5start - Obtain and optionally keep active a Kerberos ticket
7
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 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
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 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 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 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 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 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 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 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
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 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 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 This argument is only valid in combination with either -K or a
99 command to run.
100 -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 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 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 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 When using this option, consider also using -L to report k5start
125 errors to syslog.
126 -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 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 -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 -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 -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 -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 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 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 -h Display a usage message and exit.
173 -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 -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 -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 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 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 -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 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 -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 This is useful when debugging problems in combination with -b.
223 -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 -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 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 -n Ignored, present for option compatibility with the now-obsolete
239 k4start.
240 -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 -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 -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 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 -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 -r service realm
268 The realm for the service principal. This defaults to the default
269 local realm.
270 -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 -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 -t Run an external program after getting a ticket. The intended use
287 of this is to run aklog to get a token. If the environment
288 variable AKLOG (or KINIT_PROG for backward compatibility) is set,
289 it overrides the compiled-in default.
290 If a command was given on the command line, k5start will attempt to
292 isolate the AFS credentials for that command from the invoking
293 process. There are two possible ways in which this is done.
294 First, if k5start has been built with AFS setpag() support and AFS
296 is available, k5start will create a new PAG before running the
297 external program.
298 Otherwise, if either k5start was not built with AFS setpag()
300 support or AFS is not available, but the Linux kafs module is
301 available and k5start was built with libkeyutils support, it will
302 create a new session keyring and link it to the current user
303 keyring before running the external program.
304 If neither of these conditions are true, k5start will run the
306 external program without doing any credential isolation, which may
307 also affect the credentials of the invoking process.
308 -U Rather than requiring the authentication principal be given on the
310 command line, read it from the keytab specified with -f. The
311 principal will be taken from the first entry in the keytab. -f
312 must be specified if this option is used.
313 When -U is given, k5start will not expect a principal name to be
315 given on the command line, and any arguments after the options will
316 be taken as a command to run.
317 -u client principal
319 This specifies the principal to obtain credentials as. The entire
320 principal may be specified here, or alternatively just the first
321 portion may be specified with this flag and the instance specified
322 with -i.
323 Note that there's normally no reason to use this flag rather than
325 simply giving the principal on the command line as the first
326 regular argument.
327 -v Be verbose. This will print out a bit of additional information
329 about what is being attempted and what the results are.
330 -x Exit immediately on any error. Normally, when running a command or
332 when run with the -K option, k5start keeps running even if it fails
333 to refresh the ticket cache and will try again at the next check
334 interval. With this option, k5start will instead exit.
335
337 The program exits with status 0 if it successfully gets a ticket or has
338 a happy ticket (see -H). If k5start runs aklog or some other program
339 k5start returns the exit status of that program if it exits normally.
340 If the program exits abnormally due to a signal, k5start will exit with
341 a status of 128 plus the signal number. (This matches the behavior of
342 bash.)
343
345 Use the /etc/krb5.keytab keytab to obtain a ticket granting ticket for
346 the principal host/example.com, putting the ticket cache in
347 /tmp/service.tkt. The lifetime is 10 hours and the program wakes up
348 every 10 minutes to check if the ticket is about to expire.
349 k5start -k /tmp/service.tkt -f /etc/krb5.keytab -K 10 -l 10h \
351 host/example.com
352 Do the same, but using the default ticket cache and run the command
354 /usr/local/bin/auth-backup. k5start will continue running until the
355 command finishes. If the initial authentication fails, keep trying,
356 and don't start the command until it succeeds. This could be used
357 during system startup for a command that must have valid tickets before
358 starting, and tolerates having k5start start before the network is
359 completely set up.
360 k5start -f /etc/krb5.keytab -K 10 -l 10h host/example.com \
362 /usr/local/bin/auth-backup
363 Shows the permissions of the temporary cache file created by k5start:
365 k5start -f /etc/krb5.keytab host/example.com \
367 -- sh -c 'ls -l $KRB5CCNAME'
368 Notice the "--" before the command to keep k5start from parsing the
370 "-c" as its own option.
371 Do the same thing, but determine the principal from the keytab:
373 k5start -f /etc/krb5.keytab -U -- sh -c 'ls -l $KRB5CCNAME'
375 Note that no principal is given before the command.
377 Starts k5start as a daemon using the Debian start-stop-daemon
379 management program. This is the sort of line that one could put into a
380 Debian init script:
381 start-stop-daemon --start --pidfile /var/run/k5start.pid \
383 --exec /usr/local/bin/k5start -- -b -p /var/run/k5start.pid \
384 -f /etc/krb5.keytab host/example.com
385 This uses /var/run/k5start.pid as the PID file and obtains
387 host/example.com tickets from the system keytab file. k5start would
388 then be stopped with:
389 start-stop-daemon --stop --pidfile /var/run/k5start.pid
391 rm -f /var/run/k5start.pid
392 This code could be added to an init script for Apache, for example, to
394 start a k5start process alongside Apache to manage its Kerberos
395 credentials.
396
398 If the environment variable AKLOG is set, its value will be used as the
399 program to run with -t rather than the default complied into k5start.
400 If AKLOG is not set and KINIT_PROG is set, its value will be used
401 instead. KINIT_PROG is honored for backward compatibility but its use
402 is not recommended due to its confusing name.
403 If no ticket file (with -k) or command is specified on the command
405 line, k5start will use the environment variable KRB5CCNAME to determine
406 the location of the the ticket granting ticket. If either a command is
407 specified or the -k option is used, KRB5CCNAME will be set to point to
408 the ticket file before running the aklog program or any command given
409 on the command line.
410
412 The default ticket cache is determined by the underlying Kerberos
413 libraries. The default path for aklog is determined at build time, and
414 will normally be whichever of aklog or afslog is found in the user's
415 path.
416 If a command is specified and -k was not given, k5start will create a
418 temporary ticket cache file of the form "/tmp/krb5cc_%d_%s" where %d is
419 the UID k5start is running as and %s is a random string.
420
422 k5start was based on the k4start code written by Robert Morgan. It was
423 ported to Kerberos v5 by Booker C. Bense. Additional cleanup and
424 current maintenance are done by Russ Allbery <eagle@eyrie.org>.
425 Implementations of -b and -p and the example for a Debian init script
427 are based on code contributed by Navid Golpayegani.
428
430 Copyright 2015, 2021 Russ Allbery <eagle@eyrie.org>
431 Copyright 2002, 2004-2012, 2014 The Board of Trustees of the Leland
433 Stanford Junior University
434 Copying and distribution of this file, with or without modification,
436 are permitted in any medium without royalty provided the copyright
437 notice and this notice are preserved. This file is offered as-is,
438 without any warranty.
439 SPDX-License-Identifier: FSFAP
441
443 kinit(1), krenew(1)
444 This program is part of kstart. The current version is available from
446 its web site at <https://www.eyrie.org/~eagle/software/kstart/>.
4474.3 2021-08-31 K5START(1)