REMCTL(1)							      remctl								 REMCTL(1)

NAME

       remctl - Remote execution tool

SYNOPSIS

       remctl [-dhv] [-b source-ip] [-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

       -b source-ip
	   When connecting to the remote remctl server, use source-ip as the source IP address.  This can be useful on multihomed systems where
	   the remctl connections need to be made over a particular network.  source-ip must be an IP address, not a hostname, and can be either
	   an IPv4 or IPv6 address (assuming IPv6 is supported).

       -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, 2010, 2011 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.

3.2								    2012-06-19								 REMCTL(1)