Add documentation

docs/README.md

@@ -0,0 +1,29 @@
+[Читать на русском](README.ru.md)
+
+# Vitastor Documentation
+
+- Installation
+  - [Quick Start](installation/quickstart.en.md)
+  - [Packages](installation/packages.en.md)
+  - [Proxmox](installation/proxmox.en.md)
+  - [OpenStack](installation/openstack.en.md)
+  - [Kubernetes CSI](installation/kubernetes.en.md)
+  - [Building from Source](installation/source.en.md)
+- Configuration
+  - [Overview](config.en.md)
+  - Parameter Reference
+    - [Common](config/common.en.md)
+    - [Network](config/network.en.md)
+    - [Global Disk Layout](config/layout-cluster.en.md)
+    - [OSD Disk Layout](config/layout-osd.en.md)
+    - [OSD Runtime Parameters](config/osd.en.md)
+    - [Monitor](config/monitor.en.md)
+  - [Pool configuration](config/pool.en.md)
+- Usage
+  - [vitastor-cli](usage/cli.en.md) (command-line interface)
+  - [NBD](usage/nbd.en.md) for kernel mounts
+  - [QEMU and qemu-img](usage/qemu.en.md)
+- Performance
+  - [Understanding storage performance](performance/understanding.md)
+  - [Theoretical performance](performance/theoretical.md)
+  - [Example comparison with Ceph](performance/comparison1.md)

docs/config.en.md

@@ -0,0 +1,60 @@
+[Читать на русском](config.ru.md)
+
+# Configuration Reference
+
+Vitastor configuration consists of:
+- Configuration parameters (key-value), described here
+- [Pool configuration](pool.en.md)
+- OSD placement tree configuration
+- Inode configuration i.e. image metadata like name, size and parent reference
+
+Configuration parameters can be set in 3 places:
+- Configuration file (`/etc/vitastor/vitastor.conf` or other path)
+- etcd key `/vitastor/config/global`. Most variables can be set there, but etcd
+  connection parameters should obviously be set in the configuration file.
+- Command line of Vitastor components: OSD, mon, fio and QEMU options,
+  OpenStack/Proxmox/etc configuration. The latter doesn't allow to set all
+  variables directly, but it allows to override the configuration file and
+  set everything you need inside it.
+
+In the future, additional configuration methods may be added:
+- OSD superblock which will, by design, contain parameters related to the disk
+  layout and to one specific OSD.
+- OSD-specific keys in etcd like `/vitastor/config/osd/<number>`.
+
+## Common Parameters
+
+These are the most common parameters which apply to all components of Vitastor.
+
+[See the list](common.en.md)
+
+## Cluster-Wide Disk Layout Parameters
+
+These parameters apply to clients and OSDs and can't be changed after OSD
+initialization.
+
+[See the list](layout-cluster.en.md)
+
+## OSD Disk Layout Parameters
+
+These parameters apply to OSDs and can't be changed after OSD initialization.
+
+[See the list](layout-osd.en.md)
+
+## Network Protocol Parameters
+
+These parameters apply to clients and OSDs and can be changed with a restart.
+
+[See the list](network.en.md)
+
+## Runtime OSD Parameters
+
+These parameters apply to OSDs and can be changed with an OSD restart.
+
+[See the list](osd.en.md)
+
+## Monitor Parameters
+
+These parameters only apply to Monitors.
+
+[See the list](monitor.en.md)

docs/config.ru.md

@@ -0,0 +1,62 @@
+[Read in Enlish](config.en.md)
+
+# Конфигурация Vitastor
+
+Конфигурация Vitastor состоит из:
+- Параметров (ключ-значение), описанных на данной странице
+- [Настроек пулов](pool.ru.md)
+- Настроек дерева OSD
+- Настроек инодов, т.е. метаданных образов, таких, как имя, размер и ссылки на
+  родительский образ
+
+Параметры конфигурации могут задаваться в 3 местах:
+- Файле конфигурации (`/etc/vitastor/vitastor.conf` или по другому пути)
+- Ключе в etcd `/vitastor/config/global`. Большая часть параметров может
+  задаваться там, кроме, естественно, самих параметров соединения с etcd,
+  которые должны задаваться в файле конфигурации
+- В командной строке компонентов Vitastor: OSD, монитора, опциях fio и QEMU,
+  настроек OpenStack, Proxmox и т.п. Последние, как правило, не включают полный
+  набор параметров напрямую, но разрешают определить путь к файлу конфигурации
+  и задать любые параметры в нём.
+
+В будущем также могут быть добавлены другие способы конфигурации:
+- Суперблок OSD, в котором будут храниться параметры OSD, связанные с дисковым
+  форматом и с этим конкретным OSD.
+- OSD-специфичные ключи в etcd типа `/vitastor/config/osd/<номер>`.
+
+## Общие параметры
+
+Это наиболее общие параметры, используемые всеми компонентами Vitastor.
+
+[Посмотреть список](common.ru.md)
+
+## Дисковые параметры уровня кластера
+
+Эти параметры используются клиентами и OSD и не могут быть изменены после
+инициализации OSD.
+
+[Посмотреть список](layout-cluster.ru.md)
+
+## Дисковые параметры OSD
+
+Эти параметры используются OSD и не могут быть изменены после инициализации OSD.
+
+[Посмотреть список](layout-osd.ru.md)
+
+## Параметры сетевого протокола
+
+Эти параметры используются клиентами и OSD и могут быть изменены с перезапуском.
+
+[Посмотреть список](network.ru.md)
+
+## Изменяемые параметры OSD
+
+Эти параметры используются OSD и могут быть изменены с перезапуском.
+
+[Посмотреть список](osd.ru.md)
+
+## Параметры мониторов
+
+Данные параметры используются только мониторами Vitastor.
+
+[Посмотреть список](monitor.ru.md)

docs/config/common.en.md

