src/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` [ --run-name *run_name* ] [ --prefix *prefix* ]
 140   Clean up a previous benchmark operation.
 141   Note: the default run-name is "benchmark_last_metadata"
 142
 143 :command:`listxattr` *name*
 144   List all extended attributes of an object.
 145
 146 :command:`getxattr` *name* *attr*
 147   Dump the extended attribute value of *attr* of an object.
 148
 149 :command:`setxattr` *name* *attr* *value*
 150   Set the value of *attr* in the extended attributes of an object.
 151
 152 :command:`rmxattr` *name* *attr*
 153   Remove *attr* from the extended attributes of an object.
 154
 155 :command:`listomapkeys` *name*
 156   List all the keys stored in the object map of object name.
 157
 158 :command:`listomapvals` *name*
 159   List all key/value pairs stored in the object map of object name.
 160   The values are dumped in hexadecimal.
 161
 162 :command:`getomapval` [ --omap-key-file *file* ] *name* *key* [ *out-file* ]
 163   Dump the hexadecimal value of key in the object map of object name.
 164   If the optional *out-file* argument is not provided, the value will be
 165   written to standard output.
 166
 167 :command:`setomapval` [ --omap-key-file *file* ] *name* *key* [ *value* ]
 168   Set the value of key in the object map of object name. If the optional
 169   *value* argument is not provided, the value will be read from standard
 170   input.
 171
 172 :command:`rmomapkey` [ --omap-key-file *file* ] *name* *key*
 173   Remove key from the object map of object name.
 174
 175 :command:`getomapheader` *name*
 176   Dump the hexadecimal value of the object map header of object name.
 177
 178 :command:`setomapheader` *name* *value*
 179   Set the value of the object map header of object name.
 180
 181 Examples
 182 ========
 183
 184 To view cluster utilization::
 185
 186        rados df
 187
 188 To get a list object in pool foo sent to stdout::
 189
 190        rados -p foo ls -
 191
 192 To write an object::
 193
 194        rados -p foo put myobject blah.txt
 195
 196 To create a snapshot::
 197
 198        rados -p foo mksnap mysnap
 199
 200 To delete the object::
 201
 202        rados -p foo rm myobject
 203
 204 To read a previously snapshotted version of an object::
 205
 206        rados -p foo -s mysnap get myobject blah.txt.old
 207
 208 To list inconsistent objects in PG 0.6::
 209
 210        rados list-inconsistent-obj 0.6 --format=json-pretty
 211
 212
 213 Availability
 214 ============
 215
 216 **rados** is part of Ceph, a massively scalable, open-source, distributed storage system. Please refer to
 217 the Ceph documentation at http://ceph.com/docs for more information.
 218
 219
 220 See also
 221 ========
 222
 223 :doc:`ceph <ceph>`\(8)