- name: block_size
  type: int
  default: 131072
  info: |
    Size of objects (data blocks) into which all physical and virtual drives
    (within a pool) are subdivided in Vitastor. One of current main settings
    in Vitastor, affects memory usage, write amplification and I/O load
    distribution effectiveness.

    Recommended default block size is 128 KB for SSD and 1 MB for HDD. In fact,
    it's possible to use 1 MB for SSD too - it will lower memory usage, but
    may increase average WA and reduce linear performance.

    OSD memory usage is roughly (SIZE / BLOCK * 68 bytes) which is roughly
    544 MB per 1 TB of used disk space with the default 128 KB block size.
    With 1 MB it's 8 times lower.
  info_ru: |
    Размер объектов (блоков данных), на которые делятся физические и виртуальные
    диски в Vitastor (в рамках каждого пула). Одна из ключевых на данный момент
    настроек, влияет на потребление памяти, объём избыточной записи (write
    amplification) и эффективность распределения нагрузки по OSD.

    Рекомендуемые по умолчанию размеры блока - 128 килобайт для SSD и 1 мегабайт
    для HDD. В принципе, для SSD можно тоже использовать блок размером 1 мегабайт,
    это понизит использование памяти, но ухудшит распределение нагрузки и в
    среднем увеличит WA.

    Потребление памяти OSD составляет примерно (РАЗМЕР / БЛОК * 68 байт),
    т.е. примерно 544 МБ памяти на 1 ТБ занятого места на диске при
    стандартном 128 КБ блоке. При 1 МБ блоке памяти нужно в 8 раз меньше.
- name: bitmap_granularity
  type: int
  default: 4096
  info: |
    Required virtual disk write alignment ("sector size"). Must be a multiple
    of disk_alignment. It's called bitmap granularity because Vitastor tracks
    an allocation bitmap for each object containing 2 bits per each
    (bitmap_granularity) bytes.

    Can't be smaller than the OSD data device sector.
  info_ru: |
    Требуемое выравнивание записи на виртуальные диски (размер их "сектора").
    Должен быть кратен disk_alignment. Называется гранулярностью битовой карты
    потому, что Vitastor хранит битовую карту для каждого объекта, содержащую
    по 2 бита на каждые (bitmap_granularity) байт.

    Не может быть меньше размера сектора дисков данных OSD.
