]>
Commit | Line | Data |
---|---|---|
7c673cae FG |
1 | :orphan: |
2 | ||
3 | =============================================== | |
4 | rbd -- manage rados block device (RBD) images | |
5 | =============================================== | |
6 | ||
7 | .. program:: rbd | |
8 | ||
9 | Synopsis | |
10 | ======== | |
11 | ||
12 | | **rbd** [ -c *ceph.conf* ] [ -m *monaddr* ] [--cluster *cluster-name*] | |
13 | [ -p | --pool *pool* ] [ *command* ... ] | |
14 | ||
15 | ||
16 | Description | |
17 | =========== | |
18 | ||
19 | **rbd** is a utility for manipulating rados block device (RBD) images, | |
20 | used by the Linux rbd driver and the rbd storage driver for QEMU/KVM. | |
21 | RBD images are simple block devices that are striped over objects and | |
22 | stored in a RADOS object store. The size of the objects the image is | |
23 | striped over must be a power of two. | |
24 | ||
25 | ||
26 | Options | |
27 | ======= | |
28 | ||
29 | .. option:: -c ceph.conf, --conf ceph.conf | |
30 | ||
31 | Use ceph.conf configuration file instead of the default /etc/ceph/ceph.conf to | |
32 | determine monitor addresses during startup. | |
33 | ||
34 | .. option:: -m monaddress[:port] | |
35 | ||
36 | Connect to specified monitor (instead of looking through ceph.conf). | |
37 | ||
38 | .. option:: --cluster cluster-name | |
39 | ||
40 | Use different cluster name as compared to default cluster name *ceph*. | |
41 | ||
42 | .. option:: -p pool-name, --pool pool-name | |
43 | ||
44 | Interact with the given pool. Required by most commands. | |
45 | ||
11fdf7f2 TL |
46 | .. option:: --namespace namespace-name |
47 | ||
48 | Use a pre-defined image namespace within a pool | |
49 | ||
7c673cae FG |
50 | .. option:: --no-progress |
51 | ||
52 | Do not output progress information (goes to standard error by | |
53 | default for some commands). | |
54 | ||
55 | ||
56 | Parameters | |
57 | ========== | |
58 | ||
59 | .. option:: --image-format format-id | |
60 | ||
61 | Specifies which object layout to use. The default is 2. | |
62 | ||
63 | * format 1 - (deprecated) Use the original format for a new rbd image. This | |
64 | format is understood by all versions of librbd and the kernel rbd module, | |
65 | but does not support newer features like cloning. | |
66 | ||
9f95a23c TL |
67 | * format 2 - Use the second rbd format, which is supported by librbd since |
68 | the Bobtail release and the kernel rbd module since kernel 3.10 (except | |
69 | for "fancy" striping, which is supported since kernel 4.17). This adds | |
7c673cae FG |
70 | support for cloning and is more easily extensible to allow more |
71 | features in the future. | |
72 | ||
73 | .. option:: -s size-in-M/G/T, --size size-in-M/G/T | |
74 | ||
75 | Specifies the size of the new rbd image or the new size of the existing rbd | |
76 | image in M/G/T. If no suffix is given, unit M is assumed. | |
77 | ||
78 | .. option:: --object-size size-in-B/K/M | |
79 | ||
80 | Specifies the object size in B/K/M. Object size will be rounded up the | |
81 | nearest power of two; if no suffix is given, unit B is assumed. The default | |
82 | object size is 4M, smallest is 4K and maximum is 32M. | |
83 | ||
84 | .. option:: --stripe-unit size-in-B/K/M | |
85 | ||
86 | Specifies the stripe unit size in B/K/M. If no suffix is given, unit B is | |
87 | assumed. See striping section (below) for more details. | |
88 | ||
89 | .. option:: --stripe-count num | |
90 | ||
91 | Specifies the number of objects to stripe over before looping back | |
92 | to the first object. See striping section (below) for more details. | |
93 | ||
94 | .. option:: --snap snap | |
95 | ||
96 | Specifies the snapshot name for the specific operation. | |
97 | ||
98 | .. option:: --id username | |
99 | ||
100 | Specifies the username (without the ``client.`` prefix) to use with the map command. | |
101 | ||
102 | .. option:: --keyring filename | |
103 | ||
104 | Specifies a keyring file containing a secret for the specified user | |
105 | to use with the map command. If not specified, the default keyring | |
106 | locations will be searched. | |
107 | ||
108 | .. option:: --keyfile filename | |
109 | ||
110 | Specifies a file containing the secret key of ``--id user`` to use with the map command. | |
111 | This option is overridden by ``--keyring`` if the latter is also specified. | |
112 | ||
113 | .. option:: --shared lock-tag | |
114 | ||
115 | Option for `lock add` that allows multiple clients to lock the | |
116 | same image if they use the same tag. The tag is an arbitrary | |
117 | string. This is useful for situations where an image must | |
118 | be open from more than one client at once, like during | |
119 | live migration of a virtual machine, or for use underneath | |
9f95a23c | 120 | a clustered file system. |
7c673cae FG |
121 | |
122 | .. option:: --format format | |
123 | ||
124 | Specifies output formatting (default: plain, json, xml) | |
125 | ||
126 | .. option:: --pretty-format | |
127 | ||
128 | Make json or xml formatted output more human-readable. | |
129 | ||
130 | .. option:: -o krbd-options, --options krbd-options | |
131 | ||
132 | Specifies which options to use when mapping or unmapping an image via the | |
133 | rbd kernel driver. krbd-options is a comma-separated list of options | |
134 | (similar to mount(8) mount options). See kernel rbd (krbd) options section | |
135 | below for more details. | |
136 | ||
137 | .. option:: --read-only | |
138 | ||
139 | Map the image read-only. Equivalent to -o ro. | |
140 | ||
141 | .. option:: --image-feature feature-name | |
142 | ||
143 | Specifies which RBD format 2 feature should be enabled when creating | |
144 | an image. Multiple features can be enabled by repeating this option | |
145 | multiple times. The following features are supported: | |
146 | ||
147 | * layering: layering support | |
148 | * striping: striping v2 support | |
149 | * exclusive-lock: exclusive locking support | |
150 | * object-map: object map support (requires exclusive-lock) | |
151 | * fast-diff: fast diff calculations (requires object-map) | |
152 | * deep-flatten: snapshot flatten support | |
153 | * journaling: journaled IO support (requires exclusive-lock) | |
11fdf7f2 | 154 | * data-pool: erasure coded pool support |
7c673cae FG |
155 | |
156 | .. option:: --image-shared | |
157 | ||
158 | Specifies that the image will be used concurrently by multiple clients. | |
159 | This will disable features that are dependent upon exclusive ownership | |
160 | of the image. | |
161 | ||
162 | .. option:: --whole-object | |
163 | ||
164 | Specifies that the diff should be limited to the extents of a full object | |
165 | instead of showing intra-object deltas. When the object map feature is | |
166 | enabled on an image, limiting the diff to the object extents will | |
167 | dramatically improve performance since the differences can be computed | |
168 | by examining the in-memory object map instead of querying RADOS for each | |
169 | object within the image. | |
170 | ||
171 | .. option:: --limit | |
172 | ||
173 | Specifies the limit for the number of snapshots permitted. | |
174 | ||
175 | Commands | |
176 | ======== | |
177 | ||
178 | .. TODO rst "option" directive seems to require --foo style options, parsing breaks on subcommands.. the args show up as bold too | |
179 | ||
11fdf7f2 TL |
180 | :command:`bench` --io-type <read | write | readwrite | rw> [--io-size *size-in-B/K/M/G/T*] [--io-threads *num-ios-in-flight*] [--io-total *size-in-B/K/M/G/T*] [--io-pattern seq | rand] [--rw-mix-read *read proportion in readwrite*] *image-spec* |
181 | Generate a series of IOs to the image and measure the IO throughput and | |
182 | latency. If no suffix is given, unit B is assumed for both --io-size and | |
183 | --io-total. Defaults are: --io-size 4096, --io-threads 16, --io-total 1G, | |
184 | --io-pattern seq, --rw-mix-read 50. | |
185 | ||
186 | :command:`children` *snap-spec* | |
187 | List the clones of the image at the given snapshot. This checks | |
188 | every pool, and outputs the resulting poolname/imagename. | |
189 | ||
190 | This requires image format 2. | |
191 | ||
192 | :command:`clone` [--object-size *size-in-B/K/M*] [--stripe-unit *size-in-B/K/M* --stripe-count *num*] [--image-feature *feature-name*] [--image-shared] *parent-snap-spec* *child-image-spec* | |
193 | Will create a clone (copy-on-write child) of the parent snapshot. | |
194 | Object size will be identical to that of the parent image unless | |
195 | specified. Size will be the same as the parent snapshot. The --stripe-unit | |
196 | and --stripe-count arguments are optional, but must be used together. | |
197 | ||
198 | The parent snapshot must be protected (see `rbd snap protect`). | |
199 | This requires image format 2. | |
200 | ||
201 | :command:`config global get` *config-entity* *key* | |
202 | Get a global-level configuration override. | |
203 | ||
204 | :command:`config global list` [--format plain | json | xml] [--pretty-format] *config-entity* | |
205 | List global-level configuration overrides. | |
206 | ||
207 | :command:`config global set` *config-entity* *key* *value* | |
208 | Set a global-level configuration override. | |
209 | ||
210 | :command:`config global remove` *config-entity* *key* | |
211 | Remove a global-level configuration override. | |
212 | ||
213 | :command:`config image get` *image-spec* *key* | |
214 | Get an image-level configuration override. | |
215 | ||
216 | :command:`config image list` [--format plain | json | xml] [--pretty-format] *image-spec* | |
217 | List image-level configuration overrides. | |
218 | ||
219 | :command:`config image set` *image-spec* *key* *value* | |
220 | Set an image-level configuration override. | |
221 | ||
222 | :command:`config image remove` *image-spec* *key* | |
223 | Remove an image-level configuration override. | |
224 | ||
225 | :command:`config pool get` *pool-name* *key* | |
226 | Get a pool-level configuration override. | |
227 | ||
228 | :command:`config pool list` [--format plain | json | xml] [--pretty-format] *pool-name* | |
229 | List pool-level configuration overrides. | |
230 | ||
231 | :command:`config pool set` *pool-name* *key* *value* | |
232 | Set a pool-level configuration override. | |
233 | ||
234 | :command:`config pool remove` *pool-name* *key* | |
235 | Remove a pool-level configuration override. | |
236 | ||
237 | :command:`cp` (*src-image-spec* | *src-snap-spec*) *dest-image-spec* | |
238 | Copy the content of a src-image into the newly created dest-image. | |
239 | dest-image will have the same size, object size, and image format as src-image. | |
240 | ||
241 | :command:`create` (-s | --size *size-in-M/G/T*) [--image-format *format-id*] [--object-size *size-in-B/K/M*] [--stripe-unit *size-in-B/K/M* --stripe-count *num*] [--thick-provision] [--no-progress] [--image-feature *feature-name*]... [--image-shared] *image-spec* | |
242 | Will create a new rbd image. You must also specify the size via --size. The | |
243 | --stripe-unit and --stripe-count arguments are optional, but must be used together. | |
244 | If the --thick-provision is enabled, it will fully allocate storage for | |
245 | the image at creation time. It will take a long time to do. | |
246 | Note: thick provisioning requires zeroing the contents of the entire image. | |
247 | ||
248 | :command:`deep cp` (*src-image-spec* | *src-snap-spec*) *dest-image-spec* | |
249 | Deep copy the content of a src-image into the newly created dest-image. | |
250 | Dest-image will have the same size, object size, image format, and snapshots as src-image. | |
251 | ||
252 | :command:`device list` [-t | --device-type *device-type*] [--format plain | json | xml] --pretty-format | |
253 | Show the rbd images that are mapped via the rbd kernel module | |
254 | (default) or other supported device. | |
255 | ||
256 | :command:`device map` [-t | --device-type *device-type*] [--read-only] [--exclusive] [-o | --options *device-options*] *image-spec* | *snap-spec* | |
257 | Map the specified image to a block device via the rbd kernel module | |
258 | (default) or other supported device (*nbd* on Linux or *ggate* on | |
259 | FreeBSD). | |
260 | ||
261 | The --options argument is a comma separated list of device type | |
262 | specific options (opt1,opt2=val,...). | |
263 | ||
264 | :command:`device unmap` [-t | --device-type *device-type*] [-o | --options *device-options*] *image-spec* | *snap-spec* | *device-path* | |
265 | Unmap the block device that was mapped via the rbd kernel module | |
266 | (default) or other supported device. | |
267 | ||
268 | The --options argument is a comma separated list of device type | |
269 | specific options (opt1,opt2=val,...). | |
270 | ||
271 | :command:`diff` [--from-snap *snap-name*] [--whole-object] *image-spec* | *snap-spec* | |
272 | Dump a list of byte extents in the image that have changed since the specified start | |
273 | snapshot, or since the image was created. Each output line includes the starting offset | |
274 | (in bytes), the length of the region (in bytes), and either 'zero' or 'data' to indicate | |
275 | whether the region is known to be zeros or may contain other data. | |
7c673cae | 276 | |
9f95a23c | 277 | :command:`du` [-p | --pool *pool-name*] [*image-spec* | *snap-spec*] [--merge-snapshots] |
7c673cae FG |
278 | Will calculate the provisioned and actual disk usage of all images and |
279 | associated snapshots within the specified pool. It can also be used against | |
280 | individual images and snapshots. | |
281 | ||
c07f9fc5 | 282 | If the RBD fast-diff feature is not enabled on images, this operation will |
7c673cae FG |
283 | require querying the OSDs for every potential object within the image. |
284 | ||
9f95a23c TL |
285 | The --merge-snapshots will merge snapshots used space into their parent images. |
286 | ||
11fdf7f2 TL |
287 | :command:`export` [--export-format *format (1 or 2)*] (*image-spec* | *snap-spec*) [*dest-path*] |
288 | Export image to dest path (use - for stdout). | |
289 | The --export-format accepts '1' or '2' currently. Format 2 allow us to export not only the content | |
290 | of image, but also the snapshots and other properties, such as image_order, features. | |
7c673cae | 291 | |
11fdf7f2 TL |
292 | :command:`export-diff` [--from-snap *snap-name*] [--whole-object] (*image-spec* | *snap-spec*) *dest-path* |
293 | Export an incremental diff for an image to dest path (use - for stdout). If | |
294 | an initial snapshot is specified, only changes since that snapshot are included; otherwise, | |
295 | any regions of the image that contain data are included. The end snapshot is specified | |
296 | using the standard --snap option or @snap syntax (see below). The image diff format includes | |
297 | metadata about image size changes, and the start and end snapshots. It efficiently represents | |
298 | discarded or 'zero' regions of the image. | |
7c673cae | 299 | |
11fdf7f2 TL |
300 | :command:`feature disable` *image-spec* *feature-name*... |
301 | Disable the specified feature on the specified image. Multiple features can | |
302 | be specified. | |
7c673cae | 303 | |
11fdf7f2 TL |
304 | :command:`feature enable` *image-spec* *feature-name*... |
305 | Enable the specified feature on the specified image. Multiple features can | |
306 | be specified. | |
7c673cae FG |
307 | |
308 | :command:`flatten` *image-spec* | |
309 | If image is a clone, copy all shared blocks from the parent snapshot and | |
310 | make the child independent of the parent, severing the link between | |
311 | parent snap and child. The parent snapshot can be unprotected and | |
312 | deleted if it has no further dependent clones. | |
313 | ||
314 | This requires image format 2. | |
315 | ||
11fdf7f2 TL |
316 | :command:`group create` *group-spec* |
317 | Create a group. | |
7c673cae | 318 | |
11fdf7f2 TL |
319 | :command:`group image add` *group-spec* *image-spec* |
320 | Add an image to a group. | |
7c673cae | 321 | |
11fdf7f2 TL |
322 | :command:`group image list` *group-spec* |
323 | List images in a group. | |
7c673cae | 324 | |
11fdf7f2 TL |
325 | :command:`group image remove` *group-spec* *image-spec* |
326 | Remove an image from a group. | |
7c673cae | 327 | |
11fdf7f2 TL |
328 | :command:`group ls` [-p | --pool *pool-name*] |
329 | List rbd groups. | |
330 | ||
331 | :command:`group rename` *src-group-spec* *dest-group-spec* | |
332 | Rename a group. Note: rename across pools is not supported. | |
333 | ||
334 | :command:`group rm` *group-spec* | |
335 | Delete a group. | |
336 | ||
337 | :command:`group snap create` *group-snap-spec* | |
338 | Make a snapshot of a group. | |
339 | ||
340 | :command:`group snap list` *group-spec* | |
341 | List snapshots of a group. | |
342 | ||
343 | :command:`group snap rm` *group-snap-spec* | |
344 | Remove a snapshot from a group. | |
345 | ||
346 | :command:`group snap rename` *group-snap-spec* *snap-name* | |
347 | Rename group's snapshot. | |
348 | ||
349 | :command:`group snap rollback` *group-snap-spec* | |
350 | Rollback group to snapshot. | |
351 | ||
352 | :command:`image-meta get` *image-spec* *key* | |
353 | Get metadata value with the key. | |
354 | ||
355 | :command:`image-meta list` *image-spec* | |
356 | Show metadata held on the image. The first column is the key | |
357 | and the second column is the value. | |
358 | ||
359 | :command:`image-meta remove` *image-spec* *key* | |
360 | Remove metadata key with the value. | |
361 | ||
362 | :command:`image-meta set` *image-spec* *key* *value* | |
363 | Set metadata key with the value. They will displayed in `image-meta list`. | |
7c673cae FG |
364 | |
365 | :command:`import` [--export-format *format (1 or 2)*] [--image-format *format-id*] [--object-size *size-in-B/K/M*] [--stripe-unit *size-in-B/K/M* --stripe-count *num*] [--image-feature *feature-name*]... [--image-shared] *src-path* [*image-spec*] | |
c07f9fc5 | 366 | Create a new image and imports its data from path (use - for |
7c673cae FG |
367 | stdin). The import operation will try to create sparse rbd images |
368 | if possible. For import from stdin, the sparsification unit is | |
369 | the data block size of the destination image (object size). | |
370 | ||
371 | The --stripe-unit and --stripe-count arguments are optional, but must be | |
372 | used together. | |
373 | ||
374 | The --export-format accepts '1' or '2' currently. Format 2 allow us to import not only the content | |
375 | of image, but also the snapshots and other properties, such as image_order, features. | |
376 | ||
11fdf7f2 TL |
377 | :command:`import-diff` *src-path* *image-spec* |
378 | Import an incremental diff of an image and applies it to the current image. If the diff | |
379 | was generated relative to a start snapshot, we verify that snapshot already exists before | |
380 | continuing. If there was an end snapshot we verify it does not already exist before | |
381 | applying the changes, and create the snapshot when we are done. | |
382 | ||
383 | :command:`info` *image-spec* | *snap-spec* | |
384 | Will dump information (such as size and object size) about a specific rbd image. | |
385 | If image is a clone, information about its parent is also displayed. | |
386 | If a snapshot is specified, whether it is protected is shown as well. | |
387 | ||
388 | :command:`journal client disconnect` *journal-spec* | |
389 | Flag image journal client as disconnected. | |
390 | ||
391 | :command:`journal export` [--verbose] [--no-error] *src-journal-spec* *path-name* | |
392 | Export image journal to path (use - for stdout). It can be make a backup | |
393 | of the image journal especially before attempting dangerous operations. | |
394 | ||
395 | Note that this command may not always work if the journal is badly corrupted. | |
396 | ||
397 | :command:`journal import` [--verbose] [--no-error] *path-name* *dest-journal-spec* | |
398 | Import image journal from path (use - for stdin). | |
399 | ||
400 | :command:`journal info` *journal-spec* | |
401 | Show information about image journal. | |
402 | ||
403 | :command:`journal inspect` [--verbose] *journal-spec* | |
404 | Inspect and report image journal for structural errors. | |
405 | ||
406 | :command:`journal reset` *journal-spec* | |
407 | Reset image journal. | |
408 | ||
409 | :command:`journal status` *journal-spec* | |
410 | Show status of image journal. | |
411 | ||
412 | :command:`lock add` [--shared *lock-tag*] *image-spec* *lock-id* | |
413 | Lock an image. The lock-id is an arbitrary name for the user's | |
414 | convenience. By default, this is an exclusive lock, meaning it | |
415 | will fail if the image is already locked. The --shared option | |
416 | changes this behavior. Note that locking does not affect | |
417 | any operation other than adding a lock. It does not | |
418 | protect an image from being deleted. | |
419 | ||
420 | :command:`lock ls` *image-spec* | |
421 | Show locks held on the image. The first column is the locker | |
422 | to use with the `lock remove` command. | |
423 | ||
424 | :command:`lock rm` *image-spec* *lock-id* *locker* | |
425 | Release a lock on an image. The lock id and locker are | |
426 | as output by lock ls. | |
427 | ||
428 | :command:`ls` [-l | --long] [*pool-name*] | |
429 | Will list all rbd images listed in the rbd_directory object. With | |
430 | -l, also show snapshots, and use longer-format output including | |
431 | size, parent (if clone), format, etc. | |
7c673cae FG |
432 | |
433 | :command:`merge-diff` *first-diff-path* *second-diff-path* *merged-diff-path* | |
434 | Merge two continuous incremental diffs of an image into one single diff. The | |
435 | first diff's end snapshot must be equal with the second diff's start snapshot. | |
436 | The first diff could be - for stdin, and merged diff could be - for stdout, which | |
437 | enables multiple diff files to be merged using something like | |
438 | 'rbd merge-diff first second - | rbd merge-diff - third result'. Note this command | |
439 | currently only support the source incremental diff with stripe_count == 1 | |
440 | ||
11fdf7f2 TL |
441 | :command:`migration abort` *image-spec* |
442 | Cancel image migration. This step may be run after successful or | |
443 | failed migration prepare or migration execute steps and returns the | |
444 | image to its initial (before migration) state. All modifications to | |
445 | the destination image are lost. | |
446 | ||
447 | :command:`migration commit` *image-spec* | |
448 | Commit image migration. This step is run after a successful migration | |
449 | prepare and migration execute steps and removes the source image data. | |
450 | ||
451 | :command:`migration execute` *image-spec* | |
452 | Execute image migration. This step is run after a successful migration | |
453 | prepare step and copies image data to the destination. | |
454 | ||
455 | :command:`migration prepare` [--order *order*] [--object-size *object-size*] [--image-feature *image-feature*] [--image-shared] [--stripe-unit *stripe-unit*] [--stripe-count *stripe-count*] [--data-pool *data-pool*] *src-image-spec* [*dest-image-spec*] | |
456 | Prepare image migration. This is the first step when migrating an | |
457 | image, i.e. changing the image location, format or other | |
458 | parameters that can't be changed dynamically. The destination can | |
459 | match the source, and in this case *dest-image-spec* can be omitted. | |
460 | After this step the source image is set as a parent of the | |
461 | destination image, and the image is accessible in copy-on-write mode | |
462 | by its destination spec. | |
463 | ||
464 | :command:`mirror image demote` *image-spec* | |
465 | Demote a primary image to non-primary for RBD mirroring. | |
466 | ||
467 | :command:`mirror image disable` [--force] *image-spec* | |
468 | Disable RBD mirroring for an image. If the mirroring is | |
469 | configured in ``image`` mode for the image's pool, then it | |
470 | can be explicitly disabled mirroring for each image within | |
471 | the pool. | |
472 | ||
9f95a23c | 473 | :command:`mirror image enable` *image-spec* *mode* |
11fdf7f2 TL |
474 | Enable RBD mirroring for an image. If the mirroring is |
475 | configured in ``image`` mode for the image's pool, then it | |
476 | can be explicitly enabled mirroring for each image within | |
477 | the pool. | |
478 | ||
9f95a23c TL |
479 | The mirror image mode can either be ``journal`` (default) or |
480 | ``snapshot``. The ``journal`` mode requires the RBD journaling | |
481 | feature. | |
11fdf7f2 TL |
482 | |
483 | :command:`mirror image promote` [--force] *image-spec* | |
484 | Promote a non-primary image to primary for RBD mirroring. | |
485 | ||
486 | :command:`mirror image resync` *image-spec* | |
487 | Force resync to primary image for RBD mirroring. | |
488 | ||
489 | :command:`mirror image status` *image-spec* | |
490 | Show RBD mirroring status for an image. | |
491 | ||
492 | :command:`mirror pool demote` [*pool-name*] | |
493 | Demote all primary images within a pool to non-primary. | |
494 | Every mirroring enabled image will demoted in the pool. | |
495 | ||
496 | :command:`mirror pool disable` [*pool-name*] | |
497 | Disable RBD mirroring by default within a pool. When mirroring | |
498 | is disabled on a pool in this way, mirroring will also be | |
499 | disabled on any images (within the pool) for which mirroring | |
500 | was enabled explicitly. | |
501 | ||
502 | :command:`mirror pool enable` [*pool-name*] *mode* | |
503 | Enable RBD mirroring by default within a pool. | |
504 | The mirroring mode can either be ``pool`` or ``image``. | |
505 | If configured in ``pool`` mode, all images in the pool | |
506 | with the journaling feature enabled are mirrored. | |
507 | If configured in ``image`` mode, mirroring needs to be | |
508 | explicitly enabled (by ``mirror image enable`` command) | |
509 | on each image. | |
510 | ||
511 | :command:`mirror pool info` [*pool-name*] | |
512 | Show information about the pool mirroring configuration. | |
513 | It includes mirroring mode, peer UUID, remote cluster name, | |
514 | and remote client name. | |
515 | ||
516 | :command:`mirror pool peer add` [*pool-name*] *remote-cluster-spec* | |
517 | Add a mirroring peer to a pool. | |
518 | *remote-cluster-spec* is [*remote client name*\ @\ ]\ *remote cluster name*. | |
519 | ||
520 | The default for *remote client name* is "client.admin". | |
521 | ||
522 | This requires mirroring mode is enabled. | |
523 | ||
524 | :command:`mirror pool peer remove` [*pool-name*] *uuid* | |
525 | Remove a mirroring peer from a pool. The peer uuid is available | |
526 | from ``mirror pool info`` command. | |
527 | ||
528 | :command:`mirror pool peer set` [*pool-name*] *uuid* *key* *value* | |
529 | Update mirroring peer settings. | |
530 | The key can be either ``client`` or ``cluster``, and the value | |
531 | is corresponding to remote client name or remote cluster name. | |
532 | ||
533 | :command:`mirror pool promote` [--force] [*pool-name*] | |
534 | Promote all non-primary images within a pool to primary. | |
535 | Every mirroring enabled image will promoted in the pool. | |
536 | ||
537 | :command:`mirror pool status` [--verbose] [*pool-name*] | |
538 | Show status for all mirrored images in the pool. | |
539 | With --verbose, also show additionally output status | |
540 | details for every mirroring image in the pool. | |
7c673cae | 541 | |
9f95a23c TL |
542 | :command:`mirror snapshot schedule add` [-p | --pool *pool*] [--namespace *namespace*] [--image *image*] *interval* [*start-time*] |
543 | Add mirror snapshot schedule. | |
544 | ||
545 | :command:`mirror snapshot schedule list` [-R | --recursive] [--format *format*] [--pretty-format] [-p | --pool *pool*] [--namespace *namespace*] [--image *image*] | |
546 | List mirror snapshot schedule. | |
547 | ||
548 | :command:`mirror snapshot schedule remove` [-p | --pool *pool*] [--namespace *namespace*] [--image *image*] *interval* [*start-time*] | |
549 | Remove mirror snapshot schedule. | |
550 | ||
551 | :command:`mirror snapshot schedule status` [-p | --pool *pool*] [--format *format*] [--pretty-format] [--namespace *namespace*] [--image *image*] | |
552 | Show mirror snapshot schedule status. | |
553 | ||
7c673cae | 554 | :command:`mv` *src-image-spec* *dest-image-spec* |
c07f9fc5 | 555 | Rename an image. Note: rename across pools is not supported. |
7c673cae | 556 | |
eafe8130 | 557 | :command:`namespace create` *pool-name*/*namespace-name* |
11fdf7f2 | 558 | Create a new image namespace within the pool. |
7c673cae | 559 | |
11fdf7f2 TL |
560 | :command:`namespace list` *pool-name* |
561 | List image namespaces defined within the pool. | |
7c673cae | 562 | |
eafe8130 | 563 | :command:`namespace remove` *pool-name*/*namespace-name* |
11fdf7f2 | 564 | Remove an empty image namespace from the pool. |
7c673cae | 565 | |
11fdf7f2 TL |
566 | :command:`object-map check` *image-spec* | *snap-spec* |
567 | Verify the object map is correct. | |
7c673cae FG |
568 | |
569 | :command:`object-map rebuild` *image-spec* | *snap-spec* | |
c07f9fc5 | 570 | Rebuild an invalid object map for the specified image. An image snapshot can be |
7c673cae FG |
571 | specified to rebuild an invalid object map for a snapshot. |
572 | ||
11fdf7f2 TL |
573 | :command:`pool init` [*pool-name*] [--force] |
574 | Initialize pool for use by RBD. Newly created pools must initialized | |
575 | prior to use. | |
576 | ||
577 | :command:`resize` (-s | --size *size-in-M/G/T*) [--allow-shrink] *image-spec* | |
578 | Resize rbd image. The size parameter also needs to be specified. | |
579 | The --allow-shrink option lets the size be reduced. | |
580 | ||
581 | :command:`rm` *image-spec* | |
582 | Delete an rbd image (including all data blocks). If the image has | |
583 | snapshots, this fails and nothing is deleted. | |
7c673cae FG |
584 | |
585 | :command:`snap create` *snap-spec* | |
c07f9fc5 | 586 | Create a new snapshot. Requires the snapshot name parameter specified. |
7c673cae | 587 | |
11fdf7f2 TL |
588 | :command:`snap limit clear` *image-spec* |
589 | Remove any previously set limit on the number of snapshots allowed on | |
590 | an image. | |
7c673cae | 591 | |
11fdf7f2 TL |
592 | :command:`snap limit set` [--limit] *limit* *image-spec* |
593 | Set a limit for the number of snapshots allowed on an image. | |
7c673cae | 594 | |
11fdf7f2 TL |
595 | :command:`snap ls` *image-spec* |
596 | Dump the list of snapshots inside a specific image. | |
7c673cae FG |
597 | |
598 | :command:`snap protect` *snap-spec* | |
599 | Protect a snapshot from deletion, so that clones can be made of it | |
600 | (see `rbd clone`). Snapshots must be protected before clones are made; | |
601 | protection implies that there exist dependent cloned children that | |
602 | refer to this snapshot. `rbd clone` will fail on a nonprotected | |
603 | snapshot. | |
604 | ||
605 | This requires image format 2. | |
606 | ||
11fdf7f2 TL |
607 | :command:`snap purge` *image-spec* |
608 | Remove all unprotected snapshots from an image. | |
609 | ||
610 | :command:`snap rename` *src-snap-spec* *dest-snap-spec* | |
611 | Rename a snapshot. Note: rename across pools and images is not supported. | |
612 | ||
613 | :command:`snap rm` [--force] *snap-spec* | |
614 | Remove the specified snapshot. | |
615 | ||
616 | :command:`snap rollback` *snap-spec* | |
617 | Rollback image content to snapshot. This will iterate through the entire blocks | |
618 | array and update the data head content to the snapshotted version. | |
619 | ||
7c673cae FG |
620 | :command:`snap unprotect` *snap-spec* |
621 | Unprotect a snapshot from deletion (undo `snap protect`). If cloned | |
622 | children remain, `snap unprotect` fails. (Note that clones may exist | |
623 | in different pools than the parent snapshot.) | |
624 | ||
625 | This requires image format 2. | |
626 | ||
11fdf7f2 TL |
627 | :command:`sparsify` [--sparse-size *sparse-size*] *image-spec* |
628 | Reclaim space for zeroed image extents. The default sparse size is | |
629 | 4096 bytes and can be changed via --sparse-size option with the | |
630 | following restrictions: it should be power of two, not less than | |
9f95a23c | 631 | 4096, and not larger than image object size. |
7c673cae FG |
632 | |
633 | :command:`status` *image-spec* | |
634 | Show the status of the image, including which clients have it open. | |
635 | ||
c07f9fc5 FG |
636 | :command:`trash ls` [*pool-name*] |
637 | List all entries from trash. | |
638 | ||
639 | :command:`trash mv` *image-spec* | |
640 | Move an image to the trash. Images, even ones actively in-use by | |
641 | clones, can be moved to the trash and deleted at a later time. | |
642 | ||
11fdf7f2 TL |
643 | :command:`trash purge` [*pool-name*] |
644 | Remove all expired images from trash. | |
645 | ||
646 | :command:`trash restore` *image-id* | |
647 | Restore an image from trash. | |
648 | ||
c07f9fc5 FG |
649 | :command:`trash rm` *image-id* |
650 | Delete an image from trash. If image deferment time has not expired | |
651 | you can not removed it unless use force. But an actively in-use by clones | |
652 | or has snapshots can not be removed. | |
653 | ||
9f95a23c TL |
654 | :command:`trash purge schedule add` [-p | --pool *pool*] [--namespace *namespace*] *interval* [*start-time*] |
655 | Add trash purge schedule. | |
656 | ||
657 | :command:`trash purge schedule list` [-R | --recursive] [--format *format*] [--pretty-format] [-p | --pool *pool*] [--namespace *namespace*] | |
658 | List trash purge schedule. | |
659 | ||
660 | :command:`trash purge schedule remove` [-p | --pool *pool*] [--namespace *namespace*] *interval* [*start-time*] | |
661 | Remove trash purge schedule. | |
662 | ||
663 | :command:`trash purge schedule status` [-p | --pool *pool*] [--format *format*] [--pretty-format] [--namespace *namespace*] | |
664 | Show trash purge schedule status. | |
665 | ||
11fdf7f2 TL |
666 | :command:`watch` *image-spec* |
667 | Watch events on image. | |
668 | ||
669 | Image, snap, group and journal specs | |
670 | ==================================== | |
c07f9fc5 | 671 | |
11fdf7f2 TL |
672 | | *image-spec* is [*pool-name*/[*namespace-name*/]]\ *image-name* |
673 | | *snap-spec* is [*pool-name*/[*namespace-name*/]]\ *image-name*\ @\ *snap-name* | |
674 | | *group-spec* is [*pool-name*/[*namespace-name*/]]\ *group-name* | |
675 | | *group-snap-spec* is [*pool-name*/[*namespace-name*/]]\ *group-name*\ @\ *snap-name* | |
676 | | *journal-spec* is [*pool-name*/[*namespace-name*/]]\ *journal-name* | |
7c673cae | 677 | |
11fdf7f2 TL |
678 | The default for *pool-name* is "rbd" and *namespace-name* is "". If an image |
679 | name contains a slash character ('/'), *pool-name* is required. | |
7c673cae | 680 | |
11fdf7f2 | 681 | The *journal-name* is *image-id*. |
7c673cae | 682 | |
11fdf7f2 TL |
683 | You may specify each name individually, using --pool, --namespace, --image, and |
684 | --snap options, but this is discouraged in favor of the above spec syntax. | |
7c673cae FG |
685 | |
686 | Striping | |
687 | ======== | |
688 | ||
689 | RBD images are striped over many objects, which are then stored by the | |
690 | Ceph distributed object store (RADOS). As a result, read and write | |
691 | requests for the image are distributed across many nodes in the | |
692 | cluster, generally preventing any single node from becoming a | |
693 | bottleneck when individual images get large or busy. | |
694 | ||
695 | The striping is controlled by three parameters: | |
696 | ||
697 | .. option:: object-size | |
698 | ||
699 | The size of objects we stripe over is a power of two. It will be rounded up the nearest power of two. | |
700 | The default object size is 4 MB, smallest is 4K and maximum is 32M. | |
701 | ||
702 | .. option:: stripe_unit | |
703 | ||
704 | Each [*stripe_unit*] contiguous bytes are stored adjacently in the same object, before we move on | |
705 | to the next object. | |
706 | ||
707 | .. option:: stripe_count | |
708 | ||
709 | After we write [*stripe_unit*] bytes to [*stripe_count*] objects, we loop back to the initial object | |
710 | and write another stripe, until the object reaches its maximum size. At that point, | |
711 | we move on to the next [*stripe_count*] objects. | |
712 | ||
713 | By default, [*stripe_unit*] is the same as the object size and [*stripe_count*] is 1. Specifying a different | |
9f95a23c | 714 | [*stripe_unit*] and/or [*stripe_count*] is often referred to as using "fancy" striping and requires format 2. |
7c673cae FG |
715 | |
716 | ||
717 | Kernel rbd (krbd) options | |
718 | ========================= | |
719 | ||
720 | Most of these options are useful mainly for debugging and benchmarking. The | |
721 | default values are set in the kernel and may therefore depend on the version of | |
722 | the running kernel. | |
723 | ||
11fdf7f2 | 724 | Per client instance `rbd device map` options: |
7c673cae FG |
725 | |
726 | * fsid=aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee - FSID that should be assumed by | |
727 | the client. | |
728 | ||
729 | * ip=a.b.c.d[:p] - IP and, optionally, port the client should use. | |
730 | ||
731 | * share - Enable sharing of client instances with other mappings (default). | |
732 | ||
733 | * noshare - Disable sharing of client instances with other mappings. | |
734 | ||
735 | * crc - Enable CRC32C checksumming for data writes (default). | |
736 | ||
737 | * nocrc - Disable CRC32C checksumming for data writes. | |
738 | ||
739 | * cephx_require_signatures - Require cephx message signing (since 3.19, | |
740 | default). | |
741 | ||
742 | * nocephx_require_signatures - Don't require cephx message signing (since | |
743 | 3.19). | |
744 | ||
745 | * tcp_nodelay - Disable Nagle's algorithm on client sockets (since 4.0, | |
746 | default). | |
747 | ||
748 | * notcp_nodelay - Enable Nagle's algorithm on client sockets (since 4.0). | |
749 | ||
750 | * cephx_sign_messages - Enable message signing (since 4.4, default). | |
751 | ||
752 | * nocephx_sign_messages - Disable message signing (since 4.4). | |
753 | ||
11fdf7f2 TL |
754 | * mount_timeout=x - A timeout on various steps in `rbd device map` and |
755 | `rbd device unmap` sequences (default is 60 seconds). In particular, | |
756 | since 4.2 this can be used to ensure that `rbd device unmap` eventually | |
757 | times out when there is no network connection to a cluster. | |
7c673cae FG |
758 | |
759 | * osdkeepalive=x - OSD keepalive timeout (default is 5 seconds). | |
760 | ||
761 | * osd_idle_ttl=x - OSD idle TTL (default is 60 seconds). | |
762 | ||
11fdf7f2 | 763 | Per mapping (block device) `rbd device map` options: |
7c673cae FG |
764 | |
765 | * rw - Map the image read-write (default). | |
766 | ||
767 | * ro - Map the image read-only. Equivalent to --read-only. | |
768 | ||
769 | * queue_depth=x - queue depth (since 4.2, default is 128 requests). | |
770 | ||
771 | * lock_on_read - Acquire exclusive lock on reads, in addition to writes and | |
772 | discards (since 4.9). | |
773 | ||
774 | * exclusive - Disable automatic exclusive lock transitions (since 4.12). | |
775 | ||
11fdf7f2 TL |
776 | * lock_timeout=x - A timeout on waiting for the acquisition of exclusive lock |
777 | (since 4.17, default is 0 seconds, meaning no timeout). | |
778 | ||
779 | * notrim - Turn off discard and write zeroes offload support to avoid | |
780 | deprovisioning a fully provisioned image (since 4.17). When enabled, discard | |
781 | requests will fail with -EOPNOTSUPP, write zeroes requests will fall back to | |
782 | manually zeroing. | |
783 | ||
784 | * abort_on_full - Fail write requests with -ENOSPC when the cluster is full or | |
785 | the data pool reaches its quota (since 5.0). The default behaviour is to | |
786 | block until the full condition is cleared. | |
787 | ||
788 | * alloc_size - Minimum allocation unit of the underlying OSD object store | |
789 | backend (since 5.1, default is 64K bytes). This is used to round off and | |
790 | drop discards that are too small. For bluestore, the recommended setting is | |
791 | bluestore_min_alloc_size (typically 64K for hard disk drives and 16K for | |
792 | solid-state drives). For filestore with filestore_punch_hole = false, the | |
793 | recommended setting is image object size (typically 4M). | |
794 | ||
f6b5b4d7 TL |
795 | * crush_location=x - Specify the location of the client in terms of CRUSH |
796 | hierarchy (since 5.8). This is a set of key-value pairs separated from | |
797 | each other by '|', with keys separated from values by ':'. Note that '|' | |
798 | may need to be quoted or escaped to avoid it being interpreted as a pipe | |
799 | by the shell. The key is the bucket type name (e.g. rack, datacenter or | |
800 | region with default bucket types) and the value is the bucket name. For | |
801 | example, to indicate that the client is local to rack "myrack", data center | |
802 | "mydc" and region "myregion":: | |
803 | ||
804 | crush_location=rack:myrack|datacenter:mydc|region:myregion | |
805 | ||
806 | Each key-value pair stands on its own: "myrack" doesn't need to reside in | |
807 | "mydc", which in turn doesn't need to reside in "myregion". The location | |
808 | is not a path to the root of the hierarchy but rather a set of nodes that | |
809 | are matched independently, owning to the fact that bucket names are unique | |
810 | within a CRUSH map. "Multipath" locations are supported, so it is possible | |
811 | to indicate locality for multiple parallel hierarchies:: | |
812 | ||
813 | crush_location=rack:myrack1|rack:myrack2|datacenter:mydc | |
814 | ||
815 | * read_from_replica=no - Disable replica reads, always pick the primary OSD | |
816 | (since 5.8, default). | |
817 | ||
818 | * read_from_replica=balance - When issued a read on a replicated pool, pick | |
819 | a random OSD for serving it (since 5.8). | |
820 | ||
821 | This mode is safe for general use only since Octopus (i.e. after "ceph osd | |
822 | require-osd-release octopus"). Otherwise it should be limited to read-only | |
823 | workloads such as images mapped read-only everywhere or snapshots. | |
824 | ||
825 | * read_from_replica=localize - When issued a read on a replicated pool, pick | |
826 | the most local OSD for serving it (since 5.8). The locality metric is | |
827 | calculated against the location of the client given with crush_location; | |
828 | a match with the lowest-valued bucket type wins. For example, with default | |
829 | bucket types, an OSD in a matching rack is closer than an OSD in a matching | |
830 | data center, which in turn is closer than an OSD in a matching region. | |
831 | ||
832 | This mode is safe for general use only since Octopus (i.e. after "ceph osd | |
833 | require-osd-release octopus"). Otherwise it should be limited to read-only | |
834 | workloads such as images mapped read-only everywhere or snapshots. | |
835 | ||
836 | * compression_hint=none - Don't set compression hints (since 5.8, default). | |
837 | ||
838 | * compression_hint=compressible - Hint to the underlying OSD object store | |
839 | backend that the data is compressible, enabling compression in passive mode | |
840 | (since 5.8). | |
841 | ||
842 | * compression_hint=incompressible - Hint to the underlying OSD object store | |
843 | backend that the data is incompressible, disabling compression in aggressive | |
844 | mode (since 5.8). | |
845 | ||
11fdf7f2 | 846 | `rbd device unmap` options: |
7c673cae FG |
847 | |
848 | * force - Force the unmapping of a block device that is open (since 4.9). The | |
849 | driver will wait for running requests to complete and then unmap; requests | |
850 | sent to the driver after initiating the unmap will be failed. | |
851 | ||
852 | ||
853 | Examples | |
854 | ======== | |
855 | ||
856 | To create a new rbd image that is 100 GB:: | |
857 | ||
858 | rbd create mypool/myimage --size 102400 | |
859 | ||
860 | To use a non-default object size (8 MB):: | |
861 | ||
862 | rbd create mypool/myimage --size 102400 --object-size 8M | |
863 | ||
864 | To delete an rbd image (be careful!):: | |
865 | ||
866 | rbd rm mypool/myimage | |
867 | ||
868 | To create a new snapshot:: | |
869 | ||
870 | rbd snap create mypool/myimage@mysnap | |
871 | ||
872 | To create a copy-on-write clone of a protected snapshot:: | |
873 | ||
874 | rbd clone mypool/myimage@mysnap otherpool/cloneimage | |
875 | ||
876 | To see which clones of a snapshot exist:: | |
877 | ||
878 | rbd children mypool/myimage@mysnap | |
879 | ||
880 | To delete a snapshot:: | |
881 | ||
882 | rbd snap rm mypool/myimage@mysnap | |
883 | ||
884 | To map an image via the kernel with cephx enabled:: | |
885 | ||
11fdf7f2 | 886 | rbd device map mypool/myimage --id admin --keyfile secretfile |
7c673cae FG |
887 | |
888 | To map an image via the kernel with different cluster name other than default *ceph*:: | |
889 | ||
11fdf7f2 | 890 | rbd device map mypool/myimage --cluster cluster-name |
7c673cae FG |
891 | |
892 | To unmap an image:: | |
893 | ||
11fdf7f2 | 894 | rbd device unmap /dev/rbd0 |
7c673cae FG |
895 | |
896 | To create an image and a clone from it:: | |
897 | ||
898 | rbd import --image-format 2 image mypool/parent | |
899 | rbd snap create mypool/parent@snap | |
900 | rbd snap protect mypool/parent@snap | |
901 | rbd clone mypool/parent@snap otherpool/child | |
902 | ||
903 | To create an image with a smaller stripe_unit (to better distribute small writes in some workloads):: | |
904 | ||
905 | rbd create mypool/myimage --size 102400 --stripe-unit 65536B --stripe-count 16 | |
906 | ||
907 | To change an image from one image format to another, export it and then | |
908 | import it as the desired image format:: | |
909 | ||
910 | rbd export mypool/myimage@snap /tmp/img | |
911 | rbd import --image-format 2 /tmp/img mypool/myimage2 | |
912 | ||
913 | To lock an image for exclusive use:: | |
914 | ||
915 | rbd lock add mypool/myimage mylockid | |
916 | ||
917 | To release a lock:: | |
918 | ||
919 | rbd lock remove mypool/myimage mylockid client.2485 | |
920 | ||
c07f9fc5 FG |
921 | To list images from trash:: |
922 | ||
923 | rbd trash ls mypool | |
924 | ||
11fdf7f2 | 925 | To defer delete an image (use *--expires-at* to set expiration time, default is now):: |
c07f9fc5 | 926 | |
11fdf7f2 | 927 | rbd trash mv mypool/myimage --expires-at "tomorrow" |
c07f9fc5 FG |
928 | |
929 | To delete an image from trash (be careful!):: | |
930 | ||
931 | rbd trash rm mypool/myimage-id | |
932 | ||
933 | To force delete an image from trash (be careful!):: | |
934 | ||
935 | rbd trash rm mypool/myimage-id --force | |
936 | ||
937 | To restore an image from trash:: | |
938 | ||
939 | rbd trash restore mypool/myimage-id | |
940 | ||
941 | To restore an image from trash and rename it:: | |
942 | ||
943 | rbd trash restore mypool/myimage-id --image mynewimage | |
944 | ||
7c673cae FG |
945 | |
946 | Availability | |
947 | ============ | |
948 | ||
949 | **rbd** is part of Ceph, a massively scalable, open-source, distributed storage system. Please refer to | |
950 | the Ceph documentation at http://ceph.com/docs for more information. | |
951 | ||
952 | ||
953 | See also | |
954 | ======== | |
955 | ||
956 | :doc:`ceph <ceph>`\(8), | |
957 | :doc:`rados <rados>`\(8) |