Environment Variables

This is a consolidated list of environment variables available to configure Cribl Stream instances.


Distributed Deployment

You can use the following environment variables to configure your distributed Cribl Stream instance.

NamePurpose
CRIBL_DIST_MASTER_URLURL of the Leader Node. Example: CRIBL_DIST_MASTER_URL=tls://<authToken>@leader:4200. See Formatting Notes below.
CRIBL_DIST_MODEworker or master. Defaults to worker, if (and only if) CRIBL_DIST_MASTER_URL is present.
CRIBL_HOMEAuto setup on startup. Defaults to parent of bin directory.
CRIBL_CONF_DIRAuto setup on startup. Defaults to parent of bin directory.
CRIBL_NOAUTHDisables authentication. Careful here!!
CRIBL_TMP_DIRDefines the root of a temporary directory. See Formatting Notes below.
CRIBL_VOLUME_DIRSets a directory that persists modified data between different containers or ephemeral instances. When set, this environment variable overrides $CRIBL_HOME. It also creates predefined folders in the specified directory. If that directory already contains folders with those names, they will be overwritten.
CRIBL_DIST_WORKER_PROXYCommunicate to the Leader Node via a SOCKS proxy.See Formatting Notes below.
CRIBL_BOOTSTRAPQuickstart a Cribl instance by configuring this variable.
CRIBL_BOOTSTRAP_HOSTHost name for connecting to the Leader Node when setting up a new Worker Node. This variable is not related to CRIBL_BOOTSTRAP.
CRIBL_USERNAMEUsed to log in or out of Cribl.
CRIBL_PASSWORDUsed to log in or out of Cribl.
CRIBL_HOSTThe Host URL for authentication. Example: CRIBL_HOST=<url> CRIBL_USERNAME=<username> CRIBL_PASSWORD=<password> $CRIBL_HOME/bin/cribl auth login

Usage Notes

This section explains how to use certain complex environment variables.

CRIBL_DIST_MASTER_URL

Use this format:

<tls|tcp>://<authToken>@host:port?group=defaultGroup&tag=tag1&tag=tag2&tls.<tls_settings>

Here are the components:

  • group – The preferred Worker Group assignment.
  • resiliency – The preferred Leader failover mode.
  • volume– The location of the NFS directory to support Leader failover.
  • tag – A list of tags that you can use to assign (Stream, Edge) the Worker to a Worker Group.
  • tls.privKeyPath – Private Key Path.
  • tls.passphrase – Key Passphrase.
  • tls.caPath – CA Certificate Path.
  • tls.certPath – Certificate Path.
  • tls.rejectUnauthorized – Validate Client Certs. Boolean, defaults to false.
  • tls.requestCert – Authenticate Client (mutual auth). Boolean, defaults to false.
  • tls.commonNameRegex – Regex matching peer certificate > subject > common names allowed to connect. Used only if tls.requestCert is set to true.

To generate a random authentication token, leave <authToken> unchanged. You can define it to add your own token instead, but make sure it’s secure enough.

CRIBL_TMP_DIR

Sources use this variable to construct temporary directories in which to stage downloaded Parquet data. If CRIBL_TMP_DIR is not set (the default), Cribl applications create subdirectories within your operating system’s default temporary directory:

  • For Cribl Stream: <OS_default_temporary_directory>/stream/.
  • For Cribl Edge: <OS_default_temporary_directory>/edge/.

For example, on Linux, Stream’s default staging directory would be /tmp/stream/.

If you explicitly set this CRIBL_TMP_DIR environment variable, its value replaces this OS-specific default parent directory.

CRIBL_DIST_WORKER_PROXY

Use the format <socks4|socks5>://<username>:<password>@<host>:<port>. Only <host>:<port> are required.

The default protocol is socks5://, but you can specify socks4://proxyhost:port if needed.

To authenticate on a SOCKS4 proxy with username and password, use this format: username:password@proxyhost:port. The proxyhost can be a hostname, ip4, or ip6.

CRIBL_BOOTSTRAP_HOST

CRIBL_BOOTSTRAP_HOST overrides the Add/Bootstrap New Worker script generator’s default hostname.

For example, if you set CRIBL_BOOTSTRAP=myhost, then myhost will appear in the script modal’s Leader hostname/IP field, instead of the URL used in the browser.

CRIBL_BOOTSTRAP

CRIBL_BOOTSTRAP enables specifying a URL, an absolute disk file path, or a YAML string, in order to bootstrap a configuration to the $CRIBL_HOME/local directory. Cribl Stream applies this configuration only upon its first startup.

For any method, Cribl Stream expects each targeted config file to be YAML-formatted. Each file’s top-level keys should be the paths to config files inside the $CRIBL_HOME/local/... subdirectory.

