numam-spdk/doc/jsonrpc.md

JSON-RPC Methods

Overview

SPDK implements a JSON-RPC 2.0 server to allow external management tools to dynamically configure SPDK components.

Parameters

Most of the commands can take parameters. If present, parameter is validated against its domain. If this check fail whole command will fail with response error message [Invalid params](@ref jsonrpc_error_message).

Required parameters

These parameters are mandatory. If any required parameter is missing RPC command will fail with proper error response.

Optional parameters

Those parameters might be omitted. If an optional parameter is present it must be valid otherwise command will fail proper error response.

Error response message

Each error response will contain proper message. As much as possible the message should indicate what went wrong during command processing.

There is ongoing effort to customize this messages but some RPC methods just return "Invalid parameters" as message body for any kind of error.

Code	Description
-1	Invalid state - given method exists but it is not callable in [current runtime state](@ref rpc_start_subsystem_init)
-32600	Invalid request - not compliant with JSON-RPC 2.0 Specification
-32601	Method not found
-32602	@ref jsonrpc_invalid_params
-32603	Internal error for e.g.: errors like out of memory
-32700	@ref jsonrpc_parser_error

Parser error

Encountered some error during parsing request like:

• the JSON object is malformed
• parameter is too long
• request is too long

Invalid params

This type of error is most common one. It mean that there is an error while processing the request like:

• Parameters decoding in RPC method handler failed because required parameter is missing.
• Unknown parameter present encountered.
• Parameter type doesn't match expected type e.g.: given number when expected a string.
• Parameter domain check failed.
• Request is valid but some other error occurred during processing request. If possible message explains the error reason nature.

App Framework

kill_instance

Send a signal to the application.

Parameters

Name	Optional	Type	Description
sig_name	Required	string	Signal to send (SIGINT, SIGTERM, SIGQUIT, SIGHUP, or SIGKILL)

Example

Example request:

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "kill_instance",
  "params": {
    "sig_name": "SIGINT"
  }
}

Example response:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": true
}

context_switch_monitor

Query, enable, or disable the context switch monitoring functionality.

Parameters

Name	Optional	Type	Description
enabled	Optional	boolean	Enable (true) or disable (false) monitoring (omit this parameter to query the current state)

Response

Name	Type	Description
enabled	boolean	The current state of context switch monitoring

Example

Example request:

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "context_switch_monitor",
  "params": {
    "enabled": false
  }
}

Example response:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "enabled": false
  }
}

start_subsystem_init

Start initialization of SPDK subsystems when it is deferred by starting SPDK application with option -w. During its deferral some RPCs can be used to set global parameters for SPDK subsystems. This RPC can be called only once.

Parameters

This method has no parameters.

Response

Completion status of SPDK subsystem initialization is returned as a boolean.

Example

Example request:

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "start_subsystem_init"
}

Example response:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": true
}

wait_subsystem_init

Do not return until all subsystems have been initialized and the RPC system state is running. If the application is already running, this call will return immediately. This RPC can be called at any time.

Parameters

This method has no parameters.

Response

Returns True when subsystems have been initialized.

Example

Example request:

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "wait_subsystem_init"
}

Example response:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": true
}

rpc_get_methods

Get an array of supported RPC methods.

Parameters

Name	Optional	Type	Description
current	Optional	boolean	Get an array of RPC methods only callable in the current state.

Response

The response is an array of supported RPC methods.

Example

Example request:

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "rpc_get_methods"
}

Example response:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": [
    "start_subsystem_init",
    "get_rpc_methods",
    "get_scsi_devices",
    "get_interfaces",
    "delete_ip_address",
    "add_ip_address",
    "get_nbd_disks",
    "stop_nbd_disk",
    "start_nbd_disk",
    "get_log_flags",
    "clear_log_flag",
    "set_log_flag",
    "get_log_level",
    "set_log_level",
    "get_log_print_level",
    "set_log_print_level",
    "get_iscsi_global_params",
    "target_node_add_lun",
    "get_iscsi_connections",
    "delete_portal_group",
    "add_portal_group",
    "get_portal_groups",
    "delete_target_node",
    "delete_pg_ig_maps",
    "add_pg_ig_maps",
    "construct_target_node",
    "get_target_nodes",
    "delete_initiator_group",
    "delete_initiators_from_initiator_group",
    "add_initiators_to_initiator_group",
    "add_initiator_group",
    "get_initiator_groups",
    "set_iscsi_options",
    "set_bdev_options",
    "set_bdev_qos_limit",
    "get_bdevs",
    "get_bdevs_iostat",
    "get_subsystem_config",
    "get_subsystems",
    "context_switch_monitor",
    "kill_instance",
    "scan_ioat_copy_engine",
    "construct_virtio_dev",
    "get_virtio_scsi_devs",
    "remove_virtio_bdev",
    "delete_aio_bdev",
    "construct_aio_bdev",
    "destruct_split_vbdev",
    "construct_split_vbdev",
    "bdev_inject_error",
    "delete_error_bdev",
    "construct_error_bdev",
    "construct_passthru_bdev",
    "apply_nvme_firmware",
    "delete_nvme_controller",
    "construct_nvme_bdev",
    "construct_null_bdev",
    "delete_malloc_bdev",
    "construct_malloc_bdev",
    "delete_ftl_bdev",
    "construct_ftl_bdev",
    "get_lvol_stores",
    "destroy_lvol_bdev",
    "resize_lvol_bdev",
    "set_read_only_lvol_bdev",
    "decouple_parent_lvol_bdev",
    "inflate_lvol_bdev",
    "rename_lvol_bdev",
    "clone_lvol_bdev",
    "snapshot_lvol_bdev",
    "construct_lvol_bdev",
    "destroy_lvol_store",
    "rename_lvol_store",
    "construct_lvol_store"
  ]
}

get_subsystems

Get an array of name and dependency relationship of SPDK subsystems in initialization order.

Parameters

None

Response

The response is an array of name and dependency relationship of SPDK subsystems in initialization order.

Example

Example request:

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "get_subsystems"
}

Example response:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": [
    {
      "subsystem": "copy",
      "depends_on": []
    },
    {
      "subsystem": "interface",
      "depends_on": []
    },
    {
      "subsystem": "net_framework",
      "depends_on": [
        "interface"
      ]
    },
    {
      "subsystem": "bdev",
      "depends_on": [
        "copy"
      ]
    },
    {
      "subsystem": "nbd",
      "depends_on": [
        "bdev"
      ]
    },
    {
      "subsystem": "nvmf",
      "depends_on": [
        "bdev"
      ]
    },
    {
      "subsystem": "scsi",
      "depends_on": [
        "bdev"
      ]
    },
    {
      "subsystem": "vhost",
      "depends_on": [
        "scsi"
      ]
    },
    {
      "subsystem": "iscsi",
      "depends_on": [
        "scsi"
      ]
    }
  ]
}

get_subsystem_config

Get current configuration of the specified SPDK subsystem

Parameters

Name	Optional	Type	Description
name	Required	string	SPDK subsystem name

Response

The response is current configuration of the specified SPDK subsystem. Null is returned if it is not retrievable by the get_subsystem_config method and empty array is returned if it is empty.

Example

Example request:

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "get_subsystem_config",
  "params": {
    "name": "bdev"
  }
}

Example response:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": [
    {
      "params": {
        "base_bdev": "Malloc2",
        "split_size_mb": 0,
        "split_count": 2
      },
      "method": "construct_split_vbdev"
    },
    {
      "params": {
        "trtype": "PCIe",
        "name": "Nvme1",
        "traddr": "0000:01:00.0"
      },
      "method": "construct_nvme_bdev"
    },
    {
      "params": {
        "trtype": "PCIe",
        "name": "Nvme2",
        "traddr": "0000:03:00.0"
      },
      "method": "construct_nvme_bdev"
    },
    {
      "params": {
        "block_size": 512,
        "num_blocks": 131072,
        "name": "Malloc0",
        "uuid": "913fc008-79a7-447f-b2c4-c73543638c31"
      },
      "method": "construct_malloc_bdev"
    },
    {
      "params": {
        "block_size": 512,
        "num_blocks": 131072,
        "name": "Malloc1",
        "uuid": "dd5b8f6e-b67a-4506-b606-7fff5a859920"
      },
      "method": "construct_malloc_bdev"
    }
  ]
}

Block Device Abstraction Layer

set_bdev_options

Set global parameters for the block device (bdev) subsystem. This RPC may only be called before SPDK subsystems have been initialized.

Parameters

Name	Optional	Type	Description
bdev_io_pool_size	Optional	number	Number of spdk_bdev_io structures in shared buffer pool
bdev_io_cache_size	Optional	number	Maximum number of spdk_bdev_io structures cached per thread

Example

Example request:

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "set_bdev_options",
  "params": {
    "bdev_io_pool_size": 65536,
    "bdev_io_cache_size": 256
  }
}

Example response:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": true
}

get_bdevs

Get information about block devices (bdevs).

Parameters

The user may specify no parameters in order to list all block devices, or a block device may be specified by name.

Name	Optional	Type	Description
name	Optional	string	Block device name

Response

The response is an array of objects containing information about the requested block devices.

Example

Example request:

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "get_bdevs",
  "params": {
    "name": "Malloc0"
  }
}

Example response:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": [
    {
      "name": "Malloc0",
      "product_name": "Malloc disk",
      "block_size": 512,
      "num_blocks": 20480,
      "claimed": false,
      "supported_io_types": {
        "read": true,
        "write": true,
        "unmap": true,
        "write_zeroes": true,
        "flush": true,
        "reset": true,
        "nvme_admin": false,
        "nvme_io": false
      },
      "driver_specific": {}
    }
  ]
}

get_bdevs_iostat

Get I/O statistics of block devices (bdevs).

Parameters

The user may specify no parameters in order to list all block devices, or a block device may be specified by name.

Name	Optional	Type	Description
name	Optional	string	Block device name

Response

The response is an array of objects containing I/O statistics of the requested block devices.

Example

Example request:

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "get_bdevs_iostat",
  "params": {
    "name": "Nvme0n1"
  }
}

Example response:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "tick_rate": 2200000000,
    "bdevs" : [
      {
        "name": "Nvme0n1",
        "bytes_read": 36864,
        "num_read_ops": 2,
        "bytes_written": 0,
        "num_write_ops": 0,
        "bytes_unmapped": 0,
        "num_unmap_ops": 0,
        "read_latency_ticks": 178904,
        "write_latency_ticks": 0,
        "unmap_latency_ticks": 0,
        "queue_depth_polling_period": 2,
        "queue_depth": 0,
        "io_time": 0,
        "weighted_io_time": 0
      }
    ]
  }
}

enable_bdev_histogram

Control whether collecting data for histogram is enabled for specified bdev.

Parameters

Name	Optional	Type	Description
name	Required	string	Block device name
enable	Required	boolean	Enable or disable histogram on specified device

Example

Example request:

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "enable_bdev_histogram",
  "params": {
    "name": "Nvme0n1"
    "enable": true
  }
}

Example response:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": true
}

get_bdev_histogram

Get latency histogram for specified bdev.

Parameters

Name	Optional	Type	Description
name	Required	string	Block device name

