1REMCTL-SHELL(8)                     remctl                     REMCTL-SHELL(8)
2
3
4

NAME

6       remctl-shell - Restricted shell that mimics a remctl server
7

SYNOPSIS

9       remctl-shell [-dhqSv] [-f config] -c command
10
11       remctl-shell [-dqS] [-f config] user
12

DESCRIPTION

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
22       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
29       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
36       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
44   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
57       For example, to run the command "log message" with argument "this is a
58       message" via ssh from the command line, use:
59
60           ssh remctl@example.com log message "'this is a message'"
61
62       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
67           ssh remctl@example.com "log message 'this is a message'"
68
69       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
73       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
85   "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
90       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
95       Using forced commands
96
97       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
102           command="/usr/sbin/remctl-shell example@EXAMPLE.ORG"
103
104       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
107           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
112       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
116       Using a shell
117
118       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
125       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
130           PermitUserEnvironment yes
131
132       Other options
133
134       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
138       Examples
139
140       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
145           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
149       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
153           environment="REMCTL_USER=example@EXAMPLE.ORG",restrict ssh-rsa \
154           AAAAB3NzaC1yc2EA... example@some-host.example.org
155
156       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

OPTIONS

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
167       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
170       -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
176           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
180       -d  [3.12] Enable verbose debug logging to syslog (or to standard
181           output if -S is also given).
182
183       -f config
184           [3.12] The configuration file for remctld, overriding the default
185           path.
186
187       -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
192       -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
196       -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
202       -v  [3.12] Print the version of remctl-shell and exit.
203

ENVIRONMENT

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
208       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
217       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
225       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
229       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
234       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
239       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
243       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
250       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
255           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
260       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
266       Note that REMOTE_HOST is not set by remctl-shell, at least currently.
267

EXAMPLES

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
275           remctl-shell -c 'command subcommand argument'
276
277       (if used as a shell) or with:
278
279           remctl-shell user@EXAMPLE.ORG
280
281       (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
284       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
288           remctl-shell -S -c 'command subcommand argument'
289
290       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

COMPATIBILITY

297       remctl-shell was added in the remctl 3.12 release.
298
299       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

CAVEATS

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
309       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
316       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

AUTHOR

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
329       Copyright 2016 Dropbox, Inc.
330
331       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

SEE ALSO

337       remctld(8), sshd(8)
338
339       The current version of this program is available from its web page at
340       <http://www.eyrie.org/~eagle/software/remctl/>.
341
342
343
3443.14                              2018-04-01                   REMCTL-SHELL(8)
Impressum