Infrastructure Layer

Advanced configuration

You can configure the Gremlin Agent with a configuration file or with environment variables. We recommend using the configuration file unless you can't. This is because the Gremlin software is comprised of two processes, gremlin and gremlind and configuration via environment variables requires that they be passed to both processes.

Using the configuration file

Gremlin's configuration values can be stored in config.yaml (on Linux, this file lives in /etc/gremlin). By default, Gremlin ships with a commented-out version of this file. Use the comments or the example below to set up your configuration.

Any changes to `config.yaml` require a restart of the `gremlind` service

shell

1# restart gremlind on Linux with systemd
2sudo systemctl restart gremlind

Accepted variables

Variable	Description
`identifier`	a string that uniquely identifies a gremlin installation (defaults to the hosts IP address)
`team_id`	the ID of your Gremlin team
`tags`	key-value pairs that help you target this machine during attacks
`team_secret`	the secret value (used by secret authentication only)
`team_certificate`	the public portion of the certificate-pair (required for signature auth only)
`team_private_key`	the private portion of the certificate-pair (required for signature auth only)
`https_proxy`	the url of a proxy in between Gremlin and api.gremlin.com
`ssl_cert_file`	the ssl certificate for your https proxy
`push_metrics`	set to `false` if you would like to disable system metrics used for attack charting (defaults to `true`)

Example: config.yaml

yaml

1## Gremlin Identifier; uniquely identifies this machine with Gremlin
2## (can also set with GREMLIN_IDENTIFIER environment variable)
3identifier: gremlin-01
4
5## Gremlin Team Id; you can find this value at https://app.gremlin.com/settings/teams
6## (can also be set with GREMLIN_TEAM_ID environment variable)
7team_id: 11111111-1111-1111-1111-111111111111
8
9## Gremlin Client Tags; Tag your machine with key-value pairs that help you target this machine during attacks
10## (can also set with GREMLIN_CLIENT_TAGS environment variable)
11tags:
12  service: pet-store
13  interface: http
14
15## Gremlin Team Secret, should not be set when using `team_certificate`+`team_private_key`
16## (can also set with GREMLIN_TEAM_SECRET environment variable)
17#team_secret: 11111111-1111-1111-1111-111111111111
18
19## Gremlin Team Certificate, should not be set when using `team_secret`.
20## Paste certificate content here or a paths to the file (prefixed with `file://`)
21## (can also set with GREMLIN_TEAM_CERTIFICATE_OR_FILE environment variable)
22team_certificate: |
23  -----BEGIN CERTIFICATE-----
24  1111111111111111111111111111111111111111111111111111111111111111
25  1111111111111111111111111111111111111111111111111111111111111111
26  1111111111111111111111111111111111111111111111111111111111111111
27  1111111111111111111111111111111111111111111111111111111111111111
28  1111111111111111111111111111111111111111111111111111111111111111
29  1111111111111111111111111111111111111111111111111111111111111111
30  1111111111111111111111111111111111111111111111111111111111111111
31  1111111111111111111111111111111111111111111111111111111111111111
32  1111111111111111111111111111111111111111111111111111111111111111
33  11111111111111111111111111111111111111111111111111==
34  -----END CERTIFICATE-----
35
36## Gremlin Team Certificate, should not be set when using `team_secret`.
37## Paste certificate content here or a paths to the file (prefixed with `file://`)
38## (can also set with GREMLIN_TEAM_PRIVATE_KEY_OR_FILE environment variable)
39team_private_key: file:///var/lib/gremlin/key.pem
40
41## HTTPS Proxy, set this when routing outbound Gremlin HTTPS traffic through a proxy
42## (can also set with HTTPS_PROXY or https_proxy environment variables)
43https_proxy: https://localhost:3128
44
45## SSL CERT FILE, set this when using a https proxy with a self-signed certificate
46## Paste certificate content here or a paths to the file (prefixed with `file://`)
47## (can also set with SSL_CERT_FILE environment variable)
48ssl_cert_file: file:///var/lib/gremlin/proxy_cert.pem
49
50## Push Metrics, tell Gremlin whether to send system metrics to the control plane for charting the impact of attacks in
51## real time. Metrics are only collected during active attacks, and only metrics relevant to the attack are collected.
52## defaults to `true`
53## (can also set with PUSH_METRICS environment variable)
54push_metrics: true
55
56## Collect Process Data, data about running processes is sent to Gremlin for service discovery.
57# defaults to `false`
58collect_processes: true

Using environment variables

The daemon supports the following environment variables:

Environment Variable	Description
`GREMLIN_TEAM_ID`	Your Team ID (required for authentication)
`GREMLIN_TEAM_SECRET`	Your Team Secret (should only require secret or PEM certificates, not both)
`GREMLIN_TEAM_PRIVATE_KEY_OR_FILE`	Your PEM-encoded private key or path to a file containing the private key (required for authentication). Paths should be prefixed with `file://` (ex: `file:///var/lib/gremlin/key.pem`)
`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). Paths should be prefixed with `file://` (ex: `file:///var/lib/gremlin/cert.pem`)
`GREMLIN_IDENTIFIER`	Custom name for this client (default as the host's IP address)
`GREMLIN_CLIENT_TAGS`	Comma-separated list of custom tags to assign to this client. For example: `GREMLIN_CLIENT_TAGS="zone=us-east1,role=mysql,foo=bar"`

The following are optional environment variables that may be required in Docker containerized deployments:

Environment Variable	Description
`GREMLIN_BYPASS_USERNS_REMAP`	Indicates to run the Gremlin Daemon on the same Docker namespace as the host. By default, Gremlin does not launch with a namespace defined. To set this variable, change the value to `1`
`GREMLIN_DOCKER_IMAGE`	Indicates the location and version of the Gremlin Docker image to use. This variable can be used to indicate an internal repository. For example: `GREMLIN_DOCKER_IMAGE=registry.hub.docker.com/gremlin/gremlin:latest`
`net=host`	Indicates to run the Gremlin Daemon to use the host network. By default, Gremlin network attacks will not affect the host network for containerized environments.
`pid=host`	Indicates to run the Gremlin Daemon to affect host processes. By default, Gremlin process killer will not affect host processes for containerized environments.

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

Environment Variable	Description
`https_proxy`	In the form `http[s]://[username:password@]address:port`
`SSL_CERT_FILE`	Indicates location of the proxy certificates used to authenticate traffic with the proxy. For Example: `SSL_CERT_FILE=/etc/ssl/certs/ca-example.crt`

Passing environment variables to Systemd or SysV

While configuring the daemon with config.yaml is recommended, process managers like systemd and sysvinit can pass environment variables directly to the daemon process from /etc/default/gremlind. Your installation comes with an example of this file at /etc/default/gremlind.example

shell

1# Gremlin Identifier; uniquely identifies this machine with Gremlin
2GREMLIN_IDENTIFIER=gremlin-01
3
4# Gremlin Team ID; you can find this value at https://app.gremlin.com/settings/teams
5GREMLIN_TEAM_ID=11111111-1111-1111-1111-111111111111
6
7# `gremlin init` will run automatically when the gremlind service starts.
8# Supply extra options to `gremlin init` via this variable
9GREMLIN_INIT_OPTS="--tag service=pet-store --tag interface=http"
10
11# Gremlin Team Secret, should not be set when using `team_certificate`+`team_private_key`
12GREMLIN_TEAM_SECRET=11111111-1111-1111-1111-111111111111

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