1Remctl(3) User Contributed Perl Documentation Remctl(3)
2
6 Net::Remctl - Perl bindings for remctl (Kerberos remote command execu‐
7 tion)
8
10 # Simplified form.
11 use Net::Remctl;
12 my $result = remctl("hostname", undef, undef, "test", "echo", "Hi");
13 if ($result->error) {
14 die "test echo failed with error ", $result->error, "\n";
15 } else {
16 warn $result->stderr;
17 print $result->stdout;
18 exit $result->status;
19 }
20 # Full interface.
22 use Net::Remctl ();
23 my $remctl = Net::Remctl->new;
24 $remctl->open("hostname")
25 or die "Cannot connect to hostname: ", $remctl->error, "\n";
26 $remctl->command("test", "echo", "Hi there")
27 or die "Cannot send command: ", $remctl->error, "\n";
28 my $output;
29 do {
30 $output = $remctl->output;
31 if ($output->type eq 'output') {
32 if ($output->stream == 1) {
33 print $output->data;
34 } elsif ($output->stream == 2) {
35 warn $output->data;
36 }
37 } elsif ($output->type eq 'error') {
38 warn $output->error, "\n";
39 } elsif ($output->type eq 'status') {
40 exit $output->status;
41 } else {
42 die "Unknown output token from library: ", $output->type, "\n";
43 }
44 } while ($output->type eq 'output');
45
47 Net::Remctl provides Perl bindings to the libremctl client library.
48 remctl is a protocol for remote command execution using GSS-API authen‐
49 tication. The specific allowable commands must be listed in a configu‐
50 ration file on the remote system and the remote system can map the rem‐
51 ctl command names to any local command without exposing that mapping to
52 the client. This module implements a remctl client.
53 Simplified Interface
55 If you want to run a single command on a remote system and get back the
57 output and exit status, you can use the exported remctl() function:
58 remctl(HOSTNAME, PORT, PRINCIPAL, COMMAND, [ARGS, ...])
60 Runs a command on the remote system and returns a Net::Rem‐
61 ctl::Result object (see below). HOSTNAME is the remote host to
62 contact. PORT is the port of the remote remctld server and may be
63 0 to tell the library to use the default (first try 4373, the reg‐
64 istered remctl port, and fall back to the legacy 4444 port if that
65 fails). PRINCIPAL is the principal of the server to use for
66 authentication; pass in the empty string to use the default of
67 host/hostname in the default local realm. The remaining arguments
68 are the remctl command and arguments passed to the remote server.
69 As far as the module is concerned, undef may be passed as PORT and
71 PRINCIPAL and is the same as 0 and the empty string respectively.
72 However, Perl will warn about passing undef explicitly as a func‐
73 tion argument.
74 The return value is a Net::Remctl::Result object which supports the
76 following methods:
77 error()
79 Returns the error message from either the remote host or from
80 the local client library (if, for instance, contacting the
81 remote host failed). Returns undef if there was no error.
82 Checking whether error() returns undef is the supported way of
83 determining whether the remctl() call succeeded.
84 stdout()
86 Returns the command's standard output or undef if there was
87 none.
88 stderr()
90 Returns the command's standard error or undef if there was
91 none.
92 status()
94 Returns the command's exit status.
95 Each call to remctl() will open a new connection to the remote host
97 and close it after retrieving the results of the command. To main‐
98 tain a persistant connection, use the full interface described
99 below.
100 Full Interface
102 The full remctl library interface requires that the user do more book‐
104 keeping, but it provides more flexibility and allows one to issue mul‐
105 tiple commands on the same persistent connection (provided that the
106 remote server supports protocol version two; if not, the library will
107 transparently fall back to opening a new connection for each command).
108 To use the full interface, first create a Net::Remctl object with new()
110 and then connect() to a remote server. Then, issue a command() and
111 call output() to retrieve output tokens (as Net::Remctl::Output
112 objects) until a status token is received. Destroying the Net::Remctl
113 object will close the connection.
114 The supported object methods are:
116 new()
118 Create a new Net::Remctl object. This doesn't attempt to connect
119 to a host and hence will only fail (by throwing an exception) if
120 the library cannot allocate memory.
121 error()
123 Retrieves the error message from the last failing operation and
124 returns it as a string.
125 open(HOSTNAME[, PORT[, PRINCIPAL]])
127 Connect to HOSTNAME on port PORT using PRINCIPAL as the remote
128 server's principal for authentication. If PORT is omitted, undef,
129 or 0, use the default (first try 4373, the registered remctl port,
130 and fall back to the legacy 4444 port if that fails). If PRINCIPAL
131 is omitted or undef, use the default of host/hostname in the local
132 realm. Returns true on success, false on failure. On failure,
133 call error() to get the failure message.
134 command(COMMAND[, ARGS, ...])
136 Send the command and arguments to the remote host. The command and
137 the arguments may, under the remctl protocol, contain any charac‐
138 ter, but be aware that most remctl servers will reject commands or
139 arguments containing ASCII 0 (NUL), so currently this cannot be
140 used for upload of arbitrary unencoded binary data. Returns true
141 on success (meaning success in sending the command, and implying
142 nothing about the result of the command), false on failure. On
143 failure, call error() to get the failure message.
144 output()
146 Returns the next output token from the remote host. The token is
147 returned as a Net::Remctl::Output object, which supports the fol‐
148 lowing methods:
149 type()
151 Returns the type of the output token, which will be one of
152 "output", "error", "status", or "done". A command will result
153 in either one "error" token or zero or more "output" tokens
154 followed by a "status" token. After either a "error" or "sta‐
155 tus" token is seen, another command can be issued. If the
156 caller tries to retrieve another output token when it has
157 already consumed all of them for that command, the library will
158 return a "done" token.
159 data()
161 Returns the contents of the token. This method only makes
162 sense for "output" and "error" tokens; otherwise, it will
163 return undef. Note that the returned value may contain any
164 character, including ASCII 0 (NUL).
165 length()
167 Returns the length of the data in the token. As with data(),
168 this method only makes sense for the "output" and "error"
169 tokens. It will return 0 if there is no data or if the data is
170 zero-length.
171 stream()
173 For an "output" token, returns the stream with which the data
174 is associated. Currently, only two stream values will be used:
175 1, meaning standard output; and 2, meaning standard error. The
176 value is undefined for all other output token types.
177 status()
179 For a "status" token, returns the exit status of the remote
180 command. The value is undefined for all other token types.
181 error()
183 For an "error" token, returns the remctl error code for the
184 protocol error. The text message will be returned by data().
185 The value is undefined for all other token types.
186 Note that, due to internal implementation details in the library, the
188 Net::Remctl::Output object returned by output() will be invalidated by
189 the next call to command() or output() or by destroying the producing
190 Net::Remctl object. Therefore, any data in the output token should be
191 processed and stored if needed before making any further Net::Remctl
192 method calls on the same object.
193
195 The default behavior, when the port is not specified, of trying 4373
196 and falling back to 4444 will be removed in a future version of this
197 module in favor of using the "remctl" service in /etc/services if set
198 and then falling back on only 4373. 4444 was the poorly-chosen origi‐
199 nal remctl port and should be phased out.
200
202 The remctl port number, 4373, was derived by tracing the diagonals of a
203 QWERTY keyboard up from the letters "remc" to the number row.
204
206 remctl(1), remctld(8)
207 The current version of this module is available from its web page at
209 <http://www.eyrie.org/~eagle/software/remctl/>.
210
212 Russ Allbery <rra@stanford.edu>
213
215 Copyright 2007 Board of Trustees, Leland Stanford Jr. University. All
216 rights reserved.
217 Permission to use, copy, modify, and distribute this software and its
219 documentation for any purpose and without fee is hereby granted, pro‐
220 vided that the above copyright notice appear in all copies and that
221 both that copyright notice and this permission notice appear in sup‐
222 porting documentation, and that the name of Stanford University not be
223 used in advertising or publicity pertaining to distribution of the
224 software without specific, written prior permission. Stanford Univer‐
225 sity makes no representations about the suitability of this software
226 for any purpose. It is provided "as is" without express or implied
227 warranty.
228 THIS SOFTWARE IS PROVIDED "AS IS" AND WITHOUT ANY EXPRESS OR IMPLIED
230 WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED WARRANTIES OF
231 MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE.
232perl v5.8.8 2007-09-02 Remctl(3)