]>
Commit | Line | Data |
---|---|---|
7c673cae FG |
1 | :orphan: |
2 | ||
3 | ======================================= | |
4 | rados -- rados object storage utility | |
5 | ======================================= | |
6 | ||
7 | .. program:: rados | |
8 | ||
9 | Synopsis | |
10 | ======== | |
11 | ||
11fdf7f2 | 12 | | **rados** [ *options* ] [ *command* ] |
7c673cae FG |
13 | |
14 | ||
15 | Description | |
16 | =========== | |
17 | ||
18 | **rados** is a utility for interacting with a Ceph object storage | |
19 | cluster (RADOS), part of the Ceph distributed storage system. | |
20 | ||
21 | ||
f67539c2 TL |
22 | Global Options |
23 | ============== | |
24 | ||
25 | .. option:: --object-locator object_locator | |
26 | ||
27 | Set object_locator for operation. | |
7c673cae FG |
28 | |
29 | .. option:: -p pool, --pool pool | |
30 | ||
31 | Interact with the given pool. Required by most commands. | |
32 | ||
f67539c2 TL |
33 | .. option:: --target-pool pool |
34 | ||
35 | Select target pool by name. | |
36 | ||
eafe8130 TL |
37 | .. option:: --pgid |
38 | ||
39 | As an alternative to ``--pool``, ``--pgid`` also allow users to specify the | |
40 | PG id to which the command will be directed. With this option, certain | |
41 | commands like ``ls`` allow users to limit the scope of the command to the given PG. | |
42 | ||
43 | .. option:: -N namespace, --namespace namespace | |
44 | ||
45 | Specify the rados namespace to use for the object. | |
46 | ||
f67539c2 TL |
47 | .. option:: --all |
48 | ||
49 | Use with ls to list objects in all namespaces. | |
50 | Put in CEPH_ARGS environment variable to make this the default. | |
51 | ||
52 | .. option:: --default | |
53 | ||
54 | Use with ls to list objects in default namespace. | |
55 | Takes precedence over --all in case --all is in environment. | |
56 | ||
7c673cae FG |
57 | .. option:: -s snap, --snap snap |
58 | ||
59 | Read from the given pool snapshot. Valid for all pool-specific read operations. | |
60 | ||
f67539c2 TL |
61 | .. option:: --create |
62 | ||
63 | Create the pool or directory that was specified. | |
64 | ||
7c673cae FG |
65 | .. option:: -i infile |
66 | ||
67 | will specify an input file to be passed along as a payload with the | |
68 | command to the monitor cluster. This is only used for specific | |
69 | monitor commands. | |
70 | ||
7c673cae FG |
71 | .. option:: -m monaddress[:port] |
72 | ||
73 | Connect to specified monitor (instead of looking through ceph.conf). | |
74 | ||
75 | .. option:: -b block_size | |
76 | ||
77 | Set the block size for put/get/append ops and for write benchmarking. | |
78 | ||
79 | .. option:: --striper | |
80 | ||
81 | Uses the striping API of rados rather than the default one. | |
11fdf7f2 | 82 | Available for stat, stat2, get, put, append, truncate, rm, ls |
f67539c2 TL |
83 | and all xattr related operation. |
84 | ||
85 | .. option:: -O object_size, --object-size object_size | |
86 | ||
87 | Set the object size for put/get ops and for write benchmarking. | |
7c673cae | 88 | |
f67539c2 | 89 | .. option:: --max-objects |
9f95a23c | 90 | |
f67539c2 | 91 | Set the max number of objects for write benchmarking. |
9f95a23c TL |
92 | |
93 | .. option:: --lock-cookie locker-cookie | |
94 | ||
f67539c2 | 95 | Will set the lock cookie for acquiring advisory lock (lock get command). |
9f95a23c TL |
96 | If the cookie is not empty, this option must be passed to lock break command |
97 | to find the correct lock when releasing lock. | |
98 | ||
f67539c2 TL |
99 | .. option:: --target-locator |
100 | ||
101 | Use with cp to specify the locator of the new object. | |
102 | ||
103 | .. option:: --target-nspace | |
104 | ||
105 | Use with cp to specify the namespace of the new object. | |
106 | ||
107 | ||
108 | Bench options | |
109 | ============= | |
110 | ||
111 | .. option:: -t N, --concurrent-ios=N | |
112 | ||
113 | Set number of concurrent I/O operations. | |
114 | ||
115 | .. option:: --show-time | |
116 | ||
117 | Prefix output with date/time. | |
118 | ||
119 | .. option:: --no-verify | |
120 | ||
121 | Do not verify contents of read objects. | |
122 | ||
123 | .. option:: --write-object | |
124 | ||
125 | Write contents to the objects. | |
126 | ||
127 | .. option:: --write-omap | |
128 | ||
129 | Write contents to the omap. | |
130 | ||
131 | .. option:: --write-xattr | |
132 | ||
133 | Write contents to the extended attributes. | |
134 | ||
135 | ||
136 | Load gen options | |
137 | ================ | |
138 | ||
139 | .. option:: --num-objects | |
140 | ||
141 | Total number of objects. | |
142 | ||
143 | .. option:: --min-object-size | |
144 | ||
145 | Min object size. | |
146 | ||
147 | .. option:: --max-object-size | |
148 | ||
149 | Max object size. | |
150 | ||
151 | .. option:: --min-op-len | |
152 | ||
153 | Min io size of operations. | |
154 | ||
155 | .. option:: --max-op-len | |
156 | ||
157 | Max io size of operations. | |
158 | ||
159 | .. option:: --max-ops | |
160 | ||
161 | Max number of operations. | |
162 | ||
163 | .. option:: --max-backlog | |
164 | ||
165 | Max backlog size. | |
166 | ||
167 | .. option:: --read-percent | |
168 | ||
169 | Percent of operations that are read. | |
170 | ||
171 | .. option:: --target-throughput | |
172 | ||
173 | Target throughput (in bytes). | |
174 | ||
175 | .. option:: --run-length | |
176 | ||
177 | Total time (in seconds). | |
178 | ||
179 | .. option:: --offset-align | |
180 | ||
181 | At what boundary to align random op offsets. | |
182 | ||
183 | ||
184 | Cache pools options | |
185 | =================== | |
186 | ||
187 | .. option:: --with-clones | |
188 | ||
189 | Include clones when doing flush or evict. | |
190 | ||
191 | ||
192 | OMAP options | |
193 | ============ | |
194 | ||
195 | .. option:: --omap-key-file file | |
196 | ||
197 | Read the omap key from a file. | |
198 | ||
199 | ||
200 | Generic options | |
201 | =============== | |
202 | ||
203 | .. option:: -c FILE, --conf FILE | |
204 | ||
205 | Read configuration from the given configuration file. | |
206 | ||
207 | .. option:: --id ID | |
208 | ||
209 | Set ID portion of my name. | |
210 | ||
211 | .. option:: -n TYPE.ID, --name TYPE.ID | |
212 | ||
213 | Set cephx user name. | |
214 | ||
215 | .. option:: --cluster NAME | |
216 | ||
217 | Set cluster name (default: ceph). | |
218 | ||
219 | .. option:: --setuser USER | |
220 | ||
221 | Set uid to user or uid (and gid to user's gid). | |
222 | ||
223 | .. option:: --setgroup GROUP | |
224 | ||
225 | Set gid to group or gid. | |
226 | ||
227 | .. option:: --version | |
228 | ||
229 | Show version and quit. | |
230 | ||
7c673cae FG |
231 | |
232 | Global commands | |
233 | =============== | |
234 | ||
235 | :command:`lspools` | |
236 | List object pools | |
237 | ||
238 | :command:`df` | |
239 | Show utilization statistics, including disk usage (bytes) and object | |
240 | counts, over the entire system and broken down by pool. | |
241 | ||
7c673cae FG |
242 | :command:`list-inconsistent-pg` *pool* |
243 | List inconsistent PGs in given pool. | |
244 | ||
245 | :command:`list-inconsistent-obj` *pgid* | |
246 | List inconsistent objects in given PG. | |
247 | ||
248 | :command:`list-inconsistent-snapset` *pgid* | |
249 | List inconsistent snapsets in given PG. | |
250 | ||
11fdf7f2 | 251 | |
7c673cae FG |
252 | Pool specific commands |
253 | ====================== | |
254 | ||
255 | :command:`get` *name* *outfile* | |
256 | Read object name from the cluster and write it to outfile. | |
257 | ||
224ce89b WB |
258 | :command:`put` *name* *infile* [--offset offset] |
259 | Write object name with start offset (default:0) to the cluster with contents from infile. | |
11fdf7f2 TL |
260 | **Warning:** The put command creates a single RADOS object, sized just as |
261 | large as your input file. Unless your objects are of reasonable and consistent sizes, that | |
262 | is probably not what you want -- consider using RGW/S3, CephFS, or RBD instead. | |
7c673cae FG |
263 | |
264 | :command:`append` *name* *infile* | |
265 | Append object name to the cluster with contents from infile. | |
266 | ||
20effc67 TL |
267 | :command:`rm` [--force-full] *name* ... |
268 | Remove object(s) with name(s). With ``--force-full`` will remove when cluster is marked full. | |
7c673cae FG |
269 | |
270 | :command:`listwatchers` *name* | |
271 | List the watchers of object name. | |
272 | ||
273 | :command:`ls` *outfile* | |
eafe8130 | 274 | List objects in the given pool and write to outfile. Instead of ``--pool`` if ``--pgid`` will be specified, ``ls`` will only list the objects in the given PG. |
7c673cae FG |
275 | |
276 | :command:`lssnap` | |
277 | List snapshots for given pool. | |
278 | ||
279 | :command:`clonedata` *srcname* *dstname* --object-locator *key* | |
280 | Clone object byte data from *srcname* to *dstname*. Both objects must be stored with the locator key *key* (usually either *srcname* or *dstname*). Object attributes and omap keys are not copied or cloned. | |
281 | ||
282 | :command:`mksnap` *foo* | |
283 | Create pool snapshot named *foo*. | |
284 | ||
285 | :command:`rmsnap` *foo* | |
286 | Remove pool snapshot named *foo*. | |
287 | ||
288 | :command:`bench` *seconds* *mode* [ -b *objsize* ] [ -t *threads* ] | |
289 | Benchmark for *seconds*. The mode can be *write*, *seq*, or | |
290 | *rand*. *seq* and *rand* are read benchmarks, either | |
291 | sequential or random. Before running one of the reading benchmarks, | |
292 | run a write benchmark with the *--no-cleanup* option. The default | |
293 | object size is 4 MB, and the default number of simulated threads | |
294 | (parallel writes) is 16. The *--run-name <label>* option is useful | |
295 | for benchmarking a workload test from multiple clients. The *<label>* | |
296 | is an arbitrary object name. It is "benchmark_last_metadata" by | |
297 | default, and is used as the underlying object name for "read" and | |
298 | "write" ops. | |
299 | Note: -b *objsize* option is valid only in *write* mode. | |
300 | Note: *write* and *seq* must be run on the same host otherwise the | |
301 | objects created by *write* will have names that will fail *seq*. | |
302 | ||
d2e6a577 FG |
303 | :command:`cleanup` [ --run-name *run_name* ] [ --prefix *prefix* ] |
304 | Clean up a previous benchmark operation. | |
305 | Note: the default run-name is "benchmark_last_metadata" | |
7c673cae | 306 | |
31f18b77 FG |
307 | :command:`listxattr` *name* |
308 | List all extended attributes of an object. | |
309 | ||
310 | :command:`getxattr` *name* *attr* | |
311 | Dump the extended attribute value of *attr* of an object. | |
312 | ||
313 | :command:`setxattr` *name* *attr* *value* | |
314 | Set the value of *attr* in the extended attributes of an object. | |
315 | ||
316 | :command:`rmxattr` *name* *attr* | |
317 | Remove *attr* from the extended attributes of an object. | |
318 | ||
11fdf7f2 TL |
319 | :command:`stat` *name* |
320 | Get stat (ie. mtime, size) of given object | |
321 | ||
322 | :command:`stat2` *name* | |
323 | Get stat (similar to stat, but with high precision time) of given object | |
324 | ||
7c673cae FG |
325 | :command:`listomapkeys` *name* |
326 | List all the keys stored in the object map of object name. | |
327 | ||
328 | :command:`listomapvals` *name* | |
329 | List all key/value pairs stored in the object map of object name. | |
330 | The values are dumped in hexadecimal. | |
331 | ||
332 | :command:`getomapval` [ --omap-key-file *file* ] *name* *key* [ *out-file* ] | |
333 | Dump the hexadecimal value of key in the object map of object name. | |
c07f9fc5 | 334 | If the optional *out-file* argument is not provided, the value will be |
7c673cae FG |
335 | written to standard output. |
336 | ||
337 | :command:`setomapval` [ --omap-key-file *file* ] *name* *key* [ *value* ] | |
338 | Set the value of key in the object map of object name. If the optional | |
c07f9fc5 | 339 | *value* argument is not provided, the value will be read from standard |
7c673cae FG |
340 | input. |
341 | ||
342 | :command:`rmomapkey` [ --omap-key-file *file* ] *name* *key* | |
343 | Remove key from the object map of object name. | |
344 | ||
345 | :command:`getomapheader` *name* | |
346 | Dump the hexadecimal value of the object map header of object name. | |
347 | ||
348 | :command:`setomapheader` *name* *value* | |
349 | Set the value of the object map header of object name. | |
350 | ||
11fdf7f2 TL |
351 | :command:`export` *filename* |
352 | Serialize pool contents to a file or standard output.\n" | |
353 | ||
354 | :command:`import` [--dry-run] [--no-overwrite] < filename | - > | |
355 | Load pool contents from a file or standard input | |
356 | ||
357 | ||
7c673cae FG |
358 | Examples |
359 | ======== | |
360 | ||
361 | To view cluster utilization:: | |
362 | ||
363 | rados df | |
364 | ||
365 | To get a list object in pool foo sent to stdout:: | |
366 | ||
367 | rados -p foo ls - | |
368 | ||
eafe8130 TL |
369 | To get a list of objects in PG 0.6:: |
370 | ||
371 | rados --pgid 0.6 ls | |
372 | ||
7c673cae FG |
373 | To write an object:: |
374 | ||
375 | rados -p foo put myobject blah.txt | |
376 | ||
377 | To create a snapshot:: | |
378 | ||
379 | rados -p foo mksnap mysnap | |
380 | ||
381 | To delete the object:: | |
382 | ||
383 | rados -p foo rm myobject | |
384 | ||
385 | To read a previously snapshotted version of an object:: | |
386 | ||
387 | rados -p foo -s mysnap get myobject blah.txt.old | |
388 | ||
389 | To list inconsistent objects in PG 0.6:: | |
390 | ||
391 | rados list-inconsistent-obj 0.6 --format=json-pretty | |
392 | ||
393 | ||
394 | Availability | |
395 | ============ | |
396 | ||
397 | **rados** is part of Ceph, a massively scalable, open-source, distributed storage system. Please refer to | |
20effc67 | 398 | the Ceph documentation at https://docs.ceph.com for more information. |
7c673cae FG |
399 | |
400 | ||
401 | See also | |
402 | ======== | |
403 | ||
404 | :doc:`ceph <ceph>`\(8) |