source: web/old/remctl-2.14/README @ f6f3e91

web
Last change on this file since f6f3e91 was f6f3e91, checked in by Jessica B. Hamrick <jhamrick@…>, 15 years ago

Preserve directory hierarchy (not sure what happened to it)

  • Property mode set to 100644
File size: 14.7 KB
Line 
1                           remctl release 2.14
2            (remote authenticated command execution with ACLs)
3
4                   Originally written by Anton Ushakov
5         Currently maintained by Russ Allbery <rra@stanford.edu>
6
7  Copyright 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009 Board of
8  Trustees, Leland Stanford Jr. University.  This software is distributed
9  under a BSD-style license.  Please see the file LICENSE in the
10  distribution for more information.
11
12BLURB
13
14  remctl is a client/server application that supports remote execution of
15  specific commands, using Kerberos v5 GSS-API for authentication.
16  Authorization is controlled by a configuration file and ACL files and
17  can be set separately for each command, unlike with rsh.  remctl is like
18  a Kerberos-authenticated simple CGI server, or a combination of Kerberos
19  rsh and sudo without most of the features and complexity of either.
20
21DESCRIPTION
22
23  remctl is a client/server application that supports remote execution of
24  specific commands, using Kerberos v5 GSS-API for authentication.  Which
25  commands a given user can execute is controlled by a configuration file
26  and ACL files and can be easily tightly limited, unlike with rsh.
27
28  remctld is very similar to a CGI server that uses a different network
29  protocol than HTTP and always does strong authentication before
30  executing the desired command.  Alternately, you can think of it as a
31  very simple combination of Kerberos rsh and sudo, without most of the
32  features of both but with simpler authorization.
33
34  This package was developed to replace the use of sysctl, another package
35  that allowed remote code execution with Kerberos (v4) authentication.
36  sysctl embedded Tcl and allowed for arbitrary Tcl code to be run, but at
37  Stanford we found that in practice all we did with it was execute
38  programs on the host system.  remctl is a Kerberos v5 equivalent that
39  does only the portions we actually needed.
40
41  Both C and Java clients and servers are provided, as well as Perl, PHP,
42  and Python bindings for the C client library.  For more information
43  about the Java client, see java/README.  For more information about the
44  PHP bindings, see php/README.  For more information about the Python
45  bindings, see python/README.
46
47  Complete protocol documentation is available in docs/protocol.html.
48  Also present, as docs/design.html, is the original design document (now
49  somewhat out of date).
50
51REQUIREMENTS
52
53  The remctld server and the standard client are written in C and require
54  a C compiler to build.  Both will build against either MIT Kerberos or
55  Heimdal (tested with Heimdal 0.6 and later).  remctl will also build
56  against the Kerberos GSS-API implementation shipped with AIX 5.2.
57
58  To build the remctl client for Windows, the Microsoft Windows SDK for
59  Windows Vista and the MIT Kerberos for Windows SDK are required, along
60  with a Microsoft Windows build environment (probably Visual Studio).
61  remctl has only been tested with the 3.2.1 MIT Kerberos for Windows SDK.
62  To run the resulting binary, MIT Kerberos for Windows must be installed
63  and configured.  The client has been tested on Windows XP and Vista and
64  should work on Windows 2000 and up.  The server is not supported on
65  Windows.
66
67  To build the Perl bindings for the C client library, you will need Perl
68  5.6.0 or later.  To run the full test suite for the Perl bindings, the
69  Perl modules Test::More and Test::Pod must be installed.  Test::More
70  comes with Perl 5.8 and later.  Test::Pod currently must be installed
71  separately, but the POD tests will be skipped without interfering with
72  the rest of the tests if it's not installed.  The Perl bindings have not
73  been tested in Windows.
74
75  To build the PHP bindings for the C client library, you will need PHP
76  5.x (only tested with 5.2) and phpize, plus any other programs that
77  phpize requires.
78
79  To build the Python bindings for the C client library, you will need
80  Python 2.3 or later (primarily tested with Python 2.5).  The Python
81  bindings have not been tested on Windows.
82
83  A Java client and Java server are available in the java subdirectory,
84  but they are not integrated into the normal build or built by default.
85  There is a basic Makefile in that directory that may require some
86  tweaking.  It currently requires the Sun Java JDK (1.4.2, 5, or 6).
87
88  To run the test suite, you will need Test::Pod as described above.  The
89  test suite will also need to be able to build to 127.0.0.1 on port 11119
90  and 14373 to run test network server programs.  In order to fully test
91  remctl, you will also need to create a keytab for a valid Kerberos
92  principal in your local realm; see tests/data/README for more
93  information.
94
95  To check spelling in the POD documentation, Pod::Spell (available from
96  CPAN) and either aspell or ispell with the american dictionary are also
97  required.  The user's path is searched for aspell or ispell and aspell
98  is preferred.  Spelling tests are disabled by default since spelling
99  dictionaries differ too much between systems.  To enable those tests,
100  set RRA_MAINTAINER_TESTS to a true value.
101
102  To bootstrap from a Git checkout, or if you change the Automake files
103  and need to regenerate Makefile.in, you will need Automake 1.10 or
104  later.  For bootstrap or if you change configure.ac or any of the m4
105  files it includes and need to regenerate configure or config.h.in, you
106  will need Autoconf 2.63 or later.  Perl and xml2rfc are also required to
107  generate the manual pages and protocol documentation from a fresh Git
108  checkout.
109
110INSTALLATION (UNIX)
111
112  You can build and install remctl with the standard commands:
113
114      ./configure
115      make
116      make install
117
118  The last step will probably have to be done as root.  By default, remctl
119  installs itself under /usr/local; you can change that path by passing
120  the --prefix=PATH argument to configure.
121
122  To also build the Perl bindings for the libremctl client library, pass
123  the --enable-perl option to configure.  The Perl module build is handled
124  by the normal Perl extension build system, and therefore will be built
125  with compiler flags defined by your Perl installation and installed into
126  your local Perl module directory regardless of the --prefix argument to
127  configure.  To change this, you will need to run perl on Makefile.PL in
128  the perl subdirectory of the build tree with appropriate options and
129  rebuild the module after running make and before running make install.
130
131  To also build the remctl PECL extension for PHP, pass the --enable-php
132  option to configure.  The PHP PECL module build is handled by the normal
133  PHP extension build system and therefore will be installed into your
134  local PHP module directory.  The configure script will look for phpize
135  on your PATH by default; if it's in some other directory, set the PHPIZE
136  environment variable to the full path or set it on the configure command
137  line.  The configure script for the PECL extension will be run during
138  the build instead of during configure.  This is unfortunately apparently
139  unavoidable given how the PECL build system works.
140
141  To also build the Python bindings for the libremctl client library, pass
142  the --enable-python option to configure.  The Python module build is
143  handled by the normal Python extension build system, and therefore will
144  be installed into your local Python module directory regardless of the
145  --prefix argument to configure.  To change this, you will need to run
146  python setup.py install by hand in the python directory with whatever
147  options you want to use.
148
149  Normally, configure will use krb5-config to determine the flags to use
150  to compile with your Kerberos GSS-API libraries.  If krb5-config isn't
151  found, it will look for the standard Kerberos libraries in locations
152  already searched by your compiler.  If the the krb5-config script first
153  in your path is not the one corresponding to the Kerberos libraries you
154  want to use or if your Kerberos libraries and includes aren't in a
155  location searched by default by your compiler, you need to specify
156  --with-gssapi=PATH:
157
158      ./configure --with-gssapi=/usr/pubsw
159
160  You can also individually set the paths to the include directory and the
161  library directory with --with-gssapi-include and --with-gssapi-lib.  You
162  may need to do this if Autoconf can't figure out whether to use lib,
163  lib32, or lib64 on your platform.  Note that these settings aren't used
164  if a krb5-config script is found.
165
166  To specify a particular krb5-config script to use, either set the
167  KRB5_CONFIG environment variable or pass it to configure like:
168
169      ./configure KRB5_CONFIG=/path/to/krb5-config
170
171  To not use krb5-config and force library probing even if there is a
172  krb5-config script on your path, set KRB5_CONFIG to a nonexistent path:
173
174      ./configure KRB5_CONFIG=/nonexistent
175
176  remctl will automatically build with GPUT support if the GPUT header and
177  library are found.  You can pass --with-gput to configure to specify the
178  root directory where GPUT is installed, or set the include and library
179  directories separately with --with-gput-include and --with-gput-lib.
180
181  You can build remctl in a different directory from the source if you
182  wish.  To do this, create a new empty directory, cd to that directory,
183  and then give the path to configure when running configure.  Everything
184  else should work as above.
185
186  Usage information is available in the manual pages which will be
187  installed with remctl.  You will need to set up a remctl.conf file for
188  the server; see docs/remctl.conf for an example.  The default location
189  for remctl.conf is <prefix>/etc, but can be changed with the
190  --sysconfdir flag to configure.
191
192  You can pass the --enable-reduced-depends flag to configure to try to
193  minimize the shared library dependencies encoded in the binaries.  This
194  omits from the link line all the libraries included solely because the
195  Kerberos libraries depend on them and instead links the programs only
196  against libraries whose APIs are called directly.  This will only work
197  with shared Kerberos libraries and will only work on platforms where
198  shared libraries properly encode their own dependencies (such as Linux).
199  It is intended primarily for building packages for Linux distributions
200  to avoid encoding unnecessary shared library dependencies that make
201  shared library migrations more difficult.  If none of the above made any
202  sense to you, don't bother with this flag.
203
204  The Java client and server aren't integrated with the regular build
205  system.  For information on building and installing them, see
206  java/README.
207
208INSTALLATION (Windows)
209
210  First, install the Microsoft Windows SDK for Windows Vista if you have
211  not already.  This is a free download from Microsoft for users of
212  "Genuine Microsoft Windows."  The vcvars32.bat environment provided by
213  Visual Studio may work as an alternative, but has not been tested.
214
215  Next, install the MIT Kerberos for Windows SDK, available for download
216  from http://web.mit.edu/kerberos/www/dist/index.html.  remctl has been
217  tested with version 3.2.1 but should hopefully work with later versions.
218
219  Then, follow these steps:
220
221  1. Run the InitEnv.cmd script included with the Windows SDK with
222     parameters "/xp /release".
223
224  2. Run the configure.bat script, giving it as an argument the location
225     of the Kerberos for Windows SDK.  For example, if you installed the
226     KfW SDK in "c:\KfW SDK", you should run:
227
228         configure "c:\KfW SDK"
229
230  3. Run nmake to start compiling.  You can ignore the warnings.
231
232  If all goes well, you will have remctl.exe and remctl.dll.  The latter
233  is a shared library used by the client program.  It exports the same
234  interface as the UNIX libremctl library.
235
236TESTING
237
238  remctl comes with an extensive test suite which you can run after
239  building remctl with:
240
241      make check
242
243  In order to do more than limited tests of the low-level routines, you
244  should first create a keytab for testing use containing the key for a
245  principal in your local domain.  See tests/data/README for instructions
246  on what to create and where to place the files.
247
248  If a test case fails, please run the that individual test case with
249  verbose output using:
250
251      tests/runtests -o <name-of-test>
252
253  and send me the output when reporting the problem.  Note that on
254  particularly slow or loaded systems, you may see intermittant failures
255  from the server/streaming test because it's timing-sensitive.
256
257HOMEPAGE AND SOURCE REPOSITORY
258
259  The remctl web page at:
260
261      http://www.eyrie.org/~eagle/software/remctl/
262
263  will always have the current version of this package, the current
264  documentation, and pointers to any additional resources.
265
266  remctl is maintained using Git.  You can access the current source by
267  cloning the repository at:
268
269      git://git.eyrie.org/kerberos/remctl.git
270
271  or view the repository via the web at:
272
273      http://git.eyrie.org/?p=kerberos/remctl.git
274
275THANKS
276
277  To Anton Ushakov for the original design document, much of the version
278  one protocol design, and the initial implementation.
279
280  To Roland Schemers for extensive review of the initial code and protocol
281  and help with the original Java client.
282
283  To Romain LENGLET for the idea and code for examples/rsh-wrapper.
284
285  To Thomas Kula for testing of remctl 2.0 and later versions on NetBSD
286  and Heimdal and for the Python bindings.
287
288  To Ralf Wildenhues for help in getting make check to work with builddir
289  != srcdir builds.
290
291  To Darren Patterson and Digant Kasundra for contributions to the RPM
292  spec file and testing on Red Hat.
293
294  To Jonathan Kollasch for the initial IPv6 patch and for identifying all
295  of the places the code was making IPv4 assuptions.
296
297  To Andrew Mortensen for the initial -F and -k flag support for remctld.
298
299  To Alf Wachsmann for catching inaccuracies in the Perl documentation.
300
301  To Jeffrey Hutzelman and Chaskiel Grundman for testing with Heimdal 0.6
302  and teaching me a great deal about GSS-API flags and the security issues
303  that surround them.
304
305  To Marcus Watts for testing and various bug fixes, lots of improvements
306  to the standalone server mode, and fixes for the Perl API.  Marcus also
307  rewrote the Java client, adding support for protocol version two and a
308  server implementation.
309
310  To Sandor Sklar for testing multiple patches for the remctl build on AIX
311  5.2 and providing an account so that I could investigate test suite
312  issues.
313
314  To Matthew Loar for the Windows port of the remctl client.
315
316  To Andrew Mortensen for the initial remctl PECL extension for PHP and
317  for general code formatting comments and a reminder to free malloc'd
318  memory in the Python bindings.
319
320  To Jeffrey Hutzelman for adding the framework for ACL method support and
321  implementing the file, princ, deny, and gput schemes, as well as lots of
322  testing and portability bug reports.
323
324  To Timothy G. Abbott for suggesting additional restrictions on the names
325  of files read when processing an include of a directory.
Note: See TracBrowser for help on using the repository browser.