- name: client_iothread_count
  type: int
  default: 0
  online: false
  info: |
    Number of separate threads for handling TCP network I/O at client library
    side. Enabling 4 threads usually allows to increase peak performance of each
    client from approx. 2-3 to 7-8 GByte/s linear read/write and from approx.
    100-150 to 400 thousand iops, but at the same time it increases latency.
    Latency increase depends on CPU: with CPU power saving disabled latency
    only increases by ~10 us (equivalent to Q=1 iops decrease from 10500 to 9500),
    with CPU power saving enabled it may be as high as 500 us (equivalent to Q=1
    iops decrease from 2000 to 1000). RDMA isn't affected by this option.

    It's recommended to enable client I/O threads if you don't use RDMA and want
    to increase peak client performance.
  info_ru: |
    Число отдельных потоков для обработки ввода-вывода через TCP сеть на стороне
    клиентской библиотеки. Включение 4 потоков обычно позволяет поднять пиковую
    производительность каждого клиента примерно с 2-3 до 7-8 Гбайт/с линейного
    чтения/записи и примерно с 100-150 до 400 тысяч операций ввода-вывода в
    секунду, но ухудшает задержку. Увеличение задержки зависит от процессора:
    при отключённом энергосбережении CPU это всего ~10 микросекунд (равносильно
    падению iops с Q=1 с 10500 до 9500), а при включённом это может быть
    и 500 микросекунд (равносильно падению iops с Q=1 с 2000 до 1000). На работу
    RDMA данная опция не влияет.

    Рекомендуется включать клиентские потоки ввода-вывода, если вы не используете
    RDMA и хотите повысить пиковую производительность клиентов.
- name: client_retry_interval
  type: ms
  min: 10
  default: 50
  online: true
  info: |
    Retry time for I/O requests failed due to inactive PGs or network
    connectivity errors.
  info_ru: |
    Время повтора запросов ввода-вывода, неудачных из-за неактивных PG или
    ошибок сети.
- name: client_eio_retry_interval
  type: ms
  default: 1000
  online: true
  info: |
    Retry time for I/O requests failed due to data corruption or unfinished
    EC object deletions (has_incomplete PG state). 0 disables such retries
    and clients are not blocked and just get EIO error code instead.
  info_ru: |
    Время повтора запросов ввода-вывода, неудачных из-за повреждения данных
    или незавершённых удалений EC-объектов (состояния PG has_incomplete).
    0 отключает повторы таких запросов и клиенты не блокируются, а вместо
    этого просто получают код ошибки EIO.
- name: client_retry_enospc
  type: bool
  default: true
  online: true
  info: |
    Retry writes on out of space errors to wait until some space is freed on
    OSDs.
  info_ru: |
    Повторять запросы записи, завершившиеся с ошибками нехватки места, т.е.
    ожидать, пока на OSD не освободится место.
