These docs are for Cribl Stream 4.14 and are no longer actively maintained.

See the latest version (4.20).

This page outlines how you can upgrade a Cribl Stream single-instance or distributed deployment along one of these supported upgrade paths, which apply to UI-based upgrades:

If you’re upgrading Worker Nodes directly from the command line, you don’t have to worry about a version upgrade path. There are no restrictions on the versions you can upgrade from or to.

Considerations ​

Here are some considerations to look at before you upgrade.

Manual Upgrade Required for Hybrid and On-Prem Deployments ​

Whether your upgrade is automatic or manual depends on your deployment type:

• For Cribl.Cloud: Cribl Stream automatically upgrades the Leader Node in Cribl.Cloud deployments.
• For customer-managed (hybrid) Cribl.Cloud Worker Groups, and all on-prem deployments: Requires manual upgrades for Worker Groups and distributed instances.

Maintaining compatible versions across all Cribl Stream deployments–whether in the cloud, hybrid, or on-premise–is crucial for optimal performance and stability.

Supported Version Differences Between Leader and Workers ​

Cribl strongly recommends keeping Leader Nodes and Worker Groups/instances on the same version for the best experience and to ensure access to all features. Upgrading a Leader Node to a newer version may surface configuration options in the UI that will not be functional until you upgrade the connected Workers to the same version.

However, this section outlines the supported version differences between Leader Nodes and Worker Groups (or distributed instances) across all deployment types–including Cribl.Cloud, hybrid, and on-premise. Following these guidelines is essential to ensure functionality, compatibility, and full support coverage:

• Patch Versions: Cribl supports Leaders and Worker Groups or distributed instances on different patch versions within the same minor version. For example, a Worker Group on 4.5.0 and Leader on 4.5.1.
• Minor Versions: Cribl supports Worker Groups or distributed instances that are one minor version behind the Leader Node. For example, a Worker Group on 4.5.1 and a Leader is on 4.6.0.

Do not upgrade Workers to a newer version than the Leader Node.

Cribl does not support version differences greater than one minor version, which may lead to unpredictable behavior and compatibility issues. Support requests for configurations exceeding this limit will require updating to compatible versions.

Requirements for Specific Version Upgrades ​

• Upgrading from a pre-GA candidate: Cribl Stream does not support direct upgrades from any pre-GA version (such as a Cribl-provided test candidate) to a GA version. To get the GA version running, you must perform a new install.

• Upgrading your Leader to 4.0 and newer: Before upgrading, see Persisting Socket Connections to prepare the host to keep communications open from Worker Nodes.

• Upgrading to 3.5.4 or newer: All Worker Nodes will need to be on the same version as the Leader. Leaders running v.3.5.4 and newer test whether Worker Nodes are running a compatible version before deploying configs that could break Worker Nodes’ data flow. The Leader will prompt you to upgrade these Nodes as needed.

  Version 3.5.4 was also a compatibility breakpoint for the Cribl HTTP Source and Destination, and for the Cribl TCP Source and Destination. When running on Cribl Stream 3.5.4 and newer, these two Sources can send data only to Nodes running v.3.5.4 and newer, and these two Destinations can receive data only from Nodes running v.3.5.4 and newer. When running on Cribl Stream 3.5.3 and older, these four integrations can similarly interoperate only with Nodes running v.3.5.3 and older.

• Upgrade to v.4.3.x using Leader-Managed Upgrades for Worker Nodes: If a Leader is on Cribl Stream v.4.3.x, you should upgrade all Worker Nodes to v.4.3.x before making any config changes or committing and deploying to the Nodes. If you have already committed and deployed to Nodes that are on a version older than 4.3.0, and the Leader is on v.4.3.x, you won’t be able to upgrade the Nodes. In this case, there are three workaround options:

  • Revert and redeploy the last commit, then upgrade the Worker Nodes and deploy the most up-to-date changes; or
  • Upgrade the Worker Nodes via command line or script; or
  • Downgrade the Leader to v.4.2.2, and wait for a future release that will enable you to upgrade Worker Nodes across all Leaders and 4.x.x versions.

• Upgrading from v.4.1 and older: Before upgrading, encrypt TLS certificate private key files when you add or modify them. See the next section about Safeguard Unencrypted Private Key Files for Rollback for information about backing up your keys from older versions.

Safeguard Unencrypted Private Key Files for Rollback ​

Before upgrading from a version older than 4.1, make a backup copy of all unencrypted TLS certificate private key files. Having access to the unencrypted files is essential if you later find that you need to roll back to your previous version.

