monmaptool is a command‑line utility used to view and modify the monitor cluster map in Ceph clusters. It allows you to inspect the current monitor map, add or remove monitors, and save the updated map back to the cluster.

How to use monmaptool

1. Install the tool

Ensure the ceph client tools are installed on the machine where you will run monmaptool. On Debian/Ubuntu systems you can install them with:

   sudo apt-get install ceph

1. Obtain a Ceph configuration file

You need a ceph.conf that contains the cluster’s monitor addresses and authentication details. Copy it to the machine or set the CEPH_CONFIG environment variable to point to its location.

1. Connect to the cluster

Use the --cluster option to specify the cluster name, or rely on the default cluster name defined in ceph.conf. Example:

   monmaptool --cluster mycluster

1. Display the current monitor map

To view the existing map, run:

   monmaptool --show

The output lists each monitor by name, IP address, and public key fingerprint.

1. Add a new monitor to the map

     ceph mon getmap -o /tmp/monmap
     monmaptool --add  --ip  --fsid  --secret 

     monmaptool --add  --ip  --fsid 

• Generate a monitor key if you do not already have one:
• Alternatively, use a simpler command if you already have the key:
• After adding, verify the map with --show.

   monmaptool --rm 

1. Remove a monitor from the map

This removes the specified monitor entry from the map.

1. Save the updated map back to the cluster

Once you have made the desired changes, write the modified map to the cluster’s monitor configuration:

   monmaptool --save

This command updates the monitor map stored in the cluster’s metadata.

1. Validate the map

After saving, you can verify that the cluster recognises the new map by running:

   ceph -s

The status output should reflect the updated monitor list.

Common troubleshooting steps

• Permission denied – Ensure you are running the command as a user with sufficient Ceph privileges, typically a user that can read ceph.conf and has access to the monitor keys.
• Unable to connect to monitors – Verify network connectivity to the monitor IPs and that the monitor ports (usually 3300) are open.
• Key mismatch – If adding a monitor fails due to a key mismatch, regenerate the monitor key using ceph auth get-or-create and provide the correct secret to monmaptool.

When to use monmaptool

• When initially setting up a new Ceph cluster and manually defining monitors.
• When adding or removing monitors in an existing cluster without using higher‑level Ceph commands.
• When troubleshooting monitor-related issues and needing to inspect the current monitor map directly.

By following these steps you can effectively manage the monitor cluster map using monmaptool. If any step fails, check the relevant Ceph logs and ensure that the monitor addresses and authentication keys are correct.