Configuring the Gremlin Daemon

You can configure the Gremlin daemon either via environment variables or a configuration file.

Using Environment Variables

The daemon supports the following environment variables:

Variable Description
GREMLIN_TEAM_ID Your Team ID (required for authentication)
GREMLIN_TEAM_PRIVATE_KEY_OR_FILE Your PEM-encoded private key or path/filename to a file containing the private key (required for authentication)
GREMLIN_TEAM_CERTIFICATE_OR_FILE The PEM-encoded public-key certificate or path/filename to the file containing your PEM-encoded public-key certificate (required for authentication)
GREMLIN_TEAM_SECRET Your Team Secret
GREMLIN_IDENTIFIER Custom name to assign to this client (default is the host’s IP address)
GREMLIN_CLIENT_TAGS Comma-separated list of custom tags to assign to this client (e.g. GREMLIN_CLIENT_TAGS="zone=us-east1,role=mysql,foo=bar")
GREMLIN_INIT_OPTS Tags to associate to this client if using secret based auth (e.g. GREMLIN_INIT_OPTS="--tag service=my-api --tag service-version=1.0.0 --tag service-type=http")
GREMLIN_CONFIG_SERVICE Service or group tag
GREMLIN_CONFIG_REGION Region or datacenter
GREMLIN_CONFIG_ZONE Availability zone
GREMLIN_CONFIG_PUBLIC_IP Public IP address
GREMLIN_CONFIG_PUBLIC_HOSTNAME Public hostname
GREMLIN_CONFIG_LOCAL_IP Internal IP address
GREMLIN_CONFIG_LOCAL_HOSTNAME Internal hostname

In addition, the following standard Linux environment variables allow proxy configuration:

Environment variable Description
http_proxy In the form http[s]://[username:passsword@]address:port
https_proxy In the form http[s]://[username:passsword@]address:port

Using the Configuration File

To configure the daemon using a configuration file instead, create a file, /etc/default/gremlind.

NOTE: In previous versions of Gremlin (gremlind <= 2.8.28), all variables below should be preceeded by an export when running on Upstart and SysvInit.

#==============================#
# Gremlin Daemon Configuration #
#==============================#

# This file is used to expose configuration to the Gremlin daemon process (`gremlind`)

# When the Gremlin daemon starts, it will automatically issue a `gremlin init` command to
# register this machine with the Gremlin Control Plane. This requires the following team and
# secret values to be set. If these values are not set, the Gremlin daemon will continue to
# start up. However `gremlin init` will need to be run separately before attacks can be run.
#GREMLIN_TEAM_ID=
#GREMLIN_TEAM_PRIVATE_KEY_OR_FILE=
#GREMLIN_TEAM_CERTIFICATE_OR_FILE=

# Supply extra options to `gremlin init` via this variable
# Example: `GREMLIN_INIT_OPTS=--tag service=api` (see https://help.gremlin.com/configuration)
#GREMLIN_INIT_OPTS=

# To use Gremlin with an http proxy, provide the proxy information. Note that all of Gremlin's
# communication with the Gremlin Control Plane is via outbound HTTPs, therefore `https_proxy`
# (not `http_proxy` should be used in most cases)
# Example: https_proxy=https://proxyuser:proxypass@10.0.0.3:3218
#https_proxy=

# Any additional Gremlin Daemon variables (such as GREMLIN_IDENTIFIER) may be defined here
# (see https://help.gremlin.com/configuration)

You can set any of the environment variables listed in the previous section in the configuration file.

Signature-based Authentication

The Gremlin daemon (gremlind) connects to the Gremlin Control plane and waits for attack orders from you. When it receives attack orders, it uses the CLI (gremlin) to run the attack.

To connect gremlind to the Control Plane, you need your client credentials. (This is NOT the same as the email/password credentials you use to access the Gremlin Web App.) Read Client Auth to see how to find your client credentials in the Web App.

With the credentials in hand, it’s time to configure the daemon.

First, configure your Team ID:

$ echo 'GREMLIN_TEAM_ID="<YOUR_TEAM_ID>"' >> /etc/default/gremlind

Then, add your certificate and private key to two separate files in the gremlin user’s home directory (e.g., /var/lib/gremlin/gremlin.pub_cert.pem and /var/lib/gremlin/gremlin.priv_key.pem), and configure the client with them either via configuration file:

$ echo 'GREMLIN_TEAM_CERTIFICATE_OR_FILE="file:///var/lib/gremlin/gremlin.pub_cert.pem"' >> /etc/default/gremlind
$ echo 'GREMLIN_TEAM_PRIVATE_KEY_OR_FILE="file:///var/lib/gremlin/gremlin.priv_key.pem"' >> /etc/default/gremlind

Then set the ownership and restrict the permissions on both files:

sudo chown gremlin:gremlin /var/lib/gremlin/gremlin.p*
sudo chmod 600 /var/lib/gremlin/gremlin.p*

Finally, reload the Gremlin daemon:

sudo systemctl reload gremlind

Secret-based Authentication and gremlin init

For secret-based authentication, gremlin init command is used to configure secrets. This command also lets you configure tags. Our init scripts run gremlin init before starting the daemon and expect the following vars to be set.

Export your Team ID and Secret as environment variables or add them to /etc/default/gremlind:

$ export GREMLIN_TEAM_ID="<YOUR_TEAM_ID>"
$ export GREMLIN_TEAM_SECRET="<YOUR_TEAM_SECRET>"

Or

$ echo 'GREMLIN_TEAM_ID="<YOUR_TEAM_ID>"' >> /etc/default/gremlind
$ echo 'GREMLIN_TEAM_SECRET="<YOUR_TEAM_SECRET>"' >> /etc/default/gremlind

To find your Team ID, sign in to the Gremlin Web App, go to Company Settings, and click your Team.

You cannot download your Team Secret from the Gremlin Web App. Get the secret from another Gremlin daemon that’s configured with it, or ask a teammate. (If no one knows the Secret and no active clients are using it, use signature-based auth instead.)

If you need to run gremlin init for any reason, you can run it like below passing in any tags you want to associate with this client:

$ gremlin init --tag service=my-api --tag service-version=1.0.0 --tag service-type=http

If secret-based auth is successful, the client will create a hidden file, .credentials in the gremlin user’s home directory. This file contains an authentication token that gremlind uses to connect to the Gremlin Control Plane.