[ceph.git] / ceph / doc / rados / operations / erasure-code-jerasure.rst

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

The *jerasure* plugin is the most generic and flexible plugin, it is
also the default for Ceph erasure coded pools. 

The *jerasure* plugin encapsulates the `Jerasure
<http://jerasure.org>`_ library. It is
recommended to read the *jerasure* documentation to get a better
understanding of the parameters.

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

To create a new *jerasure* erasure code profile::

        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*. 

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

``packetsize={bytes}``

:Description: The encoding will be done on packets of *bytes* size at
              a time. Chosing 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 ruleset. For intance **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 ruleset 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.
:Default:

 ``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.
Commit	Line	Data
7c673cae FG	1	============================
	2	Jerasure erasure code plugin
	3	============================
	4
	5	The jerasure plugin is the most generic and flexible plugin, it is
	6	also the default for Ceph erasure coded pools.
	7
	8	The jerasure plugin encapsulates the `Jerasure
31f18b77	9	<http://jerasure.org>`_ library. It is
7c673cae FG	10	recommended to read the jerasure documentation to get a better
	11	understanding of the parameters.
	12
	13	Create a jerasure profile
	14	=========================
	15
	16	To create a new jerasure erasure code profile::
	17
	18	ceph osd erasure-code-profile set {name} \
	19	plugin=jerasure \
	20	k={data-chunks} \
	21	m={coding-chunks} \
	22	technique={reed_sol_van\|reed_sol_r6_op\|cauchy_orig\|cauchy_good\|liberation\|blaum_roth\|liber8tion} \
224ce89b WB	23	[crush-root={root}] \
	24	[crush-failure-domain={bucket-type}] \
	25	[crush-device-class={device-class}] \
7c673cae FG	26	[directory={directory}] \
	27	[--force]
	28
	29	Where:
	30
	31	``k={data chunks}``
	32
	33	:Description: Each object is split in data-chunks parts,
	34	each stored on a different OSD.
	35
	36	:Type: Integer
	37	:Required: Yes.
	38	:Example: 4
	39
	40	``m={coding-chunks}``
	41
	42	:Description: Compute coding chunks for each object and store them
	43	on different OSDs. The number of coding chunks is also
	44	the number of OSDs that can be down without losing data.
	45
	46	:Type: Integer
	47	:Required: Yes.
	48	:Example: 2
	49
	50	``technique={reed_sol_van\|reed_sol_r6_op\|cauchy_orig\|cauchy_good\|liberation\|blaum_roth\|liber8tion}``
	51
	52	:Description: The more flexible technique is reed_sol_van : it is
	53	enough to set k and m. The cauchy_good technique
	54	can be faster but you need to chose the packetsize
	55	carefully. All of reed_sol_r6_op, liberation,
	56	blaum_roth, liber8tion are RAID6 equivalents in
	57	the sense that they can only be configured with m=2.
	58
	59	:Type: String
	60	:Required: No.
	61	:Default: reed_sol_van
	62
	63	``packetsize={bytes}``
	64
	65	:Description: The encoding will be done on packets of bytes size at
	66	a time. Chosing the right packet size is difficult. The
	67	jerasure documentation contains extensive information
	68	on this topic.
	69
	70	:Type: Integer
	71	:Required: No.
	72	:Default: 2048
	73
224ce89b	74	``crush-root={root}``
7c673cae FG	75
	76	:Description: The name of the crush bucket used for the first step of
	77	the ruleset. For intance step take default.
	78
	79	:Type: String
	80	:Required: No.
	81	:Default: default
	82
224ce89b	83	``crush-failure-domain={bucket-type}``
7c673cae FG	84
	85	:Description: Ensure that no two chunks are in a bucket with the same
	86	failure domain. For instance, if the failure domain is
	87	host no two chunks will be stored on the same
	88	host. It is used to create a ruleset step such as **step
	89	chooseleaf host**.
	90
	91	:Type: String
	92	:Required: No.
	93	:Default: host
	94
224ce89b WB	95	``crush-device-class={device-class}``
	96
	97	:Description: Restrict placement to devices of a specific class (e.g.,
	98	``ssd`` or ``hdd``), using the crush device class names
	99	in the CRUSH map.
	100
	101	:Type: String
	102	:Required: No.
	103	:Default:
	104
	105	``directory={directory}``
7c673cae FG	106
	107	:Description: Set the directory name from which the erasure code
	108	plugin is loaded.
	109
	110	:Type: String
	111	:Required: No.
	112	:Default: /usr/lib/ceph/erasure-code
	113
	114	``--force``
	115
	116	:Description: Override an existing profile by the same name.
	117
	118	:Type: String
	119	:Required: No.
	120