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

web
Last change on this file since f6f3e91 was f6f3e91, checked in by Jessica B. Hamrick <jhamrick@…>, 15 years ago

Preserve directory hierarchy (not sure what happened to it)

  • Property mode set to 100644
File size: 4.8 KB
Line 
1=for stopwords
2remctl -dhv subcommand remctld GSS-API GSS-API's hostname AFS
3canonicalizes DNS DNS-based canonicalization Heimdal MICs Ushakov Allbery
4
5=head1 NAME
6
7remctl - Remote execution tool
8
9=head1 SYNOPSIS
10
11remctl [B<-dhv>] [B<-p> I<port>] [B<-s> I<service>] I<host> I<command>
12    I<subcommand> [I<parameters> ...]
13
14=head1 DESCRIPTION
15
16B<remctl> is a program that allows a user to execute commands remotely on
17a server that is running the remctld daemon.  B<remctl> does not interpret
18the commands given to it.  It passes them to the server and displays the
19return message.  The commands must be defined on the server-side before a
20B<remctl> client can execute them, and the user running B<remctl> must be
21authorized to execute the particular command on the server.
22
23Access to remote commands is authenticated via Kerberos v5 GSS-API, so a
24user must have a ticket granting ticket to use B<remctl>.  All
25transmissions to and from the remctld server are encrypted using GSS-API's
26security layer.
27
28I<host> is the hostname of the target server.  I<command> and
29I<subcommand> together specify the command to run and correspond to the
30command names in the configuration file on the server.  I<parameters> are
31any additional command-line parameters to pass to the remote command.
32
33=head1 OPTIONS
34
35=over 4
36
37=item B<-d>
38
39Turn on extra debugging output of the client-server interaction.
40
41=item B<-h>
42
43Show a brief usage message and then exit.
44
45=item B<-p> I<port>
46
47Connect to the server on I<port>.  If this option isn't given, the client
48first tries the registered remctl port (4373) and then falls back on the
49legacy port (4444) if that fails.
50
51=item B<-s> I<service>
52
53Authenticate to the server with a service ticket for I<service> rather
54than the default server identity of host/I<hostname>.  This may be
55necessary with, for instance, a server where B<remctld> is not running as
56root.
57
58=item B<-v>
59
60Print the version of B<remctl> and exit.
61
62=back
63
64=head1 EXIT STATUS
65
66B<remctl> will exit with the exit status returned by the remote command.
67If some network or authentication error occurred and B<remctl> was unable
68to run the remote command or retrieve its exit status, or if B<remctl> was
69called with invalid arguments, B<remctl> will exit with status 1.
70
71=head1 EXAMPLES
72
73Release an AFS volume called ls.tripwire:
74
75    remctl lsdb afs release ls.tripwire
76
77=head1 CAVEATS
78
79If no principal is specified with B<-s>, B<remctl> canonicalizes the
80server host name using DNS before connecting.  This ensures that the
81network connection and the GSS-API authentication use the same server name
82even if some common DNS-based load-balancing schemes are in use.  To
83disable this canonicalization, specify the server principal using B<-s>.
84
85The default behavior, when the port is not specified, of trying 4373 and
86falling back to 4444 will be removed in a future version of B<remctl> in
87favor of using the C<remctl> service in F</etc/services> if set and then
88falling back on only 4373.  4444 was the poorly-chosen original remctl
89port and should be phased out.
90
91When using Heimdal with triple-DES keys and talking to old servers that
92only speak version one of the remctl protocol, B<remctl> may have problems
93with MIC verification.  This doesn't affect new clients and servers since
94the version two protocol doesn't use MICs.  If you are using Heimdal and
95run into MIC verification problems, see the COMPATIBILITY section of
96gssapi(3).
97
98=head1 NOTES
99
100The remctl port number, 4373, was derived by tracing the diagonals of a
101QWERTY keyboard up from the letters C<remc> to the number row.
102
103=head1 SEE ALSO
104
105kinit(1), remctld(8)
106
107The current version of this program is available from its web page at
108L<http://www.eyrie.org/~eagle/software/remctl/>.
109
110=head1 AUTHOR
111
112Anton Ushakov <antonu@stanford.edu> is the original author.  Updates and
113current maintenance are done by Russ Allbery <rra@stanford.edu>.
114
115=head1 COPYRIGHT AND LICENSE
116
117Copyright 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009 Board of
118Trustees, Leland Stanford Jr. University.  All rights reserved.
119 
120Permission to use, copy, modify, and distribute this software and its
121documentation for any purpose and without fee is hereby granted, provided
122that the above copyright notice appear in all copies and that both that
123copyright notice and this permission notice appear in supporting
124documentation, and that the name of Stanford University not be used in
125advertising or publicity pertaining to distribution of the software
126without specific, written prior permission.  Stanford University makes no
127representations about the suitability of this software for any purpose.
128It is provided "as is" without express or implied warranty.
129
130THIS SOFTWARE IS PROVIDED "AS IS" AND WITHOUT ANY EXPRESS OR IMPLIED
131WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED WARRANTIES OF
132MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE.
133
134=cut
Note: See TracBrowser for help on using the repository browser.