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_framework_start_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

spdk_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": "spdk_kill_instance",
  "params": {
    "sig_name": "SIGINT"
  }
}

Example response:

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

framework_monitor_context_switch

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": "framework_monitor_context_switch",
  "params": {
    "enabled": false
  }
}

Example response:

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

framework_start_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": "framework_start_init"
}

Example response:

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

framework_wait_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": "framework_wait_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": [
    "framework_start_init",
    "rpc_get_methods",
    "scsi_get_devices",
    "net_get_interfaces",
    "delete_ip_address",
    "net_interface_add_ip_address",
    "nbd_get_disks",
    "nbd_stop_disk",
    "nbd_start_disk",
    "log_get_flags",
    "log_clear_flag",
    "log_set_flag",
    "log_get_level",
    "log_set_level",
    "log_get_print_level",
    "log_set_print_level",
    "iscsi_get_options",
    "iscsi_target_node_add_lun",
    "iscsi_get_connections",
    "iscsi_delete_portal_group",
    "iscsi_create_portal_group",
    "iscsi_get_portal_groups",
    "iscsi_delete_target_node",
    "iscsi_target_node_remove_pg_ig_maps",
    "iscsi_target_node_add_pg_ig_maps",
    "iscsi_create_target_node",
    "iscsi_get_target_nodes",
    "iscsi_delete_initiator_group",
    "iscsi_initiator_group_remove_initiators",
    "iscsi_initiator_group_add_initiators",
    "iscsi_create_initiator_group",
    "iscsi_get_initiator_groups",
    "iscsi_set_options",
    "bdev_set_options",
    "bdev_set_qos_limit",
    "bdev_get_bdevs",
    "bdev_get_iostat",
    "framework_get_config",
    "framework_get_subsystems",
    "framework_monitor_context_switch",
    "spdk_kill_instance",
    "ioat_scan_accel_engine",
    "bdev_virtio_attach_controller",
    "bdev_virtio_scsi_get_devices",
    "bdev_virtio_detach_controller",
    "bdev_aio_delete",
    "bdev_aio_create",
    "bdev_split_delete",
    "bdev_split_create",
    "bdev_error_inject_error",
    "bdev_error_delete",
    "bdev_error_create",
    "bdev_passthru_create",
    "bdev_passthru_delete"
    "bdev_nvme_apply_firmware",
    "bdev_nvme_detach_controller",
    "bdev_nvme_attach_controller",
    "bdev_null_create",
    "bdev_malloc_delete",
    "bdev_malloc_create",
    "bdev_ftl_delete",
    "bdev_ftl_create",
    "bdev_lvol_get_lvstores",
    "bdev_lvol_delete",
    "bdev_lvol_resize",
    "bdev_lvol_set_read_only",
    "bdev_lvol_decouple_parent",
    "bdev_lvol_inflate",
    "bdev_lvol_rename",
    "bdev_lvol_clone",
    "bdev_lvol_snapshot",
    "bdev_lvol_create",
    "bdev_lvol_delete_lvstore",
    "bdev_lvol_rename_lvstore",
    "bdev_lvol_create_lvstore"
  ]
}

framework_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": "framework_get_subsystems"
}

Example response:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": [
    {
      "subsystem": "accel",
      "depends_on": []
    },
    {
      "subsystem": "interface",
      "depends_on": []
    },
    {
      "subsystem": "net_framework",
      "depends_on": [
        "interface"
      ]
    },
    {
      "subsystem": "bdev",
      "depends_on": [
        "accel"
      ]
    },
    {
      "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"
      ]
    }
  ]
}

framework_get_config

Get current configuration of the specified SPDK framework

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 framework_get_config method and empty array is returned if it is empty.

Example

Example request:

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

Example response:

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

framework_get_reactors

Retrieve an array of all reactors.

Parameters

This method has no parameters.

Response

The response is an array of all reactors.

Example

Example request:

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