Result

Name	Description
histogram	Base64 encoded histogram
bucket_shift	Granularity of the histogram buckets
tsc_rate	Ticks per second

Example

Example request:

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "get_bdev_histogram",
  "params": {
    "name": "Nvme0n1"
  }
}

Example response: Note that histogram field is trimmed, actual encoded histogram length is ~80kb.

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "histogram": "AAAAAAAAAAAAAA...AAAAAAAAA==",
    "tsc_rate": 2300000000,
    "bucket_shift": 7
  }
}

set_bdev_qos_limit

Set the quality of service rate limit on a bdev.

Parameters

Name	Optional	Type	Description
name	Required	string	Block device name
rw_ios_per_sec	Optional	number	Number of R/W I/Os per second to allow. 0 means unlimited.
rw_mbytes_per_sec	Optional	number	Number of R/W megabytes per second to allow. 0 means unlimited.
r_mbytes_per_sec	Optional	number	Number of Read megabytes per second to allow. 0 means unlimited.
w_mbytes_per_sec	Optional	number	Number of Write megabytes per second to allow. 0 means unlimited.

Example

Example request:

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "set_bdev_qos_limit",
  "params": {
    "name": "Malloc0"
    "rw_ios_per_sec": 20000
    "rw_mbytes_per_sec": 100
    "r_mbytes_per_sec": 50
    "w_mbytes_per_sec": 50
  }
}

Example response:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": true
}

construct_ocf_bdev

Construct new OCF bdev. Command accepts cache mode that is going to be used. Currently, we support Write-Through, Pass-Through and Write-Back OCF cache modes.

Parameters

Name	Optional	Type	Description
name	Required	string	Bdev name to use
mode	Required	string	OCF cache mode ('wb' or 'wt' or 'pt')
cache_bdev_name	Required	string	Name of underlying cache bdev
core_bdev_name	Required	string	Name of underlying core bdev

Result

Name of newly created bdev.

Example

Example request:

{
  "params": {
    "name": "ocf0",
    "mode": "wt",
    "cache_bdev_name": "Nvme0n1"
    "core_bdev_name": "aio0"
  },
  "jsonrpc": "2.0",
  "method": "construct_ocf_bdev",
  "id": 1
}

Example response:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": "ocf0"
}

delete_ocf_bdev

Delete the OCF bdev

Parameters

Name	Optional	Type	Description
name	Required	string	Bdev name

Example

Example request:

{
  "params": {
    "name": "ocf0"
  },
  "jsonrpc": "2.0",
  "method": "delete_ocf_bdev",
  "id": 1
}

Example response:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": true
}

get_ocf_stats

Get statistics of chosen OCF block device.

Parameters

Name	Optional	Type	Description
name	Required	string	Block device name

Response

Statistics as json object.

Example

Example request:

{
  "jsonrpc": "2.0",
  "method": "get_ocf_stats",
  "id": 1
}

Example response:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": [
  "usage": {
    "clean": {
      "count": 76033,
      "units": "4KiB blocks",
      "percentage": "100.0"
    },
    "free": {
      "count": 767,
      "units": "4KiB blocks",
      "percentage": "0.9"
    },
    "occupancy": {
      "count": 76033,
      "units": "4KiB blocks",
      "percentage": "99.0"
    },
    "dirty": {
      "count": 0,
      "units": "4KiB blocks",
      "percentage": "0.0"
    }
  },
  "requests": {
    "rd_total": {
      "count": 2,
      "units": "Requests",
      "percentage": "0.0"
    },
    "wr_full_misses": {
      "count": 76280,
      "units": "Requests",
      "percentage": "35.6"
    },
    "rd_full_misses": {
      "count": 1,
      "units": "Requests",
      "percentage": "0.0"
    },
    "rd_partial_misses": {
      "count": 0,
      "units": "Requests",
      "percentage": "0.0"
    },
    "wr_total": {
      "count": 212416,
      "units": "Requests",
      "percentage": "99.2"
    },
    "wr_pt": {
      "count": 1535,
      "units": "Requests",
      "percentage": "0.7"
    },
    "wr_partial_misses": {
      "count": 0,
      "units": "Requests",
      "percentage": "0.0"
    },
    "serviced": {
      "count": 212418,
      "units": "Requests",
      "percentage": "99.2"
    },
    "rd_pt": {
      "count": 0,
      "units": "Requests",
      "percentage": "0.0"
    },
    "total": {
      "count": 213953,
      "units": "Requests",
      "percentage": "100.0"
    },
    "rd_hits": {
      "count": 1,
      "units": "Requests",
      "percentage": "0.0"
    },
    "wr_hits": {
      "count": 136136,
      "units": "Requests",
      "percentage": "63.6"
    }
  },
  "errors": {
    "total": {
      "count": 0,
      "units": "Requests",
      "percentage": "0.0"
    },
    "cache_obj_total": {
      "count": 0,
      "units": "Requests",
      "percentage": "0.0"
    },
    "core_obj_total": {
      "count": 0,
      "units": "Requests",
      "percentage": "0.0"
    },
    "cache_obj_rd": {
      "count": 0,
      "units": "Requests",
      "percentage": "0.0"
    },
    "core_obj_wr": {
      "count": 0,
      "units": "Requests",
      "percentage": "0.0"
    },
    "core_obj_rd": {
      "count": 0,
      "units": "Requests",
      "percentage": "0.0"
    },
    "cache_obj_wr": {
      "count": 0,
      "units": "Requests",
      "percentage": "0.0"
    }
  },
  "blocks": {
    "volume_rd": {
      "count": 9,
      "units": "4KiB blocks",
      "percentage": "0.0"
    },
    "volume_wr": {
      "count": 213951,
      "units": "4KiB blocks",
      "percentage": "99.9"
    },
    "cache_obj_total": {
      "count": 212425,
      "units": "4KiB blocks",
      "percentage": "100.0"
    },
    "core_obj_total": {
      "count": 213959,
      "units": "4KiB blocks",
      "percentage": "100.0"
    },
    "cache_obj_rd": {
      "count": 1,
      "units": "4KiB blocks",
      "percentage": "0.0"
    },
    "core_obj_wr": {
      "count": 213951,
      "units": "4KiB blocks",
      "percentage": "99.9"
    },
    "volume_total": {
      "count": 213960,
      "units": "4KiB blocks",
      "percentage": "100.0"
    },
    "core_obj_rd": {
      "count": 8,
      "units": "4KiB blocks",
      "percentage": "0.0"
    },
    "cache_obj_wr": {
      "count": 212424,
      "units": "4KiB blocks",
      "percentage": "99.9"
    }
  ]
}

get_ocf_bdevs

Get list of OCF devices including unregistered ones.

Parameters

Name	Optional	Type	Description
name	Optional	string	Name of OCF vbdev or name of cache device or name of core device

Response

Array of OCF devices with their current status, along with core and cache bdevs.

Example

Example request:

{
  "jsonrpc": "2.0",
  "method": "get_ocf_bdevs",
  "id": 1
}

Example response:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": [
    {
      "name": "PartCache",
      "started": false,
      "cache": {
        "name": "Malloc0",
        "attached": true
      },
      "core": {
        "name": "Malloc1",
        "attached": false
      }
    }
  ]
}

construct_malloc_bdev

Construct @ref bdev_config_malloc

Parameters

Name	Optional	Type	Description
name	Optional	string	Bdev name to use
block_size	Required	number	Block size in bytes -must be multiple of 512
num_blocks	Required	number	Number of blocks
uuid	Optional	string	UUID of new bdev

Result

Name of newly created bdev.

Example

Example request:

{
  "params": {
    "block_size": 4096,
    "num_blocks": 16384,
    "name": "Malloc0",
    "uuid": "2b6601ba-eada-44fb-9a83-a20eb9eb9e90"
  },
  "jsonrpc": "2.0",
  "method": "construct_malloc_bdev",
  "id": 1
}

Example response:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": "Malloc0"
}

delete_malloc_bdev

Delete @ref bdev_config_malloc

Parameters

Name	Optional	Type	Description
name	Required	string	Bdev name

Example

Example request:

{
  "params": {
    "name": "Malloc0"
  },
  "jsonrpc": "2.0",
  "method": "delete_malloc_bdev",
  "id": 1
}

Example response:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": true
}

construct_null_bdev

Construct @ref bdev_config_null

Parameters

Name	Optional	Type	Description
name	Optional	string	Bdev name to use
block_size	Required	number	Block size in bytes
num_blocks	Required	number	Number of blocks
uuid	Optional	string	UUID of new bdev

Result

Name of newly created bdev.

Example

Example request:

{
  "params": {
    "block_size": 4096,
    "num_blocks": 16384,
    "name": "Null0",
    "uuid": "2b6601ba-eada-44fb-9a83-a20eb9eb9e90"
  },
  "jsonrpc": "2.0",
  "method": "construct_null_bdev",
  "id": 1
}

Example response:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": "Null0"
}

delete_null_bdev

Delete @ref bdev_config_null.

Parameters

Name	Optional	Type	Description
name	Required	string	Bdev name

Example

Example request:

{
  "params": {
    "name": "Null0"
  },
  "jsonrpc": "2.0",
  "method": "delete_null_bdev",
  "id": 1
}

Example response:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": true
}

construct_aio_bdev

Construct @ref bdev_config_aio.

Parameters

Name	Optional	Type	Description
name	Required	string	Bdev name to use
filename	Required	number	Path to device or file
block_size	Optional	number	Block size in bytes

Result

Name of newly created bdev.

Example

Example request:

{
  "params": {
    "block_size": 4096,
    "name": "Aio0",
    "filename": "/tmp/aio_bdev_file"
  },
  "jsonrpc": "2.0",
  "method": "construct_aio_bdev",
  "id": 1
}

Example response:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": "Aio0"
}

delete_aio_bdev

Delete @ref bdev_config_aio.

Parameters

Name	Optional	Type	Description
name	Required	string	Bdev name

Example

Example request:

{
  "params": {
    "name": "Aio0"
  },
  "jsonrpc": "2.0",
  "method": "delete_aio_bdev",
  "id": 1
}

Example response:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": true
}

set_bdev_nvme_options

Set global parameters for all bdev NVMe. This RPC may only be called before SPDK subsystems have been initialized.

Parameters

Name	Optional	Type	Description
action_on_timeout	Optional	string	Action to take on command time out: none, reset or abort
timeout_us	Optional	number	Timeout for each command, in microseconds. If 0, don't track timeouts
retry_count	Optional	number	The number of attempts per I/O before an I/O fails
nvme_adminq_poll_period_us	Optional	number	How often the admin queue is polled for asynchronous events in microseconds
nvme_ioq_poll_period_us	Optional	number	How often I/O queues are polled for completions, in microseconds. Default: 0 (as fast as possible).

Example

Example request:

request:
{
  "params": {
    "retry_count": 5,
    "nvme_adminq_poll_period_us": 2000,
    "timeout_us": 10000000,
    "action_on_timeout": "reset"
  },
  "jsonrpc": "2.0",
  "method": "set_bdev_nvme_options",
  "id": 1
}

Example response:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": true
}

set_bdev_nvme_hotplug

