# Executor Operator
The **Executor** Operator can be used to execute a shell command on a target machine using SSH.
## Operator arguments
| Name | Type | Values restrictions | Required | Default | Description |
| ----------- | ------- | -------------------------------------------------------------------------- | -------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `command` | String | | yes | | The shell command to be executed on the remote machine |
| `host` | Object | See structure documented below | no | | Information relative to the target machine onto which the command has to be executed using SSH |
| `component` | String | It should match the name of an existing Component of the System under test | no | | The name of the Component whose properties can be used as arguments of the operator |
| `detach` | Boolean | | no | `False` | The execution mode of the shell command.
Default (False) execution will be synchronous, detached (True) execution will be asynchronous and will return immediately
|
### `Host` structure and arguments
Here follows the structure of the `host` argument:
```yaml
host:
hostname: this_is_a_hostname
username: this_is_a_username
password: this_is_a_password
sshPort: 22
key: this_is_a_key
```
with its arguments:
| Name | Type | Value Retrictions | Required | Default | Description |
| ---------- | ------ | ------------------------------------------ | ----------------------------------------------------------------------------------------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `hostname` | String | should be a valid SSH host address | no, if the Component whose name is defined in `component` has a property named `hostname` | | SSH endpoint |
| `username` | String | | no, if the Component whose name is defined in `component` has a property named `username` | | SSH login username |
| `password` | String | cannot be set if `key` is already set | no, if the Component whose name is defined in `component` has a property named `password` | | SSH login password |
| `sshPort` | Number | 1≤`sshPort`≤65532 | no | 22 | SSH port |
| `key` | String | cannot be set if `password` is already set | no, if the Component whose name is defined in `component` has a property named `key` | | SSH login key. Either provide directly the key value or specify the path of the file (local to the cli executing the create command) to read the key from. The operator supports RSA and DSA Keys. |
### Get operator arguments from `component`
The `component` argument can refer to a component by name and use its properties as the arguments of the operator (see mapping here below). In case the mapped arguments are already provided to the operator, there is no override.
#### Component property to operator argument mapping
| Component Property | Operator Argument |
| ------------------ | ----------------- |
| `hostname` | `host->hostname` |
| `username` | `host->username` |
| `sshPort` | `host->sshPort` |
| `password` | `host->password` |
| `key` | `host->key` |
### Examples
Let's assume you want to run a script on a remote host and expect the script to be executed successfully within 30 seconds but might fail occasionally.
Launch a script, wait for its completion, and in case of failures or timeout retry 3 times by waiting 10 seconds between retries:
```yaml
name: Run Script
operator: Executor
arguments:
timeout: 30s
retries: 3
retry_delay: 10s
command: bash /tmp/myscript.sh
host:
hostname: frontend.akamas.io
username: akamas
key: secret.key
```
Execute a *uname* command with explicit host information (explicit SSH key)
```yaml
name: TestConnectivity
operator: Executor
arguments:
command: bash uname -a
host:
hostname: frontend.akamas.io
username: akamas
key: |-
-----BEGIN RSA PRIVATE KEY-----
RSA KEY HERE
-----END RSA PRIVATE KEY-----
```
Execute a *uname* command with explicit host information (imported SSH key)
```yaml
name: TestConnectivity
operator: Executor
arguments:
command: bash uname -a
host:
hostname: frontend.akamas.io
username: akamas
key: path/to/key
```
Execute a *uname* command with host information taken from a Component
```yaml
name: TestConnectivity
operator: Executor
arguments:
command: bash uname -a
component: frontend1
```
Start a load-testing script and keep it running in the background during the workflow
```yaml
name: TestConnectivity
operator: Executor
arguments:
command: bash start_load.sh
component: tester
detach: true
```
### Troubleshooting
#### **Troubles in running sh scripts remotely**
Due to the *stderr* configuration, it could happen that invoking a bash script on a server has a different result than running the same script from Akamas Executor Operator. This is quite common with Tomcat startup scripts like `$HOME/tomcat/apache-tomcat_1299/bin/startup.sh`.
To avoid this issue simply create a wrapper bash file on the target server adding the set -m instruction before the sh command, eg:
```bash
#!/bin/bash
set -m;
$HOME/tomcat/apache-tomcat_1299/bin/startup.sh
```
and then configure the Executor Operator to run the wrapper script like:
```bash
command: "bash $HOME/akamasScript/tomcatStart.sh
```
You can run the following to emulate the same behavior of Akamas running scripts over SSH:
```bash
ssh -t @
```
#### **Troubles in keeping a script running in the background**
There are cases in which you would like to keep a script running for the whole duration of the test.\
Some examples could be:
* A script applying load to your system for the duration of the workflow
* The manual start of an application to be tested
* The setup of a listener that gathers logs, metrics, or data
In all the instances where you need to keep a task running beyond the task that started it, you must use the `detach: true` property.\
Note that a detached executor task returns immediately, so you should run only the background task in detached mode.
Remember to keep all tasks requiring synchronous (standard) behavior out of the detached task.
Example:
```
switch on machine and wait for SSH
run application test in background → detached mode
execute test run
```
**Library references**
The library used to execute scripts remotely is [Fabric](https://www.fabfile.org), a high-level Python library designed to execute shell commands remotely over SSH, yielding useful Python objects in return.
The Fabric library uses a connection object to execute scripts remotely (see [connection — Fabric documentation)](https://docs.fabfile.org/en/2.6/api/connection.html). The option of a dedicated `detach` mode comes from implementing the more robust `disown` property from the Invoke Runner underlying the Connection (see [runners — Invoke documentation](https://docs.pyinvoke.org/en/stable/api/runners.html)). This is the reason you should rely on `detach` whenever possible instead of running the background processes straight into the script.
In the [Frequently Asked/Answered Questions (FAQ) — Fabric documentation](https://www.fabfile.org/faq.html) you may find some further information about the typical problems and solutions due to hanging problems for background processes.