Red Hat Summit Red Hat SummitSupportConsoleDevelopersStart a trialContact

Chapter 8. Troubleshooting objects

As a storage administrator, you can use the ceph-objectstore-tool utility to perform high-level or low-level object operations. The ceph-objectstore-tool utility can help you troubleshoot problems related to objects within a particular OSD or placement group.

Important

Manipulating objects can cause unrecoverable data loss. Contact Red Hat support before using the ceph-objectstore-tool utility.

8.1. Prerequisites
Copy link

  • Verify there are no network related issues.

8.2. Troubleshooting high-level object operations
Copy link

As a storage administrator, you can use the ceph-objectstore-tool utility to perform high-level object operations. The ceph-objectstore-tool utility supports the following high-level object operations:

  • List objects
  • List lost objects
  • Fix lost objects
Important

Manipulating objects can cause unrecoverable data loss. Contact Red Hat support before using the ceph-objectstore-tool utility.

8.2.1. Prerequisites
Copy link

  • Having root access to the Ceph OSD nodes.

8.2.2. Listing objects
Copy link

The OSD can contain zero to many placement groups, and zero to many objects within a placement group (PG). The ceph-objectstore-tool utility allows you to list objects stored within an OSD.

Prerequisites

  • Having root access to the Ceph OSD node.
  • Stopping the ceph-osd daemon.

Procedure

  1. Verify the appropriate OSD is down:

    Syntax

    systemctl status ceph-osd@$OSD_NUMBER
    Copy to Clipboard Toggle word wrap

    Example

    [root@osd ~]# systemctl status ceph-osd@1
    Copy to Clipboard Toggle word wrap

  2. Identify all the objects within an OSD, regardless of their placement group:

    Syntax

    ceph-objectstore-tool --data-path $PATH_TO_OSD --op list
    Copy to Clipboard Toggle word wrap

    Example

    [root@osd ~]# ceph-objectstore-tool --data-path /var/lib/ceph/osd/ceph-0 --op list
    Copy to Clipboard Toggle word wrap

  3. Identify all the objects within a placement group:

    Syntax

    ceph-objectstore-tool --data-path $PATH_TO_OSD --pgid $PG_ID --op list
    Copy to Clipboard Toggle word wrap

    Example

    [root@osd ~]# ceph-objectstore-tool --data-path /var/lib/ceph/osd/ceph-0 --pgid 0.1c --op list
    Copy to Clipboard Toggle word wrap

  4. Identify the PG an object belongs to:

    Syntax

    ceph-objectstore-tool --data-path $PATH_TO_OSD --op list $OBJECT_ID
    Copy to Clipboard Toggle word wrap

    Example

    [root@osd ~]# ceph-objectstore-tool --data-path /var/lib/ceph/osd/ceph-0 --op list default.region
    Copy to Clipboard Toggle word wrap

Additional Resources

8.2.3. Fixing lost objects
Copy link

You can use the ceph-objectstore-tool utility to list and fix lost and unfound objects stored within a Ceph OSD. This procedure applies only to legacy objects.

Prerequisites

  • Having root access to the Ceph OSD node.
  • Stopping the ceph-osd daemon.

