RepoMirrors
/
ceph
mirror of https://github.com/ceph/ceph
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity
ceph/doc/man/8/rgw-restore-bucket-index.rst

114 lines
3.5 KiB
ReStructuredText
Raw Permalink Normal View History

rgw: enhances rgw-restore-bucket-index script This enhances the script to both process versioned buckets correctly and to handle object names that begin with underscore. If the bucket is versioned it submits each version chronologically (based on mtime) to be reindexed in order to "replay" the modification of objects. However mtime is not a perfect indicator. So additionally it looks at the OLH object to determine the most recent version and the script makes sure that it is replayed last. The order of previous versions is likely correct, but not guaranteed to be so. Additional logic is added to handle objects with names that begin with underscore ('_') since that's used as a delimiter and needs to be escaped and rados object locators are also used. A man page for the script is added. Signed-off-by: J. Eric Ivancich <ivancich@redhat.com>
2023-06-14 19:53:19 +00:00
:orphan:
==================================================================================
rgw-restore-bucket-index -- try to restore a bucket's objects to its bucket index
==================================================================================
.. program:: rgw-restore-bucket-index
Synopsis
========
| **rgw-restore-bucket-index**
Description
===========
:program:`rgw-restore-bucket-index` is an *EXPERIMENTAL* RADOS gateway
user administration utility. It scans the data pool for objects that
belong to a given bucket and tries to add those objects back to the
bucket index. It's intended as a **last resort** after a
**catastrophic** loss of a bucket index. Please thorougly review the
*Warnings* listed below.
The utility works with regular (i.e., un-versioned) buckets, versioned
buckets, and buckets were versioning has been suspended.
Warnings
========
This utility is currently considered *EXPERIMENTAL*.
The results are unpredictable if the bucket is in
active use while this utility is running.
The results are unpredictable if only some bucket's objects are
missing from the bucket index. In such a case, consider using the
"object reindex" subcommand of `radosgw-admin` to restore object's to
the bucket index one-by-one.
For objects in versioned buckets, if the latest version is a delete
marker, it will be restored. If a delete marker has been written over
with a new version, then that delete marker will not be restored. This
should have minimal impact on results in that the it recovers the
latest version and previous versions are all accessible.
Command-Line Arguments
======================
.. option:: -b <bucket>
Specify the bucket to be reindexed.
.. option:: -p <pool>
Optional, specify the data pool containing head objects for the
bucket. If omitted the utility will try to determine the data pool
on its own.
rgw: allow multisite specification used w/ rgw-restore-bucket-index script When the metadata for a bucket is requested only the default realm/zonegroup/zone is currently supported. This adds three new command-line options to rgw-restore-bucket-index: -r <realm-name> -g <zonegroup-name> -z <zone-name> The multisite specification will then be used in invocations of `radosgw-admin`, such as to query the zone, get metadata, and invoke the "object reindex" subcommand. Signed-off-by: J. Eric Ivancich <ivancich@redhat.com>
2023-07-12 17:54:07 +00:00
.. option:: -r <realm-name>
Optional, specify the realm if the restoration is not being applied
to the default realm.
.. option:: -g <zonegroup-name>
Optional, specify the zonegroup if the restoration is not being applied
to the default zonegroup.
.. option:: -z <zone-name>
Optional, specify the zone if the restoration is not being applied
to the default zone.
rgw: enhances rgw-restore-bucket-index script This enhances the script to both process versioned buckets correctly and to handle object names that begin with underscore. If the bucket is versioned it submits each version chronologically (based on mtime) to be reindexed in order to "replay" the modification of objects. However mtime is not a perfect indicator. So additionally it looks at the OLH object to determine the most recent version and the script makes sure that it is replayed last. The order of previous versions is likely correct, but not guaranteed to be so. Additional logic is added to handle objects with names that begin with underscore ('_') since that's used as a delimiter and needs to be escaped and rados object locators are also used. A man page for the script is added. Signed-off-by: J. Eric Ivancich <ivancich@redhat.com>
2023-06-14 19:53:19 +00:00
.. option:: -l <rados-ls-output-file>
Optional, specify a file containing the output of a rados listing
of the data pool. Since listing the data pool can be an expensive
and time-consuming operation, if trying to recover the indices for
multiple buckets, it could be more efficient to re-use the same
listing.
rgw: make rgw-restore-bucket-index more robust This experimental tool write a series of temporary files, the combined size of which is roughly proportional to some combination of the number of objects in the bucket and their respective sizes. Previously the script stored all temporary files in /tmp, which may not be sufficiently large in many cases. There are now two enhancements. First, using the "-t" command-line argument, the directory for temporary files can be specified. Second, if the script consumes all available space on the file system containing the temporary directory, an error message to that effect is displayed, so the user understands what corrective action to take. Signed-off-by: J. Eric Ivancich <ivancich@redhat.com>
2024-03-01 23:54:12 +00:00
.. option:: -t <temporary-directory>
Optional, specify a directory in which to store temporary files.
The size of the temporary files is highly dependent on the number
of bucket entries involved, so the partition on which the temporary
directory exists should be of suitable size.
rgw: enhances rgw-restore-bucket-index script This enhances the script to both process versioned buckets correctly and to handle object names that begin with underscore. If the bucket is versioned it submits each version chronologically (based on mtime) to be reindexed in order to "replay" the modification of objects. However mtime is not a perfect indicator. So additionally it looks at the OLH object to determine the most recent version and the script makes sure that it is replayed last. The order of previous versions is likely correct, but not guaranteed to be so. Additional logic is added to handle objects with names that begin with underscore ('_') since that's used as a delimiter and needs to be escaped and rados object locators are also used. A man page for the script is added. Signed-off-by: J. Eric Ivancich <ivancich@redhat.com>
2023-06-14 19:53:19 +00:00
.. option:: -y
Optional, proceed without further prompting. Without this option
the utility will display some information and prompt the user as to
whether to proceed. When provided, the utility will simply
proceed. Please use caution when using this option.
Examples
========
Attempt to restore the index for a bucket named *summer-2023-photos*::
$ rgw-restore-bucket-index -b summer-2023-photos
Availability
============
:program:`rgw-restore-bucket-index` is part of Ceph, a massively
scalable, open-source, distributed storage system. Please refer to
the Ceph documentation at https://docs.ceph.com for more information.
See also
========
:doc:`radosgw-admin <radosgw-admin>`\(8)