Authenticating the Gremlin Agent
Supported platforms:
Before you can start using Gremlin, you need to authenticate the Agent with your Gremlin team. This documentation page covers the various methods of authenticating the Agent.
Agent authentication methods
There are three methods for authenticating clients with Gremlin:
- (Recommended) The Client configuration file is a pre-generated configuration file containing everything needed to authenticate a Gremlin Agent, including a team ID.
- Signature authentication requires supplying a public and private ECDSA certificate-key pair to Gremlin clients. This certificate pair is created from the Gremlin web app, and can be downloaded again at any time, but expires 1 year from the date of creation.
- Secret authentication involves a secret string value that Gremlin clients use to prove their identity. Secrets are created from the Gremlin UI, and are like passwords. They can never be retrieved from Gremlin after creation; they can only be reset.
The recommended method is using the client configuration file, but the other authentication methods are available for teams that wish to use them.
Client Configuration File
Gremlin automatically generates a pre-formatted configuration file containing everything you need to authenticate, including your team ID. It uses signature-based authentication to generate a private and public key pair and embeds those keys into a YAML file, which you can use to authenticate your Agents.
To create a client configuration file:
- Access the Team Settings page in the Gremlin web app.
- Click the Configuration tab.
- On the Client Configuration File line, click Download to download the file. You'll receive a file named
config.yaml. - Optionally, make any additional configurations to the
config.yamlfile. - Copy the contents of the file into the
/etc/gremlin/config.yamlfile (or simply overwrite the existing file). - Restart the
gremlindservice.
Signature-based authentication
Download a certificate pair
To generate a certificate pair:
- Navigate to Team Settings in the Gremlin web app.
- Under Team Settings, click Details.
- On the Certificates line, click Create to create a new certificate (skip this step if your team already has a valid certificate).
- Click Download to download your certificates. The downloaded zip file contains both a public certificate file and a matching private key file.
- Unzip the file, then read the next section to configure the clients.
Configure clients with certificate pair
To configure Gremlin clients for signature authentication, provide your team certificate and private key (or paths to their files) to the agent using one of the agent configuration methods.
Configuration file
Set team_id, team_certificate, and team_ private_ key in your config.yaml:
Environment variables
Pass the environment variables GREMLIN_TEAM_ID, GREMLIN_TEAM_CERTIFICATE_OR_FILE, and GREMLIN_TEAM_PRIVATE_KEY_OR_FILE directly to the gremlind process:
Rotating expiring certificates
All certificates expire one year after creation. Before the expiration date, you must create a new certificate, reconfigure all clients with it, and delete the old certificate. As the expiration date draws near, the Gremlin web app will display a warning about it.
To create a new certificate, simply click the Create New button next to your existing certificate. Now that you have two certificates, you cannot download the older certificate (though all clients still configured with it may still use it to authenticate), and you cannot create a third certificate. Make sure you move all clients to the new certificate before the old one expires.
Secret-based authentication
Secret-based authentication uses password-like secret strings to authenticate Gremlin clients.
Create a secret
To create a new secret:
- Navigate to Team Settings in the Gremlin web app.
- Click on the Configuration tab.
- On the Secret Key line, click Create to create a new secret key, then read the next section to configure your Agents.
Configure clients with secret
To configure Gremlin clients for secret authentication, pass the secret to the Gremlin agent using one of the agent configuration methods.
Configuration file
Set team_id and team_secret in your config.yaml file:
Environment variables
Pass GREMLIN_TEAM_ID and GREMLIN_TEAM_SECRET directly to the gremlind process:
Using the Gremlin CLI
Alternatively, you can set up secret authentication by running gremlin init:
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. To learn more, see Gremlin .credentials file.
Verifying Gremlin Agent authentication
To verify that your Gremlin Agents are connected to the Gremlin Control Plane, open the Agents page in the Gremlin web app. If your system doesn't appear there, the next step is to ensure that the Gremlin Agent is running.
For Linux hosts, run the following command:
For Windows hosts, run the following command:
The output from either of these commands should show the service as Running.
Next, use gremlin check auth to check the Gremlin Agent's authentication status:
If the Gremlin Agent authenticated successfully, the output will be similar to the following:
If not, the output will explain why the Gremlin Agent was unable to authenticate:
If you're having trouble authenticating, see the troubleshooting section below.
Releasing client certificates
There are three different methods you can use to release client certificates:
- Web app - From the Agents page in the Gremlin web app, you can release a client's license by clicking Deactivate. This will prevent the host from being used in future experiments until it is reactivated.
- Gremlin Logout command - From the host, you can log out of the client using the command
gremlin logout. This method removes the authorization from our server while letting you keep the binaries in place for future use. - Uninstalling Gremlin client from the host - If you're sure you won't want to register this host in the future, you can uninstall the Gremlin client to release its license.
Once any of these options have been performed, it may take a few minutes for new clients to use the newly released entitlements. You can view the details of which teams have active clients for a given month by navigating to Gremlin Reports within the Gremlin web app. The Active Clients metric on this page is cumulative for any active clients that may have authenticated.
Gremlin .credentials file
When secret-based authentication is used and the Gremlin agent successfully authenticates against the Gremlin Control Plane, the Gremlin agent creates a new file named /var/lib/gremlin/.credentials (C:\ProgramData\Gremlin\Agent\.credentials on a Windows-based install). This file stores temporary session and authorization data. Sessions are valid for twelve hours. After twelve hours (or if the session is ever invalidated), the agent creates a new .credentials file in the same location. It also assigns the file to user ID and group ID (uid:gid) gremlin:gremlin and sets the file's permissions to 660.
Note that this file isn't created when using certificate-based authentication.
Troubleshooting
If you're having problems authenticating the agent, see the Authentication FAQ in the Gremlin Knowledge Base.
Configuring Gremlin
Once you've successfully authenticated, continue to Configuring Gremlin to complete Agent setup.