This is a cache of https://docs.okd.io/4.17/backup_and_restore/application_backup_and_restore/troubleshooting/using-the-must-gather-tool.html. It is a snapshot of the page at 2025-08-24T01:30:14.912+0000.
Using the must-gather tool - OADP Application backup and restore | Backup and restore | OKD 4.17
  1. Documentation
×

Using the must-gather tool

You can collect logs and information about OADP custom resources by using the must-gather tool. The must-gather data must be attached to all customer cases.

The must-gather tool is a container and does not run all the time. The tool runs for a few minutes only after you invoke the tool by running the must-gather command.

Using the must-gather tool

You can run the must-gather tool with the following options. To use an option, add a flag corresponding to that option in the must-gather command.

Default configuration

This configuration collects pod logs, OADP, and Velero custom resource (CR) information for all namespaces where the OADP Operator is installed.

Timeout

Data collection can take a long time if there are many failed Backup CRs. You can improve performance by setting a timeout value.

Insecure TLS connections

If a custom CA certificate is used, run the must-gather tool with insecure TLS connections.

The must-gather tool generates a Markdown output file with the collected information. The Markdown file is located in a cluster directory.

For more information about the supported flags, use the help flag with the must-gather tool as shown in the following example:

$ oc adm must-gather --image=registry.redhat.io/oadp/oadp-mustgather-rhel9:v1.4 -- /usr/bin/gather -h
Prerequisites

  • You have logged in to the OKD cluster as a user with the cluster-admin role.

  • You have installed the OpenShift CLI (oc).

  • You must use Fedora 9 with OADP 1.4.

Procedure

  1. Navigate to the directory where you want to store the must-gather data.

  2. Run the oc adm must-gather command for one of the following data collection options:

    • To use the default configuration of the must-gather tool, run the following command:

      $ oc adm must-gather --image=registry.redhat.io/oadp/oadp-mustgather-rhel9:v1.4

    • To use the timeout flag with the must-gather tool, run the following command:

      $ oc adm must-gather --image=registry.redhat.io/oadp/oadp-mustgather-rhel9:v1.4 -- /usr/bin/gather --request-timeout 1m (1)
      1 In this example, the timeout is 1 minute.

    • To use the insecure TLS connection flag with the must-gather tool, run the following command:

      $ oc adm must-gather --image=registry.redhat.io/oadp/oadp-mustgather-rhel9:v1.4 -- /usr/bin/gather --skip-tls

    • To use a combination of the insecure TLS connection, and the timeout flags with the must-gather tool, run the following command:

      $ oc adm must-gather --image=registry.redhat.io/oadp/oadp-mustgather-rhel9:v1.4 -- /usr/bin/gather --request-timeout 15s --skip-tls (1)
      1 In this example, the timeout is 15 seconds. By default, the --skip-tls flag value is false. Set the value to true to allow insecure TLS connections.
Verification

  1. Verify that the Markdown output file is generated at the following location: must-gather.local.89…​054550/registry.redhat.io/oadp/oadp-mustgather-rhel9:v1.5-sha256-0…​84/clusters/a4…​86/oadp-must-gather-summary.md

  2. Review the must-gather data in the Markdown file by opening the file in a Markdown previewer. For an example output, refer to the following image. You can upload this output file to a support case on the Red Hat Customer Portal.

    must-gather markdown output
    Figure 1. Example markdown output
Additional resources