IBM Support

Generate Maximo Application Suite MustGather File with IBM MAS CLI in Docker or Podman

How To


Summary

This technote shows how to get the Maximo Application Suite must gather data using the IBM MAS CLI utility.

Objective

To generate a mustgather file to aid in troubleshooting Maximo Application Suite problems.

Environment

The environment must have Docker or Podman installed and running. Installation of Docker or Podman is not described in this note. Refer to Podman or Docker installation documentation.
 
In some cases, if it's not possible to run a container in the admin host, an option is to download the standalone binary.
For the steps described here, an Ubuntu v22.04 virtual machine is used as host environment. Docker is used to illustrate the installation of the MAS CLI tool. If Podman is used, use the `podman` command in place of `docker` in the commands.

Steps

1. Making sure that Docker or Podman is running in your host environment, run the docker or podman command to create the MAS CLI container.
 
Note that the docker run command below has '--rm' flag. Exiting the container deletes it. Keep in mind to save the must gather data outside of the container (see step 3).
 
Also, the container is mounted on the home directory in the host, which makes it possible to save the must gather data locally. If unable to mount the container to a folder in the host environment, use the docker cp or podman cp command to transfer the must gather data tar file from the container to the local environment. See "Additional notes" below.
 
mas@controlav1:~$ docker run -ti --rm -v ~:/mnt/home --pull always quay.io/ibmmas/cli
latest: Pulling from ibmmas/cli
Digest: sha256:9bd2bb61d1d4c5f0cb654ee7d4106bccc91d52b287f4a614323223078ebf8994
Status: Image is up to date for quay.io/ibmmas/cli:latest
IBM Maximo Application Suite CLI Container v15.9.1
https://github.com/ibm-mas/ansible-devops
https://github.com/ibm-mas/cli
MAS Management:
  - mas install to install a new MAS instance
  - mas update to apply a new catalog update
  - mas upgrade to upgrade an existing MAS install to a new release
  - mas must-gather to perform must-gather against the target cluster
  - mas uninstall to uninstall a MAS instance
  - mas configtool-oidc to configure OIDC integration
Disconnected Install Support:
  - mas setup-registry to setup a private container registry on an OCP cluster
  - mas teardown-registry to delete a private container registry on an OCP cluster
  - mas mirror-images to mirror container images required by MAS to a private registry
  - mas configure-airgap to configure a cluster to use a private registry as a mirror
OpenShift Cluster Management:
  - mas provision-aws to provision an OCP cluster on AWS
  - mas provision-roks to provision an OCP cluster on IBMCloud Red Hat OpenShift Service (ROKS)
  - mas provision-rosa to provision an OCP cluster on AWS Red Hat OpenShift Service (ROSA)
  - mas provision-fyre to provision an OCP cluster on IBM DevIT Fyre (internal)
AI Service (Standalone) Management:
  - mas aiservice-install to install a new AI Service instance
[ibmmas/cli:15.9.1]mascli$
 
2. In the container, login to the OpenShift cluster that hosts your MAS instance.
     a. Copy the login command.
     b. Run the command in the container.
[ibmmas/cli:15.9.1]mascli$ oc login --token=xxx --server=https://api.xxx.cp.fyre.ibm.com:6443
The server uses a certificate signed by an unknown authority.
You can bypass the certificate check, but any data you send to the server could be intercepted by others.
Use insecure connections? (y/n): y
WARNING: Using insecure TLS client config. Setting this option is not supported!
Logged into "https://api.xxx.cp.fyre.ibm.com:6443" as "kube:admin" using the token provided.
You have access to 88 projects, the list has been suppressed. You can list all projects with 'oc projects'
Using project "default".
Welcome! See 'oc help' to get started.
[ibmmas/cli:15.9.1]mascli$
 
3. Run the 'mas must-gather' command with the '-d' option, which allows the must gather data to be saved in the host in a folder called 'mymasmg'.
 
[ibmmas/cli:15.9.1]mascli$ mas must-gather -d /mnt/home/mymasmg
IBM Maximo Application Suite Must-Gather Tool (v15.9.1)
Command executed: must-gather -d /mnt/home/mymasmg
Must gather generated with mas cli version: 15.9.1
Must gather will be saved to: /mnt/home/mymasmg/must-gather-20251012-045219.tgz
....
 
When ran without any other option, the 'mas must-gather' command collects the following data (as of version 15.9.1):
 
  • OpenShift resources
  • In-cluster dependencies (if present in the cluster)
    • IBM CloudPak Foundation Services
    • IBM CloudPak for Data
    • IBM Db2 Universal Operator
    • IBM Data Reporter Operator
    • Red Hat Certificate Manager
    • Kafka
    • Grafana
    • MongoCE
  • Suite License Service
  • MAS core
  • MAS applications present
  • Pipeline custom resources
  • MAS quick summary
  • In-cluster AI Service Dependencies
 
4. When the command finishes running, a tar file is generated in the folder provided in the '-d' option to the command.
 
....
Must gather successfully saved to: /mnt/home/mymasmg/must-gather-20251012-045219.tgz
[ibmmas/cli:15.9.1]mascli$
 
 
5. Exit the container and locate the tar file.
 
[ibmmas/cli:15.9.1]mascli$ exit
exit
mas@controlav1:~$ ls -lt mymasmg/
total 139324
-rw-r--r-- 1 root root 142666937 Oct 11 22:18 must-gather-20251012-045219.tgz
 
It is recommended to review the tar file before attaching it to the support ticket. A very common issue is that the tar file does not contain any data because the 'mas must-gather' command was ran without running the 'oc login' command (step 2).
 
Must gather options
 
Options to the 'mas must-gather' command other that '-d' are available.  Here are some that are commonly used:
 
--secret-data  # Include secrets content in the must-gather
--mas-instance-ids  # Limit must-gather to a list of MAS instance IDs (comma-seperated list)
--extra-namespaces # Enable must-gather in custom namespaces (comma-seperated list)
 
Refer to the IBM MAS CLI documentation for examples of how to use these options and for information of what data are collected.
 
Reviewing the must gather data
 
A separate technote deals with reviewing the MAS must gather data. 
 
Additional notes
 
If no volume was mounted to the pod when it was created, you can use the podman or docker command to copy the must gather archive to the host:
 
While the MAS cli container is still running, get the container name:
podman ps
Use the name of the container to use the cp command
podman cp <containerName>:<path to the mustgather tar file> <path where to copy the file to>
 

For example, to copy to the current local directory:

podman ps
CONTAINER ID  IMAGE                      COMMAND          CREATED      STATUS      PORTS       NAMES
095512c45cff  quay.io/ibmmas/cli:latest  /bin/sh -c bash  2 weeks ago  Up 2 weeks              mascli
podman cp mascli:/mascli/must-gather-20250128-120001.tgz .
 

Document Location

Worldwide

[{"Type":"MASTER","Line of Business":{"code":"LOB77","label":"Automation Platform"},"Business Unit":{"code":"BU048","label":"IBM Software"},"Product":{"code":"SSRHPA","label":"IBM Maximo Application Suite"},"ARM Category":[{"code":"a8m0z000000cwZDAAY","label":"Maximo Application Suite"}],"ARM Case Number":"","Platform":[{"code":"PF025","label":"Platform Independent"}],"Version":"All Versions"}]

Document Information

Modified date:
13 August 2026

UID

ibm16998647

Page Feedback