Net::Remctl(3pm)

📦

version 3.18 · 7 versions

3.18 · debian trixie, ubuntu questing (latest)
3.18 · epel 9
3.18 · ubuntu stonking
3.17 · ubuntu jammy
3.18 · ubuntu noble
3.18 · debian bookworm
3.18 · ubuntu resolute

💖 NAME 💖

okay so bestie, welcome to the Net::Remctl(3pm) manual — it's coming at you from User Contributed Perl Documentation. Net::Remctl is literally Perl bindings for remctl, aka Kerberos remote command execution. no cap, it's the Perl bestie for talking to remctl. 💅

✨ SYNOPSIS ✨

there are two whole vibes here: the simplified form first, and then the full interface for when you want every little bit of control. both are right here, fr fr.

# Simplified form.
use Net::Remctl;
my $result = remctl("hostname", undef, undef, "test", "echo", "Hi");
if ($result->error) {
    die "test echo failed with error ", $result->error, "\n";
} else {
    warn $result->stderr;
    print $result->stdout;
    exit $result->status;
}

and now the full interface, because sometimes you want the whole menu, not just the snack:

# Full interface.
use Net::Remctl ();
my $remctl = Net::Remctl->new;
$remctl->open("hostname")
    or die "Cannot connect to hostname: ", $remctl->error, "\n";
$remctl->command("test", "echo", "Hi there")
    or die "Cannot send command: ", $remctl->error, "\n";
my $output;
do {
    $output = $remctl->output;
    if ($output->type eq 'output') {
        if ($output->stream == 1) {
            print $output->data;
        } elsif ($output->stream == 2) {
            warn $output->data;
        }
    } elsif ($output->type eq 'error') {
        warn $output->error, "\n";
    } elsif ($output->type eq 'status') {
        exit $output->status;
    } else {
        die "Unknown output token from library: ", $output->type, "\n";
    }
} while ($output->type eq 'output');
$remctl->noop or die "Cannot send NOOP: ", $remctl->error, "\n";

okay bestie, buckle up, because Net::Remctl is the Perl glow-up for the libremctl client library 💅

remctl is a protocol for remote command execution that uses GSS-API authentication. The specific commands you're actually allowed to run have to be listed in a config file on the remote system, and — this is the iconic part — the remote system can map remctl command names to literally any local command it wants without exposing that mapping to the client. This module implements a remctl client. No cap. 🦋

✨ Simplified Interface ✨

If you just wanna run one single command on a remote system and get the output and exit status back, use the exported remctl() function. So simple, so clean, main character energy fr fr.

remctl(HOSTNAME, PORT, PRINCIPAL, COMMAND, [ARGS, ...])

Runs a command on the remote system and hands you back a Net::Remctl::Result object (more on that below, keep reading bestie 👀).

HOSTNAME — the remote host you're contacting.
PORT — the port of the remote remctld server, and it may be 0 to tell the library to just use the default. The default is: first try 4373, the registered remctl port, and then fall back to the legacy 4444 port if that fails. Lowkey iconic behaviour.
PRINCIPAL — the principal of the server to use for authentication. Pass in the empty string to use the default of host/HOSTNAME, with the realm determined by domain-realm mapping.
The remaining arguments are the remctl command and the arguments passed to the remote server.

As far as this module is concerned, undef may be passed as PORT and PRINCIPAL and it's the same as 0 and the empty string respectively. But heads up: Perl will warn about passing undef explicitly as a function argument, so like... don't do that unless you want the noise 🙈

The return value is a Net::Remctl::Result object which supports the following methods:

error() — returns the error message from either the remote host or from the local client library (if, for instance, contacting the remote host failed). Returns undef if there was no error. Checking whether error() returns undef is the supported way of determining whether the remctl() call succeeded. That's the vibe check you need, periodt.
stdout() — returns the command's standard output, or undef if there was none.
stderr() — returns the command's standard error, or undef if there was none.
status() — returns the command's exit status.

Each call to remctl() will open a new connection to the remote host and close it after retrieving the results of the command. To maintain a persistent connection, use the full interface described below. It's giving "one and done" vs "let's stay in touch" 💖

🌸 Full Interface 🌸

The full remctl library interface requires that you do more bookkeeping, ngl, but it provides more flexibility and lets you issue multiple commands on the same persistent connection — provided that the remote server supports protocol version two. If not, the library will transparently fall back to opening a new connection for each command. It's got your back 🫶

To use the full interface: first create a Net::Remctl object with new(), and then connect() to a remote server. Then, issue a command() and call output() to retrieve output tokens (as Net::Remctl::Output objects) until a status token is received. Destroying the Net::Remctl object will close the connection. Cleanup queen ✨