Change settings of the NVMe hotplug feature. If enabled, PCIe NVMe bdevs will be automatically discovered on insertion and deleted on removal.

Parameters

Name	Optional	Type	Description
enabled	Required	string	True to enable, false to disable
period_us	Optional	number	How often to poll for hot-insert and hot-remove events. Values: 0 - reset/use default or 1 to 10000000.

Example

Example request:

request:
{
  "params": {
    "enabled": true,
    "period_us": 2000
  },
  "jsonrpc": "2.0",
  "method": "set_bdev_nvme_hotplug",
  "id": 1
}

Example response:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": true
}

construct_nvme_bdev

Construct @ref bdev_config_nvme

Result

Array of names of newly created bdevs.

Parameters

Name	Optional	Type	Description
name	Required	string	Name of the NVMe controller, prefix for each bdev name
trtype	Required	string	NVMe-oF target trtype: rdma or pcie
traddr	Required	string	NVMe-oF target address: ip or BDF
adrfam	Optional	string	NVMe-oF target adrfam: ipv4, ipv6, ib, fc, intra_host
trsvcid	Optional	string	NVMe-oF target trsvcid: port number
subnqn	Optional	string	NVMe-oF target subnqn
hostnqn	Optional	string	NVMe-oF target hostnqn
hostaddr	Optional	string	NVMe-oF host address: ip address
hostsvcid	Optional	string	NVMe-oF host trsvcid: port number
prchk_reftag	Optional	bool	Enable checking of PI reference tag for I/O processing
prchk_guard	Optional	bool	Enable checking of PI guard for I/O processing

Example

Example request:

{
  "params": {
    "trtype": "pcie",
    "name": "Nvme0",
    "traddr": "0000:0a:00.0"
  },
  "jsonrpc": "2.0",
  "method": "construct_nvme_bdev",
  "id": 1
}

Example response:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": [
    "Nvme0n1"
  ]
}

get_nvme_controllers

Get information about NVMe controllers.

Parameters

The user may specify no parameters in order to list all NVMe controllers, or one NVMe controller may be specified by name.

Name	Optional	Type	Description
name	Optional	string	NVMe controller name

Response

The response is an array of objects containing information about the requested NVMe controllers.

Example

Example request:

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "get_nvme_controllers",
  "params": {
    "name": "Nvme0"
  }
}

Example response:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": [
    {
      "name": "Nvme0",
      "trid": {
        "trtype": "PCIe",
        "traddr": "0000:05:00.0"
      }
    }
  ]
}

delete_nvme_controller

Delete NVMe controller.

Parameters

Name	Optional	Type	Description
name	Required	string	Controller name

Example

Example requests:

{
  "params": {
    "name": "Nvme0"
  },
  "jsonrpc": "2.0",
  "method": "delete_nvme_controller",
  "id": 1
}

Example response:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": true
}

construct_rbd_bdev

Construct @ref bdev_config_rbd bdev

This method is available only if SPDK was build with Ceph RBD support.

Parameters

Name	Optional	Type	Description
name	Optional	string	Bdev name
user_id	Optional	string	Ceph ID (i.e. admin, not client.admin)
pool_name	Required	string	Pool name
rbd_name	Required	string	Image name
block_size	Required	number	Block size
config	Optional	string map	Explicit librados configuration

If no config is specified, Ceph configuration files must exist with all relevant settings for accessing the pool. If a config map is passed, the configuration files are ignored and instead all key/value pairs are passed to rados_conf_set to configure cluster access. In practice, "mon_host" (= list of monitor address+port) and "key" (= the secret key stored in Ceph keyrings) are enough.

When accessing the image as some user other than "admin" (the default), the "user_id" has to be set.

Result

Name of newly created bdev.

Example

Example request with key from /etc/ceph/ceph.client.admin.keyring:

{
  "params": {
    "pool_name": "rbd",
    "rbd_name": "foo",
    "config": {
      "mon_host": "192.168.7.1:6789,192.168.7.2:6789",
      "key": "AQDwf8db7zR1GRAA5k7NKXjS5S5V4mntwUDnGQ==",
    }
    "block_size": 4096
  },
  "jsonrpc": "2.0",
  "method": "construct_rbd_bdev",
  "id": 1
}

Example response:

response:
{
  "jsonrpc": "2.0",
  "id": 1,
  "result": "Ceph0"
}

delete_rbd_bdev

Delete @ref bdev_config_rbd bdev

This method is available only if SPDK was build with Ceph RBD support.

Result

true if bdev with provided name was deleted or false otherwise.

Parameters

Name	Optional	Type	Description
name	Required	string	Bdev name

Example

Example request:

{
  "params": {
    "name": "Rbd0"
  },
  "jsonrpc": "2.0",
  "method": "delete_rbd_bdev",
  "id": 1
}

Example response:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": true
}

bdev_delay_create

Create delay bdev. This bdev type redirects all IO to it's base bdev and inserts a delay on the completion path to create an artificial drive latency.

Parameters

Name	Optional	Type	Description
name	Required	string	Bdev name
base_bdev_name	Required	string	Base bdev name
avg_read_latency	Required	number	average read latency (us)
p99_read_latency	Required	number	p99 read latency (us)
avg_write_latency	Required	number	average write latency (us)
p99_write_latency	Required	number	p99 write latency (us)

Result

Name of newly created bdev.

Example

Example request:

{
  "params": {
    "base_bdev_name": "Null0",
    "name": "Delay0",
    "avg_read_latency": "15",
    "p99_read_latency": "50",
    "avg_write_latency": "40",
    "p99_write_latency": "110",
  },
  "jsonrpc": "2.0",
  "method": "bdev_delay_create",
  "id": 1
}

Example response:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": "Delay0"
}

bdev_delay_delete

Delete delay bdev.

Parameters

Name	Optional	Type	Description
name	Required	string	Bdev name

Example

Example request:

{
  "params": {
    "name": "Delay0"
  },
  "jsonrpc": "2.0",
  "method": "bdev_delay_delete",
  "id": 1
}

Example response:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": true
}

construct_error_bdev

Construct error bdev.

Parameters

Name	Optional	Type	Description
base_name	Required	string	Base bdev name

Example

Example request:

{
  "params": {
    "base_name": "Malloc0"
  },
  "jsonrpc": "2.0",
  "method": "construct_error_bdev",
  "id": 1
}

Example response:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": true
}

delete_error_bdev

Delete error bdev

Result

true if bdev with provided name was deleted or false otherwise.

Parameters

Name	Optional	Type	Description
name	Required	string	Error bdev name

Example

Example request:

{
  "params": {
    "name": "EE_Malloc0"
  },
  "jsonrpc": "2.0",
  "method": "delete_error_bdev",
  "id": 1
}

Example response:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": true
}

construct_iscsi_bdev

Connect to iSCSI target and create bdev backed by this connection.

This method is available only if SPDK was build with iSCSI initiator support.

Parameters

Name	Optional	Type	Description
name	Required	string	Bdev name
initiator_iqn	Required	string	IQN name used during connection
url	Required	string	iSCSI resource URI

Result

Name of newly created bdev.

Example

Example request:

{
  "params": {
    "url": "iscsi://127.0.0.1/iqn.2016-06.io.spdk:disk1/0",
    "initiator_iqn": "iqn.2016-06.io.spdk:init",
    "name": "iSCSI0"
  },
  "jsonrpc": "2.0",
  "method": "construct_iscsi_bdev",
  "id": 1
}

Example response:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": "iSCSI0"
}

delete_iscsi_bdev

Delete iSCSI bdev and terminate connection to target.

This method is available only if SPDK was built with iSCSI initiator support.

Parameters

Name	Optional	Type	Description
name	Required	string	Bdev name

Example

Example request:

{
  "params": {
    "name": "iSCSI0"
  },
  "jsonrpc": "2.0",
  "method": "delete_iscsi_bdev",
  "id": 1
}

Example response:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": true
}

construct_ftl_bdev

Create FTL bdev.

This RPC is subject to change.

Parameters

Name	Optional	Type	Description
name	Required	string	Bdev name
trtype	Required	string	Transport type
traddr	Required	string	NVMe target address
punits	Required	string	Parallel unit range in the form of start-end e.g 4-8
uuid	Optional	string	UUID of restored bdev (not applicable when creating new instance)
cache	Optional	string	Name of the bdev to be used as a write buffer cache

Result

Name of newly created bdev.

Example

Example request:

{
  "params": {
    "name": "nvme0"
    "trtype" "pcie"
    "traddr": "0000:00:04.0"
    "punits": "0-3"
    "uuid": "4a7481ce-786f-41a0-9b86-8f7465c8f4d3"
  },
  "jsonrpc": "2.0",
  "method": "construct_ftl_bdev",
  "id": 1
}

Example response:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
      "name" : "nvme0"
      "uuid" : "4a7481ce-786f-41a0-9b86-8f7465c8f4d3"
  }
}

delete_ftl_bdev

Delete FTL bdev.

This RPC is subject to change.

Parameters

Name	Optional	Type	Description
name	Required	string	Bdev name

Example

Example request:

{
  "params": {
    "name": "nvme0"
  },
  "jsonrpc": "2.0",
  "method": "delete_ftl_bdev",
  "id": 1
}

Example response:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": true
}

create_pmem_pool

Create a @ref bdev_config_pmem blk pool file. It is equivalent of following pmempool create command:

pmempool create -s $((num_blocks * block_size)) blk $block_size $pmem_file

This method is available only if SPDK was built with PMDK support.

Parameters

Name	Optional	Type	Description
pmem_file	Required	string	Path to new pmem file
num_blocks	Required	number	Number of blocks
block_size	Required	number	Size of each block in bytes

Example

Example request:

{
  "params": {
    "block_size": 512,
    "num_blocks": 131072,
    "pmem_file": "/tmp/pmem_file"
  },
  "jsonrpc": "2.0",
  "method": "create_pmem_pool",
  "id": 1
}

Example response:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": true
}

pmem_pool_info

Retrieve basic information about PMDK memory pool.

This method is available only if SPDK was built with PMDK support.

Parameters

Name	Optional	Type	Description
pmem_file	Required	string	Path to existing pmem file

Result

Array of objects describing memory pool:

Name	Type	Description
num_blocks	number	Number of blocks
block_size	number	Size of each block in bytes

Example

Example request:

request:
{
  "params": {
    "pmem_file": "/tmp/pmem_file"
  },
  "jsonrpc": "2.0",
  "method": "pmem_pool_info",
  "id": 1
}

Example response:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": [
    {
      "block_size": 512,
      "num_blocks": 129728
    }
  ]
}

delete_pmem_pool

Delete pmem pool by removing file pmem_file. This method will fail if pmem_file is not a valid pmem pool file.

This method is available only if SPDK was built with PMDK support.

Parameters

Name	Optional	Type	Description
pmem_file	Required	string	Path to new pmem file

Example

Example request:

{
  "params": {
    "pmem_file": "/tmp/pmem_file"
  },
  "jsonrpc": "2.0",
  "method": "delete_pmem_pool",
  "id": 1
}

Example response:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": true
}

construct_pmem_bdev

Construct @ref bdev_config_pmem bdev.

This method is available only if SPDK was built with PMDK support.