Procedure

  1. Verify the appropriate OSD is down:

    Syntax

    systemctl status ceph-osd@$OSD_NUMBER
    Copy to Clipboard Toggle word wrap

    Example

    [root@osd ~]# systemctl status ceph-osd@1
    Copy to Clipboard Toggle word wrap

  2. To list all the lost legacy objects:

    Syntax

    ceph-objectstore-tool --data-path $PATH_TO_OSD --op fix-lost --dry-run
    Copy to Clipboard Toggle word wrap

    Example

    [root@osd ~]# ceph-objectstore-tool --data-path /var/lib/ceph/osd/ceph-0 --op fix-lost --dry-run
    Copy to Clipboard Toggle word wrap

  3. Use the ceph-objectstore-tool utility to fix lost and unfound objects. Select the appropriate circumstance:

    1. To fix all lost objects:

      Syntax

      ceph-objectstore-tool --data-path $PATH_TO_OSD --op fix-lost
      Copy to Clipboard Toggle word wrap

      Example

      [root@osd ~]# ceph-objectstore-tool --data-path /var/lib/ceph/osd/ceph-0 --op fix-lost
      Copy to Clipboard Toggle word wrap

    2. To fix all the lost objects within a placement group:

      Syntax

      ceph-objectstore-tool --data-path $PATH_TO_OSD --pgid $PG_ID --op fix-lost
      Copy to Clipboard Toggle word wrap

      Example

      [root@osd ~]# ceph-objectstore-tool --data-path /var/lib/ceph/osd/ceph-0 --pgid 0.1c --op fix-lost
      Copy to Clipboard Toggle word wrap

    3. To fix a lost object by its identifier:

      Syntax

      ceph-objectstore-tool --data-path $PATH_TO_OSD --op fix-lost $OBJECT_ID
      Copy to Clipboard Toggle word wrap

      Example

      [root@osd ~]# ceph-objectstore-tool --data-path /var/lib/ceph/osd/ceph-0 --op fix-lost default.region
      Copy to Clipboard Toggle word wrap

Additional Resources

8.3. Troubleshooting low-level object operations
Copy link

As a storage administrator, you can use the ceph-objectstore-tool utility to perform low-level object operations. The ceph-objectstore-tool utility supports the following low-level object operations:

  • Manipulate the object’s content
  • Remove an object
  • List the object map (OMAP)
  • Manipulate the OMAP header
  • Manipulate the OMAP key
  • List the object’s attributes
  • Manipulate the object’s attribute key
Important

Manipulating objects can cause unrecoverable data loss. Contact Red Hat support before using the ceph-objectstore-tool utility.

8.3.1. Prerequisites
Copy link

  • Having root access to the Ceph OSD nodes.

8.3.2. Manipulating the object’s content
Copy link

With the ceph-objectstore-tool utility, you can get or set bytes on an object.

Important

Setting the bytes on an object can cause unrecoverable data loss. To prevent data loss, make a backup copy of the object.

Prerequisites

  • Having root access to the Ceph OSD node.
  • Stopping the ceph-osd daemon.

Procedure

  1. Verify the appropriate OSD is down:

    Syntax

    systemctl status ceph-osd@$OSD_NUMBER
    Copy to Clipboard Toggle word wrap

    Example

    [root@osd ~]# systemctl status ceph-osd@1
    Copy to Clipboard Toggle word wrap

  2. Find the object by listing the objects of the OSD or placement group (PG).

  3. Before setting the bytes on an object, make a backup and a working copy of the object:

    Syntax

    ceph-objectstore-tool --data-path $PATH_TO_OSD --pgid $PG_ID \
$OBJECT \
get-bytes > $OBJECT_FILE_NAME

ceph-objectstore-tool --data-path $PATH_TO_OSD --pgid $PG_ID \
$OBJECT \
get-bytes > $OBJECT_FILE_NAME
    Copy to Clipboard Toggle word wrap

    Example

    [root@osd ~]# ceph-objectstore-tool --data-path /var/lib/ceph/osd/ceph-0 --pgid 0.1c \
'{"oid":"zone_info.default","key":"","snapid":-2,"hash":235010478,"max":0,"pool":11,"namespace":""}'  \
get-bytes > zone_info.default.backup

[root@osd ~]# ceph-objectstore-tool --data-path /var/lib/ceph/osd/ceph-0 --pgid 0.1c \
'{"oid":"zone_info.default","key":"","snapid":-2,"hash":235010478,"max":0,"pool":11,"namespace":""}'  \
get-bytes > zone_info.default.working-copy
    Copy to Clipboard Toggle word wrap

  4. Edit the working copy object file and modify the object contents accordingly.

  5. Set the bytes of the object:

    Syntax

    ceph-objectstore-tool --data-path $PATH_TO_OSD --pgid $PG_ID \
$OBJECT \
set-bytes < $OBJECT_FILE_NAME
    Copy to Clipboard Toggle word wrap

    Example

    [root@osd ~]# ceph-objectstore-tool --data-path /var/lib/ceph/osd/ceph-0 --pgid 0.1c \
