Gremlin must be installed on each host you wish to attack. In order for your hosts (and containers within the hosts) to be targetable, the installed gremlin must be registered with the Gremlin Control Plane.
Gremlin can be deployed into bare-metal environments running either Linux or Windows, into container-based infrastructure environments running on Linux, and into virtual infrastructure environments.
General steps deploying to Virtual Machine:
- Get credentials - Team ID with secret or certificates
- Install Gremlin packages:
- Register to the Control Plane
General steps deploying to Kubernetes:
Before installing look at our caveats page to see if there are additional steps needed for your distribution during installation.
For DEB-based Linux distributions (DEB packages)
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 Gremlin client and daemon11sudo apt update && sudo apt install -y gremlin gremlind
List older versions of gremlin via:
apt list -a gremlin and install them via
apt install gremlin=x.x.x-x
For RPM-based Linux distributions (RPM packages)
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 Gremlin client and daemon8sudo yum install -y gremlin gremlind
List older versions of gremlin via:
yum list available gremlin --showduplicates and install them via
yum install gremlin-x.x.x-x
Alternatively, instead of installing Gremlin directly on the host operating system, you can deploy Gremlin from the Docker image on DockerHub.
gremlind to attack Docker containers, you need to add the
gremlin user to the
docker group after installing Gremlin and Docker.
1sudo adduser gremlin docker
Gremlin allows targeting objects within your Kubernetes clusters. After selecting a cluster, you can filter the visible set of objects by selecting a namespace. Select any of your
Pods. When one object is selected, all child objects will also be targeted. For example, when selecting a DaemonSet, all of the pods within will be selected.
Only parent Kubernetes objects are available to target. Pods will be listed only if they don't belong to a Set or Deployment.
The Gremlin Kubernetes client can be installed in place of—or in addition to—installing the Gremlin client on a host. You can install the Kubernetes client using either
helm. Both methods are outlined here.
When using signature-based authentication, we recommend storing your certificates as a Kubernetes secret. This section will walk you through this process.
- Download the Gremlin certificates (your role must either be Team Manager or Team Credential Manager).
- Unzip certificates.zip.
- Rename the files in the certificates folder.
- Create a gremlin namespace:bash1kubectl create namespace gremlin
- Create a kubernetes secret by running the following:bash1kubectl -n gremlin create secret generic gremlin-team-cert --from-file=/path/to/gremlin.cert --from-file=/path/to/gremlin.key
Download the Gremlin configuration manifest by running the following:bash1wget https://k8s.gremlin.com/resources/gremlin-conf.yaml
Open the file and update the following:
<YOUR TEAM ID GOES HERE>with your Gremlin team ID.
<YOUR TEAM SECRET GOES HERE>with your Gremlin team secret (If you are using certificate-based authentication, remove this line.)
<YOUR UNIQUE CLUSTER NAME GOES HERE>with a unique name for your cluster. This can be any name you want, and will appear in Gremlin in the Kubernetes client list.
Apply the manifest with this command:bash1kubectl apply -f gremlin-conf.yaml
If you are using certificate-based authentication, download and apply the gremlin client manifest for your Kubernetes cluster by running the following:
1kubectl apply -f https://k8s.gremlin.com/resources/gremlin-client.yaml2kubectl apply -f https://k8s.gremlin.com/resources/gremlin-chao.yaml
If you are using secret-based authentication, download and apply the gremlin client manifest for your Kubernetes cluster by running the following:
1kubectl apply -f https://k8s.gremlin.com/resources/gremlin-client-secret.yaml2kubectl apply -f https://k8s.gremlin.com/resources/gremlin-chao-secret.yaml
To deploy Gremlin using Helm, first add the Gremlin Helm chart repository:
1helm repo remove gremlin2helm repo add gremlin https://helm.gremlin.com
Next, create a new
gremlin namespace. The Helm chart will be deployed to this namespace:
1kubectl create namespace gremlin
Create three environment variables: one for your Gremlin team ID, another fir your Gremlin secret key, and a third for your Kubernetes cluster name. If you are using certificate-based authentication or are managing your secrets in Kubernetes, see the Chart readme for more information.
Lastly, deploy the Helm chart:
1helm install gremlin/gremlin \2 --name gremlin \3 --namespace gremlin \4 --set gremlin.secret.managed=true \5 --set gremlin.secret.type=secret \6 --set gremlin.secret.teamID=$GREMLIN_TEAM_ID \7 --set gremlin.secret.clusterID=$GREMLIN_CLUSTER_ID \8 --set gremlin.secret.teamSecret=$GREMLIN_TEAM_SECRET
The Gremlin helm chart also supports certificate-based authentication, and manually managed Kubernetes secrets, as well as several other configuration options. For the most complete, up-to-date instructions for installing from the Gremlin helm chart, see the README.
Once you select the Kubernetes objects to be targeted, select and configure your desired Gremlin attack. When the attack is run, the underlying containers within the objects selected will be impacted.
Containers share resources with their hosts. Running resource attacks on Kubernetes objects will impact the hosts where the targeted containers are running, including the host's full set of containers.
Additional installation tutorials are available in our community site.
For Microsoft Windows run the following from an elevated command prompt.
1msiexec /quiet /package https://windows.gremlin.com/installer/latest/gremlin_installer.msi
After installation, you need to authenticate the agent.
After installation, the next step is to authenticate the agent with the Gremlin Control Plane. See Authentication for more information.
For additional configuration options, such as using the Gremlin configuration file and environment variables, see Advanced Configuration.
By default on Linux, Gremlin installs a
gremlin Linux user and group, and sets the
suid bit on
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:
|GREMLIN_INSTALL_USER||The Linux user to own all file installed by Gremlin. This user is created if it does not exist|
|GREMLIN_INSTALL_GROUP||The Linux group to own all file installed by Gremlin. This group is created if it does not exist|
|GREMLIN_INSTALL_BIN_MODE||The file mode for executable files installed by Gremlin.|