                           remctl release 2.11
            (remote authenticated command execution with ACLs)

                   Originally written by Anton Ushakov
         Currently maintained by Russ Allbery <rra@stanford.edu>

  Copyright 2002, 2003, 2004, 2005, 2006, 2007 Board of Trustees, Leland
  Stanford Jr. University.  This software is distributed under a BSD-style
  license.  Please see the section LICENSE below for more information.

BLURB

  remctl is a client/server application that supports remote execution of
  specific commands, using Kerberos v5 GSS-API for authentication.
  Authorization is controlled by a configuration file and ACL files and
  can be set separately for each command, unlike with rsh.  remctl is like
  a Kerberos-authenticated simple CGI server, or a combination of Kerberos
  rsh and sudo without most of the features and complexity of either.

DESCRIPTION

  remctl is a client/server application that supports remote execution of
  specific commands, using Kerberos v5 GSS-API for authentication.  Which
  commands a given user can execute is controlled by a configuration file
  and ACL files and can be easily tightly limited, unlike with rsh.

  remctld is very similar to a CGI server that uses a different network
  protocol than HTTP and always does strong authentication before
  executing the desired command.  Alternately, you can think of it as a
  very simple combination of Kerberos rsh and sudo, without most of the
  features of both but with simpler authorization.

  This package was developed to replace the use of sysctl, another package
  that allowed remote code execution with Kerberos (v4) authentication.
  sysctl embedded Tcl and allowed for arbitrary Tcl code to be run, but at
  Stanford we found that in practice all we did with it was execute
  programs on the host system.  remctl is a Kerberos v5 equivalent that
  does only the portions we actually needed.

  Both C and Java clients are provided, as well as Perl bindings for the C
  client library.  For more information about the Java client, see
  java/README.  The design documentation is available in docs/design.html.

REQUIREMENTS

  The remctld server and the standard client are written in C and require
  a C compiler to build.  Both will build against either MIT Kerberos or
  Heimdal (tested with Heimdal 0.6 and later).  remctl will also build
  against the Kerberos GSS-API implementation shipped with AIX 5.2.

  To build the Perl bindings for the C client library, you will need Perl
  5.6.0 or later.  To run the full test suite for the Perl bindings, the
  Perl modules Test::More and Test::Pod must be installed.  Test::More
  comes with Perl 5.8 and later.  Test::Pod currently must be installed
  separately, but the POD tests will be skipped without interfering with
  the rest of the tests if it's not installed.

  A Java client and Java server are available in the java subdirectory,
  but they are not integrated into the normal build or built by default.
  There is a basic Makefile in that directory that may require some
  tweaking.  It currently requires the Sun Java JDK (1.4.2, 5, or 6).

  To run the test suite, it will need to be able to build to 127.0.0.1 on
  port 11119 and 14444 to run test network server programs.  In order to
  fully test remctl, you will also need to create a keytab for a valid
  Kerberos principal in your local realm.

  If you change the Automake files and need to regenerate Makefile.in, you
  will need Automake 1.10 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.61 or later.

INSTALLATION

  You can build and install remctl with the standard commands:

      ./configure
      make
      make install

  The last step will probably have to be done as root.  By default, remctl
  installs itself under /usr/local; you can change that path by passing
  the --prefix=PATH argument to configure.

  To also build the Perl bindings for the libremctl client library, pass
  the --enable-perl option to configure.  The Perl module build is handled
  by the normal Perl extension build system, and therefore will be built
  with compiler flags defined by your Perl installation and installed into
  your local Perl module directory regardless of the --prefix argument to
  configure.  To change this, you will need to run perl on Makefile.PL in
  the perl subdirectory of the build tree with appropriate options and
  rebuild the module after running make and before running make install.

  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-kerberos=PATH:

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

  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

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

  Usage information is available in the manual pages which will be
  installed with remctl.  You will need to set up a remctl.conf file for
  the server; see docs/remctl.conf for an example.  The default location
  for remctl.conf is <prefix>/etc, but can be changed with the
  --sysconfdir flag to configure.

  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.

  The Java client and server aren't integrated with the regular build
  system.  For information on building and installing them, see
  java/README.