Parameters

Name	Optional	Type	Description
name	Required	string	Bdev name
pmem_file	Required	string	Path to existing pmem blk pool file

Result

Name of newly created bdev.

Example

Example request:

{
  "params": {
    "pmem_file": "/tmp/pmem_file",
    "name": "Pmem0"
  },
  "jsonrpc": "2.0",
  "method": "construct_pmem_bdev",
  "id": 1
}

Example response:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": "Pmem0"
}

delete_pmem_bdev

Delete @ref bdev_config_pmem bdev. This call will not remove backing pool files.

This method is available only if SPDK was built with PMDK support.

Result

true if bdev with provided name was deleted or false otherwise.

Parameters

Name	Optional	Type	Description
name	Required	string	Bdev name

Example

Example request:

{
  "params": {
    "name": "Pmem0"
  },
  "jsonrpc": "2.0",
  "method": "delete_pmem_bdev",
  "id": 1
}

Example response:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": true
}

construct_passthru_bdev

Create passthru bdev. This bdev type redirects all IO to it's base bdev. It has no other purpose than being an example and a starting point in development of new bdev type.

Parameters

Name	Optional	Type	Description
name	Required	string	Bdev name
base_bdev_name	Required	string	Base bdev name

Result

Name of newly created bdev.

Example

Example request:

{
  "params": {
    "base_bdev_name": "Malloc0",
    "name": "Passsthru0"
  },
  "jsonrpc": "2.0",
  "method": "construct_passthru_bdev",
  "id": 1
}

Example response:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": "Passsthru0"
}

delete_passthru_bdev

Delete passthru bdev.

Parameters

Name	Optional	Type	Description
name	Required	string	Bdev name

Example

Example request:

{
  "params": {
    "name": "Passsthru0"
  },
  "jsonrpc": "2.0",
  "method": "delete_passthru_bdev",
  "id": 1
}

Example response:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": true
}

construct_virtio_dev

Create new initiator @ref bdev_config_virtio_scsi or @ref bdev_config_virtio_blk and expose all found bdevs.

Parameters

Name	Optional	Type	Description
name	Required	string	Virtio SCSI base bdev name or Virtio Blk bdev name
trtype	Required	string	Virtio target trtype: pci or user
traddr	Required	string	target address: BDF or UNIX socket file path
dev_type	Required	string	Virtio device type: blk or scsi
vq_count	Optional	number	Number of queues this controller will utilize (default: 1)
vq_size	Optional	number	Size of each queue. Must be power of 2. (default: 512)

In case of Virtio SCSI the name parameter will be base name for new created bdevs. For Virtio Blk name will be the name of created bdev.

vq_count and vq_size parameters are valid only if trtype is user.

Result

Array of names of newly created bdevs.

Example

Example request:

{
  "params": {
    "name": "VirtioScsi0",
    "trtype": "user",
    "vq_size": 128,
    "dev_type": "scsi",
    "traddr": "/tmp/VhostScsi0",
    "vq_count": 4
  },
  "jsonrpc": "2.0",
  "method": "construct_virtio_dev",
  "id": 1
}

Example response:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": ["VirtioScsi0t2", "VirtioScsi0t4"]
}

get_virtio_scsi_devs

Show information about all available Virtio SCSI devices.

Parameters

This method has no parameters.

Result

Array of Virtio SCSI information objects.

Example

Example request:

{
  "jsonrpc": "2.0",
  "method": "get_virtio_scsi_devs",
  "id": 1
}

Example response:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": [
    {
      "name": "VirtioScsi0",
      "virtio": {
          "vq_size": 128,
          "vq_count": 4,
          "type": "user",
          "socket": "/tmp/VhostScsi0"
      }
    }
  ]
}

remove_virtio_bdev

Remove a Virtio device. This command can be used to remove any type of virtio device.

Parameters

Name	Optional	Type	Description
name	Required	string	Virtio name

Example

Example request:

{
  "params": {
    "name": "VirtioUser0"
  },
  "jsonrpc": "2.0",
  "method": "remove_virtio_bdev",
  "id": 1
}

Example response:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": true
}

iSCSI Target

set_iscsi_options method

Set global parameters for iSCSI targets.

This RPC may only be called before SPDK subsystems have been initialized. This RPC can be called only once.

Parameters

Name	Optional	Type	Description
auth_file	Optional	string	Path to CHAP shared secret file (default: "")
node_base	Optional	string	Prefix of the name of iSCSI target node (default: "iqn.2016-06.io.spdk")
nop_timeout	Optional	number	Timeout in seconds to nop-in request to the initiator (default: 60)
nop_in_interval	Optional	number	Time interval in secs between nop-in requests by the target (default: 30)
disable_chap	Optional	boolean	CHAP for discovery session should be disabled (default: false)
require_chap	Optional	boolean	CHAP for discovery session should be required (default: false)
mutual_chap	Optional	boolean	CHAP for discovery session should be unidirectional (false) or bidirectional (true) (default: false)
chap_group	Optional	number	CHAP group ID for discovery session (default: 0)
max_sessions	Optional	number	Maximum number of sessions in the host (default: 128)
max_queue_depth	Optional	number	Maximum number of outstanding I/Os per queue (default: 64)
max_connections_per_session	Optional	number	Session specific parameter, MaxConnections (default: 2)
default_time2wait	Optional	number	Session specific parameter, DefaultTime2Wait (default: 2)
default_time2retain	Optional	number	Session specific parameter, DefaultTime2Retain (default: 20)
first_burst_length	Optional	number	Session specific parameter, FirstBurstLength (default: 8192)
immediate_data	Optional	boolean	Session specific parameter, ImmediateData (default: true)
error_recovery_level	Optional	number	Session specific parameter, ErrorRecoveryLevel (default: 0)
allow_duplicated_isid	Optional	boolean	Allow duplicated initiator session ID (default: false)

To load CHAP shared secret file, its path is required to specify explicitly in the parameter auth_file.

Parameters disable_chap and require_chap are mutually exclusive. Parameters no_discovery_auth, req_discovery_auth, req_discovery_auth_mutual, and discovery_auth_group are still available instead of disable_chap, require_chap, mutual_chap, and chap_group, respectivey but will be removed in future releases.

Example

Example request:

{
  "params": {
    "allow_duplicated_isid": true,
    "default_time2retain": 60,
    "first_burst_length": 8192,
    "immediate_data": true,
    "node_base": "iqn.2016-06.io.spdk",
    "max_sessions": 128,
    "nop_timeout": 30,
    "nop_in_interval": 30,
    "auth_file": "/usr/local/etc/spdk/auth.conf",
    "disable_chap": true,
    "default_time2wait": 2
  },
  "jsonrpc": "2.0",
  "method": "set_iscsi_options",
  "id": 1
}

Example response:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": true
}

get_iscsi_global_params method

Show global parameters of iSCSI targets.

Parameters

This method has no parameters.

Example

Example request:

request:
{
  "jsonrpc": "2.0",
  "method": "get_iscsi_global_params",
  "id": 1
}

Example response:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "allow_duplicated_isid": true,
    "default_time2retain": 60,
    "first_burst_length": 8192,
    "immediate_data": true,
    "node_base": "iqn.2016-06.io.spdk",
    "mutual_chap": false,
    "nop_in_interval": 30,
    "chap_group": 0,
    "max_connections_per_session": 2,
    "max_queue_depth": 64,
    "nop_timeout": 30,
    "max_sessions": 128,
    "error_recovery_level": 0,
    "auth_file": "/usr/local/etc/spdk/auth.conf",
    "disable_chap": true,
    "default_time2wait": 2,
    "require_chap": false
  }
}

set_iscsi_discovery_auth method

Set CHAP authentication for sessions dynamically.

Parameters

Name	Optional	Type	Description
disable_chap	Optional	boolean	CHAP for discovery session should be disabled (default: false)
require_chap	Optional	boolean	CHAP for discovery session should be required (default: false)
mutual_chap	Optional	boolean	CHAP for discovery session should be unidirectional (false) or bidirectional (true) (default: false)
chap_group	Optional	number	CHAP group ID for discovery session (default: 0)

Parameters disable_chap and require_chap are mutually exclusive.

Example

Example request:

request:
{
  "params": {
    "chap_group": 1,
    "require_chap": true,
    "mutual_chap": true
  },
  "jsonrpc": "2.0",
  "method": "set_iscsi_discovery_auth",
  "id": 1
}

Example response:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": true
}

add_iscsi_auth_group method

Add an authentication group for CHAP authentication.

Parameters

Name	Optional	Type	Description
tag	Required	number	Authentication group tag (unique, integer > 0)
secrets	Optional	array	Array of @ref rpc_add_iscsi_auth_group_secret objects

secret

Name	Optional	Type	Description
user	Required	string	Unidirectional CHAP name
secret	Required	string	Unidirectional CHAP secret
muser	Optional	string	Bidirectional CHAP name
msecret	Optional	string	Bidirectional CHAP secret

Example

Example request:

{
  "params": {
    "secrets": [
      {
        "muser": "mu1",
        "secret": "s1",
        "user": "u1",
        "msecret": "ms1"
      }
    ],
    "tag": 2
  },
  "jsonrpc": "2.0",
  "method": "add_iscsi_auth_group",
  "id": 1
}

Example response:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": true
}

delete_iscsi_auth_group method

Delete an existing authentication group for CHAP authentication.

Parameters

Name	Optional	Type	Description
tag	Required	number	Authentication group tag (unique, integer > 0)

Example

Example request:

{
  "params": {
    "tag": 2
  },
  "jsonrpc": "2.0",
  "method": "delete_iscsi_auth_group",
  "id": 1
}

Example response:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": true
}

get_iscsi_auth_groups

Show information about all existing authentication group for CHAP authentication.

Parameters

This method has no parameters.

Result

Array of objects describing authentication group.

Name	Type	Description
tag	number	Authentication group tag
secrets	array	Array of @ref rpc_add_iscsi_auth_group_secret objects

Example

Example request:

{
  "jsonrpc": "2.0",
  "method": "get_iscsi_auth_groups",
  "id": 1
}

Example response:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": [
    {
      "secrets": [
        {
          "muser": "mu1",
          "secret": "s1",
          "user": "u1",
          "msecret": "ms1"
        }
      ],
      "tag": 1
    },
    {
      "secrets": [
        {
          "secret": "s2",
          "user": "u2"
        }
      ],
      "tag": 2
    }
  ]
}

add_secret_to_iscsi_auth_group

Add a secret to an existing authentication group for CHAP authentication.

Parameters

Name	Optional	Type	Description
tag	Required	number	Authentication group tag (unique, integer > 0)
user	Required	string	Unidirectional CHAP name
secret	Required	string	Unidirectional CHAP secret
muser	Optional	string	Bidirectional CHAP name
msecret	Optional	string	Bidirectional CHAP secret

Example

Example request:

{
  "params": {
    "muser": "mu3",
    "secret": "s3",
    "tag": 2,
    "user": "u3",
    "msecret": "ms3"
  },
  "jsonrpc": "2.0",
  "method": "add_secret_to_iscsi_auth_group",
  "id": 1
}

Example response:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": true
}

delete_secret_from_iscsi_auth_group

