src/ceph/doc/ceph-volume/simple/scan.rst

   1 .. _ceph-volume-simple-scan:
   2
   3 ``scan``
   4 ========
   5 Scanning allows to capture any important details from an already-deployed OSD
   6 so that ``ceph-volume`` can manage it without the need of any other startup
   7 workflows or tools (like ``udev`` or ``ceph-disk``).
   8
   9 The command has the ability to inspect a running OSD, by inspecting the
  10 directory where the OSD data is stored, or by consuming the data partition.
  11
  12 Once scanned, information will (by default) persist the metadata as JSON in
  13 a file in ``/etc/ceph/osd``. This ``JSON`` file will use the naming convention
  14 of: ``{OSD ID}-{OSD FSID}.json``. An OSD with an id of 1, and an FSID like
  15 ``86ebd829-1405-43d3-8fd6-4cbc9b6ecf96`` the absolute path of the file would
  16 be::
  17
  18     /etc/ceph/osd/1-86ebd829-1405-43d3-8fd6-4cbc9b6ecf96.json
  19
  20 The ``scan`` subcommand will refuse to write to this file if it already exists.
  21 If overwriting the contents is needed, the ``--force`` flag must be used::
  22
  23     ceph-volume simple scan --force {path}
  24
  25 If there is no need to persist the ``JSON`` metadata, there is support to send
  26 the contents to ``stdout`` (no file will be written)::
  27
  28     ceph-volume simple scan --stdout {path}
  29
  30
  31 .. _ceph-volume-simple-scan-directory:
  32
  33 Directory scan
  34 --------------
  35 The directory scan will capture OSD file contents from interesting files. There
  36 are a few files that must exist in order to have a successful scan:
  37
  38 * ``ceph_fsid``
  39 * ``fsid``
  40 * ``keyring``
  41 * ``ready``
  42 * ``type``
  43 * ``whoami``
  44
  45 In the case of any other file, as long as it is not a binary or a directory, it
  46 will also get captured and persisted as part of the JSON object.
  47
  48 The convention for the keys in the JSON object is that any file name will be
  49 a key, and its contents will be its value. If the contents are a single line
  50 (like in the case of the ``whoami``) the contents are trimmed, and the newline
  51 is dropped. For example with an OSD with an id of 1, this is how the JSON entry
  52 would look like::
  53
  54     "whoami": "1",
  55
  56 For files that may have more than one line, the contents are left as-is, for
  57 example, a ``keyring`` could look like this::
  58
  59     "keyring": "[osd.1]\n\tkey = AQBBJ/dZp57NIBAAtnuQS9WOS0hnLVe0rZnE6Q==\n",
  60
  61 For a directory like ``/var/lib/ceph/osd/ceph-1``, the command could look
  62 like::
  63
  64     ceph-volume simple scan /var/lib/ceph/osd/ceph1
  65
  66
  67 .. note:: There is no support for encrypted OSDs
  68
  69
  70 .. _ceph-volume-simple-scan-device:
  71
  72 Device scan
  73 -----------
  74 When an OSD directory is not available (OSD is not running, or device is not
  75 mounted) the ``scan`` command is able to introspect the device to capture
  76 required data. Just like :ref:`ceph-volume-simple-scan-directory`, it would
  77 still require a few files present. This means that the device to be scanned
  78 **must be** the data partition of the OSD.
  79
  80 As long as the data partition of the OSD is being passed in as an argument, the
  81 sub-command can scan its contents.
  82
  83 In the case where the device is already mounted, the tool can detect this
  84 scenario and capture file contents from that directory.
  85
  86 If the device is not mounted, a temporary directory will be created, and the
  87 device will be mounted temporarily just for scanning the contents. Once
  88 contents are scanned, the device will be unmounted.
  89
  90 For a device like ``/dev/sda1`` which **must** be a data partition, the command
  91 could look like::
  92
  93     ceph-volume simple scan /dev/sda1
  94
  95
  96 .. note:: There is no support for encrypted OSDs
  97
  98
  99 .. _ceph-volume-simple-scan-json:
 100
 101 ``JSON`` contents
 102 -----------------
 103 The contents of the JSON object is very simple. The scan not only will persist
 104 information from the special OSD files and their contents, but will also
 105 validate paths and device UUIDs. Unlike what ``ceph-disk`` would do, by storing
 106 them in ``{device type}_uuid`` files, the tool will persist them as part of the
 107 device type key.
 108
 109 For example, a ``block.db`` device would look something like::
 110
 111     "block.db": {
 112         "path": "/dev/disk/by-partuuid/6cc43680-4f6e-4feb-92ff-9c7ba204120e",
 113         "uuid": "6cc43680-4f6e-4feb-92ff-9c7ba204120e"
 114     },
 115
 116 But it will also persist the ``ceph-disk`` special file generated, like so::
 117
 118     "block.db_uuid": "6cc43680-4f6e-4feb-92ff-9c7ba204120e",
 119
 120 This duplication is in place because the tool is trying to ensure the
 121 following:
 122
 123 # Support OSDs that may not have ceph-disk special files
 124 # Check the most up-to-date information on the device, by querying against LVM
 125 and ``blkid``
 126 # Support both logical volumes and GPT devices
 127
 128 This is a sample ``JSON`` metadata, from an OSD that is using ``bluestore``::
 129
 130     {
 131         "active": "ok",
 132         "block": {
 133             "path": "/dev/disk/by-partuuid/40fd0a64-caa5-43a3-9717-1836ac661a12",
 134             "uuid": "40fd0a64-caa5-43a3-9717-1836ac661a12"
 135         },
 136         "block.db": {
 137             "path": "/dev/disk/by-partuuid/6cc43680-4f6e-4feb-92ff-9c7ba204120e",
 138             "uuid": "6cc43680-4f6e-4feb-92ff-9c7ba204120e"
 139         },
 140         "block.db_uuid": "6cc43680-4f6e-4feb-92ff-9c7ba204120e",
 141         "block_uuid": "40fd0a64-caa5-43a3-9717-1836ac661a12",
 142         "bluefs": "1",
 143         "ceph_fsid": "c92fc9eb-0610-4363-aafc-81ddf70aaf1b",
 144         "cluster_name": "ceph",
 145         "data": {
 146             "path": "/dev/sdr1",
 147             "uuid": "86ebd829-1405-43d3-8fd6-4cbc9b6ecf96"
 148         },
 149         "fsid": "86ebd829-1405-43d3-8fd6-4cbc9b6ecf96",
 150         "keyring": "[osd.3]\n\tkey = AQBBJ/dZp57NIBAAtnuQS9WOS0hnLVe0rZnE6Q==\n",
 151         "kv_backend": "rocksdb",
 152         "magic": "ceph osd volume v026",
 153         "mkfs_done": "yes",
 154         "ready": "ready",
 155         "systemd": "",
 156         "type": "bluestore",
 157         "whoami": "3"
 158     }