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