Delete a secret from an existing authentication group for CHAP authentication.

Parameters

Name	Optional	Type	Description
tag	Required	number	Authentication group tag (unique, integer > 0)
user	Required	string	Unidirectional CHAP name

Example

Example request:

{
  "params": {
    "tag": 2,
    "user": "u3"
  },
  "jsonrpc": "2.0",
  "method": "delete_secret_from_iscsi_auth_group",
  "id": 1
}

Example response:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": true
}

get_initiator_groups method

Show information about all available initiator groups.

Parameters

This method has no parameters.

Result

Array of objects describing initiator groups.

Name	Type	Description
tag	number	Initiator group tag
initiators	array	Array of initiator hostnames or IP addresses
netmasks	array	Array of initiator netmasks

Example

Example request:

{
  "jsonrpc": "2.0",
  "method": "get_initiator_groups",
  "id": 1
}

Example response:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": [
    {
      "initiators": [
        "iqn.2016-06.io.spdk:host1",
        "iqn.2016-06.io.spdk:host2"
      ],
      "tag": 1,
      "netmasks": [
        "192.168.1.0/24"
      ]
    }
  ]
}

add_initiator_group method

Add an initiator group.

Parameters

Name	Optional	Type	Description
tag	Required	number	Initiator group tag (unique, integer > 0)
initiators	Required	array	Not empty array of initiator hostnames or IP addresses
netmasks	Required	array	Not empty array of initiator netmasks

Example

Example request:

{
  "params": {
    "initiators": [
      "iqn.2016-06.io.spdk:host1",
      "iqn.2016-06.io.spdk:host2"
    ],
    "tag": 1,
    "netmasks": [
      "192.168.1.0/24"
    ]
  },
  "jsonrpc": "2.0",
  "method": "add_initiator_group",
  "id": 1
}

Example response:

response:
{
  "jsonrpc": "2.0",
  "id": 1,
  "result": true
}

delete_initiator_group method

Delete an existing initiator group.

Parameters

Name	Optional	Type	Description
tag	Required	number	Initiator group tag (unique, integer > 0)

Example

Example request:

{
  "params": {
    "tag": 1
  },
  "jsonrpc": "2.0",
  "method": "delete_initiator_group",
  "id": 1
}

Example response:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": true
}

add_initiators_to_initiator_group method

Add initiators to an existing initiator group.

Parameters

Name	Optional	Type	Description
tag	Required	number	Existing initiator group tag.
initiators	Optional	array	Array of initiator hostnames or IP addresses
netmasks	Optional	array	Array of initiator netmasks

Example

Example request:

request:
{
  "params": {
    "initiators": [
      "iqn.2016-06.io.spdk:host3"
    ],
    "tag": 1,
    "netmasks": [
      "255.255.255.1"
    ]
  },
  "jsonrpc": "2.0",
  "method": "add_initiators_to_initiator_group",
  "id": 1
}

Example response:

response:
{
  "jsonrpc": "2.0",
  "id": 1,
  "result": true
}

get_target_nodes method

Show information about all available iSCSI target nodes.

Parameters

This method has no parameters.

Result

Array of objects describing target node.

Name	Type	Description
name	string	Target node name (ASCII)
alias_name	string	Target node alias name (ASCII)
pg_ig_maps	array	Array of Portal_Group_Tag:Initiator_Group_Tag mappings
luns	array	Array of Bdev names to LUN ID mappings
queue_depth	number	Target queue depth
disable_chap	boolean	CHAP authentication should be disabled for this target
require_chap	boolean	CHAP authentication should be required for this target
mutual_chap	boolean	CHAP authentication should be bidirectional (true) or unidirectional (false)
chap_group	number	Authentication group ID for this target node
header_digest	boolean	Header Digest should be required for this target node
data_digest	boolean	Data Digest should be required for this target node

Example

Example request:

{
  "jsonrpc": "2.0",
  "method": "get_target_nodes",
  "id": 1
}

Example response:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": [
    {
      "luns": [
        {
          "lun_id": 0,
          "bdev_name": "Nvme0n1"
        }
      ],
      "mutual_chap": false,
      "name": "iqn.2016-06.io.spdk:target1",
      "alias_name": "iscsi-target1-alias",
      "require_chap": false,
      "chap_group": 0,
      "pg_ig_maps": [
        {
          "ig_tag": 1,
          "pg_tag": 1
        }
      ],
      "data_digest": false,
      "disable_chap": false,
      "header_digest": false,
      "queue_depth": 64
    }
  ]
}

construct_target_node method

Add a iSCSI target node.

Parameters

Name	Optional	Type	Description
name	Required	string	Target node name (ASCII)
alias_name	Required	string	Target node alias name (ASCII)
pg_ig_maps	Required	array	Array of (Portal_Group_Tag:Initiator_Group_Tag) mappings
luns	Required	array	Array of Bdev names to LUN ID mappings
queue_depth	Required	number	Target queue depth
disable_chap	Optional	boolean	CHAP authentication should be disabled for this target
require_chap	Optional	boolean	CHAP authentication should be required for this target
mutual_chap	Optional	boolean	CHAP authentication should be bidirectional (true) or unidirectional (false)
chap_group	Optional	number	Authentication group ID for this target node
header_digest	Optional	boolean	Header Digest should be required for this target node
data_digest	Optional	boolean	Data Digest should be required for this target node

Parameters disable_chap and require_chap are mutually exclusive.

Example

Example request:

{
  "params": {
    "luns": [
      {
        "lun_id": 0,
        "bdev_name": "Nvme0n1"
      }
    ],
    "mutual_chap": true,
    "name": "target2",
    "alias_name": "iscsi-target2-alias",
    "pg_ig_maps": [
      {
        "ig_tag": 1,
        "pg_tag": 1
      },
      {
        "ig_tag": 2,
        "pg_tag": 2
      }
    ],
    "data_digest": true,
    "disable_chap": true,
    "header_digest": true,
    "queue_depth": 24
  },
  "jsonrpc": "2.0",
  "method": "construct_target_node",
  "id": 1
}

Example response:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": true
}

set_iscsi_target_node_auth method

Set CHAP authentication to an existing iSCSI target node.

Parameters

Name	Optional	Type	Description
name	Required	string	Target node name (ASCII)
disable_chap	Optional	boolean	CHAP authentication should be disabled for this target
require_chap	Optional	boolean	CHAP authentication should be required for this target
mutual_chap	Optional	boolean	CHAP authentication should be bidirectional (true) or unidirectional (false)
chap_group	Optional	number	Authentication group ID for this target node

Parameters disable_chap and require_chap are mutually exclusive.

Example

Example request:

{
  "params": {
    "chap_group": 1,
    "require_chap": true,
    "name": "iqn.2016-06.io.spdk:target1",
    "mutual_chap": true
  },
  "jsonrpc": "2.0",
  "method": "set_iscsi_target_node_auth",
  "id": 1
}

Example response:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": true
}

add_pg_ig_maps method

Add initiator group to portal group mappings to an existing iSCSI target node.

Parameters

Name	Optional	Type	Description
name	Required	string	Target node name (ASCII)
pg_ig_maps	Required	array	Not empty array of initiator to portal group mappings objects

Portal to Initiator group mappings object:

Name	Optional	Type	Description
ig_tag	Required	number	Existing initiator group tag
pg_tag	Required	number	Existing portal group tag

Example

Example request:

{
  "params": {
    "pg_ig_maps": [
      {
        "ig_tag": 1,
        "pg_tag": 1
      },
      {
        "ig_tag": 2,
        "pg_tag": 2
      },
      {
        "ig_tag": 3,
        "pg_tag": 3
      }
    ],
    "name": "iqn.2016-06.io.spdk:target3"
  },
  "jsonrpc": "2.0",
  "method": "add_pg_ig_maps",
  "id": 1
}

Example response:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": true
}

delete_pg_ig_maps method

Delete initiator group to portal group mappings from an existing iSCSI target node.

Parameters

Name	Optional	Type	Description
name	Required	string	Target node name (ASCII)
pg_ig_maps	Required	array	Not empty array of Portal to Initiator group mappings objects

Portal to Initiator group mappings object:

Name	Optional	Type	Description
ig_tag	Required	number	Existing initiator group tag
pg_tag	Required	number	Existing portal group tag

Example

Example request:

{
  "params": {
    "pg_ig_maps": [
      {
        "ig_tag": 1,
        "pg_tag": 1
      },
      {
        "ig_tag": 2,
        "pg_tag": 2
      },
      {
        "ig_tag": 3,
        "pg_tag": 3
      }
    ],
    "name": "iqn.2016-06.io.spdk:target3"
  },
  "jsonrpc": "2.0",
  "method": "delete_pg_ig_maps",
  "id": 1
}

Example response:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": true
}

delete_target_node method

Delete a iSCSI target node.

Parameters

Name	Optional	Type	Description
name	Required	string	Target node name (ASCII)

Example

Example request:

{
  "params": {
    "name": "iqn.2016-06.io.spdk:target1"
  },
  "jsonrpc": "2.0",
  "method": "delete_target_node",
  "id": 1
}

Example response:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": true
}

get_portal_groups method

Show information about all available portal groups.

Parameters

This method has no parameters.

Example

Example request:

request:
{
  "jsonrpc": "2.0",
  "method": "get_portal_groups",
  "id": 1
}

Example response:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": [
    {
      "portals": [
        {
          "cpumask": "0x2",
          "host": "127.0.0.1",
          "port": "3260"
        }
      ],
      "tag": 1
    }
  ]
}

add_portal_group method

Add a portal group.

Parameters

Name	Optional	Type	Description
tag	Required	number	Portal group tag
portals	Required	array	Not empty array of portals

Portal object

Name	Optional	Type	Description
host	Required	string	Hostname or IP address
port	Required	string	Port number

Example

Example request:

{
  "params": {
    "portals": [
      {
        "host": "127.0.0.1",
        "port": "3260"
      }
    ],
    "tag": 1
  },
  "jsonrpc": "2.0",
  "method": "add_portal_group",
  "id": 1
}

Example response:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": true
}

delete_portal_group method

Delete an existing portal group.

Parameters

Name	Optional	Type	Description
tag	Required	number	Existing portal group tag

Example

Example request:

{
  "params": {
    "tag": 1
  },
  "jsonrpc": "2.0",
  "method": "delete_portal_group",
  "id": 1
}

Example response:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": true
}

get_iscsi_connections method

Show information about all active connections.

Parameters

This method has no parameters.

Results

Array of objects describing iSCSI connection.

Name	Type	Description
id	number	Index (used for TTT - Target Transfer Tag)
cid	number	CID (Connection ID)
tsih	number	TSIH (Target Session Identifying Handle)
lcore_id	number	Core number on which the iSCSI connection runs
initiator_addr	string	Initiator address
target_addr	string	Target address
target_node_name	string	Target node name (ASCII) without prefix

Example

Example request:

{
  "jsonrpc": "2.0",
  "method": "get_iscsi_connections",
  "id": 1
}

Example response:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": [
    {
      "tsih": 4,
      "cid": 0,
      "target_node_name": "target1",
      "lcore_id": 0,
      "initiator_addr": "10.0.0.2",
      "target_addr": "10.0.0.1",
      "id": 0
    }
  ]
}

