Skip to content

RapidDisk Administration Utility

Petros Koutoupis edited this page Jun 28, 2023 · 15 revisions

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