'{"oid":"zone_info.default","key":"","snapid":-2,"hash":235010478,"max":0,"pool":11,"namespace":""}' \
set-bytes < zone_info.default.working-copy
    Copy to Clipboard Toggle word wrap

Additional Resources

8.3.3. Removing an object
Copy link

Use the ceph-objectstore-tool utility to remove an object. By removing an object, its contents and references are removed from the placement group (PG).

Important

You cannot recreate an object once it is removed.

Prerequisites

  • Having root access to the Ceph OSD node.
  • Stopping the ceph-osd daemon.

Procedure

  1. Remove an object:

    Syntax

    ceph-objectstore-tool --data-path $PATH_TO_OSD --pgid $PG_ID \
$OBJECT \
remove
    Copy to Clipboard Toggle word wrap

    Example

    [root@osd ~]# ceph-objectstore-tool --data-path /var/lib/ceph/osd/ceph-0 --pgid 0.1c \
'{"oid":"zone_info.default","key":"","snapid":-2,"hash":235010478,"max":0,"pool":11,"namespace":""}' \
remove
    Copy to Clipboard Toggle word wrap

Additional Resources

8.3.4. Listing the object map
Copy link

Use the ceph-objectstore-tool utility to list the contents of the object map (OMAP). The output provides you a list of keys.

Prerequisites

  • Having root access to the Ceph OSD node.
  • Stopping the ceph-osd daemon.

Procedure

  1. Verify the appropriate OSD is down:

    Syntax

    systemctl status ceph-osd@$OSD_NUMBER
    Copy to Clipboard Toggle word wrap

    Example

    [root@osd ~]# systemctl status ceph-osd@1
    Copy to Clipboard Toggle word wrap

  2. List the object map:

    Syntax

    ceph-objectstore-tool --data-path $PATH_TO_OSD --pgid $PG_ID \
$OBJECT \
list-omap
    Copy to Clipboard Toggle word wrap

    Example

    [root@osd ~]# ceph-objectstore-tool --data-path /var/lib/ceph/osd/ceph-0 --pgid 0.1c \
'{"oid":"zone_info.default","key":"","snapid":-2,"hash":235010478,"max":0,"pool":11,"namespace":""}' \
list-omap
    Copy to Clipboard Toggle word wrap

Additional Resources

8.3.5. Manipulating the object map header
Copy link

The ceph-objectstore-tool utility will output the object map (OMAP) header with the values associated with the object’s keys.

Note

If using FileStore as the OSD backend object store, then add the --journal-path $PATH_TO_JOURNAL argument when getting or setting the object map header. Where the $PATH_TO_JOURNAL variable is the absolute path to the OSD journal, for example /var/lib/ceph/osd/ceph-0/journal.

Prerequisites

  • Having root access to the Ceph OSD node.
  • Stopping the ceph-osd daemon.

Procedure

  1. Verify the appropriate OSD is down:

    Syntax

    systemctl status ceph-osd@$OSD_NUMBER
    Copy to Clipboard Toggle word wrap

    Example

    [root@osd ~]# systemctl status ceph-osd@1
    Copy to Clipboard Toggle word wrap

    • Get the object map header:

      Syntax

      ceph-objectstore-tool --data-path $PATH_TO_OSD \
--pgid $PG_ID $OBJECT \
get-omaphdr > $OBJECT_MAP_FILE_NAME
      Copy to Clipboard Toggle word wrap

      Example

      [root@osd ~]# ceph-objectstore-tool --data-path /var/lib/ceph/osd/ceph-0 \
--pgid 0.1c '{"oid":"zone_info.default","key":"","snapid":-2,"hash":235010478,"max":0,"pool":11,"namespace":""}'  \
get-omaphdr > zone_info.default.omaphdr.txt
      Copy to Clipboard Toggle word wrap

    • Set the object map header:

      Syntax

      ceph-objectstore-tool --data-path $PATH_TO_OSD \
