]>
Commit | Line | Data |
---|---|---|
7c673cae FG |
1 | ======================= |
2 | Block Device Commands | |
3 | ======================= | |
4 | ||
5 | .. index:: Ceph Block Device; image management | |
6 | ||
7 | The ``rbd`` command enables you to create, list, introspect and remove block | |
8 | device images. You can also use it to clone images, create snapshots, | |
9 | rollback an image to a snapshot, view a snapshot, etc. For details on using | |
10 | the ``rbd`` command, see `RBD – Manage RADOS Block Device (RBD) Images`_ for | |
11 | details. | |
12 | ||
13 | .. important:: To use Ceph Block Device commands, you must have access to | |
14 | a running Ceph cluster. | |
15 | ||
c07f9fc5 FG |
16 | Create a Block Device Pool |
17 | ========================== | |
18 | ||
19 | #. On the admin node, use the ``ceph`` tool to `create a pool`_. | |
20 | ||
21 | #. On the admin node, use the ``rbd`` tool to initialize the pool for use by RBD:: | |
22 | ||
23 | rbd pool init <pool-name> | |
24 | ||
25 | .. note:: The ``rbd`` tool assumes a default pool name of 'rbd' when not | |
26 | provided. | |
27 | ||
28 | Create a Block Device User | |
29 | ========================== | |
30 | ||
31 | Unless specified, the ``rbd`` command will access the Ceph cluster using the ID | |
32 | ``admin``. This ID allows full administrative access to the cluster. It is | |
33 | recommended that you utilize a more restricted user wherever possible. | |
34 | ||
35 | To `create a Ceph user`_, with ``ceph`` specify the ``auth get-or-create`` | |
36 | command, user name, monitor caps, and OSD caps:: | |
37 | ||
38 | ceph auth get-or-create client.{ID} mon 'profile rbd' osd 'profile {profile name} [pool={pool-name}][, profile ...]' | |
39 | ||
40 | For example, to create a user ID named ``qemu`` with read-write access to the | |
41 | pool ``vms`` and read-only access to the pool ``images``, execute the | |
42 | following:: | |
43 | ||
44 | ceph auth get-or-create client.qemu mon 'profile rbd' osd 'profile rbd pool=vms, profile rbd-read-only pool=images' | |
45 | ||
46 | The output from the ``ceph auth get-or-create`` command will be the keyring for | |
47 | the specified user, which can be written to ``/etc/ceph/ceph.client.{ID}.keyring``. | |
48 | ||
49 | .. note:: The user ID can be specified when using the ``rbd`` command by | |
50 | providing the ``--id {id}`` optional argument. | |
7c673cae FG |
51 | |
52 | Creating a Block Device Image | |
53 | ============================= | |
54 | ||
55 | Before you can add a block device to a node, you must create an image for it in | |
56 | the :term:`Ceph Storage Cluster` first. To create a block device image, execute | |
57 | the following:: | |
58 | ||
59 | rbd create --size {megabytes} {pool-name}/{image-name} | |
c07f9fc5 | 60 | |
7c673cae FG |
61 | For example, to create a 1GB image named ``bar`` that stores information in a |
62 | pool named ``swimmingpool``, execute the following:: | |
63 | ||
64 | rbd create --size 1024 swimmingpool/bar | |
65 | ||
66 | If you don't specify pool when creating an image, it will be stored in the | |
67 | default pool ``rbd``. For example, to create a 1GB image named ``foo`` stored in | |
68 | the default pool ``rbd``, execute the following:: | |
69 | ||
70 | rbd create --size 1024 foo | |
71 | ||
72 | .. note:: You must create a pool first before you can specify it as a | |
73 | source. See `Storage Pools`_ for details. | |
74 | ||
75 | Listing Block Device Images | |
76 | =========================== | |
77 | ||
78 | To list block devices in the ``rbd`` pool, execute the following | |
79 | (i.e., ``rbd`` is the default pool name):: | |
80 | ||
81 | rbd ls | |
82 | ||
83 | To list block devices in a particular pool, execute the following, | |
84 | but replace ``{poolname}`` with the name of the pool:: | |
85 | ||
86 | rbd ls {poolname} | |
87 | ||
88 | For example:: | |
89 | ||
90 | rbd ls swimmingpool | |
c07f9fc5 FG |
91 | |
92 | To list deferred delete block devices in the ``rbd`` pool, execute the | |
93 | following:: | |
94 | ||
95 | rbd trash ls | |
96 | ||
97 | To list deferred delete block devices in a particular pool, execute the | |
98 | following, but replace ``{poolname}`` with the name of the pool:: | |
99 | ||
100 | rbd trash ls {poolname} | |
101 | ||
102 | For example:: | |
103 | ||
104 | rbd trash ls swimmingpool | |
105 | ||
7c673cae FG |
106 | Retrieving Image Information |
107 | ============================ | |
108 | ||
109 | To retrieve information from a particular image, execute the following, | |
110 | but replace ``{image-name}`` with the name for the image:: | |
111 | ||
112 | rbd info {image-name} | |
113 | ||
114 | For example:: | |
115 | ||
116 | rbd info foo | |
117 | ||
118 | To retrieve information from an image within a pool, execute the following, | |
119 | but replace ``{image-name}`` with the name of the image and replace ``{pool-name}`` | |
120 | with the name of the pool:: | |
121 | ||
122 | rbd info {pool-name}/{image-name} | |
123 | ||
124 | For example:: | |
125 | ||
126 | rbd info swimmingpool/bar | |
127 | ||
128 | Resizing a Block Device Image | |
129 | ============================= | |
130 | ||
131 | :term:`Ceph Block Device` images are thin provisioned. They don't actually use | |
132 | any physical storage until you begin saving data to them. However, they do have | |
133 | a maximum capacity that you set with the ``--size`` option. If you want to | |
134 | increase (or decrease) the maximum size of a Ceph Block Device image, execute | |
135 | the following:: | |
136 | ||
137 | rbd resize --size 2048 foo (to increase) | |
138 | rbd resize --size 2048 foo --allow-shrink (to decrease) | |
139 | ||
140 | ||
141 | Removing a Block Device Image | |
142 | ============================= | |
143 | ||
144 | To remove a block device, execute the following, but replace ``{image-name}`` | |
145 | with the name of the image you want to remove:: | |
146 | ||
147 | rbd rm {image-name} | |
c07f9fc5 | 148 | |
7c673cae FG |
149 | For example:: |
150 | ||
151 | rbd rm foo | |
c07f9fc5 | 152 | |
7c673cae FG |
153 | To remove a block device from a pool, execute the following, but replace |
154 | ``{image-name}`` with the name of the image to remove and replace | |
155 | ``{pool-name}`` with the name of the pool:: | |
156 | ||
157 | rbd rm {pool-name}/{image-name} | |
c07f9fc5 | 158 | |
7c673cae FG |
159 | For example:: |
160 | ||
161 | rbd rm swimmingpool/bar | |
162 | ||
c07f9fc5 FG |
163 | To defer delete a block device from a pool, execute the following, but |
164 | replace ``{image-name}`` with the name of the image to move and replace | |
165 | ``{pool-name}`` with the name of the pool:: | |
166 | ||
167 | rbd trash mv {pool-name}/{image-name} | |
168 | ||
169 | For example:: | |
170 | ||
171 | rbd trash mv swimmingpool/bar | |
172 | ||
173 | To remove a deferred block device from a pool, execute the following, but | |
174 | replace ``{image-id}`` with the id of the image to remove and replace | |
175 | ``{pool-name}`` with the name of the pool:: | |
176 | ||
177 | rbd trash rm {pool-name}/{image-id} | |
178 | ||
179 | For example:: | |
180 | ||
181 | rbd trash rm swimmingpool/2bf4474b0dc51 | |
182 | ||
183 | .. note:: | |
184 | ||
185 | * You can move an image to the trash even it has shapshot(s) or actively | |
186 | in-use by clones, but can not be removed from trash. | |
187 | ||
188 | * You can use *--delay* to set the defer time (default is 0), and if its | |
189 | deferment time has not expired, it can not be removed unless you use | |
190 | force. | |
191 | ||
192 | Restoring a Block Device Image | |
193 | ============================== | |
194 | ||
195 | To restore a deferred delete block device in the rbd pool, execute the | |
196 | following, but replace ``{image-id}`` with the id of the image:: | |
197 | ||
198 | rbd trash restore {image-d} | |
199 | ||
200 | For example:: | |
201 | ||
202 | rbd trash restore 2bf4474b0dc51 | |
203 | ||
204 | To restore a deferred delete block device in a particular pool, execute | |
205 | the following, but replace ``{image-id}`` with the id of the image and | |
206 | replace ``{pool-name}`` with the name of the pool:: | |
207 | ||
208 | rbd trash restore {pool-name}/{image-id} | |
209 | ||
210 | For example:: | |
211 | ||
212 | rbd trash restore swimmingpool/2bf4474b0dc51 | |
213 | ||
214 | Also you can use *--image* to rename the iamge when restore it, for | |
215 | example:: | |
216 | ||
217 | rbd trash restore swimmingpool/2bf4474b0dc51 --image new-name | |
7c673cae FG |
218 | |
219 | ||
c07f9fc5 | 220 | .. _create a pool: ../../rados/operations/pools/#create-a-pool |
7c673cae FG |
221 | .. _Storage Pools: ../../rados/operations/pools |
222 | .. _RBD – Manage RADOS Block Device (RBD) Images: ../../man/8/rbd/ | |
c07f9fc5 | 223 | .. _create a Ceph user: ../../rados/operations/user-management#add-a-user |