SPDK implements a JSON-RPC 2.0 server to allow external management tools to dynamically configure SPDK components.
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.
These parameters are mandatory. If any required parameter is missing RPC command will fail with proper error response.
Those parameters might be omitted. If an optional parameter is present it must be valid otherwise command will fail proper error response.
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 |
| -32600 | Invalid request - not compliant with JSON-RPC 2.0 Specification |
| -32601 | Method not found |
| -32602 | Invalid params |
| -32603 | Internal error for e.g.: errors like out of memory |
| -32700 | Parser error |
Encountered some error during parsing request like:
This type of error is most common one. It mean that there is an error while processing the request like:
SPDK provides a set of Python scripts which can invoke the JSON-RPC methods described in this document. 'rpc.py' in the scripts directory is the main script that users will invoke to execute a JSON-RPC method. The scripts/rpc directory contains modules that 'rpc.py' imports for definitions of each SPDK library's or module's methods.
Example:
A brief description of each of the RPC methods and optional 'rpc.py' arguments can be viewed with:
A detailed description of each RPC method and its parameters is also available. For example:
An initial configuration can be specified for an SPDK application via the '-c' command line parameter. The configuration file is a JSON file containing all of the JSON-RPC method invocations necessary for the desired configuration. Writing these files by hand is extremely tedious however, so 'rpc.py' provides a mechanism to generate a JSON-RPC file based on the current configuration.
'config.json' can then be passed to a new SPDK application using the '-c' command line parameter to reproduce the same configuration.
'rpc.py' also supports batching of multiple JSON-RPC methods with one invocation. So instead of calling 'rpc.py' once for each JSON-RPC method, such as:
you can put the following into a text file:
and then just do:
SPDK includes both in-tree modules as well as the ability to use external modules. The in-tree modules include some python scripts to ease the process of sending RPCs to in-tree modules. External modules can utilize this same framework to add new RPC methods as follows:
If PYTHONPATH doesn't include the location of the external RPC python script, it should be updated:
In provided location, create python module file (e.g. rpc_plugin.py) with new RPC methods. The file should contain spdk_rpc_plugin_initialize() method that will be called when the plugin is loaded to define new parsers for provided subparsers argument that adds new RPC calls (subparsers.add_parser()). The new parsers should use the client.call() method to call RPC functions registered within the external module using the SPDK_RPC_REGISTER() macro. Example:
Finally, call the rpc.py script with '–plugin' parameter to provide above python module name:
Starting with SPDK 20.10, legacy configuration file support has been removed. Users with extensive configuration files already running in SPDK application, can generate JSON-RPC for current configuration.
If binary for deploying the application is unavailable, the legacy configuration file can be converted to JSON-RPC using python tool:
Send a signal to the application.
| Name | Optional | Type | Description |
|---|---|---|---|
| sig_name | Required | string | Signal to send (SIGINT, SIGTERM, SIGQUIT, SIGHUP, or SIGKILL) |
Example request:
Example response:
Query, enable, or disable the context switch monitoring functionality.
| Name | Optional | Type | Description |
|---|---|---|---|
| enabled | Optional | boolean | Enable (true) or disable (false) monitoring (omit this parameter to query the current state) |
| Name | Type | Description |
|---|---|---|
| enabled | boolean | The current state of context switch monitoring |
Example request:
Example response:
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.
This method has no parameters.
Completion status of SPDK subsystem initialization is returned as a boolean.
Example request:
Example response:
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.
This method has no parameters.
Returns True when subsystems have been initialized.
Example request:
Example response:
Get an array of supported RPC methods.
| Name | Optional | Type | Description |
|---|---|---|---|
| current | Optional | boolean | Get an array of RPC methods only callable in the current state. |
The response is an array of supported RPC methods.
Example request:
Example response:
Get an array of name and dependency relationship of SPDK subsystems in initialization order.
None
The response is an array of name and dependency relationship of SPDK subsystems in initialization order.
Example request:
Example response:
Get current configuration of the specified SPDK framework
| Name | Optional | Type | Description |
|---|---|---|---|
| name | Required | string | SPDK subsystem name |
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 request:
Example response:
Retrieve an array of all reactors.
This method has no parameters.
The response is an array of all reactors.
Example request:
Example response:
Select thread scheduler that will be activated. This feature is considered as experimental.
| Name | Optional | Type | Description |
|---|---|---|---|
| name | Required | string | Name of a scheduler |
| period | Optional | number | Scheduler period |
| load_limit | Optional | number | Thread load limit in % (dynamic only) |
| core_limit | Optional | number | Load limit on the core to be considered full (dynamic only) |
| core_busy | Optional | number | Indicates at what load on core scheduler should move threads to a different core (dynamic only) |
Completion status of the operation is returned as a boolean.
Example request:
Example response:
Retrieve currently set scheduler name and period, along with current governor name.
This method has no parameters.
| Name | Description |
|---|---|
| scheduler_name | Current scheduler name |
| scheduler_period | Currently set scheduler period in microseconds |
| governor_name | Governor name |
| scheduling_core | Current scheduling core |
| isolated_core_mask | Current isolated core mask of scheduler |
Example request:
Example response:
Retrieve current governor name, power env, frequencies available and frequency set to the cpu cores.
This method has no parameters.
Displays the current governor name, power env, frequencies available and frequency set to the cpu cores.
Example request:
Example response:
Set options for scheduler.
This RPC may only be called before SPDK subsystems have been initialized. This RPC can be called only once.
| Name | Optional | Type | Description |
|---|---|---|---|
| scheduling_core | Optional | number | Main core of scheduler. Idle threads move to the scheduling core. Can be set only once |
| isolated_core_mask | Optional | string | Select CPU cores to isolate from scheduling changes. Can be set only once |
Example request:
Example response:
Enable CPU core lock files to block multiple SPDK applications from running on the same cpumask. The CPU core locks are enabled by default, unless user specified --disable-cpumask-locks command line option when launching SPDK.
This RPC may be called after locks have already been enabled, with no effect and no error response.
This method has no parameters.
true on success
Example request:
Example response:
Disable CPU core lock files. The locks can also be disabled during startup, when user specifies --disable-cpumask-locks command line option during SPDK launch.
This RPC may be called after locks have already been disabled, with no effect and no error response.
This method has no parameters.
true on success
Example request:
Example response:
Retrieve current statistics of all the threads.
This method has no parameters.
The response is an array of objects containing threads statistics.
Example request:
Example response:
Set the cpumask of the thread to the specified value. The thread may be migrated to one of the specified CPUs.
| Name | Optional | Type | Description |
|---|---|---|---|
| id | Required | string | Thread ID |
| cpumask | Required | string | Cpumask for this thread |
Completion status of the operation is returned as a boolean.
Example request:
Example response:
Enable trace on a specific tpoint group. For example "bdev" for bdev trace group, "all" for all trace groups.
| Name | Optional | Type | Description |
|---|---|---|---|
| name | Required | string | bdev, nvmf_rdma, nvmf_tcp, blobfs, scsi, iscsi_conn, ftl, all |
Example request:
Example response:
Disable trace on a specific tpoint group. For example "bdev" for bdev trace group, "all" for all trace groups.
| Name | Optional | Type | Description |
|---|---|---|---|
| name | Required | string | bdev, nvmf_rdma, nvmf_tcp, blobfs, all |
Example request:
Example response:
Enable tracepoint mask on a specific tpoint group. For example "bdev" for bdev trace group, and 0x1 to enable the first tracepoint inside the group (BDEV_IO_START). This command will not disable already active tracepoints or those not specified in the mask. For a full description of all available trace groups, see tracepoint documentation.
| Name | Optional | Type | Description |
|---|---|---|---|
| name | Required | string | bdev, nvmf_rdma, nvmf_tcp, blobfs, scsi, iscsi_conn, ftl |
| tpoint_mask | Required | number | mask to enable tracepoints inside a group |
Example request:
Example response:
Disable tracepoint mask on a specific tpoint group. For example "bdev" for bdev trace group, and 0x1 to disable the first tracepoint inside the group (BDEV_IO_START). For a full description of all available trace groups, see tracepoint documentation.
| Name | Optional | Type | Description |
|---|---|---|---|
| name | Required | string | bdev, nvmf_rdma, nvmf_tcp, blobfs, scsi, iscsi_conn, ftl |
| tpoint_mask | Required | number | mask to diesable tracepoints inside a group |
Example request:
Example response:
Display mask info for every group.
No parameters required
Example request:
Example response:
Get name of shared memory file, list of the available trace point groups and mask of the available trace points for each group
No parameters required
Example request:
Example response:
Set the current level at which output will additionally be sent to the current console.
| Name | Optional | Type | Description |
|---|---|---|---|
| level | Required | string | ERROR, WARNING, NOTICE, INFO, DEBUG |
Example request:
Example response:
Get the current level at which output will additionally be sent to the current console.
Example request:
Example response:
Set the current logging level output by the log module.
| Name | Optional | Type | Description |
|---|---|---|---|
| level | Required | string | ERROR, WARNING, NOTICE, INFO, DEBUG |
Example request:
Example response:
Get the current logging level output by the log module.
Example request:
Example response:
Enable logging for specific portions of the application. The list of possible log flags can be obtained using the log_get_flags RPC and may be different for each application.
| Name | Optional | Type | Description |
|---|---|---|---|
| flag | Required | string | A log flag, or 'all' |
Example request:
Example response:
Disable logging for specific portions of the application. The list of possible log flags can be obtained using the log_get_flags RPC and may be different for each application.
| Name | Optional | Type | Description |
|---|---|---|---|
| flag | Required | string | A log flag, or 'all' |
Example request:
Example response:
Get the list of valid flags for this application and whether they are currently enabled.
Example request:
Example response:
Enable or disable timestamps.
| Name | Optional | Type | Description |
|---|---|---|---|
| enabled | Required | boolean | on or off |
Example request:
Example response:
Retrieve current pollers of all the threads.
This method has no parameters.
The response is an array of objects containing pollers of all the threads.
Example request:
Example response:
Retrieve current IO channels of all the threads.
This method has no parameters.
The response is an array of objects containing IO channels of all the threads.
Example request:
Example response:
Write the dpdk memory stats to a file.
This method has no parameters.
The response is a pathname to a text file containing the memory stats.
Example request:
Example response:
Get a list of valid module names and their supported operations.
None
Example request:
Example response:
Get a list of opcode names and their assigned accel_fw modules.
None
Example request:
Example response:
Manually assign an operation to a module.
| Name | Optional | Type | Description |
|---|---|---|---|
| opname | Required | string | name of operation |
| module | Required | string | name of module |
Example request:
Example response:
Create a crypto key which will be used in accel framework
| Name | Optional | Type | Description |
|---|---|---|---|
| cipher | Required | string | crypto cipher to use |
| key | Required | string | Key in hex form |
| key2 | Optional | string | Optional 2nd part of the key or a tweak in hex form |
| tweak_mode | Optional | string | Tweak mode to use: SIMPLE_LBA, JOIN_NEG_LBA_WITH_LBA, INCR_512_FULL_LBA, INCR_512_UPPER_LBA. Default is SIMPLE_LBA |
| name | Required | string | The key name |
Example request:
Example response:
Destroy a crypto key. The user is responsible for ensuring that the deleted key is not used by acceleration modules.
| Name | Optional | Type | Description |
|---|---|---|---|
| name | Required | string | The key name |
Example request:
Example response:
Get information about existing crypto keys
| Name | Optional | Type | Description |
|---|---|---|---|
| key_name | Optional | string | If specified, return info about a specific key |
Example request:
Example response:
Select platform driver to execute operation chains. Until a driver is selected, all operations are executed through accel modules.
| Name | Optional | Type | Description |
|---|---|---|---|
| name | Required | string | Name of the platform driver |
Example request:
Example response:
Set accel framework's options.
| Name | Optional | Type | Description |
|---|---|---|---|
| small_cache_size | Optional | number | Size of the small iobuf cache |
| large_cache_size | Optional | number | Size of the large iobuf cache |
| task_count | Optional | number | Maximum number of tasks per IO channel |
| sequence_count | Optional | number | Maximum number of sequences per IO channel |
| buf_count | Optional | number | Maximum number of accel buffers per IO channel |
Example request:
Example response:
Retrieve accel framework's statistics. Statistics for opcodes that have never been executed (i.e. all their stats are at 0) aren't included in the operations array.
None.
Example request:
Example response:
Inject an error to execution of a given operation. Note, that in order for the errors to be actually injected, the error module must be assigned to that operation via accel_assign_opc.
| Name | Optional | Type | Description |
|---|---|---|---|
| opcode | Required | string | Operation to inject errors. |
| type | Required | string | Type of errors to inject ("corrupt": corrupt the data, "failure": fail the operation, "disable": disable error injection). |
| count | Optional | number | Numbers of errors to inject on each IO channel (UINT64_MAX by default). |
| interval | Optional | number | Interval between injections. |
| errcode | Optional | number | Error code to inject (only relevant for type=failure). |
Example request:
Example response:
Set config and enable compressdev accel module offload. Select the DPDK polled mode driver (pmd) for the accel compress module, 0 = auto-select, 1= QAT only, 2 = mlx5_pci only.
| Name | Optional | Type | Description |
|---|---|---|---|
| pmd | Required | int | pmd selection |
Example request:
Example response:
Set config and enable dsa accel module offload. This feature is considered as experimental.
| Name | Optional | Type | Description |
|---|---|---|---|
| config_kernel_mode | Optional | Boolean | If set, will use kernel idxd driver. |
Example request:
Example response:
Enable IAA accel module offload. This feature is considered as experimental.
None
Example request:
Example response:
Enable ioat accel module offload.
None
Example request:
Example response:
Enable dpdk_cryptodev accel offload
None
Example request:
Example response:
Set the DPDK cryptodev driver
| Name | Optional | Type | Description |
|---|---|---|---|
| crypto_pmd | Required | string | The driver, can be one of crypto_aesni_mb, crypto_qat or mlx5_pci |
Example request:
Example response:
Get the DPDK cryptodev driver
None
Example request:
Example response:
Enable mlx5 accel offload
| Name | Optional | Type | Description |
|---|---|---|---|
| qp_size | Optional | number | qpair size |
| num_requests | Optional | number | Size of the shared requests pool |
Example request:
Example response:
Set global parameters for the block device (bdev) subsystem. This RPC may only be called before SPDK subsystems have been initialized.
| 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 |
| bdev_auto_examine | Optional | boolean | If set to false, the bdev layer will not examine every disks automatically |
| iobuf_small_cache_size | Optional | number | Size of the small iobuf per thread cache |
| iobuf_large_cache_size | Optional | number | Size of the large iobuf per thread cache |
Example request:
Example response:
Get information about block devices (bdevs).
The user may specify no parameters in order to list all block devices, or a block device may be specified by name. If a timeout is specified, the method will block until a bdev with a specified name appears or the timeout expires. By default, the timeout is zero, meaning the method returns immediately whether the bdev exists or not.
| Name | Optional | Type | Description |
|---|---|---|---|
| name | Optional | string | Block device name |
| timeout | Optional | number | Time (ms) to wait for a bdev with specified name to appear |
The response is an array of objects containing information about the requested block devices.
Example request:
Example response:
Request that the bdev layer examines the given bdev for metadata and creates new bdevs if metadata is found. This is only necessary if auto_examine has been set to false using bdev_set_options. By default, auto_examine is true and bdev examination is automatic.
| Name | Optional | Type | Description |
|---|---|---|---|
| name | Required | string | Block device name |
The response is an array of objects containing I/O statistics of the requested block devices.
Example request:
Example response:
Report when all bdevs have been examined by every bdev module.
None
The response is sent when all bdev modules had a chance to examine every bdev.
Example request:
Example response:
Get I/O statistics of block devices (bdevs).
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 |
| per_channel | Optional | bool | Display per channel data for specified block device. |
The response is an array of objects containing I/O statistics of the requested block devices.
Example request:
Example response:
Reset I/O statistics of block devices (bdevs). Note that if one consumer resets I/O statistics, it affects all other consumers.
The user may specify no parameters in order to reset I/O statistics for all block devices, or a block device may be specified by name.
| Name | Optional | Type | Description |
|---|---|---|---|
| name | Optional | string | Block device name |
| mode | Optional | string | Mode to reset I/O statistics: all, maxmin (default: all) |
Example request:
Example response:
Control whether collecting data for histogram is enabled for specified bdev.
| Name | Optional | Type | Description |
|---|---|---|---|
| name | Required | string | Block device name |
| enable | Required | boolean | Enable or disable histogram on specified device |
| opc | Optional | string | IO type name |
Example request:
Example response:
Get latency histogram for specified bdev.
| Name | Optional | Type | Description |
|---|---|---|---|
| name | Required | string | Block device name |
| Name | Description |
|---|---|
| histogram | Base64 encoded histogram |
| bucket_shift | Granularity of the histogram buckets |
| tsc_rate | Ticks per second |
Example request:
Example response: Note that histogram field is trimmed, actual encoded histogram length is ~80kb.
Set the quality of service rate limit on a bdev.
| 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 request:
Example response:
Enable queue depth tracking on a specified bdev.
| Name | Optional | Type | Description |
|---|---|---|---|
| name | Required | string | Block device name |
| period | Required | int | period (in microseconds).If set to 0, polling will be disabled. |
Example request:
Example response:
Create a new compress bdev on a given base bdev.
| Name | Optional | Type | Description |
|---|---|---|---|
| base_bdev_name | Required | string | Name of the base bdev |
| pm_path | Required | string | Path to persistent memory |
| lb_size | Optional | int | Compressed vol logical block size (512 or 4096) |
Name of newly created bdev.
Example request:
Delete a compressed bdev.
| Name | Optional | Type | Description |
|---|---|---|---|
| name | Required | string | Name of the compress bdev |
Example request:
Example response:
Get a list of compressed volumes that are missing their pmem metadata.
| Name | Optional | Type | Description |
|---|---|---|---|
| name | Optional | string | Name of the compress bdev |
Example request:
Example response:
Create a new crypto bdev on a given base bdev.
| Name | Optional | Type | Description |
|---|---|---|---|
| base_bdev_name | Required | string | Name of the base bdev |
| name | Required | string | Name of the crypto vbdev to create |
| crypto_pmd | Optional | string | Name of the crypto device driver. Obsolete, see accel_crypto_key_create |
| key | Optional | string | Key in hex form. Obsolete, see accel_crypto_key_create |
| cipher | Optional | string | Cipher to use, AES_CBC or AES_XTS (QAT and MLX5). Obsolete, see accel_crypto_key_create |
| key2 | Optional | string | 2nd key in hex form only required for cipher AET_XTS. Obsolete, see accel_crypto_key_create |
| key_name | Optional | string | Name of the key created with accel_crypto_key_create |
Both key and key2 must be passed in the hexlified form. For example, 256bit AES key may look like this: afd9477abf50254219ccb75965fbe39f23ebead5676e292582a0a67f66b88215
Name of newly created bdev.
Example request:
Example response:
Delete a crypto bdev.
| Name | Optional | Type | Description |
|---|---|---|---|
| name | Required | string | Name of the crypto bdev |
Example request:
Example response:
Construct new OCF bdev. Command accepts cache mode that is going to be used. You can find more details about supported cache modes in the OCF documentation
| Name | Optional | Type | Description |
|---|---|---|---|
| name | Required | string | Bdev name to use |
| mode | Required | string | OCF cache mode: wb, wt, pt, wa, wi, wo |
| cache_line_size | Optional | int | OCF cache line size in KiB: 4, 8, 16, 32, 64 |
| cache_bdev_name | Required | string | Name of underlying cache bdev |
| core_bdev_name | Required | string | Name of underlying core bdev |
Name of newly created bdev.
Example request:
Example response:
Delete the OCF bdev
| Name | Optional | Type | Description |
|---|---|---|---|
| name | Required | string | Bdev name |
Example request:
Example response:
Get statistics of chosen OCF block device.
| Name | Optional | Type | Description |
|---|---|---|---|
| name | Required | string | Block device name |
Statistics as json object.
Example request:
Example response:
Reset statistics of chosen OCF block device.
| Name | Optional | Type | Description |
|---|---|---|---|
| name | Required | string | Block device name |
Completion status of reset statistics operation returned as a boolean.
Example request:
Example response:
Get list of OCF devices including unregistered ones.
| Name | Optional | Type | Description |
|---|---|---|---|
| name | Optional | string | Name of OCF vbdev or name of cache device or name of core device |
Array of OCF devices with their current status, along with core and cache bdevs.
Example request:
Example response:
Set new cache mode on OCF bdev.
| Name | Optional | Type | Description |
|---|---|---|---|
| name | Required | string | Bdev name |
| mode | Required | string | OCF cache mode: wb, wt, pt, wa, wi, wo |
New cache mode name.
Example request:
Example response:
Set sequential cutoff parameters on all cores for the given OCF cache device. A brief description of this functionality can be found in OpenCAS documentation.
| Name | Optional | Type | Description |
|---|---|---|---|
| name | Required | string | Bdev name |
| policy | Required | string | Sequential cutoff policy: always, full, never |
| threshold | Optional | int | Activation threshold in KiB |
| promotion_count | Optional | int | Promotion request count |
Example request:
Example response:
Start flushing OCF cache device.
Automatic flushes of dirty data are managed by OCF cleaning policy settings. In addition to that, all dirty data is flushed to core device when there is an attempt to stop caching. On the other hand, this RPC call gives a possibility to flush dirty data manually when there is a need for it, e.g. to speed up the shutdown process when data hasn't been flushed for a long time. This RPC returns immediately, and flush is then being performed in the background. To see the status of flushing operation use bdev_ocf_flush_status.
| Name | Optional | Type | Description |
|---|---|---|---|
| name | Required | string | Bdev name |
Example request:
Example response:
Get flush status of OCF cache device.
Automatic flushes of dirty data are managed by OCF cleaning policy settings. In addition to that, all dirty data is flushed to core device when there is an attempt to stop caching. On the other hand, there is a possibility to flush dirty data manually when there is a need for it, e.g. to speed up the shutdown process when data hasn't been flushed for a long time. This RPC reports if such manual flush is still in progress and if the operation was successful. To start manual flush use bdev_ocf_flush_start.
| Name | Optional | Type | Description |
|---|---|---|---|
| name | Required | string | Bdev name |
Status of OCF cache device flush.
Example request:
Example response:
Construct Malloc bdev
The dif_type parameter can have 0, 1, 2, or 3, and controls the check of the guard tag and the reference tag. If the dif_type is 1, 2, or 3, the malloc bdev compares the guard tag to the CRC-16 computed over the block data. If the dif_type is 1 or 2, the malloc bdev compares the reference tag to the computed reference tag. The computed reference tag for the first block of the I/O is the init_ref_tag of the DIF context, and the computed reference tag is incremented for each subsequent block. If the dif_type is 3, the malloc bdev does not check the reference tag. The application tag is not checked by the malloc bdev because the current block device API does not expose it to the upper layer yet.
| Name | Optional | Type | Description |
|---|---|---|---|
| name | Optional | string | Bdev name to use |
| block_size | Required | number | Data block size in bytes -must be multiple of 512 |
| num_blocks | Required | number | Number of blocks |
| uuid | Optional | string | UUID of new bdev |
| optimal_io_boundary | Optional | number | Split on optimal IO boundary, in number of blocks, default 0 |
| md_size | Optional | number | Metadata size for this bdev (0, 8, 16, 32, 64, or 128). Default is 0. |
| md_interleave | Optional | boolean | Metadata location, interleaved if true, and separated if false. Default is false. |
| dif_type | Optional | number | Protection information type. Parameter –md-size needs to be set along –dif-type. Default=0 - no protection. |
| dif_is_head_of_md | Optional | boolean | Protection information is in the first 8 bytes of metadata. Default=false. |
| physical_block_size | Optional | number | Physical block size of device; must be a power of 2 and at least 512 |
Name of newly created bdev.
Example request:
Example response:
Delete Malloc bdev
| Name | Optional | Type | Description |
|---|---|---|---|
| name | Required | string | Bdev name |
Example request:
Example response:
Construct Null
| Name | Optional | Type | Description |
|---|---|---|---|
| name | Required | 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 for this bdev. Default=0. |
| dif_type | Optional | number | Protection information type. Parameter –md-size needs to be set along –dif-type. Default=0 - no protection. |
| dif_is_head_of_md | Optional | boolean | Protection information is in the first 8 bytes of metadata. Default=false. |
Name of newly created bdev.
Example request:
Example response:
Delete Null.
| Name | Optional | Type | Description |
|---|---|---|---|
| name | Required | string | Bdev name |
Example request:
Example response:
Resize Null.
| Name | Optional | Type | Description |
|---|---|---|---|
| name | Required | string | Bdev name |
| new_size | Required | number | Bdev new capacity in MiB |
Example request:
Example response:
Construct Linux AIO bdev.
| 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 |
| readonly | Optional | boolean | set aio bdev as read-only |
| fallocate | Optional | boolean | Enable UNMAP and WRITE ZEROES support. Intended only for testing purposes due to synchronous syscall. |
| uuid | Optional | string | UUID of new bdev |
Name of newly created bdev.
Example request:
Example response:
Rescan the size of Linux AIO bdev.
| Name | Optional | Type | Description |
|---|---|---|---|
| name | Required | string | Bdev name |
Example request:
Example response:
Delete Linux AIO bdev.
| Name | Optional | Type | Description |
|---|---|---|---|
| name | Required | string | Bdev name |
Example request:
Example response:
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, ctrlr_loss_timeout_sec, reconnect_delay_sec, and fast_io_fail_timeout_sec, are for I/O error resiliency. They can be overridden if they are given by the RPC bdev_nvme_attach_controller.
| 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 |
| timeout_admin_us | Optional | number | Timeout for each admin command, in microseconds. If 0, treat same as io timeouts ('timeout_us') |
| keep_alive_timeout_ms | Optional | number | Keep alive timeout period in milliseconds, default is 10s |
| 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. |
| transport_retry_count | Optional | number | The number of attempts per I/O in the transport layer before an I/O fails. |
| bdev_retry_count | Optional | number | The number of attempts per I/O in the bdev layer before an I/O fails. -1 means infinite retries. |
| transport_ack_timeout | Optional | number | Time to wait ack until retransmission for RDMA or connection close for TCP. Range 0-31 where 0 means use default. |
| ctrlr_loss_timeout_sec | Optional | number | Time to wait until ctrlr is reconnected before deleting ctrlr. -1 means infinite reconnects. 0 means no reconnect. |
| reconnect_delay_sec | Optional | number | Time to delay a reconnect trial. 0 means no reconnect. |
| fast_io_fail_timeout_sec | Optional | number | Time to wait until ctrlr is reconnected before failing I/O to ctrlr. 0 means no such timeout. |
| disable_auto_failback | Optional | boolean | Disable automatic failback. The RPC bdev_nvme_set_preferred_path can be used to do manual failback. |
| generate_uuids | Optional | boolean | Enable generation of UUIDs for NVMe bdevs that do not provide this value themselves. |
| transport_tos | Optional | number | IPv4 Type of Service value. Only applicable for RDMA transport. Default: 0 (no TOS is applied). |
| nvme_error_stat | Optional | boolean | Enable collecting NVMe error counts. |
| rdma_srq_size | Optional | number | Set the size of a shared rdma receive queue. Default: 0 (disabled). |
| io_path_stat | Optional | boolean | Enable collecting I/O stat of each nvme bdev io path. Default: false. |
| allow_accel_sequence | Optional | boolean | Allow NVMe bdevs to advertise support for accel sequences if the controller also supports them. Default: false. |
| rdma_max_cq_size | Optional | number | Set the maximum size of a rdma completion queue. Default: 0 (unlimited) |
| rdma_cm_event_timeout_ms | Optional | number | Time to wait for RDMA CM events. Default: 0 (0 means using default value of driver). |
| dhchap_digests | Optional | list | List of allowed DH-HMAC-CHAP digests. |
| dhchap_dhgroups | Optional | list | List of allowed DH-HMAC-CHAP DH groups. |
Example request:
Example response:
Change settings of the NVMe hotplug feature. If enabled, PCIe NVMe bdevs will be automatically discovered on insertion and deleted on removal.
| Name | Optional | Type | Description |
|---|---|---|---|
| enable | 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 request:
Example response:
Construct NVMe bdev. This RPC can also be used to add additional paths to an existing controller to enable multipathing. This is done by specifying the name parameter as an existing controller. When adding an additional path, the hostnqn, hostsvcid, hostaddr, prchk_reftag, and prchk_guard_arguments must not be specified and are assumed to have the same value as the existing path.
The parameters, ctrlr_loss_timeout_sec, reconnect_delay_sec, and fast_io_fail_timeout_sec, are mutually dependent. If reconnect_delay_sec is non-zero, ctrlr_loss_timeout_sec has to be -1 or not less than reconnect_delay_sec. If reconnect_delay_sec is zero, ctrlr_loss_timeout_sec has to be zero. If fast_io_fail_timeout_sec is not zero, it has to be not less than reconnect_delay_sec and less than ctrlr_loss_timeout_sec if ctrlr_loss_timeout_sec is not -1.
Array of names of newly created bdevs.
| 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 |
| priority | Optional | string | Transport connection priority. Supported by TCP transport with POSIX sock module (see socket(7) man page). |
| 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 |
| hdgst | Optional | bool | Enable TCP header digest |
| ddgst | Optional | bool | Enable TCP data digest |
| fabrics_connect_timeout_us | Optional | number | Timeout for fabrics connect (in microseconds) |
| multipath | Optional | string | Multipathing behavior: disable, failover, multipath. Default is failover. |
| num_io_queues | Optional | number | The number of IO queues to request during initialization. Range: (0, UINT16_MAX + 1], Default is 1024. |
| ctrlr_loss_timeout_sec | Optional | number | Time to wait until ctrlr is reconnected before deleting ctrlr. -1 means infinite reconnects. 0 means no reconnect. |
| reconnect_delay_sec | Optional | number | Time to delay a reconnect trial. 0 means no reconnect. |
| fast_io_fail_timeout_sec | Optional | number | Time to wait until ctrlr is reconnected before failing I/O to ctrlr. 0 means no such timeout. |
| psk | Optional | string | Name of the pre-shared key to be used for TLS (Enables SSL socket implementation for TCP) |
| max_bdevs | Optional | number | The size of the name array for newly created bdevs. Default is 128. |
| dhchap_key | Optional | string | DH-HMAC-CHAP key name. |
| dhchap_ctrlr_key | Optional | string | DH-HMAC-CHAP controller key name. |
| allow_unrecognized_csi | Optional | bool | Allow attaching namespaces with unrecognized command set identifiers. These will only support NVMe passthrough. |
Example request:
Example response:
Get information about NVMe controllers.
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 |
The response is an array of objects containing information about the requested NVMe controllers.
Example request:
Example response:
Detach NVMe controller and delete any associated bdevs. Optionally, If all of the transport ID options are specified, only remove that transport path from the specified controller. If that is the only available path for the controller, this will also result in the controller being detached and the associated bdevs being deleted.
returns true if the controller and bdevs were successfully destroyed or the address was properly removed, false otherwise.
| Name | Optional | Type | Description |
|---|---|---|---|
| name | Required | string | Controller name |
| trtype | Optional | string | NVMe-oF target trtype: rdma or tcp |
| traddr | Optional | 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 |
| hostaddr | Optional | string | NVMe-oF host address: ip |
| hostsvcid | Optional | string | NVMe-oF host svcid: port number |
Example requests:
Example response:
For non NVMe multipath, reset an NVMe controller whose name is given by the name parameter.
For NVMe multipath, an NVMe bdev controller is created and it aggregates multiple NVMe controllers. The name parameter is an NVMe bdev controller name and the cntlid parameter is used to identify an NVMe controller in the NVMe bdev controller. Reset only one NVMe-oF controller if the cntlid parameter is specified, or all NVMe-oF controllers in an NVMe bdev controller if it is omitted.
Returns true if the controller reset was successful, false otherwise.
| Name | Optional | Type | Description |
|---|---|---|---|
| name | Required | string | NVMe controller name (or NVMe bdev controller name for multipath) |
| cntlid | Optional | number | NVMe controller ID (used as NVMe controller name for multipath) |
Example request:
Example response:
For non NVMe multipath, enable an NVMe controller whose name is given by the name parameter.
For NVMe multipath, an NVMe bdev controller is created and it aggregates multiple NVMe controllers. The name parameter is an NVMe bdev controller name and the cntlid parameter is used to identify an NVMe controller in the NVMe bdev controller. Enable only one NVMe-oF controller if the cntlid parameter is specified, or all NVMe-oF controllers in an NVMe bdev controller if it is omitted.
Returns true if the controller enablement was successful or a controller was already enabled, false otherwise.
| Name | Optional | Type | Description |
|---|---|---|---|
| name | Required | string | NVMe controller name (or NVMe bdev controller name for multipath) |
| cntlid | Optional | number | NVMe controller ID (used as NVMe controller name for multipath) |
Example request:
Example response:
For non NVMe multipath, disable an NVMe controller whose name is given by the name parameter.
For NVMe multipath, an NVMe bdev controller is created and it aggregates multiple NVMe controllers. The name parameter is an NVMe bdev controller name and the cntlid parameter is used to identify an NVMe controller in the NVMe bdev controller. Disable only one NVMe-oF controller if the cntlid parameter is specified, or all NVMe-oF controllers in an NVMe bdev controller if it is omitted.
Returns true if the controller disablement was successful or a controller was already disabled, false otherwise.
| Name | Optional | Type | Description |
|---|---|---|---|
| name | Required | string | NVMe controller name (or NVMe bdev controller name for multipath) |
| cntlid | Optional | number | NVMe controller ID (used as NVMe controller name for multipath) |
Example request:
Example response:
Start a discovery service for the discovery subsystem of the specified transport ID.
The discovery service will read the discovery log page for the specified discovery subsystem, and automatically attach to any subsystems found in the log page. When determining a controller name to use when attaching, it will use the 'name' parameter as a prefix, followed by a unique integer for that discovery service. If the discovery service identifies a subsystem that has been previously attached but is listed with a different path, it will use the same controller name as the previous entry, and connect as a multipath.
When the discovery service sees that a subsystem entry has been removed from the log page, it will automatically detach from that controller as well.
The 'name' is also used to later stop the discovery service.
| Name | Optional | Type | Description |
|---|---|---|---|
| name | Required | string | Prefix for NVMe controllers |
| trtype | Required | string | NVMe-oF target trtype: rdma or tcp |
| traddr | Required | string | NVMe-oF target address: ip |
| adrfam | Optional | string | NVMe-oF target adrfam: ipv4, ipv6 |
| trsvcid | Optional | string | NVMe-oF target trsvcid: port number |
| hostnqn | Optional | string | NVMe-oF target hostnqn |
| wait_for_attach | Optional | bool | Wait to complete until all discovered NVM subsystems are attached |
| attach_timeout_ms | Optional | number | Time to wait until the discovery and all discovered NVM subsystems are attached |
| ctrlr_loss_timeout_sec | Optional | number | Time to wait until ctrlr is reconnected before deleting ctrlr. -1 means infinite reconnects. 0 means no reconnect. |
| reconnect_delay_sec | Optional | number | Time to delay a reconnect trial. 0 means no reconnect. |
| fast_io_fail_timeout_sec | Optional | number | Time to wait until ctrlr is reconnected before failing I/O to ctrlr. 0 means no such timeout. |
Example request:
Example response:
Stop a discovery service. This includes detaching any controllers that were discovered via the service that is being stopped.
| Name | Optional | Type | Description |
|---|---|---|---|
| name | Required | string | Name of service to stop |
Example request:
Example response:
Get information about the discovery service.
Example request:
Example response:
Display all or the specified NVMe bdev's active I/O paths.
| Name | Optional | Type | Description |
|---|---|---|---|
| name | Optional | string | Name of the NVMe bdev |
Example request:
Example response:
Set the preferred I/O path for an NVMe bdev in multipath mode.
NOTE: This RPC does not support NVMe bdevs in failover mode.
| Name | Optional | Type | Description |
|---|---|---|---|
| name | Required | string | Name of the NVMe bdev |
| cntlid | Required | number | NVMe-oF controller ID |
Example request:
Example response:
Set multipath policy of the NVMe bdev in multipath mode or set multipath selector for active-active multipath policy.
| Name | Optional | Type | Description |
|---|---|---|---|
| name | Required | string | Name of the NVMe bdev |
| policy | Required | string | Multipath policy: active_active or active_passive |
| selector | Optional | string | Multipath selector: round_robin or queue_depth, used in active-active mode. Default is round_robin |
| rr_min_io | Optional | number | Number of I/Os routed to current io path before switching to another for round-robin selector. The min value is 1. |
Example request:
Example response:
Get I/O statistics for IO paths of the block device. Call RPC bdev_nvme_set_options to set enable_io_path_stat true before using this RPC.
| Name | Optional | Type | Description |
|---|---|---|---|
| name | Required | string | Name of the NVMe bdev |
Example request:
Example response:
Register CUSE device on NVMe controller.
| Name | Optional | Type | Description |
|---|---|---|---|
| name | Required | string | Name of the NVMe controller |
Example request:
Example response:
Unregister CUSE device on NVMe controller.
| Name | Optional | Type | Description |
|---|---|---|---|
| name | Required | string | Name of the NVMe controller |
Example request:
Example response:
Creates a virtual zone device on top of existing non-zoned bdev.
| Name | Optional | Type | Description |
|---|---|---|---|
| name | Required | string | Name of the Zone device |
| base_bdev | Required | string | Name of the Base bdev |
| zone_capacity | Required | number | Zone capacity in blocks |
| optimal_open_zones | Required | number | Number of zones required to reach optimal write speed |
Example request:
Example response:
Deletes a virtual zone device.
| Name | Optional | Type | Description |
|---|---|---|---|
| name | Required | string | Name of the Zone device |
Example request:
Example response:
Download and commit firmware to NVMe device.
| Name | Optional | Type | Description |
|---|---|---|---|
| filename | Required | string | filename of the firmware to download |
| bdev_name | Required | string | Name of the NVMe block device |
Example request:
Get bdev_nvme poll group transport statistics.
This RPC method accepts no parameters
The response is an array of objects containing information about transport statistics per NVME poll group.
Example request:
Example response:
Display health log of the required NVMe bdev device.
| Name | Optional | Type | Description |
|---|---|---|---|
| name | Required | string | Name of the NVMe bdev controller |
The response is the object containing information about health log of the NVMe controller.
Example request:
Example response:
This method is available only if SPDK was build with Ceph RBD support.
| Name | Optional | Type | Description |
|---|---|---|---|
| name | Optional | string | Registered Rados cluster object name |
| user_id | Optional | string | Ceph ID (i.e. admin, not client.admin) |
| config_param | Optional | string map | Explicit librados configuration |
| config_file | Optional | string | File path of librados configuration file |
| key_file | Optional | string | File path of librados key file |
| core_mask | Optional | string | Core mask for librados IO context threads |
This RPC registers a Rados Cluster object handle which is only known to rbd module, it uses user_id + config_param or user_id + config_file + key_file or user_id + config_param + config_file + key_file to identify a Rados cluster object.
When accessing the Ceph cluster as some user other than "admin" (the default), the "user_id" has to be set.
The configuration items and secret key can be specified by setting config_param, config_file and key_file, all of them, or none of them. If only config_param is passed, 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. If config_file and key_file are specified, they must exist with all relevant settings for accessing the Ceph cluster. If config_param, config_file and key_file are specified, get the key/value pairs from config_file first and set to rados_conf_set function, then set pairs in config_param and keyring in key_file. If nothing is specified, it will get configuration file and key file from the default location /etc/ceph/ceph.conf and /etc/ceph/ceph.client.user_id.keyring.
Name of newly created Rados cluster object.
Example request:
~~ { "params": { "name": "rbd_cluster", "user_id": cinder, "config_file": "/root/ceph_conf/ceph.conf", "key_file": "/root/ceph_conf/ceph.client.cinder.keyring" }, "jsonrpc": "2.0", "method": "bdev_rbd_register_cluster", "id": 1 } ~~
Example response:
~~ response: { "jsonrpc": "2.0", "id": 1, "result": "rbd_cluster" } ~~
This method is available only if SPDK was build with Ceph RBD support. If there is still rbd bdev using this cluster, the unregisteration operation will fail.
true if Rados cluster object with provided name was deleted or false otherwise.
| Name | Optional | Type | Description |
|---|---|---|---|
| name | Required | string | Rados cluster object name |
Example request:
~~ { "params": { "name": "rbd_cluster" }, "jsonrpc": "2.0", "method": "bdev_rbd_unregister_cluster", "id": 1 } ~~
Example response:
~~ { "jsonrpc": "2.0", "id": 1, "result": true } ~~
This method is available only if SPDK was build with Ceph RBD support.
Returns the cluster info of the Rados Cluster name if provided. Otherwise, it returns the cluster info of every registered Raods Cluster name.
| Name | Optional | Type | Description |
|---|---|---|---|
| name | Optional | string | Rados cluster object name |
Example request:
~~ { "params": { "name": "rbd_cluster" }, "jsonrpc": "2.0", "method": "bdev_rbd_get_clusters_info", "id": 1 } ~~
Example response:
~~ { "jsonrpc": "2.0", "cluster_name": "rbd_cluster" } ~~
Create Ceph RBD bdev
This method is available only if SPDK was build with Ceph RBD support.
| 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 |
| cluster_name | Optional | string | Rados cluster object name created in this module. |
| uuid | Optional | string | UUID of new bdev |
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.
If provided with cluster_name option, it will use the Rados cluster object referenced by the name (created by bdev_rbd_register_cluster RPC) and ignores "user_id + config" combination to create its own Rados cluster. In this scenario, all the bdevs will share the same cluster with one connection of Ceph in librbd module. Performance tuning on the I/O workload could be done by estimating how many io_contxt threads and messager threads in Ceph side and how many cores would be reasonable to provide for SPDK to get up to your projections.
Name of newly created bdev.
Example request with key from /etc/ceph/ceph.client.admin.keyring:
Example response:
Example request with cluster_name:
~~ { "params": { "pool_name": "rbd", "rbd_name": "foo", "block_size": 4096, "cluster_name": "rbd_cluster" }, "jsonrpc": "2.0", "method": "bdev_rbd_create", "id": 1 } ~~
Example response:
~~ response: { "jsonrpc": "2.0", "id": 1, "result": "Ceph0" } ~~
Delete Ceph RBD bdev
This method is available only if SPDK was build with Ceph RBD support.
true if bdev with provided name was deleted or false otherwise.
| Name | Optional | Type | Description |
|---|---|---|---|
| name | Required | string | Bdev name |
Example request:
Example response:
Resize Ceph RBD bdev
This method is available only if SPDK was build with Ceph RBD support.
true if bdev with provided name was resized or false otherwise.
| Name | Optional | Type | Description |
|---|---|---|---|
| name | Required | string | Bdev name |
| new_size | Required | int | New bdev size for resize operation in MiB |
Example request:
Example response:
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.
| 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) |
| uuid | Optional | string | UUID of new bdev |
Name of newly created bdev.
Example request:
Example response:
Delete delay bdev.
| Name | Optional | Type | Description |
|---|---|---|---|
| name | Required | string | Bdev name |
Example request:
Example response:
Update a target latency value associated with a given delay bdev. Any currently outstanding I/O will be completed with the old latency.
| 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 |
Name of newly created bdev.
Example request:
Example response:
Construct error bdev.
| Name | Optional | Type | Description |
|---|---|---|---|
| base_name | Required | string | Base bdev name |
| uuid | Optional | string | UUID for this bdev |
Example request:
Example response:
Delete error bdev
true if bdev with provided name was deleted or false otherwise.
| Name | Optional | Type | Description |
|---|---|---|---|
| name | Required | string | Error bdev name |
Example request:
Example response:
Inject an error via an error bdev. Create an error bdev on base bdev first. Default 'num' value is 1 and if 'num' is set to zero, the specified injection is disabled.
| Name | Optional | Type | Description |
|---|---|---|---|
| name | Required | string | Name of the error injection bdev |
| io_type | Required | string | io type 'clear' 'read' 'write' 'unmap' 'flush' 'all' |
| error_type | Required | string | error type 'failure' 'pending' 'corrupt_data' 'nomem' |
| num | Optional | int | the number of commands you want to fail.(default:1) |
| queue_depth | Optional | int | the queue depth at which to trigger the error |
| corrupt_offset | Optional | int | the offset in bytes to xor with corrupt_value |
| corrupt_value | Optional | int | the value for xor (1-255, 0 is invalid) |
Example request:
Example response:
This RPC can be called at any time, but the new value will only take effect for new iSCSI bdevs.
| Name | Optional | Type | Description |
|---|---|---|---|
| timeout_sec | Optional | number | Timeout for command, in seconds, if 0, don't track timeout |
Example request:
Example response:
Connect to iSCSI target and create bdev backed by this connection.
This method is available only if SPDK was build with iSCSI initiator support.
| Name | Optional | Type | Description |
|---|---|---|---|
| name | Required | string | Bdev name |
| initiator_iqn | Required | string | IQN name used during connection |
| url | Required | string | iSCSI resource URI |
Name of newly created bdev.
Example request:
Example response:
Delete iSCSI bdev and terminate connection to target.
This method is available only if SPDK was built with iSCSI initiator support.
| Name | Optional | Type | Description |
|---|---|---|---|
| name | Required | string | Bdev name |
Example request:
Example response:
Create FTL bdev.
This RPC is subject to change.
| Name | Optional | Type | Description |
|---|---|---|---|
| name | Required | string | Bdev name |
| base_bdev | Required | string | Name of the base device |
| cache | Required | string | Name of the cache device |
| uuid | Optional | string | UUID of restored bdev (not applicable when creating new instance) |
| core_mask | Optional | string | CPU core(s) possible for placement of the ftl core thread, application main thread by default |
| overprovisioning | Optional | int | Percentage of base device used for relocation, 20% by default |
| fast_shutdown | Optional | bool | When set FTL will minimize persisted data on target application shutdown and rely on shared memory during next load |
| l2p_dram_limit | Optional | int | DRAM limit for most recent L2P addresses (default 2048 MiB) |
Name of newly created bdev.
Example request:
Example response:
Loads FTL bdev.
This RPC is subject to change.
| Name | Optional | Type | Description |
|---|---|---|---|
| name | Required | string | Bdev name |
| base_bdev | Required | string | Name of the base device |
| cache | Required | string | Name of the cache device |
| uuid | Required | string | UUID of restored bdev |
| core_mask | Optional | string | CPU core(s) possible for placement of the ftl core thread, application main thread by default |
| overprovisioning | Optional | int | Percentage of base device used for relocation, 20% by default |
| fast_shutdown | Optional | bool | When set FTL will minimize persisted data on target application shutdown and rely on shared memory during next load |
| l2p_dram_limit | Optional | int | DRAM limit for most recent L2P addresses (default 2048 MiB) |
Name of loaded bdev.
Example request:
Example response:
Delete FTL bdev.
This RPC is subject to change.
| Name | Optional | Type | Description |
|---|---|---|---|
| name | Required | string | Bdev name |
| fast_shutdown | Optional | bool | When set FTL will minimize persisted data during deletion and rely on shared memory during next load |
Example request:
Example response:
Unloads FTL bdev.
This RPC is subject to change.
| Name | Optional | Type | Description |
|---|---|---|---|
| name | Required | string | Bdev name |
| fast_shutdown | Optional | bool | When set FTL will minimize persisted data during deletion and rely on shared memory during next load |
Example request:
Example response:
Unmap range of LBAs.
This RPC is subject to change.
| Name | Optional | Type | Description |
|---|---|---|---|
| name | Required | string | Bdev name |
| lba | Required | number | start lba, aligned to 1024 |
| num_blocks | Required | number | number of blocks, aligned to 1024 |
Example request:
Example response:
Get IO statistics for FTL bdev
This RPC is subject to change.
| Name | Optional | Type | Description |
|---|---|---|---|
| name | Required | string | Bdev name |
The response is an object containing IO statistics for an FTL instance, split into multiple subobjects:
user - contains information about number of IOs, and errors for any incoming requests,cmp - information about IO for the compaction process,gc - information about IO for the garbage collection process,md_base - internal metadata requests to the base FTL device,md_nv_cache - internal metadata requests to the cache device,l2p - requests done on the L2P cache region.Each subobject contains the following information:
ios - describes the total number of IOs requested,blocks - the total number of requested blocks,errors - describes the number of detected errors for a given operation, with the following distinctions:media - media errors,crc - mismatch in calculated CRC versus saved checksum in the metadata,other - any other errors.Example request:
Example response:
Get FTL properties
| Name | Optional | Type | Description |
|---|---|---|---|
| name | Required | string | Bdev name |
The response contains FTL bdev properties. Some of them can be modified, other reported as read only.
Example request:
Example response:
Set FTL property. Trying to set a read-only property will result in an error.
| Name | Optional | Type | Description |
|---|---|---|---|
| name | Required | string | Bdev name |
| property | Required | string | Name of the property to modify |
| value | Required | string | New value of the property to be set |
Example request:
Example response:
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.
| Name | Optional | Type | Description |
|---|---|---|---|
| name | Required | string | Bdev name |
| base_bdev_name | Required | string | Base bdev name |
| uuid | Optional | string | UUID of new bdev |
Name of newly created bdev.
Example request:
Example response:
Delete passthru bdev.
| Name | Optional | Type | Description |
|---|---|---|---|
| name | Required | string | Bdev name |
Example request:
Example response:
Create xnvme bdev. This bdev type redirects all IO to its underlying backend.
| Name | Optional | Type | Description |
|---|---|---|---|
| name | Required | string | name of xNVMe bdev to create |
| filename | Required | string | path to device or file (ex: /dev/nvme0n1) |
| io_mechanism | Required | string | IO mechanism to use (ex: libaio, io_uring, io_uring_cmd, etc.) |
| conserve_cpu | Optional | boolean | Whether or not to conserve CPU when polling (default: false) |
Name of newly created bdev.
Example request:
Example response:
Delete xnvme bdev.
| Name | Optional | Type | Description |
|---|---|---|---|
| name | Required | string | name of xnvme bdev to delete |
Example request:
Example response:
Create new initiator Virtio SCSI or Virtio Block and expose all found bdevs.
| 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.
Array of names of newly created bdevs.
Example request:
Example response:
Show information about all available Virtio SCSI devices.
This method has no parameters.
Array of Virtio SCSI information objects.
Example request:
Example response:
Remove a Virtio device. This command can be used to remove any type of virtio device.
| Name | Optional | Type | Description |
|---|---|---|---|
| name | Required | string | Virtio name |
Example request:
Example response:
Enable/Disable the virtio blk hotplug monitor or change the monitor period time
| Name | Optional | Type | Description |
|---|---|---|---|
| enable | Required | bool | Enable or disable the virtio blk hotplug monitor |
| period-us | Optional | number | The period time of the monitor |
When the enable is true then the period-us is optional. If user don't set the period time then use the default value. When the enable is false then the period-us is not required.
True the rpc is successful otherwise false
Example request:
Example response:
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.
| 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) |
| max_large_datain_per_connection | Optional | number | Max number of outstanding split read I/Os per connection (default: 64) |
| max_r2t_per_connection | Optional | number | Max number of outstanding R2Ts per connection (default: 4) |
| pdu_pool_size | Optional | number | Number of PDUs in the pool (default: approximately 2 * max_sessions * (max_queue_depth + max_connections_per_session)) |
| immediate_data_pool_size | Optional | number | Number of immediate data buffers in the pool (default: 128 * max_sessions) |
| data_out_pool_size | Optional | number | Number of data out buffers in the pool (default: 16 * max_sessions) |
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 request:
Example response:
Show global parameters of iSCSI targets.
This method has no parameters.
Example request:
Example response:
Display SCSI devices
This method has no parameters.
Example request:
Example response:
Set CHAP authentication for sessions dynamically.
| 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 request:
Example response:
Create an authentication group for CHAP authentication.
| Name | Optional | Type | Description |
|---|---|---|---|
| tag | Required | number | Authentication group tag (unique, integer > 0) |
| secrets | Optional | array | Array of secret objects |
| 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 request:
Example response:
Delete an existing authentication group for CHAP authentication.
| Name | Optional | Type | Description |
|---|---|---|---|
| tag | Required | number | Authentication group tag (unique, integer > 0) |
Example request:
Example response:
Show information about all existing authentication group for CHAP authentication.
This method has no parameters.
Array of objects describing authentication group.
| Name | Type | Description |
|---|---|---|
| tag | number | Authentication group tag |
| secrets | array | Array of secret objects |
Example request:
Example response:
Add a secret to an existing authentication group for CHAP authentication.
| 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 request:
json
Example response:
Remove a secret from an existing authentication group for CHAP authentication.
| Name | Optional | Type | Description |
|---|---|---|---|
| tag | Required | number | Authentication group tag (unique, integer > 0) |
| user | Required | string | Unidirectional CHAP name |
Example request:
Example response:
Show information about all available initiator groups.
This method has no parameters.
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 request:
Example response:
Add an initiator group.
| 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 request:
Example response:
Delete an existing initiator group.
| Name | Optional | Type | Description |
|---|---|---|---|
| tag | Required | number | Initiator group tag (unique, integer > 0) |
Example request:
Example response:
Add initiators to an existing initiator group.
| 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 request:
Example response:
Remove initiators from an initiator group.
| 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 request:
Example response:
Show information about all available iSCSI target nodes.
This method has no parameters.
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 request:
Example response:
Add an iSCSI target node.
| 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 request:
Example response:
Set CHAP authentication to an existing iSCSI target node.
| 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 request:
Example response:
Add initiator group to portal group mappings to an existing iSCSI target node.
| 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 request:
Example response:
Delete initiator group to portal group mappings from an existing iSCSI target node.
| 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 request:
Example response:
Delete an iSCSI target node.
| Name | Optional | Type | Description |
|---|---|---|---|
| name | Required | string | Target node name (ASCII) |
Example request:
Example response:
Show information about all available portal groups.
This method has no parameters.
Example request:
Example response:
Add a portal group.
| Name | Optional | Type | Description |
|---|---|---|---|
| tag | Required | number | Portal group tag |
| portals | Required | array | Not empty array of portals |
| private | Optional | boolean | When true, portals in this group are not returned by a discovery session. Used for login redirection. (default: false) |
| wait | Optional | boolean | When true, do not listen on portals until it is started explicitly. (default: false) |
Portal object
| Name | Optional | Type | Description |
|---|---|---|---|
| host | Required | string | Hostname or IP address |
| port | Required | string | Port number |
Example request:
Example response:
Start listening on portals if the portal group is not started yet, or do nothing if the portal group already started. Return a success response for both cases.
| Name | Optional | Type | Description |
|---|---|---|---|
| tag | Required | number | Existing portal group tag |
Example request:
Example response:
Delete an existing portal group.
| Name | Optional | Type | Description |
|---|---|---|---|
| tag | Required | number | Existing portal group tag |
Example request:
Example response:
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.
| 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 request:
Example response:
Show information about all active connections.
This method has no parameters.
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 request:
Example response:
Show stat information of iSCSI connections.
This method has no parameters.
Stat information of iSCSI connections.
| Name | Type | Description |
|---|---|---|
| invalid | number | The number of invalid connections |
| running | number | The number of running connections |
| exiting | number | The number of exiting connections |
| exited | number | The number of exited connections |
Example request:
Example response:
Add an LUN to an existing iSCSI target node.
| 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 request:
Example response:
Update redirect portal of the primary portal group for the target node,
| Name | Optional | Type | Description |
|---|---|---|---|
| name | Required | string | Target node name (ASCII) |
| pg_tag | Required | number | Existing portal group tag |
| redirect_host | Optional | string | Numeric IP address to which the target node is redirected |
| redirect_port | Optional | string | Numeric TCP port to which the target node is redirected |
If both redirect_host and redirect_port are omitted, clear the redirect portal.
Example request:
Example response:
For the target node, request connections whose portal group tag match to logout, or request all connections to logout if portal group tag is omitted.
| Name | Optional | Type | Description |
|---|---|---|---|
| name | Required | string | Target node name (ASCII) |
| pg_tag | Optional | number | Existing portal group tag |
Example request:
Example response:
Control whether collecting data for histogram is enabled for specified iscsi target node.
| Name | Optional | Type | Description |
|---|---|---|---|
| name | Required | string | Iscsi target node name |
| enable | Required | boolean | Enable or disable histogram on specified target node |
Example request:
Example response:
Get latency histogram for specified iscsi target node.
| Name | Optional | Type | Description |
|---|---|---|---|
| name | Required | string | Iscsi target node name |
| Name | Description |
|---|---|
| histogram | Base64 encoded histogram |
| bucket_shift | Granularity of the histogram buckets |
| tsc_rate | Ticks per second |
Example request:
Example response: Note that histogram field is trimmed, actual encoded histogram length is ~80kb.
Initialize an NVMe-oF transport with the given options.
| 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_io_qpairs_per_ctrlr | Optional | number | Max number of IO qpairs 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 |
| num_cqe | Optional | number | The number of CQ entries. Only used when no_srq=true (RDMA only) |
| 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 |
| sock_priority | Optional | number | The socket priority of the connection owned by this transport (TCP only) |
| acceptor_backlog | Optional | number | The number of pending connections allowed in backlog before failing new connection attempts (RDMA only) |
| abort_timeout_sec | Optional | number | Abort execution timeout value, in seconds |
| no_wr_batching | Optional | boolean | Disable work requests batching (RDMA only) |
| control_msg_num | Optional | number | The number of control messages per poll group (TCP only) |
| disable_mappable_bar0 | Optional | boolean | disable client mmap() of BAR0 (VFIO-USER only) |
| disable_adaptive_irq | Optional | boolean | Disable adaptive interrupt feature (VFIO-USER only) |
| disable_shadow_doorbells | Optional | boolean | disable shadow doorbell support (VFIO-USER only) |
| zcopy | Optional | boolean | Use zero-copy operations if the underlying bdev supports them |
| ack_timeout | Optional | number | ACK timeout in milliseconds |
| data_wr_pool_size | Optional | number | RDMA data WR pool size (RDMA only) |
| disable_command_passthru | Optional | boolean | Disallow command passthru. |
Example request:
Example response:
| Name | Optional | Type | Description |
|---|---|---|---|
| tgt_name | Optional | string | Parent NVMe-oF target name. |
Example request:
Example response:
Construct an NVMe over Fabrics target subsystem.
| 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: 32 (also used if user specifies 0) |
| allow_any_host | Optional | boolean | Allow any host (true) or enforce allowed host list (false). Default: false. |
| ana_reporting | Optional | boolean | Enable ANA reporting feature (default: false). |
| min_cntlid | Optional | number | Minimum controller ID. Default: 1 |
| max_cntlid | Optional | number | Maximum controller ID. Default: 0xffef |
| max_discard_size_kib | Optional | number | Maximum discard size (Kib). Default: 0 |
| max_write_zeroes_size_kib | Optional | number | Maximum write_zeroes size (Kib). Default: 0 |
| passthrough | Optional | boolean | Use NVMe passthrough for I/O commands and namespace-directed admin commands. Default: false. |
Example request:
Example response:
Delete an existing NVMe-oF subsystem.
| Parameter | Optional | Type | Description |
|---|---|---|---|
| nqn | Required | string | Subsystem NQN to delete. |
| tgt_name | Optional | string | Parent NVMe-oF target name. |
Example request:
Example response:
Add a new listen address to an NVMe-oF subsystem.
This method will fail if listener with given address already exists.
| Name | Optional | Type | Description |
|---|---|---|---|
| nqn | Required | string | Subsystem NQN |
| tgt_name | Optional | string | Parent NVMe-oF target name. |
| listen_address | Required | object | listen_address object |
| secure_channel | Optional | bool | Whether all connections immediately attempt to establish a secure channel |
| sock_impl | Optional | string | The socket implementation to use for the listener |
The listen_address is used for adding the listeners to the NVMe-oF target and for referring to discovery services on other targets.
| Name | Optional | Type | Description |
|---|---|---|---|
| trtype | Required | string | Transport type ("RDMA") |
| adrfam | Optional | string | Address family ("IPv4", "IPv6", "IB", or "FC") |
| traddr | Required | string | Transport address |
| trsvcid | Optional | string | Transport service ID (required for RDMA or TCP) |
Example request:
Example response:
Remove a listen address from an NVMe-oF subsystem.
| Name | Optional | Type | Description |
|---|---|---|---|
| nqn | Required | string | Subsystem NQN |
| tgt_name | Optional | string | Parent NVMe-oF target name. |
| listen_address | Required | object | listen_address object |
Example request:
Example response:
Set ANA state of a listener for an NVMe-oF subsystem. Only the ANA state of the specified ANA group is updated, or ANA states of all ANA groups if ANA group is not specified.
| Name | Optional | Type | Description |
|---|---|---|---|
| nqn | Required | string | Subsystem NQN |
| tgt_name | Optional | string | Parent NVMe-oF target name. |
| listen_address | Required | object | listen_address object |
| ana_state | Required | string | ANA state to set ("optimized", "non_optimized", or "inaccessible") |
| anagrpid | Optional | number | ANA group ID |
Example request:
Example response:
Add a namespace to a subsystem. The namespace ID is returned as the result.
| Name | Optional | Type | Description |
|---|---|---|---|
| nqn | Required | string | Subsystem NQN |
| namespace | Required | object | namespace object |
| tgt_name | Optional | string | Parent NVMe-oF target name. |
| no_auto_visible | Optional | bool | Namespace is not automatically visible to controllers (default: false) |
| 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 |
| anagrpid | Optional | number | ANA group ID. Default: Namespace ID. |
Example request:
Example response:
Remove a namespace from a subsystem.
| Name | Optional | Type | Description |
|---|---|---|---|
| nqn | Required | string | Subsystem NQN |
| nsid | Required | number | Namespace ID |
| tgt_name | Optional | string | Parent NVMe-oF target name. |
Example request:
Example response:
Add a host NQN to the list of allowed hosts. Adding an already allowed host will result in an error.
| 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. |
| psk | Optional | string | Path to a file containing PSK for TLS connection |
| dhchap_key | Optional | string | DH-HMAC-CHAP key name. |
| dhchap_ctrlr_key | Optional | string | DH-HMAC-CHAP controller key name. |
Example request:
Example response:
Remove a host NQN from the list of allowed hosts.
| 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 request:
Example response:
Configure a subsystem to allow any host to connect or to enforce the host NQN list.
| Name | Optional | Type | Description |
|---|---|---|---|
| nqn | Required | string | Subsystem NQN |
| allow_any_host | Required | boolean | Allow any host (true) or enforce allowed host list (false). |
| tgt_name | Optional | string | Parent NVMe-oF target name. |
Example request:
Example response:
| Name | Optional | Type | Description |
|---|---|---|---|
| nqn | Required | string | Subsystem NQN |
| tgt_name | Optional | string | Parent NVMe-oF target name. |
Example request:
Example response:
| Name | Optional | Type | Description |
|---|---|---|---|
| nqn | Required | string | Subsystem NQN |
| tgt_name | Optional | string | Parent NVMe-oF target name. |
Example request:
Example response:
| Name | Optional | Type | Description |
|---|---|---|---|
| nqn | Required | string | Subsystem NQN |
| tgt_name | Optional | string | Parent NVMe-oF target name. |
Example request:
Example response:
Make the specified namespace of the specified subnqn visible to any existing or future controllers with the specified hostnqn.
Note: the namespace must have been added with no_auto_visible = false (see nvmf_subsystem_add_ns method).
| Name | Optional | Type | Description |
|---|---|---|---|
| nqn | Required | string | Subsystem NQN |
| nsid | Required | number | Namespace ID |
| host | Required | string | Host NQN |
Example request:
Example response:
Make the specified namespace of the specified subnqn not visible to any existing or future controllers with the specified hostnqn.
Note: the namespace must have been added to the subsystem with no_auto_visible = false (see nvmf_subsystem_add_ns method).
| Name | Optional | Type | Description |
|---|---|---|---|
| nqn | Required | string | Subsystem NQN |
| nsid | Required | number | Namespace ID |
| host | Required | string | Host NQN |
Example request:
Example response:
Set the maximum allowed subsystems for the NVMe-oF target. This RPC may only be called before SPDK subsystems have been initialized.
| Name | Optional | Type | Description |
|---|---|---|---|
| max_subsystems | Required | number | Maximum number of NVMe-oF subsystems |
Example request:
Example response:
Add a discovery service referral to an NVMe-oF target. If a referral with the given parameters already exists, no action will be taken.
| Name | Optional | Type | Description |
|---|---|---|---|
| tgt_name | Optional | string | Parent NVMe-oF target name. |
| address | Required | object | listen_address object |
| secure_channel | Optional | bool | The connection to that discovery subsystem requires a secure channel |
Example request:
Example response:
Remove a discovery service referral from an NVMe-oF target.
| Name | Optional | Type | Description |
|---|---|---|---|
| tgt_name | Optional | string | Parent NVMe-oF target name. |
| address | Required | object | listen_address object |
Example request:
Example response:
| Name | Optional | Type | Description |
|---|---|---|---|
| tgt_name | Optional | string | Parent NVMe-oF target name. |
Example request:
Example response:
Set global configuration of NVMe-oF target. This RPC may only be called before SPDK subsystems have been initialized.
| 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 |
| poll_groups_mask | Optional | string | Set cpumask for NVMf poll groups |
| discovery_filter | Optional | string | Set discovery filter, possible values are: match_any (default) or comma separated values: transport, address, svcid |
| dhchap_digests | Optional | list | List of allowed DH-HMAC-CHAP digests. |
| dhchap_dhgroups | Optional | list | List of allowed DH-HMAC-CHAP DH groups. |
| 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 request:
Example response:
The user may specify no parameters in order to list all transports, or a transport may be specified by type.
| Name | Optional | Type | Description |
|---|---|---|---|
| tgt_name | Optional | string | Parent NVMe-oF target name. |
| trtype | Optional | string | Transport type. |
Example request:
Example response:
Retrieve current statistics of the NVMf subsystem.
| Name | Optional | Type | Description |
|---|---|---|---|
| tgt_name | Optional | string | Parent NVMe-oF target name. |
The response is an object containing NVMf subsystem statistics. In the response, admin_qpairs and io_qpairs are reflecting cumulative queue pair counts while current_admin_qpairs and current_io_qpairs are showing the current number.
Example request:
Example response:
Set the 3 CRDT (Command Retry Delay Time) values. For details about CRDT, please refer to the NVMe specification. Currently all the SPDK nvmf subsystems share the same CRDT values. The default values are 0. This rpc can only be invoked in STARTUP stage. All values are in units of 100 milliseconds (same as the NVMe specification).
| Name | Optional | Type | Description |
|---|---|---|---|
| crdt1 | Optional | number | Command Retry Delay Time 1 |
| crdt2 | Optional | number | Command Retry Delay Time 2 |
| crdt3 | Optional | number | Command Retry Delay Time 3 |
Set base path of Unix Domain socket file.
| Name | Optional | Type | Description |
|---|---|---|---|
| path | Required | string | Base path |
Example request:
Example response:
Delete PCI device via endpoint name.
| Name | Optional | Type | Description |
|---|---|---|---|
| name | Required | string | Endpoint name |
Example request:
Example response:
Create vfio-user virtio-blk PCI endpoint.
| Name | Optional | Type | Description |
|---|---|---|---|
| name | Required | string | Endpoint name |
| bdev_name | Required | string | Block device name |
| cpumask | Optional | string | CPU masks |
| num_queues | Optional | number | Number of queues |
| qsize | Optional | number | Queue size |
| packed_ring | Optional | boolean | Enable packed ring |
Example request:
Example response:
Add block device to specified SCSI target of vfio-user virtio-scsi PCI endpoint.
| Name | Optional | Type | Description |
|---|---|---|---|
| name | Required | string | Endpoint name |
| scsi_target_num | Required | number | SCSI target number |
| bdev_name | Required | string | Block device name |
Example request:
Example response:
Remove a SCSI target of vfio-user virtio-scsi PCI endpoint.
| Name | Optional | Type | Description |
|---|---|---|---|
| name | Required | string | Endpoint name |
| scsi_target_num | Required | number | SCSI target number |
Example request:
Example response:
Create vfio-user virtio-scsi PCI endpoint.
| Name | Optional | Type | Description |
|---|---|---|---|
| name | Required | string | Endpoint name |
| cpumask | Optional | string | CPU masks |
| num_io_queues | Optional | number | Number of IO queues |
| qsize | Optional | number | Queue size |
| packed_ring | Optional | boolean | Enable packed ring |
Example request:
Example response:
Create vfio-user virtio-fs PCI endpoint.
| Name | Optional | Type | Description |
|---|---|---|---|
| name | Required | string | Endpoint name |
| fsdev_name | Optional | string | Name of an underlying fsdev |
| tag | Optional | string | Virtio FS tag according to the virtio specification |
| cpumask | Optional | string | CPU masks |
| num_queues | Optional | number | Number of IO queues |
| qsize | Optional | number | Queue size |
| packed_ring | Optional | boolean | Enable packed ring |
Example request:
Example response:
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.
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.
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.
| 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 request:
Example response:
Construct vhost SCSI target.
| Name | Optional | Type | Description |
|---|---|---|---|
| ctrlr | Required | string | Controller name |
| cpumask | Optional | string | CPU mask for this controller |
| delay | Optional | boolean | If true, delay the controller startup. |
Example request:
Example response:
Start vhost SCSI controller, if controller is already started, do nothing.
| Name | Optional | Type | Description |
|---|---|---|---|
| ctrlr | Required | string | Controller name |
Example request:
Example response:
In vhost target ctrlr create SCSI target with ID scsi_target_num and add bdev_name as LUN 0.
| 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 |
SCSI target ID.
Example request:
Example response:
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).
| Name | Optional | Type | Description |
|---|---|---|---|
| ctrlr | Required | string | Controller name |
| scsi_target_num | Required | number | SCSI target ID between 0 and 7 |
Example request:
Example response:
Create virtio blk transport.
| Name | Optional | Type | Description |
|---|---|---|---|
| name | Required | string | Transport name |
Example request:
Example response:
The user may specify no parameters in order to list all transports, or a transport name may be specified.
| Name | Optional | Type | Description |
|---|---|---|---|
| name | Optional | string | Transport name. |
Example request:
Example response:
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.
| 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 | CPU mask for this controller |
| transport | Optional | string | virtio blk transport name (default: vhost_user_blk) |
Example request:
Example response:
Display information about all or specific vhost controller(s).
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 is an array of objects describing requested controller(s). Common fields are:
| Name | Type | Description |
|---|---|---|
| ctrlr | string | Controller name |
| cpumask | string | 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 information |
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 |
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 Vhost SCSI LUN |
Object of type:
| Name | Type | Description |
|---|---|---|
| id | number | SCSI LUN ID |
| bdev_name | string | Backing bdev name |
backend_specific contains namespaces array of following objects:
| Name | Type | Description |
|---|---|---|
| nsid | number | Namespace ID |
| bdev | string | Backing bdev name |
Example request:
Example response:
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 vhost_scsi_controller_remove_target.
| Name | Optional | Type | Description |
|---|---|---|---|
| ctrlr | Required | string | Controller name |
Example request:
Example response:
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:
Construct a logical volume store.
| 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 (Default: 4MiB) |
| clear_method | Optional | string | Change clear method for data region. Available: none, unmap (default), write_zeroes |
| num_md_pages_per_cluster_ratio | Optional | number | Reserved metadata pages per cluster (Default: 100) |
The num_md_pages_per_cluster_ratio defines the amount of metadata to allocate when the logical volume store is created. The default value is '100', which translates to 1 4KiB per cluster. For the default 4MiB cluster size, this equates to about 0.1% of the underlying block device allocated for metadata. Logical volume stores can be grown, if the size of the underlying block device grows in the future, but only if enough metadata pages were allocated to support the growth. So num_md_pages_per_cluster_ratio should be set to a higher value if wanting to support future growth. For example, num_md_pages_per_cluster_ratio = 200 would support future 2x growth of the logical volume store, and would result in 0.2% of the underlying block device allocated for metadata (with a default 4MiB cluster size).
UUID of the created logical volume store is returned.
Example request:
Example response:
Destroy a logical volume store.
| 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 request:
Example response:
Get a list of logical volume stores.
| 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 request:
Example response:
Rename a logical volume store.
| Name | Optional | Type | Description |
|---|---|---|---|
| old_name | Required | string | Existing logical volume store name |
| new_name | Required | string | New logical volume store name |
Example request:
Example response:
Grow the logical volume store to fill the underlying bdev
| Name | Optional | Type | Description |
|---|---|---|---|
| uuid | Optional | string | UUID of the logical volume store to grow |
| lvs_name | Optional | string | Name of the logical volume store to grow |
Either uuid or lvs_name must be specified, but not both.
Example request:
Example response:
Create a logical volume on a logical volume store.
| Name | Optional | Type | Description |
|---|---|---|---|
| lvol_name | Required | string | Name of logical volume to create |
| size_in_mib | Required | number | Desired size of logical volume in MiB |
| 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.
UUID of the created logical volume is returned.
Example request:
Example response:
Capture a snapshot of the current state of a logical volume.
| 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 |
UUID of the created logical volume snapshot is returned.
Example request:
Example response:
Create a logical volume based on a snapshot.
| 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 |
UUID of the created logical volume clone is returned.
Example request:
Example response:
Create a logical volume based on an external snapshot bdev. The external snapshot bdev is a bdev that will not be written to by any consumer and must not be an lvol in the lvstore as the clone.
Regardless of whether the bdev is specified by name or UUID, the bdev UUID will be stored in the logical volume's metadata for use while the lvolstore is loading. For this reason, it is important that the bdev chosen has a static UUID.
| Name | Optional | Type | Description |
|---|---|---|---|
| bdev | Required | string | Name or UUID for bdev that acts as the external snapshot |
| lvs_name | Required | string | logical volume store name |
| clone_name | Required | string | Name for the logical volume to create |
UUID of the created logical volume clone is returned.
Example request:
Example response:
Rename a logical volume. New name will rename only the alias of the logical volume.
| 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 request:
Example response:
Resize a logical volume.
| Name | Optional | Type | Description |
|---|---|---|---|
| name | Required | string | UUID or alias of the logical volume to resize |
| size_in_mib | Required | number | Desired size of the logical volume in MiB |
Example request:
Example response:
Mark logical volume as read only.
| Name | Optional | Type | Description |
|---|---|---|---|
| name | Required | string | UUID or alias of the logical volume to set as read only |
Example request:
Example response:
Destroy a logical volume.
| Name | Optional | Type | Description |
|---|---|---|---|
| name | Required | string | UUID or alias of the logical volume to destroy |
Example request:
Example response:
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.
| Name | Optional | Type | Description |
|---|---|---|---|
| name | Required | string | UUID or alias of the logical volume to inflate |
Example request:
Example response:
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.
| Name | Optional | Type | Description |
|---|---|---|---|
| name | Required | string | UUID or alias of the logical volume to decouple the parent of it |
Example request:
Example response:
Get a list of logical volumes. This list can be limited by lvol store and will display volumes even if they are degraded. Degraded lvols do not have an associated bdev, thus this RPC call may return lvols not returned by bdev_get_bdevs.
| Name | Optional | Type | Description |
|---|---|---|---|
| lvs_uuid | Optional | string | Only show volumes in the logical volume store with this UUID |
| lvs_name | Optional | string | Only show volumes in the logical volume store with this name |
Either lvs_uuid or lvs_name may be specified, but not both. If both lvs_uuid and lvs_name are omitted, information about lvols in all logical volume stores is returned.
Example request:
Example response:
Set a snapshot as the parent of a lvol, making the lvol a clone of this snapshot. The previous parent of the lvol, if any, can be another snapshot or an external snapshot; if the lvol is not a clone, it must be thin-provisioned. Lvol and parent snapshot must have the same size and must belong to the same lvol store.
| Name | Optional | Type | Description |
|---|---|---|---|
| lvol_name | Required | string | UUID or alias of the lvol to set parent of |
| parent_name | Required | string | UUID or alias of the snapshot to become parent of lvol |
Example request:
Example response:
Set an external snapshot as the parent of a lvol, making the lvol a clone of this external snapshot (see bdev_lvol_clone_bdev). The previous parent of the lvol, if any, can be another external snapshot or a snapshot; if the lvol is not a clone, it must be thin-provisioned. The size of the external snapshot device must be an integer multiple of cluster size of lvol's lvolstore.
| Name | Optional | Type | Description |
|---|---|---|---|
| lvol_name | Required | string | UUID or alias of the lvol to set external parent of |
| parent_name | Required | string | UUID or name of the external snapshot to become parent of lvol |
Example request:
Example response:
Start a shallow copy of an lvol over a given bdev. Only clusters allocated to the lvol will be written on the bdev. Must have:
This RPC starts the operation and return an identifier that can be used to query the status of the operation with the RPC bdev_lvol_check_shallow_copy.
| Name | Optional | Type | Description |
|---|---|---|---|
| src_lvol_name | Required | string | UUID or alias of lvol to create a copy from |
| dst_bdev_name | Required | string | Name of the bdev that acts as destination for the copy |
Example request:
Example response:
Get shallow copy status.
Get info about the shallow copy operation identified by operation id. It reports operation's status, which can be in progress, complete or error, the actual number of copied clusters, the total number of clusters to copy and, in case of error, a description. Once the operation is ended and the result has been retrieved, the operation is removed from the internal list of ended operation, so its result cannot be accessed anymore.
| Name | Optional | Type | Description |
|---|---|---|---|
| operation_id | Required | number | operation identifier |
Example request:
Example response:
Set options for bdev raid.
This RPC can be called at any time, but the new value will only take effect for new raid bdevs.
The process_window_size_kb parameter defines the size of the "window" (LBA range of the raid bdev) in which a background process like rebuild performs its work. Any positive value is valid, but the value actually used by a raid bdev can be adjusted to the size of the raid bdev or the write unit size. process_max_bandwidth_mb_sec parameter defines the maximum bandwidth used by a background process like rebuild. Any positive value or zero is valid, zero means no bandwidth limitation for background process. It can only limit the process bandwidth but doesn't guarantee it can be reached. Changing this value will not affect existing processes, it will only take effect on new processes generated after the RPC is completed.
| Name | Optional | Type | Description |
|---|---|---|---|
| process_window_size_kb | Optional | number | Background process (e.g. rebuild) window size in KiB |
| process_max_bandwidth_mb_sec | Optional | number | Background process (e.g. rebuild) maximum bandwidth in MiB/Sec |
Example request:
Example response:
This is used to list all the raid bdev details 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.
| Name | Optional | Type | Description |
|---|---|---|---|
| category | Required | string | all or online or configuring or offline |
Example request:
Example response:
Constructs new RAID bdev.
| Name | Optional | Type | Description |
|---|---|---|---|
| name | Required | string | RAID bdev name |
| strip_size_kb | Required | number | Strip size in KB |
| raid_level | Required | string | RAID level |
| base_bdevs | Required | string | Base bdevs name, whitespace separated list in quotes |
| uuid | Optional | string | UUID for this RAID bdev |
| superblock | Optional | boolean | If set, information about raid bdev will be stored in superblock on each base bdev (default: false) |
Example request:
Example response:
Removes RAID bdev.
| Name | Optional | Type | Description |
|---|---|---|---|
| name | Required | string | RAID bdev name |
Example request:
Example response:
Add base bdev to existing raid bdev. The raid bdev must have an empty base bdev slot. The bdev must be large enough and have the same block size and metadata format as the other base bdevs.
| Name | Optional | Type | Description |
|---|---|---|---|
| raid_bdev | Required | string | Raid bdev name |
| base_bdev | Required | string | Base bdev name |
Example request:
Example response:
Remove base bdev from existing raid bdev.
| Name | Optional | Type | Description |
|---|---|---|---|
| name | Required | string | Base bdev name in RAID |
Example request:
Example response:
This is used to split an underlying block device and create several smaller equal-sized vbdevs.
| Name | Optional | Type | Description |
|---|---|---|---|
| base_bdev | Required | string | base bdev name |
| split_count | Required | number | number of splits |
| split_size_mb | Optional | number | size in MB to restrict the size |
Example request:
Example response:
This is used to remove the split vbdevs.
| Name | Optional | Type | Description |
|---|---|---|---|
| base_bdev | Required | string | base bdev name |
Example request:
Example response:
Create a bdev with io_uring backend.
| Name | Optional | Type | Description |
|---|---|---|---|
| filename | Required | string | path to device or file (ex: /dev/nvme0n1) |
| name | Required | string | name of bdev |
| block_size | Optional | number | block size of device (If omitted, get the block size from the file) |
| uuid | Optional | string | UUID of new bdev |
Example request:
Example response:
Rescan the size of a uring bdev.
| Name | Optional | Type | Description |
|---|---|---|---|
| name | Required | string | name of uring bdev to rescan |
Example request:
Example response:
Remove a uring bdev.
| Name | Optional | Type | Description |
|---|---|---|---|
| name | Required | string | name of uring bdev to delete |
Example request:
Example response:
This is used to initialize OPAL of a given NVMe ctrlr, including taking ownership and activating.
| Name | Optional | Type | Description |
|---|---|---|---|
| nvme_ctrlr_name | Required | string | name of nvme ctrlr |
| password | Required | string | admin password of OPAL |
Example request:
Example response:
This is used to revert OPAL to its factory settings. Erase all user configuration and data.
| Name | Optional | Type | Description |
|---|---|---|---|
| nvme_ctrlr_name | Required | string | name of nvme ctrlr |
| password | Required | string | admin password of OPAL |
Example request:
Example response:
This is used to create an OPAL virtual bdev.
| 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 |
The response is the name of created OPAL virtual bdev.
Example request:
Example response:
This is used to get information of a given OPAL bdev.
| Name | Optional | Type | Description |
|---|---|---|---|
| bdev_name | Required | string | name of OPAL vbdev |
| password | Required | string | admin password |
The response is the locking info of OPAL virtual bdev.
Example request:
Example response:
This is used to delete OPAL vbdev.
| Name | Optional | Type | Description |
|---|---|---|---|
| bdev_name | Required | string | name of OPAL vbdev |
| password | Required | string | admin password |
Example request:
Example response:
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.
| 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 request:
Example response:
This is used to lock/unlock specific opal bdev providing user ID and password.
| 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 request:
Example response:
Return list of all supported notification types.
None
The response is an array of strings - supported RPC notification types.
Example request:
Example response:
Request notifications. Returns array of notifications that happened since the specified id (or first that is available).
Notice: Notifications are kept in circular buffer with limited size. Older notifications might be inaccessible due to being overwritten by new ones.
| 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 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 request:
Example response:
SPDK supports exporting bdevs though Linux ublk. The motivation behind it is to back a Linux kernel block device with an SPDK user space bdev.
To export a device over ublk, first make sure the Linux kernel ublk driver is loaded by running 'modprobe ublk_drv'.
Start to create ublk threads and initialize ublk target. It will return an error if user calls this RPC twice without ublk_destroy_target in between. It will use current cpumask in SPDK when user does not specify cpumask option.
| Name | Optional | Type | Description |
|---|---|---|---|
| cpumask | Optional | string | Cpumask for ublk target |
| disable-user-copy | Optional | boolean | Disable user copy feature |
True if ublk target initialization is successful; False if failed.
Example request:
Example response:
Release all UBLK devices and destroy ublk target.
True if ublk target destruction is successful; False if failed.
Example request:
Example response:
Start to export one SPDK bdev as a UBLK device
| Name | Optional | Type | Description |
|---|---|---|---|
| bdev_name | Required | string | Bdev name to export |
| ublk_id | Required | int | Device id |
| queue_depth | Optional | int | Device queue depth |
| num_queues | Optional | int | Total number of device queues |
UBLK device ID
Example request:
Example response:
Recover original UBLK device with ID and block device
| Name | Optional | Type | Description |
|---|---|---|---|
| bdev_name | Required | string | Bdev name to export |
| ublk_id | Required | int | Device id |
UBLK device ID
Example request:
Example response:
Delete a UBLK device
| Name | Optional | Type | Description |
|---|---|---|---|
| ublk_id | Required | int | Device id to delete |
True if UBLK device is deleted successfully; False if failed.
Example request:
Example response:
Display full or specified ublk device list
| Name | Optional | Type | Description |
|---|---|---|---|
| ublk_id | Optional | int | ublk device id to display |
Display ublk device list
Example request:
Example response:
SPDK supports exporting bdevs through Linux nbd. These devices then appear as standard Linux kernel block devices and can be accessed using standard utilities like fdisk.
In order to export a device over nbd, first make sure the Linux kernel nbd driver is loaded by running 'modprobe nbd'.
Start to export one SPDK bdev as NBD disk
| Name | Optional | Type | Description |
|---|---|---|---|
| bdev_name | Required | string | Bdev name to export |
| nbd_device | Optional | string | NBD device name to assign |
Path of exported NBD disk
Example request:
Example response:
Stop one NBD disk which is based on SPDK bdev.
| Name | Optional | Type | Description |
|---|---|---|---|
| nbd_device | Required | string | NBD device name to stop |
Example request:
Example response:
Display all or specified NBD device list
| Name | Optional | Type | Description |
|---|---|---|---|
| nbd_device | Optional | string | NBD device name to display |
The response is an array of exported NBD devices and their corresponding SPDK bdev.
Example request:
Example response:
Detect whether a blobfs exists on bdev.
| Name | Optional | Type | Description |
|---|---|---|---|
| bdev_name | Required | string | Block device name to detect blobfs |
True if a blobfs exists on the bdev; False otherwise.
Example request:
Example response:
Build blobfs on bdev.
| 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 request:
Example response:
Mount a blobfs on bdev to one host path through FUSE
| 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 request:
Example response:
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.
| Name | Optional | Type | Description |
|---|---|---|---|
| size_in_mb | Required | number | Cache size in megabytes |
True if cache size is set successfully; False if failed to set.
Example request:
Example response:
Get parameters for the socket layer implementation.
| Name | Optional | Type | Description |
|---|---|---|---|
| impl_name | Required | string | Name of socket implementation, e.g. posix |
Response is an object with current socket layer options for requested implementation.
Example request:
Example response:
Set parameters for the socket layer implementation.
| Name | Optional | Type | Description |
|---|---|---|---|
| impl_name | Required | string | Name of socket implementation, e.g. posix |
| recv_buf_size | Optional | number | Size of socket receive buffer in bytes |
| send_buf_size | Optional | number | Size of socket send buffer in bytes |
| enable_recv_pipe | Optional | boolean | Enable or disable receive pipe |
| enable_quick_ack | Optional | boolean | Enable or disable quick ACK |
| enable_placement_id | Optional | number | Enable or disable placement_id. 0:disable,1:incoming_napi,2:incoming_cpu |
| enable_zerocopy_send_server | Optional | boolean | Enable or disable zero copy on send for server sockets |
| enable_zerocopy_send_client | Optional | boolean | Enable or disable zero copy on send for client sockets |
| zerocopy_threshold | Optional | number | Set zerocopy_threshold in bytes. A consecutive sequence of requests' iovecs |
| – | – | – | that fall below this threshold may be sent without zerocopy flag set |
| tls_version | Optional | number | TLS protocol version, e.g. 13 for v1.3 (only applies when impl_name == ssl) |
| enable_ktls | Optional | boolean | Enable or disable Kernel TLS (only applies when impl_name == ssl) |
True if socket layer options were set successfully.
Example request:
Example response:
Set the default sock implementation.
| Name | Optional | Type | Description |
|---|---|---|---|
| impl_name | Required | string | Name of socket implementation, e.g. posix |
True if the default socket layer configuration was set successfully.
Example request:
Example response:
Get the name of the default sock implementation.
This function has no parameters.
The name of the current default socket implementation.
Example request:
Example response:
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 guarantee the correctness of NVMe command itself, and also optional parameters. Illegal command contents or mismatching buffer size may result in unpredictable behavior.
| 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 |
| 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 request:
Example response:
Enable VMD enumeration.
This method has no parameters.
Completion status of enumeration is returned as a boolean.
Example request:
Example response:
Remove a device behind a VMD.
| Name | Optional | Type | Description |
|---|---|---|---|
| addr | Required | string | Address of the device to remove. |
Example response:
Force a rescan of the devices behind VMD.
This method has no parameters.
The response is the number of new devices found.
Example response:
Get the version info of the running SPDK application.
This method has no parameters.
The response is the version number including major version number, minor version number, patch level number and suffix string.
Example request:
Example response:
List PCIe devices attached to an SPDK application and the contents of their config space.
This method has no parameters.
The response is an array of attached PCIe devices.
Example request:
Example response: Note that the config space buffer was trimmed.
Add a NVMe command error injection for a bdev nvme controller.
| Name | Optional | Type | Description |
|---|---|---|---|
| name | Required | string | Name of the operating NVMe controller |
| cmd_type | Required | string | Type of NVMe command. Valid values are: admin, io |
| opc | Required | number | Opcode for which the error injection is applied |
| do_not_submit | Optional | boolean | Set to true if request should not be submitted to the controller (default false) |
| timeout_in_us | Optional | number | Wait specified microseconds when do_not_submit is true |
| err_count | Optional | number | Number of matching NVMe commands to inject errors |
| sct | Optional | number | Status code type (default 0) |
| sc | Optional | number | Status code (default 0) |
true on success
Example request:
Example response:
Remove a NVMe command error injection.
| Name | Optional | Type | Description |
|---|---|---|---|
| name | Required | string | Name of the operating NVMe controller |
| cmd_type | Required | string | Type of NVMe command. Valid values are: admin, io |
| opc | Required | number | Opcode for which the error injection is applied |
true on success
Example request:
Example response:
Construct DAOS bdev
| Name | Optional | Type | Description |
|---|---|---|---|
| name | Required | string | Bdev name to use |
| pool | Required | string | DAOS pool label or its uuid |
| cont | Required | string | DAOS cont label or its uuid |
| 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 |
| oclass | Optional | string | DAOS object class (default SX) |
To find more about various object classes please visit DAOS documentation. Please note, that DAOS bdev module uses the same CLI flag notation as dmg and daos commands, for instance, SX or EC_4P2G2 rather than in DAOS header file OC_SX or OC_EC_4P2G2.
Name of newly created bdev.
Example request:
Example response:
Delete DAOS bdev
| Name | Optional | Type | Description |
|---|---|---|---|
| name | Required | string | Bdev name |
Example request:
Example response:
Resize DAOS bdev.
| Name | Optional | Type | Description |
|---|---|---|---|
| name | Required | string | Bdev name |
| new_size | Required | number | Bdev new capacity in MiB |
Example request:
Example response:
Set iobuf buffer pool options.
| Name | Optional | Type | Description |
|---|---|---|---|
| small_pool_count | Optional | number | Number of small buffers in the global pool |
| large_pool_count | Optional | number | Number of large buffers in the global pool |
| small_bufsize | Optional | number | Size of a small buffer |
| large_bufsize | Optional | number | Size of a small buffer |
Example request:
Example response:
Retrieve iobuf's statistics.
None.
Example request:
Example response:
Starts an mDNS based discovery service for the specified service type for the auto-discovery of discovery controllers (NVMe TP-8009).
The discovery service will listen for the mDNS discovery events from the Avahi-daemon and will connect to the newly learnt discovery controllers. Then the discovery service will automatically attach to any subsystem found in the discovery log page from the discovery controllers learnt using mDNS. When determining a controller name to use when attaching, it will use the 'name' parameter as a prefix, followed by a unique integer assigned for each of the discovery controllers learnt through mDNS, followed by a unique integer for that discovery service. If the discovery service identifies a subsystem that has been previously attached but is listed with a different path, it will use the same controller name as the previous entry, and connect as a multipath.
When the discovery service sees that a subsystem entry has been removed from the log page, it will automatically detach from that controller as well.
The 'name' is also used to later stop the discovery service.
| Name | Optional | Type | Description |
|---|---|---|---|
| name | Required | string | Prefix for NVMe discovery services found |
| svcname | Required | string | Service to discover: e.g. _nvme-disc._tcp |
| hostnqn | Optional | string | NVMe-oF hostnqn |
Example request:
Example response:
Stops a mDNS discovery service. This includes detaching any controllers that were discovered via the service that is being stopped.
| Name | Optional | Type | Description |
|---|---|---|---|
| name | Required | string | Name of mDNS discovery instance to stop |
Example request:
Example response:
Get the information about the mDNS discovery service instances.
Example request:
Example response:
Add a file-based key to a keyring.
| Name | Optional | Type | Description |
|---|---|---|---|
| name | Required | string | Name of the key to add. |
| path | Required | string | Path to a file containing the key. |
Example request:
Example response:
Remove a file-based key from a keyring.
| Name | Optional | Type | Description |
|---|---|---|---|
| name | Required | string | Name of the key to remove. |
Example request:
Example response:
Get a list of available keys. This RPC will only list keys that are currently attached to a keyring. Dynamically loaded keys (via the probe_key() callback) will only be included if they're currently in-use (i.e. with active references obtained via spdk_keyring_get_key()).
Example request:
Example response:
Set options of the keyring_linux module.
| Name | Optional | Type | Description |
|---|---|---|---|
| enable | Optional | boolean | Enable the module. |
Example request:
Example response:
This interface is used to publish an NVMf target's service location using mDNS (Multicast DNS) protocol. It allows clients to discover the NVMf target using the published service location.
| Name | Optional | Type | Description |
|---|---|---|---|
| tgt_name | Optional | string | Parent NVMe-oF target name. |
Example request:
Example response:
This interface is used to stop publishing the NVMf target's service location using mDNS (Multicast DNS) protocol. It removes the published service location, preventing clients from discovering the NVMf target.
| Name | Optional | Type | Description |
|---|---|---|---|
| tgt_name | Optional | string | Parent NVMe-oF target name. |
Example request:
Example response:
json { "jsonrpc": "2.0", "method": "fsdev_get_opts", "id": 1 }
json { "jsonrpc": "2.0", "id": 1, "result": { "fsdev_io_pool_size": 65535, "fsdev_io_cache_size": 256 } }
json { "jsonrpc": "2.0", "method": "fsdev_get_opts", "id": 1, "params": { "fsdev_io_pool_size": 65535, "fsdev_io_cache_size": 256 } }
json { "jsonrpc": "2.0", "id": 1, "result": { "fsdev_io_pool_size": 65535, "fsdev_io_cache_size": 256 } }
json { "jsonrpc": "2.0", "method": "fsdev_aio_create", "id": 8, "params": { "name": "aio0", "root_path": "/tmp/vfio-test", "enable_xattr": false, "enable_writeback_cache": true, "max_write": 65535 } }
json { "jsonrpc": "2.0", "id": 8, "result": "aio0" }
json { "jsonrpc": "2.0", "method": "fsdev_aio_delete", "id": 1, "params": { "name": "aio0" } }
json { "jsonrpc": "2.0", "id": 1, "result": true } ~~~