Example response:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "tick_rate": 2400000000,
    "reactors": [
      {
        "lcore": 0,
        "busy": 41289723495,
        "idle": 3624832946,
        "lw_threads": [
          {
            "name": "app_thread",
            "id", 1,
            "cpumask": "1",
            "elapsed": 44910853363
          }
        ]
      }
    ]
  }
}

thread_get_stats

Retrieve current statistics of all the threads.

Parameters

This method has no parameters.

Response

The response is an array of objects containing threads statistics.

Example

Example request:

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

Example response:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "tick_rate": 2400000000,
    "threads": [
      {
        "name": "app_thread",
        "id": 1,
	"cpumask": "1",
        "busy": 139223208,
        "idle": 8641080608,
        "active_pollers_count": 1,
        "timed_pollers_count": 2,
        "paused_pollers_count": 0
      }
    ]
  }
}

thread_set_cpumask

Set the cpumask of the thread to the specified value. The thread may be migrated to one of the specified CPUs.

Parameters

Name	Optional	Type	Description
id	Required	string	Thread ID
cpumask	Required	string	Cpumask for this thread

Response

Completion status of the operation is returned as a boolean.

Example

Example request:

{
  "jsonrpc": "2.0",
  "method": "thread_set_cpumask",
  "id": 1,
  "params": {
    "id": "1",
    "cpumask": "1"
  }
}

Example response:

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

thread_get_pollers

Retrieve current pollers of all the threads.

Parameters

This method has no parameters.

Response

The response is an array of objects containing pollers of all the threads.

Example

Example request:

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

Example response:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "tick_rate": 2500000000,
    "threads": [
      {
        "name": "app_thread",
        "id": 1,
        "active_pollers": [],
        "timed_pollers": [
          {
            "name": "spdk_rpc_subsystem_poll",
            "state": "waiting",
            "run_count": 12345,
            "busy_count": 10000,
            "period_ticks": 10000000
          }
        ],
        "paused_pollers": []
      }
    ]
  }
}

thread_get_io_channels

Retrieve current IO channels of all the threads.

Parameters

This method has no parameters.

Response

The response is an array of objects containing IO channels of all the threads.

Example

Example request:

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

Example response:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "tick_rate": 2500000000,
    "threads": [
      {
        "name": "app_thread",
        "io_channels": [
          {
            "name": "nvmf_tgt",
            "ref": 1
          }
        ]
      }
    ]
  }
}

Block Device Abstraction Layer

bdev_set_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": "bdev_set_options",
  "params": {
    "bdev_io_pool_size": 65536,
    "bdev_io_cache_size": 256
  }
}

Example response:

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

bdev_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": "bdev_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,
      "zoned": 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": {}
    }
  ]
}

bdev_get_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": "bdev_get_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
      }
    ]
  }
}

bdev_enable_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": "bdev_enable_histogram",
  "params": {
    "name": "Nvme0n1"
    "enable": true
  }
}

Example response:

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

bdev_get_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": "bdev_get_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
  }
}

bdev_set_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": "bdev_set_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
}

bdev_ocf_create

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": "bdev_ocf_create",
  "id": 1
}

Example response:

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

bdev_ocf_delete

Delete the OCF bdev

Parameters

Name	Optional	Type	Description
name	Required	string	Bdev name

Example

Example request:

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

Example response:

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

bdev_ocf_get_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": "bdev_ocf_get_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"
    }
  ]
}

bdev_ocf_get_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": "bdev_ocf_get_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
      }
    }
  ]
}

bdev_malloc_create

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": "bdev_malloc_create",
  "id": 1
}

Example response:

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

bdev_malloc_delete

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": "bdev_malloc_delete",
  "id": 1
}

Example response:

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

bdev_null_create

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
md_size	Optional	number	Metadata size in bytes
dif_type	Optional	number	Protection information type (0, 1, 2 or 3). Default: 0 - no protection.
dif_is_head_of_md	Optional	boolean	Protection information is in the first 8 bytes of MD. Default: in the last 8 bytes.

Result

Name of newly created bdev.

Example

Example request:

