summaryrefslogtreecommitdiffstats
path: root/doc/man/8/ceph-bluestore-tool.rst
diff options
context:
space:
mode:
Diffstat (limited to 'doc/man/8/ceph-bluestore-tool.rst')
-rw-r--r--doc/man/8/ceph-bluestore-tool.rst182
1 files changed, 182 insertions, 0 deletions
diff --git a/doc/man/8/ceph-bluestore-tool.rst b/doc/man/8/ceph-bluestore-tool.rst
new file mode 100644
index 00000000..667c330d
--- /dev/null
+++ b/doc/man/8/ceph-bluestore-tool.rst
@@ -0,0 +1,182 @@
+:orphan:
+
+======================================================
+ ceph-bluestore-tool -- bluestore administrative tool
+======================================================
+
+.. program:: ceph-bluestore-tool
+
+Synopsis
+========
+
+| **ceph-bluestore-tool** *command*
+ [ --dev *device* ... ]
+ [ --path *osd path* ]
+ [ --out-dir *dir* ]
+ [ --log-file | -l *filename* ]
+ [ --deep ]
+| **ceph-bluestore-tool** fsck|repair --path *osd path* [ --deep ]
+| **ceph-bluestore-tool** show-label --dev *device* ...
+| **ceph-bluestore-tool** prime-osd-dir --dev *device* --path *osd path*
+| **ceph-bluestore-tool** bluefs-export --path *osd path* --out-dir *dir*
+| **ceph-bluestore-tool** bluefs-bdev-new-wal --path *osd path* --dev-target *new-device*
+| **ceph-bluestore-tool** bluefs-bdev-new-db --path *osd path* --dev-target *new-device*
+| **ceph-bluestore-tool** bluefs-bdev-migrate --path *osd path* --dev-target *new-device* --devs-source *device1* [--devs-source *device2*]
+| **ceph-bluestore-tool** free-dump|free-score --path *osd path* [ --allocator block/bluefs-wal/bluefs-db/bluefs-slow ]
+
+
+Description
+===========
+
+**ceph-bluestore-tool** is a utility to perform low-level administrative
+operations on a BlueStore instance.
+
+Commands
+========
+
+:command:`help`
+
+ show help
+
+:command:`fsck` [ --deep ]
+
+ run consistency check on BlueStore metadata. If *--deep* is specified, also read all object data and verify checksums.
+
+:command:`repair`
+
+ Run a consistency check *and* repair any errors we can.
+
+:command:`bluefs-export`
+
+ Export the contents of BlueFS (i.e., rocksdb files) to an output directory.
+
+:command:`bluefs-bdev-sizes` --path *osd path*
+
+ Print the device sizes, as understood by BlueFS, to stdout.
+
+:command:`bluefs-bdev-expand` --path *osd path*
+
+ Instruct BlueFS to check the size of its block devices and, if they have expanded, make use of the additional space.
+
+:command:`bluefs-bdev-new-wal` --path *osd path* --dev-target *new-device*
+
+ Adds WAL device to BlueFS, fails if WAL device already exists.
+
+:command:`bluefs-bdev-new-db` --path *osd path* --dev-target *new-device*
+
+ Adds DB device to BlueFS, fails if DB device already exists.
+
+:command:`bluefs-bdev-migrate` --dev-target *new-device* --devs-source *device1* [--devs-source *device2*]
+
+ Moves BlueFS data from source device(s) to the target one, source devices
+ (except the main one) are removed on success. Target device can be both
+ already attached or new device. In the latter case it's added to OSD
+ replacing one of the source devices. Following replacement rules apply
+ (in the order of precedence, stop on the first match):
+
+ - if source list has DB volume - target device replaces it.
+ - if source list has WAL volume - target device replace it.
+ - if source list has slow volume only - operation isn't permitted, requires explicit allocation via new-db/new-wal command.
+
+:command:`show-label` --dev *device* [...]
+
+ Show device label(s).
+
+:command:`free-dump` --path *osd path* [ --allocator block/bluefs-wal/bluefs-db/bluefs-slow ]
+
+ Dump all free regions in allocator.
+
+:command:`free-score` --path *osd path* [ --allocator block/bluefs-wal/bluefs-db/bluefs-slow ]
+
+ Give a [0-1] number that represents quality of fragmentation in allocator.
+ 0 represents case when all free space is in one chunk. 1 represents worst possible fragmentation.
+
+Options
+=======
+
+.. option:: --dev *device*
+
+ Add *device* to the list of devices to consider
+
+.. option:: --devs-source *device*
+
+ Add *device* to the list of devices to consider as sources for migrate operation
+
+.. option:: --dev-target *device*
+
+ Specify target *device* migrate operation or device to add for adding new DB/WAL.
+
+.. option:: --path *osd path*
+
+ Specify an osd path. In most cases, the device list is inferred from the symlinks present in *osd path*. This is usually simpler than explicitly specifying the device(s) with --dev.
+
+.. option:: --out-dir *dir*
+
+ Output directory for bluefs-export
+
+.. option:: -l, --log-file *log file*
+
+ file to log to
+
+.. option:: --log-level *num*
+
+ debug log level. Default is 30 (extremely verbose), 20 is very
+ verbose, 10 is verbose, and 1 is not very verbose.
+
+.. option:: --deep
+
+ deep scrub/repair (read and validate object data, not just metadata)
+
+.. option:: --allocator *name*
+
+ Useful for *free-dump* and *free-score* actions. Selects allocator(s).
+
+Device labels
+=============
+
+Every BlueStore block device has a single block label at the beginning of the
+device. You can dump the contents of the label with::
+
+ ceph-bluestore-tool show-label --dev *device*
+
+The main device will have a lot of metadata, including information
+that used to be stored in small files in the OSD data directory. The
+auxiliary devices (db and wal) will only have the minimum required
+fields (OSD UUID, size, device type, birth time).
+
+OSD directory priming
+=====================
+
+You can generate the content for an OSD data directory that can start up a
+BlueStore OSD with the *prime-osd-dir* command::
+
+ ceph-bluestore-tool prime-osd-dir --dev *main device* --path /var/lib/ceph/osd/ceph-*id*
+
+BlueFS log rescue
+=====================
+
+Some versions of BlueStore were susceptible to BlueFS log growing extremaly large -
+beyond the point of making booting OSD impossible. This state is indicated by
+booting that takes very long and fails in _replay function.
+
+This can be fixed by::
+ ceph-bluestore-tool fsck --path *osd path* --bluefs_replay_recovery=true
+
+It is advised to first check if rescue process would be successfull::
+ ceph-bluestore-tool fsck --path *osd path* \
+ --bluefs_replay_recovery=true --bluefs_replay_recovery_disable_compact=true
+
+If above fsck is successfull fix procedure can be applied.
+
+Availability
+============
+
+**ceph-bluestore-tool** is part of Ceph, a massively scalable,
+open-source, distributed storage system. Please refer to the Ceph
+documentation at http://ceph.com/docs for more information.
+
+
+See also
+========
+
+:doc:`ceph-osd <ceph-osd>`\(8)