NAME
remctl - Remote execution tool
SYNOPSIS
remctl [-dhv] [-p port] [-s service] host command
[subcommand [parameters ...]]
DESCRIPTION
remctl is a program that allows a user to execute commands remotely on
a server that is running the remctld daemon. remctl does not interpret
the commands given to it. It passes them to the server and displays
the return message. The commands must be defined on the server-side
before a remctl client can execute them, and the user running remctl
must be authorized to execute the particular command on the server.
Access to remote commands is authenticated via Kerberos v5 GSS-API, so
a user must have a ticket granting ticket to use remctl. All
transmissions to and from the remctld server are encrypted using GSS-
API’s security layer.
host is the hostname of the target server. command and subcommand
together specify the command to run and correspond to the command names
in the configuration file on the server. parameters are any additional
command-line parameters to pass to the remote command.
OPTIONS
-d Turn on extra debugging output of the client-server interaction.
-h Show a brief usage message and then exit.
-p port
Connect to the server on port. If this option isn’t given, the
client first tries the registered remctl port (4373) and then falls
back on the legacy port (4444) if that fails.
-s service
Authenticate to the server with a service ticket for service rather
than the default server identity of host/hostname. This may be
necessary with, for instance, a server where remctld is not running
as root.
-v Print the version of remctl and exit.
EXIT STATUS
remctl will exit with the exit status returned by the remote command.
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.
EXAMPLES
Release an AFS volume called ls.tripwire:
remctl lsdb afs release ls.tripwire
CAVEATS
If no principal is specified with -s, remctl canonicalizes the server
host name using DNS before connecting. This ensures 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. To disable
this canonicalization, specify the server principal using -s.
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.
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 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.
SEE ALSO
kinit(1), remctld(8)
The current version of this program is available from its web page at
<http://www.eyrie.org/~eagle/software/remctl/>.
AUTHOR
Anton Ushakov <antonu@stanford.edu> is the original author. Updates
and current maintenance are done by Russ Allbery <rra@stanford.edu>.
COPYRIGHT AND LICENSE
Copyright 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009 Board of
Trustees, Leland Stanford Jr. University. All rights reserved.
Permission to use, copy, modify, and distribute this software and its
documentation for any purpose and without fee is hereby granted,
provided that the above copyright notice appear in all copies and that
both that copyright notice and this permission notice appear in
supporting documentation, and that the name of Stanford University not
be used in advertising or publicity pertaining to distribution of the
software without specific, written prior permission. Stanford
University makes no representations about the suitability of this
software for any purpose. It is provided "as is" without express or
implied warranty.
THIS SOFTWARE IS PROVIDED "AS IS" AND WITHOUT ANY EXPRESS OR IMPLIED
WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED WARRANTIES OF
MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE.