REMCTL(1)

📦
version 3.18 · 3 versions
, in debian bookworm, debian trixie, epel 9, ubuntu noble, ubuntu questing, ubuntu resolute, ubuntu stonking

💅 remctl(1) — the manual page, but make it make sense

okay bestie, sit down, hydrate, because we're about to talk about remctl, the remote execution tool, and it's genuinely so good. this is section 1 of the manual, so it's a user command — you run it, it does a thing. slay.

✨ NAME ✨

remctl — Remote execution tool. that's it, that's the name, it's giving "does what it says on the tin."

✨ SYNOPSIS ✨

remctl [-dhv] [-b source-ip] [-p port] [-s service]
    [-t timeout] host command [subcommand [parameters ...]]

look at her. she's flexible. she's got options. she's got a host and a command and then however many subcommands and parameters you feel like throwing at her. iconic behavior.

✨ DESCRIPTION ✨

so remctl is literally just a program that lets you execute commands remotely on a server that's running the remctld daemon. that's the whole vibe. 🦋

here's the important part though — remctl does not interpret the commands you give it. she is not out here reading your mind or your shell syntax. she takes what you typed, hands it to the server, and shows you the return message. that's it. no notes. 💅

which means: the commands have to already be defined on the server side before a remctl client can even try to execute them, and the user running remctl has to be authorized to execute that particular command on that particular server. no sneaking in, no cap. 🚫

access to remote commands is authenticated via Kerberos GSS-API, so bestie you need a ticket granting ticket to use remctl. non-negotiable. and every single transmission going to and from the remctld server is encrypted using GSS-API's security layer. locked down, sealed up, safe. 🔐✨

so, the arguments:

  • host — the hostname of the target server. the address, the destination, the place we're going. 🏠
  • command and subcommand — together these specify the command to run, and they correspond to the command names in the configuration file on the server. yes, they have to match. the server is checking. 👀
  • parameters — any extra command-line parameters you want to pass along to the remote command. go off, add as many as you need. 🎀

✨ OPTIONS ✨

heads up: the start of each option description is annotated with the version of remctl in which that option was added with its current meaning. so when you see [3.0] that's a "she's been like this since 3.0" moment. okay let's go, one by one, no skipping. 👑

  • -b source-ip — [3.0] when connecting to the remote remctl server, use source-ip as the source IP address. this is lowkey a lifesaver on multihomed systems where your remctl connections need to go out over one particular network. source-ip has to be an actual IP address, not a hostname — and it can be either an IPv4 or IPv6 address (assuming IPv6 is supported, which, in this economy, hopefully). 📡
  • -d — [1.10] turn on extra debugging output of the client-server interaction. it's giving "let me see what y'all are saying to each other." 🕵️♀️
  • -h — [1.10] show a brief usage message and then exit. the classic "help me help you." 🫶
  • -p port — [1.0] connect to the server on port. and if you don't give this option? the client first tries the registered remctl port (4373) and then falls back on the legacy port (4444) if that fails. two chances, bestie. 💫
  • -s service — [1.0] authenticate to the server with a service ticket for service rather than the default server identity of host/hostname. you might need this with, for instance, a server where remctld is not running as root. very "she doesn't have root and that's fine" energy. 🎀
  • -t timeout — [3.16] set the timeout for all network operations to timeout (in seconds).
okay important, read this twice: this is a timeout on network activity, not on a complete operation. so like, a timeout of ten seconds just means the server needs to send some data at least every ten seconds. if the server is out here dribbling out tiny amounts of data at a time, the complete operation could take wayyyyy longer without ever triggering the timeout. not me warning you about this in advance. 😭
  • -v — [1.10] print the version of remctl and exit. short and sweet, we love her. ⭐

✨ EXIT STATUS ✨

remctl will exit with the exit status returned by the remote command. yes, she's a messenger, she brings back the receipts. 🧾

but — if some network or authentication error occurred and remctl was unable to run the remote command or retrieve its exit status, or if remctl was called with invalid arguments, remctl will exit with status 1. so 1 is the "something went wrong on my end" number. noted. 💀

✨ EXAMPLES ✨

release an AFS volume called ls.tripwire:

remctl lsdb afs release ls.tripwire

ate. no crumbs. 🔥

✨ COMPATIBILITY ✨

  • the default port was changed to the IANA-registered port of 4373 in version 2.11.
  • support for IPv6 was added in version 2.4.

growth. evolution. glow-up. 🌈

✨ CAVEATS ✨

okay this is the section where we get real, because there are some things you genuinely need to know.

  • if no principal is specified with -s, remctl canonicalizes the server host name using DNS before connecting. this makes sure that the network connection and the GSS-API authentication use the same server name, even if some common DNS-based load-balancing schemes are in use. and if you want to turn that canonicalization off? specify the server principal using -s. simple as that. 🧚
  • 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 remctl, in favor of using the "remctl" service in /etc/services if set and then falling back on only 4373. 4444 was the poorly-chosen original remctl port and should be phased out. she's legacy, bestie, let her rest. ⚰️
  • when using Heimdal with triple-DES keys and talking to old servers that only speak version one of the remctl protocol, remctl may have problems with MIC verification. this doesn't affect new clients and servers, since the version two protocol doesn't use MICs. if you are using Heimdal and you run into MIC verification problems, see the COMPATIBILITY section of gssapi(3). 🙈

✨ 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.

that's it. that's the lore. and honestly? it's iconic. someone sat there with a keyboard and followed the vibes and now it's in the IANA registry. 👑

✨ AUTHOR ✨

remctl was originally written by Anton Ushakov. updates and current maintenance are done by Russ Allbery <eagle@eyrie.org>.

thank you for your service, both of you. 🫶

Copyright 2018 Russ Allbery <eagle@eyrie.org>

Copyright 2002-2011, 2014 The Board of Trustees of the Leland Stanford Junior University

Copying and distribution of this file, with or without modification, are permitted in any medium without royalty provided the copyright notice and this notice are preserved. This file is offered as-is, without any warranty.

SPDX-License-Identifier: FSFAP

(translation: use it, share it, just keep the receipts and don't come for anybody if it breaks. 💖)

✨ SEE ALSO ✨

the current version of this program is available from its web page at <https://www.eyrie.org/~eagle/software/remctl/>. go check it out, she's thriving. 🌸

and that's the whole page, bestie. this was remctl(1) from the remctl package, version 3.18, dated 2022-05-09. mwah. 💋✨ go run something remotely, you've earned it. 💅🦋

📦 where this page comes from