1 | =for stopwords |
---|
2 | remctld remctl -dFhmSv keytab GSS-API tcpserver inetd subcommand AFS |
---|
3 | backend logmask NUL acl ACL princ filename gput CMU GPUT xform ANYUSER IP |
---|
4 | IPv4 IPv6 hostname SCPRINCIPAL sysctld Heimdal MICs Ushakov Allbery |
---|
5 | subcommands REMUSER |
---|
6 | |
---|
7 | =head1 NAME |
---|
8 | |
---|
9 | remctld - Server for remctl, a remote command execution utility |
---|
10 | |
---|
11 | =head1 SYNOPSIS |
---|
12 | |
---|
13 | remctld [B<-dFhmSv>] [B<-f> I<config>] [B<-k> I<keytab>] [B<-P> I<file>] |
---|
14 | [B<-p> I<port>] [B<-s> I<service>] |
---|
15 | |
---|
16 | =head1 DESCRIPTION |
---|
17 | |
---|
18 | B<remctld> is the server for remctl. It accepts a connection from remctl, |
---|
19 | receives the command to execute and the arguments, verifies authorization |
---|
20 | of the user and executes the command, returning the result back to the |
---|
21 | client. All connections are authenticated using GSS-API Kerberos v5, and |
---|
22 | all transmissions are also encrypted using the GSS-API privacy layer. |
---|
23 | |
---|
24 | B<remctld> is normally started using B<tcpserver> or from B<inetd>, but it |
---|
25 | may be run in stand-alone mode as a daemon using B<-m>. Either B<-s> must |
---|
26 | be given to use an alternate identity (which will require the same flag be |
---|
27 | used for B<remctl> client invocations), or it must be run as root to read |
---|
28 | the host keytab file. B<remctld> logs its activity using syslog (the |
---|
29 | daemon facility). |
---|
30 | |
---|
31 | The location of the configuration file may be specified with the B<-f> |
---|
32 | option. The default location is F<@sysconfdir@/remctl.conf>. For |
---|
33 | information on the format of the configuration file, see L<"CONFIGURATION |
---|
34 | FILE"> below. |
---|
35 | |
---|
36 | When the command is run, several environment variables will be set |
---|
37 | providing information about the remote connection. See L<ENVIRONMENT> |
---|
38 | below for more information. |
---|
39 | |
---|
40 | =head1 OPTIONS |
---|
41 | |
---|
42 | =over 4 |
---|
43 | |
---|
44 | =item B<-d> |
---|
45 | |
---|
46 | Enable verbose debug logging to syslog (or to standard output if B<-S> is |
---|
47 | also given). |
---|
48 | |
---|
49 | =item B<-F> |
---|
50 | |
---|
51 | Normally when running in stand-alone mode (B<-m>), B<remctld> backgrounds |
---|
52 | itself to run as a daemon, changes directory to F</>, and drops any |
---|
53 | controlling terminal. This flag suppresses this behavior, usually for |
---|
54 | debugging or so that B<remctld> can be monitored by other processes. |
---|
55 | |
---|
56 | =item B<-f> I<config> |
---|
57 | |
---|
58 | The configuration file for B<remctld>, overriding the default path. |
---|
59 | |
---|
60 | =item B<-h> |
---|
61 | |
---|
62 | Show a brief usage message and then exit. |
---|
63 | |
---|
64 | =item B<-k> I<keytab> |
---|
65 | |
---|
66 | Use I<keytab> as the keytab for server credentials rather than the system |
---|
67 | default or the value of the KRB5_KTNAME environment variable. Using B<-k> |
---|
68 | just sets the KRB5_KTNAME environment variable internally in the process. |
---|
69 | |
---|
70 | =item B<-m> |
---|
71 | |
---|
72 | Enable stand-alone mode. B<remctld> will listen to its configured port |
---|
73 | and fork a new child for each incoming connection. By default, when this |
---|
74 | option is used, B<remctld> also changes directory to F</>, backgrounds |
---|
75 | itself, and closes standard input, output, and error. To not background, |
---|
76 | pass B<-F> as well. To not close standard output and error and continue |
---|
77 | using them for logging, pass B<-S> as well. |
---|
78 | |
---|
79 | To determine the port, B<remctld> attempts to look up the C<remctl> |
---|
80 | service in the local F</etc/services> file and uses the port defined |
---|
81 | there. If the C<remctl> service could not be found, it uses 4373, the |
---|
82 | registered remctl port. |
---|
83 | |
---|
84 | =item B<-P> I<file> |
---|
85 | |
---|
86 | When running in stand-alone mode (B<-m>), write the PID of B<remctld> to |
---|
87 | I<file>. This option is ignored unless B<-m> is also given. |
---|
88 | |
---|
89 | =item B<-p> I<port> |
---|
90 | |
---|
91 | When running in stand-alone mode, Listen on port I<port> rather than the |
---|
92 | default. This option does nothing unless used with B<-m>. |
---|
93 | |
---|
94 | =item B<-S> |
---|
95 | |
---|
96 | Rather than logging to syslog, log debug and routine connection messages |
---|
97 | to standard output and error messages to standard error. This option is |
---|
98 | mostly useful for testing and debugging. |
---|
99 | |
---|
100 | =item B<-s> I<service> |
---|
101 | |
---|
102 | Specifies which principal is used as the server identity for client |
---|
103 | authentication. The client must also use the same identity as the server |
---|
104 | identity for authentication to succeed. By default, B<remctld> accepts |
---|
105 | any principal with a key in the default keytab file (which can be changed |
---|
106 | with the B<-k> option). This is normally the most desirable behavior. |
---|
107 | |
---|
108 | =item B<-v> |
---|
109 | |
---|
110 | Print the version of B<remctld> and exit. |
---|
111 | |
---|
112 | =back |
---|
113 | |
---|
114 | =head1 CONFIGURATION FILE |
---|
115 | |
---|
116 | The configuration file defines the allowed commands and specifies access |
---|
117 | control information. The configuration file format is lines of space- or |
---|
118 | tab-separated strings, where each line is: |
---|
119 | |
---|
120 | command subcommand executable [option=value ...] acl [acl ...] |
---|
121 | |
---|
122 | Each command consists of a command, a subcommand, and zero or more |
---|
123 | arguments. Each configuration line defines an acceptable command and |
---|
124 | subcommand (or, if C<ALL> is used as mentioned below under I<service>, a |
---|
125 | set of commands). The first configuration line matching the received |
---|
126 | command is used, so list more specific entries before more general |
---|
127 | entries. |
---|
128 | |
---|
129 | Blank lines and lines beginning with C<#> are ignored. Lines can be |
---|
130 | continued on the next line by ending them with a backslash (C<\>). Be |
---|
131 | aware that comments can be continued with a backslash as well. |
---|
132 | |
---|
133 | As a special case, a line like: |
---|
134 | |
---|
135 | include file |
---|
136 | |
---|
137 | will include I<file> as if its contents were pasted verbatim into the |
---|
138 | configuration file at that point. I<file> may be a directory, in which |
---|
139 | case all files whose names do not contain a period found in that directory |
---|
140 | will be included (in no particular order). I<file> should be a fully |
---|
141 | qualified path. |
---|
142 | |
---|
143 | The meaning of these fields is: |
---|
144 | |
---|
145 | =over 4 |
---|
146 | |
---|
147 | =item I<command> |
---|
148 | |
---|
149 | The command being issued. Normally, related commands (such as all |
---|
150 | commands for managing a particular service) are grouped together as |
---|
151 | subcommands under one command. |
---|
152 | |
---|
153 | =item I<subcommand> |
---|
154 | |
---|
155 | The subcommand within the command being requested, such as C<release> for |
---|
156 | the release function of the AFS volume backend. If the keyword C<ALL> is |
---|
157 | used instead of a specific subcommand, this line matches all subcommands |
---|
158 | with the given command and can be used to dispatch all subcommands under |
---|
159 | that command to the same executable with the same ACLs. Since the first |
---|
160 | matching entry is used, list entries for specific services first (if any) |
---|
161 | and then the C<ALL> catch-all. |
---|
162 | |
---|
163 | B<remctld> accepts commands with no subcommand argument. Such commands |
---|
164 | will only match lines in the configuration file with C<ALL> for the |
---|
165 | service. (The B<remctl> client will not send such commands, but they can |
---|
166 | be sent using the client library or via another implementation.) |
---|
167 | |
---|
168 | The subcommand is always passed as the first argument to the executable |
---|
169 | program that is listed for that service unless no subcommand was given. |
---|
170 | |
---|
171 | =item I<executable> |
---|
172 | |
---|
173 | The full path to the command executable to run for this command and |
---|
174 | subcommand combination. (See examples below.) |
---|
175 | |
---|
176 | =item I<option>=I<value> |
---|
177 | |
---|
178 | An option setting that applies to this command. Supported option settings |
---|
179 | are: |
---|
180 | |
---|
181 | =over 4 |
---|
182 | |
---|
183 | =item I<logmask>=I<n>[,...] |
---|
184 | |
---|
185 | Limit logging of command arguments. Any argument listed in the logmask |
---|
186 | list will have its value logged as "**MASKED**". This is to avoid logging |
---|
187 | the arguments of commands that take private information such as passwords. |
---|
188 | The logmask list should contain argument numbers separated by commas, with |
---|
189 | the I<subcommand> considered argument 1. The I<command> argument cannot |
---|
190 | be masked. |
---|
191 | |
---|
192 | For example, if the command is C<admin passwd I<username> I<password>>, |
---|
193 | then you'd want to set logmask to C<3>, so the password argument gets |
---|
194 | logged as C<**MASKED**>. If the command is C<user passwd I<username> |
---|
195 | I<old-password> I<new-password>>, you'd want to set logmask to C<3,4>. |
---|
196 | |
---|
197 | =item I<stdin>=(I<n> | C<last>) |
---|
198 | |
---|
199 | Specifies that the I<n>th or last argument to the command be passed on |
---|
200 | standard input instead of on the command line. The value of this option |
---|
201 | must either be the number of argument to pass on standard input (with the |
---|
202 | I<subcommand> considered argument 1) or the special value C<last>, which |
---|
203 | indicates that the final argument (no matter how many there are) be passed |
---|
204 | on standard input. |
---|
205 | |
---|
206 | The I<subcommand> cannot be passed on standard input, so I<n> must be at |
---|
207 | least C<2>. If this option is set to C<last> and no arguments are given |
---|
208 | except the I<command> and possibly the I<subcommand>, nothing will be |
---|
209 | passed on standard input. |
---|
210 | |
---|
211 | This option is used primarily for passing large amounts of data that may |
---|
212 | not fit on the command line or data that contains NUL characters. It can |
---|
213 | also be used for arguments like passwords that shouldn't be exposed on the |
---|
214 | command line. Only at most one argument may be passed on standard input |
---|
215 | to the command. |
---|
216 | |
---|
217 | =back |
---|
218 | |
---|
219 | =item I<acl> |
---|
220 | |
---|
221 | One or more entries of the form [I<method>:]I<data>, where I<method> |
---|
222 | specifies an access control method to be used, and I<data> contains |
---|
223 | parameters whose meaning depends on the method. If the method is omitted, |
---|
224 | the data is processed as described for the C<file> method. |
---|
225 | |
---|
226 | If I<method> is omitted, I<acl> must either begin with C</> or must not |
---|
227 | contain C<=>. Otherwise, it will be parsed as an option instead. If |
---|
228 | there is any ambiguity, prepend the I<method>. |
---|
229 | |
---|
230 | Each entry is checked in order, and access is granted as soon as an |
---|
231 | entry matches. If no entry matches, access is denied. The following |
---|
232 | methods are supported: |
---|
233 | |
---|
234 | =over 4 |
---|
235 | |
---|
236 | =item file |
---|
237 | |
---|
238 | The data is the full path of an ACL file or to a directory containing ACL |
---|
239 | files. Directories are handled as described for the include directive in |
---|
240 | configuration files. An ACL file contains one entry per line, in the |
---|
241 | [I<method>:]I<data> form described above. Entries are handled exactly as |
---|
242 | if they had appeared in the configuration file except that the default |
---|
243 | method is C<princ> instead of C<file>. Blank lines and lines beginning |
---|
244 | with C<#> are ignored in the ACL files. |
---|
245 | |
---|
246 | For backward compatibility, a line like: |
---|
247 | |
---|
248 | include [<method>:]<data> |
---|
249 | |
---|
250 | in an ACL file behaves exactly as if the C<include> directive had been |
---|
251 | omitted, except that the default method is C<file>. Thus, writing: |
---|
252 | |
---|
253 | include <path> |
---|
254 | |
---|
255 | in an ACL file is the same as writing: |
---|
256 | |
---|
257 | file:<path> |
---|
258 | |
---|
259 | and is handled identically to the include directive in configuration |
---|
260 | files. |
---|
261 | |
---|
262 | =item princ |
---|
263 | |
---|
264 | The data is the name of a Kerberos v5 principal which is to be granted |
---|
265 | access, such as C<username@EXAMPLE.ORG>. |
---|
266 | |
---|
267 | =item deny |
---|
268 | |
---|
269 | This method is used to selectively deny access. The data is parsed as a |
---|
270 | [I<method>:]I<data> and evaluated as described above, with the default |
---|
271 | scheme being C<princ>. If it matches, access is denied immediately |
---|
272 | without examining any further entries. Otherwise, processing continues. |
---|
273 | |
---|
274 | Remember that access is granted as soon as an entry matches. For C<deny> |
---|
275 | rules to be effective, they therefore must come before any ACLs they are |
---|
276 | intended to override. Be careful when using C<deny> when including a |
---|
277 | directory of ACL files, since the files in that directory are read in an |
---|
278 | undefined order (not in alphabetical order by filename). It's best to |
---|
279 | explicitly include the file containing C<deny> ACL rules first. |
---|
280 | |
---|
281 | Note that C<deny> only denies access; it never grants it. Thus, deny |
---|
282 | alone does not grant access to anyone, and using deny on itself as in |
---|
283 | C<deny:deny:foo> neither denies nor grants access to anyone. |
---|
284 | |
---|
285 | =item gput |
---|
286 | |
---|
287 | This method is used to grant access based on the CMU GPUT (Global |
---|
288 | Privileged User Table -- see gput(5)). The data is either a GPUT role |
---|
289 | name or a string of the form I<group>[I<xform>], where I<group> is a GPUT |
---|
290 | role name and I<xform> is a GPUT transform string. Access is granted if |
---|
291 | the user is a member of the specified GPUT group, after applying either |
---|
292 | the optional I<xform> or the default transform. |
---|
293 | |
---|
294 | This method is supported only if B<remctld> was compiled with GPUT support |
---|
295 | by using the C<--with-gput> configure option. |
---|
296 | |
---|
297 | =back |
---|
298 | |
---|
299 | The keyword ANYUSER may be used instead of the ACLs to allow access to all |
---|
300 | users. The user still needs to authenticate to B<remctld>; this only |
---|
301 | affects authorization. This can be used for backend programs that want to |
---|
302 | check ACLs themselves and will retrieve the authenticated principal from |
---|
303 | the REMOTE_USER environment variable. Note that ANYUSER accepts B<any> |
---|
304 | authenticated user, including cross-realm users from foreign Kerberos |
---|
305 | realms. |
---|
306 | |
---|
307 | Support for ACL schemes is new in remctl 2.13. Prior versions of |
---|
308 | B<remctld> expected only files in the main B<remctld> configuration file, |
---|
309 | and only principals or lines starting with C<include> in those files, |
---|
310 | without any I<method>: prefixes. |
---|
311 | |
---|
312 | =back |
---|
313 | |
---|
314 | =head1 ENVIRONMENT |
---|
315 | |
---|
316 | The following environment variables will be set for any commands run via |
---|
317 | B<remctld>: |
---|
318 | |
---|
319 | =over 4 |
---|
320 | |
---|
321 | =item REMOTE_USER |
---|
322 | |
---|
323 | =item REMUSER |
---|
324 | |
---|
325 | Set to the Kerberos principal of the authenticated client. REMUSER has |
---|
326 | always been set by B<remctld>; REMOTE_USER is also set (to the same value) |
---|
327 | starting with remctl 2.1. |
---|
328 | |
---|
329 | =item REMOTE_ADDR |
---|
330 | |
---|
331 | The IP address of the remote host. Currently, this is always an IPv4 |
---|
332 | address, but in the future it may be set to an IPv6 address. This |
---|
333 | environment variable was added in remctl 2.1. |
---|
334 | |
---|
335 | =item REMOTE_HOST |
---|
336 | |
---|
337 | The hostname of the remote host, if it was available. If reverse name |
---|
338 | resolution failed, this environment variable will not be set. This |
---|
339 | variable was added in remctl 2.1. |
---|
340 | |
---|
341 | =back |
---|
342 | |
---|
343 | B<remctld> also used to set SCPRINCIPAL for (partial) backward |
---|
344 | compatibility with B<sysctld>, but stopped doing so as of remctl 2.1. |
---|
345 | |
---|
346 | If the B<-k> flag is used, B<remctld> will also set KRB5_KTNAME to the |
---|
347 | provided keytab path. This is primarily for communication with the |
---|
348 | GSS-API library, but this setting will also be inherited by any commands |
---|
349 | run by B<remctld>. |
---|
350 | |
---|
351 | =head1 EXAMPLES |
---|
352 | |
---|
353 | Typically B<remctld> is to be started as follows, where "hostname" is the |
---|
354 | machine where remctld will run, and 4373 is the port: |
---|
355 | |
---|
356 | tcpserver hostname 4373 remctld |
---|
357 | |
---|
358 | The equivalent line for F</etc/inetd.conf> is: |
---|
359 | |
---|
360 | 4373 stream tcp nowait root /usr/sbin/tcpd /usr/sbin/remctld |
---|
361 | |
---|
362 | or: |
---|
363 | |
---|
364 | remctl stream tcp nowait root /usr/sbin/tcpd /usr/sbin/remctld |
---|
365 | |
---|
366 | if the C<remctl> service is listed in your F</etc/services> file. |
---|
367 | |
---|
368 | To start B<remctld> in stand-alone mode instead, run: |
---|
369 | |
---|
370 | remctld -m |
---|
371 | |
---|
372 | Example configuration file: |
---|
373 | |
---|
374 | # Comments can be used like this. |
---|
375 | accounts create /usr/local/bin/doaccount /etc/acl/group1 \ |
---|
376 | /etc/acl/group2 |
---|
377 | accounts delete /usr/local/bin/doaccount /etc/acl/group3 |
---|
378 | accounts view /usr/local/bin/doaccount ANYUSER |
---|
379 | accounts passwd /usr/local/bin/dopasswd logmask=3 /etc/acl/group1 |
---|
380 | printing ALL /usr/local/bin/printthing /etc/acl/group2 |
---|
381 | |
---|
382 | The commands C<accounts create>, C<accounts delete>, and so forth will all |
---|
383 | be passed to /usr/local/bin/doaccount with the first argument being the |
---|
384 | specific subcommand, with the exception of C<accounts passwd>. That |
---|
385 | command will be passed to /usr/local/bin/dopasswd instead, but it will |
---|
386 | still get C<passwd> as its first argument. The third argument to |
---|
387 | C<accounts passwd> (presumably the password) will not be logged to syslog. |
---|
388 | All commands starting with C<printing> will be passed to |
---|
389 | /usr/local/bin/printthing. |
---|
390 | |
---|
391 | Example ACL file using the scheme support new in remctl 2.13: |
---|
392 | |
---|
393 | # This is a comment. |
---|
394 | deny:baduser@EXAMPLE.ORG |
---|
395 | file:/etc/remctl/acl/admins |
---|
396 | principal:service/admin@EXAMPLE.ORG |
---|
397 | service/other@EXAMPLE.ORG |
---|
398 | |
---|
399 | This ACL file will reject C<baduser@EXAMPLE.ORG> even if that user would |
---|
400 | have been allowed by one of the other ACL rules. It will then grant |
---|
401 | access according to the ACL entries in F</etc/remctl/acl/admins> and the |
---|
402 | specific principals C<service/admin@EXAMPLE.ORG> and |
---|
403 | C<service/other@EXAMPLE.ORG>. The last line takes advantage of the |
---|
404 | default ACL method of C<principal> when processing an ACL file. |
---|
405 | |
---|
406 | =head1 CAVEATS |
---|
407 | |
---|
408 | When using Heimdal with triple-DES keys and talking to old clients that |
---|
409 | only speak version one of the remctl protocol, B<remctld> may have |
---|
410 | problems with MIC verification. This doesn't affect new clients and |
---|
411 | servers since the version two protocol doesn't use MICs. If you are using |
---|
412 | Heimdal and run into MIC verification problems, see the COMPATIBILITY |
---|
413 | section of gssapi(3). |
---|
414 | |
---|
415 | B<remctld> does not itself impose any limits on the number of child |
---|
416 | processes or other system resources. You may want to set resource limits |
---|
417 | in your inetd server or with B<ulimit> when running it as a standalone |
---|
418 | daemon or under B<tcpserver>. |
---|
419 | |
---|
420 | Command arguments may not contain NUL characters and must be shorter than |
---|
421 | the operating system limit on the length of a command line since they're |
---|
422 | passed to the command as command-line arguments. The exception is an |
---|
423 | argument passed via standard input using the C<stdin=> option in the |
---|
424 | configuration file. At most one argument may be passed that way. |
---|
425 | |
---|
426 | =head1 NOTES |
---|
427 | |
---|
428 | The remctl port number, 4373, was derived by tracing the diagonals of a |
---|
429 | QWERTY keyboard up from the letters C<remc> to the number row. |
---|
430 | |
---|
431 | =head1 SEE ALSO |
---|
432 | |
---|
433 | remctl(1), syslog(3), tcpserver(1) |
---|
434 | |
---|
435 | The current version of this program is available from its web page at |
---|
436 | L<http://www.eyrie.org/~eagle/software/remctl/>. |
---|
437 | |
---|
438 | =head1 AUTHOR |
---|
439 | |
---|
440 | Anton Ushakov <antonu@stanford.edu> is the original author. Updates and |
---|
441 | current maintenance are done by Russ Allbery <rra@stanford.edu>. |
---|
442 | |
---|
443 | =head1 COPYRIGHT AND LICENSE |
---|
444 | |
---|
445 | Copyright 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009 Board of |
---|
446 | Trustees, Leland Stanford Jr. University. All rights reserved. |
---|
447 | |
---|
448 | Permission to use, copy, modify, and distribute this software and its |
---|
449 | documentation for any purpose and without fee is hereby granted, provided |
---|
450 | that the above copyright notice appear in all copies and that both that |
---|
451 | copyright notice and this permission notice appear in supporting |
---|
452 | documentation, and that the name of Stanford University not be used in |
---|
453 | advertising or publicity pertaining to distribution of the software |
---|
454 | without specific, written prior permission. Stanford University makes no |
---|
455 | representations about the suitability of this software for any purpose. |
---|
456 | It is provided "as is" without express or implied warranty. |
---|
457 | |
---|
458 | THIS SOFTWARE IS PROVIDED "AS IS" AND WITHOUT ANY EXPRESS OR IMPLIED |
---|
459 | WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED WARRANTIES OF |
---|
460 | MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. |
---|
461 | |
---|
462 | =cut |
---|