Search documentation
Dashboard
Getting Started

Installing Gremlin on a virtual machine

General steps for deploying the Gremlin Agent to a virtual machine:

Gather your credentials

All Gremlin integration installations require authentication with the Gremlin Control Plane. You can use either Team ID with secret or certificates. See Authentication to learn more about the two methods.

Install Gremlin packages

DEB packages

For DEB-based Linux distributions such as Ubuntu, Debian, and so on.

bash
1# Add packages needed to install and verify gremlin (already on many systems)
2sudo apt update && sudo apt install -y apt-transport-https dirmngr
3
4# Add the Gremlin repo
5echo "deb https://deb.gremlin.com/ release non-free" | sudo tee /etc/apt/sources.list.d/gremlin.list
6
7# Import the GPG key
8sudo apt-key adv --keyserver keyserver.ubuntu.com --recv-keys 9CDB294B29A5B1E2E00C24C022E8EF3461A50EF6
9
10# Install Gremlin
11sudo apt update && sudo apt install -y gremlin gremlind

RPM packages

For RPM-based Linux distributions such as Amazon Linux, RHEL, CentOS, and so on.

bash
1# Install dependencies
2sudo yum install -y iproute-tc
3
4# Add the Gremlin repo
5sudo curl https://rpm.gremlin.com/gremlin.repo -o /etc/yum.repos.d/gremlin.repo
6
7# Install Gremlin
8sudo yum install -y gremlin gremlind

Docker image

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

For gremlind to attack Docker containers, you need to add the gremlin user to the docker group after installing Gremlin and Docker.

bash
1sudo adduser gremlin docker

Configure Gremlin

The minimum configuration required to register the Gremlin Agent with the Control Plane is:

  • Team ID
  • Secret or certificate

For Reliability Management, Gremlin uses tags (such as operating system, zone, or local-hostname) to identify a Service's fingerprint, so you will need to assign those tags to the Gremlin Agent as well.

You can configure Gremlin using the Gremlin configuration file or with environment variables. For more information and additional configuration options, see Configuring Gremlin for more information.

When you are done, restart the Gremlin Agent to pick up your changes.

Validate the installation

Now it’s time to validate the installation.

Check Gremlin Agents

Make sure that the Gremlin Agent is active in the Agents list. If the Gremlin Agent is unhealthy, it may not have been installed or configured correctly. See Gremlin Agent in the Gremlin Knowledge Base for troubleshooting information.

Verify Control Plane connection

To verify that your Gremlin Agents are connected to the Gremlin Control Plane:

Verify Gremlin Agent

Use the command appropriate for your environment to verify that the Gremlin Agent is running.

System V

For hosts running System V (RHEL 6, CentOS 6, Amazon Linux 1, etc.), use the service command:

shell
1sudo service gremlind status
Systemd

For hosts running systemd (RHEL 7+, CentOS 7+, Amazon Linux 2, Ubuntu/Debian, etc.), use the systemctl command:

shell
1sudo systemctl status gremlind
Check Gremlin Agent status

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

shell
1gremlin check auth

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

1auth
2====================================================
3Auth Input Type : Certificate
4API Response : OK

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

1auth
2====================================================
3Auth Input Type : No valid auth found
4========= Identification ============:
5Team ID Source : Team ID not found
6Gremlin Identifier : [Host identifier]
7Gremlin Identifier Source : Not supplied explicitly, using the default
8========= Secret/Token Info =========:
9Team Secret Source : Team Secret not found
10.credentials valid : /var/lib/gremlin/.credentials file not found
11========= Certificate Info ==========:
12Team Certificate Source : Team Certificate not found
13========= Private Key Info ==========:
14Team Private Key Source : Team Private Key not found

If you're having trouble authenticating, see the Authentication FAQ in the Gremlin Knowledge Base for possible causes and solutions.