README

                            kadmin-remctl 3.6
             (remctl interface for Kerberos kadmin functions)

                Written by Russ Allbery <eagle@eyrie.org>

  Copyright 1997, 2003, 2007, 2008, 2009, 2010, 2011, 2013 The Board of
  Trustees of the Leland Stanford Junior University.  This software is
  distributed under a BSD-style license.  Please see the section LICENSE
  below for more information.

BLURB

  kadmin-remctl provides a remctl backend that implements basic Kerberos
  account administration functions (create, delete, enable, disable,
  reset password, examine) plus user password changes and a call to
  strength-check a given password.  It can also provide similar management
  of instances and creation, deletion, and management of accounts in
  Heimdal, MIT Kerberos, Active Directory, and an AFS kaserver where
  appropriate.  Also included is a client for privileged users to use
  for password resets and a simple client for password chnages via the
  Kerberos password change protocol.  Many of the defaults and namespace
  checks are Stanford-specific, but it can be modified for other sites.

DESCRIPTION

  At Stanford, we are currently running two Kerberos realms: a Heimdal
  Kerberos realm and an Active Directory realm.  We previously also had
  an AFS kaserver Kerberos v4 realm.  We also have middleware and web
  applications that support changing or resetting passwords, creating new
  accounts, examining principals, and enabling or disabling accounts based
  on affiliation changes.  Rather than give all of these systems kadmin
  access (and force them to use kadmin clients, which is difficult since
  many are written in Java), and rather than forcing them to do realm
  synchronization themselves, we export an interface via remctl and use
  the Java remctl client to talk to that interface.

  This package includes the kadmin backend, a Perl script that supports
  creating, deleting, enabling, and disabling accounts, changing or
  resetting passwords, and checking password strength.  This script does
  synchronization to Active Directory and an AFS kaserver Kerberos v4
  realm as well where appropriate.  It also includes ksetpass, a simple
  client for changing passwords via the Kerberos password change protocol
  that doesn't prompt for the existing password like kpasswd.  This client
  is used to set passwords in Active Directory.

  Also included in this package is a C client for use by privileged users
  when changing passwords for others.  This client searches for the user
  in a password file first to present the full name for verification, and
  then obtains special credentials for a designated principal and then
  contacts a remctl server on a non-standard port to issue a change
  password command.  This is done on a non-standard port so that it can
  use a different principal for authentication than the regular host
  principal normally used by remctl and require that the privileged user
  reauthenticate before using this service.

  Some aspects of this package are very Stanford-specific, most
  notably some of the namespace constraints on principals and the
  sometimes-bizarre formatting of the output from this script (which
  is for compatibility with the legacy APIs used at Stanford).  It is
  probably not suitable for using at other sites without modifications,
  but may provide ideas for how to do something similar for another site.

  The remctl backend was originally developed by Roland Schemers in
  conjunction with a locally-patched Kerberos v4 kadmin client.  Booker
  Bense wrote the code to talk to a Kerberos v5 kadmin client via Expect.
  I've since substantially rewritten it to merge those features and add
  additional code to propagate instance creation to Active Directory.  Jon
  Robertson ported the MIT Kerberos code to Heimdal using Heimdal::Kadm5.

  The AFS kaserver support should be considered frozen and is no longer
  tested since Stanford no longer runs a kaserver environment.  It may be
  dropped from a future release if the code is significantly restructured.

  For more information, see docs/design in the source distribution.

REQUIREMENTS

  The kadmin backend is written in Perl and requires the Perl Expect
  module.  The Heimdal version also requires the IPC::Run module.  The MIT
  version (kadmin-backend) calls the MIT Kerberos kadmin and kpasswd
  programs and therefore requires that they be available.  The Heimdal
  version similarly requires kpasswd, but uses the Perl module
  Heimdal::Kadm5 for kadmin operations and requires it be installed.  For
  integration with the AFS kaserver Kerberos v4 realm, it uses kasetkey.
  The Kerberos v4 synchronization is disabled by default.

  The kadmin backend can propagate instance creation and deletion to an
  Active Directory.  To use this support, you will need the Perl Encode,
  MIME::Base64, and Text::Template modules.  (Encode and MIME::Base64
  come with Perl 5.8 and later.)  You will also need k5start and the
  OpenLDAP binaries ldapadd, ldapdelete, and ldapmodify.  You can get
  k5start from:

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

  The passwd_change C client requires the C libremctl library be available
  to build (plus, obviously, a C compiler).  It and ksetpass also require
  a Kerberos library; any version of either MIT Kerberos or Heimdal should
  be sufficient.

  Finally, the backend is intended to be run under remctld and use remctl
  to handle authentication, privacy, and integrity.

  remctl is available from:

      <http://www.eyrie.org/~eagle/software/remctl/>

  kasetkey is available as part of old versions of the wallet distribution
  at:

      <http://www.eyrie.org/~eagle/software/wallet/>

  To bootstrap from a Git checkout, or if you change the Automake files
  and need to regenerate Makefile.in, you will need Automake 1.11 or
  later.  For bootstrap or 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.  Perl is also required to generate the
  manual pages from a fresh Git checkout.