@@ -0,0 +1,42 @@
+[Читать на русском](common.ru.md)
+
+# Common Parameters
+
+These are the most common parameters which apply to all components of Vitastor.
+
+- [config_path](#config_path)
+- [etcd_address](#etcd_address)
+- [etcd_prefix](#etcd_prefix)
+- [log_level](#log_level)
+
+## config_path
+
+- Type: string
+- Default: /etc/vitastor/vitastor.conf
+
+Path to the JSON configuration file. Configuration file is optional,
+a non-existing configuration file does not prevent Vitastor from
+running if required parameters are specified.
+
+## etcd_address
+
+- Type: string or array of strings
+
+etcd connection endpoint(s). Multiple endpoints may be delimited by "," or
+specified in a JSON array `["10.0.115.10:2379/v3","10.0.115.11:2379/v3"]`.
+Note that https is not supported for etcd connections yet.
+
+## etcd_prefix
+
+- Type: string
+- Default: /vitastor
+
+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.
+
+## log_level
+
+- Type: integer
+- Default: 0
+
+Log level. Raise if you want more verbose output.

docs/config/common.ru.md

@@ -0,0 +1,41 @@
+[Read in English](common.en.md)
+
+# Общие параметры
+
+Это наиболее общие параметры, используемые всеми компонентами Vitastor.
+
+- [config_path](#config_path)
+- [etcd_address](#etcd_address)
+- [etcd_prefix](#etcd_prefix)
+- [log_level](#log_level)
+
+## config_path
+
+- Тип: строка
+- Значение по умолчанию: /etc/vitastor/vitastor.conf
+
+Путь к файлу конфигурации в формате JSON. Файл конфигурации необязателен,
+без него Vitastor тоже будет работать, если переданы необходимые параметры.
+
+## etcd_address
+
+- Тип: строка или массив строк
+
+Адрес(а) подключения к etcd. Несколько адресов могут разделяться запятой
+или указываться в виде JSON-массива `["10.0.115.10:2379/v3","10.0.115.11:2379/v3"]`.
+
+## etcd_prefix
+
+- Тип: строка
+- Значение по умолчанию: /vitastor
+
+Префикс для ключей etcd, которые использует Vitastor. Вы можете задать другой
+префикс, например, чтобы запустить несколько кластеров Vitastor с одним
+кластером etcd.
+
+## log_level
+
+- Тип: целое число
+- Значение по умолчанию: 0
+
+Уровень логгирования. Повысьте, если хотите более подробный вывод.

docs/config/layout-cluster.en.md

@@ -0,0 +1,120 @@
+[Читать на русском](layout-cluster.ru.md)
+
+# Cluster-Wide Disk Layout Parameters
+
+These parameters apply to clients and OSDs, are fixed at the moment of OSD drive
+initialization and can't be changed after it without losing data.
+
+- [block_size](#block_size)
+- [bitmap_granularity](#bitmap_granularity)
+- [immediate_commit](#immediate_commit)
+- [client_dirty_limit](#client_dirty_limit)
+
+## block_size
+
+- Type: integer
+- Default: 131072
+
+Size of objects (data blocks) into which all physical and virtual drives 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 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.
+
+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 the default 128 KB block size.
+
+## bitmap_granularity
+
+- Type: integer
+- Default: 4096
+
+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.
+
+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.
+
+## immediate_commit
+
+- Type: string
+- Default: false
+
+Another parameter which is really important for performance.
+
+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, when you want to guarantee that
+each change gets immediately 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" the whole
+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).
+
+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
+cluster. Set it to "small" if you only use such SSDs for journals. Leave
+empty if your drives have write-back cache.
+
+## client_dirty_limit
+
+- Type: integer
+- Default: 33554432
+
+Without 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.
+
+This parameter doesn't affect OSDs themselves.

docs/config/layout-cluster.ru.md

@@ -0,0 +1,130 @@
+[Read in English](layout-cluster.en.md)
+
+# Дисковые параметры уровня кластера
+
+Данные параметры используются клиентами и OSD, задаются в момент инициализации
+диска OSD и не могут быть изменены после этого без потери данных.
+
+- [block_size](#block_size)
+- [bitmap_granularity](#bitmap_granularity)
+- [immediate_commit](#immediate_commit)
+- [client_dirty_limit](#client_dirty_limit)
+
+## block_size
+
+- Тип: целое число
+- Значение по умолчанию: 131072
+
+Размер объектов (блоков данных), на которые делятся физические и виртуальные
+диски в Vitastor. Одна из ключевых на данный момент настроек, влияет на
+потребление памяти, объём избыточной записи (write amplification) и
+эффективность распределения нагрузки по OSD.
+
+Рекомендуемые по умолчанию размеры блока - 128 килобайт для SSD и 4
+мегабайта для HDD. В принципе, для SSD можно тоже использовать 4 мегабайта,
+это понизит использование памяти, но ухудшит распределение нагрузки и в
+среднем увеличит WA.
+
+OSD с разными размерами блока (например, SSD и SSD+HDD OSD) на данный
+момент могут сосуществовать в рамках одного etcd только в виде двух независимых
+кластеров Vitastor с разными etcd_prefix.
+
+Также размер блока нельзя менять после инициализации OSD без потери данных.
+
+Если вы меняете размер блока, обязательно прописывайте его в etcd в
+/vitastor/config/global, дабы все клиенты его знали.
+
+Потребление памяти OSD составляет примерно (РАЗМЕР / БЛОК * 68 байт),
+т.е. примерно 544 МБ памяти на 1 ТБ занятого места на диске при
+стандартном 128 КБ блоке.
+
+## bitmap_granularity
+
+- Тип: целое число
+- Значение по умолчанию: 4096
+
+Требуемое выравнивание записи на виртуальные диски (размер их "сектора").
+Должен быть кратен disk_alignment. Называется гранулярностью битовой карты
+потому, что Vitastor хранит битовую карту для каждого объекта, содержащую
+по 2 бита на каждые (bitmap_granularity) байт.
+
+Данный параметр нельзя менять после инициализации OSD без потери данных.
+Также он фиксирован для всего кластера Vitastor, т.е. разные значения
+не могут сосуществовать в одном кластере.
+
+Клиенты ДОЛЖНЫ знать правильное значение этого параметра, так что если вы
+его меняете, обязательно прописывайте изменённое значение в etcd в ключ
+/vitastor/config/global.
+
+## immediate_commit
+
+- Тип: строка
+- Значение по умолчанию: false
+
+Ещё один важный для производительности параметр.
+
+Модели 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-кэш, хотя это и не
+указано в спецификациях).
+
+Данный параметр нужно указывать и в etcd в /vitastor/config/global, и в
+командной строке или конфигурации OSD. Значения "all" и "small" требуют
+включения disable_journal_fsync и disable_meta_fsync, значение "all" также
+требует включения disable_data_fsync.
+
+Итого, вкратце: для оптимальной производительности установите
+immediate_commit в значение "all", если вы используете в кластере только SSD
+с суперконденсаторами и для данных, и для журналов. Если вы используете
+такие SSD для всех журналов, но не для данных - можете установить параметр
+в "small". Если и какие-то из дисков журналов имеют волатильный кэш записи -
+оставьте параметр пустым.
+
+## client_dirty_limit
+
+- Тип: целое число
+- Значение по умолчанию: 33554432
+
+При работе без immediate_commit=all - это лимит объёма "грязных" (не
+зафиксированных fsync-ом) данных, при достижении которого клиент будет
+принудительно вызывать fsync и фиксировать данные. Также стоит иметь в виду,
+что в этом случае до момента fsync клиент хранит копию незафиксированных
+данных в памяти, то есть, настройка влияет на потребление памяти клиентами.
+
+Параметр не влияет на сами OSD.

docs/config/layout-osd.en.md

@@ -0,0 +1,171 @@
+[Читать на русском](layout-osd.ru.md)
+
+# OSD Disk Layout Parameters
+
+These parameters apply to OSDs, are fixed at the moment of OSD drive
+initialization and can't be changed after it without losing data.
+
+- [data_device](#data_device)
+- [meta_device](#meta_device)
+- [journal_device](#journal_device)
+- [journal_offset](#journal_offset)
+- [journal_size](#journal_size)
+- [meta_offset](#meta_offset)
+- [data_offset](#data_offset)
+- [data_size](#data_size)
+- [meta_block_size](#meta_block_size)
+- [journal_block_size](#journal_block_size)
+- [disable_data_fsync](#disable_data_fsync)
+- [disable_meta_fsync](#disable_meta_fsync)
+- [disable_journal_fsync](#disable_journal_fsync)
+- [disable_device_lock](#disable_device_lock)
+- [disk_alignment](#disk_alignment)
+
+## data_device
+
+- Type: string
+
+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.
+
+## meta_device
+
+- Type: string
+
+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.
+
+## journal_device
+
+- Type: string
+
+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`.
+
+## journal_offset
+
+- Type: integer
+- Default: 0
+
+Offset on the device in bytes where the journal is stored.
+
+## journal_size
+
+- Type: integer
+
+Journal size in bytes. Doesn't have to be large, 16-32 MB is usually fine.
+By default, the whole journal device will be used for the journal. You must
+set it to some value manually (or use make-osd.sh) if you colocate the
+journal with data or metadata.
+
+## meta_offset
+
+- Type: integer
+- Default: 0
+
+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.
+
+## data_offset
+
+- Type: integer
+- Default: 0
+
+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.
+
+## data_size
+
+- Type: integer
+
+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.
+
+## meta_block_size
+
+- Type: integer
+- Default: 4096
+
+Physical block size of the metadata device. 4096 for most current
+HDDs and SSDs.
+
+## journal_block_size
+
+- Type: integer
+- Default: 4096
+
+Physical block size of the journal device. Must be a multiple of
+`disk_alignment`. 4096 for most current HDDs and SSDs.
+
+## disable_data_fsync
+
+- Type: boolean
+- Default: false
+
+Do not issue fsyncs to the data device, i.e. do not flush its cache.
+Safe ONLY if your data device has write-through cache. If you disable
+the cache yourself using `hdparm` or `scsi_disk/cache_type` then make sure
+that the cache disable command is run every time before starting Vitastor
+OSD, for example, in the systemd unit. See also `immediate_commit` option
+for the instructions to disable cache and how to benefit from it.
+
+## disable_meta_fsync
+
+- Type: boolean
+- Default: false
+
+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.
+
+## disable_journal_fsync
+
+- Type: boolean
+- Default: false
+
+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.
+
+## disable_device_lock
+
+- Type: boolean
+- Default: false
+
+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.
+
+## disk_alignment
+
+- Type: integer
+- Default: 4096
+
+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.

docs/config/layout-osd.ru.md

@@ -0,0 +1,181 @@
+[Read in English](layout-osd.en.md)
+
+# Дисковые параметры OSD
+
+Данные параметры используются только OSD и, также как и общекластерные
+дисковые параметры, задаются в момент инициализации дисков OSD и не могут быть
+изменены после этого без потери данных.
+
+- [data_device](#data_device)
+- [meta_device](#meta_device)
+- [journal_device](#journal_device)
+- [journal_offset](#journal_offset)
+- [journal_size](#journal_size)
+- [meta_offset](#meta_offset)
+- [data_offset](#data_offset)
+- [data_size](#data_size)
+- [meta_block_size](#meta_block_size)
+- [journal_block_size](#journal_block_size)
+- [disable_data_fsync](#disable_data_fsync)
+- [disable_meta_fsync](#disable_meta_fsync)
+- [disable_journal_fsync](#disable_journal_fsync)
+- [disable_device_lock](#disable_device_lock)
+- [disk_alignment](#disk_alignment)
+
+## data_device
+
+- Тип: строка
+
+Путь к диску (блочному устройству) для хранения данных. Крайне рекомендуется
+использовать стабильные пути: `/dev/disk/by-partuuid/xxx...` вместо простых
+`/dev/sda` или `/dev/nvme0n1`, чтобы пути не могли спутаться после
+перезагрузки сервера. Также вместо блочных устройств можно указывать файлы,
+но это реализовано только для тестирования, а не для боевой среды.
+
+## meta_device
+
+- Тип: строка
+
+Путь к диску метаданных. Метаданные должны располагаться на быстром
+SSD-диске, иначе производительность пострадает. Если эта опция не указана,
+для метаданных используется `data_device`.
+
+## journal_device
+
+- Тип: строка
+
+Путь к диску журнала. Журнал должен располагаться на быстром SSD-диске,
+иначе производительность пострадает. Если эта опция не указана,
+для журнала используется `meta_device`, если же пуста и она, журнал
+располагается на `data_device`. Нормально располагать журнал и метаданные
+на одном устройстве, в этом случае достаточно указать только `meta_device`.
+
+## journal_offset
+
+- Тип: целое число
+- Значение по умолчанию: 0
+
+Смещение на устройстве в байтах, по которому располагается журнал.
+
+## journal_size
+
+- Тип: целое число
+
+Размер журнала в байтах. Большим быть не обязан, 16-32 МБ обычно достаточно.
+По умолчанию для журнала используется всё устройство журнала. Если же вы
+размещаете журнал на устройстве данных или метаданных, то вы должны
+установить эту опцию в какое-то значение сами (или использовать скрипт
+make-osd.sh).
+
+## meta_offset
+
+- Тип: целое число
+- Значение по умолчанию: 0
+
+Смещение на устройстве в байтах, по которому располагаются метаданные.
+Эту опцию нужно задать, если метаданные у вас хранятся на том же
+устройстве, что данные или журнал.
+
+## data_offset
+
+- Тип: целое число
+- Значение по умолчанию: 0
+
+Смещение на устройстве в байтах, по которому располагаются данные.
+Эту опцию нужно задать, если данные у вас хранятся на том же
+устройстве, что метаданные или журнал.
+
+## data_size
+
+- Тип: целое число
+
+Размер области данных в байтах. По умолчанию под данные будет использована
+вся доступная область устройства данных до конца устройства, но вы можете
+использовать эту опцию, чтобы ограничить её меньшим размером. Заметьте, что
+опции размера области метаданных нет - она вычисляется из размера области
+данных автоматически.
+
+## meta_block_size
+
+- Тип: целое число
+- Значение по умолчанию: 4096
+
+Размер физического блока устройства метаданных. 4096 для большинства
+современных SSD и HDD.
+
+## journal_block_size
+
+- Тип: целое число
+- Значение по умолчанию: 4096
+
+Размер физического блока устройства журнала. Должен быть кратен
+`disk_alignment`. 4096 для большинства современных SSD и HDD.
+
+## disable_data_fsync
+
+- Тип: булево (да/нет)
+- Значение по умолчанию: false
+
+Не отправлять fsync-и устройству данных, т.е. не сбрасывать его кэш.
+Безопасно, ТОЛЬКО если ваше устройство данных имеет кэш со сквозной
+записью (write-through). Если вы отключаете кэш через `hdparm` или
+`scsi_disk/cache_type`, то удостоверьтесь, что команда отключения кэша
+выполняется перед каждым запуском Vitastor OSD, например, в systemd unit-е.
+Смотрите также опцию `immediate_commit` для инструкций по отключению кэша
+и о том, как из этого извлечь выгоду.
+
+## disable_meta_fsync
+
+- Тип: булево (да/нет)
+- Значение по умолчанию: false
+
+То же, что disable_data_fsync, но для устройства метаданных. Если устройство
+метаданных не задано или если оно равно устройству данных, значение опции
+игнорируется и вместо него используется значение опции disable_data_fsync.
+
+## disable_journal_fsync
+
+- Тип: булево (да/нет)
+- Значение по умолчанию: false
+
+То же, что disable_data_fsync, но для устройства журнала. Если устройство
+журнала не задано или если оно равно устройству метаданных, значение опции
+игнорируется и вместо него используется значение опции disable_meta_fsync.
+Если одно и то же устройство используется и под данные, и под журнал, и под
+метаданные - значение опции также игнорируется и вместо него используется
+значение опции disable_data_fsync.
+
+## disable_device_lock
+
+- Тип: булево (да/нет)
+- Значение по умолчанию: false
+
+Не блокировать устройства данных, метаданных и журнала от открытия их
+другими OSD с помощью flock(). Так делать не рекомендуется, но теоретически
+вы можете это использовать, чтобы запускать несколько OSD на одном
+устройстве с разными смещениями и без использования разделов.
+
+## disk_alignment
+
+- Тип: целое число
+- Значение по умолчанию: 4096
+
+Требуемое выравнивание записи на физические диски. Почти все современные
+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/config/monitor.en.md

@@ -0,0 +1,75 @@
+[Читать на русском](monitor.ru.md)
+
+# Monitor Parameters
+
+These parameters only apply to Monitors.
+
+- [etcd_mon_ttl](#etcd_mon_ttl)
+- [etcd_mon_timeout](#etcd_mon_timeout)
+- [etcd_mon_retries](#etcd_mon_retries)
+- [mon_change_timeout](#mon_change_timeout)
+- [mon_stats_timeout](#mon_stats_timeout)
+- [osd_out_time](#osd_out_time)
+- [placement_levels](#placement_levels)
+
+## etcd_mon_ttl
+
+- Type: seconds
+- Default: 30
+- Minimum: 10
+
+Monitor etcd lease refresh interval in seconds
+
+## etcd_mon_timeout
+
+- Type: milliseconds
+- Default: 1000
+
+etcd request timeout used by monitor
+
+## etcd_mon_retries
+
+- Type: integer
+- Default: 5
+
+Maximum number of attempts for one monitor etcd request
+
+## mon_change_timeout
+
+- Type: milliseconds
+- Default: 1000
+- Minimum: 100
+
+Optimistic retry interval for monitor etcd modification requests
+
+## mon_stats_timeout
+
+- Type: milliseconds
+- Default: 1000
+- Minimum: 100
+
+Interval for monitor to wait before updating aggregated statistics in
+etcd after receiving OSD statistics updates
+
+## osd_out_time
+
+- Type: seconds
+- Default: 600
+
+Time after which a failed OSD is removed from the data distribution.
+I.e. time which the monitor waits before attempting to restore data
+redundancy using other OSDs.
+
+## placement_levels
+
+- Type: json
+- Default: `{"host":100,"osd":101}`
+
+Levels for the placement tree. You can define arbitrary tree levels by
+defining them in this parameter. The configuration parameter value should
+contain a JSON object with level names as keys and integer priorities as
+values.  Smaller priority means higher level in tree. For example,
+"datacenter" should have smaller priority than "osd". "host" and "osd"
+levels are always predefined and can't be removed. If one of them is not
+present in the configuration, then it is defined with the default priority
+(100 for "host", 101 for "osd").

docs/config/monitor.ru.md

@@ -0,0 +1,76 @@
+[Read in English](monitor.en.md)
+
+# Параметры мониторов
+
+Данные параметры используются только мониторами Vitastor.
+
+- [etcd_mon_ttl](#etcd_mon_ttl)
+- [etcd_mon_timeout](#etcd_mon_timeout)
+- [etcd_mon_retries](#etcd_mon_retries)
+- [mon_change_timeout](#mon_change_timeout)
+- [mon_stats_timeout](#mon_stats_timeout)
+- [osd_out_time](#osd_out_time)
+- [placement_levels](#placement_levels)
+
+## etcd_mon_ttl
+
+- Тип: секунды
+- Значение по умолчанию: 30
+- Минимальное значение: 10
+
+Интервал обновления etcd резервации (lease) монитором
+
+## etcd_mon_timeout
+
+- Тип: миллисекунды
+- Значение по умолчанию: 1000
+
+Таймаут выполнения запросов к etcd от монитора
+
+## etcd_mon_retries
+
+- Тип: целое число
+- Значение по умолчанию: 5
+
+Максимальное число попыток выполнения запросов к etcd монитором
+
+## mon_change_timeout
+
+- Тип: миллисекунды
+- Значение по умолчанию: 1000
+- Минимальное значение: 100
+
+Время повтора при коллизиях при запросах модификации в etcd, производимых монитором
+
+## mon_stats_timeout
+
+- Тип: миллисекунды
+- Значение по умолчанию: 1000
+- Минимальное значение: 100
+
+Интервал, который монитор ожидает при изменении статистики по отдельным
+OSD перед обновлением агрегированной статистики в etcd
+
+## osd_out_time
+
+- Тип: секунды
+- Значение по умолчанию: 600
+
+Время, через которое отключенный OSD исключается из распределения данных.
+То есть, время, которое монитор ожидает перед попыткой переместить данные
+на другие OSD и таким образом восстановить избыточность хранения.
+
+## placement_levels
+
+- Тип: json
+- Значение по умолчанию: `{"host":100,"osd":101}`
+
+Определения уровней для дерева размещения OSD. Вы можете определять
+произвольные уровни, помещая их в данный параметр конфигурации. Значение
+параметра должно содержать JSON-объект, ключи которого будут являться
+названиями уровней, а значения - целочисленными приоритетами. Меньшие
+приоритеты соответствуют верхним уровням дерева. Например, уровень
+"датацентр" должен иметь меньший приоритет, чем "OSD". Уровни с названиями
+"host" и "osd" являются предопределёнными и не могут быть удалены. Если
+один из них отсутствует в конфигурации, он доопределяется с приоритетом по
+умолчанию (100 для уровня "host", 101 для "osd").

docs/config/network.en.md

@@ -0,0 +1,210 @@
+[Читать на русском](network.ru.md)
+
+# Network Protocol Parameters
+
+These parameters apply to clients and OSDs and affect network connection logic
+between clients, OSDs and etcd.
+
+- [tcp_header_buffer_size](#tcp_header_buffer_size)
+- [use_sync_send_recv](#use_sync_send_recv)
+- [use_rdma](#use_rdma)
+- [rdma_device](#rdma_device)
+- [rdma_port_num](#rdma_port_num)
+- [rdma_gid_index](#rdma_gid_index)
+- [rdma_mtu](#rdma_mtu)
+- [rdma_max_sge](#rdma_max_sge)
+- [rdma_max_msg](#rdma_max_msg)
+- [rdma_max_recv](#rdma_max_recv)
+- [peer_connect_interval](#peer_connect_interval)
+- [peer_connect_timeout](#peer_connect_timeout)
+- [osd_idle_timeout](#osd_idle_timeout)
+- [osd_ping_timeout](#osd_ping_timeout)
+- [up_wait_retry_interval](#up_wait_retry_interval)
+- [max_etcd_attempts](#max_etcd_attempts)
+- [etcd_quick_timeout](#etcd_quick_timeout)
+- [etcd_slow_timeout](#etcd_slow_timeout)
+- [etcd_keepalive_timeout](#etcd_keepalive_timeout)
+- [etcd_ws_keepalive_timeout](#etcd_ws_keepalive_timeout)
+
+## tcp_header_buffer_size
+
+- Type: integer
+- Default: 65536
+
+Size of the buffer used to read data using an additional copy. Vitastor
+packet headers are 128 bytes, payload is always at least 4 KB, so it is
+usually beneficial to try to read multiple packets at once even though
+it requires to copy the data an additional time. The rest of each packet
+is received without an additional copy. You can try to play with this
+parameter and see how it affects random iops and linear bandwidth if you
+want.
+
+## use_sync_send_recv
+
+- Type: boolean
+- Default: false
+
+If true, synchronous send/recv syscalls are used instead of io_uring for
+socket communication. Useless for OSDs because they require io_uring anyway,
+but may be required for clients with old kernel versions.
+
+## use_rdma
+
+- Type: boolean
+- Default: true
+
+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.
+
+## rdma_device
+
+- Type: string
+
+RDMA device name to use for Vitastor OSD communications (for example,
+"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.
+
+## rdma_port_num
+
+- Type: integer
+- Default: 1
+
+RDMA device port number to use. Only for devices that have more than 1 port.
+See `phys_port_cnt` in `ibv_devinfo -v` output to determine how many ports
+your device has.
+
+## rdma_gid_index
+
+- Type: integer
+- Default: 0
+
+Global address identifier index of the RDMA device to use. Different GID
+indexes may correspond to different protocols like RoCEv1, RoCEv2 and iWARP.
+Search for "GID" in `ibv_devinfo -v` output to determine which GID index
+you need.
+
+**IMPORTANT:** If you want to use RoCEv2 (as recommended) then the correct
+rdma_gid_index is usually 1 (IPv6) or 3 (IPv4).
+
+## rdma_mtu
+
+- Type: integer
+- Default: 4096
+
+RDMA Path MTU to use. Must be 1024, 2048 or 4096. There is usually no
+sense to change it from the default 4096.
+
+## rdma_max_sge
+
+- Type: integer
+- Default: 128
+
+Maximum number of scatter/gather entries to use for RDMA. OSDs negotiate
+the actual value when establishing connection anyway, so it's usually not
+required to change this parameter.
+
+## rdma_max_msg
+
+- Type: integer
+- Default: 1048576
+
+Maximum size of a single RDMA send or receive operation in bytes.
+
+## rdma_max_recv
+
+- Type: integer
+- Default: 8
+
+Maximum number of parallel RDMA receive operations. Note that this number
+of receive buffers `rdma_max_msg` in size are allocated for each client,
+so this setting actually affects memory usage. This is because RDMA receive
+operations are (sadly) still not zero-copy in Vitastor. It may be fixed in
+later versions.
+
+## peer_connect_interval
+
+- Type: seconds
+- Default: 5
+- Minimum: 1
+
+Interval before attempting to reconnect to an unavailable OSD.
+
+## peer_connect_timeout
+
+- Type: seconds
+- Default: 5
+- Minimum: 1
+
+Timeout for OSD connection attempts.
+
+## osd_idle_timeout
+
+- Type: seconds
+- Default: 5
+- Minimum: 1
+
+OSD connection inactivity time after which clients and other OSDs send
+keepalive requests to check state of the connection.
+
+## osd_ping_timeout
+
+- Type: seconds
+- Default: 5
+- Minimum: 1
+
+Maximum time to wait for OSD keepalive responses. If an OSD doesn't respond
+within this time, the connection to it is dropped and a reconnection attempt
+is scheduled.
+
+## up_wait_retry_interval
+
+- Type: milliseconds
+- Default: 500
+- Minimum: 50
+
+OSDs respond to clients with a special error code when they receive I/O
+requests for a PG that's not synchronized and started. This parameter sets
+the time for the clients to wait before re-attempting such I/O requests.
+
+## max_etcd_attempts
+
+- Type: integer
+- Default: 5
+
+Maximum number of attempts for etcd requests which can't be retried
+indefinitely.
+
+## etcd_quick_timeout
+
+- Type: milliseconds
+- Default: 1000
+
+Timeout for etcd requests which should complete quickly, like lease refresh.
+
+## etcd_slow_timeout
+
+- Type: milliseconds
+- Default: 5000
+
+Timeout for etcd requests which are allowed to wait for some time.
+
+## etcd_keepalive_timeout
+
+- Type: seconds
+- Default: max(30, etcd_report_interval*2)
+
+Timeout for etcd connection HTTP Keep-Alive. Should be higher than
+etcd_report_interval to guarantee that keepalive actually works.
+
+## etcd_ws_keepalive_timeout
+
+- Type: seconds
+- Default: 30
+
+etcd websocket ping interval required to keep the connection alive and
+detect disconnections quickly.

docs/config/network.ru.md

@@ -0,0 +1,220 @@
+[Read in English](network.en.md)
+
+# Параметры сетевого протокола
+
+Данные параметры используются клиентами и OSD и влияют на логику сетевого
+взаимодействия между клиентами, OSD, а также etcd.
+
+- [tcp_header_buffer_size](#tcp_header_buffer_size)
+- [use_sync_send_recv](#use_sync_send_recv)
+- [use_rdma](#use_rdma)
+- [rdma_device](#rdma_device)
+- [rdma_port_num](#rdma_port_num)
+- [rdma_gid_index](#rdma_gid_index)
+- [rdma_mtu](#rdma_mtu)
+- [rdma_max_sge](#rdma_max_sge)
+- [rdma_max_msg](#rdma_max_msg)
+- [rdma_max_recv](#rdma_max_recv)
+- [peer_connect_interval](#peer_connect_interval)
+- [peer_connect_timeout](#peer_connect_timeout)
+- [osd_idle_timeout](#osd_idle_timeout)
+- [osd_ping_timeout](#osd_ping_timeout)
+- [up_wait_retry_interval](#up_wait_retry_interval)
+- [max_etcd_attempts](#max_etcd_attempts)
+- [etcd_quick_timeout](#etcd_quick_timeout)
+- [etcd_slow_timeout](#etcd_slow_timeout)
+- [etcd_keepalive_timeout](#etcd_keepalive_timeout)
+- [etcd_ws_keepalive_timeout](#etcd_ws_keepalive_timeout)
+
+## tcp_header_buffer_size
+
+- Тип: целое число
+- Значение по умолчанию: 65536
+
+Размер буфера для чтения данных с дополнительным копированием. Пакеты
+Vitastor содержат 128-байтные заголовки, за которыми следуют данные размером
+от 4 КБ и для мелких операций ввода-вывода обычно выгодно за 1 вызов читать
+сразу несколько пакетов, даже не смотря на то, что это требует лишний раз
+скопировать данные. Часть каждого пакета за пределами значения данного
+параметра читается без дополнительного копирования. Вы можете попробовать
+поменять этот параметр и посмотреть, как он влияет на производительность
+случайного и линейного доступа.
+
+## use_sync_send_recv
+
+- Тип: булево (да/нет)
+- Значение по умолчанию: false
+
+Если установлено в истину, то вместо io_uring для передачи данных по сети
+будут использоваться обычные синхронные системные вызовы send/recv. Для OSD
+это бессмысленно, так как OSD в любом случае нуждается в io_uring, но, в
+принципе, это может применяться для клиентов со старыми версиями ядра.
+
+## use_rdma
+
+- Тип: булево (да/нет)
+- Значение по умолчанию: true
+
+Пытаться использовать 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.
+
+## rdma_device
+
+- Тип: строка
+
+Название RDMA-устройства для связи с Vitastor OSD (например, "rocep5s0f0").
+Имейте в виду, что поддержка RDMA в Vitastor требует функций устройства
+Implicit On-Demand Paging (Implicit ODP) и Scatter/Gather (SG). Например,
+адаптеры Mellanox ConnectX-3 и более старые не поддерживают Implicit ODP и
+потому не поддерживаются в Vitastor. Запустите `ibv_devinfo -v` от имени
+суперпользователя, чтобы посмотреть список доступных RDMA-устройств, их
+параметры и возможности.
+
+## rdma_port_num
+
+- Тип: целое число
+- Значение по умолчанию: 1
+
+Номер порта RDMA-устройства, который следует использовать. Имеет смысл
+только для устройств, у которых более 1 порта. Чтобы узнать, сколько портов
+у вашего адаптера, посмотрите `phys_port_cnt` в выводе команды
+`ibv_devinfo -v`.
+
+## rdma_gid_index
+
+- Тип: целое число
+- Значение по умолчанию: 0
+
+Номер глобального идентификатора адреса RDMA-устройства, который следует
+использовать. Разным gid_index могут соответствовать разные протоколы связи:
+RoCEv1, RoCEv2, iWARP. Чтобы понять, какой нужен вам - смотрите строчки со
+словом "GID" в выводе команды `ibv_devinfo -v`.
+
+**ВАЖНО:** Если вы хотите использовать RoCEv2 (как мы и рекомендуем), то
+правильный rdma_gid_index, как правило, 1 (IPv6) или 3 (IPv4).
+
+## rdma_mtu
+
+- Тип: целое число
+- Значение по умолчанию: 4096
+
+Максимальная единица передачи (Path MTU) для RDMA. Должно быть равно 1024,
+2048 или 4096. Обычно нет смысла менять значение по умолчанию, равное 4096.
+
+## rdma_max_sge
+
+- Тип: целое число
+- Значение по умолчанию: 128
+
+Максимальное число записей разделения/сборки (scatter/gather) для RDMA.
+OSD в любом случае согласовывают реальное значение при установке соединения,
+так что менять этот параметр обычно не нужно.
+
+## rdma_max_msg
+
+- Тип: целое число
+- Значение по умолчанию: 1048576
+
+Максимальный размер одной RDMA-операции отправки или приёма.
+
+## rdma_max_recv
+
+- Тип: целое число
+- Значение по умолчанию: 8
+
+Максимальное число параллельных RDMA-операций получения данных. Следует
+иметь в виду, что данное число буферов размером `rdma_max_msg` выделяется
+для каждого подключённого клиентского соединения, так что данная настройка
+влияет на потребление памяти. Это так потому, что RDMA-приём данных в
+Vitastor, увы, всё равно не является zero-copy, т.е. всё равно 1 раз
+копирует данные в памяти. Данная особенность, возможно, будет исправлена в
+более новых версиях Vitastor.
+
+## peer_connect_interval
+
+- Тип: секунды
+- Значение по умолчанию: 5
+- Минимальное значение: 1
+
+Время ожидания перед повторной попыткой соединиться с недоступным OSD.
+
+## peer_connect_timeout
+
+- Тип: секунды
+- Значение по умолчанию: 5
+- Минимальное значение: 1
+
+Максимальное время ожидания попытки соединения с OSD.
+
+## osd_idle_timeout
+
+- Тип: секунды
+- Значение по умолчанию: 5
+- Минимальное значение: 1
+
+Время неактивности соединения с OSD, после которого клиенты или другие OSD
+посылают запрос проверки состояния соединения.
+
+## osd_ping_timeout
+
+- Тип: секунды
+- Значение по умолчанию: 5
+- Минимальное значение: 1
+
+Максимальное время ожидания ответа на запрос проверки состояния соединения.
+Если OSD не отвечает за это время, соединение отключается и производится
+повторная попытка соединения.
+
+## up_wait_retry_interval
+
+- Тип: миллисекунды
+- Значение по умолчанию: 500
+- Минимальное значение: 50
+
+Когда OSD получают от клиентов запросы ввода-вывода, относящиеся к не
+поднятым на данный момент на них PG, либо к PG в процессе синхронизации,
+они отвечают клиентам специальным кодом ошибки, означающим, что клиент
+должен некоторое время подождать перед повторением запроса. Именно это время
+ожидания задаёт данный параметр.
+
+## max_etcd_attempts
+
+- Тип: целое число
+- Значение по умолчанию: 5
+
+Максимальное число попыток выполнения запросов к etcd для тех запросов,
+которые нельзя повторять бесконечно.
+
+## etcd_quick_timeout
+
+- Тип: миллисекунды
+- Значение по умолчанию: 1000
+
+Максимальное время выполнения запросов к etcd, которые должны завершаться
+быстро, таких, как обновление резервации (lease).
+
+## etcd_slow_timeout
+
+- Тип: миллисекунды
+- Значение по умолчанию: 5000
+
+Максимальное время выполнения запросов к etcd, для которых не обязательно
+гарантировать быстрое выполнение.
+
+## etcd_keepalive_timeout
+
+- Тип: секунды
+- Значение по умолчанию: max(30, etcd_report_interval*2)
+
+Таймаут для HTTP Keep-Alive в соединениях к etcd. Должен быть больше, чем
+etcd_report_interval, чтобы keepalive гарантированно работал.
+
+## etcd_ws_keepalive_timeout
+
+- Тип: секунды
+- Значение по умолчанию: 30
+
+Интервал проверки живости вебсокет-подключений к etcd.

docs/config/osd.en.md

@@ -0,0 +1,293 @@
+[Читать на русском](osd.ru.md)
+
+# Runtime OSD Parameters
+
+These parameters only apply to OSDs, are not fixed at the moment of OSD drive
+initialization and can be changed with an OSD restart.
+
+- [etcd_report_interval](#etcd_report_interval)
+- [run_primary](#run_primary)
+- [osd_network](#osd_network)
+- [bind_address](#bind_address)
+- [bind_port](#bind_port)
+- [autosync_interval](#autosync_interval)
+- [autosync_writes](#autosync_writes)
+- [recovery_queue_depth](#recovery_queue_depth)
+- [recovery_sync_batch](#recovery_sync_batch)
+- [readonly](#readonly)
+- [no_recovery](#no_recovery)
+- [no_rebalance](#no_rebalance)
+- [print_stats_interval](#print_stats_interval)
+- [slow_log_interval](#slow_log_interval)
+- [max_write_iodepth](#max_write_iodepth)
+- [min_flusher_count](#min_flusher_count)
+- [max_flusher_count](#max_flusher_count)
+- [inmemory_metadata](#inmemory_metadata)
+- [inmemory_journal](#inmemory_journal)
+- [journal_sector_buffer_count](#journal_sector_buffer_count)
+- [journal_no_same_sector_overwrites](#journal_no_same_sector_overwrites)
+- [throttle_small_writes](#throttle_small_writes)
+- [throttle_target_iops](#throttle_target_iops)
+- [throttle_target_mbs](#throttle_target_mbs)
+- [throttle_target_parallelism](#throttle_target_parallelism)
+- [throttle_threshold_us](#throttle_threshold_us)
+- [osd_memlock](#osd_memlock)
+
+## etcd_report_interval
+
+- Type: seconds
+- Default: 5
+
+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
+that every OSD always refreshes its lease in time.
+
+## run_primary
+
+- Type: boolean
+- Default: true
+
+Start primary OSD logic on this OSD. As of now, can be turned off only for
+debugging purposes. It's possible to implement additional feature for the
+monitor which may allow to separate primary and secondary OSDs, but it's
+unclear why anyone could need it, so it's not implemented.
+
+## osd_network
+
+- Type: string or array of strings
+
+Network mask of the network (IPv4 or IPv6) to use for OSDs. Note that
+although it's possible to specify multiple networks here, this does not
+mean that OSDs will create multiple listening sockets - they'll only
+pick the first matching address of an UP + RUNNING interface. Separate
+networks for cluster and client connections are also not implemented, but
+they are mostly useless anyway, so it's not a big deal.
+
+## bind_address
+
+- Type: string
+- Default: 0.0.0.0
+
+Instead of the network mask, you can also set OSD listen address explicitly
+using this parameter. May be useful if you want to start OSDs on interfaces
+that are not UP + RUNNING.
+
+## bind_port
+
+- Type: integer
+
+By default, OSDs pick random ports to use for incoming connections
+automatically. With this option you can set a specific port for a specific
+OSD by hand.
+
+## autosync_interval
+
+- Type: seconds
+- Default: 5
+
+Time interval at which automatic fsyncs/flushes are issued by each OSD when
+the immediate_commit mode if disabled. fsyncs are required because without
+them OSDs quickly fill their journals, become unable to clear them and
+stall. Also this option limits the amount of recent uncommitted changes
+which OSDs may lose in case of a power outage in case when clients don't
+issue fsyncs at all.
+
+## autosync_writes
+
+- Type: integer
+- Default: 128
+
+Same as autosync_interval, but sets the maximum number of uncommitted write
+operations before issuing an fsync operation internally.
+
+## recovery_queue_depth
+
+- Type: integer
+- Default: 4
+
+Maximum recovery operations per one primary OSD at any given moment of time.
+Currently it's the only parameter available to tune the speed or recovery
+and rebalancing, but it's planned to implement more.
+
+## recovery_sync_batch
+
+- Type: integer
+- Default: 16
+
+Maximum number of recovery operations before issuing an additional fsync.
+
+## readonly
+
+- Type: boolean
+- Default: false
+
+Read-only mode. If this is enabled, an OSD will never issue any writes to
+the underlying device. This may be useful for recovery purposes.
+
+## no_recovery
+
+- Type: boolean
+- Default: false
+
+Disable automatic background recovery of objects. Note that it doesn't
+affect implicit recovery of objects happening during writes - a write is
+always made to a full set of at least pg_minsize OSDs.
+
+## no_rebalance
+
+- Type: boolean
+- Default: false
+
+Disable background movement of data between different OSDs. Disabling it
+means that PGs in the `has_misplaced` state will be left in it indefinitely.
+
+## print_stats_interval
+
+- Type: seconds
+- Default: 3
+
+Time interval at which OSDs print simple human-readable operation
+statistics on stdout.
+
+## slow_log_interval
+
+- Type: seconds
+- Default: 10
+
+Time interval at which OSDs dump slow or stuck operations on stdout, if
+they're any. Also it's the time after which an operation is considered
+"slow".
+
+## max_write_iodepth
+
+- Type: integer
+- Default: 128
+
+Parallel client write operation limit per one OSD. Operations that exceed
+this limit are pushed to a temporary queue instead of being executed
+immediately.
+
+## min_flusher_count
+
+- Type: integer
+- Default: 1
+
+Flusher is a micro-thread that moves data from the journal to the data
+area of the device. Their number is auto-tuned between minimum and maximum.
+Minimum number is set by this parameter.
+
+## max_flusher_count
+
+- Type: integer
+- Default: 256
+
+Maximum number of journal flushers (see above min_flusher_count).
+
+## inmemory_metadata
+
+- Type: boolean
+- Default: true
+
+This parameter makes Vitastor always keep metadata area of the block device
+in memory. It's required for good performance because it allows to avoid
+additional read-modify-write cycles during metadata modifications. Metadata
+area size is currently roughly 224 MB per 1 TB of data. You can turn it off
+to reduce memory usage by this value, but it will hurt performance. This
+restriction is likely to be removed in the future along with the upgrade
+of the metadata storage scheme.
+
+## inmemory_journal
+
+- Type: boolean
+- Default: true
+
+This parameter make Vitastor always keep journal area of the block
+device in memory. Turning it off will, again, reduce memory usage, but
+hurt performance because flusher coroutines will have to read data from
+the disk back before copying it into the main area. The memory usage benefit
+is typically very small because it's sufficient to have 16-32 MB journal
+for SSD OSDs. However, in theory it's possible that you'll want to turn it
+off for hybrid (HDD+SSD) OSDs with large journals on quick devices.
+
+## journal_sector_buffer_count
+
+- Type: integer
+- Default: 32
+
+Maximum number of buffers that can be used for writing journal metadata
+blocks. The only situation when you should increase it to a larger value
+is when you enable journal_no_same_sector_overwrites. In this case set
+it to, for example, 1024.
+
+## journal_no_same_sector_overwrites
+
+- Type: boolean
+- Default: false
+
+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 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.
+
+Most (99%) other SSDs don't need this option.
+
+## throttle_small_writes
+
+- Type: boolean
+- Default: false
+
+Enable soft throttling of small journaled writes. Useful for hybrid OSDs
+with fast journal/metadata devices and slow data devices. The idea is that
+small writes complete very quickly because they're first written to the
+journal device, but moving them to the main device is slow. So if an OSD
+allows clients to issue a lot of small writes it will perform very good
+for several seconds and then the journal will fill up and the performance
+will drop to almost zero. Throttling is meant to prevent this problem by
+artifically slowing quick writes down based on the amount of free space in
+the journal. When throttling is used, the performance of small writes will
+decrease smoothly instead of abrupt drop at the moment when the journal
+fills up.
+
+## throttle_target_iops
+
+- Type: integer
+- Default: 100
+
+Target maximum number of throttled operations per second under the condition
+of full journal. Set it to approximate random write iops of your data devices
+(HDDs).
+
+## throttle_target_mbs
+
+- Type: integer
+- Default: 100
+
+Target maximum bandwidth in MB/s of throttled operations per second under
+the condition of full journal. Set it to approximate linear write
+performance of your data devices (HDDs).
+
+## throttle_target_parallelism
+
+- Type: integer
+- Default: 1
+
+Target maximum parallelism of throttled operations under the condition of
+full journal. Set it to approximate internal parallelism of your data
+devices (1 for HDDs, 4-8 for SSDs).
+
+## throttle_threshold_us
+
+- Type: microseconds
+- Default: 50
+
+Minimal computed delay to be applied to throttled operations. Usually
+doesn't need to be changed.
+
+## osd_memlock
+
+- Type: boolean
+- Default: false
+
+Lock all OSD memory to prevent it from being unloaded into swap with mlockall(). Requires sufficient ulimit -l (max locked memory).

docs/config/osd.ru.md

@@ -0,0 +1,306 @@
+[Read in English](osd.en.md)
+
+# Изменяемые параметры OSD
+
+Данные параметры используются только OSD, но, в отличие от дисковых параметров,
+не фиксируются в момент инициализации дисков OSD и могут быть изменены в любой
+момент с перезапуском OSD.
+
+- [etcd_report_interval](#etcd_report_interval)
+- [run_primary](#run_primary)
+- [osd_network](#osd_network)
+- [bind_address](#bind_address)
+- [bind_port](#bind_port)
+- [autosync_interval](#autosync_interval)
+- [autosync_writes](#autosync_writes)
+- [recovery_queue_depth](#recovery_queue_depth)
+- [recovery_sync_batch](#recovery_sync_batch)
+- [readonly](#readonly)
+- [no_recovery](#no_recovery)
+- [no_rebalance](#no_rebalance)
+- [print_stats_interval](#print_stats_interval)
+- [slow_log_interval](#slow_log_interval)
+- [max_write_iodepth](#max_write_iodepth)
+- [min_flusher_count](#min_flusher_count)
+- [max_flusher_count](#max_flusher_count)
+- [inmemory_metadata](#inmemory_metadata)
+- [inmemory_journal](#inmemory_journal)
+- [journal_sector_buffer_count](#journal_sector_buffer_count)
+- [journal_no_same_sector_overwrites](#journal_no_same_sector_overwrites)
+- [throttle_small_writes](#throttle_small_writes)
+- [throttle_target_iops](#throttle_target_iops)
+- [throttle_target_mbs](#throttle_target_mbs)
+- [throttle_target_parallelism](#throttle_target_parallelism)
+- [throttle_threshold_us](#throttle_threshold_us)
+- [osd_memlock](#osd_memlock)
+
+## etcd_report_interval
+
+- Тип: секунды
+- Значение по умолчанию: 5
+
+Интервал, с которым OSD обновляет своё состояние в etcd. Значение параметра
+влияет на время резервации (lease) OSD и поэтому на скорость переключения
+при падении OSD. Время lease равняется значению этого параметра плюс
+max_etcd_attempts * etcd_quick_timeout.
+
+## run_primary
+
+- Тип: булево (да/нет)
+- Значение по умолчанию: true
+
+Запускать логику первичного OSD на данном OSD. На данный момент отключать
+эту опцию может иметь смысл только в целях отладки. В теории, можно
+реализовать дополнительный режим для монитора, который позволит отделять
+первичные OSD от вторичных, но пока не понятно, зачем это может кому-то
+понадобиться, поэтому это не реализовано.
+
+## osd_network
+
+- Тип: строка или массив строк
+
+Маска подсети (IPv4 или IPv6) для использования для соединений с OSD.
+Имейте в виду, что хотя сейчас и можно передать в этот параметр несколько
+подсетей, это не означает, что OSD будут создавать несколько слушающих
+сокетов - они лишь будут выбирать адрес первого поднятого (состояние UP +
+RUNNING), подходящий под заданную маску. Также не реализовано разделение
+кластерной и публичной сетей OSD. Правда, от него обычно всё равно довольно
+мало толку, так что особенной проблемы в этом нет.
+
+## bind_address
+
+- Тип: строка
+- Значение по умолчанию: 0.0.0.0
+
+Этим параметром можно явным образом задать адрес, на котором будет ожидать
+соединений OSD (вместо использования маски подсети). Может быть полезно,
+например, чтобы запускать OSD на неподнятых интерфейсах (не UP + RUNNING).
+
+## bind_port
+
+- Тип: целое число
+
+По умолчанию OSD сами выбирают случайные порты для входящих подключений.
+С помощью данной опции вы можете задать порт для отдельного OSD вручную.
+
+## autosync_interval
+
+- Тип: секунды
+- Значение по умолчанию: 5
+
+Временной интервал отправки автоматических fsync-ов (операций очистки кэша)
+каждым OSD для случая, когда режим immediate_commit отключён. fsync-и нужны
+OSD, чтобы успевать очищать журнал - без них OSD быстро заполняют журналы и
+перестают обрабатывать операции записи. Также эта опция ограничивает объём
+недавних незафиксированных изменений, которые OSD могут терять при
+отключении питания, если клиенты вообще не отправляют fsync.
+
+## autosync_writes
+
+- Тип: целое число
+- Значение по умолчанию: 128
+
+Аналогично autosync_interval, но задаёт не временной интервал, а
+максимальное количество незафиксированных операций записи перед
+принудительной отправкой fsync-а.
+
+## recovery_queue_depth
+
+- Тип: целое число
+- Значение по умолчанию: 4
+
+Максимальное число операций восстановления на одном первичном OSD в любой
+момент времени. На данный момент единственный параметр, который можно менять
+для ускорения или замедления восстановления и перебалансировки данных, но
+в планах реализация других параметров.
+
+## recovery_sync_batch
+
+- Тип: целое число
+- Значение по умолчанию: 16
+
+Максимальное число операций восстановления перед дополнительным fsync.
+
+## readonly
+
+- Тип: булево (да/нет)
+- Значение по умолчанию: false
+
+Режим "только чтение". Если включить этот режим, OSD не будет писать ничего
+на диск. Может быть полезно в целях восстановления.
+
+## no_recovery