Skip to main content

SSH Data Source

The SSH data source executes commands on remote systems over SSH and captures the command output as Mango data point values. Each data point defines a query command that runs on every poll cycle, and optionally a set command that executes when a value is written to the point. This data source supports all Mango data types (Binary, Multistate, Numeric, and Alphanumeric), with automatic type conversion applied to the command output.

The SSH data source is useful for monitoring remote Linux/Unix servers, reading sensor values from embedded devices accessible via SSH, controlling equipment through command-line interfaces, and collecting metrics from systems that expose data only through shell commands.

Overview​

PropertyValue
ModulemangoAutomation-Ssh
ProtocolSSH
DirectionPolling
Typical UseExecuting remote commands and collecting output via SSH

Prerequisites​

  • SSH access to the remote host. The remote system must be running an SSH server (such as OpenSSH or Dropbear).
  • Authentication credentials -- either password-based or public key-based authentication.
  • Knowledge of the commands to execute on the remote system and the format of their output.
  • Network connectivity between the Mango server and the remote host on the SSH port (default: 22).

Setting Up Public Key Authentication​

Public key authentication is recommended for unattended operation because it eliminates the need to store passwords.

Linux/OpenSSH example:

  1. Log in to the Mango server.
  2. Generate an RSA key pair (do not enter a passphrase): 
    ssh-keygen -t rsa
  3. Copy the generated public key to the remote server: 
    scp ~/.ssh/id_rsa.pub user@remotehost:.ssh/authorized_mango_keys
  4. Log in to the remote server and append the public key to the authorized keys file: 
    cat ~/.ssh/authorized_mango_keys >> ~/.ssh/authorized_keys
  5. Set correct permissions on all SSH files: 
    chmod 600 ~/.ssh/authorized_keys ~/.ssh/authorized_mango_keys

The default location for authorized keys varies by SSH server implementation:

  • OpenSSH: /root/.ssh/authorized_keys (or ~/.ssh/authorized_keys for non-root users)
  • Dropbear: /home/root/.ssh/authorized_keys

To change the passphrase on an existing key, use ssh-keygen -p.

Configuration​

Data Source Settings​

SettingDescription
NameA descriptive name for the data source.
HostThe IP address or hostname of the remote SSH server.
PortThe SSH port number (default: 22).
UsernameThe SSH login username.
PasswordThe SSH password (if using password authentication).
Update periodHow frequently the data source polls the remote system by executing query commands.
TimeoutMaximum time to wait for a response from the SSH server.

Data Point Configuration​

SettingDescription
Device NameThe device name for organizational purposes.
NameThe display name of the data point.
XIDA unique identifier for the data point.
Data typeThe Mango data type. Determines how the command output is interpreted (see below).
QueryableWhen checked, the Query Command is issued every poll cycle and the response is captured as the point value.
Query CommandThe shell command to execute on the remote system. The output is parsed according to the data type.
SettableWhen checked, the point can be written to, which triggers execution of the Set Command.
Set CommandThe shell command to execute when a value is written to this point. Every occurrence of the string VALUE (all capitals) in the command is replaced with the value being set.

Data Type Conversion​

Data TypeExpected OutputConversion Behavior
BinaryAny textOutput starting with 0 or yielding no response is treated as false. All other output is true. Setting false sends 0; setting true sends 1.
MultistateAn integerThe response must be a single integer value.
NumericA floating-point numberThe response must be a single double-precision number.
AlphanumericAny textThe full response text is captured as the point value.

Multiple Commands and Delays​

Both query and set commands support executing multiple commands in sequence within the same SSH channel:

  • Linux/Unix: Delimit commands with ; (e.g., command1; command2; command3;)
  • Windows: Delimit commands with & (e.g., command1 & command2 & command3)

This is particularly important for set commands, where a delay may be needed between setting a value and querying the result:

program set-value VALUE; sleep 0.2s; program read-value;

The delay (using sleep or equivalent) ensures the controlled device has time to process the set command before the query command reads the new state.

tip

Because the query string is also used in the set channel to read back the new value, it is best practice to end set commands with the OS-specific delimiter (; for Linux, & for Windows), even if there is only one set command. If the point is not queryable, this is not strictly necessary, but it is a good habit.

Common Patterns​

Monitoring Remote Server Metrics​

Create points to read CPU temperature, disk usage, memory utilization, or process counts from a remote Linux server:

MetricExample Query Command
CPU temperaturecat /sys/class/thermal/thermal_zone0/temp
Disk usage (%)df / --output=pcent | tail -1 | tr -d ' %'
Available memory (MB)free -m | awk '/Mem:/ {print $7}'
Process countps aux | wc -l

Reading Embedded Device Sensors​

Many embedded devices (Raspberry Pi, BeagleBone, industrial edge devices) expose sensor data through system files or command-line utilities. The SSH data source can read these values without installing any additional software on the device.

Remote Equipment Control​

Use settable points to control equipment on a remote system. For example, to toggle a GPIO pin on a Raspberry Pi:

  • Set Command: echo VALUE > /sys/class/gpio/gpio18/value; sleep 0.1s;
  • Query Command: cat /sys/class/gpio/gpio18/value

Network Device Monitoring​

SSH into network switches, routers, or firewalls to read interface statistics, routing table entries, or device status. Many network devices provide SSH access with proprietary CLI commands.

Troubleshooting​

Connection Refused​

  1. Verify the remote host is running an SSH server and listening on the configured port.
  2. Check for firewall rules blocking SSH traffic between the Mango server and the remote host.
  3. Confirm the hostname or IP address is correct and reachable from the Mango server.

Authentication Failures​

  1. Password auth: Verify the username and password are correct. Some SSH servers disable password authentication by default.
  2. Public key auth: Ensure the public key is correctly appended to the remote server's authorized_keys file and that file permissions are set to 600.
  3. Check that the SSH key was generated without a passphrase. Mango cannot interactively enter a passphrase.

Wrong or Missing Values​

  1. Command output format -- if the query command returns extra text (headers, labels, whitespace), the data type conversion will fail. Use shell utilities like awk, grep, tr, or cut to extract only the numeric or text value.
  2. Binary points returning false -- remember that any output starting with 0 is treated as false. If the command returns 0.5, the binary conversion sees the leading 0 and returns false.
  3. Multistate points failing -- ensure the command output is a clean integer with no extra characters or whitespace.

Stale Values After Set​

If the query command immediately after a set returns the old value, the remote device may need time to process the change. Add a sleep command between the set and query commands in the set command string.

Connection Drops​

Long-running SSH connections may be terminated by firewalls or SSH server idle timeouts. If the data source shows intermittent connection errors, check the SSH server's ClientAliveInterval and ClientAliveCountMax settings, and any firewall rules that expire idle TCP connections.