--pgid $PG_ID $OBJECT \
get-omaphdr < $OBJECT_MAP_FILE_NAME
      Copy to Clipboard Toggle word wrap

      Example

      [root@osd ~]# ceph-objectstore-tool --data-path /var/lib/ceph/osd/ceph-0 \
--pgid 0.1c '{"oid":"zone_info.default","key":"","snapid":-2,"hash":235010478,"max":0,"pool":11,"namespace":""}'  \
set-omaphdr < zone_info.default.omaphdr.txt
      Copy to Clipboard Toggle word wrap

Additional Resources

8.3.6. Manipulating the object map key
Copy link

Use the ceph-objectstore-tool utility to change the object map (OMAP) key. You need to provide the data path, the placement group identifier (PG ID), the object, and the key in the OMAP.

Note

If using FileStore as the OSD backend object store, then add the --journal-path $PATH_TO_JOURNAL argument when getting, setting or removing the object map key. Where the $PATH_TO_JOURNAL variable is the absolute path to the OSD journal, for example /var/lib/ceph/osd/ceph-0/journal.

Prerequisites

  • Having root access to the Ceph OSD node.
  • Stopping the ceph-osd daemon.

Procedure

  • Get the object map key:

    Syntax

    ceph-objectstore-tool --data-path $PATH_TO_OSD \
--pgid $PG_ID $OBJECT \
get-omap $KEY > $OBJECT_MAP_FILE_NAME
    Copy to Clipboard Toggle word wrap

    Example

    [root@osd ~]# ceph-objectstore-tool --data-path /var/lib/ceph/osd/ceph-0 \
--pgid 0.1c '{"oid":"zone_info.default","key":"","snapid":-2,"hash":235010478,"max":0,"pool":11,"namespace":""}'  \
get-omap "" > zone_info.default.omap.txt
    Copy to Clipboard Toggle word wrap

  • Set the object map key:

    Syntax

    ceph-objectstore-tool --data-path $PATH_TO_OSD \
--pgid $PG_ID $OBJECT \
set-omap $KEY < $OBJECT_MAP_FILE_NAME
    Copy to Clipboard Toggle word wrap

    Example

    [root@osd ~]# ceph-objectstore-tool --data-path /var/lib/ceph/osd/ceph-0 \
--pgid 0.1c '{"oid":"zone_info.default","key":"","snapid":-2,"hash":235010478,"max":0,"pool":11,"namespace":""}'  \
set-omap "" < zone_info.default.omap.txt
    Copy to Clipboard Toggle word wrap

  • Remove the object map key:

    Syntax

    ceph-objectstore-tool --data-path $PATH_TO_OSD \
--pgid $PG_ID $OBJECT \
rm-omap $KEY
    Copy to Clipboard Toggle word wrap

    Example

    [root@osd ~]# ceph-objectstore-tool --data-path /var/lib/ceph/osd/ceph-0 \
--pgid 0.1c '{"oid":"zone_info.default","key":"","snapid":-2,"hash":235010478,"max":0,"pool":11,"namespace":""}'  \
rm-omap ""
    Copy to Clipboard Toggle word wrap

Additional Resources

8.3.7. Listing the object’s attributes
Copy link

Use the ceph-objectstore-tool utility to list an object’s attributes. The output provides you with the object’s keys and values.

Note

If using FileStore as the OSD backend object store, then add the --journal-path $PATH_TO_JOURNAL argument when listing an object’s attributes. Where the $PATH_TO_JOURNAL variable is the absolute path to the OSD journal, for example /var/lib/ceph/osd/ceph-0/journal.

Prerequisites

  • Having root access to the Ceph OSD node.
  • Stopping the ceph-osd daemon.

Procedure

  1. Verify the appropriate OSD is down:

    Syntax

    systemctl status ceph-osd@$OSD_NUMBER
    Copy to Clipboard Toggle word wrap

    Example

    [root@osd ~]# systemctl status ceph-osd@1
    Copy to Clipboard Toggle word wrap

  2. List the object’s attributes:

    Syntax

    ceph-objectstore-tool --data-path $PATH_TO_OSD \
