CEPH-VOLUME(8)

💖 CEPH-VOLUME(8) 💖

okay bestie, gather round 🫶 this is the manual page for ceph-volume, straight out of the Ceph docs (section 8, admin girlies only). it's giving "deploy my OSDs" energy and honestly? obsessed. let's gooo 💅

🎀 NAME 🎀

ceph-volume — the Ceph OSD deployment and inspection tool ✨

🌸 SYNOPSIS 🌸

ceph-volume [-h] [--cluster CLUSTER] [--log-level LOG_LEVEL] [--log-path LOG_PATH]

ceph-volume inventory

ceph-volume lvm [ trigger | create | activate | prepare | zap | list | batch | new-wal | new-db | migrate ]

ceph-volume simple [ trigger | scan | activate ]

💅 DESCRIPTION 💅

so, ceph-volume is a single purpose command line tool whose whole job is deploying logical volumes as OSDs. it tries to maintain a similar API to ceph-disk when it's preparing, activating, and creating OSDs — so if you already know ceph-disk, the vibes will feel familiar.

where does it deviate from ceph-disk? it does not interact with or rely on the udev rules that come installed for Ceph. those rules are what allow automatic detection of previously setup devices, which then get fed into ceph-disk to activate them. ceph-volume said "not me, I handle my own business" 💅

🔥 COMMANDS 🔥

🔍 inventory

