Find solutions to common issues you can encounter when upgrading Cribl Edge.

While we expect you’ll have an easy time upgrading Cribl Edge, here is the troubleshooting information we’ve curated in case you do experience a hiccup:

Direct Upgrades

​

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

Service Timeout for Leader Upgrades

​

If your Leader is managed by a service manager (such as systemd, openRC, or Upstart), the default TimeoutSec=60 might be insufficient for complex environments.

The cumulative time required to parse dozens of Fleets, or environments with a high density of Sources, Destinations, and Routes, can easily exceed the 60-second window. If this threshold is hit, systemd will end the process mid-migration, causing the upgrade to fail.

To prevent this, temporarily increase the timeout:

1. Open the service configuration (or use an override): systemctl edit cribl.service
2. Set a higher limit, for example: TimeoutSec=600
3. Reload the configuration: systemctl daemon-reload
4. Retry the upgrade.

Once the upgrade completes, repeat these steps to revert to the default value, TimeoutSec=60. This keeps your stop/restart cycles fast by allowing systemd to intervene quickly if the process becomes unresponsive.

For more background on timeouts during larger data migrations, see details in Addressing HA Migration Timeouts.

Leader and Edge Nodes Compatibility

​

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 Edge Nodes to the same version.

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

Upgrade to Older Versions

​

Take a look at the following information if your Edge Nodes are running older software versions.

Upgrade to 4.2.x

​

Leaders on 4.2.x are compatible with Edge Nodes on 4.1.2, 4.1.3, and later. Due to a security update, Edge Nodes running on 4.0.4 cannot receive configurations from 4.2.x Leaders.

Upgrade to 4.1.x or Newer

​

Cribl Edge 4.1 and newer encrypts TLS certificate private key files when you add or modify them. See instructions for backing up your keys from earlier versions.

Upgrade to 4.0.x or Newer

​

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

Safeguard Unencrypted Private Keys for Rollback

​

Cribl Edge 4.1 and newer encrypt TLS certificate private key files when you add or modify them.

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/
• Etc.

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 Restoring Unencrypted Private Keys.