1REMCTLD(8)                      System Daemons                      REMCTLD(8)
2
3
4

NAME

6       remctld - Server for remctl, a remote command execution utility
7

SYNOPSIS

9       remctld [-dFhmSv] [-f config] [-k keytab] [-P file] [-p port] [-s ser‐
10       vice]
11

DESCRIPTION

13       remctld is the server for remctl.  It accepts a connection from remctl,
14       receives the command to execute and the arguments, verifies authoriza‐
15       tion of the user and executes the command, returning the result back to
16       the client.  All connections are authenticated using GSS-API Kerberos
17       v5, and all transmissions are also encrypted using the GSS-API privacy
18       layer.
19
20       remctld is normally started using tcpserver or from inetd, but it may
21       be run in stand-alone mode as a daemon using -m.  Either -s must be
22       given to use an alternate identity (which will require the same flag be
23       used for remctl client invocations), or it must be run as root to read
24       the host keytab file.  remctld logs its activity using syslog (the dae‐
25       mon facility).
26
27       The location of the configuration file may be specified with the -f
28       option.  The default location is /etc/remctl.conf.  For information on
29       the format of the configuration file, see "CONFIGURATION FILE" below.
30
31       When the command is run, several environment variables will be set pro‐
32       viding information about the remote connection.  See ENVIRONMENT below
33       for more information.
34

OPTIONS

36       -d  Enable verbose debug logging to syslog (or to standard output if -S
37           is also given).
38
39       -F  Normally when running in stand-alone mode (-m), remctld backgrounds
40           itself to run as a daemon, changes directory to /, and drops any
41           controlling terminal.  This flag suppresses this behavior, usually
42           for debugging or so that remctld can be monitored by other pro‐
43           cesses.
44
45       -f config
46           The configuration file for remctld, overriding the default path.
47
48       -h  Show a brief usage message and then exit.
49
50       -k keytab
51           Use keytab as the keytab for server credentials rather than the
52           system default or the value of the KRB5_KTNAME environment vari‐
53           able.  Using -k just sets the KRB5_KTNAME environment variable
54           internally in the process.
55
56       -m  Enable stand-alone mode.  remctld will listen to its configured
57           port and fork a new child for each incoming connection.  By
58           default, when this option is used, remctld also changes directory
59           to /, backgrounds itself, and closes standard input, output, and
60           error.  To not background, pass -F as well.  To not close standard
61           output and error and continue using them for logging, pass -S as
62           well.
63
64           To determine the port, remctld attempts to look up the "remctl"
65           service in the local /etc/services file and uses the port defined
66           there.  If the "remctl" service could not be found, it uses 4373,
67           the registered remctl port.
68
69       -P file
70           When running in stand-alone mode (-m), write the PID of remctld to
71           file.  This option is ignored unless -m is also given.
72
73       -p port
74           When running in stand-alone mode, Listen on port port rather than
75           the default.  This option does nothing unless used with -m.
76
77       -S  Rather than logging to syslog, log debug and routine connection
78           messages to standard output and error messages to standard error.
79           This option is mostly useful for testing and debugging.
80
81       -s service
82           This option is used to specify the Kerberos service principal for
83           remctld to run as, the default is the server host principal:
84           "host/<machinename>.stanford.edu"
85
86       -v  Print the version of remctld and exit.
87

CONFIGURATION FILE

