Add documentation

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)