target_node_add_lun method

Add an LUN to an existing iSCSI target node.

Parameters

Name	Optional	Type	Description
name	Required	string	Target node name (ASCII)
bdev_name	Required	string	bdev name to be added as a LUN
lun_id	Optional	number	LUN ID (default: first free ID)

Example

Example request:

{
  "params": {
    "lun_id": 2,
    "name": "iqn.2016-06.io.spdk:target1",
    "bdev_name": "Malloc0"
  },
  "jsonrpc": "2.0",
  "method": "target_node_add_lun",
  "id": 1
}

Example response:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": true
}

NVMe-oF Target

nvmf_create_transport method

Initialize an NVMe-oF transport with the given options.

Parameters

Name	Optional	Type	Description
trtype	Required	string	Transport type (ex. RDMA)
max_queue_depth	Optional	number	Max number of outstanding I/O per queue
max_qpairs_per_ctrlr	Optional	number	Max number of SQ and CQ per controller
in_capsule_data_size	Optional	number	Max number of in-capsule data size
max_io_size	Optional	number	Max I/O size (bytes)
io_unit_size	Optional	number	I/O unit size (bytes)
max_aq_depth	Optional	number	Max number of admin cmds per AQ
num_shared_buffers	Optional	number	The number of pooled data buffers available to the transport
buf_cache_size	Optional	number	The number of shared buffers to reserve for each poll group
max_srq_depth	Optional	number	The number of elements in a per-thread shared receive queue (RDMA only)
no_srq	Optional	boolean	Disable shared receive queue even for devices that support it. (RDMA only)

Example:

Example request:

{
  "jsonrpc": "2.0",
  "method": "nvmf_create_transport",
  "id": 1,
  "params": {
    "trtype": "RDMA",
    "max_queue_depth": 32
  }
}

Example response:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": true
}

get_nvmf_subsystems method

Parameters

This method has no parameters.

Example

Example request:

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "get_nvmf_subsystems"
}

Example response:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": [
    {
      "nqn": "nqn.2014-08.org.nvmexpress.discovery",
      "subtype": "Discovery"
      "listen_addresses": [],
      "hosts": [],
      "allow_any_host": true
    },
    {
      "nqn": "nqn.2016-06.io.spdk:cnode1",
      "subtype": "NVMe",
      "listen_addresses": [
        {
          "trtype": "RDMA",
          "adrfam": "IPv4",
          "traddr": "192.168.0.123",
          "trsvcid": "4420"
        }
      ],
      "hosts": [
        {"nqn": "nqn.2016-06.io.spdk:host1"}
      ],
      "allow_any_host": false,
      "serial_number": "abcdef",
      "model_number": "ghijklmnop",
      "namespaces": [
        {"nsid": 1, "name": "Malloc2"},
        {"nsid": 2, "name": "Nvme0n1"}
      ]
    }
  ]
}

nvmf_subsystem_create method

Construct an NVMe over Fabrics target subsystem.

Parameters

Name	Optional	Type	Description
nqn	Required	string	Subsystem NQN
serial_number	Optional	string	Serial number of virtual controller
model_number	Optional	string	Model number of virtual controller
max_namespaces	Optional	number	Maximum number of namespaces that can be attached to the subsystem. Default: 0 (Unlimited)
allow_any_host	Optional	boolean	Allow any host (true) or enforce allowed host whitelist (false). Default: false.

Example

Example request:

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "nvmf_subsystem_create",
  "params": {
    "nqn": "nqn.2016-06.io.spdk:cnode1",
    "allow_any_host": false,
    "serial_number": "abcdef",
    "model_number": "ghijklmnop"
  }
}

Example response:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": true
}

delete_nvmf_subsystem method

Delete an existing NVMe-oF subsystem.

Parameters

Parameter	Optional	Type	Description
nqn	Required	string	Subsystem NQN to delete.

Example

Example request:

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "delete_nvmf_subsystem",
  "params": {
    "nqn": "nqn.2016-06.io.spdk:cnode1"
  }
}

Example response:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": true
}

nvmf_subsystem_add_listener method

Add a new listen address to an NVMe-oF subsystem.

Parameters

Name	Optional	Type	Description
nqn	Required	string	Subsystem NQN
listen_address	Required	object	@ref rpc_nvmf_listen_address object

listen_address

Name	Optional	Type	Description
trtype	Required	string	Transport type ("RDMA")
adrfam	Required	string	Address family ("IPv4", "IPv6", "IB", or "FC")
traddr	Required	string	Transport address
trsvcid	Required	string	Transport service ID

Example

Example request:

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "nvmf_subsystem_add_listener",
  "params": {
    "nqn": "nqn.2016-06.io.spdk:cnode1",
    "listen_address": {
      "trtype": "RDMA",
      "adrfam": "IPv4",
      "traddr": "192.168.0.123",
      "trsvcid: "4420"
    }
  }
}

Example response:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": true
}

nvmf_subsystem_add_ns method

Add a namespace to a subsystem. The namespace ID is returned as the result.

Parameters

Name	Optional	Type	Description
nqn	Required	string	Subsystem NQN
namespace	Required	object	@ref rpc_nvmf_namespace object

namespace

Name	Optional	Type	Description
nsid	Optional	number	Namespace ID between 1 and 4294967294, inclusive. Default: Automatically assign NSID.
bdev_name	Required	string	Name of bdev to expose as a namespace.
nguid	Optional	string	16-byte namespace globally unique identifier in hexadecimal (e.g. "ABCDEF0123456789ABCDEF0123456789")
eui64	Optional	string	8-byte namespace EUI-64 in hexadecimal (e.g. "ABCDEF0123456789")
uuid	Optional	string	RFC 4122 UUID (e.g. "ceccf520-691e-4b46-9546-34af789907c5")

Example

Example request:

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "nvmf_subsystem_add_ns",
  "params": {
    "nqn": "nqn.2016-06.io.spdk:cnode1",
    "namespace": {
      "nsid": 3,
      "bdev_name": "Nvme0n1"
    }
  }
}

Example response:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": 3
}

nvmf_subsystem_remove_ns method

Remove a namespace from a subsystem.

Parameters

Name	Optional	Type	Description
nqn	Required	string	Subsystem NQN
nsid	Required	number	Namespace ID

Example

Example request:

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "nvmf_subsystem_remove_ns",
  "params": {
    "nqn": "nqn.2016-06.io.spdk:cnode1",
    "nsid": 1
  }
}

Example response:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": true
}

nvmf_subsystem_add_host method

Add a host NQN to the whitelist of allowed hosts.

Parameters

Name	Optional	Type	Description
nqn	Required	string	Subsystem NQN
host	Required	string	Host NQN to add to the list of allowed host NQNs

Example

Example request:

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "nvmf_subsystem_add_host",
  "params": {
    "nqn": "nqn.2016-06.io.spdk:cnode1",
    "host": "nqn.2016-06.io.spdk:host1"
  }
}

Example response:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": true
}

nvmf_subsystem_remove_host method

Remove a host NQN from the whitelist of allowed hosts.

Parameters

Name	Optional	Type	Description
nqn	Required	string	Subsystem NQN
host	Required	string	Host NQN to remove from the list of allowed host NQNs

Example

Example request:

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "nvmf_subsystem_remove_host",
  "params": {
    "nqn": "nqn.2016-06.io.spdk:cnode1",
    "host": "nqn.2016-06.io.spdk:host1"
  }
}

Example response:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": true
}

nvmf_subsystem_allow_any_host method

Configure a subsystem to allow any host to connect or to enforce the host NQN whitelist.

Parameters

Name	Optional	Type	Description
nqn	Required	string	Subsystem NQN
allow_any_host	Required	boolean	Allow any host (true) or enforce allowed host whitelist (false).

Example

Example request:

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "nvmf_subsystem_allow_any_host",
  "params": {
    "nqn": "nqn.2016-06.io.spdk:cnode1",
    "allow_any_host": true
  }
}

Example response:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": true
}

set_nvmf_target_max_subsystems

Set the maximum allowed subsystems for the NVMe-oF target. This RPC may only be called before SPDK subsystems have been initialized.

Parameters

Name	Optional	Type	Description
max_subsystems	Required	number	Maximum number of NVMe-oF subsystems

Example

Example request:

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "set_nvmf_target_max_subsystems",
  "params": {
    "max_subsystems": 1024
  }
}

Example response:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": true
}

set_nvmf_target_config

Set global configuration of NVMe-oF target. This RPC may only be called before SPDK subsystems have been initialized.

Parameters

Name	Optional	Type	Description
acceptor_poll_rate	Optional	number	Polling interval of the acceptor for incoming connections (microseconds)

Example

Example request:

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "set_nvmf_target_config",
  "params": {
    "acceptor_poll_rate": 10000
  }
}

Example response:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": true
}

get_nvmf_transports method

Parameters

This method has no parameters.

Example

Example request:

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "get_nvmf_transports"
}

Example response:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": [
    {
      "type": "RDMA".
      "max_queue_depth": 128,
      "max_qpairs_per_ctrlr": 64,
      "in_capsule_data_size": 4096,
      "max_io_size": 131072,
      "io_unit_size": 131072
    }
  ]
}

Vhost Target

The following common preconditions need to be met in all target types.

Controller name will be used to create UNIX domain socket. This implies that name concatenated with vhost socket directory path needs to be valid UNIX socket name.

@ref cpu_mask parameter is used to choose CPU on which pollers will be launched when new initiator is connecting. It must be a subset of application CPU mask. Default value is CPU mask of the application.

set_vhost_controller_coalescing

Controls interrupt coalescing for specific target. Because delay_base_us is used to calculate delay in CPU ticks there is no hardcoded limit for this parameter. Only limitation is that final delay in CPU ticks might not overflow 32 bit unsigned integer (which is more than 1s @ 4GHz CPU). In real scenarios delay_base_us should be much lower than 150us. To disable coalescing set delay_base_us to 0.

Parameters

Name	Optional	Type	Description
ctrlr	Required	string	Controller name
delay_base_us	Required	number	Base (minimum) coalescing time in microseconds
iops_threshold	Required	number	Coalescing activation level greater than 0 in IO per second

Example

Example request:

{
  "params": {
    "iops_threshold": 100000,
    "ctrlr": "VhostScsi0",
    "delay_base_us": 80
  },
  "jsonrpc": "2.0",
  "method": "set_vhost_controller_coalescing",
  "id": 1
}

Example response:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": true
}

construct_vhost_scsi_controller

Construct vhost SCSI target.

Parameters

Name	Optional	Type	Description
ctrlr	Required	string	Controller name
cpumask	Optional	string	@ref cpu_mask for this controller

Example

Example request:

{
  "params": {
    "cpumask": "0x2",
    "ctrlr": "VhostScsi0"
  },
  "jsonrpc": "2.0",
  "method": "construct_vhost_scsi_controller",
  "id": 1
}

Example response:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": true
}

add_vhost_scsi_lun

In vhost target ctrlr create SCSI target with ID scsi_target_num and add bdev_name as LUN 0.

Parameters