Methods below are annotated with the version at which they were added. Note that this is the version of the remctl distribution, which only matches the Net::Remctl module version in 3.05 and later. Earlier versions of the module used an independent versioning system that is not documented here, and versions earlier than 3.05 are therefore not suitable for use with "use". Not me warning you about version chaos 💀

The supported object methods are:

new() — [2.8] Create a new Net::Remctl object. This doesn't attempt to connect to a host, and hence will only fail (by throwing an exception) if the library cannot allocate memory.
error() — [2.8] Retrieves the error message from the last failing operation and returns it as a string.
set_ccache(CCACHE) — [3.00] Sets the GSS-API credential cache for outgoing connections to CCACHE, which is normally the path to a Kerberos ticket cache but may have other valid forms depending on the underlying Kerberos implementation in use by GSS-API. This method will affect all subsequent open() calls on at least the same object, but will have no effect on connections that are already open. Returns true on success and false on failure.

If the remctl client library was built against a Kerberos library and the GSS-API library supported gss_krb5_import_cred, this call affects only this Net::Remctl object. Otherwise, this will affect not only all subsequent open() calls for the same object, but all subsequent remctl connections of any kind from the same process, and even other GSS-API connections from the same process unrelated to remctl. Yeah. Scope creep, literally.

Not all GSS-API implementations support setting the credential cache. If this is not supported, false will be returned.

set_source_ip(SOURCE) — [3.00] Sets the source IP for outgoing connections to SOURCE, which can be either an IPv4 or an IPv6 address (if IPv6 is supported). It must be an IP address, not a host name. This will affect all subsequent open() calls on the same object, but will have no effect on connections that are already open. Returns true on success and false on failure.
set_timeout(TIMEOUT) — [3.01] Sets the timeout for connections and commands to TIMEOUT, which should be an integer number of seconds. TIMEOUT may be 0 to clear a timeout that was previously set. All subsequent operations on this Net::Remctl object will be subject to this timeout, including open() if called prior to calling open(). Returns true on success and false on failure. Failure is only possible if TIMEOUT is malformed.

The timeout is a timeout on network activity from the server, not on a complete operation. So, for example, a timeout of ten seconds just requires that the server send some data every ten seconds. If the server sends only tiny amounts of data at a time, the complete operation could take much longer than ten seconds without triggering the timeout. It's giving "still alive, still texting" not "finish already" 😭

open(HOSTNAME[, PORT[, PRINCIPAL]]) — [2.8] Connect to HOSTNAME on port PORT using PRINCIPAL as the remote server's principal for authentication. If PORT is omitted or 0, use the default (first try 4373, the registered remctl port, and fall back to the legacy 4444 port if that fails). If PRINCIPAL is omitted or the empty string, use the default of host/HOSTNAME, with the realm determined by domain-realm mapping. Returns true on success, false on failure. On failure, call error() to get the failure message.

