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