1Net::Remctl(3) User Contributed Perl Documentation Net::Remctl(3)
2
6 Net::Remctl - Perl bindings for remctl (Kerberos remote command
7 execution)
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 $remctl->noop or die "Cannot send NOOP: ", $remctl->error, "\n";
46
48 Net::Remctl provides Perl bindings to the libremctl client library.
49 remctl is a protocol for remote command execution using GSS-API
50 authentication. The specific allowable commands must be listed in a
51 configuration file on the remote system and the remote system can map
52 the remctl command names to any local command without exposing that
53 mapping to the client. This module implements a remctl client.
54 Simplified Interface
56 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
61 Net::Remctl::Result object (see below). HOSTNAME is the remote
62 host to contact. PORT is the port of the remote remctld server and
63 may be 0 to tell the library to use the default (first try 4373,
64 the registered remctl port, and fall back to the legacy 4444 port
65 if that fails). PRINCIPAL is the principal of the server to use
66 for authentication; pass in the empty string to use the default of
67 host/HOSTNAME, with the realm determined by domain-realm mapping.
68 The remaining arguments are the remctl command and arguments passed
69 to the remote server.
70 As far as the module is concerned, undef may be passed as PORT and
72 PRINCIPAL and is the same as 0 and the empty string respectively.
73 However, Perl will warn about passing undef explicitly as a
74 function argument.
75 The return value is a Net::Remctl::Result object which supports the
77 following methods:
78 error()
80 Returns the error message from either the remote host or from
81 the local client library (if, for instance, contacting the
82 remote host failed). Returns undef if there was no error.
83 Checking whether error() returns undef is the supported way of
84 determining whether the remctl() call succeeded.
85 stdout()
87 Returns the command's standard output or undef if there was
88 none.
89 stderr()
91 Returns the command's standard error or undef if there was
92 none.
93 status()
95 Returns the command's exit status.
96 Each call to remctl() will open a new connection to the remote host
98 and close it after retrieving the results of the command. To
99 maintain a persistent connection, use the full interface described
100 below.
101 Full Interface
103 The full remctl library interface requires that the user do more
104 bookkeeping, but it provides more flexibility and allows one to issue
105 multiple 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 Methods below are annotated with the version at which they were added.
116 Note that this is the version of the remctl distribution, which only
117 matches the Net::Remctl module version in 3.05 and later. Earlier
118 versions of the module used an independent versioning system that is
119 not documented here, and versions earlier than 3.05 are therefore not
120 suitable for use with "use".
121 The supported object methods are:
123 new()
125 [2.8] Create a new Net::Remctl object. This doesn't attempt to
126 connect to a host and hence will only fail (by throwing an
127 exception) if the library cannot allocate memory.
128 error()
130 [2.8] Retrieves the error message from the last failing operation
131 and returns it as a string.
132 set_ccache(CCACHE)
134 [3.00] Sets the GSS-API credential cache for outgoing connections
135 to CCACHE, which is normally the path to a Kerberos ticket cache
136 but may have other valid forms depending on the underlying Kerberos
137 implementation in use by GSS-API. This method will affect all
138 subsequent open() calls on at least the same object, but will have
139 no effect on connections that are already open. Returns true on
140 success and false on failure.
141 If the remctl client library was built against a Kerberos library
143 and the GSS-API library supported gss_krb5_import_cred, this call
144 affects only this Net::Remctl object. Otherwise, this will affect
145 not only all subsequent open() calls for the same object, but all
146 subsequent remctl connections of any kind from the same process,
147 and even other GSS-API connections from the same process unrelated
148 to remctl.
149 Not all GSS-API implementations support setting the credential
151 cache. If this is not supported, false will be returned.
152 set_source_ip(SOURCE)
154 [3.00] Sets the source IP for outgoing connections to SOURCE, which
155 can be either an IPv4 or an IPv6 address (if IPv6 is supported).
156 It must be an IP address, not a host name. This will affect all
157 subsequent open() calls on the same object, but will have no effect
158 on connections that are already open. Returns true on success and
159 false on failure.
160 set_timeout(TIMEOUT)
162 [3.01] Sets the timeout for connections and commands to TIMEOUT,
163 which should be an integer number of seconds. TIMEOUT may be 0 to
164 clear a timeout that was previously set. All subsequent operations
165 on this Net::Remctl object will be subject to this timeout,
166 including open() if called prior to calling open(). Returns true
167 on success and false on failure. Failure is only possible if
168 TIMEOUT is malformed.
169 The timeout is a timeout on network activity from the server, not
171 on a complete operation. So, for example, a timeout of ten seconds
172 just requires that the server send some data every ten seconds. If
173 the server sends only tiny amounts of data at a time, the complete
174 operation could take much longer than ten seconds without
175 triggering the timeout.
176 open(HOSTNAME[, PORT[, PRINCIPAL]])
178 [2.8] Connect to HOSTNAME on port PORT using PRINCIPAL as the
179 remote server's principal for authentication. If PORT is omitted
180 or 0, use the default (first try 4373, the registered remctl port,
181 and fall back to the legacy 4444 port if that fails). If PRINCIPAL
182 is omitted or the empty string, use the default of host/HOSTNAME,
183 with the realm determined by domain-realm mapping. Returns true on
184 success, false on failure. On failure, call error() to get the
185 failure message.
186 As far as the module is concerned, undef may be passed as PORT and
188 PRINCIPAL and is the same as 0 and the empty string respectively.
189 However, Perl will warn about passing undef explicitly as a
190 function argument.
191 command(COMMAND[, ARGS, ...])
193 [2.8] Send the command and arguments to the remote host. The
194 command and the arguments may, under the remctl protocol, contain
195 any character, but be aware that most remctl servers will reject
196 commands or arguments containing ASCII 0 (NUL), so currently this
197 cannot be used for upload of arbitrary unencoded binary data.
198 Returns true on success (meaning success in sending the command,
199 and implying nothing about the result of the command), false on
200 failure. On failure, call error() to get the failure message.
201 output()
203 [2.8] Returns the next output token from the remote host. The
204 token is returned as a Net::Remctl::Output object, which supports
205 the following methods:
206 type()
208 Returns the type of the output token, which will be one of
209 "output", "error", "status", or "done". A command will result
210 in either one "error" token or zero or more "output" tokens
211 followed by a "status" token. After either a "error" or
212 "status" token is seen, another command can be issued. If the
213 caller tries to retrieve another output token when it has
214 already consumed all of them for that command, the library will
215 return a "done" token.
216 data()
218 Returns the contents of the token. This method only makes
219 sense for "output" and "error" tokens; otherwise, it will
220 return undef. Note that the returned value may contain any
221 character, including ASCII 0 (NUL).
222 length()
224 Returns the length of the data in the token. As with data(),
225 this method only makes sense for the "output" and "error"
226 tokens. It will return 0 if there is no data or if the data is
227 zero-length.
228 stream()
230 For an "output" token, returns the stream with which the data
231 is associated. Currently, only two stream values will be used:
232 1, meaning standard output; and 2, meaning standard error. The
233 value is undefined for all other output token types.
234 status()
236 For a "status" token, returns the exit status of the remote
237 command. The value is undefined for all other token types.
238 error()
240 For an "error" token, returns the remctl error code for the
241 protocol error. The text message will be returned by data().
242 The value is undefined for all other token types.
243 noop()
245 [3.00] Send a NOOP message to the server and read the reply. This
246 is primarily used to keep a connection to a remctl server alive,
247 such as through a firewall with a session timeout, while waiting to
248 issue further commands. Returns true on success, false on failure.
249 On failure, call error() to get the failure message.
250 The NOOP message requires protocol version 3 support in the server,
252 so the caller should be prepared for this function to fail,
253 indicating that the connection could not be kept alive and possibly
254 that it was closed by the server. In this case, the client will
255 need to explicitly reopen the connection with open().
256 Note that, due to internal implementation details in the library, the
258 Net::Remctl::Output object returned by output() will be invalidated by
259 the next call to command() or output() or by destroying the producing
260 Net::Remctl object. Therefore, any data in the output token should be
261 processed and stored if needed before making any further Net::Remctl
262 method calls on the same object.
263
265 The main object methods are annotated above with the version in which
266 that interface was added. All unannotated methods have been present
267 since the first release of the module.
268 Support for the gss_krb5_import_cred method of isolating the changed
270 ticket cache to only this remctl client object was added in version
271 3.5.
272 The default port was changed to the IANA-registered port of 4373 in
274 version 2.11.
275 This module was first released with version 2.8.
277
279 If the principal argument to remctl() or remctl_open() is NULL, most
280 GSS-API libraries will canonicalize the host using DNS before deriving
281 the principal name from it. This means that when connecting to a
282 remctl server via a CNAME, remctl() and remctl_open() will normally
283 authenticate using a principal based on the canonical name of the host
284 instead of the specified host parameter. This behavior may cause
285 problems if two consecutive DNS lookups of host may return two
286 different results, such as with some DNS-based load-balancing systems.
287 The canonicalization behavior is controlled by the GSS-API library;
289 with the MIT Kerberos GSS-API library, canonicalization can be disabled
290 by setting "rdns" to false in the [libdefaults] section of krb5.conf.
291 It can also be disabled by passing an explicit Kerberos principal name
292 via the principal argument, which will then be used without changes.
293 If canonicalization is desired, the caller may wish to canonicalize
294 host before calling remctl() or remctl_open() to avoid problems with
295 multiple DNS calls returning different results.
296 The default behavior, when the port is not specified, of trying 4373
298 and falling back to 4444 will be removed in a future version of this
299 module in favor of using the "remctl" service in /etc/services if set
300 and then falling back on only 4373. 4444 was the poorly-chosen
301 original remctl port and should be phased out.
302
304 The remctl port number, 4373, was derived by tracing the diagonals of a
305 QWERTY keyboard up from the letters "remc" to the number row.
306
308 Russ Allbery <eagle@eyrie.org>
309
311 Copyright 2020, 2022 Russ Allbery <eagle@eyrie.org>
312 Copyright 2007-2008, 2011-2014 The Board of Trustees of the Leland
314 Stanford Junior University
315 Permission is hereby granted, free of charge, to any person obtaining a
317 copy of this software and associated documentation files (the
318 "Software"), to deal in the Software without restriction, including
319 without limitation the rights to use, copy, modify, merge, publish,
320 distribute, sublicense, and/or sell copies of the Software, and to
321 permit persons to whom the Software is furnished to do so, subject to
322 the following conditions:
323 The above copyright notice and this permission notice shall be included
325 in all copies or substantial portions of the Software.
326 THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
328 OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
329 MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
330 IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
331 CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
332 TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
333 SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
334
336 remctl(1), remctld(8)
337 The current version of this module is available from its web page at
339 <https://www.eyrie.org/~eagle/software/remctl/>.
340perl v5.36.0 2023-01-20 Net::Remctl(3)