{
  "params": {
    "block_size": 4104,
    "num_blocks": 16384,
    "name": "Null0",
    "uuid": "2b6601ba-eada-44fb-9a83-a20eb9eb9e90",
    "md_size": 8,
    "dif_type": 1,
    "dif_is_head_of_md": true
  },
  "jsonrpc": "2.0",
  "method": "bdev_null_create",
  "id": 1
}

Example response:

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

bdev_null_delete

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": "bdev_null_delete",
  "id": 1
}

Example response:

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

bdev_aio_create

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": "bdev_aio_create",
  "id": 1
}

Example response:

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

bdev_aio_delete

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": "bdev_aio_delete",
  "id": 1
}

Example response:

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

bdev_nvme_set_options

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

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
arbitration_burst	Optional	number	The value is expressed as a power of two, a value of 111b indicates no limit
low_priority_weight	Optional	number	The maximum number of commands that the controller may launch at one time from a low priority queue
medium_priority_weight	Optional	number	The maximum number of commands that the controller may launch at one time from a medium priority queue
high_priority_weight	Optional	number	The maximum number of commands that the controller may launch at one time from a high priority queue
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).
io_queue_requests	Optional	number	The number of requests allocated for each NVMe I/O queue. Default: 512.
delay_cmd_submit	Optional	boolean	Enable delaying NVMe command submission to allow batching of multiple commands. Default: true.

Example

Example request:

request:
{
  "params": {
    "retry_count": 5,
    "arbitration_burst": 3,
    "low_priority_weight": 8,
    "medium_priority_weight":8,
    "high_priority_weight": 8,
    "nvme_adminq_poll_period_us": 2000,
    "timeout_us": 10000000,
    "action_on_timeout": "reset",
    "io_queue_requests" : 2048,
    "delay_cmd_submit": true
  },
  "jsonrpc": "2.0",
  "method": "bdev_nvme_set_options",
  "id": 1
}

Example response:

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

bdev_nvme_set_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": "bdev_nvme_set_hotplug",
  "id": 1
}

Example response:

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

bdev_nvme_attach_controller

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": "bdev_nvme_attach_controller",
  "id": 1
}

Example response:

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

bdev_nvme_get_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": "bdev_nvme_get_controllers",
  "params": {
    "name": "Nvme0"
  }
}

Example response:

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

bdev_nvme_detach_controller

Detach NVMe controller and delete any associated bdevs.

Parameters

Name	Optional	Type	Description
name	Required	string	Controller name

Example

Example requests:

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

Example response:

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

bdev_nvme_cuse_register

Register CUSE device on NVMe controller. This feature is considered as experimental.

Parameters

Name	Optional	Type	Description
name	Required	string	Name of the NVMe controller
dev_path	Required	string	Path to the CUSE controller device, e.g. spdk/nvme0

Example

Example request:

{
  "params": {
    "dev_path": "spdk/nvme0",
    "name": "Nvme0"
  },
  "jsonrpc": "2.0",
  "method": "bdev_nvme_cuse_register",
  "id": 1
}

Example response:

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

bdev_nvme_cuse_unregister

Unregister CUSE device on NVMe controller. This feature is considered as experimental.

Parameters

Name	Optional	Type	Description
name	Required	string	Name of the NVMe controller

Example

Example request:

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

Example response:

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

bdev_rbd_create

Create @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": "bdev_rbd_create",
  "id": 1
}

Example response:

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

bdev_rbd_delete

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": "bdev_rbd_delete",
  "id": 1
}

Example response:

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

bdev_rbd_resize

Resize @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 resized or false otherwise.

Parameters

Name	Optional	Type	Description
name	Required	string	Bdev name
new_size	Required	int	New bdev size for resize operation in MiB

Example

Example request:

{
  "params": {
    "name": "Rbd0"
    "new_size": "4096"
  },
  "jsonrpc": "2.0",
  "method": "bdev_rbd_resize",
  "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. All latency values supplied to this bdev should be in microseconds.

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
}

bdev_delay_update_latency

Update a target latency value associated with a given delay bdev. Any currently outstanding I/O will be completed with the old latency.

