remctl-shell [-dqS] [-f config] user
The output of the command ran is returned on standard output and standard error, like a normal command run via ssh, and the exit status of remctl-shell will be the exit status of the command. Only one command can be run per ssh connection, so this will be noticeably slower for each command execution than a well-designed remctl client and server design that holds connections open for multiple commands.
remctl-shell is designed to mimic the behavior of remctld and uses the same configuration syntax and environment variables. See ``CONFIGURATION FILE'' in remctld(8) for configuration information and ENVIRONMENT below for more specific details about environment variable handling. The location of the configuration file may be specified with the -f option. The default location is /etc/remctl.conf.
Since remctl-shell is designed to be run by a potentially untrusted user as a shell, normally all error messages and logging is done via syslog and not sent to standard error. See the -S, -d, and -q options when running it manually to debug problems. (When running manually, you will also normally need to set the SSH_CONNECTION environment variable and either REMCTL_USER or SSH_ORIGINAL_COMMAND depending on how you invoke it.)
For example, to run the command "log message" with argument "this is a message" via ssh from the command line, use:
ssh remctl@example.com log message "'this is a message'"
The first level of "" quoting will be removed by your local shell, and remctl-shell will interpret the second level of '' quotes. Note that, because of how ssh does command argument passing, this is exactly equivalent to:
ssh remctl@example.com "log message 'this is a message'"
since ssh doesn't preserve the distinction between separate arguments when creating the command to send to the remote server. It may be less confusing to get in the habit of quoting the entire command.
Also be aware that the full command is passed via command line arguments, which means, when invoking remctl-shell as a shell, there is a tight limit on the length of the whole command plus arguments. Expect to have problems if the total command length exceeds 1000 characters. For the same reason, binary data including null characters cannot be passed via remctl-shell. Invoking it as a forced command may work around these limitations by putting the command into the environment instead, but there may still be restrictions on that. (The regular remctl protocol supports arbitrary-length arguments, limited only by server-side configuration and available server memory, and supports arbitrary binary data in arguments.)
There are two ways to set up remctl-shell: either by specifying forced commands, or by configuring remctl-shell as the shell of the account. The forced command approach is recommended, since it doesn't require setting a non-default sshd_config option.
Using forced commands
For the role account that you want to use to run remctl commands ("remctl" by convention), create an authorized_keys file listing everyone who should be able to run commands. Before each key, set the "command" option like the below:
command="/usr/sbin/remctl-shell example@EXAMPLE.ORG"
where the argument to remctl-shell is the identity matching the ssh key on that line. A more complete example of a line in authorized_keys:
command="/usr/sbin/remctl-shell example@EXAMPLE.ORG",\
no-agent-forwarding,no-port-forwarding,no-pty,no-user-rc,\
no-X11-forwarding ssh-rsa AAAAB3NzaC1yc2EA... \
example@some-host.example.org
Backslashes and line breaks were added for clarity. The actual entry should be a single long line. For more information on the other settings here, see Examples below.
Using a shell
When running remctl-shell as the shell of the account, instead of using forced commands, the authorized_keys configuration must be set up to associate each key with an identity by setting the REMCTL_USER environment variable. Using user identities that look like Kerberos principal names is strongly recommended, since it may make it easier to use some of the ACL methods intended for the normal remctl server.
Since this relies on setting environment variables via "authorized_keys", you unfortunately have to enable "PermitUserEnvironment" in sshd_config (this is not the default) by adding:
PermitUserEnvironment yes
Other options
remctl-shell will not make use of forwarded connections or agents, and will not pass them along to the processes they run, so all such ssh options should normally be disabled for defense in depth security.
Examples
Here is a recommended line in "authorized_keys" for the account managed by remctl-shell, with appropriate restrictions and an example of how to set the REMCTL_USER variable. Backslashes and line breaks were added for clarity. The actual entry should be a single long line.
environment="REMCTL_USER=example@EXAMPLE.ORG",no-agent-forwarding,\
no-port-forwarding,no-pty,no-user-rc,no-X11-forwarding ssh-rsa \
AAAAB3NzaC1yc2EA... example@some-host.example.org
Setting "no-user-rc" is particularly important for remctl-shell. If you have OpenSSH 7.2 or later, which added the "restrict" keyword, you can instead use the much simpler:
environment="REMCTL_USER=example@EXAMPLE.ORG",restrict ssh-rsa \
AAAAB3NzaC1yc2EA... example@some-host.example.org
REMCTL_USER should be set to the identity string for the owner of that key pair, as used in the ACLs in your remctl configuration.
The start of each option description is annotated with the version of remctl-shell in which that option was added with its current meaning.
This is mandatory when using remctl-shell as a shell. If using it as a forced command, pass the user on the command line instead and do not use this option.
The following environment variables will be set for any commands run via remctl-shell (annotated with the version at which they were added). These are mostly the same as those set by remctld. Differences are noted in each description.
This is determined via a simple reverse DNS lookup and should be considered under the control of the client. remctl commands should treat it with skepticism and not use it for anything other than logging purposes.
Note that REMOTE_HOST is not set by remctl-shell, at least currently.
remctl-shell -c 'command subcommand argument'
(if used as a shell) or with:
remctl-shell user@EXAMPLE.ORG
(if used as a forced command) by sshd for each incoming connection from a user that has a key in the authorized_keys file.
If you need to run a command manually for debugging, you can run the same command as above, but it's often more useful to send errors to standard error instead of to syslog. You can do that with:
remctl-shell -S -c 'command subcommand argument'
If you don't want to see the normal command logging, add the -q option as well. You can test an alternate configuration file by specifying it with the -f option. You will need to set SSH_CONNECTION and either REMCTL_USER (if using -c) or SSH_ORIGINAL_COMMAND (if passing the user on the command line).
The forced command mode where the user can be passed on the command line and the command retrieved from SSH_ORIGINAL_COMMAND was added in the remctl 3.13 release.
Normally, remctl-shell runs as a dedicated non-root user (as opposed to often running as root like remctld), which means that all commands will normally run as that user and the "user" configuration option will not work. The easiest way to run commands as other users is to have the underlying command use sudo or some other user switching mechanism, which will normally require additional local configuration.
User environment setting has to be enabled in sshd by setting the non-default "PermitUserEnvironment" configuration option. A future version of remctl-shell may use forced commands with an argument instead of a shell to avoid this.
Copyright 2016 Dropbox, Inc.
Copying and distribution of this file, with or without modification, are permitted in any medium without royalty provided the copyright notice and this notice are preserved. This file is offered as-is, without any warranty.
SPDX-License-Identifier: FSFAP
The current version of this program is available from its web page at <https://www.eyrie.org/~eagle/software/remctl/>.