This page outlines how to upgrade Cribl LogStream's Single-Instance or Distributed Deployment packages along one of the following supported upgrade paths:
- v2.x ==> v2.x
- v1.7.x/v2.0.x ==> v2.x.x
- v1.6.x or below ==> v1.7.x ==> v2.x.x
See notes on Upgrading to LogStream 2.3 below.
LogStream does not support direct upgrades from a Beta to a GA version. To get the GA version running, you must perform a new install.
Standalone/Single-Instance
This path requires upgrading only the single/standalone node:
-
Stop Cribl LogStream.
-
Uncompress the new version on top of the old one.
On some Linux systems,
tar
might complain with:cribl/bin/cribl: Cannot open: File exists
. In this case, please remove thecribl/bin/cribl
directory if it's empty, and untar again. If you have custom functions incribl/bin/cribl
, please move them under$CRIBL_HOME/local/cribl/functions/
before untarring again. -
Restart LogStream.
Distributed Deployment
For a distributed deployment, the order of upgrade is: Upgrade first the Master Node, then upgrade the Worker Nodes, then commit and deploy the changes on the Master.
Upgrade the Master Node
-
Commit and deploy your desired last version. (This will be your most recent checkpoint.)
- Optionally,
git push
to your configured remote repo.
- Optionally,
-
Stop Cribl LogStream.
-
Optional but recommended: Back up the entire
$CRIBL_HOME
directory. -
Optional: Check that the Worker Nodes are still functioning as expected. In absence of the Master Node, they should continue to work with their last deployed configurations.
-
-
Uncompress the new LogStream version on top of the old one.
-
Restart LogStream and log back in.
-
Wait for all the Worker Nodes to report to the Master, and ensure that they are correctly reporting the last committed configuration version.
Workers' UI will not be available until the Worker version has been upgraded to match the version on the Master. Errors like those below will appear until the Worker nodes are upgraded.


Worker Node version mismatch
Upgrade the Worker Nodes
These are the same basic steps as when upgrading a Standalone Instance, above:
-
Stop Cribl LogStream on each Worker Node.
-
Uncompress the new version on top of the old one.
-
Restart LogStream.
Commit and Deploy Changes on the Master Node
-
Ensure that newly upgraded Worker Nodes report to the Master with their new software version.
-
Commit and deploy the newly updated configuration only after all Workers have upgraded.


Post-2.1.4 upgrade to 2.2
Upgrading to LogStream 2.3
As of version 2.3, LogStream Free and One licenses are permanent, but they enforce certain restrictions that especially affect distributed deployments:
-
Even if you have more than one Worker Group defined, only one Worker Group will be visible and usable.
- This will be the first Group listed in
$CRIBL_HOME/local/cribl/groups.yml
– typically, thedefault
Group. You can editgroups.yml
to move the desired Group to the top.
- This will be the first Group listed in
-
Your cluster will be limited to 10 Worker Processes across all Worker Nodes.
- LogStream will balance (or rebalance) these Processes as evenly as possible across the Worker Nodes.
-
Authentication will fall back to local authorization. You will not be able to authenticate via Splunk, LDAP, or SSO/OpenID.
-
Git Push to remote repos will not be supported through the product.
If you are upgrading LogStream Free or LogStream One from version 2.2.x or lower, these changes might require you to adjust your existing configuration and/or workflows.
See Licensing for details on all current license options.
As of LogStream 2.3, licenses no longer need to be deployed directly to Worker Groups. The Master will push license information down to Worker Groups as part of the heartbeat.
Splunk App Package Upgrade Steps
See Deprecation note for v.2.1.
Follow these steps to upgrade from v.1.7, or higher, of the Cribl App for Splunk:
-
Stop Splunk.
-
Untar/unzip the new app version on top of the old one.
On some Linux systems,
tar
might complain with:cribl/bin/cribl: Cannot open: File exists
. In this case, please remove thecribl/bin/cribl
directory if it's empty, and untar again. If you have custom functions incribl/bin/cribl
, please move them under$CRIBL_HOME/local/cribl/functions/
before untarring again. -
Restart Splunk.
Upgrading from Splunk App v.1.6 (or Lower)
As of v.1.7, contrary to prior versions, Cribl's Splunk App package defaults to Search Head Mode. If you have v.1.6 or earlier deployed as a Heavy Forwarder app, upgrading requires an extra step to restore this setting:
-
Stop Splunk.
-
Untar/unzip the new app version on top of the old one.
-
Convert to HF mode by running:
$SPLUNK_HOME/etc/apps/cribl/bin/cribld mode-hwf
-
Restart Splunk.
Updated 3 months ago