1RADOS(8)                             Ceph                             RADOS(8)
2
3
4

NAME

6       rados - rados object storage utility
7

SYNOPSIS

9       rados [ options ] [ command ]
10
11

DESCRIPTION

13       rados  is  a utility for interacting with a Ceph object storage cluster
14       (RADOS), part of the Ceph distributed storage system.
15

GLOBAL OPTIONS

17       --object-locator object_locator
18              Set object_locator for operation.
19
20       -p pool, --pool pool
21              Interact with the given pool. Required by most commands.
22
23       --target-pool pool
24              Select target pool by name.
25
26       --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
31       -N namespace, --namespace namespace
32              Specify the rados namespace to use for the object.
33
34       --all  Use with ls to list objects in all namespaces.  Put in CEPH_ARGS
35              environment variable to make this the default.
36
37       --default
38              Use with ls to list objects in default namespace.  Takes  prece‐
39              dence over --all in case --all is in environment.
40
41       -s snap, --snap snap
42              Read  from  the given pool snapshot. Valid for all pool-specific
43              read operations.
44
45       --create
46              Create the pool or directory that was specified.
47
48       -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
53       -m monaddress[:port]
54              Connect  to  specified  monitor  (instead  of  looking   through
55              ceph.conf).
56
57       -b block_size
58              Set  the  block size for put/get/append ops and for write bench‐
59              marking.
60
61       --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
66       -O object_size, --object-size object_size
67              Set the object size for put/get ops and for write benchmarking.
68
69       --max-objects
70              Set the max number of objects for write benchmarking.
71
72       --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
78       --target-locator
79              Use with cp to specify the locator of the new object.
80
81       --target-nspace
82              Use with cp to specify the namespace of the new object.
83

BENCH OPTIONS

85       -t N, --concurrent-ios=N
86              Set number of concurrent I/O operations.
87
88       --show-time
89              Prefix output with date/time.
90
91       --no-verify
92              Do not verify contents of read objects.
93
94       --write-object
95              Write contents to the objects.
96
97       --write-omap
98              Write contents to the omap.
99
100       --write-xattr
101              Write contents to the extended attributes.
102

LOAD GEN OPTIONS

104       --num-objects
105              Total number of objects.
106
107       --min-object-size
108              Min object size.
109
110       --max-object-size
111              Max object size.
112
113       --min-op-len
114              Min io size of operations.
115
116       --max-op-len
117              Max io size of operations.
118
119       --max-ops
120              Max number of operations.
121
122       --max-backlog
123              Max backlog size.
124
125       --read-percent
126              Percent of operations that are read.
127
128       --target-throughput
129              Target throughput (in bytes).
130
131       --run-length
132              Total time (in seconds).
133
134       --offset-align
135              At what boundary to align random op offsets.
136

CACHE POOLS OPTIONS

138       --with-clones
139              Include clones when doing flush or evict.
140

OMAP OPTIONS

142       --omap-key-file file
143              Read the omap key from a file.
144

GENERIC OPTIONS

146       -c FILE, --conf FILE
147              Read configuration from the given configuration file.
148
149       --id ID
150              Set ID portion of my name.
151
152       -n TYPE.ID, --name TYPE.ID
153              Set cephx user name.
154
155       --cluster NAME
156              Set cluster name (default: ceph).
157
158       --setuser USER
159              Set uid to user or uid (and gid to user's gid).
160
161       --setgroup GROUP
162              Set gid to group or gid.
163
164       --version
165              Show version and quit.
166

GLOBAL COMMANDS

168       lspools
169              List object pools
170
171       df     Show  utilization  statistics,  including disk usage (bytes) and
172              object counts, over the entire system and broken down by pool.
173
174       list-inconsistent-pg pool
175              List inconsistent PGs in given pool.
176
177       list-inconsistent-obj pgid
178              List inconsistent objects in given PG.
179
180       list-inconsistent-snapset pgid
181              List inconsistent snapsets in given PG.
182

POOL SPECIFIC COMMANDS

184       get name outfile
185              Read object name from the cluster and write it to outfile.
186
187       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
195       append name infile
196              Append object name to the cluster with contents from infile.
197
198       rm [--force-full] name ...
199              Remove  object(s)  with  name(s).  With --force-full will remove
200              when cluster is marked full.
201
202       listwatchers name
203              List the watchers of object name.
204
205       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
210       lssnap List snapshots for given pool.
211
212       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
218       mksnap foo
219              Create pool snapshot named foo.
220
221       rmsnap foo
222              Remove pool snapshot named foo.
223
224       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
239       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
243       listxattr name
244              List all extended attributes of an object.
245
246       getxattr name attr
247              Dump the extended attribute value of attr of an object.
248
249       setxattr name attr value
250              Set the value of attr in the extended attributes of an object.
251
252       rmxattr name attr
253              Remove attr from the extended attributes of an object.
254
255       stat name
256              Get stat (ie. mtime, size) of given object
257
258       stat2 name
259              Get stat (similar to stat, but  with  high  precision  time)  of
260              given object
261
262       listomapkeys name
263              List all the keys stored in the object map of object name.
264
265       listomapvals name
266              List  all  key/value  pairs  stored  in the object map of object
267              name.  The values are dumped in hexadecimal.
268
269       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
274       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
279       rmomapkey [ --omap-key-file file ] name key
280              Remove key from the object map of object name.
281
282       getomapheader name
283              Dump the hexadecimal value of the object map  header  of  object
284              name.
285
286       setomapheader name value
287              Set the value of the object map header of object name.
288
289       export filename
290              Serialize pool contents to a file or standard output.n"
291
292       import [--dry-run] [--no-overwrite] < filename | - >
293              Load pool contents from a file or standard input
294

EXAMPLES

296       To view cluster utilization:
297
298          rados df
299
300       To get a list object in pool foo sent to stdout:
301
302          rados -p foo ls -
303
304       To get a list of objects in PG 0.6:
305
306          rados --pgid 0.6 ls
307
308       To write an object:
309
310          rados -p foo put myobject blah.txt
311
312       To create a snapshot:
313
314          rados -p foo mksnap mysnap
315
316       To delete the object:
317
318          rados -p foo rm myobject
319
320       To read a previously snapshotted version of an object:
321
322          rados -p foo -s mysnap get myobject blah.txt.old
323
324       To list inconsistent objects in PG 0.6:
325
326          rados list-inconsistent-obj 0.6 --format=json-pretty
327

AVAILABILITY

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

SEE ALSO

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)
339
340
341
342
343dev                              Nov 02, 2023                         RADOS(8)
Impressum