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:

1. Stop Cribl LogStream.

2. 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 the cribl/bin/cribl directory if it's empty, and untar again. If you have custom functions in cribl/bin/cribl, please move them under $CRIBL_HOME/local/cribl/functions/ before untarring again.

3. 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

1. Commit and deploy your desired last version. (This will be your most recent checkpoint.)

   • Optionally, git push to your configured remote repo.

2. 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.

3. Uncompress the new LogStream version on top of the old one.

4. Restart LogStream and log back in.

5. 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.

Upgrade the Worker Nodes

These are the same basic steps as when upgrading a Standalone Instance, above:

1. Stop Cribl LogStream on each Worker Node.

2. Uncompress the new version on top of the old one.

3. Restart LogStream.

Commit and Deploy Changes on the Master Node

1. Ensure that newly upgraded Worker Nodes report to the Master with their new software version.

2. Commit and deploy the newly updated configuration only after all Workers have upgraded.

Upgrading via the UI (Beta Feature)

LogStream v.2.4.4 and higher provide streamlined options to upgrade the Master Node (or single instance), as well as Worker Nodes, directly through the UI at Settings > System > Controls > Upgrade. These streamlined controls perform the whole above sequence of stopping the LogStream server, updating the installed package, and restarting LogStream.

❗️

These options are still experimental. As the UI warns: Use them in production at your own risk, and always back up your current installation before proceeding. These options will work only if all LogStream instances (including Worker Processes) start at v.2.4.4 or higher.

Also, be aware that the Checking for upgrade status message, and its accompanying spinner, can take several minutes to resolve.

The following controls are available:

Package source: Select either CDN (the default, downloads a package directly from Cribl's content delivery network) or Path, which exposes these additional controls:

• Package location: Enter either a URL (HTTP) or a local path to the upgrade package.
• Package hash location: Enter either a URL (HTTP) or a local path to the hash that validates the package. (Supports md5 and sha256 formats).
• Save/Cancel buttons: Click Save to store the specified locations. Clicking Cancel restores the CDN package-source selection.

Upgrade/Upgrade Instance: In a Single-instance deployment, the Upgrade button is the only other control provided. In a Distributed deployment, the Upgrade button is displayed on an Upgrade Instance tab, and clicking it upgrades the Master Node. (As with manual upgrades, always upgrade the Master before upgrading the Workers.)

Upgrade Worker Groups

This second tab is displayed only in distributed deployments. Here, each Worker Group's row provides three basic controls:

Quantity %: Specify what percentage of the Group's Workers to upgrade in this operation. Enter a value less than the default 100% to perform a partial upgrade, leaving some Workers up to process data.

Upgrade: Click this button to upgrade the selected percentage of Workers.

Logs: Click to see details beyond the default Status indicator.

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, the default Group. You can edit groups.yml to move the desired Group to the top.

• 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:

1. Stop Splunk.

2. 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 the cribl/bin/cribl directory if it's empty, and untar again. If you have custom functions in cribl/bin/cribl, please move them under $CRIBL_HOME/local/cribl/functions/ before untarring again.

3. 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:

1. Stop Splunk.

2. Untar/unzip the new app version on top of the old one.

3. Convert to HF mode by running: $SPLUNK_HOME/etc/apps/cribl/bin/cribld mode-hwf

4. Restart Splunk.