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