Installing Gremlin on a virtual machine
Before installing, review the list of caveats to see if additional steps are required for your environment.
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. 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:
- Access the Team Settings page in the Gremlin web app.
- Click the Configuration tab.
- On the Client Configuration File line, click Download to download the file. You'll receive a file named
config.yaml
. - 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
DEB packages
For DEB-based Linux distributions such as Ubuntu, Debian, and so on.
1# Add packages needed to install and verify gremlin (already on many systems)2sudo apt update && sudo apt install -y apt-transport-https dirmngr34# Add the Gremlin repo5echo "deb https://deb.gremlin.com/ release non-free" | sudo tee /etc/apt/sources.list.d/gremlin.list67# Import the GPG key8sudo apt-key adv --keyserver keyserver.ubuntu.com --recv-keys 9CDB294B29A5B1E2E00C24C022E8EF3461A50EF6910# Install Gremlin11sudo apt update && sudo apt install -y gremlin gremlind
If you want to install an older version of Gremlin, you can list all Agent versions using apt list -a gremlin
and install them using apt install gremlin-x.x.x-x
RPM packages
SUSE-based distributions
For distributions based on SUSE Linux, such as SUSE Linux Enterprise Server (SLES), openSUSE, etc.:
1# Install dependencies2sudo zypper install -y iproute-tc libcap-progs34# Add the Gremlin repo5sudo zypper addrepo https://rpm.gremlin.com/gremlin.repo gremlin67# Install Gremlin and dependencies8sudo zypper refresh && sudo zypper install gremlin gremlind
Non SUSE-based distributions
For non SUSE-based RPM distributions such as Amazon Linux, RHEL, CentOS, etc.:
1# Install dependencies2sudo yum install -y iproute-tc34# Add the Gremlin repo5sudo curl https://rpm.gremlin.com/gremlin.repo -o /etc/yum.repos.d/gremlin.repo67# Install Gremlin8sudo yum install -y gremlin gremlind
If you want to install an older version of Gremlin, you can list all Agent versions using yum list available gremlin --showduplicates
and install them using yum install gremlin-x.x.x-x
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 $GREMLIN_TEAM_ID
with your team ID and $GREMLIN_TEAM_SECRET
with your team's secret key:
1docker run -d --net=host \2 --cap-add=NET_ADMIN --cap-add=SYS_BOOT --cap-add=SYS_TIME \3 --cap-add=KILL \4 --pid=host \5 -v $PWD/var/lib/gremlin:/var/lib/gremlin \6 -v $PWD/var/log/gremlin:/var/log/gremlin \7 -v /var/run/docker.sock:/var/run/docker.sock \8 -e GREMLIN_TEAM_ID="$GREMLIN_TEAM_ID" \9 -e GREMLIN_TEAM_SECRET="$GREMLIN_TEAM_SECRET" \10 gremlin/gremlin daemon
If you want to run tests on other Docker containers, you'll need to add the gremlin
user to the docker
group after installing both Gremlin and Docker:
1sudo adduser gremlin docker
Configure Gremlin
The minimum configuration required to authenticate the Gremlin Agent is:
- Team ID
- Secret or certificate
If you downloaded a client configuration file, you already have everything needed to register the Agent. Just follow these instructions:
Copy the configuration file (named
config.yaml
) to the/etc/gremlin/
directory. The final path should be/etc/gremlin/config.yaml
:bash1sudo cp config.yaml /etc/gremlin/config.yamlRestart the
gremlind
service:bash1sudo systemctl restart gremlind
Additional configuration options
Read this section if you wish to further configure the Gremlin Agent. Otherwise, skip to the next section.
For Reliability Management, Gremlin uses tags such as operating system, zone, and local-hostname to identify each service's fingerprint. Gremlin automatically detects many tags, but if you wish to apply custom tags (e.g. environment, location, or service name), read the Network tags documentation.
For more information and additional configuration options, see Configuring Gremlin for more information.
Make any edits to the /etc/gremlin/config.yaml
file, then restart the gremlind
service after you've made your changes.
Customize Gremlin's Linux user and group
By default on Linux, Gremlin installs a gremlin
Linux user and group, and sets the suid
bit on /usr/bin/gremlin
so that all users can run the Gremlin executable. These defaults can be overridden at installation time by supplying
environment variables to the installer.
For example, to run Gremlin as root and restrict executable access to root:root
, you would run:
1GREMLIN_INSTALL_USER=root GREMLIN_INSTALL_GROUP=root GREMLIN_INSTALL_BIN_MODE=0770 \2 sudo -E yum install gremlin gremlind
The full list of variables available at install time, and their defaults are as follows:
Variable | Default | Description |
---|---|---|
GREMLIN_INSTALL_USER | gremlin | The Linux user to own all file installed by Gremlin. This user is created if it does not exist |
GREMLIN_INSTALL_GROUP | gremlin | The Linux group to own all file installed by Gremlin. This group is created if it does not exist |
GREMLIN_INSTALL_BIN_MODE | 0750 1 | The file mode for executable files installed by Gremlin. |
GREMLIN_INSTALL_BIN_CAPABILITIES | unset | A boolean argument specifying whether Gremlin's required capabilities should be set on the binaries themselves. The default is false. Any value supplied to this variable evaluates to true. |
1. Gremlin versions before 2.33.0
default this value to 6111
instead.
Validate the installation
There are two ways to ensure your installation was successful and your Agents authenticated successfully:
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:
1sudo systemctl status gremlind
This should return the following:
1● gremlind.service - Gremlin Daemon2 Loaded: loaded (/etc/systemd/system/gremlind.service; enabled; vendor preset: enabled)3 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:
1sudo systemctl restart gremlind
After verifying that the Gremlin Agent is running, use gremlin check auth
to check the Gremlin Agent's authentication status:
1gremlin check auth
If the Gremlin Agent authenticated successfully, the output will be similar to the following:
1auth2====================================================3Auth Input Type : Certificate4API Response : OK
If not, the output will explain why the Gremlin Agent was unable to authenticate:
1auth2====================================================3Auth Input Type : No valid auth found4========= Identification ============:5Team ID Source : Team ID not found6Gremlin Identifier : [Host identifier]7Gremlin Identifier Source : Not supplied explicitly, using the default8========= Secret/Token Info =========:9Team Secret Source : Team Secret not found10.credentials valid : /var/lib/gremlin/.credentials file not found11========= Certificate Info ==========:12Team Certificate Source : Team Certificate not found13========= Private Key Info ==========:14Team 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.
DEB packages
For DEB-based Linux distributions such as Ubuntu and Debian:
1sudo apt remove gremlin gremlind
RPM packages
SUSE-based distributions
For distributions based on SUSE Linux, such as SUSE Linux Enterprise Server (SLES), openSUSE, etc.:
1sudo zypper remove gremlin gremlind
Non SUSE-based distributions
For non SUSE-based RPM distributions such as Amazon Linux, RHEL, CentOS, etc.:
1sudo yum remove gremlin gremlind
Docker image
If you deployed Gremlin using Docker, use the following command to uninstall it. Note that the container name may be different than gremlin
, depending on whether you specified a name:
1sudo docker stop gremlin2sudo docker rm gremlin