[ceph.git] / ceph / doc / man / 8 / ceph-volume.rst

:orphan:

========================================
 ceph-volume -- Ceph OSD deployment tool
========================================

.. program:: ceph-volume

Synopsis
========

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

| **ceph-volume** **lvm** [ *trigger* | *create* | *activate* | *prepare*
| *zap* | *list* | *batch*]

| **ceph-volume** **simple** [ *trigger* | *scan* | *activate* ]


Description
===========

:program:`ceph-volume` is a single purpose command line tool to deploy logical
volumes as OSDs, trying to maintain a similar API to ``ceph-disk`` when
preparing, activating, and creating OSDs.

It deviates from ``ceph-disk`` by not interacting or relying on the udev rules
that come installed for Ceph. These rules allow automatic detection of
previously setup devices that are in turn fed into ``ceph-disk`` to activate
them.


Commands
========

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
activated.

Subcommands:

**batch**
Creates OSDs from a list of devices using a ``filestore``
or ``bluestore`` (default) setup. It will create all necessary volume groups
and logical volumes required to have a working OSD.

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)
* [--filestore]         Use the filestore objectstore
* [--yes]               Skip the report and prompt to continue provisioning
* [--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
* [--report]         Report what the potential outcome would be for the
                     current input (requires devices to be passed in)
* [--format]         Output format when reporting (used along with
                     --report), can be one of 'pretty' (default) or 'json'

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 objecstore by inspecting
  the OSD
* [--bluestore] bluestore objectstore (default)
* [--filestore] filestore objectstore
* [--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 ``filestore``
or ``bluestore`` (default) setup. It will not create or modify the logical volumes
except for adding extra metadata.

Usage::

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

Optional arguments:

* [-h, --help]          show the help message and exit
* [--journal JOURNAL]   A 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
* [--filestore]         Use the filestore objectstore
* [--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

For encrypting an OSD, the ``--dmcrypt`` flag must be added when preparing
(also supported in the ``create`` sub-command).


**create**
Wraps the two-step process to provision 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
avoiding large amounts of data being rebalanced.

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

**trigger**
This subcommand is not meant to be used directly, and it is 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 needed tags and metadata exist.

Positional arguments:

* <SYSTEMD_DATA>  Data from a systemd unit containing ID and UUID of the OSD.

**list**
List 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 needed tags and metadata exist.

Usage::

    ceph-volume lvm list

List a particular device, reporting all 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 given a path to a logical
volume it must be in the format of vg/lv. Any filesystems present
on the given lv or partition will be removed and all data will be purged.

However, the lv or partition will be kept intact.

Usage, for logical volumes::

      ceph-volume lvm zap {vg/lv}

Usage, for logical partitions::

      ceph-volume lvm zap /dev/sdc1

Positional arguments:

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


simple
------

Scan legacy OSD directories or data devices that may have been created by
ceph-disk, or manually.

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 reading 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)
* [--filestore] filestore objectstore

Note: It requires a matching JSON file with the following format::

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


**scan**
Scan a running OSD or data device for an OSD for metadata that can later be
used to activate and manage the OSD with ceph-volume. The scan method will
create a JSON file with the required information plus anything found in the OSD
directory as well.

Optionally, the JSON blob can be sent to stdout for further inspection.

Usage on data devices::

    ceph-volume simple scan <data device>

Running OSD directories::

    ceph-volume simple scan <path to osd dir>


Optional arguments:

* [-h, --help]          show the help message and exit
* [--stdout]            Send the JSON blob to stdout
* [--force]             If the JSON file exists at destination, overwrite it

Required Positional arguments:

* <DATA DEVICE or OSD DIR>  Actual data partition or a path to the running OSD

**trigger**
This subcommand is not meant to be used directly, and it is used by systemd so
that it proxies input to ``ceph-volume simple activate`` by parsing the
input from systemd, detecting the UUID and ID associated with an OSD.

Usage::

    ceph-volume simple trigger <SYSTEMD-DATA>

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

    <OSD ID>-<OSD UUID>

The JSON file associated with the OSD need to have been persisted previously by
a scan (or manually), so that all needed metadata can be used.

Positional arguments:

* <SYSTEMD_DATA>  Data from a systemd unit containing ID and UUID of the OSD.


Availability
============

:program:`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.


See also
========

:doc:`ceph-osd <ceph-osd>`\(8),
:doc:`ceph-disk <ceph-disk>`\(8),
Commit	Line	Data
b5b8bbf5 FG	1	:orphan:
	2
	3	========================================
	4	ceph-volume -- Ceph OSD deployment tool
	5	========================================
	6
	7	.. program:: ceph-volume
	8
	9	Synopsis
	10	========
	11
	12	\| ceph-volume [-h] [--cluster CLUSTER] [--log-level LOG_LEVEL]
	13	\| [--log-path LOG_PATH]
	14
b32b8144	15	\| ceph-volume lvm [ trigger \| create \| activate \| prepare
1adf2230	16	\| zap \| list \| batch]
b32b8144 FG	17
	18	\| ceph-volume simple [ trigger \| scan \| activate ]
	19
b5b8bbf5 FG	20
	21	Description
	22	===========
	23
	24	:program:`ceph-volume` is a single purpose command line tool to deploy logical
	25	volumes as OSDs, trying to maintain a similar API to ``ceph-disk`` when
	26	preparing, activating, and creating OSDs.
	27
	28	It deviates from ``ceph-disk`` by not interacting or relying on the udev rules
	29	that come installed for Ceph. These rules allow automatic detection of
	30	previously setup devices that are in turn fed into ``ceph-disk`` to activate
	31	them.
	32
	33
	34	Commands
	35	========
	36
	37	lvm
	38	---
	39
	40	By making use of LVM tags, the ``lvm`` sub-command is able to store and later
	41	re-discover and query devices associated with OSDs so that they can later
	42	activated.
	43
	44	Subcommands:
	45
1adf2230 AA	46	batch
	47	Creates OSDs from a list of devices using a ``filestore``
	48	or ``bluestore`` (default) setup. It will create all necessary volume groups
	49	and logical volumes required to have a working OSD.
	50
	51	Example usage with three devices::
	52
	53	ceph-volume lvm batch --bluestore /dev/sda /dev/sdb /dev/sdc
	54
	55	Optional arguments:
	56
	57	* [-h, --help] show the help message and exit
	58	* [--bluestore] Use the bluestore objectstore (default)
	59	* [--filestore] Use the filestore objectstore
	60	* [--yes] Skip the report and prompt to continue provisioning
	61	* [--dmcrypt] Enable encryption for the underlying OSD devices
	62	* [--crush-device-class] Define a CRUSH device class to assign the OSD to
	63	* [--no-systemd] Do not enable or create any systemd units
	64	* [--report] Report what the potential outcome would be for the
	65	current input (requires devices to be passed in)
	66	* [--format] Output format when reporting (used along with
	67	--report), can be one of 'pretty' (default) or 'json'
	68
	69	Required positional arguments:
	70
	71	* <DEVICE> Full path to a raw device, like ``/dev/sda``. Multiple
	72	``<DEVICE>`` paths can be passed in.
	73
	74
b5b8bbf5 FG	75	activate
	76	Enables a systemd unit that persists the OSD ID and its UUID (also called
	77	``fsid`` in Ceph CLI tools), so that at boot time it can understand what OSD is
	78	enabled and needs to be mounted.
	79
	80	Usage::
	81
94b18763	82	ceph-volume lvm activate --bluestore <osd id> <osd fsid>
b5b8bbf5 FG	83
	84	Optional Arguments:
	85
	86	* [-h, --help] show the help message and exit
94b18763 FG	87	* [--auto-detect-objectstore] Automatically detect the objecstore by inspecting
	88	the OSD
	89	* [--bluestore] bluestore objectstore (default)
	90	* [--filestore] filestore objectstore
	91	* [--all] Activate all OSDs found in the system
	92	* [--no-systemd] Skip creating and enabling systemd units and starting of OSD
	93	services
b5b8bbf5	94
28e407b8 AA	95	Multiple OSDs can be activated at once by using the (idempotent) ``--all`` flag::
	96
	97	ceph-volume lvm activate --all
	98
b5b8bbf5 FG	99
b5b8bbf5 FG	100	prepare
94b18763 FG	101	Prepares a logical volume to be used as an OSD and journal using a ``filestore``
94b18763 FG	102	or ``bluestore`` (default) setup. It will not create or modify the logical volumes
b5b8bbf5 FG	103	except for adding extra metadata.
	104
	105	Usage::
	106
	107	ceph-volume lvm prepare --filestore --data <data lv> --journal <journal device>
	108
	109	Optional arguments:
	110
	111	* [-h, --help] show the help message and exit
	112	* [--journal JOURNAL] A logical group name, path to a logical volume, or path to a device
b32b8144	113	* [--bluestore] Use the bluestore objectstore (default)
94b18763 FG	114	* [--block.wal] Path to a bluestore block.wal logical volume or partition
94b18763 FG	115	* [--block.db] Path to a bluestore block.db logical volume or partition
b32b8144 FG	116	* [--filestore] Use the filestore objectstore
b32b8144 FG	117	* [--dmcrypt] Enable encryption for the underlying OSD devices
b5b8bbf5 FG	118	* [--osd-id OSD_ID] Reuse an existing OSD id
b5b8bbf5 FG	119	* [--osd-fsid OSD_FSID] Reuse an existing OSD fsid
94b18763	120	* [--crush-device-class] Define a CRUSH device class to assign the OSD to
b5b8bbf5 FG	121
	122	Required arguments:
	123
	124	* --data A logical group name or a path to a logical volume
	125
28e407b8 AA	126	For encrypting an OSD, the ``--dmcrypt`` flag must be added when preparing
	127	(also supported in the ``create`` sub-command).
	128
	129
b5b8bbf5 FG	130	create
	131	Wraps the two-step process to provision a new osd (calling ``prepare`` first
	132	and then ``activate``) into a single one. The reason to prefer ``prepare`` and
	133	then ``activate`` is to gradually introduce new OSDs into a cluster, and
	134	avoiding large amounts of data being rebalanced.
	135
	136	The single-call process unifies exactly what ``prepare`` and ``activate`` do,
	137	with the convenience of doing it all at once. Flags and general usage are
94b18763	138	equivalent to those of the ``prepare`` and ``activate`` subcommand.
b5b8bbf5 FG	139
	140	trigger
	141	This subcommand is not meant to be used directly, and it is used by systemd so
	142	that it proxies input to ``ceph-volume lvm activate`` by parsing the
	143	input from systemd, detecting the UUID and ID associated with an OSD.
	144
	145	Usage::
	146
	147	ceph-volume lvm trigger <SYSTEMD-DATA>
	148
	149	The systemd "data" is expected to be in the format of::
	150
	151	<OSD ID>-<OSD UUID>
	152
	153	The lvs associated with the OSD need to have been prepared previously,
	154	so that all needed tags and metadata exist.
	155
	156	Positional arguments:
	157
	158	* <SYSTEMD_DATA> Data from a systemd unit containing ID and UUID of the OSD.
	159
b32b8144 FG	160	list
	161	List devices or logical volumes associated with Ceph. An association is
	162	determined if a device has information relating to an OSD. This is
	163	verified by querying LVM's metadata and correlating it with devices.
	164
	165	The lvs associated with the OSD need to have been prepared previously by
	166	ceph-volume so that all needed tags and metadata exist.
	167
	168	Usage::
	169
	170	ceph-volume lvm list
	171
	172	List a particular device, reporting all metadata about it::
	173
	174	ceph-volume lvm list /dev/sda1
	175
	176	List a logical volume, along with all its metadata (vg is a volume
	177	group, and lv the logical volume name)::
	178
	179	ceph-volume lvm list {vg/lv}
	180
	181	Positional arguments:
	182
94b18763 FG	183	* <DEVICE> Either in the form of ``vg/lv`` for logical volumes,
94b18763 FG	184	``/path/to/sda1`` or ``/path/to/sda`` for regular devices.
b32b8144 FG	185
	186
	187	zap
	188	Zaps the given logical volume or partition. If given a path to a logical
	189	volume it must be in the format of vg/lv. Any filesystems present
	190	on the given lv or partition will be removed and all data will be purged.
	191
	192	However, the lv or partition will be kept intact.
	193
	194	Usage, for logical volumes::
	195
	196	ceph-volume lvm zap {vg/lv}
	197
	198	Usage, for logical partitions::
	199
	200	ceph-volume lvm zap /dev/sdc1
	201
	202	Positional arguments:
	203
94b18763 FG	204	* <DEVICE> Either in the form of ``vg/lv`` for logical volumes,
94b18763 FG	205	``/path/to/sda1`` or ``/path/to/sda`` for regular devices.
b32b8144 FG	206
	207
	208	simple
	209	------
	210
	211	Scan legacy OSD directories or data devices that may have been created by
	212	ceph-disk, or manually.
	213
	214	Subcommands:
	215
	216	activate
	217	Enables a systemd unit that persists the OSD ID and its UUID (also called
	218	``fsid`` in Ceph CLI tools), so that at boot time it can understand what OSD is
	219	enabled and needs to be mounted, while reading information that was previously
	220	created and persisted at ``/etc/ceph/osd/`` in JSON format.
	221
	222	Usage::
	223
	224	ceph-volume simple activate --bluestore <osd id> <osd fsid>
	225
	226	Optional Arguments:
	227
	228	* [-h, --help] show the help message and exit
	229	* [--bluestore] bluestore objectstore (default)
	230	* [--filestore] filestore objectstore
	231
	232	Note: It requires a matching JSON file with the following format::
	233
	234	/etc/ceph/osd/<osd id>-<osd fsid>.json
	235
	236
	237	scan
	238	Scan a running OSD or data device for an OSD for metadata that can later be
	239	used to activate and manage the OSD with ceph-volume. The scan method will
	240	create a JSON file with the required information plus anything found in the OSD
	241	directory as well.
	242
	243	Optionally, the JSON blob can be sent to stdout for further inspection.
	244
	245	Usage on data devices::
	246
	247	ceph-volume simple scan <data device>
	248
	249	Running OSD directories::
	250
	251	ceph-volume simple scan <path to osd dir>
	252
	253
	254	Optional arguments:
	255
	256	* [-h, --help] show the help message and exit
	257	* [--stdout] Send the JSON blob to stdout
	258	* [--force] If the JSON file exists at destination, overwrite it
	259
	260	Required Positional arguments:
	261
	262	* <DATA DEVICE or OSD DIR> Actual data partition or a path to the running OSD
	263
	264	trigger
	265	This subcommand is not meant to be used directly, and it is used by systemd so
	266	that it proxies input to ``ceph-volume simple activate`` by parsing the
	267	input from systemd, detecting the UUID and ID associated with an OSD.
	268
	269	Usage::
270
271	ceph-volume simple trigger <SYSTEMD-DATA>
272
273	The systemd "data" is expected to be in the format of::
274
275	<OSD ID>-<OSD UUID>
276
277	The JSON file associated with the OSD need to have been persisted previously by
278	a scan (or manually), so that all needed metadata can be used.
279
280	Positional arguments:
281
282	* <SYSTEMD_DATA> Data from a systemd unit containing ID and UUID of the OSD.
283
284
b5b8bbf5 FG	285	Availability
	286	============
	287
	288	:program:`ceph-volume` is part of Ceph, a massively scalable, open-source, distributed storage system. Please refer to
	289	the documentation at http://docs.ceph.com/ for more information.
	290
	291
	292	See also
	293	========
	294
	295	:doc:`ceph-osd <ceph-osd>`\(8),
	296	:doc:`ceph-disk <ceph-disk>`\(8),