Skip to content

SSH ​

The SSH task runs a command on a computer that can't run a Situate agent, such as a network appliance or a server you aren't allowed to install software on. It connects to the computer over SSH through an SSH endpoint, logs in with the identity of the user the workflow runs as, runs one command and captures its output.

Where the Remote Execution task runs a command on any number of assets, the SSH task runs one command on one endpoint.

Setting Up ​

Before an SSH task can run, three things are needed:

  1. An SSH endpoint for the computer, with its host key accepted.
  2. An identity for that endpoint (a login and private key) for each user or service account that runs the task.
  3. The identity's public key in the login's ~/.ssh/authorized_keys on the computer.

The SSH Endpoint ​

Create the endpoint under Endpoints in the Object Browser: New Endpoint, then SSH. See Endpoints for the settings every endpoint has. Access Through Asset is the asset whose agent makes the connection; any agent can, so choose one that can reach the computer.

SettingMeaning
HostThe computer's host name or IP address
PortIts SSH port, 22 by default
Host keyThe computer's host key fingerprint. It is set by testing the endpoint, not typed in

The endpoint holds no login or password. Each user connects with their own identity for the endpoint, so one endpoint serves every user who has one.

Accepting the Host Key ​

Situate only connects to a computer whose host key you've accepted, so an impostor can't receive your commands. Test the endpoint (the Test button) to read the key. Situate connects, shows the key's type and fingerprint, and asks whether to accept it:

The host presented this ssh-ed25519 key:

SHA256:/n0jHG5mtt3tAwQg+EU/lGoCdtOLcvYKORi0n4manI8

Before accepting, compare the fingerprint with the computer's own. On the computer, run:

ssh-keygen -lf /etc/ssh/ssh_host_ed25519_key.pub

(Use the ecdsa or rsa key file for those key types.) Accepting saves the fingerprint in the endpoint and tests it again. From then on, Situate refuses to connect if the computer presents a different key.

If a computer's host key changes, for example because it was reinstalled, the next test shows Host Key Changed with the new key. Accept it only if you know why it changed.

The test logs in with your own identity for the endpoint. You can accept the host key before anyone has an identity; the test then reports that you have none.

Identities ​

Each user or service account that runs SSH tasks needs an Endpoint specific authentication identity for the endpoint with the Private Key security type. See Identities.

FieldMeaning
LoginThe account to log in as on the computer
Private KeyThe private key, pasted in. PEM (-----BEGIN RSA PRIVATE KEY-----, -----BEGIN PRIVATE KEY-----) and OpenSSH (-----BEGIN OPENSSH PRIVATE KEY-----) keys are accepted

The key can't have a passphrase, because Situate doesn't store one. Remove it from a copy of the key with ssh-keygen -p -f <keyfile> before pasting it in. The key is stored encrypted, and it is never written to the computer that makes the connection.

A role can carry the identity, so a group of users can share one login. As with any identity, Situate uses the first identity for the endpoint it finds; see Identities.

The Public Key ​

Add the identity's public key to the login's ~/.ssh/authorized_keys on the computer. If you have only the private key, ssh-keygen -y -f <keyfile> prints the public key.

Situate authenticates with keys only; it never uses passwords.

The Command ​

FieldMeaning
Task NameThe task's name
EndpointThe SSH endpoint to connect through. It may be an expression escape that names the endpoint
CommandThe command to run. It may contain expression escapes
Argument BuilderArguments added to the end of the command; see Argument Builder
Success CodesExit statuses that mean the task succeeded, separated by commas or spaces. 0 by default

The command is run by the login's shell on the computer, the way ssh host 'command' runs it, so pipes, redirections and && work as they do in that shell. The login's shell startup files apply as they do for any SSH command.

Security ​

The task logs in with the identity, for the endpoint, of the user the workflow runs as. Who that is follows the workflow's run-as settings, and can be changed for part of a workflow with the substitute user group. If that user has no identity for the endpoint, the task fails with a message naming the user.

Situate offers only current host key algorithms (Ed25519, ECDSA, and RSA with SHA-2 signatures), and it never sends a login to a computer whose host key doesn't match the accepted one.

The Task Log ​

The command's output, both stdout and stderr, is written to the task log as it arrives. You can watch it while the command runs: the task's status shows View Log and Quick Tail as soon as the command starts.

The log is kept on the agent of the endpoint's Access Through Asset, in logs/tasklogs/ssh under its install directory, for 30 days. A refiner on the task reads it, as it reads a Remote Execution task's output.

Success and Failure ​

When the command exits, its exit status is checked against the success codes. The task succeeds if the status is one of them, and fails otherwise. A command ended by a signal fails, whatever the success codes.

The task also fails, with the reason in its status and in the task log, when:

StatusWhat to do
The endpoint's host key isn't pinnedTest the endpoint and accept the host's key
The host key of host has changedSee Accepting the Host Key
user has no identity for this SSH endpointAdd an identity for the endpoint to the user (or a role)
host refused the private key of the identity for loginAdd the identity's public key to the login's ~/.ssh/authorized_keys
Unable to connect to host port nCheck the host, the port, and that the Access Through Asset can reach it

Canceling ​

Canceling the task sends the command a TERM signal and closes the connection.

Workload Automation and Orchestration