1K5START(1) User commands K5START(1)
2
6 k5start - Obtain and optionally keep active a Kerberos v5 ticket.
7
9 k5start [-bhnqstv] [-c child pid file] [-f keytab]
10 [-g group] [-H minutes] [-I service instance]
11 [-i client instance] [-K minutes] [-k ticket file]
12 [-l time string] [-m mode] [-o owner]
13 [-p pid file] [-r service realm] [-S service name]
14 [-u client principal] [username [command ...]]
15 k5start -U -f keytab [-bhnqstv] [-c child pid file]
17 [-g group] [-H minutes] [-I service instance]
18 [-K minutes] [-k ticket file] [-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 v5 ticket-granting
24 ticket for a principal. k5start can be used as an alternative to
25 kinit, but it is primarily intended to be used by programs that want to
26 use a keytab to obtain Kerberos credentials, such as a web server that
27 needs 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. username 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 spec‐
33 ifying the principal, but generally aren't as convenient. If no user‐
34 name is given as either the first argument or the argument to the -u
35 option, the client principal defaults to the Unix username of the user
36 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 run‐
42 ning, 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, and QUIT signals
59 to the child process and does not exit when those signals are received.
60 (If the propagated signal causes the child process to exit, k5start
61 will then exit.) This allows k5start to react properly when run under
62 a command supervision system such as runit(8) or svscan(8) that uses
63 signals to control supervised commands.
64
66 -b After starting, detach from the controlling terminal and run in the
67 background. This option only makes sense in combination with -K or
68 a command that k5start will be running and can only be used if a
69 keytab is specified with -f. k5start will not background itself
70 until after it does the initial authentication, so that any initial
71 errors will be reported, but it will then redirect output to
72 /dev/null and no subsequent errors will be reported.
73 If used in conjunction with a command to run, that command will
75 also run in the background and will also have its input and output
76 redirected to /dev/null. It will have to report any errors via
77 some other mechanism for the errors to be seen.
78 Note that on Mac OS X, the default ticket cache type is per-session
80 and using the -b flag will disassociate k5start from the existing
81 ticket cache. When using -b in conjunction with -K on Mac OS X,
82 you probably also want to use the -k flag to specify a ticket cache
83 file and force the use of a file cache.
84 -c child pid file
86 Save the process ID (PID) of the child process into child pid file.
87 child pid file is created if it doesn't exist and overwritten if it
88 does exist. This option is only allowed when a command was given
89 on the command line and is most useful in conjunction with -b to
90 allow management of the running child process.
91 Note that, when used with -b, the PID file is written out after
93 k4start is backgrounded and changes its working directory to /, so
94 relative paths for the PID file will be relative to / (probably not
95 what you want).
96 -f keytab
98 Authenticate using the keytab keytab rather than asking for a pass‐
99 word. A key for the client principal must be present in keytab.
100 -g group
102 After creating the ticket cache, change its group ownership to
103 group, which may be either the name of a group or a numeric group
104 ID. Ticket caches are created with 0600 permissions by default, so
105 this will have no useful effect unless used with -m.
106 This option may not be used with -K or a specified command since
108 changing the ownership of the ticket cache will prevent k5start
109 from re-reading it or renewing it.
110 -H minutes
112 Check for a happy ticket, defined as one that has a remaining life‐
113 time of at least minutes minutes. If such a ticket is found, do
114 not attempt authentication. Instead, just run the command (if one
115 was specified) or exit immediately with status 0 (if none was).
116 Otherwise, try to obtain a new ticket and then run the command, if
117 any. Cannot be used with -K.
118 -h Display a usage message and exit.
120 -I service instance
122 The instance portion of the service principal. The default is the
123 default realm of the machine. Note that unlike the client princi‐
124 pal, a non-default service principal must be specified with -I and
125 -S; one cannot provide the instance portion as part of the argument
126 to -S.
127 -i client instance
129 Specifies the instance portion of the principal. This option
130 doesn't make sense except in combination with -u. Note that the
131 instance can be specified as part of username through the normal
132 convention of appending a slash and then the instance, so one never
133 has to use this option.
134 -K minutes
136 Run in daemon mode to keep a ticket alive indefinitely. The pro‐
137 gram reawakens after minutes minutes, checks if the ticket will
138 expire before or less than two minutes after the next wakeup, and
139 gets a new ticket if needed.
140 -k ticket file
142 Use ticket file as the ticket cache rather than the contents of the
143 environment variable KRB5CCNAME or the library default. ticket
144 file should be the path to a file, without any leading "FILE:"
145 string. Using this option forces a file-based ticket cache; if you
146 wish to use a different type of ticket cache, don't specify -k and
147 instead set KRB5CCNAME to the designator of the cache you wish to
148 use.
149 -l time string
151 Set the ticket lifetime. time string should be in a format recog‐
152 nized by the Kerberos libraries for specifying times, such as "10h"
153 (ten hours) or "10m" (ten minutes). Known units are "s", "m", "h",
154 and "d". For more information, see kinit(1).
155 -m mode
157 After creating the ticket cache, change its file permissions to
158 mode, which must be a file mode in octal (640 or 444, for example).
159 This option may not be used with -K or a specified command since
161 changing the permissions of the ticket cache will prevent k5start
162 from re-reading it or renewing it.
163 -n Ignored, present for option compatibility with k4start.
165 -o owner
167 After creating the ticket cache, change its ownership to owner,
168 which may be either the name of a user or a numeric user ID. If
169 owner is the name of a user and -g was not also given, also change
170 the group ownership of the ticket cache to the default group for
171 that user.
172 This option may not be used with -K or a specified command since
174 changing the ownership of the ticket cache will prevent k5start
175 from re-reading it or renewing it.
176 -p pid file
178 Save the process ID (PID) of the running k5start process into pid
179 file. pid file is created if it doesn't exist and overwritten if
180 it does exist. This option is most useful in conjunction with -b
181 to allow management of the running k5start daemon.
182 Note that, when used with -b the PID file is written out after
184 k5start is backgrounded and changes its working directory to /, so
185 relative paths for the PID file will be relative to / (probably not
186 what you want).
187 -q Quiet. Suppresses the printing of the initial banner message say‐
189 ing what Kerberos principal tickets are being obtained for, and
190 also suppresses the password prompt when the -s option is given.
191 -r service realm
193 The realm for the service principal. This defaults to the default
194 local realm.
195 -S service name
197 Specifies the principal for which k5start is getting a service
198 ticket. The default value is "krbtgt", to obtain a ticket-granting
199 ticket. This option (along with -I) may be used if one only needs
200 access to a single service. Note that unlike the client principal,
201 a non-default service principal must be specified with both -S and
202 -I; one cannot provide the instance portion as part of the argument
203 to -S.
204 -s Read the password from standard input. This bypasses the normal
206 password prompt, which means echo isn't suppressed and input isn't
207 forced to be from the controlling terminal. Most uses of this
208 option are a security risk. You normally want to use a keytab and
209 the -f option intead.
210 -t Run an external program after getting a ticket. The default use of
212 this is to run aklog to get a token. If the environment variable
213 KINIT_PROG is set, it overrides the compiled-in default.
214 If k5start has been built with AFS setpag support and a command was
216 given on the command line, k5start will create a new PAG before
217 obtaining AFS tokens. Otherwise, it will obtain tokens in the cur‐
218 rent PAG.
219 -U Rather than requiring the principal to authenticate as be given on
221 the command line, read it from the keytab specified with -f. The
222 principal will be taken from the first entry in the keytab. -f
223 must be specified if this option is used.
224 When -U is given, k5start will not expect a principal name to be
226 given on the command line, and any arguments after the options will
227 be taken as a command to run.
228 -u client principal
230 This specifies the principal to obtain credentials as. The entire
231 principal may be specified here, or alternatively just the first
232 portion may be specified with this flag and the instance specified
233 with -i.
234 Note that there's normally no reason to use this flag rather than
236 simply giving the principal on the command line as the first regu‐
237 lar argument.
238 -v Be verbose. This will print out a bit of additional information
240 about what is being attempted and what the results are.
241
243 The program exits with status 0 if it successfully gets a ticket or has
244 a happy ticket (see -H). If k5start runs aklog or some other program
245 k5start returns the exit status of that program.
246
248 Use the /etc/krb5.keytab keytab to obtain a ticket granting ticket for
249 the principal host/example.com, putting the ticket cache in /tmp/ser‐
250 vice.tkt. The lifetime is 10 hours and the program wakes up every 10
251 minutes to check if the ticket is about to expire.
252 k5start -k /tmp/service.tkt -f /etc/krb5.keytab -K 10 -l 10h \
254 host/example.com
255 Do the same, but using the default ticket cache and run the command
257 /usr/local/bin/auth-backup. k5start will continue running until the
258 command finishes.
259 k5start -f /etc/krb5.keytab -K 10 -l 10h host/example.com \
261 /usr/local/bin/auth-backup
262 Shows the permissions of the temporary cache file created by k5start:
264 k5start -f /etc/krb5.keytab host/example.com \
266 -- sh -c 'ls -l $KRB5CCNAME'
267 Notice the "--" before the command to keep k5start from parsing the
269 "-c" as its own option.
270 Do the same thing, but determine the principal from the keytab:
272 k5start -f /etc/krb5.keytab -U -- sh -c 'ls -l $KRB5CCNAME'
274 Note that no principal is given before the command.
276 Starts k5start as a daemon using the Debian start-stop-daemon manage‐
278 ment program. This is the sort of line that one could put into a
279 Debian init script:
280 start-stop-daemon --start --pidfile /var/run/k5start.pid \
282 --exec /usr/local/bin/k5start -- -b -p /var/run/k5start.pid \
283 -f /etc/krb5.keytab host/example.com
284 This uses /var/run/k5start.pid as the PID file and obtains host/exam‐
286 ple.com tickets from the system keytab file. k5start would then be
287 stopped with:
288 start-stop-daemon --stop --pidfile /var/run/k5start.pid
290 rm -f /var/run/k5start.pid
291 This code could be added to an init script for Apache, for example, to
293 start a k5start process alongside Apache to manage its Kerberos creden‐
294 tials.
295
297 If the environment variable KINIT_PROG is set to a program (such as
298 aklog) then this path will be used for the program to run with -t
299 rather than the default compiled into k5start.
300 If no ticket file (with -k) or command is specified on the command
302 line, k5start will use the environment variable KRB5CCNAME to determine
303 the location of the the ticket granting ticket. If either a command is
304 specified or the -k option is used, KRB5CCNAME will be set to point to
305 the ticket file before running the aklog program or any command given
306 on the command line.
307
309 The default ticket cache is determined by the underlying Kerberos
310 libraries. The default path for aklog is determined at build time, and
311 will normally be whichever of aklog or afslog is found in the user's
312 path.
313 If a command is specified and -k was not given, k5start will create a
315 temporary ticket cache file of the form "/tmp/krb5cc_%d_%s" where %d is
316 the UID k5start is running as and %s is a random string.
317
319 k4start(1), kinit(1), krenew(1)
320 The kstart web page at <http://www.eyrie.org/~eagle/software/kstart/>
322 will have the current version of k4start, k5start, and krenew.
323
325 k5start was based on the k4start code written by Robert Morgan. It was
326 ported to Kerberos v5 by Booker C. Bense. Additional cleanup and cur‐
327 rent maintenance are done by Russ Allbery <rra@stanford.edu>.
328 Implementations of -b and -p and the example for a Debian init script
330 are based on code contributed by Navid Golpayegani.
3313.11 2008-04-09 K5START(1)