this subcommand gives you the tea on a host's physical disc inventory and reports metadata about those discs. among that metadata you'll find disc-specific data items (like the model, the size, whether it's rotational or solid state) plus data items specific to ceph using a device — like whether it's available for use with ceph, or whether logical volumes are present. full download on every disc 🦋

examples:

ceph-volume inventory
ceph-volume inventory /dev/sda
ceph-volume inventory --format json-pretty

optional arguments:

-h, --help — show the help message and exit
--format — the report format. valid values are plain (the default), json and json-pretty

🧚 lvm

by making use of LVM tags, the lvm sub-command is able to store and later re-discover and query devices associated with OSDs, so that they can later be activated. it remembers its friends 💜

subcommands:

✨ batch

creates OSDs from a list of devices using a bluestore (default) setup. it will create all the necessary volume groups and logical volumes required to have a working OSD. one command, whole working OSD. slay.

example usage with three devices:

ceph-volume lvm batch --bluestore /dev/sda /dev/sdb /dev/sdc

optional arguments:

-h, --help — show the help message and exit
--bluestore — use the bluestore objectstore (default)
--yes — skip the report and the prompt to continue provisioning
--prepare — only prepare OSDs, do not activate
--dmcrypt — enable encryption for the underlying OSD devices
--crush-device-class — define a CRUSH device class to assign the OSD to
--no-systemd — do not enable or create any systemd units
--osds-per-device — provision more than 1 (the default) OSD per device
--report — report what the potential outcome would be for the current input (requires devices to be passed in)
--format — the output format when reporting (used along with --report), can be one of 'pretty' (default) or 'json'
--block-db-size — set (or override) the "bluestore_block_db_size" value, in bytes
--journal-size — override the "osd_journal_size" value, in megabytes

required positional arguments:

<DEVICE> — full path to a raw device, like /dev/sda. multiple <DEVICE> paths can be passed in.

🔥 activate

enables a systemd unit that persists the OSD ID and its UUID (also called fsid in Ceph CLI tools), so that at boot time it can understand what OSD is enabled and needs to be mounted.

usage:

ceph-volume lvm activate --bluestore <osd id> <osd fsid>

optional Arguments:

-h, --help — show the help message and exit
--auto-detect-objectstore — automatically detect the objectstore by inspecting the OSD
--bluestore — bluestore objectstore (default)
--all — activate all OSDs found in the system
--no-systemd — skip creating and enabling systemd units and starting of OSD services

multiple OSDs can be activated at once by using the (idempotent) --all flag:

ceph-volume lvm activate --all

🎀 prepare

prepares a logical volume to be used as an OSD and journal using a bluestore (default) setup. it will not create or modify the logical volumes, except for adding extra metadata.

usage:

ceph-volume lvm prepare --bluestore --data <data lv> --journal <journal device>

optional arguments:

-h, --help — show the help message and exit
--journal JOURNAL — logical group name, path to a logical volume, or path to a device
--bluestore — use the bluestore objectstore (default)
--block.wal — path to a bluestore block.wal logical volume or partition
--block.db — path to a bluestore block.db logical volume or partition
--dmcrypt — enable encryption for the underlying OSD devices
--osd-id OSD_ID — reuse an existing OSD id
--osd-fsid OSD_FSID — reuse an existing OSD fsid
--crush-device-class — define a CRUSH device class to assign the OSD to

required arguments:

--data — a logical group name or a path to a logical volume

and bestie, for encrypting an OSD, the --dmcrypt flag must be added when preparing (it's also supported in the create sub-command).

🦋 create

wraps the two-step process of provisioning a new osd (calling prepare first and then activate) into a single one. the reason to prefer prepare and then activate is to gradually introduce new OSDs into a cluster, and to avoid large amounts of data being rebalanced. like, nobody wants a surprise rebalance, fr fr 😭

the single-call process unifies exactly what prepare and activate do, with the convenience of doing it all at once. the flags and general usage are equivalent to those of the prepare and activate subcommand.

💜 trigger

this subcommand is not meant to be used directly — it's used by systemd, so that it proxies input to ceph-volume lvm activate by parsing the input from systemd, detecting the UUID and ID associated with an OSD.

usage:

ceph-volume lvm trigger <SYSTEMD-DATA>

the systemd "data" is expected to be in the format of:

<OSD ID>-<OSD UUID>

the lvs associated with the OSD need to have been prepared previously, so that all the needed tags and metadata exist.

positional arguments:

<SYSTEMD_DATA> — data from a systemd unit containing the ID and UUID of the OSD.

⭐ list

lists devices or logical volumes associated with Ceph. an association is determined if a device has information relating to an OSD. this is verified by querying LVM's metadata and correlating it with devices.

the lvs associated with the OSD need to have been prepared previously by ceph-volume so that all the needed tags and metadata exist.

usage:

ceph-volume lvm list

list a particular device, reporting all the metadata about it:

ceph-volume lvm list /dev/sda1

list a logical volume, along with all its metadata (vg is a volume group, and lv the logical volume name):

ceph-volume lvm list {vg/lv}

positional arguments:

<DEVICE> — either in the form of vg/lv for logical volumes, /path/to/sda1 or /path/to/sda for regular devices.

💀 zap

zaps the given logical volume or partition. if you hand it a path to a logical volume it must be in the format of vg/lv. any file systems present on the given lv or partition will be removed and all data will be purged.

however — and this part matters — the lv or partition will be kept intact. it just gets its whole soul wiped. 💅

usage, for logical volumes:

ceph-volume lvm zap {vg/lv}

usage, for logical partitions:

ceph-volume lvm zap /dev/sdc1

for full removal of the device, use the --destroy flag (allowed for all device types):

ceph-volume lvm zap --destroy /dev/sdc1

multiple devices can be removed by specifying the OSD ID and/or the OSD FSID:

ceph-volume lvm zap --destroy --osd-id 1
ceph-volume lvm zap --destroy --osd-id 1 --osd-fsid C9605912-8395-4D76-AFC0-7DFDAC315D59

bestie, mind the --destroy energy here. purging data is one thing, but full removal of the device is another thing entirely. 👀

positional arguments:

<DEVICE> — either in the form of vg/lv for logical volumes, /path/to/sda1 or /path/to/sda for regular devices.

🌈 new-wal

attaches the given logical volume to an OSD as a WAL. the logical volume name format is vg/lv. it fails if the OSD has already got an attached WAL.

usage:

ceph-volume lvm new-wal --osd-id OSD_ID --osd-fsid OSD_FSID --target <target lv>

optional arguments:

-h, --help — show the help message and exit
--no-systemd — skip checking OSD systemd unit

required arguments:

--target — logical volume name to attach as WAL

🍓 new-db

attaches the given logical volume to an OSD as a DB. the logical volume name format is vg/lv. it fails if the OSD has already got an attached DB.

usage:

ceph-volume lvm new-db --osd-id OSD_ID --osd-fsid OSD_FSID --target <target lv>

optional arguments:

-h, --help — show the help message and exit
--no-systemd — skip checking OSD systemd unit

required arguments:

--target — logical volume name to attach as DB

👑 migrate

moves BlueFS data from the source volume(s) to the target one, and the source volumes (except the main one, i.e. the data or block one) are removed on success. LVM volumes are permitted for the Target only, whether it's already attached or a new one. in the latter case it gets attached to the OSD, replacing one of the source devices.

the following replacement rules apply, in the order of precedence, stopping on the first match:

if the source list has a DB volume — the target device replaces it.
if the source list has a WAL volume — the target device replaces it.
if the source list has a slow volume only — the operation is not permitted, and requires explicit allocation via the new-db/new-wal command.

usage:

ceph-volume lvm migrate --osd-id OSD_ID --osd-fsid OSD_FSID --target <target lv> --from {data|db|wal} [{data|db|wal} ...]

optional arguments:

-h, --help — show the help message and exit
--no-systemd — skip checking OSD systemd unit

required arguments:

--from — list of source device type names
--target — logical volume to move data to

🌸 simple

scans legacy OSD directories, or data devices that may have been created by ceph-disk, or manually. archaeology, but make it storage. 🧚

subcommands:

🎀 activate

enables a systemd unit that persists the OSD ID and its UUID (also called fsid in Ceph CLI tools), so that at boot time it can understand what OSD is enabled and needs to be mounted, while it reads information that was previously created and persisted at /etc/ceph/osd/ in JSON format.

usage:

ceph-volume simple activate --bluestore <osd id> <osd fsid>

optional Arguments:

-h, --help — show the help message and exit
--bluestore — bluestore objectstore (default)

note: it requires a matching JSON file with the following format:

/etc/ceph/osd/<osd id>-<osd fsid>.json

🌸 `scan` 🌸

okay so scan is the little detective of the simple family 🔍 — it goes sniffing around a running OSD or a data device for an OSD and pulls out all the metadata you're gonna need later to activate and manage that OSD with ceph-volume. And bestie, it doesn't just grab the basics: it makes a JSON file with everything required, plus anything else it finds chilling in the OSD directory too. thorough queen 💅

And if you wanna peek at the receipts yourself, you can optionally yeet that JSON blob straight to stdout for further inspection 👀✨

Usage when you wanna hit all the running OSDs:

ceph-volume simple scan

Usage on data devices:

ceph-volume simple scan <data device>

And for running OSD directories:

ceph-volume simple scan <path to osd dir>

Optional arguments:

-h, --help — shows the help message and dips out (exit) 🫶
--stdout — sends the JSON blob to stdout, no cap 📤
--force — if the JSON file already exists at the destination, this overwrites it. lowkey ruthless but sometimes necessary 💀

Optional Positional arguments:

<DATA DEVICE or OSD DIR> — the actual data partition, or a path to the running OSD 🌈

🌸 `trigger` 🌸

so trigger is not meant to be used directly, periodt 🙅‍♀️ it's a backstage-pass situation — systemd uses it, and what it does is proxy input over to ceph-volume simple activate by parsing the input coming from systemd, detecting the UUID and ID associated with an OSD. it's giving middle-manager energy but like, in a helpful way 💜

Usage:

ceph-volume simple trigger <SYSTEMD-DATA>

the systemd "data" is expected to arrive looking exactly like this, bestie:

<OSD ID>-<OSD UUID>

⚠️ heads up: the JSON file associated with the OSD needs to have been persisted previously by a scan (or manually 👀) so that all the needed metadata is actually there to be used. no file, no vibes, no activation. 🙈

Positional arguments:

<SYSTEMD_DATA> — data from a systemd unit containing the ID and UUID of the OSD 🎀

✨ AVAILABILITY ✨

ceph-volume is part of Ceph, a massively scalable, open-source, distributed storage system 🌍🦋 please refer to the documentation at http://docs.ceph.com/ for more information — it's the main character source of truth, iykyk 💖

👑 SEE ALSO 👑

ceph-osd <>(8),

🎀 Copyright 🎀

2010-2014, Inktank Storage, Inc. and contributors. Licensed under Creative Commons Attribution Share Alike 3.0 (CC-BY-SA-3.0) 📜✨

and that's a wrap on this whole page, bestie 🫶 this one came from the dev source, version line CEPH-VOLUME(8), dated Oct 06, 2026 — go forth and manage your OSDs like the icon you are 💅🌈⭐

📦 where this page comes from

ubuntu stonking: ceph-volume 20.2.4+ds1-0ubuntu1 · LGPL2.1 (see COPYING-LGPL2.1
💖 girlified by deepseek-ai/DeepSeek-V4.1-Flash on 2026-11-03: a language model's rewrite of the original, under its terms

CEPH-VOLUME(8)

💖 CEPH-VOLUME(8) 💖

🎀 NAME 🎀

🌸 SYNOPSIS 🌸

💅 DESCRIPTION 💅

🔥 COMMANDS 🔥

🔍 inventory

🧚 lvm

✨ batch

🔥 activate

🎀 prepare

🦋 create

💜 trigger

⭐ list

💀 zap

🌈 new-wal

🍓 new-db

👑 migrate

🌸 simple

🎀 activate

🌸 scan 🌸

🌸 trigger 🌸

✨ AVAILABILITY ✨

👑 SEE ALSO 👑

🎀 Copyright 🎀

🌸 `scan` 🌸

🌸 `trigger` 🌸