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