As far as the module is concerned, undef may be passed as PORT and PRINCIPAL and is the same as 0 and the empty string respectively. However, Perl will warn about passing undef explicitly as a function argument. (Yes, same warning as before. It's consistent. We stan consistency 💅)

command(COMMAND[, ARGS, ...]) — [2.8] Send the command and arguments to the remote host. The command and the arguments may, under the remctl protocol, contain any character, but be aware that most remctl servers will reject commands or arguments containing ASCII 0 (NUL), so currently this cannot be used for upload of arbitrary unencoded binary data. Returns true on success (meaning success in sending the command, and implying nothing about the result of the command), false on failure. On failure, call error() to get the failure message.

Sending it ≠ it worked. "Success" here is just "the send went through", bestie. Don't confuse the two 👑

output() — [2.8] Returns the next output token from the remote host. The token is returned as a Net::Remctl::Output object, which supports the following methods:
- type() — Returns the type of the output token, which will be one of "output", "error", "status", or "done". A command will result in either one "error" token or zero or more "output" tokens followed by a "status" token. After either a "error" or "status" token is seen, another command can be issued. If the caller tries to retrieve another output token when it has already consumed all of them for that command, the library will return a "done" token.
- data() — Returns the contents of the token. This method only makes sense for "output" and "error" tokens; otherwise, it will return undef. Note that the returned value may contain any character, including ASCII 0 (NUL). 🫣
- length() — Returns the length of the data in the token. As with data(), this method only makes sense for the "output" and "error" tokens. It will return 0 if there is no data or if the data is zero-length.
- stream() — For an "output" token, returns the stream with which the data is associated. Currently, only two stream values will be used: 1, meaning standard output; and 2, meaning standard error. The value is undefined for all other output token types.
- status() — For a "status" token, returns the exit status of the remote command. The value is undefined for all other token types.
- error() — For an "error" token, returns the remctl error code for the protocol error. The text message will be returned by data(). The value is undefined for all other token types.
noop() — [3.00] Send a NOOP message to the server and read the reply. This is primarily used to keep a connection to a remctl server alive, such as through a firewall with a session timeout, while waiting to issue further commands. Returns true on success, false on failure. On failure, call error() to get the failure message.

The NOOP message requires protocol version 3 support in the server, so the caller should be prepared for this function to fail, indicating that the connection could not be kept alive and possibly that it was closed by the server. In this case, the client will need to explicitly reopen the connection with open(). Keep-alive failed, bestie — you're gonna have to re-open it yourself. 🧚

Note that, due to internal implementation details in the library, the Net::Remctl::Output object returned by output() will be invalidated by the next call to command() or output() or by destroying the producing Net::Remctl object. Therefore, any data in the output token should be processed and stored if needed before making any further Net::Remctl method calls on the same object.

So like... copy that data out immediately. It's giving limited-edition drop, it's gone the second you look away 💀🌸

✨ COMPATIBILITY ✨

okay so the main object methods up above all got little annotations next to them telling you which version added that interface, right? Well — every method that does not have an annotation has been there since the very first release of this module. OG status. 👑

Support for the gss_krb5_import_cred method — the one that isolates the changed ticket cache to only this remctl client object — was added in version 3.5.

The default port got switched to the IANA-registered port of 4373 in version 2.11.

And this module? First released with version 2.8. Baby pics. 🍼

💀 CAVEATS 💀

bestie listen. this one matters.

If the principal argument to remctl() or remctl_open() is NULL, most GSS-API libraries will canonicalize the host using DNS before deriving the principal name from it. Which means: when you're connecting to a remctl server via a CNAME, remctl() and remctl_open() will normally authenticate using a principal based on the canonical name of the host instead of the host parameter you actually specified. 😭

And that can cause problems if two consecutive DNS lookups of host return two different results — like, say, with some DNS-based load-balancing systems. Not the vibe.

The canonicalization behavior is controlled by the GSS-API library. With the MIT Kerberos GSS-API library, you can turn canonicalization off by setting "rdns" to false in the [libdefaults] section of krb5.conf. You can also disable it by passing an explicit Kerberos principal name via the principal argument — which will then be used without changes. And if you do want canonicalization, you might wanna canonicalize host yourself before calling remctl() or remctl_open(), so you dodge the whole "multiple DNS calls returning different results" mess. 🫠

Also, heads up: the default behavior — when the port is not specified — of trying 4373 and falling back to 4444 will be removed in a future version of this module. It's getting replaced by using the "remctl" service in /etc/services if set, and then falling back on only 4373. Because 4444 was the poorly-chosen original remctl port and it should be phased out. periodt. 💅

📝 NOTES 📝

The remctl port number, 4373, was derived by tracing the diagonals of a QWERTY keyboard up from the letters "remc" to the number row.

I KNOW. iconic. that's the kind of lore you can't make up. 🌈✨

👑 AUTHOR 👑

Russ Allbery <eagle@eyrie.org>

🎀 COPYRIGHT AND LICENSE 🎀

Permission is hereby granted, free of charge, to any person obtaining a
copy of this software and associated documentation files (the
"Software"), to deal in the Software without restriction, including
without limitation the rights to use, copy, modify, merge, publish,
distribute, sublicense, and/or sell copies of the Software, and to
permit persons to whom the Software is furnished to do so, subject to
the following conditions:

The above copyright notice and this permission notice shall be included
in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

(yes the all-caps parts are legally required screaming. not me yelling at you fr fr, that's just how warranties work 🙈)

🌸 SEE ALSO 🌸

remctl(1), remctld(8)

The current version of this module is available from its web page at <https://www.eyrie.org/~eagle/software/remctl/>. go get it, bestie 🦋

and that's a wrap on the whole page!! this one's from perl v5.40.1, dated 2025-04-12, and it lives at Net::Remctl(3pm). mwah 💖💅✨

📦 where this page comes from

debian trixie: libnet-remctl-perl 3.18-3 · MIT
ubuntu questing: libnet-remctl-perl 3.18-3
💖 girlified by deepseek-ai/DeepSeek-V4.1-Flash on 2026-10-14: a language model's rewrite of the original, under its terms