Update some parameter docs

docs/params/common.yml

@@ -22,7 +22,7 @@
   type: string
   default: "/vitastor"
   info: |
-    Prefix for all keys in etcd Vitastor uses. You can change prefix and, for
+    Prefix for all keys in etcd used by Vitastor. You can change prefix and, for
     example, use a single etcd cluster for multiple Vitastor clusters.
   info_ru: |
     Префикс для ключей etcd, которые использует Vitastor. Вы можете задать другой

docs/params/layout-cluster.yml

@@ -6,80 +6,45 @@
     subdivided in Vitastor. One of current main settings in Vitastor, affects
     memory usage, write amplification and I/O load distribution effectiveness.
 
-    Block size is fixed for the whole Vitastor cluster i.e. two different block
-    sizes can't be used in a single Vitastor cluster. Also you must not change
-    block size after initializing an OSD because even if you succeed you'll
-    destroy your data.
-
     Recommended default block size is 128 KB for SSD and 4 MB for HDD. In fact,
     it's possible to use 4 MB for SSD too - it will lower memory usage, but
-    may increase average WA and reduce linear performance. SSD and HDD OSDs
-    with different block size can currently coexist in one etcd instance only
-    within separate Vitastor clusters with different etcd_prefix'es.
+    may increase average WA and reduce linear performance.
+
+    OSDs with different block sizes (for example, SSD and SSD+HDD OSDs) can
+    currently coexist in one etcd instance only within separate Vitastor
+    clusters with different etcd_prefix'es.
+
+    Also block size can't be changed after OSD initialization without losing
+    data.
 
     You must always specify block_size in etcd in /vitastor/config/global if
     you change it so all clients can know about it.
 
     OSD memory usage is roughly (SIZE / BLOCK * 68 bytes) which is roughly
-    544 MB per 1 TB of used disk space with default 128 KB block size.
+    544 MB per 1 TB of used disk space with the default 128 KB block size.
   info_ru: |
     Размер объектов (блоков данных), на которые делятся физические и виртуальные
     диски в Vitastor. Одна из ключевых на данный момент настроек, влияет на
     потребление памяти, объём избыточной записи (write amplification) и
     эффективность распределения нагрузки по OSD.
 
-    Размер блока фиксируется на уровне всего кластера Vitastor, т.е. разные
-    размеры блока не могут сосуществовать в одном кластере. Также размер блока
-    нельзя менять после инициализации OSD - даже если у вас получится, вы
-    уничтожите сохранённые на OSD данные.
-
     Рекомендуемые по умолчанию размеры блока - 128 килобайт для SSD и 4
     мегабайта для HDD. В принципе, для SSD можно тоже использовать 4 мегабайта,
     это понизит использование памяти, но ухудшит распределение нагрузки и в
-    среднем увеличит WA. SSD и HDD с разными размерами блока на данный момент
-    могут сосуществовать в рамках одного etcd только в виде двух независимых
+    среднем увеличит WA.
+
+    OSD с разными размерами блока (например, SSD и SSD+HDD OSD) на данный
+    момент могут сосуществовать в рамках одного etcd только в виде двух независимых
     кластеров Vitastor с разными etcd_prefix.
 
+    Также размер блока нельзя менять после инициализации OSD без потери данных.
+
     Если вы меняете размер блока, обязательно прописывайте его в etcd в
     /vitastor/config/global, дабы все клиенты его знали.
 
     Потребление памяти OSD составляет примерно (РАЗМЕР / БЛОК * 68 байт),
     т.е. примерно 544 МБ памяти на 1 ТБ занятого места на диске при
     стандартном 128 КБ блоке.
-- 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 the only SSD that may fit into this category is
-    Intel Optane (probably, not tested yet).
-  info_ru: |
-    Требуемое выравнивание записи на физические диски. Почти все современные
-    SSD и HDD диски используют 4 КБ физические секторы, даже если показывают
-    логический размер сектора 512 байт, поэтому 4 КБ - хорошее значение по
-    умолчанию.
-
-    Однако стоит понимать, что физический размер сектора тоже влияет на
-    избыточную запись (WA), потому что ничего меньше блока (сектора) на блочное
-    устройство записать невозможно. Таким образом, когда Vitastor-у нужно
-    записать на диск всего лишь одну 32-байтную запись метаданных, фактически
-    приходится перезаписывать 4 КБ сектор целиком.
-
-    Поэтому, на самом деле, может быть выгодно найти SSD, хорошо работающие с
-    меньшими, 512-байтными, блоками и использовать 512-байтные disk_alignment,
-    journal_block_size и meta_block_size. Однако единственные SSD, которые
-    теоретически могут попасть в эту категорию - это Intel Optane (но и это
-    пока не проверялось автором).
 - name: bitmap_granularity
   type: int
   default: 4096