Parameters

Name	Optional	Type	Description
delay_bdev_name	Required	string	Name of the delay bdev
latency_type	Required	string	One of: avg_read, avg_write, p99_read, p99_write
latency_us	Required	number	The new latency value in microseconds

Result

Name of newly created bdev.

Example

Example request:

{
  "params": {
    "delay_bdev_name": "Delay0",
    "latency_type": "avg_read",
    "latency_us": "100",
  },
  "jsonrpc": "2.0",
  "method": "bdev_delay_update_latency",
  "id": 1
}

Example response:

{
  "result": "true"
}

bdev_error_create

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": "bdev_error_create",
  "id": 1
}

Example response:

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

bdev_error_delete

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": "bdev_error_delete",
  "id": 1
}

Example response:

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

bdev_iscsi_create

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": "bdev_iscsi_create",
  "id": 1
}

Example response:

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

bdev_iscsi_delete

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": "bdev_iscsi_delete",
  "id": 1
}

Example response:

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

bdev_ftl_create

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": "bdev_ftl_create",
  "id": 1
}

Example response:

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

bdev_ftl_delete

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": "bdev_ftl_delete",
  "id": 1
}

Example response:

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

bdev_pmem_create_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": "bdev_pmem_create_pool",
  "id": 1
}

Example response:

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

bdev_pmem_get_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": "bdev_pmem_get_pool_info",
  "id": 1
}

Example response:

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

bdev_pmem_delete_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": "bdev_pmem_delete_pool",
  "id": 1
}

Example response:

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

bdev_pmem_create

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": "bdev_pmem_create",
  "id": 1
}

Example response:

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

bdev_pmem_delete

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": "bdev_pmem_delete",
  "id": 1
}

Example response:

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

bdev_passthru_create

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": "bdev_passthru_create",
  "id": 1
}

Example response:

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

bdev_passthru_delete

Delete passthru bdev.

Parameters

Name	Optional	Type	Description
name	Required	string	Bdev name

Example

Example request:

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

Example response:

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

bdev_virtio_attach_controller

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": "bdev_virtio_attach_controller",
  "id": 1
}

Example response:

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

bdev_virtio_scsi_get_devices

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": "bdev_virtio_scsi_get_devices",
  "id": 1
}

Example response:

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

bdev_virtio_detach_controller

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": "bdev_virtio_detach_controller",
  "id": 1
}

Example response:

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

iSCSI Target

iscsi_set_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": "iscsi_set_options",
  "id": 1
}

Example response:

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

iscsi_get_options method

Show global parameters of iSCSI targets.

Parameters

This method has no parameters.

Example

Example request:

request:
{
  "jsonrpc": "2.0",
  "method": "iscsi_get_options",
  "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
  }
}

iscsi_set_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": "iscsi_set_discovery_auth",
  "id": 1
}

Example response:

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

iscsi_create_auth_group method

Create 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_iscsi_create_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": "iscsi_create_auth_group",
  "id": 1
}

Example response:

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

iscsi_delete_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": "iscsi_delete_auth_group",
  "id": 1
}

Example response:

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

iscsi_get_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_iscsi_create_auth_group_secret objects

Example

Example request:

{
  "jsonrpc": "2.0",
  "method": "iscsi_get_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
    }
  ]
}

iscsi_auth_group_add_secret

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": "iscsi_auth_group_add_secret",
  "id": 1
}

Example response:

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

iscsi_auth_group_remove_secret

Remove 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": "iscsi_auth_group_remove_secret",
  "id": 1
}

Example response:

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

iscsi_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": "iscsi_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"
      ]
    }
  ]
}

iscsi_create_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": "iscsi_create_initiator_group",
  "id": 1
}

Example response:

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

iscsi_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": "iscsi_delete_initiator_group",
  "id": 1
}

Example response:

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

iscsi_initiator_group_add_initiators 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": "iscsi_initiator_group_add_initiators",
  "id": 1
}

Example response:

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

iscsi_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": "iscsi_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
    }
  ]
}

iscsi_create_target_node method

