Installing Gremlin on a virtual machine

‍

Steps for deploying the Gremlin agent to a virtual machine include:

1. Gathering your credentials
2. Installing Gremlin packages
3. Configuring Gremlin
4. Validating the installation

‍

Gather your credentials

All Gremlin integration installations require authentication with the Gremlin Control Plane. We recommend using the Client Configuration File method, as it contains everything needed to authenticate and configure the Gremlin Agent in one file. To create and download a client configuration file:

1. Open the Settings page in the Gremlin web app.
2. Under Team Settings, select Details.
3. On the Client Configuration File line, click Download to download the file. You'll receive a file named config.yaml.
4. Optionally, make any additional configurations to the config.yaml file.

If you wish to use another method of authenticating, see the Authentication docs.

‍

Install Gremlin packages

Choose the format that corresponds to your distribution.

• DEB packages (Ubuntu, Debian, etc.)
• RPM packages (SUSE, Amazon Linux, RHEL, CentOS, Rocky, etc.)
• Docker image

If you intend to run experiments against container workloads, it is recommended to install Gremlin as a container using the Docker image. If you choose to install Gremlin using an RPM or DEB package and target container workloads with experiments, some work may be necessary to grant the gremlin Linux user access to container socket files such as /run/containerd/containerd.sock . By default, Gremlin will add itself to the docker Linux group if it is present during installation.

‍

DEB packages

For DEB-based Linux distributions such as Ubuntu, Debian, and so on. Note that this will also install the required dependencies apt-transport-https and dirmngr.

‍

If the export step prints gpg: WARNING: nothing exported, /usr/share/keyrings/gremlin.gpg will exist but be empty and apt update will report the repository as unsigned. Confirm the file is not empty before continuing.

‍

RPM packages

Amazon Linux, RHEL, CentOS

For non SUSE-based RPM distributions such as Amazon Linux, RHEL, etc. Note that this will also install the required dependencies iproute-tc  and kernel-modules-extra.

‍

SUSE

For distributions based on SUSE Linux, such as SUSE Linux Enterprise Server (SLES), openSUSE, etc. Note that this will also install the required dependency libcap-progs.

‍

Docker image

Alternatively, instead of installing Gremlin directly on the host operating system, you can deploy Gremlin from the Docker image on DockerHub.

To run the daemon, use the following command (replace /path/to/config.yaml with the actual path to your config.yaml file):

‍

Validate the installation

There are two ways to ensure your installation was successful and your Agents authenticated successfully:

1. Check the agents list in the Gremlin web app
2. Check the agent's connection to Gremlin's servers

‍

Check the Gremlin web app

The easiest way to verify connectivity is to open the agents list in the Gremlin web app. Check for your newly installed agent by name or by tag. You can also use the search box to search by name or tag, agent version, operating system (OS), or region. If your agent does not appear in this list, it may not have been installed or configured correctly, or it might not be able to reach Gremlin's servers.

‍

Check the Gremlin Agent

First, verify that the Gremlin Agent is running on the target system:

sudo systemctl status gremlind

‍

This should return the following:

● gremlind.service - Gremlin Daemon
     Loaded: loaded (/etc/systemd/system/gremlind.service; enabled; vendor preset: enabled)
     Active: active (running) since Wed 2023-01-04 10:44:12 EST; 5 days ago

‍

If the service is instead reporting as inactive or failed, try restarting the service using:

sudo systemctl restart gremlind

‍

After verifying that the Gremlin agent is running, use gremlin check auth to check the Gremlin Agent's authentication status:

gremlin check auth

‍

If the Gremlin agent authenticated successfully, the output will be similar to the following:

auth
====================================================
Auth Input Type                      : Certificate
API Response                         : OK

‍

If not, the output will explain why the Gremlin agent was unable to authenticate:

auth
====================================================
Auth Input Type                      : No valid auth found
========= Identification ============:
Team ID Source                       : Team ID not found
Gremlin Identifier                   : [Host identifier]
Gremlin Identifier Source            : Not supplied explicitly, using the default
========= Secret/Token Info =========:
Team Secret Source                   : Team Secret not found
.credentials valid                   : /var/lib/gremlin/.credentials file not found
========= Certificate Info ==========:
Team Certificate Source              : Team Certificate not found
========= Private Key Info ==========:
Team Private Key Source              : Team Private Key not found

‍

Troubleshooting

If the Agent is connected but is reporting as unhealthy, see Troubleshooting Unhealthy State in the Gremlin Knowledge Base. If you're having trouble authenticating, see the Authentication FAQ in the Gremlin Knowledge Base for possible causes and solutions.

‍

Uninstalling Gremlin from a virtual machine

The command for uninstalling the Gremlin agent from a Linux virtual machine will vary depending on your distribution.

‍

Uninstalling DEB packages

For DEB-based Linux distributions such as Ubuntu and Debian:

sudo apt remove gremlin gremlind

‍

Uninstalling RPM packages

SUSE-based distributions

For distributions based on SUSE Linux, such as SUSE Linux Enterprise Server (SLES), openSUSE, etc.:

sudo zypper remove gremlin gremlind

‍

Non SUSE-based distributions

For non SUSE-based RPM distributions such as Amazon Linux, RHEL, CentOS, etc.:

sudo yum remove gremlin gremlind

‍

Uninstalling Docker image

If you deployed Gremlin using Docker, use the following command to uninstall it. Note that the container name may be different, depending on whether you specified a name:

sudo docker stop gremlin
sudo docker rm gremlin