Move NBD netlink map&unmap to separate commands, add "netlink-revive" command
This commit is contained in:
Vitaliy Filippov
+63
-10
@@ -15,12 +15,21 @@ See also [VDUSE](qemu.en.md#vduse) as a better alternative to NBD.
|
||||
|
||||
Vitastor Kubernetes CSI driver uses NBD when VDUSE is unavailable.
|
||||
|
||||
## Map image
|
||||
Supports the following commands:
|
||||
|
||||
- [map](#map)
|
||||
- [unmap](#unmap)
|
||||
- [ls](#ls)
|
||||
- [netlink-map](#netlink-map)
|
||||
- [netlink-unmap](#netlink-unmap)
|
||||
- [netlink-revive](#netlink-revive)
|
||||
|
||||
## map
|
||||
|
||||
To create a local block device for a Vitastor image run:
|
||||
|
||||
```
|
||||
vitastor-nbd map --image testimg
|
||||
vitastor-nbd map [/dev/nbdN] --image testimg
|
||||
```
|
||||
|
||||
It will output a block device name like /dev/nbd0 which you can then use as a normal disk.
|
||||
@@ -29,25 +38,25 @@ You can also use `--pool <POOL> --inode <INODE> --size <SIZE>` instead of `--ima
|
||||
|
||||
vitastor-nbd supports all usual Vitastor configuration options like `--config_file <path_to_config>` plus NBD-specific:
|
||||
|
||||
* `--nbd_timeout 300` \
|
||||
Timeout for I/O operations in seconds after exceeding which the kernel stops
|
||||
the device. You can set it to 0 to disable the timeout, but beware that you
|
||||
won't be able to stop the device at all if vitastor-nbd process dies.
|
||||
* `--nbd_timeout 0` \
|
||||
Timeout for I/O operations in seconds after exceeding which the kernel stops the device.
|
||||
Before Linux 5.19, if nbd_timeout is 0, a dead NBD device can't be removed from
|
||||
the system at all without rebooting.
|
||||
* `--nbd_max_devices 64 --nbd_max_part 3` \
|
||||
Options for the `nbd` kernel module when modprobing it (`nbds_max` and `max_part`).
|
||||
note that maximum allowed (nbds_max)*(1+max_part) is 256.
|
||||
* `--logfile /path/to/log/file.txt` \
|
||||
Write log messages to the specified file instead of dropping them (in background mode)
|
||||
or printing them to the standard output (in foreground mode).
|
||||
* `--dev_num N` \
|
||||
Use the specified device /dev/nbdN instead of automatic selection.
|
||||
Use the specified device /dev/nbdN instead of automatic selection (alternative syntax
|
||||
to /dev/nbdN positional parameter).
|
||||
* `--foreground 1` \
|
||||
Stay in foreground, do not daemonize.
|
||||
|
||||
Note that `nbd_timeout`, `nbd_max_devices` and `nbd_max_part` options may also be specified
|
||||
in `/etc/vitastor/vitastor.conf` or in other configuration file specified with `--config_file`.
|
||||
|
||||
## Unmap image
|
||||
## unmap
|
||||
|
||||
To unmap the device run:
|
||||
|
||||
@@ -55,12 +64,14 @@ To unmap the device run:
|
||||
vitastor-nbd unmap /dev/nbd0
|
||||
```
|
||||
|
||||
## List mapped images
|
||||
## ls
|
||||
|
||||
```
|
||||
vitastor-nbd ls [--json]
|
||||
```
|
||||
|
||||
List mapped images.
|
||||
|
||||
Example output (normal format):
|
||||
|
||||
```
|
||||
@@ -78,3 +89,45 @@ Example output (JSON format):
|
||||
```
|
||||
{"/dev/nbd0": {"image": "bench", "pid": 584536}, "/dev/nbd1": {"image": "bench1", "pid": 584546}}
|
||||
```
|
||||
|
||||
## netlink-map
|
||||
|
||||
```
|
||||
vitastor-nbd netlink-map [/dev/nbdN] (--image <image> | --pool <pool> --inode <inode> --size <size in bytes>)
|
||||
```
|
||||
|
||||
On recent kernel versions it's also possinle to map NBD devices using netlink interface.
|
||||
|
||||
This is an experimental feature because it doesn't solve all issues of NBD. Differences from regular ioctl-based 'map':
|
||||
|
||||
1. netlink-map can create new `/dev/nbdN` devices (those not present in /dev/).
|
||||
2. netlink-mapped devices can be unmapped only using `netlink-unmap` command.
|
||||
3. netlink-mapped devices don't show up `ls` output (yet).
|
||||
4. Dead netlink-mapped devices can be 'revived' using `netlink-revive`.
|
||||
However, old I/O requests will hang forever if `nbd_timeout` is not specified.
|
||||
5. netlink-map supports additional options:
|
||||
|
||||
* `--nbd_conn_timeout 0` \
|
||||
Disconnect a dead device automatically after this number of seconds.
|
||||
* `--nbd_destroy_on_disconnect 1` \
|
||||
Delete the nbd device on disconnect.
|
||||
* `--nbd_disconnect_on_close 1` \
|
||||
Disconnect the nbd device on close by last opener.
|
||||
* `--nbd_ro 1` \
|
||||
Set device into read only mode.
|
||||
|
||||
## netlink-unmap
|
||||
|
||||
```
|
||||
vitastor-nbd netlink-unmap /dev/nbdN
|
||||
```
|
||||
|
||||
Unmap a device using netlink interface. Works with both netlink and ioctl mapped devices.
|
||||
|
||||
## netlink-revive
|
||||
|
||||
```
|
||||
vitastor-nbd netlink-revive /dev/nbdX (--image <image> | --pool <pool> --inode <inode> --size <size in bytes>)
|
||||
```
|
||||
|
||||
Restart a dead NBD netlink-mapped device without removing it. Supports the same options as `netlink-map`.
|
||||
|
||||
+63
-12
@@ -18,12 +18,21 @@ NBD немного снижает производительность из-за
|
||||
|
||||
CSI-драйвер Kubernetes Vitastor использует NBD, когда VDUSE недоступен.
|
||||
|
||||
## Подключить устройство
|
||||
Поддерживаются следующие команды:
|
||||
|
||||
- [map](#map)
|
||||
- [unmap](#unmap)
|
||||
- [ls](#ls)
|
||||
- [netlink-map](#netlink-map)
|
||||
- [netlink-unmap](#netlink-unmap)
|
||||
- [netlink-revive](#netlink-revive)
|
||||
|
||||
## map
|
||||
|
||||
Чтобы создать локальное блочное устройство для образа, выполните команду:
|
||||
|
||||
```
|
||||
vitastor-nbd map --image testimg
|
||||
vitastor-nbd map [/dev/nbdN] --image testimg
|
||||
```
|
||||
|
||||
Команда напечатает название блочного устройства вида /dev/nbd0, которое потом можно
|
||||
@@ -35,16 +44,13 @@ vitastor-nbd map --image testimg
|
||||
vitastor-nbd поддерживает все обычные опции Vitastor, например, `--config_file <path_to_config>`,
|
||||
плюс специфичные для NBD:
|
||||
|
||||
* `--nbd_timeout 30` \
|
||||
* `--nbd_timeout 0` \
|
||||
Максимальное время выполнения любой операции чтения/записи в секундах, при
|
||||
превышении которого ядро остановит NBD-устройство. Вы можете установить опцию
|
||||
в 0, чтобы отключить ограничение времени, но имейте в виду, что в этом случае
|
||||
вы вообще не сможете отключить NBD-устройство при нештатном завершении процесса
|
||||
vitastor-nbd.
|
||||
превышении которого ядро остановит NBD-устройство. На ядрах Linux старее 5.19,
|
||||
если таймаут установлен в 0, NBD-устройство вообще невозможно отключить из системы
|
||||
при нештатном завершении процесса.
|
||||
* `--nbd_max_devices 64 --nbd_max_part 3` \
|
||||
Опции, передаваемые модулю ядра nbd, если его загружает vitastor-nbd
|
||||
(`nbds_max` и `max_part`). Имейте в виду, что (nbds_max)*(1+max_part)
|
||||
обычно не должно превышать 256.
|
||||
Опции, передаваемые модулю ядра nbd, если его загружает vitastor-nbd (`nbds_max` и `max_part`).
|
||||
* `--logfile /path/to/log/file.txt` \
|
||||
Писать сообщения о процессе работы в заданный файл, вместо пропуска их
|
||||
при фоновом режиме запуска или печати на стандартный вывод при запуске
|
||||
@@ -58,7 +64,7 @@ vitastor-nbd поддерживает все обычные опции Vitastor,
|
||||
также задавать в `/etc/vitastor/vitastor.conf` или в другом файле конфигурации,
|
||||
заданном опцией `--config_file`.
|
||||
|
||||
## Отключить устройство
|
||||
## unmap
|
||||
|
||||
Для отключения устройства выполните:
|
||||
|
||||
@@ -66,12 +72,14 @@ vitastor-nbd поддерживает все обычные опции Vitastor,
|
||||
vitastor-nbd unmap /dev/nbd0
|
||||
```
|
||||
|
||||
## Вывести подключённые устройства
|
||||
## ls
|
||||
|
||||
```
|
||||
vitastor-nbd ls [--json]
|
||||
```
|
||||
|
||||
Вывести подключённые устройства.
|
||||
|
||||
Пример вывода в обычном формате:
|
||||
|
||||
```
|
||||
@@ -89,3 +97,46 @@ pid: 584546
|
||||
```
|
||||
{"/dev/nbd0": {"image": "bench", "pid": 584536}, "/dev/nbd1": {"image": "bench1", "pid": 584546}}
|
||||
```
|
||||
|
||||
## netlink-map
|
||||
|
||||
```
|
||||
vitastor-nbd netlink-map [/dev/nbdN] (--image <image> | --pool <POOL> --inode <INODE> --size <SIZE>)
|
||||
```
|
||||
|
||||
На свежих версиях ядра Linux также возможно подключать NBD-устройства через интерфейс netlink.
|
||||
|
||||
Это экспериментальная функция, так как она не решает всех проблем NBD. Отличия от обычного 'map':
|
||||
|
||||
1. Можно создавать новые `/dev/nbdN` устройства (отсутствующие в /dev/).
|
||||
2. Отключать netlink-устройства можно только командой `netlink-unmap`.
|
||||
3. netlink-устройства не видно в выводе `ls` (пока что).
|
||||
4. Мёртвые netlink-устройства можно "оживить" командой `netlink-revive`. Правда, предыдущие
|
||||
запросы ввода-вывода всё равно зависнут навсегда, если `nbd_timeout` не задан.
|
||||
5. Поддерживаются дополнительные опции:
|
||||
|
||||
* `--nbd_conn_timeout 0` \
|
||||
Отключать мёртвое устройство автоматически через данное число секунд.
|
||||
* `--nbd_destroy_on_disconnect 1` \
|
||||
Удалять NBD-устройство при отключении.
|
||||
* `--nbd_disconnect_on_close 1` \
|
||||
Отключать NBD-устройство автоматически, когда его все закроют.
|
||||
* `--nbd_ro 1` \
|
||||
Установить для NBD-устройства режим "только для чтения".
|
||||
|
||||
## netlink-unmap
|
||||
|
||||
```
|
||||
vitastor-nbd netlink-unmap /dev/nbdN
|
||||
```
|
||||
|
||||
Отключить устройство через интерфейс netlink. Работает и с обычными, и с netlink-устройствами.
|
||||
|
||||
## netlink-revive
|
||||
|
||||
```
|
||||
vitastor-nbd netlink-revive /dev/nbdX (--image <image> | --pool <pool> --inode <inode> --size <size in bytes>)
|
||||
```
|
||||
|
||||
Оживить мёртвое NBD-устройство, ранее подключённое через netlink, без удаления. Поддерживает
|
||||
те же опции, что и `netlink-map`.
|
||||
|
||||
Reference in New Issue
Block a user