- name: client_wait_up_timeout
  type: sec
  default: 16
  online: true
  info: |
    Wait for this number of seconds until PGs are up when doing operations
    which require all PGs to be up. Currently only used by object listings
    in delete and merge-based commands ([vitastor-cli rm](../usage/cli.en.md#rm), merge and so on).

    The default value is calculated as `1 + OSD lease timeout`, which is
    `1 + etcd_report_interval + max_etcd_attempts*2*etcd_quick_timeout`.
  info_ru: |
    Время ожидания поднятия PG при операциях, требующих активности всех PG.
    В данный момент используется листингами объектов в командах, использующих
    удаление и слияние ([vitastor-cli rm](../usage/cli.ru.md#rm), merge и подобные).

    Значение по умолчанию вычисляется как `1 + время lease OSD`, равное
    `1 + etcd_report_interval + max_etcd_attempts*2*etcd_quick_timeout`.
- name: client_max_dirty_bytes
  type: int
  default: 33554432
  online: true
  info: |
    Without [immediate_commit](layout-cluster.en.md#immediate_commit)=all this parameter sets the limit of "dirty"
    (not committed by fsync) data allowed by the client before forcing an
    additional fsync and committing the data. Also note that the client always
    holds a copy of uncommitted data in memory so this setting also affects
    RAM usage of clients.
  info_ru: |
    При работе без [immediate_commit](layout-cluster.ru.md#immediate_commit)=all - это лимит объёма "грязных" (не
    зафиксированных fsync-ом) данных, при достижении которого клиент будет
    принудительно вызывать fsync и фиксировать данные. Также стоит иметь в виду,
    что в этом случае до момента fsync клиент хранит копию незафиксированных
    данных в памяти, то есть, настройка влияет на потребление памяти клиентами.
- name: client_max_dirty_ops
  type: int
  default: 1024
  online: true
  info: |
    Same as client_max_dirty_bytes, but instead of total size, limits the number
    of uncommitted write operations.
  info_ru: |
    Аналогично client_max_dirty_bytes, но ограничивает количество
    незафиксированных операций записи вместо их общего объёма.
- name: client_enable_writeback
  type: bool
  default: false
  online: true
  info: |
    This parameter enables client-side write buffering. This means that write
    requests are accumulated in memory for a short time before being sent to
    a Vitastor cluster which allows to send them in parallel and increase
    performance of some applications. Writes are buffered until client forces
    a flush with fsync() or until the amount of buffered writes exceeds the
    limit.

    Write buffering significantly increases performance of some applications,
    for example, CrystalDiskMark under Windows (LOL :-D), but also any other
    applications if they do writes in one of two non-optimal ways: either if
    they do a lot of small (4 kb or so) sequential writes, or if they do a lot
    of small random writes, but without any parallelism or asynchrony, and also
    without calling fsync().

    With write buffering enabled, you can expect around 22000 T1Q1 random write
    iops in QEMU more or less regardless of the quality of your SSDs, and this
    number is in fact bound by QEMU itself rather than Vitastor (check it
    yourself by adding a "driver=null-co" disk in QEMU). Without write
    buffering, the current record is 9900 iops, but the number is usually
    even lower with non-ideal hardware, for example, it may be 5000 iops.

    Even when this parameter is enabled, write buffering isn't enabled until
    the client explicitly allows it, because enabling it without the client
    being aware of the fact that his writes may be buffered may lead to data
    loss. Because of this, older versions of clients don't support write
    buffering at all, newer versions of the QEMU driver allow write buffering
    only if it's enabled in disk settings with `-blockdev cache.direct=false`,
    and newer versions of FIO only allow write buffering if you don't specify
    `-direct=1`. NBD and NFS drivers allow write buffering by default.

    You can overcome this restriction too with the `client_writeback_allowed`
    parameter, but you shouldn't do that unless you **really** know what you
    are doing.
  info_ru: |
    Данный параметр разрешает включать буферизацию записи в памяти. Буферизация
    означает, что операции записи отправляются на кластер Vitastor не сразу, а
    могут небольшое время накапливаться в памяти и сбрасываться сразу пакетами,
    до тех пор, пока либо не будет превышен лимит неотправленных записей, либо
    пока клиент не вызовет fsync.

    Буферизация значительно повышает производительность некоторых приложений,
    например, CrystalDiskMark в Windows (ха-ха :-D), но также и любых других,
    которые пишут на диск неоптимально: либо последовательно, но мелкими блоками
    (например, по 4 кб), либо случайно, но без параллелизма и без fsync - то
    есть, например, отправляя 128 операций записи в разные места диска, но не
    все сразу с помощью асинхронного I/O, а по одной.

    В QEMU с буферизацией записи можно ожидать показателя примерно 22000
    операций случайной записи в секунду в 1 поток и с глубиной очереди 1 (T1Q1)
    без fsync, почти вне зависимости от того, насколько хороши ваши диски - эта
    цифра упирается в сам QEMU. Без буферизации рекорд пока что - 9900 операций
    в секунду, но на железе похуже может быть и поменьше, например, 5000 операций
    в секунду.

    При этом, даже если данный параметр включён, буферизация не включается, если
    явно не разрешена клиентом, т.к. если клиент не знает, что запросы записи
    буферизуются, это может приводить к потере данных. Поэтому в старых версиях
    клиентских драйверов буферизация записи не включается вообще, в новых
    версиях QEMU-драйвера включается, только если разрешена опцией диска
    `-blockdev cache.direct=false`, а в fio - только если нет опции `-direct=1`.
    В NBD и NFS драйверах буферизация записи разрешена по умолчанию.

    Можно обойти и это ограничение с помощью параметра `client_writeback_allowed`,
    но делать так не надо, если только вы не уверены в том, что делаете, на все
    100%. :-)
- name: client_max_buffered_bytes
  type: int
  default: 33554432
  online: true
  info: |
    Maximum total size of buffered writes which triggers write-back when reached.
  info_ru: |
    Максимальный общий размер буферизованных записей, при достижении которого
    начинается процесс сброса данных на сервер.
- name: client_max_buffered_ops
  type: int
  default: 1024
  online: true
  info: |
    Maximum number of buffered writes which triggers write-back when reached.
    Multiple consecutive modified data regions are counted as 1 write here.
  info_ru: |
    Максимальное количество буферизованных записей, при достижении которого
    начинается процесс сброса данных на сервер. При этом несколько
    последовательных изменённых областей здесь считаются 1 записью.
- name: client_max_writeback_iodepth
  type: int
  default: 256
  online: true
  info: |
    Maximum number of parallel writes when flushing buffered data to the server.
  info_ru: |
    Максимальное число параллельных операций записи при сбросе буферов на сервер.
- name: nbd_timeout
  type: sec
  default: 300
  online: false
  info: |
    Timeout for I/O operations for [NBD](../usage/nbd.en.md). If an operation
    executes for longer than this timeout, including when your cluster is just
    temporarily down for more than timeout, the NBD device will detach by itself
    (and possibly break the mounted file system).

    You can set timeout to 0 to never detach, but in that case you won't be
    able to remove the kernel device at all if the NBD process dies - you'll have
    to reboot the host.
  info_ru: |
    Таймаут для операций чтения/записи через [NBD](../usage/nbd.ru.md). Если
    операция выполняется дольше таймаута, включая временную недоступность
    кластера на время, большее таймаута, NBD-устройство отключится само собой
    (и, возможно, сломает примонтированную ФС).

    Вы можете установить таймаут в 0, чтобы никогда не отключать устройство по
    таймауту, но в этом случае вы вообще не сможете удалить устройство, если
    процесс NBD умрёт - вам придётся перезагружать сервер.
- name: nbd_max_devices
  type: int
  default: 64
  online: false
  info: |
    Maximum number of NBD devices in the system. This value is passed as
    `nbds_max` parameter for the nbd kernel module when vitastor-nbd autoloads it.
  info_ru: |
    Максимальное число NBD-устройств в системе. Данное значение передаётся
    модулю ядра nbd как параметр `nbds_max`, когда его загружает vitastor-nbd.
- name: nbd_max_part
  type: int
  default: 3
  online: false
  info: |
    Maximum number of partitions per NBD device. This value is passed as
    `max_part` parameter for the nbd kernel module when vitastor-nbd autoloads it.
    Note that (nbds_max)*(1+max_part) usually can't exceed 256.
  info_ru: |
    Максимальное число разделов на одном NBD-устройстве. Данное значение передаётся
    модулю ядра nbd как параметр `max_part`, когда его загружает vitastor-nbd.
    Имейте в виду, что (nbds_max)*(1+max_part) обычно не может превышать 256.
- name: osd_nearfull_ratio
  type: float
  default: 0.95
  online: true
  info: |
    Ratio of used space on OSD to treat it as "almost full" in vitastor-cli status output.

    Remember that some client writes may hang or complete with an error if even
    just one OSD becomes 100 % full!

    However, unlike in Ceph, 100 % full Vitastor OSDs don't crash (in Ceph they're
    unable to start at all), so you'll be able to recover from "out of space" errors
    without destroying and recreating OSDs.
  info_ru: |
    Доля занятого места на OSD, начиная с которой он считается "почти заполненным" в
    выводе vitastor-cli status.

    Помните, что часть клиентских запросов может зависнуть или завершиться с ошибкой,
    если на 100 % заполнится хотя бы 1 OSD!

    Однако, в отличие от Ceph, заполненные на 100 % OSD Vitastor не падают (в Ceph
    заполненные на 100% OSD вообще не могут стартовать), так что вы сможете
    восстановить работу кластера после ошибок отсутствия свободного места
    без уничтожения и пересоздания OSD.
- name: hostname
  type: string
  online: true
  info: |
    Clients use host name to find their distance to OSDs when [localized reads](pool.en.md#local_reads)
    are enabled. By default, standard [gethostname](https://man7.org/linux/man-pages/man2/gethostname.2.html)
    function is used to determine host name, but you can also override it with this parameter.
  info_ru: |
    Клиенты используют имя хоста для определения расстояния до OSD, когда включены
    [локальные чтения](pool.ru.md#local_reads). По умолчанию для определения имени
    хоста используется стандартная функция [gethostname](https://man7.org/linux/man-pages/man2/gethostname.2.html),
    но вы также можете задать имя хоста вручную данным параметром.
- name: ublk_queue_depth
  type: int
  default: 256
  online: false
  info: Default queue depth for [Vitastor ublk servers](../usage/ublk.en.md).
  info_ru: Глубина очереди по умолчанию для [ublk-серверов Vitastor](../usage/ublk.ru.md).
- name: ublk_max_io_size
  type: int
  online: false
  info: |
    Default maximum I/O size for Vitastor [ublk servers](../usage/ublk.en.md).
    The largest of 1 MB and pool block size multiplied by EC data chunk count is used if not specified.
  info_ru: |
    Максимальный размер запроса ввода-вывода для [ublk-серверов Vitastor](../usage/ublk.ru.md).
    Если не задан, используется максимум из 1 МБ и размера блока пула, умноженного на число частей
    данных EC-пула.
- name: qemu_file_mirror_path
  type: string
  info: |
    When set to an FS directory path (for example, `/mnt/vitastor/`), `qemu-img info` and similar
    QAPI commands return the name of the image inside this directory instead of normal
    `vitastor://?image=abc` URI as `filename`.

    This allows to then mount this path using [vitastor-nfs](../usage/nfs.en.md) and trick
    third-party systems like Veeam which rely on `filename` in the image info but don't support Vitastor.
  info_ru: |
    Если установить эту опцию равной пути к каталогу в ФС, команда `qemu-img info` и подобные
    команды QAPI будут возвращать в поле `filename` имя образа внутри заданного каталога вместо
    обычного адреса типа `vitastor://?image=abc`.

    Это позволяет смонтировать этот путь с помощью [vitastor-nfs](../usage/nfs.ru.md) и обмануть
    сторонние системы типа Veeam, которые полагаются на поле `filename` в информации об образе QEMU,
    но не поддерживают Vitastor.
