remctl release 3.8
            (remote authenticated command execution with ACLs)

                   Originally written by Anton Ushakov
          Currently maintained by Russ Allbery <eagle@eyrie.org>

  Copyright 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011,
  2012, 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

  remctl is a client/server application that supports remote execution
  of specific commands, using Kerberos 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 GSS-API for authentication
  and confidentiality.  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.  The mapping of command to backend
  program is done by the configuration file, which allows some additional
  flexibility compared to ssh command restrictions and works with Kerberos
  authentications rather than being limited to public key authentications.

  remctld is very similar to a CGI server that uses a different network
  protocol than HTTP, always does strong authentication before executing
  the desired command, and guarantees the data is encrypted on the
  network.  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.

  There are a lot of different client/server systems that do something
  similar, including regular rsh, CGI, IBM's sysctl (not to be confused
  with the Linux kernel call and configuration file of the same name),
  CERN's arc, and more elaborate systems like MIT's Moira. remctl has the
  advantage over many of these schemes of using GSS-API and being about
  as simple as it possibly can be while still being useful.  It doesn't
  require any particular programming language, builds self-contained
  binaries, and uses as minimal of a protocol as possible.

  Both C and Java clients and servers are provided, as well as Perl, PHP,
  and Python bindings for the C client library.  For more information
  about the Java client, see java/README.  For more information about the
  PHP bindings, see php/README.  For more information about the Python
  bindings, see python/README.

  remctl was originally written by Anton Ushakov as a replacement
  for IBM's sysctl, a client/server application with Kerberos v4
  authentication that allowed the client to run Tcl code on the server,
  protected by ACLs.  At Stanford, we used sysctl extensively, but mostly
  only to run external programs, so remctl was developed as a kerberos v5
  equivalent that did only the portions we needed.

  Complete protocol documentation is available in docs/protocol.html.
  Also present, as docs/design.html, is the original design document (now
  somewhat out of date).

  For release history and user-visible changes, see the file NEWS.

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 (and
  possibly later versions) and the Solaris 10 generic GSS-API library.
  The remctl_set_ccache implementation is improved by building against
  Kerberos libraries and a GSS-API library that supports
  gss_krb5_import_cred.

  The remctld server requires libevent 1.4.x or later.  It's only been
  tested with libevent 1.4.13-stable, but should work with 1.4.4 or later.
  It is primarily tested with libevent 2.x, so moving to a later version
  of libevent if possible is recommended.

  The remctl server will support regex ACLs if the system supports the
  POSIX regex API.  The remctl server also optionally supports PCRE
  regular expressions in ACLs.  To include that support, the PCRE library
  is required.

  To build the remctl client for Windows, the Microsoft Windows SDK for
  Windows Vista and the MIT Kerberos for Windows SDK are required, along
  with a Microsoft Windows build environment (probably Visual Studio).
  remctl has only been tested with the 3.2.1 MIT Kerberos for Windows SDK.
  To run the resulting binary, MIT Kerberos for Windows must be installed
  and configured.  The client has been tested on Windows XP and Vista and
  should work on Windows 2000 and up.  The server is not supported on
  Windows.

  To build the Perl bindings for the C client library, you will need Perl
  5.8 or later.  To run the full test suite for the Perl bindings, you
  will also need the Perl modules:

      Test::MinimumVersion
      Test::Pod
      Test::Strict
      Test::Synopsis

  but tests that require modules that aren't installed will be skipped.
  The Perl bindings have not been tested on Windows.

  To build the PHP bindings for the C client library, you will need PHP
  5.x (only tested with 5.2 and 5.3) and phpize, plus any other programs
  that phpize requires.  The PHP bindings have not been tested on Windows.

  To build the Python bindings for the C client library, you will need
  Python 2.3 or later (primarily tested with Python 2.5 and later).  The
  Python bindings have not been tested on Windows.

  To build the Ruby bindings for the C client library, you will need Ruby
  1.8 or later.  The Ruby bindings have not been tested on Windows.

  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)
  or OpenJDK 6 or later.  A considerably better Java implementation is
  currently under development.

  To run the test suite, you will need Test::Pod as described above.  The
  test suite will also need to be able to bind to 127.0.0.1 on port 11119
  and 14373 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; see tests/config/README for more
  information.

  To test user handling in remctld, you will need the fakeroot command
  (available in the fakeroot package in Debian and Ubuntu).  This test
  will be skipped if fakeroot isn't available.

  Bootstrapping from a Git checkout, or making changes to some of the
  generated files, will require the following additional packages:

      Autoconf 2.64 or later
      Automake 1.11 or later
      Perl 5.10 or later
      pkg-config
      xml2rfc

  Some parts of the test suite are suppressed by default because those
  tests are normally only useful for the maintainer.  This includes tests
  of POD spelling and Perl coding style.  To enable those tests, set the
  environment variable RRA_MAINTAINER_TESTS to a true value.  For these
  tests, the additional Perl modules:

      Test::Perl::Critic
      Test::Spelling
      Test::Strict

  and their dependencies as well as a spell-checking program (several are
  supported by Test::Spelling) are required.  These modules are all
  available from CPAN.