@@ -88,11 +53,26 @@
     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.
+
+    This parameter can't be changed after OSD initialization without losing
+    data. Also it's fixed for the whole Vitastor cluster i.e. two different
+    values can't be used in a single Vitastor cluster.
+
+    Clients MUST be aware of this parameter value, so put it into etcd key
+    /vitastor/config/global if you change it for any reason.
   info_ru: |
     Требуемое выравнивание записи на виртуальные диски (размер их "сектора").
     Должен быть кратен disk_alignment. Называется гранулярностью битовой карты
     потому, что Vitastor хранит битовую карту для каждого объекта, содержащую
     по 2 бита на каждые (bitmap_granularity) байт.
+
+    Данный параметр нельзя менять после инициализации OSD без потери данных.
+    Также он фиксирован для всего кластера Vitastor, т.е. разные значения
+    не могут сосуществовать в одном кластере.
+
+    Клиенты ДОЛЖНЫ знать правильное значение этого параметра, так что если вы
+    его меняете, обязательно прописывайте изменённое значение в etcd в ключ
+    /vitastor/config/global.
 - name: immediate_commit
   type: string
   default: false
@@ -134,6 +114,11 @@
     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).
 
+    This parameter must be set both in etcd in /vitastor/config/global and in
+    OSD command line or configuration. Setting it to "all" or "small" requires
+    enabling disable_journal_fsync and disable_meta_fsync, setting it to "all"
+    also requires enabling disable_data_fsync.
+
     TLDR: For optimal performance, set immediate_commit to "all" if you only use
     SSDs with supercapacitor-based power loss protection (nonvolatile
     write-through cache) for both data and journals in the whole Vitastor
@@ -183,6 +168,11 @@
     многих дисках Seagate EXOS (у них есть внутренний SSD-кэш, хотя это и не
     указано в спецификациях).
 
+    Данный параметр нужно указывать и в etcd в /vitastor/config/global, и в
+    командной строке или конфигурации OSD. Значения "all" и "small" требуют
+    включения disable_journal_fsync и disable_meta_fsync, значение "all" также
+    требует включения disable_data_fsync.
+
     Итого, вкратце: для оптимальной производительности установите
     immediate_commit в значение "all", если вы используете в кластере только SSD
     с суперконденсаторами и для данных, и для журналов. Если вы используете
@@ -198,9 +188,13 @@
     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.
+
+    This parameter doesn't affect OSDs themselves.
   info_ru: |
     При работе без immediate_commit=all - это лимит объёма "грязных" (не
     зафиксированных fsync-ом) данных, при достижении которого клиент будет
     принудительно вызывать fsync и фиксировать данные. Также стоит иметь в виду,
     что в этом случае до момента fsync клиент хранит копию незафиксированных
     данных в памяти, то есть, настройка влияет на потребление памяти клиентами.
+
+    Параметр не влияет на сами OSD.

docs/params/layout-osd.yml

@@ -4,14 +4,14 @@
     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.
-    For testing purposes, files can also be used instead of block devices, but
-    that's not for a production environment, of course.
+    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: |
@@ -130,7 +130,7 @@
     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: |
+  info_ru: |
     То же, что disable_data_fsync, но для устройства метаданных. Если устройство
     метаданных не задано или если оно равно устройству данных, значение опции
     игнорируется и вместо него используется значение опции disable_data_fsync.
@@ -143,7 +143,7 @@
     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: |
+  info_ru: |
     То же, что disable_data_fsync, но для устройства журнала. Если устройство
     журнала не задано или если оно равно устройству метаданных, значение опции
     игнорируется и вместо него используется значение опции disable_meta_fsync.
@@ -163,3 +163,43 @@
     другими 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 the only SSD that may fit into this category is
+    Intel Optane (probably, not tested yet).
+
+    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, которые
+    теоретически могут попасть в эту категорию - это Intel Optane (но и это
+    пока не проверялось автором).
+
+    Клиентам не обязательно знать про disk_alignment, так что помещать значение
+    этого параметра в etcd в /vitastor/config/global не нужно.

docs/params/monitor.yml

@@ -43,7 +43,7 @@
     на другие OSD и таким образом восстановить избыточность хранения.
 - name: placement_levels
   type: json
-  default: '{"host":100,"osd":101}'
+  default: '`{"host":100,"osd":101}`'
   info: |
     Levels for the placement tree. You can define arbitrary tree levels by
     defining them in this parameter. The configuration parameter value should

docs/params/network.yml

@@ -34,20 +34,33 @@
   type: bool
   default: true
   info: |