89       The configuration file defines the allowed commands and specifies
90       access control information.  The configuration file format is lines of
91       space- or tab-separated strings, where each line is:
92
93           type service executable [logmask=n[,...]] {aclfile}+
94
95       Each command consists of a type, a service, and zero or more arguments.
96       Each configuration line defines an acceptable commands (or, if "ALL" is
97       used as mentioned below under service, a set of commands).
98
99       Blank lines and lines beginning with "#" are ignored.  Lines can be
100       continued on the next line by ending them with a backslash ("\").  Be
101       aware that comments can be continued with a backslash as well.
102
103       As a special case, a line like:
104
105           include file
106
107       will include file as if its contents were pasted verbatim into the con‐
108       figuration file at that point.  file may be a directory, in which case
109       all files whose names do not contain a period found in that directory
110       will be included (in no particular order).  file should be a fully
111       qualified path.
112
113       The meaning of these fields is:
114
115       type
116           The type of the command being requested.  Normally, related com‐
117           mands (such as all commands for managing a particular service) are
118           grouped together under one type.
119
120       service
121           The service within the type being requested, such as "release" for
122           the release function of the AFS volume backend.  service can also
123           be thought of as the sub-command.  If the keyword "ALL" is used
124           instead of a specific service, this line matches all commands with
125           the given type and can be used to dispatch all services under that
126           type to the same executable with the same ACLs.  The first matching
127           entry is used; one may list specific services first and then an
128           "ALL" catch-all.
129
130           remctld accepts commands with no service argument, only a type,
131           such commands will only match a line in the configuration file if
132           an "ALL" line is present for that type.  (The remctl client will
133           not send such commands, but they can be sent using the client
134           library or via another implementation.)
135
136           The service is always passed as the first argument to the exe‐
137           cutable program that is listed for that service unless no service
138           was given.
139
140       executable
141           The full path to the commmand executable to run for this type-ser‐
142           vice combination.  (See examples below.)
143
144       logmask=n[,...]
145           Limit logging of command arguments.  Any argument listed in the
146           logmask list will have its value logged as "**MASKED**".  This is
147           to avoid logging the arguments of commands that take privileged
148           information.
149
150           For example, if the command is "admin passwd {username} {passwd}",
151           then you'd want to set logmask to 3, so the password argument gets
152           logged as "**MASKED**".
153
154       aclfile
155           The full paths of one or more access control files, each containing
156           one Kerberos v5 principal per line, such as "username@stan‐
157           ford.edu".  Blank lines and lines beginning with "#" are ignored in
158           the ACL files.  As a special case, a line like:
159
160               include file
161
162           in an ACL file includes other ACL files and is handled identically
163           to the include directive in configuration files.
164
165           The keyword ANYUSER may be used instead of the aclfiles to allow
166           access to all users.  The user still needs to authenticate to rem‐
167           ctld; this only affects authorization.  This can be used for back‐
168           end programs that want to check ACLs themselves and will retrieve
169           the authenticated principal from the REMOTE_USER environment vari‐
170           able.  Note that ANYUSER accepts any authenticated user, including
171           cross-realm users from foreign Kerberos realms.
172

ENVIRONMENT

174       The following environment variables will be set for any commands run
175       via remctld:
176
177       REMOTE_USER
178       REMUSER
179           Set to the Kerberos principal of the authenticated client.  REMUSER
180           has always been set by remctld; REMOTE_USER is also set (to the
181           same value) starting with remctl 2.1.
182
183       REMOTE_ADDR
184           The IP address of the remote host.  Currently, this is always an
185           IPv4 address, but in the future it may be set to an IPv6 address.
186           This environment variable was added in remctl 2.1.
187
188       REMOTE_HOST
189           The hostname of the remote host, if it was available.  If reverse
190           name resolution failed, this environment variable will not be set.
191           This variable was added in remctl 2.1.
192
193       remctld also used to set SCPRINCIPAL for (partial) backward compatibil‐
194       ity with sysctld, but stopped doing so as of remctl 2.1.
195
196       If the -k flag is used, remctld will also set KRB5_KTNAME to the pro‐
197       vided keytab path.  This is primarily for communication with the GSS-
198       API library, but this setting will also be inherited by any commands
199       run by remctld.
200

EXAMPLES

202       Typically remctld is to be started as follows, where "hostname" is the
203       machine where remctld will run, and 4373 is the port:
204
205           tcpserver hostname 4373 remctld
206
207       The equivalent line for /etc/inetd.conf is:
208
209           4373 stream tcp nowait root /usr/sbin/tcpd /usr/sbin/remctld
210
211       or:
212
213           remctl stream tcp nowait root /usr/sbin/tcpd /usr/sbin/remctld
214
215       if the "remctl" service is listed in your /etc/services file.
216
217       To start remctld in stand-alone mode instead, run:
218
219           remctld -m
220
221       Example configuration file:
222
223        # Comments can be used like this.
224        accounts create /usr/local/bin/doaccount  /etc/acl/group1 \
225            /etc/acl/group2
226        accounts delete /usr/local/bin/doaccount  /etc/acl/group3
227        accounts view   /usr/local/bin/doaccount  ANYUSER
228        accounts passwd /usr/local/bin/dopasswd   logmask=3 /etc/acl/group1
229        printing ALL    /usr/local/bin/printthing /etc/acl/group2
230
231       The commands "accounts create", "accounts delete", and so forth will
232       all be passed to /usr/local/bin/doaccount with the first argument being
233       the specific subcommand, with the exception of "accounts passwd".  That
234       command will be passed to /usr/local/bin/dopasswd instead, but it will
235       still get "passwd" as its first argument.  The third argument to
236       "accounts passwd" (presumably the password) will not be logged to sys‐
237       log.  All commands starting with "printing" will be passed to
238       /usr/local/bin/printthing.
239

CAVEATS

241       When using Heimdal with triple-DES keys and talking to old clients that
242       only speak version one of the remctl protocol, remctld may have prob‐
243       lems with MIC verification.  This doesn't affect new clients and
244       servers since the version two protocol doesn't use MICs.  If you are
245       using Heimdal and run into MIC verification problems, see the COMPATI‐
246       BILITY section of gssapi(3).
247

NOTES

249       The remctl port number, 4373, was derived by tracing the diagonals of a
250       QWERTY keyboard up from the letters "remc" to the number row.
251

SEE ALSO

253       remctl(1), syslog(3), tcpserver(1)
254
255       The current version of this program is available from its web page at
256       <http://www.eyrie.org/~eagle/software/remctl/>.
257

AUTHOR

259       Anton Ushakov <antonu@stanford.edu> is the original author.  Updates
260       and current maintenance are done by Russ Allbery <rra@stanford.edu>.
261
263       Copyright 2002, 2003, 2004, 2005, 2006, 2007 Board of Trustees, Leland
264       Stanford Jr. University.  All rights reserved.
265
266       Permission to use, copy, modify, and distribute this software and its
267       documentation for any purpose and without fee is hereby granted, pro‐
268       vided that the above copyright notice appear in all copies and that
269       both that copyright notice and this permission notice appear in sup‐
270       porting documentation, and that the name of Stanford University not be
271       used in advertising or publicity pertaining to distribution of the
272       software without specific, written prior permission.  Stanford Univer‐
273       sity makes no representations about the suitability of this software
274       for any purpose.  It is provided "as is" without express or implied
275       warranty.
276
277       THIS SOFTWARE IS PROVIDED "AS IS" AND WITHOUT ANY EXPRESS OR IMPLIED
278       WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED WARRANTIES OF
279       MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE.
280
281
282
2832.11                              2007-11-08                        REMCTLD(8)
Impressum