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

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