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