INSTALLATION (UNIX)

  You can build and install remctl with the standard commands:

      ./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.  By default, remctl
  installs itself under /usr/local; you can change that path by passing
  the --prefix=PATH argument to configure.

  Solaris users should then look at examples/remctld.xml, an SMF manifest
  for running the remctld daemon.

  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.

  To also build the remctl PECL extension for PHP, pass the --enable-php
  option to configure.  The PHP PECL module build is handled by the normal
  PHP extension build system and therefore will be installed into your
  local PHP module directory.  The configure script will look for phpize
  on your PATH by default; if it's in some other directory, set the PHPIZE
  environment variable to the full path or set it on the configure command
  line.  The configure script for the PECL extension will be run during
  the build instead of during configure.  This is unfortunately apparently
  unavoidable given how the PECL build system works.

  To also build the Python bindings for the libremctl client library, pass
  the --enable-python option to configure.  The Python module build is
  handled by the normal Python extension build system, and therefore will
  be installed into your local Python module directory regardless of the
  --prefix argument to configure.  To change this, you will need to run
  python setup.py install by hand in the python directory with whatever
  options you want to use.

  To also build the Ruby bindings for the libremctl client library, pass
  the --enable-ruby option to configure.  The Ruby module build is handled
  by the normal Ruby module build system, and therefore will be installed
  into your local Ruby module directory regardless of the --prefix
  argument to configure.  To change this, override the sitedir variable on
  the make install command line, as in:

      make install sitedir=/opt/ruby

  Normally, configure will use krb5-config to determine the flags to use
  to compile with your Kerberos GSS-API libraries.  If krb5-config isn't
  found, it will look for the standard Kerberos libraries in locations
  already searched by your compiler.  If 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-gssapi=PATH:

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

  You can also individually set the paths to the include directory and the
  library directory with --with-gssapi-include and --with-gssapi-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-gssapi-include or --with-gssapi-lib are given.

  You can similarly override krb5-config for Kerberos libraries (if you
  have them) with --with-krb5, --with-krb5-include, and --with-krb5-lib.

  remctl will use pkg-config if it's available to find the build flags for
  libevent.  You can control which pkg-config binary and paths are used
  with the normal pkg-config environment variables of PKG_CONFIG,
  PKG_CONFIG_PATH, and PKG_CONFIG_LIBDIR, and you can override the
  pkg-config results with LIBEVENT_CFLAGS and LIBEVENT_LIBS.  Alternately,
  you can bypass pkg-config by passing one or more of --with-libevent,
  --with-libevent-include, and --with-libevent-lib to indicate the install
  prefix, include directory, or library directory.

  remctl will automatically build with PCRE support if pcre-config or the
  PCRE library are found.  You can pass --with-pcre to configure to
  specify the root directory where PCRE is installed, or set the include
  and library directories separately with --with-pcre-include and
  --with-pcre-lib.  You can also set PCRE_CONFIG to point to a different
  pcre-config script, or do similar things as with KRB5_CONFIG described
  above.

  remctl will automatically build with GPUT support if the GPUT header and
  library are found.  You can pass --with-gput to configure to specify the
  root directory where GPUT is installed, or set the include and library
  directories separately with --with-gput-include and --with-gput-lib.

  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 remctl build system also supports a few other environment variables
  that can be set to control aspects of the Perl, Python, and Ruby binding
  build systems.  These are primarily only of use when packaging the
  software.  For more information, a list of the variables, and their
  effects, see the comment at the start of Makefile.am.

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

INSTALLATION (Windows)

  First, install the Microsoft Windows SDK for Windows Vista if you have
  not already.  This is a free download from Microsoft for users of
  "Genuine Microsoft Windows."  The vcvars32.bat environment provided by
  Visual Studio may work as an alternative, but has not been tested.

  Next, install the MIT Kerberos for Windows SDK, available for download
  from http://web.mit.edu/kerberos/www/dist/index.html.  remctl has been
  tested with version 3.2.1 but should hopefully work with later versions.

  Then, follow these steps:

  1. Run the InitEnv.cmd script included with the Windows SDK with
     parameters "/xp /release".

  2. Run the configure.bat script, giving it as an argument the location
     of the Kerberos for Windows SDK.  For example, if you installed the
     KfW SDK in "c:\KfW SDK", you should run:

         configure "c:\KfW SDK"

  3. Run nmake to start compiling.  You can ignore the warnings.

  If all goes well, you will have remctl.exe and remctl.dll.  The latter
  is a shared library used by the client program.  It exports the same
  interface as the UNIX libremctl library.

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 realm.  See tests/config/README for instructions
  on what to create and where to place the files.

  If a test case fails, please run the that individual test case with
  verbose output using:

      tests/runtests -o <name-of-test>

  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.

HOMEPAGE AND SOURCE REPOSITORY

  The remctl web page at:

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

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

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

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

  or view the repository via the web at:

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

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, for the Python bindings, and for the REMCTL_COMMAND
  environment variable implementation.

  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,
  for the initial remctl PECL extension for PHP, for general code
  formatting comments and a reminder to free malloc'd memory in the Python
  bindings, and for implementing the user option in the remctld
  configuration file.

  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.

  To Matthew Loar for the Windows port of the remctl client.

  To Jeffrey Hutzelman for adding the framework for ACL method support and
  implementing the file, princ, deny, and gput schemes, as well as lots of
  testing and portability bug reports and patches.

  To Timothy G. Abbott for suggesting additional restrictions on the names
  of files read when processing an include of a directory.

  To Jeffrey Altman for additional porting to Windows and fixes to the
  Windows build infrastructure.

  To Anthony M. Martinez for the initial Ruby bindings.

  To Peter Eriksson for the example SMF manifest for the remctld daemon
  and help with building against Solaris 10's native GSS-API libraries.

  To Anton Lundin for the initial implementation that led to regex and
  PCRE ACL support in remctld.

  To Tollef Fog Heen for assistance in writing the pkg-config
  configuration file for libremctl.

LICENSE

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

    Copyright 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011,
        2012, 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.