1 kstart release 4.2
2 (kinit daemon with keytab, renewal, and AFS support)
3
4 Originally written by Robert Morgan and Booker C. Bense
5 Currently maintained by Russ Allbery <eagle@eyrie.org>
6
7 Copyright 2015 Russ Allbery <eagle@eyrie.org>. Copyright 1995, 1996,
8 1997, 1999, 2000, 2001, 2002, 2004, 2005, 2006, 2007, 2008, 2009, 2010,
9 2011, 2012, 2014 The Board of Trustees of the Leland Stanford Junior
10 University. This software is distributed under a BSD-style license.
11 Please see the section LICENSE below for more information.
12
13BLURB
14
15 k5start and krenew are modified versions of kinit which add support for
16 running as a daemon to maintain a ticket cache, running a command with
17 credentials from a keytab and maintaining a ticket cache until that
18 command completes, obtaining AFS tokens (via an external aklog) after
19 obtaining tickets, and creating an AFS PAG for a command. They are
20 primarily useful in conjunction with long-running jobs; for moving
21 ticket handling code out of servers, cron jobs, or daemons; and to
22 obtain tickets and AFS tokens with a single command.
23
24DESCRIPTION
25
26 k5start is a modified version of kinit. It can be used as a substitute
27 for kinit (with some additional helpful options), but it can also obtain
28 credentials automatically from a keytab. It can run as a daemon, waking
29 up periodically to refresh credentials using that keytab, and can also
30 check for the validity of tickets and only refresh if they're no longer
31 valid.
32
33 Some of these capabilities have been included in Kerberos's kinit, but
34 the ability to maintain tickets while running as a daemon has not and is
35 useful for servers that need to use Kerberos. Using kstart allows the
36 ticket handling to be moved out of the server into a separate process
37 dedicated just to that purpose.
38
39 k5start can optionally run an external program whenever the ticket is
40 refreshed to obtain an AFS token, and therefore can be used in
41 conjunction with a program like aklog or afslog to maintain an AFS
42 token. When built with support for AFS PAGs, it can also put the
43 program in its own PAG so that its authentication doesn't affect any
44 other programs.
45
46 krenew is identical to k5start except that rather than obtaining new
47 tickets from a password or keytab, it renews an existing renewable
48 ticket cache. It can be used to periodically renew tickets and
49 optionally AFS tokens for long-running processes in cases where using a
50 keytab is inappropriate (such as users running their own jobs with their
51 own credentials).
52
53REQUIREMENTS
54
55 As Kerberos programs, k5start and krenew require Kerberos libraries to
56 link against. They have only been thoroughly tested with the MIT
57 Kerberos and Heimdal libraries on Debian, but should work with the
58 included Kerberos libraries on many other platforms.
59
60 Other than that, all you should need is a suitable C compiler. Neither
61 program has been tested on non-Unix systems.
62
63 If you want the -t option to work, you need a program to obtain AFS
64 tokens from Kerberos tickets. You can specify the program to use on
65 your system with the --with-aklog option to configure; if that option is
66 not given, the first of aklog or afslog that is found on your path at
67 configure time will be used.
68
69 For AFS PAG support, one of Linux, Mac OS X, Solaris 11, the kafs
70 library that comes with either Heimdal or KTH Kerberos, the kopenafs
71 library that comes with newer OpenAFS, AFS header files (on any other
72 platform besides AIX or IRIX), or AFS libraries (on AIX and IRIX) is
73 required. AIX binaries with AFS PAG support may not run on AIX systems
74 that do not have an AFS client installed due to how AIX handles system
75 calls.
76
77 To run the test suite, you must have the Perl 5.006 or later and the
78 modules Test::More and Test::Pod installed. Test::More comes with Perl
79 5.8 or later and Test::Pod is available from CPAN. You will also need
80 the kinit and klist commands to be from MIT Kerberos, not Heimdal.
81
82 To check spelling in the POD documentation, Pod::Spell (available from
83 CPAN) and either aspell or ispell with the american dictionary are also
84 required. The user's path is searched for aspell or ispell and aspell
85 is preferred. Spelling tests are disabled by default since spelling
86 dictionaries differ too much between systems.
87
88 To enable tests that may be sensitive to the local environment or that
89 produce a lot of false positives without uncovering many problems,
90 including the spelling tests, set RRA_MAINTAINER_TESTS to a true value.
91
92 To bootstrap from a Git checkout, or if you change the Automake files
93 and need to regenerate Makefile.in, you will need Automake 1.11 or
94 later. For bootstrap or if you change configure.ac or any of the m4
95 files it includes and need to regenerate configure or config.h.in, you
96 will need Autoconf 2.64 or later. Perl is also required to generate
97 the manual pages from a fresh Git checkout.
98
99INSTALLATION
100
101 Basic installation is simple. Just run:
102
103 ./configure
104 make
105 make install
106
107 Pass --enable-silent-rules to configure for a quieter build (similar to
108 the Linux kernel). Use make warnings instead of make to build with full
109 GCC compiler warnings (requires a relatively current version of GCC).
110
111 This will build k5start and krenew and install them in /usr/local/bin
112 with man pages in /usr/local/man/man1. You may need to be root to run
113 make install. To install in a different location, specify a different
114 location with the --prefix option to configure, as in:
115
116 ./configure --prefix=/opt/sw
117
118 Binaries would then be installed in /opt/sw/bin and man pages in
119 /opt/sw/man/man1. Alternately, --bindir and --mandir can be given to
120 change the installation locations of the binaries and manual pages
121 separately.
122
123 Normally, configure will use krb5-config to determine the flags to use
124 to compile with your Kerberos libraries. If krb5-config isn't found, it
125 will look for the standard Kerberos libraries in locations already
126 searched by your compiler. If the the krb5-config script first in your
127 path is not the one corresponding to the Kerberos libraries you want to
128 use or if your Kerberos libraries and includes aren't in a location
129 searched by default by your compiler, you need to specify
130 --with-krb5=PATH:
131
132 ./configure --with-krb5=/usr/pubsw
133
134 You can also individually set the paths to the include directory and the
135 library directory with --with-krb5-include and --with-krb5-lib. You may
136 need to do this if Autoconf can't figure out whether to use lib, lib32,
137 or lib64 on your platform.
138
139 To specify a particular krb5-config script to use, either set the
140 PATH_KRB5_CONFIG environment variable or pass it to configure like:
141
142 ./configure PATH_KRB5_CONFIG=/path/to/krb5-config
143
144 To not use krb5-config and force library probing even if there is a
145 krb5-config script on your path, set PATH_KRB5_CONFIG to a nonexistent
146 path:
147
148 ./configure PATH_KRB5_CONFIG=/nonexistent
149
150 If you are using aklog, afslog, or some other program to obtain AFS
151 tokens, give its path to configure with the --with-aklog option, as in:
152
153 ./configure --with-aklog=/usr/local/bin/aklog
154
155 This program will be run when the -t option is given to k5start or
156 krenew.
157
158 To enable support for AFS PAGs, pass the --enable-setpag flag to
159 configure. It is not enabled by default. On platforms other than Linux
160 and without the kafs library, you will need to add the --with-afs flag
161 specifying the location of your AFS includes and libraries unless
162 they're on your standard search path. For example:
163
164 ./configure --enable-setpag --with-afs=/usr/afsws
165
166 When enabled, k5start and krenew will always create a new PAG before
167 authentication when running a specific command and when aklog is being
168 run.
169
170 You can build kstart in a different directory from the source if you
171 wish. To do this, create a new empty directory, cd to that directory,
172 and then give the path to configure when running configure. Everything
173 else should work as above.
174
175 You can pass the --enable-reduced-depends flag to configure to try to
176 minimize the shared library dependencies encoded in the binaries. This
177 omits from the link line all the libraries included solely because the
178 Kerberos libraries depend on them and instead links the programs only
179 against libraries whose APIs are called directly. This will only work
180 with shared Kerberos libraries and will only work on platforms where
181 shared libraries properly encode their own dependencies (such as Linux).
182 It is intended primarily for building packages for Linux distributions
183 to avoid encoding unnecessary shared library dependencies that make
184 shared library migrations more difficult. If none of the above made any
185 sense to you, don't bother with this flag.
186
187TESTING
188
189 kstart comes with the beginnings of a test suite, which you can run
190 with:
191
192 make check
193
194 In order to test the client in a meaningful way, you will need to do
195 some preparatory work before running the test suite. Review the file:
196
197 tests/data/README
198
199 and follow the instructions in that file to enable the full test suite.
200
201 The test suite also requires some additional software be installed that
202 isn't otherwise used by kstart. See REQUIREMENTS above for the full
203 list of requirements for the test suite. The test driver attempts to
204 selectively skip those tests for which the necessary configuration is
205 not available, but this has not yet been fully tested in all of its
206 possible permutations (and the test suite cannot cope with a missing
207 Test::More module).
208
209 If a test fails, you can run a single test with verbose output via:
210
211 tests/runtests -o <name-of-test>
212
213 Do this instead of running the test program directly since it will
214 ensure that necessary environment variables are set up.
215
216HOMEPAGE AND SOURCE REPOSITORY
217
218 The kstart web page at:
219
220 http://www.eyrie.org/~eagle/software/kstart/
221
222 will always have the current version of this package, the current
223 documentation, and pointers to any additional resources.
224
225 kstart is maintained using Git. You can access the current source by
226 cloning the repository at:
227
228 git://git.eyrie.org/kerberos/kstart.git
229
230 or view the repository via the web at:
231
232 http://git.eyrie.org/?p=kerberos/kstart.git
233
234THANKS
235
236 To Navid Golpayegani, for contributing the initial implementation of the
237 -b option to background after the initial authentication and the -p
238 option to save the PID in a file.
239
240 To Buck Huppmann, for contributing an RPM spec file and suggesting
241 krenew.
242
243 To Adam Megacz, for pointing out that checking the executability of the
244 aklog program isn't necessary and for contributing the code to propagate
245 signals to a child process.
246
247 To Quanah Gibson-Mount, for pointing out various build system issues and
248 missing documentation.
249
250 To Sidney Cammeresi, for catching a missing include in krenew and for
251 providing information and suggestions about Mac OS X's default ticket
252 cache and its effects on the -b option of k5start and krenew.
253
254 To Thomas Kula, for pointing out that k_hasafs has to be called before
255 k_setpag when using the kafs functions.
256
257 To Thomas Weiss, for noticing that code restructuring caused the
258 argument to -H to be ignored in k5start and that -H and -K should be
259 diagnosed as mutually exclusive.
260
261 To Howard Wilkinson, for the initial version of the -o, -g, and -m
262 support and further debugging of it.
263
264 To Sascha Tandel, for the initial version of -c support and reports of
265 build problems when the AFS libauthent and libafsrpc libraries didn't
266 work.
267
268 To Gautam Iyer, for the initial version of -H support in krenew.
269
270 To Mike Horansky, for the idea of copying the current ticket cache when
271 running krenew with a command, thereby saving the ticket cache from
272 destruction when the user logs out.
273
274LICENSE
275
276 The kstart package as a whole covered by the following copyright
277 statement and license:
278
279 Copyright 2015 Russ Allbery <eagle@eyrie.org>
280 Copyright 1995, 1996, 1997, 1999, 2000, 2001, 2002, 2004, 2005, 2006,
281 2007, 2008, 2009, 2010, 2011, 2012, 2014 The Board of Trustees of
282 the Leland Stanford Junior University
283
284 Permission is hereby granted, free of charge, to any person obtaining
285 a copy of this software and associated documentation files (the
286 "Software"), to deal in the Software without restriction, including
287 without limitation the rights to use, copy, modify, merge, publish,
288 distribute, sublicense, and/or sell copies of the Software, and to
289 permit persons to whom the Software is furnished to do so, subject to
290 the following conditions:
291
292 The above copyright notice and this permission notice shall be
293 included in all copies or substantial portions of the Software.
294
295 THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
296 EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
297 MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
298 IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
299 CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
300 TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
301 SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
302
303 All individual files without an explicit exception below are released
304 under this license. Some files may have additional copyright holders as
305 noted in those files. There is detailed information about the licensing
306 of each file in the LICENSE file in this distribution.
307
308 Some files in this distribution are individually released under
309 different licenses, all of which are compatible with the above general
310 package license but which may require preservation of additional
311 notices. All required notices are preserved in the LICENSE file.
312