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