Add an 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": "iscsi_create_target_node",
  "id": 1
}

Example response:

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

iscsi_target_node_set_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": "iscsi_target_node_set_auth",
  "id": 1
}

Example response:

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

iscsi_target_node_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": "iscsi_target_node_add_pg_ig_maps",
  "id": 1
}

Example response:

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

iscsi_target_node_remove_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": "iscsi_target_node_remove_pg_ig_maps",
  "id": 1
}

Example response:

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

iscsi_delete_target_node method

Delete an 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": "iscsi_delete_target_node",
  "id": 1
}

Example response:

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

iscsi_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": "iscsi_get_portal_groups",
  "id": 1
}

Example response:

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

iscsi_create_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": "iscsi_create_portal_group",
  "id": 1
}

Example response:

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

iscsi_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": "iscsi_delete_portal_group",
  "id": 1
}

Example response:

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

iscsi_portal_group_set_auth method

Set CHAP authentication for discovery sessions specific for the existing iSCSI portal group. This RPC overwrites the setting by the global parameters for the iSCSI portal group.

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": {
    "tag": 1,
    "chap_group": 1,
    "require_chap": true,
    "mutual_chap": true
  },
  "jsonrpc": "2.0",
  "method": "iscsi_portal_group_set_auth",
  "id": 1
}

Example response:

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

iscsi_get_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": "iscsi_get_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
    }
  ]
}

iscsi_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": "iscsi_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)
tgt_name	Optional	string	Parent NVMe-oF target name.
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)
c2h_success	Optional	boolean	Disable C2H success optimization (TCP only)
dif_insert_or_strip	Optional	boolean	Enable DIF insert for write I/O and DIF strip for read I/O DIF (TCP only)
sock_priority	Optional	number	The socket priority of the connection owned by this transport (TCP 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
}

nvmf_get_subsystems method

Parameters

Name	Optional	Type	Description
tgt_name	Optional	string	Parent NVMe-oF target name.

Example

Example request:

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "nvmf_get_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_create_subsystem method

Construct an NVMe over Fabrics target subsystem.

Parameters

Name	Optional	Type	Description
nqn	Required	string	Subsystem NQN
tgt_name	Optional	string	Parent NVMe-oF target name.
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_create_subsystem",
  "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
}

nvmf_delete_subsystem method

Delete an existing NVMe-oF subsystem.

Parameters

Parameter	Optional	Type	Description
nqn	Required	string	Subsystem NQN to delete.
tgt_name	Optional	string	Parent NVMe-oF target name.

Example

Example request:

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "nvmf_delete_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
tgt_name	Optional	string	Parent NVMe-oF target name.
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
tgt_name	Optional	string	Parent NVMe-oF target name.

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")
ptpl_file	Optional	string	File path to save/restore persistent reservation information

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",
      "ptpl_file": "/opt/Nvme0n1PR.json"
    }
  }
}

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
tgt_name	Optional	string	Parent NVMe-oF target name.

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
tgt_name	Optional	string	Parent NVMe-oF target name.

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
tgt_name	Optional	string	Parent NVMe-oF target name.

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).
tgt_name	Optional	string	Parent NVMe-oF target name.

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
}

nvmf_set_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": "nvmf_set_max_subsystems",
  "params": {
    "max_subsystems": 1024
  }
}

Example response:

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

nvmf_set_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)
admin_cmd_passthru	Optional	object	Admin command passthru configuration

admin_cmd_passthru

Name	Optional	Type	Description
identify_ctrlr	Required	bool	If true, enables custom identify handler that reports some identify attributes from the underlying NVMe drive

Example

Example request:

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

Example response:

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

nvmf_get_transports method

Parameters

Name	Optional	Type	Description
tgt_name	Optional	string	Parent NVMe-oF target name.

Example

Example request:

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "nvmf_get_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
    }
  ]
}

nvmf_get_stats method

Retrieve current statistics of the NVMf subsystem.

Parameters

Name	Optional	Type	Description
tgt_name	Optional	string	Parent NVMe-oF target name.

