1Remctl(3) User Contributed Perl Documentation 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
47 Net::Remctl provides Perl bindings to the libremctl client library.
48 remctl is a protocol for remote command execution using GSS-API
49 authentication. The specific allowable commands must be listed in a
50 configuration file on the remote system and the remote system can map
51 the remctl command names to any local command without exposing that
52 mapping to 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
56 output and exit status, you can use the exported remctl() function:
57 remctl(HOSTNAME, PORT, PRINCIPAL, COMMAND, [ARGS, ...])
59 Runs a command on the remote system and returns a
60 Net::Remctl::Result object (see below). HOSTNAME is the remote
61 host to contact. PORT is the port of the remote remctld server and
62 may be 0 to tell the library to use the default (first try 4373,
63 the registered remctl port, and fall back to the legacy 4444 port
64 if that fails). PRINCIPAL is the principal of the server to use
65 for authentication; pass in the empty string to use the default of
66 host/hostname in the default local realm. The remaining arguments
67 are the remctl command and arguments passed to the remote server.
68 As far as the module is concerned, undef may be passed as PORT and
70 PRINCIPAL and is the same as 0 and the empty string respectively.
71 However, Perl will warn about passing undef explicitly as a
72 function argument.
73 The return value is a Net::Remctl::Result object which supports the
75 following methods:
76 error()
78 Returns the error message from either the remote host or from
79 the local client library (if, for instance, contacting the
80 remote host failed). Returns undef if there was no error.
81 Checking whether error() returns undef is the supported way of
82 determining whether the remctl() call succeeded.
83 stdout()
85 Returns the command's standard output or undef if there was
86 none.
87 stderr()
89 Returns the command's standard error or undef if there was
90 none.
91 status()
93 Returns the command's exit status.
94 Each call to remctl() will open a new connection to the remote host
96 and close it after retrieving the results of the command. To
97 maintain a persistant connection, use the full interface described
98 below.
99 Full Interface
101 The full remctl library interface requires that the user do more
102 bookkeeping, but it provides more flexibility and allows one to issue
103 multiple commands on the same persistent connection (provided that the
104 remote server supports protocol version two; if not, the library will
105 transparently fall back to opening a new connection for each command).
106 To use the full interface, first create a Net::Remctl object with new()
108 and then connect() to a remote server. Then, issue a command() and
109 call output() to retrieve output tokens (as Net::Remctl::Output
110 objects) until a status token is received. Destroying the Net::Remctl
111 object will close the connection.
112 The supported object methods are:
114 new()
116 Create a new Net::Remctl object. This doesn't attempt to connect
117 to a host and hence will only fail (by throwing an exception) if
118 the library cannot allocate memory.
119 error()
121 Retrieves the error message from the last failing operation and
122 returns it as a string.
123 open(HOSTNAME[, PORT[, PRINCIPAL]])
125 Connect to HOSTNAME on port PORT using PRINCIPAL as the remote
126 server's principal for authentication. If PORT is omitted, undef,
127 or 0, use the default (first try 4373, the registered remctl port,
128 and fall back to the legacy 4444 port if that fails). If PRINCIPAL
129 is omitted or undef, use the default of host/hostname in the local
130 realm. Returns true on success, false on failure. On failure,
131 call error() to get the failure message.
132 command(COMMAND[, ARGS, ...])
134 Send the command and arguments to the remote host. The command and
135 the arguments may, under the remctl protocol, contain any
136 character, but be aware that most remctl servers will reject
137 commands or arguments containing ASCII 0 (NUL), so currently this
138 cannot be used for upload of arbitrary unencoded binary data.
139 Returns true on success (meaning success in sending the command,
140 and implying nothing about the result of the command), false on
141 failure. On failure, call error() to get the failure message.
142 output()
144 Returns the next output token from the remote host. The token is
145 returned as a Net::Remctl::Output object, which supports the
146 following methods:
147 type()
149 Returns the type of the output token, which will be one of
150 "output", "error", "status", or "done". A command will result
151 in either one "error" token or zero or more "output" tokens
152 followed by a "status" token. After either a "error" or
153 "status" token is seen, another command can be issued. If the
154 caller tries to retrieve another output token when it has
155 already consumed all of them for that command, the library will
156 return a "done" token.
157 data()
159 Returns the contents of the token. This method only makes
160 sense for "output" and "error" tokens; otherwise, it will
161 return undef. Note that the returned value may contain any
162 character, including ASCII 0 (NUL).
163 length()
165 Returns the length of the data in the token. As with data(),
166 this method only makes sense for the "output" and "error"
167 tokens. It will return 0 if there is no data or if the data is
168 zero-length.
169 stream()
171 For an "output" token, returns the stream with which the data
172 is associated. Currently, only two stream values will be used:
173 1, meaning standard output; and 2, meaning standard error. The
174 value is undefined for all other output token types.
175 status()
177 For a "status" token, returns the exit status of the remote
178 command. The value is undefined for all other token types.
179 error()
181 For an "error" token, returns the remctl error code for the
182 protocol error. The text message will be returned by data().
183 The value is undefined for all other token types.
184 Note that, due to internal implementation details in the library, the
186 Net::Remctl::Output object returned by output() will be invalidated by
187 the next call to command() or output() or by destroying the producing
188 Net::Remctl object. Therefore, any data in the output token should be
189 processed and stored if needed before making any further Net::Remctl
190 method calls on the same object.
191
193 The default behavior, when the port is not specified, of trying 4373
194 and falling back to 4444 will be removed in a future version of this
195 module in favor of using the "remctl" service in /etc/services if set
196 and then falling back on only 4373. 4444 was the poorly-chosen
197 original remctl port and should be phased out.
198
200 The remctl port number, 4373, was derived by tracing the diagonals of a
201 QWERTY keyboard up from the letters "remc" to the number row.
202
204 remctl(1), remctld(8)
205 The current version of this module is available from its web page at
207 <http://www.eyrie.org/~eagle/software/remctl/>.
208
210 Russ Allbery <rra@stanford.edu>
211
213 Copyright 2007 Board of Trustees, Leland Stanford Jr. University. All
214 rights reserved.
215 Permission to use, copy, modify, and distribute this software and its
217 documentation for any purpose and without fee is hereby granted,
218 provided that the above copyright notice appear in all copies and that
219 both that copyright notice and this permission notice appear in
220 supporting documentation, and that the name of Stanford University not
221 be used in advertising or publicity pertaining to distribution of the
222 software without specific, written prior permission. Stanford
223 University makes no representations about the suitability of this
224 software for any purpose. It is provided "as is" without express or
225 implied warranty.
226 THIS SOFTWARE IS PROVIDED "AS IS" AND WITHOUT ANY EXPRESS OR IMPLIED
228 WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED WARRANTIES OF
229 MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE.
230perl v5.12.0 2007-09-02 Remctl(3)