kstart release 3.15
               (kinit daemon that uses srvtabs or keytabs)

         Originally written by Robert Morgan and Booker C. Bense
         Currently maintained by Russ Allbery <rra@stanford.edu>

  Copyright 1995, 1996, 1997, 1999, 2000, 2001, 2002, 2004, 2005, 2006,
  2007, 2008, 2009 Board of Trustees, Leland Stanford Jr. University.
  Based on code copyright 1987, 1988, 1989 by the Massachusetts Institute
  of Technology.  This software is distributed under a BSD-style license.
  Please see the file LICENSE in the distribution for more information.

BLURB

  k4start, k5start, and krenew are modified versions of kinit which add
  support for running as a daemon to maintain a ticket cache, running a
  command with credentials from a keytab and maintaining a ticket cache
  until that command completes, obtaining AFS tokens (via an external
  aklog) after obtaining tickets, and creating an AFS PAG for a command.
  They are primarily useful in conjunction with long-running jobs; for
  moving ticket handling code out of servers, cron jobs, or daemons; and
  to obtain tickets and AFS tokens with a single command.

DESCRIPTION

  k4start (for Kerberos v4) and k5start (for Kerberos v5) are modified
  versions of kinit.  They can be used as a substitute for kinit (with
  better command-line handling than the old Kerberos v4 kinit), but they
  can also obtain credentials automatically from a v4 srvtab or a v5
  keytab.  They can run as a daemon, waking up periodically to refresh
  credentials using that srvtab or keytab, and can also check for the
  validity of tickets and only refresh if they're no longer valid.

  Some of these capabilities have been included in Kerberos v5's kinit,
  but the ability to maintain tickets while running as a daemon has not
  and is useful for servers that need to use Kerberos.  Using kstart
  allows the ticket handling to be moved out of the server into a separate
  process dedicated just to that purpose.

  k4start and k5start can optionally run an external program whenever the
  ticket is refreshed to obtain an AFS token, and therefore can be used in
  conjunction with a program like aklog or afslog to maintain an AFS
  token.  When built with support for AFS PAGs, they can also put the
  program in its own PAG so that its authentication doesn't affect any
  other programs.

  krenew is identical to k5start except that rather than obtaining new
  tickets from a password or keytab, it renews an existing renewable
  ticket cache.  It can be used to periodically renew tickets and
  optionally AFS tokens for long-running processes in cases where using a
  keytab is inappropriate (such as users running their own jobs with their
  own credentials).

  k4start is generally frozen and is no longer actively tested in new
  releases.  I will fix bugs in k4start where possible, but I no longer
  have a Kerberos v4 realm with which to test.  New features added to
  k5start and krenew will not be added to k4start.

REQUIREMENTS

  As Kerberos programs, k4start, k5start, and krenew require Kerberos
  libraries to link against.  They have only been thoroughly tested with
  the MIT Kerberos libraries, but should work with Heimdal and KTH
  Kerberos v4.

  If you only have Heimdal but not KTH Kerberos v4, you can build only
  k5start and krenew by passing the --disable-k4start flag to configure.

  Other than that, all you should need is a suitable C compiler.  Neither
  program has been tested on non-Unix systems.

  If you want the -t option to work, you need a program to obtain AFS
  tokens from Kerberos tickets.  You can specify the program to use on
  your system with the --with-aklog option to configure; if that option is
  not given, the first of aklog or afslog that is found on your path at
  configure time will be used.

  AFS PAG support on platforms other than Linux requires the kafs library
  that comes with either Heimdal or KTH Kerberos, AFS header files (on any
  other platform besides AIX or IRIX), or AFS libraries (on AIX and IRIX).
  AIX binaries with AFS PAG support may not run on AIX systems that do not
  have an AFS client installed due to how AIX handles system calls.  On
  Linux, kstart uses its own internal implementation of the AFS system
  call interface and doesn't require any external libraries.

  To run the test suite, you must have the Perl 5.006 or later and the
  modules Test::More and Test::Pod installed.  Test::More comes with Perl
  5.8 or later and Test::Pod is available from CPAN.

  To check spelling in the POD documentation, Pod::Spell (available from
  CPAN) and either aspell or ispell with the american dictionary are also
  required.  The user's path is searched for aspell or ispell and aspell
  is preferred.  Spelling tests are disabled by default since spelling
  dictionaries differ too much between systems.  To enable those tests,
  set RRA_MAINTAINER_TESTS to a true value.

  If you change the Automake files and need to regenerate Makefile.in, you
  will need Automake 1.11 or later.  If you change configure.ac or any of
  the m4 files it includes and need to regenerate configure or
  config.h.in, you will need Autoconf 2.64 or later.

