Describe OSD placement tree and reweights

Return results and errors in a variable instead of just printing them,
separate vitastor-cli main() from cli_tool_t, move positional argument
parsing to CLI main from command implementations.

CMakeLists.txt

@@ -2,6 +2,6 @@ cmake_minimum_required(VERSION 2.8)
 
 project(vitastor)
 
-set(VERSION "0.6.10")
+set(VERSION "0.6.17")
 
 add_subdirectory(src)

README-ru.md

@@ -4,628 +4,68 @@
 
 ## Идея
 
-Я всего лишь хочу сделать качественную блочную SDS!
+Вернём былую скорость кластерному блочному хранилищу!
 
-Vitastor - распределённая блочная SDS, прямой аналог Ceph RBD и внутренних СХД популярных
-облачных провайдеров. Однако, в отличие от них, Vitastor быстрый и при этом простой.
-Только пока маленький :-).
+Vitastor - распределённая блочная SDS (программная СХД), прямой аналог Ceph RBD и
+внутренних СХД популярных облачных провайдеров. Однако, в отличие от них, Vitastor
+быстрый и при этом простой. Только пока маленький :-).
 
-Архитектурная схожесть с Ceph означает заложенную на уровне алгоритмов записи строгую консистентность,
+Vitastor архитектурно похож на Ceph, что означает атомарность и строгую консистентность,
 репликацию через первичный OSD, симметричную кластеризацию без единой точки отказа
 и автоматическое распределение данных по любому числу дисков любого размера с настраиваемыми схемами
 избыточности - репликацией или с произвольными кодами коррекции ошибок.
 
-## Возможности
-
-Vitastor на данный момент находится в статусе предварительного выпуска, расширенные
-возможности пока отсутствуют, а в будущих версиях вероятны "ломающие" изменения.
-
-Однако следующее уже реализовано:
-
-- Базовая часть - надёжное кластерное блочное хранилище без единой точки отказа
-- Производительность ;-D
-- Несколько схем отказоустойчивости: репликация, XOR n+1 (1 диск чётности), коды коррекции ошибок
-  Рида-Соломона на основе библиотеки jerasure с любым числом дисков данных и чётности в группе
-- Конфигурация через простые человекочитаемые JSON-структуры в etcd
-- Автоматическое распределение данных по OSD, с поддержкой:
-  - Математической оптимизации для лучшей равномерности распределения и минимизации перемещений данных
-  - Нескольких пулов с разными схемами избыточности
-  - Дерева распределения, выбора OSD по тегам / классам устройств (только SSD, только HDD) и по поддереву
-  - Настраиваемых доменов отказа (диск/сервер/стойка и т.п.)
-- Восстановление деградированных блоков
-- Ребаланс, то есть перемещение данных между OSD (дисками)
-- Поддержка "ленивого" fsync (fsync не на каждую операцию)
-- Сбор статистики ввода/вывода в etcd
-- Клиентская библиотека режима пользователя для ввода/вывода
-- Драйвер диска для QEMU (собирается вне дерева исходников QEMU)
-- Драйвер диска для утилиты тестирования производительности fio (также собирается вне дерева исходников fio)
-- NBD-прокси для монтирования образов ядром ("блочное устройство в режиме пользователя")
-- Утилита для удаления образов/инодов (vitastor-cli rm-data)
-- Пакеты для Debian и CentOS
-- Статистика операций ввода/вывода и занятого места в разрезе инодов
-- Именование инодов через хранение их метаданных в etcd
-- Снапшоты и copy-on-write клоны
-- Сглаживание производительности случайной записи в SSD+HDD конфигурациях
-- Поддержка RDMA/RoCEv2 через libibverbs
-- CSI-плагин для Kubernetes
-- Базовая поддержка OpenStack: драйвер Cinder, патчи для Nova и libvirt
-- Слияние снапшотов (vitastor-cli {snap-rm,flatten,merge})
-- Консольный интерфейс для управления образами (vitastor-cli {ls,create,modify})
-- Плагин для Proxmox
-
-## Планы развития
-
-- Поддержка удаления снапшотов (слияния слоёв)
-- Более корректные скрипты разметки дисков и автоматического запуска OSD
-- Другие инструменты администрирования
-- Плагины для OpenNebula и других облачных систем
-- iSCSI-прокси
-- Более быстрое переключение при отказах
-- Фоновая проверка целостности без контрольных сумм (сверка реплик)
-- Контрольные суммы
-- Поддержка SSD-кэширования (tiered storage)
-- Поддержка NVDIMM
-- Web-интерфейс
-- Возможно, сжатие
-- Возможно, поддержка кэширования данных через системный page cache
-
-## Архитектура
-
-Так же, как и в Ceph, в Vitastor:
-
-- Есть пулы (pools), PG, OSD, мониторы, домены отказа, дерево распределения (аналог crush-дерева).
-- Образы делятся на блоки фиксированного размера (объекты), и эти объекты распределяются по OSD.
-- У OSD есть журнал и метаданные и они тоже могут размещаться на отдельных быстрых дисках.
-- Все операции записи тоже транзакционны. В Vitastor, правда, есть режим отложенного/ленивого fsync
-  (коммита), в котором fsync не вызывается на каждую операцию записи, что делает его более
-  пригодным для использования на "плохих" (десктопных) SSD. Однако все операции записи
-  в любом случае атомарны.
-- Клиентская библиотека тоже старается ждать восстановления после любого отказа кластера, то есть,
-  вы тоже можете перезагрузить хоть весь кластер разом, и клиенты только на время зависнут,
-  но не отключатся.
-
-Некоторые базовые термины для тех, кто не знаком с Ceph:
-
-- OSD (Object Storage Daemon) - процесс, который хранит данные на одном диске и обрабатывает
-  запросы чтения/записи от клиентов.
-- Пул (Pool) - контейнер для данных, имеющих одну и ту же схему избыточности и правила распределения по OSD.
-- PG (Placement Group) - группа объектов, хранимых на одном и том же наборе реплик (OSD).
-  Несколько PG могут храниться на одном и том же наборе реплик, но объекты одной PG
-  в норме не хранятся на разных наборах OSD.
-- Монитор - демон, хранящий состояние кластера.
-- Домен отказа (Failure Domain) - группа OSD, которым вы разрешаете "упасть" всем вместе.
-  Иными словами, это группа OSD, в которые СХД не помещает разные копии одного и того же
-  блока данных. Например, если домен отказа - сервер, то на двух дисках одного сервера
-  никогда не окажется 2 и более копий одного и того же блока данных, а значит, даже
-  если в этом сервере откажут все диски, это будет равносильно потере только 1 копии
-  любого блока данных.
-- Дерево распределения (Placement Tree / CRUSH Tree) - иерархическая группировка OSD
-  в узлы, которые далее можно использовать как домены отказа. То есть, диск (OSD) входит в
-  сервер, сервер входит в стойку, стойка входит в ряд, ряд в датацентр и т.п.
-
-Чем Vitastor отличается от Ceph:
-
-- Vitastor в первую очередь сфокусирован на SSD. Также Vitastor, вероятно, должен неплохо работать
-  с комбинацией SSD и HDD через bcache, а в будущем, возможно, будут добавлены и нативные способы
-  оптимизации под SSD+HDD. Однако хранилище на основе одних лишь жёстких дисков, вообще без SSD,
-  не в приоритете, поэтому оптимизации под этот кейс могут вообще не состояться.
-- OSD Vitastor однопоточный и всегда таким останется, так как это самый оптимальный способ работы.
-  Если вам не хватает 1 ядра на 1 диск, просто делите диск на разделы и запускайте на нём несколько OSD.
-  Но, скорее всего, вам хватит и 1 ядра - Vitastor не так прожорлив к ресурсам CPU, как Ceph.
-- Журнал и метаданные всегда размещаются в памяти, благодаря чему никогда не тратится лишнее время
-  на чтение метаданных с диска. Размер метаданных линейно зависит от размера диска и блока данных,
-  который задаётся в конфигурации кластера и по умолчанию составляет 128 КБ. С блоком 128 КБ метаданные
-  занимают примерно 512 МБ памяти на 1 ТБ дискового пространства (и это всё равно меньше, чем нужно Ceph-у).
-  Журнал вообще не должен быть большим, например, тесты производительности в данном документе проводились
-  с журналом размером всего 16 МБ. Большой журнал, вероятно, даже вреден, т.к. "грязные" записи (записи,
-  не сброшенные из журнала) тоже занимают память и могут немного замедлять работу.
-- В Vitastor нет внутреннего copy-on-write. Я считаю, что реализация CoW-хранилища гораздо сложнее,
-  поэтому сложнее добиться устойчиво хороших результатов. Возможно, в один прекрасный день
-  я придумаю красивый алгоритм для CoW-хранилища, но пока нет - внутреннего CoW в Vitastor не будет.
-  Всё это не относится к "внешнему" CoW (снапшотам и клонам).
-- Базовый слой Vitastor - простое блочное хранилище с блоками фиксированного размера, а не сложное
-  объектное хранилище с расширенными возможностями, как в Ceph (RADOS).
-- В Vitastor есть режим "ленивых fsync", в котором OSD группирует запросы записи перед сбросом их
-  на диск, что позволяет получить лучшую производительность с дешёвыми настольными SSD без конденсаторов
-  ("Advanced Power Loss Protection" / "Capacitor-Based Power Loss Protection").
-  Тем не менее, такой режим всё равно медленнее использования нормальных серверных SSD и мгновенного
-  fsync, так как приводит к дополнительным операциям передачи данных по сети, поэтому рекомендуется
-  всё-таки использовать хорошие серверные диски, тем более, стоят они почти так же, как десктопные.
-- PG эфемерны. Это означает, что они не хранятся на дисках и существуют только в памяти работающих OSD.
-- Процессы восстановления оперируют отдельными объектами, а не целыми PG.
-- PGLOG-ов нет.
-- "Мониторы" не хранят данные. Конфигурация и состояние кластера хранятся в etcd в простых человекочитаемых
-  JSON-структурах. Мониторы Vitastor только следят за состоянием кластера и управляют перемещением данных.
-  В этом смысле монитор Vitastor не является критичным компонентом системы и больше похож на Ceph-овский
-  менеджер (MGR). Монитор Vitastor написан на node.js.
-- Распределение PG не основано на консистентных хешах. Вместо этого все маппинги PG хранятся прямо в etcd
-  (ибо нет никакой проблемы сохранить несколько сотен-тысяч записей в памяти, а не считать каждый раз хеши).
-  Перераспределение PG по OSD выполняется через математическую оптимизацию,
-  а конкретно, сведение задачи к ЛП (задаче линейного программирования) и решение оной с помощью утилиты
-  lp_solve. Такой подход позволяет обычно выравнивать распределение места почти идеально - равномерность
-  обычно составляет 96-99%, в отличие от Ceph, где на голом CRUSH-е без балансировщика обычно выходит 80-90%.
-  Также это позволяет минимизировать объём перемещения данных и случайность связей между OSD, а также менять
-  распределение вручную, не боясь сломать логику перебалансировки. В таком подходе есть и потенциальный
-  недостаток - есть предположение, что в очень большом кластере он может сломаться - однако вплоть до
-  нескольких сотен OSD подход точно работает нормально. Ну и, собственно, при необходимости легко
-  реализовать и консистентные хеши.
-- Отдельный слой, подобный слою "CRUSH-правил", отсутствует. Вы настраиваете схемы отказоустойчивости,
-  домены отказа и правила выбора OSD напрямую в конфигурации пулов.
-
-## Понимание сути производительности систем хранения
-
-Вкратце: для быстрой хранилки задержки важнее, чем пиковые iops-ы.
-
-Лучшая возможная задержка достигается при тестировании в 1 поток с глубиной очереди 1,
-что приблизительно означает минимально нагруженное состояние кластера. В данном случае
-IOPS = 1/задержка. Ни числом серверов, ни дисков, ни серверных процессов/потоков
-задержка не масштабируется... Она зависит только от того, насколько быстро один
-серверный процесс (и клиент) обрабатывают одну операцию.
-
-Почему задержки важны? Потому, что некоторые приложения *не могут* использовать глубину
-очереди больше 1, ибо их задача не параллелизуется. Важный пример - это все СУБД
-с поддержкой консистентности (ACID), потому что все они обеспечивают её через
-журналирование, а журналы пишутся последовательно и с fsync() после каждой операции.
-
-fsync, кстати - это ещё одна очень важная вещь, про которую почти всегда забывают в тестах.
-Смысл в том, что все современные диски имеют кэши/буферы записи и не гарантируют, что
-данные реально физически записываются на носитель до того, как вы делаете fsync(),
-который транслируется в команду сброса кэша операционной системой.
-
-Дешёвые SSD для настольных ПК и ноутбуков очень быстрые без fsync - NVMe диски, например,
-могут обработать порядка 80000 операций записи в секунду с глубиной очереди 1 без fsync.
-Однако с fsync, когда они реально вынуждены писать каждый блок данных во флеш-память,
-они выжимают лишь 1000-2000 операций записи в секунду (число практически постоянное
-для всех моделей SSD).
-
-Серверные SSD часто имеют суперконденсаторы, работающие как встроенный источник
-бесперебойного питания и дающие дискам успеть сбросить их DRAM-кэш в постоянную
-флеш-память при отключении питания. Благодаря этому диски с чистой совестью
-*игнорируют fsync*, так как точно знают, что данные из кэша доедут до постоянной
-памяти.
-
-Все наиболее известные программные СХД, например, Ceph и внутренние СХД, используемые
-такими облачными провайдерами, как Amazon, Google, Яндекс, медленные в смысле задержки.
-В лучшем случае они дают задержки от 0.3мс на чтение и 0.6мс на запись 4 КБ блоками
-даже при условии использования наилучшего возможного железа.
-
-И это в эпоху SSD, когда вы можете пойти на рынок и купить там SSD, задержка которого
-на чтение будет 0.1мс, а на запись - 0.04мс, за 100$ или даже дешевле.
-
-Когда мне нужно быстро протестировать производительность дисковой подсистемы, я
-использую следующие 6 команд, с небольшими вариациями:
-
-- Линейная запись:
-  `fio -ioengine=libaio -direct=1 -invalidate=1 -name=test -bs=4M -iodepth=32 -rw=write -runtime=60 -filename=/dev/sdX`
-- Линейное чтение:
-  `fio -ioengine=libaio -direct=1 -invalidate=1 -name=test -bs=4M -iodepth=32 -rw=read -runtime=60 -filename=/dev/sdX`
-- Запись в 1 поток (T1Q1):
-  `fio -ioengine=libaio -direct=1 -invalidate=1 -name=test -bs=4k -iodepth=1 -fsync=1 -rw=randwrite -runtime=60 -filename=/dev/sdX`
-- Чтение в 1 поток (T1Q1):
-  `fio -ioengine=libaio -direct=1 -invalidate=1 -name=test -bs=4k -iodepth=1 -rw=randread -runtime=60 -filename=/dev/sdX`
-- Параллельная запись (numjobs используется, когда 1 ядро CPU не может насытить диск):
-  `fio -ioengine=libaio -direct=1 -invalidate=1 -name=test -bs=4k -iodepth=128 [-numjobs=4 -group_reporting] -rw=randwrite -runtime=60 -filename=/dev/sdX`
-- Параллельное чтение (numjobs - аналогично):
-  `fio -ioengine=libaio -direct=1 -invalidate=1 -name=test -bs=4k -iodepth=128 [-numjobs=4 -group_reporting] -rw=randread -runtime=60 -filename=/dev/sdX`
-
-## Теоретическая максимальная производительность Vitastor
-
-При использовании репликации:
-- Задержка чтения в 1 поток (T1Q1): 1 сетевой RTT + 1 чтение с диска.
-- Запись+fsync в 1 поток:
-  - С мгновенным сбросом: 2 RTT + 1 запись.
-  - С отложенным ("ленивым") сбросом: 4 RTT + 1 запись + 1 fsync.
-- Параллельное чтение: сумма IOPS всех дисков либо производительность сети, если в сеть упрётся раньше.
-- Параллельная запись: сумма IOPS всех дисков / число реплик / WA либо производительность сети, если в сеть упрётся раньше.
-
-При использовании кодов коррекции ошибок (EC):
-- Задержка чтения в 1 поток (T1Q1): 1.5 RTT + 1 чтение.
-- Запись+fsync в 1 поток:
-  - С мгновенным сбросом: 3.5 RTT + 1 чтение + 2 записи.
-  - С отложенным ("ленивым") сбросом: 5.5 RTT + 1 чтение + 2 записи + 2 fsync.
-- Под 0.5 на самом деле подразумевается (k-1)/k, где k - число дисков данных,
-  что означает, что дополнительное обращение по сети не нужно, когда операция
-  чтения обслуживается локально.
-- Параллельное чтение: сумма IOPS всех дисков либо производительность сети, если в сеть упрётся раньше.
-- Параллельная запись: сумма IOPS всех дисков / общее число дисков данных и чётности / WA либо производительность сети, если в сеть упрётся раньше.
-  Примечание: IOPS дисков в данном случае надо брать в смешанном режиме чтения/записи в пропорции, аналогичной формулам выше.
-
-WA (мультипликатор записи) для 4 КБ блоков в Vitastor обычно составляет 3-5:
-1. Запись метаданных в журнал
-2. Запись блока данных в журнал
-3. Запись метаданных в БД
-4. Ещё одна запись метаданных в журнал при использовании EC
-5. Запись блока данных на диск данных
-
-Если вы найдёте SSD, хорошо работающий с 512-байтными блоками данных (Optane?),
-то 1, 3 и 4 можно снизить до 512 байт (1/8 от размера данных) и получить WA всего 2.375.
-
-Кроме того, WA снижается при использовании отложенного/ленивого сброса при параллельной
-нагрузке, т.к. блоки журнала записываются на диск только когда они заполняются или явным
-образом запрашивается fsync.
-
-## Пример сравнения с Ceph
-
-Железо - 4 сервера, в каждом:
-- 6x SATA SSD Intel D3-4510 3.84 TB
-- 2x Xeon Gold 6242 (16 cores @ 2.8 GHz)
-- 384 GB RAM
-- 1x 25 GbE сетевая карта (Mellanox ConnectX-4 LX), подключённая к свитчу Juniper QFX5200
-
-Экономия энергии CPU отключена. В тестах и Vitastor, и Ceph развёрнуто по 2 OSD на 1 SSD.
-
-Все результаты ниже относятся к случайной нагрузке 4 КБ блоками (если явно не указано обратное).
-
-Производительность голых дисков:
-- T1Q1 запись ~27000 iops (задержка ~0.037ms)
-- T1Q1 чтение ~9800 iops (задержка ~0.101ms)
-- T1Q32 запись ~60000 iops
-- T1Q32 чтение ~81700 iops
-
-Ceph 15.2.4 (Bluestore):
-- T1Q1 запись ~1000 iops (задержка ~1ms)
-- T1Q1 чтение ~1750 iops (задержка ~0.57ms)
-- T8Q64 запись ~100000 iops, потребление CPU процессами OSD около 40 ядер на каждом сервере
-- T8Q64 чтение ~480000 iops, потребление CPU процессами OSD около 40 ядер на каждом сервере
-
-Тесты в 8 потоков проводились на 8 400GB RBD образах со всех хостов (с каждого хоста запускалось 2 процесса fio).
-Это нужно потому, что в Ceph несколько RBD-клиентов, пишущих в 1 образ, очень сильно замедляются.
-
-Настройки RocksDB и Bluestore в Ceph не менялись, единственным изменением было отключение cephx_sign_messages.
-
-На самом деле, результаты теста не такие уж и плохие для Ceph (могло быть хуже).
-Собственно говоря, эти серверы как раз хорошо сбалансированы для Ceph - 6 SATA SSD как раз
-утилизируют 25-гигабитную сеть, а без 2 мощных процессоров Ceph-у бы не хватило ядер,
-чтобы выдать пристойный результат. Собственно, что и показывает жор 40 ядер в процессе
-параллельного теста.
-
-Vitastor:
-- T1Q1 запись: 7087 iops (задержка 0.14ms)
-- T1Q1 чтение: 6838 iops (задержка 0.145ms)
-- T2Q64 запись: 162000 iops, потребление CPU - 3 ядра на каждом сервере
-- T8Q64 чтение: 895000 iops, потребление CPU - 4 ядра на каждом сервере
-- Линейная запись (4M T1Q32): 2800 МБ/с
-- Линейное чтение (4M T1Q32): 1500 МБ/с
-
-Тест на чтение в 8 потоков проводился на 1 большом образе (3.2 ТБ) со всех хостов (опять же, по 2 fio с каждого).
-В Vitastor никакой разницы между 1 образом и 8-ю нет. Естественно, примерно 1/4 запросов чтения
-в такой конфигурации, как и в тестах Ceph выше, обслуживалась с локальной машины. Если проводить
-тест так, чтобы все операции всегда обращались к первичным OSD по сети - тест сильнее упирался
-в сеть и результат составлял примерно 689000 iops.
-
-Настройки Vitastor: `--disable_data_fsync true --immediate_commit all --flusher_count 8
-  --disk_alignment 4096 --journal_block_size 4096 --meta_block_size 4096
-  --journal_no_same_sector_overwrites true --journal_sector_buffer_count 1024
-  --journal_size 16777216`.
-
-### EC/XOR 2+1
-
-Vitastor:
-- T1Q1 запись: 2808 iops (задержка ~0.355ms)
-- T1Q1 чтение: 6190 iops (задержка ~0.16ms)
-- T2Q64 запись: 85500 iops, потребление CPU - 3.4 ядра на каждом сервере
-- T8Q64 чтение: 812000 iops, потребление CPU - 4.7 ядра на каждом сервере
-- Линейная запись (4M T1Q32): 3200 МБ/с
-- Линейное чтение (4M T1Q32): 1800 МБ/с
-
-Ceph:
-- T1Q1 запись: 730 iops (задержка ~1.37ms latency)
-- T1Q1 чтение: 1500 iops с холодным кэшем метаданных (задержка ~0.66ms), 2300 iops через 2 минуты прогрева (задержка ~0.435ms)
-- T4Q128 запись (4 RBD images): 45300 iops, потребление CPU - 30 ядер на каждом сервере
-- T8Q64 чтение (4 RBD images): 278600 iops, потребление CPU - 40 ядер на каждом сервере
-- Линейная запись (4M T1Q32): 1950 МБ/с в пустой образ, 2500 МБ/с в заполненный образ
-- Линейное чтение (4M T1Q32): 2400 МБ/с
-
-### NBD
-
-NBD расшифровывается как "сетевое блочное устройство", но на самом деле оно также
-работает просто как аналог FUSE для блочных устройств, то есть, представляет собой
-"блочное устройство в пространстве пользователя".
-
-NBD - на данный момент единственный способ монтировать Vitastor ядром Linux.
-NBD немного снижает производительность, так как приводит к дополнительным копированиям
-данных между ядром и пространством пользователя. Тем не менее, способ достаточно оптимален,
-а производительность случайного доступа вообще затрагивается слабо.
-
-Vitastor с однопоточной NBD прокси на том же стенде:
-- T1Q1 запись: 6000 iops (задержка 0.166ms)
-- T1Q1 чтение: 5518 iops (задержка 0.18ms)
-- T1Q128 запись: 94400 iops
-- T1Q128 чтение: 103000 iops
-- Линейная запись (4M T1Q128): 1266 МБ/с (в сравнении с 2800 МБ/с через fio)
-- Линейное чтение (4M T1Q128): 975 МБ/с (в сравнении с 1500 МБ/с через fio)
-
-## Установка
-
-### Debian
-
-- Добавьте ключ репозитория Vitastor:
-  `wget -q -O - https://vitastor.io/debian/pubkey | sudo apt-key add -`
-- Добавьте репозиторий Vitastor в /etc/apt/sources.list:
-  - Debian 11 (Bullseye/Sid): `deb https://vitastor.io/debian bullseye main`
-  - Debian 10 (Buster): `deb https://vitastor.io/debian buster main`
-- Для Debian 10 (Buster) также включите репозиторий backports:
-  `deb http://deb.debian.org/debian buster-backports main`
-- Установите пакеты: `apt update; apt install vitastor lp-solve etcd linux-image-amd64 qemu`
-
-### CentOS
-
-- Добавьте в систему репозиторий Vitastor:
-  - CentOS 7: `yum install https://vitastor.io/rpms/centos/7/vitastor-release-1.0-1.el7.noarch.rpm`
-  - CentOS 8: `dnf install https://vitastor.io/rpms/centos/8/vitastor-release-1.0-1.el8.noarch.rpm`
-- Включите EPEL: `yum/dnf install epel-release`
-- Включите дополнительные репозитории CentOS:
-  - CentOS 7: `yum install centos-release-scl`
-  - CentOS 8: `dnf install centos-release-advanced-virtualization`
-- Включите elrepo-kernel:
-  - CentOS 7: `yum install https://www.elrepo.org/elrepo-release-7.el7.elrepo.noarch.rpm`
-  - CentOS 8: `dnf install https://www.elrepo.org/elrepo-release-8.el8.elrepo.noarch.rpm`
-- Установите пакеты: `yum/dnf install vitastor lpsolve etcd kernel-ml qemu-kvm`
-
-### Установка из исходников
-
-- Установите ядро 5.4 или более новое, для поддержки io_uring. Желательно 5.8 или даже новее,
-  так как в 5.4 есть как минимум 1 известный баг, ведущий к зависанию с io_uring и контроллером HP SmartArray.
-- Установите liburing 0.4 или более новый и его заголовки.
-- Установите lp_solve.
-- Установите etcd, версии не ниже 3.4.15. Более ранние версии работать не будут из-за различных багов,
-  например [#12402](https://github.com/etcd-io/etcd/pull/12402). Также вы можете взять версию 3.4.13 с
-  этим конкретным исправлением из ветки release-3.4 репозитория https://github.com/vitalif/etcd/.
-- Установите node.js 10 или новее.
-- Установите gcc и g++ 8.x или новее.
-- Склонируйте данный репозиторий с подмодулями: `git clone https://yourcmc.ru/git/vitalif/vitastor/`.
-- Желательно пересобрать QEMU с патчем, который делает необязательным запуск через LD_PRELOAD.
-  См `patches/qemu-*.*-vitastor.patch` - выберите версию, наиболее близкую вашей версии QEMU.
-- Установите QEMU 3.0 или новее, возьмите исходные коды установленного пакета, начните его пересборку,
-  через некоторое время остановите её и скопируйте следующие заголовки:
-   - `<qemu>/include` &rarr; `<vitastor>/qemu/include`
-   - Debian:
-      * Берите qemu из основного репозитория
-      * `<qemu>/b/qemu/config-host.h` &rarr; `<vitastor>/qemu/b/qemu/config-host.h`
-      * `<qemu>/b/qemu/qapi` &rarr; `<vitastor>/qemu/b/qemu/qapi`
-   - CentOS 8:
-      * Берите qemu из репозитория Advanced-Virtualization. Чтобы включить его, запустите
-        `yum install centos-release-advanced-virtualization.noarch` и далее `yum install qemu`
-      * `<qemu>/config-host.h` &rarr; `<vitastor>/qemu/b/qemu/config-host.h`
-      * Для QEMU 3.0+: `<qemu>/qapi` &rarr; `<vitastor>/qemu/b/qemu/qapi`
-      * Для QEMU 2.0+: `<qemu>/qapi-types.h` &rarr; `<vitastor>/qemu/b/qemu/qapi-types.h`
-   - `config-host.h` и `qapi` нужны, т.к. в них содержатся автогенерируемые заголовки
-- Установите fio 3.7 или новее, возьмите исходники пакета и сделайте на них симлинк с `<vitastor>/fio`.
-- Соберите и установите Vitastor командой `mkdir build && cd build && cmake .. && make -j8 && make install`.
-  Обратите внимание на переменную cmake `QEMU_PLUGINDIR` - под RHEL её нужно установить равной `qemu-kvm`.
-
-## Запуск
-
-Внимание: процедура пока что достаточно нетривиальная, задавать конфигурацию и смещения
-на диске нужно почти вручную. Это будет исправлено в ближайшем будущем.
-
-- Желательны SATA SSD или NVMe диски с конденсаторами (серверные SSD). Можно использовать и
-  десктопные SSD, включив режим отложенного fsync, но производительность однопоточной записи
-  в этом случае пострадает.
-- Быстрая сеть, минимум 10 гбит/с
-- Для наилучшей производительности нужно отключить энергосбережение CPU: `cpupower idle-set -D 0 && cpupower frequency-set -g performance`.
-- На хостах мониторов:
-  - Пропишите нужные вам значения в файле `/usr/lib/vitastor/mon/make-units.sh`
-  - Создайте юниты systemd для etcd и мониторов: `/usr/lib/vitastor/mon/make-units.sh`
-- Пропишите etcd_address и osd_network в `/etc/vitastor/vitastor.conf`. Например:
-  ```
-  {
-    "etcd_address": ["10.200.1.10:2379","10.200.1.11:2379","10.200.1.12:2379"],
-    "osd_network": "10.200.1.0/24"
-  }
-  ```
-- Создайте юниты systemd для OSD: `/usr/lib/vitastor/make-osd.sh /dev/disk/by-partuuid/XXX [/dev/disk/by-partuuid/YYY ...]`
-- Вы можете менять параметры OSD в юнитах systemd или в `vitastor.conf`. Смысл некоторых параметров:
-  - `disable_data_fsync 1` - отключает fsync, используется с SSD с конденсаторами.
-  - `immediate_commit all` - используется с SSD с конденсаторами.
-    Внимание: если установлено, также нужно установить его в то же значение в etcd в /vitastor/config/global
-  - `disable_device_lock 1` - отключает блокировку файла устройства, нужно, только если вы запускаете
-    несколько OSD на одном блочном устройстве.
-  - `flusher_count 256` - "flusher" - микропоток, удаляющий старые данные из журнала.
-    Не волнуйтесь об этой настройке, 256 теперь достаточно практически всегда.
-  - `disk_alignment`, `journal_block_size`, `meta_block_size` следует установить равными размеру
-    внутреннего блока SSD. Это почти всегда 4096.
-  - `journal_no_same_sector_overwrites true` запрещает перезапись одного и того же сектора журнала подряд
-    много раз в процессе записи. Большинство (99%) SSD не нуждаются в данной опции. Однако выяснилось, что
-    диски, используемые на одном из тестовых стендов - Intel D3-S4510 - очень сильно не любят такую
-    перезапись, и для них была добавлена эта опция. Когда данный режим включён, также нужно поднимать
-    значение `journal_sector_buffer_count`, так как иначе Vitastor не хватит буферов для записи в журнал.
-- Запустите все etcd: `systemctl start etcd`
-- Создайте глобальную конфигурацию в etcd: `etcdctl --endpoints=... put /vitastor/config/global '{"immediate_commit":"all"}'`
-  (если все ваши диски - серверные с конденсаторами).
-- Создайте пулы: `etcdctl --endpoints=... put /vitastor/config/pools '{"1":{"name":"testpool","scheme":"replicated","pg_size":2,"pg_minsize":1,"pg_count":256,"failure_domain":"host"}}'`.
-  Для jerasure EC-пулов конфигурация должна выглядеть так: `2:{"name":"ecpool","scheme":"jerasure","pg_size":4,"parity_chunks":2,"pg_minsize":2,"pg_count":256,"failure_domain":"host"}`.
-- Запустите все OSD: `systemctl start vitastor.target`
-- Ваш кластер должен быть готов - один из мониторов должен уже сконфигурировать PG, а OSD должны запустить их.
-- Вы можете проверить состояние PG прямо в etcd: `etcdctl --endpoints=... get --prefix /vitastor/pg/state`. Все PG должны быть 'active'.
-
-### Задать имя образу
-
-```
-etcdctl --endpoints=<etcd> put /vitastor/config/inode/<pool>/<inode> '{"name":"<name>","size":<size>[,"parent_id":<parent_inode_number>][,"readonly":true]}'
-```
-
-Например:
-
-```
-etcdctl --endpoints=http://10.115.0.10:2379/v3 put /vitastor/config/inode/1/1 '{"name":"testimg","size":2147483648}'
-```
-
-Если вы зададите parent_id, то образ станет CoW-клоном, т.е. все новые запросы записи пойдут в новый инод, а запросы
-чтения будут проверять сначала его, а потом родительские слои по цепочке вверх. Чтобы случайно не перезаписать данные
-в родительском слое, вы можете переключить его в режим "только чтение", добавив флаг `"readonly":true` в его запись
-метаданных. В таком случае родительский образ становится просто снапшотом.
-
-Таким образом, для создания снапшота вам нужно просто переименовать предыдущий inode (например, из testimg в testimg@0),
-сделать его readonly и создать новый слой с исходным именем образа (testimg), ссылающийся на только что переименованный
-в качестве родительского.
-
-### Запуск тестов с fio
-
-Пример команды для запуска тестов:
-
-```
-fio -thread -ioengine=libfio_vitastor.so -name=test -bs=4M -direct=1 -iodepth=16 -rw=write -etcd=10.115.0.10:2379/v3 -image=testimg
-```
-
-Если вы не хотите обращаться к образу по имени, вместо `-image=testimg` можно указать номер пула, номер инода и размер:
-`-pool=1 -inode=1 -size=400G`.
-
-### Загрузить образ диска ВМ в/из Vitastor
-
-Используйте qemu-img и строку `vitastor:etcd_host=<HOST>:image=<IMAGE>` в качестве имени файла диска. Например:
-
-```
-qemu-img convert -f qcow2 debian10.qcow2 -p -O raw 'vitastor:etcd_host=10.115.0.10\:2379/v3:image=testimg'
-```
-
-Обратите внимание, что если вы используете немодифицированный QEMU, потребуется установить переменную окружения
-`LD_PRELOAD=/usr/lib/x86_64-linux-gnu/qemu/block-vitastor.so`.
-
-Если вы не хотите обращаться к образу по имени, вместо `:image=<IMAGE>` можно указать номер пула, номер инода и размер:
-`:pool=<POOL>:inode=<INODE>:size=<SIZE>`.
-
-### Запустить ВМ
-
-Для запуска QEMU используйте опцию `-drive file=vitastor:etcd_host=<HOST>:image=<IMAGE>` (аналогично qemu-img)
-и физический размер блока 4 KB.
-
-Например:
-
-```
-qemu-system-x86_64 -enable-kvm -m 1024
-  -drive 'file=vitastor:etcd_host=10.115.0.10\:2379/v3:image=testimg',format=raw,if=none,id=drive-virtio-disk0,cache=none
-  -device virtio-blk-pci,scsi=off,bus=pci.0,addr=0x5,drive=drive-virtio-disk0,id=virtio-disk0,bootindex=1,write-cache=off,physical_block_size=4096,logical_block_size=512
-  -vnc 0.0.0.0:0
-```
-
-Обращение по номерам (`:pool=<POOL>:inode=<INODE>:size=<SIZE>` вместо `:image=<IMAGE>`) работает аналогично qemu-img.
-
-### Удалить образ
-
-Используйте утилиту vitastor-cli rm-data. Например:
-
-```
-vitastor-cli rm-data --etcd_address 10.115.0.10:2379/v3 --pool 1 --inode 1 --parallel_osds 16 --iodepth 32
-```
-
-### NBD
-
-Чтобы создать локальное блочное устройство, используйте NBD. Например:
-
-```
-vitastor-nbd map --etcd_address 10.115.0.10:2379/v3 --image testimg
-```
-
-Команда напечатает название устройства вида /dev/nbd0, которое потом можно будет форматировать
-и использовать как обычное блочное устройство.
-
-Для обращения по номеру инода, аналогично другим командам, можно использовать опции
-`--pool <POOL> --inode <INODE> --size <SIZE>` вместо `--image testimg`.
-
-### Kubernetes
-
-У Vitastor есть CSI-плагин для Kubernetes, поддерживающий RWO-тома.
-
-Для установки возьмите манифесты из директории [csi/deploy/](csi/deploy/), поместите
-вашу конфигурацию подключения к Vitastor в [csi/deploy/001-csi-config-map.yaml](001-csi-config-map.yaml),
-настройте StorageClass в [csi/deploy/009-storage-class.yaml](009-storage-class.yaml)
-и примените все `NNN-*.yaml` к вашей инсталляции Kubernetes.
-
-```
-for i in ./???-*.yaml; do kubectl apply -f $i; done
-```
-
-После этого вы сможете создавать PersistentVolume. Пример смотрите в файле [csi/deploy/example-pvc.yaml](csi/deploy/example-pvc.yaml).
-
-### OpenStack
-
-Чтобы подключить Vitastor к OpenStack:
-
-- Установите пакеты vitastor-client, libvirt и QEMU из DEB или RPM репозитория Vitastor
-- Примените патч `patches/nova-21.diff` или `patches/nova-23.diff` к вашей инсталляции Nova.
-  nova-21.diff подходит для Nova 21-22, nova-23.diff подходит для Nova 23-24.
-- Скопируйте `patches/cinder-vitastor.py` в инсталляцию Cinder как `cinder/volume/drivers/vitastor.py`
-- Создайте тип томов в cinder.conf (см. ниже)
-- Обязательно заблокируйте доступ от виртуальных машин к сети Vitastor (OSD и etcd), т.к. Vitastor (пока) не поддерживает аутентификацию
-- Перезапустите Cinder и Nova
-
-Пример конфигурации Cinder:
-
-```
-[DEFAULT]
-enabled_backends = lvmdriver-1, vitastor-testcluster
-# ...
-
-[vitastor-testcluster]
-volume_driver = cinder.volume.drivers.vitastor.VitastorDriver
-volume_backend_name = vitastor-testcluster
-image_volume_cache_enabled = True
-volume_clear = none
-vitastor_etcd_address = 192.168.7.2:2379
-vitastor_etcd_prefix =
-vitastor_config_path = /etc/vitastor/vitastor.conf
-vitastor_pool_id = 1
-image_upload_use_cinder_backend = True
-```
-
-Чтобы помещать в Vitastor Glance-образы, нужно использовать
-[https://docs.openstack.org/cinder/pike/admin/blockstorage-volume-backed-image.html](образы на основе томов Cinder),
-однако, поддержка этой функции ещё не проверялась.
-
-### Proxmox
-
-Чтобы подключить Vitastor к Proxmox Virtual Environment (поддерживаются версии 6.4 и 7.1):
-
-- Добавьте соответствующий Debian-репозиторий Vitastor в sources.list на хостах Proxmox
-  (buster для 6.4, bullseye для 7.1)
-- Установите пакеты vitastor-client, pve-qemu-kvm, pve-storage-vitastor (* или см. сноску) из репозитория Vitastor
-- Определите тип хранилища в `/etc/pve/storage.cfg` (см. ниже)
-- Обязательно заблокируйте доступ от виртуальных машин к сети Vitastor (OSD и etcd), т.к. Vitastor (пока) не поддерживает аутентификацию
-- Перезапустите демон Proxmox: `systemctl restart pvedaemon`
-
-Пример `/etc/pve/storage.cfg` (единственная обязательная опция - vitastor_pool, все остальные
-перечислены внизу для понимания значений по умолчанию):
-
-```
-vitastor: vitastor
-    # Пул, в который будут помещаться образы дисков
-    vitastor_pool testpool
-    # Путь к файлу конфигурации
-    vitastor_config_path /etc/vitastor/vitastor.conf
-    # Адрес(а) etcd, нужны, только если не указаны в vitastor.conf
-    vitastor_etcd_address 192.168.7.2:2379/v3
-    # Префикс ключей метаданных в etcd
-    vitastor_etcd_prefix /vitastor
-    # Префикс имён образов
-    vitastor_prefix pve/
-    # Монтировать образы через NBD прокси, через ядро (нужно только для контейнеров)
-    vitastor_nbd 0
-```
-
-\* Примечание: вместо установки пакета pve-storage-vitastor вы можете вручную скопировать файл
-[patches/PVE_VitastorPlugin.pm](patches/PVE_VitastorPlugin.pm) на хосты Proxmox как
-`/usr/share/perl5/PVE/Storage/Custom/VitastorPlugin.pm`.
-
-## Известные проблемы
-
-- Запросы удаления объектов могут в данный момент приводить к "неполным" объектам в EC-пулах,
-  если в процессе удаления произойдут отказы OSD или серверов, потому что правильная обработка
-  запросов удаления в кластере должна быть "трёхфазной", а это пока не реализовано. Если вы
-  столкнётесь с такой ситуацией, просто повторите запрос удаления.
-
-## Принципы реализации
-
-- Я люблю архитектурно простые решения. Vitastor проектируется именно так и я намерен
-  и далее следовать данному принципу.
-- Если вы пришли сюда за идеальным кодом на C++, вы, вероятно, не по адресу. "Общепринятые"
-  практики написания C++ кода меня не очень волнуют, так как зачастую, опять-таки, ведут к
-  излишним усложнениям и код получается красивый... но медленный.
-- По той же причине в коде иногда можно встретить велосипеды типа собственного упрощённого
-  HTTP-клиента для работы с etcd. Зато эти велосипеды маленькие и компактные и не требуют
-  использования десятка внешних библиотек.
-- node.js для монитора - не случайный выбор. Он очень быстрый, имеет встроенную событийную
-  машину, приятный нейтральный C-подобный язык программирования и развитую инфраструктуру.
+Vitastor нацелен на SSD и SSD+HDD кластеры с как минимум 10 Гбит/с сетью, поддерживает
+TCP и RDMA и на хорошем железе может достигать задержки 4 КБ чтения и записи на уровне ~0.1 мс,
+что примерно в 10 раз быстрее, чем Ceph и другие популярные программные СХД.
+
+Vitastor поддерживает QEMU-драйвер, протоколы NBD и NFS, драйверы OpenStack, Proxmox, Kubernetes.
+Другие драйверы могут также быть легко реализованы.
+
+Подробности смотрите в документации по ссылкам ниже.
+
+## Презентации и записи докладов
+
+- DevOpsConf'2021: презентация ([на русском](https://vitastor.io/presentation/devopsconf/devopsconf.html),
+  [на английском](https://vitastor.io/presentation/devopsconf/devopsconf_en.html)),
+  [видео](https://vitastor.io/presentation/devopsconf/talk.webm)
+- Highload'2022: презентация ([на русском](https://vitastor.io/presentation/highload/highload.html)),
+  [видео](https://vitastor.io/presentation/highload/talk.webm)
+
+## Документация
+
+- Введение
+  - [Быстрый старт](docs/intro/quickstart.ru.md)
+  - [Возможности](docs/intro/features.ru.md)
+  - [Архитектура](docs/intro/architecture.ru.md)
+  - [Автор и лицензия](docs/intro/author.ru.md)
+- Установка
+  - [Пакеты](docs/installation/packages.ru.md)
+  - [Proxmox](docs/installation/proxmox.ru.md)
+  - [OpenStack](docs/installation/openstack.ru.md)
+  - [Kubernetes CSI](docs/installation/kubernetes.ru.md)
+  - [Сборка из исходных кодов](docs/installation/source.ru.md)
+- Конфигурация
+  - [Обзор](docs/config.ru.md)
+  - Параметры
+    - [Общие](docs/config/common.ru.md)
+    - [Сетевые](docs/config/network.ru.md)
+    - [Глобальные дисковые параметры](docs/config/layout-cluster.ru.md)
+    - [Дисковые параметры OSD](docs/config/layout-osd.ru.md)
+    - [Прочие параметры OSD](docs/config/osd.ru.md)
+    - [Параметры мониторов](docs/config/monitor.ru.md)
+  - [Настройки пулов](docs/config/pool.ru.md)
+  - [Метаданные образов в etcd](docs/config/inode.ru.md)
+- Использование
+  - [vitastor-cli](docs/usage/cli.ru.md) (консольный интерфейс)
+  - [fio](docs/usage/fio.ru.md) для тестов производительности
+  - [NBD](docs/usage/nbd.ru.md) для монтирования ядром
+  - [QEMU и qemu-img](docs/usage/qemu.ru.md)
+  - [NFS](docs/usage/nfs.ru.md)-прокси для VMWare и подобных
+- Производительность
+  - [Понимание сути производительности](docs/performance/understanding.ru.md)
+  - [Теоретический максимум](docs/performance/theoretical.ru.md)
+  - [Пример сравнения с Ceph](docs/performance/comparison1.ru.md)
 
 ## Автор и лицензия
 

README.md

@@ -1,579 +1,71 @@
-## Vitastor
+# Vitastor
 
 [Читать на русском](README-ru.md)
 
 ## The Idea
 
-Make Software-Defined Block Storage Great Again.
-
-Vitastor is a small, simple and fast clustered block storage (storage for VM drives),
-architecturally similar to Ceph which means strong consistency, primary-replication, symmetric
-clustering and automatic data distribution over any number of drives of any size
-with configurable redundancy (replication or erasure codes/XOR).
-
-## Features
-
-Vitastor is currently a pre-release, a lot of features are missing and you can still expect
-breaking changes in the future. However, the following is implemented:
-
-- Basic part: highly-available block storage with symmetric clustering and no SPOF
-- Performance ;-D
-- Multiple redundancy schemes: Replication, XOR n+1, Reed-Solomon erasure codes
-  based on jerasure library with any number of data and parity drives in a group
-- Configuration via simple JSON data structures in etcd
-- Automatic data distribution over OSDs, with support for:
-  - Mathematical optimization for better uniformity and less data movement
-  - Multiple pools
-  - Placement tree, OSD selection by tags (device classes) and placement root
-  - Configurable failure domains
-- Recovery of degraded blocks
-- Rebalancing (data movement between OSDs)
-- Lazy fsync support
-- I/O statistics reporting to etcd
-- Generic user-space client library
-- QEMU driver (built out-of-tree)
-- Loadable fio engine for benchmarks (also built out-of-tree)
-- NBD proxy for kernel mounts
-- Inode removal tool (vitastor-cli rm-data)
-- Packaging for Debian and CentOS
-- Per-inode I/O and space usage statistics
-- Inode metadata storage in etcd
-- Snapshots and copy-on-write image clones
-- Write throttling to smooth random write workloads in SSD+HDD configurations
-- RDMA/RoCEv2 support via libibverbs
-- CSI plugin for Kubernetes
-- Basic OpenStack support: Cinder driver, Nova and libvirt patches
-- Snapshot merge tool (vitastor-cli {snap-rm,flatten,merge})
-- Image management CLI (vitastor-cli {ls,create,modify})
-- Proxmox storage plugin
-
-## Roadmap
-
-- Snapshot deletion (layer merge) support
-- Better OSD creation and auto-start tools
-- Other administrative tools
-- Plugins for OpenNebula, Proxmox and other cloud systems
-- iSCSI proxy
-- Faster failover
-- Scrubbing without checksums (verification of replicas)
-- Checksums
-- Tiered storage
-- NVDIMM support
-- Web GUI
-- Compression (possibly)
-- Read caching using system page cache (possibly)
-
-## Architecture
-
-Similarities:
-
-- Just like Ceph, Vitastor has Pools, PGs, OSDs, Monitors, Failure Domains, Placement Tree.
-- Just like Ceph, Vitastor is transactional (even though there's a "lazy fsync mode" which
-  doesn't implicitly flush every operation to disks).
-- OSDs also have journal and metadata and they can also be put on separate drives.
-- Just like in Ceph, client library attempts to recover from any cluster failure so
-  you can basically reboot the whole cluster and only pause, but not crash, your clients
-  (I consider this a bug if the client crashes in that case).
-
-Some basic terms for people not familiar with Ceph:
-
-- OSD (Object Storage Daemon) is a process that stores data and serves read/write requests.
-- PG (Placement Group) is a container for data that (normally) shares the same replicas.
-- Pool is a container for data that has the same redundancy scheme and placement rules.
-- Monitor is a separate daemon that watches cluster state and handles failures.
-- Failure Domain is a group of OSDs that you allow to fail. It's "host" by default.
-- Placement Tree groups OSDs in a hierarchy to later split them into Failure Domains.
-
-Architectural differences from Ceph:
-
-- Vitastor's primary focus is on SSDs. Proper SSD+HDD optimizations may be added in the future, though.
-- Vitastor OSD is (and will always be) single-threaded. If you want to dedicate more than 1 core
-  per drive you should run multiple OSDs each on a different partition of the drive.
-  Vitastor isn't CPU-hungry though (as opposed to Ceph), so 1 core is sufficient in a lot of cases.
-- Metadata and journal are always kept in memory. Metadata size depends linearly on drive capacity
-  and data store block size which is 128 KB by default. With 128 KB blocks metadata should occupy
-  around 512 MB per 1 TB (which is still less than Ceph wants). Journal doesn't have to be big,
-  the example test below was conducted with only 16 MB journal. A big journal is probably even
-  harmful as dirty write metadata also take some memory.
-- Vitastor storage layer doesn't have internal copy-on-write or redirect-write. I know that maybe
-  it's possible to create a good copy-on-write storage, but it's much harder and makes performance
-  less deterministic, so CoW isn't used in Vitastor.
-- The basic layer of Vitastor is block storage with fixed-size blocks, not object storage with
-  rich semantics like in Ceph (RADOS).
-- There's a "lazy fsync" mode which allows to batch writes before flushing them to the disk.
-  This allows to use Vitastor with desktop SSDs, but still lowers performance due to additional
-  network roundtrips, so use server SSDs with capacitor-based power loss protection
-  ("Advanced Power Loss Protection") for best performance.
-- PGs are ephemeral. This means that they aren't stored on data disks and only exist in memory
-  while OSDs are running.
-- Recovery process is per-object (per-block), not per-PG. Also there are no PGLOGs.
-- Monitors don't store data. Cluster configuration and state is stored in etcd in simple human-readable
-  JSON structures. Monitors only watch cluster state and handle data movement.
-  Thus Vitastor's Monitor isn't a critical component of the system and is more similar to Ceph's Manager.
-  Vitastor's Monitor is implemented in node.js.
-- PG distribution isn't based on consistent hashes. All PG mappings are stored in etcd.
-  Rebalancing PGs between OSDs is done by mathematical optimization - data distribution problem
-  is reduced to a linear programming problem and solved by lp_solve. This allows for almost
-  perfect (96-99% uniformity compared to Ceph's 80-90%) data distribution in most cases, ability
-  to map PGs by hand without breaking rebalancing logic, reduced OSD peer-to-peer communication
-  (on average, OSDs have fewer peers) and less data movement. It also probably has a drawback -
-  this method may fail in very large clusters, but up to several hundreds of OSDs it's perfectly fine.
-  It's also easy to add consistent hashes in the future if something proves their necessity.
-- There's no separate CRUSH layer. You select pool redundancy scheme, placement root, failure domain
-  and so on directly in pool configuration.
-
-## Understanding Storage Performance
-
-The most important thing for fast storage is latency, not parallel iops.
-
-The best possible latency is achieved with one thread and queue depth of 1 which basically means
-"client load as low as possible". In this case IOPS = 1/latency, and this number doesn't
-scale with number of servers, drives, server processes or threads and so on.
-Single-threaded IOPS and latency numbers only depend on *how fast a single daemon is*.
-
-Why is it important? It's important because some of the applications *can't* use
-queue depth greater than 1 because their task isn't parallelizable. A notable example
-is any ACID DBMS because all of them write their WALs sequentially with fsync()s.
-
-fsync, by the way, is another important thing often missing in benchmarks. The point is
-that drives have cache buffers and don't guarantee that your data is actually persisted
-until you call fsync() which is translated to a FLUSH CACHE command by the OS.
-
-Desktop SSDs are very fast without fsync - NVMes, for example, can process ~80000 write
-operations per second with queue depth of 1 without fsync - but they're really slow with
-fsync because they have to actually write data to flash chips when you call fsync. Typical
-number is around 1000-2000 iops with fsync.
-
-Server SSDs often have supercapacitors that act as a built-in UPS and allow the drive
-to flush its DRAM cache to the persistent flash storage when a power loss occurs.
-This makes them perform equally well with and without fsync. This feature is called
-"Advanced Power Loss Protection" by Intel; other vendors either call it similarly
-or directly as "Full Capacitor-Based Power Loss Protection".
-
-All software-defined storages that I currently know are slow in terms of latency.
-Notable examples are Ceph and internal SDSes used by cloud providers like Amazon, Google,
-Yandex and so on. They're all slow and can only reach ~0.3ms read and ~0.6ms 4 KB write latency
-with best-in-slot hardware.
-
-And that's in the SSD era when you can buy an SSD that has ~0.04ms latency for 100 $.
-
-I use the following 6 commands with small variations to benchmark any storage:
-
-- Linear write:
-  `fio -ioengine=libaio -direct=1 -invalidate=1 -name=test -bs=4M -iodepth=32 -rw=write -runtime=60 -filename=/dev/sdX`
-- Linear read:
-  `fio -ioengine=libaio -direct=1 -invalidate=1 -name=test -bs=4M -iodepth=32 -rw=read -runtime=60 -filename=/dev/sdX`
-- Random write latency (T1Q1, this hurts storages the most):
-  `fio -ioengine=libaio -direct=1 -invalidate=1 -name=test -bs=4k -iodepth=1 -fsync=1 -rw=randwrite -runtime=60 -filename=/dev/sdX`
-- Random read latency (T1Q1):
-  `fio -ioengine=libaio -direct=1 -invalidate=1 -name=test -bs=4k -iodepth=1 -rw=randread -runtime=60 -filename=/dev/sdX`
-- Parallel write iops (use numjobs if a single CPU core is insufficient to saturate the load):
-  `fio -ioengine=libaio -direct=1 -invalidate=1 -name=test -bs=4k -iodepth=128 [-numjobs=4 -group_reporting] -rw=randwrite -runtime=60 -filename=/dev/sdX`
-- Parallel read iops (use numjobs if a single CPU core is insufficient to saturate the load):
-  `fio -ioengine=libaio -direct=1 -invalidate=1 -name=test -bs=4k -iodepth=128 [-numjobs=4 -group_reporting] -rw=randread -runtime=60 -filename=/dev/sdX`
-
-## Vitastor's Theoretical Maximum Random Access Performance
-
-Replicated setups:
-- Single-threaded (T1Q1) read latency: 1 network roundtrip + 1 disk read.
-- Single-threaded write+fsync latency:
-  - With immediate commit: 2 network roundtrips + 1 disk write.
-  - With lazy commit: 4 network roundtrips + 1 disk write + 1 disk flush.
-- Saturated parallel read iops: min(network bandwidth, sum(disk read iops)).
-- Saturated parallel write iops: min(network bandwidth, sum(disk write iops / number of replicas / write amplification)).
-
-EC/XOR setups:
-- Single-threaded (T1Q1) read latency: 1.5 network roundtrips + 1 disk read.
-- Single-threaded write+fsync latency:
-  - With immediate commit: 3.5 network roundtrips + 1 disk read + 2 disk writes.
-  - With lazy commit: 5.5 network roundtrips + 1 disk read + 2 disk writes + 2 disk fsyncs.
-  - 0.5 in actually (k-1)/k which means that an additional roundtrip doesn't happen when
-    the read sub-operation can be served locally.
-- Saturated parallel read iops: min(network bandwidth, sum(disk read iops)).
-- Saturated parallel write iops: min(network bandwidth, sum(disk write iops * number of data drives / (number of data + parity drives) / write amplification)).
-  In fact, you should put disk write iops under the condition of ~10% reads / ~90% writes in this formula.
-
-Write amplification for 4 KB blocks is usually 3-5 in Vitastor:
-1. Journal block write
-2. Journal data write
-3. Metadata block write
-4. Another journal block write for EC/XOR setups
-5. Data block write
-
-If you manage to get an SSD which handles 512 byte blocks well (Optane?) you may
-lower 1, 3 and 4 to 512 bytes (1/8 of data size) and get WA as low as 2.375.
-
-Lazy fsync also reduces WA for parallel workloads because journal blocks are only
-written when they fill up or fsync is requested.
-
-## Example Comparison with Ceph
-
-Hardware configuration: 4 nodes, each with:
-- 6x SATA SSD Intel D3-4510 3.84 TB
-- 2x Xeon Gold 6242 (16 cores @ 2.8 GHz)
-- 384 GB RAM
-- 1x 25 GbE network interface (Mellanox ConnectX-4 LX), connected to a Juniper QFX5200 switch
-
-CPU powersaving was disabled. Both Vitastor and Ceph were configured with 2 OSDs per 1 SSD.
-
-All of the results below apply to 4 KB blocks and random access (unless indicated otherwise).
-
-Raw drive performance:
-- T1Q1 write ~27000 iops (~0.037ms latency)
-- T1Q1 read ~9800 iops (~0.101ms latency)
-- T1Q32 write ~60000 iops
-- T1Q32 read ~81700 iops
-
-Ceph 15.2.4 (Bluestore):
-- T1Q1 write ~1000 iops (~1ms latency)
-- T1Q1 read ~1750 iops (~0.57ms latency)
-- T8Q64 write ~100000 iops, total CPU usage by OSDs about 40 virtual cores on each node
-- T8Q64 read ~480000 iops, total CPU usage by OSDs about 40 virtual cores on each node
-
-T8Q64 tests were conducted over 8 400GB RBD images from all hosts (every host was running 2 instances of fio).
-This is because Ceph has performance penalties related to running multiple clients over a single RBD image.
-
-cephx_sign_messages was set to false during tests, RocksDB and Bluestore settings were left at defaults.
-
-In fact, not that bad for Ceph. These servers are an example of well-balanced Ceph nodes.
-However, CPU usage and I/O latency were through the roof, as usual.
-
-Vitastor:
-- T1Q1 write: 7087 iops (0.14ms latency)
-- T1Q1 read: 6838 iops (0.145ms latency)
-- T2Q64 write: 162000 iops, total CPU usage by OSDs about 3 virtual cores on each node
-- T8Q64 read: 895000 iops, total CPU usage by OSDs about 4 virtual cores on each node
-- Linear write (4M T1Q32): 2800 MB/s
-- Linear read (4M T1Q32): 1500 MB/s
-
-T8Q64 read test was conducted over 1 larger inode (3.2T) from all hosts (every host was running 2 instances of fio).
-Vitastor has no performance penalties related to running multiple clients over a single inode.
-If conducted from one node with all primary OSDs moved to other nodes the result was slightly lower (689000 iops),
-this is because all operations resulted in network roundtrips between the client and the primary OSD.
-When fio was colocated with OSDs (like in Ceph benchmarks above), 1/4 of the read workload actually
-used the loopback network.
-
-Vitastor was configured with: `--disable_data_fsync true --immediate_commit all --flusher_count 8
-  --disk_alignment 4096 --journal_block_size 4096 --meta_block_size 4096
-  --journal_no_same_sector_overwrites true --journal_sector_buffer_count 1024
-  --journal_size 16777216`.
-
-### EC/XOR 2+1
-
-Vitastor:
-- T1Q1 write: 2808 iops (~0.355ms latency)
-- T1Q1 read: 6190 iops (~0.16ms latency)
-- T2Q64 write: 85500 iops, total CPU usage by OSDs about 3.4 virtual cores on each node
-- T8Q64 read: 812000 iops, total CPU usage by OSDs about 4.7 virtual cores on each node
-- Linear write (4M T1Q32): 3200 MB/s
-- Linear read (4M T1Q32): 1800 MB/s
-
-Ceph:
-- T1Q1 write: 730 iops (~1.37ms latency)
-- T1Q1 read: 1500 iops with cold cache (~0.66ms latency), 2300 iops after 2 minute metadata cache warmup (~0.435ms latency)
-- T4Q128 write (4 RBD images): 45300 iops, total CPU usage by OSDs about 30 virtual cores on each node
-- T8Q64 read (4 RBD images): 278600 iops, total CPU usage by OSDs about 40 virtual cores on each node
-- Linear write (4M T1Q32): 1950 MB/s before preallocation, 2500 MB/s after preallocation
-- Linear read (4M T1Q32): 2400 MB/s
-
-### NBD
-
-NBD is currently required to mount Vitastor via kernel, but it imposes additional overhead
-due to additional copying between the kernel and userspace. This mostly hurts linear
-bandwidth, not iops.
-
-Vitastor with single-thread NBD on the same hardware:
-- T1Q1 write: 6000 iops (0.166ms latency)
-- T1Q1 read: 5518 iops (0.18ms latency)
-- T1Q128 write: 94400 iops
-- T1Q128 read: 103000 iops
-- Linear write (4M T1Q128): 1266 MB/s (compared to 2800 MB/s via fio)
-- Linear read (4M T1Q128): 975 MB/s (compared to 1500 MB/s via fio)
-
-## Installation
-
-### Debian
-
-- Trust Vitastor package signing key:
-  `wget -q -O - https://vitastor.io/debian/pubkey | sudo apt-key add -`
-- Add Vitastor package repository to your /etc/apt/sources.list:
-  - Debian 11 (Bullseye/Sid): `deb https://vitastor.io/debian bullseye main`
-  - Debian 10 (Buster): `deb https://vitastor.io/debian buster main`
-- For Debian 10 (Buster) also enable backports repository:
-  `deb http://deb.debian.org/debian buster-backports main`
-- Install packages: `apt update; apt install vitastor lp-solve etcd linux-image-amd64 qemu`
-
-### CentOS
-
-- Add Vitastor package repository:
-  - CentOS 7: `yum install https://vitastor.io/rpms/centos/7/vitastor-release-1.0-1.el7.noarch.rpm`
-  - CentOS 8: `dnf install https://vitastor.io/rpms/centos/8/vitastor-release-1.0-1.el8.noarch.rpm`
-- Enable EPEL: `yum/dnf install epel-release`
-- Enable additional CentOS repositories:
-  - CentOS 7: `yum install centos-release-scl`
-  - CentOS 8: `dnf install centos-release-advanced-virtualization`
-- Enable elrepo-kernel:
-  - CentOS 7: `yum install https://www.elrepo.org/elrepo-release-7.el7.elrepo.noarch.rpm`
-  - CentOS 8: `dnf install https://www.elrepo.org/elrepo-release-8.el8.elrepo.noarch.rpm`
-- Install packages: `yum/dnf install vitastor lpsolve etcd kernel-ml qemu-kvm`
-
-### Building from Source
-
-- Install Linux kernel 5.4 or newer, for io_uring support. 5.8 or later is highly recommended because
-  there is at least one known io_uring hang with 5.4 and an HP SmartArray controller.
-- Install liburing 0.4 or newer and its headers.
-- Install lp_solve.
-- Install etcd, at least version 3.4.15. Earlier versions won't work because of various bugs,
-  for example [#12402](https://github.com/etcd-io/etcd/pull/12402). You can also take 3.4.13
-  with this specific fix from here: https://github.com/vitalif/etcd/, branch release-3.4.
-- Install node.js 10 or newer.
-- Install gcc and g++ 8.x or newer.
-- Clone https://yourcmc.ru/git/vitalif/vitastor/ with submodules.
-- Install QEMU 3.0+, get its source, begin to build it, stop the build and copy headers:
-   - `<qemu>/include` &rarr; `<vitastor>/qemu/include`
-   - Debian:
-      * Use qemu packages from the main repository
-      * `<qemu>/b/qemu/config-host.h` &rarr; `<vitastor>/qemu/b/qemu/config-host.h`
-      * `<qemu>/b/qemu/qapi` &rarr; `<vitastor>/qemu/b/qemu/qapi`
-   - CentOS 8:
-      * Use qemu packages from the Advanced-Virtualization repository. To enable it, run
-        `yum install centos-release-advanced-virtualization.noarch` and then `yum install qemu`
-      * `<qemu>/config-host.h` &rarr; `<vitastor>/qemu/b/qemu/config-host.h`
-      * For QEMU 3.0+: `<qemu>/qapi` &rarr; `<vitastor>/qemu/b/qemu/qapi`
-      * For QEMU 2.0+: `<qemu>/qapi-types.h` &rarr; `<vitastor>/qemu/b/qemu/qapi-types.h`
-   - `config-host.h` and `qapi` are required because they contain generated headers
-- You can also rebuild QEMU with a patch that makes LD_PRELOAD unnecessary to load vitastor driver.
-  See `patches/qemu-*.*-vitastor.patch`.
-- Install fio 3.7 or later, get its source and symlink it into `<vitastor>/fio`.
-- Build & install Vitastor with `mkdir build && cd build && cmake .. && make -j8 && make install`.
-  Pay attention to the `QEMU_PLUGINDIR` cmake option - it must be set to `qemu-kvm` on RHEL.
-
-## Running
-
-Please note that startup procedure isn't currently simple - you specify configuration
-and calculate disk offsets almost by hand. This will be fixed in near future.
-
-- Get some SATA or NVMe SSDs with capacitors (server-grade drives). You can use desktop SSDs
-  with lazy fsync, but prepare for inferior single-thread latency.
-- Get a fast network (at least 10 Gbit/s).
-- Disable CPU powersaving: `cpupower idle-set -D 0 && cpupower frequency-set -g performance`.
-- On the monitor hosts:
-  - Edit variables at the top of `/usr/lib/vitastor/mon/make-units.sh` to desired values.
-  - Create systemd units for the monitor and etcd: `/usr/lib/vitastor/mon/make-units.sh`
-- Put etcd_address and osd_network into `/etc/vitastor/vitastor.conf`. Example:
-  ```
-  {
-    "etcd_address": ["10.200.1.10:2379","10.200.1.11:2379","10.200.1.12:2379"],
-    "osd_network": "10.200.1.0/24"
-  }
-  ```
-- Create systemd units for your OSDs: `/usr/lib/vitastor/mon/make-osd.sh /dev/disk/by-partuuid/XXX [/dev/disk/by-partuuid/YYY ...]`
-- You can change OSD configuration in units or in `vitastor.conf`. Notable configuration variables:
-  - `disable_data_fsync 1` - only safe with server-grade drives with capacitors.
-  - `immediate_commit all` - use this if all your drives are server-grade.
-    If all OSDs have it set to all then you should also put the same value in etcd into /vitastor/config/global
-  - `disable_device_lock 1` - only required if you run multiple OSDs on one block device.
-  - `flusher_count 256` - flusher is a micro-thread that removes old data from the journal.
-    You don't have to worry about this parameter anymore, 256 is enough.
-  - `disk_alignment`, `journal_block_size`, `meta_block_size` should be set to the internal
-    block size of your SSDs which is 4096 on most drives.
-  - `journal_no_same_sector_overwrites true` prevents multiple overwrites of the same journal sector.
-    Most (99%) SSDs don't need this option. But Intel D3-4510 does because it doesn't like when you
-    overwrite the same sector twice in a short period of time. The setting forces Vitastor to never
-    overwrite the same journal sector twice in a row which makes D3-4510 almost happy. Not totally
-    happy, because overwrites of the same block can still happen in the metadata area... When this
-    setting is set, it is also required to raise `journal_sector_buffer_count` setting, which is the
-    number of dirty journal sectors that may be written to at the same time.
-- `systemctl start vitastor.target` everywhere.
-- Create global configuration in etcd: `etcdctl --endpoints=... put /vitastor/config/global '{"immediate_commit":"all"}'`
-  (if all your drives have capacitors).
-- Create pool configuration in etcd: `etcdctl --endpoints=... put /vitastor/config/pools '{"1":{"name":"testpool","scheme":"replicated","pg_size":2,"pg_minsize":1,"pg_count":256,"failure_domain":"host"}}'`.
-  For jerasure pools the configuration should look like the following: `2:{"name":"ecpool","scheme":"jerasure","pg_size":4,"parity_chunks":2,"pg_minsize":2,"pg_count":256,"failure_domain":"host"}`.
-- At this point, one of the monitors will configure PGs and OSDs will start them.
-- You can check PG states with `etcdctl --endpoints=... get --prefix /vitastor/pg/state`. All PGs should become 'active'.
-
-### Name an image
-
-```
-etcdctl --endpoints=<etcd> put /vitastor/config/inode/<pool>/<inode> '{"name":"<name>","size":<size>[,"parent_id":<parent_inode_number>][,"readonly":true]}'
-```
-
-For example:
-
-```
-etcdctl --endpoints=http://10.115.0.10:2379/v3 put /vitastor/config/inode/1/1 '{"name":"testimg","size":2147483648}'
-```
-
-If you specify parent_id the image becomes a CoW clone. I.e. all writes go to the new inode and reads first check it
-and then upper layers. You can then make parent readonly by updating its entry with `"readonly":true` for safety and
-basically treat it as a snapshot.
-
-So to create a snapshot you basically rename the previous upper layer (for example from testimg to testimg@0), make it readonly
-and create a new top layer with the original name (testimg) and the previous one as a parent.
-
-### Run fio benchmarks
-
-fio command example:
-
-```
-fio -thread -ioengine=libfio_vitastor.so -name=test -bs=4M -direct=1 -iodepth=16 -rw=write -etcd=10.115.0.10:2379/v3 -image=testimg
-```
-
-If you don't want to access your image by name, you can specify pool number, inode number and size
-(`-pool=1 -inode=1 -size=400G`) instead of the image name (`-image=testimg`).
-
-### Upload VM image
-
-Use qemu-img and `vitastor:etcd_host=<HOST>:image=<IMAGE>` disk filename. For example:
-
-```
-qemu-img convert -f qcow2 debian10.qcow2 -p -O raw 'vitastor:etcd_host=10.115.0.10\:2379/v3:image=testimg'
-```
-
-Note that the command requires to be run with `LD_PRELOAD=/usr/lib/x86_64-linux-gnu/qemu/block-vitastor.so qemu-img ...`
-if you use unmodified QEMU.
-
-You can also specify `:pool=<POOL>:inode=<INODE>:size=<SIZE>` instead of `:image=<IMAGE>`
-if you don't want to use inode metadata.
-
-### Start a VM
-
-Run QEMU with `-drive file=vitastor:etcd_host=<HOST>:image=<IMAGE>` and use 4 KB physical block size.
-
-For example:
-
-```
-qemu-system-x86_64 -enable-kvm -m 1024
-  -drive 'file=vitastor:etcd_host=10.115.0.10\:2379/v3:image=testimg',format=raw,if=none,id=drive-virtio-disk0,cache=none
-  -device virtio-blk-pci,scsi=off,bus=pci.0,addr=0x5,drive=drive-virtio-disk0,id=virtio-disk0,bootindex=1,write-cache=off,physical_block_size=4096,logical_block_size=512
-  -vnc 0.0.0.0:0
-```
-
-You can also specify `:pool=<POOL>:inode=<INODE>:size=<SIZE>` instead of `:image=<IMAGE>`,
-just like in qemu-img.
-
-### Remove inode
-
-Use vitastor-rm / vitastor-cli rm-data. For example:
-
-```
-vitastor-cli rm-data --etcd_address 10.115.0.10:2379/v3 --pool 1 --inode 1 --parallel_osds 16 --iodepth 32
-```
-
-### NBD
-
-To create a local block device for a Vitastor image, use NBD. For example:
-
-```
-vitastor-nbd map --etcd_address 10.115.0.10:2379/v3 --image testimg
-```
-
-It will output the device name, like /dev/nbd0 which you can then format and mount as a normal block device.
-
-Again, you can use `--pool <POOL> --inode <INODE> --size <SIZE>` insteaf of `--image <IMAGE>` if you want.
-
-### Kubernetes
-
-Vitastor has a CSI plugin for Kubernetes which supports RWO volumes.
-
-To deploy it, take manifests from [csi/deploy/](csi/deploy/) directory, put your
-Vitastor configuration in [csi/deploy/001-csi-config-map.yaml](001-csi-config-map.yaml),
-configure storage class in [csi/deploy/009-storage-class.yaml](009-storage-class.yaml)
-and apply all `NNN-*.yaml` manifests to your Kubernetes installation:
-
-```
-for i in ./???-*.yaml; do kubectl apply -f $i; done
-```
-
-After that you'll be able to create PersistentVolumes. See example in [csi/deploy/example-pvc.yaml](csi/deploy/example-pvc.yaml).
-
-### OpenStack
-
-To enable Vitastor support in an OpenStack installation:
-
-- Install vitastor-client, patched QEMU and libvirt packages from Vitastor DEB or RPM repository
-- Use `patches/nova-21.diff` or `patches/nova-23.diff` to patch your Nova installation.
-  Patch 21 fits Nova 21-22, patch 23 fits Nova 23-24.
-- Install `patches/cinder-vitastor.py` as `..../cinder/volume/drivers/vitastor.py`
-- Define a volume type in cinder.conf (see below)
-- Block network access from VMs to Vitastor network (to OSDs and etcd), because Vitastor doesn't support authentication (yet)
-- Restart Cinder and Nova
-
-Cinder volume type configuration example:
-
-```
-[DEFAULT]
-enabled_backends = lvmdriver-1, vitastor-testcluster
-# ...
-
-[vitastor-testcluster]
-volume_driver = cinder.volume.drivers.vitastor.VitastorDriver
-volume_backend_name = vitastor-testcluster
-image_volume_cache_enabled = True
-volume_clear = none
-vitastor_etcd_address = 192.168.7.2:2379
-vitastor_etcd_prefix =
-vitastor_config_path = /etc/vitastor/vitastor.conf
-vitastor_pool_id = 1
-image_upload_use_cinder_backend = True
-```
-
-To put Glance images in Vitastor, use [https://docs.openstack.org/cinder/pike/admin/blockstorage-volume-backed-image.html](volume-backed images),
-although the support has not been verified yet.
-
-### Proxmox
-
-To enable Vitastor support in Proxmox Virtual Environment (6.4 and 7.1 are supported):
-
-- Add the corresponding Vitastor Debian repository into sources.list on Proxmox hosts
-  (buster for 6.4, bullseye for 7.1)
-- Install vitastor-client, pve-qemu-kvm, pve-storage-vitastor (* or see note) packages from Vitastor repository
-- Define storage in `/etc/pve/storage.cfg` (see below)
-- Block network access from VMs to Vitastor network (to OSDs and etcd), because Vitastor doesn't support authentication (yet)
-- Restart pvedaemon: `systemctl restart pvedaemon`
-
-`/etc/pve/storage.cfg` example (the only required option is vitastor_pool, all others
-are listed below with their default values):
-
-```
-vitastor: vitastor
-    # pool to put new images into
-    vitastor_pool testpool
-    # path to the configuration file
-    vitastor_config_path /etc/vitastor/vitastor.conf
-    # etcd address(es), required only if missing in the configuration file
-    vitastor_etcd_address 192.168.7.2:2379/v3
-    # prefix for keys in etcd
-    vitastor_etcd_prefix /vitastor
-    # prefix for images
-    vitastor_prefix pve/
-    # use NBD mounter (only required for containers)
-    vitastor_nbd 0
-```
-
-\* Note: you can also manually copy [patches/PVE_VitastorPlugin.pm](patches/PVE_VitastorPlugin.pm) to Proxmox hosts
-as `/usr/share/perl5/PVE/Storage/Custom/VitastorPlugin.pm` instead of installing pve-storage-vitastor.
-
-## Known Problems
-
-- Object deletion requests may currently lead to 'incomplete' objects in EC pools
-  if your OSDs crash during deletion because proper handling of object cleanup
-  in a cluster should be "three-phase" and it's currently not implemented.
-  Just repeat the removal request again in this case.
-
-## Implementation Principles
-
-- I like architecturally simple solutions. Vitastor is and will always be designed
-  exactly like that.
-- I also like reinventing the wheel to some extent, like writing my own HTTP client
-  for etcd interaction instead of using prebuilt libraries, because in this case
-  I'm confident about what my code does and what it doesn't do.
-- I don't care about C++ "best practices" like RAII or proper inheritance or usage of
-  smart pointers or whatever and I don't intend to change my mind, so if you're here
-  looking for ideal reference C++ code, this probably isn't the right place.
-- I like node.js better than any other dynamically-typed language interpreter
-  because it's faster than any other interpreter in the world, has neutral C-like
-  syntax and built-in event loop. That's why Monitor is implemented in node.js.
+Make Clustered Block Storage Fast Again.
+
+Vitastor is a distributed block SDS, direct replacement of Ceph RBD and internal SDS's
+of public clouds. However, in contrast to them, Vitastor is fast and simple at the same time.
+The only thing is it's slightly young :-).
+
+Vitastor is architecturally similar to Ceph which means strong consistency,
+primary-replication, symmetric clustering and automatic data distribution over any
+number of drives of any size with configurable redundancy (replication or erasure codes/XOR).
+
+Vitastor targets SSD and SSD+HDD clusters with at least 10 Gbit/s network, supports
+TCP and RDMA and may achieve 4 KB read and write latency as low as ~0.1 ms
+with proper hardware which is ~10 times faster than other popular SDS's like Ceph
+or internal systems of public clouds.
+
+Vitastor supports QEMU, NBD, NFS protocols, OpenStack, Proxmox, Kubernetes drivers.
+More drivers may be created easily.
+
+Read more details below in the documentation.
+
+## Talks and presentations
+
+- DevOpsConf'2021: presentation ([in Russian](https://vitastor.io/presentation/devopsconf/devopsconf.html),
+  [in English](https://vitastor.io/presentation/devopsconf/devopsconf_en.html)),
+  [video](https://vitastor.io/presentation/devopsconf/talk.webm)
+- Highload'2022: presentation ([in Russian](https://vitastor.io/presentation/highload/highload.html)),
+  [video](https://vitastor.io/presentation/highload/talk.webm)
+
+## Documentation
+
+- Introduction
+  - [Quick Start](docs/intro/quickstart.en.md)
+  - [Features](docs/intro/features.en.md)
+  - [Architecture](docs/intro/architecture.en.md)
+  - [Author and license](docs/intro/author.en.md)
+- Installation
+  - [Packages](docs/installation/packages.en.md)
+  - [Proxmox](docs/installation/proxmox.en.md)
+  - [OpenStack](docs/installation/openstack.en.md)
+  - [Kubernetes CSI](docs/installation/kubernetes.en.md)
+  - [Building from Source](docs/installation/source.en.md)
+- Configuration
+  - [Overview](docs/config.en.md)
+  - Parameter Reference
+    - [Common](docs/config/common.en.md)
+    - [Network](docs/config/network.en.md)
+    - [Global Disk Layout](docs/config/layout-cluster.en.md)
+    - [OSD Disk Layout](docs/config/layout-osd.en.md)
+    - [OSD Runtime Parameters](docs/config/osd.en.md)
+    - [Monitor](docs/config/monitor.en.md)
+  - [Pool configuration](docs/config/pool.en.md)
+  - [Image metadata in etcd](docs/config/inode.en.md)
+- Usage
+  - [vitastor-cli](docs/usage/cli.en.md) (command-line interface)
+  - [fio](docs/usage/fio.en.md) for benchmarks
+  - [NBD](docs/usage/nbd.en.md) for kernel mounts
+  - [QEMU and qemu-img](docs/usage/qemu.en.md)
+  - [NFS](docs/usage/nfs.en.md) emulator for VMWare and similar
+- Performance
+  - [Understanding storage performance](docs/performance/understanding.en.md)
+  - [Theoretical performance](docs/performance/theoretical.en.md)
+  - [Example comparison with Ceph](docs/performance/comparison1.en.md)
 
 ## Author and License
 

cpp-btree

@@ -1 +1 @@
-Subproject commit 5dc108754ad40d3b1d024f9bd7cca0595ef1a1db
+Subproject commit 45e6d1f13196a0824e2089a586c53b9de0283f17

csi/Makefile

@@ -1,4 +1,4 @@
-VERSION ?= v0.6.10
+VERSION ?= v0.6.17
 
 all: build push
 

csi/deploy/004-csi-nodeplugin.yaml

@@ -49,7 +49,7 @@ spec:
             capabilities:
               add: ["SYS_ADMIN"]
             allowPrivilegeEscalation: true
-          image: vitalif/vitastor-csi:v0.6.10
+          image: vitalif/vitastor-csi:v0.6.17
           args:
             - "--node=$(NODE_ID)"
             - "--endpoint=$(CSI_ENDPOINT)"

csi/deploy/007-csi-provisioner.yaml

@@ -116,7 +116,7 @@ spec:
             privileged: true
             capabilities:
               add: ["SYS_ADMIN"]
-          image: vitalif/vitastor-csi:v0.6.10
+          image: vitalif/vitastor-csi:v0.6.17
           args:
             - "--node=$(NODE_ID)"
             - "--endpoint=$(CSI_ENDPOINT)"

csi/deploy/example-pvc-block.yaml

@@ -0,0 +1,13 @@
+---
+apiVersion: v1
+kind: PersistentVolumeClaim
+metadata:
+  name: test-vitastor-pvc-block
+spec:
+  storageClassName: vitastor
+  volumeMode: Block
+  accessModes:
+    - ReadWriteMany
+  resources:
+    requests:
+      storage: 10Gi

csi/deploy/example-test-pod-block.yaml

@@ -0,0 +1,17 @@
+apiVersion: v1
+kind: Pod
+metadata:
+  name: vitastor-test-block-pvc
+  namespace: default
+spec:
+  containers:
+  - name: vitastor-test-block-pvc
+    image: nginx
+    volumeDevices:
+      - name: data
+        devicePath: /dev/xvda
+  volumes:
+  - name: data
+    persistentVolumeClaim:
+      claimName: test-vitastor-pvc-block
+      readOnly: false

csi/deploy/example-test-pod.yaml

@@ -0,0 +1,17 @@
+apiVersion: v1
+kind: Pod
+metadata:
+  name: vitastor-test-nginx
+  namespace: default
+spec:
+  containers:
+   - name: vitastor-test-nginx
+     image: nginx
+     volumeMounts:
+       - mountPath: /usr/share/nginx/html/s3
+         name: data
+  volumes:
+   - name: data
+     persistentVolumeClaim:
+       claimName: test-vitastor-pvc
+       readOnly: false

csi/src/config.go

@@ -5,7 +5,7 @@ package vitastor
 
 const (
     vitastorCSIDriverName    = "csi.vitastor.io"
-    vitastorCSIDriverVersion = "0.6.10"
+    vitastorCSIDriverVersion = "0.6.17"
 )
 
 // Config struct fills the parameters of request or user input

csi/src/nodeserver.go

@@ -67,29 +67,44 @@ func (ns *NodeServer) NodePublishVolume(ctx context.Context, req *csi.NodePublis
     klog.Infof("received node publish volume request %+v", protosanitizer.StripSecrets(req))
 
     targetPath := req.GetTargetPath()
+    isBlock := req.GetVolumeCapability().GetBlock() != nil
 
     // Check that it's not already mounted
-    free, error := mount.IsNotMountPoint(ns.mounter, targetPath)
+    _, error := mount.IsNotMountPoint(ns.mounter, targetPath)
     if (error != nil)
     {
         if (os.IsNotExist(error))
         {
-            error := os.MkdirAll(targetPath, 0777)
-            if (error != nil)
+            if (isBlock)
             {
-                return nil, status.Error(codes.Internal, error.Error())
+                pathFile, err := os.OpenFile(targetPath, os.O_CREATE|os.O_RDWR, 0o600)
+                if (err != nil)
+                {
+                    klog.Errorf("failed to create block device mount target %s with error: %v", targetPath, err)
+                    return nil, status.Error(codes.Internal, err.Error())
+                }
+                err = pathFile.Close()
+                if (err != nil)
+                {
+                    klog.Errorf("failed to close %s with error: %v", targetPath, err)
+                    return nil, status.Error(codes.Internal, err.Error())
+                }
+            }
+            else
+            {
+                err := os.MkdirAll(targetPath, 0777)
+                if (err != nil)
+                {
+                    klog.Errorf("failed to create fs mount target %s with error: %v", targetPath, err)
+                    return nil, status.Error(codes.Internal, err.Error())
+                }
             }
-            free = true
         }
         else
         {
             return nil, status.Error(codes.Internal, error.Error())
         }
     }
-    if (!free)
-    {
-        return &csi.NodePublishVolumeResponse{}, nil
-    }
 
     ctxVars := make(map[string]string)
     err := json.Unmarshal([]byte(req.VolumeId), &ctxVars)
@@ -149,7 +164,6 @@ func (ns *NodeServer) NodePublishVolume(ctx context.Context, req *csi.NodePublis
 
     // Format the device (ext4 or xfs)
     fsType := req.GetVolumeCapability().GetMount().GetFsType()
-    isBlock := req.GetVolumeCapability().GetBlock() != nil
     opt := req.GetVolumeCapability().GetMount().GetMountFlags()
     opt = append(opt, "_netdev")
     if ((req.VolumeCapability.AccessMode.Mode == csi.VolumeCapability_AccessMode_MULTI_NODE_READER_ONLY ||

debian/changelog

@@ -1,4 +1,4 @@
-vitastor (0.6.10-1) unstable; urgency=medium
+vitastor (0.6.17-1) unstable; urgency=medium
 
   * RDMA support
   * Bugfixes

debian/vitastor-client.install

@@ -2,5 +2,6 @@ usr/bin/vita
 usr/bin/vitastor-cli
 usr/bin/vitastor-rm
 usr/bin/vitastor-nbd
+usr/bin/vitastor-nfs
 usr/lib/*/libvitastor*.so*
 mon/make-osd.sh /usr/lib/vitastor

debian/vitastor.Dockerfile

@@ -33,8 +33,8 @@ RUN set -e -x; \
     mkdir -p /root/packages/vitastor-$REL; \
     rm -rf /root/packages/vitastor-$REL/*; \
     cd /root/packages/vitastor-$REL; \
-    cp -r /root/vitastor vitastor-0.6.10; \
-    cd vitastor-0.6.10; \
+    cp -r /root/vitastor vitastor-0.6.17; \
+    cd vitastor-0.6.17; \
     ln -s /root/fio-build/fio-*/ ./fio; \
     FIO=$(head -n1 fio/debian/changelog | perl -pe 's/^.*\((.*?)\).*$/$1/'); \
     ls /usr/include/linux/raw.h || cp ./debian/raw.h /usr/include/linux/raw.h; \
@@ -47,8 +47,8 @@ RUN set -e -x; \
     rm -rf a b; \
     echo "dep:fio=$FIO" > debian/fio_version; \
     cd /root/packages/vitastor-$REL; \
-    tar --sort=name --mtime='2020-01-01' --owner=0 --group=0 --exclude=debian -cJf vitastor_0.6.10.orig.tar.xz vitastor-0.6.10; \
-    cd vitastor-0.6.10; \
+    tar --sort=name --mtime='2020-01-01' --owner=0 --group=0 --exclude=debian -cJf vitastor_0.6.17.orig.tar.xz vitastor-0.6.17; \
+    cd vitastor-0.6.17; \
     V=$(head -n1 debian/changelog | perl -pe 's/^.*\((.*?)\).*$/$1/'); \
     DEBFULLNAME="Vitaliy Filippov <vitalif@yourcmc.ru>" dch -D $REL -v "$V""$REL" "Rebuild for $REL"; \
     DEB_BUILD_OPTIONS=nocheck dpkg-buildpackage --jobs=auto -sa; \

docs/config.en.md

@@ -0,0 +1,37 @@
+[Documentation](../README.md#documentation) → Configuration Reference
+
+-----
+
+[Читать на русском](config.ru.md)
+
+# Configuration Reference
+
+Vitastor configuration consists of:
+- [Configuration parameters (key-value)](#parameter-reference)
+- [Pool configuration](config/pool.en.md)
+- [OSD placement tree configuration](config/pool.en.md#placement-tree)
+- [Separate OSD settings](config/pool.en.md#osd-settings)
+- [Inode configuration](config/inode.en.md) 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>`.
+
+## 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)

docs/config.ru.md

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

docs/config/common.en.md

@@ -0,0 +1,46 @@
+[Documentation](../../README.md#documentation) → [Configuration](../config.en.md) → Common Parameters
+
+-----
+
+[Читать на русском](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,45 @@
+[Документация](../../README-ru.md#документация) → [Конфигурация](../config.ru.md) → Общие параметры
+
+-----
+
+[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/inode.en.md

@@ -0,0 +1,32 @@
+[Documentation](../../README.md#documentation) → [Configuration](../config.en.md) → Image metadata in etcd
+
+-----
+
+[Читать на русском](inode.ru.md)
+
+# Image metadata in etcd
+
+Image list is stored in etcd in `/vitastor/config/inode/<pool>/<inode>` keys.
+
+You can even create images manually:
+
+```
+etcdctl --endpoints=<etcd> put /vitastor/config/inode/<pool>/<inode> '{"name":"<name>","size":<size>[,"parent_id":<parent_inode_number>][,"readonly":true]}'
+```
+
+For example:
+
+```
+etcdctl --endpoints=http://10.115.0.10:2379/v3 put /vitastor/config/inode/1/1 '{"name":"testimg","size":2147483648}'
+```
+
+If you specify parent_id the image becomes a CoW clone. I.e. all writes go to the new inode and reads first check it
+and then upper layers. You can then make parent readonly by updating its entry with `"readonly":true` for safety and
+basically treat it as a snapshot.
+
+So to create a snapshot you basically rename the previous upper layer (for example from testimg to testimg@0), make it readonly
+and create a new top layer with the original name (testimg) and the previous one as a parent.
+
+vitastor-cli, K8s, OpenStack and other drivers also store the reverse mapping in `/vitastor/index/image/<name>` keys
+in JSON format: `{"id":<inode>,"pool_id":<pool>}` and ID counters in `/vitastor/index/maxid/<pool>` as numbers
+to simplify ID generation.

docs/config/inode.ru.md

@@ -0,0 +1,34 @@
+[Документация](../../README-ru.md#документация) → [Конфигурация](../config.ru.md) → Метаданные образов в etcd
+
+-----
+
+[Read in English](inode.en.md)
+
+# Метаданные образов в etcd
+
+Список образов хранится в etcd в ключах `/vitastor/config/inode/<pool>/<inode>`.
+
+Вы можете даже создавать образы вручную:
+
+```
+etcdctl --endpoints=<etcd> put /vitastor/config/inode/<pool>/<inode> '{"name":"<name>","size":<size>[,"parent_id":<parent_inode_number>][,"readonly":true]}'
+```
+
+Например:
+
+```
+etcdctl --endpoints=http://10.115.0.10:2379/v3 put /vitastor/config/inode/1/1 '{"name":"testimg","size":2147483648}'
+```
+
+Если вы зададите parent_id, то образ станет CoW-клоном, т.е. все новые запросы записи пойдут в новый инод, а запросы
+чтения будут проверять сначала его, а потом родительские слои по цепочке вверх. Чтобы случайно не перезаписать данные
+в родительском слое, вы можете переключить его в режим "только чтение", добавив флаг `"readonly":true` в его запись
+метаданных. В таком случае родительский образ становится просто снапшотом.
+
+Таким образом, для создания снапшота вам нужно просто переименовать предыдущий inode (например, из testimg в testimg@0),
+сделать его readonly и создать новый слой с исходным именем образа (testimg), ссылающийся на только что переименованный
+в качестве родительского.
+
+vitastor-cli и драйвера K8s, OpenStack и т.п. также хранят обратный маппинг в ключах `/vitastor/index/image/<name>`
+в JSON-формате: `{"id":<inode>,"pool_id":<pool>}` и счётчики ID `/vitastor/index/maxid/<pool>` в виде просто чисел
+для упрощения генерации ID новых образов.

docs/config/layout-cluster.en.md

@@ -0,0 +1,124 @@
+[Documentation](../../README.md#documentation) → [Configuration](../config.en.md) → Cluster-Wide Disk Layout Parameters
+
+-----
+
+[Читать на русском](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,134 @@
+[Документация](../../README-ru.md#документация) → [Конфигурация](../config.ru.md) → Дисковые параметры уровня кластера
+
+-----
+
+[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,176 @@
+[Documentation](../../README.md#documentation) → [Configuration](../config.en.md) → OSD Disk Layout Parameters
+
+-----
+
+[Читать на русском](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. By default, all available space between journal_offset
+and data_offset, meta_offset or the end of the journal device is used.
+Large journals aren't needed in SSD-only setups, 32 MB is always enough.
+In SSD+HDD setups it is beneficial to use larger journals (for example, 1 GB)
+and enable [throttle_small_writes](osd.en.md#throttle_small_writes).
+
+## 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,185 @@
+[Документация](../../README-ru.md#документация) → [Конфигурация](../config.ru.md) → Дисковые параметры OSD
+
+-----
+
+[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
+
+- Тип: целое число
+
+Размер журнала в байтах. По умолчанию для журнала используется всё доступное
+место между journal_offset и data_offset, meta_offset или концом диска.
+В SSD-кластерах большие журналы не нужны, достаточно 32 МБ. В гибридных
+(SSD+HDD) кластерах осмысленно использовать больший размер журнал (например, 1 ГБ)
+и включить [throttle_small_writes](osd.ru.md#throttle_small_writes).
+
+## 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,79 @@
+[Documentation](../../README.md#documentation) → [Configuration](../config.en.md) → Monitor Parameters
+
+-----
+
+[Читать на русском](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,80 @@
+[Документация](../../README-ru.md#документация) → [Конфигурация](../config.ru.md) → Параметры мониторов
+
+-----
+
+[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,214 @@
+[Documentation](../../README.md#documentation) → [Configuration](../config.en.md) → Network Protocol Parameters
+
+-----
+
+[Читать на русском](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. TCP-only clients can also talk to an RDMA-enabled
+cluster, so disabling RDMA may be needed if clients have RDMA devices,
+but they are not connected to the cluster.
+
+## 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,224 @@
+[Документация](../../README-ru.md#документация) → [Конфигурация](../config.ru.md) → Параметры сетевого протокола
+
+-----
+
+[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.
+TCP-клиенты также могут работать с RDMA-кластером, так что отключать
+RDMA может быть нужно только если у клиентов есть RDMA-устройства,
+но они не имеют соединения с кластером Vitastor.
+
+## 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,297 @@
+[Documentation](../../README.md#documentation) → [Configuration](../config.en.md) → Runtime OSD Parameters
+
+-----
+
+[Читать на русском](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,310 @@
+[Документация](../../README-ru.md#документация) → [Конфигурация](../config.ru.md) → Изменяемые параметры OSD
+
+-----
+
+[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
+
+- Тип: булево (да/нет)
+- Значение по умолчанию: false
+
+Отключить автоматическое фоновое восстановление объектов. Обратите внимание,
+что эта опция не отключает восстановление объектов, происходящее при
+записи - запись всегда производится в полный набор из как минимум pg_minsize
+OSD.
+
+## no_rebalance
+
+- Тип: булево (да/нет)
+- Значение по умолчанию: false
+
+Отключить фоновое перемещение объектов между разными OSD. Отключение
+означает, что PG, находящиеся в состоянии `has_misplaced`, будут оставлены
+в нём на неопределённый срок.
+
+## print_stats_interval
+
+- Тип: секунды
+- Значение по умолчанию: 3
+
+Временной интервал, с которым OSD печатают простую человекочитаемую
+статистику выполнения операций в стандартный вывод.
+
+## slow_log_interval
+
+- Тип: секунды
+- Значение по умолчанию: 10
+
+Временной интервал, с которым OSD выводят в стандартный вывод список
+медленных или зависших операций, если таковые имеются. Также время, при
+превышении которого операция считается "медленной".
+
+## max_write_iodepth
+
+- Тип: целое число
+- Значение по умолчанию: 128
+
+Максимальное число одновременных клиентских операций записи на один OSD.
+Операции, превышающие этот лимит, не исполняются сразу, а сохраняются во
+временной очереди.
+
+## min_flusher_count
+
+- Тип: целое число
+- Значение по умолчанию: 1
+
+Flusher - это микро-поток (корутина), которая копирует данные из журнала в
+основную область устройства данных. Их число настраивается динамически между
+минимальным и максимальным значением. Этот параметр задаёт минимальное число.
+
+## max_flusher_count
+
+- Тип: целое число
+- Значение по умолчанию: 256
+
+Максимальное число микро-потоков очистки журнала (см. выше min_flusher_count).
+
+## inmemory_metadata
+
+- Тип: булево (да/нет)
+- Значение по умолчанию: true
+
+Данный параметр заставляет Vitastor всегда держать область метаданных диска
+в памяти. Это нужно, чтобы избегать дополнительных операций чтения с диска
+при записи. Размер области метаданных на данный момент составляет примерно
+224 МБ на 1 ТБ данных. При включении потребление памяти снизится примерно
+на эту величину, но при этом также снизится и производительность. В будущем,
+после обновления схемы хранения метаданных, это ограничение, скорее всего,
+будет ликвидировано.
+
+## inmemory_journal
+
+- Тип: булево (да/нет)
+- Значение по умолчанию: true
+
+Данный параметр заставляет Vitastor всегда держать в памяти журналы OSD.
+Отключение параметра, опять же, снижает потребление памяти, но ухудшает
+производительность, так как для копирования данных из журнала в основную
+область устройства OSD будут вынуждены читать их обратно с диска. Выигрыш
+по памяти при этом обычно крайне низкий, так как для SSD OSD обычно
+достаточно 16- или 32-мегабайтного журнала. Однако в теории отключение
+параметра может оказаться полезным для гибридных OSD (HDD+SSD) с большими
+журналами, расположенными на быстром по сравнению с HDD устройстве.
+
+## journal_sector_buffer_count
+
+- Тип: целое число
+- Значение по умолчанию: 32
+
+Максимальное число буферов, разрешённых для использования под записываемые
+в журнал блоки метаданных. Единственная ситуация, в которой этот параметр
+нужно менять - это если вы включаете journal_no_same_sector_overwrites. В
+этом случае установите данный параметр, например, в 1024.
+
+## journal_no_same_sector_overwrites
+
+- Тип: булево (да/нет)
+- Значение по умолчанию: false
+
+Включайте данную опцию для SSD вроде Intel D3-S4510 и D3-S4610, которые
+ОЧЕНЬ не любят, когда ПО перезаписывает один и тот же сектор несколько раз
+подряд. Такие SSD при многократной перезаписи одного и того же сектора
+сильно замедляются - условно, с 25000 и более iops до 3000 iops. Когда
+данная опция установлена, Vitastor всегда переходит к следующему сектору
+журнала после записи вместо потенциально повторной перезаписи того же
+самого сектора.
+
+Почти все другие SSD (99% моделей) не требуют данной опции.
+
+## throttle_small_writes
+
+- Тип: булево (да/нет)
+- Значение по умолчанию: false
+
+Разрешить мягкое ограничение скорости журналируемой записи. Полезно для
+гибридных OSD с быстрыми устройствами метаданных и медленными устройствами
+данных. Идея заключается в том, что мелкие записи в этой ситуации могут
+завершаться очень быстро, так как они изначально записываются на быстрое
+журнальное устройство (SSD). Но перемещать их потом на основное медленное
+устройство долго. Поэтому если OSD быстро примет от клиентов очень много
+мелких операций записи, он быстро заполнит свой журнал, после чего
+производительность записи резко упадёт практически до нуля. Ограничение
+скорости записи призвано решить эту проблему с помощью искусственного
+замедления операций записи на основании объёма свободного места в журнале.
+Когда эта опция включена, производительность мелких операций записи будет
+снижаться плавно, а не резко в момент окончательного заполнения журнала.
+
+## throttle_target_iops
+
+- Тип: целое число
+- Значение по умолчанию: 100
+
+Расчётное максимальное число ограничиваемых операций в секунду при условии
+отсутствия свободного места в журнале. Устанавливайте приблизительно равным
+максимальной производительности случайной записи ваших устройств данных
+(HDD) в операциях в секунду.
+
+## throttle_target_mbs
+
+- Тип: целое число
+- Значение по умолчанию: 100
+
+Расчётный максимальный размер в МБ/с ограничиваемых операций в секунду при
+условии отсутствия свободного места в журнале. Устанавливайте приблизительно
+равным максимальной производительности линейной записи ваших устройств
+данных (HDD).
+
+## throttle_target_parallelism
+
+- Тип: целое число
+- Значение по умолчанию: 1
+
+Расчётный максимальный параллелизм ограничиваемых операций в секунду при
+условии отсутствия свободного места в журнале. Устанавливайте приблизительно
+равным внутреннему параллелизму ваших устройств данных (1 для HDD, 4-8
+для SSD).
+
+## throttle_threshold_us
+
+- Тип: микросекунды
+- Значение по умолчанию: 50
+
+Минимальная применимая к ограничиваемым операциям задержка. Обычно не
+требует изменений.
+
+## osd_memlock
+
+- Тип: булево (да/нет)
+- Значение по умолчанию: false
+
+Блокировать всю память OSD с помощью mlockall, чтобы запретить её выгрузку в пространство подкачки. Требует достаточного значения ulimit -l (лимита заблокированной памяти).

docs/config/pool.en.md

@@ -0,0 +1,254 @@
+[Documentation](../../README.md#documentation) → [Configuration](../config.en.md) → Pool configuration
+
+-----
+
+[Читать на русском](pool.ru.md)
+
+# Pool configuration
+
+Pool configuration is set in etcd key `/vitastor/config/pools` in the following
+JSON format:
+
+```
+{
+  "<Numeric ID>": {
+    "name": "<name>",
+    ...other parameters...
+  }
+}
+```
+
+Pool configuration is also affected by:
+
+- [OSD Placement Tree](#placement-tree)
+- [Separate OSD settings](#osd-settings)
+
+Parameters:
+
+- [name](#name)
+- [scheme](#scheme)
+- [pg_size](#pg_size)
+- [parity_chunks](#parity_chunks)
+- [pg_minsize](#pg_minsize)
+- [pg_count](#pg_count)
+- [failure_domain](#failure_domain)
+- [max_osd_combinations](#max_osd_combinations)
+- [pg_stripe_size](#pg_stripe_size)
+- [root_node](#root_node)
+- [osd_tags](#osd_tags)
+- [primary_affinity_tags](#primary_affinity_tags)
+
+Examples:
+
+- [Replicated Pool](#replicated-pool)
+- [Erasure-coded Pool](#erasure-coded-pool)
+
+# Placement Tree
+
+OSD placement tree is set in a separate etcd key `/vitastor/config/node_placement`
+in the following JSON format:
+
+`
+{
+  "<node name or OSD number>": {
+    "level": "<level>",
+    "parent": "<parent node name, if any>"
+  },
+  ...
+}
+`
+
+Here, if a node name is a number then it is assumed to refer to an OSD.
+Level of the OSD is always "osd" and cannot be overriden. You may only
+override parent node of the OSD which is its host by default.
+
+Non-numeric node names refer to other placement tree nodes like hosts, racks,
+datacenters and so on.
+
+Hosts of all OSDs are auto-created in the tree with level "host" and name
+equal to the host name reported by a corresponding OSD. You can refer to them
+without adding them to this JSON tree manually.
+
+Level may be "host", "osd" or refer to some other placement tree level
+from [placement_levels](monitor.en.md#placement_levels).
+
+Parent node reference is required for intermediate tree nodes.
+
+# OSD settings
+
+Separate OSD settings are set in etc keys `/vitastor/config/osd/<number>`
+in JSON format `{"<key>":<value>}`.
+
+As of now, there is only one setting:
+
+## reweight
+
+- Type: number, between 0 and 1
+- Default: 1
+
+Every OSD receives PGs proportional to its size. Reweight is a multiplier for
+OSD size used during PG distribution.
+
+This means an OSD configured with reweight lower than 1 receives less PGs than
+it normally would. An OSD with reweight = 0 won't store any data. You can set
+reweight to 0 to trigger rebalance and remove all data from an OSD.
+
+# Pool parameters
+
+## name
+
+- Type: string
+- Required
+
+Pool name.
+
+## scheme
+
+- Type: string
+- Required
+- One of: "replicated", "xor" or "jerasure"
+
+Redundancy scheme used for data in this pool.
+
+## pg_size
+
+- Type: integer
+- Required
+
+Total number of disks for PGs of this pool - i.e., number of replicas for
+replicated pools and number of data plus parity disks for EC/XOR pools.
+
+## parity_chunks
+
+- Type: integer
+
+Number of parity chunks for EC/XOR pools. For such pools, data will be lost
+if you lose more than parity_chunks disks at once, so this parameter can be
+equally described as FTT (number of failures to tolerate).
+
+Required for EC/XOR pools, ignored for replicated pools.
+
+## pg_minsize
+
+- Type: integer
+- Required
+
+Number of available live disks for PGs of this pool to remain active.
+That is, if it becomes impossible to place PG data on at least (pg_minsize)
+OSDs, PG is deactivated for both read and write. So you know that a fresh
+write always goes to at least (pg_minsize) OSDs (disks).
+
+FIXME: pg_minsize behaviour may be changed in the future to only make PGs
+read-only instead of deactivating them.
+
+## pg_count
+
+- Type: integer
+- Required
+
+Number of PGs for this pool. The value should be big enough for the monitor /
+LP solver to be able to optimize data placement.
+
+"Enough" is usually around 64-128 PGs per OSD, i.e. you set pg_count for pool
+to (total OSD count * 100 / pg_size). You can round it to the closest power of 2,
+because it makes it easier to reduce or increase PG count later by dividing or
+multiplying it by 2.
+
+In Vitastor, PGs are ephemeral, so you can change pool PG count anytime just
+by overwriting pool configuration in etcd. Amount of the data affected by
+rebalance will be smaller if the new PG count is a multiple of the old PG count
+or vice versa.
+
+## failure_domain
+
+- Type: string
+- Default: host
+
+Failure domain specification. Must be "host" or "osd" or refer to one of the
+placement tree levels, defined in [placement_levels](monitor.en.md#placement_levels).
+
+Two replicas, or two parts in case of EC/XOR, of the same block of data are
+never put on OSDs in the same failure domain (for example, on the same host).
+So failure domain specifies the unit which failure you are protecting yourself
+from.
+
+## max_osd_combinations
+
+- Type: integer
+- Default: 10000
+
+Vitastor data placement algorithm is based on the LP solver and OSD combinations
+which are fed to it are generated ramdonly. This parameter specifies the maximum
+number of combinations to generate when optimising PG placement.
+
+This parameter usually doesn't require to be changed.
+
+## pg_stripe_size
+
+- Type: integer
+- Default: 0
+
+Specifies the stripe size for this pool according to which images are split into
+different PGs. Stripe size can't be smaller than [block_size](layout-cluster.en.md#block_size)
+multiplied by (pg_size - parity_chunks) for EC/XOR pools, or 1 for replicated pools,
+and the same value is used by default.
+
+This means first `pg_stripe_size = (block_size * (pg_size-parity_chunks))` bytes
+of an image go to one PG, next `pg_stripe_size` bytes go to another PG and so on.
+
+Usually doesn't require to be changed separately from the block size.
+
+## root_node
+
+- Type: string
+
+Specifies the root node of the OSD tree to restrict this pool OSDs to.
+Referenced root node must exist in /vitastor/config/node_placement.
+
+## osd_tags
+
+- Type: string or array of strings
+
+Specifies OSD tags to restrict this pool to. If multiple tags are specified,
+only OSDs having all of these tags will be used for this pool.
+
+## primary_affinity_tags
+
+- Type: string or array of strings
+
+Specifies OSD tags to prefer putting primary OSDs in this pool to.
+Note that for EC/XOR pools Vitastor always prefers to put primary OSD on one
+of the OSDs containing a data chunk for a PG.
+
+# Examples
+
+## Replicated pool
+
+```
+{
+  "1": {
+    "name":"testpool",
+    "scheme":"replicated",
+    "pg_size":2,
+    "pg_minsize":1,
+    "pg_count":256,
+    "failure_domain":"host"
+  }
+}
+```
+
+## Erasure-coded pool
+
+```
+{
+  "2": {
+    "name":"ecpool",
+    "scheme":"jerasure",
+    "pg_size":3,
+    "parity_chunks":1,
+    "pg_minsize":2,
+    "pg_count":256,
+    "failure_domain":"host"
+  }
+}
+```

docs/config/pool.ru.md

@@ -0,0 +1,253 @@
+[Документация](../../README-ru.md#документация) → [Конфигурация](../config.ru.md) → Конфигурация пулов
+
+-----
+
+[Read in English](pool.en.md)
+
+# Конфигурация пулов
+
+Настройки пулов задаются в ключе etcd `/vitastor/config/pools` в JSON-формате:
+
+```
+{
+  "<Численный ID>": {
+    "name": "<имя>",
+    ...остальные параметры...
+  }
+}
+```
+
+На настройку пулов также влияют:
+
+- [Дерево размещения OSD](#дерево-размещения)
+- [Настройки отдельных OSD](#настройки-osd)
+
+Параметры:
+
+- [name](#name)
+- [scheme](#scheme)
+- [pg_size](#pg_size)
+- [parity_chunks](#parity_chunks)
+- [pg_minsize](#pg_minsize)
+- [pg_count](#pg_count)
+- [failure_domain](#failure_domain)
+- [max_osd_combinations](#max_osd_combinations)
+- [pg_stripe_size](#pg_stripe_size)
+- [root_node](#root_node)
+- [osd_tags](#osd_tags)
+- [primary_affinity_tags](#primary_affinity_tags)
+
+Примеры:
+
+- [Реплицированный пул](#реплицированный-пул)
+- [Пул с кодами коррекции ошибок 2+1](#пул-с-кодами-коррекции-ошибок)
+
+# Дерево размещения
+
+Дерево размещения OSD задаётся в отдельном ключе etcd `/vitastor/config/node_placement`
+в следующем JSON-формате:
+
+`
+{
+  "<имя узла или номер OSD>": {
+    "level": "<уровень>",
+    "parent": "<имя родительского узла, если есть>"
+  },
+  ...
+}
+`
+
+Здесь, если название узла - число, считается, что это OSD. Уровень OSD
+всегда равен "osd" и не может быть переопределён. Для OSD вы можете только
+переопределить родительский узел. По умолчанию родителем OSD считается его хост.
+
+Нечисловые имена узлов относятся к другим узлам дерева OSD, таким, как хосты (серверы),
+стойки, датацентры и так далее.
+
+Хосты всех OSD автоматически создаются в дереве с уровнем "host" и именем, равным имени хоста,
+сообщаемым соответствующим OSD. Вы можете ссылаться на эти хосты, не заводя их
+в дереве вручную.
+
+Уровень может быть "host", "osd" или относиться к другому уровню размещения из
+[placement_levels](monitor.ru.md#placement_levels).
+
+Родительский узел нужен только для промежуточных узлов дерева.
+
+# Настройки OSD
+
+Настройки отдельных OSD задаются в ключах etcd `/vitastor/config/osd/<number>`
+в JSON-формате `{"<key>":<value>}`.
+
+На данный момент поддерживается одна настройка:
+
+## reweight
+
+- Тип: число, от 0 до 1
+- По умолчанию: 1
+
+Каждый OSD получает число PG, пропорциональное его размеру. Reweight - это
+множитель для размера, используемый в процессе распределения PG.
+
+Это значит, что OSD, сконфигурированный с reweight меньше 1 будет получать
+меньше PG, чем обычно. OSD с reweight, равным 0, не будет участвовать в
+хранении данных вообще. Вы можете установить reweight в 0, чтобы убрать
+все данные с OSD.
+
+# Параметры
+
+## name
+
+- Тип: строка
+- Обязательный
+
+Название пула.
+
+## scheme
+
+- Тип: строка
+- Обязательный
+- Возможные значения: "replicated", "xor" или "jerasure"
+
+Схема избыточности, используемая в данном пуле.
+
+## pg_size
+
+- Тип: целое число
+- Обязательный
+
+Размер PG данного пула, т.е. число реплик для реплицированных пулов или
+число дисков данных плюс дисков чётности для пулов EC/XOR.
+
+## parity_chunks
+
+- Тип: целое число
+
+Число дисков чётности для EC/XOR пулов. Иными словами, число дисков, при
+одновременной потере которых данные будут потеряны.
+
+Игнорируется для реплицированных пулов, обязательно для EC/XOR.
+
+## pg_minsize
+
+- Тип: целое число
+- Обязательный
+
+Число доступных дисков для PG данного пула, при котором PG остаются активны.
+Если становится невозможно размещать новые данные в PG как минимум на pg_minsize
+OSD, PG деактивируется на чтение и запись. Иными словами, всегда известно,
+что новые блоки данных всегда записываются как минимум на pg_minsize дисков.
+
+FIXME: Поведение pg_minsize может быть изменено в будущем с полной деактивации
+PG на перевод их в режим только для чтения.
+
+## pg_count
+
+- Тип: целое число
+- Обязательный
+
+Число PG для данного пула. Число должно быть достаточно большим, чтобы монитор
+мог равномерно распределить по ним данные.
+
+Обычно это означает примерно 64-128 PG на 1 OSD, т.е. pg_count можно устанавливать
+равным (общему числу OSD * 100 / pg_size). Значение можно округлить до ближайшей
+степени 2, чтобы потом было легче уменьшать или увеличивать число PG, умножая
+или деля его на 2.
+
+PG в Vitastor эферемерны, то есть вы можете менять их число в любой момент,
+просто перезаписывая конфигурацию пулов в etcd. Однако объём перемещения данных
+при этом будет минимален, если новое число PG кратно старому (или наоборот).
+
+## failure_domain
+
+- Тип: строка
+- По умолчанию: host
+
+Домен отказа для пула. Может быть равен "host" или "osd" или любому другому
+уровню дерева OSD, задаваемому в настройке [placement_levels](monitor.ru.md#placement_levels).
+
+Смысл домена отказа в том, что 2 копии, или 2 части одного блока данных в случае
+кодов коррекции ошибок, никогда не помещаются на OSD, принадлежащие одному домену отказа.
+Иными словами, домен отказа - это то, от отказа чего вы защищаете себя избыточным
+хранением.
+
+## max_osd_combinations
+
+- Тип: целое число
+- По умолчанию: 10000
+
+Алгоритм распределения данных Vitastor основан на решателе задачи линейного
+программирования. При этом для снижения сложности задачи возможные комбинации OSD
+генерируются случайно и ограничиваются количеством, равным значению этого параметра.
+
+Обычно данный параметр не требует изменений.
+
+## pg_stripe_size
+
+- Тип: целое число
+- По умолчанию: 0
+
+Данный параметр задаёт размер полосы "нарезки" образов на PG. Размер полосы не может
+быть меньше, чем [block_size](layout-cluster.ru.md#block_size), умноженный на
+(pg_size - parity_chunks) для EC-пулов или 1 для реплицированных пулов. То же
+значение используется по умолчанию.
+
+Это означает, что по умолчанию первые `pg_stripe_size = (block_size * (pg_size-parity_chunks))` байт
+образа помещаются в одну PG, следующие `pg_stripe_size` байт помещаются в другую
+и т.п.
+
+Данный параметр обычно тоже не требует изменений.
+
+## root_node
+
+- Тип: строка
+
+Корневой узел дерева OSD для ограничения OSD, выбираемых для пула. Задаваемый
+узел должен быть предварительно задан в /vitastor/config/node_placement.
+
+## osd_tags
+
+- Тип: строка или массив строк
+
+Теги OSD для ограничения OSD, выбираемых для пула. Если задаётся несколько тегов
+массивом, то выбираются только OSD, у которых есть все эти теги.
+
+## primary_affinity_tags
+
+- Тип: строка или массив строк
+
+Теги OSD, по которым должны выбираться OSD, предпочитаемые в качестве первичных
+для PG этого пула. Имейте в виду, что для EC-пулов Vitastor также всегда
+предпочитает помещать первичный OSD на один из OSD с данными, а не с чётностью.
+
+# Примеры
+
+## Реплицированный пул
+
+```
+{
+  "1": {
+    "name":"testpool",
+    "scheme":"replicated",
+    "pg_size":2,
+    "pg_minsize":1,
+    "pg_count":256,
+    "failure_domain":"host"
+  }
+}
+```
+
+## Пул с кодами коррекции ошибок
+
+```
+{
+  "2": {
+    "name":"ecpool",
+    "scheme":"jerasure",
+    "pg_size":3,
+    "parity_chunks":1,
+    "pg_minsize":2,
+    "pg_count":256,
+    "failure_domain":"host"
+  }
+}
+```

docs/config/src/common.en.md

@@ -0,0 +1,3 @@
+# Common Parameters
+
+These are the most common parameters which apply to all components of Vitastor.

docs/config/src/common.ru.md

@@ -0,0 +1,3 @@
+# Общие параметры
+
+Это наиболее общие параметры, используемые всеми компонентами Vitastor.

docs/config/src/common.yml

@@ -0,0 +1,35 @@
+- name: config_path
+  type: string
+  default: "/etc/vitastor/vitastor.conf"
+  info: |
+    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.
+  info_ru: |
+    Путь к файлу конфигурации в формате JSON. Файл конфигурации необязателен,
+    без него Vitastor тоже будет работать, если переданы необходимые параметры.
+- name: etcd_address
+  type: string or array of strings
+  type_ru: строка или массив строк
+  info: |
+    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.
+  info_ru: |
+    Адрес(а) подключения к etcd. Несколько адресов могут разделяться запятой
+    или указываться в виде JSON-массива `["10.0.115.10:2379/v3","10.0.115.11:2379/v3"]`.
+- name: etcd_prefix
+  type: string
+  default: "/vitastor"
+  info: |
+    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. Вы можете задать другой
+    префикс, например, чтобы запустить несколько кластеров Vitastor с одним
+    кластером etcd.
+- name: log_level
+  type: int
+  default: 0
+  info: Log level. Raise if you want more verbose output.
+  info_ru: Уровень логгирования. Повысьте, если хотите более подробный вывод.

docs/config/src/layout-cluster.en.md

@@ -0,0 +1,4 @@
+# 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.

docs/config/src/layout-cluster.ru.md

@@ -0,0 +1,4 @@
+# Дисковые параметры уровня кластера
+
+Данные параметры используются клиентами и OSD, задаются в момент инициализации
+диска OSD и не могут быть изменены после этого без потери данных.

docs/config/src/layout-cluster.yml

@@ -0,0 +1,200 @@
+- name: block_size
+  type: int
+  default: 131072
+  info: |
+    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.
+  info_ru: |
+    Размер объектов (блоков данных), на которые делятся физические и виртуальные
+    диски в 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 КБ блоке.
+- name: bitmap_granularity
+  type: int
+  default: 4096
+  info: |
+    Required virtual disk write alignment ("sector size"). Must be a multiple
+    of disk_alignment. It's called bitmap granularity because Vitastor tracks
+    an allocation bitmap for each object containing 2 bits per each
+    (bitmap_granularity) bytes.
+
+    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
+  info: |
+    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.
+  info_ru: |
+    Ещё один важный для производительности параметр.
+
+    Модели 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". Если и какие-то из дисков журналов имеют волатильный кэш записи -
+    оставьте параметр пустым.
+- name: client_dirty_limit
+  type: int
+  default: 33554432
+  info: |
+    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.
+  info_ru: |
+    При работе без immediate_commit=all - это лимит объёма "грязных" (не
+    зафиксированных fsync-ом) данных, при достижении которого клиент будет
+    принудительно вызывать fsync и фиксировать данные. Также стоит иметь в виду,
+    что в этом случае до момента fsync клиент хранит копию незафиксированных
+    данных в памяти, то есть, настройка влияет на потребление памяти клиентами.
+
+    Параметр не влияет на сами OSD.

docs/config/src/layout-osd.en.md

@@ -0,0 +1,4 @@
+# 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.

docs/config/src/layout-osd.ru.md

@@ -0,0 +1,5 @@
+# Дисковые параметры OSD
+
+Данные параметры используются только OSD и, также как и общекластерные
+дисковые параметры, задаются в момент инициализации дисков OSD и не могут быть
+изменены после этого без потери данных.

docs/config/src/layout-osd.yml

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

@@ -0,0 +1,120 @@
+#!/usr/bin/nodejs
+
+const fs = require('fs');
+const yaml = require('yaml');
+
+const L = {
+    en: {
+        Documentation: 'Documentation',
+        Configuration: 'Configuration',
+        Crossref: 'Read in English',
+        toc_root: '[Documentation](../README.md#documentation)',
+        toc_intro: 'Introduction',
+        toc_installation: 'Installation',
+        toc_config: '[Configuration](../config.en.md)',
+        toc_usage: 'Usage',
+        toc_performance: 'Performance',
+    },
+    ru: {
+        Documentation: 'Документация',
+        Configuration: 'Конфигурация',
+        Type: 'Тип',
+        Default: 'Значение по умолчанию',
+        Minimum: 'Минимальное значение',
+        Crossref: 'Читать на русском',
+        toc_root: '[Документация](../README-ru.md#документация)',
+        toc_intro: 'Введение',
+        toc_installation: 'Установка',
+        toc_config: '[Конфигурация](../config.ru.md)',
+        toc_usage: 'Использование',
+        toc_performance: 'Производительность',
+    },
+};
+const types = {
+    en: {
+        string: 'string',
+        bool: 'boolean',
+        int: 'integer',
+        sec: 'seconds',
+        ms: 'milliseconds',
+        us: 'microseconds',
+    },
+    ru: {
+        string: 'строка',
+        bool: 'булево (да/нет)',
+        int: 'целое число',
+        sec: 'секунды',
+        ms: 'миллисекунды',
+        us: 'микросекунды',
+    },
+};
+const params_files = fs.readdirSync(__dirname)
+    .filter(f => f.substr(-4) == '.yml')
+    .map(f => f.substr(0, f.length-4));
+
+for (const file of params_files)
+{
+    const cfg = yaml.parse(fs.readFileSync(__dirname+'/'+file+'.yml', { encoding: 'utf-8' }));
+    for (const lang in types)
+    {
+        let out = '\n';
+        for (const c of cfg)
+        {
+            out += `\n- [${c.name}](#${c.name})`;
+        }
+        for (const c of cfg)
+        {
+            out += `\n\n## ${c.name}\n\n`;
+            out += `- ${L[lang]['Type'] || 'Type'}: ${c["type_"+lang] || types[lang][c.type] || c.type}\n`;
+            if (c.default !== undefined)
+                out += `- ${L[lang]['Default'] || 'Default'}: ${c.default}\n`;
+            if (c.min !== undefined)
+                out += `- ${L[lang]['Minimum'] || 'Minimum'}: ${c.min}\n`;
+            out += `\n`+(c["info_"+lang] || c["info"]).replace(/\s+$/, '');
+        }
+        const head = fs.readFileSync(__dirname+'/'+file+'.'+lang+'.md', { encoding: 'utf-8' });
+        out = head.replace(/\s+$/, '')+out+"\n";
+        fs.writeFileSync(__dirname+'/../'+file+'.'+lang+'.md', out);
+    }
+}
+
+// Add "Read in..." to all other documentation files
+
+for (const file of find_files(__dirname+'/../..', name => name.substr(-3) == '.md' && !/config\/src\//.exec(name)))
+{
+    const m = /^(?:(.*?)\/)?([^\/]+)\.([^\.]+)\.[^\.]+$/.exec(file);
+    if (!m)
+        continue;
+    const [ , subdir, filename, lang ] = m;
+    if (!L[lang])
+        continue;
+    let text = fs.readFileSync(__dirname+'/../../'+file, { encoding: 'utf-8' });
+    const title = /(^|\n)# ([^\n]+)/.exec(text)[2];
+    let read_in = Object.keys(L).filter(other => other != lang)
+        .map(other => `[${L[other].Crossref}](${filename}.${other}.md)`)
+        .join(' ')+'\n\n';
+    read_in = L[lang]['toc_root'].replace(/\.\.\//, subdir ? '../../' : '../')+' → '+
+        (subdir ? L[lang]['toc_'+subdir]+' → ' : '')+
+        title+'\n\n-----\n\n'+
+        read_in;
+    if (text.substr(0, read_in.length) != read_in)
+    {
+        fs.writeFileSync(__dirname+'/../../'+file, read_in + (text[0] == '#' ? text : text.replace(/^([\s\S]*?\n)?#/, '#')));
+    }
+}
+
+function find_files(dir, fn, subdir = '', res = [])
+{
+    for (const ent of fs.readdirSync(dir+'/'+subdir, { withFileTypes: true }))
+    {
+        if (ent.isDirectory())
+        {
+            find_files(dir, fn, subdir ? subdir+'/'+ent.name : ent.name, res);
+        }
+        else if (fn(subdir ? subdir+'/'+ent.name : ent.name, ent))
+        {
+            res.push(subdir ? subdir+'/'+ent.name : ent.name);
+        }
+    }
+    return res;
+}

docs/config/src/monitor.en.md

@@ -0,0 +1,3 @@
+# Monitor Parameters
+
+These parameters only apply to Monitors.

docs/config/src/monitor.ru.md

@@ -0,0 +1,3 @@
+# Параметры мониторов
+
+Данные параметры используются только мониторами Vitastor.

docs/config/src/monitor.yml

@@ -0,0 +1,65 @@
+- name: etcd_mon_ttl
+  type: sec
+  min: 10
+  default: 30
+  info: Monitor etcd lease refresh interval in seconds
+  info_ru: Интервал обновления etcd резервации (lease) монитором
+- name: etcd_mon_timeout
+  type: ms
+  default: 1000
+  info: etcd request timeout used by monitor
+  info_ru: Таймаут выполнения запросов к etcd от монитора
+- name: etcd_mon_retries
+  type: int
+  default: 5
+  info: Maximum number of attempts for one monitor etcd request
+  info_ru: Максимальное число попыток выполнения запросов к etcd монитором
+- name: mon_change_timeout
+  type: ms
+  min: 100
+  default: 1000
+  info: Optimistic retry interval for monitor etcd modification requests
+  info_ru: Время повтора при коллизиях при запросах модификации в etcd, производимых монитором
+- name: mon_stats_timeout
+  type: ms
+  min: 100
+  default: 1000
+  info: |
+    Interval for monitor to wait before updating aggregated statistics in
+    etcd after receiving OSD statistics updates
+  info_ru: |
+    Интервал, который монитор ожидает при изменении статистики по отдельным
+    OSD перед обновлением агрегированной статистики в etcd
+- name: osd_out_time
+  type: sec
+  default: 600
+  info: |
+    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.
+  info_ru: |
+    Время, через которое отключенный OSD исключается из распределения данных.
+    То есть, время, которое монитор ожидает перед попыткой переместить данные
+    на другие OSD и таким образом восстановить избыточность хранения.
+- name: placement_levels
+  type: json
+  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
+    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").
+  info_ru: |
+    Определения уровней для дерева размещения OSD. Вы можете определять
+    произвольные уровни, помещая их в данный параметр конфигурации. Значение
+    параметра должно содержать JSON-объект, ключи которого будут являться
+    названиями уровней, а значения - целочисленными приоритетами. Меньшие
+    приоритеты соответствуют верхним уровням дерева. Например, уровень
+    "датацентр" должен иметь меньший приоритет, чем "OSD". Уровни с названиями
+    "host" и "osd" являются предопределёнными и не могут быть удалены. Если
+    один из них отсутствует в конфигурации, он доопределяется с приоритетом по
+    умолчанию (100 для уровня "host", 101 для "osd").

docs/config/src/network.en.md

@@ -0,0 +1,4 @@
+# Network Protocol Parameters
+
+These parameters apply to clients and OSDs and affect network connection logic
+between clients, OSDs and etcd.

docs/config/src/network.ru.md

@@ -0,0 +1,4 @@
+# Параметры сетевого протокола
+
+Данные параметры используются клиентами и OSD и влияют на логику сетевого
+взаимодействия между клиентами, OSD, а также etcd.

docs/config/src/network.yml

@@ -0,0 +1,225 @@
+- name: tcp_header_buffer_size
+  type: int
+  default: 65536
+  info: |
+    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.
+  info_ru: |
+    Размер буфера для чтения данных с дополнительным копированием. Пакеты
+    Vitastor содержат 128-байтные заголовки, за которыми следуют данные размером
+    от 4 КБ и для мелких операций ввода-вывода обычно выгодно за 1 вызов читать
+    сразу несколько пакетов, даже не смотря на то, что это требует лишний раз
+    скопировать данные. Часть каждого пакета за пределами значения данного
+    параметра читается без дополнительного копирования. Вы можете попробовать
+    поменять этот параметр и посмотреть, как он влияет на производительность
+    случайного и линейного доступа.
+- name: use_sync_send_recv
+  type: bool
+  default: false
+  info: |
+    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.
+  info_ru: |
+    Если установлено в истину, то вместо io_uring для передачи данных по сети
+    будут использоваться обычные синхронные системные вызовы send/recv. Для OSD
+    это бессмысленно, так как OSD в любом случае нуждается в io_uring, но, в
+    принципе, это может применяться для клиентов со старыми версиями ядра.
+- name: use_rdma
+  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. TCP-only clients can also talk to an RDMA-enabled
+    cluster, so disabling RDMA may be needed if clients have RDMA devices,
+    but they are not connected to the cluster.
+  info_ru: |
+    Пытаться использовать RDMA для связи при наличии доступных устройств.
+    Отключите, если вы не хотите, чтобы Vitastor использовал RDMA.
+    TCP-клиенты также могут работать с RDMA-кластером, так что отключать
+    RDMA может быть нужно только если у клиентов есть RDMA-устройства,
+    но они не имеют соединения с кластером Vitastor.
+- name: rdma_device
+  type: string
+  info: |
+    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.
+  info_ru: |
+    Название 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-устройств, их
+    параметры и возможности.
+- name: rdma_port_num
+  type: int
+  default: 1
+  info: |
+    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.
+  info_ru: |
+    Номер порта RDMA-устройства, который следует использовать. Имеет смысл
+    только для устройств, у которых более 1 порта. Чтобы узнать, сколько портов
+    у вашего адаптера, посмотрите `phys_port_cnt` в выводе команды
+    `ibv_devinfo -v`.
+- name: rdma_gid_index
+  type: int
+  default: 0
+  info: |
+    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).
+  info_ru: |
+    Номер глобального идентификатора адреса RDMA-устройства, который следует
+    использовать. Разным gid_index могут соответствовать разные протоколы связи:
+    RoCEv1, RoCEv2, iWARP. Чтобы понять, какой нужен вам - смотрите строчки со
+    словом "GID" в выводе команды `ibv_devinfo -v`.
+
+    **ВАЖНО:** Если вы хотите использовать RoCEv2 (как мы и рекомендуем), то
+    правильный rdma_gid_index, как правило, 1 (IPv6) или 3 (IPv4).
+- name: rdma_mtu
+  type: int
+  default: 4096
+  info: |
+    RDMA Path MTU to use. Must be 1024, 2048 or 4096. There is usually no
+    sense to change it from the default 4096.
+  info_ru: |
+    Максимальная единица передачи (Path MTU) для RDMA. Должно быть равно 1024,
+    2048 или 4096. Обычно нет смысла менять значение по умолчанию, равное 4096.
+- name: rdma_max_sge
+  type: int
+  default: 128
+  info: |
+    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.
+  info_ru: |
+    Максимальное число записей разделения/сборки (scatter/gather) для RDMA.
+    OSD в любом случае согласовывают реальное значение при установке соединения,
+    так что менять этот параметр обычно не нужно.
+- name: rdma_max_msg
+  type: int
+  default: 1048576
+  info: Maximum size of a single RDMA send or receive operation in bytes.
+  info_ru: Максимальный размер одной RDMA-операции отправки или приёма.
+- name: rdma_max_recv
+  type: int
+  default: 8
+  info: |
+    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.
+  info_ru: |
+    Максимальное число параллельных RDMA-операций получения данных. Следует
+    иметь в виду, что данное число буферов размером `rdma_max_msg` выделяется
+    для каждого подключённого клиентского соединения, так что данная настройка
+    влияет на потребление памяти. Это так потому, что RDMA-приём данных в
+    Vitastor, увы, всё равно не является zero-copy, т.е. всё равно 1 раз
+    копирует данные в памяти. Данная особенность, возможно, будет исправлена в
+    более новых версиях Vitastor.
+- name: peer_connect_interval
+  type: sec
+  min: 1
+  default: 5
+  info: Interval before attempting to reconnect to an unavailable OSD.
+  info_ru: Время ожидания перед повторной попыткой соединиться с недоступным OSD.
+- name: peer_connect_timeout
+  type: sec
+  min: 1
+  default: 5
+  info: Timeout for OSD connection attempts.
+  info_ru: Максимальное время ожидания попытки соединения с OSD.
+- name: osd_idle_timeout
+  type: sec
+  min: 1
+  default: 5
+  info: |
+    OSD connection inactivity time after which clients and other OSDs send
+    keepalive requests to check state of the connection.
+  info_ru: |
+    Время неактивности соединения с OSD, после которого клиенты или другие OSD
+    посылают запрос проверки состояния соединения.
+- name: osd_ping_timeout
+  type: sec
+  min: 1
+  default: 5
+  info: |
+    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.
+  info_ru: |
+    Максимальное время ожидания ответа на запрос проверки состояния соединения.
+    Если OSD не отвечает за это время, соединение отключается и производится
+    повторная попытка соединения.
+- name: up_wait_retry_interval
+  type: ms
+  min: 50
+  default: 500
+  info: |
+    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.
+  info_ru: |
+    Когда OSD получают от клиентов запросы ввода-вывода, относящиеся к не
+    поднятым на данный момент на них PG, либо к PG в процессе синхронизации,
+    они отвечают клиентам специальным кодом ошибки, означающим, что клиент
+    должен некоторое время подождать перед повторением запроса. Именно это время
+    ожидания задаёт данный параметр.
+- name: max_etcd_attempts
+  type: int
+  default: 5
+  info: |
+    Maximum number of attempts for etcd requests which can't be retried
+    indefinitely.
+  info_ru: |
+    Максимальное число попыток выполнения запросов к etcd для тех запросов,
+    которые нельзя повторять бесконечно.
+- name: etcd_quick_timeout
+  type: ms
+  default: 1000
+  info: |
+    Timeout for etcd requests which should complete quickly, like lease refresh.
+  info_ru: |
+    Максимальное время выполнения запросов к etcd, которые должны завершаться
+    быстро, таких, как обновление резервации (lease).
+- name: etcd_slow_timeout
+  type: ms
+  default: 5000
+  info: Timeout for etcd requests which are allowed to wait for some time.
+  info_ru: |
+    Максимальное время выполнения запросов к etcd, для которых не обязательно
+    гарантировать быстрое выполнение.
+- name: etcd_keepalive_timeout
+  type: sec
+  default: max(30, etcd_report_interval*2)
+  info: |
+    Timeout for etcd connection HTTP Keep-Alive. Should be higher than
+    etcd_report_interval to guarantee that keepalive actually works.
+  info_ru: |
+    Таймаут для HTTP Keep-Alive в соединениях к etcd. Должен быть больше, чем
+    etcd_report_interval, чтобы keepalive гарантированно работал.
+- name: etcd_ws_keepalive_timeout
+  type: sec
+  default: 30
+  info: |
+    etcd websocket ping interval required to keep the connection alive and
+    detect disconnections quickly.
+  info_ru: |
+    Интервал проверки живости вебсокет-подключений к etcd.

docs/config/src/osd.en.md

@@ -0,0 +1,4 @@
+# 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.

docs/config/src/osd.ru.md

@@ -0,0 +1,5 @@
+# Изменяемые параметры OSD
+
+Данные параметры используются только OSD, но, в отличие от дисковых параметров,
+не фиксируются в момент инициализации дисков OSD и могут быть изменены в любой
+момент с перезапуском OSD.

docs/config/src/osd.yml

@@ -0,0 +1,345 @@
+- name: etcd_report_interval
+  type: sec
+  default: 5
+  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
+    that every OSD always refreshes its lease in time.
+  info_ru: |
+    Интервал, с которым OSD обновляет своё состояние в etcd. Значение параметра
+    влияет на время резервации (lease) OSD и поэтому на скорость переключения
+    при падении OSD. Время lease равняется значению этого параметра плюс
+    max_etcd_attempts * etcd_quick_timeout.
+- name: run_primary
+  type: bool
+  default: true
+  info: |
+    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.
+  info_ru: |
+    Запускать логику первичного OSD на данном OSD. На данный момент отключать
+    эту опцию может иметь смысл только в целях отладки. В теории, можно
+    реализовать дополнительный режим для монитора, который позволит отделять
+    первичные OSD от вторичных, но пока не понятно, зачем это может кому-то
+    понадобиться, поэтому это не реализовано.
+- name: osd_network
+  type: string or array of strings
+  type_ru: строка или массив строк
+  info: |
+    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.
+  info_ru: |
+    Маска подсети (IPv4 или IPv6) для использования для соединений с OSD.
+    Имейте в виду, что хотя сейчас и можно передать в этот параметр несколько
+    подсетей, это не означает, что OSD будут создавать несколько слушающих
+    сокетов - они лишь будут выбирать адрес первого поднятого (состояние UP +
+    RUNNING), подходящий под заданную маску. Также не реализовано разделение
+    кластерной и публичной сетей OSD. Правда, от него обычно всё равно довольно
+    мало толку, так что особенной проблемы в этом нет.
+- name: bind_address
+  type: string
+  default: "0.0.0.0"
+  info: |
+    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.
+  info_ru: |
+    Этим параметром можно явным образом задать адрес, на котором будет ожидать
+    соединений OSD (вместо использования маски подсети). Может быть полезно,
+    например, чтобы запускать OSD на неподнятых интерфейсах (не UP + RUNNING).
+- name: bind_port
+  type: int
+  info: |
+    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.
+  info_ru: |
+    По умолчанию OSD сами выбирают случайные порты для входящих подключений.
+    С помощью данной опции вы можете задать порт для отдельного OSD вручную.
+- name: autosync_interval
+  type: sec
+  default: 5
+  info: |
+    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.
+  info_ru: |
+    Временной интервал отправки автоматических fsync-ов (операций очистки кэша)
+    каждым OSD для случая, когда режим immediate_commit отключён. fsync-и нужны
+    OSD, чтобы успевать очищать журнал - без них OSD быстро заполняют журналы и
+    перестают обрабатывать операции записи. Также эта опция ограничивает объём
+    недавних незафиксированных изменений, которые OSD могут терять при
+    отключении питания, если клиенты вообще не отправляют fsync.
+- name: autosync_writes
+  type: int
+  default: 128
+  info: |
+    Same as autosync_interval, but sets the maximum number of uncommitted write
+    operations before issuing an fsync operation internally.
+  info_ru: |
+    Аналогично autosync_interval, но задаёт не временной интервал, а
+    максимальное количество незафиксированных операций записи перед
+    принудительной отправкой fsync-а.
+- name: recovery_queue_depth
+  type: int
+  default: 4
+  info: |
+    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.
+  info_ru: |
+    Максимальное число операций восстановления на одном первичном OSD в любой
+    момент времени. На данный момент единственный параметр, который можно менять
+    для ускорения или замедления восстановления и перебалансировки данных, но
+    в планах реализация других параметров.
+- name: recovery_sync_batch
+  type: int
+  default: 16
+  info: Maximum number of recovery operations before issuing an additional fsync.
+  info_ru: Максимальное число операций восстановления перед дополнительным fsync.
+- name: readonly
+  type: bool
+  default: false
+  info: |
+    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.
+  info_ru: |
+    Режим "только чтение". Если включить этот режим, OSD не будет писать ничего
+    на диск. Может быть полезно в целях восстановления.
+- name: no_recovery
+  type: bool
+  default: false
+  info: |
+    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.
+  info_ru: |
+    Отключить автоматическое фоновое восстановление объектов. Обратите внимание,
+    что эта опция не отключает восстановление объектов, происходящее при
+    записи - запись всегда производится в полный набор из как минимум pg_minsize
+    OSD.
+- name: no_rebalance
+  type: bool
+  default: false
+  info: |
+    Disable background movement of data between different OSDs. Disabling it
+    means that PGs in the `has_misplaced` state will be left in it indefinitely.
+  info_ru: |
+    Отключить фоновое перемещение объектов между разными OSD. Отключение
+    означает, что PG, находящиеся в состоянии `has_misplaced`, будут оставлены
+    в нём на неопределённый срок.
+- name: print_stats_interval
+  type: sec
+  default: 3
+  info: |
+    Time interval at which OSDs print simple human-readable operation
+    statistics on stdout.
+  info_ru: |
+    Временной интервал, с которым OSD печатают простую человекочитаемую
+    статистику выполнения операций в стандартный вывод.
+- name: slow_log_interval
+  type: sec
+  default: 10
+  info: |
+    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".
+  info_ru: |
+    Временной интервал, с которым OSD выводят в стандартный вывод список
+    медленных или зависших операций, если таковые имеются. Также время, при
+    превышении которого операция считается "медленной".
+- name: max_write_iodepth
+  type: int
+  default: 128
+  info: |
+    Parallel client write operation limit per one OSD. Operations that exceed
+    this limit are pushed to a temporary queue instead of being executed
+    immediately.
+  info_ru: |
+    Максимальное число одновременных клиентских операций записи на один OSD.
+    Операции, превышающие этот лимит, не исполняются сразу, а сохраняются во
+    временной очереди.
+- name: min_flusher_count
+  type: int
+  default: 1
+  info: |
+    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.
+  info_ru: |
+    Flusher - это микро-поток (корутина), которая копирует данные из журнала в
+    основную область устройства данных. Их число настраивается динамически между
+    минимальным и максимальным значением. Этот параметр задаёт минимальное число.
+- name: max_flusher_count
+  type: int
+  default: 256
+  info: |
+    Maximum number of journal flushers (see above min_flusher_count).
+  info_ru: |
+    Максимальное число микро-потоков очистки журнала (см. выше min_flusher_count).
+- name: inmemory_metadata
+  type: bool
+  default: true
+  info: |
+    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.
+  info_ru: |
+    Данный параметр заставляет Vitastor всегда держать область метаданных диска
+    в памяти. Это нужно, чтобы избегать дополнительных операций чтения с диска
+    при записи. Размер области метаданных на данный момент составляет примерно
+    224 МБ на 1 ТБ данных. При включении потребление памяти снизится примерно
+    на эту величину, но при этом также снизится и производительность. В будущем,
+    после обновления схемы хранения метаданных, это ограничение, скорее всего,
+    будет ликвидировано.
+- name: inmemory_journal
+  type: bool
+  default: true
+  info: |
+    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.
+  info_ru: |
+    Данный параметр заставляет Vitastor всегда держать в памяти журналы OSD.
+    Отключение параметра, опять же, снижает потребление памяти, но ухудшает
+    производительность, так как для копирования данных из журнала в основную
+    область устройства OSD будут вынуждены читать их обратно с диска. Выигрыш
+    по памяти при этом обычно крайне низкий, так как для SSD OSD обычно
+    достаточно 16- или 32-мегабайтного журнала. Однако в теории отключение
+    параметра может оказаться полезным для гибридных OSD (HDD+SSD) с большими
+    журналами, расположенными на быстром по сравнению с HDD устройстве.
+- name: journal_sector_buffer_count
+  type: int
+  default: 32
+  info: |
+    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.
+  info_ru: |
+    Максимальное число буферов, разрешённых для использования под записываемые
+    в журнал блоки метаданных. Единственная ситуация, в которой этот параметр
+    нужно менять - это если вы включаете journal_no_same_sector_overwrites. В
+    этом случае установите данный параметр, например, в 1024.
+- name: journal_no_same_sector_overwrites
+  type: bool
+  default: false
+  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 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.
+  info_ru: |
+    Включайте данную опцию для SSD вроде Intel D3-S4510 и D3-S4610, которые
+    ОЧЕНЬ не любят, когда ПО перезаписывает один и тот же сектор несколько раз
+    подряд. Такие SSD при многократной перезаписи одного и того же сектора
+    сильно замедляются - условно, с 25000 и более iops до 3000 iops. Когда
+    данная опция установлена, Vitastor всегда переходит к следующему сектору
+    журнала после записи вместо потенциально повторной перезаписи того же
+    самого сектора.
+
+    Почти все другие SSD (99% моделей) не требуют данной опции.
+- name: throttle_small_writes
+  type: bool
+  default: false
+  info: |
+    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.
+  info_ru: |
+    Разрешить мягкое ограничение скорости журналируемой записи. Полезно для
+    гибридных OSD с быстрыми устройствами метаданных и медленными устройствами
+    данных. Идея заключается в том, что мелкие записи в этой ситуации могут
+    завершаться очень быстро, так как они изначально записываются на быстрое
+    журнальное устройство (SSD). Но перемещать их потом на основное медленное
+    устройство долго. Поэтому если OSD быстро примет от клиентов очень много
+    мелких операций записи, он быстро заполнит свой журнал, после чего
+    производительность записи резко упадёт практически до нуля. Ограничение
+    скорости записи призвано решить эту проблему с помощью искусственного
+    замедления операций записи на основании объёма свободного места в журнале.
+    Когда эта опция включена, производительность мелких операций записи будет
+    снижаться плавно, а не резко в момент окончательного заполнения журнала.
+- name: throttle_target_iops
+  type: int
+  default: 100
+  info: |
+    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).
+  info_ru: |
+    Расчётное максимальное число ограничиваемых операций в секунду при условии
+    отсутствия свободного места в журнале. Устанавливайте приблизительно равным
+    максимальной производительности случайной записи ваших устройств данных
+    (HDD) в операциях в секунду.
+- name: throttle_target_mbs
+  type: int
+  default: 100
+  info: |
+    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).
+  info_ru: |
+    Расчётный максимальный размер в МБ/с ограничиваемых операций в секунду при
+    условии отсутствия свободного места в журнале. Устанавливайте приблизительно
+    равным максимальной производительности линейной записи ваших устройств
+    данных (HDD).
+- name: throttle_target_parallelism
+  type: int
+  default: 1
+  info: |
+    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).
+  info_ru: |
+    Расчётный максимальный параллелизм ограничиваемых операций в секунду при
+    условии отсутствия свободного места в журнале. Устанавливайте приблизительно
+    равным внутреннему параллелизму ваших устройств данных (1 для HDD, 4-8
+    для SSD).
+- name: throttle_threshold_us
+  type: us
+  default: 50
+  info: |
+    Minimal computed delay to be applied to throttled operations. Usually
+    doesn't need to be changed.
+  info_ru: |
+    Минимальная применимая к ограничиваемым операциям задержка. Обычно не
+    требует изменений.
+- name: osd_memlock
+  type: bool
+  default: false
+  info: >
+    Lock all OSD memory to prevent it from being unloaded into swap with
+    mlockall(). Requires sufficient ulimit -l (max locked memory).
+  info_ru: >
+    Блокировать всю память OSD с помощью mlockall, чтобы запретить её выгрузку
+    в пространство подкачки. Требует достаточного значения ulimit -l (лимита
+    заблокированной памяти).

docs/installation/kubernetes.en.md

@@ -0,0 +1,20 @@
+[Documentation](../../README.md#documentation) → Installation → Kubernetes CSI
+
+-----
+
+[Читать на русском](kubernetes.ru.md)
+
+# Kubernetes CSI
+
+Vitastor has a CSI plugin for Kubernetes which supports RWO (and block RWX) volumes.
+
+To deploy it, take manifests from [csi/deploy/](../../csi/deploy/) directory, put your
+Vitastor configuration in [001-csi-config-map.yaml](../../csi/deploy/001-csi-config-map.yaml),
+configure storage class in [009-storage-class.yaml](../../csi/deploy/009-storage-class.yaml)
+and apply all `NNN-*.yaml` manifests to your Kubernetes installation:
+
+```
+for i in ./???-*.yaml; do kubectl apply -f $i; done
+```
+
+After that you'll be able to create PersistentVolumes. See example in [csi/deploy/example-pvc.yaml](../../csi/deploy/example-pvc.yaml).

docs/installation/kubernetes.ru.md

@@ -0,0 +1,20 @@
+[Документация](../../README-ru.md#документация) → Установка → Kubernetes CSI
+
+-----
+
+[Read in English](kubernetes.en.md)
+
+# Kubernetes CSI
+
+У Vitastor есть CSI-плагин для Kubernetes, поддерживающий RWO, а также блочные RWX, тома.
+
+Для установки возьмите манифесты из директории [csi/deploy/](../csi/deploy/), поместите
+вашу конфигурацию подключения к Vitastor в [csi/deploy/001-csi-config-map.yaml](../csi/deploy/001-csi-config-map.yaml),
+настройте StorageClass в [csi/deploy/009-storage-class.yaml](../csi/deploy/009-storage-class.yaml)
+и примените все `NNN-*.yaml` к вашей инсталляции Kubernetes.
+
+```
+for i in ./???-*.yaml; do kubectl apply -f $i; done
+```
+
+После этого вы сможете создавать PersistentVolume. Пример смотрите в файле [csi/deploy/example-pvc.yaml](../csi/deploy/example-pvc.yaml).

docs/installation/openstack.en.md

@@ -0,0 +1,40 @@
+[Documentation](../../README.md#documentation) → Installation → OpenStack
+
+-----
+
+[Читать на русском](openstack.ru.md)
+
+# OpenStack
+
+To enable Vitastor support in an OpenStack installation:
+
+- Install vitastor-client, patched QEMU and libvirt packages from Vitastor DEB or RPM repository
+- Use `patches/nova-21.diff` or `patches/nova-23.diff` to patch your Nova installation.
+  Patch 21 fits Nova 21-22, patch 23 fits Nova 23-24.
+- Install `patches/cinder-vitastor.py` as `..../cinder/volume/drivers/vitastor.py`
+- Define a volume type in cinder.conf (see below)
+- Block network access from VMs to Vitastor network (to OSDs and etcd),
+  because Vitastor doesn't support authentication
+- Restart Cinder and Nova
+
+Cinder volume type configuration example:
+
+```
+[DEFAULT]
+enabled_backends = lvmdriver-1, vitastor-testcluster
+# ...
+
+[vitastor-testcluster]
+volume_driver = cinder.volume.drivers.vitastor.VitastorDriver
+volume_backend_name = vitastor-testcluster
+image_volume_cache_enabled = True
+volume_clear = none
+vitastor_etcd_address = 192.168.7.2:2379
+vitastor_etcd_prefix =
+vitastor_config_path = /etc/vitastor/vitastor.conf
+vitastor_pool_id = 1
+image_upload_use_cinder_backend = True
+```
+
+To put Glance images in Vitastor, use [https://docs.openstack.org/cinder/pike/admin/blockstorage-volume-backed-image.html](volume-backed images),
+although the support has not been verified yet.

docs/installation/openstack.ru.md

@@ -0,0 +1,40 @@
+[Документация](../../README-ru.md#документация) → Установка → OpenStack
+
+-----
+
+[Read in English](openstack.en.md)
+
+# OpenStack
+
+Чтобы подключить Vitastor к OpenStack:
+
+- Установите пакеты vitastor-client, libvirt и QEMU из DEB или RPM репозитория Vitastor
+- Примените патч `patches/nova-21.diff` или `patches/nova-23.diff` к вашей инсталляции Nova.
+  nova-21.diff подходит для Nova 21-22, nova-23.diff подходит для Nova 23-24.
+- Скопируйте `patches/cinder-vitastor.py` в инсталляцию Cinder как `cinder/volume/drivers/vitastor.py`
+- Создайте тип томов в cinder.conf (см. ниже)
+- Обязательно заблокируйте доступ от виртуальных машин к сети Vitastor (OSD и etcd), т.к. Vitastor (пока) не поддерживает аутентификацию
+- Перезапустите Cinder и Nova
+
+Пример конфигурации Cinder:
+
+```
+[DEFAULT]
+enabled_backends = lvmdriver-1, vitastor-testcluster
+# ...
+
+[vitastor-testcluster]
+volume_driver = cinder.volume.drivers.vitastor.VitastorDriver
+volume_backend_name = vitastor-testcluster
+image_volume_cache_enabled = True
+volume_clear = none
+vitastor_etcd_address = 192.168.7.2:2379
+vitastor_etcd_prefix =
+vitastor_config_path = /etc/vitastor/vitastor.conf
+vitastor_pool_id = 1
+image_upload_use_cinder_backend = True
+```
+
+Чтобы помещать в Vitastor Glance-образы, нужно использовать
+[https://docs.openstack.org/cinder/pike/admin/blockstorage-volume-backed-image.html](образы на основе томов Cinder),
+однако, поддержка этой функции ещё не проверялась.

docs/installation/packages.en.md

@@ -0,0 +1,44 @@
+[Documentation](../../README.md#documentation) → Installation → Packages
+
+-----
+
+[Читать на русском](packages.ru.md)
+
+# Packages
+
+## Debian
+
+- Trust Vitastor package signing key:
+  `wget -q -O - https://vitastor.io/debian/pubkey | sudo apt-key add -`
+- Add Vitastor package repository to your /etc/apt/sources.list:
+  - Debian 11 (Bullseye/Sid): `deb https://vitastor.io/debian bullseye main`
+  - Debian 10 (Buster): `deb https://vitastor.io/debian buster main`
+- For Debian 10 (Buster) also enable backports repository:
+  `deb http://deb.debian.org/debian buster-backports main`
+- Install packages: `apt update; apt install vitastor lp-solve etcd linux-image-amd64 qemu`
+
+## CentOS
+
+- Add Vitastor package repository:
+  - CentOS 7: `yum install https://vitastor.io/rpms/centos/7/vitastor-release-1.0-1.el7.noarch.rpm`
+  - CentOS 8: `dnf install https://vitastor.io/rpms/centos/8/vitastor-release-1.0-1.el8.noarch.rpm`
+- Enable EPEL: `yum/dnf install epel-release`
+- Enable additional CentOS repositories:
+  - CentOS 7: `yum install centos-release-scl`
+  - CentOS 8: `dnf install centos-release-advanced-virtualization`
+- Enable elrepo-kernel:
+  - CentOS 7: `yum install https://www.elrepo.org/elrepo-release-7.el7.elrepo.noarch.rpm`
+  - CentOS 8: `dnf install https://www.elrepo.org/elrepo-release-8.el8.elrepo.noarch.rpm`
+- Install packages: `yum/dnf install vitastor lpsolve etcd kernel-ml qemu-kvm`
+
+## Installation requirements
+
+- Linux kernel 5.4 or newer, for io_uring support. 5.8 or later is highly
+  recommended because io_uring is a relatively new technology and there is
+  at least one bug which reproduces with io_uring and HP SmartArray
+  controllers in 5.4
+- liburing 0.4 or newer
+- lp_solve
+- etcd 3.4.15 or newer. Earlier versions won't work because of various bugs,
+  for example [#12402](https://github.com/etcd-io/etcd/pull/12402).
+- node.js 10 or newer

docs/installation/packages.ru.md

@@ -0,0 +1,43 @@
+[Документация](../../README-ru.md#документация) → Установка → Установка из пакетов
+
+-----
+
+[Read in English](packages.en.md)
+
+# Установка из пакетов
+
+## Debian
+
+- Добавьте ключ репозитория Vitastor:
+  `wget -q -O - https://vitastor.io/debian/pubkey | sudo apt-key add -`
+- Добавьте репозиторий Vitastor в /etc/apt/sources.list:
+  - Debian 11 (Bullseye/Sid): `deb https://vitastor.io/debian bullseye main`
+  - Debian 10 (Buster): `deb https://vitastor.io/debian buster main`
+- Для Debian 10 (Buster) также включите репозиторий backports:
+  `deb http://deb.debian.org/debian buster-backports main`
+- Установите пакеты: `apt update; apt install vitastor lp-solve etcd linux-image-amd64 qemu`
+
+## CentOS
+
+- Добавьте в систему репозиторий Vitastor:
+  - CentOS 7: `yum install https://vitastor.io/rpms/centos/7/vitastor-release-1.0-1.el7.noarch.rpm`
+  - CentOS 8: `dnf install https://vitastor.io/rpms/centos/8/vitastor-release-1.0-1.el8.noarch.rpm`
+- Включите EPEL: `yum/dnf install epel-release`
+- Включите дополнительные репозитории CentOS:
+  - CentOS 7: `yum install centos-release-scl`
+  - CentOS 8: `dnf install centos-release-advanced-virtualization`
+- Включите elrepo-kernel:
+  - CentOS 7: `yum install https://www.elrepo.org/elrepo-release-7.el7.elrepo.noarch.rpm`
+  - CentOS 8: `dnf install https://www.elrepo.org/elrepo-release-8.el8.elrepo.noarch.rpm`
+- Установите пакеты: `yum/dnf install vitastor lpsolve etcd kernel-ml qemu-kvm`
+
+## Установочные требования
+
+- Ядро Linux 5.4 или новее, для поддержки io_uring. Рекомендуется даже 5.8,
+  так как io_uring - относительно новый интерфейс и в версиях до 5.8 встречались
+  некоторые баги, например, зависание с io_uring и контроллером HP SmartArray
+- liburing 0.4 или новее
+- lp_solve
+- etcd 3.4.15 или новее. Более старые версии не будут работать из-за разных багов,
+  например, [#12402](https://github.com/etcd-io/etcd/pull/12402).
+- node.js 10 или новее

docs/installation/proxmox.en.md

@@ -0,0 +1,39 @@
+[Documentation](../../README.md#documentation) → Installation → Proxmox VE
+
+-----
+
+[Читать на русском](proxmox.ru.md)
+
+# Proxmox VE
+
+To enable Vitastor support in Proxmox Virtual Environment (6.4 and 7.1 are supported):
+
+- Add the corresponding Vitastor Debian repository into sources.list on Proxmox hosts
+  (buster for 6.4, bullseye for 7.1)
+- Install vitastor-client, pve-qemu-kvm, pve-storage-vitastor (* or see note) packages from Vitastor repository
+- Define storage in `/etc/pve/storage.cfg` (see below)
+- Block network access from VMs to Vitastor network (to OSDs and etcd),
+  because Vitastor doesn't support authentication
+- Restart pvedaemon: `systemctl restart pvedaemon`
+
+`/etc/pve/storage.cfg` example (the only required option is vitastor_pool, all others
+are listed below with their default values):
+
+```
+vitastor: vitastor
+    # pool to put new images into
+    vitastor_pool testpool
+    # path to the configuration file
+    vitastor_config_path /etc/vitastor/vitastor.conf
+    # etcd address(es), required only if missing in the configuration file
+    vitastor_etcd_address 192.168.7.2:2379/v3
+    # prefix for keys in etcd
+    vitastor_etcd_prefix /vitastor
+    # prefix for images
+    vitastor_prefix pve/
+    # use NBD mounter (only required for containers)
+    vitastor_nbd 0
+```
+
+\* Note: you can also manually copy [patches/PVE_VitastorPlugin.pm](patches/PVE_VitastorPlugin.pm) to Proxmox hosts
+as `/usr/share/perl5/PVE/Storage/Custom/VitastorPlugin.pm` instead of installing pve-storage-vitastor.

docs/installation/proxmox.ru.md

@@ -0,0 +1,39 @@
+[Документация](../../README-ru.md#документация) → Установка → Proxmox
+
+-----
+
+[Read in English](proxmox.en.md)
+
+# Proxmox
+
+Чтобы подключить Vitastor к Proxmox Virtual Environment (поддерживаются версии 6.4 и 7.1):
+
+- Добавьте соответствующий Debian-репозиторий Vitastor в sources.list на хостах Proxmox
+  (buster для 6.4, bullseye для 7.1)
+- Установите пакеты vitastor-client, pve-qemu-kvm, pve-storage-vitastor (* или см. сноску) из репозитория Vitastor
+- Определите тип хранилища в `/etc/pve/storage.cfg` (см. ниже)
+- Обязательно заблокируйте доступ от виртуальных машин к сети Vitastor (OSD и etcd), т.к. Vitastor (пока) не поддерживает аутентификацию
+- Перезапустите демон Proxmox: `systemctl restart pvedaemon`
+
+Пример `/etc/pve/storage.cfg` (единственная обязательная опция - vitastor_pool, все остальные
+перечислены внизу для понимания значений по умолчанию):
+
+```
+vitastor: vitastor
+    # Пул, в который будут помещаться образы дисков
+    vitastor_pool testpool
+    # Путь к файлу конфигурации
+    vitastor_config_path /etc/vitastor/vitastor.conf
+    # Адрес(а) etcd, нужны, только если не указаны в vitastor.conf
+    vitastor_etcd_address 192.168.7.2:2379/v3
+    # Префикс ключей метаданных в etcd
+    vitastor_etcd_prefix /vitastor
+    # Префикс имён образов
+    vitastor_prefix pve/
+    # Монтировать образы через NBD прокси, через ядро (нужно только для контейнеров)
+    vitastor_nbd 0
+```
+
+\* Примечание: вместо установки пакета pve-storage-vitastor вы можете вручную скопировать файл
+[patches/PVE_VitastorPlugin.pm](patches/PVE_VitastorPlugin.pm) на хосты Proxmox как
+`/usr/share/perl5/PVE/Storage/Custom/VitastorPlugin.pm`.

docs/installation/source.en.md

@@ -0,0 +1,65 @@
+[Documentation](../../README.md#documentation) → Installation → Building from Source
+
+-----
+
+[Читать на русском](source.ru.md)
+
+# Building from Source
+
+- [Requirements](#requirements)
+- [Basic instructions](#basic-instructions)
+- [QEMU Driver](#qemu-driver)
+
+## Requirements
+
+- gcc and g++ 8 or newer, clang 10 or newer, or other compiler with C++11 plus
+  designated initializers support from C++20
+- CMake
+- liburing, jerasure headers
+- tcmalloc (google-perftools-dev)
+
+## Basic instructions
+
+Download source, for example using git: `git clone --recurse-submodules https://yourcmc.ru/git/vitalif/vitastor/`
+
+Get `fio` source and symlink it into `<vitastor>/fio`. If you don't want to build fio engine,
+you can disable it by passing `-DWITH_FIO=no` to cmake.
+
+Build and install Vitastor:
+
+```
+cd vitastor
+mkdir build
+cd build
+cmake .. && make -j8 install
+```
+
+## QEMU Driver
+
+It's recommended to build the QEMU driver (qemu_driver.c) in-tree, as a part of
+QEMU build process. To do that:
+- Install vitastor client library headers (from source or from vitastor-client-dev package)
+- Take a corresponding patch from `patches/qemu-*-vitastor.patch` and apply it to QEMU source
+- Copy `src/qemu_driver.c` to QEMU source directory as `block/block-vitastor.c`
+- Build QEMU as usual
+
+But it is also possible to build it out-of-tree. To do that:
+- Get QEMU source, begin to build it, stop the build and copy headers:
+   - `<qemu>/include` &rarr; `<vitastor>/qemu/include`
+   - Debian:
+      * Use qemu packages from the main repository
+      * `<qemu>/b/qemu/config-host.h` &rarr; `<vitastor>/qemu/b/qemu/config-host.h`
+      * `<qemu>/b/qemu/qapi` &rarr; `<vitastor>/qemu/b/qemu/qapi`
+   - CentOS 8:
+      * Use qemu packages from the Advanced-Virtualization repository. To enable it, run
+        `yum install centos-release-advanced-virtualization.noarch` and then `yum install qemu`
+      * `<qemu>/config-host.h` &rarr; `<vitastor>/qemu/b/qemu/config-host.h`
+      * For QEMU 3.0+: `<qemu>/qapi` &rarr; `<vitastor>/qemu/b/qemu/qapi`
+      * For QEMU 2.0+: `<qemu>/qapi-types.h` &rarr; `<vitastor>/qemu/b/qemu/qapi-types.h`
+   - `config-host.h` and `qapi` are required because they contain generated headers
+- Configure Vitastor with `WITH_QEMU=yes` and, if you're on RHEL, also with `QEMU_PLUGINDIR=qemu-kvm`:
+  `cmake .. -DWITH_QEMU=yes`.
+- After that, Vitastor will build `block-vitastor.so` during its build process.
+- This way you can use the driver even with unmodified QEMU, but you'll need to set
+  environment variable `LD_PRELOAD=/usr/lib/x86_64-linux-gnu/qemu/block-vitastor.so`
+  and Vitastor disks won't work in QAPI and in "new" JSON syntax `-blockdev` in this case.

docs/installation/source.ru.md

@@ -0,0 +1,68 @@
+[Документация](../../README-ru.md#документация) → Установка → Сборка из исходных кодов
+
+-----
+
+[Read in English](source.en.md)
+
+# Сборка из исходных кодов
+
+- [Требования](#требования)
+- [Базовая инструкция](#базовая-инструкция)
+- [Драйвер QEMU](#драйвер-qemu)
+
+## Требования
+
+- gcc и g++ >= 8, либо clang >= 10, либо другой компилятор с поддержкой C++11 плюс
+  назначенных инициализаторов (designated initializers) из C++20
+- CMake
+- Заголовки liburing, jerasure
+- tcmalloc (google-perftools-dev)
+
+## Базовая инструкция
+
+Скачайте исходные коды, например, из git: `git clone --recurse-submodules https://yourcmc.ru/git/vitalif/vitastor/`
+
+Скачайте исходные коды пакета `fio`, распакуйте их и создайте символическую ссылку на них
+в директории исходников Vitastor: `<vitastor>/fio`. Либо, если вы не хотите собирать плагин fio,
+его можно исключить из сборки путём передачи `-DWITH_FIO=no` в cmake.
+
+Собрать и установить Vitastor:
+
+```
+cd vitastor
+mkdir build
+cd build
+cmake .. && make -j8 install
+```
+
+## Драйвер QEMU
+
+Драйвер QEMU (qemu_driver.c) рекомендуется собирать вместе с самим QEMU. Для этого:
+- Установите заголовки клиентской библиотеки Vitastor (из исходников или из пакета vitastor-client-dev)
+- Возьмите соответствующий патч из `patches/qemu-*-vitastor.patch` и примените его к исходникам QEMU
+- Скопируйте [src/qemu_driver.c](../../src/qemu_driver.c) в директорию исходников QEMU как `block/block-vitastor.c`
+- Соберите QEMU как обычно
+
+Однако в целях отладки драйвер также можно собирать отдельно от QEMU. Для этого:
+- Установите QEMU, возьмите исходные коды установленного пакета, начните его пересборку,
+  через некоторое время остановите её и скопируйте следующие заголовки:
+   - `<qemu>/include` &rarr; `<vitastor>/qemu/include`
+   - Debian:
+      * Берите qemu из основного репозитория
+      * `<qemu>/b/qemu/config-host.h` &rarr; `<vitastor>/qemu/b/qemu/config-host.h`
+      * `<qemu>/b/qemu/qapi` &rarr; `<vitastor>/qemu/b/qemu/qapi`
+   - CentOS 8:
+      * Берите qemu из репозитория Advanced-Virtualization. Чтобы включить его, запустите
+        `yum install centos-release-advanced-virtualization.noarch` и далее `yum install qemu`
+      * `<qemu>/config-host.h` &rarr; `<vitastor>/qemu/b/qemu/config-host.h`
+      * Для QEMU 3.0+: `<qemu>/qapi` &rarr; `<vitastor>/qemu/b/qemu/qapi`
+      * Для QEMU 2.0+: `<qemu>/qapi-types.h` &rarr; `<vitastor>/qemu/b/qemu/qapi-types.h`
+   - `config-host.h` и `qapi` нужны, т.к. в них содержатся автогенерируемые заголовки
+- Сконфигурируйте cmake Vitastor с `WITH_QEMU=yes` (`cmake .. -DWITH_QEMU=yes`) и, если вы
+  используете RHEL-подобый дистрибутив, также с `QEMU_PLUGINDIR=qemu-kvm`.
+- После этого в процессе сборки Vitastor также будет собираться подходящий для вашей
+  версии QEMU `block-vitastor.so`.
+- Таким образом можно использовать драйвер даже с немодифицированным QEMU, но в этом случае
+  диски Vitastor не будут работать через QAPI и через JSON-синтаксис `-blockdev`, а также
+  потребуется устанавливать переменную окружения
+  `LD_PRELOAD=/usr/lib/x86_64-linux-gnu/qemu/block-vitastor.so`.

docs/intro/architecture.en.md

@@ -0,0 +1,91 @@
+[Documentation](../../README.md#documentation) → Introduction → Architecture
+
+-----
+
+[Читать на русском](architecture.ru.md)
+
+# Architecture
+
+- [Basic concepts](#basic-concepts)
+- [Similarities to Ceph](#similarities-to-ceph)
+- [Differences from Ceph](#differences-from-ceph)
+- [Implementation Principles](#implementation-principles)
+
+## Basic concepts
+
+- OSD (Object Storage Daemon) is a process that stores data and serves read/write requests.
+- PG (Placement Group) is a "shard" of the cluster, group of data stored on one set of replicas.
+- Pool is a container for data that has equal redundancy scheme and placement rules.
+- Monitor is a separate daemon that watches cluster state and handles failures.
+- Failure Domain is a group of OSDs that you allow to fail. It's "host" by default.
+- Placement Tree groups OSDs in a hierarchy to later split them into Failure Domains.
+
+## Similarities to Ceph
+
+- Vitastor also has Pools, PGs, OSDs, Monitors, Failure Domains, Placement Tree:
+- Vitastor also distributes every image data across the whole cluster.
+- Vitastor is also transactional. Even though there's a "lazy fsync mode" which
+  doesn't implicitly flush every operation to disks, every write to the cluster is atomic.
+- OSDs also have journal and metadata and they can also be put on separate drives.
+- Just like in Ceph, client library attempts to recover from any cluster failure so
+  you can basically reboot the whole cluster and only pause, but not crash, your clients.
+
+## Differences from Ceph
+
+- Vitastor's primary focus is on SSDs: SSD-only and SSD+HDD clusters.
+- The basic layer of Vitastor is block storage with fixed-size blocks, not object storage with
+  rich semantics like in Ceph (RADOS).
+- PGs are ephemeral in Vitastor. This means that they aren't stored on data disks and only exist
+  in memory while OSDs are running.
+- Vitastor OSD is (and will always be) single-threaded. If you want to dedicate more than 1 core
+  per drive you should run multiple OSDs each on a different partition of the drive.
+  Vitastor isn't CPU-hungry though (as opposed to Ceph), so 1 core is sufficient in a lot of cases.
+- Metadata is always kept in memory which removes the need for extra disk reads. Metadata size
+  depends linearly on drive capacity and data store block size which is 128 KB by default.
+  With 128 KB blocks metadata takes around 512 MB per 1 TB (which is still less than Ceph wants).
+  Journal is also kept in memory by default, but in SSD-only clusters it's only 32 MB, and in SSD+HDD
+  clusters, where it's beneficial to increase it, [inmemory_journal](docs/config/osd.en.md#inmemory_journal) can be disabled.
+- Vitastor storage layer doesn't have internal copy-on-write or redirect-write. I know that maybe
+  it's possible to create a good copy-on-write storage, but it's much harder and makes performance
+  less deterministic, so CoW isn't used in Vitastor.
+- There's a "lazy fsync" mode which allows to batch writes before flushing them to the disk.
+  This allows to use Vitastor with desktop SSDs, but still lowers performance due to additional
+  network roundtrips, so use server SSDs with capacitor-based power loss protection
+  ("Advanced Power Loss Protection") for best performance.
+- Recovery process is per-object (per-block), not per-PG. Also there are no PGLOGs.
+- Monitors don't store data. Cluster configuration and state is stored in etcd in simple human-readable
+  JSON structures. Monitors only watch cluster state and handle data movement.
+  Thus Vitastor's Monitor isn't a critical component of the system and is more similar to Ceph's Manager.
+  Vitastor's Monitor is implemented in node.js.
+- PG distribution isn't based on consistent hashes. All PG mappings are stored in etcd.
+  Rebalancing PGs between OSDs is done by mathematical optimization - data distribution problem
+  is reduced to a linear programming problem and solved by lp_solve. This allows for almost
+  perfect (96-99% uniformity compared to Ceph's 80-90%) data distribution in most cases, ability
+  to map PGs by hand without breaking rebalancing logic, reduced OSD peer-to-peer communication
+  (on average, OSDs have fewer peers) and less data movement. It also probably has a drawback -
+  this method may fail in very large clusters, but up to several hundreds of OSDs it's perfectly fine.
+  It's also easy to add consistent hashes in the future if something proves their necessity.
+- There's no separate CRUSH layer. You select pool redundancy scheme, placement root, failure domain
+  and so on directly in pool configuration.
+
+## Implementation Principles
+
+- I like architecturally simple solutions. Vitastor is and will always be designed
+  exactly like that.
+- I also like reinventing the wheel to some extent, like writing my own HTTP client
+  for etcd interaction instead of using prebuilt libraries, because in this case
+  I'm confident about what my code does and what it doesn't do.
+- I don't care about C++ "best practices" like RAII or proper inheritance or usage of
+  smart pointers or whatever and I don't intend to change my mind, so if you're here
+  looking for ideal reference C++ code, this probably isn't the right place.
+- I like node.js better than any other dynamically-typed language interpreter
+  because it's faster than any other interpreter in the world, has neutral C-like
+  syntax and built-in event loop. That's why Monitor is implemented in node.js.
+
+## Known Problems
+
+- Deleting images in a degraded cluster may currently lead to objects reappearing
+  after dead OSDs come back, and in case of erasure-coded pools, they may even
+  reappear as incomplete. Just repeat the removal request again in this case.
+  This problem will be fixed in the nearest future, the fix is already implemented
+  in the "epoch-deletions" branch.

docs/intro/architecture.ru.md

@@ -0,0 +1,208 @@
+[Документация](../../README-ru.md#документация) → Введение → Архитектура
+
+-----
+
+[Read in English](architecture.en.md)
+
+# Архитектура
+
+Краткое описание архитектуры Vitastor.
+
+- [Серверные компоненты](#серверные-компоненты)
+- [Базовые понятия](#базовые-понятия)
+- [Клиентские компоненты](#клиентские-компоненты)
+- [Общий процесс записи и чтения](#общий-процесс-записи-и-чтения)
+  - [Особенности обработки запросов](#особенности-обработки-запросов)
+- [Схожесть с Ceph](#схожесть-с-ceph)
+- [Отличия от Ceph](#отличия-от-ceph)
+- [Принципы разработки](#принципы-разработки)
+
+## Серверные компоненты
+
+- **OSD** (Object Storage Daemon) — процесс, который непосредственно работает с диском, пишет и читает данные.
+  Один OSD управляет одним диском (или разделом). OSD общаются с etcd и друг с другом — от etcd они
+  получают состояние кластера, а друг другу передают запросы записи и чтения вторичных копий данных.
+- **etcd** — кластерная key/value база данных, используется для хранения настроек и верхнеуровневого
+  состояния кластера, а также предотвращения разделения сознания. Блоки данных в etcd не хранятся,
+  в обработке клиентских запросов чтения и записи etcd не участвует.
+- **Монитор** — отдельный демон на node.js, рассчитывающий необходимые изменения в конфигурацию
+  кластера, сохраняющий эту информацию в etcd и таким образом командующий OSD применить эти изменения.
+  Также агрегирует статистику. Контактирует только с etcd, OSD с монитором не общаются.
+
+## Базовые понятия
+
+- **Пул (Pool)** — контейнер для данных, имеющих одну и ту же схему избыточности и правила распределения по OSD.
+- **PG (Placement Group)** — "шард", единица деления пулов в кластере, которой назначается свой набор
+  OSD для хранения данных (копий или частей объектов).
+- **Домен отказа (Failure Domain)** — группа OSD, одновременное падение которых рассматривается
+  как вероятное. По умолчанию это "host" (сервер).
+- **Дерево распределения** (Placement Tree, в Ceph CRUSH Tree) — иерархическая группировка OSD
+  в узлы, которые далее можно использовать как домены отказа.
+
+## Клиентские компоненты
+
+- **Клиентская библиотека** — инкапсулирует логику на стороне клиента. Соединяются с etcd и со всеми OSD,
+  от etcd получают состояние кластера, команды чтения и записи отправляют на все OSD напрямую.
+  В силу архитектуры все отдельные блоки данных (по умолчанию по 128 КБ) располагается на разных
+  OSD, но клиент устроен так, что всегда точно знает, к какому OSD обращаться, и подключается
+  к нему напрямую.
+
+На базе клиентской библиотеки реализованы все остальные клиенты:
+
+- **vitastor-cli** — утилита командной строки для управления кластером. В данный момент позволяет
+  просматривать общее состояние кластера и управлять образами — т.е. создавать, менять и удалять
+  виртуальные диски, их снимки и клоны.
+- **Драйвер QEMU** — подключаемый модуль QEMU, позволяющий QEMU/KVM виртуальным машинам работать
+  с виртуальными дисками Vitastor напрямую из пространства пользователя с помощью клиентской
+  библиотеки, без необходимости отображения дисков в виде блочных устройств.
+- **vitastor-nbd** — утилита, позволяющая монтировать образы Vitastor в виде блочных устройств
+  с помощью NBD (Network Block Device), на самом деле скорее работающего как "BUSE"
+  (Block Device In Userspace). Модуля ядра Linux для выполнения той же задачи в Vitastor нет
+  (по крайней мере, пока).
+- **CSI драйвер** — драйвер для подключения Vitastor-образов в виде персистентных томов (PV) Kubernetes.
+  Работает через vitastor-nbd — образы отражаются в виде блочных устройств и монтируются
+  в контейнеры.
+- **Драйвера Proxmox, OpenStack и т.п.** — подключаемые модули для соответствующих систем,
+  позволяющие использовать Vitastor как хранилище в оных.
+- **vitastor-nfs** — утилита, предоставляющая файловый доступ к образам в кластере Vitastor
+  по протоколу NFS 3.0. Предназначена для гипервизоров, не основанных на QEMU и Linux, но при
+  этом поддерживающих NFS.
+
+## Общий процесс записи и чтения
+
+- В Vitastor хранятся виртуальные диски, также называемые "образы" или "иноды".
+- Каждый образ хранится в определённом пуле. Пул определяет параметры хранения образов в нём,
+  такие, как схему избыточности (репликация или EC — коды коррекции ошибок), домен отказа
+  и ограничения по выбору OSD для размещения данных образов. См. [Конфигурация пулов](../config/pool.ru.md).
+- Каждый образ разбивается на объекты фиксированного размера, равного [block_size](../config/layout-cluster.ru.md#block_size)
+  (по умолчанию 128 КБ), умноженному на число частей данных для EC или на 1 для реплик.
+  То есть, например, если в пуле используется схема кодирования 4+2 (4 части данных + 2 чётности),
+  то при стандартном block_size образы разбиваются на части по 512 КБ.
+- Клиентские запросы чтения/записи разделяются на части, соответствующие этим объектам.
+- Для каждого объекта определяется номер PG, которой он принадлежит, путём простого взятия
+  остатка от деления ID образа и смещения на число PG в пуле, которому принадлежит образ.
+- Клиент читает информацию о первичном OSD всех PG из etcd. Первичный OSD каждой PG назначается
+  монитором в процессе работы кластера, вместе с текущим целевым набором OSD этой PG.
+- Клиент соединяется (если ещё не соединён) с первичными OSD всех PG, объекты которых участвуют
+  в запросе и одновременно отправляет им запросы чтения/записи частей.
+- Если какие-то из первичных OSD недоступны, клиент повторяет попытки соединения бесконечно до
+  тех пор, пока они не станут доступны или пока PG не будут назначены другие первичные OSD.
+- Клиент также повторяет запросы, если первичные OSD отвечают кодом ошибки EPIPE, означающим,
+  что запрос не может быть обработан в данный момент. Это происходит, если PG либо не активна
+  вообще, либо не активна на данном OSD в данный момент (например, если в этот момент меняется
+  её первичный OSD) или если в процессе обработки запроса сам первичный OSD теряет подключение
+  к репликам.
+- Первичный OSD определяет, на каких OSD находятся части объекта. По умолчанию все объекты
+  считаются находящимися на текущем целевом наборе OSD соответствующей PG, но какие-то могут
+  находиться на других OSD, если эти объекты деградированы или перемещены, или идёт процесс
+  ребаланса. Запросы для проверки по сети не отправляются, информация о местоположении всех
+  объектов рассчитывается первичным OSD при активации PG и хранится в памяти.
+- Первичный OSD соединяется (если ещё не соединён) с вторичными OSD, на которых располагаются
+  части объекта, и отправляет им запросы чтения/записи, а также читает/пишет из/в своё локальное
+  хранилище, если сам входит в набор.
+- После завершения всех вторичных операций чтения/записи первичный OSD отправляет ответ клиенту.
+
+### Особенности обработки запросов
+
+- Если в пуле используются коды коррекции ошибок и при этом часть OSD недоступна, первичный
+  OSD при чтении восстанавливает данные из оставшихся частей.
+- Каждый объект имеет номер версии. При записи объекта первичный OSD сначала читает из номер
+  версии объекта. Так как первичный OSD обычно сам хранит копию или часть объекта, номер
+  версии обычно читается из памяти самого OSD. Однако, если ни одна часть обновляемого объекта
+  не находится на первичном OSD, для получения номера версии он обращается к одному из вторичных
+  OSD, на которых копия объекта есть. Обращения к диску при этом всё равно не происходит,
+  так как метаданные объектов, включая номер версии, все OSD хранят в памяти.
+- Если в пуле используются коды коррекции ошибок, перед частичной записью объекта для вычисления
+  чётности зачастую требуется чтение частей объекта с вторичных OSD или с локального диска
+  самого первичного OSD.
+- Также, если в пуле используются коды коррекции ошибок, для закрытия Write Hole применяется
+  двухфазный алгоритм записи: сначала на все вторичные OSD записывается новая версия частей
+  объекта, но при этом старая версия не удаляется, а потом, после получения подтверждения
+  успешной записи от всех вторичных OSD, новая версия фиксируется и разрешается удаление старой.
+- Если в кластере не включён режим immediate_commit, то запросы записи, отправляемые клиентами,
+  не считаются зафиксированными на физических накопителях сразу. Для фиксации данных клиенты
+  должны отдельно отправлять запросы SYNC (отдельный от чтения и записи вид запроса),
+  а пока такой запрос не отправлен, считается, что записанные данные могут исчезнуть,
+  если соответствующий OSD упадёт. Поэтому, когда режим immediate_commit отключён, все
+  запросы записи клиенты копируют в памяти и при потере соединения и повторном соединении
+  с OSD повторяют из памяти. Скопированные в память данные удаляются при успешном fsync,
+  а чтобы хранение этих данных не приводило к чрезмерному потреблению памяти, клиенты
+  автоматически выполняют fsync каждые [client_dirty_limit](../config/layout-cluster.ru.md#client_dirty_limit)
+  записанных байт.
+
+## Схожесть с Ceph
+
+- В Vitastor тоже есть пулы (pools), PG, OSD, мониторы, домены отказы, дерево распределения (аналог crush-дерева).
+- Vitastor тоже равномерно распределяет данные каждого образа по всем PG пула.
+- Vitastor тоже транзакционный, то есть, каждая запись в кластер атомарна.
+- У Vitastor OSD тоже есть журнал и метаданные и их тоже можно размещать на отдельном диске.
+- Как и в Ceph, клиентская библиотека пытается дождаться восстановления работы
+  при любом полном или частичном отказе кластера, то есть, вы можете перезагрузить
+  хоть весь кластер разом, и клиенты не отключатся, только на время зависнут.
+
+## Отличия от Ceph
+
+- Vitastor в первую очередь сфокусирован на использовании с SSD: либо в кластерах на основе
+  только SSD, либо гибридных (HDD с журналами на SSD).
+- Базовый слой Vitastor — простое блочное хранилище с блоками фиксированного размера, а не
+  объектное со сложной семантикой, как в Ceph (RADOS).
+- PG в Vitastor эфемерны. Это означает, что они не хранятся на дисках и существуют только в
+  памяти работающих OSD.
+- Vitastor OSD однопоточные и всегда такими останутся. Если вам нужно выделить больше 1 ядра
+  на 1 диск — создайте несколько OSD на разделах этого диска. Нужно это в основном для NVMe,
+  так как Vitastor не потребляет много ресурсов CPU.
+- Метаданные всегда размещаются в памяти, благодаря чему никогда не тратится лишнее время
+  на чтение метаданных с диска. Объём метаданных линейно зависит от ёмкости диска и размера
+  блока хранилища (block_size, по умолчанию 128 КБ). С 128 КБ блоком потребление памяти
+  составляет примерно 512 МБ на 1 ТБ данных. Журналы по умолчанию тоже хранятся в памяти,
+  но в SSD-кластерах нужный размер журнала составляет всего 32 МБ, а в гибридных (SSD+HDD)
+  кластерах, в которых есть смысл делать журналы больше, можно отключить [inmemory_journal](../docs/config/osd.ru.md#inmemory_journal).
+- В Vitastor нет внутреннего copy-on-write. Я считаю, что реализация CoW-хранилища гораздо сложнее,
+  поэтому сложнее добиться устойчиво хороших результатов. Возможно, в один прекрасный день
+  я придумаю красивый алгоритм для CoW-хранилища, но пока нет — внутреннего CoW в Vitastor не будет.
+  Всё это не относится к "внешнему" CoW (снапшотам и клонам).
+- В Vitastor есть режим "ленивых fsync", в котором OSD группирует запросы записи перед сбросом их
+  на диск, что позволяет получить лучшую производительность с дешёвыми настольными SSD без конденсаторов
+  ("Advanced Power Loss Protection" / "Capacitor-Based Power Loss Protection").
+  Тем не менее, такой режим всё равно медленнее использования нормальных серверных SSD и мгновенного
+  fsync, так как приводит к дополнительным операциям передачи данных по сети, поэтому рекомендуется
+  всё-таки использовать хорошие серверные диски, тем более, стоят они почти так же, как десктопные.
+- Процессы восстановления оперируют отдельными объектами, а не целыми PG.
+- "Мониторы" не хранят данные. Конфигурация и состояние кластера хранятся в etcd в простых человекочитаемых
+  JSON-структурах. Мониторы Vitastor только следят за состоянием кластера и управляют перемещением данных.
+  В этом смысле монитор Vitastor не является критичным компонентом системы и больше похож на Ceph-овский
+  менеджер (MGR). Монитор Vitastor написан на node.js.
+- Распределение PG не основано на консистентных хешах. Вместо этого все маппинги PG хранятся прямо в etcd
+  (ибо нет никакой проблемы сохранить несколько сотен-тысяч записей в памяти, а не считать каждый раз хеши).
+  Перераспределение PG по OSD выполняется через математическую оптимизацию,
+  а конкретно, сведение задачи к ЛП (задаче линейного программирования) и решение оной с помощью утилиты
+  lp_solve. Такой подход позволяет обычно выравнивать распределение места почти идеально — равномерность
+  обычно составляет 96-99%, в отличие от Ceph, где на голом CRUSH-е без балансировщика обычно выходит 80-90%.
+  Также это позволяет минимизировать объём перемещения данных и случайность связей между OSD, а также менять
+  распределение вручную, не боясь сломать логику перебалансировки. В таком подходе есть и потенциальный
+  недостаток — есть предположение, что в очень большом кластере он может сломаться — однако вплоть до
+  нескольких сотен OSD подход точно работает нормально. Ну и, собственно, при необходимости легко
+  реализовать и консистентные хеши.
+- Отдельный слой, подобный слою "CRUSH-правил", отсутствует. Вы настраиваете схемы отказоустойчивости,
+  домены отказа и правила выбора OSD напрямую в конфигурации пулов.
+
+## Принципы разработки
+
+- Я люблю простые решения. Поэтому Vitastor простой и быстрый и всегда будет таковым.
+- Я не против иногда изобрести велосипед, например, собственный простенький HTTP-клиент
+  для работы с etcd, вместо того, чтобы взять тяжёлую готовую библиотеку, ибо в данном
+  случае я точно уверен в том, что знаю, что делает код.
+- Общепринятые практики написания C++ кода с RAII, наследованием, умными указателями
+  и так далее меня также не волнуют, поэтому если вы хотели увидеть здесь красивый
+  идиоматичный C++ код, вы, вероятно, пришли не по адресу.
+- Из всех интерпретаторов скриптоты больше всех я люблю node.js, это самый быстрый в мире
+  интерпретатор, у него есть встроенная событийная машина, развитая инфраструктура и
+  приятный нейтральный C-подобный язык программирования. Поэтому Монитор реализован на node.js.
+
+## Известные проблемы
+
+- Удаление образов в деградированном кластере может в данный момент приводить к повторному
+  "появлению" удалённых объектов после поднятия отключённых OSD, причём в случае EC-пулов,
+  объекты могут появиться в виде "неполных". Если вы столкнётесь с такой ситуацией, просто
+  повторите запрос удаления. Исправление этой проблемы уже реализовано в ветке "epoch-deletions"
+  и вскоре будет включено в релиз.

docs/intro/author.en.md

@@ -0,0 +1,37 @@
+[Documentation](../../README.md#documentation) → Introduction → Author and License
+
+-----
+
+[Читать на русском](author.ru.md)
+
+# Author and License
+
+Copyright (c) Vitaliy Filippov (vitalif [at] yourcmc.ru), 2019+
+
+Join Vitastor Telegram Chat: https://t.me/vitastor
+
+All server-side code (OSD, Monitor and so on) is licensed under the terms of
+Vitastor Network Public License 1.1 (VNPL 1.1), a copyleft license based on
+GNU GPLv3.0 with the additional "Network Interaction" clause which requires
+opensourcing all programs directly or indirectly interacting with Vitastor
+through a computer network and expressly designed to be used in conjunction
+with it ("Proxy Programs"). Proxy Programs may be made public not only under
+the terms of the same license, but also under the terms of any GPL-Compatible
+Free Software License, as listed by the Free Software Foundation.
+This is a stricter copyleft license than the Affero GPL.
+
+Please note that VNPL doesn't require you to open the code of proprietary
+software running inside a VM if it's not specially designed to be used with
+Vitastor.
+
+Basically, you can't use the software in a proprietary environment to provide
+its functionality to users without opensourcing all intermediary components
+standing between the user and Vitastor or purchasing a commercial license
+from the author 😀.
+
+Client libraries (cluster_client and so on) are dual-licensed under the same
+VNPL 1.1 and also GNU GPL 2.0 or later to allow for compatibility with GPLed
+software like QEMU and fio.
+
+You can find the full text of VNPL-1.1 in the file [VNPL-1.1.txt](../../VNPL-1.1.txt).
+GPL 2.0 is also included in this repository as [GPL-2.0.txt](../../GPL-2.0.txt).

docs/intro/author.ru.md

@@ -0,0 +1,37 @@
+[Документация](../../README-ru.md#документация) → Введение → Автор и лицензия
+
+-----
+
+[Read in English](author.en.md)
+
+# Автор и лицензия
+
+Автор: Виталий Филиппов (vitalif [at] yourcmc.ru), 2019+
+
+Заходите в Telegram-чат Vitastor: https://t.me/vitastor
+
+Лицензия: VNPL 1.1 на серверный код и двойная VNPL 1.1 + GPL 2.0+ на клиентский.
+
+VNPL - "сетевой копилефт", собственная свободная копилефт-лицензия
+Vitastor Network Public License 1.1, основанная на GNU GPL 3.0 с дополнительным
+условием "Сетевого взаимодействия", требующим распространять все программы,
+специально разработанные для использования вместе с Vitastor и взаимодействующие
+с ним по сети, под лицензией VNPL или под любой другой свободной лицензией.
+
+Идея VNPL - расширение действия копилефта не только на модули, явным образом
+связываемые с кодом Vitastor, но также на модули, оформленные в виде микросервисов
+и взаимодействующие с ним по сети.
+
+Таким образом, если вы хотите построить на основе Vitastor сервис, содержаший
+компоненты с закрытым кодом, взаимодействующие с Vitastor, вам нужна коммерческая
+лицензия от автора 😀.
+
+На Windows и любое другое ПО, не разработанное *специально* для использования
+вместе с Vitastor, никакие ограничения не накладываются.
+
+Клиентские библиотеки распространяются на условиях двойной лицензии VNPL 1.0
+и также на условиях GNU GPL 2.0 или более поздней версии. Так сделано в целях
+совместимости с таким ПО, как QEMU и fio.
+
+Вы можете найти полный текст VNPL 1.1 в файле [VNPL-1.1.txt](../../VNPL-1.1.txt),
+а GPL 2.0 в файле [GPL-2.0.txt](../../GPL-2.0.txt).

docs/intro/features.en.md

@@ -0,0 +1,62 @@
+[Documentation](../../README.md#documentation) → Introduction → Features
+
+-----
+
+[Читать на русском](features.ru.md)
+
+# Features
+
+- [Server-side features](#server-side-features)
+- [Plugins and tools](#plugins-and-tools)
+- [Roadmap](#roadmap)
+
+## Server-side features
+
+- Basic part: highly-available block storage with symmetric clustering and no SPOF
+- [Performance](../performance/comparison1.en.md) ;-D
+- [Multiple redundancy schemes](../config/pool.en.md#scheme): Replication, XOR n+1, Reed-Solomon erasure codes
+  based on jerasure library with any number of data and parity drives in a group
+- Configuration via simple JSON data structures in etcd (parameters, pools and images)
+- Automatic data distribution over OSDs, with support for:
+  - Mathematical optimization for better uniformity and less data movement
+  - Multiple pools
+  - Placement tree, OSD selection by tags (device classes) and placement root
+  - Configurable failure domains
+- Recovery of degraded blocks
+- Rebalancing (data movement between OSDs)
+- [Lazy fsync support](../config/layout-cluster.en.md#immediate_commit)
+- Per-OSD and per-image I/O and space usage statistics in etcd
+- Snapshots and copy-on-write image clones
+- [Write throttling to smooth random write workloads in SSD+HDD configurations](../config/osd.en.md#throttle_small_writes)
+- [RDMA/RoCEv2 support via libibverbs](../config/network.en.md#rdma_device)
+
+## Plugins and tools
+
+- [Debian and CentOS packages](../installation/packages.en.md)
+- [Image management CLI (vitastor-cli)](../usage/cli.en.md)
+- Generic user-space client library
+- [Native QEMU driver](../usage/qemu.en.md)
+- [Loadable fio engine for benchmarks](../usage/fio.en.md)
+- [NBD proxy for kernel mounts](../usage/nbd.en.md)
+- [CSI plugin for Kubernetes](../installation/kubernetes.en.md)
+- [OpenStack support: Cinder driver, Nova and libvirt patches](../installation/openstack.en.md)
+- [Proxmox storage plugin and packages](../installation/proxmox.en.md)
+- [Simplified NFS proxy for file-based image access emulation (suitable for VMWare)](../usage/nfs.en.md)
+
+## Roadmap
+
+The following features are planned for the future:
+
+- Better OSD creation and auto-start tools
+- Other administrative tools
+- Web GUI
+- OpenNebula plugin
+- iSCSI proxy
+- Multi-threaded client
+- Faster failover
+- Scrubbing without checksums (verification of replicas)
+- Checksums
+- Tiered storage (SSD caching)
+- NVDIMM support
+- Compression (possibly)
+- Read caching using system page cache (possibly)

docs/intro/features.ru.md

@@ -0,0 +1,62 @@
+[Документация](../../README-ru.md#документация) → Введение → Возможности Vitastor
+
+-----
+
+[Read in English](features.en.md)
+
+# Возможности Vitastor
+
+- [Серверные функции](#серверные-функции)
+- [Драйверы и инструменты](#драйверы-и-инструменты)
+- [Планы развития](#планы-развития)
+
+## Серверные функции
+
+- Базовая часть - надёжное кластерное блочное хранилище без единой точки отказа
+- [Производительность](../comparison1.ru.md) ;-D
+- [Несколько схем отказоустойчивости](../config/pool.ru.md#scheme): репликация, XOR n+1 (1 диск чётности), коды коррекции ошибок
+  Рида-Соломона на основе библиотеки jerasure с любым числом дисков данных и чётности в группе
+- Конфигурация через простые человекочитаемые JSON-структуры в etcd
+- Автоматическое распределение данных по OSD, с поддержкой:
+  - Математической оптимизации для лучшей равномерности распределения и минимизации перемещений данных
+  - Нескольких пулов с разными схемами избыточности
+  - Дерева распределения, выбора OSD по тегам / классам устройств (только SSD, только HDD) и по поддереву
+  - Настраиваемых доменов отказа (диск/сервер/стойка и т.п.)
+- Восстановление деградированных блоков
+- Ребаланс, то есть перемещение данных между OSD (дисками)
+- [Поддержка "ленивого" fsync (fsync не на каждую операцию)](../config/layout-cluster.ru.md#immediate_commit)
+- Сбор статистики ввода/вывода в etcd
+- Статистика операций ввода/вывода и занятого места в разрезе инодов
+- Именование инодов через хранение их метаданных в etcd
+- Снапшоты и copy-on-write клоны
+- [Сглаживание производительности случайной записи в SSD+HDD конфигурациях](../config/osd.ru.md#throttle_small_writes)
+- [Поддержка RDMA/RoCEv2 через libibverbs](../config/network.ru.md#rdma_device)
+
+## Драйверы и инструменты
+
+- [Пакеты для Debian и CentOS](../installation/packages.ru.md)
+- [Консольный интерфейс управления образами (vitastor-cli)](../usage/cli.ru.md)
+- Общая пользовательская клиентская библиотека для работы с кластером
+- [Драйвер диска для QEMU](../usage/qemu.ru.md)
+- [Драйвер диска для утилиты тестирования производительности fio](../usage/fio.ru.md)
+- [NBD-прокси для монтирования образов ядром](../usage/nbd.ru.md) ("блочное устройство в режиме пользователя")
+- [CSI-плагин для Kubernetes](../installation/kubernetes.ru.md)
+- [Базовая поддержка OpenStack: драйвер Cinder, патчи для Nova и libvirt](../installation/openstack.ru.md)
+- [Плагин для Proxmox](../installation/proxmox.ru.md)
+- [Упрощённая NFS-прокси для эмуляции файлового доступа к образам (подходит для VMWare)](../usage/nfs.ru.md)
+
+## Планы развития
+
+- Более корректные скрипты разметки дисков и автоматического запуска OSD
+- Другие инструменты администрирования
+- Web-интерфейс
+- Плагин для OpenNebula
+- iSCSI-прокси
+- Многопоточный клиент
+- Более быстрое переключение при отказах
+- Фоновая проверка целостности без контрольных сумм (сверка реплик)
+- Контрольные суммы
+- Поддержка SSD-кэширования (tiered storage)
+- Поддержка NVDIMM
+- Возможно, сжатие
+- Возможно, поддержка кэширования данных через системный page cache

docs/intro/quickstart.en.md

@@ -0,0 +1,95 @@
+[Documentation](../../README.md#documentation) → Introduction → Quick Start
+
+-----
+
+[Читать на русском](quickstart.ru.md)
+
+# Quick Start
+
+- [Preparation](#preparation)
+- [Configure monitors](#configure-monitors)
+- [Configure OSDs](#configure-osds)
+- [Create a pool](#create-a-pool)
+- [Check cluster status](#check-cluster-status)
+- [Create an image](#create-an-image)
+- [Install plugins](#install-plugins)
+
+## Preparation
+
+- Get some SATA or NVMe SSDs with capacitors (server-grade drives). You can use desktop SSDs
+  with lazy fsync, but prepare for inferior single-thread latency. Read more about capacitors
+  [here](../config/layout-cluster.en.md#immediate_commit).
+- Get a fast network (at least 10 Gbit/s). Something like Mellanox ConnectX-4 with RoCEv2 is ideal.
+- Disable CPU powersaving: `cpupower idle-set -D 0 && cpupower frequency-set -g performance`.
+- [Install Vitastor packages](../installation/packages.en.md).
+
+## Configure monitors
+
+On the monitor hosts:
+- Edit variables at the top of `/usr/lib/vitastor/mon/make-units.sh` to desired values.
+- Create systemd units for the monitor and etcd: `/usr/lib/vitastor/mon/make-units.sh`
+- Start etcd and monitors: `systemctl start etcd vitastor-mon`
+
+## Configure OSDs
+
+- Put etcd_address and osd_network into `/etc/vitastor/vitastor.conf`. Example:
+  ```
+  {
+    "etcd_address": ["10.200.1.10:2379","10.200.1.11:2379","10.200.1.12:2379"],
+    "osd_network": "10.200.1.0/24"
+  }
+  ```
+- Initialize OSDs:
+  - Simplest, SSD-only: `/usr/lib/vitastor/mon/make-osd.sh /dev/disk/by-partuuid/XXX [/dev/disk/by-partuuid/YYY ...]`
+    **Warning!** This very simple script by default makes units for server-grade SSDs with write-through cache!
+    If it's not your case, you MUST remove disable_data_fsync and immediate_commit from systemd units.
+  - Hybrid, HDD+SSD: `/usr/lib/vitastor/mon/make-osd-hybrid.js /dev/sda /dev/sdb ...` — pass all your
+    devices (HDD and SSD) to this script — it will partition disks and initialize journals on its own.
+    This script skips HDDs which are already partitioned so if you want to use non-empty disks for
+    Vitastor you should first wipe them with `wipefs -a`. SSDs with GPT partition table are not skipped,
+    but some free unpartitioned space must be available because the script creates new partitions for journals.
+- You can change OSD configuration in units or in `vitastor.conf`.
+  Check [Configuration Reference](../config.en.md) for parameter descriptions.
+- If all your drives have capacitors, create global configuration in etcd: \
+  `etcdctl --endpoints=... put /vitastor/config/global '{"immediate_commit":"all"}'`
+- Start all OSDs: `systemctl start vitastor.target`
+
+## Create a pool
+
+Create pool configuration in etcd:
+
+```
+etcdctl --endpoints=... put /vitastor/config/pools '{"1":{"name":"testpool",
+  "scheme":"replicated","pg_size":2,"pg_minsize":1,"pg_count":256,"failure_domain":"host"}}'
+```
+
+For jerasure pools the configuration should look like the following:
+
+```
+etcdctl --endpoints=... put /vitastor/config/pools '{"2":{"name":"ecpool",
+  "scheme":"jerasure","pg_size":4,"parity_chunks":2,"pg_minsize":2,"pg_count":256,"failure_domain":"host"}`
+```
+
+After you do this, one of the monitors will configure PGs and OSDs will start them.
+
+## Check cluster status
+
+`vitastor-cli status`
+
+Or you can check PG states with `etcdctl --endpoints=... get --prefix /vitastor/pg/state`. All PGs should become 'active'.
+
+## Create an image
+
+Use vitastor-cli ([read CLI documentation here](../usage/cli.en.md)):
+
+```
+vitastor-cli create -s 10G testimg
+```
+
+After that, you can [run benchmarks](../usage/fio.en.md) or [start QEMU manually](../usage/qemu.en.md) with this image.
+
+## Install plugins
+
+- [Proxmox](../installation/proxmox.en.md)
+- [OpenStack](../installation/openstack.en.md)
+- [Kubernetes CSI](../installation/kubernetes.en.md)

docs/intro/quickstart.ru.md

@@ -0,0 +1,103 @@
+[Документация](../../README-ru.md#документация) → Введение → Быстрый старт
+
+-----
+
+[Read in English](quickstart.en.md)
+
+# Быстрый старт
+
+- [Подготовка](#подготовка)
+- [Настройте мониторы](#настройте-мониторы)
+- [Настройте OSD](#настройте-osd)
+- [Создайте пул](#создайте-пул)
+- [Проверьте состояние кластера](#проверьте-состояние-кластера)
+- [Создайте образ](#создайте-образ)
+- [Установите плагины](#установите-плагины)
+
+## Подготовка
+
+- Возьмите серверы с SSD (SATA или NVMe), желательно с конденсаторами (серверные SSD). Можно
+  использовать и десктопные SSD, включив режим отложенного fsync, но производительность будет хуже.
+  О конденсаторах читайте [здесь](../config/layout-cluster.ru.md#immediate_commit).
+- Возьмите быструю сеть, минимум 10 гбит/с. Идеал - что-то вроде Mellanox ConnectX-4 с RoCEv2.
+- Для лучшей производительности отключите энергосбережение CPU: `cpupower idle-set -D 0 && cpupower frequency-set -g performance`.
+- [Установите пакеты Vitastor](../installation/packages.ru.md).
+
+## Настройте мониторы
+
+На хостах, выделенных под мониторы:
+- Пропишите нужные вам значения в файле `/usr/lib/vitastor/mon/make-units.sh`
+- Создайте юниты systemd для etcd и мониторов: `/usr/lib/vitastor/mon/make-units.sh`
+- Запустите etcd и мониторы: `systemctl start etcd vitastor-mon`
+- Пропишите etcd_address и osd_network в `/etc/vitastor/vitastor.conf`. Например:
+  ```
+  {
+    "etcd_address": ["10.200.1.10:2379","10.200.1.11:2379","10.200.1.12:2379"],
+    "osd_network": "10.200.1.0/24"
+  }
+  ```
+
+## Настройте OSD
+
+- Пропишите etcd_address и osd_network в `/etc/vitastor/vitastor.conf`. Например:
+  ```
+  {
+    "etcd_address": ["10.200.1.10:2379","10.200.1.11:2379","10.200.1.12:2379"],
+    "osd_network": "10.200.1.0/24"
+  }
+  ```
+- Инициализуйте OSD:
+  - SSD: `/usr/lib/vitastor/make-osd.sh /dev/disk/by-partuuid/XXX [/dev/disk/by-partuuid/YYY ...]`. \
+    **Внимание!** Скрипт по умолчанию рассчитан на то, что у вас диски с конденсаторами и отключённым
+    кэшем! Если это не так, из юнитов systemd нужно убрать строчки disable_data_fsync и immediate_commit!
+  - Гибридные, HDD+SSD: `/usr/lib/vitastor/mon/make-osd-hybrid.js /dev/sda /dev/sdb ...` - передайте
+    все ваши SSD и HDD скрипту в командной строке подряд, скрипт автоматически выделит разделы под
+    журналы на SSD и данные на HDD. Скрипт пропускает HDD, на которых уже есть разделы
+    или вообще какие-то данные, поэтому если диски непустые, сначала очистите их с помощью
+    `wipefs -a`. SSD с таблицей разделов не пропускаются, но так как скрипт создаёт новые разделы
+    для журналов, на SSD должно быть доступно свободное нераспределённое место.
+- Вы можете менять параметры OSD в юнитах systemd или в `vitastor.conf`. Описания параметров
+  смотрите в [справке по конфигурации](../config.ru.md).
+- Если все ваши диски - серверные с конденсаторами, пропишите это в глобальную конфигурацию в etcd: \
+  `etcdctl --endpoints=... put /vitastor/config/global '{"immediate_commit":"all"}'`
+- Запустите все OSD: `systemctl start vitastor.target`
+
+## Создайте пул
+
+Создайте конфигурацию пула с помощью etcdctl:
+
+```
+etcdctl --endpoints=... put /vitastor/config/pools '{"1":{"name":"testpool",
+  "scheme":"replicated","pg_size":2,"pg_minsize":1,"pg_count":256,"failure_domain":"host"}}'
+```
+
+Для пулов с кодами коррекции ошибок конфигурация должна выглядеть примерно так:
+
+```
+etcdctl --endpoints=... put /vitastor/config/pools '{"2":{"name":"ecpool",
+  "scheme":"jerasure","pg_size":4,"parity_chunks":2,"pg_minsize":2,"pg_count":256,"failure_domain":"host"}`
+```
+
+После этого один из мониторов должен сконфигурировать PG, а OSD должны запустить их.
+
+## Проверьте состояние кластера
+
+`vitastor-cli status`
+
+Либо же вы можете проверять состояние PG прямо в etcd: `etcdctl --endpoints=... get --prefix /vitastor/pg/state`. Все PG должны быть 'active'.
+
+## Создайте образ
+
+Используйте vitastor-cli ([смотрите документацию CLI здесь](../usage/cli.ru.md)):
+
+```
+vitastor-cli create -s 10G testimg
+```
+
+После этого вы можете [запускать тесты](../usage/fio.ru.md) или [вручную запускать QEMU](../usage/qemu.ru.md) с новым образом.
+
+## Установите плагины
+
+- [Proxmox](../installation/proxmox.ru.md)
+- [OpenStack](../installation/openstack.ru.md)
+- [Kubernetes CSI](../installation/kubernetes.ru.md)

docs/performance/comparison1.en.md

@@ -0,0 +1,108 @@
+[Documentation](../../README.md#documentation) → Performance → Example Comparison with Ceph
+
+-----
+
+[Читать на русском](comparison1.ru.md)
+
+# Example Comparison with Ceph
+
+- [Test environment](#test-environment)
+- [Raw drive performance](#raw-drive-performance)
+- [2 replicas](#2-replicas)
+  - [Ceph 15.2.4 (Bluestore)](#ceph-15-2-4-bluestore)
+  - [Vitastor 0.4.0 (native)](#vitastor-0-4-0-native)
+  - [Vitastor 0.4.0 (NBD)](#vitastor-0-4-0-nbd)
+- [EC/XOR 2+1](#ec/xor-2-1)
+  - [Ceph 15.2.4](#ceph-15-2-4)
+  - [Vitastor 0.4.0](#vitastor-0-4-0)
+
+## Test environment
+
+Hardware configuration: 4 nodes, each with:
+- 6x SATA SSD Intel D3-S4510 3.84 TB
+- 2x Xeon Gold 6242 (16 cores @ 2.8 GHz)
+- 384 GB RAM
+- 1x 25 GbE network interface (Mellanox ConnectX-4 LX), connected to a Juniper QFX5200 switch
+
+CPU powersaving was disabled. Both Vitastor and Ceph were configured with 2 OSDs per 1 SSD.
+
+All of the results below apply to 4 KB blocks and random access (unless indicated otherwise).
+
+T8Q64 tests were conducted over 8 400GB RBD images from all hosts (every host was running 2 instances of fio).
+This is because Ceph has performance penalties related to running multiple clients over a single RBD image.
+
+cephx_sign_messages was set to false during tests, RocksDB and Bluestore settings were left at defaults.
+
+T8Q64 read test was conducted over 1 larger inode (3.2T) from all hosts (every host was running 2 instances of fio).
+Vitastor has no performance penalties related to running multiple clients over a single inode.
+If conducted from one node with all primary OSDs moved to other nodes the result was slightly lower (689000 iops),
+this is because all operations resulted in network roundtrips between the client and the primary OSD.
+When fio was colocated with OSDs (like in Ceph benchmarks above), 1/4 of the read workload actually
+used the loopback network.
+
+Vitastor was configured with: `--disable_data_fsync true --immediate_commit all --flusher_count 8
+  --disk_alignment 4096 --journal_block_size 4096 --meta_block_size 4096
+  --journal_no_same_sector_overwrites true --journal_sector_buffer_count 1024
+  --journal_size 16777216`.
+
+## Raw drive performance
+
+- T1Q1 write ~27000 iops (~0.037ms latency)
+- T1Q1 read ~9800 iops (~0.101ms latency)
+- T1Q32 write ~60000 iops
+- T1Q32 read ~81700 iops
+
+## 2 replicas
+
+### Ceph 15.2.4 (Bluestore)
+
+- T1Q1 write ~1000 iops (~1ms latency)
+- T1Q1 read ~1750 iops (~0.57ms latency)
+- T8Q64 write ~100000 iops, total CPU usage by OSDs about 40 virtual cores on each node
+- T8Q64 read ~480000 iops, total CPU usage by OSDs about 40 virtual cores on each node
+
+In fact, not that bad for Ceph. These servers are an example of well-balanced Ceph nodes.
+However, CPU usage and I/O latency were through the roof, as usual.
+
+### Vitastor 0.4.0 (native)
+
+- T1Q1 write: 7087 iops (0.14ms latency)
+- T1Q1 read: 6838 iops (0.145ms latency)
+- T2Q64 write: 162000 iops, total CPU usage by OSDs about 3 virtual cores on each node
+- T8Q64 read: 895000 iops, total CPU usage by OSDs about 4 virtual cores on each node
+- Linear write (4M T1Q32): 2800 MB/s
+- Linear read (4M T1Q32): 1500 MB/s
+
+### Vitastor 0.4.0 (NBD)
+
+NBD is currently required to mount Vitastor via kernel, but it imposes additional overhead
+due to additional copying between the kernel and userspace. This mostly hurts linear
+bandwidth, not iops.
+
+Vitastor with single-threaded NBD on the same hardware:
+- T1Q1 write: 6000 iops (0.166ms latency)
+- T1Q1 read: 5518 iops (0.18ms latency)
+- T1Q128 write: 94400 iops
+- T1Q128 read: 103000 iops
+- Linear write (4M T1Q128): 1266 MB/s (compared to 2800 MB/s via fio)
+- Linear read (4M T1Q128): 975 MB/s (compared to 1500 MB/s via fio)
+
+## EC/XOR 2+1
+
+### Ceph 15.2.4
+
+- T1Q1 write: 730 iops (~1.37ms latency)
+- T1Q1 read: 1500 iops with cold cache (~0.66ms latency), 2300 iops after 2 minute metadata cache warmup (~0.435ms latency)
+- T4Q128 write (4 RBD images): 45300 iops, total CPU usage by OSDs about 30 virtual cores on each node
+- T8Q64 read (4 RBD images): 278600 iops, total CPU usage by OSDs about 40 virtual cores on each node
+- Linear write (4M T1Q32): 1950 MB/s before preallocation, 2500 MB/s after preallocation
+- Linear read (4M T1Q32): 2400 MB/s
+
+### Vitastor 0.4.0
+
+- T1Q1 write: 2808 iops (~0.355ms latency)
+- T1Q1 read: 6190 iops (~0.16ms latency)
+- T2Q64 write: 85500 iops, total CPU usage by OSDs about 3.4 virtual cores on each node
+- T8Q64 read: 812000 iops, total CPU usage by OSDs about 4.7 virtual cores on each node
+- Linear write (4M T1Q32): 3200 MB/s
+- Linear read (4M T1Q32): 1800 MB/s

docs/performance/comparison1.ru.md

@@ -0,0 +1,113 @@
+[Документация](../../README-ru.md#документация) → Производительность → Пример сравнения с Ceph
+
+-----
+
+[Read in English](comparison1.en.md)
+
+# Пример сравнения с Ceph
+
+- [Описание стенда](#описание-стенда)
+- [Производительность голых дисков](#производительность-голых-дисков)
+- [2 реплики](#2-реплики)
+  - [Ceph 15.2.4 (Bluestore)](#ceph-15-2-4-bluestore)
+  - [Vitastor 0.4.0 (нативный драйвер fio)](#vitastor-0-4-0-нативный-драйвер-fio)
+  - [Vitastor 0.4.0 (NBD)](#vitastor-0-4-0-nbd)
+- [EC/XOR 2+1](#ec/xor-2-1)
+  - [Ceph 15.2.4](#ceph-15-2-4)
+  - [Vitastor 0.4.0](#vitastor-0-4-0)
+
+## Описание стенда
+
+Железо: 4 сервера, в каждом:
+- 6x SATA SSD Intel D3-4510 3.84 TB
+- 2x Xeon Gold 6242 (16 cores @ 2.8 GHz)
+- 384 GB RAM
+- 1x 25 GbE сетевая карта (Mellanox ConnectX-4 LX), подключённая к свитчу Juniper QFX5200
+
+Экономия энергии CPU отключена. В тестах и Vitastor, и Ceph развёрнуто по 2 OSD на 1 SSD.
+
+Все результаты ниже относятся к случайной нагрузке 4 КБ блоками (если явно не указано обратное).
+
+Тесты в 8 потоков проводились на 8 400GB RBD образах со всех хостов (с каждого хоста запускалось 2 процесса fio).
+Это нужно потому, что в Ceph несколько RBD-клиентов, пишущих в 1 образ, очень сильно замедляются.
+
+Настройки RocksDB и Bluestore в Ceph не менялись, единственным изменением было отключение cephx_sign_messages.
+
+Тест на чтение в 8 потоков проводился на 1 большом образе (3.2 ТБ) со всех хостов (опять же, по 2 fio с каждого).
+В Vitastor никакой разницы между 1 образом и 8-ю нет. Естественно, примерно 1/4 запросов чтения
+в такой конфигурации, как и в тестах Ceph выше, обслуживалась с локальной машины. Если проводить
+тест так, чтобы все операции всегда обращались к первичным OSD по сети - тест сильнее упирался
+в сеть и результат составлял примерно 689000 iops.
+
+Настройки Vitastor: `--disable_data_fsync true --immediate_commit all --flusher_count 8
+  --disk_alignment 4096 --journal_block_size 4096 --meta_block_size 4096
+  --journal_no_same_sector_overwrites true --journal_sector_buffer_count 1024
+  --journal_size 16777216`.
+
+## Производительность голых дисков
+
+- T1Q1 запись ~27000 iops (задержка ~0.037ms)
+- T1Q1 чтение ~9800 iops (задержка ~0.101ms)
+- T1Q32 запись ~60000 iops
+- T1Q32 чтение ~81700 iops
+
+## 2 реплики
+
+### Ceph 15.2.4 (Bluestore)
+
+- T1Q1 запись ~1000 iops (задержка ~1ms)
+- T1Q1 чтение ~1750 iops (задержка ~0.57ms)
+- T8Q64 запись ~100000 iops, потребление CPU процессами OSD около 40 ядер на каждом сервере
+- T8Q64 чтение ~480000 iops, потребление CPU процессами OSD около 40 ядер на каждом сервере
+
+Если не учитывать как обычно запредельное потребление CPU (40 ядер), не так уж и плохо для Ceph.
+Данные серверы - как раз хороший пример сбалансированных Ceph-нод - 6 SATA SSD как раз
+утилизируют 25-гигабитную сеть, а без 2 мощных процессоров Ceph-у бы не хватило ядер,
+чтобы выдать пристойный результат.
+
+### Vitastor 0.4.0 (нативный драйвер fio)
+
+- T1Q1 запись: 7087 iops (задержка 0.14ms)
+- T1Q1 чтение: 6838 iops (задержка 0.145ms)
+- T2Q64 запись: 162000 iops, потребление CPU - 3 ядра на каждом сервере
+- T8Q64 чтение: 895000 iops, потребление CPU - 4 ядра на каждом сервере
+- Линейная запись (4M T1Q32): 2800 МБ/с
+- Линейное чтение (4M T1Q32): 1500 МБ/с
+
+### Vitastor 0.4.0 (NBD)
+
+NBD расшифровывается как "сетевое блочное устройство", но на самом деле оно также
+работает просто как аналог FUSE для блочных устройств, то есть, представляет собой
+"блочное устройство в пространстве пользователя".
+
+NBD - на данный момент единственный способ монтировать Vitastor ядром Linux. Его
+производительность немного хуже из-за дополнительных операций копирований данных
+между ядром и пространством пользователя, что, правда, в основном затрагивает линейное
+чтение/запись, а не случайный доступ.
+
+- T1Q1 запись: 6000 iops (задержка 0.166ms)
+- T1Q1 чтение: 5518 iops (задержка 0.18ms)
+- T1Q128 запись: 94400 iops
+- T1Q128 чтение: 103000 iops
+- Линейная запись (4M T1Q128): 1266 МБ/с (в сравнении с 2800 МБ/с через fio)
+- Линейное чтение (4M T1Q128): 975 МБ/с (в сравнении с 1500 МБ/с через fio)
+
+## EC/XOR 2+1
+
+### Ceph 15.2.4
+
+- T1Q1 запись: 730 iops (задержка ~1.37ms latency)
+- T1Q1 чтение: 1500 iops с холодным кэшем метаданных (задержка ~0.66ms), 2300 iops через 2 минуты прогрева (задержка ~0.435ms)
+- T4Q128 запись (4 RBD images): 45300 iops, потребление CPU - 30 ядер на каждом сервере
+- T8Q64 чтение (4 RBD images): 278600 iops, потребление CPU - 40 ядер на каждом сервере
+- Линейная запись (4M T1Q32): 1950 МБ/с в пустой образ, 2500 МБ/с в заполненный образ
+- Линейное чтение (4M T1Q32): 2400 МБ/с
+
+### Vitastor 0.4.0
+
+- T1Q1 запись: 2808 iops (задержка ~0.355ms)
+- T1Q1 чтение: 6190 iops (задержка ~0.16ms)
+- T2Q64 запись: 85500 iops, потребление CPU - 3.4 ядра на каждом сервере
+- T8Q64 чтение: 812000 iops, потребление CPU - 4.7 ядра на каждом сервере
+- Линейная запись (4M T1Q32): 3200 МБ/с
+- Линейное чтение (4M T1Q32): 1800 МБ/с

docs/performance/theoretical.en.md

@@ -0,0 +1,49 @@
+[Documentation](../../README.md#documentation) → Performance → Vitastor's Theoretical Maximum Performance
+
+-----
+
+[Читать на русском](theoretical.ru.md)
+
+# Vitastor's Theoretical Maximum Performance
+
+Replicated setups:
+- Single-threaded (T1Q1) read latency: 1 network roundtrip + 1 disk read.
+- Single-threaded write+fsync latency:
+  - With immediate commit: 2 network roundtrips + 1 disk write.
+  - With lazy commit: 4 network roundtrips + 1 disk write + 1 disk flush.
+- Saturated parallel read iops: min(network bandwidth, sum(disk read iops)).
+- Saturated parallel write iops: min(network bandwidth, sum(disk write iops / number of replicas / write amplification)).
+
+EC/XOR setups:
+- Single-threaded (T1Q1) read latency: 1.5 network roundtrips + 1 disk read.
+- Single-threaded write+fsync latency:
+  - With immediate commit: 3.5 network roundtrips + 1 disk read + 2 disk writes.
+  - With lazy commit: 5.5 network roundtrips + 1 disk read + 2 disk writes + 2 disk fsyncs.
+  - 0.5 in actually (k-1)/k which means that an additional roundtrip doesn't happen when
+    the read sub-operation can be served locally.
+- Saturated parallel read iops: min(network bandwidth, sum(disk read iops)).
+- Saturated parallel write iops: min(network bandwidth, sum(disk write iops * number of data drives / (number of data + parity drives) / write amplification)).
+  In fact, you should put disk write iops under the condition of ~10% reads / ~90% writes in this formula.
+
+Write amplification for 4 KB blocks is usually 3-5 in Vitastor:
+1. Journal block write
+2. Journal data write
+3. Metadata block write
+4. Another journal block write for EC/XOR setups
+5. Data block write
+
+If you manage to get an SSD which handles 512 byte blocks well (Optane?) you may
+lower 1, 3 and 4 to 512 bytes (1/8 of data size) and get WA as low as 2.375.
+
+Lazy fsync also reduces WA for parallel workloads because journal blocks are only
+written when they fill up or fsync is requested.
+
+## In Practice
+
+In practice, using tests from [Understanding Performance](understanding.en.md)
+and good server-grade SSD/NVMe drives, you should head for:
+- At least 5000 T1Q1 replicated read and write iops (maximum 0.2ms latency)
+- At least ~80k parallel read iops or ~30k write iops per 1 core (1 OSD)
+- Disk-speed or wire-speed linear reads and writes, whichever is the bottleneck in your case
+
+Lower results may mean that you have bad drives, bad network or some kind of misconfiguration.

docs/performance/theoretical.ru.md

@@ -0,0 +1,41 @@
+[Документация](../../README-ru.md#документация) → Производительность → Теоретическая максимальная производительность Vitastor
+
+-----
+
+[Read in English](theoretical.en.md)
+
+# Теоретическая максимальная производительность Vitastor
+
+При использовании репликации:
+- Задержка чтения в 1 поток (T1Q1): 1 сетевой RTT + 1 чтение с диска.
+- Запись+fsync в 1 поток:
+  - С мгновенным сбросом: 2 RTT + 1 запись.
+  - С отложенным ("ленивым") сбросом: 4 RTT + 1 запись + 1 fsync.
+- Параллельное чтение: сумма IOPS всех дисков либо производительность сети, если в сеть упрётся раньше.
+- Параллельная запись: сумма IOPS всех дисков / число реплик / WA либо производительность сети, если в сеть упрётся раньше.
+
+При использовании кодов коррекции ошибок (EC):
+- Задержка чтения в 1 поток (T1Q1): 1.5 RTT + 1 чтение.
+- Запись+fsync в 1 поток:
+  - С мгновенным сбросом: 3.5 RTT + 1 чтение + 2 записи.
+  - С отложенным ("ленивым") сбросом: 5.5 RTT + 1 чтение + 2 записи + 2 fsync.
+- Под 0.5 на самом деле подразумевается (k-1)/k, где k - число дисков данных,
+  что означает, что дополнительное обращение по сети не нужно, когда операция
+  чтения обслуживается локально.
+- Параллельное чтение: сумма IOPS всех дисков либо производительность сети, если в сеть упрётся раньше.
+- Параллельная запись: сумма IOPS всех дисков / общее число дисков данных и чётности / WA либо производительность сети, если в сеть упрётся раньше.
+  Примечание: IOPS дисков в данном случае надо брать в смешанном режиме чтения/записи в пропорции, аналогичной формулам выше.
+
+WA (мультипликатор записи) для 4 КБ блоков в Vitastor обычно составляет 3-5:
+1. Запись метаданных в журнал
+2. Запись блока данных в журнал
+3. Запись метаданных в БД
+4. Ещё одна запись метаданных в журнал при использовании EC
+5. Запись блока данных на диск данных
+
+Если вы найдёте SSD, хорошо работающий с 512-байтными блоками данных (Optane?),
+то 1, 3 и 4 можно снизить до 512 байт (1/8 от размера данных) и получить WA всего 2.375.
+
+Кроме того, WA снижается при использовании отложенного/ленивого сброса при параллельной
+нагрузке, т.к. блоки журнала записываются на диск только когда они заполняются или явным
+образом запрашивается fsync.

docs/performance/understanding.en.md

@@ -0,0 +1,57 @@
+[Documentation](../../README.md#documentation) → Performance → Understanding Storage Performance
+
+-----
+
+[Читать на русском](understanding.ru.md)
+
+# Understanding Storage Performance
+
+The most important thing for fast storage is latency, not parallel iops.
+
+The best possible latency is achieved with one thread and queue depth of 1 which basically means
+"client load as low as possible". In this case IOPS = 1/latency, and this number doesn't
+scale with number of servers, drives, server processes or threads and so on.
+Single-threaded IOPS and latency numbers only depend on *how fast a single daemon is*.
+
+Why is it important? It's important because some of the applications *can't* use
+queue depth greater than 1 because their task isn't parallelizable. A notable example
+is any ACID DBMS because all of them write their WALs sequentially with fsync()s.
+
+fsync, by the way, is another important thing often missing in benchmarks. The point is
+that drives have cache buffers and don't guarantee that your data is actually persisted
+until you call fsync() which is translated to a FLUSH CACHE command by the OS.
+
+Desktop SSDs are very fast without fsync - NVMes, for example, can process ~80000 write
+operations per second with queue depth of 1 without fsync - but they're really slow with
+fsync because they have to actually write data to flash chips when you call fsync. Typical
+number is around 1000-2000 iops with fsync.
+
+Server SSDs often have supercapacitors that act as a built-in UPS and allow the drive
+to flush its DRAM cache to the persistent flash storage when a power loss occurs.
+This makes them perform equally well with and without fsync. This feature is called
+"Advanced Power Loss Protection" by Intel; other vendors either call it similarly
+or directly as "Full Capacitor-Based Power Loss Protection".
+
+All software-defined storages that I currently know are slow in terms of latency.
+Notable examples are Ceph and internal SDSes used by cloud providers like Amazon, Google,
+Yandex and so on. They're all slow and can only reach ~0.3ms read and ~0.6ms 4 KB write latency
+with best-in-slot hardware.
+
+And that's in the SSD era when you can buy an SSD that has ~0.04ms latency for 100 $.
+
+## fio commands
+
+I use the following 6 commands with small variations to benchmark block storage:
+
+- Linear write (results in MB/s):
+  `fio -ioengine=libaio -direct=1 -invalidate=1 -name=test -bs=4M -iodepth=32 -rw=write -runtime=60 -filename=/dev/sdX`
+- Linear read (results in MB/s):
+  `fio -ioengine=libaio -direct=1 -invalidate=1 -name=test -bs=4M -iodepth=32 -rw=read -runtime=60 -filename=/dev/sdX`
+- Random write latency (T1Q1, this hurts storages the most) (results in iops or milliseconds of latency):
+  `fio -ioengine=libaio -direct=1 -invalidate=1 -name=test -bs=4k -iodepth=1 -fsync=1 -rw=randwrite -runtime=60 -filename=/dev/sdX`
+- Random read latency (T1Q1) (results in iops or milliseconds of latency):
+  `fio -ioengine=libaio -direct=1 -invalidate=1 -name=test -bs=4k -iodepth=1 -rw=randread -runtime=60 -filename=/dev/sdX`
+- Parallel write iops (use numjobs=4 if a single CPU core is insufficient to saturate the load) (results only in iops):
+  `fio -ioengine=libaio -direct=1 -invalidate=1 -name=test -bs=4k -iodepth=128 [-numjobs=4 -group_reporting] -rw=randwrite -runtime=60 -filename=/dev/sdX`
+- Parallel read iops (use numjobs if a single CPU core is insufficient to saturate the load) (results only in iops):
+  `fio -ioengine=libaio -direct=1 -invalidate=1 -name=test -bs=4k -iodepth=128 [-numjobs=4 -group_reporting] -rw=randread -runtime=60 -filename=/dev/sdX`

docs/performance/understanding.ru.md

@@ -0,0 +1,65 @@
+[Документация](../../README-ru.md#документация) → Производительность → Понимание сути производительности систем хранения
+
+-----
+
+[Read in English](understanding.en.md)
+
+# Понимание сути производительности систем хранения
+
+Вкратце: для быстрой хранилки задержки важнее, чем пиковые iops-ы.
+
+Лучшая возможная задержка достигается при тестировании в 1 поток с глубиной очереди 1,
+что приблизительно означает минимально нагруженное состояние кластера. В данном случае
+IOPS = 1/задержка. Ни числом серверов, ни дисков, ни серверных процессов/потоков
+задержка не масштабируется... Она зависит только от того, насколько быстро один
+серверный процесс (и клиент) обрабатывают одну операцию.
+
+Почему задержки важны? Потому, что некоторые приложения *не могут* использовать глубину
+очереди больше 1, ибо их задача не параллелизуется. Важный пример - это все СУБД
+с поддержкой консистентности (ACID), потому что все они обеспечивают её через
+журналирование, а журналы пишутся последовательно и с fsync() после каждой операции.
+
+fsync, кстати - это ещё одна очень важная вещь, про которую почти всегда забывают в тестах.
+Смысл в том, что все современные диски имеют кэши/буферы записи и не гарантируют, что
+данные реально физически записываются на носитель до того, как вы делаете fsync(),
+который транслируется в команду сброса кэша операционной системой.
+
+Дешёвые SSD для настольных ПК и ноутбуков очень быстрые без fsync - NVMe диски, например,
+могут обработать порядка 80000 операций записи в секунду с глубиной очереди 1 без fsync.
+Однако с fsync, когда они реально вынуждены писать каждый блок данных во флеш-память,
+они выжимают лишь 1000-2000 операций записи в секунду (число практически постоянное
+для всех моделей SSD).
+
+Серверные SSD часто имеют суперконденсаторы, работающие как встроенный источник
+бесперебойного питания и дающие дискам успеть сбросить их DRAM-кэш в постоянную
+флеш-память при отключении питания. Благодаря этому диски с чистой совестью
+*игнорируют fsync*, так как точно знают, что данные из кэша доедут до постоянной
+памяти.
+
+Все наиболее известные программные СХД, например, Ceph и внутренние СХД, используемые
+такими облачными провайдерами, как Amazon, Google, Яндекс, медленные в смысле задержки.
+В лучшем случае они дают задержки от 0.3мс на чтение и 0.6мс на запись 4 КБ блоками
+даже при условии использования наилучшего возможного железа.
+
+И это в эпоху SSD, когда вы можете пойти на рынок и купить там SSD, задержка которого
+на чтение будет 0.1мс, а на запись - 0.04мс, за 100$ или даже дешевле.
+
+## Команды fio
+
+Когда мне нужно быстро протестировать производительность блочного устройства, я
+использую следующие 6 команд, с небольшими вариациями:
+
+- Линейная запись (результаты в МБ/с):
+  `fio -ioengine=libaio -direct=1 -invalidate=1 -name=test -bs=4M -iodepth=32 -rw=write -runtime=60 -filename=/dev/sdX`
+- Линейное чтение (результаты в МБ/с):
+  `fio -ioengine=libaio -direct=1 -invalidate=1 -name=test -bs=4M -iodepth=32 -rw=read -runtime=60 -filename=/dev/sdX`
+- Запись в 1 поток (T1Q1) (результаты в iops или миллисекундах задержки):
+  `fio -ioengine=libaio -direct=1 -invalidate=1 -name=test -bs=4k -iodepth=1 -fsync=1 -rw=randwrite -runtime=60 -filename=/dev/sdX`
+- Чтение в 1 поток (T1Q1) (результаты в iops или миллисекундах задержки):
+  `fio -ioengine=libaio -direct=1 -invalidate=1 -name=test -bs=4k -iodepth=1 -rw=randread -runtime=60 -filename=/dev/sdX`
+- Параллельная запись (numjobs=4 использовать, когда 1 ядро CPU не может насытить диск) (результаты только в iops):
+  `fio -ioengine=libaio -direct=1 -invalidate=1 -name=test -bs=4k -iodepth=128 [-numjobs=4 -group_reporting] -rw=randwrite -runtime=60 -filename=/dev/sdX`
+- Параллельное чтение (numjobs - аналогично) (результаты только в iops):
+  `fio -ioengine=libaio -direct=1 -invalidate=1 -name=test -bs=4k -iodepth=128 [-numjobs=4 -group_reporting] -rw=randread -runtime=60 -filename=/dev/sdX`
+
+Почему нужно тестировать именно так - см. [тут](https://yourcmc.ru/wiki/Производительность_Ceph#.D0.9B.D0.B8.D1.80.D0.B8.D1.87.D0.B5.D1.81.D0.BA.D0.BE.D0.B5_.D0.BE.D1.82.D1.81.D1.82.D1.83.D0.BF.D0.BB.D0.B5.D0.BD.D0.B8.D0.B5).

docs/usage/cli.en.md

@@ -0,0 +1,206 @@
+[Documentation](../../README.md#documentation) → Usage → Vitastor CLI
+
+-----
+
+[Читать на русском](cli.ru.md)
+
+# Vitastor CLI
+
+vitastor-cli is a command-line tool for administrative tasks like image management.
+
+It supports the following commands:
+
+- [status](#status)
+- [df](#df)
+- [ls](#ls)
+- [create](#create)
+- [modify](#modify)
+- [rm](#rm)
+- [flatten](#flatten)
+- [rm-data](#rm-data)
+- [merge-data](#merge-data)
+- [alloc-osd](#alloc-osd)
+- [simple-offsets](#simple-offsets)
+
+Global options:
+
+```
+--etcd_address ADDR  Etcd connection address
+--iodepth N          Send N operations in parallel to each OSD when possible (default 32)
+--parallel_osds M    Work with M osds in parallel when possible (default 4)
+--progress 1|0       Report progress (default 1)
+--cas 1|0            Use CAS writes for flatten, merge, rm (default is decide automatically)
+--no-color           Disable colored output
+--json               JSON output
+```
+
+## status
+
+`vitastor-cli status`
+
+Показать состояние кластера.
+
+Пример вывода:
+
+```
+  cluster:
+    etcd: 1 / 1 up, 1.8 M database size
+    mon:  1 up, master stump
+    osd:  8 / 12 up
+
+  data:
+    raw:   498.5 G used, 301.2 G / 799.7 G available, 399.8 G down
+    state: 156.6 G clean, 97.6 G misplaced
+    pools: 2 / 3 active
+    pgs:   30 active
+           34 active+has_misplaced
+           32 offline
+
+  io:
+    client:    0 B/s rd, 0 op/s rd, 0 B/s wr, 0 op/s wr
+    rebalance: 989.8 M/s, 7.9 K op/s
+```
+
+## df
+
+`vitastor-cli df`
+
+Показать список пулов и занятое место.
+
+Пример вывода:
+
+```
+NAME      SCHEME  PGS  TOTAL    USED    AVAILABLE  USED%   EFFICIENCY
+testpool  2/1     32   100 G    34.2 G  60.7 G     39.23%  100%
+size1     1/1     32   199.9 G  10 G    121.5 G    39.23%  100%
+kaveri    2/1     32   0 B      10 G    0 B        100%    0%
+```
+
+В примере у пула "kaveri" эффективность равна нулю, так как все OSD выключены.
+
+## ls
+
+`vitastor-cli ls [-l] [-p POOL] [--sort FIELD] [-r] [-n N] [<glob> ...]`
+
+Показать список образов, если переданы шаблоны `<glob>`, то только с именами,
+соответствующими этим шаблонам (стандартные ФС-шаблоны с * и ?).
+
+Опции:
+
+```
+-p|--pool POOL  Фильтровать образы по пулу (ID или имени)
+-l|--long       Также выводить статистику занятого места и ввода-вывода
+--del           Также выводить статистику операций удаления
+--sort FIELD    Сортировать по заданному полю (name, size, used_size, <read|write|delete>_<iops|bps|lat|queue>)
+-r|--reverse    Сортировать в обратном порядке
+-n|--count N    Показывать только первые N записей
+```
+
+Пример вывода:
+
+```
+NAME                 POOL      SIZE  USED    READ   IOPS  QUEUE  LAT   WRITE  IOPS  QUEUE  LAT   FLAGS  PARENT
+debian9              testpool  20 G  12.3 G  0 B/s  0     0      0 us  0 B/s  0     0      0 us     RO
+pve/vm-100-disk-0    testpool  20 G  0 B     0 B/s  0     0      0 us  0 B/s  0     0      0 us      -  debian9
+pve/base-101-disk-0  testpool  20 G  0 B     0 B/s  0     0      0 us  0 B/s  0     0      0 us     RO  debian9
+pve/vm-102-disk-0    testpool  32 G  36.4 M  0 B/s  0     0      0 us  0 B/s  0     0      0 us      -  pve/base-101-disk-0
+debian9-test         testpool  20 G  36.6 M  0 B/s  0     0      0 us  0 B/s  0     0      0 us      -  debian9
+bench                testpool  10 G  10 G    0 B/s  0     0      0 us  0 B/s  0     0      0 us      -
+bench-kaveri         kaveri    10 G  10 G    0 B/s  0     0      0 us  0 B/s  0     0      0 us      -
+```
+
+## create
+
+`vitastor-cli create -s|--size <size> [-p|--pool <id|name>] [--parent <parent_name>[@<snapshot>]] <name>`
+
+Создать образ. Для размера `<size>` можно использовать суффиксы K/M/G/T (килобайт-мегабайт-гигабайт-терабайт).
+Если указана опция `--parent`, создаётся клон образа. Родитель `<parent_name>[@<snapshot>]` должен быть
+снимком (или просто немодифицируемым образом). Пул обязательно указывать, если в кластере больше одного пула.
+
+```
+vitastor-cli create --snapshot <snapshot> [-p|--pool <id|name>] <image>
+vitastor-cli snap-create [-p|--pool <id|name>] <image>@<snapshot>
+```
+
+Создать снимок образа `<name>` (можно использовать любую форму команды). Снимок можно создавать без остановки
+клиентов, если пишущий клиент максимум 1.
+
+## modify
+
+`vitastor-cli modify <name> [--rename <new-name>] [--resize <size>] [--readonly | --readwrite] [-f|--force]`
+
+Изменить размер, имя образа или флаг "только для чтения". Снимать флаг "только для чтения"
+и уменьшать размер образов, у которых есть дочерние клоны, без `--force` нельзя.
+
+Если новый размер меньше старого, "лишние" данные будут удалены, поэтому перед уменьшением
+образа сначала уменьшите файловую систему в нём.
+
+```
+-f|--force  Разрешить уменьшение или перевод в чтение-запись образа, у которого есть клоны.
+```
+
+## rm
+
+`vitastor-cli rm <from> [<to>] [--writers-stopped]`
+
+Удалить образ `<from>` или все слои от `<from>` до `<to>` (`<to>` должен быть дочерним
+образом `<from>`), одновременно меняя родительские образы их клонов (если таковые есть).
+
+`--writers-stopped` позволяет чуть более эффективно удалять образы в частом случае, когда
+у удаляемой цепочки есть только один дочерний образ, содержащий небольшой объём данных.
+В этом случае дочерний образ вливается в родительский и удаляется, а родительский
+переименовывается в дочерний.
+
+В других случаях родительские слои вливаются в дочерние.
+
+## flatten
+
+`vitastor-cli flatten <layer>`
+
+Сделай образ `<layer>` плоским, то есть, скопировать в него данные и разорвать его
+соединение с родительскими.
+
+## rm-data
+
+`vitastor-cli rm-data --pool <pool> --inode <inode> [--wait-list] [--min-offset <offset>]`
+
+Удалить данные инода, не меняя метаданные образов.
+
+```
+--wait-list   Сначала запросить полный листинг объектов, а потом начать удалять.
+              Требует больше памяти, но позволяет правильно печатать прогресс удаления.
+--min-offset  Удалять только данные, начиная с заданного смещения.
+```
+
+## merge-data
+
+`vitastor-cli merge-data <from> <to> [--target <target>]`
+
+Слить данные слоёв, не меняя метаданные. Вливает данные из слоёв от `<from>` до `<to>`
+в целевой образ `<target>`. `<to>` должен быть дочерним образом `<from>`, а `<target>`
+должен быть одним из слоёв между `<from>` и `<to>`, включая сами `<from>` и `<to>`.
+
+## alloc-osd
+
+`vitastor-cli alloc-osd`
+
+Атомарно выделить новый номер OSD и зарезервировать его, создав в etcd пустой
+ключ `/osd/stats/<n>`.
+
+## simple-offsets
+
+`vitastor-cli simple-offsets <device>`
+
+Рассчитать смещения для простого и тупого создания OSD на диске (без суперблока).
+
+Опции (см. также [Дисковые параметры уровня кластера](../config/layout-cluster.ru.md)):
+
+```
+--object_size 128k       Размер блока хранилища
+--bitmap_granularity 4k  Гранулярность битовых карт
+--journal_size 32M       Размер журнала
+--device_block_size 4k   Размер блока устройства
+--journal_offset 0       Смещение журнала
+--device_size 0          Размер устройства
+--format text            Формат результата: json, options, env или text
+```

docs/usage/cli.ru.md

@@ -0,0 +1,197 @@
+[Документация](../../README-ru.md#документация) → Использование → Консольный интерфейс Vitastor
+
+-----
+
+[Read in English](cli.en.md)
+
+# Консольный интерфейс Vitastor
+
+vitastor-cli - интерфейс командной строки для административных задач, таких, как
+управление образами дисков.
+
+Поддерживаются следующие команды:
+
+- [status](#status)
+- [df](#df)
+- [ls](#ls)
+- [create](#create)
+- [modify](#modify)
+- [rm](#rm)
+- [flatten](#flatten)
+- [rm-data](#rm-data)
+- [merge-data](#merge-data)
+- [alloc-osd](#alloc-osd)
+- [simple-offsets](#simple-offsets)
+
+Глобальные опции:
+
+```
+--etcd_address ADDR  Адрес соединения с etcd
+--iodepth N          Отправлять параллельно N операций на каждый OSD (по умолчанию 32)
+--parallel_osds M    Работать параллельно с M OSD (по умолчанию 4)
+--progress 1|0       Печатать прогресс выполнения (по умолчанию 1)
+--cas 1|0            Для команд flatten, merge, rm - использовать CAS при записи (по умолчанию - решение принимается автоматически)
+--no-color           Отключить цветной вывод
+--json               Включить JSON-вывод
+```
+
+## status
+
+`vitastor-cli status`
+
+Show cluster status.
+
+Example output:
+
+```
+  cluster:
+    etcd: 1 / 1 up, 1.8 M database size
+    mon:  1 up, master stump
+    osd:  8 / 12 up
+
+  data:
+    raw:   498.5 G used, 301.2 G / 799.7 G available, 399.8 G down
+    state: 156.6 G clean, 97.6 G misplaced
+    pools: 2 / 3 active
+    pgs:   30 active
+           34 active+has_misplaced
+           32 offline
+
+  io:
+    client:    0 B/s rd, 0 op/s rd, 0 B/s wr, 0 op/s wr
+    rebalance: 989.8 M/s, 7.9 K op/s
+```
+
+## df
+
+`vitastor-cli df`
+
+Show pool space statistics.
+
+Example output:
+
+```
+NAME      SCHEME  PGS  TOTAL    USED    AVAILABLE  USED%   EFFICIENCY
+testpool  2/1     32   100 G    34.2 G  60.7 G     39.23%  100%
+size1     1/1     32   199.9 G  10 G    121.5 G    39.23%  100%
+kaveri    2/1     32   0 B      10 G    0 B        100%    0%
+```
+
+In the example above, "kaveri" pool has "zero" efficiency because all its OSD are down.
+
+## ls
+
+`vitastor-cli ls [-l] [-p POOL] [--sort FIELD] [-r] [-n N] [<glob> ...]`
+
+List images (only matching `<glob>` pattern(s) if passed).
+
+Options:
+
+```
+-p|--pool POOL  Filter images by pool ID or name
+-l|--long       Also report allocated size and I/O statistics
+--del           Also include delete operation statistics
+--sort FIELD    Sort by specified field (name, size, used_size, <read|write|delete>_<iops|bps|lat|queue>)
+-r|--reverse    Sort in descending order
+-n|--count N    Only list first N items
+```
+
+Example output:
+
+```
+NAME                 POOL      SIZE  USED    READ   IOPS  QUEUE  LAT   WRITE  IOPS  QUEUE  LAT   FLAGS  PARENT
+debian9              testpool  20 G  12.3 G  0 B/s  0     0      0 us  0 B/s  0     0      0 us     RO
+pve/vm-100-disk-0    testpool  20 G  0 B     0 B/s  0     0      0 us  0 B/s  0     0      0 us      -  debian9
+pve/base-101-disk-0  testpool  20 G  0 B     0 B/s  0     0      0 us  0 B/s  0     0      0 us     RO  debian9
+pve/vm-102-disk-0    testpool  32 G  36.4 M  0 B/s  0     0      0 us  0 B/s  0     0      0 us      -  pve/base-101-disk-0
+debian9-test         testpool  20 G  36.6 M  0 B/s  0     0      0 us  0 B/s  0     0      0 us      -  debian9
+bench                testpool  10 G  10 G    0 B/s  0     0      0 us  0 B/s  0     0      0 us      -
+bench-kaveri         kaveri    10 G  10 G    0 B/s  0     0      0 us  0 B/s  0     0      0 us      -
+```
+
+## create
+
+`vitastor-cli create -s|--size <size> [-p|--pool <id|name>] [--parent <parent_name>[@<snapshot>]] <name>`
+
+Create an image. You may use K/M/G/T suffixes for `<size>`. If `--parent` is specified,
+a copy-on-write image clone is created. Parent must be a snapshot (readonly image).
+Pool must be specified if there is more than one pool.
+
+```
+vitastor-cli create --snapshot <snapshot> [-p|--pool <id|name>] <image>
+vitastor-cli snap-create [-p|--pool <id|name>] <image>@<snapshot>
+```
+
+Create a snapshot of image `<name>` (either form can be used). May be used live if only a single writer is active.
+
+## modify
+
+`vitastor-cli modify <name> [--rename <new-name>] [--resize <size>] [--readonly | --readwrite] [-f|--force]`
+
+Rename, resize image or change its readonly status. Images with children can't be made read-write.
+If the new size is smaller than the old size, extra data will be purged.
+You should resize file system in the image, if present, before shrinking it.
+
+```
+-f|--force  Proceed with shrinking or setting readwrite flag even if the image has children.
+```
+
+## rm
+
+`vitastor-cli rm <from> [<to>] [--writers-stopped]`
+
+Remove `<from>` or all layers between `<from>` and `<to>` (`<to>` must be a child of `<from>`),
+rebasing all their children accordingly. --writers-stopped allows merging to be a bit
+more effective in case of a single 'slim' read-write child and 'fat' removed parent:
+the child is merged into parent and parent is renamed to child in that case.
+In other cases parent layers are always merged into children.
+
+## flatten
+
+`vitastor-cli flatten <layer>`
+
+Flatten a layer, i.e. merge data and detach it from parents.
+
+## rm-data
+
+`vitastor-cli rm-data --pool <pool> --inode <inode> [--wait-list] [--min-offset <offset>]`
+
+Remove inode data without changing metadata.
+
+```
+--wait-list   Retrieve full objects listings before starting to remove objects.
+              Requires more memory, but allows to show correct removal progress.
+--min-offset  Purge only data starting with specified offset.
+```
+
+## merge-data
+
+`vitastor-cli merge-data <from> <to> [--target <target>]`
+
+Merge layer data without changing metadata. Merge `<from>`..`<to>` to `<target>`.
+`<to>` must be a child of `<from>` and `<target>` may be one of the layers between
+`<from>` and `<to>`, including `<from>` and `<to>`.
+
+## alloc-osd
+
+`vitastor-cli alloc-osd`
+
+Allocate a new OSD number and reserve it by creating empty `/osd/stats/<n>` key.
+
+## simple-offsets
+
+`vitastor-cli simple-offsets <device>`
+
+Calculate offsets for simple&stupid (no superblock) OSD deployment.
+
+Options (see also [Cluster-Wide Disk Layout Parameters](../config/layout-cluster.en.md)):
+
+```
+--object_size 128k       Set blockstore block size
+--bitmap_granularity 4k  Set bitmap granularity
+--journal_size 32M       Set journal size
+--device_block_size 4k   Set device block size
+--journal_offset 0       Set journal offset
+--device_size 0          Set device size
+--format text            Result format: json, options, env, or text
+```

docs/usage/fio.en.md

@@ -0,0 +1,23 @@
+[Documentation](../../README.md#documentation) → Usage → fio driver
+
+-----
+
+[Читать на русском](fio.ru.md)
+
+# fio driver
+
+[fio](https://fio.readthedocs.io/en/latest/fio_doc.html) (Flexible I/O tester) is the
+best utility for benchmarking block devices.
+
+Vitastor has a fio driver which can be installed from the package vitastor-fio.
+
+Use the following command as an example to run tests with fio against a Vitastor cluster:
+
+```
+fio -thread -ioengine=libfio_vitastor.so -name=test -bs=4M -direct=1 -iodepth=16 -rw=write -etcd=10.115.0.10:2379/v3 -image=testimg
+```
+
+If you don't want to access your image by name, you can specify pool number, inode number and size
+(`-pool=1 -inode=1 -size=400G`) instead of the image name (`-image=testimg`).
+
+See exact fio commands to use for benchmarking [here](../performance/understanding.en.md#команды-fio).

docs/usage/fio.ru.md

@@ -0,0 +1,23 @@
+[Документация](../../README-ru.md#документация) → Использование → Драйвер fio
+
+-----
+
+[Read in English](fio.en.md)
+
+# Драйвер fio
+
+[fio](https://fio.readthedocs.io/en/latest/fio_doc.html) (Flexible I/O tester) - лучшая
+актуальная утилита для тестирования производительности блочных устройств.
+
+В Vitastor есть драйвер для fio, устанавливаемый из пакета vitastor-fio.
+
+Используйте следующую команду как пример для запуска тестов кластера Vitastor через fio:
+
+```
+fio -thread -ioengine=libfio_vitastor.so -name=test -bs=4M -direct=1 -iodepth=16 -rw=write -etcd=10.115.0.10:2379/v3 -image=testimg
+```
+
+Вместо обращения к образу по имени (`-image=testimg`) можно указать номер пула, номер инода и размер:
+`-pool=1 -inode=1 -size=400G`.
+
+Конкретные команды fio для тестирования производительности можно посмотреть [здесь](../performance/understanding.ru.md#команды-fio).

docs/usage/nbd.en.md

@@ -0,0 +1,34 @@
+[Documentation](../../README.md#documentation) → Usage → NBD
+
+-----
+
+[Читать на русском](nbd.ru.md)
+
+# NBD
+
+NBD stands for "Network Block Device", but in fact it also functions as "BUSE"
+(Block Device in UserSpace). NBD is currently required to mount Vitastor via kernel.
+NBD slighly lowers the performance due to additional overhead, but performance still
+remains decent (see an example [here](../performance/comparison1.en.md#vitastor-0-4-0-nbd)).
+
+Vitastor Kubernetes CSI driver is based on NBD.
+
+## Map image
+
+To create a local block device for a Vitastor image run:
+
+```
+vitastor-nbd map --etcd_address 10.115.0.10:2379/v3 --image testimg
+```
+
+It will output a block device name like /dev/nbd0 which you can then use as a normal disk.
+
+You can also use `--pool <POOL> --inode <INODE> --size <SIZE>` instead of `--image <IMAGE>` if you want.
+
+## Unmap image
+
+To unmap the device run:
+
+```
+vitastor-nbd unmap /dev/nbd0
+```

docs/usage/nbd.ru.md

@@ -0,0 +1,39 @@
+[Документация](../../README-ru.md#документация) → Использование → NBD
+
+-----
+
+[Read in English](nbd.en.md)
+
+# NBD
+
+NBD расшифровывается как "сетевое блочное устройство", но на самом деле оно также
+работает просто как аналог FUSE для блочных устройств, то есть, представляет собой
+"блочное устройство в пространстве пользователя".
+
+NBD на данный момент необходимо, чтобы монтировать диски Vitastor ядром Linux.
+NBD немного снижает производительность из-за дополнительных копирований памяти,
+но она всё равно остаётся на неплохом уровне (см. для примера [тест](../performance/comparison1.ru.md#vitastor-0-4-0-nbd)).
+
+CSI-драйвер Kubernetes Vitastor основан на NBD.
+
+## Подключить устройство
+
+Чтобы создать локальное блочное устройство для образа, выполните команду:
+
+```
+vitastor-nbd map --etcd_address 10.115.0.10:2379/v3 --image testimg
+```
+
+Команда напечатает название блочного устройства вида /dev/nbd0, которое потом можно
+будет использовать как обычный диск.
+
+Для обращения по номеру инода, аналогично другим командам, можно использовать опции
+`--pool <POOL> --inode <INODE> --size <SIZE>` вместо `--image testimg`.
+
+## Отключить устройство
+
+Для отключения устройства выполните:
+
+```
+vitastor-nbd unmap /dev/nbd0
+```

docs/usage/nfs.en.md

@@ -0,0 +1,45 @@
+[Documentation](../../README.md#documentation) → Usage → NFS
+
+-----
+
+[Читать на русском](nfs.ru.md)
+
+# NFS
+
+Vitastor has a simplified NFS 3.0 proxy for file-based image access emulation. It's not
+suitable as a full-featured file system, at least because all file/image metadata is stored
+in etcd and kept in memory all the time - thus you can't put a lot of files in it.
+
+However, NFS proxy is totally fine as a method to provide VM image access and allows to
+plug Vitastor into, for example, VMWare. It's important to note that for VMWare it's a much
+better access method than iSCSI, because with iSCSI we'd have to put all VM images into one
+Vitastor image exported as a LUN to VMWare and formatted with VMFS. VMWare doesn't use VMFS
+over NFS.
+
+NFS proxy is stateless if you use immediate_commit=all mode (for SSD with capacitors or
+HDDs with disabled cache), so you can run multiple NFS proxies and use a network load
+balancer or any failover method you want to in that case.
+
+vitastor-nfs usage:
+
+```
+vitastor-nfs [--etcd_address ADDR] [OTHER OPTIONS]
+
+--subdir <DIR>    export images prefixed <DIR>/ (default empty - export all images)
+--portmap 0       do not listen on port 111 (portmap/rpcbind, requires root)
+--bind <IP>       bind service to <IP> address (default 0.0.0.0)
+--nfspath <PATH>  set NFS export path to <PATH> (default is /)
+--port <PORT>     use port <PORT> for NFS services (default is 2049)
+--pool <POOL>     use <POOL> as default pool for new files (images)
+--foreground 1    stay in foreground, do not daemonize
+```
+
+Example start and mount commands:
+
+```
+vitastor-nfs --etcd_address 192.168.5.10:2379 --portmap 0 --port 2050 --pool testpool
+```
+
+```
+mount localhost:/ /mnt/ -o port=2050,mountport=2050,nfsvers=3,soft,nolock,tcp
+```

docs/usage/nfs.ru.md

@@ -0,0 +1,44 @@
+[Документация](../../README-ru.md#документация) → Использование → NFS
+
+-----
+
+[Read in English](nfs.en.md)
+
+# NFS
+
+В Vitastor реализована упрощённая NFS 3.0 прокси для эмуляции файлового доступа к образам.
+Это не полноценная файловая система, т.к. метаданные всех файлов (образов) сохраняются
+в etcd и всё время хранятся в оперативной памяти - то есть, положить туда много файлов
+не получится.
+
+Однако в качестве способа доступа к образам виртуальных машин NFS прокси прекрасно подходит
+и позволяет подключить Vitastor, например, к VMWare.
+
+При этом, если вы используете режим immediate_commit=all (для SSD с конденсаторами или HDD
+с отключённым кэшем), то NFS-сервер не имеет состояния и вы можете свободно поднять
+его в нескольких экземплярах и использовать поверх них сетевой балансировщик нагрузки или
+схему с отказоустойчивостью.
+
+Использование vitastor-nfs:
+
+```
+vitastor-nfs [--etcd_address ADDR] [ДРУГИЕ ОПЦИИ]
+
+--subdir <DIR>    экспортировать "поддиректорию" - образы с префиксом имени <DIR>/ (по умолчанию пусто - экспортировать все образы)
+--portmap 0       отключить сервис portmap/rpcbind на порту 111 (по умолчанию включён и требует root привилегий)
+--bind <IP>       принимать соединения по адресу <IP> (по умолчанию 0.0.0.0 - на всех)
+--nfspath <PATH>  установить путь NFS-экспорта в <PATH> (по умолчанию /)
+--port <PORT>     использовать порт <PORT> для NFS-сервисов (по умолчанию 2049)
+--pool <POOL>     исползовать пул <POOL> для новых образов (обязательно, если пул в кластере не один)
+--foreground 1    не уходить в фон после запуска
+```
+
+Пример монтирования Vitastor через NFS:
+
+```
+vitastor-nfs --etcd_address 192.168.5.10:2379 --portmap 0 --port 2050 --pool testpool
+```
+
+```
+mount localhost:/ /mnt/ -o port=2050,mountport=2050,nfsvers=3,soft,nolock,tcp
+```

docs/usage/qemu.en.md

@@ -0,0 +1,48 @@
+[Documentation](../../README.md#documentation) → Usage → QEMU and qemu-img
+
+-----
+
+[Читать на русском](qemu.ru.md)
+
+# QEMU and qemu-img
+
+## QEMU
+
+You need patched QEMU version to use Vitastor driver. Pre-built [packages](../installation/packages.en.md) are available.
+
+To start a VM using plain QEMU command-line with Vitastor disk, use the following commands:
+
+Old syntax (-drive):
+
+```
+qemu-system-x86_64 -enable-kvm -m 1024 \
+    -drive 'file=vitastor:etcd_host=192.168.7.2\:2379/v3:image=debian9',
+        format=raw,if=none,id=drive-virtio-disk0,cache=none \
+    -device 'virtio-blk-pci,scsi=off,bus=pci.0,addr=0x5,drive=drive-virtio-disk0,
+        id=virtio-disk0,bootindex=1,write-cache=off' \
+    -vnc 0.0.0.0:0
+```
+
+New syntax (-blockdev):
+
+```
+qemu-system-x86_64 -enable-kvm -m 1024 \
+    -blockdev '{"node-name":"drive-virtio-disk0","driver":"vitastor","image":"debian9",
+        "cache":{"direct":true,"no-flush":false},"auto-read-only":true,"discard":"unmap"}' \
+    -device 'virtio-blk-pci,scsi=off,bus=pci.0,addr=0x5,drive=drive-virtio-disk0,
+        id=virtio-disk0,bootindex=1,write-cache=off' \
+    -vnc 0.0.0.0:0
+```
+
+## qemu-img
+
+For qemu-img, you should use `vitastor:etcd_host=<HOST>:image=<IMAGE>` as filename.
+
+For example, to upload a VM image into Vitastor, run:
+
+```
+qemu-img convert -f qcow2 debian10.qcow2 -p -O raw 'vitastor:etcd_host=192.168.7.2\:2379/v3:image=debian10'
+```
+
+You can also specify `:pool=<POOL>:inode=<INODE>:size=<SIZE>` instead of `:image=<IMAGE>`
+if you don't want to use inode metadata.

docs/usage/qemu.ru.md

@@ -0,0 +1,52 @@
+[Документация](../../README-ru.md#документация) → Использование → QEMU и qemu-img
+
+-----
+
+[Read in English](qemu.en.md)
+
+# QEMU и qemu-img
+
+## QEMU
+
+Чтобы использовать Vitastor-диски в QEMU, вам нужна доработанная версия QEMU.
+Её можно установить [из пакетов](../installation/packages.ru.md).
+
+Для ручного запуска виртуальной машины QEMU из командной строки с Vitastor-диском
+используйте один из следующих вариантов команд:
+
+Старый синтаксис (-drive):
+
+```
+qemu-system-x86_64 -enable-kvm -m 1024 \
+    -drive 'file=vitastor:etcd_host=192.168.7.2\:2379/v3:image=debian9',
+        format=raw,if=none,id=drive-virtio-disk0,cache=none \
+    -device 'virtio-blk-pci,scsi=off,bus=pci.0,addr=0x5,drive=drive-virtio-disk0,
+        id=virtio-disk0,bootindex=1,write-cache=off' \
+    -vnc 0.0.0.0:0
+```
+
+Новый синтаксис (-blockdev):
+
+```
+qemu-system-x86_64 -enable-kvm -m 1024 \
+    -blockdev '{"node-name":"drive-virtio-disk0","driver":"vitastor","image":"debian9",
+        "cache":{"direct":true,"no-flush":false},"auto-read-only":true,"discard":"unmap"}' \
+    -device 'virtio-blk-pci,scsi=off,bus=pci.0,addr=0x5,drive=drive-virtio-disk0,
+        id=virtio-disk0,bootindex=1,write-cache=off' \
+    -vnc 0.0.0.0:0
+```
+
+Вместо `:image=<IMAGE>` также можно указывать номер инода, пул и размер: `:pool=<POOL>:inode=<INODE>:size=<SIZE>`.
+
+## qemu-img
+
+Для qemu-img используйте строку `vitastor:etcd_host=<HOST>:image=<IMAGE>` в качестве имени файла диска.
+
+Например, чтобы загрузить образ диска в Vitastor:
+
+```
+qemu-img convert -f qcow2 debian10.qcow2 -p -O raw 'vitastor:etcd_host=10.115.0.10\:2379/v3:image=testimg'
+```
+
+Если вы не хотите обращаться к образу по имени, вместо `:image=<IMAGE>` можно указать номер пула, номер инода и размер:
+`:pool=<POOL>:inode=<INODE>:size=<SIZE>`.

json11

@@ -1 +1 @@
-Subproject commit 55363fc2653b8802637a3d2e73a06839a72c585d
+Subproject commit 52a3af664f40775426b189c85b6088d436d05df3

mon/lp-optimizer.js

@@ -50,7 +50,7 @@ async function lp_solve(text)
     return { score, vars };
 }
 
-async function optimize_initial({ osd_tree, pg_count, pg_size = 3, pg_minsize = 2, max_combinations = 10000, parity_space = 1, round_robin = false })
+async function optimize_initial({ osd_tree, pg_count, pg_size = 3, pg_minsize = 2, max_combinations = 10000, parity_space = 1, ordered = false })
 {
     if (!pg_count || !osd_tree)
     {
@@ -92,7 +92,7 @@ async function optimize_initial({ osd_tree, pg_count, pg_size = 3, pg_minsize =
         console.log(lp);
         throw new Error('Problem is infeasible or unbounded - is it a bug?');
     }
-    const int_pgs = make_int_pgs(lp_result.vars, pg_count, round_robin);
+    const int_pgs = make_int_pgs(lp_result.vars, pg_count, ordered);
     const eff = pg_list_space_efficiency(int_pgs, all_weights, pg_minsize, parity_space);
     const res = {
         score: lp_result.score,
@@ -140,20 +140,20 @@ function make_int_pgs(weights, pg_count, round_robin)
     return int_pgs;
 }
 
-function calc_intersect_weights(pg_size, pg_count, prev_weights, all_pgs)
+function calc_intersect_weights(old_pg_size, pg_size, pg_count, prev_weights, all_pgs, ordered)
 {
     const move_weights = {};
-    if ((1 << pg_size) < pg_count)
+    if ((1 << old_pg_size) < pg_count)
     {
         const intersect = {};
         for (const pg_name in prev_weights)
         {
             const pg = pg_name.substr(3).split(/_/);
-            for (let omit = 1; omit < (1 << pg_size); omit++)
+            for (let omit = 1; omit < (1 << old_pg_size); omit++)
             {
                 let pg_omit = [ ...pg ];
-                let intersect_count = pg_size;
-                for (let i = 0; i < pg_size; i++)
+                let intersect_count = old_pg_size;
+                for (let i = 0; i < old_pg_size; i++)
                 {
                     if (omit & (1 << i))
                     {
@@ -161,6 +161,8 @@ function calc_intersect_weights(pg_size, pg_count, prev_weights, all_pgs)
                         intersect_count--;
                     }
                 }
+                if (!ordered)
+                    pg_omit = pg_omit.filter(n => n).sort();
                 pg_omit = pg_omit.join(':');
                 intersect[pg_omit] = Math.max(intersect[pg_omit] || 0, intersect_count);
             }
@@ -174,10 +176,10 @@ function calc_intersect_weights(pg_size, pg_count, prev_weights, all_pgs)
                 for (let i = 0; i < pg_size; i++)
                 {
                     if (omit & (1 << i))
-                    {
                         pg_omit[i] = '';
-                    }
                 }
+                if (!ordered)
+                    pg_omit = pg_omit.filter(n => n).sort();
                 pg_omit = pg_omit.join(':');
                 max_int = Math.max(max_int, intersect[pg_omit] || 0);
             }
@@ -186,15 +188,18 @@ function calc_intersect_weights(pg_size, pg_count, prev_weights, all_pgs)
     }
     else
     {
-        const prev_pg_hashed = Object.keys(prev_weights).map(pg_name => pg_name.substr(3).split(/_/).reduce((a, c) => { a[c] = 1; return a; }, {}));
+        const prev_pg_hashed = Object.keys(prev_weights).map(pg_name => pg_name
+            .substr(3).split(/_/).reduce((a, c, i) => { a[c] = i+1; return a; }, {}));
         for (const pg of all_pgs)
         {
             if (!prev_weights['pg_'+pg.join('_')])
             {
                 let max_int = 0;
-                for (const prev_hash in prev_pg_hashed)
+                for (const prev_hash of prev_pg_hashed)
                 {
-                    const intersect_count = pg.reduce((a, osd) => a + (prev_hash[osd] ? 1 : 0), 0);
+                    const intersect_count = ordered
+                        ? pg.reduce((a, osd, i) => a + (prev_hash[osd] == 1+i ? 1 : 0), 0)
+                        : pg.reduce((a, osd, i) => a + (prev_hash[osd] ? 1 : 0), 0);
                     if (max_int < intersect_count)
                     {
                         max_int = intersect_count;
@@ -243,7 +248,7 @@ function add_valid_previous(osd_tree, prev_weights, all_pgs)
 }
 
 // Try to minimize data movement
-async function optimize_change({ prev_pgs: prev_int_pgs, osd_tree, pg_size = 3, pg_minsize = 2, max_combinations = 10000, parity_space = 1 })
+async function optimize_change({ prev_pgs: prev_int_pgs, osd_tree, pg_size = 3, pg_minsize = 2, max_combinations = 10000, parity_space = 1, ordered = false })
 {
     if (!osd_tree)
     {
@@ -266,9 +271,13 @@ async function optimize_change({ prev_pgs: prev_int_pgs, osd_tree, pg_size = 3,
             prev_pg_per_osd[osd].push([ pg_name, (i >= pg_minsize ? parity_space : 1) ]);
         }
     }
+    const old_pg_size = prev_int_pgs[0].length;
     // Get all combinations
     let all_pgs = random_combinations(osd_tree, pg_size, max_combinations, parity_space > 1);
-    add_valid_previous(osd_tree, prev_weights, all_pgs);
+    if (old_pg_size == pg_size)
+    {
+        add_valid_previous(osd_tree, prev_weights, all_pgs);
+    }
     all_pgs = Object.values(all_pgs);
     const pg_per_osd = {};
     for (const pg of all_pgs)
@@ -282,7 +291,7 @@ async function optimize_change({ prev_pgs: prev_int_pgs, osd_tree, pg_size = 3,
         }
     }
     // Penalize PGs based on their similarity to old PGs
-    const move_weights = calc_intersect_weights(pg_size, pg_count, prev_weights, all_pgs);
+    const move_weights = calc_intersect_weights(old_pg_size, pg_size, pg_count, prev_weights, all_pgs, ordered);
     // Calculate total weight - old PG weights
     const all_pg_names = all_pgs.map(pg => 'pg_'+pg.join('_'));
     const all_pgs_hash = all_pg_names.reduce((a, c) => { a[c] = true; return a; }, {});
@@ -373,11 +382,35 @@ async function optimize_change({ prev_pgs: prev_int_pgs, osd_tree, pg_size = 3,
         {
             differs++;
         }
-        for (let j = 0; j < pg_size; j++)
+    }
+    if (ordered)
+    {
+        for (let i = 0; i < pg_count; i++)
         {
-            if (new_pgs[i][j] != prev_int_pgs[i][j])
+            for (let j = 0; j < pg_size; j++)
             {
-                osd_differs++;
+                if (new_pgs[i][j] != prev_int_pgs[i][j])
+                {
+                    osd_differs++;
+                }
+            }
+        }
+    }
+    else
+    {
+        for (let i = 0; i < pg_count; i++)
+        {
+            const old_map = prev_int_pgs[i].reduce((a, c) => { a[c] = (a[c]|0) + 1; return a; }, {});
+            for (let j = 0; j < pg_size; j++)
+            {
+                if ((0|old_map[new_pgs[i][j]]) > 0)
+                {
+                    old_map[new_pgs[i][j]]--;
+                }
+                else
+                {
+                    osd_differs++;
+                }
             }
         }
     }

mon/make-osd-hybrid.js

@@ -0,0 +1,414 @@
+#!/usr/bin/nodejs
+// systemd unit generator for hybrid (HDD+SSD) vitastor OSDs
+// Copyright (c) Vitaliy Filippov, 2019+
+// License: VNPL-1.1
+
+// USAGE: nodejs make-osd-hybrid.js [--disable_ssd_cache 0] [--disable_hdd_cache 0] /dev/sda /dev/sdb /dev/sdc /dev/sdd ...
+// I.e. - just pass all HDDs and SSDs mixed, the script will decide where
+// to put journals on its own
+
+const fs = require('fs');
+const fsp = fs.promises;
+const child_process = require('child_process');
+
+const options = {
+    debug: 1,
+    journal_size: 1024*1024*1024,
+    min_meta_size: 1024*1024*1024,
+    object_size: 1024*1024,
+    bitmap_granularity: 4096,
+    device_block_size: 4096,
+    disable_ssd_cache: 1,
+    disable_hdd_cache: 1,
+};
+
+run().catch(console.fatal);
+
+async function run()
+{
+    const device_list = parse_options();
+    await system_or_die("mkdir -p /var/log/vitastor; chown vitastor /var/log/vitastor");
+    // Collect devices
+    const all_devices = await collect_devices(device_list);
+    const ssds = all_devices.filter(d => d.ssd);
+    const hdds = all_devices.filter(d => !d.ssd);
+    // Collect existing OSD units
+    const osd_units = await collect_osd_units();
+    // Count assigned HDD journals and unallocated space for each SSD
+    await check_journal_count(ssds, osd_units);
+    // Create new OSDs
+    await create_new_hybrid_osds(hdds, ssds, osd_units);
+    process.exit(0);
+}
+
+function parse_options()
+{
+    const devices = [];
+    const opt = {};
+    for (let i = 2; i < process.argv.length; i++)
+    {
+        const arg = process.argv[i];
+        if (arg == '--help' || arg == '-h')
+        {
+            opt.help = true;
+            break;
+        }
+        else if (arg.substr(0, 2) == '--')
+            opt[arg.substr(2)] = process.argv[++i];
+        else
+            devices.push(arg);
+    }
+    if (opt.help || !devices.length)
+    {
+        console.log(
+            'Prepare hybrid (HDD+SSD) Vitastor OSDs\n'+
+            '(c) Vitaliy Filippov, 2019+, license: VNPL-1.1\n\n'+
+            'USAGE: nodejs make-osd-hybrid.js [OPTIONS] /dev/sda /dev/sdb /dev/sdc ...\n'+
+            'Just pass all your SSDs and HDDs in any order, the script will distribute OSDs for you.\n\n'+
+            'OPTIONS (with defaults):\n'+
+            Object.keys(options).map(k => `  --${k} ${options[k]}`).join('\n')
+        );
+        process.exit(0);
+    }
+    for (const k in opt)
+        options[k] = opt[k];
+    return devices;
+}
+
+// Collect devices
+async function collect_devices(devices_to_check)
+{
+    const devices = [];
+    for (const dev of devices_to_check)
+    {
+        if (dev.substr(0, 5) != '/dev/')
+        {
+            console.log(`${dev} does not start with /dev/, skipping`);
+            continue;
+        }
+        if (!await file_exists('/sys/block/'+dev.substr(5)))
+        {
+            console.log(`${dev} is a partition, skipping`);
+            continue;
+        }
+        // Check if the device is an SSD
+        const rot = '/sys/block/'+dev.substr(5)+'/queue/rotational';
+        if (!await file_exists(rot))
+        {
+            console.log(`${dev} does not have ${rot} to check whether it's an SSD, skipping`);
+            continue;
+        }
+        const ssd = !parseInt(await fsp.readFile(rot, { encoding: 'utf-8' }));
+        // Check if the device has partition table
+        let [ has_partition_table, parts ] = await system(`sfdisk --dump ${dev} --json`);
+        if (has_partition_table != 0)
+        {
+            // Check if the device has any data
+            const [ has_data, out ] = await system(`blkid ${dev}`);
+            if (has_data == 0)
+            {
+                console.log(`${dev} contains data, skipping:\n  ${out.trim().replace(/\n/g, '\n  ')}`);
+                continue;
+            }
+        }
+        parts = parts ? JSON.parse(parts).partitiontable : null;
+        if (parts && parts.label != 'gpt')
+        {
+            console.log(`${dev} contains "${parts.label}" partition table, only GPT is supported, skipping`);
+            continue;
+        }
+        devices.push({
+            path: dev,
+            ssd,
+            parts,
+        });
+    }
+    return devices;
+}
+
+// Collect existing OSD units
+async function collect_osd_units()
+{
+    const units = [];
+    for (const unit of (await system("ls /etc/systemd/system/vitastor-osd*.service"))[1].trim().split('\n'))
+    {
+        if (!unit)
+        {
+            continue;
+        }
+        let cmd = /^ExecStart\s*=\s*(([^\n]*\\\n)*[^\n]*)/.exec(await fsp.readFile(unit, { encoding: 'utf-8' }));
+        if (!cmd)
+        {
+            console.log('ExecStart= not found in '+unit+', skipping')
+            continue;
+        }
+        let kv = {}, key;
+        cmd = cmd[1].replace(/^bash\s+-c\s+'/, '')
+            .replace(/>>\s*\S+2>\s*&1\s*'$/, '')
+            .replace(/\s*\\\n\s*/g, ' ')
+            .replace(/([^\s']+)|'([^']+)'/g, (m, m1, m2) =>
+            {
+                m1 = m1||m2;
+                if (key == null)
+                {
+                    if (m1.substr(0, 2) != '--')
+                    {
+                        console.log('Strange command line in '+unit+', stopping');
+                        process.exit(1);
+                    }
+                    key = m1.substr(2);
+                }
+                else
+                {
+                    kv[key] = m1;
+                    key = null;
+                }
+            });
+        units.push(kv);
+    }
+    return units;
+}
+
+// Count assigned HDD journals and unallocated space for each SSD
+async function check_journal_count(ssds, osd_units)
+{
+    const units_by_journal = osd_units.reduce((a, c) =>
+    {
+        if (c.journal_device)
+            a[c.journal_device] = c;
+        return a;
+    }, {});
+    for (const dev of ssds)
+    {
+        dev.journals = 0;
+        if (dev.parts)
+        {
+            for (const part of dev.parts.partitions)
+            {
+                if (part.uuid && units_by_journal['/dev/disk/by-partuuid/'+part.uuid.toLowerCase()])
+                {
+                    dev.journals++;
+                }
+            }
+            dev.free = free_from_parttable(dev.parts);
+        }
+        else
+        {
+            dev.free = parseInt(await system_or_die("blockdev --getsize64 "+dev.path));
+        }
+    }
+}
+
+async function create_new_hybrid_osds(hdds, ssds, osd_units)
+{
+    const units_by_disk = osd_units.reduce((a, c) => { a[c.data_device] = c; return a; }, {});
+    for (const dev of hdds)
+    {
+        if (!dev.parts)
+        {
+            // HDD is not partitioned yet, create a single partition
+            // + is the "default value" for sfdisk
+            await system_or_die('sfdisk '+dev.path, 'label: gpt\n\n+ +\n');
+            dev.parts = JSON.parse(await system_or_die('sfdisk --dump '+dev.path+' --json')).partitiontable;
+        }
+        if (dev.parts.partitions.length != 1)
+        {
+            console.log(dev.path+' has more than 1 partition, skipping');
+        }
+        else if ((dev.parts.partitions[0].start + dev.parts.partitions[0].size) != (1 + dev.parts.lastlba))
+        {
+            console.log(dev.path+'1 is not a whole-disk partition, skipping');
+        }
+        else if (!dev.parts.partitions[0].uuid)
+        {
+            console.log(dev.parts.partitions[0].node+' does not have UUID. Please repartition '+dev.path+' with GPT');
+        }
+        else if (!units_by_disk['/dev/disk/by-partuuid/'+dev.parts.partitions[0].uuid.toLowerCase()])
+        {
+            await create_hybrid_osd(dev, ssds);
+        }
+    }
+}
+
+async function create_hybrid_osd(dev, ssds)
+{
+    // Create a new OSD
+    // Calculate metadata size
+    const data_device = '/dev/disk/by-partuuid/'+dev.parts.partitions[0].uuid.toLowerCase();
+    const data_size = dev.parts.partitions[0].size * dev.parts.sectorsize;
+    const meta_entry_size = 24 + 2*options.object_size/options.bitmap_granularity/8;
+    const entries_per_block = Math.floor(options.device_block_size / meta_entry_size);
+    const object_count = Math.floor(data_size / options.object_size);
+    let meta_size = Math.ceil(1 + object_count / entries_per_block) * options.device_block_size;
+    // Leave some extra space for future metadata formats and round metadata area size to multiples of 1 MB
+    meta_size = 2*meta_size;
+    meta_size = Math.ceil(meta_size/1024/1024) * 1024*1024;
+    if (meta_size < options.min_meta_size)
+        meta_size = options.min_meta_size;
+    let journal_size = Math.ceil(options.journal_size/1024/1024) * 1024*1024;
+    // Pick an SSD for journal, balancing the number of journals across SSDs
+    let selected_ssd;
+    for (const ssd of ssds)
+        if (ssd.free >= (meta_size+journal_size) && (!selected_ssd || selected_ssd.journals > ssd.journals))
+            selected_ssd = ssd;
+    if (!selected_ssd)
+    {
+        console.error('Could not find free space for SSD journal and metadata for '+dev.path);
+        process.exit(1);
+    }
+    // Allocate an OSD number
+    const osd_num = (await system_or_die("vitastor-cli alloc-osd")).trim();
+    if (!osd_num)
+    {
+        console.error('Failed to run vitastor-cli alloc-osd');
+        process.exit(1);
+    }
+    console.log('Creating OSD '+osd_num+' on '+dev.path+' (HDD) with journal and metadata on '+selected_ssd.path+' (SSD)');
+    // Add two partitions: journal and metadata
+    const new_parts = await add_partitions(selected_ssd, [ journal_size, meta_size ]);
+    selected_ssd.journals++;
+    const journal_device = '/dev/disk/by-partuuid/'+new_parts[0].uuid.toLowerCase();
+    const meta_device = '/dev/disk/by-partuuid/'+new_parts[1].uuid.toLowerCase();
+    // Wait until the device symlinks appear
+    while (!await file_exists(journal_device))
+    {
+        await new Promise(ok => setTimeout(ok, 100));
+    }
+    while (!await file_exists(meta_device))
+    {
+        await new Promise(ok => setTimeout(ok, 100));
+    }
+    // Zero out metadata and journal
+    await system_or_die("dd if=/dev/zero of="+journal_device+" bs=1M count="+(journal_size/1024/1024)+" oflag=direct");
+    await system_or_die("dd if=/dev/zero of="+meta_device+" bs=1M count="+(meta_size/1024/1024)+" oflag=direct");
+    // Create unit file for the OSD
+    const has_scsi_cache_type = options.disable_ssd_cache &&
+        (await system("ls /sys/block/"+selected_ssd.path.substr(5)+"/device/scsi_disk/*/cache_type"))[0] == 0;
+    const write_through = options.disable_ssd_cache && (
+        has_scsi_cache_type || selected_ssd.path.substr(5, 4) == 'nvme'
+        && (await system_or_die("/sys/block/"+selected_ssd.path.substr(5)+"/queue/write_cache")).trim() == "write through");
+    await fsp.writeFile('/etc/systemd/system/vitastor-osd'+osd_num+'.service',
+`[Unit]
+Description=Vitastor object storage daemon osd.${osd_num}
+After=network-online.target local-fs.target time-sync.target
+Wants=network-online.target local-fs.target time-sync.target
+PartOf=vitastor.target
+
+[Service]
+LimitNOFILE=1048576
+LimitNPROC=1048576
+LimitMEMLOCK=infinity
+ExecStart=bash -c '/usr/bin/vitastor-osd \\
+    --osd_num ${osd_num} ${write_through
+        ? "--disable_meta_fsync 1 --disable_journal_fsync 1 --immediate_commit "+(options.disable_hdd_cache ? "all" : "small")
+        : ""} \\
+    --throttle_small_writes 1 \\
+    --disk_alignment ${options.device_block_size} \\
+    --journal_block_size ${options.device_block_size} \\
+    --meta_block_size ${options.device_block_size} \\
+    --journal_no_same_sector_overwrites true \\
+    --journal_sector_buffer_count 1024 \\
+    --block_size ${options.object_size} \\
+    --data_device ${data_device} \\
+    --journal_device ${journal_device} \\
+    --meta_device ${meta_device} >>/var/log/vitastor/osd${osd_num}.log 2>&1'
+WorkingDirectory=/
+ExecStartPre=+chown vitastor:vitastor ${data_device}
+ExecStartPre=+chown vitastor:vitastor ${journal_device}
+ExecStartPre=+chown vitastor:vitastor ${meta_device}${
+    has_scsi_cache_type
+    ? "\nExecStartPre=+bash -c 'D=$$$(readlink "+journal_device+"); echo write through > $$$(dirname /sys/block/*/$$\${D##*/})/device/scsi_disk/*/cache_type'"
+    : ""}${
+    options.disable_hdd_cache
+    ? "\nExecStartPre=+bash -c 'D=$$$(readlink "+data_device+"); echo write through > $$$(dirname /sys/block/*/$$\${D##*/})/device/scsi_disk/*/cache_type'"
+    : ""}
+User=vitastor
+PrivateTmp=false
+TasksMax=infinity
+Restart=always
+StartLimitInterval=0
+RestartSec=10
+
+[Install]
+WantedBy=vitastor.target
+`);
+    await system_or_die("systemctl enable vitastor-osd"+osd_num);
+}
+
+async function add_partitions(dev, sizes)
+{
+    let script = 'label: gpt\n\n';
+    if (dev.parts)
+    {
+        // Old partitions
+        for (const part of dev.parts.partitions)
+        {
+            script += part.node+': '+Object.keys(part).map(k => k == 'node' ? '' : k+'='+part[k]).filter(k => k).join(', ')+'\n';
+        }
+    }
+    // New partitions
+    for (const size of sizes)
+    {
+        script += '+ '+Math.ceil(size/1024)+'KiB\n';
+    }
+    await system_or_die('sfdisk '+dev.path, script);
+    // Get new partition table and find the new partition
+    const newpt = JSON.parse(await system_or_die('sfdisk --dump '+dev.path+' --json')).partitiontable;
+    const old_nodes = dev.parts ? dev.parts.partitions.reduce((a, c) => { a[c.uuid] = true; return a; }, {}) : {};
+    const new_nodes = newpt.partitions.filter(part => !old_nodes[part.uuid]);
+    if (new_nodes.length != sizes.length)
+    {
+        console.error('Failed to partition '+dev.path+': new partitions not found in table');
+        process.exit(1);
+    }
+    dev.parts = newpt;
+    dev.free = free_from_parttable(newpt);
+    return new_nodes;
+}
+
+function free_from_parttable(pt)
+{
+    let free = pt.lastlba + 1 - pt.firstlba;
+    for (const part of pt.partitions)
+    {
+        free -= part.size;
+    }
+    free *= pt.sectorsize;
+    return free;
+}
+
+async function system_or_die(cmd, input = '')
+{
+    let [ exitcode, stdout, stderr ] = await system(cmd, input);
+    if (exitcode != 0)
+    {
+        console.error(cmd+' failed: '+stderr);
+        process.exit(1);
+    }
+    return stdout;
+}
+
+async function system(cmd, input = '')
+{
+    if (options.debug)
+    {
+        process.stderr.write('+ '+cmd+(input ? " <<EOF\n"+input.replace(/\s*$/, '\n')+"EOF" : '')+'\n');
+    }
+    const cp = child_process.spawn(cmd, { shell: true });
+    let stdout = '', stderr = '', finish_cb;
+    cp.stdout.on('data', buf => stdout += buf.toString());
+    cp.stderr.on('data', buf => stderr += buf.toString());
+    cp.on('exit', () => finish_cb && finish_cb());
+    cp.stdin.write(input);
+    cp.stdin.end();
+    if (cp.exitCode == null)
+    {
+        await new Promise(ok => finish_cb = ok);
+    }
+    return [ cp.exitCode, stdout, stderr ];
+}
+
+async function file_exists(filename)
+{
+    return new Promise((ok, no) => fs.access(filename, fs.constants.R_OK, err => ok(!err)));
+}

mon/make-osd.sh

@@ -25,6 +25,10 @@ OPT=$(vitastor-cli simple-offsets --format options $DEV | tr '\n' ' ')
 META=$(vitastor-cli simple-offsets --format json $DEV | jq .data_offset)
 dd if=/dev/zero of=$DEV bs=1048576 count=$(((META+1048575)/1048576)) oflag=direct
 
+mkdir -p /var/log/vitastor
+id vitastor &>/dev/null || useradd vitastor
+chown vitastor /var/log/vitastor
+
 cat >/etc/systemd/system/vitastor-osd$OSD_NUM.service <<EOF
 [Unit]
 Description=Vitastor object storage daemon osd.$OSD_NUM
@@ -36,14 +40,14 @@ PartOf=vitastor.target
 LimitNOFILE=1048576
 LimitNPROC=1048576
 LimitMEMLOCK=infinity
-ExecStart=/usr/bin/vitastor-osd \\
+ExecStart=bash -c '/usr/bin/vitastor-osd \\
     --osd_num $OSD_NUM \\
     --disable_data_fsync 1 \\
     --immediate_commit all \\
     --disk_alignment 4096 --journal_block_size 4096 --meta_block_size 4096 \\
     --journal_no_same_sector_overwrites true \\
     --journal_sector_buffer_count 1024 \\
-    $OPT
+    $OPT >>/var/log/vitastor/osd$OSD_NUM.log 2>&1'
 WorkingDirectory=/
 ExecStartPre=+chown vitastor:vitastor $DEV
 User=vitastor

mon/mon.js

@@ -31,6 +31,7 @@ const etcd_allow = new RegExp('^'+[
     'osd/inodestats/[1-9]\\d*',
     'osd/space/[1-9]\\d*',
     'mon/master',
+    'mon/member/[a-f0-9]+',
     'pg/state/[1-9]\\d*/[1-9]\\d*',
     'pg/stats/[1-9]\\d*/[1-9]\\d*',
     'pg/history/[1-9]\\d*/[1-9]\\d*',
@@ -83,8 +84,13 @@ const etcd_tree = {
             osd_idle_timeout: 5, // seconds. min: 1
             osd_ping_timeout: 5, // seconds. min: 1
             up_wait_retry_interval: 500, // ms. min: 50
+            max_etcd_attempts: 5,
+            etcd_quick_timeout: 1000, // ms
+            etcd_slow_timeout: 5000, // ms
+            etcd_keepalive_timeout: 30, // seconds, default is max(30, etcd_report_interval*2)
+            etcd_ws_keepalive_interval: 30, // seconds
             // osd
-            etcd_report_interval: 5,
+            etcd_report_interval: 5, // seconds
             run_primary: true,
             osd_network: null, // "192.168.7.0/24" or an array of masks
             bind_address: "0.0.0.0",
@@ -99,6 +105,7 @@ const etcd_tree = {
             no_rebalance: false,
             print_stats_interval: 3,
             slow_log_interval: 10,
+            osd_memlock: false,
             // blockstore - fixed in superblock
             block_size,
             disk_alignment,
@@ -125,6 +132,11 @@ const etcd_tree = {
             inmemory_journal,
             journal_sector_buffer_count,
             journal_no_same_sector_overwrites,
+            throttle_small_writes: false,
+            throttle_target_iops: 100,
+            throttle_target_mbs: 100,
+            throttle_target_parallelism: 1,
+            throttle_threshold_us: 50,
         }, */
         global: {},
         /* node_placement: {
@@ -148,6 +160,8 @@ const etcd_tree = {
                 root_node?: 'rack1',
                 // restrict pool to OSDs having all of these tags
                 osd_tags?: 'nvme' | [ 'nvme', ... ],
+                // prefer to put primary on OSD with these tags
+                primary_affinity_tags?: 'nvme' | [ 'nvme', ... ],
             },
             ...
         }, */
@@ -212,21 +226,28 @@ const etcd_tree = {
             }, */
         },
         inodestats: {
-            /* <inode_t>: {
-                read: { count: uint64_t, usec: uint64_t, bytes: uint64_t },
-                write: { count: uint64_t, usec: uint64_t, bytes: uint64_t },
-                delete: { count: uint64_t, usec: uint64_t, bytes: uint64_t },
+            /* <pool_id>: {
+                <inode_t>: {
+                    read: { count: uint64_t, usec: uint64_t, bytes: uint64_t },
+                    write: { count: uint64_t, usec: uint64_t, bytes: uint64_t },
+                    delete: { count: uint64_t, usec: uint64_t, bytes: uint64_t },
+                },
             }, */
         },
         space: {
             /* <osd_num_t>: {
-                <inode_t>: uint64_t, // bytes
+                <pool_id>: {
+                    <inode_t>: uint64_t, // bytes
+                },
             }, */
         },
     },
     mon: {
         master: {
-            /* ip: [ string ], */
+            /* ip: [ string ], id: uint64_t */
+        },
+        standby: {
+            /* <uint64_t>: { ip: [ string ] }, */
         },
     },
     pg: {
@@ -257,7 +278,7 @@ const etcd_tree = {
                 <pg_id>: {
                     osd_sets: osd_num_t[][],
                     all_peers: osd_num_t[],
-                    epoch: uint32_t,
+                    epoch: uint64_t,
                 },
             }, */
         },
@@ -341,6 +362,9 @@ class Mon
         this.etcd_start_timeout = (config.etcd_start_timeout || 5) * 1000;
         this.state = JSON.parse(JSON.stringify(this.constructor.etcd_tree));
         this.signals_set = false;
+        this.ws = null;
+        this.ws_alive = false;
+        this.ws_keepalive_timer = null;
         this.on_stop_cb = () => this.on_stop(0).catch(console.error);
     }
 
@@ -383,7 +407,7 @@ class Mon
         for (const pool_id in this.state.config.pools)
         {
             if (!this.state.pool.stats[pool_id] ||
-                !this.state.pool.stats[pool_id].pg_real_size)
+                !Number(this.state.pool.stats[pool_id].pg_real_size))
             {
                 // Generate missing data in etcd
                 this.state.config.pgs.hash = null;
@@ -461,8 +485,20 @@ class Mon
 
     restart_watcher(cur_addr)
     {
+        if (this.ws)
+        {
+            this.ws.close();
+            this.ws = null;
+        }
+        if (this.ws_keepalive_timer)
+        {
+            clearInterval(this.ws_keepalive_timer);
+            this.ws_keepalive_timer = null;
+        }
         if (this.selected_etcd_url == cur_addr)
+        {
             this.selected_etcd_url = null;
+        }
         this.start_watcher(this.config.etcd_mon_retries).catch(this.die);
     }
 
@@ -482,6 +518,7 @@ class Mon
                 const timer_id = setTimeout(() =>
                 {
                     this.ws.close();
+                    this.ws = null;
                     ok(false);
                 }, this.config.etcd_mon_timeout);
                 this.ws = new WebSocket(base+'/watch');
@@ -510,6 +547,20 @@ class Mon
             this.die('Failed to open etcd watch websocket');
         }
         const cur_addr = this.selected_etcd_url;
+        this.ws_alive = true;
+        this.ws_keepalive_timer = setInterval(() =>
+        {
+            if (this.ws_alive)
+            {
+                this.ws_alive = false;
+                this.ws.send(JSON.stringify({ progress_request: {} }));
+            }
+            else
+            {
+                console.log('etcd websocket timed out, restarting it');
+                this.restart_watcher(cur_addr);
+            }
+        }, (Number(this.config.etcd_keepalive_interval) || 30)*1000);
         this.ws.on('error', () => this.restart_watcher(cur_addr));
         this.ws.send(JSON.stringify({
             create_request: {
@@ -522,6 +573,7 @@ class Mon
         }));
         this.ws.on('message', (msg) =>
         {
+            this.ws_alive = true;
             let data;
             try
             {
@@ -558,7 +610,7 @@ class Mon
                     console.log('Revision '+data.result.header.revision+' events: ');
                 }
                 this.etcd_watch_revision = BigInt(data.result.header.revision)+BigInt(1);
-                for (const e of data.result.events)
+                for (const e of data.result.events||[])
                 {
                     this.parse_kv(e.kv);
                     const key = e.kv.key.substr(this.etcd_prefix.length);
@@ -631,11 +683,25 @@ class Mon
         }, this.etcd_start_timeout, 0);
     }
 
+    get_mon_state()
+    {
+        return { ip: this.local_ips(), hostname: os.hostname() };
+    }
+
     async get_lease()
     {
         const max_ttl = this.config.etcd_mon_ttl + this.config.etcd_mon_timeout/1000*this.config.etcd_mon_retries;
-        const res = await this.etcd_call('/lease/grant', { TTL: max_ttl }, this.config.etcd_mon_timeout, -1);
+        // Get lease
+        let res = await this.etcd_call('/lease/grant', { TTL: max_ttl }, this.config.etcd_mon_timeout, -1);
         this.etcd_lease_id = res.ID;
+        // Register in /mon/member, just for the information
+        const state = this.get_mon_state();
+        res = await this.etcd_call('/kv/put', {
+            key: b64(this.etcd_prefix+'/mon/member/'+this.etcd_lease_id),
+            value: b64(JSON.stringify(state)),
+            lease: ''+this.etcd_lease_id
+        }, this.etcd_start_timeout, 0);
+        // Set refresh timer
         this.lease_timer = setInterval(async () =>
         {
             const res = await this.etcd_call('/lease/keepalive', { ID: this.etcd_lease_id }, this.config.etcd_mon_timeout, this.config.etcd_mon_retries);
@@ -661,7 +727,7 @@ class Mon
 
     async become_master()
     {
-        const state = { ip: this.local_ips() };
+        const state = { ...this.get_mon_state(), id: ''+this.etcd_lease_id };
         while (1)
         {
             const res = await this.etcd_call('/kv/txn', {
@@ -839,27 +905,39 @@ class Mon
         return this.seed + 2147483648;
     }
 
-    pick_primary(pool_id, osd_set, up_osds)
+    pick_primary(pool_id, osd_set, up_osds, aff_osds)
     {
         let alive_set;
         if (this.state.config.pools[pool_id].scheme === 'replicated')
-            alive_set = osd_set.filter(osd_num => osd_num && up_osds[osd_num]);
+        {
+            // Prefer "affinity" OSDs
+            alive_set = osd_set.filter(osd_num => osd_num && aff_osds[osd_num]);
+            if (!alive_set.length)
+                alive_set = osd_set.filter(osd_num => osd_num && up_osds[osd_num]);
+        }
         else
         {
             // Prefer data OSDs for EC because they can actually read something without an additional network hop
             const pg_data_size = (this.state.config.pools[pool_id].pg_size||0) -
                 (this.state.config.pools[pool_id].parity_chunks||0);
-            alive_set = osd_set.slice(0, pg_data_size).filter(osd_num => osd_num && up_osds[osd_num]);
+            alive_set = osd_set.slice(0, pg_data_size).filter(osd_num => osd_num && aff_osds[osd_num]);
             if (!alive_set.length)
-                alive_set = osd_set.filter(osd_num => osd_num && up_osds[osd_num]);
+                alive_set = osd_set.filter(osd_num => osd_num && aff_osds[osd_num]);
+            if (!alive_set.length)
+            {
+                alive_set = osd_set.slice(0, pg_data_size).filter(osd_num => osd_num && up_osds[osd_num]);
+                if (!alive_set.length)
+                    alive_set = osd_set.filter(osd_num => osd_num && up_osds[osd_num]);
+            }
         }
         if (!alive_set.length)
             return 0;
         return alive_set[this.rng() % alive_set.length];
     }
 
-    save_new_pgs_txn(request, pool_id, up_osds, prev_pgs, new_pgs, pg_history)
+    save_new_pgs_txn(request, pool_id, up_osds, osd_tree, prev_pgs, new_pgs, pg_history)
     {
+        const aff_osds = this.get_affinity_osds(this.state.config.pools[pool_id], up_osds, osd_tree);
         const pg_items = {};
         this.reset_rng();
         new_pgs.map((osd_set, i) =>
@@ -867,7 +945,7 @@ class Mon
             osd_set = osd_set.map(osd_num => osd_num === LPOptimizer.NO_OSD ? 0 : osd_num);
             pg_items[i+1] = {
                 osd_set,
-                primary: this.pick_primary(pool_id, osd_set, up_osds),
+                primary: this.pick_primary(pool_id, osd_set, up_osds, aff_osds),
             };
             if (prev_pgs[i] && prev_pgs[i].join(' ') != osd_set.join(' ') &&
                 prev_pgs[i].filter(osd_num => osd_num).length > 0)
@@ -998,6 +1076,13 @@ class Mon
                 console.log('Pool '+pool_id+' has invalid osd_tags (must be a string or array of strings)');
             return false;
         }
+        if (pool_cfg.primary_affinity_tags && typeof(pool_cfg.primary_affinity_tags) != 'string' &&
+            (!(pool_cfg.primary_affinity_tags instanceof Array) || pool_cfg.primary_affinity_tags.filter(t => typeof t != 'string').length > 0))
+        {
+            if (warn)
+                console.log('Pool '+pool_id+' has invalid primary_affinity_tags (must be a string or array of strings)');
+            return false;
+        }
         return true;
     }
 
@@ -1027,6 +1112,17 @@ class Mon
         }
     }
 
+    get_affinity_osds(pool_cfg, up_osds, osd_tree)
+    {
+        let aff_osds = up_osds;
+        if (pool_cfg.primary_affinity_tags)
+        {
+            aff_osds = { ...up_osds };
+            this.filter_osds_by_tags(osd_tree, { x: aff_osds }, pool_cfg.primary_affinity_tags);
+        }
+        return aff_osds;
+    }
+
     async recheck_pgs()
     {
         // Take configuration and state, check it against the stored configuration hash
@@ -1057,7 +1153,7 @@ class Mon
                     {
                         prev_pgs[pg-1] = this.state.config.pgs.items[pool_id][pg].osd_set;
                     }
-                    this.save_new_pgs_txn(etcd_request, pool_id, up_osds, prev_pgs, [], []);
+                    this.save_new_pgs_txn(etcd_request, pool_id, up_osds, osd_tree, prev_pgs, [], []);
                 }
             }
             for (const pool_id in this.state.config.pools)
@@ -1097,7 +1193,7 @@ class Mon
                     pg_size: pool_cfg.pg_size,
                     pg_minsize: pool_cfg.pg_minsize,
                     max_combinations: pool_cfg.max_osd_combinations,
-                    round_robin: pool_cfg.scheme != 'replicated',
+                    ordered: pool_cfg.scheme != 'replicated',
                 };
                 let optimize_result;
                 if (old_pg_count > 0)
@@ -1120,10 +1216,6 @@ class Mon
                         {
                             pg.push(0);
                         }
-                        while (pg.length > pool_cfg.pg_size)
-                        {
-                            pg.pop();
-                        }
                     }
                     if (!this.state.config.pgs.hash)
                     {
@@ -1159,8 +1251,8 @@ class Mon
                 this.state.pool.stats[pool_id] = {
                     used_raw_tb: (this.state.pool.stats[pool_id]||{}).used_raw_tb || 0,
                     total_raw_tb: optimize_result.space,
-                    pg_real_size: pg_effsize,
-                    raw_to_usable: pg_effsize / (pool_cfg.scheme === 'replicated'
+                    pg_real_size: pg_effsize || pool_cfg.pg_size,
+                    raw_to_usable: (pg_effsize || pool_cfg.pg_size) / (pool_cfg.scheme === 'replicated'
                         ? 1 : (pool_cfg.pg_size - (pool_cfg.parity_chunks||0))),
                     space_efficiency: optimize_result.space/(optimize_result.total_space||1),
                 };
@@ -1168,7 +1260,7 @@ class Mon
                     key: b64(this.etcd_prefix+'/pool/stats/'+pool_id),
                     value: b64(JSON.stringify(this.state.pool.stats[pool_id])),
                 } });
-                this.save_new_pgs_txn(etcd_request, pool_id, up_osds, real_prev_pgs, optimize_result.int_pgs, pg_history);
+                this.save_new_pgs_txn(etcd_request, pool_id, up_osds, osd_tree, real_prev_pgs, optimize_result.int_pgs, pg_history);
             }
             this.state.config.pgs.hash = tree_hash;
             await this.save_pg_config(etcd_request);
@@ -1185,13 +1277,14 @@ class Mon
                     continue;
                 }
                 const replicated = pool_cfg.scheme === 'replicated';
+                const aff_osds = this.get_affinity_osds(pool_cfg, up_osds, osd_tree);
                 this.reset_rng();
                 for (let pg_num = 1; pg_num <= pool_cfg.pg_count; pg_num++)
                 {
                     const pg_cfg = this.state.config.pgs.items[pool_id][pg_num];
                     if (pg_cfg)
                     {
-                        const new_primary = this.pick_primary(pool_id, pg_cfg.osd_set, up_osds);
+                        const new_primary = this.pick_primary(pool_id, pg_cfg.osd_set, up_osds, aff_osds);
                         if (pg_cfg.primary != new_primary)
                         {
                             console.log(
@@ -1307,21 +1400,30 @@ class Mon
         const tm = prev_stats ? BigInt(timestamp - prev_stats.timestamp) : 0;
         for (const op in op_stats)
         {
-            op_stats[op].bps = prev_stats ? (op_stats[op].bytes - prev_stats.op_stats[op].bytes) * 1000n / tm : 0;
-            op_stats[op].iops = prev_stats ? (op_stats[op].count - prev_stats.op_stats[op].count) * 1000n / tm : 0;
-            op_stats[op].lat = prev_stats ? (op_stats[op].usec - prev_stats.op_stats[op].usec)
-                / ((op_stats[op].count - prev_stats.op_stats[op].count) || 1n) : 0;
+            if (prev_stats && prev_stats.op_stats && prev_stats.op_stats[op])
+            {
+                op_stats[op].bps = (op_stats[op].bytes - prev_stats.op_stats[op].bytes) * 1000n / tm;
+                op_stats[op].iops = (op_stats[op].count - prev_stats.op_stats[op].count) * 1000n / tm;
+                op_stats[op].lat = (op_stats[op].usec - prev_stats.op_stats[op].usec)
+                    / ((op_stats[op].count - prev_stats.op_stats[op].count) || 1n);
+            }
         }
         for (const op in subop_stats)
         {
-            subop_stats[op].iops = prev_stats ? (subop_stats[op].count - prev_stats.subop_stats[op].count) * 1000n / tm : 0;
-            subop_stats[op].lat = prev_stats ? (subop_stats[op].usec - prev_stats.subop_stats[op].usec)
-                / ((subop_stats[op].count - prev_stats.subop_stats[op].count) || 1n) : 0;
+            if (prev_stats && prev_stats.subop_stats && prev_stats.subop_stats[op])
+            {
+                subop_stats[op].iops = (subop_stats[op].count - prev_stats.subop_stats[op].count) * 1000n / tm;
+                subop_stats[op].lat = (subop_stats[op].usec - prev_stats.subop_stats[op].usec)
+                    / ((subop_stats[op].count - prev_stats.subop_stats[op].count) || 1n);
+            }
         }
         for (const op in recovery_stats)
         {
-            recovery_stats[op].bps = prev_stats ? (recovery_stats[op].bytes - prev_stats.recovery_stats[op].bytes) * 1000n / tm : 0;
-            recovery_stats[op].iops = prev_stats ? (recovery_stats[op].count - prev_stats.recovery_stats[op].count) * 1000n / tm : 0;
+            if (prev_stats && prev_stats.recovery_stats && prev_stats.recovery_stats[op])
+            {
+                recovery_stats[op].bps = (recovery_stats[op].bytes - prev_stats.recovery_stats[op].bytes) * 1000n / tm;
+                recovery_stats[op].iops = (recovery_stats[op].count - prev_stats.recovery_stats[op].count) * 1000n / tm;
+            }
         }
         return { op_stats, subop_stats, recovery_stats };
     }

mon/simple-offsets.js

@@ -49,7 +49,8 @@ async function run()
     }
     options.journal_offset = Math.ceil(options.journal_offset/options.device_block_size)*options.device_block_size;
     const meta_offset = options.journal_offset + Math.ceil(options.journal_size/options.device_block_size)*options.device_block_size;
-    const entries_per_block = Math.floor(options.device_block_size / (24 + 2*options.object_size/options.bitmap_granularity/8));
+    const meta_entry_size = 24 + 2*options.object_size/options.bitmap_granularity/8;
+    const entries_per_block = Math.floor(options.device_block_size / meta_entry_size);
     const object_count = Math.floor((device_size-meta_offset)/options.object_size);
     const meta_size = Math.ceil(1 + object_count / entries_per_block) * options.device_block_size;
     const data_offset = meta_offset + meta_size;

mon/test-optimize-simple.js

@@ -5,21 +5,45 @@ const LPOptimizer = require('./lp-optimizer.js');
 
 async function run()
 {
-    const osd_tree = { a: { 1: 1 }, b: { 2: 1 }, c: { 3: 1 } };
+    const osd_tree = {
+        100: { 1: 1 },
+        200: { 2: 1 },
+        300: { 3: 1 },
+    };
+
     let res;
 
     console.log('16 PGs, size=3');
-    res = await LPOptimizer.optimize_initial({ osd_tree, pg_size: 3, pg_count: 16 });
+    res = await LPOptimizer.optimize_initial({ osd_tree, pg_size: 3, pg_count: 16, ordered: false });
     LPOptimizer.print_change_stats(res, false);
-
-    console.log('\nReduce PG size to 2');
-    res = await LPOptimizer.optimize_change({ prev_pgs: res.int_pgs.map(pg => pg.slice(0, 2)), osd_tree, pg_size: 2 });
+    assert(res.space == 3, 'Initial distribution');
+    console.log('\nChange size to 2');
+    res = await LPOptimizer.optimize_change({ prev_pgs: res.int_pgs, osd_tree, pg_size: 2, ordered: false });
     LPOptimizer.print_change_stats(res, false);
-
+    assert(res.space >= 3*14/16 && res.osd_differs == 0, 'Redistribution');
     console.log('\nRemove OSD 3');
-    delete osd_tree['c'];
-    res = await LPOptimizer.optimize_change({ prev_pgs: res.int_pgs, osd_tree, pg_size: 2 });
+    const no3_tree = { ...osd_tree };
+    delete no3_tree['300'];
+    res = await LPOptimizer.optimize_change({ prev_pgs: res.int_pgs, osd_tree: no3_tree, pg_size: 2, ordered: false });
     LPOptimizer.print_change_stats(res, false);
+    assert(res.space == 2, 'Redistribution after OSD removal');
+
+    console.log('\n16 PGs, size=3, ordered');
+    res = await LPOptimizer.optimize_initial({ osd_tree, pg_size: 3, pg_count: 16, ordered: true });
+    LPOptimizer.print_change_stats(res, false);
+    assert(res.space == 3, 'Initial distribution');
+    console.log('\nChange size to 2, ordered');
+    res = await LPOptimizer.optimize_change({ prev_pgs: res.int_pgs, osd_tree, pg_size: 2, ordered: true });
+    LPOptimizer.print_change_stats(res, false);
+    assert(res.space >= 3*14/16 && res.osd_differs < 8, 'Redistribution');
+}
+
+function assert(cond, txt)
+{
+    if (!cond)
+    {
+        throw new Error((txt||'test')+' failed');
+    }
 }
 
 run().catch(console.error);

mon/test-optimize-undersized.js

@@ -45,30 +45,45 @@ async function run()
     console.log('Empty tree:');
     let res = await LPOptimizer.optimize_initial({ osd_tree: cur_tree, pg_size: 3, pg_count: 256 });
     LPOptimizer.print_change_stats(res, false);
+    assert(res.space == 0);
     console.log('\nAdding 1st failure domain:');
     cur_tree['dom1'] = osd_tree['dom1'];
     res = await LPOptimizer.optimize_change({ prev_pgs: res.int_pgs, osd_tree: cur_tree, pg_size: 3 });
     LPOptimizer.print_change_stats(res, false);
+    assert(res.space == 12 && res.total_space == 12);
     console.log('\nAdding 2nd failure domain:');
     cur_tree['dom2'] = osd_tree['dom2'];
     res = await LPOptimizer.optimize_change({ prev_pgs: res.int_pgs, osd_tree: cur_tree, pg_size: 3 });
     LPOptimizer.print_change_stats(res, false);
+    assert(res.space == 24 && res.total_space == 24);
     console.log('\nAdding 3rd failure domain:');
     cur_tree['dom3'] = osd_tree['dom3'];
     res = await LPOptimizer.optimize_change({ prev_pgs: res.int_pgs, osd_tree: cur_tree, pg_size: 3 });
     LPOptimizer.print_change_stats(res, false);
+    assert(res.space == 36 && res.total_space == 36);
     console.log('\nRemoving 3rd failure domain:');
     delete cur_tree['dom3'];
     res = await LPOptimizer.optimize_change({ prev_pgs: res.int_pgs, osd_tree: cur_tree, pg_size: 3 });
     LPOptimizer.print_change_stats(res, false);
+    assert(res.space == 24 && res.total_space == 24);
     console.log('\nRemoving 2nd failure domain:');
     delete cur_tree['dom2'];
     res = await LPOptimizer.optimize_change({ prev_pgs: res.int_pgs, osd_tree: cur_tree, pg_size: 3 });
     LPOptimizer.print_change_stats(res, false);
+    assert(res.space == 12 && res.total_space == 12);
     console.log('\nRemoving 1st failure domain:');
     delete cur_tree['dom1'];
     res = await LPOptimizer.optimize_change({ prev_pgs: res.int_pgs, osd_tree: cur_tree, pg_size: 3 });
     LPOptimizer.print_change_stats(res, false);
+    assert(res.space == 0);
+}
+
+function assert(cond, txt)
+{
+    if (!cond)
+    {
+        throw new Error((txt||'test')+' failed');
+    }
 }
 
 run().catch(console.error);

patches/cinder-vitastor.py

@@ -50,7 +50,7 @@ from cinder.volume import configuration
 from cinder.volume import driver
 from cinder.volume import volume_utils
 
-VERSION = '0.6.10'
+VERSION = '0.6.17'
 
 LOG = logging.getLogger(__name__)
 
@@ -355,7 +355,25 @@ class VitastorDriver(driver.CloneableImageVD,
     def revert_to_snapshot(self, context, volume, snapshot):
         """Revert a volume to a given snapshot."""
 
-        # FIXME Delete the image, then recreate it from the snapshot
+        vol_name = utils.convert_str(snapshot.volume_name)
+        snap_name = utils.convert_str(snapshot.name)
+
+        # Delete the image and recreate it from the snapshot
+        args = [ 'vitastor-cli', 'rm', vol_name, *(self._vitastor_args()) ]
+        try:
+            self._execute(*args)
+        except processutils.ProcessExecutionError as exc:
+            LOG.error("Failed to delete image "+vol_name+": "+exc)
+            raise exception.VolumeBackendAPIException(data = exc.stderr)
+        args = [
+            'vitastor-cli', 'create', '--parent', vol_name+'@'+snap_name,
+            vol_name, *(self._vitastor_args())
+        ]
+        try:
+            self._execute(*args)
+        except processutils.ProcessExecutionError as exc:
+            LOG.error("Failed to recreate image "+vol_name+" from "+vol_name+"@"+snap_name+": "+exc)
+            raise exception.VolumeBackendAPIException(data = exc.stderr)
 
     def delete_snapshot(self, snapshot):
         """Deletes a snapshot."""
@@ -363,24 +381,15 @@ class VitastorDriver(driver.CloneableImageVD,
         vol_name = utils.convert_str(snapshot.volume_name)
         snap_name = utils.convert_str(snapshot.name)
 
-        # Find the snapshot
-        resp = self._etcd_txn({ 'success': [
-            { 'request_range': { 'key': 'index/image/'+vol_name+'@'+snap_name } },
-        ] })
-        if len(resp['responses'][0]['kvs']) == 0:
-            raise exception.SnapshotNotFound(snapshot_id = snap_name)
-        inode_id = int(resp['responses'][0]['kvs'][0]['value']['id'])
-        pool_id = int(resp['responses'][0]['kvs'][0]['value']['pool_id'])
-        parents = {}
-        parents[(pool_id << 48) | (inode_id & 0xffffffffffff)] = True
-
-        # Check if there are child volumes
-        children = self._child_count(parents)
-        if children > 0:
-            raise exception.SnapshotIsBusy(snapshot_name = snap_name)
-
-        # FIXME: We can't delete snapshots because we can't merge layers yet
-        raise exception.VolumeBackendAPIException(data = 'Snapshot delete (layer merge) is not implemented yet')
+        args = [
+            'vitastor-cli', 'rm', vol_name+'@'+snap_name,
+            *(self._vitastor_args())
+        ]
+        try:
+            self._execute(*args)
+        except processutils.ProcessExecutionError as exc:
+            LOG.error("Failed to remove snapshot "+vol_name+'@'+snap_name+": "+exc)
+            raise exception.VolumeBackendAPIException(data = exc.stderr)
 
     def _child_count(self, parents):
         children = 0

rpm/build-tarball.sh

@@ -25,4 +25,4 @@ rm fio
 mv fio-copy fio
 FIO=`rpm -qi fio | perl -e 'while(<>) { /^Epoch[\s:]+(\S+)/ && print "$1:"; /^Version[\s:]+(\S+)/ && print $1; /^Release[\s:]+(\S+)/ && print "-$1"; }'`
 perl -i -pe 's/(Requires:\s*fio)([^\n]+)?/$1 = '$FIO'/' $VITASTOR/rpm/vitastor-el$EL.spec
-tar --transform 's#^#vitastor-0.6.10/#' --exclude 'rpm/*.rpm' -czf $VITASTOR/../vitastor-0.6.10$(rpm --eval '%dist').tar.gz *
+tar --transform 's#^#vitastor-0.6.17/#' --exclude 'rpm/*.rpm' -czf $VITASTOR/../vitastor-0.6.17$(rpm --eval '%dist').tar.gz *

rpm/vitastor-el7.Dockerfile

@@ -34,7 +34,7 @@ ADD . /root/vitastor
 RUN set -e; \
     cd /root/vitastor/rpm; \
     sh build-tarball.sh; \
-    cp /root/vitastor-0.6.10.el7.tar.gz ~/rpmbuild/SOURCES; \
+    cp /root/vitastor-0.6.17.el7.tar.gz ~/rpmbuild/SOURCES; \
     cp vitastor-el7.spec ~/rpmbuild/SPECS/vitastor.spec; \
     cd ~/rpmbuild/SPECS/; \
     rpmbuild -ba vitastor.spec; \

rpm/vitastor-el7.spec

@@ -1,11 +1,11 @@
 Name:           vitastor
-Version:        0.6.10
+Version:        0.6.17
 Release:        1%{?dist}
 Summary:        Vitastor, a fast software-defined clustered block storage
 
 License:        Vitastor Network Public License 1.1
 URL:            https://vitastor.io/
-Source0:        vitastor-0.6.10.el7.tar.gz
+Source0:        vitastor-0.6.17.el7.tar.gz
 
 BuildRequires:  liburing-devel >= 0.6
 BuildRequires:  gperftools-devel
@@ -119,6 +119,7 @@ cp -r mon %buildroot/usr/lib/vitastor
 
 %files -n vitastor-client
 %_bindir/vitastor-nbd
+%_bindir/vitastor-nfs
 %_bindir/vitastor-cli
 %_bindir/vitastor-rm
 %_bindir/vita

rpm/vitastor-el8.Dockerfile

@@ -33,7 +33,7 @@ ADD . /root/vitastor
 RUN set -e; \
     cd /root/vitastor/rpm; \
     sh build-tarball.sh; \
-    cp /root/vitastor-0.6.10.el8.tar.gz ~/rpmbuild/SOURCES; \
+    cp /root/vitastor-0.6.17.el8.tar.gz ~/rpmbuild/SOURCES; \
     cp vitastor-el8.spec ~/rpmbuild/SPECS/vitastor.spec; \
     cd ~/rpmbuild/SPECS/; \
     rpmbuild -ba vitastor.spec; \

rpm/vitastor-el8.spec

@@ -1,11 +1,11 @@
 Name:           vitastor
-Version:        0.6.10
+Version:        0.6.17
 Release:        1%{?dist}
 Summary:        Vitastor, a fast software-defined clustered block storage
 
 License:        Vitastor Network Public License 1.1
 URL:            https://vitastor.io/
-Source0:        vitastor-0.6.10.el8.tar.gz
+Source0:        vitastor-0.6.17.el8.tar.gz
 
 BuildRequires:  liburing-devel >= 0.6
 BuildRequires:  gperftools-devel
@@ -116,6 +116,7 @@ cp -r mon %buildroot/usr/lib/vitastor
 
 %files -n vitastor-client
 %_bindir/vitastor-nbd
+%_bindir/vitastor-nfs
 %_bindir/vitastor-cli
 %_bindir/vitastor-rm
 %_bindir/vita