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 | |
---|
12 | BLURB |
---|
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 | |
---|
21 | DESCRIPTION |
---|
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 | |
---|
51 | REQUIREMENTS |
---|
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 | |
---|
110 | INSTALLATION (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 | |
---|
208 | INSTALLATION (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 | |
---|
236 | TESTING |
---|
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 | |
---|
257 | HOMEPAGE 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 | |
---|
275 | THANKS |
---|
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. |
---|