Below is an example of a bootstrap file. Its output, when Cribl Stream starts, would be to create three files inside the $CRIBL_HOME/local/cribl path: inputs.yml, outputs.yml, and pipelines/route.yml.

cribl/inputs.yml:
  inputs:
    <id>:
      <config>
cribl/outputs.yml:
  outputs:
    <id>:
      <config>
cribl/pipelines/route.yml:
  id: default
  groups: {}
  comments: []
  routes:
    ...

For details about each file’s syntax, see Config Files and its child topics.

Adding a Second Leader Node

You can configure a second Leader Node via the following environment variables.

NamePurpose
CRIBL_DIST_MASTER_RESILIENCY=failoverSets the Leader’s Resiliency to Failover mode.
CRIBL_DIST_MASTER_FAILOVER_VOLUME=/tmp/sharedSets the location of the NFS directory to support Leader failover.
CRIBL_DIST_MASTER_FAILOVER_MISSED_HB_LIMITDetermines how many Lease refresh periods elapse before the standby Nodes attempt to promote themselves to primary. Cribl recommends setting this to 3.
CRIBL_DIST_MASTER_FAILOVER_PERIODDetermines how often the primary Leader refreshes its hold on the Lease file. Cribl recommends setting this to 5s.
CRIBL_INSTANCE_HOMEIn Failover mode, this variable points to the Leader Node’s root directory, as opposed to the shared volume. It is used to access $CRIBL_INSTANCE_HOME/local/_system/instance.yml (C:\Program Data\Cribl\local\_system.yml for Cribl Edge on Windows). Outside of Failover mode, it’s the same value as CRIBL_CONF_DIR.

GitOps

Cribl Stream provides the following environment variables to facilitate GitOps.

Bootstrap Variables

NamePurpose
CRIBL_GIT_REMOTELocation of the remote repo to track. Can contain username and password for HTTPS auth.
GIT_SSH / GIT_SSH_COMMANDSee Git’s documentation.
CRIBL_GIT_BRANCHGit ref (branch, tag, commit) to track/check out.
CRIBL_GIT_AUTHOne of: none, basic, or ssh.
CRIBL_GIT_USERUsed for basic auth.
CRIBL_GIT_PASSWORDUsed for basic auth.
CRIBL_GIT_OPSOne of: push to enable the GitOps push workflow, or none to disable GitOps.
CRIBL_GIT_SSH_KEYContent of the SSH key used to access git remote.
CRIBL_GIT_STRICT_HOST_KEY_CHECKINGBoolean flag sets whether to check the host key strictly.
CRIBL_INTERACTIVEControls whether git commands called by Cribl CLI at startup are interactive.

Internal Environment Variables

Cribl Stream uses the following variables internally.

NamePurpose
CRIBL_AUTO_PORTSWhen set to true, allows the Cribl process to listen to the first open port, if the designated API port is taken.
CRIBL_EDGEWhen set to any value, runs this command at container start: cribl mode‑edge ‑H 0.0.0.0. This launches the instance as an Edge Node, listening on a Host at 0.0.0.0.
CRIBL_EDGE_FS_ROOTLocation of the host OS filesystem when mounting in a container. Defaults to /hostfs.
CRIBL_WORKER_IDPassed to Worker processes.
CRIBL_GROUP_IDPassed to ConfigHelper processes to identify Worker Groups.
CRIBL_K8S_FOOTGUNSet to true to enable resource-intensive, potentially risky modes of the Kubernetes Metrics and Kubernetes Logs Sources.
CRIBL_K8S_PODSets the name of the Kubernetes Pod in which Cribl Edge is deployed.
CRIBL_K8S_TLS_REJECT_UNAUTHORIZEDSet to 0 to disable certification validation when connecting to the Kubernetes APIs. When you disable this environment variable, all Kubernetes features (including Metadata, Metrics, Logs, and AppScope metadata) will tolerate invalid TLS certificates (i.e., expired, self-signed, etc.) when connecting to the Kubernetes APIs.
CRIBL_ROLEControls the behavior of a Cribl subprocess, e.g., LEADER, WORKER, CONFIG_HELPER.
CRIBL_SERVICESet to 1 when using systemd to start Cribl at boot time.
CRIBL_SERVICE_NAMESet to cribl when using systemd to start Cribl at boot time.
CRIBL_SERVICEACCOUNT_PATHPath to the ServiceAccount to use to query the Kubernetes API. Defaults to /var/run/secrets/kubernetes.io/serviceaccount.
CRIBL_SPOOL_DIRSpecifies the base path where events from various Sources and Destinations are spooled. Defaults to $CRIBL_HOME/state/spool or $CRIBL_VOLUME_DIR/state/spool.