ceph/doc/man/8/rados.rst

   1 :orphan:
   2
   3 =======================================
   4  rados -- rados object storage utility
   5 =======================================
   6
   7 .. program:: rados
   8
   9 Synopsis
  10 ========
  11
  12 | **rados** [ -m *monaddr* ] [ mkpool | rmpool *foo* ] [ -p | --pool
  13   *pool* ] [ -s | --snap *snap* ] [ -i *infile* ] [ -o *outfile* ]
  14   *command* ...
  15
  16
  17 Description
  18 ===========
  19
  20 **rados** is a utility for interacting with a Ceph object storage
  21 cluster (RADOS), part of the Ceph distributed storage system.
  22
  23
  24 Options
  25 =======
  26
  27 .. option:: -p pool, --pool pool
  28
  29    Interact with the given pool. Required by most commands.
  30
  31 .. option:: -s snap, --snap snap
  32
  33    Read from the given pool snapshot. Valid for all pool-specific read operations.
  34
  35 .. option:: -i infile
  36
  37    will specify an input file to be passed along as a payload with the
  38    command to the monitor cluster. This is only used for specific
  39    monitor commands.
  40
  41 .. option:: -o outfile
  42
  43    will write any payload returned by the monitor cluster with its
  44    reply to outfile. Only specific monitor commands (e.g. osd getmap)
  45    return a payload.
  46
  47 .. option:: -c ceph.conf, --conf=ceph.conf
  48
  49    Use ceph.conf configuration file instead of the default
  50    /etc/ceph/ceph.conf to determine monitor addresses during startup.
  51
  52 .. option:: -m monaddress[:port]
  53
  54    Connect to specified monitor (instead of looking through ceph.conf).
  55
  56 .. option:: -b block_size
  57
  58   Set the block size for put/get/append ops and for write benchmarking.
  59
  60 .. option:: --striper
  61
  62    Uses the striping API of rados rather than the default one.
  63    Available for stat, get, put, append, truncate, rm, ls and all xattr related operation
  64
  65
  66 Global commands
  67 ===============
  68
  69 :command:`lspools`
  70   List object pools
  71
  72 :command:`df`
  73   Show utilization statistics, including disk usage (bytes) and object
  74   counts, over the entire system and broken down by pool.
  75
  76 :command:`mkpool` *foo*
  77   Create a pool with name foo.
  78
  79 :command:`rmpool` *foo* [ *foo* --yes-i-really-really-mean-it ]
  80   Delete the pool foo (and all its data).
  81
  82 :command:`list-inconsistent-pg` *pool*
  83   List inconsistent PGs in given pool.
  84
  85 :command:`list-inconsistent-obj` *pgid*
  86   List inconsistent objects in given PG.
  87
  88 :command:`list-inconsistent-snapset` *pgid*
  89   List inconsistent snapsets in given PG.
  90
  91 Pool specific commands
  92 ======================
  93
  94 :command:`get` *name* *outfile*
  95   Read object name from the cluster and write it to outfile.
  96
  97 :command:`put` *name* *infile* [--offset offset]
  98   Write object name with start offset (default:0) to the cluster with contents from infile.
  99
 100 :command:`append` *name* *infile*
 101   Append object name to the cluster with contents from infile.
 102
 103 :command:`rm` *name*
 104   Remove object name.
 105
 106 :command:`listwatchers` *name*
 107   List the watchers of object name.
 108
 109 :command:`ls` *outfile*
 110   List objects in given pool and write to outfile.
 111
 112 :command:`lssnap`
 113   List snapshots for given pool.
 114
 115 :command:`clonedata` *srcname* *dstname* --object-locator *key*
 116   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.
 117
 118 :command:`mksnap` *foo*
 119   Create pool snapshot named *foo*.
 120
 121 :command:`rmsnap` *foo*
 122   Remove pool snapshot named *foo*.
 123
 124 :command:`bench` *seconds* *mode* [ -b *objsize* ] [ -t *threads* ]
 125   Benchmark for *seconds*. The mode can be *write*, *seq*, or
 126   *rand*. *seq* and *rand* are read benchmarks, either
 127   sequential or random. Before running one of the reading benchmarks,
 128   run a write benchmark with the *--no-cleanup* option. The default
 129   object size is 4 MB, and the default number of simulated threads
 130   (parallel writes) is 16. The *--run-name <label>* option is useful
 131   for benchmarking a workload test from multiple clients. The *<label>*
 132   is an arbitrary object name. It is "benchmark_last_metadata" by
 133   default, and is used as the underlying object name for "read" and
 134   "write" ops.
 135   Note: -b *objsize* option is valid only in *write* mode.
 136   Note: *write* and *seq* must be run on the same host otherwise the
 137   objects created by *write* will have names that will fail *seq*.
 138
 139 :command:`cleanup`
 140
 141 :command:`listxattr` *name*
 142   List all extended attributes of an object.
 143
 144 :command:`getxattr` *name* *attr*
 145   Dump the extended attribute value of *attr* of an object.
 146
 147 :command:`setxattr` *name* *attr* *value*
 148   Set the value of *attr* in the extended attributes of an object.
 149
 150 :command:`rmxattr` *name* *attr*
 151   Remove *attr* from the extended attributes of an object.
 152
 153 :command:`listomapkeys` *name*
 154   List all the keys stored in the object map of object name.
 155
 156 :command:`listomapvals` *name*
 157   List all key/value pairs stored in the object map of object name.
 158   The values are dumped in hexadecimal.
 159
 160 :command:`getomapval` [ --omap-key-file *file* ] *name* *key* [ *out-file* ]
 161   Dump the hexadecimal value of key in the object map of object name.
 162   If the optional *out-file* argument isn't provided, the value will be
 163   written to standard output.
 164
 165 :command:`setomapval` [ --omap-key-file *file* ] *name* *key* [ *value* ]
 166   Set the value of key in the object map of object name. If the optional
 167   *value* argument isn't provided, the value will be read from standard
 168   input.
 169
 170 :command:`rmomapkey` [ --omap-key-file *file* ] *name* *key*
 171   Remove key from the object map of object name.
 172
 173 :command:`getomapheader` *name*
 174   Dump the hexadecimal value of the object map header of object name.
 175
 176 :command:`setomapheader` *name* *value*
 177   Set the value of the object map header of object name.
 178
 179 Examples
 180 ========
 181
 182 To view cluster utilization::
 183
 184        rados df
 185
 186 To get a list object in pool foo sent to stdout::
 187
 188        rados -p foo ls -
 189
 190 To write an object::
 191
 192        rados -p foo put myobject blah.txt
 193
 194 To create a snapshot::
 195
 196        rados -p foo mksnap mysnap
 197
 198 To delete the object::
 199
 200        rados -p foo rm myobject
 201
 202 To read a previously snapshotted version of an object::
 203
 204        rados -p foo -s mysnap get myobject blah.txt.old
 205
 206 To list inconsistent objects in PG 0.6::
 207
 208        rados list-inconsistent-obj 0.6 --format=json-pretty
 209
 210
 211 Availability
 212 ============
 213
 214 **rados** is part of Ceph, a massively scalable, open-source, distributed storage system. Please refer to
 215 the Ceph documentation at http://ceph.com/docs for more information.
 216
 217
 218 See also
 219 ========
 220
 221 :doc:`ceph <ceph>`\(8)