Browse the docs
Command line
Environment variables and exit codes
Reference for the CRUNU_ variables that configure the agent, how it finds a CI provider's OIDC token automatically, and what each crunu exit code means.
Last updated
On this page
This page lists the environment variables crunu reads and the exit codes it returns. Use the exit codes in scripts and CI steps to tell a revoked token from a network problem or a failed signature check.
Environment variables
| Variable | Meaning |
|---|---|
CRUNU_SERVER | Server address for crunu enroll and crunu login, instead of --server. Required in service token mode. |
CRUNU_TOKEN | A service token crunu_svc_…. Turns on service token mode for run, pull, status, renew and revoke-self. |
CRUNU_OIDC_TOKEN | The CI provider's OIDC token, given explicitly. Otherwise crunu finds it itself, as described below. |
CRUNU_ID_TOKEN | The GitLab CI ID token, when the job requests one under that name. |
CRUNU_ENROLL_CODE | The enrollment code for crunu enroll, instead of stdin. A code is never accepted as an argument. |
CRUNU_ENV | The default environment for run and pull as project/environment, when --env isn't given. |
CRUNU_SOCKET | Path to the service socket: where crunu daemon listens and where run, pull, status and renew connect. With it set, a person's session isn't used. |
CRUNU_STATE_DIR | State directory instead of /var/lib/crunu, for a service in an unprivileged environment. |
CRUNU_LOG | info by default, or debug for a detailed service log. Secret values never appear in the log at any level. |
XDG_CONFIG_HOME, XDG_RUNTIME_DIR | Directories for person mode: sign-in data and the session socket. |
crunu run never passes its own credentials to the program it starts: CRUNU_TOKEN, CRUNU_OIDC_TOKEN, CRUNU_ID_TOKEN and CRUNU_ENROLL_CODE. That holds with the default allowlist and with --inherit-env. Variables of CI providers, such as BITBUCKET_STEP_OIDC_TOKEN or ACTIONS_ID_TOKEN_REQUEST_*, are passed as they are with --inherit-env, because the program may need them for other clouds.
How crunu finds the CI's OIDC token
If a service token has a CI binding, the server accepts it only together with a JWT from the CI provider. crunu looks for that JWT in this order:
- Explicit:
CRUNU_OIDC_TOKEN. - Bitbucket Pipelines:
BITBUCKET_STEP_OIDC_TOKEN, available in a step with OIDC turned on. - GitHub Actions: a request to
ACTIONS_ID_TOKEN_REQUEST_URLusingACTIONS_ID_TOKEN_REQUEST_TOKEN, with the server address as the audience. The job needs theid-token: writepermission. - GitLab CI: the
CRUNU_ID_TOKENvariable, declared underid_tokenswith the server address asaud.
If none is found, no OIDC token is sent. A service token without a CI binding doesn't need one. See Bind a service token to CI with OIDC.
Exit codes
| Code | Meaning | When you see it |
|---|---|---|
| 0 | Success | |
| 1 | Error | A network or file error, a bad server response, an environment that isn't granted, a crunu older than the server's minimum, state.json that can't be written, or crunu pull without consent to write a network-restricted environment |
| 2 | Invalid arguments | Wrong flags, a damaged enrollment code or token, no server address |
| 3 | Not enrolled or not signed in | run, pull, status, renew, revoke-self or daemon without an enrollment or sign-in. Also: enrollment didn't finish, your keys are locked, or the server didn't accept the service token |
| 4 | Access revoked or lease expired | The service got a revocation, the lease ran out without a connection, or the token was revoked |
| 5 | No connection and no valid verified state | The service doesn't answer or has no state yet, or the machine is waiting for approval |
| 6 | Signature or certificate check failed | The service is in an alert state, or a document from the server failed verification in token or person mode. The data may have been tampered with. |
| 7 | Not served to this address | run or pull with a named environment that the server doesn't serve to the request's address, because of a network rule or because the server couldn't determine the address |
crunu run also returns the exit code of the program it ran. A program ended by a signal gives 128 plus the signal number. 127 means the command wasn't found, and 126 that it couldn't be started.
Reading the codes in practice
- 3 in CI means there is no usable sign-in:
CRUNU_TOKENisn't set for the step, or the server didn't accept the token, for example because it belongs to a different server thanCRUNU_SERVER. - 4 means access ended. A machine needs to be resumed or enrolled again. A service token needs to be resumed or replaced.
- 5 on a new machine can mean it's still waiting for approval. Compare the fingerprint and approve it in the web app.
- 6 needs attention. Don't work around it. If you didn't just restore the server from a backup, find out why the server returns data that fails verification. After a restore you made yourself, reset the agent's memory of the server, as described in Backups and restore.
- 7 means the request came from outside the environment's allowed networks. Check the address in the message against the rule in Networks.
Certificates and connectivity
An unverified server certificate counts as no connection. run, pull and status with CRUNU_TOKEN, as well as renew and revoke-self, then exit with 5. The machine service keeps serving its last verified state until the lease ends. enroll, login, unlock and self-update exit with 1 in the same situation.