ceph/doc/man/8/ceph-volume.rst

   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
  15 | **ceph-volume** **lvm** [ *trigger* | *create* | *activate* | *prepare*
  16 | *zap* | *list*]
  17
  18 | **ceph-volume** **simple** [ *trigger* | *scan* | *activate* ]
  19
  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
  46 **activate**
  47 Enables a systemd unit that persists the OSD ID and its UUID (also called
  48 ``fsid`` in Ceph CLI tools), so that at boot time it can understand what OSD is
  49 enabled and needs to be mounted.
  50
  51 Usage::
  52
  53     ceph-volume lvm activate --bluestore <osd id> <osd fsid>
  54
  55 Optional Arguments:
  56
  57 * [-h, --help]  show the help message and exit
  58 * [--auto-detect-objectstore] Automatically detect the objecstore by inspecting
  59   the OSD
  60 * [--bluestore] bluestore objectstore (default)
  61 * [--filestore] filestore objectstore
  62 * [--all] Activate all OSDs found in the system
  63 * [--no-systemd] Skip creating and enabling systemd units and starting of OSD
  64   services
  65
  66 Multiple OSDs can be activated at once by using the (idempotent) ``--all`` flag::
  67
  68     ceph-volume lvm activate --all
  69
  70
  71 **prepare**
  72 Prepares a logical volume to be used as an OSD and journal using a ``filestore``
  73 or ``bluestore`` (default) setup. It will not create or modify the logical volumes
  74 except for adding extra metadata.
  75
  76 Usage::
  77
  78     ceph-volume lvm prepare --filestore --data <data lv> --journal <journal device>
  79
  80 Optional arguments:
  81
  82 * [-h, --help]          show the help message and exit
  83 * [--journal JOURNAL]   A logical group name, path to a logical volume, or path to a device
  84 * [--bluestore]         Use the bluestore objectstore (default)
  85 * [--block.wal]         Path to a bluestore block.wal logical volume or partition
  86 * [--block.db]          Path to a bluestore block.db logical volume or partition
  87 * [--filestore]         Use the filestore objectstore
  88 * [--dmcrypt]           Enable encryption for the underlying OSD devices
  89 * [--osd-id OSD_ID]     Reuse an existing OSD id
  90 * [--osd-fsid OSD_FSID] Reuse an existing OSD fsid
  91 * [--crush-device-class] Define a CRUSH device class to assign the OSD to
  92
  93 Required arguments:
  94
  95 * --data                A logical group name or a path to a logical volume
  96
  97 For encrypting an OSD, the ``--dmcrypt`` flag must be added when preparing
  98 (also supported in the ``create`` sub-command).
  99
 100
 101 **create**
 102 Wraps the two-step process to provision a new osd (calling ``prepare`` first
 103 and then ``activate``) into a single one. The reason to prefer ``prepare`` and
 104 then ``activate`` is to gradually introduce new OSDs into a cluster, and
 105 avoiding large amounts of data being rebalanced.
 106
 107 The single-call process unifies exactly what ``prepare`` and ``activate`` do,
 108 with the convenience of doing it all at once. Flags and general usage are
 109 equivalent to those of the ``prepare`` and ``activate`` subcommand.
 110
 111 **trigger**
 112 This subcommand is not meant to be used directly, and it is used by systemd so
 113 that it proxies input to ``ceph-volume lvm activate`` by parsing the
 114 input from systemd, detecting the UUID and ID associated with an OSD.
 115
 116 Usage::
 117
 118     ceph-volume lvm trigger <SYSTEMD-DATA>
 119
 120 The systemd "data" is expected to be in the format of::
 121
 122     <OSD ID>-<OSD UUID>
 123
 124 The lvs associated with the OSD need to have been prepared previously,
 125 so that all needed tags and metadata exist.
 126
 127 Positional arguments:
 128
 129 * <SYSTEMD_DATA>  Data from a systemd unit containing ID and UUID of the OSD.
 130
 131 **list**
 132 List devices or logical volumes associated with Ceph. An association is
 133 determined if a device has information relating to an OSD. This is
 134 verified by querying LVM's metadata and correlating it with devices.
 135
 136 The lvs associated with the OSD need to have been prepared previously by
 137 ceph-volume so that all needed tags and metadata exist.
 138
 139 Usage::
 140
 141     ceph-volume lvm list
 142
 143 List a particular device, reporting all metadata about it::
 144
 145     ceph-volume lvm list /dev/sda1
 146
 147 List a logical volume, along with all its metadata (vg is a volume
 148 group, and lv the logical volume name)::
 149
 150     ceph-volume lvm list {vg/lv}
 151
 152 Positional arguments:
 153
 154 * <DEVICE>  Either in the form of ``vg/lv`` for logical volumes,
 155   ``/path/to/sda1`` or ``/path/to/sda`` for regular devices.
 156
 157
 158 **zap**
 159 Zaps the given logical volume or partition. If given a path to a logical
 160 volume it must be in the format of vg/lv. Any filesystems present
 161 on the given lv or partition will be removed and all data will be purged.
 162
 163 However, the lv or partition will be kept intact.
 164
 165 Usage, for logical volumes::
 166
 167       ceph-volume lvm zap {vg/lv}
 168
 169 Usage, for logical partitions::
 170
 171       ceph-volume lvm zap /dev/sdc1
 172
 173 Positional arguments:
 174
 175 * <DEVICE>  Either in the form of ``vg/lv`` for logical volumes,
 176   ``/path/to/sda1`` or ``/path/to/sda`` for regular devices.
 177
 178
 179 simple
 180 ------
 181
 182 Scan legacy OSD directories or data devices that may have been created by
 183 ceph-disk, or manually.
 184
 185 Subcommands:
 186
 187 **activate**
 188 Enables a systemd unit that persists the OSD ID and its UUID (also called
 189 ``fsid`` in Ceph CLI tools), so that at boot time it can understand what OSD is
 190 enabled and needs to be mounted, while reading information that was previously
 191 created and persisted at ``/etc/ceph/osd/`` in JSON format.
 192
 193 Usage::
 194
 195     ceph-volume simple activate --bluestore <osd id> <osd fsid>
 196
 197 Optional Arguments:
 198
 199 * [-h, --help]  show the help message and exit
 200 * [--bluestore] bluestore objectstore (default)
 201 * [--filestore] filestore objectstore
 202
 203 Note: It requires a matching JSON file with the following format::
 204
 205     /etc/ceph/osd/<osd id>-<osd fsid>.json
 206
 207
 208 **scan**
 209 Scan a running OSD or data device for an OSD for metadata that can later be
 210 used to activate and manage the OSD with ceph-volume. The scan method will
 211 create a JSON file with the required information plus anything found in the OSD
 212 directory as well.
 213
 214 Optionally, the JSON blob can be sent to stdout for further inspection.
 215
 216 Usage on data devices::
 217
 218     ceph-volume simple scan <data device>
 219
 220 Running OSD directories::
 221
 222     ceph-volume simple scan <path to osd dir>
 223
 224
 225 Optional arguments:
 226
 227 * [-h, --help]          show the help message and exit
 228 * [--stdout]            Send the JSON blob to stdout
 229 * [--force]             If the JSON file exists at destination, overwrite it
 230
 231 Required Positional arguments:
 232
 233 * <DATA DEVICE or OSD DIR>  Actual data partition or a path to the running OSD
 234
 235 **trigger**
 236 This subcommand is not meant to be used directly, and it is used by systemd so
 237 that it proxies input to ``ceph-volume simple activate`` by parsing the
 238 input from systemd, detecting the UUID and ID associated with an OSD.
 239
 240 Usage::
 241
 242     ceph-volume simple trigger <SYSTEMD-DATA>
 243
 244 The systemd "data" is expected to be in the format of::
 245
 246     <OSD ID>-<OSD UUID>
 247
 248 The JSON file associated with the OSD need to have been persisted previously by
 249 a scan (or manually), so that all needed metadata can be used.
 250
 251 Positional arguments:
 252
 253 * <SYSTEMD_DATA>  Data from a systemd unit containing ID and UUID of the OSD.
 254
 255
 256 Availability
 257 ============
 258
 259 :program:`ceph-volume` is part of Ceph, a massively scalable, open-source, distributed storage system. Please refer to
 260 the documentation at http://docs.ceph.com/ for more information.
 261
 262
 263 See also
 264 ========
 265
 266 :doc:`ceph-osd <ceph-osd>`\(8),
 267 :doc:`ceph-disk <ceph-disk>`\(8),