Response

The response is an object containing NVMf subsystem statistics.

Example

Example request:

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

Example response:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "tick_rate": 2400000000,
    "poll_groups": [
      {
        "name": "app_thread",
        "admin_qpairs": 1,
        "io_qpairs": 4,
        "pending_bdev_io": 1721,
        "transports": [
          {
            "trtype": "RDMA",
            "pending_data_buffer": 12131888,
            "devices": [
              {
                "name": "mlx5_1",
                "polls": 72284105,
                "completions": 0,
                "requests": 0,
                "request_latency": 0,
                "pending_free_request": 0,
                "pending_rdma_read": 0,
                "pending_rdma_write": 0
              },
              {
                "name": "mlx5_0",
                "polls": 72284105,
                "completions": 15165875,
                "requests": 7582935,
                "request_latency": 1249323766184,
                "pending_free_request": 0,
                "pending_rdma_read": 337602,
                "pending_rdma_write": 0
              }
            ]
          }
        ]
      }
    ]
  }
}

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.

vhost_controller_set_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": "vhost_controller_set_coalescing",
  "id": 1
}

Example response:

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

vhost_create_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": "vhost_create_scsi_controller",
  "id": 1
}

Example response:

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

vhost_scsi_controller_add_target

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": "vhost_scsi_controller_add_target",
  "id": 1
}

Example response:

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

vhost_scsi_controller_remove_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": "vhost_scsi_controller_remove_target",
  "id": 1
}

Example response:

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

vhost_create_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": "vhost_create_nvme_controller",
  "id": 1
}

Example response:

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

vhost_nvme_controller_add_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": "vhost_nvme_controller_add_ns",
  "id": 1
}

Example response:

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

vhost_create_blk_controller

Create 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": "vhost_create_blk_controller",
  "id": 1
}

Example response:

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

vhost_get_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_vhost_get_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": "vhost_get_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
    }
  ]
}

vhost_delete_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_vhost_scsi_controller_remove_target.

Parameters

Name	Optional	Type	Description
ctrlr	Required	string	Controller name

Example

Example request:

{
  "params": {
    "ctrlr": "VhostNvme0"
  },
  "jsonrpc": "2.0",
  "method": "vhost_delete_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.

bdev_lvol_create_lvstore

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": "bdev_lvol_create_lvstore",
  "params": {
    "lvs_name": "LVS0",
    "bdev_name": "Malloc0"
    "clear_method": "write_zeroes"
  }
}

Example response:

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

bdev_lvol_delete_lvstore

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": "bdev_lvol_delete_lvstore",
  "id": 1
  "params": {
    "uuid": "a9959197-b5e2-4f2d-8095-251ffb6985a5"
  }
}

Example response:

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

bdev_lvol_get_lvstores

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": "bdev_lvol_get_lvstores",
  "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"
    }
  ]
}

bdev_lvol_rename_lvstore

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": "bdev_lvol_rename_lvstore",
  "id": 1,
  "params": {
    "old_name": "LVS0",
    "new_name": "LVS2"
  }
}

Example response:

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

bdev_lvol_create

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": "bdev_lvol_create",
  "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"
}

bdev_lvol_snapshot

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": "bdev_lvol_snapshot",
  "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"
}

bdev_lvol_clone

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": "bdev_lvol_clone",
  "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"
}

bdev_lvol_rename

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": "bdev_lvol_rename",
  "id": 1,
  "params": {
    "old_name": "067df606-6dbc-4143-a499-0d05855cb3b8",
    "new_name": "LVOL2"
  }
}

Example response:

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

bdev_lvol_resize

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": "bdev_lvol_resize",
  "id": 1,
  "params": {
    "name": "51638754-ca16-43a7-9f8f-294a0805ab0a",
    "size": 2097152
  }
}

Example response:

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

bdev_lvol_set_read_only

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": "bdev_lvol_set_read_only",
  "id": 1,
  "params": {
    "name": "51638754-ca16-43a7-9f8f-294a0805ab0a",
  }
}

