source: web/old/remctl-2.14/docs/remctl.1 @ f6f3e91

.\" Automatically generated by Pod::Man 2.22 (Pod::Simple 3.07)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is turned on, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.ie \nF \{\
.    de IX
.    tm Index:\\$1\t\\n%\t"\\$2"
..
.    nr % 0
.    rr F
.\}
.el \{\
.    de IX
..
.\}
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
.    \" fudge factors for nroff and troff
.if n \{\
.    ds #H 0
.    ds #V .8m
.    ds #F .3m
.    ds #[ \f1
.    ds #] \fP
.\}
.if t \{\
.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
.    ds #V .6m
.    ds #F 0
.    ds #[ \&
.    ds #] \&
.\}
.    \" simple accents for nroff and troff
.if n \{\
.    ds ' \&
.    ds ` \&
.    ds ^ \&
.    ds , \&
.    ds ~ ~
.    ds /
.\}
.if t \{\
.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
.    \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
.    \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
.    \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
.    ds : e
.    ds 8 ss
.    ds o a
.    ds d- d\h'-1'\(ga
.    ds D- D\h'-1'\(hy
.    ds th \o'bp'
.    ds Th \o'LP'
.    ds ae ae
.    ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "REMCTL 1"
.TH REMCTL 1 "2009-05-22" "2.14" "remctl"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
remctl \- Remote execution tool
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
remctl [\fB\-dhv\fR] [\fB\-p\fR \fIport\fR] [\fB\-s\fR \fIservice\fR] \fIhost\fR \fIcommand\fR
    \fIsubcommand\fR [\fIparameters\fR ...]
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
\&\fBremctl\fR is a program that allows a user to execute commands remotely on
a server that is running the remctld daemon.  \fBremctl\fR 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
\&\fBremctl\fR client can execute them, and the user running \fBremctl\fR must be
authorized to execute the particular command on the server.
.PP
Access to remote commands is authenticated via Kerberos v5 GSS-API, so a
user must have a ticket granting ticket to use \fBremctl\fR.  All
transmissions to and from the remctld server are encrypted using GSS-API's
security layer.
.PP
\&\fIhost\fR is the hostname of the target server.  \fIcommand\fR and
\&\fIsubcommand\fR together specify the command to run and correspond to the
command names in the configuration file on the server.  \fIparameters\fR are
any additional command-line parameters to pass to the remote command.
.SH "OPTIONS"
.IX Header "OPTIONS"
.IP "\fB\-d\fR" 4
.IX Item "-d"
Turn on extra debugging output of the client-server interaction.
.IP "\fB\-h\fR" 4
.IX Item "-h"
Show a brief usage message and then exit.
.IP "\fB\-p\fR \fIport\fR" 4
.IX Item "-p port"
Connect to the server on \fIport\fR.  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.
.IP "\fB\-s\fR \fIservice\fR" 4
.IX Item "-s service"
Authenticate to the server with a service ticket for \fIservice\fR rather
than the default server identity of host/\fIhostname\fR.  This may be
necessary with, for instance, a server where \fBremctld\fR is not running as
root.
.IP "\fB\-v\fR" 4
.IX Item "-v"
Print the version of \fBremctl\fR and exit.
.SH "EXIT STATUS"
.IX Header "EXIT STATUS"
\&\fBremctl\fR will exit with the exit status returned by the remote command.
If some network or authentication error occurred and \fBremctl\fR was unable
to run the remote command or retrieve its exit status, or if \fBremctl\fR was
called with invalid arguments, \fBremctl\fR will exit with status 1.
.SH "EXAMPLES"
.IX Header "EXAMPLES"
Release an \s-1AFS\s0 volume called ls.tripwire:
.PP
.Vb 1
\&    remctl lsdb afs release ls.tripwire
.Ve
.SH "CAVEATS"
.IX Header "CAVEATS"
If no principal is specified with \fB\-s\fR, \fBremctl\fR canonicalizes the
server host name using \s-1DNS\s0 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 \fB\-s\fR.
.PP
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 \fBremctl\fR in
favor of using the \f(CW\*(C`remctl\*(C'\fR service in \fI/etc/services\fR if set and then
falling back on only 4373.  4444 was the poorly-chosen original remctl
port and should be phased out.
.PP
When using Heimdal with triple-DES keys and talking to old servers that
only speak version one of the remctl protocol, \fBremctl\fR may have problems
with \s-1MIC\s0 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 \s-1MIC\s0 verification problems, see the \s-1COMPATIBILITY\s0 section of
\&\fIgssapi\fR\|(3).
.SH "NOTES"
.IX Header "NOTES"
The remctl port number, 4373, was derived by tracing the diagonals of a
\&\s-1QWERTY\s0 keyboard up from the letters \f(CW\*(C`remc\*(C'\fR to the number row.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
\&\fIkinit\fR\|(1), \fIremctld\fR\|(8)
.PP
The current version of this program is available from its web page at
<http://www.eyrie.org/~eagle/software/remctl/>.
.SH "AUTHOR"
.IX Header "AUTHOR"
Anton Ushakov <antonu@stanford.edu> is the original author.  Updates and
current maintenance are done by Russ Allbery <rra@stanford.edu>.
.SH "COPYRIGHT AND LICENSE"
.IX Header "COPYRIGHT AND LICENSE"
Copyright 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009 Board of
Trustees, Leland Stanford Jr. University.  All rights reserved.
.PP
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 \*(L"as is\*(R" without express or implied warranty.
.PP
\&\s-1THIS\s0 \s-1SOFTWARE\s0 \s-1IS\s0 \s-1PROVIDED\s0 \*(L"\s-1AS\s0 \s-1IS\s0\*(R" \s-1AND\s0 \s-1WITHOUT\s0 \s-1ANY\s0 \s-1EXPRESS\s0 \s-1OR\s0 \s-1IMPLIED\s0
\&\s-1WARRANTIES\s0, \s-1INCLUDING\s0, \s-1WITHOUT\s0 \s-1LIMITATION\s0, \s-1THE\s0 \s-1IMPLIED\s0 \s-1WARRANTIES\s0 \s-1OF\s0
\&\s-1MERCHANTABILITY\s0 \s-1AND\s0 \s-1FITNESS\s0 \s-1FOR\s0 A \s-1PARTICULAR\s0 \s-1PURPOSE\s0.