Appearance
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:
- An SSH endpoint for the computer, with its host key accepted.
- An identity for that endpoint (a login and private key) for each user or service account that runs the task.
- The identity's public key in the login's
~/.ssh/authorized_keyson 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.
| Setting | Meaning |
|---|---|
| Host | The computer's host name or IP address |
| Port | Its SSH port, 22 by default |
| Host key | The 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/lGoCdtOLcvYKORi0n4manI8Before 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.
| Field | Meaning |
|---|---|
| Login | The account to log in as on the computer |
| Private Key | The 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
| Field | Meaning |
|---|---|
| Task Name | The task's name |
| Endpoint | The SSH endpoint to connect through. It may be an expression escape that names the endpoint |
| Command | The command to run. It may contain expression escapes |
| Argument Builder | Arguments added to the end of the command; see Argument Builder |
| Success Codes | Exit 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:
| Status | What to do |
|---|---|
| The endpoint's host key isn't pinned | Test the endpoint and accept the host's key |
| The host key of host has changed | See Accepting the Host Key |
| user has no identity for this SSH endpoint | Add an identity for the endpoint to the user (or a role) |
| host refused the private key of the identity for login | Add the identity's public key to the login's ~/.ssh/authorized_keys |
| Unable to connect to host port n | Check 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.