Name	Optional	Type	Description
ctrlr	Required	string	Controller name
scsi_target_num	Required	number	SCSI target ID between 0 and 7 or -1 to use first free ID.
bdev_name	Required	string	Name of bdev to expose as a LUN 0

Response

SCSI target ID.

Example

Example request:

{
  "params": {
    "scsi_target_num": 1,
    "bdev_name": "Malloc0",
    "ctrlr": "VhostScsi0"
  },
  "jsonrpc": "2.0",
  "method": "add_vhost_scsi_lun",
  "id": 1
}

Example response:

response:
{
  "jsonrpc": "2.0",
  "id": 1,
  "result": 1
}

remove_vhost_scsi_target

Remove SCSI target ID scsi_target_num from vhost target scsi_target_num.

This method will fail if initiator is connected, but doesn't support hot-remove (the VIRTIO_SCSI_F_HOTPLUG is not negotiated).

Parameters

Name	Optional	Type	Description
ctrlr	Required	string	Controller name
scsi_target_num	Required	number	SCSI target ID between 0 and 7

Example

Example request:

request:
{
  "params": {
    "scsi_target_num": 1,
    "ctrlr": "VhostScsi0"
  },
  "jsonrpc": "2.0",
  "method": "remove_vhost_scsi_target",
  "id": 1
}

Example response:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": true
}

construct_vhost_nvme_controller

Construct empty vhost NVMe controller.

Parameters

Name	Optional	Type	Description
ctrlr	Required	string	Controller name
io_queues	Required	number	Number between 1 and 31 of IO queues for the controller
cpumask	Optional	string	@ref cpu_mask for this controller

Example

Example request:

{
  "params": {
    "cpumask": "0x2",
    "io_queues": 4,
    "ctrlr": "VhostNvme0"
  },
  "jsonrpc": "2.0",
  "method": "construct_vhost_nvme_controller",
  "id": 1
}

Example response:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": true
}

add_vhost_nvme_ns

Add namespace backed by bdev_name

Parameters

Name	Optional	Type	Description
ctrlr	Required	string	Controller name
bdev_name	Required	string	Name of bdev to expose as a namespace
cpumask	Optional	string	@ref cpu_mask for this controller

Example

Example request:

{
  "params": {
    "bdev_name": "Malloc0",
    "ctrlr": "VhostNvme0"
  },
  "jsonrpc": "2.0",
  "method": "add_vhost_nvme_ns",
  "id": 1
}

Example response:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": true
}

construct_vhost_blk_controller

Construct vhost block controller

If readonly is true then vhost block target will be created as read only and fail any write requests. The VIRTIO_BLK_F_RO feature flag will be offered to the initiator.

Parameters

Name	Optional	Type	Description
ctrlr	Required	string	Controller name
bdev_name	Required	string	Name of bdev to expose block device
readonly	Optional	boolean	If true, this target will be read only (default: false)
cpumask	Optional	string	@ref cpu_mask for this controller

Example

Example request:

{
  "params": {
    "dev_name": "Malloc0",
    "ctrlr": "VhostBlk0"
  },
  "jsonrpc": "2.0",
  "method": "construct_vhost_blk_controller",
  "id": 1
}

Example response:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": true
}

get_vhost_controllers

Display information about all or specific vhost controller(s).

Parameters

The user may specify no parameters in order to list all controllers, or a controller may be specified by name.

Name	Optional	Type	Description
name	Optional	string	Vhost controller name

Response

Response is an array of objects describing requested controller(s). Common fields are:

Name	Type	Description
ctrlr	string	Controller name
cpumask	string	@ref cpu_mask of this controller
delay_base_us	number	Base (minimum) coalescing time in microseconds (0 if disabled)
iops_threshold	number	Coalescing activation level
backend_specific	object	Backend specific informations

Vhost block

backend_specific contains one block object of type:

Name	Type	Description
bdev	string	Backing bdev name or Null if bdev is hot-removed
readonly	boolean	True if controllers is readonly, false otherwise

Vhost SCSI

backend_specific contains scsi array of following objects:

Name	Type	Description
target_name	string	Name of this SCSI target
id	number	Unique SPDK global SCSI target ID
scsi_dev_num	number	SCSI target ID initiator will see when scanning this controller
luns	array	array of objects describing @ref rpc_get_vhost_controllers_scsi_luns

Vhost SCSI LUN

Object of type:

Name	Type	Description
id	number	SCSI LUN ID
bdev_name	string	Backing bdev name

Vhost NVMe

backend_specific contains namespaces array of following objects:

Name	Type	Description
nsid	number	Namespace ID
bdev	string	Backing bdev name

Example

Example request:

{
  "jsonrpc": "2.0",
  "method": "get_vhost_controllers",
  "id": 1
}

Example response:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": [
    {
      "cpumask": "0x2",
      "backend_specific": {
        "block": {
          "readonly": false,
          "bdev": "Malloc0"
        }
      },
      "iops_threshold": 60000,
      "ctrlr": "VhostBlk0",
      "delay_base_us": 100
    },
    {
      "cpumask": "0x2",
      "backend_specific": {
        "scsi": [
          {
            "target_name": "Target 2",
            "luns": [
              {
                "id": 0,
                "bdev_name": "Malloc1"
              }
            ],
            "id": 0,
            "scsi_dev_num": 2
          },
          {
            "target_name": "Target 5",
            "luns": [
              {
                "id": 0,
                "bdev_name": "Malloc2"
              }
            ],
            "id": 1,
            "scsi_dev_num": 5
          }
        ]
      },
      "iops_threshold": 60000,
      "ctrlr": "VhostScsi0",
      "delay_base_us": 0
    },
    {
      "cpumask": "0x2",
      "backend_specific": {
        "namespaces": [
          {
            "bdev": "Malloc3",
            "nsid": 1
          },
          {
            "bdev": "Malloc4",
            "nsid": 2
          }
        ]
      },
      "iops_threshold": 60000,
      "ctrlr": "VhostNvme0",
      "delay_base_us": 0
    }
  ]
}

remove_vhost_controller

Remove vhost target.

This call will fail if there is an initiator connected or there is at least one SCSI target configured in case of vhost SCSI target. In the later case please remove all SCSI targets first using @ref rpc_remove_vhost_scsi_target.

Parameters

Name	Optional	Type	Description
ctrlr	Required	string	Controller name

Example

Example request:

{
  "params": {
    "ctrlr": "VhostNvme0"
  },
  "jsonrpc": "2.0",
  "method": "remove_vhost_controller",
  "id": 1
}

Example response:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": true
}

Logical Volume

Identification of logical volume store and logical volume is explained first.

A logical volume store has a UUID and a name for its identification. The UUID is generated on creation and it can be used as a unique identifier. The name is specified on creation and can be renamed. Either UUID or name is used to access logical volume store in RPCs.

A logical volume has a UUID and a name for its identification. The UUID of the logical volume is generated on creation and it can be unique identifier. The alias of the logical volume takes the format lvs_name/lvol_name where:

• lvs_name is the name of the logical volume store.
• lvol_name is specified on creation and can be renamed.

construct_lvol_store

Construct a logical volume store.

Parameters

Name	Optional	Type	Description
bdev_name	Required	string	Bdev on which to construct logical volume store
lvs_name	Required	string	Name of the logical volume store to create
cluster_sz	Optional	number	Cluster size of the logical volume store in bytes
clear_method	Optional	string	Change clear method for data region. Available: none, unmap (default), write_zeroes

Response

UUID of the created logical volume store is returned.

Example

Example request:

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "construct_lvol_store",
  "params": {
    "lvs_name": "LVS0",
    "bdev_name": "Malloc0"
    "clear_method": "write_zeroes"
  }
}

Example response:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": "a9959197-b5e2-4f2d-8095-251ffb6985a5"
}

destroy_lvol_store

Destroy a logical volume store.

Parameters

Name	Optional	Type	Description
uuid	Optional	string	UUID of the logical volume store to destroy
lvs_name	Optional	string	Name of the logical volume store to destroy

Either uuid or lvs_name must be specified, but not both.

Example

Example request:

{
  "jsonrpc": "2.0",
  "method": "destroy_lvol_store",
  "id": 1
  "params": {
    "uuid": "a9959197-b5e2-4f2d-8095-251ffb6985a5"
  }
}

Example response:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": true
}

get_lvol_stores

Get a list of logical volume stores.

Parameters

Name	Optional	Type	Description
uuid	Optional	string	UUID of the logical volume store to retrieve information about
lvs_name	Optional	string	Name of the logical volume store to retrieve information about

Either uuid or lvs_name may be specified, but not both. If both uuid and lvs_name are omitted, information about all logical volume stores is returned.

Example

Example request:

{
  "jsonrpc": "2.0",
  "method": "get_lvol_stores",
  "id": 1,
  "params": {
    "lvs_name": "LVS0"
  }
}

Example response:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": [
    {
      "uuid": "a9959197-b5e2-4f2d-8095-251ffb6985a5",
      "base_bdev": "Malloc0",
      "free_clusters": 31,
      "cluster_size": 4194304,
      "total_data_clusters": 31,
      "block_size": 4096,
      "name": "LVS0"
    }
  ]
}

rename_lvol_store

Rename a logical volume store.

Parameters

Name	Optional	Type	Description
old_name	Required	string	Existing logical volume store name
new_name	Required	string	New logical volume store name

Example

Example request:

{
  "jsonrpc": "2.0",
  "method": "rename_lvol_store",
  "id": 1,
  "params": {
    "old_name": "LVS0",
    "new_name": "LVS2"
  }
}

Example response:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": true
}

construct_lvol_bdev

Create a logical volume on a logical volume store.

Parameters

Name	Optional	Type	Description
lvol_name	Required	string	Name of logical volume to create
size	Required	number	Desired size of logical volume in megabytes
thin_provision	Optional	boolean	True to enable thin provisioning
uuid	Optional	string	UUID of logical volume store to create logical volume on
lvs_name	Optional	string	Name of logical volume store to create logical volume on
clear_method	Optional	string	Change default data clusters clear method. Available: none, unmap, write_zeroes

Size will be rounded up to a multiple of cluster size. Either uuid or lvs_name must be specified, but not both. lvol_name will be used in the alias of the created logical volume.

Response

UUID of the created logical volume is returned.

Example

Example request:

{
  "jsonrpc": "2.0",
  "method": "construct_lvol_bdev",
  "id": 1,
  "params": {
    "lvol_name": "LVOL0",
    "size": 1048576,
    "lvs_name": "LVS0",
    "clear_method": "unmap",
    "thin_provision": true
  }
}

Example response:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": "1b38702c-7f0c-411e-a962-92c6a5a8a602"
}

snapshot_lvol_bdev

Capture a snapshot of the current state of a logical volume.

Parameters

Name	Optional	Type	Description
lvol_name	Required	string	UUID or alias of the logical volume to create a snapshot from
snapshot_name	Required	string	Name for the newly created snapshot

Response

UUID of the created logical volume snapshot is returned.

Example

Example request:

{
  "jsonrpc": "2.0",
  "method": "snapshot_lvol_bdev",
  "id": 1,
  "params": {
    "lvol_name": "1b38702c-7f0c-411e-a962-92c6a5a8a602",
    "snapshot_name": "SNAP1"
  }
}

