Troubleshooting FAQs

Why are my Gremlin Agents not showing up in the Gremlin web app?

Log into the host where the Agent is installed and run gremlin check auth to see the possible causes. If you're using secret-based authentication, use gremlin init to enter your team ID and secret key again. If you're using signature-based authentication, make sure that the Gremlin Agent can read your certificates and that the file paths are correct. Then, restart the Gremlin Agent using sudo service gremlind restart or sudo systemctl restart gremlind.

Can I create one certificate for my whole Company?

No. Every Team within the Company must use its own certificate.

Can I create one certificate per Gremlin client?

No. Every Gremlin client within a Team uses the same shared certificate. When that certificate is about to expire, you must create a new certificate. For a brief time, you may have some clients configured with the older certificate and some with the newer one. But before the older certificate expires, you must move all clients to the newer certificate.

Is it OK for some clients to use secret-based auth while others use signature-based auth?

Yes, but if you are still using secret-based auth, you should move all clients to signature-based auth as soon as possible.

What does signature-based authentication have to do with SSL?

Nothing. Signature-based auth is independent of the SSL layer, but both are important. The purpose of SSL is to 1) encrypt the client-to-server connection, and 2) let the client authenticate the server (that is, the Gremlin Control Plane). Signature-based authentication lets the Gremlin Control Plane authenticate the client.

Before the client connects to the backend, it signs the payload using $GREMLIN_TEAM_PRIVATE_KEY_OR_FILE. Then it initiates an SSL handshake with the backend, verifying the backend's SSL certificate in the process. After the SSL tunnel has been established the backend verifies that the payload was signed by a Gremlin-issued key.

What cryptographic standard does signature-based authentication use?

It uses 256-bit ECDSA (prime256v1) for keys, with SHA 256-bit ECDSA for signatures. The recommended lifespan for anything secured by these standards is two years, but we are intentionally being more conservative, opting instead for one-year expiration.