remctl release 2.12 (remote authenticated command execution with ACLs) Originally written by Anton Ushakov Currently maintained by Russ Allbery Copyright 2002, 2003, 2004, 2005, 2006, 2007, 2008 Board of Trustees, Leland Stanford Jr. University. This software is distributed under a BSD-style license. Please see the file LICENSE in the distribution 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 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.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. The Perl bindings have not been tested in 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). 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 (UNIX) 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 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 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 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 /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. 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 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, 2.7) 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. To Matthew Loar for the Windows port of the remctl client.