mirror of
https://github.com/ceph/ceph
synced 2024-12-22 11:31:55 +00:00
649bdc15d3
* a clone's size can't be overridden * note which commands require format 2 * clarify details of copy * add examples for cloning * add pool to map example for consistency * fix a couple warnings and re-sync man page with rst Signed-off-by: Josh Durgin <josh.durgin@inktank.com>
338 lines
8.8 KiB
Groff
338 lines
8.8 KiB
Groff
.TH "RBD" "8" "August 29, 2012" "dev" "Ceph"
|
|
.SH NAME
|
|
rbd \- manage rados block device (RBD) images
|
|
.
|
|
.nr rst2man-indent-level 0
|
|
.
|
|
.de1 rstReportMargin
|
|
\\$1 \\n[an-margin]
|
|
level \\n[rst2man-indent-level]
|
|
level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
|
|
-
|
|
\\n[rst2man-indent0]
|
|
\\n[rst2man-indent1]
|
|
\\n[rst2man-indent2]
|
|
..
|
|
.de1 INDENT
|
|
.\" .rstReportMargin pre:
|
|
. RS \\$1
|
|
. nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin]
|
|
. nr rst2man-indent-level +1
|
|
.\" .rstReportMargin post:
|
|
..
|
|
.de UNINDENT
|
|
. RE
|
|
.\" indent \\n[an-margin]
|
|
.\" old: \\n[rst2man-indent\\n[rst2man-indent-level]]
|
|
.nr rst2man-indent-level -1
|
|
.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
|
|
.in \\n[rst2man-indent\\n[rst2man-indent-level]]u
|
|
..
|
|
.\" Man page generated from reStructuredText.
|
|
.
|
|
.SH SYNOPSIS
|
|
.nf
|
|
\fBrbd\fP [ \-c \fIceph.conf\fP ] [ \-m \fImonaddr\fP ] [ \-p | \-\-pool \fIpool\fP ] [
|
|
\-\-size \fIsize\fP ] [ \-\-order \fIbits\fP ] [ \fIcommand\fP ... ]
|
|
.fi
|
|
.sp
|
|
.SH DESCRIPTION
|
|
.sp
|
|
\fBrbd\fP is a utility for manipulating rados block device (RBD) images,
|
|
used by the Linux rbd driver and the rbd storage driver for Qemu/KVM.
|
|
RBD images are simple block devices that are striped over objects and
|
|
stored in a RADOS object store. The size of the objects the image is
|
|
striped over must be a power of two.
|
|
.SH OPTIONS
|
|
.INDENT 0.0
|
|
.TP
|
|
.B \-c ceph.conf, \-\-conf ceph.conf
|
|
Use ceph.conf configuration file instead of the default /etc/ceph/ceph.conf to
|
|
determine monitor addresses during startup.
|
|
.UNINDENT
|
|
.INDENT 0.0
|
|
.TP
|
|
.B \-m monaddress[:port]
|
|
Connect to specified monitor (instead of looking through ceph.conf).
|
|
.UNINDENT
|
|
.INDENT 0.0
|
|
.TP
|
|
.B \-p pool, \-\-pool pool
|
|
Interact with the given pool. Required by most commands.
|
|
.UNINDENT
|
|
.SH PARAMETERS
|
|
.INDENT 0.0
|
|
.TP
|
|
.B \-\-format format
|
|
Specifies which object layout to use. The default is 1.
|
|
.INDENT 7.0
|
|
.IP \(bu 2
|
|
format 1 \- Use the original format for a new rbd image. This format is
|
|
understood by all versions of librbd and the kernel rbd module, but
|
|
does not support newer features like cloning.
|
|
.IP \(bu 2
|
|
format 2 \- Use the second rbd format, which is supported by
|
|
librbd (but not the kernel rbd module) at this time. This adds
|
|
support for cloning and is more easily extensible to allow more
|
|
features in the future.
|
|
.UNINDENT
|
|
.UNINDENT
|
|
.INDENT 0.0
|
|
.TP
|
|
.B \-\-size size\-in\-mb
|
|
Specifies the size (in megabytes) of the new rbd image.
|
|
.UNINDENT
|
|
.INDENT 0.0
|
|
.TP
|
|
.B \-\-order bits
|
|
Specifies the object size expressed as a number of bits, such that
|
|
the object size is \fB1 << order\fP. The default is 22 (4 MB).
|
|
.UNINDENT
|
|
.INDENT 0.0
|
|
.TP
|
|
.B \-\-snap snap
|
|
Specifies the snapshot name for the specific operation.
|
|
.UNINDENT
|
|
.INDENT 0.0
|
|
.TP
|
|
.B \-\-id username
|
|
Specifies the username (without the \fBclient.\fP prefix) to use with the map command.
|
|
.UNINDENT
|
|
.INDENT 0.0
|
|
.TP
|
|
.B \-\-keyfile filename
|
|
Specifies a file containing the secret to use with the map command.
|
|
If not specified, \fBclient.admin\fP will be used by default.
|
|
.UNINDENT
|
|
.INDENT 0.0
|
|
.TP
|
|
.B \-\-keyring filename
|
|
Specifies a keyring file containing a secret for the specified user
|
|
to use with the map command. If not specified, the default keyring
|
|
locations will be searched.
|
|
.UNINDENT
|
|
.SH COMMANDS
|
|
.INDENT 0.0
|
|
.TP
|
|
.B \fBls\fP [\fIpool\-name\fP]
|
|
Will list all rbd images listed in the rbd_directory object.
|
|
.TP
|
|
.B \fBinfo\fP [\fIimage\-name\fP]
|
|
Will dump information (such as size and order) about a specific rbd image.
|
|
If image is a clone, information about its parent is also displayed.
|
|
If a snapshot is specified, whether it is protected is shown as well.
|
|
.TP
|
|
.B \fBcreate\fP [\fIimage\-name\fP]
|
|
Will create a new rbd image. You must also specify the size via \-\-size.
|
|
.TP
|
|
.B \fBclone\fP [\fIparent\-snapname\fP] [\fIimage\-name\fP]
|
|
Will create a clone (copy\-on\-write child) of the parent snapshot.
|
|
Object order will be identical to that of the parent image unless
|
|
specified. Size will be the same as the parent snapshot.
|
|
.sp
|
|
The parent snapshot must be protected (see \fIrbd snap protect\fP).
|
|
This requires format 2.
|
|
.TP
|
|
.B \fBflatten\fP [\fIimage\-name\fP]
|
|
If image is a clone, copy all shared blocks from the parent snapshot and
|
|
make the child independent of the parent, severing the link between
|
|
parent snap and child. The parent snapshot can be unprotected and
|
|
deleted if it has no further dependent clones.
|
|
.sp
|
|
This requires format 2.
|
|
.TP
|
|
.B \fBchildren\fP [\fIimage\-name\fP]
|
|
List the clones of the image at the given snapshot. This checks
|
|
every pool, and outputs the resulting poolname/imagename.
|
|
.sp
|
|
This requires format 2.
|
|
.TP
|
|
.B \fBresize\fP [\fIimage\-name\fP]
|
|
Resizes rbd image. The size parameter also needs to be specified.
|
|
.TP
|
|
.B \fBrm\fP [\fIimage\-name\fP]
|
|
Deletes an rbd image (including all data blocks). If the image has
|
|
snapshots, this fails and nothing is deleted.
|
|
.TP
|
|
.B \fBexport\fP [\fIimage\-name\fP] [\fIdest\-path\fP]
|
|
Exports image to dest path.
|
|
.TP
|
|
.B \fBimport\fP [\fIpath\fP] [\fIdest\-image\fP]
|
|
Creates a new image and imports its data from path.
|
|
.TP
|
|
.B \fBcp\fP [\fIsrc\-image\fP] [\fIdest\-image\fP]
|
|
Copies the content of a src\-image into the newly created dest\-image.
|
|
dest\-image will have the same size, order, and format as src\-image.
|
|
.TP
|
|
.B \fBmv\fP [\fIsrc\-image\fP] [\fIdest\-image\fP]
|
|
Renames an image. Note: rename across pools is not supported.
|
|
.TP
|
|
.B \fBsnap\fP ls [\fIimage\-name\fP]
|
|
Dumps the list of snapshots inside a specific image.
|
|
.TP
|
|
.B \fBsnap\fP create [\fIimage\-name\fP]
|
|
Creates a new snapshot. Requires the snapshot name parameter specified.
|
|
.TP
|
|
.B \fBsnap\fP rollback [\fIimage\-name\fP]
|
|
Rollback image content to snapshot. This will iterate through the entire blocks
|
|
array and update the data head content to the snapshotted version.
|
|
.TP
|
|
.B \fBsnap\fP rm [\fIimage\-name\fP]
|
|
Removes the specified snapshot.
|
|
.TP
|
|
.B \fBsnap\fP purge [\fIimage\-name\fP]
|
|
Removes all snapshots from an image.
|
|
.TP
|
|
.B \fBsnap\fP protect [\fIimage\-name\fP]
|
|
Protect a snapshot from deletion, so that clones can be made of it
|
|
(see \fIrbd clone\fP). Snapshots must be protected before clones are made;
|
|
protection implies that there exist dependent cloned children that
|
|
refer to this snapshot. \fIrbd clone\fP will fail on a nonprotected
|
|
snapshot.
|
|
.sp
|
|
This requires format 2.
|
|
.TP
|
|
.B \fBsnap\fP unprotect [\fIimage\-name\fP]
|
|
Unprotect a snapshot from deletion (undo \fIsnap protect\fP). If cloned
|
|
children remain, \fIsnap unprotect\fP fails. (Note that clones may exist
|
|
in different pools than the parent snapshot.)
|
|
.sp
|
|
This requires format 2.
|
|
.TP
|
|
.B \fBmap\fP [\fIimage\-name\fP]
|
|
Maps the specified image to a block device via the rbd kernel module.
|
|
.TP
|
|
.B \fBunmap\fP [\fIdevice\-path\fP]
|
|
Unmaps the block device that was mapped via the rbd kernel module.
|
|
.TP
|
|
.B \fBshowmapped\fP
|
|
Show the rbd images that are mapped via the rbd kernel module.
|
|
.UNINDENT
|
|
.SH IMAGE NAME
|
|
.sp
|
|
In addition to using the \-\-pool and the \-\-snap options, the image name can include both
|
|
the pool name and the snapshot name. The image name format is as follows:
|
|
.sp
|
|
.nf
|
|
.ft C
|
|
[pool/]image\-name[@snap]
|
|
.ft P
|
|
.fi
|
|
.sp
|
|
Thus an image name that contains a slash character (\(aq/\(aq) requires specifying the pool
|
|
name explicitly.
|
|
.SH EXAMPLES
|
|
.sp
|
|
To create a new rbd image that is 100 GB:
|
|
.sp
|
|
.nf
|
|
.ft C
|
|
rbd \-p mypool create myimage \-\-size 102400
|
|
.ft P
|
|
.fi
|
|
.sp
|
|
or alternatively:
|
|
.sp
|
|
.nf
|
|
.ft C
|
|
rbd create mypool/myimage \-\-size 102400
|
|
.ft P
|
|
.fi
|
|
.sp
|
|
To use a non\-default object size (8 MB):
|
|
.sp
|
|
.nf
|
|
.ft C
|
|
rbd create mypool/myimage \-\-size 102400 \-\-order 23
|
|
.ft P
|
|
.fi
|
|
.sp
|
|
To delete an rbd image (be careful!):
|
|
.sp
|
|
.nf
|
|
.ft C
|
|
rbd rm mypool/myimage
|
|
.ft P
|
|
.fi
|
|
.sp
|
|
To create a new snapshot:
|
|
.sp
|
|
.nf
|
|
.ft C
|
|
rbd snap create mypool/myimage@mysnap
|
|
.ft P
|
|
.fi
|
|
.sp
|
|
To create a copy\-on\-write clone of a protected snapshot:
|
|
.sp
|
|
.nf
|
|
.ft C
|
|
rbd clone mypool/myimage@mysnap otherpool/cloneimage
|
|
.ft P
|
|
.fi
|
|
.sp
|
|
To see which clones of a snapshot exist:
|
|
.sp
|
|
.nf
|
|
.ft C
|
|
rbd children mypool/myimage@mysnap
|
|
.ft P
|
|
.fi
|
|
.sp
|
|
To delete a snapshot:
|
|
.sp
|
|
.nf
|
|
.ft C
|
|
rbd snap rm mypool/myimage@mysnap
|
|
.ft P
|
|
.fi
|
|
.sp
|
|
To map an image via the kernel with cephx enabled:
|
|
.sp
|
|
.nf
|
|
.ft C
|
|
rbd map mypool/myimage \-\-id admin \-\-keyfile secretfile
|
|
.ft P
|
|
.fi
|
|
.sp
|
|
To unmap an image:
|
|
.sp
|
|
.nf
|
|
.ft C
|
|
rbd unmap /dev/rbd0
|
|
.ft P
|
|
.fi
|
|
.sp
|
|
To create an image and a clone from it:
|
|
.sp
|
|
.nf
|
|
.ft C
|
|
rbd import \-\-format 2 image mypool/parent
|
|
rbd snap create \-\-snap snapname mypool/parent
|
|
rbd snap protect mypool/parent@snap
|
|
rbd clone mypool/parent@snap otherpool/child
|
|
.ft P
|
|
.fi
|
|
.sp
|
|
To change an image from one format to another, export it and then
|
|
import it as the desired format:
|
|
.sp
|
|
.nf
|
|
.ft C
|
|
rbd export mypool/myimage@snap /tmp/img
|
|
rbd import \-\-format 2 /tmp/img mypool/myimage2
|
|
.ft P
|
|
.fi
|
|
.SH AVAILABILITY
|
|
.sp
|
|
\fBrbd\fP is part of the Ceph distributed file system. Please refer to
|
|
the Ceph documentation at \fI\%http://ceph.com/docs\fP for more information.
|
|
.SH SEE ALSO
|
|
.sp
|
|
\fBceph\fP(8),
|
|
\fBrados\fP(8)
|
|
.SH COPYRIGHT
|
|
2012, Inktank Storage, Inc.
|
|
.\" Generated by docutils manpage writer.
|
|
.
|