src/ceph/doc/rados/operations/erasure-code-profile.rst

   1 =====================
   2 Erasure code profiles
   3 =====================
   4
   5 Erasure code is defined by a **profile** and is used when creating an
   6 erasure coded pool and the associated crush ruleset.
   7
   8 The **default** erasure code profile (which is created when the Ceph
   9 cluster is initialized) provides the same level of redundancy as two
  10 copies but requires 25% less disk space. It is described as a profile
  11 with **k=2** and **m=1**, meaning the information is spread over three
  12 OSD (k+m == 3) and one of them can be lost.
  13
  14 To improve redundancy without increasing raw storage requirements, a
  15 new profile can be created. For instance, a profile with **k=10** and
  16 **m=4** can sustain the loss of four (**m=4**) OSDs by distributing an
  17 object on fourteen (k+m=14) OSDs. The object is first divided in
  18 **10** chunks (if the object is 10MB, each chunk is 1MB) and **4**
  19 coding chunks are computed, for recovery (each coding chunk has the
  20 same size as the data chunk, i.e. 1MB). The raw space overhead is only
  21 40% and the object will not be lost even if four OSDs break at the
  22 same time.
  23
  24 .. _list of available plugins:
  25
  26 .. toctree::
  27         :maxdepth: 1
  28
  29         erasure-code-jerasure
  30         erasure-code-isa
  31         erasure-code-lrc
  32         erasure-code-shec
  33
  34 osd erasure-code-profile set
  35 ============================
  36
  37 To create a new erasure code profile::
  38
  39         ceph osd erasure-code-profile set {name} \
  40              [{directory=directory}] \
  41              [{plugin=plugin}] \
  42              [{stripe_unit=stripe_unit}] \
  43              [{key=value} ...] \
  44              [--force]
  45
  46 Where:
  47
  48 ``{directory=directory}``
  49
  50 :Description: Set the **directory** name from which the erasure code
  51               plugin is loaded.
  52
  53 :Type: String
  54 :Required: No.
  55 :Default: /usr/lib/ceph/erasure-code
  56
  57 ``{plugin=plugin}``
  58
  59 :Description: Use the erasure code **plugin** to compute coding chunks
  60               and recover missing chunks. See the `list of available
  61               plugins`_ for more information.
  62
  63 :Type: String
  64 :Required: No.
  65 :Default: jerasure
  66
  67 ``{stripe_unit=stripe_unit}``
  68
  69 :Description: The amount of data in a data chunk, per stripe. For
  70               example, a profile with 2 data chunks and stripe_unit=4K
  71               would put the range 0-4K in chunk 0, 4K-8K in chunk 1,
  72               then 8K-12K in chunk 0 again. This should be a multiple
  73               of 4K for best performance. The default value is taken
  74               from the monitor config option
  75               ``osd_pool_erasure_code_stripe_unit`` when a pool is
  76               created.  The stripe_width of a pool using this profile
  77               will be the number of data chunks multiplied by this
  78               stripe_unit.
  79
  80 :Type: String
  81 :Required: No.
  82
  83 ``{key=value}``
  84
  85 :Description: The semantic of the remaining key/value pairs is defined
  86               by the erasure code plugin.
  87
  88 :Type: String
  89 :Required: No.
  90
  91 ``--force``
  92
  93 :Description: Override an existing profile by the same name, and allow
  94               setting a non-4K-aligned stripe_unit.
  95
  96 :Type: String
  97 :Required: No.
  98
  99 osd erasure-code-profile rm
 100 ============================
 101
 102 To remove an erasure code profile::
 103
 104         ceph osd erasure-code-profile rm {name}
 105
 106 If the profile is referenced by a pool, the deletion will fail.
 107
 108 osd erasure-code-profile get
 109 ============================
 110
 111 To display an erasure code profile::
 112
 113         ceph osd erasure-code-profile get {name}
 114
 115 osd erasure-code-profile ls
 116 ===========================
 117
 118 To list the names of all erasure code profiles::
 119
 120         ceph osd erasure-code-profile ls
 121