Shell

The Shell Agent Component allows you to invoke individual shell commands on your robot remotely, and also to interact with your robot through a secure remote shell session (refer to Remote Shell Access).

Note

The Shell Agent Component needs Agent Version 1.6+

Configuration

To use the Shell component, your agent will need a section in its agent-settings.json file which enables the shell component, as shown below. For more information on how to configure the agent components, see Agent Configuration.

...
"components": [
...
{
  "enabled": true,
  "id": "shell",
  "settings": {
    "logLevel": 4
  }
},
...
]

The shell component understands the following configuration parameters. Generally, you should not need to modify these settings:

Name	Description	Default	Unit
enabled	Whether to enable the shell component or not.	false
name	How this instance of the shell plugin should be named. In order for the remote shell feature of the Portal to work, there must be an instance named "shell", so changing this isn't recommended.	"shell"
logLevel	The logging verbosity: 1 - very quiet, 6 - very talkative.	4
enableInteractiveShells	Whether to enable support for the remote shell feature in the portal while the component is enabled. This can be disabled separately to help limit access to your robot.	true
shellSessionCommand	The command which the agent runs to begin a new interactive shell session.	Platform dependent. On Linux: /usr/bin/env bash -c "read -p \"$HOSTNAME login: \" username ; su -l $username ; true"
serviceCommandTemplate	A template which the agent applies to commands which are individually run using run() service. This ensures that commands you enter run in a convenient environment.	Platform dependent. On Linux: /usr/bin/env bash -c "cd / ; ${$cmd}"
serviceCommandTemplateTimeout	Because the serviceCommandTemplate can potentially be used to execute arbitrary JavaScript, a timeout can be applied to the templating operation.	"250ms"

Data Model

The shell component makes available a single Service named run, which can be invoked to execute a single shell command on the robot:

The service request takes the shell command to be executed as a string, and returns a single string response containing the data which the shell command printed to stdout. Long running commands will not output any response data until after the shell command has exited.

The requested command is templated prior to execution; this makes the service more convenient, because commands are executed in a consistent environment. By default on Linux hosts, the specified command will be run in the root (/) directory on the host.

Note

The entered shell command will be executed as the rocos-agent user; make sure you consider the permissions the command will be run with.