Example response:

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

bdev_lvol_delete

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": "bdev_lvol_delete",
  "id": 1,
  "params": {
    "name": "51638754-ca16-43a7-9f8f-294a0805ab0a"
  }
}

Example response:

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

bdev_lvol_inflate

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": "bdev_lvol_inflate",
  "id": 1,
  "params": {
    "name": "8d87fccc-c278-49f0-9d4c-6237951aca09"
  }
}

Example response:

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

bdev_lvol_decouple_parent

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": "bdev_lvol_decouple_parent",
  "id": 1.
  "params": {
    "name": "8d87fccc-c278-49f0-9d4c-6237951aca09"
  }
}

Example response:

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

RAID

bdev_raid_get_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": "bdev_raid_get_bdevs",
  "id": 1,
  "params": {
    "category": "all"
  }
}

Example response:

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

bdev_raid_create

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": "bdev_raid_create",
  "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
}

bdev_raid_delete

Removes RAID bdev.

Parameters

Name	Optional	Type	Description
name	Required	string	RAID bdev name

Example

Example request:

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

Example response:

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

OPAL

bdev_nvme_opal_init

This is used to initialize OPAL of a given NVMe ctrlr, including taking ownership and activating.

Parameters

Name	Optional	Type	Description
nvme_ctrlr_name	Required	string	name of nvme ctrlr
password	Required	string	admin password of OPAL

Example

Example request:

{
  "jsonrpc": "2.0",
  "method": "bdev_nvme_opal_init",
  "id": 1,
  "params": {
    "nvme_ctrlr_name": "nvme0",
    "password": "*****"
  }
}

Example response:

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

bdev_nvme_opal_revert

This is used to revert OPAL to its factory settings. Erase all user configuration and data.

Parameters

Name	Optional	Type	Description
nvme_ctrlr_name	Required	string	name of nvme ctrlr
password	Required	string	admin password of OPAL

Example

Example request:

{
  "jsonrpc": "2.0",
  "method": "bdev_nvme_opal_revert",
  "id": 1,
  "params": {
    "nvme_ctrlr_name": "nvme0",
    "password": "*****"
  }
}

Example response:

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

bdev_opal_create

This is used to create an OPAL virtual bdev.

Parameters

Name	Optional	Type	Description
nvme_ctrlr_name	Required	string	name of nvme ctrlr that supports OPAL
nsid	Required	number	namespace ID
locking_range_id	Required	number	OPAL locking range ID
range_start	Required	number	locking range start LBA
range_length	Required	number	locking range length
password	Required	string	admin password of OPAL

Response

The response is the name of created OPAL virtual bdev.

Example

Example request:

{
  "jsonrpc": "2.0",
  "method": "bdev_opal_create",
  "id": 1,
  "params": {
    "nvme_ctrlr_name": "nvme0",
    "nsid": 1,
    "locking_range_id": 1,
    "range_start": 0,
    "range_length": 4096,
    "password": "*****"
  }
}

Example response:

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

bdev_opal_get_info

This is used to get information of a given OPAL bdev.

Parameters

Name	Optional	Type	Description
bdev_name	Required	string	name of OPAL vbdev
password	Required	string	admin password

Response

The response is the locking info of OPAL virtual bdev.

Example

Example request:

{
  "jsonrpc": "2.0",
  "method": "bdev_opal_get_info",
  "id": 1,
  "params": {
    "bdev_name": "nvme0n1r1",
    "password": "*****"
  }
}

Example response:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
      "name": "nvme0n1r1",
      "range_start": 0,
      "range_length": 4096,
      "read_lock_enabled": true,
      "write_lock_enabled": true,
      "read_locked": false,
      "write_locked": false
    }
}

bdev_opal_delete

This is used to delete OPAL vbdev.

Parameters

Name	Optional	Type	Description
bdev_name	Required	string	name of OPAL vbdev
password	Required	string	admin password

Example

Example request:

{
  "jsonrpc": "2.0",
  "method": "bdev_opal_delete",
  "id": 1,
  "params": {
    "bdev_name": "nvme0n1r1",
    "password": "*****"
  }
}

