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