[ceph.git] / ceph / doc / rados / configuration / journal-ref.rst

==========================
 Journal Config Reference
==========================

.. index:: journal; journal configuration

Filestore OSDs use a journal for two reasons: speed and consistency.  Note
that since Luminous, the BlueStore OSD back end has been preferred and default.
This information is provided for pre-existing OSDs and for rare situations where
Filestore is preferred for new deployments.

- **Speed:** The journal enables the Ceph OSD Daemon to commit small writes 
  quickly. Ceph writes small, random i/o to the journal sequentially, which 
  tends to speed up bursty workloads by allowing the backing file system more 
  time to coalesce writes. The Ceph OSD Daemon's journal, however, can lead 
  to spiky performance with short spurts of high-speed writes followed by 
  periods without any write progress as the file system catches up to the 
  journal.

- **Consistency:** Ceph OSD Daemons require a file system interface that 
  guarantees atomic compound operations. Ceph OSD Daemons write a description 
  of the operation to the journal and apply the operation to the file system. 
  This enables atomic updates to an object (for example, placement group 
  metadata). Every few seconds--between ``filestore max sync interval`` and
  ``filestore min sync interval``--the Ceph OSD Daemon stops writes and 
  synchronizes the journal with the file system, allowing Ceph OSD Daemons to 
  trim operations from the journal and reuse the space. On failure, Ceph 
  OSD Daemons replay the journal starting after the last synchronization 
  operation.

Ceph OSD Daemons recognize the following journal settings: 


``journal_dio``

:Description: Enables direct i/o to the journal. Requires ``journal block 
              align`` set to ``true``.
              
:Type: Boolean
:Required: Yes when using ``aio``.
:Default: ``true``


``journal_aio``

.. versionchanged:: 0.61 Cuttlefish

:Description: Enables using ``libaio`` for asynchronous writes to the journal. 
              Requires ``journal dio`` set to ``true``.

:Type: Boolean 
:Required: No.
:Default: Version 0.61 and later, ``true``. Version 0.60 and earlier, ``false``.


``journal_block_align``

:Description: Block aligns write operations. Required for ``dio`` and ``aio``.
:Type: Boolean
:Required: Yes when using ``dio`` and ``aio``.
:Default: ``true``


``journal_max_write_bytes``

:Description: The maximum number of bytes the journal will write at 
              any one time.

:Type: Integer
:Required: No
:Default: ``10 << 20``


``journal_max_write_entries``

:Description: The maximum number of entries the journal will write at 
              any one time.

:Type: Integer
:Required: No
:Default: ``100``


``journal_queue_max_ops``

:Description: The maximum number of operations allowed in the queue at 
              any one time.

:Type: Integer
:Required: No
:Default: ``500``


``journal_queue_max_bytes``

:Description: The maximum number of bytes allowed in the queue at 
              any one time.

:Type: Integer
:Required: No
:Default: ``10 << 20``


``journal_align_min_size``

:Description: Align data payloads greater than the specified minimum.
:Type: Integer
:Required: No
:Default: ``64 << 10``


``journal_zero_on_create``

:Description: Causes the file store to overwrite the entire journal with 
              ``0``'s during ``mkfs``.
:Type: Boolean
:Required: No
:Default: ``false``
Commit	Line	Data
7c673cae FG	1	==========================
	2	Journal Config Reference
	3	==========================
	4
	5	.. index:: journal; journal configuration
	6
f67539c2 TL	7	Filestore OSDs use a journal for two reasons: speed and consistency. Note
	8	that since Luminous, the BlueStore OSD back end has been preferred and default.
	9	This information is provided for pre-existing OSDs and for rare situations where
	10	Filestore is preferred for new deployments.
7c673cae FG	11
	12	- Speed: The journal enables the Ceph OSD Daemon to commit small writes
	13	quickly. Ceph writes small, random i/o to the journal sequentially, which
