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 name
199 Remove object name.
200 listwatchers name
202 List the watchers of object name.
203 ls outfile
205 List objects in the given pool and write to outfile. Instead of
206 --pool if --pgid will be specified, ls will only list the ob‐
207 jects in the given PG.
208 lssnap List snapshots for given pool.
210 clonedata srcname dstname --object-locator key
212 Clone object byte data from srcname to dstname. Both objects
213 must be stored with the locator key key (usually either srcname
214 or dstname). Object attributes and omap keys are not copied or
215 cloned.
216 mksnap foo
218 Create pool snapshot named foo.
219 rmsnap foo
221 Remove pool snapshot named foo.
222 bench seconds mode [ -b objsize ] [ -t threads ]
224 Benchmark for seconds. The mode can be write, seq, or rand. seq
225 and rand are read benchmarks, either sequential or random. Be‐
226 fore running one of the reading benchmarks, run a write bench‐
227 mark with the --no-cleanup option. The default object size is 4
228 MB, and the default number of simulated threads (parallel
229 writes) is 16. The --run-name <label> option is useful for
230 benchmarking a workload test from multiple clients. The <label>
231 is an arbitrary object name. It is "benchmark_last_metadata" by
232 default, and is used as the underlying object name for "read"
233 and "write" ops. Note: -b objsize option is valid only in write
234 mode. Note: write and seq must be run on the same host other‐
235 wise the objects created by write will have names that will fail
236 seq.
237 cleanup [ --run-name run_name ] [ --prefix prefix ]
239 Clean up a previous benchmark operation. Note: the default
240 run-name is "benchmark_last_metadata"
241 listxattr name
243 List all extended attributes of an object.
244 getxattr name attr
246 Dump the extended attribute value of attr of an object.
247 setxattr name attr value
249 Set the value of attr in the extended attributes of an object.
250 rmxattr name attr
252 Remove attr from the extended attributes of an object.
253 stat name
255 Get stat (ie. mtime, size) of given object
256 stat2 name
258 Get stat (similar to stat, but with high precision time) of
259 given object
260 listomapkeys name
262 List all the keys stored in the object map of object name.
263 listomapvals name
265 List all key/value pairs stored in the object map of object
266 name. The values are dumped in hexadecimal.
267 getomapval [ --omap-key-file file ] name key [ out-file ]
269 Dump the hexadecimal value of key in the object map of object
270 name. If the optional out-file argument is not provided, the
271 value will be written to standard output.
272 setomapval [ --omap-key-file file ] name key [ value ]
274 Set the value of key in the object map of object name. If the
275 optional value argument is not provided, the value will be read
276 from standard input.
277 rmomapkey [ --omap-key-file file ] name key
279 Remove key from the object map of object name.
280 getomapheader name
282 Dump the hexadecimal value of the object map header of object
283 name.
284 setomapheader name value
286 Set the value of the object map header of object name.
287 export filename
289 Serialize pool contents to a file or standard output.n"
290 import [--dry-run] [--no-overwrite] < filename | - >
292 Load pool contents from a file or standard input
293
295 To view cluster utilization:
296 rados df
298 To get a list object in pool foo sent to stdout:
300 rados -p foo ls -
302 To get a list of objects in PG 0.6:
304 rados --pgid 0.6 ls
306 To write an object:
308 rados -p foo put myobject blah.txt
310 To create a snapshot:
312 rados -p foo mksnap mysnap
314 To delete the object:
316 rados -p foo rm myobject
318 To read a previously snapshotted version of an object:
320 rados -p foo -s mysnap get myobject blah.txt.old
322 To list inconsistent objects in PG 0.6:
324 rados list-inconsistent-obj 0.6 --format=json-pretty
326
328 rados is part of Ceph, a massively scalable, open-source, distributed
329 storage system. Please refer to the Ceph documentation at
330 http://ceph.com/docs for more information.
331
333 ceph(8)
334
336 2010-2021, Inktank Storage, Inc. and contributors. Licensed under Cre‐
337 ative Commons Attribution Share Alike 3.0 (CC-BY-SA-3.0)
338dev May 13, 2021 RADOS(8)