============================
Jerasure erasure code plugin
============================

The *jerasure* plugin is a generic and flexible plugin. However,
the *jerasure* library is no longer maintained and has not been
updated to support modern CPU instructions that can improve
performance when encoding and decoding data.

The *jerasure* plugin encapsulates the `Jerasure
<https://github.com/ceph/jerasure>`_ library. It is
recommended to read the ``jerasure`` documentation to
understand the parameters. Note that the ``jerasure.org``
web site as of 2023 may no longer be connected to the original
project or legitimate.

Create a jerasure profile
=========================

To create a new *jerasure* erasure code profile:
 
.. prompt:: bash $

   ceph osd erasure-code-profile set {name} \
     plugin=jerasure \
     k={data-chunks} \
     m={coding-chunks} \
     technique={reed_sol_van|reed_sol_r6_op|cauchy_orig|cauchy_good|liberation|blaum_roth|liber8tion} \
     [crush-root={root}] \
     [crush-failure-domain={bucket-type}] \
     [crush-device-class={device-class}] \
     [directory={directory}] \
     [--force]

Where:

``k={data chunks}``

:Description: Each object is split in **data-chunks** parts,
              each stored on a different OSD.

:Type: Integer
:Required: Yes.
:Example: 4

``m={coding-chunks}``

:Description: Compute **coding chunks** for each object and store them
              on different OSDs. The number of coding chunks is also
              the number of OSDs that can be down without losing data.

:Type: Integer
:Required: Yes.
:Example: 2

``technique={reed_sol_van|reed_sol_r6_op|cauchy_orig|cauchy_good|liberation|blaum_roth|liber8tion}``

:Description: The more flexible technique is *reed_sol_van* : it is
              enough to set *k* and *m*. The *cauchy_good* technique
              can be faster but you need to chose the *packetsize*
              carefully. All of *reed_sol_r6_op*, *liberation*,
              *blaum_roth*, *liber8tion* are *RAID6* equivalents in
              the sense that they can only be configured with *m=2*. 

              .. note:: When using ``blaum_roth`` coding, the default 
                 word size of ``w=7`` is suboptimal because ``blaum_roth`` 
                 works best when ``w+1`` is prime. When creating a new 
                 erasure-code profile with ``technique=blaum_roth``, 
                 set ``w`` to a number that is one integer less than a prime 
                 number (for example, ``6``). See `Loic Dachary's 
                 commit f51d21b to ceph/ceph <https://github.com/ceph/ceph/commit/f51d21b53d26d4f27c950cb1ba3f989e713ab325>`_ for information about
                 why this default cannot be changed easily in the
                 source code, and see `the second bullet point on
                 page 29 of Plank and Greenan's "Jerasure: A Library
                 in C Facilitating Erasure Coding for Storage
                 Applications" <https://github.com/ceph/jerasure/blob/master/Manual.pdf>`_ for an unequivocal statement of the restriction that applies 
                 to ``w`` when using Blaum-Roth coding.
                 (Information about the proper value of ``w`` when
                 using ``blaum_roth`` coding was provided to the
                 Ceph upstream in September of 2024 by Benjamin
                 Mare.)

:Type: String
:Required: No.
:Default: reed_sol_van

``packetsize={bytes}``

:Description: The encoding will be done on packets of *bytes* size at
              a time. Choosing the right packet size is difficult. The
              *jerasure* documentation contains extensive information
              on this topic.

:Type: Integer
:Required: No.
:Default: 2048

``crush-root={root}``

:Description: The name of the crush bucket used for the first step of
              the CRUSH rule. For instance **step take default**.

:Type: String
:Required: No.
:Default: default

``crush-failure-domain={bucket-type}``

:Description: Ensure that no two chunks are in a bucket with the same
              failure domain. For instance, if the failure domain is
              **host** no two chunks will be stored on the same
              host. It is used to create a CRUSH rule step such as **step
              chooseleaf host**.

:Type: String
:Required: No.
:Default: host

``crush-device-class={device-class}``

:Description: Restrict placement to devices of a specific class (e.g.,
              ``ssd`` or ``hdd``), using the crush device class names
              in the CRUSH map.

:Type: String
:Required: No.

``directory={directory}``

:Description: Set the **directory** name from which the erasure code
              plugin is loaded.

:Type: String
:Required: No.
:Default: /usr/lib/ceph/erasure-code

``--force``

:Description: Override an existing profile by the same name.

:Type: String
:Required: No.

