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.