- name: immediate_commit
  type: string
  default: all
  info: |
    One of "none", "all" or "small". Global value, may be overriden [at pool level](pool.en.md#immediate_commit).

    This parameter is also really important for performance.

    TLDR: default "all" is optimal for server-grade SSDs with supercapacitor-based
    power loss protection (nonvolatile write-through cache) and also for most HDDs.
    "none" or "small" should be only selected if you use desktop SSDs without
    capacitors or drives with slow write-back cache that can't be disabled. Check
    immediate_commit of your OSDs in [ls-osd](../usage/cli.en.md#ls-osd).

    Detailed explanation:

    Desktop SSDs are very fast (100000+ iops) for simple random writes
    without cache flush. However, they are really slow (only around 1000 iops)
    if you try to fsync() each write, that is, if you want to guarantee that
    each change gets actually persisted to the physical media.

    Server-grade SSDs with "Advanced/Enhanced Power Loss Protection" or with
    "Supercapacitor-based Power Loss Protection", on the other hand, are equally
    fast with and without fsync because their cache is protected from sudden
    power loss by a built-in supercapacitor-based "UPS".

    Some software-defined storage systems always fsync each write and thus are
    really slow when used with desktop SSDs. Vitastor, however, can also
    efficiently utilize desktop SSDs by postponing fsync until the client calls
    it explicitly.

    This is what this parameter regulates. When it's set to "all" Vitastor
    cluster commits each change to disks immediately and clients just
    ignore fsyncs because they know for sure that they're unneeded. This reduces
    the amount of network roundtrips performed by clients and improves
    performance. So it's always better to use server grade SSDs with
    supercapacitors even with Vitastor, especially given that they cost only
    a bit more than desktop models.

    There is also a common SATA SSD (and HDD too!) firmware bug (or feature)
    that makes server SSDs which have supercapacitors slow with fsync. To check
    if your SSDs are affected, compare benchmark results from `fio -name=test
    -ioengine=libaio -direct=1 -bs=4k -rw=randwrite -iodepth=1` with and without
    `-fsync=1`. Results should be the same. If fsync=1 result is worse you can
    try to work around this bug by "disabling" drive write-back cache by running
    `hdparm -W 0 /dev/sdXX` or `echo write through > /sys/block/sdXX/device/scsi_disk/*/cache_type`
    (IMPORTANT: don't mistake it with `/sys/block/sdXX/queue/write_cache` - it's
    unsafe to change by hand). The same may apply to newer HDDs with internal
    SSD cache or "media-cache" - for example, a lot of Seagate EXOS drives have
    it (they have internal SSD cache even though it's not stated in datasheets).

    Setting this parameter to "all" or "small" in OSD parameters requires enabling
    [disable_journal_fsync](layout-osd.en.md#disable_journal_fsync) and
    [disable_meta_fsync](layout-osd.en.md#disable_meta_fsync), setting it to
    "all" also requires enabling [disable_data_fsync](layout-osd.en.md#disable_data_fsync).
    vitastor-disk tried to do that by default, first checking/disabling drive cache.
    If it can't disable drive cache, OSD get initialized with "none".
  info_ru: |
    Одно из значений "none", "small" или "all". Глобальное значение, может быть
    переопределено [на уровне пула](pool.ru.md#immediate_commit).

    Данный параметр тоже важен для производительности.

    Вкратце: значение по умолчанию "all" оптимально для всех серверных SSD с
    суперконденсаторами и также для большинства HDD. "none" и "small" имеет смысл
    устанавливать только при использовании SSD настольного класса без
    суперконденсаторов или дисков с медленным неотключаемым кэшем записи.
    Проверьте настройку immediate_commit своих OSD в выводе команды [ls-osd](../usage/cli.ru.md#ls-osd).

    Модели SSD для настольных компьютеров очень быстрые (100000+ операций в
    секунду) при простой случайной записи без сбросов кэша. Однако они очень
    медленные (всего порядка 1000 iops), если вы пытаетесь сбрасывать кэш после
    каждой записи, то есть, если вы пытаетесь гарантировать, что каждое
    изменение физически записывается в энергонезависимую память.

    С другой стороны, серверные SSD с конденсаторами - функцией, называемой
    "Advanced/Enhanced Power Loss Protection" или просто "Supercapacitor-based
    Power Loss Protection" - одинаково быстрые и со сбросом кэша, и без
    него, потому что их кэш защищён от потери питания встроенным "источником
    бесперебойного питания" на основе суперконденсаторов и на самом деле они
    его никогда не сбрасывают.

    Некоторые программные СХД всегда сбрасывают кэши дисков при каждой записи
    и поэтому работают очень медленно с настольными SSD. Vitastor, однако, может
    откладывать fsync до явного его вызова со стороны клиента и таким образом
    эффективно утилизировать настольные SSD.

    Данный параметр влияет как раз на это. Когда он установлен в значение "all",
    кластер Vitastor мгновенно фиксирует каждое изменение на физические
    носители и клиенты могут просто игнорировать запросы fsync, т.к. они точно
    знают, что fsync-и не нужны. Это уменьшает число необходимых обращений к OSD
    по сети и улучшает производительность. Поэтому даже с Vitastor лучше всегда
    использовать только серверные модели SSD с суперконденсаторами, особенно
    учитывая то, что стоят они ненамного дороже настольных.

    Также в прошивках SATA SSD (и даже HDD!) очень часто встречается либо баг,
    либо просто особенность логики, из-за которой серверные SSD, имеющие
    конденсаторы и защиту от потери питания, всё равно медленно работают с
    fsync. Чтобы понять, подвержены ли этой проблеме ваши SSD, сравните
    результаты тестов `fio -name=test -ioengine=libaio -direct=1 -bs=4k
    -rw=randwrite -iodepth=1` без и с опцией `-fsync=1`. Результаты должны
    быть одинаковые. Если результат с `fsync=1` хуже, вы можете попробовать
    обойти проблему, "отключив" кэш записи диска командой `hdparm -W 0 /dev/sdXX`
    либо `echo write through > /sys/block/sdXX/device/scsi_disk/*/cache_type`
    (ВАЖНО: не перепутайте с `/sys/block/sdXX/queue/write_cache` - этот параметр
    менять руками небезопасно). Такая же проблема может встречаться и в новых
    HDD-дисках с внутренним SSD или "медиа" кэшем - например, она встречается во
    многих дисках Seagate EXOS (у них есть внутренний SSD-кэш, хотя это и не
    указано в спецификациях).

    Указание "all" или "small" в настройках / командной строке OSD требует
    включения [disable_journal_fsync](layout-osd.ru.md#disable_journal_fsync) и
    [disable_meta_fsync](layout-osd.ru.md#disable_meta_fsync), значение "all"
    также требует включения [disable_data_fsync](layout-osd.ru.md#disable_data_fsync).