1REMCTL-SHELL(8) remctl REMCTL-SHELL(8)
2
6 remctl-shell - Restricted shell that mimics a remctl server
7
9 remctl-shell [-dhqSv] [-f config] -c command
10 remctl-shell [-dqS] [-f config] user
12
14 remctl-shell is a restricted shell that mimics the behavior of the
15 remctld server without using the remctl protocol, GSS-API, or Kerberos.
16 It's intended to be run via ssh as either the shell or the forced
17 command for a special user (by convention, "remctl", although remctl-
18 shell doesn't care), with an authorized_keys file that specifies the
19 user identity corresponding to each key that is allowed to run remctl
20 commands. All access control then works as normal.
21 The output of the command ran is returned on standard output and
23 standard error, like a normal command run via ssh, and the exit status
24 of remctl-shell will be the exit status of the command. Only one
25 command can be run per ssh connection, so this will be noticeably
26 slower for each command execution than a well-designed remctl client
27 and server design that holds connections open for multiple commands.
28 remctl-shell is designed to mimic the behavior of remctld and uses the
30 same configuration syntax and environment variables. See
31 "CONFIGURATION FILE" in remctld(8) for configuration information and
32 ENVIRONMENT below for more specific details about environment variable
33 handling. The location of the configuration file may be specified with
34 the -f option. The default location is /etc/remctl.conf.
35 Since remctl-shell is designed to be run by a potentially untrusted
37 user as a shell, normally all error messages and logging is done via
38 syslog and not sent to standard error. See the -S, -d, and -q options
39 when running it manually to debug problems. (When running manually,
40 you will also normally need to set the SSH_CONNECTION environment
41 variable and either REMCTL_USER or SSH_ORIGINAL_COMMAND depending on
42 how you invoke it.)
43 Quoting and Command Limitations
45 The ssh protocol is much less sophisticated than remctl at passing
46 command arguments from the client to the server, so remctl-shell
47 requires careful attention to command arguments and quoting. ssh does
48 no quoting of arguments, just adds a single space between each argument
49 and passes them verbatim to the shell on the server side. This means
50 the client has to add quoting to any arguments containing whitespace.
51 remctl-shell supports single and double quotes, and supports using
52 backslash to escape any character inside or outside either quotes.
53 However, be aware, when running ssh from the command line, that your
54 shell will remove another level of quoting. You will therefore usually
55 have to double-quote arguments.
56 For example, to run the command "log message" with argument "this is a
58 message" via ssh from the command line, use:
59 ssh remctl@example.com log message "'this is a message'"
61 The first level of "" quoting will be removed by your local shell, and
63 remctl-shell will interpret the second level of '' quotes. Note that,
64 because of how ssh does command argument passing, this is exactly
65 equivalent to:
66 ssh remctl@example.com "log message 'this is a message'"
68 since ssh doesn't preserve the distinction between separate arguments
70 when creating the command to send to the remote server. It may be less
71 confusing to get in the habit of quoting the entire command.
72 Also be aware that the full command is passed via command line
74 arguments, which means, when invoking remctl-shell as a shell, there is
75 a tight limit on the length of the whole command plus arguments.
76 Expect to have problems if the total command length exceeds 1000
77 characters. For the same reason, binary data including null characters
78 cannot be passed via remctl-shell. Invoking it as a forced command may
79 work around these limitations by putting the command into the
80 environment instead, but there may still be restrictions on that. (The
81 regular remctl protocol supports arbitrary-length arguments, limited
82 only by server-side configuration and available server memory, and
83 supports arbitrary binary data in arguments.)
84 "authorized_keys" Configuration
86 remctl-shell is intended for use via ssh using "authorized_keys" to
87 manage authentication. (If you have Kerberos available, it's generally
88 better to use the normal remctld server and native remctl protocol.)
89 There are two ways to set up remctl-shell: either by specifying forced
91 commands, or by configuring remctl-shell as the shell of the account.
92 The forced command approach is recommended, since it doesn't require
93 setting a non-default sshd_config option.
94 Using forced commands
96 For the role account that you want to use to run remctl commands
98 ("remctl" by convention), create an authorized_keys file listing
99 everyone who should be able to run commands. Before each key, set the
100 "command" option like the below:
101 command="/usr/sbin/remctl-shell example@EXAMPLE.ORG"
103 where the argument to remctl-shell is the identity matching the ssh key
105 on that line. A more complete example of a line in authorized_keys:
106 command="/usr/sbin/remctl-shell example@EXAMPLE.ORG",\
108 no-agent-forwarding,no-port-forwarding,no-pty,no-user-rc,\
109 no-X11-forwarding ssh-rsa AAAAB3NzaC1yc2EA... \
110 example@some-host.example.org
111 Backslashes and line breaks were added for clarity. The actual entry
113 should be a single long line. For more information on the other
114 settings here, see Examples below.
115 Using a shell
117 When running remctl-shell as the shell of the account, instead of using
119 forced commands, the authorized_keys configuration must be set up to
120 associate each key with an identity by setting the REMCTL_USER
121 environment variable. Using user identities that look like Kerberos
122 principal names is strongly recommended, since it may make it easier to
123 use some of the ACL methods intended for the normal remctl server.
124 Since this relies on setting environment variables via
126 "authorized_keys", you unfortunately have to enable
127 "PermitUserEnvironment" in sshd_config (this is not the default) by
128 adding:
129 PermitUserEnvironment yes
131 Other options
133 remctl-shell will not make use of forwarded connections or agents, and
135 will not pass them along to the processes they run, so all such ssh
136 options should normally be disabled for defense in depth security.
137 Examples
139 Here is a recommended line in "authorized_keys" for the account managed
141 by remctl-shell, with appropriate restrictions and an example of how to
142 set the REMCTL_USER variable. Backslashes and line breaks were added
143 for clarity. The actual entry should be a single long line.
144 environment="REMCTL_USER=example@EXAMPLE.ORG",no-agent-forwarding,\
146 no-port-forwarding,no-pty,no-user-rc,no-X11-forwarding ssh-rsa \
147 AAAAB3NzaC1yc2EA... example@some-host.example.org
148 Setting "no-user-rc" is particularly important for remctl-shell. If
150 you have OpenSSH 7.2 or later, which added the "restrict" keyword, you
151 can instead use the much simpler:
152 environment="REMCTL_USER=example@EXAMPLE.ORG",restrict ssh-rsa \
154 AAAAB3NzaC1yc2EA... example@some-host.example.org
155 REMCTL_USER should be set to the identity string for the owner of that
157 key pair, as used in the ACLs in your remctl configuration.
158
160 remctl-shell is normally only run with either the -c option or with a
161 user, since it's intended for use as a shell or forced command.
162 However, it does support some other options for testing, which may be
163 useful in authorized_keys. If using it as a shell, one can use a small
164 wrapper program as the configured shell that passes additional options
165 into remctl-shell if needed.
166 The start of each option description is annotated with the version of
168 remctl-shell in which that option was added with its current meaning.
169 -c command
171 [3.12] The command to run. This is how ssh passes the command
172 string into remctl-shell. remctl-shell will then parse it into
173 separate arguments using an algorithm similar to that used by a
174 shell. See the above discussion of quoting for more information.
175 This is mandatory when using remctl-shell as a shell. If using it
177 as a forced command, pass the user on the command line instead and
178 do not use this option.
179 -d [3.12] Enable verbose debug logging to syslog (or to standard
181 output if -S is also given).
182 -f config
184 [3.12] The configuration file for remctld, overriding the default
185 path.
186 -h [3.12] Show a brief usage message and then exit. This usage method
188 will include a list of supported ACL types and can be used to
189 determine if optional ACL methods were compiled into a given
190 remctl-shell build.
191 -q [3.12] Suppress the normal informational logging of what commands
193 are being executed and by whom. This is intended primarily to
194 avoid spamming syslog during testing.
195 -S [3.12] Rather than logging to syslog, log debug and routine
197 connection messages to standard output and error messages to
198 standard error. In normal usage, this would send all the logging
199 back to the client, intermixed with program output, so it's
200 normally useful only for testing and debugging.
201 -v [3.12] Print the version of remctl-shell and exit.
203
205 remctl-shell itself requires the following environment variables be set
206 when it is invoked, or it exits with an error and doesn't do anything.
207 REMCTL_USER
209 The user used for logging and to make authorization decisions,
210 unless that was passed on the command line. The security of all
211 remctl-shell authorization checks is based on the accuracy of this
212 environment variable, so be sure that it is set correctly. The
213 best way to do this is via "environment" stanzas in authorized_keys
214 as described above. If the user is passed on the command line,
215 this is ignored.
216 SSH_CONNECTION
218 sshd uses this environment variable to communication information
219 about the local and remote IP addresses and ports of the ssh
220 connection. remctl-shell expects the first space-separated token
221 in this environment variable to be the IP address of the client.
222 It then uses that to set REMOTE_ADDR in the environment of any
223 commands it runs.
224 SSH_ORIGINAL_COMMAND
226 When run as a forced command, the command run by the user is taken
227 from this environment variable, which is set by sshd.
228 The following environment variables will be set for any commands run
230 via remctl-shell (annotated with the version at which they were added).
231 These are mostly the same as those set by remctld. Differences are
232 noted in each description.
233 REMCTL_COMMAND
235 [3.12] The command string that caused this command to be run. This
236 variable will contain only the command, not the subcommand or any
237 additional arguments (which are passed as command arguments).
238 REMOTE_ADDR
240 [3.12] The IP address of the remote host. This may be IPv4 or
241 IPv6. This is taken from the SSH_CONNECTION environment variable.
242 REMOTE_EXPIRES
244 [3.12] Normally, this communicates the time (in seconds since UNIX
245 epoch) when the authenticated remote session will expire. However,
246 this is not a meaningful concept for ssh authentication via public
247 key, and regardless is not communicated by sshd to the shell. It
248 is therefore always set to 0 by remctl-shell.
249 REMOTE_HOST
251 [3.12] The hostname of the remote host, if it was available. If
252 reverse name resolution failed, this environment variable will not
253 be set.
254 This is determined via a simple reverse DNS lookup and should be
256 considered under the control of the client. remctl commands should
257 treat it with skepticism and not use it for anything other than
258 logging purposes.
259 REMOTE_USER
261 REMUSER
262 [3.12] Set to the value of REMCTL_CLIENT as set in the environment
263 of remctl-shell. This should be set securely via authorized_keys as
264 discussed above.
265 Note that REMOTE_HOST is not set by remctl-shell, at least currently.
267
269 Typically, remctl-shell will either be run as a forced command or set
270 as the shell for a dedicated user, normally "remctl", via the normal
271 mechanism for local account creation. That account should be
272 configured with an ssh authorized_keys file as discussed above.
273 remctl-shell will then be invoked with:
274 remctl-shell -c 'command subcommand argument'
276 (if used as a shell) or with:
278 remctl-shell user@EXAMPLE.ORG
280 (if used as a forced command) by sshd for each incoming connection from
282 a user that has a key in the authorized_keys file.
283 If you need to run a command manually for debugging, you can run the
285 same command as above, but it's often more useful to send errors to
286 standard error instead of to syslog. You can do that with:
287 remctl-shell -S -c 'command subcommand argument'
289 If you don't want to see the normal command logging, add the -q option
291 as well. You can test an alternate configuration file by specifying it
292 with the -f option. You will need to set SSH_CONNECTION and either
293 REMCTL_USER (if using -c) or SSH_ORIGINAL_COMMAND (if passing the user
294 on the command line).
295
297 remctl-shell was added in the remctl 3.12 release.
298 The forced command mode where the user can be passed on the command
300 line and the command retrieved from SSH_ORIGINAL_COMMAND was added in
301 the remctl 3.13 release.
302
304 Most of the caveats and differences between remctl-shell and the normal
305 remctld server are from quoting and the limitations of passing
306 arguments via the command line. Review the section on quoting above
307 for more information.
308 Normally, remctl-shell runs as a dedicated non-root user (as opposed to
310 often running as root like remctld), which means that all commands will
311 normally run as that user and the "user" configuration option will not
312 work. The easiest way to run commands as other users is to have the
313 underlying command use sudo or some other user switching mechanism,
314 which will normally require additional local configuration.
315 User environment setting has to be enabled in sshd by setting the non-
317 default "PermitUserEnvironment" configuration option. A future version
318 of remctl-shell may use forced commands with an argument instead of a
319 shell to avoid this.
320
322 remctl-shell was written by Russ Allbery <eagle@eyrie.org>. Many
323 thanks to Dropbox, Inc. for providing the time to write the initial
324 implementation during Dropbox's annual Hack Week.
325
327 Copyright 2016 Russ Allbery <eagle@eyrie.org>
328 Copyright 2016 Dropbox, Inc.
330 Copying and distribution of this file, with or without modification,
332 are permitted in any medium without royalty provided the copyright
333 notice and this notice are preserved. This file is offered as-is,
334 without any warranty.
335 SPDX-License-Identifier: FSFAP
337
339 remctld(8), sshd(8)
340 The current version of this program is available from its web page at
342 <https://www.eyrie.org/~eagle/software/remctl/>.
3433.17 2020-12-13 REMCTL-SHELL(8)