INSTALLATION

  This software should not be deployed as-is at any site other than
  Stanford.  It needs to be reviewed and modified for changing local
  assumptions, paths, and integration requirements.

  There are two components: the remctl backend and remctld configuration
  for the interface, and the passwd_change client program.  The remctl
  backend script is a Perl script and doesn't require compilation.  It
  loads its defaults from /etc/kadmin-remctl.conf; see its man page for
  more details on the configuration options, most of which must be set.
  remctl configuration fragments suitable for being included in your
  remctld configuration are in the remctl subdirectory.  The kadmin
  fragment provides the general interface.

  To set up the server for the passwd_change client, create a special
  designated principal in your Kerberos database, set the
  DISALLOW_TGT_BASED flag on that principal to require manual
  authentication, and set the lifetime of that principal to one hour.
  Then, create a keytab for that principal on the host running the special
  server and set up a separate instance of remctld running on a different
  port that includes the remctl/password configuration fragment.  That
  instance of remctl should be run with the KRB5_KTNAME environment
  variable set, pointing it at the keytab for this designated principal.

  Before building the passwd_change client, you will want to modify the
  settings at the top of the passwd_change.c code to point it to the
  correct server and port, to use the correct designated principal for the
  password changing service, and to set the path to the passwd file.  (If
  you don't, you'll have to always have appropriate configuration in your
  krb5.conf file.)  Then, 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).

  The last step will probably have to be done as root and will install
  both the client and the kadmin-backend script.  You may need to change
  the path to Perl on the first line of kadmin-backend (as well as the
  other defaults in it).  By default, kadmin-remctl installs itself under
  /usr/local; you can change that path by passing the --prefix=PATH
  argument to configure.

  If the remctl libraries aren't installed in a directory searched by the
  compiler, use --with-remctl to specify the root directory (prefix) under
  which remctl was installed.  You can also individually set the paths to
  the library directory and the include directory with --with-remctl-lib
  and --with-remctl-include respectively.  You may need to do this if
  Autoconf can't figure out whether to use lib, lib32, or lib64 on your
  platform.

  After installation, you may want to configure passwd_change in your
  krb5.conf files.  See the passwd_change man page for configuration
  details.

  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 a different
  Kerberos installation root via --with-krb5=PATH.  For example:

      ./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.

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

      ./configure PATH_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 PATH_KRB5_CONFIG to a nonexistent
  path:

      ./configure PATH_KRB5_CONFIG=/nonexistent

  krb5-config is not used and library probing is always done if either
  --with-krb5-include or --with-krb5-lib are given.

  You can build kadmin-remctl 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.

SUPPORT

  The kadmin-remctl web page at:

      http://www.eyrie.org/~eagle/software/kadmin-remctl/

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

  I welcome bug reports and patches for this package at eagle@eyrie.org.
  However, please be aware that I tend to be extremely busy and work
  projects often take priority.  I'll save your mail and get to it as soon
  as I can, but it may take me a couple of months.

SOURCE REPOSITORY

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

      git://git.eyrie.org/kerberos/kadmin-remctl.git

  or view the repository via the web at:

      http://git.eyrie.org/?p=kerberos/kadmin-remctl.git

  When contributing modifications, patches (possibly generated by
  git-format-patch) are preferred to Git pull requests.

THANKS

  To Jon Robertson for the port of kadmin-backend to Heimdal.

  To Derrick Brashear and Ken Hornstein of Sine Nomine Associates, who did
  work on behalf of Stanford University on realm synchronization that was
  a predecessor of the ksetpass program.

LICENSE

  The kadmin-remctl package as a whole covered by the following copyright
  statement and license:

    Copyright 1997, 2003, 2006, 2007, 2008, 2009, 2010, 2011, 2013
        The Board of Trustees of the Leland Stanford Junior University

    Permission is hereby granted, free of charge, to any person obtaining
    a copy of this software and associated documentation files (the
    "Software"), to deal in the Software without restriction, including
    without limitation the rights to use, copy, modify, merge, publish,
    distribute, sublicense, and/or sell copies of the Software, and to
    permit persons to whom the Software is furnished to do so, subject to
    the following conditions:

    The above copyright notice and this permission notice shall be
    included in all copies or substantial portions of the Software.

    THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
    EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
    MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
    IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
    CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
    TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
    SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

  All individual files without an explicit exception below are released
  under this license.  Some files may have additional copyright holders as
  noted in those files.  There is detailed information about the licensing
  of each file in the LICENSE file in this distribution.

  Some files in this distribution are individually released under
  different licenses, all of which are compatible with the above general
  package license but which may require preservation of additional
  notices.  All required notices are preserved in the LICENSE file.