INSTALLATION

  Basic installation is simple.  Just run:

      ./configure
      make
      make install

  Pass --enable-silent-rules to configure for a quieter build (similar to
  the Linux kernel).  Use make warnings instead of make to build with full
  GCC compiler warnings (requires a relatively current version of GCC).

  This will build k4start, k5start, and krenew and install them in
  /usr/local/bin with man pages in /usr/local/man/man1.  You may need to
  be root to run make install.  To install in a different location,
  specify a different location with the --prefix option to configure, as
  in:

      ./configure --prefix=/opt/sw

  Binaries would then be installed in /opt/sw/bin and man pages in
  /opt/sw/man/man1.  Alternately, --bindir and --mandir can be given to
  change the installation locations of the binaries and manual pages
  separately.

  If Kerberos v4 libraries are found during configure time, k4start will
  be built.  Otherwise, it will be skipped.  To never build k4start, even
  if Kerberos v4 libraries are available, pass --disable-k4start to
  configure.

  Normally, configure will use krb5-config to determine the flags to use
  to compile with your Kerberos libraries.  If krb5-config isn't found, it
  will look for the standard Kerberos libraries in locations already
  searched by your compiler.  If the the krb5-config script first in your
  path is not the one corresponding to the Kerberos libraries you want to
  use or if your Kerberos libraries and includes aren't in a location
  searched by default by your compiler, you need to specify
  --with-krb5=PATH:

      ./configure --with-krb5=/usr/pubsw

  You can also individually set the paths to the include directory and the
  library directory with --with-krb5-include and --with-krb5-lib.  You may
  need to do this if Autoconf can't figure out whether to use lib, lib32,
  or lib64 on your platform.  Similarly, if your Kerberos v4 libraries
  aren't found by default and krb5-config doesn't return the flags for
  building with Kerberos v4, use the --with-krb4, --with-krb4-include, or
  --with-krb4-lib options to configure.  Note that these settings aren't
  used if a krb5-config script is found.

  To specify a particular krb5-config script to use, either set the
  KRB5_CONFIG environment variable or pass it to configure like:

      ./configure KRB5_CONFIG=/path/to/krb5-config

  To not use krb5-config and force library probing even if there is a
  krb5-config script on your path, set KRB5_CONFIG to a nonexistent path:

      ./configure KRB5_CONFIG=/nonexistent

  If you are using aklog, afslog, or some other program to obtain AFS
  tokens, give its path to configure with the --with-aklog option, as in:

      ./configure --with-aklog=/usr/local/bin/aklog

  This program will be run when the -t option is given to k4start,
  k5start, or krenew.

  To enable support for AFS PAGs, pass the --enable-setpag flag to
  configure.  It is not enabled by default.  On platforms other than Linux
  and without the kafs library, you will need to add the --with-afs flag
  specifying the location of your AFS includes and libraries unless
  they're on your standard search path.  For example:

      ./configure --enable-setpag --with-afs=/usr/afsws

  When enabled, k4start, k5start, and krenew will always create a new PAG
  before authentication when running a specific command and when aklog is
  being run.

  You can build kstart in a different directory from the source if you
  wish.  To do this, create a new empty directory, cd to that directory,
  and then give the path to configure when running configure.  Everything
  else should work as above.

  You can pass the --enable-reduced-depends flag to configure to try to
  minimize the shared library dependencies encoded in the binaries.  This
  omits from the link line all the libraries included solely because the
  Kerberos libraries depend on them and instead links the programs only
  against libraries whose APIs are called directly.  This will only work
  with shared Kerberos libraries and will only work on platforms where
  shared libraries properly encode their own dependencies (such as Linux).
  It is intended primarily for building packages for Linux distributions
  to avoid encoding unnecessary shared library dependencies that make
  shared library migrations more difficult.  If none of the above made any
  sense to you, don't bother with this flag.

TESTING

  kstart comes with the beginnings of a test suite, which you can run
  with:

      make check

  In order to test the client in a meaningful way, you will need to do
  some preparatory work before running the test suite.  Review the file:

      tests/data/README

  and follow the instructions in that file to enable the full test suite.

  The test suite also requires some additional software be installed that
  isn't otherwise used by the wallet.  See REQUIREMENTS above for the full
  list of requirements for the test suite.  The test driver attempts to
  selectively skip those tests for which the necessary configuration is
  not available, but this has not yet been fully tested in all of its
  possible permutations (and the test suite cannot cope with a missing
  Test::More module).

  If a test case fails, please run that individual test program directly
  and send me the output when reporting the problem.

HOMEPAGE AND SOURCE REPOSITORY

  The kstart web page at:

      http://www.eyrie.org/~eagle/software/kstart/

  will always have the current version of this package, the current
  documentation, and pointers to any additional resources.

  kstart is maintained using Git.  You can access the current source by
  cloning the repository at:

      git://git.eyrie.org/kerberos/kstart.git

  or view the repository via the web at:

      http://git.eyrie.org/?p=kerberos/kstart.git

THANKS

  To Navid Golpayegani, for contributing the initial implementation of the
  -b option to background after the initial authentication and the -p
  option to save the PID in a file.

  To Buck Huppmann, for contributing an RPM spec file and suggesting
  krenew.

  To Adam Megacz, for pointing out that checking the executability of the
  aklog program isn't necessary and for contributing the code to propagate
  signals to a child process.

  To Quanah Gibson-Mount, for pointing out various build system issues and
  missing documentation.

  To Sidney Cammeresi, for catching a missing include in krenew and for
  providing information and suggestions about Mac OS X's default ticket
  cache and its effects on the -b option of k5start and krenew.

  To Thomas Kula, for pointing out that k_hasafs has to be called before
  k_setpag when using the kafs functions.

  To Thomas Weiss, for noticing that code restructuring caused the
  argument to -H to be ignored in both k4start and k5start and that -H and
  -K should be diagnosed as mutually exclusive.

  To Howard Wilkinson, for the initial version of the -o, -g, and -m
  support and further debugging of it.

  To Sascha Tandel, for the initial version of -c support and reports of
  build problems when the AFS libauthent and libafsrpc libraries didn't
  work.

  To Gautam Iyer, for the initial version of -H support in krenew.

  To Mike Horansky, for the idea of copying the current ticket cache when
  running krenew with a command, thereby saving the ticket cache from
  destruction when the user logs out.