Remote Shell

A command line tool for your device

The Remote Shell tab enables you to execute bash shell commands against the device hosting the Ardexa Agent.

MENU: > [DEVICES] > (select device) > [REMOTE SHELL]

Permissions

Using the Remote Shell requires that you have the "Control Devices" permission on the device's Workgroup and/or Device Group. See Users and Permissions for more information.

Warning: commands executed on the remote shell will execute as the root user on the remote device.

Using the Remote Shell

To run a command using the Remote Shell, enter it into the command text box and hit Enter, or the "Run Command" button. The command will be executed on the device, and the contents of standard output and/or standard error will be displayed in your local browser.

For example, to print the local system time on the device, you could run:

echo My local time is $(date)

The command's return code is displayed after the command. => 0 indicates the return code, which in this case was successful.

The Copy button next to the return code will copy the command's output to your clipboard when clicked.

Previously executed commands can be selected by pressing the up and down arrow keys while the command text box is selected, as in other typical command prompts. Command history is shared between all devices within the same workgroup, in the same user session.

Clicking the Clear Output button will remove the results of previous commands from the window. Previous commands can still be accessed via the arrow keys.

Changing Directory

Initially, the current working directory will be the system root directory, '/'. Changing to another directory will update the "Current Directory" field.

File Transfers

Typical remote shell usage often involves transferring files to and from the device. To do this, use the Get Files and Send Files tabs.

If you have a command that generates a large volume of output, consider outputting to a local file on the device, then using Get Files to retrieve it.

Command Execution

Note: Long Running Processes and the Disown Option

[REMOTE SHELL] is designed to work with non-interactive commands that produce a finite set of output. If you have a long-running process, consider using the [Disown] checkbox option to prevent the Remote Shell in the Ardexa waiting for a response until the command times out.

[REMOTE SHELL] > [Advanced Settings] > [Disown]

By default, remote shell commands time out after five minutes. At this point, the command will be killed, and any output returned to the remote shell.

If you do happen to run a command that requires further interaction (example tail -f data.csv , which 'follows' new entries in a log file until terminated) the remote shell will not return any output, and will wait until it is timed out. You can use a combination of ps, grep and kill to find and kill the process:

ps | grep tail
Finding the process id that is executing our errant tail command: 2494
kill <process id>
Issuing a kill command to terminate the tail command
Checking that the tail has been killed. Any output generated by the tail command prior to termination will also be displayed

This method can also be used to terminate a disowned process (see below).

Using Disown

Some commands do not play nicely with the Remote Shell's command execution model. For example, restarting the Agent by running service ardexa restart will restart the Agent, but will not generate a response back to the Remote Shell as the connection will be broken. To tell the Remote Shell to not wait around for a response, you can click the "Disown" option under Advanced Settings:

Alternatively, you can attach a disown: prefix to the command. For the above example, this would be:

disown: service ardexa restart