Collecting diagnostic data using Must-Gather scripts

Edit online

The Must-Gather scripts automatically collects diagnostic data across IBM Storage Protect products. The diagnostic data includes; logs, configuration files, performance statistics, connectivity details, and system information that are frequently required by IBM Software Support to diagnose problems efficiently.

When an issue occurs in any IBM Storage Protect environment, running the Must-Gather scripts ensures that all essential diagnostic data is collected in a consistent and structured manner. The collected information helps identify configuration issues, communication failures, and performance-related problems. If the collected data does not resolve the issue, the complete Must-Gather package can be provided to IBM Software Support for in-depth analysis.

Prerequisites

  • Perl 5.x installed.
  • Sudo privileges for network/firewall commands (Linux/Aix/Solaris/MacOS).
  • IBM Storage Protect product must be installed on the system.
  • Output directory must have write permissions.

How to get the Must-Gather scripts

The scripts are available in two locations:

  • IBM Open-Source Git Repository (latest version)

    The latest version scripts can be downloaded from:

    https://github.com/IBM/storage-protect-galaxy/releases

    Each product includes its own README file.

  • Product Installation Package (Optional)

    IBM Storage Protect products include the Must-Gather scripts in the installation package. The Must-Gather scripts are available in the installation directory at the following path:

    %INSTALLATION_DIR%/tools/scripts/must-gather

Executing the Must-Gather Script

This section describes how to execute the script, the common data it collects, and the structure of the output framework.

Product-specific documentation provides details about any additional data collected for each IBM Storage Protect product.

How to run the Must-Gather script

  1. Open a terminal at the Must-Gather script directory.
  2. Run the following command. For example:

    perl mustgather.pl --product <product_name> --output-dir <target_path> --caseno <case_number> --adminid <id> [options]

Script parameters

The script accepts both mandatory and optional parameters:
Parameter / Option Mandatory(M)/ Optional(O) Description
--product / -p M Specifies the product name. For the BA client, this value must be: sp-client-ba. This parameter is required for every execution.
--output-dir / -o M Defines the directory where all collected data will be stored. The directory will be created if it does not exist.
--adminid / -id M Specifies the IBM Storage Protect server administrator ID used for running server queries. A valid admin ID is required for the server module.
--caseno / -c M IBM Support Case Number (format: TS followed by 9 digits, for example; TS020757841)
--modules / -m O Allows selection of specific modules to run. If not specified, all modules are collected by default.
--optfile O Specifies a custom dsm.opt file location if not in the default installation directory.
--no-compress O Prevents the script from creating a ZIP file. Output remains as raw folders.
--verbose / -v O Displays detailed logs of each module’s execution.
--help / -h O Displays script usage, parameter descriptions, and syntax guidance.

Common modules collected

Regardless of the product, the Must-Gather framework collects a common set modules:

Module Description
system Collects system information, OS details, and environment variables.
network Performs network checks including ping, port check, firewall rules, and tcpdump capture.
server Runs Storage Protect administrative queries for system, storage, logs, and server status.

Execution summary and result status

At the end of execution, the Must-Gather script displays a module-level summary, as shown below.

Additionally, all previously generated Must-Gather reports in the output directory are deleted before creating the new report.

=== Must-Gather Collection Summary ===
Product              : <product_name>
Version              : Version 8, Release 2, Level 2.0
Node Name            : TEST
Server Name          : server1
 
  Modules           : Status
-----------------------------
 1. system          : Success
 2. network         : Partial
 3. server          : Success
 4. logs            : Success
Check script.log inside each module folder for detailed failures.
Output : <output-dir>/mustgather_<case_number>_<product_name>_20251124_165659.zip
This file can be sent to IBM Support team for analysis.

Explanation of status values

  • Success: All expected data for that module was collected successfully.
  • Partial: Some data are collected, but it may fail to gather certain important files or execute some commands.
  • Failed: Module failed to run or no data collected.

Each module writes its own script.log inside its output folder:

<output-dir>/<module>/script.log

At the end of execution, the script automatically creates a .zip file:

mustgather_<case_number>_<product_name>_<timestamp>.zip