Collecting MustGather data

IBM Security QRadar® Suite Software provides a mustgather action that you must use to collect system information before you raise an issue that requires IBM® Support. For example, the mustgather action collects logs or system state information that can be used to diagnose an issue.

Before you begin

Install the command-line interface (CLI) utility cpctl from the cp-serviceability pod. For more information, see Installing the cpctl utility.

If the cp-serviceability pod isn't deployed or isn't available, run the mustgather action manually. For more information, see cp-serviceability pod not deployed or unavailable.

About this task

The mustgather action has the following parameters.

Table 1. mustgather action has the following parameters
Parameter Description
--token Specify the cluster administrator token. The token can be generated when you are logged in as an admin user by running the oc whoami -t command.
--namespaces Specify the IBM Cloud Pak® namespace or namespaces where the data is collected for the IBM Cloud Pak and secrets data modules. Separate each namespace with a semicolon.

If you do not specify a namespace, the namespace is set to ibm-common-services.

Procedure

  1. To make sure that the list of available cpctl actions is up to date, enter the following command.
    cpctl load
    The cpctl load command retrieves all of the available actions that can be run on QRadar Suite Software. The actions are cached to your local environment.
  2. Run the mustgather action by typing the following command. Replace <namespace> with a comma-separated list of the namespaces that you require.
    cpctl diagnostics mustgather --token <token> --namespaces <namespace>
    Note: If you run the mustgather action in an offline environment, the serviceability repository value is used.
  3. Optional: Copy the collected data from the /tmp directory on the cp-serviceability pod into your local directory.
    1. Set the $POD environment variable to the name of the serviceability pod by typing the following command.
      POD=$(oc get pod -A -l run=cp-serviceability --no-headers | awk '{print $2}')
    2. Copy the mustgather.tgz file into your local directory by typing the following command.
      rsync --rsh='oc rsh' -av -c --inplace --partial --append --progress $POD:/tmp/mustgather.tgz ./mustgather.tgz

Cp-serviceability pod not deployed or unavailable

You can run the mustgather action manually if the cp-serviceability pod is not deployed or is unavailable.

Before you begin

To complete this task, you must be a Red Hat® OpenShift® cluster administrator.

Review the Planning for installation section to ensure that you meet the hardware, system, storage, and other requirements.

Before you install QRadar Suite Software, review and take the following prerequisite steps for a successful installation.

Install Red Hat OpenShift CLI 4.14 or later

The Red Hat OpenShift CLI client helps you develop, build, deploy, and run your applications on any Red Hat OpenShift or Kubernetes cluster. It also includes the administrative commands for managing a cluster under the adm subcommand.

Procedure

  1. Download Red Hat OpenShift CLI 4.14 or later from https://mirror.openshift.com/pub/openshift-v4/x86_64/clients/ocp/stable-4.14/. The file to download is called openshift-client-<platform>-<version>.tar.gz.
  2. Extract the binary file that you downloaded by typing the following command, where <oc_cli_archive_file> is the name of the archive file that you downloaded.
    tar -xf <oc_cli_archive_file>
  3. Modify the permissions of the binary file by typing the following command, where <oc_cli_binary> is the name of the Red Hat OpenShift binary that you extracted from the archive.
  4. Move the binary file to the /usr/local/bin directory by typing the following command.
    mv <oc_cli_binary> /usr/local/bin/oc
    Tip: If this command returns a No such file or directory or Not a directory error message, create the /usr/local/bin directory by typing the following command.
    sudo mkdir /usr/local/bin
  5. Ensure that the Red Hat OpenShift CLI client is working by typing the following command.
    oc version
    Tip: MacOS users might see a message that this tool cannot be opened because it is from an unidentified developer. Close this message and go to System Preferences > Security & Privacy. On the General tab, click Open Anyway or Allow Anyway. Repeat the oc version command.

Cp-serviceability pod not deployed or unavailable

Run the mustgather action manually if the cp-serviceability pod is not deployed or is unavailable.

Procedure

  1. Log in to your Red Hat OpenShift Container Platform cluster as a cluster administrator by typing one of the following commands, where <openshift_url> is the URL for your Red Hat OpenShift Container Platform environment.
    • Using a username and password.
      oc login <openshift_url> -u <cluster_admin_user> -p <cluster_admin_password>
    • Using a token.
      oc login --token=<token> --server=<openshift_url>
  2. Set the $CP4S_NAMESPACE environment variable by typing the following command, where <cp4s_namespace> is the namespace where you are installing QRadar Suite Software.
    Important: If you install QRadar Suite Software in the all namespace mode, set the <cp4s_namespace> value as openshift-operators.
    export CP4S_NAMESPACE=<cp4s_namespace>
  3. Set the $FS_NAMESPACE environment variable to your foundational services namespace by typing the following command.
    export FS_NAMESPACE=$(oc get cm cp4s-config -o jsonpath="{.data.CSNamespace}" -n $CP4S_NAMESPACE)
  4. If the cp-serviceability pod is not deployed or is unavailable, you can run the mustgather action manually by typing the following command.
    oc adm must-gather --image=icr.io/cpopen/cp4s/cp4s-must-gather:1.10.16.0 -- gather -n $FS_NAMESPACE,<cp4s_namespace>
  5. In an offline environment, you must point to your local docker registry where all the QRadar Suite Software images are mirrored.
    oc adm must-gather --image=<local_registry>:5000/cpopen/cp4s/cp4s-must-gather:1.10.16.0 -- gather -n $FS_NAMESPACE,<cp4s_namespace>

Results

When the MustGather command is run manually, the action prints output to the console.