TESTING

  remctl comes with an extensive test suite which you can run after
  building remctl with:

      make check

  In order to do more than limited tests of the low-level routines, you
  should first create a keytab for testing use containing the key for a
  principal in your local domain.  See tests/data/README for instructions
  on what to create and where to place the files.

  If a test case fails, please run that individual test case directly and
  send me the output when reporting the problem.  Note that on
  particularly slow or loaded systems, you may see intermittant failures
  from the server/streaming test because it's timing-sensitive.

PORTING

  remctl should port reasonably well.  It has been tested on:

      Solaris 8, 9, 10
      Linux (glibc 2.2, 2.3, 2.5, 2.6, 2.6.1)
      Mac OS X 10.4
      NetBSD
      AIX 5.2

  but should work on any Unix varient that meets the requirements noted
  above.

THANKS

  To Anton Ushakov for the original design document, much of the version
  one protocol design, and the initial implementation.

  To Roland Schemers for extensive review of the initial code and protocol
  and help with the original Java client.

  To Romain LENGLET for the idea and code for examples/rsh-wrapper.

  To Thomas Kula for testing of remctl 2.0 and later versions on NetBSD
  and Heimdal.

  To Ralf Wildenhues for help in getting make check to work with builddir
  != srcdir builds.

  To Darren Patterson and Digant Kasundra for contributions to the RPM
  spec file and testing on Red Hat.

  To Jonathan Kollasch for the initial IPv6 patch and for identifying all
  of the places the code was making IPv4 assuptions.

  To Andrew Mortensen for the initial -F and -k flag support for remctld.

  To Alf Wachsmann for catching inaccuracies in the Perl documentation.

  To Jeffrey Hutzelman and Chaskiel Grundman for testing with Heimdal 0.6
  and teaching me a great deal about GSS-API flags and the security issues
  that surround them.

  To Marcus Watts for testing and various bug fixes, lots of improvements
  to the standalone server mode, and fixes for the Perl API.  Marcus also
  rewrote the Java client, adding support for protocol version two and a
  server implementation.

  To Sandor Sklar for testing multiple patches for the remctl build on AIX
  5.2 and providing an account so that I could investigate test suite
  issues.

LICENSE

  Copyright 2002, 2003, 2004, 2005, 2006, 2007 Board of Trustees, Leland
  Stanford Jr. University.  All rights reserved.
    
  Permission to use, copy, modify, and distribute this software and its
  documentation for any purpose and without fee is hereby granted,
  provided that the above copyright notice appear in all copies and that
  both that copyright notice and this permission notice appear in
  supporting documentation, and that the name of Stanford University not
  be used in advertising or publicity pertaining to distribution of the
  software without specific, written prior permission.  Stanford
  University makes no representations about the suitability of this
  software for any purpose.  It is provided "as is" without express or
  implied warranty.

  THIS SOFTWARE IS PROVIDED "AS IS" AND WITHOUT ANY EXPRESS OR IMPLIED
  WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED WARRANTIES OF
  MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE.

  Some code in remctl was taken from INN and contributions to INN by Russ
  Allbery.  That code is either in the public domain or covered by the
  following copyright and license:

  Copyright (c) 2004, 2005, 2006, 2007
      by Internet Systems Consortium, Inc. ("ISC")
  Copyright (c) 1991, 1994, 1995, 1996, 1997, 1998, 1999, 2000, 2001,
      2002, 2003 by The Internet Software Consortium and Rich Salz

  This code is derived from software contributed to the Internet Software
  Consortium by Rich Salz.

  Permission to use, copy, modify, and distribute this software for any
  purpose with or without fee is hereby granted, provided that the above
  copyright notice and this permission notice appear in all copies.

  THE SOFTWARE IS PROVIDED "AS IS" AND ISC DISCLAIMS ALL WARRANTIES WITH
  REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
  MERCHANTABILITY AND FITNESS.  IN NO EVENT SHALL ISC BE LIABLE FOR ANY
  SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
  WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
  ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
  OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
