Unix Shell

The Unix Shell Agent allows you to run a shell script on a remote Unix (Linux) machine. To set up the Unix Shell Agent, follow the steps below.

Setup

The following steps require fundamental knowledge about the UnixShell. The given commands are not guaranteed to work on any Unix (Linux) distribution and need to be adopted according to your distribution.

Create an automation agent in aqua and write down the Access key (also known as Agent code) Check if Java is installed on the target Unix (Linux) machine, e.g. by running the following command:

java -version

The result should look similar to the screenshot below:

If Java is not installed on your target machine, you can install it by following the instructions for your Unix (Linux) distribution. Alternatively, you can download a java runtime environment (jre) as a *.tar.gz package and unpack it to a folder of your choice. The following commands are examples for an Ubuntu distribution:

mkdir /usr/java 
cd /usr/java
tar zxvf <path-to-your-java-tar.gz>

Upload aqua UnixShell-agent to your Unix (Linux) machine and unzip it to a folder of your choice (e.g. using unzip command in Ubuntu that can be installed via sudo apt-get install unzip).

cd /usr
unzip <path-to-UnixShell-agent-zip-file>

Edit the file agent.properties (e.g. using command nano) and change the line agentCode (see the first step) as well as aquaServiceUrl so that the agent can communicate with your aqua Server.

An example can be seen below.

If you installed java following the alternative approach as described in Step 2, please edit the file agent.sh and adopt the path to the java command. Please note the option to run agent in window-mode. This might be suitable for Unix (Linux) machines that have a GUI installed.

Make the file agent.sh executable. sudo chmod +x ./agent.sh

Start agent by running agent.sh. cd <path to agent folder> ./agent.sh When an exception occurred, please check file agent.properties again, if agentcode and aquaServiceUrl is set properly.

In aqua, you should see a green indicator for your agent.

Writing Shell-Script that return results to aqua

To run a UnixShell script in aqua, create a new test case, open the Step Designer and select the Automation tab. Select the test step (click on the empty space of the given step) and add a new Unix shell script.

Adding UnixShell script

In the Script-area of the step, you are able to insert the script to be run on the remote machine. An example is given below:

##################
#!/bin/bash
# Sample bash script
 
# everything that is written to the console is send back to aqua
echo "script is running"
 
# Access variable named VAR1
echo "$AQUA_VAR1"
 
# files that are stored in subfolder toAttach are send back to aqua (below are two examples)
# Example 1: Attach a file named test.txt to the execution (touch creates a new file in subfolder named -toAttach-)
touch ./toAttach/test.txt
 
# Example 2: in order to upload files, you can also copy a file to be uploaded to the subfolder -toAttach-
# Syntax: cp <filePath> ./toAttach
cp /tmp/screnshot.png ./toAttach
 
# Return the execution result: 0 means Passed. Everything else means Failed
exit 0
##################

UnixShell automated script

When you are done with your script, you can save and run your test case.

For the execution, a new subfolder is created in the temp-Folder of the agent. In this subfolder, another subfolder toAttach is created automatically so that you are able to upload attachments as given in the example. If you want to see the temp-Folder after execution, please set deleteTempFiles=false in file agent.properties and restart your agent.

Upload File

Using the Upload file button, you can add files to the automated UnixShell step, which are then automatically downloaded during execution and stored in the temp folder of the agent in which the script is also executed. This allows you to easily use these files within the script. In addition, files can also be uploaded during script execution as mentioned above.

Limitations

• Images can be uploaded as attachments. However, uploading images so that they are directly visible in the aqua execution log is not possible so far.

• Complete output of the console is written to the last step in the execution log and not written as multiple execution log entries.

• As a consequence of the 2nd limitation, you can not control the log level of a single execution log message.