Example response:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": "cc8d7fdf-7865-4d1f-9fc6-35da8e368670"
}

clone_lvol_bdev

Create a logical volume based on a snapshot.

Parameters

Name	Optional	Type	Description
snapshot_name	Required	string	UUID or alias of the snapshot to clone
clone_name	Required	string	Name for the logical volume to create

Response

UUID of the created logical volume clone is returned.

Example

Example request:

{
  "jsonrpc": "2.0"
  "method": "clone_lvol_bdev",
  "id": 1,
  "params": {
    "snapshot_name": "cc8d7fdf-7865-4d1f-9fc6-35da8e368670",
    "clone_name": "CLONE1"
  }
}

Example response:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": "8d87fccc-c278-49f0-9d4c-6237951aca09"
}

rename_lvol_bdev

Rename a logical volume. New name will rename only the alias of the logical volume.

Parameters

Name	Optional	Type	Description
old_name	Required	string	UUID or alias of the existing logical volume
new_name	Required	string	New logical volume name

Example

Example request:

{
  "jsonrpc": "2.0",
  "method": "rename_lvol_bdev",
  "id": 1,
  "params": {
    "old_name": "067df606-6dbc-4143-a499-0d05855cb3b8",
    "new_name": "LVOL2"
  }
}

Example response:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": true
}

resize_lvol_bdev

Resize a logical volume.

Parameters

Name	Optional	Type	Description
name	Required	string	UUID or alias of the logical volume to resize
size	Required	number	Desired size of the logical volume in megabytes

Example

Example request:

{
  "jsonrpc": "2.0",
  "method": "resize_lvol_bdev",
  "id": 1,
  "params": {
    "name": "51638754-ca16-43a7-9f8f-294a0805ab0a",
    "size": 2097152
  }
}

Example response:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": true
}

set_read_only_lvol_bdev

Mark logical volume as read only.

Parameters

Name	Optional	Type	Description
name	Required	string	UUID or alias of the logical volume to set as read only

Example

Example request:

{
  "jsonrpc": "2.0",
  "method": "set_read_only_lvol_bdev",
  "id": 1,
  "params": {
    "name": "51638754-ca16-43a7-9f8f-294a0805ab0a",
  }
}

Example response:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": true
}

destroy_lvol_bdev

Destroy a logical volume.

Parameters

Name	Optional	Type	Description
name	Required	string	UUID or alias of the logical volume to destroy

Example

Example request:

{
  "jsonrpc": "2.0",
  "method": "destroy_lvol_bdev",
  "id": 1,
  "params": {
    "name": "51638754-ca16-43a7-9f8f-294a0805ab0a"
  }
}

Example response:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": true
}

inflate_lvol_bdev

Inflate a logical volume. All unallocated clusters are allocated and copied from the parent or zero filled if not allocated in the parent. Then all dependencies on the parent are removed.

Parameters

Name	Optional	Type	Description
name	Required	string	UUID or alias of the logical volume to inflate

Example

Example request:

{
  "jsonrpc": "2.0",
  "method": "inflate_lvol_bdev",
  "id": 1,
  "params": {
    "name": "8d87fccc-c278-49f0-9d4c-6237951aca09"
  }
}

Example response:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": true
}

decouple_parent_lvol_bdev

Decouple the parent of a logical volume. For unallocated clusters which is allocated in the parent, they are allocated and copied from the parent, but for unallocated clusters which is thin provisioned in the parent, they are kept thin provisioned. Then all dependencies on the parent are removed.

Parameters

Name	Optional	Type	Description
name	Required	string	UUID or alias of the logical volume to decouple the parent of it

Example

Example request:

{
  "jsonrpc": "2.0",
  "method": "decouple_parent_lvol_bdev",
  "id": 1.
  "params": {
    "name": "8d87fccc-c278-49f0-9d4c-6237951aca09"
  }
}

Example response:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": true
}

RAID

get_raid_bdevs

This is used to list all the raid bdev names based on the input category requested. Category should be one of 'all', 'online', 'configuring' or 'offline'. 'all' means all the raid bdevs whether they are online or configuring or offline. 'online' is the raid bdev which is registered with bdev layer. 'configuring' is the raid bdev which does not have full configuration discovered yet. 'offline' is the raid bdev which is not registered with bdev as of now and it has encountered any error or user has requested to offline the raid bdev.

Parameters

Name	Optional	Type	Description
category	Required	string	all or online or configuring or offline

Example

Example request:

{
  "jsonrpc": "2.0",
  "method": "get_raid_bdevs",
  "id": 1,
  "params": {
    "category": "all"
  }
}

Example response:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": [
    "Raid0"
  ]
}

construct_raid_bdev

Constructs new RAID bdev.

Parameters

Name	Optional	Type	Description
name	Required	string	RAID bdev name
strip_size_kb	Required	number	Strip size in KB
raid_level	Required	number	RAID level
base_bdevs	Required	string	Base bdevs name, whitespace separated list in quotes

Example

Example request:

{
  "jsonrpc": "2.0",
  "method": "construct_raid_bdev",
  "id": 1,
  "params": {
    "name": "Raid0",
    "raid_level": 0,
    "base_bdevs": [
      "Malloc0",
      "Malloc1",
      "Malloc2",
      "Malloc3"
    ],
    "strip_size": 4096
  }
}

Example response:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": true
}

destroy_raid_bdev

Removes RAID bdev.

Parameters

Name	Optional	Type	Description
name	Required	string	RAID bdev name

Example

Example request:

{
  "jsonrpc": "2.0",
  "method": "destroy_raid_bdev",
  "id": 1,
  "params": {
    "name": "Raid0"
  }
}

Example response:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": true
}

Notifications

get_notification_types

Return list of all supported notification types.

Parameters

None

Response

The response is an array of strings - supported RPC notification types.

Example

Example request:

{
  "jsonrpc": "2.0",
  "method": "get_notification_types",
  "id": 1
}

Example response:

{
  "id": 1,
  "result": [
    "bdev_register",
    "bdev_unregister"
  ],
  "jsonrpc": "2.0"
}

get_notifications

Request notifications. Returns array of notifications that happend since the specified id (or first that is available).

Notice: Notifications are kept in circular buffer with limited size. Older notifications might be inaccesible due to being overwritten by new ones.

Parameters

Name	Optional	Type	Description
id	Optional	number	First Event ID to fetch (default: first available).
max	Optional	number	Maximum number of event to return (default: no limit).

Response

Response is an array of event objects.

Name	Optional	Type	Description
id	Optional	number	Event ID.
type	Optional	number	Type of the event.
ctx	Optional	string	Event context.

Example

Example request:

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "get_notifications",
  "params": {
    "id": 1,
    "max": 10
  }
}

Example response:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": [
    {
      "ctx": "Malloc0",
      "type": "bdev_register",
      "id": 1
    },
    {
      "ctx": "Malloc2",
      "type": "bdev_register",
      "id": 2
    }
  ]
}

Linux Network Block Device (NBD)

SPDK supports exporting bdevs through Linux nbd. These devices then appear as standard Linux kernel block devices and can be accessed using standard utilities like fdisk.

In order to export a device over nbd, first make sure the Linux kernel nbd driver is loaded by running 'modprobe nbd'.

start_nbd_disk

Start to export one SPDK bdev as NBD disk

Parameters

Name	Optional	Type	Description
bdev_name	Required	string	Bdev name to export
nbd_device	Optional	string	NBD device name to assign

Response

Path of exported NBD disk

Example

Example request:

{
 "params": {
    "nbd_device": "/dev/nbd1",
    "bdev_name": "Malloc1"
  },
  "jsonrpc": "2.0",
  "method": "start_nbd_disk",
  "id": 1
}

Example response:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": "/dev/nbd1"
}

stop_nbd_disk

Stop one NBD disk which is based on SPDK bdev.

Parameters

Name	Optional	Type	Description
nbd_device	Required	string	NBD device name to stop

Example

Example request:

{
 "params": {
    "nbd_device": "/dev/nbd1",
  },
  "jsonrpc": "2.0",
  "method": "stop_nbd_disk",
  "id": 1
}

Example response:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": "true"
}

get_nbd_disks

Display all or specified NBD device list

Parameters

Name	Optional	Type	Description
nbd_device	Optional	string	NBD device name to display

Response

The response is an array of exported NBD devices and their corresponding SPDK bdev.

Example

Example request:

{
  "jsonrpc": "2.0",
  "method": "get_nbd_disks",
  "id": 1
}

Example response:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result":  [
    {
      "bdev_name": "Malloc0",
      "nbd_device": "/dev/nbd0"
    },
    {
      "bdev_name": "Malloc1",
      "nbd_device": "/dev/nbd1"
    }
  ]
}

Miscellaneous RPC commands

send_nvme_cmd

Send NVMe command directly to NVMe controller or namespace. Parameters and responses encoded by base64 urlsafe need further processing.

Notice: send_nvme_cmd requires user to guarentee the correctness of NVMe command itself, and also optional parameters. Illegal command contents or mismatching buffer size may result in unpredictable behavior.

Parameters

Name	Optional	Type	Description
name	Required	string	Name of the operating NVMe controller
cmd_type	Required	string	Type of nvme cmd. Valid values are: admin, io
data_direction	Required	string	Direction of data transfer. Valid values are: c2h, h2c
cmdbuf	Required	string	NVMe command encoded by base64 urlsafe
data	Optional	string	Data transferring to controller from host, encoded by base64 urlsafe
metadata	Optional	string	Metadata transferring to controller from host, encoded by base64 urlsafe
data_len	Optional	number	Data length required to transfer from controller to host
metadata_len	Optional	number	Metadata length required to transfer from controller to host
timeout_ms	Optional	number	Command execution timeout value, in milliseconds

Response

Name	Type	Description
cpl	string	NVMe completion queue entry, encoded by base64 urlsafe
data	string	Data transferred from controller to host, encoded by base64 urlsafe
metadata	string	Metadata transferred from controller to host, encoded by base64 urlsafe

Example

Example request:

{
  "jsonrpc": "2.0",
  "method": "send_nvme_cmd",
  "id": 1,
  "params": {
    "name": "Nvme0",
    "cmd_type": "admin"
    "data_direction": "c2h",
    "cmdbuf": "BgAAAAEAAAAAAAAAAAAAAAAAAAAAAAAAsGUs9P5_AAAAAAAAABAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA==",
    "data_len": 60,
  }
}

Example response:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result":  {
    "cpl": "AAAAAAAAAAARAAAAWrmwABAA==",
    "data": "sIjg6AAAAACwiODoAAAAALCI4OgAAAAAAAYAAREAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA"
  }

}

get_spdk_version

Get the version info of the running SPDK application.

Parameters

This method has no parameters.

Response

The response is the version number including major version number, minor version number, patch level number and suffix string.

Example

Example request: ~~ { "jsonrpc": "2.0", "id": 1, "method": "get_spdk_version" } ~~

Example response: ~~ { "jsonrpc": "2.0", "id": 1, "result": { "version": "19.04-pre", "fields" : { "major": 19, "minor": 4, "patch": 0, "suffix": "-pre" } } } ~~