- name: meta_format
  type: int
  default: 3
  info: |
    OSD store implementation version and on-disk metadata format.

    Three versions are currently supported: 3, 2 and 1.
    - 3 the new log-structured store, it's overall faster, has lower Write
      Amplification, which may be even close to 1 (i.e. almost no extra writes)
      if your SSDs support atomic writes (see [atomic_write_size](osd.en.md#atomic_write_size)).
    - 2 is the old stable store from Vitastor 0.9-2.x.
    - 1 is the same old store but with a legacy metadata format from Vitastor
      versions to up 0.8.x, without any support for checksums.
  info_ru: |
    Версия реализации дискового хранилища OSD и дискового формата метаданных.

    Поддерживаются три версии: 3, 2 и 1.
    - 3 - новое лог-структурированное хранилище, в целом более быстрое, со
      сниженным фактором амплификации записи, который может составлять около 1
      (то есть, практически без лишней служебной записи), если ваши SSD
      поддерживают атомарную запись (см. [atomic_write_size](osd.ru.md#atomic_write_size)).
    - 2 - старое стабильное хранилище из версий Vitastor 0.9-2.x.
    - 1 - то же самое стабильное хранилище, но с ещё более старым форматом
      метаданных из версий Vitastor до 0.8.x, без какой-либо поддержки
      контрольных сумм.
- name: data_device
  type: string
  info: |
    Path to the block device to use for data. It's highly recommendded to use
    stable paths for all device names: `/dev/disk/by-partuuid/xxx...` instead
    of just `/dev/sda` or `/dev/nvme0n1` to not mess up after server restart.
    Files can also be used instead of block devices, but this is implemented
    only for testing purposes and not for production.
  info_ru: |
    Путь к диску (блочному устройству) для хранения данных. Крайне рекомендуется
    использовать стабильные пути: `/dev/disk/by-partuuid/xxx...` вместо простых
    `/dev/sda` или `/dev/nvme0n1`, чтобы пути не могли спутаться после
    перезагрузки сервера. Также вместо блочных устройств можно указывать файлы,
    но это реализовано только для тестирования, а не для боевой среды.
- name: meta_device
  type: string
  info: |
    Path to the block device to use for the metadata. Metadata must be on a fast
    SSD or performance will suffer. If this option is skipped, `data_device` is
    used for the metadata.
  info_ru: |
    Путь к диску метаданных. Метаданные должны располагаться на быстром
    SSD-диске, иначе производительность пострадает. Если эта опция не указана,
    для метаданных используется `data_device`.
- name: journal_device
  type: string
  info: |
    Path to the block device to use for the journal. Journal must be on a fast
    SSD or performance will suffer. If this option is skipped, `meta_device` is
    used for the journal, and if it's also empty, journal is put on
    `data_device`. It's almost always fine to put metadata and journal on the
    same device, in this case you only need to set `meta_device`.
  info_ru: |
    Путь к диску журнала. Журнал должен располагаться на быстром SSD-диске,
    иначе производительность пострадает. Если эта опция не указана,
    для журнала используется `meta_device`, если же пуста и она, журнал
    располагается на `data_device`. Нормально располагать журнал и метаданные
    на одном устройстве, в этом случае достаточно указать только `meta_device`.
- name: journal_offset
  type: int
  default: 0
  info: Offset on the device in bytes where the journal is stored.
  info_ru: Смещение на устройстве в байтах, по которому располагается журнал.
- name: journal_size
  type: int
  info: |
    Journal size in bytes. By default, all available space between journal_offset
    and data_offset, meta_offset or the end of the journal device is used.
    Large journals aren't needed in SSD-only setups, 32 MB is always enough.
    In SSD+HDD setups it is beneficial to use larger journals (for example, 1 GB)
    and enable [throttle_small_writes](osd.en.md#throttle_small_writes).
  info_ru: |
    Размер журнала в байтах. По умолчанию для журнала используется всё доступное
    место между journal_offset и data_offset, meta_offset или концом диска.
    В SSD-кластерах большие журналы не нужны, достаточно 32 МБ. В гибридных
    (SSD+HDD) кластерах осмысленно использовать больший размер журнал (например, 1 ГБ)
    и включить [throttle_small_writes](osd.ru.md#throttle_small_writes).
- name: meta_offset
  type: int
  default: 0
  info: |
    Offset on the device in bytes where the metadata area is stored.
    Again, set it to something if you colocate metadata with journal or data.
  info_ru: |
    Смещение на устройстве в байтах, по которому располагаются метаданные.
    Эту опцию нужно задать, если метаданные у вас хранятся на том же
    устройстве, что данные или журнал.
- name: data_offset
  type: int
  default: 0
  info: |
    Offset on the device in bytes where the data area is stored.
    Again, set it to something if you colocate data with journal or metadata.
  info_ru: |
    Смещение на устройстве в байтах, по которому располагаются данные.
    Эту опцию нужно задать, если данные у вас хранятся на том же
    устройстве, что метаданные или журнал.
- name: data_size
  type: int
  info: |
    Data area size in bytes. By default, the whole data device up to the end
    will be used for the data area, but you can restrict it if you want to use
    a smaller part. Note that there is no option to set metadata area size -
    it's derived from the data area size.
  info_ru: |
    Размер области данных в байтах. По умолчанию под данные будет использована
    вся доступная область устройства данных до конца устройства, но вы можете
    использовать эту опцию, чтобы ограничить её меньшим размером. Заметьте, что
    опции размера области метаданных нет - она вычисляется из размера области
    данных автоматически.
- name: meta_block_size
  type: int
  default: 4096
  info: |
    Physical block size of the metadata device. 4096 for most current
    HDDs and SSDs.
  info_ru: |
    Размер физического блока устройства метаданных. 4096 для большинства
    современных SSD и HDD.
- name: journal_block_size
  type: int
  default: 4096
  info: |
    Physical block size of the journal device. Must be a multiple of
    `disk_alignment`. 4096 for most current HDDs and SSDs.
  info_ru: |
    Размер физического блока устройства журнала. Должен быть кратен
    `disk_alignment`. 4096 для большинства современных SSD и HDD.
- name: disable_data_fsync
  type: bool
  default: false
  info: |
    Do not issue fsyncs to the data device, i.e. do not force it to flush cache.
    Safe ONLY if your data device has write-through cache or if write-back
    cache is disabled. If you disable drive cache manually with `hdparm` or
    writing to `/sys/.../scsi_disk/cache_type` then make sure that you do it
    every time before starting Vitastor OSD (vitastor-disk does it automatically).
    See also [immediate_commit](layout-cluster.en.md#immediate_commit)
    for information about how to benefit from disabled cache.
  info_ru: |
    Не отправлять fsync-и устройству данных, т.е. не заставлять его сбрасывать кэш.
    Безопасно, ТОЛЬКО если ваше устройство данных имеет кэш со сквозной
    записью (write-through) или если кэш с отложенной записью (write-back) отключён.
    Если вы отключаете кэш вручную через `hdparm` или запись в `/sys/.../scsi_disk/cache_type`,
    то удостоверьтесь, что вы делаете это каждый раз перед запуском Vitastor OSD
    (vitastor-disk делает это автоматически). Смотрите также опцию
    [immediate_commit](layout-cluster.ru.md#immediate_commit) для информации о том,
    как извлечь выгоду из отключённого кэша.
- name: disable_meta_fsync
  type: bool
  default: false
  info: |
    Same as disable_data_fsync, but for the metadata device. If the metadata
    device is not set or if the data device is used for the metadata the option
    is ignored and disable_data_fsync value is used instead of it.
  info_ru: |
    То же, что disable_data_fsync, но для устройства метаданных. Если устройство
    метаданных не задано или если оно равно устройству данных, значение опции
    игнорируется и вместо него используется значение опции disable_data_fsync.
- name: disable_journal_fsync
  type: bool
  default: false
  info: |
    Same as disable_data_fsync, but for the journal device. If the journal
    device is not set or if the metadata device is used for the journal the
    option is ignored and disable_meta_fsync value is used instead of it. If
    the same device is used for data, metadata and journal the option is also
    ignored and disable_data_fsync value is used instead of it.
  info_ru: |
    То же, что disable_data_fsync, но для устройства журнала. Если устройство
    журнала не задано или если оно равно устройству метаданных, значение опции
    игнорируется и вместо него используется значение опции disable_meta_fsync.
    Если одно и то же устройство используется и под данные, и под журнал, и под
    метаданные - значение опции также игнорируется и вместо него используется
    значение опции disable_data_fsync.
- name: disable_device_lock
  type: bool
  default: false
  info: |
    Do not lock data, metadata and journal block devices exclusively with
    flock(). Though it's not recommended, but you can use it you want to run
    multiple OSD with a single device and different offsets, without using
    partitions.
  info_ru: |
    Не блокировать устройства данных, метаданных и журнала от открытия их
    другими OSD с помощью flock(). Так делать не рекомендуется, но теоретически
    вы можете это использовать, чтобы запускать несколько OSD на одном
    устройстве с разными смещениями и без использования разделов.
- name: disk_alignment
  type: int
  default: 4096
  info: |
    Required physical disk write alignment. Most current SSD and HDD drives
    use 4 KB physical sectors even if they report 512 byte logical sector
    size, so 4 KB is a good default setting.

    Note, however, that physical sector size also affects WA, because with block
    devices it's impossible to write anything smaller than a block. So, when
    Vitastor has to write a single metadata entry that's only about 32 bytes in
    size, it actually has to write the whole 4 KB sector.

    Because of this it can actually be beneficial to use SSDs which work well
    with 512 byte sectors and use 512 byte disk_alignment, journal_block_size
    and meta_block_size. But at the moment, no such SSDs are known...

    Clients don't need to be aware of disk_alignment, so it's not required to
    put a modified value into etcd key /vitastor/config/global.
  info_ru: |
    Требуемое выравнивание записи на физические диски. Почти все современные
    SSD и HDD диски используют 4 КБ физические секторы, даже если показывают
    логический размер сектора 512 байт, поэтому 4 КБ - хорошее значение по
    умолчанию.

    Однако стоит понимать, что физический размер сектора тоже влияет на
    избыточную запись (WA), потому что ничего меньше блока (сектора) на блочное
    устройство записать невозможно. Таким образом, когда Vitastor-у нужно
    записать на диск всего лишь одну 32-байтную запись метаданных, фактически
    приходится перезаписывать 4 КБ сектор целиком.

    Поэтому, на самом деле, может быть выгодно найти SSD, хорошо работающие с
    меньшими, 512-байтными, блоками и использовать 512-байтные disk_alignment,
    journal_block_size и meta_block_size. Однако на данный момент такие SSD
    не известны...

    Клиентам не обязательно знать про disk_alignment, так что помещать значение
    этого параметра в etcd в /vitastor/config/global не нужно.
- name: data_csum_type
  type: string
  default: none
  info: |
    Data checksum type to use. May be "crc32c" or "none". Set to "crc32c" to
    enable data checksums.
  info_ru: |
    Тип используемых OSD контрольных сумм данных. Может быть "crc32c" или "none".
    Установите в "crc32c", чтобы включить расчёт и проверку контрольных сумм данных.

    Следует понимать, что контрольные суммы в зависимости от размера блока их
    расчёта либо увеличивают потребление памяти, либо снижают производительность.
    Подробнее смотрите в описании параметра [csum_block_size](#csum_block_size).
- name: csum_block_size
  type: int
  default: 4096
  info: |
    Checksum calculation block size.

    Must be equal or a multiple of [bitmap_granularity](layout-cluster.en.md#bitmap_granularity)
    (which is usually 4 KB).

    Checksums increase metadata size by 4 bytes per each csum_block_size of data.

    Checksums are always a tradeoff:
    1. You either sacrifice +1 GB RAM per 1 TB of data
    2. Or you raise csum_block_size, for example, to 32k and sacrifice
       50% random write iops due to checksum read-modify-write
    3. Or you turn off [inmemory_metadata](osd.en.md#inmemory_metadata) and
       sacrifice 50% random read iops due to checksum reads

    All-flash clusters usually have enough RAM to use default csum_block_size,
    which uses 1 GB RAM per 1 TB of data. HDD clusters usually don't.

    Thus, recommended setups are:
    1. All-flash, 1 GB RAM per 1 TB data: default (csum_block_size=4k)
    2. All-flash, less RAM: csum_block_size=4k + inmemory_metadata=false
    3. Hybrid HDD+SSD: csum_block_size=4k + inmemory_metadata=false
    4. HDD-only, faster random read: csum_block_size=32k
    5. HDD-only, faster random write: csum_block_size=4k +
       inmemory_metadata=false + meta_io=cached

    See also [meta_io](osd.en.md#meta_io).
  info_ru: |
    Размер блока расчёта контрольных сумм.

    Должен быть равен или кратен [bitmap_granularity](layout-cluster.ru.md#bitmap_granularity)
    (который обычно равен 4 КБ).

    Контрольные суммы увеличивают размер метаданных на 4 байта на каждые
    csum_block_size данных.

    Контрольные суммы - это всегда компромисс:
    1. Вы либо жертвуете потреблением +1 ГБ памяти на 1 ТБ дискового пространства
    2. Либо вы повышаете csum_block_size до, скажем, 32k и жертвуете 50%
       скорости случайной записи из-за цикла чтения-изменения-записи для расчёта
       новых контрольных сумм
    3. Либо вы отключаете [inmemory_metadata](osd.ru.md#inmemory_metadata) и
       жертвуете 50% скорости случайного чтения из-за чтения контрольных сумм
       с диска

    Таким образом, рекомендуются следующие варианты настроек:
    1. All-flash, 1 ГБ памяти на 1 ТБ данных: по умолчанию (csum_block_size=4k)
    2. All-flash, меньше памяти: csum_block_size=4k + inmemory_metadata=false
    3. Гибридные HDD+SSD: csum_block_size=4k + inmemory_metadata=false
    4. Только HDD, быстрее случайное чтение: csum_block_size=32k
    5. Только HDD, быстрее случайная запись: csum_block_size=4k +
       inmemory_metadata=false + meta_io=cached

    Смотрите также [meta_io](osd.ru.md#meta_io).
