Before you upgrade VM

When a new platform release is available, you can upgrade your existing installation to benefit from the latest features and enhancements.
When you download a new VM image containing a newer platform release than the currently installed one on your system, you can upgrade your platform installation to the latest available public version.
The upgrade procedure requires some housekeeping; once you are done, you can access new features, and you can enjoy the improvements we introduce in the product on a regular basis.

To successfully execute commands in the command line or in the terminal, you may require root-level access rights.

Command and code examples

At times throughout this document, you are required to enter commands in the terminal, the console, or the command line.

The commands we ask you to enter or execute do not usually include the $ (non-sudo access level) or the # (sudo access level) prefix.
When you need root-access level to run a command, this is usually explicitly mentioned.
The recommended way to obtain root-level access is sudo -i.

Example

# Grant the currently logged in user root-level access 
sudo -i
 
# Grant root-level access to a different user
sudo -i -u ${user_name}
 
# Run a command as a different user, with root-level access
sudo -i -u ${user_name} ${command} ${options}

Disable rules

Disable all platform rules: entity, observable, enrichment, and discovery rules.
You can disable rules in one of the following ways:

In the rule detail pane

Click Data configuration > Rules > Observable ; or: Data configuration > Rules > Entity; or: Data configuration > Rules > Enrichment; or: Data configuration > Rules > Discovery to display the observable, entity, enrichment, or discovery rule overview.
In the rule overview click anywhere in the row corresponding to the rule you want to disable.
In the rule detail panel:
1. Click > Enable to disable the rule.
  Alternatively:
2. In the Details tab click Disable.

A notification message is displayed to confirm the change.

In the rule overview

Click Data configuration > Rules > Observable ; or: Data configuration > Rules > Entity; or: Data configuration > Rules > Enrichment; or: Data configuration > Rules > Discovery to display the observable, entity, enrichment, or discovery rule overview.
In the row corresponding to the rule you want to disable, click > Disable.

A notification message is displayed to confirm the change.

Bulk enable

Click Data configuration > Rules > Observable ; or: Data configuration > Rules > Entity; or: Data configuration > Rules > Enrichment; or: Data configuration > Rules > Discovery to display the observable, entity, enrichment, or discovery rule overview.
In the top-left corner click the quick filter icon to display the available rule quick filters.
Click Show, select Enabled, and then click OK to display only enabled rules.
To select all the rules on the view, click the checkbox in the top-left corner of the table.
To disable all the selected rules in bulk, in the quick filter horizontal bar click > Disable.

A notification message is displayed to confirm the change.

Exit the platform

To sign out of the platform:

In the side navigation bar click the currently signed-in user avatar image.
From the pop-up menu select Sign out.
You are signed out.

Back up your data

Before proceeding to upgrade the platform or any of its third-party components, always back up your data.

Shut down the platform

To graciously shut down EclecticIQ Platform, stop all platform-related services and processes.

A normal platform shutdown consists of one command to stop all backend processes and services.
To shut down the platform before performing an upgrade, it is advisable to stop platform components, services, and processes gradually.
The goal is to avoid hanging queues, tasks or PIDs that might cause issues during the upgrade.

Normal shutdown

To stop systemd-managed platform services through the command line:

systemctl stop eclecticiq-platform-backend-services

Shutdown before a platform upgrade

If you are shutting down the platform before performing an upgrade or a database backup, stop platform components in the order described below to make sure that:

No Celery tasks are left over in the queue.
No read/write activity is in progress in Redis.

This prevents hanging tasks in the queue from interfering with the upgrade or backup procedures.

To stop systemd-managed platform services through the command line:

systemctl stop eclecticiq-platform-backend-services

Check Celery queues. They should be empty:

# Launch redis-cli

$ redis-cli

$ > llen enrichers

$ > llen integrations

$ > llen priority_enrichers

$ > llen priority_providers

$ > llen priority_utilities

$ > llen providers

$ > llen reindexing

$ > llen utilities

To delete a non-empty Celery queue:

# Launch redis-cli

$ redis-cli

# Delete the entity ingestion queue

$ > del "queue:ingestion:inbound"

# Delete the graph ingestion queue

$ > del "queue:graph:inbound"

# Delete the search indexing queue

$ > del "queue:search:inbound"
Stop the remaining Celery workers:

systemctl stop eclecticiq-platform-backend-worker*.service

Check for leftover PIDs

Check that there are no leftover PID files
- First, make sure that no platform-related PID is running:
  
  ps auxf | grep beat

If any platform-related PIDs are running, terminate them with the kill command.
Manually remove any leftover PID files with the rm command.
Usually, PID files are stored in /var/run.

As a final inspection, you may want to get a snapshot overview of the currently running processes:

ps auxf

If you suspect that a specific process may be hanging or that it may still be running, look for it by searching for its name:

ps auxf | grep ${process_name}

When upgrading dependencies and third-party components, refer to their official documentation for detailed instructions on installation and upgrade procedures, and look up their official release notes for any product changes that may impact your environment.