--pgid $PG_ID $OBJECT \
list-attrs
    Copy to Clipboard Toggle word wrap

    Example

    [root@osd ~]# ceph-objectstore-tool --data-path /var/lib/ceph/osd/ceph-0 \
--pgid 0.1c '{"oid":"zone_info.default","key":"","snapid":-2,"hash":235010478,"max":0,"pool":11,"namespace":""}' \
list-attrs
    Copy to Clipboard Toggle word wrap

Additional Resources

8.3.8. Manipulating the object attribute key
Copy link

Use the ceph-objectstore-tool utility to change an object’s attributes. To manipulate the object’s attributes you need the data and journal paths, the placement group identifier (PG ID), the object, and the key in the object’s attribute.

Note

If using FileStore as the OSD backend object store, then add the --journal-path $PATH_TO_JOURNAL argument when getting, setting or removing the object’s attributes. Where the $PATH_TO_JOURNAL variable is the absolute path to the OSD journal, for example /var/lib/ceph/osd/ceph-0/journal.

Prerequisites

  • Having root access to the Ceph OSD node.
  • Stopping the ceph-osd daemon.

Procedure

  1. Verify the appropriate OSD is down:

    Syntax

    systemctl status ceph-osd@$OSD_NUMBER
    Copy to Clipboard Toggle word wrap

    Example

    [root@osd ~]# systemctl status ceph-osd@1
    Copy to Clipboard Toggle word wrap

    • Get the object’s attributes:

      Syntax

      ceph-objectstore-tool --data-path $PATH_TO_OSD \
--pgid $PG_ID $OBJECT \
get-attrs $KEY > $OBJECT_ATTRS_FILE_NAME
      Copy to Clipboard Toggle word wrap

      Example

      [root@osd ~]# ceph-objectstore-tool --data-path /var/lib/ceph/osd/ceph-0 \
--pgid 0.1c '{"oid":"zone_info.default","key":"","snapid":-2,"hash":235010478,"max":0,"pool":11,"namespace":""}' \
get-attrs "oid" > zone_info.default.attr.txt
      Copy to Clipboard Toggle word wrap

    • Set an object’s attributes:

      Syntax

      ceph-objectstore-tool --data-path $PATH_TO_OSD \
--pgid $PG_ID $OBJECT \
set-attrs $KEY < $OBJECT_ATTRS_FILE_NAME
      Copy to Clipboard Toggle word wrap

      Example

      [root@osd ~]# ceph-objectstore-tool --data-path /var/lib/ceph/osd/ceph-0 \
--pgid 0.1c '{"oid":"zone_info.default","key":"","snapid":-2,"hash":235010478,"max":0,"pool":11,"namespace":""}' \
set-attrs "oid" < zone_info.default.attr.txt
      Copy to Clipboard Toggle word wrap

    • Remove an object’s attributes:

      Syntax

      ceph-objectstore-tool --data-path $PATH_TO_OSD \
--pgid $PG_ID $OBJECT \
rm-attrs $KEY
      Copy to Clipboard Toggle word wrap

      Example

      [root@osd ~]# ceph-objectstore-tool --data-path /var/lib/ceph/osd/ceph-0 \
--pgid 0.1c '{"oid":"zone_info.default","key":"","snapid":-2,"hash":235010478,"max":0,"pool":11,"namespace":""}' \
rm-attrs "oid"
      Copy to Clipboard Toggle word wrap

Additional Resources

8.4. Additional Resources
Copy link

Back to top
Red Hat logoGithubredditYoutubeTwitter

Learn

Try, buy, & sell

Communities

About Red Hat Documentation

We help Red Hat users innovate and achieve their goals with our products and services with content they can trust. Explore our recent updates.

Making open source more inclusive

Red Hat is committed to replacing problematic language in our code, documentation, and web properties. For more details, see the Red Hat Blog.

About Red Hat

We deliver hardened solutions that make it easier for enterprises to work across platforms and environments, from the core datacenter to the network edge.

Theme

© 2025 Red Hat