1Net::Remctl(3)        User Contributed Perl Documentation       Net::Remctl(3)
2
3
4

NAME

6       Net::Remctl - Perl bindings for remctl (Kerberos remote command
7       execution)
8

SYNOPSIS

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
21           # 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

DESCRIPTION

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
55   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
59       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
71           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
76           The return value is a Net::Remctl::Result object which supports the
77           following methods:
78
79           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
86           stdout()
87               Returns the command's standard output or undef if there was
88               none.
89
90           stderr()
91               Returns the command's standard error or undef if there was
92               none.
93
94           status()
95               Returns the command's exit status.
96
97           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
102   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
109       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
115       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
122       The supported object methods are:
123
124       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
129       error()
130           [2.8] Retrieves the error message from the last failing operation
131           and returns it as a string.
132
133       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
142           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
150           Not all GSS-API implementations support setting the credential
151           cache.  If this is not supported, false will be returned.
152
153       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
161       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
170           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
177       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
187           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
192       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
202       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
207           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
217           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
223           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
229           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
235           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
239           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
244       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
251           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
257       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

COMPATIBILITY

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
269       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
273       The default port was changed to the IANA-registered port of 4373 in
274       version 2.11.
275
276       This module was first released with version 2.8.
277

CAVEATS

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
288       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
297       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

NOTES

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

AUTHOR

308       Russ Allbery <eagle@eyrie.org>
309
311       Copyright 2020, 2022 Russ Allbery <eagle@eyrie.org>
312
313       Copyright 2007-2008, 2011-2014 The Board of Trustees of the Leland
314       Stanford Junior University
315
316       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
324       The above copyright notice and this permission notice shall be included
325       in all copies or substantial portions of the Software.
326
327       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

SEE ALSO

336       remctl(1), remctld(8)
337
338       The current version of this module is available from its web page at
339       <https://www.eyrie.org/~eagle/software/remctl/>.
340
341
342
343perl v5.36.0                      2022-07-23                    Net::Remctl(3)
Impressum