1CEPH-VOLUME(8) Ceph CEPH-VOLUME(8)
2
6 ceph-volume - Ceph OSD deployment and inspection tool
7
9 ceph-volume [-h] [--cluster CLUSTER] [--log-level LOG_LEVEL]
10 [--log-path LOG_PATH]
11 ceph-volume inventory
13 ceph-volume lvm [ trigger | create | activate | prepare
15 zap | list | batch]
16 ceph-volume simple [ trigger | scan | activate ]
18
21 ceph-volume is a single purpose command line tool to deploy logical
22 volumes as OSDs, trying to maintain a similar API to ceph-disk when
23 preparing, activating, and creating OSDs.
24 It deviates from ceph-disk by not interacting or relying on the udev
26 rules that come installed for Ceph. These rules allow automatic detec‐
27 tion of previously setup devices that are in turn fed into ceph-disk to
28 activate them.
29
31 inventory
32 This subcommand provides information about a host's physical disc in‐
33 ventory and reports metadata about these discs. Among this metadata one
34 can find disc specific data items (like model, size, rotational or
35 solid state) as well as data items specific to ceph using a device,
36 such as if it is available for use with ceph or if logical volumes are
37 present.
38 Examples:
40 ceph-volume inventory
42 ceph-volume inventory /dev/sda
43 ceph-volume inventory --format json-pretty
44 Optional arguments:
46 • [-h, --help] show the help message and exit
48 •
50 [--format] report format, valid values are plain (default),
52 json and json-pretty
53 lvm
55 By making use of LVM tags, the lvm sub-command is able to store and
56 later re-discover and query devices associated with OSDs so that they
57 can later activated.
58 Subcommands:
60 batch Creates OSDs from a list of devices using a filestore or blue‐
62 store (default) setup. It will create all necessary volume groups and
63 logical volumes required to have a working OSD.
64 Example usage with three devices:
66 ceph-volume lvm batch --bluestore /dev/sda /dev/sdb /dev/sdc
68 Optional arguments:
70 • [-h, --help] show the help message and exit
72 • [--bluestore] Use the bluestore objectstore (default)
74 • [--filestore] Use the filestore objectstore
76 • [--yes] Skip the report and prompt to continue provi‐
78 sioning
79 • [--prepare] Only prepare OSDs, do not activate
81 • [--dmcrypt] Enable encryption for the underlying OSD de‐
83 vices
84 • [--crush-device-class] Define a CRUSH device class to assign the OSD
86 to
87 • [--no-systemd] Do not enable or create any systemd units
89 • [--osds-per-device] Provision more than 1 (the default) OSD per de‐
91 vice
92 • [--report] Report what the potential outcome would be for the
94 current input (requires devices to be passed in)
95 • [--format] Output format when reporting (used along with
97 --report), can be one of 'pretty' (default) or 'json'
98 • [--block-db-size] Set (or override) the "bluestore_block_db_size"
100 value, in bytes
101 • [--journal-size] Override the "osd_journal_size" value, in
103 megabytes
104 Required positional arguments:
106 •
108 <DEVICE> Full path to a raw device, like /dev/sda. Multiple
110 <DEVICE> paths can be passed in.
111 activate Enables a systemd unit that persists the OSD ID and its UUID
113 (also called fsid in Ceph CLI tools), so that at boot time it can un‐
114 derstand what OSD is enabled and needs to be mounted.
115 Usage:
117 ceph-volume lvm activate --bluestore <osd id> <osd fsid>
119 Optional Arguments:
121 • [-h, --help] show the help message and exit
123 • [--auto-detect-objectstore] Automatically detect the objectstore by
125 inspecting the OSD
126 • [--bluestore] bluestore objectstore (default)
128 • [--filestore] filestore objectstore
130 • [--all] Activate all OSDs found in the system
132 • [--no-systemd] Skip creating and enabling systemd units and starting
134 of OSD services
135 Multiple OSDs can be activated at once by using the (idempotent) --all
137 flag:
138 ceph-volume lvm activate --all
140 prepare Prepares a logical volume to be used as an OSD and journal us‐
142 ing a filestore or bluestore (default) setup. It will not create or
143 modify the logical volumes except for adding extra metadata.
144 Usage:
146 ceph-volume lvm prepare --filestore --data <data lv> --journal <journal device>
148 Optional arguments:
150 • [-h, --help] show the help message and exit
152 • [--journal JOURNAL] A logical group name, path to a logical volume,
154 or path to a device
155 • [--bluestore] Use the bluestore objectstore (default)
157 • [--block.wal] Path to a bluestore block.wal logical volume or
159 partition
160 • [--block.db] Path to a bluestore block.db logical volume or
162 partition
163 • [--filestore] Use the filestore objectstore
165 • [--dmcrypt] Enable encryption for the underlying OSD de‐
167 vices
168 • [--osd-id OSD_ID] Reuse an existing OSD id
170 • [--osd-fsid OSD_FSID] Reuse an existing OSD fsid
172 • [--crush-device-class] Define a CRUSH device class to assign the OSD
174 to
175 Required arguments:
177 •
179 --data A logical group name or a path to a logical volume
181 For encrypting an OSD, the --dmcrypt flag must be added when preparing
183 (also supported in the create sub-command).
184 create Wraps the two-step process to provision a new osd (calling pre‐
186 pare first and then activate) into a single one. The reason to prefer
187 prepare and then activate is to gradually introduce new OSDs into a
188 cluster, and avoiding large amounts of data being rebalanced.
189 The single-call process unifies exactly what prepare and activate do,
191 with the convenience of doing it all at once. Flags and general usage
192 are equivalent to those of the prepare and activate subcommand.
193 trigger This subcommand is not meant to be used directly, and it is
195 used by systemd so that it proxies input to ceph-volume lvm activate by
196 parsing the input from systemd, detecting the UUID and ID associated
197 with an OSD.
198 Usage:
200 ceph-volume lvm trigger <SYSTEMD-DATA>
202 The systemd "data" is expected to be in the format of:
204 <OSD ID>-<OSD UUID>
206 The lvs associated with the OSD need to have been prepared previously,
208 so that all needed tags and metadata exist.
209 Positional arguments:
211 • <SYSTEMD_DATA> Data from a systemd unit containing ID and UUID of
213 the OSD.
214 list List devices or logical volumes associated with Ceph. An associa‐
216 tion is determined if a device has information relating to an OSD. This
217 is verified by querying LVM's metadata and correlating it with devices.
218 The lvs associated with the OSD need to have been prepared previously
220 by ceph-volume so that all needed tags and metadata exist.
221 Usage:
223 ceph-volume lvm list
225 List a particular device, reporting all metadata about it:
227 ceph-volume lvm list /dev/sda1
229 List a logical volume, along with all its metadata (vg is a volume
231 group, and lv the logical volume name):
232 ceph-volume lvm list {vg/lv}
234 Positional arguments:
236 • <DEVICE> Either in the form of vg/lv for logical volumes,
238 /path/to/sda1 or /path/to/sda for regular devices.
239 zap Zaps the given logical volume or partition. If given a path to a
241 logical volume it must be in the format of vg/lv. Any file systems
242 present on the given lv or partition will be removed and all data will
243 be purged.
244 However, the lv or partition will be kept intact.
246 Usage, for logical volumes:
248 ceph-volume lvm zap {vg/lv}
250 Usage, for logical partitions:
252 ceph-volume lvm zap /dev/sdc1
254 For full removal of the device use the --destroy flag (allowed for all
256 device types):
257 ceph-volume lvm zap --destroy /dev/sdc1
259 Multiple devices can be removed by specifying the OSD ID and/or the OSD
261 FSID:
262 ceph-volume lvm zap --destroy --osd-id 1
264 ceph-volume lvm zap --destroy --osd-id 1 --osd-fsid C9605912-8395-4D76-AFC0-7DFDAC315D59
265 Positional arguments:
267 • <DEVICE> Either in the form of vg/lv for logical volumes,
269 /path/to/sda1 or /path/to/sda for regular devices.
270 simple
272 Scan legacy OSD directories or data devices that may have been created
273 by ceph-disk, or manually.
274 Subcommands:
276 activate Enables a systemd unit that persists the OSD ID and its UUID
278 (also called fsid in Ceph CLI tools), so that at boot time it can un‐
279 derstand what OSD is enabled and needs to be mounted, while reading in‐
280 formation that was previously created and persisted at /etc/ceph/osd/
281 in JSON format.
282 Usage:
284 ceph-volume simple activate --bluestore <osd id> <osd fsid>
286 Optional Arguments:
288 • [-h, --help] show the help message and exit
290 • [--bluestore] bluestore objectstore (default)
292 • [--filestore] filestore objectstore
294 Note: It requires a matching JSON file with the following format:
296 /etc/ceph/osd/<osd id>-<osd fsid>.json
298 scan Scan a running OSD or data device for an OSD for metadata that can
300 later be used to activate and manage the OSD with ceph-volume. The scan
301 method will create a JSON file with the required information plus any‐
302 thing found in the OSD directory as well.
303 Optionally, the JSON blob can be sent to stdout for further inspection.
305 Usage on all running OSDs:
307 ceph-volume simple scan
309 Usage on data devices:
311 ceph-volume simple scan <data device>
313 Running OSD directories:
315 ceph-volume simple scan <path to osd dir>
317 Optional arguments:
319 • [-h, --help] show the help message and exit
321 • [--stdout] Send the JSON blob to stdout
323 • [--force] If the JSON file exists at destination, over‐
325 write it
326 Optional Positional arguments:
328 • <DATA DEVICE or OSD DIR> Actual data partition or a path to the run‐
330 ning OSD
331 trigger This subcommand is not meant to be used directly, and it is
333 used by systemd so that it proxies input to ceph-volume simple activate
334 by parsing the input from systemd, detecting the UUID and ID associated
335 with an OSD.
336 Usage:
338 ceph-volume simple trigger <SYSTEMD-DATA>
340 The systemd "data" is expected to be in the format of:
342 <OSD ID>-<OSD UUID>
344 The JSON file associated with the OSD need to have been persisted pre‐
346 viously by a scan (or manually), so that all needed metadata can be
347 used.
348 Positional arguments:
350 • <SYSTEMD_DATA> Data from a systemd unit containing ID and UUID of
352 the OSD.
353
355 ceph-volume is part of Ceph, a massively scalable, open-source, dis‐
356 tributed storage system. Please refer to the documentation at
357 http://docs.ceph.com/ for more information.
358
360 ceph-osd(8),
361
363 2010-2021, Inktank Storage, Inc. and contributors. Licensed under Cre‐
364 ative Commons Attribution Share Alike 3.0 (CC-BY-SA-3.0)
365dev May 13, 2021 CEPH-VOLUME(8)