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 (deprecated in favor of certificate+private key, i.e. signature-based auth) |
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_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:
#==============================#
# Gremlin Daemon Configuration #
#==============================#
# This file is used to expose configuration to the Gremlin daemon process (`gremlind`)
# NOTE: Some process managers such as sysvinit may require these variables to be preceded
# by `export`
# 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 (DEPRECATED)¶
Before signature-based auth, there was secret-based auth. Gremlin stopped issuing new Secrets in July 2018, but if you signed up for Gremlin before then, your clients can still use your pre-existing Secret to authenticate. You should move all clients to signature-based auth as soon as possible, but in the interim, the following instructions can help you configure secret-based auth.
You must use the gremlin init command to configure Secrets. This command also lets you configure tags. (Gremlin also deprecated gremlin init in July 2018.)
First, export your Team ID and Secret as environment variables:
$ export GREMLIN_TEAM_ID="<YOUR_TEAM_ID>"
$ export GREMLIN_TEAM_SECRET="<YOUR_TEAM_SECRET>"
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.)
Finally, run gremlin init, 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.