9f95a23c	14	tends to speed up bursty workloads by allowing the backing file system more
7c673cae FG	15	time to coalesce writes. The Ceph OSD Daemon's journal, however, can lead
7c673cae FG	16	to spiky performance with short spurts of high-speed writes followed by
9f95a23c	17	periods without any write progress as the file system catches up to the
7c673cae FG	18	journal.
7c673cae FG	19
9f95a23c	20	- Consistency: Ceph OSD Daemons require a file system interface that
7c673cae	21	guarantees atomic compound operations. Ceph OSD Daemons write a description
9f95a23c	22	of the operation to the journal and apply the operation to the file system.
7c673cae FG	23	This enables atomic updates to an object (for example, placement group
	24	metadata). Every few seconds--between ``filestore max sync interval`` and
	25	``filestore min sync interval``--the Ceph OSD Daemon stops writes and
9f95a23c	26	synchronizes the journal with the file system, allowing Ceph OSD Daemons to
7c673cae FG	27	trim operations from the journal and reuse the space. On failure, Ceph
	28	OSD Daemons replay the journal starting after the last synchronization
	29	operation.
	30
f67539c2	31	Ceph OSD Daemons recognize the following journal settings:
7c673cae FG	32
7c673cae FG	33
f67539c2	34	``journal_dio``
7c673cae FG	35
	36	:Description: Enables direct i/o to the journal. Requires ``journal block
	37	align`` set to ``true``.
	38
	39	:Type: Boolean
	40	:Required: Yes when using ``aio``.
	41	:Default: ``true``
	42
	43
	44
f67539c2	45	``journal_aio``
7c673cae FG	46
	47	.. versionchanged:: 0.61 Cuttlefish
	48
	49	:Description: Enables using ``libaio`` for asynchronous writes to the journal.
	50	Requires ``journal dio`` set to ``true``.
	51
	52	:Type: Boolean
	53	:Required: No.
	54	:Default: Version 0.61 and later, ``true``. Version 0.60 and earlier, ``false``.
	55
	56
f67539c2	57	``journal_block_align``
7c673cae FG	58
	59	:Description: Block aligns write operations. Required for ``dio`` and ``aio``.
	60	:Type: Boolean
	61	:Required: Yes when using ``dio`` and ``aio``.
	62	:Default: ``true``
	63
	64
f67539c2	65	``journal_max_write_bytes``
7c673cae FG	66
	67	:Description: The maximum number of bytes the journal will write at
	68	any one time.
	69
	70	:Type: Integer
	71	:Required: No
	72	:Default: ``10 << 20``
	73
	74
f67539c2	75	``journal_max_write_entries``
7c673cae FG	76
	77	:Description: The maximum number of entries the journal will write at
	78	any one time.
	79
	80	:Type: Integer
	81	:Required: No
	82	:Default: ``100``
	83
	84
f67539c2	85	``journal_queue_max_ops``
7c673cae FG	86
	87	:Description: The maximum number of operations allowed in the queue at
	88	any one time.
	89
	90	:Type: Integer
	91	:Required: No
	92	:Default: ``500``
	93
	94
f67539c2	95	``journal_queue_max_bytes``
7c673cae FG	96
	97	:Description: The maximum number of bytes allowed in the queue at
	98	any one time.
	99
	100	:Type: Integer
	101	:Required: No
	102	:Default: ``10 << 20``
	103
	104
f67539c2	105	``journal_align_min_size``
7c673cae FG	106
	107	:Description: Align data payloads greater than the specified minimum.
	108	:Type: Integer
	109	:Required: No
	110	:Default: ``64 << 10``
	111
	112
f67539c2	113	``journal_zero_on_create``
7c673cae FG	114
	115	:Description: Causes the file store to overwrite the entire journal with
	116	``0``'s during ``mkfs``.
	117	:Type: Boolean
	118	:Required: No
	119	:Default: ``false``