Upgrade ExtraHop firmware through the REST API

You can automate upgrades to the firmware on your ExtraHop system through the ExtraHop REST API. This guide includes methods for both the cURL command and a Python script.

While the firmware upgrade process is similar across all ExtraHop appliances, some appliances have additional considerations or steps that you must address before you install the firmware in your environment. If you need assistance with your upgrade, contact ExtraHop Support.

All appliances must meet the following requirements:

  • The firmware version must be compatible with your appliance model.
  • The firmware version on your appliance must be supported by the upgrade version.
  • Command appliances must be running firmware that is greater than or equal to their connected appliances.
  • Discover appliances must be running firmware that is greater than or equal to Explore and Trace appliances.

If your deployment only includes a Discover appliance, proceed to the cURL or Python upgrade instructions.

If your deployment includes additional appliance types, you must address the following dependencies before proceeding with the upgrade instructions.

If your deployment includes... Pre-upgrade tasks Upgrade order
Command appliances Reserve a maintenance window of an hour for Command appliances managing 50,000 devices or more.
  • Command appliance
  • Discover appliances
  • All Explore appliances (manager nodes, then data nodes)
  • Trace appliances
Explore appliances See Upgrading Explore appliances.
Trace appliances None

Upgrade ExtraHop firmware with cURL

You can upgrade the firmware on an ExtraHop system through the cURL command.

Before you begin

  • The cURL tool must be installed on your machine.
  • The system firmware .tar file must be downloaded on your machine.
  1. Open a terminal application.
  2. Upload the firmware file.

    Run the following command, where YOUR_KEY is the API key for your user account, HOSTNAME is the hostname of your ExtraHop system, and FILE_PATH is the relative file path of the system firmware .tar file:

    curl -X POST https://HOSTNAME/api/v1/extrahop/firmware --data-binary @FILE_PATH -H "Content-Type:application/vnd.extrahop.firmware" -H "Authorization: ExtraHop apikey=YOUR_KEY"
  3. Upgrade the system firmware.

    Run the following command, where YOUR_KEY is the API key for your user account, and HOSTNAME is the hostname of your ExtraHop system:

    curl -X POST "https://HOST/api/v1/extrahop/firmware/latest/upgrade" -H "accept: application/json" -H "Authorization: ExtraHop apikey=YOUR_KEY" -H "Content-Type: application/json" -d "{ \"restart_after\": true}"
  4. Verify that the system has been successfully upgraded.

    Run the following command, where YOUR_KEY is the API key for your user account, and HOSTNAME is the hostname of your ExtraHop system:

    curl -X GET https://HOST/api/v1/extrahop -H "Authorization: ExtraHop apikey=YOUR_KEY"

    The command displays an object that contains information about the firmware currently running on the system. Verify that the version field matches the firmware version you are upgrading to. If the above command does not display the correct version number, wait a few minutes, and then try again. It might take several minutes for the upgrade to complete.

Retrieve and run the example Python script

The ExtraHop GitHub repository contains an example Python script that upgrades multiple ExtraHop systems by reading URLs, API keys, and firmware file paths from a CSV file.

Note:The script does not automatically disable record ingest for Explore appliances. You must manually disable record ingest before running the script for an Explore appliance.
  1. Go to the ExtraHop code-examples GitHub repository and download the upgrade_system/upgrade_system.py file to your local machine.
  2. Create a CSV file with rows that contain the following columns in the specified order:
    System hostname API key Firmware file path
    Tip:The upgrade_system directory contains an example CSV file named systems.csv.
  3. In a text editor, open the upgrade_system.py file and replace the following configuration variables with information from your environment:

    SYSTEM_LIST: The relative file path of the CSV file.

    MAX_RETRIES: The maximum number of times to retry uploading the firmware to a system.

    MAX_THREADS: The maximum number of concurrent threads

    WAIT: The number of minutes the script waits between checking the progress of an upgrade.

  4. Run the following command:
    python3 upgrade_system.py
    Note:If the script returns an error message that the SSL certificate verification failed, make sure that a trusted certificate has been added to your ExtraHop system. Alternatively, you can add the verify=False option to bypass certificate verification. However, this method is not secure and is not recommended. The following code sends an HTTP GET request without certificate verification:
    requests.get(url, headers=headers, verify=False)

Upgrading Explore appliances

Pre-upgrade tasks

Before upgrading an Explore appliance, you must halt record ingest. You can halt record ingest for all of the nodes in a cluster from a single node.

Note:The message Could not determine ingest status on some nodes and Error might appear on the Cluster Data Management page in the Administration settings of the upgraded nodes until all nodes in the cluster are upgraded. These errors are expected and can be ignored.
  1. Open a terminal application.
  2. Run the following command, where YOUR_KEY is the API for your user account, and HOSTNAME is the hostname of your Explore appliance:
    curl -X PATCH "https://HOST/api/v1/extrahop/cluster" -H "accept: application/json" -H "Authorization: ExtraHop apikey=YOUR_KEY" -H "Content-Type: application/json" -d "{ \"ingest_enabled\": false}"

Post-upgrade tasks

After you have upgraded all of the nodes in the Explore cluster, enable record ingest.

  1. Open a terminal application.
  2. Run the following command, where YOUR_KEY is the API for your user account, and HOSTNAME is the hostname of your Explore appliance:
    curl -X PATCH "https://HOST/api/v1/extrahop/cluster" -H "accept: application/json" -H "Authorization: ExtraHop apikey=YOUR_KEY" -H "Content-Type: application/json" -d "{ \"ingest_enabled\": false}"
Last modified 2023-11-07