1RADOS(8) Ceph RADOS(8)
2
6 rados - rados object storage utility
7
9 rados [ options ] [ command ]
10
13 rados is a utility for interacting with a Ceph object storage cluster
14 (RADOS), part of the Ceph distributed storage system.
15
17 --object-locator object_locator
18 Set object_locator for operation.
19 -p pool, --pool pool
21 Interact with the given pool. Required by most commands.
22 --target-pool pool
24 Select target pool by name.
25 --pgid As an alternative to --pool, --pgid also allow users to specify
27 the PG id to which the command will be directed. With this op‐
28 tion, certain commands like ls allow users to limit the scope of
29 the command to the given PG.
30 -N namespace, --namespace namespace
32 Specify the rados namespace to use for the object.
33 --all Use with ls to list objects in all namespaces. Put in CEPH_ARGS
35 environment variable to make this the default.
36 --default
38 Use with ls to list objects in default namespace. Takes prece‐
39 dence over --all in case --all is in environment.
40 -s snap, --snap snap
42 Read from the given pool snapshot. Valid for all pool-specific
43 read operations.
44 --create
46 Create the pool or directory that was specified.
47 -i infile
49 will specify an input file to be passed along as a payload with
50 the command to the monitor cluster. This is only used for spe‐
51 cific monitor commands.
52 -m monaddress[:port]
54 Connect to specified monitor (instead of looking through
55 ceph.conf).
56 -b block_size
58 Set the block size for put/get/append ops and for write bench‐
59 marking.
60 --striper
62 Uses the striping API of rados rather than the default one.
63 Available for stat, stat2, get, put, append, truncate, rm, ls
64 and all xattr related operation.
65 -O object_size, --object-size object_size
67 Set the object size for put/get ops and for write benchmarking.
68 --max-objects
70 Set the max number of objects for write benchmarking.
71 --lock-cookie locker-cookie
73 Will set the lock cookie for acquiring advisory lock (lock get
74 command). If the cookie is not empty, this option must be
75 passed to lock break command to find the correct lock when re‐
76 leasing lock.
77 --target-locator
79 Use with cp to specify the locator of the new object.
80 --target-nspace
82 Use with cp to specify the namespace of the new object.
83
85 -t N, --concurrent-ios=N
86 Set number of concurrent I/O operations.
87 --show-time
89 Prefix output with date/time.
90 --no-verify
92 Do not verify contents of read objects.
93 --write-object
95 Write contents to the objects.
96 --write-omap
98 Write contents to the omap.
99 --write-xattr
101 Write contents to the extended attributes.
102
104 --num-objects
105 Total number of objects.
106 --min-object-size
108 Min object size.
109 --max-object-size
111 Max object size.
112 --min-op-len
114 Min io size of operations.
115 --max-op-len
117 Max io size of operations.
118 --max-ops
120 Max number of operations.
121 --max-backlog
123 Max backlog size.
124 --read-percent
126 Percent of operations that are read.
127 --target-throughput
129 Target throughput (in bytes).
130 --run-length
132 Total time (in seconds).
133 --offset-align
135 At what boundary to align random op offsets.
136
138 --with-clones
139 Include clones when doing flush or evict.
140
142 --omap-key-file file
143 Read the omap key from a file.
144
146 -c FILE, --conf FILE
147 Read configuration from the given configuration file.
148 --id ID
150 Set ID portion of my name.
151 -n TYPE.ID, --name TYPE.ID
153 Set cephx user name.
154 --cluster NAME
156 Set cluster name (default: ceph).
157 --setuser USER
159 Set uid to user or uid (and gid to user's gid).
160 --setgroup GROUP
162 Set gid to group or gid.
163 --version
165 Show version and quit.
166
168 lspools
169 List object pools
170 df Show utilization statistics, including disk usage (bytes) and
172 object counts, over the entire system and broken down by pool.
173 list-inconsistent-pg pool
175 List inconsistent PGs in given pool.
176 list-inconsistent-obj pgid
178 List inconsistent objects in given PG.
179 list-inconsistent-snapset pgid
181 List inconsistent snapsets in given PG.
182
184 get name outfile
185 Read object name from the cluster and write it to outfile.
186 put name infile [--offset offset]
188 Write object name with start offset (default:0) to the cluster
189 with contents from infile. Warning: The put command creates a
190 single RADOS object, sized just as large as your input file. Un‐
191 less your objects are of reasonable and consistent sizes, that
192 is probably not what you want -- consider using RGW/S3, CephFS,
193 or RBD instead.
194 append name infile
196 Append object name to the cluster with contents from infile.
197 rm [--force-full] name ...
199 Remove object(s) with name(s). With --force-full will remove
200 when cluster is marked full.
201 listwatchers name
203 List the watchers of object name.
204 ls outfile
206 List objects in the given pool and write to outfile. Instead of
207 --pool if --pgid will be specified, ls will only list the ob‐
208 jects in the given PG.
209 lssnap List snapshots for given pool.
211 clonedata srcname dstname --object-locator key
213 Clone object byte data from srcname to dstname. Both objects
214 must be stored with the locator key key (usually either srcname
215 or dstname). Object attributes and omap keys are not copied or
216 cloned.
217 mksnap foo
219 Create pool snapshot named foo.
220 rmsnap foo
222 Remove pool snapshot named foo.
223 bench seconds mode [ -b objsize ] [ -t threads ]
225 Benchmark for seconds. The mode can be write, seq, or rand. seq
226 and rand are read benchmarks, either sequential or random. Be‐
227 fore running one of the reading benchmarks, run a write bench‐
228 mark with the --no-cleanup option. The default object size is 4
229 MB, and the default number of simulated threads (parallel
230 writes) is 16. The --run-name <label> option is useful for
231 benchmarking a workload test from multiple clients. The <label>
232 is an arbitrary object name. It is "benchmark_last_metadata" by
233 default, and is used as the underlying object name for "read"
234 and "write" ops. Note: -b objsize option is valid only in write
235 mode. Note: write and seq must be run on the same host other‐
236 wise the objects created by write will have names that will fail
237 seq.
238 cleanup [ --run-name run_name ] [ --prefix prefix ]
240 Clean up a previous benchmark operation. Note: the default
241 run-name is "benchmark_last_metadata"
242 listxattr name
244 List all extended attributes of an object.
245 getxattr name attr
247 Dump the extended attribute value of attr of an object.
248 setxattr name attr value
250 Set the value of attr in the extended attributes of an object.
251 rmxattr name attr
253 Remove attr from the extended attributes of an object.
254 stat name
256 Get stat (ie. mtime, size) of given object
257 stat2 name
259 Get stat (similar to stat, but with high precision time) of
260 given object
261 listomapkeys name
263 List all the keys stored in the object map of object name.
264 listomapvals name
266 List all key/value pairs stored in the object map of object
267 name. The values are dumped in hexadecimal.
268 getomapval [ --omap-key-file file ] name key [ out-file ]
270 Dump the hexadecimal value of key in the object map of object
271 name. If the optional out-file argument is not provided, the
272 value will be written to standard output.
273 setomapval [ --omap-key-file file ] name key [ value ]
275 Set the value of key in the object map of object name. If the
276 optional value argument is not provided, the value will be read
277 from standard input.
278 rmomapkey [ --omap-key-file file ] name key
280 Remove key from the object map of object name.
281 getomapheader name
283 Dump the hexadecimal value of the object map header of object
284 name.
285 setomapheader name value
287 Set the value of the object map header of object name.
288 export filename
290 Serialize pool contents to a file or standard output.n"
291 import [--dry-run] [--no-overwrite] < filename | - >
293 Load pool contents from a file or standard input
294
296 To view cluster utilization:
297 rados df
299 To get a list object in pool foo sent to stdout:
301 rados -p foo ls -
303 To get a list of objects in PG 0.6:
305 rados --pgid 0.6 ls
307 To write an object:
309 rados -p foo put myobject blah.txt
311 To create a snapshot:
313 rados -p foo mksnap mysnap
315 To delete the object:
317 rados -p foo rm myobject
319 To read a previously snapshotted version of an object:
321 rados -p foo -s mysnap get myobject blah.txt.old
323 To list inconsistent objects in PG 0.6:
325 rados list-inconsistent-obj 0.6 --format=json-pretty
327
329 rados is part of Ceph, a massively scalable, open-source, distributed
330 storage system. Please refer to the Ceph documentation at
331 https://docs.ceph.com for more information.
332
334 ceph(8)
335
337 2010-2023, Inktank Storage, Inc. and contributors. Licensed under Cre‐
338 ative Commons Attribution Share Alike 3.0 (CC-BY-SA-3.0)
339dev Nov 02, 2023 RADOS(8)