source: web/old/remctl-2.14/perl/Remctl.pm.in @ 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: 11.1 KB
Line 
1# Net::Remctl -- Perl bindings for the remctl client library.
2#
3# This is the Perl boostrap file for the Net::Remctl module, nearly all of
4# which is implemented in XS.  For the actual source, see Remctl.xs.  This
5# file contains the bootstrap and export code and the documentation.
6#
7# Written by Russ Allbery <rra@stanford.edu>
8# Copyright 2007, 2008 Board of Trustees, Leland Stanford Jr. University
9#
10# See LICENSE for licensing terms.
11
12package Net::Remctl;
13
14use 5.006;
15use strict;
16use warnings;
17
18our $VERSION = '@PACKAGE_VERSION@';
19
20require Exporter;
21require DynaLoader;
22
23our @ISA = qw(Exporter DynaLoader);
24our @EXPORT = qw(remctl);
25
26bootstrap Net::Remctl;
271;
28
29=head1 NAME
30
31Net::Remctl - Perl bindings for remctl (Kerberos remote command execution)
32
33=head1 SYNOPSIS
34
35    # Simplified form.
36    use Net::Remctl;
37    my $result = remctl("hostname", undef, undef, "test", "echo", "Hi");
38    if ($result->error) {
39        die "test echo failed with error ", $result->error, "\n";
40    } else {
41        warn $result->stderr;
42        print $result->stdout;
43        exit $result->status;
44    }
45
46    # Full interface.
47    use Net::Remctl ();
48    my $remctl = Net::Remctl->new;
49    $remctl->open("hostname")
50        or die "Cannot connect to hostname: ", $remctl->error, "\n";
51    $remctl->command("test", "echo", "Hi there")
52        or die "Cannot send command: ", $remctl->error, "\n";
53    my $output;
54    do {
55        $output = $remctl->output;
56        if ($output->type eq 'output') {
57            if ($output->stream == 1) {
58                print $output->data;
59            } elsif ($output->stream == 2) {
60                warn $output->data;
61            }
62        } elsif ($output->type eq 'error') {
63            warn $output->error, "\n";
64        } elsif ($output->type eq 'status') {
65            exit $output->status;
66        } else {
67            die "Unknown output token from library: ", $output->type, "\n";
68        }
69    } while ($output->type eq 'output');
70
71=head1 DESCRIPTION
72
73Net::Remctl provides Perl bindings to the libremctl client library.  remctl
74is a protocol for remote command execution using GSS-API authentication.
75The specific allowable commands must be listed in a configuration file on
76the remote system and the remote system can map the remctl command names to
77any local command without exposing that mapping to the client.  This module
78implements a remctl client.
79
80=head2 Simplified Interface
81
82If you want to run a single command on a remote system and get back the
83output and exit status, you can use the exported remctl() function:
84
85=over 4
86
87=item remctl(HOSTNAME, PORT, PRINCIPAL, COMMAND, [ARGS, ...])
88
89Runs a command on the remote system and returns a Net::Remctl::Result
90object (see below).  HOSTNAME is the remote host to contact.  PORT is the
91port of the remote B<remctld> server and may be 0 to tell the library to
92use the default (first try 4373, the registered remctl port, and fall back
93to the legacy 4444 port if that fails).  PRINCIPAL is the principal of the
94server to use for authentication; pass in the empty string to use the
95default of host/HOSTNAME, with the realm determined by domain-realm
96mapping.  The remaining arguments are the remctl command and arguments
97passed to the remote server.
98
99As far as the module is concerned, undef may be passed as PORT and
100PRINCIPAL and is the same as 0 and the empty string respectively.
101However, Perl will warn about passing undef explicitly as a function
102argument.
103
104The return value is a Net::Remctl::Result object which supports the
105following methods:
106
107=over 4
108
109=item error()
110
111Returns the error message from either the remote host or from the local
112client library (if, for instance, contacting the remote host failed).
113Returns undef if there was no error.  Checking whether error() returns undef
114is the supported way of determining whether the remctl() call succeeded.
115
116=item stdout()
117
118Returns the command's standard output or undef if there was none.
119
120=item stderr()
121
122Returns the command's standard error or undef if there was none.
123
124=item status()
125
126Returns the command's exit status.
127
128=back
129
130Each call to remctl() will open a new connection to the remote host and
131close it after retrieving the results of the command.  To maintain a
132persistant connection, use the full interface described below.
133
134=back
135
136=head2 Full Interface
137
138The full remctl library interface requires that the user do more
139bookkeeping, but it provides more flexibility and allows one to issue
140multiple commands on the same persistent connection (provided that the
141remote server supports protocol version two; if not, the library will
142transparently fall back to opening a new connection for each command).
143
144To use the full interface, first create a Net::Remctl object with new() and
145then connect() to a remote server.  Then, issue a command() and call
146output() to retrieve output tokens (as Net::Remctl::Output objects) until a
147status token is received.  Destroying the Net::Remctl object will close the
148connection.
149
150The supported object methods are:
151
152=over 4
153
154=item new()
155
156Create a new Net::Remctl object.  This doesn't attempt to connect to a host
157and hence will only fail (by throwing an exception) if the library cannot
158allocate memory.
159
160=item error()
161
162Retrieves the error message from the last failing operation and returns it
163as a string.
164
165=item open(HOSTNAME[, PORT[, PRINCIPAL]])
166
167Connect to HOSTNAME on port PORT using PRINCIPAL as the remote server's
168principal for authentication.  If PORT is omitted or 0, use the default
169(first try 4373, the registered remctl port, and fall back to the legacy
1704444 port if that fails).  If PRINCIPAL is omitted or the empty string,
171use the default of host/HOSTNAME, with the realm determined by
172domain-realm mapping.  Returns true on success, false on failure.  On
173failure, call error() to get the failure message.
174
175As far as the module is concerned, undef may be passed as PORT and
176PRINCIPAL and is the same as 0 and the empty string respectively.
177However, Perl will warn about passing undef explicitly as a function
178argument.
179
180=item command(COMMAND[, ARGS, ...])
181
182Send the command and arguments to the remote host.  The command and the
183arguments may, under the remctl protocol, contain any character, but be
184aware that most remctl servers will reject commands or arguments containing
185ASCII 0 (NUL), so currently this cannot be used for upload of arbitrary
186unencoded binary data.  Returns true on success (meaning success in sending
187the command, and implying nothing about the result of the command), false on
188failure.  On failure, call error() to get the failure message.
189
190=item output()
191
192Returns the next output token from the remote host.  The token is returned
193as a Net::Remctl::Output object, which supports the following methods:
194
195=over 4
196
197=item type()
198
199Returns the type of the output token, which will be one of C<output>,
200C<error>, C<status>, or C<done>.  A command will result in either one
201C<error> token or zero or more C<output> tokens followed by a C<status>
202token.  After either a C<error> or C<status> token is seen, another command
203can be issued.  If the caller tries to retrieve another output token when it
204has already consumed all of them for that command, the library will return a
205C<done> token.
206
207=item data()
208
209Returns the contents of the token.  This method only makes sense for
210C<output> and C<error> tokens; otherwise, it will return undef.  Note that
211the returned value may contain any character, including ASCII 0 (NUL).
212
213=item length()
214
215Returns the length of the data in the token.  As with data(), this method
216only makes sense for the C<output> and C<error> tokens.  It will return 0 if
217there is no data or if the data is zero-length.
218
219=item stream()
220
221For an C<output> token, returns the stream with which the data is
222associated.  Currently, only two stream values will be used: 1, meaning
223standard output; and 2, meaning standard error.  The value is undefined for
224all other output token types.
225
226=item status()
227
228For a C<status> token, returns the exit status of the remote command.  The
229value is undefined for all other token types.
230
231=item error()
232
233For an C<error> token, returns the remctl error code for the protocol
234error.  The text message will be returned by data().  The value is undefined
235for all other token types.
236
237=back
238
239=back
240
241Note that, due to internal implementation details in the library, the
242Net::Remctl::Output object returned by output() will be invalidated by the
243next call to command() or output() or by destroying the producing
244Net::Remctl object.  Therefore, any data in the output token should be
245processed and stored if needed before making any further Net::Remctl method
246calls on the same object.
247
248=head1 CAVEATS
249
250If the I<principal> argument to remctl() or remctl_open() is NULL, most
251GSS-API libraries will canonicalize the I<host> using DNS before deriving
252the principal name from it.  This means that when connecting to a remctl
253server via a CNAME, remctl() and remctl_open() will normally authenticate
254using a principal based on the canonical name of the host instead of the
255specified I<host> parameter.  This behavior may cause problems if two
256consecutive DNS lookups of I<host> may return two different results, such
257as with some DNS-based load-balancing systems.
258
259The canonicalization behavior is controlled by the GSS-API library; with
260the MIT Kerberos GSS-API library, canonicalization can be disabled by
261setting C<rdns> to false in the [libdefaults] section of F<krb5.conf>.  It
262can also be disabled by passing an explicit Kerberos principal name via
263the I<principal> argument, which will then be used without changes.  If
264canonicalization is desired, the caller may wish to canonicalizae I<host>
265before calling remctl() or remctl_open() to avoid problems with multiple
266DNS calls returning different results.
267
268The default behavior, when the port is not specified, of trying 4373 and
269falling back to 4444 will be removed in a future version of this module in
270favor of using the C<remctl> service in F</etc/services> if set and then
271falling back on only 4373.  4444 was the poorly-chosen original remctl
272port and should be phased out.
273
274=head1 NOTES
275
276The remctl port number, 4373, was derived by tracing the diagonals of a
277QWERTY keyboard up from the letters C<remc> to the number row.
278
279=head1 SEE ALSO
280
281remctl(1), remctld(8)
282
283The current version of this module is available from its web page at
284L<http://www.eyrie.org/~eagle/software/remctl/>.
285
286=head1 AUTHOR
287
288Russ Allbery <rra@stanford.edu>
289
290=head1 COPYRIGHT AND LICENSE
291
292Copyright 2007, 2008 Board of Trustees, Leland Stanford Jr. University.  All
293rights reserved.
294
295Permission to use, copy, modify, and distribute this software and its
296documentation for any purpose and without fee is hereby granted, provided
297that the above copyright notice appear in all copies and that both that
298copyright notice and this permission notice appear in supporting
299documentation, and that the name of Stanford University not be used in
300advertising or publicity pertaining to distribution of the software without
301specific, written prior permission.  Stanford University makes no
302representations about the suitability of this software for any purpose.  It
303is provided "as is" without express or implied warranty.
304
305THIS SOFTWARE IS PROVIDED "AS IS" AND WITHOUT ANY EXPRESS OR IMPLIED
306WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED WARRANTIES OF
307MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE.
308
309=cut
Note: See TracBrowser for help on using the repository browser.