1REMCTLD(8) System Daemons REMCTLD(8)
2
6 remctld - Server for remctl, a remote command execution utility
7
9 remctld [-dFhmSv] [-f config] [-k keytab] [-P file] [-p port] [-s ser‐
10 vice]
11
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 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 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 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
36 -d Enable verbose debug logging to syslog (or to standard output if -S
37 is also given).
38 -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 -f config
46 The configuration file for remctld, overriding the default path.
47 -h Show a brief usage message and then exit.
49 -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 -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 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 -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 -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 -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 -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 -v Print the version of remctld and exit.
87
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 type service executable [logmask=n[,...]] {aclfile}+
94 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 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 As a special case, a line like:
104 include file
106 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 The meaning of these fields is:
114 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 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 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 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 executable
141 The full path to the commmand executable to run for this type-ser‐
142 vice combination. (See examples below.)
143 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 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 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 include file
161 in an ACL file includes other ACL files and is handled identically
163 to the include directive in configuration files.
164 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
174 The following environment variables will be set for any commands run
175 via remctld:
176 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 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 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 remctld also used to set SCPRINCIPAL for (partial) backward compatibil‐
194 ity with sysctld, but stopped doing so as of remctl 2.1.
195 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
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 tcpserver hostname 4373 remctld
206 The equivalent line for /etc/inetd.conf is:
208 4373 stream tcp nowait root /usr/sbin/tcpd /usr/sbin/remctld
210 or:
212 remctl stream tcp nowait root /usr/sbin/tcpd /usr/sbin/remctld
214 if the "remctl" service is listed in your /etc/services file.
216 To start remctld in stand-alone mode instead, run:
218 remctld -m
220 Example configuration file:
222 # 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 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
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
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
253 remctl(1), syslog(3), tcpserver(1)
254 The current version of this program is available from its web page at
256 <http://www.eyrie.org/~eagle/software/remctl/>.
257
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 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 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.
2802.11 2007-11-08 REMCTLD(8)