Example response:

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

bdev_opal_new_user

This enables a new user to the specified opal bdev so that the user can lock/unlock the bdev. Recalling this for the same opal bdev, only the newest user will have the privilege.

Parameters

Name	Optional	Type	Description
bdev_name	Required	string	name of OPAL vbdev
admin_password	Required	string	admin password
user_id	Required	number	user ID
user_password	Required	string	user password

Example

Example request:

{
  "jsonrpc": "2.0",
  "method": "bdev_opal_new_user",
  "id": 1,
  "params": {
    "bdev_name": "nvme0n1r1",
    "admin_password": "*****",
    "user_id": "1",
    "user_password": "********"
  }
}

Example response:

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

bdev_opal_set_lock_state

This is used to lock/unlock specific opal bdev providing user ID and password.

Parameters

Name	Optional	Type	Description
bdev_name	Required	string	name of OPAL vbdev
user_id	Required	number	user ID
password	Required	string	user password
lock_state	Required	string	lock state

Example

Example request:

{
  "jsonrpc": "2.0",
  "method": "bdev_opal_set_lock_state",
  "id": 1,
  "params": {
    "bdev_name": "nvme0n1r1",
    "user_id": "1",
    "user_password": "********",
    "lock_state": "rwlock"
  }
}

Example response:

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

Notifications

notify_get_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": "notify_get_types",
  "id": 1
}

Example response:

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

notify_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": "notify_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'.

nbd_start_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": "nbd_start_disk",
  "id": 1
}

Example response:

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

nbd_stop_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": "nbd_stop_disk",
  "id": 1
}

Example response:

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

nbd_get_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": "nbd_get_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"
    }
  ]
}

Blobfs

blobfs_detect

Detect whether a blobfs exists on bdev.

Parameters

Name	Optional	Type	Description
bdev_name	Required	string	Block device name to detect blobfs

Response

True if a blobfs exists on the bdev; False otherwise.

Example

Example request:

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "blobfs_detect",
  "params": {
    "bdev_name": "Malloc0"
  }
}

Example response:

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

blobfs_create

Build blobfs on bdev.

Parameters

Name	Optional	Type	Description
bdev_name	Required	string	Block device name to create blobfs
cluster_sz	Optional	number	Size of cluster in bytes. Must be multiple of 4KiB page size, default and minimal value is 1M.

Example

Example request:

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "blobfs_create",
  "params": {
    "bdev_name": "Malloc0",
    "cluster_sz": 1M
  }
}

Example response:

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

blobfs_mount

Mount a blobfs on bdev to one host path through FUSE

Parameters

Name	Optional	Type	Description
bdev_name	Required	string	Block device name where the blobfs is
mountpoint	Required	string	Mountpoint path in host to mount blobfs

Example

Example request:

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": ""blobfs_mount"",
  "params": {
    "bdev_name": "Malloc0",
    "mountpoint": "/mnt/"
  }
}

Example response:

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

## blobfs_set_cache_size {#rpc_blobfs_set_cache_size}

Set cache pool size for blobfs filesystems.  This RPC is only permitted when the cache pool is not already initialized.

The cache pool is initialized when the first blobfs filesystem is initialized or loaded.  It is freed when the all initialized or loaded filesystems are unloaded.

### Parameters

Name                    | Optional | Type        | Description
----------------------- | -------- | ----------- | -----------
size_in_mb              | Required | number      | Cache size in megabytes

### Response

True if cache size is set successfully; False if failed to set.

### Example

Example request:

{ "jsonrpc": "2.0", "id": 1, "method": "blobfs_set_cache_size", "params": { "size_in_mb": 512, } }

Example response:

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

# Miscellaneous RPC commands

## bdev_nvme_send_cmd {#rpc_bdev_nvme_send_cmd}

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

Notice: bdev_nvme_send_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": "bdev_nvme_send_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" }

}

## spdk_get_version {#rpc_spdk_get_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": "spdk_get_version"
}
~~

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