RapidDisk Administration Utility - pkoutoupis/rapiddisk GitHub Wiki
RapidDisk Administration Utility
The RapidDisk user administration utility simplifies the management of the RapidDisk and RapidDisk-Cache modules. For legacy rapiddisk management, please refer to the misc/rapiddisk-legacy/rapiddisk-legacy.sh and the misc/rapiddisk-legacy/README.md for instructions on how to use it.
Manual Page
RAPIDDISK(1) GENERAL COMMANDS RAPIDDISK(1)
NAME
rapiddisk - An administration tool to manage the RapidDisk RAM disk de‐
vices and RapidDisk-Cache mappings. And export those volumes across an
NVMe Target network.
SYNOPSIS
rapiddisk [ -h | -v ] function [ parameters ]
DESCRIPTION
rapiddisk is a RapidDisk module management tool to manage RapidDisk RAM
disk devices. Dynamically create, remove, resize RAM volumes and if de‐
sired, map or unmap them as a cache volume to any block device.
Options
-h Invoke the help menu.
-v Display the version number.
Functions
-a Attach RAM disk device (size in MBytes).
-b Backend block device absolute path (for cache mapping).
-c Input capacity for size or resize of RAM disk device (in
MBytes).
-d Detach RAM disk device.
-e Export a RapidDisk block device as an NVMe Target.
-f Erase all data to a specified RapidDisk device (dangerous).
-H The host to export / unexport the NVMe Target to / from.
-i Define the network interface to enable for NVMe Target export‐
ing. Port must not already exist and interface must not be al‐
ready enabled.
-j Enable JSON formatted output.
-L Lock a RapidDisk block device (set to read-only).
-l List all attached RAM disk devices.
-m Map an RapidDisk device as a caching node to another block de‐
vice.
-N List only enabled NVMe Target ports.
-n List RapidDisk enabled NVMe Target exports.
-P The port to export / unexport the NVMe Target to / from.
-p Define cache policy: write-through (wt), write-around (wa) or
writeback (wb) (dangerous) (default: write-through). Writeback
caching is supplied by the dm-writecache kernel module and is
not intended for production use as it may result in data loss on
hardware/power failure.
-r Dynamically grow the size of an existing RapidDisk device.
-s Obtain RapidDisk-Cache Mappings statistics.
-t Define the NVMe Target port's transfer protocol (i.e. tcp or
rdma).
-U Unlock a RapidDisk block device (set to read-write).
-u Unmap a RapidDisk device from another block device.
-X Remove the NVMe Target port (must be unused).
-x Unexport a RapidDisk block device from an NVMe Target. To remove
export to host or port, only define the host and / or port. Not
defining a host or port will result in the block device being
removed from the NVMe Target subsystem.
Parameters (if applicable)
[size] Specify desired size of attaching RAM disk device in MBytes.
[mode] Write Through (wt) or Write Around (wa) for cache.
EXAMPLES USAGE
rapiddisk -l
rapiddisk -l -j
rapiddisk -a 64
rapiddisk -d rd2
rapiddisk -r rd2 -c 128
rapiddisk -m rd1 -b /dev/sdb
rapiddisk -m rd1 -b /dev/sdb -p wt
rapiddisk -m rd3 -b /dev/mapper/rc-wa_sdb -p wb
rapiddisk -u rc-wt_sdb
rapiddisk -s rc-wt_sdb
rapiddisk -f rd2
rapiddisk -L rd2
rapiddisk -U rd3
rapiddisk -i eth0 -P 1 -t tcp
rapiddisk -X -P 1
rapiddisk -e -b rd3 -P 1 -H nqn.host1
rapiddisk -x -b rd3 -P 1 -H nqn.host1
EXIT STATUS
rapiddisk returns a zero exit status if no error occurs during operation. A
non- zero value is returned on error.
AUTHORS
Original version: Petros Koutoupis ([email protected])
SEE ALSO
View the RapidDisk project page: http://www.rapiddisk.org
Linux Oct 16 2010 RAPIDDISK(1)
RapidDisk Management
Through a single management interface (/sys/kernel/rapiddisk/mgmt), the module is configured to dynamically add / remove RAM disks and more, on-the-fly. Such an open source implementation does not exist under Linux! For the most part, general functionality is handled via the rapiddisk administration tool. See RapidDisk-Cache below for details on cache mapping / unmapping RapidDisk RAM volumes as a caching node to slower storage drives for accelerated read performance. More details of usage can be found in the tool’s manual page (man 1 rapiddisk).
To list all attached RapidDisk volumes:
$ sudo rapiddisk -l
To list all volumes in JSON format:
$ sudo rapiddisk -l -j|jq .
{
"volumes": [
{
"rapiddisk": [
{
"device": "rd1",
"size": 67108864,
"usage": 4096,
"status": "unlocked"
},
{
"device": "rd0",
"size": 67108864,
"usage": 65536,
"status": "unlocked"
}
]
},
{
"rapiddisk_cache": [
{
"device": "rc-wa_loop7",
"cache": "rd0",
"source": "loop7",
"mode": "write-around"
}
]
}
]
}
To attach a new RapidDisk volume (128 MB in example – Note – All newly attached volumes will appear in the /dev directory path (e.g. /dev/rd0)):
$ sudo rapiddisk -a 128
To detach an existing RapidDisk volume:
$ sudo rapiddisk -d rd2
To resize an existing RapidDisk volume:
$ sudo rapiddisk -r rd0 -c 256
To view the module’s current settings and a volume summary:
$ cat /sys/kernel/rapiddisk/mgmt
RapidDisk-Cache Management
The same rapiddisk administration tool used for RapidDisk is also used to map and unmap RapidDisk-Cache volumes. It essentially formats the command for Device Mapper and then uses (transparent to the administrator) the dmsetup utility. More details of usage can be found in the tool’s manual page (man 1 rapiddisk).
While the rapiddisk administration utility checks for all of these (except for the last) scenarios, it is worth noting the following:
- You are not able to map any device currently in a mapping.
- You are not able unmap a mounted mapping. You must first invoke a umount.
- You are not able to detach an RapidDisk if it is currently in a mapping.
- Every mapping must have an RapidDisk device selected as the caching drive.
- Every mapping must have a typical block device that can be accessed via the /dev directory path selected as the source drive.
- Please do not map one RapidDisk device to another, it defeats the purpose of this module.
Listing all current mappings with detailed information:
$ sudo rapiddisk -l
rapiddisk 4.0
Copyright 2011-2016 Petros Koutoupis
List of RapidDisk device(s):
RapidDisk Device 1: rd0 Size (MB): 128
RapidDisk Device 2: rd1 Size (MB): 256
RapidDisk Device 3: rd2 Size (MB): 64
List of RapidDisk-Cache mapping(s):
RapidDisk-Cache Target 1: rc-wt_sdb Cache: rd1 Target: sdb (WRITETHROUGH)
All newly mapped devices will be accessible from the /dev/mapper directory path. Creating a mapping:
$ sudo rapiddisk -m rd0 -b /dev/sdb
rapiddisk 4.0
Copyright 2011-2016 Petros Koutoupis
Command to map rc-wt_sdb with rd0 and /dev/sdb has been sent.
Verify with "-l"
Removing a mapping:
$ sudo rapiddisk -u rc-wt_sdb
rapiddisk 4.0
Copyright 2011-2016 Petros Koutoupis
Command to unmap rc-wt_sdb has been sent.
Verify with "-l"
Working with a mapping:
$ sudo mke2fs -F /dev/mapper/rc-wt_sdb
$ sudo mkdir /mnt/rc-wt_sdb
$ sudo mount /dev/mapper/rc-wt_sdb /mnt/rc-wt_sdb
Other Device-Mapper specific commands:
$ sudo dmsetup status rc-wt_sdb
$ sudo dmsetup table rc-wt_sdb
NVMe Target Management of RapidDisk Volumes
List all NVMe Target ports:
$ sudo rapiddisk -N
List all NVMe Target ports in JSON format:
$ rapiddisk -N -j|jq .
{
"targets": [
{
"nvmet_ports": [
{
"port": 0,
"address": "10.0.0.185",
"protocol": "tcp"
}
]
}
]
}
List all exported NVMe Target volumes:
$ sudo rapiddisk -n
List all exported NVMe Target volumes in JSON:
$ sudo rapiddisk -n -j|jq .
{
"targets": [
{
"nvmet_targets": [
{
"nqn": "nqn.2021-06.org.rapiddisk:dev-machine-rd1",
"namespace": 1,
"device": "/dev/rd1",
"enabled": "true"
},
{
"nqn": "nqn.2021-06.org.rapiddisk:dev-machine-rd0",
"namespace": 1,
"device": "/dev/rd0",
"enabled": "true"
}
]
},
{
"nvmet_ports": [
{
"port": 0,
"address": "10.0.0.185",
"protocol": "tcp",
"nqn": "nqn.2021-06.org.rapiddisk:dev-machine-rd1"
},
{
"port": 0,
"address": "10.0.0.185",
"protocol": "tcp",
"nqn": "nqn.2021-06.org.rapiddisk:dev-machine-rd0"
}
]
}
]
}
To create an NVMe Target port:
$ sudo rapiddisk -i eno1 -P 1 -t tcp
To remove an [unused] NVMe Target port:
$ sudo rapiddisk -X -P 1
To export a RapidDisk volume via an NVMe Target port:
$ sudo rapiddisk -e -b rd1 -P 1 -H nqn.host1
To unexport a RapidDisk volume from an NVMe Target port:
$ sudo rapiddisk -x -b rd1 -P 1
To unexport a RapidDisk volume from an an existing NVMe Target host:
$ sudo rapiddisk -x -b rd1 -H nqn.host1
To completely remove a RapidDisk volume from the NVMe Target subsystem:
$ sudo rapiddisk -x -b rd1