parent
54ef2c389f
commit
a537db8909
@ -0,0 +1,245 @@ |
||||
[Documentation](../../README.md#documentation) → Usage → Disk Tool |
||||
|
||||
----- |
||||
|
||||
[Читать на русском](disk.ru.md) |
||||
|
||||
# Disk management tool |
||||
|
||||
vitastor-disk is a command-line tool for physical Vitastor disk management. |
||||
|
||||
It supports the following commands: |
||||
|
||||
- [prepare](#prepare) |
||||
- [upgrade-simple](#upgrade-simple) |
||||
- [resize](#resize) |
||||
- [start/stop/restart/enable/disable](#start/stop/restart/enable/disable) |
||||
- [read-sb](#read-sb) |
||||
- [write-sb](#write-sb) |
||||
- [udev](#udev) |
||||
- [exec-osd](#exec-osd) |
||||
- [pre-exec](#pre-exec) |
||||
- Debugging: |
||||
- [dump-journal](#dump-journal) |
||||
- [write-journal](#write-journal) |
||||
- [dump-meta](#dump-meta) |
||||
- [write-meta](#write-meta) |
||||
- [simple-offsets](#simple-offsets) |
||||
|
||||
## prepare |
||||
|
||||
`vitastor-disk prepare [OPTIONS] [devices...]` |
||||
|
||||
Initialize disk(s) for Vitastor OSD(s). |
||||
|
||||
There are two modes of this command. In the first mode, you pass `<devices>` which |
||||
must be raw disks (not partitions). They are partitioned automatically and OSDs |
||||
are initialized on all of them. |
||||
|
||||
In the second mode, you omit `<devices>` and pass `--data_device`, `--journal_device` |
||||
and/or `--meta_device` which must be already existing partitions identified by their |
||||
GPT partition UUIDs. In this case a single OSD is created. |
||||
|
||||
Requires `vitastor-cli`, `wipefs`, `sfdisk` and `partprobe` (from parted) utilities. |
||||
|
||||
Options (automatic mode): |
||||
|
||||
``` |
||||
--osd_per_disk <N> |
||||
Create <N> OSDs on each disk (default 1) |
||||
--hybrid |
||||
Prepare hybrid (HDD+SSD) OSDs using provided devices. SSDs will be used for |
||||
journals and metadata, HDDs will be used for data. Partitions for journals and |
||||
metadata will be created automatically. Whether disks are SSD or HDD is decided |
||||
by the `/sys/block/.../queue/rotational` flag. In hybrid mode, default object |
||||
size is 1 MB instead of 128 KB, default journal size is 1 GB instead of 32 MB, |
||||
and throttle_small_writes is enabled by default. |
||||
--disable_data_fsync 1 |
||||
Disable data device cache and fsync (1/yes/true = on, default on) |
||||
--disable_meta_fsync 1 |
||||
Disable metadata/journal device cache and fsync (default on) |
||||
--meta_reserve 2x,1G |
||||
New metadata partitions in --hybrid mode are created larger than actual |
||||
metadata size to ease possible future extension. The default is to allocate |
||||
2 times more space and at least 1G. Use this option to override. |
||||
--max_other 10% |
||||
Use disks for OSD data even if they already have non-Vitastor partitions, |
||||
but only if these take up no more than this percent of disk space. |
||||
``` |
||||
|
||||
Options (single-device mode): |
||||
|
||||
``` |
||||
--data_device <DEV> Use partition <DEV> for data |
||||
--meta_device <DEV> Use partition <DEV> for metadata (optional) |
||||
--journal_device <DEV> Use partition <DEV> for journal (optional) |
||||
--disable_data_fsync 0 Disable data device cache and fsync (default off) |
||||
--disable_meta_fsync 0 Disable metadata device cache and fsync (default off) |
||||
--disable_journal_fsync 0 Disable journal device cache and fsync (default off) |
||||
--force Bypass partition safety checks (for emptiness and so on) |
||||
``` |
||||
|
||||
Options (both modes): |
||||
|
||||
``` |
||||
--journal_size 1G/32M Set journal size (area or partition size) |
||||
--object_size 1M/128k Set blockstore object size |
||||
--bitmap_granularity 4k Set bitmap granularity |
||||
--data_device_block 4k Override data device block size |
||||
--meta_device_block 4k Override metadata device block size |
||||
--journal_device_block 4k Override journal device block size |
||||
``` |
||||
|
||||
[immediate_commit](../config/layout-cluster.en.md#immediate_commit) setting is |
||||
automatically derived from "disable fsync" options. It's set to "all" when fsync |
||||
is disabled on all devices, and to "small" if fsync is only disabled on journal device. |
||||
|
||||
When data/meta/journal fsyncs are disabled, the OSD startup script automatically |
||||
checks the device cache status on start and tries to disable cache for SATA/SAS disks. |
||||
If it doesn't succeed it issues a warning in the system log. |
||||
|
||||
You can also pass other OSD options here as arguments and they'll be persisted |
||||
to the superblock: max_write_iodepth, max_write_iodepth, min_flusher_count, |
||||
max_flusher_count, inmemory_metadata, inmemory_journal, journal_sector_buffer_count, |
||||
journal_no_same_sector_overwrites, throttle_small_writes, throttle_target_iops, |
||||
throttle_target_mbs, throttle_target_parallelism, throttle_threshold_us. |
||||
See [Runtime OSD Parameters](../config/osd.en.md) for details. |
||||
|
||||
## upgrade-simple |
||||
|
||||
`vitastor-disk upgrade-simple <UNIT_FILE|OSD_NUMBER>` |
||||
|
||||
Upgrade an OSD created by old (0.7.1 and older) `make-osd.sh` or `make-osd-hybrid.js` scripts. |
||||
|
||||
Adds superblocks to OSD devices, disables old `vitastor-osdN` unit and replaces it with `vitastor-osd@N`. |
||||
Can be invoked with an osd number of with a path to systemd service file `UNIT_FILE` which |
||||
must be `/etc/systemd/system/vitastor-osd<OSD_NUMBER>.service`. |
||||
|
||||
Note that the procedure isn't atomic and may ruin OSD data in case of an interrupt, |
||||
so don't upgrade all your OSDs in parallel. |
||||
|
||||
Requires the `sfdisk` utility. |
||||
|
||||
## resize |
||||
|
||||
`vitastor-disk resize <ALL_OSD_PARAMETERS> <NEW_LAYOUT> [--iodepth 32]` |
||||
|
||||
Resize data area and/or rewrite/move journal and metadata. |
||||
|
||||
`ALL_OSD_PARAMETERS` must include all (at least all disk-related) |
||||
parameters from OSD command line (i.e. from systemd unit or superblock). |
||||
|
||||
`NEW_LAYOUT` may include new disk layout parameters: |
||||
|
||||
``` |
||||
--new_data_offset SIZE resize data area so it starts at SIZE |
||||
--new_data_len SIZE resize data area to SIZE bytes |
||||
--new_meta_device PATH use PATH for new metadata |
||||
--new_meta_offset SIZE make new metadata area start at SIZE |
||||
--new_meta_len SIZE make new metadata area SIZE bytes long |
||||
--new_journal_device PATH use PATH for new journal |
||||
--new_journal_offset SIZE make new journal area start at SIZE |
||||
--new_journal_len SIZE make new journal area SIZE bytes long |
||||
``` |
||||
|
||||
SIZE may include k/m/g/t suffixes. If any of the new layout parameter |
||||
options are not specified, old values will be used. |
||||
|
||||
## start/stop/restart/enable/disable |
||||
|
||||
`vitastor-disk start|stop|restart|enable|disable [--now] <device> [device2 device3 ...]` |
||||
|
||||
Manipulate Vitastor OSDs using systemd by their device paths. |
||||
|
||||
Commands are passed to `systemctl` with `vitastor-osd@<num>` units as arguments. |
||||
|
||||
When `--now` is added to enable/disable, OSDs are also immediately started/stopped. |
||||
|
||||
## read-sb |
||||
|
||||
`vitastor-disk read-sb <device>` |
||||
|
||||
Try to read Vitastor OSD superblock from `<device>` and print it in JSON format. |
||||
|
||||
## write-sb |
||||
|
||||
`vitastor-disk write-sb <device>` |
||||
|
||||
Read JSON from STDIN and write it into Vitastor OSD superblock on `<device>`. |
||||
|
||||
## udev |
||||
|
||||
`vitastor-disk udev <device>` |
||||
|
||||
Try to read Vitastor OSD superblock from `<device>` and print variables for udev. |
||||
|
||||
## exec-osd |
||||
|
||||
`vitastor-disk exec-osd <device>` |
||||
|
||||
Read Vitastor OSD superblock from `<device>` and start the OSD with parameters from it. |
||||
|
||||
Intended for use from startup scripts (i.e. from systemd units). |
||||
|
||||
## pre-exec |
||||
|
||||
`vitastor-disk pre-exec <device>` |
||||
|
||||
Read Vitastor OSD superblock from `<device>` and perform pre-start checks for the OSD. |
||||
|
||||
For now, this only checks that device cache is in write-through mode if fsync is disabled. |
||||
|
||||
Intended for use from startup scripts (i.e. from systemd units). |
||||
|
||||
## dump-journal |
||||
|
||||
`vitastor-disk dump-journal [OPTIONS] <journal_file> <journal_block_size> <offset> <size>` |
||||
|
||||
Dump journal in human-readable or JSON (if `--json` is specified) format. |
||||
|
||||
Options: |
||||
|
||||
``` |
||||
--all Scan the whole journal area for entries and dump them, even outdated ones |
||||
--json Dump journal in JSON format |
||||
--format entries (Default) Dump actual journal entries as an array, without data |
||||
--format data Same as "entries", but also include small write data |
||||
--format blocks Dump as an array of journal blocks each containing array of entries |
||||
``` |
||||
|
||||
## write-journal |
||||
|
||||
`vitastor-disk write-journal <journal_file> <journal_block_size> <bitmap_size> <offset> <size>` |
||||
|
||||
Write journal from JSON taken from standard input in the same format as produced by |
||||
`dump-journal --json --format data`. |
||||
|
||||
## dump-meta |
||||
|
||||
`vitastor-disk dump-meta <meta_file> <meta_block_size> <offset> <size>` |
||||
|
||||
Dump metadata in JSON format. |
||||
|
||||
## write-meta |
||||
|
||||
`vitastor-disk write-meta <meta_file> <offset> <size>` |
||||
|
||||
Write metadata from JSON taken from standard input in the same format as produced by `dump-meta`. |
||||
|
||||
## simple-offsets |
||||
|
||||
`vitastor-disk simple-offsets <device>` |
||||
|
||||
Calculate offsets for old 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 |
||||
``` |
||||
@ -0,0 +1,248 @@ |
||||
[Документация](../../README-ru.md#документация) → Использование → Управление дисками |
||||
|
||||
----- |
||||
|
||||
[Read in English](disk.en.md) |
||||
|
||||
# Инструмент управления дисками |
||||
|
||||
vitastor-disk - инструмент командной строки для управления дисками Vitastor OSD. |
||||
|
||||
Поддерживаются следующие команды: |
||||
|
||||
- [prepare](#prepare) |
||||
- [upgrade-simple](#upgrade-simple) |
||||
- [resize](#resize) |
||||
- [start/stop/restart/enable/disable](#start/stop/restart/enable/disable) |
||||
- [read-sb](#read-sb) |
||||
- [write-sb](#write-sb) |
||||
- [udev](#udev) |
||||
- [exec-osd](#exec-osd) |
||||
- [pre-exec](#pre-exec) |
||||
- Для отладки: |
||||
- [dump-journal](#dump-journal) |
||||
- [write-journal](#write-journal) |
||||
- [dump-meta](#dump-meta) |
||||
- [write-meta](#write-meta) |
||||
- [simple-offsets](#simple-offsets) |
||||
|
||||
## prepare |
||||
|
||||
`vitastor-disk prepare [OPTIONS] [devices...]` |
||||
|
||||
Подготовить диск(и) для OSD Vitastor. |
||||
|
||||
У команды есть 2 режима. В первом режиме вы указываете список устройств `<devices>`, |
||||
которые должны быть целыми дисками (не разделами). На них автоматически создаются |
||||
разделы и инициализируются OSD. |
||||
|
||||
Во втором режиме вместо списка устройств вы указываете пути к отдельным устройствам |
||||
`--data_device`, `--journal_device` и/или `--meta_device`, которые должны быть |
||||
уже существующими GPT-разделами. В этом случае инициализируется ровно один OSD. |
||||
|
||||
Команде требуются утилиты `vitastor-cli`, `wipefs`, `sfdisk` и `partprobe` (из состава parted). |
||||
|
||||
Опции для автоматического режима: |
||||
|
||||
``` |
||||
--osd_per_disk <N> |
||||
Создавать по несколько (<N>) OSD на каждом диске (по умолчанию 1) |
||||
--hybrid |
||||
Инициализировать гибридные (HDD+SSD) OSD на указанных дисках. SSD будут |
||||
использованы для журналов и метаданных, а HDD - для данных. Разделы для журналов |
||||
и метаданных будут созданы автоматически. Является ли диск SSD или HDD, определяется |
||||
по флагу `/sys/block/.../queue/rotational`. В гибридном режиме по умолчанию |
||||
используется размер объекта 1 МБ вместо 128 КБ, размер журнала 1 ГБ вместо 32 МБ |
||||
и включённый throttle_small_writes. |
||||
--disable_data_fsync 1 |
||||
Отключать кэш и fsync-и для устройств данных (1/yes/true = да, по умолчанию да) |
||||
--disable_meta_fsync 1 |
||||
Отключать кэш и fsync-и для журналов и метаданных (по умолчанию да) |
||||
--meta_reserve 2x,1G |
||||
В гибридном режиме для метаданных выделяется больше места, чем нужно на самом |
||||
деле, чтобы оставить запас под будущее расширение. По умолчанию выделяется |
||||
в 2 раза больше места, и не менее 1 ГБ. Чтобы изменить это поведение, |
||||
воспользуйтесь данной опцией. |
||||
--max_other 10% |
||||
Использовать диски под данные OSD, даже если на них уже есть не-Vitastor-овые |
||||
разделы, но только в случае, если они занимают не более данного процента диска. |
||||
``` |
||||
|
||||
Опции для режима одного OSD: |
||||
|
||||
``` |
||||
--data_device <DEV> Использовать раздел <DEV> для данных |
||||
--meta_device <DEV> Использовать раздел <DEV> для метаданных (опционально) |
||||
--journal_device <DEV> Использовать раздел <DEV> для журнала (опционально) |
||||
--disable_data_fsync 0 Отключить кэш и fsync устройства данных (по умолчанию нет) |
||||
--disable_meta_fsync 0 Отключить кэш и fsync метаданных (по умолчанию нет) |
||||
--disable_journal_fsync 0 Отключить кэш и fsync журнала (по умолчанию нет) |
||||
--force Пропустить проверки разделов (на пустоту и т.п.) |
||||
``` |
||||
|
||||
Опции для обоих режимов: |
||||
|
||||
``` |
||||
--journal_size 1G/32M Задать размер журнала (области или раздела журнала) |
||||
--object_size 1M/128k Задать размер объекта |
||||
--bitmap_granularity 4k Задать гранулярность битовых карт |
||||
--data_device_block 4k Задать размер блока устройства данных |
||||
--meta_device_block 4k Задать размер блока метаданных |
||||
--journal_device_block 4k Задать размер блока журнала |
||||
``` |
||||
|
||||
Настройка [immediate_commit](../config/layout-cluster.ru.md#immediate_commit) |
||||
автоматически выводится из опций отключения кэша - она устанавливается в "all", если кэш |
||||
отключён на всех устройствах, и в "small", если он отключён только на устройстве журнала. |
||||
|
||||
Когда fsync данных/метаданных/журнала отключён, скрипты запуска OSD автоматически |
||||
проверяют состояние кэша диска и стараются его отключить для SATA/SAS дисков. Если |
||||
это не удаётся, в системный журнал выводится предупреждение. |
||||
|
||||
Вы можете передать данной команде и некоторые другие опции OSD в качестве аргументов |
||||
и они тоже будут сохранены в суперблок: max_write_iodepth, max_write_iodepth, min_flusher_count, |
||||
max_flusher_count, inmemory_metadata, inmemory_journal, journal_sector_buffer_count, |
||||
journal_no_same_sector_overwrites, throttle_small_writes, throttle_target_iops, |
||||
throttle_target_mbs, throttle_target_parallelism, throttle_threshold_us. |
||||
Читайте об этих параметрах подробнее в разделе [Изменяемые параметры OSD](../config/osd.ru.md). |
||||
|
||||
## upgrade-simple |
||||
|
||||
`vitastor-disk upgrade-simple <UNIT_FILE|OSD_NUMBER>` |
||||
|
||||
Обновить OSD, созданный старыми (0.7.1 и старее) скриптами `make-osd.sh` и `make-osd-hybrid.js`. |
||||
|
||||
Добавляет суперблок на разделы OSD, отключает старый сервис `vitastor-osdN` и заменяет его на `vitastor-osd@N`. |
||||
|
||||
Можно вызывать, указывая либо номер OSD, либо путь к файлу сервиса `UNIT_FILE`, но он обязан |
||||
иметь вид `/etc/systemd/system/vitastor-osd<OSD_NUMBER>.service`. |
||||
|
||||
Имейте в виду, что процедура обновления не атомарна и при прерывании может уничтожить данные OSD, |
||||
так что обновляйте ваши OSD по очереди. |
||||
|
||||
Команде требуется утилита `sfdisk`. |
||||
|
||||
## resize |
||||
|
||||
`vitastor-disk resize <ALL_OSD_PARAMETERS> <NEW_LAYOUT> [--iodepth 32]` |
||||
|
||||
Изменить размер области данных и/или переместить журнал и метаданные. |
||||
|
||||
В `ALL_OSD_PARAMETERS` нужно указать все относящиеся к диску параметры OSD |
||||
из суперблока OSD или из файла сервиса systemd (в старых версиях). |
||||
|
||||
В `NEW_LAYOUT` нужно указать новые параметры расположения данных: |
||||
|
||||
``` |
||||
--new_data_offset РАЗМЕР сдвинуть начало области данных на РАЗМЕР байт |
||||
--new_data_len РАЗМЕР изменить размер области данных до РАЗМЕР байт |
||||
--new_meta_device ПУТЬ использовать ПУТЬ как новое устройство метаданных |
||||
--new_meta_offset РАЗМЕР разместить новые метаданные по смещению РАЗМЕР байт |
||||
--new_meta_len РАЗМЕР сделать новые метаданные размером РАЗМЕР байт |
||||
--new_journal_device ПУТЬ использовать ПУТЬ как новое устройство журнала |
||||
--new_journal_offset РАЗМЕР разместить новый журнал по смещению РАЗМЕР байт |
||||
--new_journal_len РАЗМЕР сделать новый журнал размером РАЗМЕР байт |
||||
``` |
||||
|
||||
РАЗМЕР может быть указан с суффиксами k/m/g/t. Если любой из новых параметров |
||||
расположения не указан, он принимается равным старому значению. |
||||
|
||||
## start/stop/restart/enable/disable |
||||
|
||||
`vitastor-disk start|stop|restart|enable|disable [--now] <device> [device2 device3 ...]` |
||||
|
||||
Команды управления OSD по путям дисков через systemd. |
||||
|
||||
Команды транслируются `systemctl` с сервисами `vitastor-osd@<num>` в виде аргументов. |
||||
|
||||
Когда к командам включения/выключения добавляется параметр `--now`, OSD также сразу |
||||
запускаются/останавливаются. |
||||
|
||||
## read-sb |
||||
|
||||
`vitastor-disk read-sb <device>` |
||||
|
||||
Прочитать суперблок OSD с диска `<device>` и вывести его в формате JSON. |
||||
|
||||
## write-sb |
||||
|
||||
`vitastor-disk write-sb <device>` |
||||
|
||||
Прочитать JSON со стандартного ввода и записать его в суперблок OSD на диск `<device>`. |
||||
|
||||
## udev |
||||
|
||||
`vitastor-disk udev <device>` |
||||
|
||||
Прочитать суперблок OSD с диска `<device>` и вывести переменные для udev. |
||||
|
||||
## exec-osd |
||||
|
||||
`vitastor-disk exec-osd <device>` |
||||
|
||||
Прочитать суперблок OSD с диска `<device>` и запустить исполняемый файл OSD с параметрами оттуда. |
||||
|
||||
Команда предназначена для использования из скриптов запуска (например, из сервисов systemd). |
||||
|
||||
## pre-exec |
||||
|
||||
`vitastor-disk pre-exec <device>` |
||||
|
||||
Прочитать суперблок OSD с диска `<device>` и провести проверки OSD перед запуском. |
||||
|
||||
На данный момент только отключает кэш диска или проверяет, что он отключён, если в параметрах |
||||
OSD отключены fsync-и. |
||||
|
||||
Команда предназначена для использования из скриптов запуска (например, из сервисов systemd). |
||||
|
||||
## dump-journal |
||||
|
||||
`vitastor-disk dump-journal [OPTIONS] <journal_file> <journal_block_size> <offset> <size>` |
||||
|
||||
Вывести журнал в человекочитаемом или в JSON (с опцией `--json`) виде. |
||||
|
||||
Опции: |
||||
|
||||
``` |
||||
--all Просканировать всю область журнала и вывести даже старые записи |
||||
--json Вывести журнал в формате JSON |
||||
--format entries (По умолчанию) Вывести только актуальные записи журнала без данных |
||||
--format data Вывести только актуальные записи журнала с данными |
||||
--format blocks Вывести массив блоков журнала, а в каждом массив актуальных записей без данных |
||||
``` |
||||
|
||||
## write-journal |
||||
|
||||
`vitastor-disk write-journal <journal_file> <journal_block_size> <bitmap_size> <offset> <size>` |
||||
|
||||
Записать журнал из JSON со стандартного ввода в формате, аналогичном `dump-journal --json --format data`. |
||||
|
||||
## dump-meta |
||||
|
||||
`vitastor-disk dump-meta <meta_file> <meta_block_size> <offset> <size>` |
||||
|
||||
Вывести метаданные в формате JSON. |
||||
|
||||
## write-meta |
||||
|
||||
`vitastor-disk write-meta <meta_file> <offset> <size>` |
||||
|
||||
Записать метаданные из JSON со стандартного ввода в формате, аналогичном `dump-meta`. |
||||
|
||||
## simple-offsets |
||||
|
||||
`vitastor-disk 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 |
||||
``` |
||||
Loading…
Reference in new issue