1# JSON-RPC {#jsonrpc} 2 3## Overview {#jsonrpc_overview} 4 5SPDK implements a [JSON-RPC 2.0](http://www.jsonrpc.org/specification) server 6to allow external management tools to dynamically configure SPDK components. 7 8## Parameters 9 10Most of the commands can take parameters. If present, parameter is validated against its domain. If this check fail 11whole command will fail with response error message [Invalid params](@ref jsonrpc_error_message). 12 13### Required parameters 14 15These parameters are mandatory. If any required parameter is missing RPC command will fail with proper error response. 16 17### Optional parameters 18 19Those parameters might be omitted. If an optional parameter is present it must be valid otherwise command will fail 20proper error response. 21 22## Error response message {#jsonrpc_error_message} 23 24Each error response will contain proper message. As much as possible the message should indicate what went wrong during 25command processing. 26 27There is ongoing effort to customize this messages but some RPC methods just return "Invalid parameters" as message body 28for any kind of error. 29 30Code | Description 31------ | ----------- 32-1 | Invalid state - given method exists but it is not callable in [current runtime state](@ref rpc_framework_start_init) 33-32600 | Invalid request - not compliant with JSON-RPC 2.0 Specification 34-32601 | Method not found 35-32602 | @ref jsonrpc_invalid_params 36-32603 | Internal error for e.g.: errors like out of memory 37-32700 | @ref jsonrpc_parser_error 38 39### Parser error {#jsonrpc_parser_error} 40 41Encountered some error during parsing request like: 42 43- the JSON object is malformed 44- parameter is too long 45- request is too long 46 47### Invalid params {#jsonrpc_invalid_params} 48 49This type of error is most common one. It mean that there is an error while processing the request like: 50 51- Parameters decoding in RPC method handler failed because required parameter is missing. 52- Unknown parameter present encountered. 53- Parameter type doesn't match expected type e.g.: given number when expected a string. 54- Parameter domain check failed. 55- Request is valid but some other error occurred during processing request. If possible message explains the error reason nature. 56 57## rpc.py {#rpc_py} 58 59SPDK provides a set of Python scripts which can invoke the JSON-RPC methods described in this document. 'rpc.py' in the scripts 60directory is the main script that users will invoke to execute a JSON-RPC method. The scripts/rpc directory contains modules 61that 'rpc.py' imports for definitions of each SPDK library's or module's methods. 62 63Example: 64 65~~~bash 66scripts/rpc.py bdev_nvme_attach_controller -b nvme0 -a 00:02.0 -t pcie 67~~~ 68 69A brief description of each of the RPC methods and optional 'rpc.py' arguments can be viewed with: 70 71~~~bash 72scripts/rpc.py --help 73~~~ 74 75A detailed description of each RPC method and its parameters is also available. For example: 76 77~~~bash 78scripts/rpc.py bdev_nvme_attach_controller --help 79~~~ 80 81### Generate JSON-RPC methods for current configuration {#jsonrpc_generate} 82 83An initial configuration can be specified for an SPDK application via the '-c' command line parameter. 84The configuration file is a JSON file containing all of the JSON-RPC method invocations necessary 85for the desired configuration. Writing these files by hand is extremely tedious however, so 'rpc.py' 86provides a mechanism to generate a JSON-RPC file based on the current configuration. 87 88~~~bash 89scripts/rpc.py save_config > config.json 90~~~ 91 92'config.json' can then be passed to a new SPDK application using the '-c' command line parameter 93to reproduce the same configuration. 94 95### JSON-RPC batching 96 97'rpc.py' also supports batching of multiple JSON-RPC methods with one invocation. So instead of 98calling 'rpc.py' once for each JSON-RPC method, such as: 99 100~~~bash 101scripts/rpc.py bdev_malloc_create -b malloc0 64 512 102scripts/rpc.py nvmf_create_subsystem nqn.2016-06.io.spdk:cnode1 -a 103scripts/rpc.py nvmf_subsystem_add_ns nqn.2016-06.io.spdk:cnode1 malloc0 104scripts/rpc.py nvmf_create_transport -t tcp 105scripts/rpc.py nvmf_subsystem_add_listener nqn.2016-06.io.spdk:cnode1 -t tcp -a 127.0.0.1 -s 4420 106~~~ 107 108you can put the following into a text file: 109 110~~~bash 111bdev_malloc_create -b malloc0 64 512 112nvmf_create_subsystem nqn.2016-06.io.spdk:cnode1 -a 113nvmf_subsystem_add_ns nqn.2016-06.io.spdk:cnode1 malloc0 114nvmf_create_transport -t tcp 115nvmf_subsystem_add_listener nqn.2016-06.io.spdk:cnode1 -t tcp -a 127.0.0.1 -s 4420 116~~~ 117 118and then just do: 119 120~~~bash 121scripts/rpc.py < rpc.txt 122~~~ 123 124### Adding external RPC methods 125 126SPDK includes both in-tree modules as well as the ability to use external modules. The in-tree modules include some python 127scripts to ease the process of sending RPCs to in-tree modules. External modules can utilize this same framework to add new RPC 128methods as follows: 129 130If PYTHONPATH doesn't include the location of the external RPC python script, it should be updated: 131 132~~~bash 133export PYTHONPATH=/home/user/plugin_example/ 134~~~ 135 136In provided location, create python module file (e.g. rpc_plugin.py) with new RPC methods. The file should contain 137spdk_rpc_plugin_initialize() method that will be called when the plugin is loaded to define new parsers for provided subparsers 138argument that adds new RPC calls (subparsers.add_parser()). The new parsers should use the client.call() method to call RPC 139functions registered within the external module using the SPDK_RPC_REGISTER() macro. Example: 140 141~~~python 142from spdk.rpc.client import print_json 143 144 145def example_create(client, num_blocks, block_size, name=None, uuid=None): 146 """Construct an example block device. 147 148 Args: 149 num_blocks: size of block device in blocks 150 block_size: block size of device; must be a power of 2 and at least 512 151 name: name of block device (optional) 152 uuid: UUID of block device (optional) 153 154 Returns: 155 Name of created block device. 156 """ 157 params = {'num_blocks': num_blocks, 'block_size': block_size} 158 if name: 159 params['name'] = name 160 if uuid: 161 params['uuid'] = uuid 162 return client.call('bdev_example_create', params) 163 164 165def example_delete(client, name): 166 """Delete example block device. 167 168 Args: 169 bdev_name: name of bdev to delete 170 """ 171 params = {'name': name} 172 return client.call('bdev_example_delete', params) 173 174 175def spdk_rpc_plugin_initialize(subparsers): 176 def bdev_example_create(args): 177 num_blocks = (args.total_size * 1024 * 1024) // args.block_size 178 print_json(example_create(args.client, 179 num_blocks=int(num_blocks), 180 block_size=args.block_size, 181 name=args.name, 182 uuid=args.uuid)) 183 184 p = subparsers.add_parser('bdev_example_create', 185 help='Create an example bdev') 186 p.add_argument('-b', '--name', help="Name of the bdev") 187 p.add_argument('-u', '--uuid', help="UUID of the bdev") 188 p.add_argument( 189 'total_size', help='Size of bdev in MB (float > 0)', type=float) 190 p.add_argument('block_size', help='Block size for this bdev', type=int) 191 p.set_defaults(func=bdev_example_create) 192 193 def bdev_example_delete(args): 194 example_delete(args.client, 195 name=args.name) 196 197 p = subparsers.add_parser('bdev_example_delete', 198 help='Delete an example disk') 199 p.add_argument('name', help='example bdev name') 200 p.set_defaults(func=bdev_example_delete) 201~~~ 202 203Finally, call the rpc.py script with '--plugin' parameter to provide above python module name: 204 205~~~bash 206./scripts/rpc.py --plugin rpc_plugin bdev_example_create 10 4096 207~~~ 208 209### Converting from legacy configuration {#jsonrpc_convert} 210 211Starting with SPDK 20.10, legacy configuration file support has been removed. 212Users with extensive configuration files already running in SPDK application, 213can [generate JSON-RPC for current configuration](@ref jsonrpc_generate). 214 215If binary for deploying the application is unavailable, the legacy configuration 216file can be converted to JSON-RPC using python tool: 217 218~~~bash 219./scripts/config_converter.py < config.ini > config.json 220~~~ 221 222## App Framework {#jsonrpc_components_app} 223 224### spdk_kill_instance {#rpc_spdk_kill_instance} 225 226Send a signal to the application. 227 228#### Parameters 229 230Name | Optional | Type | Description 231----------------------- | -------- | ----------- | ----------- 232sig_name | Required | string | Signal to send (SIGINT, SIGTERM, SIGQUIT, SIGHUP, or SIGKILL) 233 234#### Example 235 236Example request: 237 238~~~json 239{ 240 "jsonrpc": "2.0", 241 "id": 1, 242 "method": "spdk_kill_instance", 243 "params": { 244 "sig_name": "SIGINT" 245 } 246} 247~~~ 248 249Example response: 250 251~~~json 252{ 253 "jsonrpc": "2.0", 254 "id": 1, 255 "result": true 256} 257~~~ 258 259### framework_monitor_context_switch {#rpc_framework_monitor_context_switch} 260 261Query, enable, or disable the context switch monitoring functionality. 262 263#### Parameters 264 265Name | Optional | Type | Description 266----------------------- | -------- | ----------- | ----------- 267enabled | Optional | boolean | Enable (`true`) or disable (`false`) monitoring (omit this parameter to query the current state) 268 269#### Response 270 271Name | Type | Description 272----------------------- | ----------- | ----------- 273enabled | boolean | The current state of context switch monitoring 274 275#### Example 276 277Example request: 278 279~~~json 280{ 281 "jsonrpc": "2.0", 282 "id": 1, 283 "method": "framework_monitor_context_switch", 284 "params": { 285 "enabled": false 286 } 287} 288~~~ 289 290Example response: 291 292~~~json 293{ 294 "jsonrpc": "2.0", 295 "id": 1, 296 "result": { 297 "enabled": false 298 } 299} 300~~~ 301 302### framework_start_init {#rpc_framework_start_init} 303 304Start initialization of SPDK subsystems when it is deferred by starting SPDK application with option -w. 305During its deferral some RPCs can be used to set global parameters for SPDK subsystems. 306This RPC can be called only once. 307 308#### Parameters 309 310This method has no parameters. 311 312#### Response 313 314Completion status of SPDK subsystem initialization is returned as a boolean. 315 316#### Example 317 318Example request: 319 320~~~json 321{ 322 "jsonrpc": "2.0", 323 "id": 1, 324 "method": "framework_start_init" 325} 326~~~ 327 328Example response: 329 330~~~json 331{ 332 "jsonrpc": "2.0", 333 "id": 1, 334 "result": true 335} 336~~~ 337 338### framework_wait_init {#rpc_framework_wait_init} 339 340Do not return until all subsystems have been initialized and the RPC system state is running. 341If the application is already running, this call will return immediately. This RPC can be called at any time. 342 343#### Parameters 344 345This method has no parameters. 346 347#### Response 348 349Returns True when subsystems have been initialized. 350 351#### Example 352 353Example request: 354 355~~~json 356{ 357 "jsonrpc": "2.0", 358 "id": 1, 359 "method": "framework_wait_init" 360} 361~~~ 362 363Example response: 364 365~~~json 366{ 367 "jsonrpc": "2.0", 368 "id": 1, 369 "result": true 370} 371~~~ 372 373### rpc_get_methods {#rpc_rpc_get_methods} 374 375Get an array of supported RPC methods. 376 377#### Parameters 378 379Name | Optional | Type | Description 380----------------------- | -------- | ----------- | ----------- 381current | Optional | boolean | Get an array of RPC methods only callable in the current state. 382 383#### Response 384 385The response is an array of supported RPC methods. 386 387#### Example 388 389Example request: 390 391~~~json 392{ 393 "jsonrpc": "2.0", 394 "id": 1, 395 "method": "rpc_get_methods" 396} 397~~~ 398 399Example response: 400 401~~~json 402{ 403 "jsonrpc": "2.0", 404 "id": 1, 405 "result": [ 406 "framework_start_init", 407 "rpc_get_methods", 408 "scsi_get_devices", 409 "nbd_get_disks", 410 "nbd_stop_disk", 411 "nbd_start_disk", 412 "log_get_flags", 413 "log_clear_flag", 414 "log_set_flag", 415 "log_get_level", 416 "log_set_level", 417 "log_get_print_level", 418 "log_set_print_level", 419 "iscsi_get_options", 420 "iscsi_target_node_add_lun", 421 "iscsi_get_connections", 422 "iscsi_delete_portal_group", 423 "iscsi_create_portal_group", 424 "iscsi_get_portal_groups", 425 "iscsi_delete_target_node", 426 "iscsi_target_node_remove_pg_ig_maps", 427 "iscsi_target_node_add_pg_ig_maps", 428 "iscsi_create_target_node", 429 "iscsi_get_target_nodes", 430 "iscsi_delete_initiator_group", 431 "iscsi_initiator_group_remove_initiators", 432 "iscsi_initiator_group_add_initiators", 433 "iscsi_create_initiator_group", 434 "iscsi_get_initiator_groups", 435 "iscsi_set_options", 436 "bdev_set_options", 437 "bdev_set_qos_limit", 438 "bdev_get_bdevs", 439 "bdev_get_iostat", 440 "framework_get_config", 441 "framework_get_subsystems", 442 "framework_monitor_context_switch", 443 "spdk_kill_instance", 444 "accel_set_options", 445 "accel_set_driver", 446 "accel_crypto_key_create", 447 "accel_crypto_key_destroy", 448 "accel_crypto_keys_get", 449 "accel_assign_opc", 450 "accel_get_module_info", 451 "accel_get_opc_assignments", 452 "accel_error_inject_error", 453 "ioat_scan_accel_module", 454 "dsa_scan_accel_module", 455 "dpdk_cryptodev_scan_accel_module", 456 "dpdk_cryptodev_set_driver", 457 "dpdk_cryptodev_get_driver", 458 "mlx5_scan_accel_module", 459 "bdev_virtio_attach_controller", 460 "bdev_virtio_scsi_get_devices", 461 "bdev_virtio_detach_controller", 462 "bdev_virtio_blk_set_hotplug", 463 "bdev_aio_delete", 464 "bdev_aio_create", 465 "bdev_split_delete", 466 "bdev_split_create", 467 "bdev_error_inject_error", 468 "bdev_error_delete", 469 "bdev_error_create", 470 "bdev_passthru_create", 471 "bdev_passthru_delete" 472 "bdev_nvme_apply_firmware", 473 "bdev_nvme_get_transport_statistics", 474 "bdev_nvme_get_controller_health_info", 475 "bdev_nvme_detach_controller", 476 "bdev_nvme_attach_controller", 477 "bdev_null_create", 478 "bdev_malloc_delete", 479 "bdev_malloc_create", 480 "bdev_ftl_delete", 481 "bdev_ftl_unload", 482 "bdev_ftl_create", 483 "bdev_ftl_load", 484 "bdev_ftl_unmap", 485 "bdev_ftl_get_stats", 486 "bdev_ftl_get_properties", 487 "bdev_ftl_set_property", 488 "bdev_lvol_get_lvstores", 489 "bdev_lvol_delete", 490 "bdev_lvol_resize", 491 "bdev_lvol_set_read_only", 492 "bdev_lvol_decouple_parent", 493 "bdev_lvol_inflate", 494 "bdev_lvol_rename", 495 "bdev_lvol_clone", 496 "bdev_lvol_snapshot", 497 "bdev_lvol_create", 498 "bdev_lvol_delete_lvstore", 499 "bdev_lvol_rename_lvstore", 500 "bdev_lvol_create_lvstore", 501 "bdev_daos_delete", 502 "bdev_daos_create", 503 "bdev_daos_resize" 504 ] 505} 506~~~ 507 508### framework_get_subsystems {#rpc_framework_get_subsystems} 509 510Get an array of name and dependency relationship of SPDK subsystems in initialization order. 511 512#### Parameters 513 514None 515 516#### Response 517 518The response is an array of name and dependency relationship of SPDK subsystems in initialization order. 519 520#### Example 521 522Example request: 523 524~~~json 525{ 526 "jsonrpc": "2.0", 527 "id": 1, 528 "method": "framework_get_subsystems" 529} 530~~~ 531 532Example response: 533 534~~~json 535{ 536 "jsonrpc": "2.0", 537 "id": 1, 538 "result": [ 539 { 540 "subsystem": "accel", 541 "depends_on": [] 542 }, 543 { 544 "subsystem": "interface", 545 "depends_on": [] 546 }, 547 { 548 "subsystem": "net_framework", 549 "depends_on": [ 550 "interface" 551 ] 552 }, 553 { 554 "subsystem": "bdev", 555 "depends_on": [ 556 "accel" 557 ] 558 }, 559 { 560 "subsystem": "nbd", 561 "depends_on": [ 562 "bdev" 563 ] 564 }, 565 { 566 "subsystem": "nvmf", 567 "depends_on": [ 568 "bdev" 569 ] 570 }, 571 { 572 "subsystem": "scsi", 573 "depends_on": [ 574 "bdev" 575 ] 576 }, 577 { 578 "subsystem": "vhost", 579 "depends_on": [ 580 "scsi" 581 ] 582 }, 583 { 584 "subsystem": "iscsi", 585 "depends_on": [ 586 "scsi" 587 ] 588 } 589 ] 590} 591~~~ 592 593### framework_get_config {#rpc_framework_get_config} 594 595Get current configuration of the specified SPDK framework 596 597#### Parameters 598 599Name | Optional | Type | Description 600----------------------- | -------- | ----------- | ----------- 601name | Required | string | SPDK subsystem name 602 603#### Response 604 605The response is current configuration of the specified SPDK subsystem. 606Null is returned if it is not retrievable by the framework_get_config method and empty array is returned if it is empty. 607 608#### Example 609 610Example request: 611 612~~~json 613{ 614 "jsonrpc": "2.0", 615 "id": 1, 616 "method": "framework_get_config", 617 "params": { 618 "name": "bdev" 619 } 620} 621~~~ 622 623Example response: 624 625~~~json 626{ 627 "jsonrpc": "2.0", 628 "id": 1, 629 "result": [ 630 { 631 "params": { 632 "base_bdev": "Malloc2", 633 "split_size_mb": 0, 634 "split_count": 2 635 }, 636 "method": "bdev_split_create" 637 }, 638 { 639 "params": { 640 "trtype": "PCIe", 641 "name": "Nvme1", 642 "traddr": "0000:01:00.0" 643 }, 644 "method": "bdev_nvme_attach_controller" 645 }, 646 { 647 "params": { 648 "trtype": "PCIe", 649 "name": "Nvme2", 650 "traddr": "0000:03:00.0" 651 }, 652 "method": "bdev_nvme_attach_controller" 653 }, 654 { 655 "params": { 656 "block_size": 512, 657 "num_blocks": 131072, 658 "name": "Malloc0", 659 "uuid": "913fc008-79a7-447f-b2c4-c73543638c31" 660 }, 661 "method": "bdev_malloc_create" 662 }, 663 { 664 "params": { 665 "block_size": 512, 666 "num_blocks": 131072, 667 "name": "Malloc1", 668 "uuid": "dd5b8f6e-b67a-4506-b606-7fff5a859920" 669 }, 670 "method": "bdev_malloc_create" 671 } 672 ] 673} 674~~~ 675 676### framework_get_reactors {#rpc_framework_get_reactors} 677 678Retrieve an array of all reactors. 679 680#### Parameters 681 682This method has no parameters. 683 684#### Response 685 686The response is an array of all reactors. 687 688#### Example 689 690Example request: 691 692~~~json 693{ 694 "jsonrpc": "2.0", 695 "method": "framework_get_reactors", 696 "id": 1 697} 698~~~ 699 700Example response: 701 702~~~json 703{ 704 "jsonrpc": "2.0", 705 "id": 1, 706 "result": { 707 "tick_rate": 2400000000, 708 "reactors": [ 709 { 710 "lcore": 0, 711 "busy": 41289723495, 712 "idle": 3624832946, 713 "lw_threads": [ 714 { 715 "name": "app_thread", 716 "id", 1, 717 "cpumask": "1", 718 "elapsed": 44910853363 719 } 720 ] 721 } 722 ] 723 } 724} 725~~~ 726 727### framework_set_scheduler {#rpc_framework_set_scheduler} 728 729Select thread scheduler that will be activated. 730This feature is considered as experimental. 731 732#### Parameters 733 734Name | Optional | Type | Description 735----------------------- | -------- | ----------- | ----------- 736name | Required | string | Name of a scheduler 737period | Optional | number | Scheduler period 738load_limit | Optional | number | Thread load limit in % (dynamic only) 739core_limit | Optional | number | Load limit on the core to be considered full (dynamic only) 740core_busy | Optional | number | Indicates at what load on core scheduler should move threads to a different core (dynamic only) 741 742#### Response 743 744Completion status of the operation is returned as a boolean. 745 746#### Example 747 748Example request: 749 750~~~json 751{ 752 "jsonrpc": "2.0", 753 "method": "framework_set_scheduler", 754 "id": 1, 755 "params": { 756 "name": "static", 757 "period": "1000000" 758 } 759} 760~~~ 761 762Example response: 763 764~~~json 765{ 766 "jsonrpc": "2.0", 767 "id": 1, 768 "result": true 769} 770~~~ 771 772### framework_get_scheduler {#rpc_framework_get_scheduler} 773 774Retrieve currently set scheduler name and period, along with current governor name. 775 776#### Parameters 777 778This method has no parameters. 779 780#### Response 781 782Name | Description 783------------------------| ----------- 784scheduler_name | Current scheduler name 785scheduler_period | Currently set scheduler period in microseconds 786governor_name | Governor name 787 788#### Example 789 790Example request: 791 792~~~json 793{ 794 "jsonrpc": "2.0", 795 "method": "framework_set_scheduler", 796 "id": 1, 797} 798~~~ 799 800Example response: 801 802~~~json 803{ 804 "jsonrpc": "2.0", 805 "id": 1, 806 "result": { 807 "scheduler_name": "static", 808 "scheduler_period": 2800000000, 809 "governor_name": "default" 810 } 811} 812~~~ 813 814### framework_enable_cpumask_locks 815 816Enable CPU core lock files to block multiple SPDK applications from running on the same cpumask. 817The CPU core locks are enabled by default, unless user specified `--disable-cpumask-locks` command 818line option when launching SPDK. 819 820This RPC may be called after locks have already been enabled, with no effect and no error response. 821 822#### Parameters 823 824This method has no parameters. 825 826#### Response 827 828true on success 829 830#### Example 831 832Example request: 833 834~~~json 835{ 836 "jsonrpc": "2.0", 837 "id": 1, 838 "method": "framework_enable_cpumask_locks" 839} 840~~~ 841 842Example response: 843 844~~~json 845{ 846 "jsonrpc": "2.0", 847 "id": 1, 848 "result": true 849} 850~~~ 851 852### framework_disable_cpumask_locks 853 854Disable CPU core lock files. The locks can also be disabled during startup, when 855user specifies `--disable-cpumask-locks` command line option during SPDK launch. 856 857This RPC may be called after locks have already been disabled, with no effect and no error 858response. 859 860#### Parameters 861 862This method has no parameters. 863 864#### Response 865 866true on success 867 868#### Example 869 870Example request: 871 872~~~json 873{ 874 "jsonrpc": "2.0", 875 "id": 1, 876 "method": "framework_disable_cpumask_locks" 877} 878~~~ 879 880Example response: 881 882~~~json 883{ 884 "jsonrpc": "2.0", 885 "id": 1, 886 "result": true 887} 888~~~ 889 890### thread_get_stats {#rpc_thread_get_stats} 891 892Retrieve current statistics of all the threads. 893 894#### Parameters 895 896This method has no parameters. 897 898#### Response 899 900The response is an array of objects containing threads statistics. 901 902#### Example 903 904Example request: 905 906~~~json 907{ 908 "jsonrpc": "2.0", 909 "method": "thread_get_stats", 910 "id": 1 911} 912~~~ 913 914Example response: 915 916~~~json 917{ 918 "jsonrpc": "2.0", 919 "id": 1, 920 "result": { 921 "tick_rate": 2400000000, 922 "threads": [ 923 { 924 "name": "app_thread", 925 "id": 1, 926 "cpumask": "1", 927 "busy": 139223208, 928 "idle": 8641080608, 929 "in_interrupt": false, 930 "active_pollers_count": 1, 931 "timed_pollers_count": 2, 932 "paused_pollers_count": 0 933 } 934 ] 935 } 936} 937~~~ 938 939### thread_set_cpumask {#rpc_thread_set_cpumask} 940 941Set the cpumask of the thread to the specified value. The thread may be migrated 942to one of the specified CPUs. 943 944#### Parameters 945 946Name | Optional | Type | Description 947----------------------- | -------- | ----------- | ----------- 948id | Required | string | Thread ID 949cpumask | Required | string | Cpumask for this thread 950 951#### Response 952 953Completion status of the operation is returned as a boolean. 954 955#### Example 956 957Example request: 958 959~~~json 960{ 961 "jsonrpc": "2.0", 962 "method": "thread_set_cpumask", 963 "id": 1, 964 "params": { 965 "id": "1", 966 "cpumask": "1" 967 } 968} 969~~~ 970 971Example response: 972 973~~~json 974{ 975 "jsonrpc": "2.0", 976 "id": 1, 977 "result": true 978} 979~~~ 980 981### trace_enable_tpoint_group {#rpc_trace_enable_tpoint_group} 982 983Enable trace on a specific tpoint group. For example "bdev" for bdev trace group, 984"all" for all trace groups. 985 986#### Parameters 987 988Name | Optional | Type | Description 989----------------------- | -------- | ----------- | ----------- 990name | Required | string | bdev, nvmf_rdma, nvmf_tcp, blobfs, scsi, iscsi_conn, ftl, all 991 992#### Example 993 994Example request: 995 996~~~json 997{ 998 "jsonrpc": "2.0", 999 "method": "trace_enable_tpoint_group", 1000 "id": 1, 1001 "params": { 1002 "name": "bdev" 1003 } 1004} 1005~~~ 1006 1007Example response: 1008 1009~~~json 1010{ 1011 "jsonrpc": "2.0", 1012 "id": 1, 1013 "result": true 1014} 1015~~~ 1016 1017### trace_disable_tpoint_group {#rpc_trace_disable_tpoint_group} 1018 1019Disable trace on a specific tpoint group. For example "bdev" for bdev trace group, 1020"all" for all trace groups. 1021 1022#### Parameters 1023 1024Name | Optional | Type | Description 1025----------------------- | -------- | ----------- | ----------- 1026name | Required | string | bdev, nvmf_rdma, nvmf_tcp, blobfs, all 1027 1028#### Example 1029 1030Example request: 1031 1032~~~json 1033{ 1034 "jsonrpc": "2.0", 1035 "method": "trace_disable_tpoint_group", 1036 "id": 1, 1037 "params": { 1038 "name": "bdev" 1039 } 1040} 1041~~~ 1042 1043Example response: 1044 1045~~~json 1046{ 1047 "jsonrpc": "2.0", 1048 "id": 1, 1049 "result": true 1050} 1051~~~ 1052 1053### trace_set_tpoint_mask {#rpc_trace_set_tpoint_mask} 1054 1055Enable tracepoint mask on a specific tpoint group. For example "bdev" for bdev trace group, 1056and 0x1 to enable the first tracepoint inside the group (BDEV_IO_START). This command will not 1057disable already active tracepoints or those not specified in the mask. For a full description 1058of all available trace groups, see 1059[tracepoint documentation](https://spdk.io/doc/nvmf_tgt_tracepoints.html). 1060 1061#### Parameters 1062 1063Name | Optional | Type | Description 1064----------------------- | -------- | ----------- | ----------- 1065name | Required | string | bdev, nvmf_rdma, nvmf_tcp, blobfs, scsi, iscsi_conn, ftl 1066tpoint_mask | Required | number | mask to enable tracepoints inside a group 1067 1068#### Example 1069 1070Example request: 1071 1072~~~json 1073{ 1074 "jsonrpc": "2.0", 1075 "method": "trace_set_tpoint_mask", 1076 "id": 1, 1077 "params": { 1078 "name": "bdev", 1079 "tpoint_mask": 0x1 1080 } 1081} 1082~~~ 1083 1084Example response: 1085 1086~~~json 1087{ 1088 "jsonrpc": "2.0", 1089 "id": 1, 1090 "result": true 1091} 1092~~~ 1093 1094### trace_clear_tpoint_mask {#rpc_trace_clear_tpoint_mask} 1095 1096Disable tracepoint mask on a specific tpoint group. For example "bdev" for bdev trace group, 1097and 0x1 to disable the first tracepoint inside the group (BDEV_IO_START). For a full description 1098of all available trace groups, see 1099[tracepoint documentation](https://spdk.io/doc/nvmf_tgt_tracepoints.html). 1100 1101#### Parameters 1102 1103Name | Optional | Type | Description 1104----------------------- | -------- | ----------- | ----------- 1105name | Required | string | bdev, nvmf_rdma, nvmf_tcp, blobfs, scsi, iscsi_conn, ftl 1106tpoint_mask | Required | number | mask to diesable tracepoints inside a group 1107 1108#### Example 1109 1110Example request: 1111 1112~~~json 1113{ 1114 "jsonrpc": "2.0", 1115 "method": "trace_clear_tpoint_mask", 1116 "id": 1, 1117 "params": { 1118 "name": "bdev", 1119 "tpoint_mask": 0x1 1120 } 1121} 1122~~~ 1123 1124Example response: 1125 1126~~~json 1127{ 1128 "jsonrpc": "2.0", 1129 "id": 1, 1130 "result": true 1131} 1132~~~ 1133 1134### trace_get_tpoint_group_mask {#rpc_trace_get_tpoint_group_mask} 1135 1136Display mask info for every group. 1137 1138#### Parameters 1139 1140No parameters required 1141 1142#### Example 1143 1144Example request: 1145 1146~~~json 1147{ 1148 "jsonrpc": "2.0", 1149 "method": "trace_get_tpoint_group_mask", 1150 "id": 1 1151} 1152~~~ 1153 1154Example response: 1155 1156~~~json 1157{ 1158 "jsonrpc": "2.0", 1159 "id": 1, 1160 "result": { 1161 "tpoint_group_mask": "0x0", 1162 "iscsi_conn": { 1163 "enabled": false, 1164 "mask": "0x2" 1165 }, 1166 "scsi": { 1167 "enabled": false, 1168 "mask": "0x4" 1169 }, 1170 "bdev": { 1171 "enabled": false, 1172 "mask": "0x8" 1173 }, 1174 "nvmf_tcp": { 1175 "enabled": false, 1176 "mask": "0x20" 1177 }, 1178 "ftl": { 1179 "enabled": false, 1180 "mask": "0x40" 1181 }, 1182 "blobfs": { 1183 "enabled": false, 1184 "mask": "0x80" 1185 } 1186 } 1187} 1188~~~ 1189 1190### trace_get_info {#rpc_trace_get_info} 1191 1192Get name of shared memory file, list of the available trace point groups 1193and mask of the available trace points for each group 1194 1195#### Parameters 1196 1197No parameters required 1198 1199#### Example 1200 1201Example request: 1202 1203~~~json 1204{ 1205 "jsonrpc": "2.0", 1206 "method": "trace_get_info", 1207 "id": 1 1208} 1209~~~ 1210 1211Example response: 1212 1213~~~json 1214{ 1215 "jsonrpc": "2.0", 1216 "id": 1, 1217 "result": { 1218 "tpoint_shm_path": "/dev/shm/spdk_tgt_trace.pid3071944", 1219 "tpoint_group_mask": "0x8", 1220 "iscsi_conn": { 1221 "mask": "0x2", 1222 "tpoint_mask": "0x0" 1223 }, 1224 "scsi": { 1225 "mask": "0x4", 1226 "tpoint_mask": "0x0" 1227 }, 1228 "bdev": { 1229 "mask": "0x8", 1230 "tpoint_mask": "0xffffffffffffffff" 1231 }, 1232 "nvmf_tcp": { 1233 "mask": "0x20", 1234 "tpoint_mask": "0x0" 1235 }, 1236 "blobfs": { 1237 "mask": "0x80", 1238 "tpoint_mask": "0x0" 1239 }, 1240 "thread": { 1241 "mask": "0x400", 1242 "tpoint_mask": "0x0" 1243 }, 1244 "nvme_pcie": { 1245 "mask": "0x800", 1246 "tpoint_mask": "0x0" 1247 }, 1248 "nvme_tcp": { 1249 "mask": "0x2000", 1250 "tpoint_mask": "0x0" 1251 }, 1252 "bdev_nvme": { 1253 "mask": "0x4000", 1254 "tpoint_mask": "0x0" 1255 } 1256 } 1257} 1258~~~ 1259 1260### log_set_print_level {#rpc_log_set_print_level} 1261 1262Set the current level at which output will additionally be 1263sent to the current console. 1264 1265#### Parameters 1266 1267Name | Optional | Type | Description 1268----------------------- | -------- | ----------- | ----------- 1269level | Required | string | ERROR, WARNING, NOTICE, INFO, DEBUG 1270 1271#### Example 1272 1273Example request: 1274 1275~~~json 1276{ 1277 "jsonrpc": "2.0", 1278 "method": "log_set_print_level", 1279 "id": 1, 1280 "params": { 1281 "level": "ERROR" 1282 } 1283} 1284~~~ 1285 1286Example response: 1287 1288~~~json 1289{ 1290 "jsonrpc": "2.0", 1291 "id": 1, 1292 "result": true 1293} 1294~~~ 1295 1296### log_get_print_level {#rpc_log_get_print_level} 1297 1298Get the current level at which output will additionally be 1299sent to the current console. 1300 1301#### Example 1302 1303Example request: 1304 1305~~~json 1306{ 1307 "jsonrpc": "2.0", 1308 "method": "log_get_print_level", 1309 "id": 1, 1310} 1311~~~ 1312 1313Example response: 1314 1315~~~json 1316{ 1317 "jsonrpc": "2.0", 1318 "id": 1, 1319 "result": "NOTICE" 1320} 1321~~~ 1322 1323### log_set_level {#rpc_log_set_level} 1324 1325Set the current logging level output by the `log` module. 1326 1327#### Parameters 1328 1329Name | Optional | Type | Description 1330----------------------- | -------- | ----------- | ----------- 1331level | Required | string | ERROR, WARNING, NOTICE, INFO, DEBUG 1332 1333#### Example 1334 1335Example request: 1336 1337~~~json 1338{ 1339 "jsonrpc": "2.0", 1340 "method": "log_set_level", 1341 "id": 1, 1342 "params": { 1343 "level": "ERROR" 1344 } 1345} 1346~~~ 1347 1348Example response: 1349 1350~~~json 1351{ 1352 "jsonrpc": "2.0", 1353 "id": 1, 1354 "result": true 1355} 1356~~~ 1357 1358### log_get_level {#rpc_log_get_level} 1359 1360Get the current logging level output by the `log` module. 1361 1362#### Example 1363 1364Example request: 1365 1366~~~json 1367{ 1368 "jsonrpc": "2.0", 1369 "method": "log_get_level", 1370 "id": 1, 1371} 1372~~~ 1373 1374Example response: 1375 1376~~~json 1377{ 1378 "jsonrpc": "2.0", 1379 "id": 1, 1380 "result": "NOTICE" 1381} 1382~~~ 1383 1384### log_set_flag {#rpc_log_set_flag} 1385 1386Enable logging for specific portions of the application. The list of possible 1387log flags can be obtained using the `log_get_flags` RPC and may be different 1388for each application. 1389 1390#### Parameters 1391 1392Name | Optional | Type | Description 1393----------------------- | -------- | ----------- | ----------- 1394flag | Required | string | A log flag, or 'all' 1395 1396#### Example 1397 1398Example request: 1399 1400~~~json 1401{ 1402 "jsonrpc": "2.0", 1403 "method": "log_set_flag", 1404 "id": 1, 1405 "params": { 1406 "flag": "all" 1407 } 1408} 1409~~~ 1410 1411Example response: 1412 1413~~~json 1414{ 1415 "jsonrpc": "2.0", 1416 "id": 1, 1417 "result": true 1418} 1419~~~ 1420 1421### log_clear_flag {#rpc_log_clear_flag} 1422 1423Disable logging for specific portions of the application. The list of possible 1424log flags can be obtained using the `log_get_flags` RPC and may be different 1425for each application. 1426 1427#### Parameters 1428 1429Name | Optional | Type | Description 1430----------------------- | -------- | ----------- | ----------- 1431flag | Required | string | A log flag, or 'all' 1432 1433#### Example 1434 1435Example request: 1436 1437~~~json 1438{ 1439 "jsonrpc": "2.0", 1440 "method": "log_clear_flag", 1441 "id": 1, 1442 "params": { 1443 "flag": "all" 1444 } 1445} 1446~~~ 1447 1448Example response: 1449 1450~~~json 1451{ 1452 "jsonrpc": "2.0", 1453 "id": 1, 1454 "result": true 1455} 1456~~~ 1457 1458### log_get_flags {#rpc_log_get_flags} 1459 1460Get the list of valid flags for this application and whether 1461they are currently enabled. 1462 1463#### Example 1464 1465Example request: 1466 1467~~~json 1468{ 1469 "jsonrpc": "2.0", 1470 "method": "log_get_flags", 1471 "id": 1, 1472} 1473~~~ 1474 1475Example response: 1476 1477~~~json 1478{ 1479 "jsonrpc": "2.0", 1480 "id": 1, 1481 "result": { 1482 "nvmf": true, 1483 "nvme": true, 1484 "aio": false, 1485 "bdev" false 1486 } 1487} 1488~~~ 1489 1490### log_enable_timestamps {#rpc_log_enable_timestamps} 1491 1492Enable or disable timestamps. 1493 1494#### Parameters 1495 1496Name | Optional | Type | Description 1497----------------------- | -------- | ----------- | ----------- 1498enabled | Required | boolean | on or off 1499 1500#### Example 1501 1502Example request: 1503 1504~~~json 1505{ 1506 "jsonrpc": "2.0", 1507 "method": "log_enable_timestamps", 1508 "id": 1, 1509 "params": { 1510 "enabled": true 1511 } 1512} 1513~~~ 1514 1515Example response: 1516 1517~~~json 1518{ 1519 "jsonrpc": "2.0", 1520 "id": 1, 1521 "result": true 1522} 1523~~~ 1524 1525### thread_get_pollers {#rpc_thread_get_pollers} 1526 1527Retrieve current pollers of all the threads. 1528 1529#### Parameters 1530 1531This method has no parameters. 1532 1533### Response 1534 1535The response is an array of objects containing pollers of all the threads. 1536 1537#### Example 1538 1539Example request: 1540 1541~~~json 1542{ 1543 "jsonrpc": "2.0", 1544 "method": "thread_get_pollers", 1545 "id": 1 1546} 1547~~~ 1548 1549Example response: 1550 1551~~~json 1552{ 1553 "jsonrpc": "2.0", 1554 "id": 1, 1555 "result": { 1556 "tick_rate": 2500000000, 1557 "threads": [ 1558 { 1559 "name": "app_thread", 1560 "id": 1, 1561 "active_pollers": [], 1562 "timed_pollers": [ 1563 { 1564 "name": "spdk_rpc_subsystem_poll", 1565 "id": 1, 1566 "state": "waiting", 1567 "run_count": 12345, 1568 "busy_count": 10000, 1569 "period_ticks": 10000000 1570 } 1571 ], 1572 "paused_pollers": [] 1573 } 1574 ] 1575 } 1576} 1577~~~ 1578 1579### thread_get_io_channels {#rpc_thread_get_io_channels} 1580 1581Retrieve current IO channels of all the threads. 1582 1583#### Parameters 1584 1585This method has no parameters. 1586 1587#### Response 1588 1589The response is an array of objects containing IO channels of all the threads. 1590 1591#### Example 1592 1593Example request: 1594 1595~~~json 1596{ 1597 "jsonrpc": "2.0", 1598 "method": "thread_get_io_channels", 1599 "id": 1 1600} 1601~~~ 1602 1603Example response: 1604 1605~~~json 1606{ 1607 "jsonrpc": "2.0", 1608 "id": 1, 1609 "result": { 1610 "tick_rate": 2500000000, 1611 "threads": [ 1612 { 1613 "name": "app_thread", 1614 "io_channels": [ 1615 { 1616 "name": "nvmf_tgt", 1617 "ref": 1 1618 } 1619 ] 1620 } 1621 ] 1622 } 1623} 1624~~~ 1625 1626### env_dpdk_get_mem_stats {#rpc_env_dpdk_get_mem_stats} 1627 1628Write the dpdk memory stats to a file. 1629 1630#### Parameters 1631 1632This method has no parameters. 1633 1634#### Response 1635 1636The response is a pathname to a text file containing the memory stats. 1637 1638#### Example 1639 1640Example request: 1641 1642~~~json 1643{ 1644 "jsonrpc": "2.0", 1645 "method": "env_dpdk_get_mem_stats", 1646 "id": 1 1647} 1648~~~ 1649 1650Example response: 1651 1652~~~json 1653{ 1654 "jsonrpc": "2.0", 1655 "id": 1, 1656 "result": { 1657 "filename": "/tmp/spdk_mem_dump.txt" 1658 } 1659} 1660~~~ 1661 1662## Acceleration Framework Layer {#jsonrpc_components_accel_fw} 1663 1664### accel_get_module_info {#accel_get_module_info} 1665 1666Get a list of valid module names and their supported operations. 1667 1668#### Parameters 1669 1670None 1671 1672#### Example 1673 1674Example request: 1675 1676~~~json 1677{ 1678 "jsonrpc": "2.0", 1679 "method": "accel_get_module_info", 1680 "id": 1 1681} 1682~~~ 1683 1684Example response: 1685 1686~~~json 1687[ 1688 { 1689 "module": "software", 1690 "supported ops": [ 1691 "copy", 1692 "fill", 1693 "dualcast", 1694 "compare", 1695 "crc32c", 1696 "copy_crc32c", 1697 "compress", 1698 "decompress" 1699 ] 1700 }, 1701 { 1702 "module": "dsa", 1703 "supported ops": [ 1704 "copy", 1705 "fill", 1706 "dualcast", 1707 "compare", 1708 "crc32c", 1709 "copy_crc32c" 1710 ] 1711 } 1712] 1713~~~ 1714 1715### accel_get_opc_assignments {#rpc_accel_get_opc_assignments} 1716 1717Get a list of opcode names and their assigned accel_fw modules. 1718 1719#### Parameters 1720 1721None 1722 1723#### Example 1724 1725Example request: 1726 1727~~~json 1728{ 1729 "jsonrpc": "2.0", 1730 "method": "accel_get_opc_assignments", 1731 "id": 1 1732} 1733~~~ 1734 1735Example response: 1736 1737~~~json 1738{ 1739 "jsonrpc": "2.0", 1740 "id": 1, 1741 "result": [ 1742 { 1743 "copy": "software", 1744 "fill": "software", 1745 "dualcast": "software", 1746 "compare": "software", 1747 "crc32c": "software", 1748 "copy_crc32c": "software", 1749 "compress": "software", 1750 "decompress": "software" 1751 } 1752 ] 1753} 1754~~~ 1755 1756### accel_assign_opc {#rpc_accel_assign_opc} 1757 1758Manually assign an operation to a module. 1759 1760#### Parameters 1761 1762Name | Optional | Type | Description 1763----------------------- | -------- | ----------- | ----------------- 1764opname | Required | string | name of operation 1765module | Required | string | name of module 1766 1767#### Example 1768 1769Example request: 1770 1771~~~json 1772{ 1773 "jsonrpc": "2.0", 1774 "method": "accel_assign_opc", 1775 "id": 1, 1776 "params": { 1777 "opname": "copy", 1778 "module": "software" 1779 } 1780} 1781~~~ 1782 1783Example response: 1784 1785~~~json 1786{ 1787 "jsonrpc": "2.0", 1788 "id": 1, 1789 "result": true 1790} 1791~~~ 1792 1793### accel_crypto_key_create {#rpc_accel_crypto_key_create} 1794 1795Create a crypto key which will be used in accel framework 1796 1797#### Parameters 1798 1799Name | Optional | Type | Description 1800-----------|----------| ----------- | ----------------- 1801cipher | Required | string | crypto cipher to use 1802key | Required | string | Key in **hex** form 1803key2 | Optional | string | Optional 2nd part of the key or a tweak in **hex** form 1804tweak_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 1805name | Required | string | The key name 1806 1807#### Example 1808 1809Example request: 1810 1811~~~json 1812{ 1813 "jsonrpc": "2.0", 1814 "method": "accel_crypto_key_create", 1815 "id": 1, 1816 "params": { 1817 "cipher": "AES_XTS", 1818 "key": "00112233445566778899001122334455", 1819 "key2": "00112233445566778899001122334455", 1820 "tweak_mode": "SIMPLE_LBA", 1821 "name": "super_key" 1822 } 1823} 1824~~~ 1825 1826Example response: 1827 1828~~~json 1829{ 1830 "jsonrpc": "2.0", 1831 "id": 1, 1832 "result": true 1833} 1834~~~ 1835 1836### accel_crypto_key_destroy {#rpc_accel_crypto_key_destroy} 1837 1838Destroy a crypto key. The user is responsible for ensuring that the deleted key is not used by acceleration modules. 1839 1840#### Parameters 1841 1842Name | Optional | Type | Description 1843-----------|----------| ----------- | ----------------- 1844name | Required | string | The key name 1845 1846#### Example 1847 1848Example request: 1849 1850~~~json 1851{ 1852 "jsonrpc": "2.0", 1853 "method": "accel_crypto_key_destroy", 1854 "id": 1, 1855 "params": { 1856 "name": "super_key" 1857 } 1858} 1859~~~ 1860 1861Example response: 1862 1863~~~json 1864{ 1865 "jsonrpc": "2.0", 1866 "id": 1, 1867 "result": true 1868} 1869~~~ 1870 1871### accel_crypto_keys_get {#rpc_accel_crypto_keys_get} 1872 1873Get information about existing crypto keys 1874 1875#### Parameters 1876 1877Name | Optional | Type | Description 1878----------------------- |----------| ----------- | ----------------- 1879key_name | Optional | string | If specified, return info about a specific key 1880 1881#### Example 1882 1883Example request: 1884 1885~~~json 1886{ 1887 "jsonrpc": "2.0", 1888 "method": "accel_crypto_keys_get", 1889 "id": 1 1890} 1891~~~ 1892 1893Example response: 1894 1895~~~json 1896{ 1897 "jsonrpc": "2.0", 1898 "id": 1, 1899 "result": [ 1900 { 1901 "name": "test_dek", 1902 "cipher": "AES_XTS", 1903 "key": "00112233445566778899001122334455", 1904 "key2": "11223344556677889900112233445500", 1905 "tweak_mode": "SIMPLE_LBA" 1906 }, 1907 { 1908 "name": "test_dek2", 1909 "cipher": "AES_XTS", 1910 "key": "11223344556677889900112233445500", 1911 "key2": "22334455667788990011223344550011", 1912 "tweak_mode": "SIMPLE_LBA" 1913 } 1914 ] 1915} 1916~~~ 1917 1918### accel_set_driver {#rpc_accel_set_driver} 1919 1920Select platform driver to execute operation chains. Until a driver is selected, all operations are 1921executed through accel modules. 1922 1923#### Parameters 1924 1925Name | Optional | Type | Description 1926----------------------- |----------| ----------- | ----------------- 1927name | Required | string | Name of the platform driver 1928 1929#### Example 1930 1931Example request: 1932 1933~~~json 1934{ 1935 "jsonrpc": "2.0", 1936 "method": "accel_set_driver", 1937 "id": 1 1938 "params": { 1939 "name": "xeon" 1940 } 1941} 1942~~~ 1943 1944Example response: 1945 1946~~~json 1947{ 1948 "jsonrpc": "2.0", 1949 "id": 1, 1950 "result": true 1951} 1952~~~ 1953 1954### accel_set_options {#rpc_accel_set_options} 1955 1956Set accel framework's options. 1957 1958#### Parameters 1959 1960Name | Optional | Type | Description 1961----------------------- |----------| ----------- | ----------------- 1962small_cache_size | Optional | number | Size of the small iobuf cache 1963large_cache_size | Optional | number | Size of the large iobuf cache 1964task_count | Optional | number | Maximum number of tasks per IO channel 1965sequence_count | Optional | number | Maximum number of sequences per IO channel 1966buf_count | Optional | number | Maximum number of accel buffers per IO channel 1967 1968#### Example 1969 1970Example request: 1971 1972~~~json 1973{ 1974 "jsonrpc": "2.0", 1975 "method": "accel_set_options", 1976 "id": 1, 1977 "params": { 1978 "small_cache_size": 128, 1979 "large_cache_size": 32 1980 } 1981} 1982~~~ 1983 1984Example response: 1985 1986~~~json 1987{ 1988 "jsonrpc": "2.0", 1989 "id": 1, 1990 "result": true 1991} 1992~~~ 1993 1994### accel_get_stats {#rpc_accel_get_stats} 1995 1996Retrieve accel framework's statistics. Statistics for opcodes that have never been executed (i.e. 1997all their stats are at 0) aren't included in the `operations` array. 1998 1999#### Parameters 2000 2001None. 2002 2003#### Example 2004 2005Example request: 2006 2007~~~json 2008{ 2009 "jsonrpc": "2.0", 2010 "method": "accel_get_stats", 2011 "id": 1 2012} 2013~~~ 2014 2015Example response: 2016 2017~~~json 2018{ 2019 "jsonrpc": "2.0", 2020 "id": 1, 2021 "result": { 2022 "sequence_executed": 256, 2023 "sequence_failed": 0, 2024 "operations": [ 2025 { 2026 "opcode": "copy", 2027 "executed": 256, 2028 "failed": 0 2029 }, 2030 { 2031 "opcode": "encrypt", 2032 "executed": 128, 2033 "failed": 0 2034 }, 2035 { 2036 "opcode": "decrypt", 2037 "executed": 128, 2038 "failed": 0 2039 } 2040 ] 2041 } 2042} 2043~~~ 2044 2045### accel_error_inject_error {#rpc_accel_error_inject_error} 2046 2047Inject an error to execution of a given operation. Note, that in order for the errors to be 2048actually injected, the error module must be assigned to that operation via `accel_assign_opc`. 2049 2050#### Parameters 2051 2052Name | Optional | Type | Description 2053----------------------- |----------| ----------- | ----------------- 2054opcode | Required | string | Operation to inject errors. 2055type | Required | string | Type of errors to inject ("corrupt": corrupt the data, "failure": fail the operation, "disable": disable error injection). 2056count | Optional | number | Numbers of errors to inject on each IO channel (`UINT64_MAX` by default). 2057interval | Optional | number | Interval between injections. 2058errcode | Optional | number | Error code to inject (only relevant for type=failure). 2059 2060#### Example 2061 2062Example request: 2063 2064~~~json 2065{ 2066 "method": "accel_error_inject_error", 2067 "params": { 2068 "opcode": "crc32c", 2069 "type": "corrupt", 2070 "count": 10000, 2071 "interval": 8 2072 } 2073} 2074~~~ 2075 2076Example response: 2077 2078~~~json 2079{ 2080 "jsonrpc": "2.0", 2081 "id": 1, 2082 "result": true 2083} 2084~~~ 2085 2086### compressdev_scan_accel_module {#rpc_compressdev_scan_accel_module} 2087 2088Set config and enable compressdev accel module offload. 2089Select the DPDK polled mode driver (pmd) for the accel compress module, 20900 = auto-select, 1= QAT only, 2 = mlx5_pci only. 2091 2092#### Parameters 2093 2094Name | Optional | Type | Description 2095----------------------- | -------- | ----------- | ----------- 2096pmd | Required | int | pmd selection 2097 2098#### Example 2099 2100Example request: 2101 2102~~~json 2103{ 2104 "params": { 2105 "pmd": 1 2106 }, 2107 "jsonrpc": "2.0", 2108 "method": "compressdev_scan_accel_module", 2109 "id": 1 2110} 2111~~~ 2112 2113Example response: 2114 2115~~~json 2116{ 2117 "jsonrpc": "2.0", 2118 "id": 1, 2119 "result": true 2120} 2121~~~ 2122 2123### dsa_scan_accel_module {#rpc_dsa_scan_accel_module} 2124 2125Set config and enable dsa accel module offload. 2126This feature is considered as experimental. 2127 2128#### Parameters 2129 2130Name | Optional | Type | Description 2131----------------------- | -------- | ----------- | ----------- 2132config_kernel_mode | Optional | Boolean | If set, will use kernel idxd driver. 2133 2134#### Example 2135 2136Example request: 2137 2138~~~json 2139{ 2140 "params": { 2141 "config_kernel_mode": false 2142 }, 2143 "jsonrpc": "2.0", 2144 "method": "dsa_scan_accel_module", 2145 "id": 1 2146} 2147~~~ 2148 2149Example response: 2150 2151~~~json 2152{ 2153 "jsonrpc": "2.0", 2154 "id": 1, 2155 "result": true 2156} 2157~~~ 2158 2159### iaa_scan_accel_module {#rpc_iaa_scan_accel_module} 2160 2161Enable IAA accel module offload. 2162This feature is considered as experimental. 2163 2164#### Parameters 2165 2166None 2167 2168#### Example 2169 2170Example request: 2171 2172~~~json 2173{ 2174 "jsonrpc": "2.0", 2175 "method": "iaa_scan_accel_module", 2176 "id": 1 2177} 2178~~~ 2179 2180Example response: 2181 2182~~~json 2183{ 2184 "jsonrpc": "2.0", 2185 "id": 1, 2186 "result": true 2187} 2188~~~ 2189 2190### ioat_scan_accel_module {#rpc_ioat_scan_accel_module} 2191 2192Enable ioat accel module offload. 2193 2194#### Parameters 2195 2196None 2197 2198#### Example 2199 2200Example request: 2201 2202~~~json 2203{ 2204 "jsonrpc": "2.0", 2205 "method": "ioat_scan_accel_module", 2206 "id": 1 2207} 2208~~~ 2209 2210Example response: 2211 2212~~~json 2213{ 2214 "jsonrpc": "2.0", 2215 "id": 1, 2216 "result": true 2217} 2218~~~ 2219 2220### dpdk_cryptodev_scan_accel_module {#rpc_dpdk_cryptodev_scan_accel_module} 2221 2222Enable dpdk_cryptodev accel offload 2223 2224#### Parameters 2225 2226None 2227 2228#### Example 2229 2230Example request: 2231 2232~~~json 2233{ 2234 "jsonrpc": "2.0", 2235 "method": "dpdk_cryptodev_scan_accel_module", 2236 "id": 1 2237} 2238~~~ 2239 2240Example response: 2241 2242~~~json 2243{ 2244 "jsonrpc": "2.0", 2245 "id": 1, 2246 "result": true 2247} 2248~~~ 2249 2250### dpdk_cryptodev_set_driver {#rpc_dpdk_cryptodev_set_driver} 2251 2252Set the DPDK cryptodev driver 2253 2254#### Parameters 2255 2256Name | Optional | Type | Description 2257----------------------- |----------|--------| ----------- 2258crypto_pmd | Required | string | The driver, can be one of crypto_aesni_mb, crypto_qat or mlx5_pci 2259 2260#### Example 2261 2262Example request: 2263 2264~~~json 2265{ 2266 "jsonrpc": "2.0", 2267 "method": "dpdk_cryptodev_set_driver", 2268 "id": 1, 2269 "params": { 2270 "crypto_pmd": "crypto_aesni_mb" 2271 } 2272} 2273~~~ 2274 2275Example response: 2276 2277~~~json 2278{ 2279 "jsonrpc": "2.0", 2280 "id": 1, 2281 "result": true 2282} 2283~~~ 2284 2285### dpdk_cryptodev_get_driver {#rpc_dpdk_cryptodev_get_driver} 2286 2287Get the DPDK cryptodev driver 2288 2289#### Parameters 2290 2291None 2292 2293#### Example 2294 2295Example request: 2296 2297~~~json 2298{ 2299 "jsonrpc": "2.0", 2300 "method": "dpdk_cryptodev_get_driver", 2301 "id": 1 2302} 2303~~~ 2304 2305Example response: 2306 2307~~~json 2308{ 2309 "jsonrpc": "2.0", 2310 "id": 1, 2311 "result": "crypto_aesni_mb" 2312} 2313~~~ 2314 2315### mlx5_scan_accel_module {#rpc_mlx5_scan_accel_module} 2316 2317Enable mlx5 accel offload 2318 2319#### Parameters 2320 2321Name | Optional | Type | Description 2322----------------------- | -------- |--------| ----------- 2323qp_size | Optional | number | qpair size 2324num_requests | Optional | number | Size of the shared requests pool 2325 2326#### Example 2327 2328Example request: 2329 2330~~~json 2331{ 2332 "jsonrpc": "2.0", 2333 "method": "mlx5_scan_accel_module", 2334 "id": 1, 2335 "params": { 2336 "qp_size": 256, 2337 "num_requests": 2047 2338 } 2339} 2340~~~ 2341 2342Example response: 2343 2344~~~json 2345{ 2346 "jsonrpc": "2.0", 2347 "id": 1, 2348 "result": true 2349} 2350~~~ 2351 2352## Block Device Abstraction Layer {#jsonrpc_components_bdev} 2353 2354### bdev_set_options {#rpc_bdev_set_options} 2355 2356Set global parameters for the block device (bdev) subsystem. This RPC may only be called 2357before SPDK subsystems have been initialized. 2358 2359#### Parameters 2360 2361Name | Optional | Type | Description 2362----------------------- | -------- | ----------- | ----------- 2363bdev_io_pool_size | Optional | number | Number of spdk_bdev_io structures in shared buffer pool 2364bdev_io_cache_size | Optional | number | Maximum number of spdk_bdev_io structures cached per thread 2365bdev_auto_examine | Optional | boolean | If set to false, the bdev layer will not examine every disks automatically 2366iobuf_small_cache_size | Optional | number | Size of the small iobuf per thread cache 2367iobuf_large_cache_size | Optional | number | Size of the large iobuf per thread cache 2368 2369#### Example 2370 2371Example request: 2372 2373~~~json 2374{ 2375 "jsonrpc": "2.0", 2376 "id": 1, 2377 "method": "bdev_set_options", 2378 "params": { 2379 "bdev_io_pool_size": 65536, 2380 "bdev_io_cache_size": 256 2381 } 2382} 2383~~~ 2384 2385Example response: 2386 2387~~~json 2388{ 2389 "jsonrpc": "2.0", 2390 "id": 1, 2391 "result": true 2392} 2393~~~ 2394 2395### bdev_get_bdevs {#rpc_bdev_get_bdevs} 2396 2397Get information about block devices (bdevs). 2398 2399#### Parameters 2400 2401The user may specify no parameters in order to list all block devices, or a block device may be 2402specified by name. If a timeout is specified, the method will block until a bdev with a specified 2403name appears or the timeout expires. By default, the timeout is zero, meaning the method returns 2404immediately whether the bdev exists or not. 2405 2406Name | Optional | Type | Description 2407----------------------- | -------- | ----------- | ----------- 2408name | Optional | string | Block device name 2409timeout | Optional | number | Time (ms) to wait for a bdev with specified name to appear 2410 2411#### Response 2412 2413The response is an array of objects containing information about the requested block devices. 2414 2415#### Example 2416 2417Example request: 2418 2419~~~json 2420{ 2421 "jsonrpc": "2.0", 2422 "id": 1, 2423 "method": "bdev_get_bdevs", 2424 "params": { 2425 "name": "Malloc0" 2426 } 2427} 2428~~~ 2429 2430Example response: 2431 2432~~~json 2433{ 2434 "jsonrpc": "2.0", 2435 "id": 1, 2436 "result": [ 2437 { 2438 "name": "Malloc0", 2439 "product_name": "Malloc disk", 2440 "block_size": 512, 2441 "num_blocks": 20480, 2442 "claimed": false, 2443 "zoned": false, 2444 "supported_io_types": { 2445 "read": true, 2446 "write": true, 2447 "unmap": true, 2448 "write_zeroes": true, 2449 "flush": true, 2450 "reset": true, 2451 "nvme_admin": false, 2452 "nvme_io": false 2453 }, 2454 "driver_specific": {} 2455 } 2456 ] 2457} 2458~~~ 2459 2460### bdev_examine {#rpc_bdev_examine} 2461 2462Request that the bdev layer examines the given bdev for metadata and creates 2463new bdevs if metadata is found. This is only necessary if `auto_examine` has 2464been set to false using `bdev_set_options`. By default, `auto_examine` is true 2465and bdev examination is automatic. 2466 2467#### Parameters 2468 2469Name | Optional | Type | Description 2470----------------------- | -------- | ----------- | ----------- 2471name | Required | string | Block device name 2472 2473#### Response 2474 2475The response is an array of objects containing I/O statistics of the requested block devices. 2476 2477#### Example 2478 2479Example request: 2480 2481~~~json 2482{ 2483 "jsonrpc": "2.0", 2484 "id": 1, 2485 "method": "bdev_examine", 2486 "params": { 2487 "name": "Nvme0n1" 2488 } 2489} 2490~~~ 2491 2492Example response: 2493 2494~~~json 2495{ 2496 "jsonrpc": "2.0", 2497 "id": 1, 2498 "result": true 2499} 2500~~~ 2501 2502### bdev_wait_for_examine {#rpc_bdev_wait_for_examine} 2503 2504Report when all bdevs have been examined by every bdev module. 2505 2506#### Parameters 2507 2508None 2509 2510#### Response 2511 2512The response is sent when all bdev modules had a chance to examine every bdev. 2513 2514#### Example 2515 2516Example request: 2517 2518~~~json 2519{ 2520 "jsonrpc": "2.0", 2521 "method": "bdev_wait_for_examine", 2522 "id": 1 2523} 2524~~~ 2525 2526Example response: 2527 2528~~~json 2529{ 2530 "jsonrpc": "2.0", 2531 "id": 1, 2532 "result": true 2533} 2534~~~ 2535 2536### bdev_get_iostat {#rpc_bdev_get_iostat} 2537 2538Get I/O statistics of block devices (bdevs). 2539 2540#### Parameters 2541 2542The user may specify no parameters in order to list all block devices, or a block device may be 2543specified by name. 2544 2545Name | Optional | Type | Description 2546----------------------- | -------- | ----------- | ----------- 2547name | Optional | string | Block device name 2548per_channel | Optional | bool | Display per channel data for specified block device. 2549 2550#### Response 2551 2552The response is an array of objects containing I/O statistics of the requested block devices. 2553 2554#### Example 2555 2556Example request: 2557 2558~~~json 2559{ 2560 "jsonrpc": "2.0", 2561 "id": 1, 2562 "method": "bdev_get_iostat", 2563 "params": { 2564 "name": "Nvme0n1", 2565 "per_channel": false 2566 } 2567} 2568~~~ 2569 2570Example response: 2571 2572~~~json 2573{ 2574 "jsonrpc": "2.0", 2575 "id": 1, 2576 "result": { 2577 "tick_rate": 2200000000, 2578 "bdevs" : [ 2579 { 2580 "name": "Nvme0n1", 2581 "bytes_read": 36864, 2582 "num_read_ops": 2, 2583 "bytes_written": 0, 2584 "num_write_ops": 0, 2585 "bytes_unmapped": 0, 2586 "num_unmap_ops": 0, 2587 "read_latency_ticks": 178904, 2588 "write_latency_ticks": 0, 2589 "unmap_latency_ticks": 0, 2590 "queue_depth_polling_period": 2, 2591 "queue_depth": 0, 2592 "io_time": 0, 2593 "weighted_io_time": 0 2594 } 2595 ] 2596 } 2597} 2598~~~ 2599 2600### bdev_reset_iostat {#rpc_bdev_reset_iostat} 2601 2602Reset I/O statistics of block devices (bdevs). Note that if one consumer resets I/O statistics, 2603it affects all other consumers. 2604 2605#### Parameters 2606 2607The user may specify no parameters in order to reset I/O statistics for all block devices, or 2608a block device may be specified by name. 2609 2610Name | Optional | Type | Description 2611----------------------- | -------- | ----------- | ----------- 2612name | Optional | string | Block device name 2613mode | Optional | string | Mode to reset I/O statistics: all, maxmin (default: all) 2614 2615#### Example 2616 2617Example request: 2618 2619~~~json 2620{ 2621 "jsonrpc": "2.0", 2622 "id": 1, 2623 "method": "bdev_reset_iostat", 2624 "params": { 2625 "name": "Nvme0n1" 2626 } 2627} 2628~~~ 2629 2630Example response: 2631 2632~~~json 2633{ 2634 "jsonrpc": "2.0", 2635 "id": 1, 2636 "result": true 2637} 2638~~~ 2639 2640### bdev_enable_histogram {#rpc_bdev_enable_histogram} 2641 2642Control whether collecting data for histogram is enabled for specified bdev. 2643 2644#### Parameters 2645 2646Name | Optional | Type | Description 2647----------------------- | -------- | ----------- | ----------- 2648name | Required | string | Block device name 2649enable | Required | boolean | Enable or disable histogram on specified device 2650 2651#### Example 2652 2653Example request: 2654 2655~~~json 2656{ 2657 "jsonrpc": "2.0", 2658 "id": 1, 2659 "method": "bdev_enable_histogram", 2660 "params": { 2661 "name": "Nvme0n1" 2662 "enable": true 2663 } 2664} 2665~~~ 2666 2667Example response: 2668 2669~~~json 2670{ 2671 "jsonrpc": "2.0", 2672 "id": 1, 2673 "result": true 2674} 2675~~~ 2676 2677### bdev_get_histogram {#rpc_bdev_get_histogram} 2678 2679Get latency histogram for specified bdev. 2680 2681#### Parameters 2682 2683Name | Optional | Type | Description 2684----------------------- | -------- | ----------- | ----------- 2685name | Required | string | Block device name 2686 2687#### Result 2688 2689Name | Description 2690------------------------| ----------- 2691histogram | Base64 encoded histogram 2692bucket_shift | Granularity of the histogram buckets 2693tsc_rate | Ticks per second 2694 2695#### Example 2696 2697Example request: 2698 2699~~~json 2700{ 2701 "jsonrpc": "2.0", 2702 "id": 1, 2703 "method": "bdev_get_histogram", 2704 "params": { 2705 "name": "Nvme0n1" 2706 } 2707} 2708~~~ 2709 2710Example response: 2711Note that histogram field is trimmed, actual encoded histogram length is ~80kb. 2712 2713~~~json 2714{ 2715 "jsonrpc": "2.0", 2716 "id": 1, 2717 "result": { 2718 "histogram": "AAAAAAAAAAAAAA...AAAAAAAAA==", 2719 "tsc_rate": 2300000000, 2720 "bucket_shift": 7 2721 } 2722} 2723~~~ 2724 2725### bdev_set_qos_limit {#rpc_bdev_set_qos_limit} 2726 2727Set the quality of service rate limit on a bdev. 2728 2729#### Parameters 2730 2731Name | Optional | Type | Description 2732----------------------- | -------- | ----------- | ----------- 2733name | Required | string | Block device name 2734rw_ios_per_sec | Optional | number | Number of R/W I/Os per second to allow. 0 means unlimited. 2735rw_mbytes_per_sec | Optional | number | Number of R/W megabytes per second to allow. 0 means unlimited. 2736r_mbytes_per_sec | Optional | number | Number of Read megabytes per second to allow. 0 means unlimited. 2737w_mbytes_per_sec | Optional | number | Number of Write megabytes per second to allow. 0 means unlimited. 2738 2739#### Example 2740 2741Example request: 2742 2743~~~json 2744{ 2745 "jsonrpc": "2.0", 2746 "id": 1, 2747 "method": "bdev_set_qos_limit", 2748 "params": { 2749 "name": "Malloc0" 2750 "rw_ios_per_sec": 20000 2751 "rw_mbytes_per_sec": 100 2752 "r_mbytes_per_sec": 50 2753 "w_mbytes_per_sec": 50 2754 } 2755} 2756~~~ 2757 2758Example response: 2759 2760~~~json 2761{ 2762 "jsonrpc": "2.0", 2763 "id": 1, 2764 "result": true 2765} 2766~~~ 2767 2768### bdev_set_qd_sampling_period {#rpc_bdev_set_qd_sampling_period} 2769 2770Enable queue depth tracking on a specified bdev. 2771 2772#### Parameters 2773 2774Name | Optional | Type | Description 2775----------------------- | -------- | ----------- | ----------- 2776name | Required | string | Block device name 2777period | Required | int | period (in microseconds).If set to 0, polling will be disabled. 2778 2779#### Example 2780 2781Example request: 2782 2783~~~json 2784{ 2785 "jsonrpc": "2.0", 2786 "method": "bdev_set_qd_sampling_period", 2787 "id": 1, 2788 "params": { 2789 "name": "Malloc0", 2790 "period": 20 2791 } 2792} 2793~~~ 2794 2795Example response: 2796 2797~~~json 2798{ 2799 "jsonrpc": "2.0", 2800 "id": 1, 2801 "result": true 2802} 2803~~~ 2804 2805### bdev_compress_create {#rpc_bdev_compress_create} 2806 2807Create a new compress bdev on a given base bdev. 2808 2809#### Parameters 2810 2811Name | Optional | Type | Description 2812----------------------- | -------- | ----------- | ----------- 2813base_bdev_name | Required | string | Name of the base bdev 2814pm_path | Required | string | Path to persistent memory 2815lb_size | Optional | int | Compressed vol logical block size (512 or 4096) 2816 2817#### Result 2818 2819Name of newly created bdev. 2820 2821#### Example 2822 2823Example request: 2824 2825~~~json 2826{ 2827 "params": { 2828 "base_bdev_name": "Nvme0n1", 2829 "pm_path": "/pm_files", 2830 "lb_size": 4096 2831 }, 2832 "jsonrpc": "2.0", 2833 "method": "bdev_compress_create", 2834 "id": 1 2835} 2836~~~ 2837 2838### bdev_compress_delete {#rpc_bdev_compress_delete} 2839 2840Delete a compressed bdev. 2841 2842#### Parameters 2843 2844Name | Optional | Type | Description 2845----------------------- | -------- | ----------- | ----------- 2846name | Required | string | Name of the compress bdev 2847 2848#### Example 2849 2850Example request: 2851 2852~~~json 2853{ 2854 "params": { 2855 "name": "COMP_Nvme0n1" 2856 }, 2857 "jsonrpc": "2.0", 2858 "method": "bdev_compress_delete", 2859 "id": 1 2860} 2861~~~ 2862 2863Example response: 2864 2865~~~json 2866{ 2867 "jsonrpc": "2.0", 2868 "id": 1, 2869 "result": true 2870} 2871~~~ 2872 2873### bdev_compress_get_orphans {#rpc_bdev_compress_get_orphans} 2874 2875Get a list of compressed volumes that are missing their pmem metadata. 2876 2877#### Parameters 2878 2879Name | Optional | Type | Description 2880----------------------- | -------- | ----------- | ----------- 2881name | Required | string | Name of the compress bdev 2882 2883#### Example 2884 2885Example request: 2886 2887~~~json 2888{ 2889 "params": { 2890 "name": "COMP_Nvme0n1" 2891 }, 2892 "jsonrpc": "2.0", 2893 "method": "bdev_compress_get_orphans", 2894 "id": 1 2895} 2896~~~ 2897 2898Example response: 2899 2900~~~json 2901{ 2902 "jsonrpc": "2.0", 2903 "id": 1, 2904 "name": "COMP_Nvme0n1" 2905} 2906~~~ 2907 2908### bdev_crypto_create {#rpc_bdev_crypto_create} 2909 2910Create a new crypto bdev on a given base bdev. 2911 2912#### Parameters 2913 2914Name | Optional | Type | Description 2915----------------------- |----------| ----------- | ----------- 2916base_bdev_name | Required | string | Name of the base bdev 2917name | Required | string | Name of the crypto vbdev to create 2918crypto_pmd | Optional | string | Name of the crypto device driver. Obsolete, see accel_crypto_key_create 2919key | Optional | string | Key in hex form. Obsolete, see accel_crypto_key_create 2920cipher | Optional | string | Cipher to use, AES_CBC or AES_XTS (QAT and MLX5). Obsolete, see accel_crypto_key_create 2921key2 | Optional | string | 2nd key in hex form only required for cipher AET_XTS. Obsolete, see accel_crypto_key_create 2922key_name | Optional | string | Name of the key created with accel_crypto_key_create 2923module | Optional | string | Name of the accel module which is used to create a key (if no key_name specified) 2924 2925Both key and key2 must be passed in the hexlified form. For example, 256bit AES key may look like this: 2926afd9477abf50254219ccb75965fbe39f23ebead5676e292582a0a67f66b88215 2927 2928#### Result 2929 2930Name of newly created bdev. 2931 2932#### Example 2933 2934Example request: 2935 2936~~~json 2937{ 2938 "params": { 2939 "base_bdev_name": "Nvme0n1", 2940 "name": "my_crypto_bdev", 2941 "crypto_pmd": "crypto_aesni_mb", 2942 "key": "12345678901234561234567890123456", 2943 "cipher": "AES_CBC" 2944 }, 2945 "jsonrpc": "2.0", 2946 "method": "bdev_crypto_create", 2947 "id": 1 2948} 2949~~~ 2950 2951Example response: 2952 2953~~~json 2954{ 2955 2956 "jsonrpc": "2.0", 2957 "id": 1, 2958 "result": "my_crypto_bdev" 2959} 2960~~~ 2961 2962### bdev_crypto_delete {#rpc_bdev_crypto_delete} 2963 2964Delete a crypto bdev. 2965 2966#### Parameters 2967 2968Name | Optional | Type | Description 2969----------------------- | -------- | ----------- | ----------- 2970name | Required | string | Name of the crypto bdev 2971 2972#### Example 2973 2974Example request: 2975 2976~~~json 2977{ 2978 "params": { 2979 "name": "my_crypto_bdev" 2980 }, 2981 "jsonrpc": "2.0", 2982 "method": "bdev_crypto_delete", 2983 "id": 1 2984} 2985~~~ 2986 2987Example response: 2988 2989~~~json 2990{ 2991 "jsonrpc": "2.0", 2992 "id": 1, 2993 "result": true 2994} 2995~~~ 2996 2997### bdev_ocf_create {#rpc_bdev_ocf_create} 2998 2999Construct new OCF bdev. 3000Command accepts cache mode that is going to be used. 3001You can find more details about supported cache modes in the [OCF documentation](https://open-cas.github.io/cache_configuration.html#cache-mode) 3002 3003#### Parameters 3004 3005Name | Optional | Type | Description 3006----------------------- | -------- | ----------- | ----------- 3007name | Required | string | Bdev name to use 3008mode | Required | string | OCF cache mode: wb, wt, pt, wa, wi, wo 3009cache_line_size | Optional | int | OCF cache line size in KiB: 4, 8, 16, 32, 64 3010cache_bdev_name | Required | string | Name of underlying cache bdev 3011core_bdev_name | Required | string | Name of underlying core bdev 3012 3013#### Result 3014 3015Name of newly created bdev. 3016 3017#### Example 3018 3019Example request: 3020 3021~~~json 3022{ 3023 "params": { 3024 "name": "ocf0", 3025 "mode": "wt", 3026 "cache_line_size": 64, 3027 "cache_bdev_name": "Nvme0n1", 3028 "core_bdev_name": "aio0" 3029 }, 3030 "jsonrpc": "2.0", 3031 "method": "bdev_ocf_create", 3032 "id": 1 3033} 3034~~~ 3035 3036Example response: 3037 3038~~~json 3039{ 3040 "jsonrpc": "2.0", 3041 "id": 1, 3042 "result": "ocf0" 3043} 3044~~~ 3045 3046### bdev_ocf_delete {#rpc_bdev_ocf_delete} 3047 3048Delete the OCF bdev 3049 3050#### Parameters 3051 3052Name | Optional | Type | Description 3053----------------------- | -------- | ----------- | ----------- 3054name | Required | string | Bdev name 3055 3056#### Example 3057 3058Example request: 3059 3060~~~json 3061{ 3062 "params": { 3063 "name": "ocf0" 3064 }, 3065 "jsonrpc": "2.0", 3066 "method": "bdev_ocf_delete", 3067 "id": 1 3068} 3069~~~ 3070 3071Example response: 3072 3073~~~json 3074{ 3075 "jsonrpc": "2.0", 3076 "id": 1, 3077 "result": true 3078} 3079~~~ 3080 3081### bdev_ocf_get_stats {#rpc_bdev_ocf_get_stats} 3082 3083Get statistics of chosen OCF block device. 3084 3085#### Parameters 3086 3087Name | Optional | Type | Description 3088----------------------- | -------- | ----------- | ----------- 3089name | Required | string | Block device name 3090 3091#### Response 3092 3093Statistics as json object. 3094 3095#### Example 3096 3097Example request: 3098 3099~~~json 3100{ 3101 "params": { 3102 "name": "ocf0" 3103 }, 3104 "jsonrpc": "2.0", 3105 "method": "bdev_ocf_get_stats", 3106 "id": 1 3107} 3108~~~ 3109 3110Example response: 3111 3112~~~json 3113{ 3114 "jsonrpc": "2.0", 3115 "id": 1, 3116 "result": [ 3117 "usage": { 3118 "clean": { 3119 "count": 76033, 3120 "units": "4KiB blocks", 3121 "percentage": "100.0" 3122 }, 3123 "free": { 3124 "count": 767, 3125 "units": "4KiB blocks", 3126 "percentage": "0.9" 3127 }, 3128 "occupancy": { 3129 "count": 76033, 3130 "units": "4KiB blocks", 3131 "percentage": "99.0" 3132 }, 3133 "dirty": { 3134 "count": 0, 3135 "units": "4KiB blocks", 3136 "percentage": "0.0" 3137 } 3138 }, 3139 "requests": { 3140 "rd_total": { 3141 "count": 2, 3142 "units": "Requests", 3143 "percentage": "0.0" 3144 }, 3145 "wr_full_misses": { 3146 "count": 76280, 3147 "units": "Requests", 3148 "percentage": "35.6" 3149 }, 3150 "rd_full_misses": { 3151 "count": 1, 3152 "units": "Requests", 3153 "percentage": "0.0" 3154 }, 3155 "rd_partial_misses": { 3156 "count": 0, 3157 "units": "Requests", 3158 "percentage": "0.0" 3159 }, 3160 "wr_total": { 3161 "count": 212416, 3162 "units": "Requests", 3163 "percentage": "99.2" 3164 }, 3165 "wr_pt": { 3166 "count": 1535, 3167 "units": "Requests", 3168 "percentage": "0.7" 3169 }, 3170 "wr_partial_misses": { 3171 "count": 0, 3172 "units": "Requests", 3173 "percentage": "0.0" 3174 }, 3175 "serviced": { 3176 "count": 212418, 3177 "units": "Requests", 3178 "percentage": "99.2" 3179 }, 3180 "rd_pt": { 3181 "count": 0, 3182 "units": "Requests", 3183 "percentage": "0.0" 3184 }, 3185 "total": { 3186 "count": 213953, 3187 "units": "Requests", 3188 "percentage": "100.0" 3189 }, 3190 "rd_hits": { 3191 "count": 1, 3192 "units": "Requests", 3193 "percentage": "0.0" 3194 }, 3195 "wr_hits": { 3196 "count": 136136, 3197 "units": "Requests", 3198 "percentage": "63.6" 3199 } 3200 }, 3201 "errors": { 3202 "total": { 3203 "count": 0, 3204 "units": "Requests", 3205 "percentage": "0.0" 3206 }, 3207 "cache_obj_total": { 3208 "count": 0, 3209 "units": "Requests", 3210 "percentage": "0.0" 3211 }, 3212 "core_obj_total": { 3213 "count": 0, 3214 "units": "Requests", 3215 "percentage": "0.0" 3216 }, 3217 "cache_obj_rd": { 3218 "count": 0, 3219 "units": "Requests", 3220 "percentage": "0.0" 3221 }, 3222 "core_obj_wr": { 3223 "count": 0, 3224 "units": "Requests", 3225 "percentage": "0.0" 3226 }, 3227 "core_obj_rd": { 3228 "count": 0, 3229 "units": "Requests", 3230 "percentage": "0.0" 3231 }, 3232 "cache_obj_wr": { 3233 "count": 0, 3234 "units": "Requests", 3235 "percentage": "0.0" 3236 } 3237 }, 3238 "blocks": { 3239 "volume_rd": { 3240 "count": 9, 3241 "units": "4KiB blocks", 3242 "percentage": "0.0" 3243 }, 3244 "volume_wr": { 3245 "count": 213951, 3246 "units": "4KiB blocks", 3247 "percentage": "99.9" 3248 }, 3249 "cache_obj_total": { 3250 "count": 212425, 3251 "units": "4KiB blocks", 3252 "percentage": "100.0" 3253 }, 3254 "core_obj_total": { 3255 "count": 213959, 3256 "units": "4KiB blocks", 3257 "percentage": "100.0" 3258 }, 3259 "cache_obj_rd": { 3260 "count": 1, 3261 "units": "4KiB blocks", 3262 "percentage": "0.0" 3263 }, 3264 "core_obj_wr": { 3265 "count": 213951, 3266 "units": "4KiB blocks", 3267 "percentage": "99.9" 3268 }, 3269 "volume_total": { 3270 "count": 213960, 3271 "units": "4KiB blocks", 3272 "percentage": "100.0" 3273 }, 3274 "core_obj_rd": { 3275 "count": 8, 3276 "units": "4KiB blocks", 3277 "percentage": "0.0" 3278 }, 3279 "cache_obj_wr": { 3280 "count": 212424, 3281 "units": "4KiB blocks", 3282 "percentage": "99.9" 3283 } 3284 ] 3285} 3286~~~ 3287 3288### bdev_ocf_reset_stats {#rpc_bdev_ocf_reset_stats} 3289 3290Reset statistics of chosen OCF block device. 3291 3292#### Parameters 3293 3294Name | Optional | Type | Description 3295----------------------- | -------- | ----------- | ----------- 3296name | Required | string | Block device name 3297 3298#### Response 3299 3300Completion status of reset statistics operation returned as a boolean. 3301 3302#### Example 3303 3304Example request: 3305 3306~~~json 3307{ 3308 "params": { 3309 "name": "ocf0" 3310 }, 3311 "jsonrpc": "2.0", 3312 "method": "bdev_ocf_reset_stats", 3313 "id": 1 3314} 3315~~~ 3316 3317Example response: 3318 3319~~~json 3320{ 3321 "jsonrpc": "2.0", 3322 "id": 1, 3323 "result": true 3324} 3325~~~ 3326 3327### bdev_ocf_get_bdevs {#rpc_bdev_ocf_get_bdevs} 3328 3329Get list of OCF devices including unregistered ones. 3330 3331#### Parameters 3332 3333Name | Optional | Type | Description 3334----------------------- | -------- | ----------- | ----------- 3335name | Optional | string | Name of OCF vbdev or name of cache device or name of core device 3336 3337#### Response 3338 3339Array of OCF devices with their current status, along with core and cache bdevs. 3340 3341#### Example 3342 3343Example request: 3344 3345~~~json 3346{ 3347 "jsonrpc": "2.0", 3348 "method": "bdev_ocf_get_bdevs", 3349 "id": 1 3350} 3351~~~ 3352 3353Example response: 3354 3355~~~json 3356{ 3357 "jsonrpc": "2.0", 3358 "id": 1, 3359 "result": [ 3360 { 3361 "name": "PartCache", 3362 "started": false, 3363 "cache": { 3364 "name": "Malloc0", 3365 "attached": true 3366 }, 3367 "core": { 3368 "name": "Malloc1", 3369 "attached": false 3370 } 3371 } 3372 ] 3373} 3374~~~ 3375 3376### bdev_ocf_set_cache_mode {#rpc_bdev_ocf_set_cache_mode} 3377 3378Set new cache mode on OCF bdev. 3379 3380#### Parameters 3381 3382Name | Optional | Type | Description 3383----------------------- | -------- | ----------- | ----------- 3384name | Required | string | Bdev name 3385mode | Required | string | OCF cache mode: wb, wt, pt, wa, wi, wo 3386 3387#### Response 3388 3389New cache mode name. 3390 3391#### Example 3392 3393Example request: 3394 3395~~~json 3396{ 3397 "params": { 3398 "name": "ocf0", 3399 "mode": "pt", 3400 }, 3401 "jsonrpc": "2.0", 3402 "method": "bdev_ocf_set_cache_mode", 3403 "id": 1 3404} 3405~~~ 3406 3407Example response: 3408 3409~~~json 3410{ 3411 "jsonrpc": "2.0", 3412 "id": 1, 3413 "result": "pt" 3414} 3415~~~ 3416 3417### bdev_ocf_set_seqcutoff {#rpc_bdev_ocf_set_seqcutoff} 3418 3419Set sequential cutoff parameters on all cores for the given OCF cache device. 3420A brief description of this functionality can be found in [OpenCAS documentation](https://open-cas.github.io/guide_tool_details.html#seq-cutoff). 3421 3422#### Parameters 3423 3424Name | Optional | Type | Description 3425----------------------- | -------- | ----------- | ----------- 3426name | Required | string | Bdev name 3427policy | Required | string | Sequential cutoff policy: always, full, never 3428threshold | Optional | int | Activation threshold in KiB 3429promotion_count | Optional | int | Promotion request count 3430 3431#### Example 3432 3433Example request: 3434 3435~~~json 3436{ 3437 "params": { 3438 "name": "ocf0", 3439 "policy": "full", 3440 "threshold": 4, 3441 "promotion_count": 2 3442 }, 3443 "jsonrpc": "2.0", 3444 "method": "bdev_ocf_set_seqcutoff", 3445 "id": 1 3446} 3447~~~ 3448 3449Example response: 3450 3451~~~json 3452{ 3453 "jsonrpc": "2.0", 3454 "id": 1, 3455 "result": true 3456} 3457~~~ 3458 3459### bdev_ocf_flush_start {#rpc_bdev_ocf_flush_start} 3460 3461Start flushing OCF cache device. 3462 3463Automatic flushes of dirty data are managed by OCF cleaning policy settings. 3464In addition to that, all dirty data is flushed to core device when there is 3465an attempt to stop caching. 3466On the other hand, this RPC call gives a possibility to flush dirty data manually 3467when there is a need for it, e.g. to speed up the shutdown process when data 3468hasn't been flushed for a long time. 3469This RPC returns immediately, and flush is then being performed in the 3470background. To see the status of flushing operation use bdev_ocf_flush_status. 3471 3472#### Parameters 3473 3474Name | Optional | Type | Description 3475----------------------- | -------- | ----------- | ----------- 3476name | Required | string | Bdev name 3477 3478#### Example 3479 3480Example request: 3481 3482~~~json 3483{ 3484 "params": { 3485 "name": "ocf0" 3486 }, 3487 "jsonrpc": "2.0", 3488 "method": "bdev_ocf_flush_start", 3489 "id": 1 3490} 3491~~~ 3492 3493Example response: 3494 3495~~~json 3496{ 3497 "jsonrpc": "2.0", 3498 "id": 1, 3499 "result": true 3500} 3501~~~ 3502 3503### bdev_ocf_flush_status {#rpc_bdev_ocf_flush_status} 3504 3505Get flush status of OCF cache device. 3506 3507Automatic flushes of dirty data are managed by OCF cleaning policy settings. 3508In addition to that, all dirty data is flushed to core device when there is 3509an attempt to stop caching. 3510On the other hand, there is a possibility to flush dirty data manually 3511when there is a need for it, e.g. to speed up the shutdown process when data 3512hasn't been flushed for a long time. 3513This RPC reports if such manual flush is still in progress and if the operation 3514was successful. To start manual flush use bdev_ocf_flush_start. 3515 3516#### Parameters 3517 3518Name | Optional | Type | Description 3519----------------------- | -------- | ----------- | ----------- 3520name | Required | string | Bdev name 3521 3522#### Response 3523 3524Status of OCF cache device flush. 3525 3526#### Example 3527 3528Example request: 3529 3530~~~json 3531{ 3532 "params": { 3533 "name": "ocf0" 3534 }, 3535 "jsonrpc": "2.0", 3536 "method": "bdev_ocf_flush_status", 3537 "id": 1 3538} 3539~~~ 3540 3541Example response: 3542 3543~~~json 3544{ 3545 "jsonrpc": "2.0", 3546 "id": 1, 3547 "result": { 3548 "in_progress": false, 3549 "status": 0 3550 } 3551} 3552~~~ 3553 3554### bdev_malloc_create {#rpc_bdev_malloc_create} 3555 3556Construct @ref bdev_config_malloc 3557 3558The `dif_type` parameter can have 0, 1, 2, or 3, and controls the check of the guard tag and the reference tag. 3559If the `dif_type` is 1, 2, or 3, the malloc bdev compares the guard tag to the CRC-16 computed over the block data. 3560If the `dif_type` is 1 or 2, the malloc bdev compares the reference tag to the computed reference tag. 3561The computed reference tag for the first block of the I/O is the `init_ref_tag` of the DIF context, and 3562the computed reference tag is incremented for each subsequent block. 3563If the `dif_type` is 3, the malloc bdev does not check the reference tag. 3564The application tag is not checked by the malloc bdev because the current block device API does not expose 3565it to the upper layer yet. 3566 3567#### Parameters 3568 3569Name | Optional | Type | Description 3570----------------------- | -------- | ----------- | ----------- 3571name | Optional | string | Bdev name to use 3572block_size | Required | number | Data block size in bytes -must be multiple of 512 3573num_blocks | Required | number | Number of blocks 3574uuid | Optional | string | UUID of new bdev 3575optimal_io_boundary | Optional | number | Split on optimal IO boundary, in number of blocks, default 0 3576md_size | Optional | number | Metadata size for this bdev (0, 8, 16, 32, 64, or 128). Default is 0. 3577md_interleave | Optional | boolean | Metadata location, interleaved if true, and separated if false. Default is false. 3578dif_type | Optional | number | Protection information type. Parameter --md-size needs to be set along --dif-type. Default=0 - no protection. 3579dif_is_head_of_md | Optional | boolean | Protection information is in the first 8 bytes of metadata. Default=false. 3580 3581#### Result 3582 3583Name of newly created bdev. 3584 3585#### Example 3586 3587Example request: 3588 3589~~~json 3590{ 3591 "params": { 3592 "block_size": 4096, 3593 "num_blocks": 16384, 3594 "name": "Malloc0", 3595 "uuid": "2b6601ba-eada-44fb-9a83-a20eb9eb9e90", 3596 "optimal_io_boundary": 16 3597 }, 3598 "jsonrpc": "2.0", 3599 "method": "bdev_malloc_create", 3600 "id": 1 3601} 3602~~~ 3603 3604Example response: 3605 3606~~~json 3607{ 3608 "jsonrpc": "2.0", 3609 "id": 1, 3610 "result": "Malloc0" 3611} 3612~~~ 3613 3614### bdev_malloc_delete {#rpc_bdev_malloc_delete} 3615 3616Delete @ref bdev_config_malloc 3617 3618#### Parameters 3619 3620Name | Optional | Type | Description 3621----------------------- | -------- | ----------- | ----------- 3622name | Required | string | Bdev name 3623 3624#### Example 3625 3626Example request: 3627 3628~~~json 3629{ 3630 "params": { 3631 "name": "Malloc0" 3632 }, 3633 "jsonrpc": "2.0", 3634 "method": "bdev_malloc_delete", 3635 "id": 1 3636} 3637~~~ 3638 3639Example response: 3640 3641~~~json 3642{ 3643 "jsonrpc": "2.0", 3644 "id": 1, 3645 "result": true 3646} 3647~~~ 3648 3649### bdev_null_create {#rpc_bdev_null_create} 3650 3651Construct @ref bdev_config_null 3652 3653#### Parameters 3654 3655Name | Optional | Type | Description 3656----------------------- | -------- | ----------- | ----------- 3657name | Optional | string | Bdev name to use 3658block_size | Required | number | Block size in bytes 3659num_blocks | Required | number | Number of blocks 3660uuid | Optional | string | UUID of new bdev 3661md_size | Optional | number | Metadata size for this bdev. Default=0. 3662dif_type | Optional | number | Protection information type. Parameter --md-size needs to be set along --dif-type. Default=0 - no protection. 3663dif_is_head_of_md | Optional | boolean | Protection information is in the first 8 bytes of metadata. Default=false. 3664 3665#### Result 3666 3667Name of newly created bdev. 3668 3669#### Example 3670 3671Example request: 3672 3673~~~json 3674{ 3675 "params": { 3676 "block_size": 4104, 3677 "num_blocks": 16384, 3678 "name": "Null0", 3679 "uuid": "2b6601ba-eada-44fb-9a83-a20eb9eb9e90", 3680 "md_size": 8, 3681 "dif_type": 1, 3682 "dif_is_head_of_md": true 3683 }, 3684 "jsonrpc": "2.0", 3685 "method": "bdev_null_create", 3686 "id": 1 3687} 3688~~~ 3689 3690Example response: 3691 3692~~~json 3693{ 3694 "jsonrpc": "2.0", 3695 "id": 1, 3696 "result": "Null0" 3697} 3698~~~ 3699 3700### bdev_null_delete {#rpc_bdev_null_delete} 3701 3702Delete @ref bdev_config_null. 3703 3704#### Parameters 3705 3706Name | Optional | Type | Description 3707----------------------- | -------- | ----------- | ----------- 3708name | Required | string | Bdev name 3709 3710#### Example 3711 3712Example request: 3713 3714~~~json 3715{ 3716 "params": { 3717 "name": "Null0" 3718 }, 3719 "jsonrpc": "2.0", 3720 "method": "bdev_null_delete", 3721 "id": 1 3722} 3723~~~ 3724 3725Example response: 3726 3727~~~json 3728{ 3729 "jsonrpc": "2.0", 3730 "id": 1, 3731 "result": true 3732} 3733~~~ 3734 3735### bdev_null_resize {#rpc_bdev_null_resize} 3736 3737Resize @ref bdev_config_null. 3738 3739#### Parameters 3740 3741Name | Optional | Type | Description 3742----------------------- | -------- | ----------- | ----------- 3743name | Required | string | Bdev name 3744new_size | Required | number | Bdev new capacity in MiB 3745 3746#### Example 3747 3748Example request: 3749 3750~~~json 3751{ 3752 "params": { 3753 "name": "Null0", 3754 "new_size": 4096 3755 }, 3756 "jsonrpc": "2.0", 3757 "method": "bdev_null_resize", 3758 "id": 1 3759} 3760~~~ 3761 3762Example response: 3763 3764~~~json 3765{ 3766 "jsonrpc": "2.0", 3767 "id": 1, 3768 "result": true 3769} 3770~~~ 3771 3772### bdev_aio_create {#rpc_bdev_aio_create} 3773 3774Construct @ref bdev_config_aio. 3775 3776#### Parameters 3777 3778Name | Optional | Type | Description 3779----------------------- | -------- | ----------- | ----------- 3780name | Required | string | Bdev name to use 3781filename | Required | number | Path to device or file 3782block_size | Optional | number | Block size in bytes 3783 3784#### Result 3785 3786Name of newly created bdev. 3787 3788#### Example 3789 3790Example request: 3791 3792~~~json 3793{ 3794 "params": { 3795 "block_size": 4096, 3796 "name": "Aio0", 3797 "filename": "/tmp/aio_bdev_file" 3798 }, 3799 "jsonrpc": "2.0", 3800 "method": "bdev_aio_create", 3801 "id": 1 3802} 3803~~~ 3804 3805Example response: 3806 3807~~~json 3808{ 3809 "jsonrpc": "2.0", 3810 "id": 1, 3811 "result": "Aio0" 3812} 3813~~~ 3814 3815### bdev_aio_rescan {#rpc_bdev_aio_rescan} 3816 3817Rescan the size of @ref bdev_config_aio. 3818 3819#### Parameters 3820 3821Name | Optional | Type | Description 3822----------------------- | -------- | ----------- | ----------- 3823name | Required | string | Bdev name 3824 3825#### Example 3826 3827Example request: 3828 3829~~~json 3830{ 3831 "params": { 3832 "name": "Aio0" 3833 }, 3834 "jsonrpc": "2.0", 3835 "method": "bdev_aio_rescan", 3836 "id": 1 3837} 3838~~~ 3839 3840Example response: 3841 3842~~~json 3843{ 3844 "jsonrpc": "2.0", 3845 "id": 1, 3846 "result": true 3847} 3848~~~ 3849 3850### bdev_aio_delete {#rpc_bdev_aio_delete} 3851 3852Delete @ref bdev_config_aio. 3853 3854#### Parameters 3855 3856Name | Optional | Type | Description 3857----------------------- | -------- | ----------- | ----------- 3858name | Required | string | Bdev name 3859 3860#### Example 3861 3862Example request: 3863 3864~~~json 3865{ 3866 "params": { 3867 "name": "Aio0" 3868 }, 3869 "jsonrpc": "2.0", 3870 "method": "bdev_aio_delete", 3871 "id": 1 3872} 3873~~~ 3874 3875Example response: 3876 3877~~~json 3878{ 3879 "jsonrpc": "2.0", 3880 "id": 1, 3881 "result": true 3882} 3883~~~ 3884 3885### bdev_nvme_set_options {#rpc_bdev_nvme_set_options} 3886 3887Set global parameters for all bdev NVMe. This RPC may only be called before SPDK subsystems have been initialized 3888or any bdev NVMe has been created. 3889 3890Parameters, ctrlr_loss_timeout_sec, reconnect_delay_sec, and fast_io_fail_timeout_sec, are for I/O error resiliency. 3891They can be overridden if they are given by the RPC bdev_nvme_attach_controller. 3892 3893#### Parameters 3894 3895Name | Optional | Type | Description 3896-------------------------- | -------- | ----------- | ----------- 3897action_on_timeout | Optional | string | Action to take on command time out: none, reset or abort 3898timeout_us | Optional | number | Timeout for each command, in microseconds. If 0, don't track timeouts 3899timeout_admin_us | Optional | number | Timeout for each admin command, in microseconds. If 0, treat same as io timeouts ('timeout_us') 3900keep_alive_timeout_ms | Optional | number | Keep alive timeout period in milliseconds, default is 10s 3901retry_count | Optional | number | The number of attempts per I/O before an I/O fails. (Deprecated. Please use transport_retry_count instead.) 3902arbitration_burst | Optional | number | The value is expressed as a power of two, a value of 111b indicates no limit 3903low_priority_weight | Optional | number | The maximum number of commands that the controller may launch at one time from a low priority queue 3904medium_priority_weight | Optional | number | The maximum number of commands that the controller may launch at one time from a medium priority queue 3905high_priority_weight | Optional | number | The maximum number of commands that the controller may launch at one time from a high priority queue 3906nvme_adminq_poll_period_us | Optional | number | How often the admin queue is polled for asynchronous events in microseconds 3907nvme_ioq_poll_period_us | Optional | number | How often I/O queues are polled for completions, in microseconds. Default: 0 (as fast as possible). 3908io_queue_requests | Optional | number | The number of requests allocated for each NVMe I/O queue. Default: 512. 3909delay_cmd_submit | Optional | boolean | Enable delaying NVMe command submission to allow batching of multiple commands. Default: `true`. 3910transport_retry_count | Optional | number | The number of attempts per I/O in the transport layer before an I/O fails. 3911bdev_retry_count | Optional | number | The number of attempts per I/O in the bdev layer before an I/O fails. -1 means infinite retries. 3912transport_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. 3913ctrlr_loss_timeout_sec | Optional | number | Time to wait until ctrlr is reconnected before deleting ctrlr. -1 means infinite reconnects. 0 means no reconnect. 3914reconnect_delay_sec | Optional | number | Time to delay a reconnect trial. 0 means no reconnect. 3915fast_io_fail_timeout_sec | Optional | number | Time to wait until ctrlr is reconnected before failing I/O to ctrlr. 0 means no such timeout. 3916disable_auto_failback | Optional | boolean | Disable automatic failback. The RPC bdev_nvme_set_preferred_path can be used to do manual failback. 3917generate_uuids | Optional | boolean | Enable generation of UUIDs for NVMe bdevs that do not provide this value themselves. 3918transport_tos | Optional | number | IPv4 Type of Service value. Only applicable for RDMA transport. Default: 0 (no TOS is applied). 3919nvme_error_stat | Optional | boolean | Enable collecting NVMe error counts. 3920rdma_srq_size | Optional | number | Set the size of a shared rdma receive queue. Default: 0 (disabled). 3921io_path_stat | Optional | boolean | Enable collecting I/O stat of each nvme bdev io path. Default: `false`. 3922allow_accel_sequence | Optional | boolean | Allow NVMe bdevs to advertise support for accel sequences if the controller also supports them. Default: `false`. 3923rdma_max_cq_size | Optional | number | Set the maximum size of a rdma completion queue. Default: 0 (unlimited) 3924rdma_cm_event_timeout_ms | Optional | number | Time to wait for RDMA CM events. Default: 0 (0 means using default value of driver). 3925dhchap_digests | Optional | list | List of allowed DH-HMAC-CHAP digests. 3926dhchap_dhgroups | Optional | list | List of allowed DH-HMAC-CHAP DH groups. 3927 3928#### Example 3929 3930Example request: 3931 3932~~~json 3933request: 3934{ 3935 "params": { 3936 "transport_retry_count": 5, 3937 "arbitration_burst": 3, 3938 "low_priority_weight": 8, 3939 "medium_priority_weight":8, 3940 "high_priority_weight": 8, 3941 "nvme_adminq_poll_period_us": 2000, 3942 "timeout_us": 10000000, 3943 "timeout_admin_us": 20000000, 3944 "keep_alive_timeout_ms": 600000, 3945 "action_on_timeout": "reset", 3946 "io_queue_requests" : 2048, 3947 "delay_cmd_submit": true 3948 "dhchap_digests": [ 3949 "sha384", 3950 "sha512" 3951 ], 3952 "dhchap_dhgroups": [ 3953 "ffdhe6144", 3954 "ffdhe8192" 3955 ] 3956 }, 3957 "jsonrpc": "2.0", 3958 "method": "bdev_nvme_set_options", 3959 "id": 1 3960} 3961~~~ 3962 3963Example response: 3964 3965~~~json 3966{ 3967 "jsonrpc": "2.0", 3968 "id": 1, 3969 "result": true 3970} 3971~~~ 3972 3973### bdev_nvme_set_hotplug {#rpc_bdev_nvme_set_hotplug} 3974 3975Change settings of the NVMe hotplug feature. If enabled, PCIe NVMe bdevs will be automatically discovered on insertion 3976and deleted on removal. 3977 3978#### Parameters 3979 3980Name | Optional | Type | Description 3981----------------------- | -------- | ----------- | ----------- 3982enable | Required | string | True to enable, false to disable 3983period_us | Optional | number | How often to poll for hot-insert and hot-remove events. Values: 0 - reset/use default or 1 to 10000000. 3984 3985#### Example 3986 3987Example request: 3988 3989~~~json 3990request: 3991{ 3992 "params": { 3993 "enable": true, 3994 "period_us": 2000 3995 }, 3996 "jsonrpc": "2.0", 3997 "method": "bdev_nvme_set_hotplug", 3998 "id": 1 3999} 4000~~~ 4001 4002Example response: 4003 4004~~~json 4005{ 4006 "jsonrpc": "2.0", 4007 "id": 1, 4008 "result": true 4009} 4010~~~ 4011 4012### bdev_nvme_attach_controller {#rpc_bdev_nvme_attach_controller} 4013 4014Construct @ref bdev_config_nvme. This RPC can also be used to add additional paths to an existing controller to enable 4015multipathing. This is done by specifying the `name` parameter as an existing controller. When adding an additional 4016path, the hostnqn, hostsvcid, hostaddr, prchk_reftag, and prchk_guard_arguments must not be specified and are assumed 4017to have the same value as the existing path. 4018 4019The parameters, `ctrlr_loss_timeout_sec`, `reconnect_delay_sec`, and `fast_io_fail_timeout_sec`, are mutually dependent. 4020If `reconnect_delay_sec` is non-zero, `ctrlr_loss_timeout_sec` has to be -1 or not less than `reconnect_delay_sec`. 4021If `reconnect_delay_sec` is zero, `ctrlr_loss_timeout_sec` has to be zero. 4022If `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. 4023 4024#### Result 4025 4026Array of names of newly created bdevs. 4027 4028#### Parameters 4029 4030Name | Optional | Type | Description 4031-------------------------- | -------- | ----------- | ----------- 4032name | Required | string | Name of the NVMe controller, prefix for each bdev name 4033trtype | Required | string | NVMe-oF target trtype: rdma or pcie 4034traddr | Required | string | NVMe-oF target address: ip or BDF 4035adrfam | Optional | string | NVMe-oF target adrfam: ipv4, ipv6, ib, fc, intra_host 4036trsvcid | Optional | string | NVMe-oF target trsvcid: port number 4037subnqn | Optional | string | NVMe-oF target subnqn 4038hostnqn | Optional | string | NVMe-oF target hostnqn 4039hostaddr | Optional | string | NVMe-oF host address: ip address 4040hostsvcid | Optional | string | NVMe-oF host trsvcid: port number 4041prchk_reftag | Optional | bool | Enable checking of PI reference tag for I/O processing 4042prchk_guard | Optional | bool | Enable checking of PI guard for I/O processing 4043hdgst | Optional | bool | Enable TCP header digest 4044ddgst | Optional | bool | Enable TCP data digest 4045fabrics_connect_timeout_us | Optional | bool | Timeout for fabrics connect (in microseconds) 4046multipath | Optional | string | Multipathing behavior: disable, failover, multipath. Default is failover. 4047num_io_queues | Optional | number | The number of IO queues to request during initialization. Range: (0, UINT16_MAX + 1], Default is 1024. 4048ctrlr_loss_timeout_sec | Optional | number | Time to wait until ctrlr is reconnected before deleting ctrlr. -1 means infinite reconnects. 0 means no reconnect. 4049reconnect_delay_sec | Optional | number | Time to delay a reconnect trial. 0 means no reconnect. 4050fast_io_fail_timeout_sec | Optional | number | Time to wait until ctrlr is reconnected before failing I/O to ctrlr. 0 means no such timeout. 4051psk | Optional | string | Name of the pre-shared key to be used for TLS (Enables SSL socket implementation for TCP) 4052max_bdevs | Optional | number | The size of the name array for newly created bdevs. Default is 128. 4053dhchap_key | Optional | string | DH-HMAC-CHAP key name. 4054dhchap_ctrlr_key | Optional | string | DH-HMAC-CHAP controller key name. 4055 4056#### Example 4057 4058Example request: 4059 4060~~~json 4061{ 4062 "params": { 4063 "trtype": "pcie", 4064 "name": "Nvme0", 4065 "traddr": "0000:0a:00.0" 4066 }, 4067 "jsonrpc": "2.0", 4068 "method": "bdev_nvme_attach_controller", 4069 "id": 1 4070} 4071~~~ 4072 4073Example response: 4074 4075~~~json 4076{ 4077 "jsonrpc": "2.0", 4078 "id": 1, 4079 "result": [ 4080 "Nvme0n1" 4081 ] 4082} 4083~~~ 4084 4085### bdev_nvme_get_controllers {#rpc_bdev_nvme_get_controllers} 4086 4087Get information about NVMe controllers. 4088 4089#### Parameters 4090 4091The user may specify no parameters in order to list all NVMe controllers, or one NVMe controller may be 4092specified by name. 4093 4094Name | Optional | Type | Description 4095----------------------- | -------- | ----------- | ----------- 4096name | Optional | string | NVMe controller name 4097 4098#### Response 4099 4100The response is an array of objects containing information about the requested NVMe controllers. 4101 4102#### Example 4103 4104Example request: 4105 4106~~~json 4107{ 4108 "jsonrpc": "2.0", 4109 "id": 1, 4110 "method": "bdev_nvme_get_controllers", 4111 "params": { 4112 "name": "Nvme0" 4113 } 4114} 4115~~~ 4116 4117Example response: 4118 4119~~~json 4120{ 4121 "jsonrpc": "2.0", 4122 "id": 1, 4123 "result": [ 4124 { 4125 "name": "Nvme0", 4126 "trid": { 4127 "trtype": "PCIe", 4128 "traddr": "0000:05:00.0" 4129 }, 4130 "cntlid": 0 4131 } 4132 ] 4133} 4134~~~ 4135 4136### bdev_nvme_detach_controller {#rpc_bdev_nvme_detach_controller} 4137 4138Detach NVMe controller and delete any associated bdevs. Optionally, 4139If all of the transport ID options are specified, only remove that 4140transport path from the specified controller. If that is the only 4141available path for the controller, this will also result in the 4142controller being detached and the associated bdevs being deleted. 4143 4144returns true if the controller and bdevs were successfully destroyed 4145or the address was properly removed, false otherwise. 4146 4147#### Parameters 4148 4149Name | Optional | Type | Description 4150----------------------- | -------- | ----------- | ----------- 4151name | Required | string | Controller name 4152trtype | Optional | string | NVMe-oF target trtype: rdma or tcp 4153traddr | Optional | string | NVMe-oF target address: ip or BDF 4154adrfam | Optional | string | NVMe-oF target adrfam: ipv4, ipv6, ib, fc, intra_host 4155trsvcid | Optional | string | NVMe-oF target trsvcid: port number 4156subnqn | Optional | string | NVMe-oF target subnqn 4157hostaddr | Optional | string | NVMe-oF host address: ip 4158hostsvcid | Optional | string | NVMe-oF host svcid: port number 4159 4160#### Example 4161 4162Example requests: 4163 4164~~~json 4165{ 4166 "params": { 4167 "name": "Nvme0" 4168 }, 4169 "jsonrpc": "2.0", 4170 "method": "bdev_nvme_detach_controller", 4171 "id": 1 4172} 4173~~~ 4174 4175Example response: 4176 4177~~~json 4178{ 4179 "jsonrpc": "2.0", 4180 "id": 1, 4181 "result": true 4182} 4183~~~ 4184 4185### bdev_nvme_reset_controller {#rpc_bdev_nvme_reset_controller} 4186 4187For non NVMe multipath, reset an NVMe controller whose name is given by the `name` parameter. 4188 4189For NVMe multipath, an NVMe bdev controller is created and it aggregates multiple NVMe controllers. 4190The `name` parameter is an NVMe bdev controller name and the `cntlid` parameter is used to identify 4191an NVMe controller in the NVMe bdev controller. Reset only one NVMe-oF controller if the `cntlid` 4192parameter is specified, or all NVMe-oF controllers in an NVMe bdev controller if it is omitted. 4193 4194Returns true if the controller reset was successful, false otherwise. 4195 4196#### Parameters 4197 4198Name | Optional | Type | Description 4199----------------------- | -------- | ----------- | ----------- 4200name | Required | string | NVMe controller name (or NVMe bdev controller name for multipath) 4201cntlid | Optional | number | NVMe controller ID (used as NVMe controller name for multipath) 4202 4203#### Example 4204 4205Example request: 4206 4207~~~json 4208{ 4209 "jsonrpc": "2.0", 4210 "id": 1, 4211 "method": "bdev_nvme_reset_controller", 4212 "params": { 4213 "name": "Nvme0" 4214 } 4215} 4216~~~ 4217 4218Example response: 4219 4220~~~json 4221{ 4222 "jsonrpc": "2.0", 4223 "id": 1, 4224 "result": true 4225} 4226~~~ 4227 4228### bdev_nvme_enable_controller {#rpc_bdev_nvme_enable_controller} 4229 4230For non NVMe multipath, enable an NVMe controller whose name is given by the `name` parameter. 4231 4232For NVMe multipath, an NVMe bdev controller is created and it aggregates multiple NVMe controllers. 4233The `name` parameter is an NVMe bdev controller name and the `cntlid` parameter is used to identify 4234an NVMe controller in the NVMe bdev controller. Enable only one NVMe-oF controller if the `cntlid` 4235parameter is specified, or all NVMe-oF controllers in an NVMe bdev controller if it is omitted. 4236 4237Returns true if the controller enablement was successful or a controller was already enabled, false otherwise. 4238 4239#### Parameters 4240 4241Name | Optional | Type | Description 4242----------------------- | -------- | ----------- | ----------- 4243name | Required | string | NVMe controller name (or NVMe bdev controller name for multipath) 4244cntlid | Optional | number | NVMe controller ID (used as NVMe controller name for multipath) 4245 4246#### Example 4247 4248Example request: 4249 4250~~~json 4251{ 4252 "jsonrpc": "2.0", 4253 "id": 1, 4254 "method": "bdev_nvme_enable_controller", 4255 "params": { 4256 "name": "Nvme0" 4257 } 4258} 4259~~~ 4260 4261Example response: 4262 4263~~~json 4264{ 4265 "jsonrpc": "2.0", 4266 "id": 1, 4267 "result": true 4268} 4269~~~ 4270 4271### bdev_nvme_disable_controller {#rpc_bdev_nvme_disable_controller} 4272 4273For non NVMe multipath, disable an NVMe controller whose name is given by the `name` parameter. 4274 4275For NVMe multipath, an NVMe bdev controller is created and it aggregates multiple NVMe controllers. 4276The `name` parameter is an NVMe bdev controller name and the `cntlid` parameter is used to identify 4277an NVMe controller in the NVMe bdev controller. Disable only one NVMe-oF controller if the `cntlid` 4278parameter is specified, or all NVMe-oF controllers in an NVMe bdev controller if it is omitted. 4279 4280Returns true if the controller disablement was successful or a controller was already disabled, false otherwise. 4281 4282#### Parameters 4283 4284Name | Optional | Type | Description 4285----------------------- | -------- | ----------- | ----------- 4286name | Required | string | NVMe controller name (or NVMe bdev controller name for multipath) 4287cntlid | Optional | number | NVMe controller ID (used as NVMe controller name for multipath) 4288 4289#### Example 4290 4291Example request: 4292 4293~~~json 4294{ 4295 "jsonrpc": "2.0", 4296 "id": 1, 4297 "method": "bdev_nvme_disable_controller", 4298 "params": { 4299 "name": "Nvme0" 4300 } 4301} 4302~~~ 4303 4304Example response: 4305 4306~~~json 4307{ 4308 "jsonrpc": "2.0", 4309 "id": 1, 4310 "result": true 4311} 4312~~~ 4313 4314### bdev_nvme_start_discovery {#rpc_bdev_nvme_start_discovery} 4315 4316Start a discovery service for the discovery subsystem of the specified transport ID. 4317 4318The discovery service will read the discovery log page for the specified 4319discovery subsystem, and automatically attach to any subsystems found in the 4320log page. When determining a controller name to use when attaching, it will use 4321the 'name' parameter as a prefix, followed by a unique integer for that discovery 4322service. If the discovery service identifies a subsystem that has been previously 4323attached but is listed with a different path, it will use the same controller name 4324as the previous entry, and connect as a multipath. 4325 4326When the discovery service sees that a subsystem entry has been removed 4327from the log page, it will automatically detach from that controller as well. 4328 4329The 'name' is also used to later stop the discovery service. 4330 4331#### Parameters 4332 4333Name | Optional | Type | Description 4334-------------------------- | -------- | ----------- | ----------- 4335name | Required | string | Prefix for NVMe controllers 4336trtype | Required | string | NVMe-oF target trtype: rdma or tcp 4337traddr | Required | string | NVMe-oF target address: ip 4338adrfam | Optional | string | NVMe-oF target adrfam: ipv4, ipv6 4339trsvcid | Optional | string | NVMe-oF target trsvcid: port number 4340hostnqn | Optional | string | NVMe-oF target hostnqn 4341wait_for_attach | Optional | bool | Wait to complete until all discovered NVM subsystems are attached 4342attach_timeout_ms | Optional | number | Time to wait until the discovery and all discovered NVM subsystems are attached 4343ctrlr_loss_timeout_sec | Optional | number | Time to wait until ctrlr is reconnected before deleting ctrlr. -1 means infinite reconnects. 0 means no reconnect. 4344reconnect_delay_sec | Optional | number | Time to delay a reconnect trial. 0 means no reconnect. 4345fast_io_fail_timeout_sec | Optional | number | Time to wait until ctrlr is reconnected before failing I/O to ctrlr. 0 means no such timeout. 4346 4347#### Example 4348 4349Example request: 4350 4351~~~json 4352{ 4353 "jsonrpc": "2.0", 4354 "method": "bdev_nvme_start_discovery", 4355 "id": 1, 4356 "params": { 4357 "name": "nvme_auto", 4358 "trtype": "tcp", 4359 "traddr": "127.0.0.1", 4360 "hostnqn": "nqn.2021-12.io.spdk:host1", 4361 "adrfam": "ipv4", 4362 "trsvcid": "4420" 4363 } 4364} 4365~~~ 4366 4367Example response: 4368 4369~~~json 4370{ 4371 "jsonrpc": "2.0", 4372 "id": 1, 4373 "result": true 4374} 4375~~~ 4376 4377### bdev_nvme_stop_discovery {#rpc_bdev_nvme_stop_discovery} 4378 4379Stop a discovery service. This includes detaching any controllers that were 4380discovered via the service that is being stopped. 4381 4382#### Parameters 4383 4384Name | Optional | Type | Description 4385-------------------------- | -------- | ----------- | ----------- 4386name | Required | string | Name of service to stop 4387 4388#### Example 4389 4390Example request: 4391 4392~~~json 4393{ 4394 "jsonrpc": "2.0", 4395 "method": "bdev_nvme_stop_discovery", 4396 "id": 1, 4397 "params": { 4398 "name": "nvme_auto" 4399 } 4400} 4401~~~ 4402 4403Example response: 4404 4405~~~json 4406{ 4407 "jsonrpc": "2.0", 4408 "id": 1, 4409 "result": true 4410} 4411~~~ 4412 4413### bdev_nvme_get_discovery_info {#rpc_bdev_nvme_get_discovery_info} 4414 4415Get information about the discovery service. 4416 4417#### Example 4418 4419Example request: 4420~~~json 4421{ 4422 "jsonrpc": "2.0", 4423 "method": "bdev_nvme_get_discovery_info", 4424 "id": 1 4425} 4426~~~ 4427 4428Example response: 4429 4430~~~json 4431{ 4432 "jsonrpc": "2.0", 4433 "id": 1, 4434 "result": [ 4435 { 4436 "name": "nvme-disc", 4437 "trid": { 4438 "trtype": "TCP", 4439 "adrfam": "IPv4", 4440 "traddr": "127.0.0.1", 4441 "trsvcid": "8009", 4442 "subnqn": "nqn.2014-08.org.nvmexpress.discovery" 4443 }, 4444 "referrals": [] 4445 } 4446 ] 4447} 4448~~~ 4449 4450### bdev_nvme_get_io_paths {#rpc_bdev_nvme_get_io_paths} 4451 4452Display all or the specified NVMe bdev's active I/O paths. 4453 4454#### Parameters 4455 4456Name | Optional | Type | Description 4457----------------------- | -------- | ----------- | ----------- 4458name | Optional | string | Name of the NVMe bdev 4459 4460#### Example 4461 4462Example request: 4463 4464~~~json 4465{ 4466 "jsonrpc": "2.0", 4467 "method": "bdev_nvme_get_io_paths", 4468 "id": 1, 4469 "params": { 4470 "name": "Nvme0n1" 4471 } 4472} 4473~~~ 4474 4475Example response: 4476 4477~~~json 4478{ 4479 "jsonrpc": "2.0", 4480 "id": 1, 4481 "result": { 4482 "poll_groups": [ 4483 { 4484 "thread": "app_thread", 4485 "io_paths": [ 4486 { 4487 "bdev_name": "Nvme0n1", 4488 "cntlid": 0, 4489 "current": true, 4490 "connected": true, 4491 "accessible": true, 4492 "transport": { 4493 "trtype": "RDMA", 4494 "traddr": "1.2.3.4", 4495 "trsvcid": "4420", 4496 "adrfam": "IPv4" 4497 } 4498 } 4499 ] 4500 } 4501 ] 4502 } 4503} 4504~~~ 4505 4506### bdev_nvme_set_preferred_path {#rpc_bdev_nvme_set_preferred_path} 4507 4508Set the preferred I/O path for an NVMe bdev in multipath mode. 4509 4510NOTE: This RPC does not support NVMe bdevs in failover mode. 4511 4512#### Parameters 4513 4514Name | Optional | Type | Description 4515----------------------- | -------- | ----------- | ----------- 4516name | Required | string | Name of the NVMe bdev 4517cntlid | Required | number | NVMe-oF controller ID 4518 4519#### Example 4520 4521Example request: 4522 4523~~~json 4524{ 4525 "jsonrpc": "2.0", 4526 "method": "bdev_nvme_set_preferred_path", 4527 "id": 1, 4528 "params": { 4529 "name": "Nvme0n1", 4530 "cntlid": 0 4531 } 4532} 4533~~~ 4534 4535Example response: 4536 4537~~~json 4538{ 4539 "jsonrpc": "2.0", 4540 "id": 1, 4541 "result": true 4542} 4543~~~ 4544 4545### bdev_nvme_set_multipath_policy {#rpc_bdev_nvme_set_multipath_policy} 4546 4547Set multipath policy of the NVMe bdev in multipath mode or set multipath 4548selector for active-active multipath policy. 4549 4550#### Parameters 4551 4552Name | Optional | Type | Description 4553----------------------- | -------- | ----------- | ----------- 4554name | Required | string | Name of the NVMe bdev 4555policy | Required | string | Multipath policy: active_active or active_passive 4556selector | Optional | string | Multipath selector: round_robin or queue_depth, used in active-active mode. Default is round_robin 4557rr_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. 4558 4559#### Example 4560 4561Example request: 4562 4563~~~json 4564{ 4565 "jsonrpc": "2.0", 4566 "method": "bdev_nvme_set_multipath_policy", 4567 "id": 1, 4568 "params": { 4569 "name": "Nvme0n1", 4570 "policy": "active_passive" 4571 } 4572} 4573~~~ 4574 4575Example response: 4576 4577~~~json 4578{ 4579 "jsonrpc": "2.0", 4580 "id": 1, 4581 "result": true 4582} 4583~~~ 4584 4585### bdev_nvme_get_path_iostat {#rpc_bdev_nvme_get_path_iostat} 4586 4587Get I/O statistics for IO paths of the block device. Call RPC bdev_nvme_set_options to set enable_io_path_stat 4588true before using this RPC. 4589 4590#### Parameters 4591 4592Name | Optional | Type | Description 4593----------------------- | -------- | ----------- | ----------- 4594name | Required | string | Name of the NVMe bdev 4595 4596#### Example 4597 4598Example request: 4599 4600~~~json 4601{ 4602 "jsonrpc": "2.0", 4603 "method": "bdev_nvme_get_path_iostat", 4604 "id": 1, 4605 "params": { 4606 "name": "NVMe0n1" 4607 } 4608} 4609~~~ 4610 4611Example response: 4612 4613~~~json 4614{ 4615 "jsonrpc": "2.0", 4616 "id": 1, 4617 "result": { 4618 "name": "NVMe0n1", 4619 "stats": [ 4620 { 4621 "trid": { 4622 "trtype": "TCP", 4623 "adrfam": "IPv4", 4624 "traddr": "10.169.204.201", 4625 "trsvcid": "4420", 4626 "subnqn": "nqn.2016-06.io.spdk:cnode1" 4627 }, 4628 "stat": { 4629 "bytes_read": 676691968, 4630 "num_read_ops": 165201, 4631 "bytes_written": 0, 4632 "num_write_ops": 0, 4633 "bytes_unmapped": 0, 4634 "num_unmap_ops": 0, 4635 "max_read_latency_ticks": 521487, 4636 "min_read_latency_ticks": 0, 4637 "write_latency_ticks": 0, 4638 "max_write_latency_ticks": 0, 4639 "min_write_latency_ticks": 0, 4640 "unmap_latency_ticks": 0, 4641 "max_unmap_latency_ticks": 0, 4642 "min_unmap_latency_ticks": 0, 4643 "copy_latency_ticks": 0, 4644 "max_copy_latency_ticks": 0, 4645 "min_copy_latency_ticks": 0 4646 } 4647 }, 4648 { 4649 "trid": { 4650 "trtype": "TCP", 4651 "adrfam": "IPv4", 4652 "traddr": "8.8.8.6", 4653 "trsvcid": "4420", 4654 "subnqn": "nqn.2016-06.io.spdk:cnode1" 4655 }, 4656 "stat": { 4657 "bytes_read": 677138432, 4658 "num_read_ops": 165317, 4659 "bytes_written": 0, 4660 "num_write_ops": 0, 4661 "bytes_unmapped": 0, 4662 "num_unmap_ops": 0, 4663 "max_read_latency_ticks": 108525, 4664 "min_read_latency_ticks": 0, 4665 "write_latency_ticks": 0, 4666 "max_write_latency_ticks": 0, 4667 "min_write_latency_ticks": 0, 4668 "unmap_latency_ticks": 0, 4669 "max_unmap_latency_ticks": 0, 4670 "min_unmap_latency_ticks": 0, 4671 "copy_latency_ticks": 0, 4672 "max_copy_latency_ticks": 0, 4673 "min_copy_latency_ticks": 0 4674 } 4675 } 4676 ] 4677 } 4678} 4679~~~ 4680 4681### bdev_nvme_cuse_register {#rpc_bdev_nvme_cuse_register} 4682 4683Register CUSE device on NVMe controller. 4684 4685#### Parameters 4686 4687Name | Optional | Type | Description 4688----------------------- | -------- | ----------- | ----------- 4689name | Required | string | Name of the NVMe controller 4690 4691#### Example 4692 4693Example request: 4694 4695~~~json 4696{ 4697 "jsonrpc": "2.0", 4698 "method": "bdev_nvme_cuse_register", 4699 "id": 1, 4700 "params": { 4701 "name": "Nvme0" 4702 } 4703} 4704~~~ 4705 4706Example response: 4707 4708~~~json 4709{ 4710 "jsonrpc": "2.0", 4711 "id": 1, 4712 "result": true 4713} 4714~~~ 4715 4716### bdev_nvme_cuse_unregister {#rpc_bdev_nvme_cuse_unregister} 4717 4718Unregister CUSE device on NVMe controller. 4719 4720#### Parameters 4721 4722Name | Optional | Type | Description 4723----------------------- | -------- | ----------- | ----------- 4724name | Required | string | Name of the NVMe controller 4725 4726#### Example 4727 4728Example request: 4729 4730~~~json 4731{ 4732 "params": { 4733 "name": "Nvme0" 4734 }, 4735 "jsonrpc": "2.0", 4736 "method": "bdev_nvme_cuse_unregister", 4737 "id": 1 4738} 4739~~~ 4740 4741Example response: 4742 4743~~~json 4744{ 4745 "jsonrpc": "2.0", 4746 "id": 1, 4747 "result": true 4748} 4749~~~ 4750 4751### bdev_zone_block_create {#rpc_bdev_zone_block_create} 4752 4753Creates a virtual zone device on top of existing non-zoned bdev. 4754 4755#### Parameters 4756 4757Name | Optional | Type | Description 4758----------------------- | -------- | ----------- | ----------- 4759name | Required | string | Name of the Zone device 4760base_bdev | Required | string | Name of the Base bdev 4761zone_capacity | Required | number | Zone capacity in blocks 4762optimal_open_zones | Required | number | Number of zones required to reach optimal write speed 4763 4764#### Example 4765 4766Example request: 4767 4768~~~json 4769{ 4770 "jsonrpc": "2.0", 4771 "method": "bdev_zone_block_create", 4772 "id": 1, 4773 "params": { 4774 "name": "zone1", 4775 "base_bdev": "NVMe0n1", 4776 "zone_capacity": 4096, 4777 "optimal_open_zones": 32 4778 } 4779} 4780~~~ 4781 4782Example response: 4783 4784~~~json 4785{ 4786 "jsonrpc": "2.0", 4787 "id": 1, 4788 "result": "zone1" 4789} 4790~~~ 4791 4792### bdev_zone_block_delete {#rpc_bdev_zone_block_delete} 4793 4794Deletes a virtual zone device. 4795 4796#### Parameters 4797 4798Name | Optional | Type | Description 4799----------------------- | -------- | ----------- | ----------- 4800name | Required | string | Name of the Zone device 4801 4802#### Example 4803 4804Example request: 4805 4806~~~json 4807{ 4808 "jsonrpc": "2.0", 4809 "method": "bdev_zone_block_delete", 4810 "id": 1, 4811 "params": { 4812 "name": "zone1" 4813 } 4814} 4815~~~ 4816 4817Example response: 4818 4819~~~json 4820{ 4821 "jsonrpc": "2.0", 4822 "id": 1, 4823 "result": true 4824} 4825~~~ 4826 4827### bdev_nvme_apply_firmware {#rpc_bdev_nvme_apply_firmware} 4828 4829Download and commit firmware to NVMe device. 4830 4831#### Parameters 4832 4833Name | Optional | Type | Description 4834----------------------- | -------- | ----------- | ----------- 4835filename | Required | string | filename of the firmware to download 4836bdev_name | Required | string | Name of the NVMe block device 4837 4838#### Example 4839 4840Example request: 4841 4842~~~json 4843{ 4844 "jsonrpc": "2.0", 4845 "method": "bdev_nvme_apply_firmware", 4846 "id": 1, 4847 "params": { 4848 "filename": "firmware_file", 4849 "bdev_name": "NVMe0n1" 4850 } 4851} 4852~~~ 4853 4854### bdev_nvme_get_transport_statistics {#rpc_bdev_nvme_get_transport_statistics} 4855 4856Get bdev_nvme poll group transport statistics. 4857 4858#### Parameters 4859 4860This RPC method accepts no parameters 4861 4862#### Response 4863 4864The response is an array of objects containing information about transport statistics per NVME poll group. 4865 4866#### Example 4867 4868Example request: 4869 4870~~~json 4871{ 4872 "jsonrpc": "2.0", 4873 "id": 1, 4874 "method": "bdev_nvme_get_transport_statistics", 4875} 4876~~~ 4877 4878Example response: 4879 4880~~~json 4881{ 4882 "jsonrpc": "2.0", 4883 "id": 1, 4884 "result": { 4885 "poll_groups": [ 4886 { 4887 "thread": "nvmf_tgt_poll_group_000", 4888 "transports": [ 4889 { 4890 "trname": "RDMA", 4891 "devices": [ 4892 { 4893 "dev_name": "mlx5_1", 4894 "polls": 137492169, 4895 "idle_polls": 137492169, 4896 "completions": 0, 4897 "queued_requests": 0, 4898 "total_send_wrs": 0, 4899 "send_sq_doorbell_updates": 0, 4900 "total_recv_wrs": 0, 4901 "recv_sq_doorbell_updates": 0 4902 }, 4903 { 4904 "dev_name": "mlx5_0", 4905 "polls": 137985185, 4906 "idle_polls": 137492169, 4907 "completions": 1474593, 4908 "queued_requests": 0, 4909 "total_send_wrs": 1474593, 4910 "send_sq_doorbell_updates": 426147, 4911 "total_recv_wrs": 1474721, 4912 "recv_sq_doorbell_updates": 348445 4913 } 4914 ] 4915 }, 4916 { 4917 "trname": "PCIE", 4918 "polls": 435419831, 4919 "idle_polls": 434901004, 4920 "completions": 1485543, 4921 "cq_doorbell_updates": 518827, 4922 "queued_requests": 0, 4923 "submitted_requests": 1485543, 4924 "sq_doorbell_updates": 516081 4925 } 4926 ] 4927 }, 4928 { 4929 "thread": "nvmf_tgt_poll_group_001", 4930 "transports": [ 4931 { 4932 "trname": "RDMA", 4933 "devices": [ 4934 { 4935 "dev_name": "mlx5_1", 4936 "polls": 140245630, 4937 "idle_polls": 140245630, 4938 "completions": 0, 4939 "queued_requests": 0, 4940 "total_send_wrs": 0, 4941 "send_sq_doorbell_updates": 0, 4942 "total_recv_wrs": 0, 4943 "recv_sq_doorbell_updates": 0 4944 }, 4945 { 4946 "dev_name": "mlx5_0", 4947 "polls": 140751844, 4948 "idle_polls": 140245630, 4949 "completions": 1489298, 4950 "queued_requests": 0, 4951 "total_send_wrs": 1489298, 4952 "send_sq_doorbell_updates": 433510, 4953 "total_recv_wrs": 1489426, 4954 "recv_sq_doorbell_updates": 357956 4955 } 4956 ] 4957 }, 4958 { 4959 "trname": "PCIE", 4960 "polls": 429044294, 4961 "idle_polls": 428525658, 4962 "completions": 1478730, 4963 "cq_doorbell_updates": 518636, 4964 "queued_requests": 0, 4965 "submitted_requests": 1478730, 4966 "sq_doorbell_updates": 511658 4967 } 4968 ] 4969 } 4970 ] 4971 } 4972} 4973~~~ 4974 4975### bdev_nvme_get_controller_health_info {#rpc_bdev_nvme_get_controller_health_info} 4976 4977Display health log of the required NVMe bdev device. 4978 4979#### Parameters 4980 4981Name | Optional | Type | Description 4982----------------------- | -------- | ----------- | ----------- 4983name | Required | string | Name of the NVMe bdev controller 4984 4985#### Response 4986 4987The response is the object containing information about health log of the NVMe controller. 4988 4989#### Example 4990 4991Example request: 4992 4993~~~json 4994{ 4995 "jsonrpc": "2.0", 4996 "method": "bdev_nvme_get_controller_health_info", 4997 "id": 1, 4998 "params": { 4999 "name": "Nvme0" 5000 } 5001} 5002~~~ 5003 5004Example response: 5005 5006~~~json 5007{ 5008 "model_number": "INTEL SSDPE2KX020T8", 5009 "serial_number": "BTLJ72430ARH2P0BGN", 5010 "firmware_revision": "VDV10110", 5011 "traddr": "0000:08:00.0", 5012 "temperature_celsius": 32, 5013 "available_spare_percentage": 99, 5014 "available_spare_threshold_percentage": 10, 5015 "percentage_used": 2, 5016 "data_units_read": 1013408619, 5017 "data_units_written": 346792685, 5018 "host_read_commands": 30457773282, 5019 "host_write_commands": 18949677715, 5020 "controller_busy_time": 4979, 5021 "power_cycles": 49, 5022 "power_on_hours": 31118, 5023 "unsafe_shutdowns": 18, 5024 "media_errors": 17, 5025 "num_err_log_entries": 19, 5026 "warning_temperature_time_minutes": 0, 5027 "critical_composite_temperature_time_minutes": 0 5028} 5029~~~ 5030 5031### bdev_rbd_register_cluster {#rpc_bdev_rbd_register_cluster} 5032 5033This method is available only if SPDK was build with Ceph RBD support. 5034 5035#### Parameters 5036 5037Name | Optional | Type | Description 5038----------------------- | -------- | ----------- | ----------- 5039name | Required | string | Registered Rados cluster object name 5040user_id | Optional | string | Ceph ID (i.e. admin, not client.admin) 5041config_param | Optional | string map | Explicit librados configuration 5042config_file | Optional | string | File path of libraodos configuration file 5043key_file | Optional | string | File path of libraodos key file 5044 5045This RPC registers a Rados Cluster object handle which is only known 5046to rbd module, it uses user_id + config_param or user_id + config_file + 5047key_file or user_id + config_param + config_file + key_file to identify 5048a Rados cluster object. 5049 5050When accessing the Ceph cluster as some user other than "admin" (the 5051default), the "user_id" has to be set. 5052 5053The configuration items and secret key can be specified by setting config_param, 5054config_file and key_file, all of them, or none of them. If only config_param is 5055passed, all key/value pairs are passed to rados_conf_set to configure cluster access. 5056In practice, "mon_host" (= list of monitor address+port) and "key" (= the secret key 5057stored in Ceph keyrings) are enough. If config_file and key_file are specified, they must 5058exist with all relevant settings for accessing the Ceph cluster. If config_param, config_file 5059and key_file are specified, get the key/value pairs from config_file first and set to 5060rados_conf_set function, then set pairs in config_param and keyring in key_file. If nothing 5061is specified, it will get configuration file and key file from the default location 5062/etc/ceph/ceph.conf and /etc/ceph/ceph.client.user_id.keyring. 5063 5064#### Result 5065 5066Name of newly created Rados cluster object. 5067 5068#### Example 5069 5070Example request: 5071 5072~~ 5073{ 5074 "params": { 5075 "name": "rbd_cluster", 5076 "user_id": cinder, 5077 "config_file": "/root/ceph_conf/ceph.conf", 5078 "key_file": "/root/ceph_conf/ceph.client.cinder.keyring" 5079 }, 5080 "jsonrpc": "2.0", 5081 "method": "bdev_rbd_register_cluster", 5082 "id": 1 5083} 5084~~ 5085 5086Example response: 5087 5088~~ 5089response: 5090{ 5091 "jsonrpc": "2.0", 5092 "id": 1, 5093 "result": "rbd_cluster" 5094} 5095~~ 5096 5097### bdev_rbd_unregister_cluster {#rpc_bdev_rbd_unregister_cluster} 5098 5099This method is available only if SPDK was build with Ceph RBD support. 5100If there is still rbd bdev using this cluster, the unregisteration operation 5101will fail. 5102 5103#### Result 5104 5105`true` if Rados cluster object with provided name was deleted or `false` otherwise. 5106 5107#### Parameters 5108 5109Name | Optional | Type | Description 5110----------------------- | -------- | ----------- | ------------------------- 5111name | Required | string | Rados cluster object name 5112 5113#### Example 5114 5115Example request: 5116 5117~~ 5118{ 5119 "params": { 5120 "name": "rbd_cluster" 5121 }, 5122 "jsonrpc": "2.0", 5123 "method": "bdev_rbd_unregister_cluster", 5124 "id": 1 5125} 5126~~ 5127 5128Example response: 5129 5130~~ 5131{ 5132 "jsonrpc": "2.0", 5133 "id": 1, 5134 "result": true 5135} 5136~~ 5137 5138### bdev_rbd_get_clusters_info {#rpc_bdev_rbd_get_clusters_info} 5139 5140This method is available only if SPDK was build with Ceph RBD support. 5141 5142#### Result 5143 5144Returns the cluster info of the Rados Cluster name if provided. Otherwise, it 5145returns the cluster info of every registered Raods Cluster name. 5146 5147#### Parameters 5148 5149Name | Optional | Type | Description 5150----------------------- | -------- | ----------- | ------------------------- 5151name | Optional | string | Rados cluster object name 5152 5153#### Example 5154 5155Example request: 5156 5157~~ 5158{ 5159 "params": { 5160 "name": "rbd_cluster" 5161 }, 5162 "jsonrpc": "2.0", 5163 "method": "bdev_rbd_get_clusters_info", 5164 "id": 1 5165} 5166~~ 5167 5168Example response: 5169 5170~~ 5171{ 5172 "jsonrpc": "2.0", 5173 "cluster_name": "rbd_cluster" 5174} 5175~~ 5176 5177### bdev_rbd_create {#rpc_bdev_rbd_create} 5178 5179Create @ref bdev_config_rbd bdev 5180 5181This method is available only if SPDK was build with Ceph RBD support. 5182 5183#### Parameters 5184 5185Name | Optional | Type | Description 5186----------------------- | -------- | ----------- | ----------- 5187name | Optional | string | Bdev name 5188user_id | Optional | string | Ceph ID (i.e. admin, not client.admin) 5189pool_name | Required | string | Pool name 5190rbd_name | Required | string | Image name 5191block_size | Required | number | Block size 5192config | Optional | string map | Explicit librados configuration 5193cluster_name | Optional | string | Rados cluster object name created in this module. 5194uuid | Optional | string | UUID of new bdev 5195 5196If no config is specified, Ceph configuration files must exist with 5197all relevant settings for accessing the pool. If a config map is 5198passed, the configuration files are ignored and instead all key/value 5199pairs are passed to rados_conf_set to configure cluster access. In 5200practice, "mon_host" (= list of monitor address+port) and "key" (= the 5201secret key stored in Ceph keyrings) are enough. 5202 5203When accessing the image as some user other than "admin" (the 5204default), the "user_id" has to be set. 5205 5206If provided with cluster_name option, it will use the Rados cluster object 5207referenced by the name (created by bdev_rbd_register_cluster RPC) and ignores 5208"user_id + config" combination to create its own Rados cluster. In this scenario, 5209all the bdevs will share the same cluster with one connection of Ceph in librbd module. 5210Performance tuning on the I/O workload could be done by estimating how many io_contxt 5211threads and messager threads in Ceph side and how many cores would be reasonable to provide 5212for SPDK to get up to your projections. 5213 5214#### Result 5215 5216Name of newly created bdev. 5217 5218#### Example 5219 5220Example request with `key` from `/etc/ceph/ceph.client.admin.keyring`: 5221 5222~~~json 5223{ 5224 "params": { 5225 "pool_name": "rbd", 5226 "rbd_name": "foo", 5227 "config": { 5228 "mon_host": "192.168.7.1:6789,192.168.7.2:6789", 5229 "key": "AQDwf8db7zR1GRAA5k7NKXjS5S5V4mntwUDnGQ==", 5230 } 5231 "block_size": 4096, 5232 "uuid": "76210ea4-7920-40a0-a07b-8992a7443c76" 5233 }, 5234 "jsonrpc": "2.0", 5235 "method": "bdev_rbd_create", 5236 "id": 1 5237} 5238~~~ 5239 5240Example response: 5241 5242~~~json 5243response: 5244{ 5245 "jsonrpc": "2.0", 5246 "id": 1, 5247 "result": "Ceph0" 5248} 5249~~~ 5250 5251Example request with `cluster_name`: 5252 5253~~ 5254{ 5255 "params": { 5256 "pool_name": "rbd", 5257 "rbd_name": "foo", 5258 "block_size": 4096, 5259 "cluster_name": "rbd_cluster" 5260 }, 5261 "jsonrpc": "2.0", 5262 "method": "bdev_rbd_create", 5263 "id": 1 5264} 5265~~ 5266 5267Example response: 5268 5269~~ 5270response: 5271{ 5272 "jsonrpc": "2.0", 5273 "id": 1, 5274 "result": "Ceph0" 5275} 5276~~ 5277 5278### bdev_rbd_delete {#rpc_bdev_rbd_delete} 5279 5280Delete @ref bdev_config_rbd bdev 5281 5282This method is available only if SPDK was build with Ceph RBD support. 5283 5284#### Result 5285 5286`true` if bdev with provided name was deleted or `false` otherwise. 5287 5288#### Parameters 5289 5290Name | Optional | Type | Description 5291----------------------- | -------- | ----------- | ----------- 5292name | Required | string | Bdev name 5293 5294#### Example 5295 5296Example request: 5297 5298~~~json 5299{ 5300 "params": { 5301 "name": "Rbd0" 5302 }, 5303 "jsonrpc": "2.0", 5304 "method": "bdev_rbd_delete", 5305 "id": 1 5306} 5307~~~ 5308 5309Example response: 5310 5311~~~json 5312{ 5313 "jsonrpc": "2.0", 5314 "id": 1, 5315 "result": true 5316} 5317~~~ 5318 5319### bdev_rbd_resize {#rpc_bdev_rbd_resize} 5320 5321Resize @ref bdev_config_rbd bdev 5322 5323This method is available only if SPDK was build with Ceph RBD support. 5324 5325#### Result 5326 5327`true` if bdev with provided name was resized or `false` otherwise. 5328 5329#### Parameters 5330 5331Name | Optional | Type | Description 5332----------------------- | -------- | ----------- | ----------- 5333name | Required | string | Bdev name 5334new_size | Required | int | New bdev size for resize operation in MiB 5335 5336#### Example 5337 5338Example request: 5339 5340~~~json 5341{ 5342 "params": { 5343 "name": "Rbd0" 5344 "new_size": "4096" 5345 }, 5346 "jsonrpc": "2.0", 5347 "method": "bdev_rbd_resize", 5348 "id": 1 5349} 5350~~~ 5351 5352Example response: 5353 5354~~~json 5355{ 5356 "jsonrpc": "2.0", 5357 "id": 1, 5358 "result": true 5359} 5360~~~ 5361 5362### bdev_delay_create {#rpc_bdev_delay_create} 5363 5364Create delay bdev. This bdev type redirects all IO to it's base bdev and inserts a delay on the completion 5365path to create an artificial drive latency. All latency values supplied to this bdev should be in microseconds. 5366 5367#### Parameters 5368 5369Name | Optional | Type | Description 5370----------------------- | -------- | ----------- | ----------- 5371name | Required | string | Bdev name 5372base_bdev_name | Required | string | Base bdev name 5373avg_read_latency | Required | number | average read latency (us) 5374p99_read_latency | Required | number | p99 read latency (us) 5375avg_write_latency | Required | number | average write latency (us) 5376p99_write_latency | Required | number | p99 write latency (us) 5377 5378#### Result 5379 5380Name of newly created bdev. 5381 5382#### Example 5383 5384Example request: 5385 5386~~~json 5387{ 5388 "params": { 5389 "base_bdev_name": "Null0", 5390 "name": "Delay0", 5391 "avg_read_latency": "15", 5392 "p99_read_latency": "50", 5393 "avg_write_latency": "40", 5394 "p99_write_latency": "110", 5395 }, 5396 "jsonrpc": "2.0", 5397 "method": "bdev_delay_create", 5398 "id": 1 5399} 5400~~~ 5401 5402Example response: 5403 5404~~~json 5405{ 5406 "jsonrpc": "2.0", 5407 "id": 1, 5408 "result": "Delay0" 5409} 5410~~~ 5411 5412### bdev_delay_delete {#rpc_bdev_delay_delete} 5413 5414Delete delay bdev. 5415 5416#### Parameters 5417 5418Name | Optional | Type | Description 5419----------------------- | -------- | ----------- | ----------- 5420name | Required | string | Bdev name 5421 5422#### Example 5423 5424Example request: 5425 5426~~~json 5427{ 5428 "params": { 5429 "name": "Delay0" 5430 }, 5431 "jsonrpc": "2.0", 5432 "method": "bdev_delay_delete", 5433 "id": 1 5434} 5435 5436~~~ 5437 5438Example response: 5439 5440~~~json 5441{ 5442 "jsonrpc": "2.0", 5443 "id": 1, 5444 "result": true 5445} 5446~~~ 5447 5448### bdev_delay_update_latency {#rpc_bdev_delay_update_latency} 5449 5450Update a target latency value associated with a given delay bdev. Any currently 5451outstanding I/O will be completed with the old latency. 5452 5453#### Parameters 5454 5455Name | Optional | Type | Description 5456----------------------- | -------- | ----------- | ----------- 5457delay_bdev_name | Required | string | Name of the delay bdev 5458latency_type | Required | string | One of: avg_read, avg_write, p99_read, p99_write 5459latency_us | Required | number | The new latency value in microseconds 5460 5461#### Result 5462 5463Name of newly created bdev. 5464 5465#### Example 5466 5467Example request: 5468 5469~~~json 5470{ 5471 "params": { 5472 "delay_bdev_name": "Delay0", 5473 "latency_type": "avg_read", 5474 "latency_us": "100", 5475 }, 5476 "jsonrpc": "2.0", 5477 "method": "bdev_delay_update_latency", 5478 "id": 1 5479} 5480~~~ 5481 5482Example response: 5483 5484~~~json 5485{ 5486 "result": "true" 5487} 5488~~~ 5489 5490### bdev_error_create {#rpc_bdev_error_create} 5491 5492Construct error bdev. 5493 5494#### Parameters 5495 5496Name | Optional | Type | Description 5497----------------------- | -------- | ----------- | ----------- 5498base_name | Required | string | Base bdev name 5499uuid | Optional | string | UUID for this bdev 5500 5501#### Example 5502 5503Example request: 5504 5505~~~json 5506{ 5507 "params": { 5508 "base_name": "Malloc0" 5509 }, 5510 "jsonrpc": "2.0", 5511 "method": "bdev_error_create", 5512 "id": 1 5513} 5514~~~ 5515 5516Example response: 5517 5518~~~json 5519{ 5520 "jsonrpc": "2.0", 5521 "id": 1, 5522 "result": true 5523} 5524~~~ 5525 5526### bdev_error_delete {#rpc_bdev_error_delete} 5527 5528Delete error bdev 5529 5530#### Result 5531 5532`true` if bdev with provided name was deleted or `false` otherwise. 5533 5534#### Parameters 5535 5536Name | Optional | Type | Description 5537----------------------- | -------- | ----------- | ----------- 5538name | Required | string | Error bdev name 5539 5540#### Example 5541 5542Example request: 5543 5544~~~json 5545{ 5546 "params": { 5547 "name": "EE_Malloc0" 5548 }, 5549 "jsonrpc": "2.0", 5550 "method": "bdev_error_delete", 5551 "id": 1 5552} 5553~~~ 5554 5555Example response: 5556 5557~~~json 5558{ 5559 "jsonrpc": "2.0", 5560 "id": 1, 5561 "result": true 5562} 5563~~~ 5564 5565### bdev_error_inject_error {#rpc_bdev_error_inject_error} 5566 5567Inject an error via an error bdev. Create an error bdev on base bdev first. Default 'num' 5568value is 1 and if 'num' is set to zero, the specified injection is disabled. 5569 5570#### Parameters 5571 5572Name | Optional | Type | Description 5573----------------------- | -------- | ----------- | ----------- 5574name | Required | string | Name of the error injection bdev 5575io_type | Required | string | io type 'clear' 'read' 'write' 'unmap' 'flush' 'all' 5576error_type | Required | string | error type 'failure' 'pending' 'corrupt_data' 'nomem' 5577num | Optional | int | the number of commands you want to fail.(default:1) 5578queue_depth | Optional | int | the queue depth at which to trigger the error 5579corrupt_offset | Optional | int | the offset in bytes to xor with corrupt_value 5580corrupt_value | Optional | int | the value for xor (1-255, 0 is invalid) 5581 5582#### Example 5583 5584Example request: 5585 5586~~~json 5587{ 5588 "jsonrpc": "2.0", 5589 "method": "bdev_error_inject_error", 5590 "id": 1, 5591 "params": { 5592 "name": "EE_Malloc0", 5593 "io_type": "write", 5594 "error_type": "pending", 5595 "num": 1 5596 } 5597} 5598~~~ 5599 5600Example response: 5601 5602~~~json 5603{ 5604 "jsonrpc": "2.0", 5605 "id": 1, 5606 "result": true 5607} 5608~~~ 5609 5610### bdev_iscsi_set_options {#rpc_bdev_iscsi_set_options} 5611 5612This RPC can be called at any time, but the new value will only take effect for new iSCSI bdevs. 5613 5614#### Parameters 5615 5616Name | Optional | Type | Description 5617-------------------------- | -------- | ----------- | ----------- 5618timeout_sec | Optional | number | Timeout for command, in seconds, if 0, don't track timeout 5619 5620#### Example 5621 5622Example request: 5623 5624~~~json 5625request: 5626{ 5627 "params": { 5628 "timeout_sec": 30 5629 }, 5630 "jsonrpc": "2.0", 5631 "method": "bdev_iscsi_set_options", 5632 "id": 1 5633} 5634~~~ 5635 5636Example response: 5637 5638~~~json 5639{ 5640 "jsonrpc": "2.0", 5641 "id": 1, 5642 "result": true 5643} 5644~~~ 5645 5646### bdev_iscsi_create {#rpc_bdev_iscsi_create} 5647 5648Connect to iSCSI target and create bdev backed by this connection. 5649 5650This method is available only if SPDK was build with iSCSI initiator support. 5651 5652#### Parameters 5653 5654Name | Optional | Type | Description 5655----------------------- | -------- | ----------- | ----------- 5656name | Required | string | Bdev name 5657initiator_iqn | Required | string | IQN name used during connection 5658url | Required | string | iSCSI resource URI 5659 5660#### Result 5661 5662Name of newly created bdev. 5663 5664#### Example 5665 5666Example request: 5667 5668~~~json 5669{ 5670 "params": { 5671 "url": "iscsi://127.0.0.1/iqn.2016-06.io.spdk:disk1/0", 5672 "initiator_iqn": "iqn.2016-06.io.spdk:init", 5673 "name": "iSCSI0" 5674 }, 5675 "jsonrpc": "2.0", 5676 "method": "bdev_iscsi_create", 5677 "id": 1 5678} 5679~~~ 5680 5681Example response: 5682 5683~~~json 5684{ 5685 "jsonrpc": "2.0", 5686 "id": 1, 5687 "result": "iSCSI0" 5688} 5689~~~ 5690 5691### bdev_iscsi_delete {#rpc_bdev_iscsi_delete} 5692 5693Delete iSCSI bdev and terminate connection to target. 5694 5695This method is available only if SPDK was built with iSCSI initiator support. 5696 5697#### Parameters 5698 5699Name | Optional | Type | Description 5700----------------------- | -------- | ----------- | ----------- 5701name | Required | string | Bdev name 5702 5703#### Example 5704 5705Example request: 5706 5707~~~json 5708{ 5709 "params": { 5710 "name": "iSCSI0" 5711 }, 5712 "jsonrpc": "2.0", 5713 "method": "bdev_iscsi_delete", 5714 "id": 1 5715} 5716~~~ 5717 5718Example response: 5719 5720~~~json 5721{ 5722 "jsonrpc": "2.0", 5723 "id": 1, 5724 "result": true 5725} 5726~~~ 5727 5728### bdev_ftl_create {#rpc_bdev_ftl_create} 5729 5730Create FTL bdev. 5731 5732This RPC is subject to change. 5733 5734#### Parameters 5735 5736Name | Optional | Type | Description 5737----------------------- | -------- | ----------- | ----------- 5738name | Required | string | Bdev name 5739base_bdev | Required | string | Name of the base device 5740cache | Required | string | Name of the cache device 5741uuid | Optional | string | UUID of restored bdev (not applicable when creating new instance) 5742core_mask | Optional | string | CPU core(s) possible for placement of the ftl core thread, application main thread by default 5743overprovisioning | Optional | int | Percentage of base device used for relocation, 20% by default 5744fast_shutdown | Optional | bool | When set FTL will minimize persisted data on target application shutdown and rely on shared memory during next load 5745 5746#### Result 5747 5748Name of newly created bdev. 5749 5750#### Example 5751 5752Example request: 5753 5754~~~json 5755{ 5756 "params": { 5757 "name": "ftl0", 5758 "base_bdev": "nvme0n1", 5759 "cache": "nvme1n1", 5760 "uuid": "4a7481ce-786f-41a0-9b86-8f7465c8f4d3", 5761 "core_mask": "[0]", 5762 "overprovisioning": 10 5763 }, 5764 "jsonrpc": "2.0", 5765 "method": "bdev_ftl_create", 5766 "id": 1 5767} 5768~~~ 5769 5770Example response: 5771 5772~~~json 5773{ 5774 "jsonrpc": "2.0", 5775 "id": 1, 5776 "result": { 5777 "name" : "ftl0" 5778 "uuid" : "4a7481ce-786f-41a0-9b86-8f7465c8f4d3" 5779 } 5780} 5781~~~ 5782 5783### bdev_ftl_load {#rpc_bdev_ftl_load} 5784 5785Loads FTL bdev. 5786 5787This RPC is subject to change. 5788 5789#### Parameters 5790 5791Name | Optional | Type | Description 5792----------------------- | -------- | ----------- | ----------- 5793name | Required | string | Bdev name 5794base_bdev | Required | string | Name of the base device 5795cache | Required | string | Name of the cache device 5796uuid | Required | string | UUID of restored bdev 5797core_mask | Optional | string | CPU core(s) possible for placement of the ftl core thread, application main thread by default 5798overprovisioning | Optional | int | Percentage of base device used for relocation, 20% by default 5799fast_shutdown | Optional | bool | When set FTL will minimize persisted data on target application shutdown and rely on shared memory during next load 5800 5801#### Result 5802 5803Name of loaded bdev. 5804 5805#### Example 5806 5807Example request: 5808 5809~~~json 5810{ 5811 "params": { 5812 "name": "ftl0", 5813 "base_bdev": "nvme0n1", 5814 "cache": "nvme1n1", 5815 "uuid": "4a7481ce-786f-41a0-9b86-8f7465c8f4d3", 5816 "core_mask": "[0]", 5817 "overprovisioning": 10 5818 }, 5819 "jsonrpc": "2.0", 5820 "method": "bdev_ftl_load", 5821 "id": 1 5822} 5823~~~ 5824 5825Example response: 5826 5827~~~json 5828{ 5829 "jsonrpc": "2.0", 5830 "id": 1, 5831 "result": { 5832 "name" : "ftl0" 5833 "uuid" : "4a7481ce-786f-41a0-9b86-8f7465c8f4d3" 5834 } 5835} 5836~~~ 5837 5838### bdev_ftl_delete {#rpc_bdev_ftl_delete} 5839 5840Delete FTL bdev. 5841 5842This RPC is subject to change. 5843 5844#### Parameters 5845 5846Name | Optional | Type | Description 5847----------------------- | -------- | ----------- | ----------- 5848name | Required | string | Bdev name 5849fast_shutdown | Optional | bool | When set FTL will minimize persisted data during deletion and rely on shared memory during next load 5850 5851#### Example 5852 5853Example request: 5854 5855~~~json 5856{ 5857 "params": { 5858 "name": "ftl0" 5859 }, 5860 "jsonrpc": "2.0", 5861 "method": "bdev_ftl_delete", 5862 "id": 1 5863} 5864~~~ 5865 5866Example response: 5867 5868~~~json 5869{ 5870 "jsonrpc": "2.0", 5871 "id": 1, 5872 "result": true 5873} 5874~~~ 5875 5876### bdev_ftl_unload {#rpc_bdev_ftl_unload} 5877 5878Unloads FTL bdev. 5879 5880This RPC is subject to change. 5881 5882#### Parameters 5883 5884Name | Optional | Type | Description 5885----------------------- | -------- | ----------- | ----------- 5886name | Required | string | Bdev name 5887fast_shutdown | Optional | bool | When set FTL will minimize persisted data during deletion and rely on shared memory during next load 5888 5889#### Example 5890 5891Example request: 5892 5893~~~json 5894{ 5895 "params": { 5896 "name": "ftl0" 5897 }, 5898 "jsonrpc": "2.0", 5899 "method": "bdev_ftl_unload", 5900 "id": 1 5901} 5902~~~ 5903 5904Example response: 5905 5906~~~json 5907{ 5908 "jsonrpc": "2.0", 5909 "id": 1, 5910 "result": true 5911} 5912~~~ 5913 5914### bdev_ftl_unmap {#rpc_bdev_ftl_unmap} 5915 5916Unmap range of LBAs. 5917 5918This RPC is subject to change. 5919 5920#### Parameters 5921 5922Name | Optional | Type | Description 5923----------------------- | -------- | ----------- | ----------- 5924name | Required | string | Bdev name 5925lba | Required | number | start lba, aligned to 1024 5926num_blocks | Required | number | number of blocks, aligned to 1024 5927 5928#### Example 5929 5930Example request: 5931 5932~~~json 5933{ 5934 "params": { 5935 "name": "ftl0" 5936 "lba": "0" 5937 "num_blocks": "1024" 5938 }, 5939 "jsonrpc": "2.0", 5940 "method": "bdev_ftl_unmap", 5941 "id": 1 5942} 5943~~~ 5944 5945Example response: 5946 5947~~~json 5948{ 5949 "jsonrpc": "2.0", 5950 "id": 1, 5951 "result": true 5952} 5953~~~ 5954 5955### bdev_ftl_get_stats {#rpc_bdev_ftl_get_stats} 5956 5957Get IO statistics for FTL bdev 5958 5959This RPC is subject to change. 5960 5961#### Parameters 5962 5963Name | Optional | Type | Description 5964----------------------- | -------- | ----------- | ----------- 5965name | Required | string | Bdev name 5966 5967#### Response 5968 5969The response is an object containing IO statistics for an FTL instance, split into multiple subobjects: 5970 5971- `user` - contains information about number of IOs, and errors for any incoming requests, 5972- `cmp` - information about IO for the compaction process, 5973- `gc` - information about IO for the garbage collection process, 5974- `md_base` - internal metadata requests to the base FTL device, 5975- `md_nv_cache` - internal metadata requests to the cache device, 5976- `l2p` - requests done on the L2P cache region. 5977 5978Each subobject contains the following information: 5979 5980- `ios` - describes the total number of IOs requested, 5981- `blocks` - the total number of requested blocks, 5982- `errors` - describes the number of detected errors for a given operation, with the following distinctions: 5983 - `media` - media errors, 5984 - `crc` - mismatch in calculated CRC versus saved checksum in the metadata, 5985 - `other` - any other errors. 5986 5987#### Example 5988 5989Example request: 5990 5991~~~json 5992{ 5993 "params": { 5994 "name": "ftl0" 5995 }, 5996 "jsonrpc": "2.0", 5997 "method": "bdev_ftl_get_stats", 5998 "id": 1 5999} 6000~~~ 6001 6002Example response: 6003 6004~~~json 6005{ 6006 "jsonrpc": "2.0", 6007 "id": 1, 6008 "result": { 6009 "name": "ftl0", 6010 "user": { 6011 "read": { 6012 "ios": 0, 6013 "blocks": 0, 6014 "errors": { 6015 "media": 0, 6016 "crc": 0, 6017 "other": 0 6018 } 6019 }, 6020 "write": { 6021 "ios": 318707, 6022 "blocks": 318707, 6023 "errors": { 6024 "media": 0, 6025 "other": 0 6026 } 6027 } 6028 }, 6029 "cmp": { 6030 "read": { 6031 "ios": 0, 6032 "blocks": 0, 6033 "errors": { 6034 "media": 0, 6035 "crc": 0, 6036 "other": 0 6037 } 6038 }, 6039 "write": { 6040 "ios": 0, 6041 "blocks": 0, 6042 "errors": { 6043 "media": 0, 6044 "other": 0 6045 } 6046 } 6047 }, 6048 "gc": { 6049 "read": { 6050 "ios": 0, 6051 "blocks": 0, 6052 "errors": { 6053 "media": 0, 6054 "crc": 0, 6055 "other": 0 6056 } 6057 }, 6058 "write": { 6059 "ios": 0, 6060 "blocks": 0, 6061 "errors": { 6062 "media": 0, 6063 "other": 0 6064 } 6065 } 6066 }, 6067 "md_base": { 6068 "read": { 6069 "ios": 0, 6070 "blocks": 0, 6071 "errors": { 6072 "media": 0, 6073 "crc": 0, 6074 "other": 0 6075 } 6076 }, 6077 "write": { 6078 "ios": 1, 6079 "blocks": 32, 6080 "errors": { 6081 "media": 0, 6082 "other": 0 6083 } 6084 } 6085 }, 6086 "md_nv_cache": { 6087 "read": { 6088 "ios": 0, 6089 "blocks": 0, 6090 "errors": { 6091 "media": 0, 6092 "crc": 0, 6093 "other": 0 6094 } 6095 }, 6096 "write": { 6097 "ios": 1064, 6098 "blocks": 1073896, 6099 "errors": { 6100 "media": 0, 6101 "other": 0 6102 } 6103 } 6104 }, 6105 "l2p": { 6106 "read": { 6107 "ios": 240659, 6108 "blocks": 240659, 6109 "errors": { 6110 "media": 0, 6111 "crc": 0, 6112 "other": 0 6113 } 6114 }, 6115 "write": { 6116 "ios": 235745, 6117 "blocks": 235745, 6118 "errors": { 6119 "media": 0, 6120 "other": 0 6121 } 6122 } 6123 } 6124 } 6125} 6126~~~ 6127 6128### bdev_ftl_get_properties {#rpc_bdev_ftl_get_properties} 6129 6130Get FTL properties 6131 6132#### Parameters 6133 6134Name | Optional | Type | Description 6135----------------------- | -------- | ----------- | ----------- 6136name | Required | string | Bdev name 6137 6138#### Response 6139 6140The response contains FTL bdev properties. Some of them can be modified, other 6141reported as read only. 6142 6143#### Example 6144 6145Example request: 6146 6147~~~json 6148{ 6149 "params": { 6150 "name": "ftl0" 6151 }, 6152 "jsonrpc": "2.0", 6153 "method": "bdev_ftl_get_properties", 6154 "id": 1 6155} 6156~~~ 6157 6158Example response: 6159 6160~~~json 6161{ 6162 "jsonrpc": "2.0", 6163 "id": 1, 6164 "result": { 6165 "name": "ftl0", 6166 "properties": [ 6167 { 6168 "name": "property1", 6169 "value": "Property Value 1", 6170 "unit": "MiB/s", 6171 "desc": "This is an example of read-only property", 6172 "read-only": true 6173 }, 6174 { 6175 "name": "property2", 6176 "value": 17, 6177 "unit": "s", 6178 "desc": "This is an example of FTL modifiable property", 6179 "read-only": false 6180 } 6181 ] 6182 } 6183} 6184~~~ 6185 6186### bdev_ftl_set_property {#rpc_bdev_ftl_set_property} 6187 6188Set FTL property. Trying to set a read-only property will result in an error. 6189 6190#### Parameters 6191 6192Name | Optional | Type | Description 6193----------------------- | -------- | ----------- | ----------- 6194name | Required | string | Bdev name 6195property | Required | string | Name of the property to modify 6196value | Required | string | New value of the property to be set 6197 6198#### Example 6199 6200Example request: 6201 6202~~~json 6203{ 6204 "params": { 6205 "name": "ftl0" 6206 "property": "nv_cache.flush" 6207 "value": "true" 6208 }, 6209 "jsonrpc": "2.0", 6210 "method": "bdev_ftl_set_property", 6211 "id": 1 6212} 6213~~~ 6214 6215Example response: 6216 6217~~~json 6218{ 6219 "jsonrpc": "2.0", 6220 "id": 1, 6221 "result": true 6222} 6223~~~ 6224 6225### bdev_passthru_create {#rpc_bdev_passthru_create} 6226 6227Create passthru bdev. This bdev type redirects all IO to it's base bdev. It has no other purpose than being an example 6228and a starting point in development of new bdev type. 6229 6230#### Parameters 6231 6232Name | Optional | Type | Description 6233----------------------- | -------- | ----------- | ----------- 6234name | Required | string | Bdev name 6235base_bdev_name | Required | string | Base bdev name 6236uuid | Optional | string | UUID of new bdev 6237 6238#### Result 6239 6240Name of newly created bdev. 6241 6242#### Example 6243 6244Example request: 6245 6246~~~json 6247{ 6248 "params": { 6249 "base_bdev_name": "Malloc0", 6250 "name": "Passsthru0" 6251 }, 6252 "jsonrpc": "2.0", 6253 "method": "bdev_passthru_create", 6254 "id": 1 6255} 6256~~~ 6257 6258Example response: 6259 6260~~~json 6261{ 6262 "jsonrpc": "2.0", 6263 "id": 1, 6264 "result": "Passsthru0" 6265} 6266~~~ 6267 6268### bdev_passthru_delete {#rpc_bdev_passthru_delete} 6269 6270Delete passthru bdev. 6271 6272#### Parameters 6273 6274Name | Optional | Type | Description 6275----------------------- | -------- | ----------- | ----------- 6276name | Required | string | Bdev name 6277 6278#### Example 6279 6280Example request: 6281 6282~~~json 6283{ 6284 "params": { 6285 "name": "Passsthru0" 6286 }, 6287 "jsonrpc": "2.0", 6288 "method": "bdev_passthru_delete", 6289 "id": 1 6290} 6291 6292~~~ 6293 6294Example response: 6295 6296~~~json 6297{ 6298 "jsonrpc": "2.0", 6299 "id": 1, 6300 "result": true 6301} 6302~~~ 6303 6304### bdev_xnvme_create {#rpc_bdev_xnvme_create} 6305 6306Create xnvme bdev. This bdev type redirects all IO to its underlying backend. 6307 6308#### Parameters 6309 6310Name | Optional | Type | Description 6311----------------------- | -------- | ----------- | ----------- 6312name | Required | string | name of xNVMe bdev to create 6313filename | Required | string | path to device or file (ex: /dev/nvme0n1) 6314io_mechanism | Required | string | IO mechanism to use (ex: libaio, io_uring, io_uring_cmd, etc.) 6315conserve_cpu | Optional | boolean | Whether or not to conserve CPU when polling (default: false) 6316 6317#### Result 6318 6319Name of newly created bdev. 6320 6321#### Example 6322 6323Example request: 6324 6325~~~json 6326{ 6327 "jsonrpc": "2.0", 6328 "method": "bdev_xnvme_create", 6329 "id": 1, 6330 "params": { 6331 "name": "bdev_ng0n1", 6332 "filename": "/dev/ng0n1", 6333 "io_mechanism": "io_uring_cmd", 6334 "conserve_cpu": false, 6335 } 6336} 6337~~~ 6338 6339Example response: 6340 6341~~~json 6342{ 6343 "jsonrpc": "2.0", 6344 "id": 1, 6345 "result": "bdev_ng0n1" 6346} 6347~~~ 6348 6349### bdev_xnvme_delete {#rpc_bdev_xnvme_delete} 6350 6351Delete xnvme bdev. 6352 6353#### Parameters 6354 6355Name | Optional | Type | Description 6356----------------------- | -------- | ----------- | ----------- 6357name | Required | string | name of xnvme bdev to delete 6358 6359#### Example 6360 6361Example request: 6362 6363~~~json 6364{ 6365 "params": { 6366 "name": "bdev_ng0n1" 6367 }, 6368 "jsonrpc": "2.0", 6369 "method": "bdev_xnvme_delete", 6370 "id": 1 6371} 6372 6373~~~ 6374 6375Example response: 6376 6377~~~json 6378{ 6379 "jsonrpc": "2.0", 6380 "id": 1, 6381 "result": true 6382} 6383~~~ 6384 6385### bdev_virtio_attach_controller {#rpc_bdev_virtio_attach_controller} 6386 6387Create new initiator @ref bdev_config_virtio_scsi or @ref bdev_config_virtio_blk and expose all found bdevs. 6388 6389#### Parameters 6390 6391Name | Optional | Type | Description 6392----------------------- | -------- | ----------- | ----------- 6393name | Required | string | Virtio SCSI base bdev name or Virtio Blk bdev name 6394trtype | Required | string | Virtio target trtype: pci or user 6395traddr | Required | string | target address: BDF or UNIX socket file path 6396dev_type | Required | string | Virtio device type: blk or scsi 6397vq_count | Optional | number | Number of queues this controller will utilize (default: 1) 6398vq_size | Optional | number | Size of each queue. Must be power of 2. (default: 512) 6399 6400In case of Virtio SCSI the `name` parameter will be base name for new created bdevs. For Virtio Blk `name` will be the 6401name of created bdev. 6402 6403`vq_count` and `vq_size` parameters are valid only if `trtype` is `user`. 6404 6405#### Result 6406 6407Array of names of newly created bdevs. 6408 6409#### Example 6410 6411Example request: 6412 6413~~~json 6414{ 6415 "params": { 6416 "name": "VirtioScsi0", 6417 "trtype": "user", 6418 "vq_size": 128, 6419 "dev_type": "scsi", 6420 "traddr": "/tmp/VhostScsi0", 6421 "vq_count": 4 6422 }, 6423 "jsonrpc": "2.0", 6424 "method": "bdev_virtio_attach_controller", 6425 "id": 1 6426} 6427~~~ 6428 6429Example response: 6430 6431~~~json 6432{ 6433 "jsonrpc": "2.0", 6434 "id": 1, 6435 "result": ["VirtioScsi0t2", "VirtioScsi0t4"] 6436} 6437~~~ 6438 6439### bdev_virtio_scsi_get_devices {#rpc_bdev_virtio_scsi_get_devices} 6440 6441Show information about all available Virtio SCSI devices. 6442 6443#### Parameters 6444 6445This method has no parameters. 6446 6447#### Result 6448 6449Array of Virtio SCSI information objects. 6450 6451#### Example 6452 6453Example request: 6454 6455~~~json 6456{ 6457 "jsonrpc": "2.0", 6458 "method": "bdev_virtio_scsi_get_devices", 6459 "id": 1 6460} 6461~~~ 6462 6463Example response: 6464 6465~~~json 6466{ 6467 "jsonrpc": "2.0", 6468 "id": 1, 6469 "result": [ 6470 { 6471 "name": "VirtioScsi0", 6472 "virtio": { 6473 "vq_size": 128, 6474 "vq_count": 4, 6475 "type": "user", 6476 "socket": "/tmp/VhostScsi0" 6477 } 6478 } 6479 ] 6480} 6481~~~ 6482 6483### bdev_virtio_detach_controller {#rpc_bdev_virtio_detach_controller} 6484 6485Remove a Virtio device. This command can be used to remove any type of virtio device. 6486 6487#### Parameters 6488 6489Name | Optional | Type | Description 6490----------------------- | -------- | ----------- | ----------- 6491name | Required | string | Virtio name 6492 6493#### Example 6494 6495Example request: 6496 6497~~~json 6498{ 6499 "params": { 6500 "name": "VirtioUser0" 6501 }, 6502 "jsonrpc": "2.0", 6503 "method": "bdev_virtio_detach_controller", 6504 "id": 1 6505} 6506 6507~~~ 6508 6509Example response: 6510 6511~~~json 6512{ 6513 "jsonrpc": "2.0", 6514 "id": 1, 6515 "result": true 6516} 6517~~~ 6518 6519### bdev_virtio_blk_set_hotplug {#rpc_bdev_virtio_blk_set_hotplug} 6520 6521Enable/Disable the virtio blk hotplug monitor or change the monitor period time 6522 6523#### Parameters 6524 6525Name | Optional | Type | Description 6526----------------------- | -------- | ----------- | ----------- 6527enable | Required | bool | Enable or disable the virtio blk hotplug monitor 6528period-us | Optional | number | The period time of the monitor 6529 6530When the enable is true then the period-us is optional. If user don't set the period time then use the default 6531value. When the enable is false then the period-us is not required. 6532 6533#### Result 6534 6535True the rpc is successful otherwise false 6536 6537#### Example 6538 6539Example request: 6540 6541~~~json 6542{ 6543 "params": { 6544 "enable": "true", 6545 "period-us": "1000000" 6546 }, 6547 "jsonrpc": "2.0", 6548 "method": "bdev_virtio_blk_set_hotplug", 6549 "id": 1 6550} 6551~~~ 6552 6553Example response: 6554 6555~~~json 6556{ 6557 "jsonrpc": "2.0", 6558 "id": 1, 6559 "result": true 6560} 6561~~~ 6562 6563## iSCSI Target {#jsonrpc_components_iscsi_tgt} 6564 6565### iscsi_set_options method {#rpc_iscsi_set_options} 6566 6567Set global parameters for iSCSI targets. 6568 6569This RPC may only be called before SPDK subsystems have been initialized. This RPC can be called only once. 6570 6571#### Parameters 6572 6573Name | Optional | Type | Description 6574------------------------------- | -------- | ------- | ----------- 6575auth_file | Optional | string | Path to CHAP shared secret file (default: "") 6576node_base | Optional | string | Prefix of the name of iSCSI target node (default: "iqn.2016-06.io.spdk") 6577nop_timeout | Optional | number | Timeout in seconds to nop-in request to the initiator (default: 60) 6578nop_in_interval | Optional | number | Time interval in secs between nop-in requests by the target (default: 30) 6579disable_chap | Optional | boolean | CHAP for discovery session should be disabled (default: `false`) 6580require_chap | Optional | boolean | CHAP for discovery session should be required (default: `false`) 6581mutual_chap | Optional | boolean | CHAP for discovery session should be unidirectional (`false`) or bidirectional (`true`) (default: `false`) 6582chap_group | Optional | number | CHAP group ID for discovery session (default: 0) 6583max_sessions | Optional | number | Maximum number of sessions in the host (default: 128) 6584max_queue_depth | Optional | number | Maximum number of outstanding I/Os per queue (default: 64) 6585max_connections_per_session | Optional | number | Session specific parameter, MaxConnections (default: 2) 6586default_time2wait | Optional | number | Session specific parameter, DefaultTime2Wait (default: 2) 6587default_time2retain | Optional | number | Session specific parameter, DefaultTime2Retain (default: 20) 6588first_burst_length | Optional | number | Session specific parameter, FirstBurstLength (default: 8192) 6589immediate_data | Optional | boolean | Session specific parameter, ImmediateData (default: `true`) 6590error_recovery_level | Optional | number | Session specific parameter, ErrorRecoveryLevel (default: 0) 6591allow_duplicated_isid | Optional | boolean | Allow duplicated initiator session ID (default: `false`) 6592max_large_datain_per_connection | Optional | number | Max number of outstanding split read I/Os per connection (default: 64) 6593max_r2t_per_connection | Optional | number | Max number of outstanding R2Ts per connection (default: 4) 6594pdu_pool_size | Optional | number | Number of PDUs in the pool (default: approximately 2 * max_sessions * (max_queue_depth + max_connections_per_session)) 6595immediate_data_pool_size | Optional | number | Number of immediate data buffers in the pool (default: 128 * max_sessions) 6596data_out_pool_size | Optional | number | Number of data out buffers in the pool (default: 16 * max_sessions) 6597 6598To load CHAP shared secret file, its path is required to specify explicitly in the parameter `auth_file`. 6599 6600Parameters `disable_chap` and `require_chap` are mutually exclusive. Parameters `no_discovery_auth`, `req_discovery_auth`, 6601`req_discovery_auth_mutual`, and `discovery_auth_group` are still available instead of `disable_chap`, `require_chap`, 6602`mutual_chap`, and `chap_group`, respectivey but will be removed in future releases. 6603 6604#### Example 6605 6606Example request: 6607 6608~~~json 6609{ 6610 "params": { 6611 "allow_duplicated_isid": true, 6612 "default_time2retain": 60, 6613 "first_burst_length": 8192, 6614 "immediate_data": true, 6615 "node_base": "iqn.2016-06.io.spdk", 6616 "max_sessions": 128, 6617 "nop_timeout": 30, 6618 "nop_in_interval": 30, 6619 "auth_file": "/usr/local/etc/spdk/auth.conf", 6620 "disable_chap": true, 6621 "default_time2wait": 2 6622 }, 6623 "jsonrpc": "2.0", 6624 "method": "iscsi_set_options", 6625 "id": 1 6626} 6627~~~ 6628 6629Example response: 6630 6631~~~json 6632{ 6633 "jsonrpc": "2.0", 6634 "id": 1, 6635 "result": true 6636} 6637~~~ 6638 6639### iscsi_get_options method {#rpc_iscsi_get_options} 6640 6641Show global parameters of iSCSI targets. 6642 6643#### Parameters 6644 6645This method has no parameters. 6646 6647#### Example 6648 6649Example request: 6650 6651~~~json 6652request: 6653{ 6654 "jsonrpc": "2.0", 6655 "method": "iscsi_get_options", 6656 "id": 1 6657} 6658~~~ 6659 6660Example response: 6661 6662~~~json 6663{ 6664 "jsonrpc": "2.0", 6665 "id": 1, 6666 "result": { 6667 "allow_duplicated_isid": true, 6668 "default_time2retain": 60, 6669 "first_burst_length": 8192, 6670 "immediate_data": true, 6671 "node_base": "iqn.2016-06.io.spdk", 6672 "mutual_chap": false, 6673 "nop_in_interval": 30, 6674 "chap_group": 0, 6675 "max_connections_per_session": 2, 6676 "max_queue_depth": 64, 6677 "nop_timeout": 30, 6678 "max_sessions": 128, 6679 "error_recovery_level": 0, 6680 "auth_file": "/usr/local/etc/spdk/auth.conf", 6681 "disable_chap": true, 6682 "default_time2wait": 2, 6683 "require_chap": false, 6684 "max_large_datain_per_connection": 64, 6685 "max_r2t_per_connection": 4 6686 } 6687} 6688~~~ 6689 6690### scsi_get_devices {#rpc_scsi_get_devices} 6691 6692Display SCSI devices 6693 6694#### Parameters 6695 6696This method has no parameters. 6697 6698#### Example 6699 6700Example request: 6701 6702~~~json 6703{ 6704 "jsonrpc": "2.0", 6705 "method": "scsi_get_devices", 6706 "id": 1 6707} 6708~~~ 6709 6710Example response: 6711 6712~~~json 6713{ 6714 "jsonrpc": "2.0", 6715 "id": 1, 6716 "result": [ 6717 { 6718 "id": 0, 6719 "device_name": "iqn.2016-06.io.spdk:Target3" 6720 } 6721 ] 6722} 6723~~~ 6724 6725### iscsi_set_discovery_auth method {#rpc_iscsi_set_discovery_auth} 6726 6727Set CHAP authentication for sessions dynamically. 6728 6729#### Parameters 6730 6731Name | Optional | Type | Description 6732--------------------------- | -------- | --------| ----------- 6733disable_chap | Optional | boolean | CHAP for discovery session should be disabled (default: `false`) 6734require_chap | Optional | boolean | CHAP for discovery session should be required (default: `false`) 6735mutual_chap | Optional | boolean | CHAP for discovery session should be unidirectional (`false`) or bidirectional (`true`) (default: `false`) 6736chap_group | Optional | number | CHAP group ID for discovery session (default: 0) 6737 6738Parameters `disable_chap` and `require_chap` are mutually exclusive. 6739 6740#### Example 6741 6742Example request: 6743 6744~~~json 6745request: 6746{ 6747 "params": { 6748 "chap_group": 1, 6749 "require_chap": true, 6750 "mutual_chap": true 6751 }, 6752 "jsonrpc": "2.0", 6753 "method": "iscsi_set_discovery_auth", 6754 "id": 1 6755} 6756~~~ 6757 6758Example response: 6759 6760~~~json 6761{ 6762 "jsonrpc": "2.0", 6763 "id": 1, 6764 "result": true 6765} 6766~~~ 6767 6768### iscsi_create_auth_group method {#rpc_iscsi_create_auth_group} 6769 6770Create an authentication group for CHAP authentication. 6771 6772#### Parameters 6773 6774Name | Optional | Type | Description 6775--------------------------- | -------- | --------| ----------- 6776tag | Required | number | Authentication group tag (unique, integer > 0) 6777secrets | Optional | array | Array of @ref rpc_iscsi_create_auth_group_secret objects 6778 6779#### secret {#rpc_iscsi_create_auth_group_secret} 6780 6781Name | Optional | Type | Description 6782--------------------------- | ---------| --------| ----------- 6783user | Required | string | Unidirectional CHAP name 6784secret | Required | string | Unidirectional CHAP secret 6785muser | Optional | string | Bidirectional CHAP name 6786msecret | Optional | string | Bidirectional CHAP secret 6787 6788#### Example 6789 6790Example request: 6791 6792~~~json 6793{ 6794 "params": { 6795 "secrets": [ 6796 { 6797 "muser": "mu1", 6798 "secret": "s1", 6799 "user": "u1", 6800 "msecret": "ms1" 6801 } 6802 ], 6803 "tag": 2 6804 }, 6805 "jsonrpc": "2.0", 6806 "method": "iscsi_create_auth_group", 6807 "id": 1 6808} 6809~~~ 6810 6811Example response: 6812 6813~~~json 6814{ 6815 "jsonrpc": "2.0", 6816 "id": 1, 6817 "result": true 6818} 6819~~~ 6820 6821### iscsi_delete_auth_group method {#rpc_iscsi_delete_auth_group} 6822 6823Delete an existing authentication group for CHAP authentication. 6824 6825#### Parameters 6826 6827Name | Optional | Type | Description 6828--------------------------- | -------- | --------| ----------- 6829tag | Required | number | Authentication group tag (unique, integer > 0) 6830 6831#### Example 6832 6833Example request: 6834 6835~~~json 6836{ 6837 "params": { 6838 "tag": 2 6839 }, 6840 "jsonrpc": "2.0", 6841 "method": "iscsi_delete_auth_group", 6842 "id": 1 6843} 6844~~~ 6845 6846Example response: 6847 6848~~~json 6849{ 6850 "jsonrpc": "2.0", 6851 "id": 1, 6852 "result": true 6853} 6854~~~ 6855 6856### iscsi_get_auth_groups {#rpc_iscsi_get_auth_groups} 6857 6858Show information about all existing authentication group for CHAP authentication. 6859 6860#### Parameters 6861 6862This method has no parameters. 6863 6864#### Result 6865 6866Array of objects describing authentication group. 6867 6868Name | Type | Description 6869--------------------------- | --------| ----------- 6870tag | number | Authentication group tag 6871secrets | array | Array of @ref rpc_iscsi_create_auth_group_secret objects 6872 6873#### Example 6874 6875Example request: 6876 6877~~~json 6878{ 6879 "jsonrpc": "2.0", 6880 "method": "iscsi_get_auth_groups", 6881 "id": 1 6882} 6883~~~ 6884 6885Example response: 6886 6887~~~json 6888{ 6889 "jsonrpc": "2.0", 6890 "id": 1, 6891 "result": [ 6892 { 6893 "secrets": [ 6894 { 6895 "muser": "mu1", 6896 "secret": "s1", 6897 "user": "u1", 6898 "msecret": "ms1" 6899 } 6900 ], 6901 "tag": 1 6902 }, 6903 { 6904 "secrets": [ 6905 { 6906 "secret": "s2", 6907 "user": "u2" 6908 } 6909 ], 6910 "tag": 2 6911 } 6912 ] 6913} 6914~~~ 6915 6916### iscsi_auth_group_add_secret {#rpc_iscsi_auth_group_add_secret} 6917 6918Add a secret to an existing authentication group for CHAP authentication. 6919 6920#### Parameters 6921 6922Name | Optional | Type | Description 6923--------------------------- | -------- | --------| ----------- 6924tag | Required | number | Authentication group tag (unique, integer > 0) 6925user | Required | string | Unidirectional CHAP name 6926secret | Required | string | Unidirectional CHAP secret 6927muser | Optional | string | Bidirectional CHAP name 6928msecret | Optional | string | Bidirectional CHAP secret 6929 6930#### Example 6931 6932Example request: 6933 6934~~~json 6935{ 6936 "params": { 6937 "muser": "mu3", 6938 "secret": "s3", 6939 "tag": 2, 6940 "user": "u3", 6941 "msecret": "ms3" 6942 }, 6943 "jsonrpc": "2.0", 6944 "method": "iscsi_auth_group_add_secret", 6945 "id": 1 6946} 6947~~~json 6948 6949Example response: 6950 6951~~~json 6952{ 6953 "jsonrpc": "2.0", 6954 "id": 1, 6955 "result": true 6956} 6957~~~ 6958 6959### iscsi_auth_group_remove_secret {#rpc_iscsi_auth_group_remove_secret} 6960 6961Remove a secret from an existing authentication group for CHAP authentication. 6962 6963#### Parameters 6964 6965Name | Optional | Type | Description 6966--------------------------- | -------- | --------| ----------- 6967tag | Required | number | Authentication group tag (unique, integer > 0) 6968user | Required | string | Unidirectional CHAP name 6969 6970#### Example 6971 6972Example request: 6973 6974~~~json 6975{ 6976 "params": { 6977 "tag": 2, 6978 "user": "u3" 6979 }, 6980 "jsonrpc": "2.0", 6981 "method": "iscsi_auth_group_remove_secret", 6982 "id": 1 6983} 6984~~~ 6985 6986Example response: 6987 6988~~~json 6989{ 6990 "jsonrpc": "2.0", 6991 "id": 1, 6992 "result": true 6993} 6994~~~ 6995 6996### iscsi_get_initiator_groups method {#rpc_iscsi_get_initiator_groups} 6997 6998Show information about all available initiator groups. 6999 7000#### Parameters 7001 7002This method has no parameters. 7003 7004#### Result 7005 7006Array of objects describing initiator groups. 7007 7008Name | Type | Description 7009--------------------------- | --------| ----------- 7010tag | number | Initiator group tag 7011initiators | array | Array of initiator hostnames or IP addresses 7012netmasks | array | Array of initiator netmasks 7013 7014#### Example 7015 7016Example request: 7017 7018~~~json 7019{ 7020 "jsonrpc": "2.0", 7021 "method": "iscsi_get_initiator_groups", 7022 "id": 1 7023} 7024~~~ 7025 7026Example response: 7027 7028~~~json 7029{ 7030 "jsonrpc": "2.0", 7031 "id": 1, 7032 "result": [ 7033 { 7034 "initiators": [ 7035 "iqn.2016-06.io.spdk:host1", 7036 "iqn.2016-06.io.spdk:host2" 7037 ], 7038 "tag": 1, 7039 "netmasks": [ 7040 "192.168.1.0/24" 7041 ] 7042 } 7043 ] 7044} 7045~~~ 7046 7047### iscsi_create_initiator_group method {#rpc_iscsi_create_initiator_group} 7048 7049Add an initiator group. 7050 7051#### Parameters 7052 7053Name | Optional | Type | Description 7054--------------------------- | -------- | --------| ----------- 7055tag | Required | number | Initiator group tag (unique, integer > 0) 7056initiators | Required | array | Not empty array of initiator hostnames or IP addresses 7057netmasks | Required | array | Not empty array of initiator netmasks 7058 7059#### Example 7060 7061Example request: 7062 7063~~~json 7064{ 7065 "params": { 7066 "initiators": [ 7067 "iqn.2016-06.io.spdk:host1", 7068 "iqn.2016-06.io.spdk:host2" 7069 ], 7070 "tag": 1, 7071 "netmasks": [ 7072 "192.168.1.0/24" 7073 ] 7074 }, 7075 "jsonrpc": "2.0", 7076 "method": "iscsi_create_initiator_group", 7077 "id": 1 7078} 7079~~~ 7080 7081Example response: 7082 7083~~~json 7084response: 7085{ 7086 "jsonrpc": "2.0", 7087 "id": 1, 7088 "result": true 7089} 7090~~~ 7091 7092### iscsi_delete_initiator_group method {#rpc_iscsi_delete_initiator_group} 7093 7094Delete an existing initiator group. 7095 7096#### Parameters 7097 7098Name | Optional | Type | Description 7099--------------------------- | -------- | --------| ----------- 7100tag | Required | number | Initiator group tag (unique, integer > 0) 7101 7102#### Example 7103 7104Example request: 7105 7106~~~json 7107{ 7108 "params": { 7109 "tag": 1 7110 }, 7111 "jsonrpc": "2.0", 7112 "method": "iscsi_delete_initiator_group", 7113 "id": 1 7114} 7115~~~ 7116 7117Example response: 7118 7119~~~json 7120{ 7121 "jsonrpc": "2.0", 7122 "id": 1, 7123 "result": true 7124} 7125~~~ 7126 7127### iscsi_initiator_group_add_initiators method {#rpc_iscsi_initiator_group_add_initiators} 7128 7129Add initiators to an existing initiator group. 7130 7131#### Parameters 7132 7133Name | Optional | Type | Description 7134--------------------------- | -------- | --------| ----------- 7135tag | Required | number | Existing initiator group tag. 7136initiators | Optional | array | Array of initiator hostnames or IP addresses 7137netmasks | Optional | array | Array of initiator netmasks 7138 7139#### Example 7140 7141Example request: 7142 7143~~~json 7144request: 7145{ 7146 "params": { 7147 "initiators": [ 7148 "iqn.2016-06.io.spdk:host3" 7149 ], 7150 "tag": 1, 7151 "netmasks": [ 7152 "255.255.255.1" 7153 ] 7154 }, 7155 "jsonrpc": "2.0", 7156 "method": "iscsi_initiator_group_add_initiators", 7157 "id": 1 7158} 7159~~~ 7160 7161Example response: 7162 7163~~~json 7164response: 7165{ 7166 "jsonrpc": "2.0", 7167 "id": 1, 7168 "result": true 7169} 7170~~~ 7171 7172### iscsi_initiator_group_remove_initiators method {#rpc_iscsi_initiator_group_remove_initiators} 7173 7174Remove initiators from an initiator group. 7175 7176#### Parameters 7177 7178Name | Optional | Type | Description 7179--------------------------- | -------- | --------| ----------- 7180tag | Required | number | Existing initiator group tag. 7181initiators | Optional | array | Array of initiator hostnames or IP addresses 7182netmasks | Optional | array | Array of initiator netmasks 7183 7184#### Example 7185 7186Example request: 7187 7188~~~json 7189request: 7190{ 7191 "params": { 7192 "initiators": [ 7193 "iqn.2016-06.io.spdk:host3" 7194 ], 7195 "tag": 1, 7196 "netmasks": [ 7197 "255.255.255.1" 7198 ] 7199 }, 7200 "jsonrpc": "2.0", 7201 "method": "iscsi_initiator_group_remove_initiators", 7202 "id": 1 7203} 7204~~~ 7205 7206Example response: 7207 7208~~~json 7209response: 7210{ 7211 "jsonrpc": "2.0", 7212 "id": 1, 7213 "result": true 7214} 7215~~~ 7216 7217### iscsi_get_target_nodes method {#rpc_iscsi_get_target_nodes} 7218 7219Show information about all available iSCSI target nodes. 7220 7221#### Parameters 7222 7223This method has no parameters. 7224 7225#### Result 7226 7227Array of objects describing target node. 7228 7229Name | Type | Description 7230--------------------------- | --------| ----------- 7231name | string | Target node name (ASCII) 7232alias_name | string | Target node alias name (ASCII) 7233pg_ig_maps | array | Array of Portal_Group_Tag:Initiator_Group_Tag mappings 7234luns | array | Array of Bdev names to LUN ID mappings 7235queue_depth | number | Target queue depth 7236disable_chap | boolean | CHAP authentication should be disabled for this target 7237require_chap | boolean | CHAP authentication should be required for this target 7238mutual_chap | boolean | CHAP authentication should be bidirectional (`true`) or unidirectional (`false`) 7239chap_group | number | Authentication group ID for this target node 7240header_digest | boolean | Header Digest should be required for this target node 7241data_digest | boolean | Data Digest should be required for this target node 7242 7243#### Example 7244 7245Example request: 7246 7247~~~json 7248{ 7249 "jsonrpc": "2.0", 7250 "method": "iscsi_get_target_nodes", 7251 "id": 1 7252} 7253~~~ 7254 7255Example response: 7256 7257~~~json 7258{ 7259 "jsonrpc": "2.0", 7260 "id": 1, 7261 "result": [ 7262 { 7263 "luns": [ 7264 { 7265 "lun_id": 0, 7266 "bdev_name": "Nvme0n1" 7267 } 7268 ], 7269 "mutual_chap": false, 7270 "name": "iqn.2016-06.io.spdk:target1", 7271 "alias_name": "iscsi-target1-alias", 7272 "require_chap": false, 7273 "chap_group": 0, 7274 "pg_ig_maps": [ 7275 { 7276 "ig_tag": 1, 7277 "pg_tag": 1 7278 } 7279 ], 7280 "data_digest": false, 7281 "disable_chap": false, 7282 "header_digest": false, 7283 "queue_depth": 64 7284 } 7285 ] 7286} 7287~~~ 7288 7289### iscsi_create_target_node method {#rpc_iscsi_create_target_node} 7290 7291Add an iSCSI target node. 7292 7293#### Parameters 7294 7295Name | Optional | Type | Description 7296--------------------------- | -------- | --------| ----------- 7297name | Required | string | Target node name (ASCII) 7298alias_name | Required | string | Target node alias name (ASCII) 7299pg_ig_maps | Required | array | Array of (Portal_Group_Tag:Initiator_Group_Tag) mappings 7300luns | Required | array | Array of Bdev names to LUN ID mappings 7301queue_depth | Required | number | Target queue depth 7302disable_chap | Optional | boolean | CHAP authentication should be disabled for this target 7303require_chap | Optional | boolean | CHAP authentication should be required for this target 7304mutual_chap | Optional | boolean | CHAP authentication should be bidirectional (`true`) or unidirectional (`false`) 7305chap_group | Optional | number | Authentication group ID for this target node 7306header_digest | Optional | boolean | Header Digest should be required for this target node 7307data_digest | Optional | boolean | Data Digest should be required for this target node 7308 7309Parameters `disable_chap` and `require_chap` are mutually exclusive. 7310 7311#### Example 7312 7313Example request: 7314 7315~~~json 7316{ 7317 "params": { 7318 "luns": [ 7319 { 7320 "lun_id": 0, 7321 "bdev_name": "Nvme0n1" 7322 } 7323 ], 7324 "mutual_chap": true, 7325 "name": "target2", 7326 "alias_name": "iscsi-target2-alias", 7327 "pg_ig_maps": [ 7328 { 7329 "ig_tag": 1, 7330 "pg_tag": 1 7331 }, 7332 { 7333 "ig_tag": 2, 7334 "pg_tag": 2 7335 } 7336 ], 7337 "data_digest": true, 7338 "disable_chap": true, 7339 "header_digest": true, 7340 "queue_depth": 24 7341 }, 7342 "jsonrpc": "2.0", 7343 "method": "iscsi_create_target_node", 7344 "id": 1 7345} 7346~~~ 7347 7348Example response: 7349 7350~~~json 7351{ 7352 "jsonrpc": "2.0", 7353 "id": 1, 7354 "result": true 7355} 7356~~~ 7357 7358### iscsi_target_node_set_auth method {#rpc_iscsi_target_node_set_auth} 7359 7360Set CHAP authentication to an existing iSCSI target node. 7361 7362#### Parameters 7363 7364Name | Optional | Type | Description 7365--------------------------- | -------- | --------| ----------- 7366name | Required | string | Target node name (ASCII) 7367disable_chap | Optional | boolean | CHAP authentication should be disabled for this target 7368require_chap | Optional | boolean | CHAP authentication should be required for this target 7369mutual_chap | Optional | boolean | CHAP authentication should be bidirectional (`true`) or unidirectional (`false`) 7370chap_group | Optional | number | Authentication group ID for this target node 7371 7372Parameters `disable_chap` and `require_chap` are mutually exclusive. 7373 7374#### Example 7375 7376Example request: 7377 7378~~~json 7379{ 7380 "params": { 7381 "chap_group": 1, 7382 "require_chap": true, 7383 "name": "iqn.2016-06.io.spdk:target1", 7384 "mutual_chap": true 7385 }, 7386 "jsonrpc": "2.0", 7387 "method": "iscsi_target_node_set_auth", 7388 "id": 1 7389} 7390~~~ 7391 7392Example response: 7393 7394~~~json 7395{ 7396 "jsonrpc": "2.0", 7397 "id": 1, 7398 "result": true 7399} 7400~~~ 7401 7402### iscsi_target_node_add_pg_ig_maps method {#rpc_iscsi_target_node_add_pg_ig_maps} 7403 7404Add initiator group to portal group mappings to an existing iSCSI target node. 7405 7406#### Parameters 7407 7408Name | Optional | Type | Description 7409--------------------------- | -------- | --------| ----------- 7410name | Required | string | Target node name (ASCII) 7411pg_ig_maps | Required | array | Not empty array of initiator to portal group mappings objects 7412 7413Portal to Initiator group mappings object: 7414 7415Name | Optional | Type | Description 7416--------------------------- | -------- | --------| ----------- 7417ig_tag | Required | number | Existing initiator group tag 7418pg_tag | Required | number | Existing portal group tag 7419 7420#### Example 7421 7422Example request: 7423 7424~~~json 7425{ 7426 "params": { 7427 "pg_ig_maps": [ 7428 { 7429 "ig_tag": 1, 7430 "pg_tag": 1 7431 }, 7432 { 7433 "ig_tag": 2, 7434 "pg_tag": 2 7435 }, 7436 { 7437 "ig_tag": 3, 7438 "pg_tag": 3 7439 } 7440 ], 7441 "name": "iqn.2016-06.io.spdk:target3" 7442 }, 7443 "jsonrpc": "2.0", 7444 "method": "iscsi_target_node_add_pg_ig_maps", 7445 "id": 1 7446} 7447~~~ 7448 7449Example response: 7450 7451~~~json 7452{ 7453 "jsonrpc": "2.0", 7454 "id": 1, 7455 "result": true 7456} 7457~~~ 7458 7459### iscsi_target_node_remove_pg_ig_maps method {#rpc_iscsi_target_node_remove_pg_ig_maps} 7460 7461Delete initiator group to portal group mappings from an existing iSCSI target node. 7462 7463#### Parameters 7464 7465Name | Optional | Type | Description 7466--------------------------- | -------- | --------| ----------- 7467name | Required | string | Target node name (ASCII) 7468pg_ig_maps | Required | array | Not empty array of Portal to Initiator group mappings objects 7469 7470Portal to Initiator group mappings object: 7471 7472Name | Optional | Type | Description 7473--------------------------- | -------- | --------| ----------- 7474ig_tag | Required | number | Existing initiator group tag 7475pg_tag | Required | number | Existing portal group tag 7476 7477#### Example 7478 7479Example request: 7480 7481~~~json 7482{ 7483 "params": { 7484 "pg_ig_maps": [ 7485 { 7486 "ig_tag": 1, 7487 "pg_tag": 1 7488 }, 7489 { 7490 "ig_tag": 2, 7491 "pg_tag": 2 7492 }, 7493 { 7494 "ig_tag": 3, 7495 "pg_tag": 3 7496 } 7497 ], 7498 "name": "iqn.2016-06.io.spdk:target3" 7499 }, 7500 "jsonrpc": "2.0", 7501 "method": "iscsi_target_node_remove_pg_ig_maps", 7502 "id": 1 7503} 7504~~~ 7505 7506Example response: 7507 7508~~~json 7509{ 7510 "jsonrpc": "2.0", 7511 "id": 1, 7512 "result": true 7513} 7514~~~ 7515 7516### iscsi_delete_target_node method {#rpc_iscsi_delete_target_node} 7517 7518Delete an iSCSI target node. 7519 7520#### Parameters 7521 7522Name | Optional | Type | Description 7523--------------------------- | -------- | --------| ----------- 7524name | Required | string | Target node name (ASCII) 7525 7526#### Example 7527 7528Example request: 7529 7530~~~json 7531{ 7532 "params": { 7533 "name": "iqn.2016-06.io.spdk:target1" 7534 }, 7535 "jsonrpc": "2.0", 7536 "method": "iscsi_delete_target_node", 7537 "id": 1 7538} 7539~~~ 7540 7541Example response: 7542 7543~~~json 7544{ 7545 "jsonrpc": "2.0", 7546 "id": 1, 7547 "result": true 7548} 7549~~~ 7550 7551### iscsi_get_portal_groups method {#rpc_iscsi_get_portal_groups} 7552 7553Show information about all available portal groups. 7554 7555#### Parameters 7556 7557This method has no parameters. 7558 7559#### Example 7560 7561Example request: 7562 7563~~~json 7564request: 7565{ 7566 "jsonrpc": "2.0", 7567 "method": "iscsi_get_portal_groups", 7568 "id": 1 7569} 7570~~~ 7571 7572Example response: 7573 7574~~~json 7575{ 7576 "jsonrpc": "2.0", 7577 "id": 1, 7578 "result": [ 7579 { 7580 "portals": [ 7581 { 7582 "host": "127.0.0.1", 7583 "port": "3260" 7584 } 7585 ], 7586 "tag": 1, 7587 "private": false 7588 } 7589 ] 7590} 7591~~~ 7592 7593### iscsi_create_portal_group method {#rpc_iscsi_create_portal_group} 7594 7595Add a portal group. 7596 7597#### Parameters 7598 7599Name | Optional | Type | Description 7600--------------------------- | -------- | --------| ----------- 7601tag | Required | number | Portal group tag 7602portals | Required | array | Not empty array of portals 7603private | Optional | boolean | When true, portals in this group are not returned by a discovery session. Used for login redirection. (default: `false`) 7604wait | Optional | boolean | When true, do not listen on portals until it is started explicitly. (default: `false`) 7605 7606Portal object 7607 7608Name | Optional | Type | Description 7609--------------------------- | -------- | --------| ----------- 7610host | Required | string | Hostname or IP address 7611port | Required | string | Port number 7612 7613#### Example 7614 7615Example request: 7616 7617~~~json 7618{ 7619 "params": { 7620 "portals": [ 7621 { 7622 "host": "127.0.0.1", 7623 "port": "3260" 7624 } 7625 ], 7626 "tag": 1 7627 }, 7628 "jsonrpc": "2.0", 7629 "method": "iscsi_create_portal_group", 7630 "id": 1 7631} 7632~~~ 7633 7634Example response: 7635 7636~~~json 7637{ 7638 "jsonrpc": "2.0", 7639 "id": 1, 7640 "result": true 7641} 7642~~~ 7643 7644### iscsi_start_portal_group method {#rpc_iscsi_start_portal_group} 7645 7646Start listening on portals if the portal group is not started yet, or do nothing 7647if the portal group already started. Return a success response for both cases. 7648 7649#### Parameters 7650 7651Name | Optional | Type | Description 7652--------------------------- | -------- | --------| ----------- 7653tag | Required | number | Existing portal group tag 7654 7655#### Example 7656 7657Example request: 7658 7659~~~json 7660{ 7661 "params": { 7662 "tag": 1 7663 }, 7664 "jsonrpc": "2.0", 7665 "method": "iscsi_start_portal_group", 7666 "id": 1 7667} 7668~~~ 7669 7670Example response: 7671 7672~~~json 7673{ 7674 "jsonrpc": "2.0", 7675 "id": 1, 7676 "result": true 7677} 7678~~~ 7679 7680### iscsi_delete_portal_group method {#rpc_iscsi_delete_portal_group} 7681 7682Delete an existing portal group. 7683 7684#### Parameters 7685 7686Name | Optional | Type | Description 7687--------------------------- | -------- | --------| ----------- 7688tag | Required | number | Existing portal group tag 7689 7690#### Example 7691 7692Example request: 7693 7694~~~json 7695{ 7696 "params": { 7697 "tag": 1 7698 }, 7699 "jsonrpc": "2.0", 7700 "method": "iscsi_delete_portal_group", 7701 "id": 1 7702} 7703~~~ 7704 7705Example response: 7706 7707~~~json 7708{ 7709 "jsonrpc": "2.0", 7710 "id": 1, 7711 "result": true 7712} 7713~~~ 7714 7715### iscsi_portal_group_set_auth method {#rpc_iscsi_portal_group_set_auth} 7716 7717Set CHAP authentication for discovery sessions specific for the existing iSCSI portal group. 7718This RPC overwrites the setting by the global parameters for the iSCSI portal group. 7719 7720#### Parameters 7721 7722Name | Optional | Type | Description 7723--------------------------- | -------- | --------| ----------- 7724disable_chap | Optional | boolean | CHAP for discovery session should be disabled (default: `false`) 7725require_chap | Optional | boolean | CHAP for discovery session should be required (default: `false`) 7726mutual_chap | Optional | boolean | CHAP for discovery session should be unidirectional (`false`) or bidirectional (`true`) (default: `false`) 7727chap_group | Optional | number | CHAP group ID for discovery session (default: 0) 7728 7729Parameters `disable_chap` and `require_chap` are mutually exclusive. 7730 7731#### Example 7732 7733Example request: 7734 7735~~~json 7736request: 7737{ 7738 "params": { 7739 "tag": 1, 7740 "chap_group": 1, 7741 "require_chap": true, 7742 "mutual_chap": true 7743 }, 7744 "jsonrpc": "2.0", 7745 "method": "iscsi_portal_group_set_auth", 7746 "id": 1 7747} 7748~~~ 7749 7750Example response: 7751 7752~~~json 7753{ 7754 "jsonrpc": "2.0", 7755 "id": 1, 7756 "result": true 7757} 7758~~~ 7759 7760### iscsi_get_connections method {#rpc_iscsi_get_connections} 7761 7762Show information about all active connections. 7763 7764#### Parameters 7765 7766This method has no parameters. 7767 7768#### Results 7769 7770Array of objects describing iSCSI connection. 7771 7772Name | Type | Description 7773--------------------------- | --------| ----------- 7774id | number | Index (used for TTT - Target Transfer Tag) 7775cid | number | CID (Connection ID) 7776tsih | number | TSIH (Target Session Identifying Handle) 7777lcore_id | number | Core number on which the iSCSI connection runs 7778initiator_addr | string | Initiator address 7779target_addr | string | Target address 7780target_node_name | string | Target node name (ASCII) without prefix 7781 7782#### Example 7783 7784Example request: 7785 7786~~~json 7787{ 7788 "jsonrpc": "2.0", 7789 "method": "iscsi_get_connections", 7790 "id": 1 7791} 7792~~~ 7793 7794Example response: 7795 7796~~~json 7797{ 7798 "jsonrpc": "2.0", 7799 "id": 1, 7800 "result": [ 7801 { 7802 "tsih": 4, 7803 "cid": 0, 7804 "target_node_name": "target1", 7805 "lcore_id": 0, 7806 "initiator_addr": "10.0.0.2", 7807 "target_addr": "10.0.0.1", 7808 "id": 0 7809 } 7810 ] 7811} 7812~~~ 7813 7814### iscsi_get_stats method {#iscsi_get_stats} 7815 7816Show stat information of iSCSI connections. 7817 7818#### Parameters 7819 7820This method has no parameters. 7821 7822#### Results 7823 7824Stat information of iSCSI connections. 7825 7826Name | Type | Description 7827--------------------------- | --------| ----------- 7828invalid | number | The number of invalid connections 7829running | number | The number of running connections 7830exiting | number | The number of exiting connections 7831exited | number | The number of exited connections 7832 7833#### Example 7834 7835Example request: 7836 7837~~~json 7838{ 7839 "jsonrpc": "2.0", 7840 "method": "iscsi_get_stats", 7841 "id": 1 7842} 7843~~~ 7844 7845Example response: 7846 7847~~~json 7848{ 7849 "jsonrpc": "2.0", 7850 "id": 1, 7851 "result": 7852 { 7853 "invalid": 0, 7854 "running": 5, 7855 "exiting": 0, 7856 "exited": 0 7857 } 7858 7859} 7860~~~ 7861 7862### iscsi_target_node_add_lun method {#rpc_iscsi_target_node_add_lun} 7863 7864Add an LUN to an existing iSCSI target node. 7865 7866#### Parameters 7867 7868Name | Optional | Type | Description 7869--------------------------- | -------- | --------| ----------- 7870name | Required | string | Target node name (ASCII) 7871bdev_name | Required | string | bdev name to be added as a LUN 7872lun_id | Optional | number | LUN ID (default: first free ID) 7873 7874#### Example 7875 7876Example request: 7877 7878~~~json 7879{ 7880 "params": { 7881 "lun_id": 2, 7882 "name": "iqn.2016-06.io.spdk:target1", 7883 "bdev_name": "Malloc0" 7884 }, 7885 "jsonrpc": "2.0", 7886 "method": "iscsi_target_node_add_lun", 7887 "id": 1 7888} 7889~~~ 7890 7891Example response: 7892 7893~~~json 7894{ 7895 "jsonrpc": "2.0", 7896 "id": 1, 7897 "result": true 7898} 7899~~~ 7900 7901### iscsi_target_node_set_redirect method {#rpc_iscsi_target_node_set_redirect} 7902 7903Update redirect portal of the primary portal group for the target node, 7904 7905#### Parameters 7906 7907Name | Optional | Type | Description 7908--------------------------- | -------- | --------| ----------- 7909name | Required | string | Target node name (ASCII) 7910pg_tag | Required | number | Existing portal group tag 7911redirect_host | Optional | string | Numeric IP address to which the target node is redirected 7912redirect_port | Optional | string | Numeric TCP port to which the target node is redirected 7913 7914If both redirect_host and redirect_port are omitted, clear the redirect portal. 7915 7916#### Example 7917 7918Example request: 7919 7920~~~json 7921{ 7922 "params": { 7923 "name": "iqn.2016-06.io.spdk:target1", 7924 "pg_tag": 1, 7925 "redirect_host": "10.0.0.3", 7926 "redirect_port": "3260" 7927 }, 7928 "jsonrpc": "2.0", 7929 "method": "iscsi_target_node_set_redirect", 7930 "id": 1 7931} 7932~~~ 7933 7934Example response: 7935 7936~~~json 7937{ 7938 "jsonrpc": "2.0", 7939 "id": 1, 7940 "result": true 7941} 7942~~~ 7943 7944### iscsi_target_node_request_logout method {#rpc_iscsi_target_node_request_logout} 7945 7946For the target node, request connections whose portal group tag match to logout, 7947or request all connections to logout if portal group tag is omitted. 7948 7949#### Parameters 7950 7951Name | Optional | Type | Description 7952--------------------------- | -------- | --------| ----------- 7953name | Required | string | Target node name (ASCII) 7954pg_tag | Optional | number | Existing portal group tag 7955 7956#### Example 7957 7958Example request: 7959 7960~~~json 7961{ 7962 "params": { 7963 "name": "iqn.2016-06.io.spdk:target1", 7964 "pg_tag": 1 7965 }, 7966 "jsonrpc": "2.0", 7967 "method": "iscsi_target_node_request_logout", 7968 "id": 1 7969} 7970~~~ 7971 7972Example response: 7973 7974~~~json 7975{ 7976 "jsonrpc": "2.0", 7977 "id": 1, 7978 "result": true 7979} 7980~~~ 7981 7982### iscsi_enable_histogram {#rpc_iscsi_enable_histogram} 7983 7984Control whether collecting data for histogram is enabled for specified iscsi target node. 7985 7986#### Parameters 7987 7988Name | Optional | Type | Description 7989----------------------- | -------- | ----------- | ----------- 7990name | Required | string | Iscsi target node name 7991enable | Required | boolean | Enable or disable histogram on specified target node 7992 7993#### Example 7994 7995Example request: 7996 7997~~~json 7998{ 7999 "jsonrpc": "2.0", 8000 "id": 1, 8001 "method": "iscsi_enable_histogram", 8002 "params": { 8003 "name": "iqn.2016-06.io.spdk:target1" 8004 "enable": true 8005 } 8006} 8007~~~ 8008 8009Example response: 8010 8011~~~json 8012{ 8013 "jsonrpc": "2.0", 8014 "id": 1, 8015 "result": true 8016} 8017~~~ 8018 8019### iscsi_get_histogram {#rpc_iscsi_get_histogram} 8020 8021Get latency histogram for specified iscsi target node. 8022 8023#### Parameters 8024 8025Name | Optional | Type | Description 8026----------------------- | -------- | ----------- | ----------- 8027name | Required | string | Iscsi target node name 8028 8029#### Result 8030 8031Name | Description 8032------------------------| ----------- 8033histogram | Base64 encoded histogram 8034bucket_shift | Granularity of the histogram buckets 8035tsc_rate | Ticks per second 8036 8037#### Example 8038 8039Example request: 8040 8041~~~json 8042{ 8043 "jsonrpc": "2.0", 8044 "id": 1, 8045 "method": "iscsi_get_histogram", 8046 "params": { 8047 "name": "iqn.2016-06.io.spdk:target1" 8048 } 8049} 8050~~~ 8051 8052Example response: 8053Note that histogram field is trimmed, actual encoded histogram length is ~80kb. 8054 8055~~~json 8056{ 8057 "jsonrpc": "2.0", 8058 "id": 1, 8059 "result": { 8060 "histogram": "AAAAAAAAAAAAAA...AAAAAAAAA==", 8061 "tsc_rate": 2300000000, 8062 "bucket_shift": 7 8063 } 8064} 8065~~~ 8066 8067## NVMe-oF Target {#jsonrpc_components_nvmf_tgt} 8068 8069### nvmf_create_transport method {#rpc_nvmf_create_transport} 8070 8071Initialize an NVMe-oF transport with the given options. 8072 8073#### Parameters 8074 8075Name | Optional | Type | Description 8076--------------------------- | -------- | --------| ----------- 8077trtype | Required | string | Transport type (ex. RDMA) 8078tgt_name | Optional | string | Parent NVMe-oF target name. 8079max_queue_depth | Optional | number | Max number of outstanding I/O per queue 8080max_io_qpairs_per_ctrlr | Optional | number | Max number of IO qpairs per controller 8081in_capsule_data_size | Optional | number | Max number of in-capsule data size 8082max_io_size | Optional | number | Max I/O size (bytes) 8083io_unit_size | Optional | number | I/O unit size (bytes) 8084max_aq_depth | Optional | number | Max number of admin cmds per AQ 8085num_shared_buffers | Optional | number | The number of pooled data buffers available to the transport 8086buf_cache_size | Optional | number | The number of shared buffers to reserve for each poll group 8087num_cqe | Optional | number | The number of CQ entries. Only used when no_srq=true (RDMA only) 8088max_srq_depth | Optional | number | The number of elements in a per-thread shared receive queue (RDMA only) 8089no_srq | Optional | boolean | Disable shared receive queue even for devices that support it. (RDMA only) 8090c2h_success | Optional | boolean | Disable C2H success optimization (TCP only) 8091dif_insert_or_strip | Optional | boolean | Enable DIF insert for write I/O and DIF strip for read I/O DIF 8092sock_priority | Optional | number | The socket priority of the connection owned by this transport (TCP only) 8093acceptor_backlog | Optional | number | The number of pending connections allowed in backlog before failing new connection attempts (RDMA only) 8094abort_timeout_sec | Optional | number | Abort execution timeout value, in seconds 8095no_wr_batching | Optional | boolean | Disable work requests batching (RDMA only) 8096control_msg_num | Optional | number | The number of control messages per poll group (TCP only) 8097disable_mappable_bar0 | Optional | boolean | disable client mmap() of BAR0 (VFIO-USER only) 8098disable_adaptive_irq | Optional | boolean | Disable adaptive interrupt feature (VFIO-USER only) 8099disable_shadow_doorbells | Optional | boolean | disable shadow doorbell support (VFIO-USER only) 8100zcopy | Optional | boolean | Use zero-copy operations if the underlying bdev supports them 8101ack_timeout | Optional | number | ACK timeout in milliseconds 8102data_wr_pool_size | Optional | number | RDMA data WR pool size (RDMA only) 8103 8104#### Example 8105 8106Example request: 8107 8108~~~json 8109{ 8110 "jsonrpc": "2.0", 8111 "method": "nvmf_create_transport", 8112 "id": 1, 8113 "params": { 8114 "trtype": "RDMA", 8115 "max_queue_depth": 32 8116 } 8117} 8118~~~ 8119 8120Example response: 8121 8122~~~json 8123{ 8124 "jsonrpc": "2.0", 8125 "id": 1, 8126 "result": true 8127} 8128~~~ 8129 8130### nvmf_get_subsystems method {#rpc_nvmf_get_subsystems} 8131 8132#### Parameters 8133 8134Name | Optional | Type | Description 8135--------------------------- | -------- | ------------| ----------- 8136tgt_name | Optional | string | Parent NVMe-oF target name. 8137 8138#### Example 8139 8140Example request: 8141 8142~~~json 8143{ 8144 "jsonrpc": "2.0", 8145 "id": 1, 8146 "method": "nvmf_get_subsystems" 8147} 8148~~~ 8149 8150Example response: 8151 8152~~~json 8153{ 8154 "jsonrpc": "2.0", 8155 "id": 1, 8156 "result": [ 8157 { 8158 "nqn": "nqn.2014-08.org.nvmexpress.discovery", 8159 "subtype": "Discovery" 8160 "listen_addresses": [], 8161 "hosts": [], 8162 "allow_any_host": true 8163 }, 8164 { 8165 "nqn": "nqn.2016-06.io.spdk:cnode1", 8166 "subtype": "NVMe", 8167 "listen_addresses": [ 8168 { 8169 "trtype": "RDMA", 8170 "adrfam": "IPv4", 8171 "traddr": "192.168.0.123", 8172 "trsvcid": "4420" 8173 } 8174 ], 8175 "hosts": [ 8176 {"nqn": "nqn.2016-06.io.spdk:host1"} 8177 ], 8178 "allow_any_host": false, 8179 "serial_number": "abcdef", 8180 "model_number": "ghijklmnop", 8181 "namespaces": [ 8182 {"nsid": 1, "name": "Malloc2"}, 8183 {"nsid": 2, "name": "Nvme0n1"} 8184 ] 8185 } 8186 ] 8187} 8188~~~ 8189 8190### nvmf_create_subsystem method {#rpc_nvmf_create_subsystem} 8191 8192Construct an NVMe over Fabrics target subsystem. 8193 8194#### Parameters 8195 8196Name | Optional | Type | Description 8197-------------------------- | -------- | ----------- | ----------- 8198nqn | Required | string | Subsystem NQN 8199tgt_name | Optional | string | Parent NVMe-oF target name. 8200serial_number | Optional | string | Serial number of virtual controller 8201model_number | Optional | string | Model number of virtual controller 8202max_namespaces | Optional | number | Maximum number of namespaces that can be attached to the subsystem. Default: 32 (also used if user specifies 0) 8203allow_any_host | Optional | boolean | Allow any host (`true`) or enforce allowed host list (`false`). Default: `false`. 8204ana_reporting | Optional | boolean | Enable ANA reporting feature (default: `false`). 8205min_cntlid | Optional | number | Minimum controller ID. Default: 1 8206max_cntlid | Optional | number | Maximum controller ID. Default: 0xffef 8207max_discard_size_kib | Optional | number | Maximum discard size (Kib). Default: 0 8208max_write_zeroes_size_kib | Optional | number | Maximum write_zeroes size (Kib). Default: 0 8209 8210#### Example 8211 8212Example request: 8213 8214~~~json 8215{ 8216 "jsonrpc": "2.0", 8217 "id": 1, 8218 "method": "nvmf_create_subsystem", 8219 "params": { 8220 "nqn": "nqn.2016-06.io.spdk:cnode1", 8221 "allow_any_host": false, 8222 "serial_number": "abcdef", 8223 "model_number": "ghijklmnop" 8224 } 8225} 8226~~~ 8227 8228Example response: 8229 8230~~~json 8231{ 8232 "jsonrpc": "2.0", 8233 "id": 1, 8234 "result": true 8235} 8236~~~ 8237 8238### nvmf_delete_subsystem method {#rpc_nvmf_delete_subsystem} 8239 8240Delete an existing NVMe-oF subsystem. 8241 8242#### Parameters 8243 8244Parameter | Optional | Type | Description 8245---------------------- | -------- | ----------- | ----------- 8246nqn | Required | string | Subsystem NQN to delete. 8247tgt_name | Optional | string | Parent NVMe-oF target name. 8248 8249#### Example 8250 8251Example request: 8252 8253~~~json 8254{ 8255 "jsonrpc": "2.0", 8256 "id": 1, 8257 "method": "nvmf_delete_subsystem", 8258 "params": { 8259 "nqn": "nqn.2016-06.io.spdk:cnode1" 8260 } 8261} 8262~~~ 8263 8264Example response: 8265 8266~~~json 8267{ 8268 "jsonrpc": "2.0", 8269 "id": 1, 8270 "result": true 8271} 8272~~~ 8273 8274### nvmf_subsystem_add_listener method {#rpc_nvmf_subsystem_add_listener} 8275 8276Add a new listen address to an NVMe-oF subsystem. 8277 8278This method will fail if listener with given address already exists. 8279 8280#### Parameters 8281 8282Name | Optional | Type | Description 8283----------------------- | -------- | ----------- | ----------- 8284nqn | Required | string | Subsystem NQN 8285tgt_name | Optional | string | Parent NVMe-oF target name. 8286listen_address | Required | object | @ref rpc_nvmf_listen_address object 8287secure_channel | Optional | bool | Whether all connections immediately attempt to establish a secure channel 8288 8289#### listen_address {#rpc_nvmf_listen_address} 8290 8291The listen_address is used for adding the listeners to the NVMe-oF target 8292and for referring to discovery services on other targets. 8293 8294Name | Optional | Type | Description 8295----------------------- | -------- | ----------- | ----------- 8296trtype | Required | string | Transport type ("RDMA") 8297adrfam | Optional | string | Address family ("IPv4", "IPv6", "IB", or "FC") 8298traddr | Required | string | Transport address 8299trsvcid | Optional | string | Transport service ID (required for RDMA or TCP) 8300 8301#### Example 8302 8303Example request: 8304 8305~~~json 8306{ 8307 "jsonrpc": "2.0", 8308 "id": 1, 8309 "method": "nvmf_subsystem_add_listener", 8310 "params": { 8311 "nqn": "nqn.2016-06.io.spdk:cnode1", 8312 "listen_address": { 8313 "trtype": "RDMA", 8314 "adrfam": "IPv4", 8315 "traddr": "192.168.0.123", 8316 "trsvcid": "4420" 8317 } 8318 } 8319} 8320~~~ 8321 8322Example response: 8323 8324~~~json 8325{ 8326 "jsonrpc": "2.0", 8327 "id": 1, 8328 "result": true 8329} 8330~~~ 8331 8332### nvmf_subsystem_remove_listener method {#rpc_nvmf_subsystem_remove_listener} 8333 8334Remove a listen address from an NVMe-oF subsystem. 8335 8336#### Parameters 8337 8338Name | Optional | Type | Description 8339----------------------- | -------- | ----------- | ----------- 8340nqn | Required | string | Subsystem NQN 8341tgt_name | Optional | string | Parent NVMe-oF target name. 8342listen_address | Required | object | @ref rpc_nvmf_listen_address object 8343 8344#### Example 8345 8346Example request: 8347 8348~~~json 8349{ 8350 "jsonrpc": "2.0", 8351 "id": 1, 8352 "method": "nvmf_subsystem_remove_listener", 8353 "params": { 8354 "nqn": "nqn.2016-06.io.spdk:cnode1", 8355 "listen_address": { 8356 "trtype": "RDMA", 8357 "adrfam": "IPv4", 8358 "traddr": "192.168.0.123", 8359 "trsvcid": "4420" 8360 } 8361 } 8362} 8363~~~ 8364 8365Example response: 8366 8367~~~json 8368{ 8369 "jsonrpc": "2.0", 8370 "id": 1, 8371 "result": true 8372} 8373~~~ 8374 8375### nvmf_subsystem_listener_set_ana_state method {#rpc_nvmf_subsystem_listener_set_ana_state} 8376 8377Set ANA state of a listener for an NVMe-oF subsystem. Only the ANA state of the specified ANA 8378group is updated, or ANA states of all ANA groups if ANA group is not specified. 8379 8380#### Parameters 8381 8382Name | Optional | Type | Description 8383----------------------- | -------- | ----------- | ----------- 8384nqn | Required | string | Subsystem NQN 8385tgt_name | Optional | string | Parent NVMe-oF target name. 8386listen_address | Required | object | @ref rpc_nvmf_listen_address object 8387ana_state | Required | string | ANA state to set ("optimized", "non_optimized", or "inaccessible") 8388anagrpid | Optional | number | ANA group ID 8389 8390#### Example 8391 8392Example request: 8393 8394~~~json 8395{ 8396 "jsonrpc": "2.0", 8397 "id": 1, 8398 "method": "nvmf_subsystem_listener_set_ana_state", 8399 "params": { 8400 "nqn": "nqn.2016-06.io.spdk:cnode1", 8401 "listen_address": { 8402 "trtype": "RDMA", 8403 "adrfam": "IPv4", 8404 "traddr": "192.168.0.123", 8405 "trsvcid": "4420" 8406 }, 8407 "ana_state", "inaccessible" 8408 } 8409} 8410~~~ 8411 8412Example response: 8413 8414~~~json 8415{ 8416 "jsonrpc": "2.0", 8417 "id": 1, 8418 "result": true 8419} 8420~~~ 8421 8422### nvmf_subsystem_add_ns method {#rpc_nvmf_subsystem_add_ns} 8423 8424Add a namespace to a subsystem. The namespace ID is returned as the result. 8425 8426### Parameters 8427 8428Name | Optional | Type | Description 8429----------------------- | -------- | ----------- | ----------- 8430nqn | Required | string | Subsystem NQN 8431namespace | Required | object | @ref rpc_nvmf_namespace object 8432tgt_name | Optional | string | Parent NVMe-oF target name. 8433no_auto_visible | Optional | bool | Namespace is not automatically visible to controllers (default: false) 8434 8435#### namespace {#rpc_nvmf_namespace} 8436 8437Name | Optional | Type | Description 8438----------------------- | -------- | ----------- | ----------- 8439nsid | Optional | number | Namespace ID between 1 and 4294967294, inclusive. Default: Automatically assign NSID. 8440bdev_name | Required | string | Name of bdev to expose as a namespace. 8441nguid | Optional | string | 16-byte namespace globally unique identifier in hexadecimal (e.g. "ABCDEF0123456789ABCDEF0123456789") 8442eui64 | Optional | string | 8-byte namespace EUI-64 in hexadecimal (e.g. "ABCDEF0123456789") 8443uuid | Optional | string | RFC 4122 UUID (e.g. "ceccf520-691e-4b46-9546-34af789907c5") 8444ptpl_file | Optional | string | File path to save/restore persistent reservation information 8445anagrpid | Optional | number | ANA group ID. Default: Namespace ID. 8446 8447#### Example 8448 8449Example request: 8450 8451~~~json 8452{ 8453 "jsonrpc": "2.0", 8454 "id": 1, 8455 "method": "nvmf_subsystem_add_ns", 8456 "params": { 8457 "nqn": "nqn.2016-06.io.spdk:cnode1", 8458 "namespace": { 8459 "nsid": 3, 8460 "bdev_name": "Nvme0n1", 8461 "ptpl_file": "/opt/Nvme0n1PR.json" 8462 } 8463 } 8464} 8465~~~ 8466 8467Example response: 8468 8469~~~json 8470{ 8471 "jsonrpc": "2.0", 8472 "id": 1, 8473 "result": 3 8474} 8475~~~ 8476 8477### nvmf_subsystem_remove_ns method {#rpc_nvmf_subsystem_remove_ns} 8478 8479Remove a namespace from a subsystem. 8480 8481#### Parameters 8482 8483Name | Optional | Type | Description 8484----------------------- | -------- | ----------- | ----------- 8485nqn | Required | string | Subsystem NQN 8486nsid | Required | number | Namespace ID 8487tgt_name | Optional | string | Parent NVMe-oF target name. 8488 8489#### Example 8490 8491Example request: 8492 8493~~~json 8494{ 8495 "jsonrpc": "2.0", 8496 "id": 1, 8497 "method": "nvmf_subsystem_remove_ns", 8498 "params": { 8499 "nqn": "nqn.2016-06.io.spdk:cnode1", 8500 "nsid": 1 8501 } 8502} 8503~~~ 8504 8505Example response: 8506 8507~~~json 8508{ 8509 "jsonrpc": "2.0", 8510 "id": 1, 8511 "result": true 8512} 8513~~~ 8514 8515### nvmf_subsystem_add_host method {#rpc_nvmf_subsystem_add_host} 8516 8517Add a host NQN to the list of allowed hosts. 8518 8519#### Parameters 8520 8521Name | Optional | Type | Description 8522----------------------- | -------- | ----------- | ----------- 8523nqn | Required | string | Subsystem NQN 8524host | Required | string | Host NQN to add to the list of allowed host NQNs 8525tgt_name | Optional | string | Parent NVMe-oF target name. 8526psk | Optional | string | Path to a file containing PSK for TLS connection 8527dhchap_key | Optional | string | DH-HMAC-CHAP key name. 8528 8529#### Example 8530 8531Example request: 8532 8533~~~json 8534{ 8535 "jsonrpc": "2.0", 8536 "id": 1, 8537 "method": "nvmf_subsystem_add_host", 8538 "params": { 8539 "nqn": "nqn.2016-06.io.spdk:cnode1", 8540 "host": "nqn.2016-06.io.spdk:host1", 8541 "dhchap_key": "key0" 8542 } 8543} 8544~~~ 8545 8546Example response: 8547 8548~~~json 8549{ 8550 "jsonrpc": "2.0", 8551 "id": 1, 8552 "result": true 8553} 8554~~~ 8555 8556### nvmf_subsystem_remove_host method {#rpc_nvmf_subsystem_remove_host} 8557 8558Remove a host NQN from the list of allowed hosts. 8559 8560#### Parameters 8561 8562Name | Optional | Type | Description 8563----------------------- | -------- | ----------- | ----------- 8564nqn | Required | string | Subsystem NQN 8565host | Required | string | Host NQN to remove from the list of allowed host NQNs 8566tgt_name | Optional | string | Parent NVMe-oF target name. 8567 8568#### Example 8569 8570Example request: 8571 8572~~~json 8573{ 8574 "jsonrpc": "2.0", 8575 "id": 1, 8576 "method": "nvmf_subsystem_remove_host", 8577 "params": { 8578 "nqn": "nqn.2016-06.io.spdk:cnode1", 8579 "host": "nqn.2016-06.io.spdk:host1" 8580 } 8581} 8582~~~ 8583 8584Example response: 8585 8586~~~json 8587{ 8588 "jsonrpc": "2.0", 8589 "id": 1, 8590 "result": true 8591} 8592~~~ 8593 8594### nvmf_subsystem_allow_any_host method {#rpc_nvmf_subsystem_allow_any_host} 8595 8596Configure a subsystem to allow any host to connect or to enforce the host NQN list. 8597 8598#### Parameters 8599 8600Name | Optional | Type | Description 8601----------------------- | -------- | ----------- | ----------- 8602nqn | Required | string | Subsystem NQN 8603allow_any_host | Required | boolean | Allow any host (`true`) or enforce allowed host list (`false`). 8604tgt_name | Optional | string | Parent NVMe-oF target name. 8605 8606#### Example 8607 8608Example request: 8609 8610~~~json 8611{ 8612 "jsonrpc": "2.0", 8613 "id": 1, 8614 "method": "nvmf_subsystem_allow_any_host", 8615 "params": { 8616 "nqn": "nqn.2016-06.io.spdk:cnode1", 8617 "allow_any_host": true 8618 } 8619} 8620~~~ 8621 8622Example response: 8623 8624~~~json 8625{ 8626 "jsonrpc": "2.0", 8627 "id": 1, 8628 "result": true 8629} 8630~~~ 8631 8632### nvmf_subsystem_get_controllers {#rpc_nvmf_subsystem_get_controllers} 8633 8634#### Parameters 8635 8636Name | Optional | Type | Description 8637----------------------- | -------- | ----------- | ----------- 8638nqn | Required | string | Subsystem NQN 8639tgt_name | Optional | string | Parent NVMe-oF target name. 8640 8641#### Example 8642 8643Example request: 8644 8645~~~json 8646{ 8647 "jsonrpc": "2.0", 8648 "id": 1, 8649 "method": "nvmf_subsystem_get_controllers", 8650 "params": { 8651 "nqn": "nqn.2016-06.io.spdk:cnode1" 8652 } 8653} 8654~~~ 8655 8656Example response: 8657 8658~~~json 8659{ 8660 "jsonrpc": "2.0", 8661 "id": 1, 8662 "result": [ 8663 { 8664 "cntlid": 1, 8665 "hostnqn": "nqn.2016-06.io.spdk:host1", 8666 "hostid": "27dad528-6368-41c3-82d3-0b956b49025d", 8667 "num_io_qpairs": 5 8668 } 8669 ] 8670} 8671~~~ 8672 8673### nvmf_subsystem_get_qpairs {#rpc_nvmf_subsystem_get_qpairs} 8674 8675#### Parameters 8676 8677Name | Optional | Type | Description 8678----------------------- | -------- | ----------- | ----------- 8679nqn | Required | string | Subsystem NQN 8680tgt_name | Optional | string | Parent NVMe-oF target name. 8681 8682#### Example 8683 8684Example request: 8685 8686~~~json 8687{ 8688 "jsonrpc": "2.0", 8689 "id": 1, 8690 "method": "nvmf_subsystem_get_qpairs", 8691 "params": { 8692 "nqn": "nqn.2016-06.io.spdk:cnode1" 8693 } 8694} 8695~~~ 8696 8697Example response: 8698 8699~~~json 8700{ 8701 "jsonrpc": "2.0", 8702 "id": 1, 8703 "result": [ 8704 { 8705 "cntlid": 1, 8706 "qid": 0, 8707 "state": "active", 8708 "listen_address": { 8709 "trtype": "RDMA", 8710 "adrfam": "IPv4", 8711 "traddr": "192.168.0.123", 8712 "trsvcid": "4420" 8713 } 8714 }, 8715 { 8716 "cntlid": 1, 8717 "qid": 1, 8718 "state": "active", 8719 "listen_address": { 8720 "trtype": "RDMA", 8721 "adrfam": "IPv4", 8722 "traddr": "192.168.0.123", 8723 "trsvcid": "4420" 8724 } 8725 } 8726 ] 8727} 8728~~~ 8729 8730### nvmf_subsystem_get_listeners {#rpc_nvmf_subsystem_get_listeners} 8731 8732#### Parameters 8733 8734Name | Optional | Type | Description 8735----------------------- | -------- | ----------- | ----------- 8736nqn | Required | string | Subsystem NQN 8737tgt_name | Optional | string | Parent NVMe-oF target name. 8738 8739#### Example 8740 8741Example request: 8742 8743~~~json 8744{ 8745 "jsonrpc": "2.0", 8746 "id": 1, 8747 "method": "nvmf_subsystem_get_listeners", 8748 "params": { 8749 "nqn": "nqn.2016-06.io.spdk:cnode1" 8750 } 8751} 8752~~~ 8753 8754Example response: 8755 8756~~~json 8757{ 8758 "jsonrpc": "2.0", 8759 "id": 1, 8760 "result": [ 8761 { 8762 "address": { 8763 "trtype": "RDMA", 8764 "adrfam": "IPv4", 8765 "traddr": "192.168.0.123", 8766 "trsvcid": "4420" 8767 }, 8768 "ana_state": "optimized" 8769 } 8770 ] 8771} 8772~~~ 8773 8774### nvmf_ns_add_host {#rpc_nvmf_ns_add_host} 8775 8776Make the specified namespace of the specified subnqn visible to any existing 8777or future controllers with the specified hostnqn. 8778 8779Note: the namespace must have been added with no_auto_visible = false 8780(see @ref rpc_nvmf_subsystem_add_ns). 8781 8782#### Parameters 8783 8784Name | Optional | Type | Description 8785----------------------- | -------- | ----------- | ----------- 8786nqn | Required | string | Subsystem NQN 8787nsid | Required | number | Namespace ID 8788host | Required | string | Host NQN 8789 8790#### Example 8791 8792Example request: 8793 8794~~~json 8795{ 8796 "jsonrpc": "2.0", 8797 "id": 1, 8798 "method": "nvmf_ns_add_host", 8799 "params": { 8800 "nqn": "nqn.2016-06.io.spdk:cnode1", 8801 "nsid": 1, 8802 "host": "nqn.2024-01.io.spdk:host0" 8803 } 8804} 8805~~~ 8806 8807Example response: 8808 8809~~~json 8810{ 8811 "jsonrpc": "2.0", 8812 "id": 1, 8813 "result": true 8814} 8815~~~ 8816 8817### nvmf_ns_remove_host {#rpc_nvmf_ns_remove_host} 8818 8819Make the specified namespace of the specified subnqn not visible to any existing 8820or future controllers with the specified hostnqn. 8821 8822Note: the namespace must have been added to the subsystem with 8823no_auto_visible = false (see @ref rpc_nvmf_subsystem_add_ns). 8824 8825#### Parameters 8826 8827Name | Optional | Type | Description 8828----------------------- | -------- | ----------- | ----------- 8829nqn | Required | string | Subsystem NQN 8830nsid | Required | number | Namespace ID 8831host | Required | string | Host NQN 8832 8833#### Example 8834 8835Example request: 8836 8837~~~json 8838{ 8839 "jsonrpc": "2.0", 8840 "id": 1, 8841 "method": "nvmf_ns_remove_host", 8842 "params": { 8843 "nqn": "nqn.2016-06.io.spdk:cnode1", 8844 "nsid": 1, 8845 "host": "nqn.2024-01.io.spdk:host0" 8846 } 8847} 8848~~~ 8849 8850Example response: 8851 8852~~~json 8853{ 8854 "jsonrpc": "2.0", 8855 "id": 1, 8856 "result": true 8857} 8858~~~ 8859 8860### nvmf_set_max_subsystems {#rpc_nvmf_set_max_subsystems} 8861 8862Set the maximum allowed subsystems for the NVMe-oF target. This RPC may only be called 8863before SPDK subsystems have been initialized. 8864 8865#### Parameters 8866 8867Name | Optional | Type | Description 8868----------------------- | -------- | ----------- | ----------- 8869max_subsystems | Required | number | Maximum number of NVMe-oF subsystems 8870 8871#### Example 8872 8873Example request: 8874 8875~~~json 8876{ 8877 "jsonrpc": "2.0", 8878 "id": 1, 8879 "method": "nvmf_set_max_subsystems", 8880 "params": { 8881 "max_subsystems": 1024 8882 } 8883} 8884~~~ 8885 8886Example response: 8887 8888~~~json 8889{ 8890 "jsonrpc": "2.0", 8891 "id": 1, 8892 "result": true 8893} 8894~~~ 8895 8896### nvmf_discovery_add_referral method {#rpc_nvmf_discovery_add_referral} 8897 8898Add a discovery service referral to an NVMe-oF target. If a referral with the given 8899parameters already exists, no action will be taken. 8900 8901#### Parameters 8902 8903Name | Optional | Type | Description 8904----------------------- | -------- | ----------- | ----------- 8905tgt_name | Optional | string | Parent NVMe-oF target name. 8906address | Required | object | @ref rpc_nvmf_listen_address object 8907secure_channel | Optional | bool | The connection to that discovery subsystem requires a secure channel 8908 8909#### Example 8910 8911Example request: 8912 8913~~~json 8914{ 8915 "jsonrpc": "2.0", 8916 "id": 1, 8917 "method": "nvmf_discovery_add_referral", 8918 "params": { 8919 "address": { 8920 "trtype": "RDMA", 8921 "adrfam": "IPv4", 8922 "traddr": "192.168.0.123", 8923 "trsvcid": "4420" 8924 } 8925 } 8926} 8927~~~ 8928 8929Example response: 8930 8931~~~json 8932{ 8933 "jsonrpc": "2.0", 8934 "id": 1, 8935 "result": true 8936} 8937~~~ 8938 8939### nvmf_discovery_remove_referral method {#rpc_nvmf_discovery_remove_referral} 8940 8941Remove a discovery service referral from an NVMe-oF target. 8942 8943#### Parameters 8944 8945Name | Optional | Type | Description 8946----------------------- | -------- | ----------- | ----------- 8947tgt_name | Optional | string | Parent NVMe-oF target name. 8948address | Required | object | @ref rpc_nvmf_listen_address object 8949 8950#### Example 8951 8952Example request: 8953 8954~~~json 8955{ 8956 "jsonrpc": "2.0", 8957 "id": 1, 8958 "method": "nvmf_discovery_remove_referral", 8959 "params": { 8960 "address": { 8961 "trtype": "RDMA", 8962 "adrfam": "IPv4", 8963 "traddr": "192.168.0.123", 8964 "trsvcid": "4420" 8965 } 8966 } 8967} 8968~~~ 8969 8970Example response: 8971 8972~~~json 8973{ 8974 "jsonrpc": "2.0", 8975 "id": 1, 8976 "result": true 8977} 8978~~~ 8979 8980### nvmf_discovery_get_referrals {#rpc_nvmf_discovery_get_referrals} 8981 8982#### Parameters 8983 8984Name | Optional | Type | Description 8985----------------------- | -------- | ----------- | ----------- 8986tgt_name | Optional | string | Parent NVMe-oF target name. 8987 8988#### Example 8989 8990Example request: 8991 8992~~~json 8993{ 8994 "jsonrpc": "2.0", 8995 "id": 1, 8996 "method": "nvmf_discovery_get_referrals" 8997} 8998~~~ 8999 9000Example response: 9001 9002~~~json 9003{ 9004 "jsonrpc": "2.0", 9005 "id": 1, 9006 "result": [ 9007 { 9008 "address": { 9009 "trtype": "RDMA", 9010 "adrfam": "IPv4", 9011 "traddr": "192.168.0.123", 9012 "trsvcid": "4420" 9013 } 9014 } 9015 ] 9016} 9017~~~ 9018 9019### nvmf_set_config {#rpc_nvmf_set_config} 9020 9021Set global configuration of NVMe-oF target. This RPC may only be called before SPDK subsystems 9022have been initialized. 9023 9024#### Parameters 9025 9026Name | Optional | Type | Description 9027----------------------- | -------- | ----------- | ----------- 9028acceptor_poll_rate | Optional | number | Polling interval of the acceptor for incoming connections (microseconds) 9029admin_cmd_passthru | Optional | object | Admin command passthru configuration 9030poll_groups_mask | Optional | string | Set cpumask for NVMf poll groups 9031discovery_filter | Optional | string | Set discovery filter, possible values are: `match_any` (default) or comma separated values: `transport`, `address`, `svcid` 9032 9033#### admin_cmd_passthru {#spdk_nvmf_admin_passthru_conf} 9034 9035Name | Optional | Type | Description 9036----------------------- | -------- | ----------- | ----------- 9037identify_ctrlr | Required | bool | If true, enables custom identify handler that reports some identify attributes from the underlying NVMe drive 9038 9039#### Example 9040 9041Example request: 9042 9043~~~json 9044{ 9045 "jsonrpc": "2.0", 9046 "id": 1, 9047 "method": "nvmf_set_config", 9048 "params": { 9049 "acceptor_poll_rate": 10000 9050 } 9051} 9052~~~ 9053 9054Example response: 9055 9056~~~json 9057{ 9058 "jsonrpc": "2.0", 9059 "id": 1, 9060 "result": true 9061} 9062~~~ 9063 9064### nvmf_get_transports method {#rpc_nvmf_get_transports} 9065 9066#### Parameters 9067 9068The user may specify no parameters in order to list all transports, or a transport may be 9069specified by type. 9070 9071Name | Optional | Type | Description 9072--------------------------- | -------- | ------------| ----------- 9073tgt_name | Optional | string | Parent NVMe-oF target name. 9074trtype | Optional | string | Transport type. 9075 9076#### Example 9077 9078Example request: 9079 9080~~~json 9081{ 9082 "jsonrpc": "2.0", 9083 "id": 1, 9084 "method": "nvmf_get_transports" 9085} 9086~~~ 9087 9088Example response: 9089 9090~~~json 9091{ 9092 "jsonrpc": "2.0", 9093 "id": 1, 9094 "result": [ 9095 { 9096 "type": "RDMA". 9097 "max_queue_depth": 128, 9098 "max_io_qpairs_per_ctrlr": 64, 9099 "in_capsule_data_size": 4096, 9100 "max_io_size": 131072, 9101 "io_unit_size": 131072, 9102 "abort_timeout_sec": 1 9103 } 9104 ] 9105} 9106~~~ 9107 9108### nvmf_get_stats method {#rpc_nvmf_get_stats} 9109 9110Retrieve current statistics of the NVMf subsystem. 9111 9112#### Parameters 9113 9114Name | Optional | Type | Description 9115--------------------------- | -------- | ------------| ----------- 9116tgt_name | Optional | string | Parent NVMe-oF target name. 9117 9118#### Response 9119 9120The response is an object containing NVMf subsystem statistics. 9121In the response, `admin_qpairs` and `io_qpairs` are reflecting cumulative queue pair counts while 9122`current_admin_qpairs` and `current_io_qpairs` are showing the current number. 9123 9124#### Example 9125 9126Example request: 9127 9128~~~json 9129{ 9130 "jsonrpc": "2.0", 9131 "method": "nvmf_get_stats", 9132 "id": 1 9133} 9134~~~ 9135 9136Example response: 9137 9138~~~json 9139{ 9140 "jsonrpc": "2.0", 9141 "id": 1, 9142 "result": { 9143 "tick_rate": 2400000000, 9144 "poll_groups": [ 9145 { 9146 "name": "app_thread", 9147 "admin_qpairs": 1, 9148 "io_qpairs": 4, 9149 "current_admin_qpairs": 1, 9150 "current_io_qpairs": 2, 9151 "pending_bdev_io": 1721, 9152 "transports": [ 9153 { 9154 "trtype": "RDMA", 9155 "pending_data_buffer": 12131888, 9156 "devices": [ 9157 { 9158 "name": "mlx5_1", 9159 "polls": 72284105, 9160 "completions": 0, 9161 "requests": 0, 9162 "request_latency": 0, 9163 "pending_free_request": 0, 9164 "pending_rdma_read": 0, 9165 "pending_rdma_write": 0, 9166 "total_send_wrs": 0, 9167 "send_doorbell_updates": 0, 9168 "total_recv_wrs": 0, 9169 "recv_doorbell_updates": 1 9170 }, 9171 { 9172 "name": "mlx5_0", 9173 "polls": 72284105, 9174 "completions": 15165875, 9175 "requests": 7582935, 9176 "request_latency": 1249323766184, 9177 "pending_free_request": 0, 9178 "pending_rdma_read": 337602, 9179 "pending_rdma_write": 0, 9180 "total_send_wrs": 15165875, 9181 "send_doorbell_updates": 1516587, 9182 "total_recv_wrs": 15165875, 9183 "recv_doorbell_updates": 1516587 9184 } 9185 ] 9186 } 9187 ] 9188 } 9189 ] 9190 } 9191} 9192~~~ 9193 9194### nvmf_set_crdt {#rpc_nvmf_set_crdt} 9195 9196Set the 3 CRDT (Command Retry Delay Time) values. For details about 9197CRDT, please refer to the NVMe specification. Currently all the 9198SPDK nvmf subsystems share the same CRDT values. The default values 9199are 0. This rpc can only be invoked in STARTUP stage. All values are 9200in units of 100 milliseconds (same as the NVMe specification). 9201 9202#### Parameters 9203 9204Name | Optional | Type | Description 9205----------------------- | -------- | ----------- | ----------- 9206crdt1 | Optional | number | Command Retry Delay Time 1 9207crdt2 | Optional | number | Command Retry Delay Time 2 9208crdt3 | Optional | number | Command Retry Delay Time 3 9209 9210## Vfio-user Target 9211 9212### vfu_tgt_set_base_path {#rpc_vfu_tgt_set_base_path} 9213 9214Set base path of Unix Domain socket file. 9215 9216#### Parameters 9217 9218Name | Optional | Type | Description 9219----------------------- | -------- | ----------- | ----------- 9220path | Required | string | Base path 9221 9222#### Example 9223 9224Example request: 9225 9226~~~json 9227{ 9228 "params": { 9229 "path": "/var/run/vfu_tgt" 9230 }, 9231 "jsonrpc": "2.0", 9232 "method": "vfu_tgt_set_base_path", 9233 "id": 1 9234} 9235~~~ 9236 9237Example response: 9238 9239~~~json 9240{ 9241 "jsonrpc": "2.0", 9242 "id": 1, 9243 "result": true 9244} 9245~~~ 9246 9247### vfu_virtio_delete_endpoint {#rpc_vfu_virtio_delete_endpoint} 9248 9249Delete PCI device via endpoint name. 9250 9251#### Parameters 9252 9253Name | Optional | Type | Description 9254----------------------- | -------- | ----------- | ----------- 9255name | Required | string | Endpoint name 9256 9257#### Example 9258 9259Example request: 9260 9261~~~json 9262{ 9263 "params": { 9264 "name": "vfu.0" 9265 }, 9266 "jsonrpc": "2.0", 9267 "method": "vfu_virtio_delete_endpoint", 9268 "id": 1 9269} 9270~~~ 9271 9272Example response: 9273 9274~~~json 9275{ 9276 "jsonrpc": "2.0", 9277 "id": 1, 9278 "result": true 9279} 9280~~~ 9281 9282### vfu_virtio_create_blk_endpoint {#rpc_vfu_virtio_create_blk_endpoint} 9283 9284Create vfio-user virtio-blk PCI endpoint. 9285 9286#### Parameters 9287 9288Name | Optional | Type | Description 9289----------------------- | -------- | ----------- | ----------- 9290name | Required | string | Endpoint name 9291bdev_name | Required | string | Block device name 9292cpumask | Optional | string | CPU masks 9293num_queues | Optional | number | Number of queues 9294qsize | Optional | number | Queue size 9295packed_ring | Optional | boolean | Enable packed ring 9296 9297#### Example 9298 9299Example request: 9300 9301~~~json 9302{ 9303 "params": { 9304 "name": "vfu.0", 9305 "bdev_name": "Malloc0", 9306 "cpumask": "0x2", 9307 "num_queues": 4, 9308 "qsize": 256 9309 }, 9310 "jsonrpc": "2.0", 9311 "method": "vfu_virtio_create_blk_endpoint", 9312 "id": 1 9313} 9314~~~ 9315 9316Example response: 9317 9318~~~json 9319{ 9320 "jsonrpc": "2.0", 9321 "id": 1, 9322 "result": true 9323} 9324~~~ 9325 9326### vfu_virtio_scsi_add_target {#rpc_vfu_virtio_scsi_add_target} 9327 9328Add block device to specified SCSI target of vfio-user virtio-scsi PCI endpoint. 9329 9330#### Parameters 9331 9332Name | Optional | Type | Description 9333----------------------- | -------- | ----------- | ----------- 9334name | Required | string | Endpoint name 9335scsi_target_num | Required | number | SCSI target number 9336bdev_name | Required | string | Block device name 9337 9338#### Example 9339 9340Example request: 9341 9342~~~json 9343{ 9344 "params": { 9345 "name": "vfu.0", 9346 "scsi_target_num": 0, 9347 "bdev_name": "Malloc0" 9348 }, 9349 "jsonrpc": "2.0", 9350 "method": "vfu_virtio_scsi_add_target", 9351 "id": 1 9352} 9353~~~ 9354 9355Example response: 9356 9357~~~json 9358{ 9359 "jsonrpc": "2.0", 9360 "id": 1, 9361 "result": true 9362} 9363~~~ 9364 9365### vfu_virtio_scsi_remove_target {#rpc_vfu_virtio_scsi_remove_target} 9366 9367Remove a SCSI target of vfio-user virtio-scsi PCI endpoint. 9368 9369#### Parameters 9370 9371Name | Optional | Type | Description 9372----------------------- | -------- | ----------- | ----------- 9373name | Required | string | Endpoint name 9374scsi_target_num | Required | number | SCSI target number 9375 9376#### Example 9377 9378Example request: 9379 9380~~~json 9381{ 9382 "params": { 9383 "name": "vfu.0", 9384 "scsi_target_num": 0 9385 }, 9386 "jsonrpc": "2.0", 9387 "method": "vfu_virtio_scsi_remove_target", 9388 "id": 1 9389} 9390~~~ 9391 9392Example response: 9393 9394~~~json 9395{ 9396 "jsonrpc": "2.0", 9397 "id": 1, 9398 "result": true 9399} 9400~~~ 9401 9402### vfu_virtio_create_scsi_endpoint {#rpc_vfu_virtio_create_scsi_endpoint} 9403 9404Create vfio-user virtio-scsi PCI endpoint. 9405 9406#### Parameters 9407 9408Name | Optional | Type | Description 9409----------------------- | -------- | ----------- | ----------- 9410name | Required | string | Endpoint name 9411cpumask | Optional | string | CPU masks 9412num_io_queues | Optional | number | Number of IO queues 9413qsize | Optional | number | Queue size 9414packed_ring | Optional | boolean | Enable packed ring 9415 9416#### Example 9417 9418Example request: 9419 9420~~~json 9421{ 9422 "params": { 9423 "name": "vfu.0", 9424 "cpumask": "0x2", 9425 "num_io_queues": 4, 9426 "qsize": 256 9427 }, 9428 "jsonrpc": "2.0", 9429 "method": "vfu_virtio_create_scsi_endpoint", 9430 "id": 1 9431} 9432~~~ 9433 9434Example response: 9435 9436~~~json 9437{ 9438 "jsonrpc": "2.0", 9439 "id": 1, 9440 "result": true 9441} 9442~~~ 9443 9444## Vhost Target {#jsonrpc_components_vhost_tgt} 9445 9446The following common preconditions need to be met in all target types. 9447 9448Controller name will be used to create UNIX domain socket. This implies that name concatenated with vhost socket 9449directory path needs to be valid UNIX socket name. 9450 9451@ref cpu_mask parameter is used to choose CPU on which pollers will be launched when new initiator is connecting. 9452It must be a subset of application CPU mask. Default value is CPU mask of the application. 9453 9454### vhost_controller_set_coalescing {#rpc_vhost_controller_set_coalescing} 9455 9456Controls interrupt coalescing for specific target. Because `delay_base_us` is used to calculate delay in CPU ticks 9457there is no hardcoded limit for this parameter. Only limitation is that final delay in CPU ticks might not overflow 945832 bit unsigned integer (which is more than 1s @ 4GHz CPU). In real scenarios `delay_base_us` should be much lower 9459than 150us. To disable coalescing set `delay_base_us` to 0. 9460 9461#### Parameters 9462 9463Name | Optional | Type | Description 9464----------------------- | -------- | ----------- | ----------- 9465ctrlr | Required | string | Controller name 9466delay_base_us | Required | number | Base (minimum) coalescing time in microseconds 9467iops_threshold | Required | number | Coalescing activation level greater than 0 in IO per second 9468 9469#### Example 9470 9471Example request: 9472 9473~~~json 9474{ 9475 "params": { 9476 "iops_threshold": 100000, 9477 "ctrlr": "VhostScsi0", 9478 "delay_base_us": 80 9479 }, 9480 "jsonrpc": "2.0", 9481 "method": "vhost_controller_set_coalescing", 9482 "id": 1 9483} 9484~~~ 9485 9486Example response: 9487 9488~~~json 9489{ 9490 "jsonrpc": "2.0", 9491 "id": 1, 9492 "result": true 9493} 9494~~~ 9495 9496### vhost_create_scsi_controller {#rpc_vhost_create_scsi_controller} 9497 9498Construct vhost SCSI target. 9499 9500#### Parameters 9501 9502Name | Optional | Type | Description 9503----------------------- | -------- | ----------- | ----------- 9504ctrlr | Required | string | Controller name 9505cpumask | Optional | string | @ref cpu_mask for this controller 9506delay | Optional | boolean | If true, delay the controller startup. 9507 9508#### Example 9509 9510Example request: 9511 9512~~~json 9513{ 9514 "params": { 9515 "cpumask": "0x2", 9516 "ctrlr": "VhostScsi0", 9517 "delay": true 9518 }, 9519 "jsonrpc": "2.0", 9520 "method": "vhost_create_scsi_controller", 9521 "id": 1 9522} 9523~~~ 9524 9525Example response: 9526 9527~~~json 9528{ 9529 "jsonrpc": "2.0", 9530 "id": 1, 9531 "result": true 9532} 9533~~~ 9534 9535### vhost_start_scsi_controller {#rpc_vhost_start_scsi_controller} 9536 9537Start vhost SCSI controller, if controller is already started, do nothing. 9538 9539#### Parameters 9540 9541Name | Optional | Type | Description 9542----------------------- | -------- | ----------- | ----------- 9543ctrlr | Required | string | Controller name 9544 9545#### Example 9546 9547Example request: 9548 9549~~~json 9550{ 9551 "params": { 9552 "ctrlr": "VhostScsi0", 9553 }, 9554 "jsonrpc": "2.0", 9555 "method": "vhost_start_scsi_controller", 9556 "id": 1 9557} 9558~~~ 9559 9560Example response: 9561 9562~~~json 9563response: 9564{ 9565 "jsonrpc": "2.0", 9566 "id": 1, 9567 "result": true 9568} 9569~~~ 9570 9571### vhost_scsi_controller_add_target {#rpc_vhost_scsi_controller_add_target} 9572 9573In vhost target `ctrlr` create SCSI target with ID `scsi_target_num` and add `bdev_name` as LUN 0. 9574 9575#### Parameters 9576 9577Name | Optional | Type | Description 9578----------------------- | -------- | ----------- | ----------- 9579ctrlr | Required | string | Controller name 9580scsi_target_num | Required | number | SCSI target ID between 0 and 7 or -1 to use first free ID. 9581bdev_name | Required | string | Name of bdev to expose as a LUN 0 9582 9583#### Response 9584 9585SCSI target ID. 9586 9587#### Example 9588 9589Example request: 9590 9591~~~json 9592{ 9593 "params": { 9594 "scsi_target_num": 1, 9595 "bdev_name": "Malloc0", 9596 "ctrlr": "VhostScsi0" 9597 }, 9598 "jsonrpc": "2.0", 9599 "method": "vhost_scsi_controller_add_target", 9600 "id": 1 9601} 9602~~~ 9603 9604Example response: 9605 9606~~~json 9607response: 9608{ 9609 "jsonrpc": "2.0", 9610 "id": 1, 9611 "result": 1 9612} 9613~~~ 9614 9615### vhost_scsi_controller_remove_target {#rpc_vhost_scsi_controller_remove_target} 9616 9617Remove SCSI target ID `scsi_target_num` from vhost target `scsi_target_num`. 9618 9619This method will fail if initiator is connected, but doesn't support hot-remove (the `VIRTIO_SCSI_F_HOTPLUG` is not negotiated). 9620 9621#### Parameters 9622 9623Name | Optional | Type | Description 9624----------------------- | -------- | ----------- | ----------- 9625ctrlr | Required | string | Controller name 9626scsi_target_num | Required | number | SCSI target ID between 0 and 7 9627 9628#### Example 9629 9630Example request: 9631 9632~~~json 9633request: 9634{ 9635 "params": { 9636 "scsi_target_num": 1, 9637 "ctrlr": "VhostScsi0" 9638 }, 9639 "jsonrpc": "2.0", 9640 "method": "vhost_scsi_controller_remove_target", 9641 "id": 1 9642} 9643~~~ 9644 9645Example response: 9646 9647~~~json 9648{ 9649 "jsonrpc": "2.0", 9650 "id": 1, 9651 "result": true 9652} 9653~~~ 9654 9655### virtio_blk_create_transport {#rpc_virtio_blk_create_transport} 9656 9657Create virtio blk transport. 9658 9659#### Parameters 9660 9661Name | Optional | Type | Description 9662----------------------- | -------- | ----------- | ----------- 9663name | Required | string | Transport name 9664 9665#### Example 9666 9667Example request: 9668 9669~~~json 9670{ 9671 "params": { 9672 "name": "vhost_user_blk" 9673 }, 9674 "jsonrpc": "2.0", 9675 "method": "virtio_blk_create_transport", 9676 "id": 1 9677} 9678~~~ 9679 9680Example response: 9681 9682~~~json 9683{ 9684 "jsonrpc": "2.0", 9685 "id": 1, 9686 "result": true 9687} 9688~~~ 9689 9690### virtio_blk_get_transports {#rpc_virtio_blk_get_transports} 9691 9692#### Parameters 9693 9694The user may specify no parameters in order to list all transports, 9695or a transport name may be specified. 9696 9697Name | Optional | Type | Description 9698--------------------------- | -------- | ------------| ----------- 9699name | Optional | string | Transport name. 9700 9701#### Example 9702 9703Example request: 9704 9705~~~json 9706{ 9707 "jsonrpc": "2.0", 9708 "method": "virtio_blk_get_transports", 9709 "id": 1 9710} 9711~~~ 9712 9713Example response: 9714 9715~~~json 9716{ 9717 "jsonrpc": "2.0", 9718 "id": 1, 9719 "result": [ 9720 { 9721 "name": "vhost_user_blk" 9722 } 9723 ] 9724} 9725~~~ 9726 9727### vhost_create_blk_controller {#rpc_vhost_create_blk_controller} 9728 9729Create vhost block controller 9730 9731If `readonly` is `true` then vhost block target will be created as read only and fail any write requests. 9732The `VIRTIO_BLK_F_RO` feature flag will be offered to the initiator. 9733 9734#### Parameters 9735 9736Name | Optional | Type | Description 9737----------------------- | -------- | ----------- | ----------- 9738ctrlr | Required | string | Controller name 9739bdev_name | Required | string | Name of bdev to expose block device 9740readonly | Optional | boolean | If true, this target will be read only (default: false) 9741cpumask | Optional | string | @ref cpu_mask for this controller 9742transport | Optional | string | virtio blk transport name (default: vhost_user_blk) 9743 9744#### Example 9745 9746Example request: 9747 9748~~~json 9749{ 9750 "params": { 9751 "dev_name": "Malloc0", 9752 "ctrlr": "VhostBlk0" 9753 }, 9754 "jsonrpc": "2.0", 9755 "method": "vhost_create_blk_controller", 9756 "id": 1 9757} 9758~~~ 9759 9760Example response: 9761 9762~~~json 9763{ 9764 "jsonrpc": "2.0", 9765 "id": 1, 9766 "result": true 9767} 9768~~~ 9769 9770### vhost_get_controllers {#rpc_vhost_get_controllers} 9771 9772Display information about all or specific vhost controller(s). 9773 9774#### Parameters 9775 9776The user may specify no parameters in order to list all controllers, or a controller may be 9777specified by name. 9778 9779Name | Optional | Type | Description 9780----------------------- | -------- | ----------- | ----------- 9781name | Optional | string | Vhost controller name 9782 9783#### Response {#rpc_vhost_get_controllers_response} 9784 9785Response is an array of objects describing requested controller(s). Common fields are: 9786 9787Name | Type | Description 9788----------------------- | ----------- | ----------- 9789ctrlr | string | Controller name 9790cpumask | string | @ref cpu_mask of this controller 9791delay_base_us | number | Base (minimum) coalescing time in microseconds (0 if disabled) 9792iops_threshold | number | Coalescing activation level 9793backend_specific | object | Backend specific information 9794 9795### Vhost block {#rpc_vhost_get_controllers_blk} 9796 9797`backend_specific` contains one `block` object of type: 9798 9799Name | Type | Description 9800----------------------- | ----------- | ----------- 9801bdev | string | Backing bdev name or Null if bdev is hot-removed 9802readonly | boolean | True if controllers is readonly, false otherwise 9803 9804### Vhost SCSI {#rpc_vhost_get_controllers_scsi} 9805 9806`backend_specific` contains `scsi` array of following objects: 9807 9808Name | Type | Description 9809----------------------- | ----------- | ----------- 9810target_name | string | Name of this SCSI target 9811id | number | Unique SPDK global SCSI target ID 9812scsi_dev_num | number | SCSI target ID initiator will see when scanning this controller 9813luns | array | array of objects describing @ref rpc_vhost_get_controllers_scsi_luns 9814 9815### Vhost SCSI LUN {#rpc_vhost_get_controllers_scsi_luns} 9816 9817Object of type: 9818 9819Name | Type | Description 9820----------------------- | ----------- | ----------- 9821id | number | SCSI LUN ID 9822bdev_name | string | Backing bdev name 9823 9824### Vhost NVMe {#rpc_vhost_get_controllers_nvme} 9825 9826`backend_specific` contains `namespaces` array of following objects: 9827 9828Name | Type | Description 9829----------------------- | ----------- | ----------- 9830nsid | number | Namespace ID 9831bdev | string | Backing bdev name 9832 9833#### Example 9834 9835Example request: 9836 9837~~~json 9838{ 9839 "jsonrpc": "2.0", 9840 "method": "vhost_get_controllers", 9841 "id": 1 9842} 9843~~~ 9844 9845Example response: 9846 9847~~~json 9848{ 9849 "jsonrpc": "2.0", 9850 "id": 1, 9851 "result": [ 9852 { 9853 "cpumask": "0x2", 9854 "backend_specific": { 9855 "block": { 9856 "readonly": false, 9857 "bdev": "Malloc0" 9858 } 9859 }, 9860 "iops_threshold": 60000, 9861 "ctrlr": "VhostBlk0", 9862 "delay_base_us": 100 9863 }, 9864 { 9865 "cpumask": "0x2", 9866 "backend_specific": { 9867 "scsi": [ 9868 { 9869 "target_name": "Target 2", 9870 "luns": [ 9871 { 9872 "id": 0, 9873 "bdev_name": "Malloc1" 9874 } 9875 ], 9876 "id": 0, 9877 "scsi_dev_num": 2 9878 }, 9879 { 9880 "target_name": "Target 5", 9881 "luns": [ 9882 { 9883 "id": 0, 9884 "bdev_name": "Malloc2" 9885 } 9886 ], 9887 "id": 1, 9888 "scsi_dev_num": 5 9889 } 9890 ] 9891 }, 9892 "iops_threshold": 60000, 9893 "ctrlr": "VhostScsi0", 9894 "delay_base_us": 0 9895 }, 9896 { 9897 "cpumask": "0x2", 9898 "backend_specific": { 9899 "namespaces": [ 9900 { 9901 "bdev": "Malloc3", 9902 "nsid": 1 9903 }, 9904 { 9905 "bdev": "Malloc4", 9906 "nsid": 2 9907 } 9908 ] 9909 }, 9910 "iops_threshold": 60000, 9911 "ctrlr": "VhostNvme0", 9912 "delay_base_us": 0 9913 } 9914 ] 9915} 9916~~~ 9917 9918### vhost_delete_controller {#rpc_vhost_delete_controller} 9919 9920Remove vhost target. 9921 9922This call will fail if there is an initiator connected or there is at least one SCSI target configured in case of 9923vhost SCSI target. In the later case please remove all SCSI targets first using @ref rpc_vhost_scsi_controller_remove_target. 9924 9925#### Parameters 9926 9927Name | Optional | Type | Description 9928----------------------- | -------- | ----------- | ----------- 9929ctrlr | Required | string | Controller name 9930 9931#### Example 9932 9933Example request: 9934 9935~~~json 9936{ 9937 "params": { 9938 "ctrlr": "VhostNvme0" 9939 }, 9940 "jsonrpc": "2.0", 9941 "method": "vhost_delete_controller", 9942 "id": 1 9943} 9944~~~ 9945 9946Example response: 9947 9948~~~json 9949{ 9950 "jsonrpc": "2.0", 9951 "id": 1, 9952 "result": true 9953} 9954~~~ 9955 9956## Logical Volume {#jsonrpc_components_lvol} 9957 9958Identification of logical volume store and logical volume is explained first. 9959 9960A logical volume store has a UUID and a name for its identification. 9961The UUID is generated on creation and it can be used as a unique identifier. 9962The name is specified on creation and can be renamed. 9963Either UUID or name is used to access logical volume store in RPCs. 9964 9965A logical volume has a UUID and a name for its identification. 9966The UUID of the logical volume is generated on creation and it can be unique identifier. 9967The alias of the logical volume takes the format _lvs_name/lvol_name_ where: 9968 9969* _lvs_name_ is the name of the logical volume store. 9970* _lvol_name_ is specified on creation and can be renamed. 9971 9972### bdev_lvol_create_lvstore {#rpc_bdev_lvol_create_lvstore} 9973 9974Construct a logical volume store. 9975 9976#### Parameters 9977 9978Name | Optional | Type | Description 9979----------------------------- | -------- | ----------- | ----------- 9980bdev_name | Required | string | Bdev on which to construct logical volume store 9981lvs_name | Required | string | Name of the logical volume store to create 9982cluster_sz | Optional | number | Cluster size of the logical volume store in bytes (Default: 4MiB) 9983clear_method | Optional | string | Change clear method for data region. Available: none, unmap (default), write_zeroes 9984num_md_pages_per_cluster_ratio| Optional | number | Reserved metadata pages per cluster (Default: 100) 9985 9986The num_md_pages_per_cluster_ratio defines the amount of metadata to 9987allocate when the logical volume store is created. The default value 9988is '100', which translates to 1 4KiB per cluster. For the default 4MiB 9989cluster size, this equates to about 0.1% of the underlying block 9990device allocated for metadata. Logical volume stores can be grown, if 9991the size of the underlying block device grows in the future, but only 9992if enough metadata pages were allocated to support the growth. So 9993num_md_pages_per_cluster_ratio should be set to a higher value if 9994wanting to support future growth. For example, 9995num_md_pages_per_cluster_ratio = 200 would support future 2x growth of 9996the logical volume store, and would result in 0.2% of the underlying 9997block device allocated for metadata (with a default 4MiB cluster 9998size). 9999 10000#### Response 10001 10002UUID of the created logical volume store is returned. 10003 10004#### Example 10005 10006Example request: 10007 10008~~~json 10009{ 10010 "jsonrpc": "2.0", 10011 "id": 1, 10012 "method": "bdev_lvol_create_lvstore", 10013 "params": { 10014 "lvs_name": "LVS0", 10015 "bdev_name": "Malloc0" 10016 "clear_method": "write_zeroes" 10017 } 10018} 10019~~~ 10020 10021Example response: 10022 10023~~~json 10024{ 10025 "jsonrpc": "2.0", 10026 "id": 1, 10027 "result": "a9959197-b5e2-4f2d-8095-251ffb6985a5" 10028} 10029~~~ 10030 10031### bdev_lvol_delete_lvstore {#rpc_bdev_lvol_delete_lvstore} 10032 10033Destroy a logical volume store. 10034 10035#### Parameters 10036 10037Name | Optional | Type | Description 10038----------------------- | -------- | ----------- | ----------- 10039uuid | Optional | string | UUID of the logical volume store to destroy 10040lvs_name | Optional | string | Name of the logical volume store to destroy 10041 10042Either uuid or lvs_name must be specified, but not both. 10043 10044#### Example 10045 10046Example request: 10047 10048~~~json 10049{ 10050 "jsonrpc": "2.0", 10051 "method": "bdev_lvol_delete_lvstore", 10052 "id": 1 10053 "params": { 10054 "uuid": "a9959197-b5e2-4f2d-8095-251ffb6985a5" 10055 } 10056} 10057~~~ 10058 10059Example response: 10060 10061~~~json 10062{ 10063 "jsonrpc": "2.0", 10064 "id": 1, 10065 "result": true 10066} 10067~~~ 10068 10069### bdev_lvol_get_lvstores {#rpc_bdev_lvol_get_lvstores} 10070 10071Get a list of logical volume stores. 10072 10073#### Parameters 10074 10075Name | Optional | Type | Description 10076----------------------- | -------- | ----------- | ----------- 10077uuid | Optional | string | UUID of the logical volume store to retrieve information about 10078lvs_name | Optional | string | Name of the logical volume store to retrieve information about 10079 10080Either uuid or lvs_name may be specified, but not both. 10081If both uuid and lvs_name are omitted, information about all logical volume stores is returned. 10082 10083#### Example 10084 10085Example request: 10086 10087~~~json 10088{ 10089 "jsonrpc": "2.0", 10090 "method": "bdev_lvol_get_lvstores", 10091 "id": 1, 10092 "params": { 10093 "lvs_name": "LVS0" 10094 } 10095} 10096~~~ 10097 10098Example response: 10099 10100~~~json 10101{ 10102 "jsonrpc": "2.0", 10103 "id": 1, 10104 "result": [ 10105 { 10106 "uuid": "a9959197-b5e2-4f2d-8095-251ffb6985a5", 10107 "base_bdev": "Malloc0", 10108 "free_clusters": 31, 10109 "cluster_size": 4194304, 10110 "total_data_clusters": 31, 10111 "block_size": 4096, 10112 "name": "LVS0" 10113 } 10114 ] 10115} 10116~~~ 10117 10118### bdev_lvol_rename_lvstore {#rpc_bdev_lvol_rename_lvstore} 10119 10120Rename a logical volume store. 10121 10122#### Parameters 10123 10124Name | Optional | Type | Description 10125----------------------- | -------- | ----------- | ----------- 10126old_name | Required | string | Existing logical volume store name 10127new_name | Required | string | New logical volume store name 10128 10129#### Example 10130 10131Example request: 10132 10133~~~json 10134{ 10135 "jsonrpc": "2.0", 10136 "method": "bdev_lvol_rename_lvstore", 10137 "id": 1, 10138 "params": { 10139 "old_name": "LVS0", 10140 "new_name": "LVS2" 10141 } 10142} 10143~~~ 10144 10145Example response: 10146 10147~~~json 10148{ 10149 "jsonrpc": "2.0", 10150 "id": 1, 10151 "result": true 10152} 10153~~~ 10154 10155### bdev_lvol_grow_lvstore {#rpc_bdev_lvol_grow_lvstore} 10156 10157Grow the logical volume store to fill the underlying bdev 10158 10159#### Parameters 10160 10161Name | Optional | Type | Description 10162----------------------- | -------- | ----------- | ----------- 10163uuid | Optional | string | UUID of the logical volume store to grow 10164lvs_name | Optional | string | Name of the logical volume store to grow 10165 10166Either uuid or lvs_name must be specified, but not both. 10167 10168#### Example 10169 10170Example request: 10171 10172~~~json 10173{ 10174 "jsonrpc": "2.0", 10175 "method": "bdev_lvol_grow_lvstore", 10176 "id": 1 10177 "params": { 10178 "uuid": "a9959197-b5e2-4f2d-8095-251ffb6985a5" 10179 } 10180} 10181~~~ 10182 10183Example response: 10184 10185~~~json 10186{ 10187 "jsonrpc": "2.0", 10188 "id": 1, 10189 "result": true 10190} 10191~~~ 10192 10193### bdev_lvol_create {#rpc_bdev_lvol_create} 10194 10195Create a logical volume on a logical volume store. 10196 10197#### Parameters 10198 10199Name | Optional | Type | Description 10200----------------------- | -------- | ----------- | ----------- 10201lvol_name | Required | string | Name of logical volume to create 10202size_in_mib | Required | number | Desired size of logical volume in MiB 10203thin_provision | Optional | boolean | True to enable thin provisioning 10204uuid | Optional | string | UUID of logical volume store to create logical volume on 10205lvs_name | Optional | string | Name of logical volume store to create logical volume on 10206clear_method | Optional | string | Change default data clusters clear method. Available: none, unmap, write_zeroes 10207 10208Size will be rounded up to a multiple of cluster size. Either uuid or lvs_name must be specified, but not both. 10209lvol_name will be used in the alias of the created logical volume. 10210 10211#### Response 10212 10213UUID of the created logical volume is returned. 10214 10215#### Example 10216 10217Example request: 10218 10219~~~json 10220{ 10221 "jsonrpc": "2.0", 10222 "method": "bdev_lvol_create", 10223 "id": 1, 10224 "params": { 10225 "lvol_name": "LVOL0", 10226 "size_in_mib": 1, 10227 "lvs_name": "LVS0", 10228 "clear_method": "unmap", 10229 "thin_provision": true 10230 } 10231} 10232~~~ 10233 10234Example response: 10235 10236~~~json 10237{ 10238 "jsonrpc": "2.0", 10239 "id": 1, 10240 "result": "1b38702c-7f0c-411e-a962-92c6a5a8a602" 10241} 10242~~~ 10243 10244### bdev_lvol_snapshot {#rpc_bdev_lvol_snapshot} 10245 10246Capture a snapshot of the current state of a logical volume. 10247 10248#### Parameters 10249 10250Name | Optional | Type | Description 10251----------------------- | -------- | ----------- | ----------- 10252lvol_name | Required | string | UUID or alias of the logical volume to create a snapshot from 10253snapshot_name | Required | string | Name for the newly created snapshot 10254 10255#### Response 10256 10257UUID of the created logical volume snapshot is returned. 10258 10259#### Example 10260 10261Example request: 10262 10263~~~json 10264{ 10265 "jsonrpc": "2.0", 10266 "method": "bdev_lvol_snapshot", 10267 "id": 1, 10268 "params": { 10269 "lvol_name": "1b38702c-7f0c-411e-a962-92c6a5a8a602", 10270 "snapshot_name": "SNAP1" 10271 } 10272} 10273~~~ 10274 10275Example response: 10276 10277~~~json 10278{ 10279 "jsonrpc": "2.0", 10280 "id": 1, 10281 "result": "cc8d7fdf-7865-4d1f-9fc6-35da8e368670" 10282} 10283~~~ 10284 10285### bdev_lvol_clone {#rpc_bdev_lvol_clone} 10286 10287Create a logical volume based on a snapshot. 10288 10289#### Parameters 10290 10291Name | Optional | Type | Description 10292----------------------- | -------- | ----------- | ----------- 10293snapshot_name | Required | string | UUID or alias of the snapshot to clone 10294clone_name | Required | string | Name for the logical volume to create 10295 10296#### Response 10297 10298UUID of the created logical volume clone is returned. 10299 10300#### Example 10301 10302Example request: 10303 10304~~~json 10305{ 10306 "jsonrpc": "2.0" 10307 "method": "bdev_lvol_clone", 10308 "id": 1, 10309 "params": { 10310 "snapshot_name": "cc8d7fdf-7865-4d1f-9fc6-35da8e368670", 10311 "clone_name": "CLONE1" 10312 } 10313} 10314~~~ 10315 10316Example response: 10317 10318~~~json 10319{ 10320 "jsonrpc": "2.0", 10321 "id": 1, 10322 "result": "8d87fccc-c278-49f0-9d4c-6237951aca09" 10323} 10324~~~ 10325 10326### bdev_lvol_clone_bdev {#rpc_bdev_lvol_clone_bdev} 10327 10328Create a logical volume based on an external snapshot bdev. The external snapshot bdev 10329is a bdev that will not be written to by any consumer and must not be an lvol in the 10330lvstore as the clone. 10331 10332Regardless of whether the bdev is specified by name or UUID, the bdev UUID will be stored 10333in the logical volume's metadata for use while the lvolstore is loading. For this reason, 10334it is important that the bdev chosen has a static UUID. 10335 10336#### Parameters 10337 10338Name | Optional | Type | Description 10339----------------------- | -------- | ----------- | ----------- 10340bdev | Required | string | Name or UUID for bdev that acts as the external snapshot 10341lvs_name | Required | string | logical volume store name 10342clone_name | Required | string | Name for the logical volume to create 10343 10344#### Response 10345 10346UUID of the created logical volume clone is returned. 10347 10348#### Example 10349 10350Example request: 10351 10352~~~json 10353{ 10354 "jsonrpc": "2.0", 10355 "method": "bdev_lvol_clone_bdev", 10356 "id": 1, 10357 "params": { 10358 "bdev_uuid": "e4b40d8b-f623-416d-8234-baf5a4c83cbd", 10359 "lvs_name": "lvs1", 10360 "clone_name": "clone2" 10361 } 10362} 10363~~~ 10364 10365Example response: 10366 10367~~~json 10368{ 10369 "jsonrpc": "2.0", 10370 "id": 1, 10371 "result": "336f662b-08e5-4006-8e06-e2023f7f9886" 10372} 10373~~~ 10374 10375### bdev_lvol_rename {#rpc_bdev_lvol_rename} 10376 10377Rename a logical volume. New name will rename only the alias of the logical volume. 10378 10379#### Parameters 10380 10381Name | Optional | Type | Description 10382----------------------- | -------- | ----------- | ----------- 10383old_name | Required | string | UUID or alias of the existing logical volume 10384new_name | Required | string | New logical volume name 10385 10386#### Example 10387 10388Example request: 10389 10390~~~json 10391{ 10392 "jsonrpc": "2.0", 10393 "method": "bdev_lvol_rename", 10394 "id": 1, 10395 "params": { 10396 "old_name": "067df606-6dbc-4143-a499-0d05855cb3b8", 10397 "new_name": "LVOL2" 10398 } 10399} 10400~~~ 10401 10402Example response: 10403 10404~~~json 10405{ 10406 "jsonrpc": "2.0", 10407 "id": 1, 10408 "result": true 10409} 10410~~~ 10411 10412### bdev_lvol_resize {#rpc_bdev_lvol_resize} 10413 10414Resize a logical volume. 10415 10416#### Parameters 10417 10418Name | Optional | Type | Description 10419----------------------- | -------- | ----------- | ----------- 10420name | Required | string | UUID or alias of the logical volume to resize 10421size_in_mib | Required | number | Desired size of the logical volume in MiB 10422 10423#### Example 10424 10425Example request: 10426 10427~~~json 10428{ 10429 "jsonrpc": "2.0", 10430 "method": "bdev_lvol_resize", 10431 "id": 1, 10432 "params": { 10433 "name": "51638754-ca16-43a7-9f8f-294a0805ab0a", 10434 "size_in_mib": 2 10435 } 10436} 10437~~~ 10438 10439Example response: 10440 10441~~~json 10442{ 10443 "jsonrpc": "2.0", 10444 "id": 1, 10445 "result": true 10446} 10447~~~ 10448 10449### bdev_lvol_set_read_only{#rpc_bdev_lvol_set_read_only} 10450 10451Mark logical volume as read only. 10452 10453#### Parameters 10454 10455Name | Optional | Type | Description 10456----------------------- | -------- | ----------- | ----------- 10457name | Required | string | UUID or alias of the logical volume to set as read only 10458 10459#### Example 10460 10461Example request: 10462 10463~~~json 10464{ 10465 "jsonrpc": "2.0", 10466 "method": "bdev_lvol_set_read_only", 10467 "id": 1, 10468 "params": { 10469 "name": "51638754-ca16-43a7-9f8f-294a0805ab0a", 10470 } 10471} 10472~~~ 10473 10474Example response: 10475 10476~~~json 10477{ 10478 "jsonrpc": "2.0", 10479 "id": 1, 10480 "result": true 10481} 10482~~~ 10483 10484### bdev_lvol_delete {#rpc_bdev_lvol_delete} 10485 10486Destroy a logical volume. 10487 10488#### Parameters 10489 10490Name | Optional | Type | Description 10491----------------------- | -------- | ----------- | ----------- 10492name | Required | string | UUID or alias of the logical volume to destroy 10493 10494#### Example 10495 10496Example request: 10497 10498~~~json 10499{ 10500 "jsonrpc": "2.0", 10501 "method": "bdev_lvol_delete", 10502 "id": 1, 10503 "params": { 10504 "name": "51638754-ca16-43a7-9f8f-294a0805ab0a" 10505 } 10506} 10507~~~ 10508 10509Example response: 10510 10511~~~json 10512{ 10513 "jsonrpc": "2.0", 10514 "id": 1, 10515 "result": true 10516} 10517~~~ 10518 10519### bdev_lvol_inflate {#rpc_bdev_lvol_inflate} 10520 10521Inflate a logical volume. All unallocated clusters are allocated and copied from the parent or zero filled 10522if not allocated in the parent. Then all dependencies on the parent are removed. 10523 10524### Parameters 10525 10526Name | Optional | Type | Description 10527----------------------- | -------- | ----------- | ----------- 10528name | Required | string | UUID or alias of the logical volume to inflate 10529 10530#### Example 10531 10532Example request: 10533 10534~~~json 10535{ 10536 "jsonrpc": "2.0", 10537 "method": "bdev_lvol_inflate", 10538 "id": 1, 10539 "params": { 10540 "name": "8d87fccc-c278-49f0-9d4c-6237951aca09" 10541 } 10542} 10543~~~ 10544 10545Example response: 10546 10547~~~json 10548{ 10549 "jsonrpc": "2.0", 10550 "id": 1, 10551 "result": true 10552} 10553~~~ 10554 10555### bdev_lvol_decouple_parent {#rpc_bdev_lvol_decouple_parent} 10556 10557Decouple the parent of a logical volume. For unallocated clusters which is allocated in the parent, they are 10558allocated and copied from the parent, but for unallocated clusters which is thin provisioned in the parent, 10559they are kept thin provisioned. Then all dependencies on the parent are removed. 10560 10561#### Parameters 10562 10563Name | Optional | Type | Description 10564----------------------- | -------- | ----------- | ----------- 10565name | Required | string | UUID or alias of the logical volume to decouple the parent of it 10566 10567#### Example 10568 10569Example request: 10570 10571~~~json 10572{ 10573 "jsonrpc": "2.0", 10574 "method": "bdev_lvol_decouple_parent", 10575 "id": 1. 10576 "params": { 10577 "name": "8d87fccc-c278-49f0-9d4c-6237951aca09" 10578 } 10579} 10580~~~ 10581 10582Example response: 10583 10584~~~json 10585{ 10586 "jsonrpc": "2.0", 10587 "id": 1, 10588 "result": true 10589} 10590~~~ 10591 10592### bdev_lvol_get_lvols {#rpc_bdev_lvol_get_lvols} 10593 10594Get a list of logical volumes. This list can be limited by lvol store and will display volumes even if 10595they are degraded. Degraded lvols do not have an associated bdev, thus this RPC call may return lvols 10596not returned by `bdev_get_bdevs`. 10597 10598#### Parameters 10599 10600Name | Optional | Type | Description 10601----------------------- | -------- | ----------- | ----------- 10602lvs_uuid | Optional | string | Only show volumes in the logical volume store with this UUID 10603lvs_name | Optional | string | Only show volumes in the logical volume store with this name 10604 10605Either lvs_uuid or lvs_name may be specified, but not both. 10606If both lvs_uuid and lvs_name are omitted, information about lvols in all logical volume stores is returned. 10607 10608#### Example 10609 10610Example request: 10611 10612~~~json 10613{ 10614 "jsonrpc": "2.0", 10615 "method": "bdev_lvol_get_lvols", 10616 "id": 1, 10617 "params": { 10618 "lvs_name": "lvs_test" 10619 } 10620} 10621~~~ 10622 10623Example response: 10624 10625~~~json 10626[ 10627 { 10628 "alias": "lvs_test/lvol1", 10629 "uuid": "b335c368-851d-4099-81e0-018cc494fdf6", 10630 "name": "lvol1", 10631 "is_thin_provisioned": false, 10632 "is_snapshot": false, 10633 "is_clone": false, 10634 "is_esnap_clone": false, 10635 "is_degraded": false, 10636 "lvs": { 10637 "name": "lvs_test", 10638 "uuid": "a1c8d950-5715-4558-936d-ab9e6eca0794" 10639 } 10640 } 10641] 10642~~~ 10643 10644## RAID 10645 10646### bdev_raid_set_options {#rpc_bdev_raid_set_options} 10647 10648Set options for bdev raid. 10649 10650This RPC can be called at any time, but the new value will only take effect for new raid bdevs. 10651 10652The `process_window_size_kb` parameter defines the size of the "window" (LBA range of the raid bdev) 10653in which a background process like rebuild performs its work. Any positive value is valid, but the value 10654actually used by a raid bdev can be adjusted to the size of the raid bdev or the write unit size. 10655 10656#### Parameters 10657 10658Name | Optional | Type | Description 10659-------------------------- | -------- | ----------- | ----------- 10660process_window_size_kb | Optional | number | Background process (e.g. rebuild) window size in KiB 10661 10662#### Example 10663 10664Example request: 10665 10666~~~json 10667request: 10668{ 10669 "jsonrpc": "2.0", 10670 "method": "bdev_raid_set_options", 10671 "id": 1, 10672 "params": { 10673 "process_window_size_kb": 512 10674 } 10675} 10676~~~ 10677 10678Example response: 10679 10680~~~json 10681{ 10682 "jsonrpc": "2.0", 10683 "id": 1, 10684 "result": true 10685} 10686~~~ 10687 10688### bdev_raid_get_bdevs {#rpc_bdev_raid_get_bdevs} 10689 10690This is used to list all the raid bdev details based on the input category requested. Category should be one 10691of 'all', 'online', 'configuring' or 'offline'. 'all' means all the raid bdevs whether they are online or 10692configuring or offline. 'online' is the raid bdev which is registered with bdev layer. 'configuring' is 10693the raid bdev which does not have full configuration discovered yet. 'offline' is the raid bdev which is 10694not registered with bdev as of now and it has encountered any error or user has requested to offline 10695the raid bdev. 10696 10697#### Parameters 10698 10699Name | Optional | Type | Description 10700----------------------- | -------- | ----------- | ----------- 10701category | Required | string | all or online or configuring or offline 10702 10703#### Example 10704 10705Example request: 10706 10707~~~json 10708{ 10709 "jsonrpc": "2.0", 10710 "method": "bdev_raid_get_bdevs", 10711 "id": 1, 10712 "params": { 10713 "category": "all" 10714 } 10715} 10716~~~ 10717 10718Example response: 10719 10720~~~json 10721{ 10722 "jsonrpc": "2.0", 10723 "id": 1, 10724 "result": [ 10725 { 10726 "name": "RaidBdev0", 10727 "uuid": "7d352e83-fe27-40f2-8fef-64563355e076", 10728 "strip_size_kb": 128, 10729 "state": "online", 10730 "raid_level": "raid0", 10731 "num_base_bdevs": 2, 10732 "num_base_bdevs_discovered": 2, 10733 "num_base_bdevs_operational": 2, 10734 "base_bdevs_list": [ 10735 { 10736 "name": "malloc0", 10737 "uuid": "d2788884-5b3e-4fd7-87ff-6c78177e14ab", 10738 "is_configured": true, 10739 "data_offset": 256, 10740 "data_size": 261888 10741 }, 10742 { 10743 "name": "malloc1", 10744 "uuid": "a81bb1f8-5865-488a-8758-10152017e7d1", 10745 "is_configured": true, 10746 "data_offset": 256, 10747 "data_size": 261888 10748 } 10749 ] 10750 }, 10751 { 10752 "name": "RaidBdev1", 10753 "uuid": "f7cb71ed-2d0e-4240-979e-27b0b7735f36", 10754 "strip_size_kb": 128, 10755 "state": "configuring", 10756 "raid_level": "raid0", 10757 "num_base_bdevs": 2, 10758 "num_base_bdevs_discovered": 1, 10759 "num_base_bdevs_operational": 2, 10760 "base_bdevs_list": [ 10761 { 10762 "name": "malloc2", 10763 "uuid": "f60c20e1-3439-4f89-ae55-965a70333f86", 10764 "is_configured": true, 10765 "data_offset": 256, 10766 "data_size": 261888 10767 } 10768 { 10769 "name": "malloc3", 10770 "uuid": "00000000-0000-0000-0000-000000000000", 10771 "is_configured": false, 10772 "data_offset": 0, 10773 "data_size": 0 10774 } 10775 ] 10776 } 10777 ] 10778} 10779~~~ 10780 10781### bdev_raid_create {#rpc_bdev_raid_create} 10782 10783Constructs new RAID bdev. 10784 10785#### Parameters 10786 10787Name | Optional | Type | Description 10788----------------------- | -------- | ----------- | ----------- 10789name | Required | string | RAID bdev name 10790strip_size_kb | Required | number | Strip size in KB 10791raid_level | Required | string | RAID level 10792base_bdevs | Required | string | Base bdevs name, whitespace separated list in quotes 10793uuid | Optional | string | UUID for this RAID bdev 10794superblock | Optional | boolean | If set, information about raid bdev will be stored in superblock on each base bdev (default: `false`) 10795 10796#### Example 10797 10798Example request: 10799 10800~~~json 10801{ 10802 "jsonrpc": "2.0", 10803 "method": "bdev_raid_create", 10804 "id": 1, 10805 "params": { 10806 "name": "Raid0", 10807 "raid_level": "0", 10808 "base_bdevs": [ 10809 "Malloc0", 10810 "Malloc1", 10811 "Malloc2", 10812 "Malloc3" 10813 ], 10814 "strip_size_kb": 4 10815 } 10816} 10817~~~ 10818 10819Example response: 10820 10821~~~json 10822{ 10823 "jsonrpc": "2.0", 10824 "id": 1, 10825 "result": true 10826} 10827~~~ 10828 10829### bdev_raid_delete {#rpc_bdev_raid_delete} 10830 10831Removes RAID bdev. 10832 10833#### Parameters 10834 10835Name | Optional | Type | Description 10836----------------------- | -------- | ----------- | ----------- 10837name | Required | string | RAID bdev name 10838 10839#### Example 10840 10841Example request: 10842 10843~~~json 10844{ 10845 "jsonrpc": "2.0", 10846 "method": "bdev_raid_delete", 10847 "id": 1, 10848 "params": { 10849 "name": "Raid0" 10850 } 10851} 10852~~~ 10853 10854Example response: 10855 10856~~~json 10857{ 10858 "jsonrpc": "2.0", 10859 "id": 1, 10860 "result": true 10861} 10862~~~ 10863 10864### bdev_raid_add_base_bdev {#rpc_bdev_raid_add_base_bdev} 10865 10866Add base bdev to existing raid bdev. The raid bdev must have an empty base bdev slot. 10867The bdev must be large enough and have the same block size and metadata format as the other base bdevs. 10868 10869#### Parameters 10870 10871Name | Optional | Type | Description 10872----------------------- | -------- | ----------- | ----------- 10873raid_bdev | Required | string | Raid bdev name 10874base_bdev | Required | string | Base bdev name 10875 10876#### Example 10877 10878Example request: 10879 10880~~~json 10881{ 10882 "jsonrpc": "2.0", 10883 "method": "bdev_raid_add_base_bdev", 10884 "id": 1, 10885 "params": { 10886 "raid_bdev": "RaidBdev0", 10887 "base_bdev": "Nvme0n1" 10888 } 10889} 10890~~~ 10891 10892Example response: 10893 10894~~~json 10895{ 10896 "jsonrpc": "2.0", 10897 "id": 1, 10898 "result": true 10899} 10900~~~ 10901### bdev_raid_remove_base_bdev {#rpc_bdev_raid_remove_base_bdev} 10902 10903Remove base bdev from existing raid bdev. 10904 10905#### Parameters 10906 10907Name | Optional | Type | Description 10908----------------------- | -------- | ----------- | ----------- 10909name | Required | string | Base bdev name in RAID 10910 10911#### Example 10912 10913Example request: 10914 10915~~~json 10916{ 10917 "jsonrpc": "2.0", 10918 "method": "bdev_raid_remove_base_bdev", 10919 "id": 1, 10920 "params": { 10921 "name": "Raid0" 10922 } 10923} 10924~~~ 10925 10926Example response: 10927 10928~~~json 10929{ 10930 "jsonrpc": "2.0", 10931 "id": 1, 10932 "result": true 10933} 10934~~~ 10935 10936## SPLIT 10937 10938### bdev_split_create {#rpc_bdev_split_create} 10939 10940This is used to split an underlying block device and create several smaller equal-sized vbdevs. 10941 10942#### Parameters 10943 10944Name | Optional | Type | Description 10945----------------------- | -------- | ----------- | ----------- 10946base_bdev | Required | string | base bdev name 10947split_count | Required | number | number of splits 10948split_size_mb | Optional | number | size in MB to restrict the size 10949 10950#### Example 10951 10952Example request: 10953 10954~~~json 10955{ 10956 "jsonrpc": "2.0", 10957 "method": "bdev_split_create", 10958 "id": 1, 10959 "params": { 10960 "base_bdev": "Malloc0", 10961 "split_count": 4 10962 } 10963} 10964~~~ 10965 10966Example response: 10967 10968~~~json 10969{ 10970 "jsonrpc": "2.0", 10971 "id": 1, 10972 "result": [ 10973 "Malloc0p0", 10974 "Malloc0p1", 10975 "Malloc0p2", 10976 "Malloc0p3" 10977 ] 10978} 10979~~~ 10980 10981### bdev_split_delete {#rpc_bdev_split_delete} 10982 10983This is used to remove the split vbdevs. 10984 10985#### Parameters 10986 10987Name | Optional | Type | Description 10988----------------------- | -------- | ----------- | ----------- 10989base_bdev | Required | string | base bdev name 10990 10991#### Example 10992 10993Example request: 10994 10995~~~json 10996{ 10997 "jsonrpc": "2.0", 10998 "method": "bdev_split_delete", 10999 "id": 1, 11000 "params": { 11001 "base_bdev": "Malloc0" 11002 } 11003} 11004~~~ 11005 11006Example response: 11007 11008~~~json 11009{ 11010 "jsonrpc": "2.0", 11011 "id": 1, 11012 "result": true 11013} 11014~~~ 11015 11016## Uring 11017 11018### bdev_uring_create {#rpc_bdev_uring_create} 11019 11020Create a bdev with io_uring backend. 11021 11022#### Parameters 11023 11024Name | Optional | Type | Description 11025----------------------- | -------- | ----------- | ----------- 11026filename | Required | string | path to device or file (ex: /dev/nvme0n1) 11027name | Required | string | name of bdev 11028block_size | Optional | number | block size of device (If omitted, get the block size from the file) 11029uuid | Optional | string | UUID of new bdev 11030 11031#### Example 11032 11033Example request: 11034 11035~~~json 11036{ 11037 "jsonrpc": "2.0", 11038 "method": "bdev_uring_create", 11039 "id": 1, 11040 "params": { 11041 "name": "bdev_u0", 11042 "filename": "/dev/nvme0n1", 11043 "block_size": 512 11044 } 11045} 11046~~~ 11047 11048Example response: 11049 11050~~~json 11051{ 11052 "jsonrpc": "2.0", 11053 "id": 1, 11054 "result": "bdev_u0" 11055} 11056~~~ 11057 11058### bdev_uring_rescan {#rpc_bdev_uring_rescan} 11059 11060Rescan the size of a uring bdev. 11061 11062#### Parameters 11063 11064Name | Optional | Type | Description 11065---- | -------- | ------ | ----------- 11066name | Required | string | name of uring bdev to rescan 11067 11068#### Example 11069 11070Example request: 11071 11072~~~json 11073{ 11074 "jsonrpc": "2.0", 11075 "method": "bdev_uring_rescan", 11076 "id": 1, 11077 "params": { 11078 "name": "bdev_u0" 11079 } 11080} 11081~~~ 11082 11083Example response: 11084 11085~~~json 11086{ 11087 "jsonrpc": "2.0", 11088 "id": 1, 11089 "result": true 11090} 11091~~~ 11092 11093### bdev_uring_delete {#rpc_bdev_uring_delete} 11094 11095Remove a uring bdev. 11096 11097#### Parameters 11098 11099Name | Optional | Type | Description 11100----------------------- | -------- | ----------- | ----------- 11101name | Required | string | name of uring bdev to delete 11102 11103#### Example 11104 11105Example request: 11106 11107~~~json 11108{ 11109 "jsonrpc": "2.0", 11110 "method": "bdev_uring_delete", 11111 "id": 1, 11112 "params": { 11113 "name": "bdev_u0" 11114 } 11115} 11116~~~ 11117 11118Example response: 11119 11120~~~json 11121{ 11122 "jsonrpc": "2.0", 11123 "id": 1, 11124 "result": true 11125} 11126~~~ 11127 11128## OPAL 11129 11130### bdev_nvme_opal_init {#rpc_bdev_nvme_opal_init} 11131 11132This is used to initialize OPAL of a given NVMe ctrlr, including taking ownership and activating. 11133 11134#### Parameters 11135 11136Name | Optional | Type | Description 11137----------------------- | -------- | ----------- | ----------- 11138nvme_ctrlr_name | Required | string | name of nvme ctrlr 11139password | Required | string | admin password of OPAL 11140 11141#### Example 11142 11143Example request: 11144 11145~~~json 11146{ 11147 "jsonrpc": "2.0", 11148 "method": "bdev_nvme_opal_init", 11149 "id": 1, 11150 "params": { 11151 "nvme_ctrlr_name": "nvme0", 11152 "password": "*****" 11153 } 11154} 11155~~~ 11156 11157Example response: 11158 11159~~~json 11160{ 11161 "jsonrpc": "2.0", 11162 "id": 1, 11163 "result": true 11164} 11165~~~ 11166 11167### bdev_nvme_opal_revert {#rpc_bdev_nvme_opal_revert} 11168 11169This is used to revert OPAL to its factory settings. Erase all user configuration and data. 11170 11171#### Parameters 11172 11173Name | Optional | Type | Description 11174----------------------- | -------- | ----------- | ----------- 11175nvme_ctrlr_name | Required | string | name of nvme ctrlr 11176password | Required | string | admin password of OPAL 11177 11178#### Example 11179 11180Example request: 11181 11182~~~json 11183{ 11184 "jsonrpc": "2.0", 11185 "method": "bdev_nvme_opal_revert", 11186 "id": 1, 11187 "params": { 11188 "nvme_ctrlr_name": "nvme0", 11189 "password": "*****" 11190 } 11191} 11192~~~ 11193 11194Example response: 11195 11196~~~json 11197{ 11198 "jsonrpc": "2.0", 11199 "id": 1, 11200 "result": true 11201} 11202~~~ 11203 11204### bdev_opal_create {#rpc_bdev_opal_create} 11205 11206This is used to create an OPAL virtual bdev. 11207 11208#### Parameters 11209 11210Name | Optional | Type | Description 11211----------------------- | -------- | ----------- | ----------- 11212nvme_ctrlr_name | Required | string | name of nvme ctrlr that supports OPAL 11213nsid | Required | number | namespace ID 11214locking_range_id | Required | number | OPAL locking range ID 11215range_start | Required | number | locking range start LBA 11216range_length | Required | number | locking range length 11217password | Required | string | admin password of OPAL 11218 11219#### Response 11220 11221The response is the name of created OPAL virtual bdev. 11222 11223#### Example 11224 11225Example request: 11226 11227~~~json 11228{ 11229 "jsonrpc": "2.0", 11230 "method": "bdev_opal_create", 11231 "id": 1, 11232 "params": { 11233 "nvme_ctrlr_name": "nvme0", 11234 "nsid": 1, 11235 "locking_range_id": 1, 11236 "range_start": 0, 11237 "range_length": 4096, 11238 "password": "*****" 11239 } 11240} 11241~~~ 11242 11243Example response: 11244 11245~~~json 11246{ 11247 "jsonrpc": "2.0", 11248 "id": 1, 11249 "result": "nvme0n1r1" 11250} 11251~~~ 11252 11253### bdev_opal_get_info {#rpc_bdev_opal_get_info} 11254 11255This is used to get information of a given OPAL bdev. 11256 11257#### Parameters 11258 11259Name | Optional | Type | Description 11260----------------------- | -------- | ----------- | ----------- 11261bdev_name | Required | string | name of OPAL vbdev 11262password | Required | string | admin password 11263 11264#### Response 11265 11266The response is the locking info of OPAL virtual bdev. 11267 11268#### Example 11269 11270Example request: 11271 11272~~~json 11273{ 11274 "jsonrpc": "2.0", 11275 "method": "bdev_opal_get_info", 11276 "id": 1, 11277 "params": { 11278 "bdev_name": "nvme0n1r1", 11279 "password": "*****" 11280 } 11281} 11282~~~ 11283 11284Example response: 11285 11286~~~json 11287{ 11288 "jsonrpc": "2.0", 11289 "id": 1, 11290 "result": { 11291 "name": "nvme0n1r1", 11292 "range_start": 0, 11293 "range_length": 4096, 11294 "read_lock_enabled": true, 11295 "write_lock_enabled": true, 11296 "read_locked": false, 11297 "write_locked": false 11298 } 11299} 11300~~~ 11301 11302### bdev_opal_delete {#rpc_bdev_opal_delete} 11303 11304This is used to delete OPAL vbdev. 11305 11306#### Parameters 11307 11308Name | Optional | Type | Description 11309----------------------- | -------- | ----------- | ----------- 11310bdev_name | Required | string | name of OPAL vbdev 11311password | Required | string | admin password 11312 11313#### Example 11314 11315Example request: 11316 11317~~~json 11318{ 11319 "jsonrpc": "2.0", 11320 "method": "bdev_opal_delete", 11321 "id": 1, 11322 "params": { 11323 "bdev_name": "nvme0n1r1", 11324 "password": "*****" 11325 } 11326} 11327~~~ 11328 11329Example response: 11330 11331~~~json 11332{ 11333 "jsonrpc": "2.0", 11334 "id": 1, 11335 "result": true 11336} 11337~~~ 11338 11339### bdev_opal_new_user {#rpc_bdev_opal_new_user} 11340 11341This enables a new user to the specified opal bdev so that the user can lock/unlock the bdev. 11342Recalling this for the same opal bdev, only the newest user will have the privilege. 11343 11344#### Parameters 11345 11346Name | Optional | Type | Description 11347----------------------- | -------- | ----------- | ----------- 11348bdev_name | Required | string | name of OPAL vbdev 11349admin_password | Required | string | admin password 11350user_id | Required | number | user ID 11351user_password | Required | string | user password 11352 11353#### Example 11354 11355Example request: 11356 11357~~~json 11358{ 11359 "jsonrpc": "2.0", 11360 "method": "bdev_opal_new_user", 11361 "id": 1, 11362 "params": { 11363 "bdev_name": "nvme0n1r1", 11364 "admin_password": "*****", 11365 "user_id": "1", 11366 "user_password": "********" 11367 } 11368} 11369~~~ 11370 11371Example response: 11372 11373~~~json 11374{ 11375 "jsonrpc": "2.0", 11376 "id": 1, 11377 "result": true 11378} 11379~~~ 11380 11381### bdev_opal_set_lock_state {#rpc_bdev_opal_set_lock_state} 11382 11383This is used to lock/unlock specific opal bdev providing user ID and password. 11384 11385#### Parameters 11386 11387Name | Optional | Type | Description 11388----------------------- | -------- | ----------- | ----------- 11389bdev_name | Required | string | name of OPAL vbdev 11390user_id | Required | number | user ID 11391password | Required | string | user password 11392lock_state | Required | string | lock state 11393 11394#### Example 11395 11396Example request: 11397 11398~~~json 11399{ 11400 "jsonrpc": "2.0", 11401 "method": "bdev_opal_set_lock_state", 11402 "id": 1, 11403 "params": { 11404 "bdev_name": "nvme0n1r1", 11405 "user_id": "1", 11406 "user_password": "********", 11407 "lock_state": "rwlock" 11408 } 11409} 11410~~~ 11411 11412Example response: 11413 11414~~~json 11415{ 11416 "jsonrpc": "2.0", 11417 "id": 1, 11418 "result": true 11419} 11420~~~ 11421 11422## Notifications 11423 11424### notify_get_types {#rpc_notify_get_types} 11425 11426Return list of all supported notification types. 11427 11428#### Parameters 11429 11430None 11431 11432#### Response 11433 11434The response is an array of strings - supported RPC notification types. 11435 11436#### Example 11437 11438Example request: 11439 11440~~~json 11441{ 11442 "jsonrpc": "2.0", 11443 "method": "notify_get_types", 11444 "id": 1 11445} 11446~~~ 11447 11448Example response: 11449 11450~~~json 11451{ 11452 "id": 1, 11453 "result": [ 11454 "bdev_register", 11455 "bdev_unregister" 11456 ], 11457 "jsonrpc": "2.0" 11458} 11459~~~ 11460 11461### notify_get_notifications {#notify_get_notifications} 11462 11463Request notifications. Returns array of notifications that happened since the specified id (or first that is available). 11464 11465Notice: Notifications are kept in circular buffer with limited size. Older notifications might be inaccessible 11466due to being overwritten by new ones. 11467 11468#### Parameters 11469 11470Name | Optional | Type | Description 11471----------------------- | -------- | ----------- | ----------- 11472id | Optional | number | First Event ID to fetch (default: first available). 11473max | Optional | number | Maximum number of event to return (default: no limit). 11474 11475#### Response 11476 11477Response is an array of event objects. 11478 11479Name | Optional | Type | Description 11480----------------------- | -------- | ----------- | ----------- 11481id | Optional | number | Event ID. 11482type | Optional | number | Type of the event. 11483ctx | Optional | string | Event context. 11484 11485#### Example 11486 11487Example request: 11488 11489~~~json 11490{ 11491 "id": 1, 11492 "jsonrpc": "2.0", 11493 "method": "notify_get_notifications", 11494 "params": { 11495 "id": 1, 11496 "max": 10 11497 } 11498} 11499 11500~~~ 11501 11502Example response: 11503 11504~~~json 11505{ 11506 "jsonrpc": "2.0", 11507 "id": 1, 11508 "result": [ 11509 { 11510 "ctx": "Malloc0", 11511 "type": "bdev_register", 11512 "id": 1 11513 }, 11514 { 11515 "ctx": "Malloc2", 11516 "type": "bdev_register", 11517 "id": 2 11518 } 11519 ] 11520} 11521~~~ 11522 11523## Linux Userspace Block Device (UBLK) {#jsonrpc_components_ublk} 11524 11525SPDK supports exporting bdevs though Linux ublk. The motivation behind it is to back a Linux kernel block device 11526with an SPDK user space bdev. 11527 11528To export a device over ublk, first make sure the Linux kernel ublk driver is loaded by running 'modprobe ublk_drv'. 11529 11530### ublk_create_target {#rpc_ublk_create_target} 11531 11532Start to create ublk threads and initialize ublk target. It will return an error if user calls this RPC twice without 11533ublk_destroy_target in between. It will use current cpumask in SPDK when user does not specify cpumask option. 11534 11535#### Parameters 11536 11537Name | Optional | Type | Description 11538----------------------- | -------- | ----------- | ----------- 11539cpumask | Optional | string | Cpumask for ublk target 11540disable-user-copy | Optional | boolean | Disable user copy feature 11541 11542#### Response 11543 11544True if ublk target initialization is successful; False if failed. 11545 11546#### Example 11547 11548Example request: 11549 11550~~~json 11551{ 11552 "params": { 11553 "cpumask": "0x2" 11554 }, 11555 "jsonrpc": "2.0", 11556 "method": "ublk_create_target", 11557 "id": 1 11558} 11559~~~ 11560 11561Example response: 11562 11563~~~json 11564{ 11565 "jsonrpc": "2.0", 11566 "id": 1, 11567 "result": true 11568} 11569~~~ 11570 11571### ublk_destroy_target {#rpc_ublk_destroy_target} 11572 11573Release all UBLK devices and destroy ublk target. 11574 11575#### Response 11576 11577True if ublk target destruction is successful; False if failed. 11578 11579#### Example 11580 11581Example request: 11582 11583~~~json 11584{ 11585 "jsonrpc": "2.0", 11586 "method": "ublk_destroy_target", 11587 "id": 1 11588} 11589~~~ 11590 11591Example response: 11592 11593~~~json 11594{ 11595 "jsonrpc": "2.0", 11596 "id": 1, 11597 "result": true 11598} 11599~~~ 11600 11601### ublk_start_disk {#rpc_ublk_start_disk} 11602 11603Start to export one SPDK bdev as a UBLK device 11604 11605#### Parameters 11606 11607Name | Optional | Type | Description 11608----------------------- | -------- | ----------- | ----------- 11609bdev_name | Required | string | Bdev name to export 11610ublk_id | Required | int | Device id 11611queue_depth | Optional | int | Device queue depth 11612num_queues | Optional | int | Total number of device queues 11613 11614#### Response 11615 11616UBLK device ID 11617 11618#### Example 11619 11620Example request: 11621 11622~~~json 11623{ 11624 "params": { 11625 "ublk_id": "1", 11626 "bdev_name": "Malloc1" 11627 }, 11628 "jsonrpc": "2.0", 11629 "method": "ublk_start_disk", 11630 "id": 1 11631} 11632~~~ 11633 11634Example response: 11635 11636~~~json 11637{ 11638 "jsonrpc": "2.0", 11639 "id": 1, 11640 "result": 1 11641} 11642~~~ 11643 11644### ublk_recover_disk {#rpc_ublk_recover_disk} 11645 11646Recover original UBLK device with ID and block device 11647 11648#### Parameters 11649 11650Name | Optional | Type | Description 11651----------------------- | -------- | ----------- | ----------- 11652bdev_name | Required | string | Bdev name to export 11653ublk_id | Required | int | Device id 11654 11655#### Response 11656 11657UBLK device ID 11658 11659#### Example 11660 11661Example request: 11662 11663~~~json 11664{ 11665 "params": { 11666 "ublk_id": "1", 11667 "bdev_name": "Malloc1" 11668 }, 11669 "jsonrpc": "2.0", 11670 "method": "ublk_recover_disk", 11671 "id": 1 11672} 11673~~~ 11674 11675Example response: 11676 11677~~~json 11678{ 11679 "jsonrpc": "2.0", 11680 "id": 1, 11681 "result": 1 11682} 11683 11684### ublk_stop_disk {#rpc_ublk_stop_disk} 11685 11686Delete a UBLK device 11687 11688#### Parameters 11689 11690Name | Optional | Type | Description 11691----------------------- | -------- | ----------- | ----------- 11692ublk_id | Required | int | Device id to delete 11693 11694#### Response 11695 11696True if UBLK device is deleted successfully; False if failed. 11697 11698#### Example 11699 11700Example request: 11701 11702~~~json 11703{ 11704 "params": { 11705 "ublk_id": "1", 11706 }, 11707 "jsonrpc": "2.0", 11708 "method": "ublk_stop_disk", 11709 "id": 1 11710} 11711~~~ 11712 11713Example response: 11714 11715~~~json 11716{ 11717 "jsonrpc": "2.0", 11718 "id": 1, 11719 "result": true 11720} 11721~~~ 11722 11723### ublk_get_disks {#rpc_ublk_get_disks} 11724 11725Display full or specified ublk device list 11726 11727#### Parameters 11728 11729Name | Optional | Type | Description 11730----------------------- | -------- | ----------- | ----------- 11731ublk_id | Optional | int | ublk device id to display 11732 11733#### Response 11734 11735Display ublk device list 11736 11737#### Example 11738 11739Example request: 11740 11741~~~json 11742{ 11743 "jsonrpc": "2.0", 11744 "method": "ublk_get_disks", 11745 "id": 1 11746} 11747~~~ 11748 11749Example response: 11750 11751~~~json 11752{ 11753 "jsonrpc": "2.0", 11754 "id": 1, 11755 "result": [ 11756 { 11757 "ublk_device": "/dev/ublkb1", 11758 "id": 1, 11759 "queue_depth": 512, 11760 "num_queues": 1, 11761 "bdev_name": "Malloc1" 11762 } 11763 ] 11764} 11765~~~ 11766 11767## Linux Network Block Device (NBD) {#jsonrpc_components_nbd} 11768 11769SPDK supports exporting bdevs through Linux nbd. These devices then appear as standard Linux kernel block devices 11770and can be accessed using standard utilities like fdisk. 11771 11772In order to export a device over nbd, first make sure the Linux kernel nbd driver is loaded by running 'modprobe nbd'. 11773 11774### nbd_start_disk {#rpc_nbd_start_disk} 11775 11776Start to export one SPDK bdev as NBD disk 11777 11778#### Parameters 11779 11780Name | Optional | Type | Description 11781----------------------- | -------- | ----------- | ----------- 11782bdev_name | Required | string | Bdev name to export 11783nbd_device | Optional | string | NBD device name to assign 11784 11785#### Response 11786 11787Path of exported NBD disk 11788 11789#### Example 11790 11791Example request: 11792 11793~~~json 11794{ 11795 "params": { 11796 "nbd_device": "/dev/nbd1", 11797 "bdev_name": "Malloc1" 11798 }, 11799 "jsonrpc": "2.0", 11800 "method": "nbd_start_disk", 11801 "id": 1 11802} 11803~~~ 11804 11805Example response: 11806 11807~~~json 11808{ 11809 "jsonrpc": "2.0", 11810 "id": 1, 11811 "result": "/dev/nbd1" 11812} 11813~~~ 11814 11815### nbd_stop_disk {#rpc_nbd_stop_disk} 11816 11817Stop one NBD disk which is based on SPDK bdev. 11818 11819#### Parameters 11820 11821Name | Optional | Type | Description 11822----------------------- | -------- | ----------- | ----------- 11823nbd_device | Required | string | NBD device name to stop 11824 11825#### Example 11826 11827Example request: 11828 11829~~~json 11830{ 11831 "params": { 11832 "nbd_device": "/dev/nbd1", 11833 }, 11834 "jsonrpc": "2.0", 11835 "method": "nbd_stop_disk", 11836 "id": 1 11837} 11838~~~ 11839 11840Example response: 11841 11842~~~json 11843{ 11844 "jsonrpc": "2.0", 11845 "id": 1, 11846 "result": "true" 11847} 11848~~~ 11849 11850### nbd_get_disks {#rpc_nbd_get_disks} 11851 11852Display all or specified NBD device list 11853 11854#### Parameters 11855 11856Name | Optional | Type | Description 11857----------------------- | -------- | ----------- | ----------- 11858nbd_device | Optional | string | NBD device name to display 11859 11860#### Response 11861 11862The response is an array of exported NBD devices and their corresponding SPDK bdev. 11863 11864#### Example 11865 11866Example request: 11867 11868~~~json 11869{ 11870 "jsonrpc": "2.0", 11871 "method": "nbd_get_disks", 11872 "id": 1 11873} 11874~~~ 11875 11876Example response: 11877 11878~~~json 11879{ 11880 "jsonrpc": "2.0", 11881 "id": 1, 11882 "result": [ 11883 { 11884 "bdev_name": "Malloc0", 11885 "nbd_device": "/dev/nbd0" 11886 }, 11887 { 11888 "bdev_name": "Malloc1", 11889 "nbd_device": "/dev/nbd1" 11890 } 11891 ] 11892} 11893~~~ 11894 11895## Blobfs {#jsonrpc_components_blobfs} 11896 11897### blobfs_detect {#rpc_blobfs_detect} 11898 11899Detect whether a blobfs exists on bdev. 11900 11901#### Parameters 11902 11903Name | Optional | Type | Description 11904----------------------- | -------- | ----------- | ----------- 11905bdev_name | Required | string | Block device name to detect blobfs 11906 11907#### Response 11908 11909True if a blobfs exists on the bdev; False otherwise. 11910 11911#### Example 11912 11913Example request: 11914 11915~~~json 11916{ 11917 "jsonrpc": "2.0", 11918 "id": 1, 11919 "method": "blobfs_detect", 11920 "params": { 11921 "bdev_name": "Malloc0" 11922 } 11923} 11924~~~ 11925 11926Example response: 11927 11928~~~json 11929{ 11930 "jsonrpc": "2.0", 11931 "id": 1, 11932 "result": "true" 11933} 11934~~~ 11935 11936### blobfs_create {#rpc_blobfs_create} 11937 11938Build blobfs on bdev. 11939 11940#### Parameters 11941 11942Name | Optional | Type | Description 11943----------------------- | -------- | ----------- | ----------- 11944bdev_name | Required | string | Block device name to create blobfs 11945cluster_sz | Optional | number | Size of cluster in bytes. Must be multiple of 4KiB page size, default and minimal value is 1M. 11946 11947#### Example 11948 11949Example request: 11950 11951~~~json 11952{ 11953 "jsonrpc": "2.0", 11954 "id": 1, 11955 "method": "blobfs_create", 11956 "params": { 11957 "bdev_name": "Malloc0", 11958 "cluster_sz": 1M 11959 } 11960} 11961~~~ 11962 11963Example response: 11964 11965~~~json 11966{ 11967 "jsonrpc": "2.0", 11968 "id": 1, 11969 "result": "true" 11970} 11971~~~ 11972 11973### blobfs_mount {#rpc_blobfs_mount} 11974 11975Mount a blobfs on bdev to one host path through FUSE 11976 11977#### Parameters 11978 11979Name | Optional | Type | Description 11980----------------------- | -------- | ----------- | ----------- 11981bdev_name | Required | string | Block device name where the blobfs is 11982mountpoint | Required | string | Mountpoint path in host to mount blobfs 11983 11984#### Example 11985 11986Example request: 11987 11988~~~json 11989{ 11990 "jsonrpc": "2.0", 11991 "id": 1, 11992 "method": ""blobfs_mount"", 11993 "params": { 11994 "bdev_name": "Malloc0", 11995 "mountpoint": "/mnt/" 11996 } 11997} 11998~~~ 11999 12000Example response: 12001 12002~~~json 12003{ 12004 "jsonrpc": "2.0", 12005 "id": 1, 12006 "result": "true" 12007} 12008~~~ 12009 12010### blobfs_set_cache_size {#rpc_blobfs_set_cache_size} 12011 12012Set cache pool size for blobfs filesystems. This RPC is only permitted when the cache pool is not already initialized. 12013 12014The cache pool is initialized when the first blobfs filesystem is initialized or loaded. It is freed when the all 12015initialized or loaded filesystems are unloaded. 12016 12017#### Parameters 12018 12019Name | Optional | Type | Description 12020----------------------- | -------- | ----------- | ----------- 12021size_in_mb | Required | number | Cache size in megabytes 12022 12023#### Response 12024 12025True if cache size is set successfully; False if failed to set. 12026 12027#### Example 12028 12029Example request: 12030 12031~~~json 12032{ 12033 "jsonrpc": "2.0", 12034 "id": 1, 12035 "method": "blobfs_set_cache_size", 12036 "params": { 12037 "size_in_mb": 512, 12038 } 12039} 12040~~~ 12041 12042Example response: 12043 12044~~~json 12045{ 12046 "jsonrpc": "2.0", 12047 "id": 1, 12048 "result": true 12049} 12050~~~ 12051 12052## Socket layer {#jsonrpc_components_sock} 12053 12054### sock_impl_get_options {#rpc_sock_impl_get_options} 12055 12056Get parameters for the socket layer implementation. 12057 12058#### Parameters 12059 12060Name | Optional | Type | Description 12061----------------------- | -------- | ----------- | ----------- 12062impl_name | Required | string | Name of socket implementation, e.g. posix 12063 12064#### Response 12065 12066Response is an object with current socket layer options for requested implementation. 12067 12068#### Example 12069 12070Example request: 12071 12072~~~json 12073{ 12074 "jsonrpc": "2.0", 12075 "method": "sock_impl_get_options", 12076 "id": 1, 12077 "params": { 12078 "impl_name": "posix" 12079 } 12080} 12081~~~ 12082 12083Example response: 12084 12085~~~json 12086{ 12087 "jsonrpc": "2.0", 12088 "id": 1, 12089 "result": { 12090 "recv_buf_size": 2097152, 12091 "send_buf_size": 2097152, 12092 "enable_recv_pipe": true, 12093 "enable_quickack": true, 12094 "enable_placement_id": 0, 12095 "enable_zerocopy_send_server": true, 12096 "enable_zerocopy_send_client": false, 12097 "zerocopy_threshold": 0, 12098 "tls_version": 13, 12099 "enable_ktls": false 12100 } 12101} 12102~~~ 12103 12104### sock_impl_set_options {#rpc_sock_impl_set_options} 12105 12106Set parameters for the socket layer implementation. 12107 12108#### Parameters 12109 12110Name | Optional | Type | Description 12111--------------------------- | -------- | ----------- | ----------- 12112impl_name | Required | string | Name of socket implementation, e.g. posix 12113recv_buf_size | Optional | number | Size of socket receive buffer in bytes 12114send_buf_size | Optional | number | Size of socket send buffer in bytes 12115enable_recv_pipe | Optional | boolean | Enable or disable receive pipe 12116enable_quick_ack | Optional | boolean | Enable or disable quick ACK 12117enable_placement_id | Optional | number | Enable or disable placement_id. 0:disable,1:incoming_napi,2:incoming_cpu 12118enable_zerocopy_send_server | Optional | boolean | Enable or disable zero copy on send for server sockets 12119enable_zerocopy_send_client | Optional | boolean | Enable or disable zero copy on send for client sockets 12120zerocopy_threshold | Optional | number | Set zerocopy_threshold in bytes. A consecutive sequence of requests' iovecs 12121-- | -- | -- | that fall below this threshold may be sent without zerocopy flag set 12122tls_version | Optional | number | TLS protocol version, e.g. 13 for v1.3 (only applies when impl_name == ssl) 12123enable_ktls | Optional | boolean | Enable or disable Kernel TLS (only applies when impl_name == ssl) 12124 12125#### Response 12126 12127True if socket layer options were set successfully. 12128 12129#### Example 12130 12131Example request: 12132 12133~~~json 12134{ 12135 "jsonrpc": "2.0", 12136 "method": "sock_impl_set_options", 12137 "id": 1, 12138 "params": { 12139 "impl_name": "posix", 12140 "recv_buf_size": 2097152, 12141 "send_buf_size": 2097152, 12142 "enable_recv_pipe": false, 12143 "enable_quick_ack": false, 12144 "enable_placement_id": 0, 12145 "enable_zerocopy_send_server": true, 12146 "enable_zerocopy_send_client": false, 12147 "zerocopy_threshold": 10240, 12148 "tls_version": 13, 12149 "enable_ktls": false 12150 } 12151} 12152~~~ 12153 12154Example response: 12155 12156~~~json 12157{ 12158 "jsonrpc": "2.0", 12159 "id": 1, 12160 "result": true 12161} 12162~~~ 12163 12164### sock_set_default_impl {#rpc_sock_set_default_impl} 12165 12166Set the default sock implementation. 12167 12168#### Parameters 12169 12170Name | Optional | Type | Description 12171----------------------- | -------- | ----------- | ----------- 12172impl_name | Required | string | Name of socket implementation, e.g. posix 12173 12174#### Response 12175 12176True if the default socket layer configuration was set successfully. 12177 12178#### Example 12179 12180Example request: 12181 12182~~~json 12183{ 12184 "jsonrpc": "2.0", 12185 "method": "sock_set_default_impl", 12186 "id": 1, 12187 "params": { 12188 "impl_name": "posix" 12189 } 12190} 12191~~~ 12192 12193Example response: 12194 12195~~~json 12196{ 12197 "jsonrpc": "2.0", 12198 "id": 1, 12199 "result": true 12200} 12201~~~ 12202 12203### sock_get_default_impl {#rpc_sock_get_default_impl} 12204 12205Get the name of the default sock implementation. 12206 12207#### Parameters 12208 12209This function has no parameters. 12210 12211#### Response 12212 12213The name of the current default socket implementation. 12214 12215#### Example 12216 12217Example request: 12218 12219~~~json 12220{ 12221 "jsonrpc": "2.0", 12222 "method": "sock_get_default_impl", 12223 "id": 1 12224} 12225~~~ 12226 12227Example response: 12228 12229~~~json 12230{ 12231 "jsonrpc": "2.0", 12232 "id": 1, 12233 "result": { 12234 "impl_name": "posix" 12235 } 12236} 12237~~~ 12238 12239## Miscellaneous RPC commands 12240 12241### bdev_nvme_send_cmd {#rpc_bdev_nvme_send_cmd} 12242 12243Send NVMe command directly to NVMe controller or namespace. Parameters and responses encoded by base64 urlsafe need further processing. 12244 12245Notice: bdev_nvme_send_cmd requires user to guarantee the correctness of NVMe command itself, and also optional parameters. 12246Illegal command contents or mismatching buffer size may result in unpredictable behavior. 12247 12248#### Parameters 12249 12250Name | Optional | Type | Description 12251----------------------- | -------- | ----------- | ----------- 12252name | Required | string | Name of the operating NVMe controller 12253cmd_type | Required | string | Type of nvme cmd. Valid values are: admin, io 12254data_direction | Required | string | Direction of data transfer. Valid values are: c2h, h2c 12255cmdbuf | Required | string | NVMe command encoded by base64 urlsafe 12256data | Optional | string | Data transferring to controller from host, encoded by base64 urlsafe 12257metadata | Optional | string | Metadata transferring to controller from host, encoded by base64 urlsafe 12258data_len | Optional | number | Data length required to transfer from controller to host 12259metadata_len | Optional | number | Metadata length required to transfer from controller to host 12260timeout_ms | Optional | number | Command execution timeout value, in milliseconds 12261 12262#### Response 12263 12264Name | Type | Description 12265----------------------- | ----------- | ----------- 12266cpl | string | NVMe completion queue entry, encoded by base64 urlsafe 12267data | string | Data transferred from controller to host, encoded by base64 urlsafe 12268metadata | string | Metadata transferred from controller to host, encoded by base64 urlsafe 12269 12270#### Example 12271 12272Example request: 12273 12274~~~json 12275{ 12276 "jsonrpc": "2.0", 12277 "method": "bdev_nvme_send_cmd", 12278 "id": 1, 12279 "params": { 12280 "name": "Nvme0", 12281 "cmd_type": "admin" 12282 "data_direction": "c2h", 12283 "cmdbuf": "BgAAAAEAAAAAAAAAAAAAAAAAAAAAAAAAsGUs9P5_AAAAAAAAABAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA==", 12284 "data_len": 60, 12285 } 12286} 12287~~~ 12288 12289Example response: 12290 12291~~~json 12292{ 12293 "jsonrpc": "2.0", 12294 "id": 1, 12295 "result": { 12296 "cpl": "AAAAAAAAAAARAAAAWrmwABAA==", 12297 "data": "sIjg6AAAAACwiODoAAAAALCI4OgAAAAAAAYAAREAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA" 12298 } 12299 12300} 12301~~~ 12302 12303### vmd_enable {#rpc_enable_vmd} 12304 12305Enable VMD enumeration. 12306 12307#### Parameters 12308 12309This method has no parameters. 12310 12311#### Response 12312 12313Completion status of enumeration is returned as a boolean. 12314 12315### Example 12316 12317Example request: 12318 12319~~~json 12320{ 12321 "jsonrpc": "2.0", 12322 "method": "vmd_enable", 12323 "id": 1 12324} 12325~~~ 12326 12327Example response: 12328 12329~~~json 12330{ 12331 "jsonrpc": "2.0", 12332 "id": 1, 12333 "result": true 12334} 12335~~~ 12336 12337### vmd_remove_device {#rpc_vmd_remove_device} 12338 12339Remove a device behind a VMD. 12340 12341### Parameters 12342 12343Name | Optional | Type | Description 12344----------------------- | -------- | ----------- | ----------- 12345addr | Required | string | Address of the device to remove. 12346 12347### Example 12348 12349~~~json 12350{ 12351 "jsonrpc": "2.0", 12352 "method": "vmd_remove_device", 12353 "params": { 12354 "addr": "5d0505:01:00.0" 12355 } 12356 "id": 1 12357} 12358~~~ 12359 12360Example response: 12361 12362~~~json 12363{ 12364 "jsonrpc": "2.0", 12365 "id": 1, 12366 "result": true 12367} 12368~~~ 12369 12370### vmd_rescan {#rpc_vmd_rescan} 12371 12372Force a rescan of the devices behind VMD. 12373 12374### Parameters 12375 12376This method has no parameters. 12377 12378#### Response 12379 12380The response is the number of new devices found. 12381 12382### Example 12383 12384~~~json 12385{ 12386 "jsonrpc": "2.0", 12387 "method": "vmd_rescan", 12388 "id": 1 12389} 12390~~~ 12391 12392Example response: 12393 12394~~~json 12395{ 12396 "jsonrpc": "2.0", 12397 "id": 1, 12398 "result": { 12399 "count": 1 12400 } 12401} 12402~~~ 12403 12404### spdk_get_version {#rpc_spdk_get_version} 12405 12406Get the version info of the running SPDK application. 12407 12408#### Parameters 12409 12410This method has no parameters. 12411 12412#### Response 12413 12414The response is the version number including major version number, minor version number, patch level number and suffix string. 12415 12416#### Example 12417 12418Example request: 12419 12420~~~json 12421{ 12422 "jsonrpc": "2.0", 12423 "id": 1, 12424 "method": "spdk_get_version" 12425} 12426~~~ 12427 12428Example response: 12429 12430~~~json 12431{ 12432 "jsonrpc": "2.0", 12433 "id": 1, 12434 "result": { 12435 "version": "19.04-pre", 12436 "fields" : { 12437 "major": 19, 12438 "minor": 4, 12439 "patch": 0, 12440 "suffix": "-pre" 12441 } 12442 } 12443} 12444~~~ 12445 12446### framework_get_pci_devices 12447 12448List PCIe devices attached to an SPDK application and the contents of their config space. 12449 12450#### Parameters 12451 12452This method has no parameters. 12453 12454#### Response 12455 12456The response is an array of attached PCIe devices. 12457 12458#### Example 12459 12460Example request: 12461 12462~~~json 12463{ 12464 "jsonrpc": "2.0", 12465 "id": 1, 12466 "method": "framework_get_pci_devices" 12467} 12468~~~ 12469 12470Example response: 12471Note that the config space buffer was trimmed. 12472 12473~~~json 12474{ 12475 "jsonrpc": "2.0", 12476 "id": 1, 12477 "result": { 12478 [ 12479 { 12480 "address": "0000:00:04.0", 12481 "config_space": "8680455807051000...0000000000000000" 12482 }, 12483 { 12484 "address": "0000:00:03.0", 12485 "config_space": "8680455807051000...0000000000000000" 12486 } 12487 ] 12488 } 12489} 12490~~~ 12491 12492### bdev_nvme_add_error_injection {#rpc_bdev_nvme_add_error_injection} 12493 12494Add a NVMe command error injection for a bdev nvme controller. 12495 12496#### Parameters 12497 12498Name | Optional | Type | Description 12499----------------------- | -------- | ----------- | ----------- 12500name | Required | string | Name of the operating NVMe controller 12501cmd_type | Required | string | Type of NVMe command. Valid values are: admin, io 12502opc | Required | number | Opcode for which the error injection is applied 12503do_not_submit | Optional | boolean | Set to true if request should not be submitted to the controller (default false) 12504timeout_in_us | Optional | number | Wait specified microseconds when do_not_submit is true 12505err_count | Optional | number | Number of matching NVMe commands to inject errors 12506sct | Optional | number | Status code type (default 0) 12507sc | Optional | number | Status code (default 0) 12508 12509#### Response 12510 12511true on success 12512 12513#### Example 12514 12515Example request: 12516 12517~~~json 12518{ 12519 "jsonrpc": "2.0", 12520 "method": "bdev_nvme_add_error_injection", 12521 "id": 1, 12522 "params": { 12523 "name": "HotInNvme0", 12524 "opc": 2, 12525 "cmd_type": "io", 12526 "err_count": 1111111, 12527 "sct": 11, 12528 "sc": 33 12529 } 12530} 12531 12532~~~ 12533 12534Example response: 12535 12536~~~json 12537{ 12538 "jsonrpc": "2.0", 12539 "id": 1, 12540 "result": true 12541} 12542 12543~~~ 12544 12545### bdev_nvme_remove_error_injection {#rpc_bdev_nvme_remove_error_injection} 12546 12547Remove a NVMe command error injection. 12548 12549#### Parameters 12550 12551Name | Optional | Type | Description 12552----------------------- | -------- | ----------- | ----------- 12553name | Required | string | Name of the operating NVMe controller 12554cmd_type | Required | string | Type of NVMe command. Valid values are: admin, io 12555opc | Required | number | Opcode for which the error injection is applied 12556 12557#### Response 12558 12559true on success 12560 12561#### Example 12562 12563Example request: 12564 12565~~~json 12566{ 12567 "jsonrpc": "2.0", 12568 "method": "bdev_nvme_remove_error_injection", 12569 "id": 1, 12570 "params": { 12571 "name": "HotInNvme0", 12572 "opc": 2, 12573 "cmd_type": "io" 12574 } 12575} 12576 12577 12578~~~ 12579 12580Example response: 12581 12582~~~json 12583{ 12584 "jsonrpc": "2.0", 12585 "id": 1, 12586 "result": true 12587} 12588 12589~~~ 12590 12591### bdev_daos_create {#rpc_bdev_daos_create} 12592 12593Construct @ref bdev_config_daos 12594 12595#### Parameters 12596 12597Name | Optional | Type | Description 12598----------------------- | -------- | ----------- | ----------- 12599name | Required | string | Bdev name to use 12600pool | Required | string | DAOS pool label or its uuid 12601cont | Required | string | DAOS cont label or its uuid 12602block_size | Required | number | Block size in bytes -must be multiple of 512 12603num_blocks | Required | number | Number of blocks 12604uuid | Optional | string | UUID of new bdev 12605oclass | Optional | string | DAOS object class (default SX) 12606 12607To find more about various object classes please visit [DAOS documentation](https://github.com/daos-stack/daos/blob/master/src/object/README.md). 12608Please note, that DAOS bdev module uses the same CLI flag notation as `dmg` and `daos` commands, 12609for instance, `SX` or `EC_4P2G2` rather than in DAOS header file `OC_SX` or `OC_EC_4P2G2`. 12610 12611#### Result 12612 12613Name of newly created bdev. 12614 12615#### Example 12616 12617Example request: 12618 12619~~~json 12620{ 12621 "params": { 12622 "block_size": 4096, 12623 "num_blocks": 16384, 12624 "name": "daosdev0", 12625 "pool": "test-pool", 12626 "cont": "test-cont", 12627 "oclass": "EC_4P2G2" 12628 }, 12629 "jsonrpc": "2.0", 12630 "method": "bdev_daos_create", 12631 "id": 1 12632} 12633~~~ 12634 12635Example response: 12636 12637~~~json 12638{ 12639 "jsonrpc": "2.0", 12640 "id": 1, 12641 "result": "daosdev0" 12642} 12643~~~ 12644 12645### bdev_daos_delete {#rpc_bdev_daos_delete} 12646 12647Delete @ref bdev_config_daos 12648 12649#### Parameters 12650 12651Name | Optional | Type | Description 12652----------------------- | -------- | ----------- | ----------- 12653name | Required | string | Bdev name 12654 12655#### Example 12656 12657Example request: 12658 12659~~~json 12660{ 12661 "params": { 12662 "name": "daosdev0" 12663 }, 12664 "jsonrpc": "2.0", 12665 "method": "bdev_daos_delete", 12666 "id": 1 12667} 12668~~~ 12669 12670Example response: 12671 12672~~~json 12673{ 12674 "jsonrpc": "2.0", 12675 "id": 1, 12676 "result": true 12677} 12678~~~ 12679 12680### bdev_daos_resize {#rpc_bdev_daos_resize} 12681 12682Resize @ref bdev_config_daos. 12683 12684#### Parameters 12685 12686Name | Optional | Type | Description 12687----------------------- | -------- | ----------- | ----------- 12688name | Required | string | Bdev name 12689new_size | Required | number | Bdev new capacity in MiB 12690 12691#### Example 12692 12693Example request: 12694 12695~~~json 12696{ 12697 "params": { 12698 "name": "daosdev0", 12699 "new_size": 8192 12700 }, 12701 "jsonrpc": "2.0", 12702 "method": "bdev_daos_resize", 12703 "id": 1 12704} 12705~~~ 12706 12707Example response: 12708 12709~~~json 12710{ 12711 "jsonrpc": "2.0", 12712 "id": 1, 12713 "result": true 12714} 12715~~~ 12716 12717### iobuf_set_options {#rpc_iobuf_set_options} 12718 12719Set iobuf buffer pool options. 12720 12721#### Parameters 12722 12723Name | Optional | Type | Description 12724----------------------- | -------- | ----------- | ----------- 12725small_pool_count | Optional | number | Number of small buffers in the global pool 12726large_pool_count | Optional | number | Number of large buffers in the global pool 12727small_bufsize | Optional | number | Size of a small buffer 12728large_bufsize | Optional | number | Size of a small buffer 12729 12730#### Example 12731 12732Example request: 12733 12734~~~json 12735{ 12736 "jsonrpc": "2.0", 12737 "id": 1, 12738 "method": "iobuf_set_options", 12739 "params": { 12740 "small_pool_count": 16383, 12741 "large_pool_count": 2047 12742 } 12743} 12744~~~ 12745 12746Example response: 12747 12748~~~json 12749{ 12750 "jsonrpc": "2.0", 12751 "id": 1, 12752 "result": true 12753} 12754~~~ 12755 12756### iobuf_get_stats {#rpc_iobuf_get_stats} 12757 12758Retrieve iobuf's statistics. 12759 12760#### Parameters 12761 12762None. 12763 12764#### Example 12765 12766Example request: 12767 12768~~~json 12769{ 12770 "jsonrpc": "2.0", 12771 "method": "iobuf_get_stats", 12772 "id": 1 12773} 12774~~~ 12775 12776Example response: 12777 12778~~~json 12779{ 12780 "jsonrpc": "2.0", 12781 "id": 1, 12782 "result": [ 12783 { 12784 "module": "accel", 12785 "small_pool": { 12786 "cache": 0, 12787 "main": 0, 12788 "retry": 0 12789 }, 12790 "large_pool": { 12791 "cache": 0, 12792 "main": 0, 12793 "retry": 0 12794 } 12795 }, 12796 { 12797 "module": "bdev", 12798 "small_pool": { 12799 "cache": 421965, 12800 "main": 1218, 12801 "retry": 0 12802 }, 12803 "large_pool": { 12804 "cache": 0, 12805 "main": 0, 12806 "retry": 0 12807 } 12808 }, 12809 { 12810 "module": "nvmf_TCP", 12811 "small_pool": { 12812 "cache": 7, 12813 "main": 0, 12814 "retry": 0 12815 }, 12816 "large_pool": { 12817 "cache": 0, 12818 "main": 0, 12819 "retry": 0 12820 } 12821 } 12822 ] 12823} 12824~~~ 12825 12826### bdev_nvme_start_mdns_discovery {#rpc_bdev_nvme_start_mdns_discovery} 12827 12828Starts an mDNS based discovery service for the specified service type for the 12829auto-discovery of discovery controllers (NVMe TP-8009). 12830 12831The discovery service will listen for the mDNS discovery events from the 12832Avahi-daemon and will connect to the newly learnt discovery controllers. 12833Then the discovery service will automatically attach to any subsystem found in the 12834discovery log page from the discovery controllers learnt using mDNS. 12835When determining a controller name to use when attaching, it will use 12836the 'name' parameter as a prefix, followed by a unique integer assigned for each of the 12837discovery controllers learnt through mDNS, followed by a unique integer for that discovery 12838service. If the discovery service identifies a subsystem that has been previously 12839attached but is listed with a different path, it will use the same controller name 12840as the previous entry, and connect as a multipath. 12841 12842When the discovery service sees that a subsystem entry has been removed 12843from the log page, it will automatically detach from that controller as well. 12844 12845The 'name' is also used to later stop the discovery service. 12846 12847#### Parameters 12848 12849Name | Optional | Type | Description 12850-------------------------- | -------- | ----------- | ----------- 12851name | Required | string | Prefix for NVMe discovery services found 12852svcname | Required | string | Service to discover: e.g. _nvme-disc._tcp 12853hostnqn | Optional | string | NVMe-oF hostnqn 12854 12855#### Example 12856 12857Example request: 12858 12859~~~json 12860{ 12861 "jsonrpc": "2.0", 12862 "method": "bdev_nvme_start_mdns_discovery", 12863 "id": 1, 12864 "params": { 12865 "name": "cdc_auto", 12866 "svcname": "_nvme-disc._tcp", 12867 "hostnqn": "nqn.2021-12.io.spdk:host1", 12868 } 12869} 12870~~~ 12871 12872Example response: 12873 12874~~~json 12875{ 12876 "jsonrpc": "2.0", 12877 "id": 1, 12878 "result": true 12879} 12880~~~ 12881 12882### bdev_nvme_stop_mdns_discovery {#rpc_bdev_nvme_stop_mdns_discovery} 12883 12884Stops a mDNS discovery service. This includes detaching any controllers that were 12885discovered via the service that is being stopped. 12886 12887#### Parameters 12888 12889Name | Optional | Type | Description 12890-------------------------- | -------- | ----------- | ----------- 12891name | Required | string | Name of mDNS discovery instance to stop 12892 12893#### Example 12894 12895Example request: 12896 12897~~~json 12898{ 12899 "jsonrpc": "2.0", 12900 "method": "bdev_nvme_stop_mdns_discovery", 12901 "id": 1, 12902 "params": { 12903 "name": "cdc_auto" 12904 } 12905} 12906~~~ 12907 12908Example response: 12909 12910~~~json 12911{ 12912 "jsonrpc": "2.0", 12913 "id": 1, 12914 "result": true 12915} 12916~~~ 12917 12918### bdev_nvme_get_mdns_discovery_info {#rpc_bdev_nvme_get_mdns_discovery_info} 12919 12920Get the information about the mDNS discovery service instances. 12921 12922#### Example 12923 12924Example request: 12925~~~json 12926{ 12927 "jsonrpc": "2.0", 12928 "method": "bdev_nvme_get_mdns_discovery_info", 12929 "id": 1 12930} 12931~~~ 12932 12933Example response: 12934 12935~~~json 12936[ 12937 { 12938 "name": "cdc_auto", 12939 "svcname": "_nvme-disc._tcp", 12940 "referrals": [ 12941 { 12942 "name": "cdc_auto0", 12943 "trid": { 12944 "trtype": "TCP", 12945 "adrfam": "IPv4", 12946 "traddr": "66.1.2.21", 12947 "trsvcid": "8009", 12948 "subnqn": "nqn.2014-08.org.nvmexpress.discovery" 12949 } 12950 }, 12951 { 12952 "name": "cdc_auto1", 12953 "trid": { 12954 "trtype": "TCP", 12955 "adrfam": "IPv4", 12956 "traddr": "66.1.1.21", 12957 "trsvcid": "8009", 12958 "subnqn": "nqn.2014-08.org.nvmexpress.discovery" 12959 } 12960 } 12961 ] 12962 } 12963] 12964~~~ 12965 12966### keyring_file_add_key {#rpc_keyring_file_add_key} 12967 12968Add a file-based key to a keyring. 12969 12970#### Parameters 12971 12972Name | Optional | Type | Description 12973-------------------------- | -------- | ----------- | ----------- 12974name | Required | string | Name of the key to add. 12975path | Required | string | Path to a file containing the key. 12976 12977#### Example 12978 12979Example request: 12980 12981~~~json 12982{ 12983 "jsonrpc": "2.0", 12984 "method": "keyring_file_add_key", 12985 "id": 1 12986 "params": { 12987 "name": "key0", 12988 "path": "/path/to/key0" 12989 } 12990} 12991~~~ 12992 12993Example response: 12994 12995~~~json 12996{ 12997 "jsonrpc": "2.0", 12998 "id": 1, 12999 "result": true 13000} 13001~~~ 13002 13003### keyring_file_remove_key {#rpc_keyring_file_remove_key} 13004 13005Remove a file-based key from a keyring. 13006 13007#### Parameters 13008 13009Name | Optional | Type | Description 13010-------------------------- | -------- | ----------- | ----------- 13011name | Required | string | Name of the key to remove. 13012 13013#### Example 13014 13015Example request: 13016 13017~~~json 13018{ 13019 "jsonrpc": "2.0", 13020 "method": "keyring_file_remove_key", 13021 "id": 1 13022 "params": { 13023 "name": "key0" 13024 } 13025} 13026~~~ 13027 13028Example response: 13029 13030~~~json 13031{ 13032 "jsonrpc": "2.0", 13033 "id": 1, 13034 "result": true 13035} 13036~~~ 13037 13038### keyring_get_keys {#rpc_keyring_get_keys} 13039 13040Get a list of available keys. This RPC will only list keys that are currently attached to a 13041keyring. Dynamically loaded keys (via the `probe_key()` callback) will only be included if they're 13042currently in-use (i.e. with active references obtained via `spdk_keyring_get_key()`). 13043 13044#### Example 13045 13046Example request: 13047~~~json 13048{ 13049 "jsonrpc": "2.0", 13050 "method": "keyring_get_keys", 13051 "id": 1 13052} 13053~~~ 13054 13055Example response: 13056 13057~~~json 13058{ 13059 "jsonrpc": "2.0", 13060 "id": 1, 13061 "result": [ 13062 { 13063 "name": "key0", 13064 "module": "keyring_file", 13065 "removed": false, 13066 "probed": false, 13067 "refcnt": 1, 13068 "path": "/path/to/key0" 13069 }, 13070 { 13071 "name": "key1", 13072 "module": "keyring_file", 13073 "removed": false, 13074 "probed": false, 13075 "refcnt": 1, 13076 "path": "/path/to/key1" 13077 } 13078 ] 13079} 13080~~~ 13081 13082### keyring_linux_set_options {#keyring_linux_set_options} 13083 13084Set options of the keyring_linux module. 13085 13086#### Parameters 13087 13088Name | Optional | Type | Description 13089----------------------- | -------- | ----------- | ----------- 13090enable | Optional | boolean | Enable the module. 13091 13092#### Example 13093 13094Example request: 13095~~~json 13096{ 13097 "jsonrpc": "2.0", 13098 "method": "keyring_linux_set_options", 13099 "id": 1 13100 "params": { 13101 "enable": true 13102 } 13103} 13104~~~ 13105 13106Example response: 13107 13108~~~json 13109{ 13110 "jsonrpc": "2.0", 13111 "id": 1, 13112 "result": true 13113} 13114~~~ 13115