-    Try to use RDMA for communication if it's available.
-    Disable if you don't want Vitastor to use RDMA.
+    Try to use RDMA for communication if it's available. Disable if you don't
+    want Vitastor to use RDMA. RDMA increases the performance, but TCP-only
+    clients can still talk to an RDMA-enabled cluster, so you don't need to
+    make sure that all clients support RDMA when enabling it.
   info_ru: |
     Пытаться использовать RDMA для связи при наличии доступных устройств.
     Отключите, если вы не хотите, чтобы Vitastor использовал RDMA.
+    RDMA улучшает производительность, но 
+    Клиенты и клиентов and TCP-only clients in the cluster at the
+    same time - TCP-only clients are still able to use an RDMA-enabled cluster.
 - name: rdma_device
   type: string
   info: |
     RDMA device name to use for Vitastor OSD communications (for example,
-    "rocep5s0f0"). Run `ibv_devinfo -v` as root to list available RDMA devices.
+    "rocep5s0f0"). Please note that Vitastor RDMA requires Implicit On-Demand
+    Paging (Implicit ODP) and Scatter/Gather (SG) support from the RDMA device
+    to work. For example, Mellanox ConnectX-3 and older adapters don't have
+    Implicit ODP, so they're unsupported by Vitastor. Run `ibv_devinfo -v` as
+    root to list available RDMA devices and their features.
   info_ru: |
     Название RDMA-устройства для связи с Vitastor OSD (например, "rocep5s0f0").
-    Запустите `ibv_devinfo -v` под суперпользователем, чтобы посмотреть список
-    доступных RDMA-устройств и их параметры.
+    Имейте в виду, что поддержка RDMA в Vitastor требует функций устройства
+    Implicit On-Demand Paging (Implicit ODP) и Scatter/Gather (SG). Например,
+    адаптеры Mellanox ConnectX-3 и более старые не поддерживают Implicit ODP и
+    потому не поддерживаются в Vitastor. Запустите `ibv_devinfo -v` от имени
+    суперпользователя, чтобы посмотреть список доступных RDMA-устройств, их
+    параметры и возможности.
 - name: rdma_port_num
   type: int
   default: 1

docs/params/osd.yml

@@ -4,13 +4,13 @@
   info: |
     Interval at which OSDs report their state to etcd. Affects OSD lease time
     and thus the failover speed. Lease time is equal to this parameter value
-    plus max_etcd_attempts*etcd_quick_timeout because it should be guaranteed
+    plus max_etcd_attempts * etcd_quick_timeout because it should be guaranteed
     that every OSD always refreshes its lease in time.
   info_ru: |
     Интервал, с которым OSD обновляет своё состояние в etcd. Значение параметра
     влияет на время резервации (lease) OSD и поэтому на скорость переключения
     при падении OSD. Время lease равняется значению этого параметра плюс
-    max_etcd_attempts*etcd_quick_timeout.
+    max_etcd_attempts * etcd_quick_timeout.
 - name: run_primary
   type: bool
   default: true
@@ -245,15 +245,17 @@
   info: |
     Enable this option for SSDs like Intel D3-S4510 and D3-S4610 which REALLY
     don't like when a program overwrites the same sector multiple times in a
-    row and slow down significantly (from 20000+ iops to ~3000 iops). When
+    row and slow down significantly (from 25000+ iops to ~3000 iops). When
     this option is set, Vitastor will always move to the next sector of the
     journal after writing it instead of possibly overwriting it the second time.
   info_ru: |
-    Включайте данную опцию для SSD вроде Intel D3-S4510 и D3-4610, которые ОЧЕНЬ
-    не любят, когда ПО перезаписывает один и тот же сектор несколько раз подряд
-    и сильно замедляются (с 20000 и более iops до 3000). Когда данная опция
-    установлена, Vitastor всегда переходит к следующему сектор журнала после
-    записи вместо потенциально повторной перезаписи того же самого сектора.
+    Включайте данную опцию для SSD вроде Intel D3-S4510 и D3-S4610, которые
+    ОЧЕНЬ не любят, когда ПО перезаписывает один и тот же сектор несколько раз
+    подряд. Такие SSD при многократной перезаписи одного и того же сектора
+    сильно замедляются - условно, с 25000 и более iops до 3000 iops. Когда
+    данная опция установлена, Vitastor всегда переходит к следующему сектору
+    журнала после записи вместо потенциально повторной перезаписи того же
+    самого сектора.
 - name: throttle_small_writes
   type: bool
   default: false
@@ -319,7 +321,7 @@
     равным внутреннему параллелизму ваших устройств данных (1 для HDD, 4-8
     для SSD).
 - name: throttle_threshold_us
-  type: usec
+  type: us
   default: 50
   info: |
     Minimal computed delay to be applied to throttled operations. Usually