To safeguard your unencrypted private keys, make a full backup of all Cribl config files. Files in the auth/certs directory are particularly important, such as those in:

• groups/default/local/cribl/auth/certs/
• groups/<groupname>/local/cribl/auth/certs/
• cribl/local/cribl/auth/certs/

Take appropriate precautions to prevent unauthorized access to these unencrypted private key files. If you need to roll back to a version older than 4.1, see Restore Unencrypted Private Keys.

Network Connectivity Requirements ​

For a smooth upgrade process, Cribl Workers require reliable and timely network access to specific resources during the upgrade. Check the following:

• Preferred Connectivity: Workers attempt to download upgrade packages from the Cribl content delivery network (CDN) for efficient updates. A stable and responsive connection to cdn.cribl.io is a must for successful upgrades.
• Alternative Connectivity (if CDN access is restricted): If accessing cdn.cribl.io is not possible due to security restrictions or other reasons, Workers can fall back to downloading the upgrade package directly from the Leader.

Network Performance Considerations ​

When accessing the CDN at cdn.cribl.io, a slow or unreliable network connection will cause the upgrade to fail due to significant delays. The upgrade package size can be around 80 MB.

If you are having problems downloading the package from the CDN, check the following:

• Ensure adequate network bandwidth and stability. Test your network connection for reliability before upgrading.
• Prevent RPC timeouts. Cribl Stream versions 4.11.1 and newer have a higher RPC timeout threshold. Upgrade your Worker Nodes to v.4.11.1 or newer to help prevent future RPC timeouts.
• Ensure access to the CDN (to download packages) is not blocked by firewall for upgrades. See the following section about Considerations for Firewalls/Web Proxies for more information.

Considerations for Firewalls/Web Proxies ​

For optimal upgrade performance, configure firewalls to allow access to cdn.cribl.io:

• If your organization restricts access to cdn.cribl.io, configure firewalls to immediately deny connection requests. This allows Workers to promptly fall back to the Leader for downloading the upgrade package and avoid timeouts.
• You may encounter the “unsafe legacy renegotiation disabled” error when the Cribl Stream Leader attempts to connect to the CDN, preventing Worker Node upgrades. This error occurs if your firewall or proxy (like PAN firewalls) doesn’t support the TLS Renegotiation Indication Extension (RFC 5746).
• Ensure your firewall or proxy is compliant with RFC 5746. Contact your firewall/proxy vendor for update instructions.

Disable SNI Routing for Firewalls/Web Proxies ​

If you’re experiencing issues with proxies or firewalls between your Cribl Stream Worker Nodes and Leader Node, you can disable Server Name Indication (SNI) routing for specific Groups.

To disable SNI routing for a Group: Navigate to Worker Group Settings > General Settings > SNI > Disable SNI Routing option. Commit and Deploy and then proceed with the upgrade. You must enable this setting for every Group that is behind a web proxy or firewall.

Upgrade a Standalone/Single-Instance ​

To upgrade a single-instance deployment from the UI, select Settings > System > Upgrade.

To upgrade a single-instance deployment using the command line:

1. Stop Cribl Stream.

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 Cribl Stream.

Upgrade a Distributed Deployment ​

You can upgrade Leader and Worker Nodes with the command line interface (CLI) or the user interface (UI).

Upgrade and Automatic Rollback via the UI ​

When you choose to upgrade via the UI, Cribl Stream stops its own server, updates the installed package, and restarts Stream for you.

Upgrading through the UI is not supported for distributed environments with an additional Leader configured for high availability/failover. Instead, use the command line interface (CLI) to upgrade.

Here’s how to access the Upgrade UI in Stream:

1. First, select Settings in the sidebar.

2. Select Upgrade depending on your deployment type:

   • In a single-instance deployment, select System, then Upgrade.
   • To upgrade the Leader Node, select Global, then System and Upgrade.
   • To upgrade a single Worker Group, select Stream then Group Upgrade.

You can also enable an automatic backup and rollback in case an upgrade fails.

These options will work only if all Stream instances (including Worker Processes) start at v.2.4.4 or higher. For other version-specific limitations, please see Known Issues.

Upgrade the Leader via the UI ​

To upgrade the Leader in a distributed deployment, go to Settings > Global > System > Upgrade.

When upgrading, you can choose to either download upgrade packages from Cribl’s content delivery network (CDN), or from a filesystem location that you specify in the form of a path.

Select a Package Source