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. 4054 4055#### Example 4056 4057Example request: 4058 4059~~~json 4060{ 4061 "params": { 4062 "trtype": "pcie", 4063 "name": "Nvme0", 4064 "traddr": "0000:0a:00.0" 4065 }, 4066 "jsonrpc": "2.0", 4067 "method": "bdev_nvme_attach_controller", 4068 "id": 1 4069} 4070~~~ 4071 4072Example response: 4073 4074~~~json 4075{ 4076 "jsonrpc": "2.0", 4077 "id": 1, 4078 "result": [ 4079 "Nvme0n1" 4080 ] 4081} 4082~~~ 4083 4084### bdev_nvme_get_controllers {#rpc_bdev_nvme_get_controllers} 4085 4086Get information about NVMe controllers. 4087 4088#### Parameters 4089 4090The user may specify no parameters in order to list all NVMe controllers, or one NVMe controller may be 4091specified by name. 4092 4093Name | Optional | Type | Description 4094----------------------- | -------- | ----------- | ----------- 4095name | Optional | string | NVMe controller name 4096 4097#### Response 4098 4099The response is an array of objects containing information about the requested NVMe controllers. 4100 4101#### Example 4102 4103Example request: 4104 4105~~~json 4106{ 4107 "jsonrpc": "2.0", 4108 "id": 1, 4109 "method": "bdev_nvme_get_controllers", 4110 "params": { 4111 "name": "Nvme0" 4112 } 4113} 4114~~~ 4115 4116Example response: 4117 4118~~~json 4119{ 4120 "jsonrpc": "2.0", 4121 "id": 1, 4122 "result": [ 4123 { 4124 "name": "Nvme0", 4125 "trid": { 4126 "trtype": "PCIe", 4127 "traddr": "0000:05:00.0" 4128 }, 4129 "cntlid": 0 4130 } 4131 ] 4132} 4133~~~ 4134 4135### bdev_nvme_detach_controller {#rpc_bdev_nvme_detach_controller} 4136 4137Detach NVMe controller and delete any associated bdevs. Optionally, 4138If all of the transport ID options are specified, only remove that 4139transport path from the specified controller. If that is the only 4140available path for the controller, this will also result in the 4141controller being detached and the associated bdevs being deleted. 4142 4143returns true if the controller and bdevs were successfully destroyed 4144or the address was properly removed, false otherwise. 4145 4146#### Parameters 4147 4148Name | Optional | Type | Description 4149----------------------- | -------- | ----------- | ----------- 4150name | Required | string | Controller name 4151trtype | Optional | string | NVMe-oF target trtype: rdma or tcp 4152traddr | Optional | string | NVMe-oF target address: ip or BDF 4153adrfam | Optional | string | NVMe-oF target adrfam: ipv4, ipv6, ib, fc, intra_host 4154trsvcid | Optional | string | NVMe-oF target trsvcid: port number 4155subnqn | Optional | string | NVMe-oF target subnqn 4156hostaddr | Optional | string | NVMe-oF host address: ip 4157hostsvcid | Optional | string | NVMe-oF host svcid: port number 4158 4159#### Example 4160 4161Example requests: 4162 4163~~~json 4164{ 4165 "params": { 4166 "name": "Nvme0" 4167 }, 4168 "jsonrpc": "2.0", 4169 "method": "bdev_nvme_detach_controller", 4170 "id": 1 4171} 4172~~~ 4173 4174Example response: 4175 4176~~~json 4177{ 4178 "jsonrpc": "2.0", 4179 "id": 1, 4180 "result": true 4181} 4182~~~ 4183 4184### bdev_nvme_reset_controller {#rpc_bdev_nvme_reset_controller} 4185 4186For non NVMe multipath, reset an NVMe controller whose name is given by the `name` parameter. 4187 4188For NVMe multipath, an NVMe bdev controller is created and it aggregates multiple NVMe controllers. 4189The `name` parameter is an NVMe bdev controller name and the `cntlid` parameter is used to identify 4190an NVMe controller in the NVMe bdev controller. Reset only one NVMe-oF controller if the `cntlid` 4191parameter is specified, or all NVMe-oF controllers in an NVMe bdev controller if it is omitted. 4192 4193Returns true if the controller reset was successful, false otherwise. 4194 4195#### Parameters 4196 4197Name | Optional | Type | Description 4198----------------------- | -------- | ----------- | ----------- 4199name | Required | string | NVMe controller name (or NVMe bdev controller name for multipath) 4200cntlid | Optional | number | NVMe controller ID (used as NVMe controller name for multipath) 4201 4202#### Example 4203 4204Example request: 4205 4206~~~json 4207{ 4208 "jsonrpc": "2.0", 4209 "id": 1, 4210 "method": "bdev_nvme_reset_controller", 4211 "params": { 4212 "name": "Nvme0" 4213 } 4214} 4215~~~ 4216 4217Example response: 4218 4219~~~json 4220{ 4221 "jsonrpc": "2.0", 4222 "id": 1, 4223 "result": true 4224} 4225~~~ 4226 4227### bdev_nvme_enable_controller {#rpc_bdev_nvme_enable_controller} 4228 4229For non NVMe multipath, enable an NVMe controller whose name is given by the `name` parameter. 4230 4231For NVMe multipath, an NVMe bdev controller is created and it aggregates multiple NVMe controllers. 4232The `name` parameter is an NVMe bdev controller name and the `cntlid` parameter is used to identify 4233an NVMe controller in the NVMe bdev controller. Enable only one NVMe-oF controller if the `cntlid` 4234parameter is specified, or all NVMe-oF controllers in an NVMe bdev controller if it is omitted. 4235 4236Returns true if the controller enablement was successful or a controller was already enabled, false otherwise. 4237 4238#### Parameters 4239 4240Name | Optional | Type | Description 4241----------------------- | -------- | ----------- | ----------- 4242name | Required | string | NVMe controller name (or NVMe bdev controller name for multipath) 4243cntlid | Optional | number | NVMe controller ID (used as NVMe controller name for multipath) 4244 4245#### Example 4246 4247Example request: 4248 4249~~~json 4250{ 4251 "jsonrpc": "2.0", 4252 "id": 1, 4253 "method": "bdev_nvme_enable_controller", 4254 "params": { 4255 "name": "Nvme0" 4256 } 4257} 4258~~~ 4259 4260Example response: 4261 4262~~~json 4263{ 4264 "jsonrpc": "2.0", 4265 "id": 1, 4266 "result": true 4267} 4268~~~ 4269 4270### bdev_nvme_disable_controller {#rpc_bdev_nvme_disable_controller} 4271 4272For non NVMe multipath, disable an NVMe controller whose name is given by the `name` parameter. 4273 4274For NVMe multipath, an NVMe bdev controller is created and it aggregates multiple NVMe controllers. 4275The `name` parameter is an NVMe bdev controller name and the `cntlid` parameter is used to identify 4276an NVMe controller in the NVMe bdev controller. Disable only one NVMe-oF controller if the `cntlid` 4277parameter is specified, or all NVMe-oF controllers in an NVMe bdev controller if it is omitted. 4278 4279Returns true if the controller disablement was successful or a controller was already disabled, false otherwise. 4280 4281#### Parameters 4282 4283Name | Optional | Type | Description 4284----------------------- | -------- | ----------- | ----------- 4285name | Required | string | NVMe controller name (or NVMe bdev controller name for multipath) 4286cntlid | Optional | number | NVMe controller ID (used as NVMe controller name for multipath) 4287 4288#### Example 4289 4290Example request: 4291 4292~~~json 4293{ 4294 "jsonrpc": "2.0", 4295 "id": 1, 4296 "method": "bdev_nvme_disable_controller", 4297 "params": { 4298 "name": "Nvme0" 4299 } 4300} 4301~~~ 4302 4303Example response: 4304 4305~~~json 4306{ 4307 "jsonrpc": "2.0", 4308 "id": 1, 4309 "result": true 4310} 4311~~~ 4312 4313### bdev_nvme_start_discovery {#rpc_bdev_nvme_start_discovery} 4314 4315Start a discovery service for the discovery subsystem of the specified transport ID. 4316 4317The discovery service will read the discovery log page for the specified 4318discovery subsystem, and automatically attach to any subsystems found in the 4319log page. When determining a controller name to use when attaching, it will use 4320the 'name' parameter as a prefix, followed by a unique integer for that discovery 4321service. If the discovery service identifies a subsystem that has been previously 4322attached but is listed with a different path, it will use the same controller name 4323as the previous entry, and connect as a multipath. 4324 4325When the discovery service sees that a subsystem entry has been removed 4326from the log page, it will automatically detach from that controller as well. 4327 4328The 'name' is also used to later stop the discovery service. 4329 4330#### Parameters 4331 4332Name | Optional | Type | Description 4333-------------------------- | -------- | ----------- | ----------- 4334name | Required | string | Prefix for NVMe controllers 4335trtype | Required | string | NVMe-oF target trtype: rdma or tcp 4336traddr | Required | string | NVMe-oF target address: ip 4337adrfam | Optional | string | NVMe-oF target adrfam: ipv4, ipv6 4338trsvcid | Optional | string | NVMe-oF target trsvcid: port number 4339hostnqn | Optional | string | NVMe-oF target hostnqn 4340wait_for_attach | Optional | bool | Wait to complete until all discovered NVM subsystems are attached 4341attach_timeout_ms | Optional | number | Time to wait until the discovery and all discovered NVM subsystems are attached 4342ctrlr_loss_timeout_sec | Optional | number | Time to wait until ctrlr is reconnected before deleting ctrlr. -1 means infinite reconnects. 0 means no reconnect. 4343reconnect_delay_sec | Optional | number | Time to delay a reconnect trial. 0 means no reconnect. 4344fast_io_fail_timeout_sec | Optional | number | Time to wait until ctrlr is reconnected before failing I/O to ctrlr. 0 means no such timeout. 4345 4346#### Example 4347 4348Example request: 4349 4350~~~json 4351{ 4352 "jsonrpc": "2.0", 4353 "method": "bdev_nvme_start_discovery", 4354 "id": 1, 4355 "params": { 4356 "name": "nvme_auto", 4357 "trtype": "tcp", 4358 "traddr": "127.0.0.1", 4359 "hostnqn": "nqn.2021-12.io.spdk:host1", 4360 "adrfam": "ipv4", 4361 "trsvcid": "4420" 4362 } 4363} 4364~~~ 4365 4366Example response: 4367 4368~~~json 4369{ 4370 "jsonrpc": "2.0", 4371 "id": 1, 4372 "result": true 4373} 4374~~~ 4375 4376### bdev_nvme_stop_discovery {#rpc_bdev_nvme_stop_discovery} 4377 4378Stop a discovery service. This includes detaching any controllers that were 4379discovered via the service that is being stopped. 4380 4381#### Parameters 4382 4383Name | Optional | Type | Description 4384-------------------------- | -------- | ----------- | ----------- 4385name | Required | string | Name of service to stop 4386 4387#### Example 4388 4389Example request: 4390 4391~~~json 4392{ 4393 "jsonrpc": "2.0", 4394 "method": "bdev_nvme_stop_discovery", 4395 "id": 1, 4396 "params": { 4397 "name": "nvme_auto" 4398 } 4399} 4400~~~ 4401 4402Example response: 4403 4404~~~json 4405{ 4406 "jsonrpc": "2.0", 4407 "id": 1, 4408 "result": true 4409} 4410~~~ 4411 4412### bdev_nvme_get_discovery_info {#rpc_bdev_nvme_get_discovery_info} 4413 4414Get information about the discovery service. 4415 4416#### Example 4417 4418Example request: 4419~~~json 4420{ 4421 "jsonrpc": "2.0", 4422 "method": "bdev_nvme_get_discovery_info", 4423 "id": 1 4424} 4425~~~ 4426 4427Example response: 4428 4429~~~json 4430{ 4431 "jsonrpc": "2.0", 4432 "id": 1, 4433 "result": [ 4434 { 4435 "name": "nvme-disc", 4436 "trid": { 4437 "trtype": "TCP", 4438 "adrfam": "IPv4", 4439 "traddr": "127.0.0.1", 4440 "trsvcid": "8009", 4441 "subnqn": "nqn.2014-08.org.nvmexpress.discovery" 4442 }, 4443 "referrals": [] 4444 } 4445 ] 4446} 4447~~~ 4448 4449### bdev_nvme_get_io_paths {#rpc_bdev_nvme_get_io_paths} 4450 4451Display all or the specified NVMe bdev's active I/O paths. 4452 4453#### Parameters 4454 4455Name | Optional | Type | Description 4456----------------------- | -------- | ----------- | ----------- 4457name | Optional | string | Name of the NVMe bdev 4458 4459#### Example 4460 4461Example request: 4462 4463~~~json 4464{ 4465 "jsonrpc": "2.0", 4466 "method": "bdev_nvme_get_io_paths", 4467 "id": 1, 4468 "params": { 4469 "name": "Nvme0n1" 4470 } 4471} 4472~~~ 4473 4474Example response: 4475 4476~~~json 4477{ 4478 "jsonrpc": "2.0", 4479 "id": 1, 4480 "result": { 4481 "poll_groups": [ 4482 { 4483 "thread": "app_thread", 4484 "io_paths": [ 4485 { 4486 "bdev_name": "Nvme0n1", 4487 "cntlid": 0, 4488 "current": true, 4489 "connected": true, 4490 "accessible": true, 4491 "transport": { 4492 "trtype": "RDMA", 4493 "traddr": "1.2.3.4", 4494 "trsvcid": "4420", 4495 "adrfam": "IPv4" 4496 } 4497 } 4498 ] 4499 } 4500 ] 4501 } 4502} 4503~~~ 4504 4505### bdev_nvme_set_preferred_path {#rpc_bdev_nvme_set_preferred_path} 4506 4507Set the preferred I/O path for an NVMe bdev in multipath mode. 4508 4509NOTE: This RPC does not support NVMe bdevs in failover mode. 4510 4511#### Parameters 4512 4513Name | Optional | Type | Description 4514----------------------- | -------- | ----------- | ----------- 4515name | Required | string | Name of the NVMe bdev 4516cntlid | Required | number | NVMe-oF controller ID 4517 4518#### Example 4519 4520Example request: 4521 4522~~~json 4523{ 4524 "jsonrpc": "2.0", 4525 "method": "bdev_nvme_set_preferred_path", 4526 "id": 1, 4527 "params": { 4528 "name": "Nvme0n1", 4529 "cntlid": 0 4530 } 4531} 4532~~~ 4533 4534Example response: 4535 4536~~~json 4537{ 4538 "jsonrpc": "2.0", 4539 "id": 1, 4540 "result": true 4541} 4542~~~ 4543 4544### bdev_nvme_set_multipath_policy {#rpc_bdev_nvme_set_multipath_policy} 4545 4546Set multipath policy of the NVMe bdev in multipath mode or set multipath 4547selector for active-active multipath policy. 4548 4549#### Parameters 4550 4551Name | Optional | Type | Description 4552----------------------- | -------- | ----------- | ----------- 4553name | Required | string | Name of the NVMe bdev 4554policy | Required | string | Multipath policy: active_active or active_passive 4555selector | Optional | string | Multipath selector: round_robin or queue_depth, used in active-active mode. Default is round_robin 4556rr_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. 4557 4558#### Example 4559 4560Example request: 4561 4562~~~json 4563{ 4564 "jsonrpc": "2.0", 4565 "method": "bdev_nvme_set_multipath_policy", 4566 "id": 1, 4567 "params": { 4568 "name": "Nvme0n1", 4569 "policy": "active_passive" 4570 } 4571} 4572~~~ 4573 4574Example response: 4575 4576~~~json 4577{ 4578 "jsonrpc": "2.0", 4579 "id": 1, 4580 "result": true 4581} 4582~~~ 4583 4584### bdev_nvme_get_path_iostat {#rpc_bdev_nvme_get_path_iostat} 4585 4586Get I/O statistics for IO paths of the block device. Call RPC bdev_nvme_set_options to set enable_io_path_stat 4587true before using this RPC. 4588 4589#### Parameters 4590 4591Name | Optional | Type | Description 4592----------------------- | -------- | ----------- | ----------- 4593name | Required | string | Name of the NVMe bdev 4594 4595#### Example 4596 4597Example request: 4598 4599~~~json 4600{ 4601 "jsonrpc": "2.0", 4602 "method": "bdev_nvme_get_path_iostat", 4603 "id": 1, 4604 "params": { 4605 "name": "NVMe0n1" 4606 } 4607} 4608~~~ 4609 4610Example response: 4611 4612~~~json 4613{ 4614 "jsonrpc": "2.0", 4615 "id": 1, 4616 "result": { 4617 "name": "NVMe0n1", 4618 "stats": [ 4619 { 4620 "trid": { 4621 "trtype": "TCP", 4622 "adrfam": "IPv4", 4623 "traddr": "10.169.204.201", 4624 "trsvcid": "4420", 4625 "subnqn": "nqn.2016-06.io.spdk:cnode1" 4626 }, 4627 "stat": { 4628 "bytes_read": 676691968, 4629 "num_read_ops": 165201, 4630 "bytes_written": 0, 4631 "num_write_ops": 0, 4632 "bytes_unmapped": 0, 4633 "num_unmap_ops": 0, 4634 "max_read_latency_ticks": 521487, 4635 "min_read_latency_ticks": 0, 4636 "write_latency_ticks": 0, 4637 "max_write_latency_ticks": 0, 4638 "min_write_latency_ticks": 0, 4639 "unmap_latency_ticks": 0, 4640 "max_unmap_latency_ticks": 0, 4641 "min_unmap_latency_ticks": 0, 4642 "copy_latency_ticks": 0, 4643 "max_copy_latency_ticks": 0, 4644 "min_copy_latency_ticks": 0 4645 } 4646 }, 4647 { 4648 "trid": { 4649 "trtype": "TCP", 4650 "adrfam": "IPv4", 4651 "traddr": "8.8.8.6", 4652 "trsvcid": "4420", 4653 "subnqn": "nqn.2016-06.io.spdk:cnode1" 4654 }, 4655 "stat": { 4656 "bytes_read": 677138432, 4657 "num_read_ops": 165317, 4658 "bytes_written": 0, 4659 "num_write_ops": 0, 4660 "bytes_unmapped": 0, 4661 "num_unmap_ops": 0, 4662 "max_read_latency_ticks": 108525, 4663 "min_read_latency_ticks": 0, 4664 "write_latency_ticks": 0, 4665 "max_write_latency_ticks": 0, 4666 "min_write_latency_ticks": 0, 4667 "unmap_latency_ticks": 0, 4668 "max_unmap_latency_ticks": 0, 4669 "min_unmap_latency_ticks": 0, 4670 "copy_latency_ticks": 0, 4671 "max_copy_latency_ticks": 0, 4672 "min_copy_latency_ticks": 0 4673 } 4674 } 4675 ] 4676 } 4677} 4678~~~ 4679 4680### bdev_nvme_cuse_register {#rpc_bdev_nvme_cuse_register} 4681 4682Register CUSE device on NVMe controller. 4683 4684#### Parameters 4685 4686Name | Optional | Type | Description 4687----------------------- | -------- | ----------- | ----------- 4688name | Required | string | Name of the NVMe controller 4689 4690#### Example 4691 4692Example request: 4693 4694~~~json 4695{ 4696 "jsonrpc": "2.0", 4697 "method": "bdev_nvme_cuse_register", 4698 "id": 1, 4699 "params": { 4700 "name": "Nvme0" 4701 } 4702} 4703~~~ 4704 4705Example response: 4706 4707~~~json 4708{ 4709 "jsonrpc": "2.0", 4710 "id": 1, 4711 "result": true 4712} 4713~~~ 4714 4715### bdev_nvme_cuse_unregister {#rpc_bdev_nvme_cuse_unregister} 4716 4717Unregister CUSE device on NVMe controller. 4718 4719#### Parameters 4720 4721Name | Optional | Type | Description 4722----------------------- | -------- | ----------- | ----------- 4723name | Required | string | Name of the NVMe controller 4724 4725#### Example 4726 4727Example request: 4728 4729~~~json 4730{ 4731 "params": { 4732 "name": "Nvme0" 4733 }, 4734 "jsonrpc": "2.0", 4735 "method": "bdev_nvme_cuse_unregister", 4736 "id": 1 4737} 4738~~~ 4739 4740Example response: 4741 4742~~~json 4743{ 4744 "jsonrpc": "2.0", 4745 "id": 1, 4746 "result": true 4747} 4748~~~ 4749 4750### bdev_zone_block_create {#rpc_bdev_zone_block_create} 4751 4752Creates a virtual zone device on top of existing non-zoned bdev. 4753 4754#### Parameters 4755 4756Name | Optional | Type | Description 4757----------------------- | -------- | ----------- | ----------- 4758name | Required | string | Name of the Zone device 4759base_bdev | Required | string | Name of the Base bdev 4760zone_capacity | Required | number | Zone capacity in blocks 4761optimal_open_zones | Required | number | Number of zones required to reach optimal write speed 4762 4763#### Example 4764 4765Example request: 4766 4767~~~json 4768{ 4769 "jsonrpc": "2.0", 4770 "method": "bdev_zone_block_create", 4771 "id": 1, 4772 "params": { 4773 "name": "zone1", 4774 "base_bdev": "NVMe0n1", 4775 "zone_capacity": 4096, 4776 "optimal_open_zones": 32 4777 } 4778} 4779~~~ 4780 4781Example response: 4782 4783~~~json 4784{ 4785 "jsonrpc": "2.0", 4786 "id": 1, 4787 "result": "zone1" 4788} 4789~~~ 4790 4791### bdev_zone_block_delete {#rpc_bdev_zone_block_delete} 4792 4793Deletes a virtual zone device. 4794 4795#### Parameters 4796 4797Name | Optional | Type | Description 4798----------------------- | -------- | ----------- | ----------- 4799name | Required | string | Name of the Zone device 4800 4801#### Example 4802 4803Example request: 4804 4805~~~json 4806{ 4807 "jsonrpc": "2.0", 4808 "method": "bdev_zone_block_delete", 4809 "id": 1, 4810 "params": { 4811 "name": "zone1" 4812 } 4813} 4814~~~ 4815 4816Example response: 4817 4818~~~json 4819{ 4820 "jsonrpc": "2.0", 4821 "id": 1, 4822 "result": true 4823} 4824~~~ 4825 4826### bdev_nvme_apply_firmware {#rpc_bdev_nvme_apply_firmware} 4827 4828Download and commit firmware to NVMe device. 4829 4830#### Parameters 4831 4832Name | Optional | Type | Description 4833----------------------- | -------- | ----------- | ----------- 4834filename | Required | string | filename of the firmware to download 4835bdev_name | Required | string | Name of the NVMe block device 4836 4837#### Example 4838 4839Example request: 4840 4841~~~json 4842{ 4843 "jsonrpc": "2.0", 4844 "method": "bdev_nvme_apply_firmware", 4845 "id": 1, 4846 "params": { 4847 "filename": "firmware_file", 4848 "bdev_name": "NVMe0n1" 4849 } 4850} 4851~~~ 4852 4853### bdev_nvme_get_transport_statistics {#rpc_bdev_nvme_get_transport_statistics} 4854 4855Get bdev_nvme poll group transport statistics. 4856 4857#### Parameters 4858 4859This RPC method accepts no parameters 4860 4861#### Response 4862 4863The response is an array of objects containing information about transport statistics per NVME poll group. 4864 4865#### Example 4866 4867Example request: 4868 4869~~~json 4870{ 4871 "jsonrpc": "2.0", 4872 "id": 1, 4873 "method": "bdev_nvme_get_transport_statistics", 4874} 4875~~~ 4876 4877Example response: 4878 4879~~~json 4880{ 4881 "jsonrpc": "2.0", 4882 "id": 1, 4883 "result": { 4884 "poll_groups": [ 4885 { 4886 "thread": "nvmf_tgt_poll_group_0", 4887 "transports": [ 4888 { 4889 "trname": "RDMA", 4890 "devices": [ 4891 { 4892 "dev_name": "mlx5_1", 4893 "polls": 137492169, 4894 "idle_polls": 137492169, 4895 "completions": 0, 4896 "queued_requests": 0, 4897 "total_send_wrs": 0, 4898 "send_sq_doorbell_updates": 0, 4899 "total_recv_wrs": 0, 4900 "recv_sq_doorbell_updates": 0 4901 }, 4902 { 4903 "dev_name": "mlx5_0", 4904 "polls": 137985185, 4905 "idle_polls": 137492169, 4906 "completions": 1474593, 4907 "queued_requests": 0, 4908 "total_send_wrs": 1474593, 4909 "send_sq_doorbell_updates": 426147, 4910 "total_recv_wrs": 1474721, 4911 "recv_sq_doorbell_updates": 348445 4912 } 4913 ] 4914 }, 4915 { 4916 "trname": "PCIE", 4917 "polls": 435419831, 4918 "idle_polls": 434901004, 4919 "completions": 1485543, 4920 "cq_doorbell_updates": 518827, 4921 "queued_requests": 0, 4922 "submitted_requests": 1485543, 4923 "sq_doorbell_updates": 516081 4924 } 4925 ] 4926 }, 4927 { 4928 "thread": "nvmf_tgt_poll_group_1", 4929 "transports": [ 4930 { 4931 "trname": "RDMA", 4932 "devices": [ 4933 { 4934 "dev_name": "mlx5_1", 4935 "polls": 140245630, 4936 "idle_polls": 140245630, 4937 "completions": 0, 4938 "queued_requests": 0, 4939 "total_send_wrs": 0, 4940 "send_sq_doorbell_updates": 0, 4941 "total_recv_wrs": 0, 4942 "recv_sq_doorbell_updates": 0 4943 }, 4944 { 4945 "dev_name": "mlx5_0", 4946 "polls": 140751844, 4947 "idle_polls": 140245630, 4948 "completions": 1489298, 4949 "queued_requests": 0, 4950 "total_send_wrs": 1489298, 4951 "send_sq_doorbell_updates": 433510, 4952 "total_recv_wrs": 1489426, 4953 "recv_sq_doorbell_updates": 357956 4954 } 4955 ] 4956 }, 4957 { 4958 "trname": "PCIE", 4959 "polls": 429044294, 4960 "idle_polls": 428525658, 4961 "completions": 1478730, 4962 "cq_doorbell_updates": 518636, 4963 "queued_requests": 0, 4964 "submitted_requests": 1478730, 4965 "sq_doorbell_updates": 511658 4966 } 4967 ] 4968 } 4969 ] 4970 } 4971} 4972~~~ 4973 4974### bdev_nvme_get_controller_health_info {#rpc_bdev_nvme_get_controller_health_info} 4975 4976Display health log of the required NVMe bdev device. 4977 4978#### Parameters 4979 4980Name | Optional | Type | Description 4981----------------------- | -------- | ----------- | ----------- 4982name | Required | string | Name of the NVMe bdev controller 4983 4984#### Response 4985 4986The response is the object containing information about health log of the NVMe controller. 4987 4988#### Example 4989 4990Example request: 4991 4992~~~json 4993{ 4994 "jsonrpc": "2.0", 4995 "method": "bdev_nvme_get_controller_health_info", 4996 "id": 1, 4997 "params": { 4998 "name": "Nvme0" 4999 } 5000} 5001~~~ 5002 5003Example response: 5004 5005~~~json 5006{ 5007 "model_number": "INTEL SSDPE2KX020T8", 5008 "serial_number": "BTLJ72430ARH2P0BGN", 5009 "firmware_revision": "VDV10110", 5010 "traddr": "0000:08:00.0", 5011 "temperature_celsius": 32, 5012 "available_spare_percentage": 99, 5013 "available_spare_threshold_percentage": 10, 5014 "percentage_used": 2, 5015 "data_units_read": 1013408619, 5016 "data_units_written": 346792685, 5017 "host_read_commands": 30457773282, 5018 "host_write_commands": 18949677715, 5019 "controller_busy_time": 4979, 5020 "power_cycles": 49, 5021 "power_on_hours": 31118, 5022 "unsafe_shutdowns": 18, 5023 "media_errors": 17, 5024 "num_err_log_entries": 19, 5025 "warning_temperature_time_minutes": 0, 5026 "critical_composite_temperature_time_minutes": 0 5027} 5028~~~ 5029 5030### bdev_rbd_register_cluster {#rpc_bdev_rbd_register_cluster} 5031 5032This method is available only if SPDK was build with Ceph RBD support. 5033 5034#### Parameters 5035 5036Name | Optional | Type | Description 5037----------------------- | -------- | ----------- | ----------- 5038name | Required | string | Registered Rados cluster object name 5039user_id | Optional | string | Ceph ID (i.e. admin, not client.admin) 5040config_param | Optional | string map | Explicit librados configuration 5041config_file | Optional | string | File path of libraodos configuration file 5042key_file | Optional | string | File path of libraodos key file 5043 5044This RPC registers a Rados Cluster object handle which is only known 5045to rbd module, it uses user_id + config_param or user_id + config_file + 5046key_file or user_id + config_param + config_file + key_file to identify 5047a Rados cluster object. 5048 5049When accessing the Ceph cluster as some user other than "admin" (the 5050default), the "user_id" has to be set. 5051 5052The configuration items and secret key can be specified by setting config_param, 5053config_file and key_file, all of them, or none of them. If only config_param is 5054passed, all key/value pairs are passed to rados_conf_set to configure cluster access. 5055In practice, "mon_host" (= list of monitor address+port) and "key" (= the secret key 5056stored in Ceph keyrings) are enough. If config_file and key_file are specified, they must 5057exist with all relevant settings for accessing the Ceph cluster. If config_param, config_file 5058and key_file are specified, get the key/value pairs from config_file first and set to 5059rados_conf_set function, then set pairs in config_param and keyring in key_file. If nothing 5060is specified, it will get configuration file and key file from the default location 5061/etc/ceph/ceph.conf and /etc/ceph/ceph.client.user_id.keyring. 5062 5063#### Result 5064 5065Name of newly created Rados cluster object. 5066 5067#### Example 5068 5069Example request: 5070 5071~~ 5072{ 5073 "params": { 5074 "name": "rbd_cluster", 5075 "user_id": cinder, 5076 "config_file": "/root/ceph_conf/ceph.conf", 5077 "key_file": "/root/ceph_conf/ceph.client.cinder.keyring" 5078 }, 5079 "jsonrpc": "2.0", 5080 "method": "bdev_rbd_register_cluster", 5081 "id": 1 5082} 5083~~ 5084 5085Example response: 5086 5087~~ 5088response: 5089{ 5090 "jsonrpc": "2.0", 5091 "id": 1, 5092 "result": "rbd_cluster" 5093} 5094~~ 5095 5096### bdev_rbd_unregister_cluster {#rpc_bdev_rbd_unregister_cluster} 5097 5098This method is available only if SPDK was build with Ceph RBD support. 5099If there is still rbd bdev using this cluster, the unregisteration operation 5100will fail. 5101 5102#### Result 5103 5104`true` if Rados cluster object with provided name was deleted or `false` otherwise. 5105 5106#### Parameters 5107 5108Name | Optional | Type | Description 5109----------------------- | -------- | ----------- | ------------------------- 5110name | Required | string | Rados cluster object name 5111 5112#### Example 5113 5114Example request: 5115 5116~~ 5117{ 5118 "params": { 5119 "name": "rbd_cluster" 5120 }, 5121 "jsonrpc": "2.0", 5122 "method": "bdev_rbd_unregister_cluster", 5123 "id": 1 5124} 5125~~ 5126 5127Example response: 5128 5129~~ 5130{ 5131 "jsonrpc": "2.0", 5132 "id": 1, 5133 "result": true 5134} 5135~~ 5136 5137### bdev_rbd_get_clusters_info {#rpc_bdev_rbd_get_clusters_info} 5138 5139This method is available only if SPDK was build with Ceph RBD support. 5140 5141#### Result 5142 5143Returns the cluster info of the Rados Cluster name if provided. Otherwise, it 5144returns the cluster info of every registered Raods Cluster name. 5145 5146#### Parameters 5147 5148Name | Optional | Type | Description 5149----------------------- | -------- | ----------- | ------------------------- 5150name | Optional | string | Rados cluster object name 5151 5152#### Example 5153 5154Example request: 5155 5156~~ 5157{ 5158 "params": { 5159 "name": "rbd_cluster" 5160 }, 5161 "jsonrpc": "2.0", 5162 "method": "bdev_rbd_get_clusters_info", 5163 "id": 1 5164} 5165~~ 5166 5167Example response: 5168 5169~~ 5170{ 5171 "jsonrpc": "2.0", 5172 "cluster_name": "rbd_cluster" 5173} 5174~~ 5175 5176### bdev_rbd_create {#rpc_bdev_rbd_create} 5177 5178Create @ref bdev_config_rbd bdev 5179 5180This method is available only if SPDK was build with Ceph RBD support. 5181 5182#### Parameters 5183 5184Name | Optional | Type | Description 5185----------------------- | -------- | ----------- | ----------- 5186name | Optional | string | Bdev name 5187user_id | Optional | string | Ceph ID (i.e. admin, not client.admin) 5188pool_name | Required | string | Pool name 5189rbd_name | Required | string | Image name 5190block_size | Required | number | Block size 5191config | Optional | string map | Explicit librados configuration 5192cluster_name | Optional | string | Rados cluster object name created in this module. 5193uuid | Optional | string | UUID of new bdev 5194 5195If no config is specified, Ceph configuration files must exist with 5196all relevant settings for accessing the pool. If a config map is 5197passed, the configuration files are ignored and instead all key/value 5198pairs are passed to rados_conf_set to configure cluster access. In 5199practice, "mon_host" (= list of monitor address+port) and "key" (= the 5200secret key stored in Ceph keyrings) are enough. 5201 5202When accessing the image as some user other than "admin" (the 5203default), the "user_id" has to be set. 5204 5205If provided with cluster_name option, it will use the Rados cluster object 5206referenced by the name (created by bdev_rbd_register_cluster RPC) and ignores 5207"user_id + config" combination to create its own Rados cluster. In this scenario, 5208all the bdevs will share the same cluster with one connection of Ceph in librbd module. 5209Performance tuning on the I/O workload could be done by estimating how many io_contxt 5210threads and messager threads in Ceph side and how many cores would be reasonable to provide 5211for SPDK to get up to your projections. 5212 5213#### Result 5214 5215Name of newly created bdev. 5216 5217#### Example 5218 5219Example request with `key` from `/etc/ceph/ceph.client.admin.keyring`: 5220 5221~~~json 5222{ 5223 "params": { 5224 "pool_name": "rbd", 5225 "rbd_name": "foo", 5226 "config": { 5227 "mon_host": "192.168.7.1:6789,192.168.7.2:6789", 5228 "key": "AQDwf8db7zR1GRAA5k7NKXjS5S5V4mntwUDnGQ==", 5229 } 5230 "block_size": 4096, 5231 "uuid": "76210ea4-7920-40a0-a07b-8992a7443c76" 5232 }, 5233 "jsonrpc": "2.0", 5234 "method": "bdev_rbd_create", 5235 "id": 1 5236} 5237~~~ 5238 5239Example response: 5240 5241~~~json 5242response: 5243{ 5244 "jsonrpc": "2.0", 5245 "id": 1, 5246 "result": "Ceph0" 5247} 5248~~~ 5249 5250Example request with `cluster_name`: 5251 5252~~ 5253{ 5254 "params": { 5255 "pool_name": "rbd", 5256 "rbd_name": "foo", 5257 "block_size": 4096, 5258 "cluster_name": "rbd_cluster" 5259 }, 5260 "jsonrpc": "2.0", 5261 "method": "bdev_rbd_create", 5262 "id": 1 5263} 5264~~ 5265 5266Example response: 5267 5268~~ 5269response: 5270{ 5271 "jsonrpc": "2.0", 5272 "id": 1, 5273 "result": "Ceph0" 5274} 5275~~ 5276 5277### bdev_rbd_delete {#rpc_bdev_rbd_delete} 5278 5279Delete @ref bdev_config_rbd bdev 5280 5281This method is available only if SPDK was build with Ceph RBD support. 5282 5283#### Result 5284 5285`true` if bdev with provided name was deleted or `false` otherwise. 5286 5287#### Parameters 5288 5289Name | Optional | Type | Description 5290----------------------- | -------- | ----------- | ----------- 5291name | Required | string | Bdev name 5292 5293#### Example 5294 5295Example request: 5296 5297~~~json 5298{ 5299 "params": { 5300 "name": "Rbd0" 5301 }, 5302 "jsonrpc": "2.0", 5303 "method": "bdev_rbd_delete", 5304 "id": 1 5305} 5306~~~ 5307 5308Example response: 5309 5310~~~json 5311{ 5312 "jsonrpc": "2.0", 5313 "id": 1, 5314 "result": true 5315} 5316~~~ 5317 5318### bdev_rbd_resize {#rpc_bdev_rbd_resize} 5319 5320Resize @ref bdev_config_rbd bdev 5321 5322This method is available only if SPDK was build with Ceph RBD support. 5323 5324#### Result 5325 5326`true` if bdev with provided name was resized or `false` otherwise. 5327 5328#### Parameters 5329 5330Name | Optional | Type | Description 5331----------------------- | -------- | ----------- | ----------- 5332name | Required | string | Bdev name 5333new_size | Required | int | New bdev size for resize operation in MiB 5334 5335#### Example 5336 5337Example request: 5338 5339~~~json 5340{ 5341 "params": { 5342 "name": "Rbd0" 5343 "new_size": "4096" 5344 }, 5345 "jsonrpc": "2.0", 5346 "method": "bdev_rbd_resize", 5347 "id": 1 5348} 5349~~~ 5350 5351Example response: 5352 5353~~~json 5354{ 5355 "jsonrpc": "2.0", 5356 "id": 1, 5357 "result": true 5358} 5359~~~ 5360 5361### bdev_delay_create {#rpc_bdev_delay_create} 5362 5363Create delay bdev. This bdev type redirects all IO to it's base bdev and inserts a delay on the completion 5364path to create an artificial drive latency. All latency values supplied to this bdev should be in microseconds. 5365 5366#### Parameters 5367 5368Name | Optional | Type | Description 5369----------------------- | -------- | ----------- | ----------- 5370name | Required | string | Bdev name 5371base_bdev_name | Required | string | Base bdev name 5372avg_read_latency | Required | number | average read latency (us) 5373p99_read_latency | Required | number | p99 read latency (us) 5374avg_write_latency | Required | number | average write latency (us) 5375p99_write_latency | Required | number | p99 write latency (us) 5376 5377#### Result 5378 5379Name of newly created bdev. 5380 5381#### Example 5382 5383Example request: 5384 5385~~~json 5386{ 5387 "params": { 5388 "base_bdev_name": "Null0", 5389 "name": "Delay0", 5390 "avg_read_latency": "15", 5391 "p99_read_latency": "50", 5392 "avg_write_latency": "40", 5393 "p99_write_latency": "110", 5394 }, 5395 "jsonrpc": "2.0", 5396 "method": "bdev_delay_create", 5397 "id": 1 5398} 5399~~~ 5400 5401Example response: 5402 5403~~~json 5404{ 5405 "jsonrpc": "2.0", 5406 "id": 1, 5407 "result": "Delay0" 5408} 5409~~~ 5410 5411### bdev_delay_delete {#rpc_bdev_delay_delete} 5412 5413Delete delay bdev. 5414 5415#### Parameters 5416 5417Name | Optional | Type | Description 5418----------------------- | -------- | ----------- | ----------- 5419name | Required | string | Bdev name 5420 5421#### Example 5422 5423Example request: 5424 5425~~~json 5426{ 5427 "params": { 5428 "name": "Delay0" 5429 }, 5430 "jsonrpc": "2.0", 5431 "method": "bdev_delay_delete", 5432 "id": 1 5433} 5434 5435~~~ 5436 5437Example response: 5438 5439~~~json 5440{ 5441 "jsonrpc": "2.0", 5442 "id": 1, 5443 "result": true 5444} 5445~~~ 5446 5447### bdev_delay_update_latency {#rpc_bdev_delay_update_latency} 5448 5449Update a target latency value associated with a given delay bdev. Any currently 5450outstanding I/O will be completed with the old latency. 5451 5452#### Parameters 5453 5454Name | Optional | Type | Description 5455----------------------- | -------- | ----------- | ----------- 5456delay_bdev_name | Required | string | Name of the delay bdev 5457latency_type | Required | string | One of: avg_read, avg_write, p99_read, p99_write 5458latency_us | Required | number | The new latency value in microseconds 5459 5460#### Result 5461 5462Name of newly created bdev. 5463 5464#### Example 5465 5466Example request: 5467 5468~~~json 5469{ 5470 "params": { 5471 "delay_bdev_name": "Delay0", 5472 "latency_type": "avg_read", 5473 "latency_us": "100", 5474 }, 5475 "jsonrpc": "2.0", 5476 "method": "bdev_delay_update_latency", 5477 "id": 1 5478} 5479~~~ 5480 5481Example response: 5482 5483~~~json 5484{ 5485 "result": "true" 5486} 5487~~~ 5488 5489### bdev_error_create {#rpc_bdev_error_create} 5490 5491Construct error bdev. 5492 5493#### Parameters 5494 5495Name | Optional | Type | Description 5496----------------------- | -------- | ----------- | ----------- 5497base_name | Required | string | Base bdev name 5498uuid | Optional | string | UUID for this bdev 5499 5500#### Example 5501 5502Example request: 5503 5504~~~json 5505{ 5506 "params": { 5507 "base_name": "Malloc0" 5508 }, 5509 "jsonrpc": "2.0", 5510 "method": "bdev_error_create", 5511 "id": 1 5512} 5513~~~ 5514 5515Example response: 5516 5517~~~json 5518{ 5519 "jsonrpc": "2.0", 5520 "id": 1, 5521 "result": true 5522} 5523~~~ 5524 5525### bdev_error_delete {#rpc_bdev_error_delete} 5526 5527Delete error bdev 5528 5529#### Result 5530 5531`true` if bdev with provided name was deleted or `false` otherwise. 5532 5533#### Parameters 5534 5535Name | Optional | Type | Description 5536----------------------- | -------- | ----------- | ----------- 5537name | Required | string | Error bdev name 5538 5539#### Example 5540 5541Example request: 5542 5543~~~json 5544{ 5545 "params": { 5546 "name": "EE_Malloc0" 5547 }, 5548 "jsonrpc": "2.0", 5549 "method": "bdev_error_delete", 5550 "id": 1 5551} 5552~~~ 5553 5554Example response: 5555 5556~~~json 5557{ 5558 "jsonrpc": "2.0", 5559 "id": 1, 5560 "result": true 5561} 5562~~~ 5563 5564### bdev_error_inject_error {#rpc_bdev_error_inject_error} 5565 5566Inject an error via an error bdev. Create an error bdev on base bdev first. Default 'num' 5567value is 1 and if 'num' is set to zero, the specified injection is disabled. 5568 5569#### Parameters 5570 5571Name | Optional | Type | Description 5572----------------------- | -------- | ----------- | ----------- 5573name | Required | string | Name of the error injection bdev 5574io_type | Required | string | io type 'clear' 'read' 'write' 'unmap' 'flush' 'all' 5575error_type | Required | string | error type 'failure' 'pending' 'corrupt_data' 'nomem' 5576num | Optional | int | the number of commands you want to fail.(default:1) 5577queue_depth | Optional | int | the queue depth at which to trigger the error 5578corrupt_offset | Optional | int | the offset in bytes to xor with corrupt_value 5579corrupt_value | Optional | int | the value for xor (1-255, 0 is invalid) 5580 5581#### Example 5582 5583Example request: 5584 5585~~~json 5586{ 5587 "jsonrpc": "2.0", 5588 "method": "bdev_error_inject_error", 5589 "id": 1, 5590 "params": { 5591 "name": "EE_Malloc0", 5592 "io_type": "write", 5593 "error_type": "pending", 5594 "num": 1 5595 } 5596} 5597~~~ 5598 5599Example response: 5600 5601~~~json 5602{ 5603 "jsonrpc": "2.0", 5604 "id": 1, 5605 "result": true 5606} 5607~~~ 5608 5609### bdev_iscsi_set_options {#rpc_bdev_iscsi_set_options} 5610 5611This RPC can be called at any time, but the new value will only take effect for new iSCSI bdevs. 5612 5613#### Parameters 5614 5615Name | Optional | Type | Description 5616-------------------------- | -------- | ----------- | ----------- 5617timeout_sec | Optional | number | Timeout for command, in seconds, if 0, don't track timeout 5618 5619#### Example 5620 5621Example request: 5622 5623~~~json 5624request: 5625{ 5626 "params": { 5627 "timeout_sec": 30 5628 }, 5629 "jsonrpc": "2.0", 5630 "method": "bdev_iscsi_set_options", 5631 "id": 1 5632} 5633~~~ 5634 5635Example response: 5636 5637~~~json 5638{ 5639 "jsonrpc": "2.0", 5640 "id": 1, 5641 "result": true 5642} 5643~~~ 5644 5645### bdev_iscsi_create {#rpc_bdev_iscsi_create} 5646 5647Connect to iSCSI target and create bdev backed by this connection. 5648 5649This method is available only if SPDK was build with iSCSI initiator support. 5650 5651#### Parameters 5652 5653Name | Optional | Type | Description 5654----------------------- | -------- | ----------- | ----------- 5655name | Required | string | Bdev name 5656initiator_iqn | Required | string | IQN name used during connection 5657url | Required | string | iSCSI resource URI 5658 5659#### Result 5660 5661Name of newly created bdev. 5662 5663#### Example 5664 5665Example request: 5666 5667~~~json 5668{ 5669 "params": { 5670 "url": "iscsi://127.0.0.1/iqn.2016-06.io.spdk:disk1/0", 5671 "initiator_iqn": "iqn.2016-06.io.spdk:init", 5672 "name": "iSCSI0" 5673 }, 5674 "jsonrpc": "2.0", 5675 "method": "bdev_iscsi_create", 5676 "id": 1 5677} 5678~~~ 5679 5680Example response: 5681 5682~~~json 5683{ 5684 "jsonrpc": "2.0", 5685 "id": 1, 5686 "result": "iSCSI0" 5687} 5688~~~ 5689 5690### bdev_iscsi_delete {#rpc_bdev_iscsi_delete} 5691 5692Delete iSCSI bdev and terminate connection to target. 5693 5694This method is available only if SPDK was built with iSCSI initiator support. 5695 5696#### Parameters 5697 5698Name | Optional | Type | Description 5699----------------------- | -------- | ----------- | ----------- 5700name | Required | string | Bdev name 5701 5702#### Example 5703 5704Example request: 5705 5706~~~json 5707{ 5708 "params": { 5709 "name": "iSCSI0" 5710 }, 5711 "jsonrpc": "2.0", 5712 "method": "bdev_iscsi_delete", 5713 "id": 1 5714} 5715~~~ 5716 5717Example response: 5718 5719~~~json 5720{ 5721 "jsonrpc": "2.0", 5722 "id": 1, 5723 "result": true 5724} 5725~~~ 5726 5727### bdev_ftl_create {#rpc_bdev_ftl_create} 5728 5729Create FTL bdev. 5730 5731This RPC is subject to change. 5732 5733#### Parameters 5734 5735Name | Optional | Type | Description 5736----------------------- | -------- | ----------- | ----------- 5737name | Required | string | Bdev name 5738base_bdev | Required | string | Name of the base device 5739cache | Required | string | Name of the cache device 5740uuid | Optional | string | UUID of restored bdev (not applicable when creating new instance) 5741core_mask | Optional | string | CPU core(s) possible for placement of the ftl core thread, application main thread by default 5742overprovisioning | Optional | int | Percentage of base device used for relocation, 20% by default 5743fast_shutdown | Optional | bool | When set FTL will minimize persisted data on target application shutdown and rely on shared memory during next load 5744 5745#### Result 5746 5747Name of newly created bdev. 5748 5749#### Example 5750 5751Example request: 5752 5753~~~json 5754{ 5755 "params": { 5756 "name": "ftl0", 5757 "base_bdev": "nvme0n1", 5758 "cache": "nvme1n1", 5759 "uuid": "4a7481ce-786f-41a0-9b86-8f7465c8f4d3", 5760 "core_mask": "[0]", 5761 "overprovisioning": 10 5762 }, 5763 "jsonrpc": "2.0", 5764 "method": "bdev_ftl_create", 5765 "id": 1 5766} 5767~~~ 5768 5769Example response: 5770 5771~~~json 5772{ 5773 "jsonrpc": "2.0", 5774 "id": 1, 5775 "result": { 5776 "name" : "ftl0" 5777 "uuid" : "4a7481ce-786f-41a0-9b86-8f7465c8f4d3" 5778 } 5779} 5780~~~ 5781 5782### bdev_ftl_load {#rpc_bdev_ftl_load} 5783 5784Loads FTL bdev. 5785 5786This RPC is subject to change. 5787 5788#### Parameters 5789 5790Name | Optional | Type | Description 5791----------------------- | -------- | ----------- | ----------- 5792name | Required | string | Bdev name 5793base_bdev | Required | string | Name of the base device 5794cache | Required | string | Name of the cache device 5795uuid | Required | string | UUID of restored bdev 5796core_mask | Optional | string | CPU core(s) possible for placement of the ftl core thread, application main thread by default 5797overprovisioning | Optional | int | Percentage of base device used for relocation, 20% by default 5798fast_shutdown | Optional | bool | When set FTL will minimize persisted data on target application shutdown and rely on shared memory during next load 5799 5800#### Result 5801 5802Name of loaded bdev. 5803 5804#### Example 5805 5806Example request: 5807 5808~~~json 5809{ 5810 "params": { 5811 "name": "ftl0", 5812 "base_bdev": "nvme0n1", 5813 "cache": "nvme1n1", 5814 "uuid": "4a7481ce-786f-41a0-9b86-8f7465c8f4d3", 5815 "core_mask": "[0]", 5816 "overprovisioning": 10 5817 }, 5818 "jsonrpc": "2.0", 5819 "method": "bdev_ftl_load", 5820 "id": 1 5821} 5822~~~ 5823 5824Example response: 5825 5826~~~json 5827{ 5828 "jsonrpc": "2.0", 5829 "id": 1, 5830 "result": { 5831 "name" : "ftl0" 5832 "uuid" : "4a7481ce-786f-41a0-9b86-8f7465c8f4d3" 5833 } 5834} 5835~~~ 5836 5837### bdev_ftl_delete {#rpc_bdev_ftl_delete} 5838 5839Delete FTL bdev. 5840 5841This RPC is subject to change. 5842 5843#### Parameters 5844 5845Name | Optional | Type | Description 5846----------------------- | -------- | ----------- | ----------- 5847name | Required | string | Bdev name 5848fast_shutdown | Optional | bool | When set FTL will minimize persisted data during deletion and rely on shared memory during next load 5849 5850#### Example 5851 5852Example request: 5853 5854~~~json 5855{ 5856 "params": { 5857 "name": "ftl0" 5858 }, 5859 "jsonrpc": "2.0", 5860 "method": "bdev_ftl_delete", 5861 "id": 1 5862} 5863~~~ 5864 5865Example response: 5866 5867~~~json 5868{ 5869 "jsonrpc": "2.0", 5870 "id": 1, 5871 "result": true 5872} 5873~~~ 5874 5875### bdev_ftl_unload {#rpc_bdev_ftl_unload} 5876 5877Unloads FTL bdev. 5878 5879This RPC is subject to change. 5880 5881#### Parameters 5882 5883Name | Optional | Type | Description 5884----------------------- | -------- | ----------- | ----------- 5885name | Required | string | Bdev name 5886fast_shutdown | Optional | bool | When set FTL will minimize persisted data during deletion and rely on shared memory during next load 5887 5888#### Example 5889 5890Example request: 5891 5892~~~json 5893{ 5894 "params": { 5895 "name": "ftl0" 5896 }, 5897 "jsonrpc": "2.0", 5898 "method": "bdev_ftl_unload", 5899 "id": 1 5900} 5901~~~ 5902 5903Example response: 5904 5905~~~json 5906{ 5907 "jsonrpc": "2.0", 5908 "id": 1, 5909 "result": true 5910} 5911~~~ 5912 5913### bdev_ftl_unmap {#rpc_bdev_ftl_unmap} 5914 5915Unmap range of LBAs. 5916 5917This RPC is subject to change. 5918 5919#### Parameters 5920 5921Name | Optional | Type | Description 5922----------------------- | -------- | ----------- | ----------- 5923name | Required | string | Bdev name 5924lba | Required | number | start lba, aligned to 1024 5925num_blocks | Required | number | number of blocks, aligned to 1024 5926 5927#### Example 5928 5929Example request: 5930 5931~~~json 5932{ 5933 "params": { 5934 "name": "ftl0" 5935 "lba": "0" 5936 "num_blocks": "1024" 5937 }, 5938 "jsonrpc": "2.0", 5939 "method": "bdev_ftl_unmap", 5940 "id": 1 5941} 5942~~~ 5943 5944Example response: 5945 5946~~~json 5947{ 5948 "jsonrpc": "2.0", 5949 "id": 1, 5950 "result": true 5951} 5952~~~ 5953 5954### bdev_ftl_get_stats {#rpc_bdev_ftl_get_stats} 5955 5956Get IO statistics for FTL bdev 5957 5958This RPC is subject to change. 5959 5960#### Parameters 5961 5962Name | Optional | Type | Description 5963----------------------- | -------- | ----------- | ----------- 5964name | Required | string | Bdev name 5965 5966#### Response 5967 5968The response is an object containing IO statistics for an FTL instance, split into multiple subobjects: 5969 5970- `user` - contains information about number of IOs, and errors for any incoming requests, 5971- `cmp` - information about IO for the compaction process, 5972- `gc` - information about IO for the garbage collection process, 5973- `md_base` - internal metadata requests to the base FTL device, 5974- `md_nv_cache` - internal metadata requests to the cache device, 5975- `l2p` - requests done on the L2P cache region. 5976 5977Each subobject contains the following information: 5978 5979- `ios` - describes the total number of IOs requested, 5980- `blocks` - the total number of requested blocks, 5981- `errors` - describes the number of detected errors for a given operation, with the following distinctions: 5982 - `media` - media errors, 5983 - `crc` - mismatch in calculated CRC versus saved checksum in the metadata, 5984 - `other` - any other errors. 5985 5986#### Example 5987 5988Example request: 5989 5990~~~json 5991{ 5992 "params": { 5993 "name": "ftl0" 5994 }, 5995 "jsonrpc": "2.0", 5996 "method": "bdev_ftl_get_stats", 5997 "id": 1 5998} 5999~~~ 6000 6001Example response: 6002 6003~~~json 6004{ 6005 "jsonrpc": "2.0", 6006 "id": 1, 6007 "result": { 6008 "name": "ftl0", 6009 "user": { 6010 "read": { 6011 "ios": 0, 6012 "blocks": 0, 6013 "errors": { 6014 "media": 0, 6015 "crc": 0, 6016 "other": 0 6017 } 6018 }, 6019 "write": { 6020 "ios": 318707, 6021 "blocks": 318707, 6022 "errors": { 6023 "media": 0, 6024 "other": 0 6025 } 6026 } 6027 }, 6028 "cmp": { 6029 "read": { 6030 "ios": 0, 6031 "blocks": 0, 6032 "errors": { 6033 "media": 0, 6034 "crc": 0, 6035 "other": 0 6036 } 6037 }, 6038 "write": { 6039 "ios": 0, 6040 "blocks": 0, 6041 "errors": { 6042 "media": 0, 6043 "other": 0 6044 } 6045 } 6046 }, 6047 "gc": { 6048 "read": { 6049 "ios": 0, 6050 "blocks": 0, 6051 "errors": { 6052 "media": 0, 6053 "crc": 0, 6054 "other": 0 6055 } 6056 }, 6057 "write": { 6058 "ios": 0, 6059 "blocks": 0, 6060 "errors": { 6061 "media": 0, 6062 "other": 0 6063 } 6064 } 6065 }, 6066 "md_base": { 6067 "read": { 6068 "ios": 0, 6069 "blocks": 0, 6070 "errors": { 6071 "media": 0, 6072 "crc": 0, 6073 "other": 0 6074 } 6075 }, 6076 "write": { 6077 "ios": 1, 6078 "blocks": 32, 6079 "errors": { 6080 "media": 0, 6081 "other": 0 6082 } 6083 } 6084 }, 6085 "md_nv_cache": { 6086 "read": { 6087 "ios": 0, 6088 "blocks": 0, 6089 "errors": { 6090 "media": 0, 6091 "crc": 0, 6092 "other": 0 6093 } 6094 }, 6095 "write": { 6096 "ios": 1064, 6097 "blocks": 1073896, 6098 "errors": { 6099 "media": 0, 6100 "other": 0 6101 } 6102 } 6103 }, 6104 "l2p": { 6105 "read": { 6106 "ios": 240659, 6107 "blocks": 240659, 6108 "errors": { 6109 "media": 0, 6110 "crc": 0, 6111 "other": 0 6112 } 6113 }, 6114 "write": { 6115 "ios": 235745, 6116 "blocks": 235745, 6117 "errors": { 6118 "media": 0, 6119 "other": 0 6120 } 6121 } 6122 } 6123 } 6124} 6125~~~ 6126 6127### bdev_ftl_get_properties {#rpc_bdev_ftl_get_properties} 6128 6129Get FTL properties 6130 6131#### Parameters 6132 6133Name | Optional | Type | Description 6134----------------------- | -------- | ----------- | ----------- 6135name | Required | string | Bdev name 6136 6137#### Response 6138 6139The response contains FTL bdev properties. Some of them can be modified, other 6140reported as read only. 6141 6142#### Example 6143 6144Example request: 6145 6146~~~json 6147{ 6148 "params": { 6149 "name": "ftl0" 6150 }, 6151 "jsonrpc": "2.0", 6152 "method": "bdev_ftl_get_properties", 6153 "id": 1 6154} 6155~~~ 6156 6157Example response: 6158 6159~~~json 6160{ 6161 "jsonrpc": "2.0", 6162 "id": 1, 6163 "result": { 6164 "name": "ftl0", 6165 "properties": [ 6166 { 6167 "name": "property1", 6168 "value": "Property Value 1", 6169 "unit": "MiB/s", 6170 "desc": "This is an example of read-only property", 6171 "read-only": true 6172 }, 6173 { 6174 "name": "property2", 6175 "value": 17, 6176 "unit": "s", 6177 "desc": "This is an example of FTL modifiable property", 6178 "read-only": false 6179 } 6180 ] 6181 } 6182} 6183~~~ 6184 6185### bdev_ftl_set_property {#rpc_bdev_ftl_set_property} 6186 6187Set FTL property. Trying to set a read-only property will result in an error. 6188 6189#### Parameters 6190 6191Name | Optional | Type | Description 6192----------------------- | -------- | ----------- | ----------- 6193name | Required | string | Bdev name 6194property | Required | string | Name of the property to modify 6195value | Required | string | New value of the property to be set 6196 6197#### Example 6198 6199Example request: 6200 6201~~~json 6202{ 6203 "params": { 6204 "name": "ftl0" 6205 "property": "nv_cache.flush" 6206 "value": "true" 6207 }, 6208 "jsonrpc": "2.0", 6209 "method": "bdev_ftl_set_property", 6210 "id": 1 6211} 6212~~~ 6213 6214Example response: 6215 6216~~~json 6217{ 6218 "jsonrpc": "2.0", 6219 "id": 1, 6220 "result": true 6221} 6222~~~ 6223 6224### bdev_passthru_create {#rpc_bdev_passthru_create} 6225 6226Create passthru bdev. This bdev type redirects all IO to it's base bdev. It has no other purpose than being an example 6227and a starting point in development of new bdev type. 6228 6229#### Parameters 6230 6231Name | Optional | Type | Description 6232----------------------- | -------- | ----------- | ----------- 6233name | Required | string | Bdev name 6234base_bdev_name | Required | string | Base bdev name 6235uuid | Optional | string | UUID of new bdev 6236 6237#### Result 6238 6239Name of newly created bdev. 6240 6241#### Example 6242 6243Example request: 6244 6245~~~json 6246{ 6247 "params": { 6248 "base_bdev_name": "Malloc0", 6249 "name": "Passsthru0" 6250 }, 6251 "jsonrpc": "2.0", 6252 "method": "bdev_passthru_create", 6253 "id": 1 6254} 6255~~~ 6256 6257Example response: 6258 6259~~~json 6260{ 6261 "jsonrpc": "2.0", 6262 "id": 1, 6263 "result": "Passsthru0" 6264} 6265~~~ 6266 6267### bdev_passthru_delete {#rpc_bdev_passthru_delete} 6268 6269Delete passthru bdev. 6270 6271#### Parameters 6272 6273Name | Optional | Type | Description 6274----------------------- | -------- | ----------- | ----------- 6275name | Required | string | Bdev name 6276 6277#### Example 6278 6279Example request: 6280 6281~~~json 6282{ 6283 "params": { 6284 "name": "Passsthru0" 6285 }, 6286 "jsonrpc": "2.0", 6287 "method": "bdev_passthru_delete", 6288 "id": 1 6289} 6290 6291~~~ 6292 6293Example response: 6294 6295~~~json 6296{ 6297 "jsonrpc": "2.0", 6298 "id": 1, 6299 "result": true 6300} 6301~~~ 6302 6303### bdev_xnvme_create {#rpc_bdev_xnvme_create} 6304 6305Create xnvme bdev. This bdev type redirects all IO to its underlying backend. 6306 6307#### Parameters 6308 6309Name | Optional | Type | Description 6310----------------------- | -------- | ----------- | ----------- 6311name | Required | string | name of xNVMe bdev to create 6312filename | Required | string | path to device or file (ex: /dev/nvme0n1) 6313io_mechanism | Required | string | IO mechanism to use (ex: libaio, io_uring, io_uring_cmd, etc.) 6314conserve_cpu | Optional | boolean | Whether or not to conserve CPU when polling (default: false) 6315 6316#### Result 6317 6318Name of newly created bdev. 6319 6320#### Example 6321 6322Example request: 6323 6324~~~json 6325{ 6326 "jsonrpc": "2.0", 6327 "method": "bdev_xnvme_create", 6328 "id": 1, 6329 "params": { 6330 "name": "bdev_ng0n1", 6331 "filename": "/dev/ng0n1", 6332 "io_mechanism": "io_uring_cmd", 6333 "conserve_cpu": false, 6334 } 6335} 6336~~~ 6337 6338Example response: 6339 6340~~~json 6341{ 6342 "jsonrpc": "2.0", 6343 "id": 1, 6344 "result": "bdev_ng0n1" 6345} 6346~~~ 6347 6348### bdev_xnvme_delete {#rpc_bdev_xnvme_delete} 6349 6350Delete xnvme bdev. 6351 6352#### Parameters 6353 6354Name | Optional | Type | Description 6355----------------------- | -------- | ----------- | ----------- 6356name | Required | string | name of xnvme bdev to delete 6357 6358#### Example 6359 6360Example request: 6361 6362~~~json 6363{ 6364 "params": { 6365 "name": "bdev_ng0n1" 6366 }, 6367 "jsonrpc": "2.0", 6368 "method": "bdev_xnvme_delete", 6369 "id": 1 6370} 6371 6372~~~ 6373 6374Example response: 6375 6376~~~json 6377{ 6378 "jsonrpc": "2.0", 6379 "id": 1, 6380 "result": true 6381} 6382~~~ 6383 6384### bdev_virtio_attach_controller {#rpc_bdev_virtio_attach_controller} 6385 6386Create new initiator @ref bdev_config_virtio_scsi or @ref bdev_config_virtio_blk and expose all found bdevs. 6387 6388#### Parameters 6389 6390Name | Optional | Type | Description 6391----------------------- | -------- | ----------- | ----------- 6392name | Required | string | Virtio SCSI base bdev name or Virtio Blk bdev name 6393trtype | Required | string | Virtio target trtype: pci or user 6394traddr | Required | string | target address: BDF or UNIX socket file path 6395dev_type | Required | string | Virtio device type: blk or scsi 6396vq_count | Optional | number | Number of queues this controller will utilize (default: 1) 6397vq_size | Optional | number | Size of each queue. Must be power of 2. (default: 512) 6398 6399In case of Virtio SCSI the `name` parameter will be base name for new created bdevs. For Virtio Blk `name` will be the 6400name of created bdev. 6401 6402`vq_count` and `vq_size` parameters are valid only if `trtype` is `user`. 6403 6404#### Result 6405 6406Array of names of newly created bdevs. 6407 6408#### Example 6409 6410Example request: 6411 6412~~~json 6413{ 6414 "params": { 6415 "name": "VirtioScsi0", 6416 "trtype": "user", 6417 "vq_size": 128, 6418 "dev_type": "scsi", 6419 "traddr": "/tmp/VhostScsi0", 6420 "vq_count": 4 6421 }, 6422 "jsonrpc": "2.0", 6423 "method": "bdev_virtio_attach_controller", 6424 "id": 1 6425} 6426~~~ 6427 6428Example response: 6429 6430~~~json 6431{ 6432 "jsonrpc": "2.0", 6433 "id": 1, 6434 "result": ["VirtioScsi0t2", "VirtioScsi0t4"] 6435} 6436~~~ 6437 6438### bdev_virtio_scsi_get_devices {#rpc_bdev_virtio_scsi_get_devices} 6439 6440Show information about all available Virtio SCSI devices. 6441 6442#### Parameters 6443 6444This method has no parameters. 6445 6446#### Result 6447 6448Array of Virtio SCSI information objects. 6449 6450#### Example 6451 6452Example request: 6453 6454~~~json 6455{ 6456 "jsonrpc": "2.0", 6457 "method": "bdev_virtio_scsi_get_devices", 6458 "id": 1 6459} 6460~~~ 6461 6462Example response: 6463 6464~~~json 6465{ 6466 "jsonrpc": "2.0", 6467 "id": 1, 6468 "result": [ 6469 { 6470 "name": "VirtioScsi0", 6471 "virtio": { 6472 "vq_size": 128, 6473 "vq_count": 4, 6474 "type": "user", 6475 "socket": "/tmp/VhostScsi0" 6476 } 6477 } 6478 ] 6479} 6480~~~ 6481 6482### bdev_virtio_detach_controller {#rpc_bdev_virtio_detach_controller} 6483 6484Remove a Virtio device. This command can be used to remove any type of virtio device. 6485 6486#### Parameters 6487 6488Name | Optional | Type | Description 6489----------------------- | -------- | ----------- | ----------- 6490name | Required | string | Virtio name 6491 6492#### Example 6493 6494Example request: 6495 6496~~~json 6497{ 6498 "params": { 6499 "name": "VirtioUser0" 6500 }, 6501 "jsonrpc": "2.0", 6502 "method": "bdev_virtio_detach_controller", 6503 "id": 1 6504} 6505 6506~~~ 6507 6508Example response: 6509 6510~~~json 6511{ 6512 "jsonrpc": "2.0", 6513 "id": 1, 6514 "result": true 6515} 6516~~~ 6517 6518### bdev_virtio_blk_set_hotplug {#rpc_bdev_virtio_blk_set_hotplug} 6519 6520Enable/Disable the virtio blk hotplug monitor or change the monitor period time 6521 6522#### Parameters 6523 6524Name | Optional | Type | Description 6525----------------------- | -------- | ----------- | ----------- 6526enable | Required | bool | Enable or disable the virtio blk hotplug monitor 6527period-us | Optional | number | The period time of the monitor 6528 6529When the enable is true then the period-us is optional. If user don't set the period time then use the default 6530value. When the enable is false then the period-us is not required. 6531 6532#### Result 6533 6534True the rpc is successful otherwise false 6535 6536#### Example 6537 6538Example request: 6539 6540~~~json 6541{ 6542 "params": { 6543 "enable": "true", 6544 "period-us": "1000000" 6545 }, 6546 "jsonrpc": "2.0", 6547 "method": "bdev_virtio_blk_set_hotplug", 6548 "id": 1 6549} 6550~~~ 6551 6552Example response: 6553 6554~~~json 6555{ 6556 "jsonrpc": "2.0", 6557 "id": 1, 6558 "result": true 6559} 6560~~~ 6561 6562## iSCSI Target {#jsonrpc_components_iscsi_tgt} 6563 6564### iscsi_set_options method {#rpc_iscsi_set_options} 6565 6566Set global parameters for iSCSI targets. 6567 6568This RPC may only be called before SPDK subsystems have been initialized. This RPC can be called only once. 6569 6570#### Parameters 6571 6572Name | Optional | Type | Description 6573------------------------------- | -------- | ------- | ----------- 6574auth_file | Optional | string | Path to CHAP shared secret file (default: "") 6575node_base | Optional | string | Prefix of the name of iSCSI target node (default: "iqn.2016-06.io.spdk") 6576nop_timeout | Optional | number | Timeout in seconds to nop-in request to the initiator (default: 60) 6577nop_in_interval | Optional | number | Time interval in secs between nop-in requests by the target (default: 30) 6578disable_chap | Optional | boolean | CHAP for discovery session should be disabled (default: `false`) 6579require_chap | Optional | boolean | CHAP for discovery session should be required (default: `false`) 6580mutual_chap | Optional | boolean | CHAP for discovery session should be unidirectional (`false`) or bidirectional (`true`) (default: `false`) 6581chap_group | Optional | number | CHAP group ID for discovery session (default: 0) 6582max_sessions | Optional | number | Maximum number of sessions in the host (default: 128) 6583max_queue_depth | Optional | number | Maximum number of outstanding I/Os per queue (default: 64) 6584max_connections_per_session | Optional | number | Session specific parameter, MaxConnections (default: 2) 6585default_time2wait | Optional | number | Session specific parameter, DefaultTime2Wait (default: 2) 6586default_time2retain | Optional | number | Session specific parameter, DefaultTime2Retain (default: 20) 6587first_burst_length | Optional | number | Session specific parameter, FirstBurstLength (default: 8192) 6588immediate_data | Optional | boolean | Session specific parameter, ImmediateData (default: `true`) 6589error_recovery_level | Optional | number | Session specific parameter, ErrorRecoveryLevel (default: 0) 6590allow_duplicated_isid | Optional | boolean | Allow duplicated initiator session ID (default: `false`) 6591max_large_datain_per_connection | Optional | number | Max number of outstanding split read I/Os per connection (default: 64) 6592max_r2t_per_connection | Optional | number | Max number of outstanding R2Ts per connection (default: 4) 6593pdu_pool_size | Optional | number | Number of PDUs in the pool (default: approximately 2 * max_sessions * (max_queue_depth + max_connections_per_session)) 6594immediate_data_pool_size | Optional | number | Number of immediate data buffers in the pool (default: 128 * max_sessions) 6595data_out_pool_size | Optional | number | Number of data out buffers in the pool (default: 16 * max_sessions) 6596 6597To load CHAP shared secret file, its path is required to specify explicitly in the parameter `auth_file`. 6598 6599Parameters `disable_chap` and `require_chap` are mutually exclusive. Parameters `no_discovery_auth`, `req_discovery_auth`, 6600`req_discovery_auth_mutual`, and `discovery_auth_group` are still available instead of `disable_chap`, `require_chap`, 6601`mutual_chap`, and `chap_group`, respectivey but will be removed in future releases. 6602 6603#### Example 6604 6605Example request: 6606 6607~~~json 6608{ 6609 "params": { 6610 "allow_duplicated_isid": true, 6611 "default_time2retain": 60, 6612 "first_burst_length": 8192, 6613 "immediate_data": true, 6614 "node_base": "iqn.2016-06.io.spdk", 6615 "max_sessions": 128, 6616 "nop_timeout": 30, 6617 "nop_in_interval": 30, 6618 "auth_file": "/usr/local/etc/spdk/auth.conf", 6619 "disable_chap": true, 6620 "default_time2wait": 2 6621 }, 6622 "jsonrpc": "2.0", 6623 "method": "iscsi_set_options", 6624 "id": 1 6625} 6626~~~ 6627 6628Example response: 6629 6630~~~json 6631{ 6632 "jsonrpc": "2.0", 6633 "id": 1, 6634 "result": true 6635} 6636~~~ 6637 6638### iscsi_get_options method {#rpc_iscsi_get_options} 6639 6640Show global parameters of iSCSI targets. 6641 6642#### Parameters 6643 6644This method has no parameters. 6645 6646#### Example 6647 6648Example request: 6649 6650~~~json 6651request: 6652{ 6653 "jsonrpc": "2.0", 6654 "method": "iscsi_get_options", 6655 "id": 1 6656} 6657~~~ 6658 6659Example response: 6660 6661~~~json 6662{ 6663 "jsonrpc": "2.0", 6664 "id": 1, 6665 "result": { 6666 "allow_duplicated_isid": true, 6667 "default_time2retain": 60, 6668 "first_burst_length": 8192, 6669 "immediate_data": true, 6670 "node_base": "iqn.2016-06.io.spdk", 6671 "mutual_chap": false, 6672 "nop_in_interval": 30, 6673 "chap_group": 0, 6674 "max_connections_per_session": 2, 6675 "max_queue_depth": 64, 6676 "nop_timeout": 30, 6677 "max_sessions": 128, 6678 "error_recovery_level": 0, 6679 "auth_file": "/usr/local/etc/spdk/auth.conf", 6680 "disable_chap": true, 6681 "default_time2wait": 2, 6682 "require_chap": false, 6683 "max_large_datain_per_connection": 64, 6684 "max_r2t_per_connection": 4 6685 } 6686} 6687~~~ 6688 6689### scsi_get_devices {#rpc_scsi_get_devices} 6690 6691Display SCSI devices 6692 6693#### Parameters 6694 6695This method has no parameters. 6696 6697#### Example 6698 6699Example request: 6700 6701~~~json 6702{ 6703 "jsonrpc": "2.0", 6704 "method": "scsi_get_devices", 6705 "id": 1 6706} 6707~~~ 6708 6709Example response: 6710 6711~~~json 6712{ 6713 "jsonrpc": "2.0", 6714 "id": 1, 6715 "result": [ 6716 { 6717 "id": 0, 6718 "device_name": "iqn.2016-06.io.spdk:Target3" 6719 } 6720 ] 6721} 6722~~~ 6723 6724### iscsi_set_discovery_auth method {#rpc_iscsi_set_discovery_auth} 6725 6726Set CHAP authentication for sessions dynamically. 6727 6728#### Parameters 6729 6730Name | Optional | Type | Description 6731--------------------------- | -------- | --------| ----------- 6732disable_chap | Optional | boolean | CHAP for discovery session should be disabled (default: `false`) 6733require_chap | Optional | boolean | CHAP for discovery session should be required (default: `false`) 6734mutual_chap | Optional | boolean | CHAP for discovery session should be unidirectional (`false`) or bidirectional (`true`) (default: `false`) 6735chap_group | Optional | number | CHAP group ID for discovery session (default: 0) 6736 6737Parameters `disable_chap` and `require_chap` are mutually exclusive. 6738 6739#### Example 6740 6741Example request: 6742 6743~~~json 6744request: 6745{ 6746 "params": { 6747 "chap_group": 1, 6748 "require_chap": true, 6749 "mutual_chap": true 6750 }, 6751 "jsonrpc": "2.0", 6752 "method": "iscsi_set_discovery_auth", 6753 "id": 1 6754} 6755~~~ 6756 6757Example response: 6758 6759~~~json 6760{ 6761 "jsonrpc": "2.0", 6762 "id": 1, 6763 "result": true 6764} 6765~~~ 6766 6767### iscsi_create_auth_group method {#rpc_iscsi_create_auth_group} 6768 6769Create an authentication group for CHAP authentication. 6770 6771#### Parameters 6772 6773Name | Optional | Type | Description 6774--------------------------- | -------- | --------| ----------- 6775tag | Required | number | Authentication group tag (unique, integer > 0) 6776secrets | Optional | array | Array of @ref rpc_iscsi_create_auth_group_secret objects 6777 6778#### secret {#rpc_iscsi_create_auth_group_secret} 6779 6780Name | Optional | Type | Description 6781--------------------------- | ---------| --------| ----------- 6782user | Required | string | Unidirectional CHAP name 6783secret | Required | string | Unidirectional CHAP secret 6784muser | Optional | string | Bidirectional CHAP name 6785msecret | Optional | string | Bidirectional CHAP secret 6786 6787#### Example 6788 6789Example request: 6790 6791~~~json 6792{ 6793 "params": { 6794 "secrets": [ 6795 { 6796 "muser": "mu1", 6797 "secret": "s1", 6798 "user": "u1", 6799 "msecret": "ms1" 6800 } 6801 ], 6802 "tag": 2 6803 }, 6804 "jsonrpc": "2.0", 6805 "method": "iscsi_create_auth_group", 6806 "id": 1 6807} 6808~~~ 6809 6810Example response: 6811 6812~~~json 6813{ 6814 "jsonrpc": "2.0", 6815 "id": 1, 6816 "result": true 6817} 6818~~~ 6819 6820### iscsi_delete_auth_group method {#rpc_iscsi_delete_auth_group} 6821 6822Delete an existing authentication group for CHAP authentication. 6823 6824#### Parameters 6825 6826Name | Optional | Type | Description 6827--------------------------- | -------- | --------| ----------- 6828tag | Required | number | Authentication group tag (unique, integer > 0) 6829 6830#### Example 6831 6832Example request: 6833 6834~~~json 6835{ 6836 "params": { 6837 "tag": 2 6838 }, 6839 "jsonrpc": "2.0", 6840 "method": "iscsi_delete_auth_group", 6841 "id": 1 6842} 6843~~~ 6844 6845Example response: 6846 6847~~~json 6848{ 6849 "jsonrpc": "2.0", 6850 "id": 1, 6851 "result": true 6852} 6853~~~ 6854 6855### iscsi_get_auth_groups {#rpc_iscsi_get_auth_groups} 6856 6857Show information about all existing authentication group for CHAP authentication. 6858 6859#### Parameters 6860 6861This method has no parameters. 6862 6863#### Result 6864 6865Array of objects describing authentication group. 6866 6867Name | Type | Description 6868--------------------------- | --------| ----------- 6869tag | number | Authentication group tag 6870secrets | array | Array of @ref rpc_iscsi_create_auth_group_secret objects 6871 6872#### Example 6873 6874Example request: 6875 6876~~~json 6877{ 6878 "jsonrpc": "2.0", 6879 "method": "iscsi_get_auth_groups", 6880 "id": 1 6881} 6882~~~ 6883 6884Example response: 6885 6886~~~json 6887{ 6888 "jsonrpc": "2.0", 6889 "id": 1, 6890 "result": [ 6891 { 6892 "secrets": [ 6893 { 6894 "muser": "mu1", 6895 "secret": "s1", 6896 "user": "u1", 6897 "msecret": "ms1" 6898 } 6899 ], 6900 "tag": 1 6901 }, 6902 { 6903 "secrets": [ 6904 { 6905 "secret": "s2", 6906 "user": "u2" 6907 } 6908 ], 6909 "tag": 2 6910 } 6911 ] 6912} 6913~~~ 6914 6915### iscsi_auth_group_add_secret {#rpc_iscsi_auth_group_add_secret} 6916 6917Add a secret to an existing authentication group for CHAP authentication. 6918 6919#### Parameters 6920 6921Name | Optional | Type | Description 6922--------------------------- | -------- | --------| ----------- 6923tag | Required | number | Authentication group tag (unique, integer > 0) 6924user | Required | string | Unidirectional CHAP name 6925secret | Required | string | Unidirectional CHAP secret 6926muser | Optional | string | Bidirectional CHAP name 6927msecret | Optional | string | Bidirectional CHAP secret 6928 6929#### Example 6930 6931Example request: 6932 6933~~~json 6934{ 6935 "params": { 6936 "muser": "mu3", 6937 "secret": "s3", 6938 "tag": 2, 6939 "user": "u3", 6940 "msecret": "ms3" 6941 }, 6942 "jsonrpc": "2.0", 6943 "method": "iscsi_auth_group_add_secret", 6944 "id": 1 6945} 6946~~~json 6947 6948Example response: 6949 6950~~~json 6951{ 6952 "jsonrpc": "2.0", 6953 "id": 1, 6954 "result": true 6955} 6956~~~ 6957 6958### iscsi_auth_group_remove_secret {#rpc_iscsi_auth_group_remove_secret} 6959 6960Remove a secret from an existing authentication group for CHAP authentication. 6961 6962#### Parameters 6963 6964Name | Optional | Type | Description 6965--------------------------- | -------- | --------| ----------- 6966tag | Required | number | Authentication group tag (unique, integer > 0) 6967user | Required | string | Unidirectional CHAP name 6968 6969#### Example 6970 6971Example request: 6972 6973~~~json 6974{ 6975 "params": { 6976 "tag": 2, 6977 "user": "u3" 6978 }, 6979 "jsonrpc": "2.0", 6980 "method": "iscsi_auth_group_remove_secret", 6981 "id": 1 6982} 6983~~~ 6984 6985Example response: 6986 6987~~~json 6988{ 6989 "jsonrpc": "2.0", 6990 "id": 1, 6991 "result": true 6992} 6993~~~ 6994 6995### iscsi_get_initiator_groups method {#rpc_iscsi_get_initiator_groups} 6996 6997Show information about all available initiator groups. 6998 6999#### Parameters 7000 7001This method has no parameters. 7002 7003#### Result 7004 7005Array of objects describing initiator groups. 7006 7007Name | Type | Description 7008--------------------------- | --------| ----------- 7009tag | number | Initiator group tag 7010initiators | array | Array of initiator hostnames or IP addresses 7011netmasks | array | Array of initiator netmasks 7012 7013#### Example 7014 7015Example request: 7016 7017~~~json 7018{ 7019 "jsonrpc": "2.0", 7020 "method": "iscsi_get_initiator_groups", 7021 "id": 1 7022} 7023~~~ 7024 7025Example response: 7026 7027~~~json 7028{ 7029 "jsonrpc": "2.0", 7030 "id": 1, 7031 "result": [ 7032 { 7033 "initiators": [ 7034 "iqn.2016-06.io.spdk:host1", 7035 "iqn.2016-06.io.spdk:host2" 7036 ], 7037 "tag": 1, 7038 "netmasks": [ 7039 "192.168.1.0/24" 7040 ] 7041 } 7042 ] 7043} 7044~~~ 7045 7046### iscsi_create_initiator_group method {#rpc_iscsi_create_initiator_group} 7047 7048Add an initiator group. 7049 7050#### Parameters 7051 7052Name | Optional | Type | Description 7053--------------------------- | -------- | --------| ----------- 7054tag | Required | number | Initiator group tag (unique, integer > 0) 7055initiators | Required | array | Not empty array of initiator hostnames or IP addresses 7056netmasks | Required | array | Not empty array of initiator netmasks 7057 7058#### Example 7059 7060Example request: 7061 7062~~~json 7063{ 7064 "params": { 7065 "initiators": [ 7066 "iqn.2016-06.io.spdk:host1", 7067 "iqn.2016-06.io.spdk:host2" 7068 ], 7069 "tag": 1, 7070 "netmasks": [ 7071 "192.168.1.0/24" 7072 ] 7073 }, 7074 "jsonrpc": "2.0", 7075 "method": "iscsi_create_initiator_group", 7076 "id": 1 7077} 7078~~~ 7079 7080Example response: 7081 7082~~~json 7083response: 7084{ 7085 "jsonrpc": "2.0", 7086 "id": 1, 7087 "result": true 7088} 7089~~~ 7090 7091### iscsi_delete_initiator_group method {#rpc_iscsi_delete_initiator_group} 7092 7093Delete an existing initiator group. 7094 7095#### Parameters 7096 7097Name | Optional | Type | Description 7098--------------------------- | -------- | --------| ----------- 7099tag | Required | number | Initiator group tag (unique, integer > 0) 7100 7101#### Example 7102 7103Example request: 7104 7105~~~json 7106{ 7107 "params": { 7108 "tag": 1 7109 }, 7110 "jsonrpc": "2.0", 7111 "method": "iscsi_delete_initiator_group", 7112 "id": 1 7113} 7114~~~ 7115 7116Example response: 7117 7118~~~json 7119{ 7120 "jsonrpc": "2.0", 7121 "id": 1, 7122 "result": true 7123} 7124~~~ 7125 7126### iscsi_initiator_group_add_initiators method {#rpc_iscsi_initiator_group_add_initiators} 7127 7128Add initiators to an existing initiator group. 7129 7130#### Parameters 7131 7132Name | Optional | Type | Description 7133--------------------------- | -------- | --------| ----------- 7134tag | Required | number | Existing initiator group tag. 7135initiators | Optional | array | Array of initiator hostnames or IP addresses 7136netmasks | Optional | array | Array of initiator netmasks 7137 7138#### Example 7139 7140Example request: 7141 7142~~~json 7143request: 7144{ 7145 "params": { 7146 "initiators": [ 7147 "iqn.2016-06.io.spdk:host3" 7148 ], 7149 "tag": 1, 7150 "netmasks": [ 7151 "255.255.255.1" 7152 ] 7153 }, 7154 "jsonrpc": "2.0", 7155 "method": "iscsi_initiator_group_add_initiators", 7156 "id": 1 7157} 7158~~~ 7159 7160Example response: 7161 7162~~~json 7163response: 7164{ 7165 "jsonrpc": "2.0", 7166 "id": 1, 7167 "result": true 7168} 7169~~~ 7170 7171### iscsi_initiator_group_remove_initiators method {#rpc_iscsi_initiator_group_remove_initiators} 7172 7173Remove initiators from an initiator group. 7174 7175#### Parameters 7176 7177Name | Optional | Type | Description 7178--------------------------- | -------- | --------| ----------- 7179tag | Required | number | Existing initiator group tag. 7180initiators | Optional | array | Array of initiator hostnames or IP addresses 7181netmasks | Optional | array | Array of initiator netmasks 7182 7183#### Example 7184 7185Example request: 7186 7187~~~json 7188request: 7189{ 7190 "params": { 7191 "initiators": [ 7192 "iqn.2016-06.io.spdk:host3" 7193 ], 7194 "tag": 1, 7195 "netmasks": [ 7196 "255.255.255.1" 7197 ] 7198 }, 7199 "jsonrpc": "2.0", 7200 "method": "iscsi_initiator_group_remove_initiators", 7201 "id": 1 7202} 7203~~~ 7204 7205Example response: 7206 7207~~~json 7208response: 7209{ 7210 "jsonrpc": "2.0", 7211 "id": 1, 7212 "result": true 7213} 7214~~~ 7215 7216### iscsi_get_target_nodes method {#rpc_iscsi_get_target_nodes} 7217 7218Show information about all available iSCSI target nodes. 7219 7220#### Parameters 7221 7222This method has no parameters. 7223 7224#### Result 7225 7226Array of objects describing target node. 7227 7228Name | Type | Description 7229--------------------------- | --------| ----------- 7230name | string | Target node name (ASCII) 7231alias_name | string | Target node alias name (ASCII) 7232pg_ig_maps | array | Array of Portal_Group_Tag:Initiator_Group_Tag mappings 7233luns | array | Array of Bdev names to LUN ID mappings 7234queue_depth | number | Target queue depth 7235disable_chap | boolean | CHAP authentication should be disabled for this target 7236require_chap | boolean | CHAP authentication should be required for this target 7237mutual_chap | boolean | CHAP authentication should be bidirectional (`true`) or unidirectional (`false`) 7238chap_group | number | Authentication group ID for this target node 7239header_digest | boolean | Header Digest should be required for this target node 7240data_digest | boolean | Data Digest should be required for this target node 7241 7242#### Example 7243 7244Example request: 7245 7246~~~json 7247{ 7248 "jsonrpc": "2.0", 7249 "method": "iscsi_get_target_nodes", 7250 "id": 1 7251} 7252~~~ 7253 7254Example response: 7255 7256~~~json 7257{ 7258 "jsonrpc": "2.0", 7259 "id": 1, 7260 "result": [ 7261 { 7262 "luns": [ 7263 { 7264 "lun_id": 0, 7265 "bdev_name": "Nvme0n1" 7266 } 7267 ], 7268 "mutual_chap": false, 7269 "name": "iqn.2016-06.io.spdk:target1", 7270 "alias_name": "iscsi-target1-alias", 7271 "require_chap": false, 7272 "chap_group": 0, 7273 "pg_ig_maps": [ 7274 { 7275 "ig_tag": 1, 7276 "pg_tag": 1 7277 } 7278 ], 7279 "data_digest": false, 7280 "disable_chap": false, 7281 "header_digest": false, 7282 "queue_depth": 64 7283 } 7284 ] 7285} 7286~~~ 7287 7288### iscsi_create_target_node method {#rpc_iscsi_create_target_node} 7289 7290Add an iSCSI target node. 7291 7292#### Parameters 7293 7294Name | Optional | Type | Description 7295--------------------------- | -------- | --------| ----------- 7296name | Required | string | Target node name (ASCII) 7297alias_name | Required | string | Target node alias name (ASCII) 7298pg_ig_maps | Required | array | Array of (Portal_Group_Tag:Initiator_Group_Tag) mappings 7299luns | Required | array | Array of Bdev names to LUN ID mappings 7300queue_depth | Required | number | Target queue depth 7301disable_chap | Optional | boolean | CHAP authentication should be disabled for this target 7302require_chap | Optional | boolean | CHAP authentication should be required for this target 7303mutual_chap | Optional | boolean | CHAP authentication should be bidirectional (`true`) or unidirectional (`false`) 7304chap_group | Optional | number | Authentication group ID for this target node 7305header_digest | Optional | boolean | Header Digest should be required for this target node 7306data_digest | Optional | boolean | Data Digest should be required for this target node 7307 7308Parameters `disable_chap` and `require_chap` are mutually exclusive. 7309 7310#### Example 7311 7312Example request: 7313 7314~~~json 7315{ 7316 "params": { 7317 "luns": [ 7318 { 7319 "lun_id": 0, 7320 "bdev_name": "Nvme0n1" 7321 } 7322 ], 7323 "mutual_chap": true, 7324 "name": "target2", 7325 "alias_name": "iscsi-target2-alias", 7326 "pg_ig_maps": [ 7327 { 7328 "ig_tag": 1, 7329 "pg_tag": 1 7330 }, 7331 { 7332 "ig_tag": 2, 7333 "pg_tag": 2 7334 } 7335 ], 7336 "data_digest": true, 7337 "disable_chap": true, 7338 "header_digest": true, 7339 "queue_depth": 24 7340 }, 7341 "jsonrpc": "2.0", 7342 "method": "iscsi_create_target_node", 7343 "id": 1 7344} 7345~~~ 7346 7347Example response: 7348 7349~~~json 7350{ 7351 "jsonrpc": "2.0", 7352 "id": 1, 7353 "result": true 7354} 7355~~~ 7356 7357### iscsi_target_node_set_auth method {#rpc_iscsi_target_node_set_auth} 7358 7359Set CHAP authentication to an existing iSCSI target node. 7360 7361#### Parameters 7362 7363Name | Optional | Type | Description 7364--------------------------- | -------- | --------| ----------- 7365name | Required | string | Target node name (ASCII) 7366disable_chap | Optional | boolean | CHAP authentication should be disabled for this target 7367require_chap | Optional | boolean | CHAP authentication should be required for this target 7368mutual_chap | Optional | boolean | CHAP authentication should be bidirectional (`true`) or unidirectional (`false`) 7369chap_group | Optional | number | Authentication group ID for this target node 7370 7371Parameters `disable_chap` and `require_chap` are mutually exclusive. 7372 7373#### Example 7374 7375Example request: 7376 7377~~~json 7378{ 7379 "params": { 7380 "chap_group": 1, 7381 "require_chap": true, 7382 "name": "iqn.2016-06.io.spdk:target1", 7383 "mutual_chap": true 7384 }, 7385 "jsonrpc": "2.0", 7386 "method": "iscsi_target_node_set_auth", 7387 "id": 1 7388} 7389~~~ 7390 7391Example response: 7392 7393~~~json 7394{ 7395 "jsonrpc": "2.0", 7396 "id": 1, 7397 "result": true 7398} 7399~~~ 7400 7401### iscsi_target_node_add_pg_ig_maps method {#rpc_iscsi_target_node_add_pg_ig_maps} 7402 7403Add initiator group to portal group mappings to an existing iSCSI target node. 7404 7405#### Parameters 7406 7407Name | Optional | Type | Description 7408--------------------------- | -------- | --------| ----------- 7409name | Required | string | Target node name (ASCII) 7410pg_ig_maps | Required | array | Not empty array of initiator to portal group mappings objects 7411 7412Portal to Initiator group mappings object: 7413 7414Name | Optional | Type | Description 7415--------------------------- | -------- | --------| ----------- 7416ig_tag | Required | number | Existing initiator group tag 7417pg_tag | Required | number | Existing portal group tag 7418 7419#### Example 7420 7421Example request: 7422 7423~~~json 7424{ 7425 "params": { 7426 "pg_ig_maps": [ 7427 { 7428 "ig_tag": 1, 7429 "pg_tag": 1 7430 }, 7431 { 7432 "ig_tag": 2, 7433 "pg_tag": 2 7434 }, 7435 { 7436 "ig_tag": 3, 7437 "pg_tag": 3 7438 } 7439 ], 7440 "name": "iqn.2016-06.io.spdk:target3" 7441 }, 7442 "jsonrpc": "2.0", 7443 "method": "iscsi_target_node_add_pg_ig_maps", 7444 "id": 1 7445} 7446~~~ 7447 7448Example response: 7449 7450~~~json 7451{ 7452 "jsonrpc": "2.0", 7453 "id": 1, 7454 "result": true 7455} 7456~~~ 7457 7458### iscsi_target_node_remove_pg_ig_maps method {#rpc_iscsi_target_node_remove_pg_ig_maps} 7459 7460Delete initiator group to portal group mappings from an existing iSCSI target node. 7461 7462#### Parameters 7463 7464Name | Optional | Type | Description 7465--------------------------- | -------- | --------| ----------- 7466name | Required | string | Target node name (ASCII) 7467pg_ig_maps | Required | array | Not empty array of Portal to Initiator group mappings objects 7468 7469Portal to Initiator group mappings object: 7470 7471Name | Optional | Type | Description 7472--------------------------- | -------- | --------| ----------- 7473ig_tag | Required | number | Existing initiator group tag 7474pg_tag | Required | number | Existing portal group tag 7475 7476#### Example 7477 7478Example request: 7479 7480~~~json 7481{ 7482 "params": { 7483 "pg_ig_maps": [ 7484 { 7485 "ig_tag": 1, 7486 "pg_tag": 1 7487 }, 7488 { 7489 "ig_tag": 2, 7490 "pg_tag": 2 7491 }, 7492 { 7493 "ig_tag": 3, 7494 "pg_tag": 3 7495 } 7496 ], 7497 "name": "iqn.2016-06.io.spdk:target3" 7498 }, 7499 "jsonrpc": "2.0", 7500 "method": "iscsi_target_node_remove_pg_ig_maps", 7501 "id": 1 7502} 7503~~~ 7504 7505Example response: 7506 7507~~~json 7508{ 7509 "jsonrpc": "2.0", 7510 "id": 1, 7511 "result": true 7512} 7513~~~ 7514 7515### iscsi_delete_target_node method {#rpc_iscsi_delete_target_node} 7516 7517Delete an iSCSI target node. 7518 7519#### Parameters 7520 7521Name | Optional | Type | Description 7522--------------------------- | -------- | --------| ----------- 7523name | Required | string | Target node name (ASCII) 7524 7525#### Example 7526 7527Example request: 7528 7529~~~json 7530{ 7531 "params": { 7532 "name": "iqn.2016-06.io.spdk:target1" 7533 }, 7534 "jsonrpc": "2.0", 7535 "method": "iscsi_delete_target_node", 7536 "id": 1 7537} 7538~~~ 7539 7540Example response: 7541 7542~~~json 7543{ 7544 "jsonrpc": "2.0", 7545 "id": 1, 7546 "result": true 7547} 7548~~~ 7549 7550### iscsi_get_portal_groups method {#rpc_iscsi_get_portal_groups} 7551 7552Show information about all available portal groups. 7553 7554#### Parameters 7555 7556This method has no parameters. 7557 7558#### Example 7559 7560Example request: 7561 7562~~~json 7563request: 7564{ 7565 "jsonrpc": "2.0", 7566 "method": "iscsi_get_portal_groups", 7567 "id": 1 7568} 7569~~~ 7570 7571Example response: 7572 7573~~~json 7574{ 7575 "jsonrpc": "2.0", 7576 "id": 1, 7577 "result": [ 7578 { 7579 "portals": [ 7580 { 7581 "host": "127.0.0.1", 7582 "port": "3260" 7583 } 7584 ], 7585 "tag": 1, 7586 "private": false 7587 } 7588 ] 7589} 7590~~~ 7591 7592### iscsi_create_portal_group method {#rpc_iscsi_create_portal_group} 7593 7594Add a portal group. 7595 7596#### Parameters 7597 7598Name | Optional | Type | Description 7599--------------------------- | -------- | --------| ----------- 7600tag | Required | number | Portal group tag 7601portals | Required | array | Not empty array of portals 7602private | Optional | boolean | When true, portals in this group are not returned by a discovery session. Used for login redirection. (default: `false`) 7603wait | Optional | boolean | When true, do not listen on portals until it is started explicitly. (default: `false`) 7604 7605Portal object 7606 7607Name | Optional | Type | Description 7608--------------------------- | -------- | --------| ----------- 7609host | Required | string | Hostname or IP address 7610port | Required | string | Port number 7611 7612#### Example 7613 7614Example request: 7615 7616~~~json 7617{ 7618 "params": { 7619 "portals": [ 7620 { 7621 "host": "127.0.0.1", 7622 "port": "3260" 7623 } 7624 ], 7625 "tag": 1 7626 }, 7627 "jsonrpc": "2.0", 7628 "method": "iscsi_create_portal_group", 7629 "id": 1 7630} 7631~~~ 7632 7633Example response: 7634 7635~~~json 7636{ 7637 "jsonrpc": "2.0", 7638 "id": 1, 7639 "result": true 7640} 7641~~~ 7642 7643### iscsi_start_portal_group method {#rpc_iscsi_start_portal_group} 7644 7645Start listening on portals if the portal group is not started yet, or do nothing 7646if the portal group already started. Return a success response for both cases. 7647 7648#### Parameters 7649 7650Name | Optional | Type | Description 7651--------------------------- | -------- | --------| ----------- 7652tag | Required | number | Existing portal group tag 7653 7654#### Example 7655 7656Example request: 7657 7658~~~json 7659{ 7660 "params": { 7661 "tag": 1 7662 }, 7663 "jsonrpc": "2.0", 7664 "method": "iscsi_start_portal_group", 7665 "id": 1 7666} 7667~~~ 7668 7669Example response: 7670 7671~~~json 7672{ 7673 "jsonrpc": "2.0", 7674 "id": 1, 7675 "result": true 7676} 7677~~~ 7678 7679### iscsi_delete_portal_group method {#rpc_iscsi_delete_portal_group} 7680 7681Delete an existing portal group. 7682 7683#### Parameters 7684 7685Name | Optional | Type | Description 7686--------------------------- | -------- | --------| ----------- 7687tag | Required | number | Existing portal group tag 7688 7689#### Example 7690 7691Example request: 7692 7693~~~json 7694{ 7695 "params": { 7696 "tag": 1 7697 }, 7698 "jsonrpc": "2.0", 7699 "method": "iscsi_delete_portal_group", 7700 "id": 1 7701} 7702~~~ 7703 7704Example response: 7705 7706~~~json 7707{ 7708 "jsonrpc": "2.0", 7709 "id": 1, 7710 "result": true 7711} 7712~~~ 7713 7714### iscsi_portal_group_set_auth method {#rpc_iscsi_portal_group_set_auth} 7715 7716Set CHAP authentication for discovery sessions specific for the existing iSCSI portal group. 7717This RPC overwrites the setting by the global parameters for the iSCSI portal group. 7718 7719#### Parameters 7720 7721Name | Optional | Type | Description 7722--------------------------- | -------- | --------| ----------- 7723disable_chap | Optional | boolean | CHAP for discovery session should be disabled (default: `false`) 7724require_chap | Optional | boolean | CHAP for discovery session should be required (default: `false`) 7725mutual_chap | Optional | boolean | CHAP for discovery session should be unidirectional (`false`) or bidirectional (`true`) (default: `false`) 7726chap_group | Optional | number | CHAP group ID for discovery session (default: 0) 7727 7728Parameters `disable_chap` and `require_chap` are mutually exclusive. 7729 7730#### Example 7731 7732Example request: 7733 7734~~~json 7735request: 7736{ 7737 "params": { 7738 "tag": 1, 7739 "chap_group": 1, 7740 "require_chap": true, 7741 "mutual_chap": true 7742 }, 7743 "jsonrpc": "2.0", 7744 "method": "iscsi_portal_group_set_auth", 7745 "id": 1 7746} 7747~~~ 7748 7749Example response: 7750 7751~~~json 7752{ 7753 "jsonrpc": "2.0", 7754 "id": 1, 7755 "result": true 7756} 7757~~~ 7758 7759### iscsi_get_connections method {#rpc_iscsi_get_connections} 7760 7761Show information about all active connections. 7762 7763#### Parameters 7764 7765This method has no parameters. 7766 7767#### Results 7768 7769Array of objects describing iSCSI connection. 7770 7771Name | Type | Description 7772--------------------------- | --------| ----------- 7773id | number | Index (used for TTT - Target Transfer Tag) 7774cid | number | CID (Connection ID) 7775tsih | number | TSIH (Target Session Identifying Handle) 7776lcore_id | number | Core number on which the iSCSI connection runs 7777initiator_addr | string | Initiator address 7778target_addr | string | Target address 7779target_node_name | string | Target node name (ASCII) without prefix 7780 7781#### Example 7782 7783Example request: 7784 7785~~~json 7786{ 7787 "jsonrpc": "2.0", 7788 "method": "iscsi_get_connections", 7789 "id": 1 7790} 7791~~~ 7792 7793Example response: 7794 7795~~~json 7796{ 7797 "jsonrpc": "2.0", 7798 "id": 1, 7799 "result": [ 7800 { 7801 "tsih": 4, 7802 "cid": 0, 7803 "target_node_name": "target1", 7804 "lcore_id": 0, 7805 "initiator_addr": "10.0.0.2", 7806 "target_addr": "10.0.0.1", 7807 "id": 0 7808 } 7809 ] 7810} 7811~~~ 7812 7813### iscsi_get_stats method {#iscsi_get_stats} 7814 7815Show stat information of iSCSI connections. 7816 7817#### Parameters 7818 7819This method has no parameters. 7820 7821#### Results 7822 7823Stat information of iSCSI connections. 7824 7825Name | Type | Description 7826--------------------------- | --------| ----------- 7827invalid | number | The number of invalid connections 7828running | number | The number of running connections 7829exiting | number | The number of exiting connections 7830exited | number | The number of exited connections 7831 7832#### Example 7833 7834Example request: 7835 7836~~~json 7837{ 7838 "jsonrpc": "2.0", 7839 "method": "iscsi_get_stats", 7840 "id": 1 7841} 7842~~~ 7843 7844Example response: 7845 7846~~~json 7847{ 7848 "jsonrpc": "2.0", 7849 "id": 1, 7850 "result": 7851 { 7852 "invalid": 0, 7853 "running": 5, 7854 "exiting": 0, 7855 "exited": 0 7856 } 7857 7858} 7859~~~ 7860 7861### iscsi_target_node_add_lun method {#rpc_iscsi_target_node_add_lun} 7862 7863Add an LUN to an existing iSCSI target node. 7864 7865#### Parameters 7866 7867Name | Optional | Type | Description 7868--------------------------- | -------- | --------| ----------- 7869name | Required | string | Target node name (ASCII) 7870bdev_name | Required | string | bdev name to be added as a LUN 7871lun_id | Optional | number | LUN ID (default: first free ID) 7872 7873#### Example 7874 7875Example request: 7876 7877~~~json 7878{ 7879 "params": { 7880 "lun_id": 2, 7881 "name": "iqn.2016-06.io.spdk:target1", 7882 "bdev_name": "Malloc0" 7883 }, 7884 "jsonrpc": "2.0", 7885 "method": "iscsi_target_node_add_lun", 7886 "id": 1 7887} 7888~~~ 7889 7890Example response: 7891 7892~~~json 7893{ 7894 "jsonrpc": "2.0", 7895 "id": 1, 7896 "result": true 7897} 7898~~~ 7899 7900### iscsi_target_node_set_redirect method {#rpc_iscsi_target_node_set_redirect} 7901 7902Update redirect portal of the primary portal group for the target node, 7903 7904#### Parameters 7905 7906Name | Optional | Type | Description 7907--------------------------- | -------- | --------| ----------- 7908name | Required | string | Target node name (ASCII) 7909pg_tag | Required | number | Existing portal group tag 7910redirect_host | Optional | string | Numeric IP address to which the target node is redirected 7911redirect_port | Optional | string | Numeric TCP port to which the target node is redirected 7912 7913If both redirect_host and redirect_port are omitted, clear the redirect portal. 7914 7915#### Example 7916 7917Example request: 7918 7919~~~json 7920{ 7921 "params": { 7922 "name": "iqn.2016-06.io.spdk:target1", 7923 "pg_tag": 1, 7924 "redirect_host": "10.0.0.3", 7925 "redirect_port": "3260" 7926 }, 7927 "jsonrpc": "2.0", 7928 "method": "iscsi_target_node_set_redirect", 7929 "id": 1 7930} 7931~~~ 7932 7933Example response: 7934 7935~~~json 7936{ 7937 "jsonrpc": "2.0", 7938 "id": 1, 7939 "result": true 7940} 7941~~~ 7942 7943### iscsi_target_node_request_logout method {#rpc_iscsi_target_node_request_logout} 7944 7945For the target node, request connections whose portal group tag match to logout, 7946or request all connections to logout if portal group tag is omitted. 7947 7948#### Parameters 7949 7950Name | Optional | Type | Description 7951--------------------------- | -------- | --------| ----------- 7952name | Required | string | Target node name (ASCII) 7953pg_tag | Optional | number | Existing portal group tag 7954 7955#### Example 7956 7957Example request: 7958 7959~~~json 7960{ 7961 "params": { 7962 "name": "iqn.2016-06.io.spdk:target1", 7963 "pg_tag": 1 7964 }, 7965 "jsonrpc": "2.0", 7966 "method": "iscsi_target_node_request_logout", 7967 "id": 1 7968} 7969~~~ 7970 7971Example response: 7972 7973~~~json 7974{ 7975 "jsonrpc": "2.0", 7976 "id": 1, 7977 "result": true 7978} 7979~~~ 7980 7981### iscsi_enable_histogram {#rpc_iscsi_enable_histogram} 7982 7983Control whether collecting data for histogram is enabled for specified iscsi target node. 7984 7985#### Parameters 7986 7987Name | Optional | Type | Description 7988----------------------- | -------- | ----------- | ----------- 7989name | Required | string | Iscsi target node name 7990enable | Required | boolean | Enable or disable histogram on specified target node 7991 7992#### Example 7993 7994Example request: 7995 7996~~~json 7997{ 7998 "jsonrpc": "2.0", 7999 "id": 1, 8000 "method": "iscsi_enable_histogram", 8001 "params": { 8002 "name": "iqn.2016-06.io.spdk:target1" 8003 "enable": true 8004 } 8005} 8006~~~ 8007 8008Example response: 8009 8010~~~json 8011{ 8012 "jsonrpc": "2.0", 8013 "id": 1, 8014 "result": true 8015} 8016~~~ 8017 8018## NVMe-oF Target {#jsonrpc_components_nvmf_tgt} 8019 8020### nvmf_create_transport method {#rpc_nvmf_create_transport} 8021 8022Initialize an NVMe-oF transport with the given options. 8023 8024#### Parameters 8025 8026Name | Optional | Type | Description 8027--------------------------- | -------- | --------| ----------- 8028trtype | Required | string | Transport type (ex. RDMA) 8029tgt_name | Optional | string | Parent NVMe-oF target name. 8030max_queue_depth | Optional | number | Max number of outstanding I/O per queue 8031max_io_qpairs_per_ctrlr | Optional | number | Max number of IO qpairs per controller 8032in_capsule_data_size | Optional | number | Max number of in-capsule data size 8033max_io_size | Optional | number | Max I/O size (bytes) 8034io_unit_size | Optional | number | I/O unit size (bytes) 8035max_aq_depth | Optional | number | Max number of admin cmds per AQ 8036num_shared_buffers | Optional | number | The number of pooled data buffers available to the transport 8037buf_cache_size | Optional | number | The number of shared buffers to reserve for each poll group 8038num_cqe | Optional | number | The number of CQ entries. Only used when no_srq=true (RDMA only) 8039max_srq_depth | Optional | number | The number of elements in a per-thread shared receive queue (RDMA only) 8040no_srq | Optional | boolean | Disable shared receive queue even for devices that support it. (RDMA only) 8041c2h_success | Optional | boolean | Disable C2H success optimization (TCP only) 8042dif_insert_or_strip | Optional | boolean | Enable DIF insert for write I/O and DIF strip for read I/O DIF 8043sock_priority | Optional | number | The socket priority of the connection owned by this transport (TCP only) 8044acceptor_backlog | Optional | number | The number of pending connections allowed in backlog before failing new connection attempts (RDMA only) 8045abort_timeout_sec | Optional | number | Abort execution timeout value, in seconds 8046no_wr_batching | Optional | boolean | Disable work requests batching (RDMA only) 8047control_msg_num | Optional | number | The number of control messages per poll group (TCP only) 8048disable_mappable_bar0 | Optional | boolean | disable client mmap() of BAR0 (VFIO-USER only) 8049disable_adaptive_irq | Optional | boolean | Disable adaptive interrupt feature (VFIO-USER only) 8050disable_shadow_doorbells | Optional | boolean | disable shadow doorbell support (VFIO-USER only) 8051zcopy | Optional | boolean | Use zero-copy operations if the underlying bdev supports them 8052ack_timeout | Optional | number | ACK timeout in milliseconds 8053data_wr_pool_size | Optional | number | RDMA data WR pool size (RDMA only) 8054 8055#### Example 8056 8057Example request: 8058 8059~~~json 8060{ 8061 "jsonrpc": "2.0", 8062 "method": "nvmf_create_transport", 8063 "id": 1, 8064 "params": { 8065 "trtype": "RDMA", 8066 "max_queue_depth": 32 8067 } 8068} 8069~~~ 8070 8071Example response: 8072 8073~~~json 8074{ 8075 "jsonrpc": "2.0", 8076 "id": 1, 8077 "result": true 8078} 8079~~~ 8080 8081### nvmf_get_subsystems method {#rpc_nvmf_get_subsystems} 8082 8083#### Parameters 8084 8085Name | Optional | Type | Description 8086--------------------------- | -------- | ------------| ----------- 8087tgt_name | Optional | string | Parent NVMe-oF target name. 8088 8089#### Example 8090 8091Example request: 8092 8093~~~json 8094{ 8095 "jsonrpc": "2.0", 8096 "id": 1, 8097 "method": "nvmf_get_subsystems" 8098} 8099~~~ 8100 8101Example response: 8102 8103~~~json 8104{ 8105 "jsonrpc": "2.0", 8106 "id": 1, 8107 "result": [ 8108 { 8109 "nqn": "nqn.2014-08.org.nvmexpress.discovery", 8110 "subtype": "Discovery" 8111 "listen_addresses": [], 8112 "hosts": [], 8113 "allow_any_host": true 8114 }, 8115 { 8116 "nqn": "nqn.2016-06.io.spdk:cnode1", 8117 "subtype": "NVMe", 8118 "listen_addresses": [ 8119 { 8120 "trtype": "RDMA", 8121 "adrfam": "IPv4", 8122 "traddr": "192.168.0.123", 8123 "trsvcid": "4420" 8124 } 8125 ], 8126 "hosts": [ 8127 {"nqn": "nqn.2016-06.io.spdk:host1"} 8128 ], 8129 "allow_any_host": false, 8130 "serial_number": "abcdef", 8131 "model_number": "ghijklmnop", 8132 "namespaces": [ 8133 {"nsid": 1, "name": "Malloc2"}, 8134 {"nsid": 2, "name": "Nvme0n1"} 8135 ] 8136 } 8137 ] 8138} 8139~~~ 8140 8141### nvmf_create_subsystem method {#rpc_nvmf_create_subsystem} 8142 8143Construct an NVMe over Fabrics target subsystem. 8144 8145#### Parameters 8146 8147Name | Optional | Type | Description 8148-------------------------- | -------- | ----------- | ----------- 8149nqn | Required | string | Subsystem NQN 8150tgt_name | Optional | string | Parent NVMe-oF target name. 8151serial_number | Optional | string | Serial number of virtual controller 8152model_number | Optional | string | Model number of virtual controller 8153max_namespaces | Optional | number | Maximum number of namespaces that can be attached to the subsystem. Default: 32 (also used if user specifies 0) 8154allow_any_host | Optional | boolean | Allow any host (`true`) or enforce allowed host list (`false`). Default: `false`. 8155ana_reporting | Optional | boolean | Enable ANA reporting feature (default: `false`). 8156min_cntlid | Optional | number | Minimum controller ID. Default: 1 8157max_cntlid | Optional | number | Maximum controller ID. Default: 0xffef 8158max_discard_size_kib | Optional | number | Maximum discard size (Kib). Default: 0 8159max_write_zeroes_size_kib | Optional | number | Maximum write_zeroes size (Kib). Default: 0 8160 8161#### Example 8162 8163Example request: 8164 8165~~~json 8166{ 8167 "jsonrpc": "2.0", 8168 "id": 1, 8169 "method": "nvmf_create_subsystem", 8170 "params": { 8171 "nqn": "nqn.2016-06.io.spdk:cnode1", 8172 "allow_any_host": false, 8173 "serial_number": "abcdef", 8174 "model_number": "ghijklmnop" 8175 } 8176} 8177~~~ 8178 8179Example response: 8180 8181~~~json 8182{ 8183 "jsonrpc": "2.0", 8184 "id": 1, 8185 "result": true 8186} 8187~~~ 8188 8189### nvmf_delete_subsystem method {#rpc_nvmf_delete_subsystem} 8190 8191Delete an existing NVMe-oF subsystem. 8192 8193#### Parameters 8194 8195Parameter | Optional | Type | Description 8196---------------------- | -------- | ----------- | ----------- 8197nqn | Required | string | Subsystem NQN to delete. 8198tgt_name | Optional | string | Parent NVMe-oF target name. 8199 8200#### Example 8201 8202Example request: 8203 8204~~~json 8205{ 8206 "jsonrpc": "2.0", 8207 "id": 1, 8208 "method": "nvmf_delete_subsystem", 8209 "params": { 8210 "nqn": "nqn.2016-06.io.spdk:cnode1" 8211 } 8212} 8213~~~ 8214 8215Example response: 8216 8217~~~json 8218{ 8219 "jsonrpc": "2.0", 8220 "id": 1, 8221 "result": true 8222} 8223~~~ 8224 8225### nvmf_subsystem_add_listener method {#rpc_nvmf_subsystem_add_listener} 8226 8227Add a new listen address to an NVMe-oF subsystem. 8228 8229#### Parameters 8230 8231Name | Optional | Type | Description 8232----------------------- | -------- | ----------- | ----------- 8233nqn | Required | string | Subsystem NQN 8234tgt_name | Optional | string | Parent NVMe-oF target name. 8235listen_address | Required | object | @ref rpc_nvmf_listen_address object 8236secure_channel | Optional | bool | Whether all connections immediately attempt to establish a secure channel 8237 8238#### listen_address {#rpc_nvmf_listen_address} 8239 8240The listen_address is used for adding the listeners to the NVMe-oF target 8241and for referring to discovery services on other targets. 8242 8243Name | Optional | Type | Description 8244----------------------- | -------- | ----------- | ----------- 8245trtype | Required | string | Transport type ("RDMA") 8246adrfam | Required | string | Address family ("IPv4", "IPv6", "IB", or "FC") 8247traddr | Required | string | Transport address 8248trsvcid | Optional | string | Transport service ID (required for RDMA or TCP) 8249 8250#### Example 8251 8252Example request: 8253 8254~~~json 8255{ 8256 "jsonrpc": "2.0", 8257 "id": 1, 8258 "method": "nvmf_subsystem_add_listener", 8259 "params": { 8260 "nqn": "nqn.2016-06.io.spdk:cnode1", 8261 "listen_address": { 8262 "trtype": "RDMA", 8263 "adrfam": "IPv4", 8264 "traddr": "192.168.0.123", 8265 "trsvcid": "4420" 8266 } 8267 } 8268} 8269~~~ 8270 8271Example response: 8272 8273~~~json 8274{ 8275 "jsonrpc": "2.0", 8276 "id": 1, 8277 "result": true 8278} 8279~~~ 8280 8281### nvmf_subsystem_remove_listener method {#rpc_nvmf_subsystem_remove_listener} 8282 8283Remove a listen address from an NVMe-oF subsystem. 8284 8285#### Parameters 8286 8287Name | Optional | Type | Description 8288----------------------- | -------- | ----------- | ----------- 8289nqn | Required | string | Subsystem NQN 8290tgt_name | Optional | string | Parent NVMe-oF target name. 8291listen_address | Required | object | @ref rpc_nvmf_listen_address object 8292 8293#### Example 8294 8295Example request: 8296 8297~~~json 8298{ 8299 "jsonrpc": "2.0", 8300 "id": 1, 8301 "method": "nvmf_subsystem_remove_listener", 8302 "params": { 8303 "nqn": "nqn.2016-06.io.spdk:cnode1", 8304 "listen_address": { 8305 "trtype": "RDMA", 8306 "adrfam": "IPv4", 8307 "traddr": "192.168.0.123", 8308 "trsvcid": "4420" 8309 } 8310 } 8311} 8312~~~ 8313 8314Example response: 8315 8316~~~json 8317{ 8318 "jsonrpc": "2.0", 8319 "id": 1, 8320 "result": true 8321} 8322~~~ 8323 8324### nvmf_subsystem_listener_set_ana_state method {#rpc_nvmf_subsystem_listener_set_ana_state} 8325 8326Set ANA state of a listener for an NVMe-oF subsystem. Only the ANA state of the specified ANA 8327group is updated, or ANA states of all ANA groups if ANA group is not specified. 8328 8329#### Parameters 8330 8331Name | Optional | Type | Description 8332----------------------- | -------- | ----------- | ----------- 8333nqn | Required | string | Subsystem NQN 8334tgt_name | Optional | string | Parent NVMe-oF target name. 8335listen_address | Required | object | @ref rpc_nvmf_listen_address object 8336ana_state | Required | string | ANA state to set ("optimized", "non_optimized", or "inaccessible") 8337anagrpid | Optional | number | ANA group ID 8338 8339#### Example 8340 8341Example request: 8342 8343~~~json 8344{ 8345 "jsonrpc": "2.0", 8346 "id": 1, 8347 "method": "nvmf_subsystem_listener_set_ana_state", 8348 "params": { 8349 "nqn": "nqn.2016-06.io.spdk:cnode1", 8350 "listen_address": { 8351 "trtype": "RDMA", 8352 "adrfam": "IPv4", 8353 "traddr": "192.168.0.123", 8354 "trsvcid": "4420" 8355 }, 8356 "ana_state", "inaccessible" 8357 } 8358} 8359~~~ 8360 8361Example response: 8362 8363~~~json 8364{ 8365 "jsonrpc": "2.0", 8366 "id": 1, 8367 "result": true 8368} 8369~~~ 8370 8371### nvmf_subsystem_add_ns method {#rpc_nvmf_subsystem_add_ns} 8372 8373Add a namespace to a subsystem. The namespace ID is returned as the result. 8374 8375### Parameters 8376 8377Name | Optional | Type | Description 8378----------------------- | -------- | ----------- | ----------- 8379nqn | Required | string | Subsystem NQN 8380namespace | Required | object | @ref rpc_nvmf_namespace object 8381tgt_name | Optional | string | Parent NVMe-oF target name. 8382no_auto_visible | Optional | bool | Namespace is not automatically visible to controllers (default: false) 8383 8384#### namespace {#rpc_nvmf_namespace} 8385 8386Name | Optional | Type | Description 8387----------------------- | -------- | ----------- | ----------- 8388nsid | Optional | number | Namespace ID between 1 and 4294967294, inclusive. Default: Automatically assign NSID. 8389bdev_name | Required | string | Name of bdev to expose as a namespace. 8390nguid | Optional | string | 16-byte namespace globally unique identifier in hexadecimal (e.g. "ABCDEF0123456789ABCDEF0123456789") 8391eui64 | Optional | string | 8-byte namespace EUI-64 in hexadecimal (e.g. "ABCDEF0123456789") 8392uuid | Optional | string | RFC 4122 UUID (e.g. "ceccf520-691e-4b46-9546-34af789907c5") 8393ptpl_file | Optional | string | File path to save/restore persistent reservation information 8394anagrpid | Optional | number | ANA group ID. Default: Namespace ID. 8395 8396#### Example 8397 8398Example request: 8399 8400~~~json 8401{ 8402 "jsonrpc": "2.0", 8403 "id": 1, 8404 "method": "nvmf_subsystem_add_ns", 8405 "params": { 8406 "nqn": "nqn.2016-06.io.spdk:cnode1", 8407 "namespace": { 8408 "nsid": 3, 8409 "bdev_name": "Nvme0n1", 8410 "ptpl_file": "/opt/Nvme0n1PR.json" 8411 } 8412 } 8413} 8414~~~ 8415 8416Example response: 8417 8418~~~json 8419{ 8420 "jsonrpc": "2.0", 8421 "id": 1, 8422 "result": 3 8423} 8424~~~ 8425 8426### nvmf_subsystem_remove_ns method {#rpc_nvmf_subsystem_remove_ns} 8427 8428Remove a namespace from a subsystem. 8429 8430#### Parameters 8431 8432Name | Optional | Type | Description 8433----------------------- | -------- | ----------- | ----------- 8434nqn | Required | string | Subsystem NQN 8435nsid | Required | number | Namespace ID 8436tgt_name | Optional | string | Parent NVMe-oF target name. 8437 8438#### Example 8439 8440Example request: 8441 8442~~~json 8443{ 8444 "jsonrpc": "2.0", 8445 "id": 1, 8446 "method": "nvmf_subsystem_remove_ns", 8447 "params": { 8448 "nqn": "nqn.2016-06.io.spdk:cnode1", 8449 "nsid": 1 8450 } 8451} 8452~~~ 8453 8454Example response: 8455 8456~~~json 8457{ 8458 "jsonrpc": "2.0", 8459 "id": 1, 8460 "result": true 8461} 8462~~~ 8463 8464### nvmf_subsystem_add_host method {#rpc_nvmf_subsystem_add_host} 8465 8466Add a host NQN to the list of allowed hosts. 8467 8468#### Parameters 8469 8470Name | Optional | Type | Description 8471----------------------- | -------- | ----------- | ----------- 8472nqn | Required | string | Subsystem NQN 8473host | Required | string | Host NQN to add to the list of allowed host NQNs 8474tgt_name | Optional | string | Parent NVMe-oF target name. 8475psk | Optional | string | Path to a file containing PSK for TLS connection 8476 8477#### Example 8478 8479Example request: 8480 8481~~~json 8482{ 8483 "jsonrpc": "2.0", 8484 "id": 1, 8485 "method": "nvmf_subsystem_add_host", 8486 "params": { 8487 "nqn": "nqn.2016-06.io.spdk:cnode1", 8488 "host": "nqn.2016-06.io.spdk:host1" 8489 } 8490} 8491~~~ 8492 8493Example response: 8494 8495~~~json 8496{ 8497 "jsonrpc": "2.0", 8498 "id": 1, 8499 "result": true 8500} 8501~~~ 8502 8503### nvmf_subsystem_remove_host method {#rpc_nvmf_subsystem_remove_host} 8504 8505Remove a host NQN from the list of allowed hosts. 8506 8507#### Parameters 8508 8509Name | Optional | Type | Description 8510----------------------- | -------- | ----------- | ----------- 8511nqn | Required | string | Subsystem NQN 8512host | Required | string | Host NQN to remove from the list of allowed host NQNs 8513tgt_name | Optional | string | Parent NVMe-oF target name. 8514 8515#### Example 8516 8517Example request: 8518 8519~~~json 8520{ 8521 "jsonrpc": "2.0", 8522 "id": 1, 8523 "method": "nvmf_subsystem_remove_host", 8524 "params": { 8525 "nqn": "nqn.2016-06.io.spdk:cnode1", 8526 "host": "nqn.2016-06.io.spdk:host1" 8527 } 8528} 8529~~~ 8530 8531Example response: 8532 8533~~~json 8534{ 8535 "jsonrpc": "2.0", 8536 "id": 1, 8537 "result": true 8538} 8539~~~ 8540 8541### nvmf_subsystem_allow_any_host method {#rpc_nvmf_subsystem_allow_any_host} 8542 8543Configure a subsystem to allow any host to connect or to enforce the host NQN list. 8544 8545#### Parameters 8546 8547Name | Optional | Type | Description 8548----------------------- | -------- | ----------- | ----------- 8549nqn | Required | string | Subsystem NQN 8550allow_any_host | Required | boolean | Allow any host (`true`) or enforce allowed host list (`false`). 8551tgt_name | Optional | string | Parent NVMe-oF target name. 8552 8553#### Example 8554 8555Example request: 8556 8557~~~json 8558{ 8559 "jsonrpc": "2.0", 8560 "id": 1, 8561 "method": "nvmf_subsystem_allow_any_host", 8562 "params": { 8563 "nqn": "nqn.2016-06.io.spdk:cnode1", 8564 "allow_any_host": true 8565 } 8566} 8567~~~ 8568 8569Example response: 8570 8571~~~json 8572{ 8573 "jsonrpc": "2.0", 8574 "id": 1, 8575 "result": true 8576} 8577~~~ 8578 8579### nvmf_subsystem_get_controllers {#rpc_nvmf_subsystem_get_controllers} 8580 8581#### Parameters 8582 8583Name | Optional | Type | Description 8584----------------------- | -------- | ----------- | ----------- 8585nqn | Required | string | Subsystem NQN 8586tgt_name | Optional | string | Parent NVMe-oF target name. 8587 8588#### Example 8589 8590Example request: 8591 8592~~~json 8593{ 8594 "jsonrpc": "2.0", 8595 "id": 1, 8596 "method": "nvmf_subsystem_get_controllers", 8597 "params": { 8598 "nqn": "nqn.2016-06.io.spdk:cnode1" 8599 } 8600} 8601~~~ 8602 8603Example response: 8604 8605~~~json 8606{ 8607 "jsonrpc": "2.0", 8608 "id": 1, 8609 "result": [ 8610 { 8611 "cntlid": 1, 8612 "hostnqn": "nqn.2016-06.io.spdk:host1", 8613 "hostid": "27dad528-6368-41c3-82d3-0b956b49025d", 8614 "num_io_qpairs": 5 8615 } 8616 ] 8617} 8618~~~ 8619 8620### nvmf_subsystem_get_qpairs {#rpc_nvmf_subsystem_get_qpairs} 8621 8622#### Parameters 8623 8624Name | Optional | Type | Description 8625----------------------- | -------- | ----------- | ----------- 8626nqn | Required | string | Subsystem NQN 8627tgt_name | Optional | string | Parent NVMe-oF target name. 8628 8629#### Example 8630 8631Example request: 8632 8633~~~json 8634{ 8635 "jsonrpc": "2.0", 8636 "id": 1, 8637 "method": "nvmf_subsystem_get_qpairs", 8638 "params": { 8639 "nqn": "nqn.2016-06.io.spdk:cnode1" 8640 } 8641} 8642~~~ 8643 8644Example response: 8645 8646~~~json 8647{ 8648 "jsonrpc": "2.0", 8649 "id": 1, 8650 "result": [ 8651 { 8652 "cntlid": 1, 8653 "qid": 0, 8654 "state": "active", 8655 "listen_address": { 8656 "trtype": "RDMA", 8657 "adrfam": "IPv4", 8658 "traddr": "192.168.0.123", 8659 "trsvcid": "4420" 8660 } 8661 }, 8662 { 8663 "cntlid": 1, 8664 "qid": 1, 8665 "state": "active", 8666 "listen_address": { 8667 "trtype": "RDMA", 8668 "adrfam": "IPv4", 8669 "traddr": "192.168.0.123", 8670 "trsvcid": "4420" 8671 } 8672 } 8673 ] 8674} 8675~~~ 8676 8677### nvmf_subsystem_get_listeners {#rpc_nvmf_subsystem_get_listeners} 8678 8679#### Parameters 8680 8681Name | Optional | Type | Description 8682----------------------- | -------- | ----------- | ----------- 8683nqn | Required | string | Subsystem NQN 8684tgt_name | Optional | string | Parent NVMe-oF target name. 8685 8686#### Example 8687 8688Example request: 8689 8690~~~json 8691{ 8692 "jsonrpc": "2.0", 8693 "id": 1, 8694 "method": "nvmf_subsystem_get_listeners", 8695 "params": { 8696 "nqn": "nqn.2016-06.io.spdk:cnode1" 8697 } 8698} 8699~~~ 8700 8701Example response: 8702 8703~~~json 8704{ 8705 "jsonrpc": "2.0", 8706 "id": 1, 8707 "result": [ 8708 { 8709 "address": { 8710 "trtype": "RDMA", 8711 "adrfam": "IPv4", 8712 "traddr": "192.168.0.123", 8713 "trsvcid": "4420" 8714 }, 8715 "ana_state": "optimized" 8716 } 8717 ] 8718} 8719~~~ 8720 8721### nvmf_ns_add_host {#rpc_nvmf_ns_add_host} 8722 8723Make the specified namespace of the specified subnqn visible to any existing 8724or future controllers with the specified hostnqn. 8725 8726Note: the namespace must have been added with no_auto_visible = false 8727(see @ref rpc_nvmf_subsystem_add_ns). 8728 8729#### Parameters 8730 8731Name | Optional | Type | Description 8732----------------------- | -------- | ----------- | ----------- 8733nqn | Required | string | Subsystem NQN 8734nsid | Required | number | Namespace ID 8735host | Required | string | Host NQN 8736 8737#### Example 8738 8739Example request: 8740 8741~~~json 8742{ 8743 "jsonrpc": "2.0", 8744 "id": 1, 8745 "method": "nvmf_ns_add_host", 8746 "params": { 8747 "nqn": "nqn.2016-06.io.spdk:cnode1", 8748 "nsid": 1, 8749 "host": "nqn.2024-01.io.spdk:host0" 8750 } 8751} 8752~~~ 8753 8754Example response: 8755 8756~~~json 8757{ 8758 "jsonrpc": "2.0", 8759 "id": 1, 8760 "result": true 8761} 8762~~~ 8763 8764### nvmf_ns_remove_host {#rpc_nvmf_ns_remove_host} 8765 8766Make the specified namespace of the specified subnqn not visible to any existing 8767or future controllers with the specified hostnqn. 8768 8769Note: the namespace must have been added to the subsystem with 8770no_auto_visible = false (see @ref rpc_nvmf_subsystem_add_ns). 8771 8772#### Parameters 8773 8774Name | Optional | Type | Description 8775----------------------- | -------- | ----------- | ----------- 8776nqn | Required | string | Subsystem NQN 8777nsid | Required | number | Namespace ID 8778host | Required | string | Host NQN 8779 8780#### Example 8781 8782Example request: 8783 8784~~~json 8785{ 8786 "jsonrpc": "2.0", 8787 "id": 1, 8788 "method": "nvmf_ns_remove_host", 8789 "params": { 8790 "nqn": "nqn.2016-06.io.spdk:cnode1", 8791 "nsid": 1, 8792 "host": "nqn.2024-01.io.spdk:host0" 8793 } 8794} 8795~~~ 8796 8797Example response: 8798 8799~~~json 8800{ 8801 "jsonrpc": "2.0", 8802 "id": 1, 8803 "result": true 8804} 8805~~~ 8806 8807### nvmf_set_max_subsystems {#rpc_nvmf_set_max_subsystems} 8808 8809Set the maximum allowed subsystems for the NVMe-oF target. This RPC may only be called 8810before SPDK subsystems have been initialized. 8811 8812#### Parameters 8813 8814Name | Optional | Type | Description 8815----------------------- | -------- | ----------- | ----------- 8816max_subsystems | Required | number | Maximum number of NVMe-oF subsystems 8817 8818#### Example 8819 8820Example request: 8821 8822~~~json 8823{ 8824 "jsonrpc": "2.0", 8825 "id": 1, 8826 "method": "nvmf_set_max_subsystems", 8827 "params": { 8828 "max_subsystems": 1024 8829 } 8830} 8831~~~ 8832 8833Example response: 8834 8835~~~json 8836{ 8837 "jsonrpc": "2.0", 8838 "id": 1, 8839 "result": true 8840} 8841~~~ 8842 8843### nvmf_discovery_add_referral method {#rpc_nvmf_discovery_add_referral} 8844 8845Add a discovery service referral to an NVMe-oF target. If a referral with the given 8846parameters already exists, no action will be taken. 8847 8848#### Parameters 8849 8850Name | Optional | Type | Description 8851----------------------- | -------- | ----------- | ----------- 8852tgt_name | Optional | string | Parent NVMe-oF target name. 8853address | Required | object | @ref rpc_nvmf_listen_address object 8854secure_channel | Optional | bool | The connection to that discovery subsystem requires a secure channel 8855 8856#### Example 8857 8858Example request: 8859 8860~~~json 8861{ 8862 "jsonrpc": "2.0", 8863 "id": 1, 8864 "method": "nvmf_discovery_add_referral", 8865 "params": { 8866 "address": { 8867 "trtype": "RDMA", 8868 "adrfam": "IPv4", 8869 "traddr": "192.168.0.123", 8870 "trsvcid": "4420" 8871 } 8872 } 8873} 8874~~~ 8875 8876Example response: 8877 8878~~~json 8879{ 8880 "jsonrpc": "2.0", 8881 "id": 1, 8882 "result": true 8883} 8884~~~ 8885 8886### nvmf_discovery_remove_referral method {#rpc_nvmf_discovery_remove_referral} 8887 8888Remove a discovery service referral from an NVMe-oF target. 8889 8890#### Parameters 8891 8892Name | Optional | Type | Description 8893----------------------- | -------- | ----------- | ----------- 8894tgt_name | Optional | string | Parent NVMe-oF target name. 8895address | Required | object | @ref rpc_nvmf_listen_address object 8896 8897#### Example 8898 8899Example request: 8900 8901~~~json 8902{ 8903 "jsonrpc": "2.0", 8904 "id": 1, 8905 "method": "nvmf_discovery_remove_referral", 8906 "params": { 8907 "address": { 8908 "trtype": "RDMA", 8909 "adrfam": "IPv4", 8910 "traddr": "192.168.0.123", 8911 "trsvcid": "4420" 8912 } 8913 } 8914} 8915~~~ 8916 8917Example response: 8918 8919~~~json 8920{ 8921 "jsonrpc": "2.0", 8922 "id": 1, 8923 "result": true 8924} 8925~~~ 8926 8927### nvmf_discovery_get_referrals {#rpc_nvmf_discovery_get_referrals} 8928 8929#### Parameters 8930 8931Name | Optional | Type | Description 8932----------------------- | -------- | ----------- | ----------- 8933tgt_name | Optional | string | Parent NVMe-oF target name. 8934 8935#### Example 8936 8937Example request: 8938 8939~~~json 8940{ 8941 "jsonrpc": "2.0", 8942 "id": 1, 8943 "method": "nvmf_discovery_get_referrals" 8944} 8945~~~ 8946 8947Example response: 8948 8949~~~json 8950{ 8951 "jsonrpc": "2.0", 8952 "id": 1, 8953 "result": [ 8954 { 8955 "address": { 8956 "trtype": "RDMA", 8957 "adrfam": "IPv4", 8958 "traddr": "192.168.0.123", 8959 "trsvcid": "4420" 8960 } 8961 } 8962 ] 8963} 8964~~~ 8965 8966### nvmf_set_config {#rpc_nvmf_set_config} 8967 8968Set global configuration of NVMe-oF target. This RPC may only be called before SPDK subsystems 8969have been initialized. 8970 8971#### Parameters 8972 8973Name | Optional | Type | Description 8974----------------------- | -------- | ----------- | ----------- 8975acceptor_poll_rate | Optional | number | Polling interval of the acceptor for incoming connections (microseconds) 8976admin_cmd_passthru | Optional | object | Admin command passthru configuration 8977poll_groups_mask | Optional | string | Set cpumask for NVMf poll groups 8978discovery_filter | Optional | string | Set discovery filter, possible values are: `match_any` (default) or comma separated values: `transport`, `address`, `svcid` 8979 8980#### admin_cmd_passthru {#spdk_nvmf_admin_passthru_conf} 8981 8982Name | Optional | Type | Description 8983----------------------- | -------- | ----------- | ----------- 8984identify_ctrlr | Required | bool | If true, enables custom identify handler that reports some identify attributes from the underlying NVMe drive 8985 8986#### Example 8987 8988Example request: 8989 8990~~~json 8991{ 8992 "jsonrpc": "2.0", 8993 "id": 1, 8994 "method": "nvmf_set_config", 8995 "params": { 8996 "acceptor_poll_rate": 10000 8997 } 8998} 8999~~~ 9000 9001Example response: 9002 9003~~~json 9004{ 9005 "jsonrpc": "2.0", 9006 "id": 1, 9007 "result": true 9008} 9009~~~ 9010 9011### nvmf_get_transports method {#rpc_nvmf_get_transports} 9012 9013#### Parameters 9014 9015The user may specify no parameters in order to list all transports, or a transport may be 9016specified by type. 9017 9018Name | Optional | Type | Description 9019--------------------------- | -------- | ------------| ----------- 9020tgt_name | Optional | string | Parent NVMe-oF target name. 9021trtype | Optional | string | Transport type. 9022 9023#### Example 9024 9025Example request: 9026 9027~~~json 9028{ 9029 "jsonrpc": "2.0", 9030 "id": 1, 9031 "method": "nvmf_get_transports" 9032} 9033~~~ 9034 9035Example response: 9036 9037~~~json 9038{ 9039 "jsonrpc": "2.0", 9040 "id": 1, 9041 "result": [ 9042 { 9043 "type": "RDMA". 9044 "max_queue_depth": 128, 9045 "max_io_qpairs_per_ctrlr": 64, 9046 "in_capsule_data_size": 4096, 9047 "max_io_size": 131072, 9048 "io_unit_size": 131072, 9049 "abort_timeout_sec": 1 9050 } 9051 ] 9052} 9053~~~ 9054 9055### nvmf_get_stats method {#rpc_nvmf_get_stats} 9056 9057Retrieve current statistics of the NVMf subsystem. 9058 9059#### Parameters 9060 9061Name | Optional | Type | Description 9062--------------------------- | -------- | ------------| ----------- 9063tgt_name | Optional | string | Parent NVMe-oF target name. 9064 9065#### Response 9066 9067The response is an object containing NVMf subsystem statistics. 9068In the response, `admin_qpairs` and `io_qpairs` are reflecting cumulative queue pair counts while 9069`current_admin_qpairs` and `current_io_qpairs` are showing the current number. 9070 9071#### Example 9072 9073Example request: 9074 9075~~~json 9076{ 9077 "jsonrpc": "2.0", 9078 "method": "nvmf_get_stats", 9079 "id": 1 9080} 9081~~~ 9082 9083Example response: 9084 9085~~~json 9086{ 9087 "jsonrpc": "2.0", 9088 "id": 1, 9089 "result": { 9090 "tick_rate": 2400000000, 9091 "poll_groups": [ 9092 { 9093 "name": "app_thread", 9094 "admin_qpairs": 1, 9095 "io_qpairs": 4, 9096 "current_admin_qpairs": 1, 9097 "current_io_qpairs": 2, 9098 "pending_bdev_io": 1721, 9099 "transports": [ 9100 { 9101 "trtype": "RDMA", 9102 "pending_data_buffer": 12131888, 9103 "devices": [ 9104 { 9105 "name": "mlx5_1", 9106 "polls": 72284105, 9107 "completions": 0, 9108 "requests": 0, 9109 "request_latency": 0, 9110 "pending_free_request": 0, 9111 "pending_rdma_read": 0, 9112 "pending_rdma_write": 0, 9113 "total_send_wrs": 0, 9114 "send_doorbell_updates": 0, 9115 "total_recv_wrs": 0, 9116 "recv_doorbell_updates": 1 9117 }, 9118 { 9119 "name": "mlx5_0", 9120 "polls": 72284105, 9121 "completions": 15165875, 9122 "requests": 7582935, 9123 "request_latency": 1249323766184, 9124 "pending_free_request": 0, 9125 "pending_rdma_read": 337602, 9126 "pending_rdma_write": 0, 9127 "total_send_wrs": 15165875, 9128 "send_doorbell_updates": 1516587, 9129 "total_recv_wrs": 15165875, 9130 "recv_doorbell_updates": 1516587 9131 } 9132 ] 9133 } 9134 ] 9135 } 9136 ] 9137 } 9138} 9139~~~ 9140 9141### nvmf_set_crdt {#rpc_nvmf_set_crdt} 9142 9143Set the 3 CRDT (Command Retry Delay Time) values. For details about 9144CRDT, please refer to the NVMe specification. Currently all the 9145SPDK nvmf subsystems share the same CRDT values. The default values 9146are 0. This rpc can only be invoked in STARTUP stage. All values are 9147in units of 100 milliseconds (same as the NVMe specification). 9148 9149#### Parameters 9150 9151Name | Optional | Type | Description 9152----------------------- | -------- | ----------- | ----------- 9153crdt1 | Optional | number | Command Retry Delay Time 1 9154crdt2 | Optional | number | Command Retry Delay Time 2 9155crdt3 | Optional | number | Command Retry Delay Time 3 9156 9157## Vfio-user Target 9158 9159### vfu_tgt_set_base_path {#rpc_vfu_tgt_set_base_path} 9160 9161Set base path of Unix Domain socket file. 9162 9163#### Parameters 9164 9165Name | Optional | Type | Description 9166----------------------- | -------- | ----------- | ----------- 9167path | Required | string | Base path 9168 9169#### Example 9170 9171Example request: 9172 9173~~~json 9174{ 9175 "params": { 9176 "path": "/var/run/vfu_tgt" 9177 }, 9178 "jsonrpc": "2.0", 9179 "method": "vfu_tgt_set_base_path", 9180 "id": 1 9181} 9182~~~ 9183 9184Example response: 9185 9186~~~json 9187{ 9188 "jsonrpc": "2.0", 9189 "id": 1, 9190 "result": true 9191} 9192~~~ 9193 9194### vfu_virtio_delete_endpoint {#rpc_vfu_virtio_delete_endpoint} 9195 9196Delete PCI device via endpoint name. 9197 9198#### Parameters 9199 9200Name | Optional | Type | Description 9201----------------------- | -------- | ----------- | ----------- 9202name | Required | string | Endpoint name 9203 9204#### Example 9205 9206Example request: 9207 9208~~~json 9209{ 9210 "params": { 9211 "name": "vfu.0" 9212 }, 9213 "jsonrpc": "2.0", 9214 "method": "vfu_virtio_delete_endpoint", 9215 "id": 1 9216} 9217~~~ 9218 9219Example response: 9220 9221~~~json 9222{ 9223 "jsonrpc": "2.0", 9224 "id": 1, 9225 "result": true 9226} 9227~~~ 9228 9229### vfu_virtio_create_blk_endpoint {#rpc_vfu_virtio_create_blk_endpoint} 9230 9231Create vfio-user virtio-blk PCI endpoint. 9232 9233#### Parameters 9234 9235Name | Optional | Type | Description 9236----------------------- | -------- | ----------- | ----------- 9237name | Required | string | Endpoint name 9238bdev_name | Required | string | Block device name 9239cpumask | Optional | string | CPU masks 9240num_queues | Optional | number | Number of queues 9241qsize | Optional | number | Queue size 9242packed_ring | Optional | boolean | Enable packed ring 9243 9244#### Example 9245 9246Example request: 9247 9248~~~json 9249{ 9250 "params": { 9251 "name": "vfu.0", 9252 "bdev_name": "Malloc0", 9253 "cpumask": "0x2", 9254 "num_queues": 4, 9255 "qsize": 256 9256 }, 9257 "jsonrpc": "2.0", 9258 "method": "vfu_virtio_create_blk_endpoint", 9259 "id": 1 9260} 9261~~~ 9262 9263Example response: 9264 9265~~~json 9266{ 9267 "jsonrpc": "2.0", 9268 "id": 1, 9269 "result": true 9270} 9271~~~ 9272 9273### vfu_virtio_scsi_add_target {#rpc_vfu_virtio_scsi_add_target} 9274 9275Add block device to specified SCSI target of vfio-user virtio-scsi PCI endpoint. 9276 9277#### Parameters 9278 9279Name | Optional | Type | Description 9280----------------------- | -------- | ----------- | ----------- 9281name | Required | string | Endpoint name 9282scsi_target_num | Required | number | SCSI target number 9283bdev_name | Required | string | Block device name 9284 9285#### Example 9286 9287Example request: 9288 9289~~~json 9290{ 9291 "params": { 9292 "name": "vfu.0", 9293 "scsi_target_num": 0, 9294 "bdev_name": "Malloc0" 9295 }, 9296 "jsonrpc": "2.0", 9297 "method": "vfu_virtio_scsi_add_target", 9298 "id": 1 9299} 9300~~~ 9301 9302Example response: 9303 9304~~~json 9305{ 9306 "jsonrpc": "2.0", 9307 "id": 1, 9308 "result": true 9309} 9310~~~ 9311 9312### vfu_virtio_scsi_remove_target {#rpc_vfu_virtio_scsi_remove_target} 9313 9314Remove a SCSI target of vfio-user virtio-scsi PCI endpoint. 9315 9316#### Parameters 9317 9318Name | Optional | Type | Description 9319----------------------- | -------- | ----------- | ----------- 9320name | Required | string | Endpoint name 9321scsi_target_num | Required | number | SCSI target number 9322 9323#### Example 9324 9325Example request: 9326 9327~~~json 9328{ 9329 "params": { 9330 "name": "vfu.0", 9331 "scsi_target_num": 0 9332 }, 9333 "jsonrpc": "2.0", 9334 "method": "vfu_virtio_scsi_remove_target", 9335 "id": 1 9336} 9337~~~ 9338 9339Example response: 9340 9341~~~json 9342{ 9343 "jsonrpc": "2.0", 9344 "id": 1, 9345 "result": true 9346} 9347~~~ 9348 9349### vfu_virtio_create_scsi_endpoint {#rpc_vfu_virtio_create_scsi_endpoint} 9350 9351Create vfio-user virtio-scsi PCI endpoint. 9352 9353#### Parameters 9354 9355Name | Optional | Type | Description 9356----------------------- | -------- | ----------- | ----------- 9357name | Required | string | Endpoint name 9358cpumask | Optional | string | CPU masks 9359num_io_queues | Optional | number | Number of IO queues 9360qsize | Optional | number | Queue size 9361packed_ring | Optional | boolean | Enable packed ring 9362 9363#### Example 9364 9365Example request: 9366 9367~~~json 9368{ 9369 "params": { 9370 "name": "vfu.0", 9371 "cpumask": "0x2", 9372 "num_io_queues": 4, 9373 "qsize": 256 9374 }, 9375 "jsonrpc": "2.0", 9376 "method": "vfu_virtio_create_scsi_endpoint", 9377 "id": 1 9378} 9379~~~ 9380 9381Example response: 9382 9383~~~json 9384{ 9385 "jsonrpc": "2.0", 9386 "id": 1, 9387 "result": true 9388} 9389~~~ 9390 9391## Vhost Target {#jsonrpc_components_vhost_tgt} 9392 9393The following common preconditions need to be met in all target types. 9394 9395Controller name will be used to create UNIX domain socket. This implies that name concatenated with vhost socket 9396directory path needs to be valid UNIX socket name. 9397 9398@ref cpu_mask parameter is used to choose CPU on which pollers will be launched when new initiator is connecting. 9399It must be a subset of application CPU mask. Default value is CPU mask of the application. 9400 9401### vhost_controller_set_coalescing {#rpc_vhost_controller_set_coalescing} 9402 9403Controls interrupt coalescing for specific target. Because `delay_base_us` is used to calculate delay in CPU ticks 9404there is no hardcoded limit for this parameter. Only limitation is that final delay in CPU ticks might not overflow 940532 bit unsigned integer (which is more than 1s @ 4GHz CPU). In real scenarios `delay_base_us` should be much lower 9406than 150us. To disable coalescing set `delay_base_us` to 0. 9407 9408#### Parameters 9409 9410Name | Optional | Type | Description 9411----------------------- | -------- | ----------- | ----------- 9412ctrlr | Required | string | Controller name 9413delay_base_us | Required | number | Base (minimum) coalescing time in microseconds 9414iops_threshold | Required | number | Coalescing activation level greater than 0 in IO per second 9415 9416#### Example 9417 9418Example request: 9419 9420~~~json 9421{ 9422 "params": { 9423 "iops_threshold": 100000, 9424 "ctrlr": "VhostScsi0", 9425 "delay_base_us": 80 9426 }, 9427 "jsonrpc": "2.0", 9428 "method": "vhost_controller_set_coalescing", 9429 "id": 1 9430} 9431~~~ 9432 9433Example response: 9434 9435~~~json 9436{ 9437 "jsonrpc": "2.0", 9438 "id": 1, 9439 "result": true 9440} 9441~~~ 9442 9443### vhost_create_scsi_controller {#rpc_vhost_create_scsi_controller} 9444 9445Construct vhost SCSI target. 9446 9447#### Parameters 9448 9449Name | Optional | Type | Description 9450----------------------- | -------- | ----------- | ----------- 9451ctrlr | Required | string | Controller name 9452cpumask | Optional | string | @ref cpu_mask for this controller 9453delay | Optional | boolean | If true, delay the controller startup. 9454 9455#### Example 9456 9457Example request: 9458 9459~~~json 9460{ 9461 "params": { 9462 "cpumask": "0x2", 9463 "ctrlr": "VhostScsi0", 9464 "delay": true 9465 }, 9466 "jsonrpc": "2.0", 9467 "method": "vhost_create_scsi_controller", 9468 "id": 1 9469} 9470~~~ 9471 9472Example response: 9473 9474~~~json 9475{ 9476 "jsonrpc": "2.0", 9477 "id": 1, 9478 "result": true 9479} 9480~~~ 9481 9482### vhost_start_scsi_controller {#rpc_vhost_start_scsi_controller} 9483 9484Start vhost SCSI controller, if controller is already started, do nothing. 9485 9486#### Parameters 9487 9488Name | Optional | Type | Description 9489----------------------- | -------- | ----------- | ----------- 9490ctrlr | Required | string | Controller name 9491 9492#### Example 9493 9494Example request: 9495 9496~~~json 9497{ 9498 "params": { 9499 "ctrlr": "VhostScsi0", 9500 }, 9501 "jsonrpc": "2.0", 9502 "method": "vhost_start_scsi_controller", 9503 "id": 1 9504} 9505~~~ 9506 9507Example response: 9508 9509~~~json 9510response: 9511{ 9512 "jsonrpc": "2.0", 9513 "id": 1, 9514 "result": true 9515} 9516~~~ 9517 9518### vhost_scsi_controller_add_target {#rpc_vhost_scsi_controller_add_target} 9519 9520In vhost target `ctrlr` create SCSI target with ID `scsi_target_num` and add `bdev_name` as LUN 0. 9521 9522#### Parameters 9523 9524Name | Optional | Type | Description 9525----------------------- | -------- | ----------- | ----------- 9526ctrlr | Required | string | Controller name 9527scsi_target_num | Required | number | SCSI target ID between 0 and 7 or -1 to use first free ID. 9528bdev_name | Required | string | Name of bdev to expose as a LUN 0 9529 9530#### Response 9531 9532SCSI target ID. 9533 9534#### Example 9535 9536Example request: 9537 9538~~~json 9539{ 9540 "params": { 9541 "scsi_target_num": 1, 9542 "bdev_name": "Malloc0", 9543 "ctrlr": "VhostScsi0" 9544 }, 9545 "jsonrpc": "2.0", 9546 "method": "vhost_scsi_controller_add_target", 9547 "id": 1 9548} 9549~~~ 9550 9551Example response: 9552 9553~~~json 9554response: 9555{ 9556 "jsonrpc": "2.0", 9557 "id": 1, 9558 "result": 1 9559} 9560~~~ 9561 9562### vhost_scsi_controller_remove_target {#rpc_vhost_scsi_controller_remove_target} 9563 9564Remove SCSI target ID `scsi_target_num` from vhost target `scsi_target_num`. 9565 9566This method will fail if initiator is connected, but doesn't support hot-remove (the `VIRTIO_SCSI_F_HOTPLUG` is not negotiated). 9567 9568#### Parameters 9569 9570Name | Optional | Type | Description 9571----------------------- | -------- | ----------- | ----------- 9572ctrlr | Required | string | Controller name 9573scsi_target_num | Required | number | SCSI target ID between 0 and 7 9574 9575#### Example 9576 9577Example request: 9578 9579~~~json 9580request: 9581{ 9582 "params": { 9583 "scsi_target_num": 1, 9584 "ctrlr": "VhostScsi0" 9585 }, 9586 "jsonrpc": "2.0", 9587 "method": "vhost_scsi_controller_remove_target", 9588 "id": 1 9589} 9590~~~ 9591 9592Example response: 9593 9594~~~json 9595{ 9596 "jsonrpc": "2.0", 9597 "id": 1, 9598 "result": true 9599} 9600~~~ 9601 9602### virtio_blk_create_transport {#rpc_virtio_blk_create_transport} 9603 9604Create virtio blk transport. 9605 9606#### Parameters 9607 9608Name | Optional | Type | Description 9609----------------------- | -------- | ----------- | ----------- 9610name | Required | string | Transport name 9611 9612#### Example 9613 9614Example request: 9615 9616~~~json 9617{ 9618 "params": { 9619 "name": "vhost_user_blk" 9620 }, 9621 "jsonrpc": "2.0", 9622 "method": "virtio_blk_create_transport", 9623 "id": 1 9624} 9625~~~ 9626 9627Example response: 9628 9629~~~json 9630{ 9631 "jsonrpc": "2.0", 9632 "id": 1, 9633 "result": true 9634} 9635~~~ 9636 9637### virtio_blk_get_transports {#rpc_virtio_blk_get_transports} 9638 9639#### Parameters 9640 9641The user may specify no parameters in order to list all transports, 9642or a transport name may be specified. 9643 9644Name | Optional | Type | Description 9645--------------------------- | -------- | ------------| ----------- 9646name | Optional | string | Transport name. 9647 9648#### Example 9649 9650Example request: 9651 9652~~~json 9653{ 9654 "jsonrpc": "2.0", 9655 "method": "virtio_blk_get_transports", 9656 "id": 1 9657} 9658~~~ 9659 9660Example response: 9661 9662~~~json 9663{ 9664 "jsonrpc": "2.0", 9665 "id": 1, 9666 "result": [ 9667 { 9668 "name": "vhost_user_blk" 9669 } 9670 ] 9671} 9672~~~ 9673 9674### vhost_create_blk_controller {#rpc_vhost_create_blk_controller} 9675 9676Create vhost block controller 9677 9678If `readonly` is `true` then vhost block target will be created as read only and fail any write requests. 9679The `VIRTIO_BLK_F_RO` feature flag will be offered to the initiator. 9680 9681#### Parameters 9682 9683Name | Optional | Type | Description 9684----------------------- | -------- | ----------- | ----------- 9685ctrlr | Required | string | Controller name 9686bdev_name | Required | string | Name of bdev to expose block device 9687readonly | Optional | boolean | If true, this target will be read only (default: false) 9688cpumask | Optional | string | @ref cpu_mask for this controller 9689transport | Optional | string | virtio blk transport name (default: vhost_user_blk) 9690 9691#### Example 9692 9693Example request: 9694 9695~~~json 9696{ 9697 "params": { 9698 "dev_name": "Malloc0", 9699 "ctrlr": "VhostBlk0" 9700 }, 9701 "jsonrpc": "2.0", 9702 "method": "vhost_create_blk_controller", 9703 "id": 1 9704} 9705~~~ 9706 9707Example response: 9708 9709~~~json 9710{ 9711 "jsonrpc": "2.0", 9712 "id": 1, 9713 "result": true 9714} 9715~~~ 9716 9717### vhost_get_controllers {#rpc_vhost_get_controllers} 9718 9719Display information about all or specific vhost controller(s). 9720 9721#### Parameters 9722 9723The user may specify no parameters in order to list all controllers, or a controller may be 9724specified by name. 9725 9726Name | Optional | Type | Description 9727----------------------- | -------- | ----------- | ----------- 9728name | Optional | string | Vhost controller name 9729 9730#### Response {#rpc_vhost_get_controllers_response} 9731 9732Response is an array of objects describing requested controller(s). Common fields are: 9733 9734Name | Type | Description 9735----------------------- | ----------- | ----------- 9736ctrlr | string | Controller name 9737cpumask | string | @ref cpu_mask of this controller 9738delay_base_us | number | Base (minimum) coalescing time in microseconds (0 if disabled) 9739iops_threshold | number | Coalescing activation level 9740backend_specific | object | Backend specific information 9741 9742### Vhost block {#rpc_vhost_get_controllers_blk} 9743 9744`backend_specific` contains one `block` object of type: 9745 9746Name | Type | Description 9747----------------------- | ----------- | ----------- 9748bdev | string | Backing bdev name or Null if bdev is hot-removed 9749readonly | boolean | True if controllers is readonly, false otherwise 9750 9751### Vhost SCSI {#rpc_vhost_get_controllers_scsi} 9752 9753`backend_specific` contains `scsi` array of following objects: 9754 9755Name | Type | Description 9756----------------------- | ----------- | ----------- 9757target_name | string | Name of this SCSI target 9758id | number | Unique SPDK global SCSI target ID 9759scsi_dev_num | number | SCSI target ID initiator will see when scanning this controller 9760luns | array | array of objects describing @ref rpc_vhost_get_controllers_scsi_luns 9761 9762### Vhost SCSI LUN {#rpc_vhost_get_controllers_scsi_luns} 9763 9764Object of type: 9765 9766Name | Type | Description 9767----------------------- | ----------- | ----------- 9768id | number | SCSI LUN ID 9769bdev_name | string | Backing bdev name 9770 9771### Vhost NVMe {#rpc_vhost_get_controllers_nvme} 9772 9773`backend_specific` contains `namespaces` array of following objects: 9774 9775Name | Type | Description 9776----------------------- | ----------- | ----------- 9777nsid | number | Namespace ID 9778bdev | string | Backing bdev name 9779 9780#### Example 9781 9782Example request: 9783 9784~~~json 9785{ 9786 "jsonrpc": "2.0", 9787 "method": "vhost_get_controllers", 9788 "id": 1 9789} 9790~~~ 9791 9792Example response: 9793 9794~~~json 9795{ 9796 "jsonrpc": "2.0", 9797 "id": 1, 9798 "result": [ 9799 { 9800 "cpumask": "0x2", 9801 "backend_specific": { 9802 "block": { 9803 "readonly": false, 9804 "bdev": "Malloc0" 9805 } 9806 }, 9807 "iops_threshold": 60000, 9808 "ctrlr": "VhostBlk0", 9809 "delay_base_us": 100 9810 }, 9811 { 9812 "cpumask": "0x2", 9813 "backend_specific": { 9814 "scsi": [ 9815 { 9816 "target_name": "Target 2", 9817 "luns": [ 9818 { 9819 "id": 0, 9820 "bdev_name": "Malloc1" 9821 } 9822 ], 9823 "id": 0, 9824 "scsi_dev_num": 2 9825 }, 9826 { 9827 "target_name": "Target 5", 9828 "luns": [ 9829 { 9830 "id": 0, 9831 "bdev_name": "Malloc2" 9832 } 9833 ], 9834 "id": 1, 9835 "scsi_dev_num": 5 9836 } 9837 ] 9838 }, 9839 "iops_threshold": 60000, 9840 "ctrlr": "VhostScsi0", 9841 "delay_base_us": 0 9842 }, 9843 { 9844 "cpumask": "0x2", 9845 "backend_specific": { 9846 "namespaces": [ 9847 { 9848 "bdev": "Malloc3", 9849 "nsid": 1 9850 }, 9851 { 9852 "bdev": "Malloc4", 9853 "nsid": 2 9854 } 9855 ] 9856 }, 9857 "iops_threshold": 60000, 9858 "ctrlr": "VhostNvme0", 9859 "delay_base_us": 0 9860 } 9861 ] 9862} 9863~~~ 9864 9865### vhost_delete_controller {#rpc_vhost_delete_controller} 9866 9867Remove vhost target. 9868 9869This call will fail if there is an initiator connected or there is at least one SCSI target configured in case of 9870vhost SCSI target. In the later case please remove all SCSI targets first using @ref rpc_vhost_scsi_controller_remove_target. 9871 9872#### Parameters 9873 9874Name | Optional | Type | Description 9875----------------------- | -------- | ----------- | ----------- 9876ctrlr | Required | string | Controller name 9877 9878#### Example 9879 9880Example request: 9881 9882~~~json 9883{ 9884 "params": { 9885 "ctrlr": "VhostNvme0" 9886 }, 9887 "jsonrpc": "2.0", 9888 "method": "vhost_delete_controller", 9889 "id": 1 9890} 9891~~~ 9892 9893Example response: 9894 9895~~~json 9896{ 9897 "jsonrpc": "2.0", 9898 "id": 1, 9899 "result": true 9900} 9901~~~ 9902 9903## Logical Volume {#jsonrpc_components_lvol} 9904 9905Identification of logical volume store and logical volume is explained first. 9906 9907A logical volume store has a UUID and a name for its identification. 9908The UUID is generated on creation and it can be used as a unique identifier. 9909The name is specified on creation and can be renamed. 9910Either UUID or name is used to access logical volume store in RPCs. 9911 9912A logical volume has a UUID and a name for its identification. 9913The UUID of the logical volume is generated on creation and it can be unique identifier. 9914The alias of the logical volume takes the format _lvs_name/lvol_name_ where: 9915 9916* _lvs_name_ is the name of the logical volume store. 9917* _lvol_name_ is specified on creation and can be renamed. 9918 9919### bdev_lvol_create_lvstore {#rpc_bdev_lvol_create_lvstore} 9920 9921Construct a logical volume store. 9922 9923#### Parameters 9924 9925Name | Optional | Type | Description 9926----------------------------- | -------- | ----------- | ----------- 9927bdev_name | Required | string | Bdev on which to construct logical volume store 9928lvs_name | Required | string | Name of the logical volume store to create 9929cluster_sz | Optional | number | Cluster size of the logical volume store in bytes (Default: 4MiB) 9930clear_method | Optional | string | Change clear method for data region. Available: none, unmap (default), write_zeroes 9931num_md_pages_per_cluster_ratio| Optional | number | Reserved metadata pages per cluster (Default: 100) 9932 9933The num_md_pages_per_cluster_ratio defines the amount of metadata to 9934allocate when the logical volume store is created. The default value 9935is '100', which translates to 1 4KiB per cluster. For the default 4MiB 9936cluster size, this equates to about 0.1% of the underlying block 9937device allocated for metadata. Logical volume stores can be grown, if 9938the size of the underlying block device grows in the future, but only 9939if enough metadata pages were allocated to support the growth. So 9940num_md_pages_per_cluster_ratio should be set to a higher value if 9941wanting to support future growth. For example, 9942num_md_pages_per_cluster_ratio = 200 would support future 2x growth of 9943the logical volume store, and would result in 0.2% of the underlying 9944block device allocated for metadata (with a default 4MiB cluster 9945size). 9946 9947#### Response 9948 9949UUID of the created logical volume store is returned. 9950 9951#### Example 9952 9953Example request: 9954 9955~~~json 9956{ 9957 "jsonrpc": "2.0", 9958 "id": 1, 9959 "method": "bdev_lvol_create_lvstore", 9960 "params": { 9961 "lvs_name": "LVS0", 9962 "bdev_name": "Malloc0" 9963 "clear_method": "write_zeroes" 9964 } 9965} 9966~~~ 9967 9968Example response: 9969 9970~~~json 9971{ 9972 "jsonrpc": "2.0", 9973 "id": 1, 9974 "result": "a9959197-b5e2-4f2d-8095-251ffb6985a5" 9975} 9976~~~ 9977 9978### bdev_lvol_delete_lvstore {#rpc_bdev_lvol_delete_lvstore} 9979 9980Destroy a logical volume store. 9981 9982#### Parameters 9983 9984Name | Optional | Type | Description 9985----------------------- | -------- | ----------- | ----------- 9986uuid | Optional | string | UUID of the logical volume store to destroy 9987lvs_name | Optional | string | Name of the logical volume store to destroy 9988 9989Either uuid or lvs_name must be specified, but not both. 9990 9991#### Example 9992 9993Example request: 9994 9995~~~json 9996{ 9997 "jsonrpc": "2.0", 9998 "method": "bdev_lvol_delete_lvstore", 9999 "id": 1 10000 "params": { 10001 "uuid": "a9959197-b5e2-4f2d-8095-251ffb6985a5" 10002 } 10003} 10004~~~ 10005 10006Example response: 10007 10008~~~json 10009{ 10010 "jsonrpc": "2.0", 10011 "id": 1, 10012 "result": true 10013} 10014~~~ 10015 10016### bdev_lvol_get_lvstores {#rpc_bdev_lvol_get_lvstores} 10017 10018Get a list of logical volume stores. 10019 10020#### Parameters 10021 10022Name | Optional | Type | Description 10023----------------------- | -------- | ----------- | ----------- 10024uuid | Optional | string | UUID of the logical volume store to retrieve information about 10025lvs_name | Optional | string | Name of the logical volume store to retrieve information about 10026 10027Either uuid or lvs_name may be specified, but not both. 10028If both uuid and lvs_name are omitted, information about all logical volume stores is returned. 10029 10030#### Example 10031 10032Example request: 10033 10034~~~json 10035{ 10036 "jsonrpc": "2.0", 10037 "method": "bdev_lvol_get_lvstores", 10038 "id": 1, 10039 "params": { 10040 "lvs_name": "LVS0" 10041 } 10042} 10043~~~ 10044 10045Example response: 10046 10047~~~json 10048{ 10049 "jsonrpc": "2.0", 10050 "id": 1, 10051 "result": [ 10052 { 10053 "uuid": "a9959197-b5e2-4f2d-8095-251ffb6985a5", 10054 "base_bdev": "Malloc0", 10055 "free_clusters": 31, 10056 "cluster_size": 4194304, 10057 "total_data_clusters": 31, 10058 "block_size": 4096, 10059 "name": "LVS0" 10060 } 10061 ] 10062} 10063~~~ 10064 10065### bdev_lvol_rename_lvstore {#rpc_bdev_lvol_rename_lvstore} 10066 10067Rename a logical volume store. 10068 10069#### Parameters 10070 10071Name | Optional | Type | Description 10072----------------------- | -------- | ----------- | ----------- 10073old_name | Required | string | Existing logical volume store name 10074new_name | Required | string | New logical volume store name 10075 10076#### Example 10077 10078Example request: 10079 10080~~~json 10081{ 10082 "jsonrpc": "2.0", 10083 "method": "bdev_lvol_rename_lvstore", 10084 "id": 1, 10085 "params": { 10086 "old_name": "LVS0", 10087 "new_name": "LVS2" 10088 } 10089} 10090~~~ 10091 10092Example response: 10093 10094~~~json 10095{ 10096 "jsonrpc": "2.0", 10097 "id": 1, 10098 "result": true 10099} 10100~~~ 10101 10102### bdev_lvol_grow_lvstore {#rpc_bdev_lvol_grow_lvstore} 10103 10104Grow the logical volume store to fill the underlying bdev 10105 10106#### Parameters 10107 10108Name | Optional | Type | Description 10109----------------------- | -------- | ----------- | ----------- 10110uuid | Optional | string | UUID of the logical volume store to grow 10111lvs_name | Optional | string | Name of the logical volume store to grow 10112 10113Either uuid or lvs_name must be specified, but not both. 10114 10115#### Example 10116 10117Example request: 10118 10119~~~json 10120{ 10121 "jsonrpc": "2.0", 10122 "method": "bdev_lvol_grow_lvstore", 10123 "id": 1 10124 "params": { 10125 "uuid": "a9959197-b5e2-4f2d-8095-251ffb6985a5" 10126 } 10127} 10128~~~ 10129 10130Example response: 10131 10132~~~json 10133{ 10134 "jsonrpc": "2.0", 10135 "id": 1, 10136 "result": true 10137} 10138~~~ 10139 10140### bdev_lvol_create {#rpc_bdev_lvol_create} 10141 10142Create a logical volume on a logical volume store. 10143 10144#### Parameters 10145 10146Name | Optional | Type | Description 10147----------------------- | -------- | ----------- | ----------- 10148lvol_name | Required | string | Name of logical volume to create 10149size | Optional | number | Desired size of logical volume in bytes (Deprecated. Please use size_in_mib instead.) 10150size_in_mib | Optional | number | Desired size of logical volume in MiB 10151thin_provision | Optional | boolean | True to enable thin provisioning 10152uuid | Optional | string | UUID of logical volume store to create logical volume on 10153lvs_name | Optional | string | Name of logical volume store to create logical volume on 10154clear_method | Optional | string | Change default data clusters clear method. Available: none, unmap, write_zeroes 10155 10156Size will be rounded up to a multiple of cluster size. Either uuid or lvs_name must be specified, but not both. 10157lvol_name will be used in the alias of the created logical volume. 10158 10159#### Response 10160 10161UUID of the created logical volume is returned. 10162 10163#### Example 10164 10165Example request: 10166 10167~~~json 10168{ 10169 "jsonrpc": "2.0", 10170 "method": "bdev_lvol_create", 10171 "id": 1, 10172 "params": { 10173 "lvol_name": "LVOL0", 10174 "size_in_mib": 1, 10175 "lvs_name": "LVS0", 10176 "clear_method": "unmap", 10177 "thin_provision": true 10178 } 10179} 10180~~~ 10181 10182Example response: 10183 10184~~~json 10185{ 10186 "jsonrpc": "2.0", 10187 "id": 1, 10188 "result": "1b38702c-7f0c-411e-a962-92c6a5a8a602" 10189} 10190~~~ 10191 10192### bdev_lvol_snapshot {#rpc_bdev_lvol_snapshot} 10193 10194Capture a snapshot of the current state of a logical volume. 10195 10196#### Parameters 10197 10198Name | Optional | Type | Description 10199----------------------- | -------- | ----------- | ----------- 10200lvol_name | Required | string | UUID or alias of the logical volume to create a snapshot from 10201snapshot_name | Required | string | Name for the newly created snapshot 10202 10203#### Response 10204 10205UUID of the created logical volume snapshot is returned. 10206 10207#### Example 10208 10209Example request: 10210 10211~~~json 10212{ 10213 "jsonrpc": "2.0", 10214 "method": "bdev_lvol_snapshot", 10215 "id": 1, 10216 "params": { 10217 "lvol_name": "1b38702c-7f0c-411e-a962-92c6a5a8a602", 10218 "snapshot_name": "SNAP1" 10219 } 10220} 10221~~~ 10222 10223Example response: 10224 10225~~~json 10226{ 10227 "jsonrpc": "2.0", 10228 "id": 1, 10229 "result": "cc8d7fdf-7865-4d1f-9fc6-35da8e368670" 10230} 10231~~~ 10232 10233### bdev_lvol_clone {#rpc_bdev_lvol_clone} 10234 10235Create a logical volume based on a snapshot. 10236 10237#### Parameters 10238 10239Name | Optional | Type | Description 10240----------------------- | -------- | ----------- | ----------- 10241snapshot_name | Required | string | UUID or alias of the snapshot to clone 10242clone_name | Required | string | Name for the logical volume to create 10243 10244#### Response 10245 10246UUID of the created logical volume clone is returned. 10247 10248#### Example 10249 10250Example request: 10251 10252~~~json 10253{ 10254 "jsonrpc": "2.0" 10255 "method": "bdev_lvol_clone", 10256 "id": 1, 10257 "params": { 10258 "snapshot_name": "cc8d7fdf-7865-4d1f-9fc6-35da8e368670", 10259 "clone_name": "CLONE1" 10260 } 10261} 10262~~~ 10263 10264Example response: 10265 10266~~~json 10267{ 10268 "jsonrpc": "2.0", 10269 "id": 1, 10270 "result": "8d87fccc-c278-49f0-9d4c-6237951aca09" 10271} 10272~~~ 10273 10274### bdev_lvol_clone_bdev {#rpc_bdev_lvol_clone_bdev} 10275 10276Create a logical volume based on an external snapshot bdev. The external snapshot bdev 10277is a bdev that will not be written to by any consumer and must not be an lvol in the 10278lvstore as the clone. 10279 10280Regardless of whether the bdev is specified by name or UUID, the bdev UUID will be stored 10281in the logical volume's metadata for use while the lvolstore is loading. For this reason, 10282it is important that the bdev chosen has a static UUID. 10283 10284#### Parameters 10285 10286Name | Optional | Type | Description 10287----------------------- | -------- | ----------- | ----------- 10288bdev | Required | string | Name or UUID for bdev that acts as the external snapshot 10289lvs_name | Required | string | logical volume store name 10290clone_name | Required | string | Name for the logical volume to create 10291 10292#### Response 10293 10294UUID of the created logical volume clone is returned. 10295 10296#### Example 10297 10298Example request: 10299 10300~~~json 10301{ 10302 "jsonrpc": "2.0", 10303 "method": "bdev_lvol_clone_bdev", 10304 "id": 1, 10305 "params": { 10306 "bdev_uuid": "e4b40d8b-f623-416d-8234-baf5a4c83cbd", 10307 "lvs_name": "lvs1", 10308 "clone_name": "clone2" 10309 } 10310} 10311~~~ 10312 10313Example response: 10314 10315~~~json 10316{ 10317 "jsonrpc": "2.0", 10318 "id": 1, 10319 "result": "336f662b-08e5-4006-8e06-e2023f7f9886" 10320} 10321~~~ 10322 10323### bdev_lvol_rename {#rpc_bdev_lvol_rename} 10324 10325Rename a logical volume. New name will rename only the alias of the logical volume. 10326 10327#### Parameters 10328 10329Name | Optional | Type | Description 10330----------------------- | -------- | ----------- | ----------- 10331old_name | Required | string | UUID or alias of the existing logical volume 10332new_name | Required | string | New logical volume name 10333 10334#### Example 10335 10336Example request: 10337 10338~~~json 10339{ 10340 "jsonrpc": "2.0", 10341 "method": "bdev_lvol_rename", 10342 "id": 1, 10343 "params": { 10344 "old_name": "067df606-6dbc-4143-a499-0d05855cb3b8", 10345 "new_name": "LVOL2" 10346 } 10347} 10348~~~ 10349 10350Example response: 10351 10352~~~json 10353{ 10354 "jsonrpc": "2.0", 10355 "id": 1, 10356 "result": true 10357} 10358~~~ 10359 10360### bdev_lvol_resize {#rpc_bdev_lvol_resize} 10361 10362Resize a logical volume. 10363 10364#### Parameters 10365 10366Name | Optional | Type | Description 10367----------------------- | -------- | ----------- | ----------- 10368name | Required | string | UUID or alias of the logical volume to resize 10369size | Optional | number | Desired size of the logical volume in bytes (Deprecated. Please use size_in_mib instead.) 10370size_in_mib | Optional | number | Desired size of the logical volume in MiB 10371 10372#### Example 10373 10374Example request: 10375 10376~~~json 10377{ 10378 "jsonrpc": "2.0", 10379 "method": "bdev_lvol_resize", 10380 "id": 1, 10381 "params": { 10382 "name": "51638754-ca16-43a7-9f8f-294a0805ab0a", 10383 "size_in_mib": 2 10384 } 10385} 10386~~~ 10387 10388Example response: 10389 10390~~~json 10391{ 10392 "jsonrpc": "2.0", 10393 "id": 1, 10394 "result": true 10395} 10396~~~ 10397 10398### bdev_lvol_set_read_only{#rpc_bdev_lvol_set_read_only} 10399 10400Mark logical volume as read only. 10401 10402#### Parameters 10403 10404Name | Optional | Type | Description 10405----------------------- | -------- | ----------- | ----------- 10406name | Required | string | UUID or alias of the logical volume to set as read only 10407 10408#### Example 10409 10410Example request: 10411 10412~~~json 10413{ 10414 "jsonrpc": "2.0", 10415 "method": "bdev_lvol_set_read_only", 10416 "id": 1, 10417 "params": { 10418 "name": "51638754-ca16-43a7-9f8f-294a0805ab0a", 10419 } 10420} 10421~~~ 10422 10423Example response: 10424 10425~~~json 10426{ 10427 "jsonrpc": "2.0", 10428 "id": 1, 10429 "result": true 10430} 10431~~~ 10432 10433### bdev_lvol_delete {#rpc_bdev_lvol_delete} 10434 10435Destroy a logical volume. 10436 10437#### Parameters 10438 10439Name | Optional | Type | Description 10440----------------------- | -------- | ----------- | ----------- 10441name | Required | string | UUID or alias of the logical volume to destroy 10442 10443#### Example 10444 10445Example request: 10446 10447~~~json 10448{ 10449 "jsonrpc": "2.0", 10450 "method": "bdev_lvol_delete", 10451 "id": 1, 10452 "params": { 10453 "name": "51638754-ca16-43a7-9f8f-294a0805ab0a" 10454 } 10455} 10456~~~ 10457 10458Example response: 10459 10460~~~json 10461{ 10462 "jsonrpc": "2.0", 10463 "id": 1, 10464 "result": true 10465} 10466~~~ 10467 10468### bdev_lvol_inflate {#rpc_bdev_lvol_inflate} 10469 10470Inflate a logical volume. All unallocated clusters are allocated and copied from the parent or zero filled 10471if not allocated in the parent. Then all dependencies on the parent are removed. 10472 10473### Parameters 10474 10475Name | Optional | Type | Description 10476----------------------- | -------- | ----------- | ----------- 10477name | Required | string | UUID or alias of the logical volume to inflate 10478 10479#### Example 10480 10481Example request: 10482 10483~~~json 10484{ 10485 "jsonrpc": "2.0", 10486 "method": "bdev_lvol_inflate", 10487 "id": 1, 10488 "params": { 10489 "name": "8d87fccc-c278-49f0-9d4c-6237951aca09" 10490 } 10491} 10492~~~ 10493 10494Example response: 10495 10496~~~json 10497{ 10498 "jsonrpc": "2.0", 10499 "id": 1, 10500 "result": true 10501} 10502~~~ 10503 10504### bdev_lvol_decouple_parent {#rpc_bdev_lvol_decouple_parent} 10505 10506Decouple the parent of a logical volume. For unallocated clusters which is allocated in the parent, they are 10507allocated and copied from the parent, but for unallocated clusters which is thin provisioned in the parent, 10508they are kept thin provisioned. Then all dependencies on the parent are removed. 10509 10510#### Parameters 10511 10512Name | Optional | Type | Description 10513----------------------- | -------- | ----------- | ----------- 10514name | Required | string | UUID or alias of the logical volume to decouple the parent of it 10515 10516#### Example 10517 10518Example request: 10519 10520~~~json 10521{ 10522 "jsonrpc": "2.0", 10523 "method": "bdev_lvol_decouple_parent", 10524 "id": 1. 10525 "params": { 10526 "name": "8d87fccc-c278-49f0-9d4c-6237951aca09" 10527 } 10528} 10529~~~ 10530 10531Example response: 10532 10533~~~json 10534{ 10535 "jsonrpc": "2.0", 10536 "id": 1, 10537 "result": true 10538} 10539~~~ 10540 10541### bdev_lvol_get_lvols {#rpc_bdev_lvol_get_lvols} 10542 10543Get a list of logical volumes. This list can be limited by lvol store and will display volumes even if 10544they are degraded. Degraded lvols do not have an associated bdev, thus this RPC call may return lvols 10545not returned by `bdev_get_bdevs`. 10546 10547#### Parameters 10548 10549Name | Optional | Type | Description 10550----------------------- | -------- | ----------- | ----------- 10551lvs_uuid | Optional | string | Only show volumes in the logical volume store with this UUID 10552lvs_name | Optional | string | Only show volumes in the logical volume store with this name 10553 10554Either lvs_uuid or lvs_name may be specified, but not both. 10555If both lvs_uuid and lvs_name are omitted, information about lvols in all logical volume stores is returned. 10556 10557#### Example 10558 10559Example request: 10560 10561~~~json 10562{ 10563 "jsonrpc": "2.0", 10564 "method": "bdev_lvol_get_lvols", 10565 "id": 1, 10566 "params": { 10567 "lvs_name": "lvs_test" 10568 } 10569} 10570~~~ 10571 10572Example response: 10573 10574~~~json 10575[ 10576 { 10577 "alias": "lvs_test/lvol1", 10578 "uuid": "b335c368-851d-4099-81e0-018cc494fdf6", 10579 "name": "lvol1", 10580 "is_thin_provisioned": false, 10581 "is_snapshot": false, 10582 "is_clone": false, 10583 "is_esnap_clone": false, 10584 "is_degraded": false, 10585 "lvs": { 10586 "name": "lvs_test", 10587 "uuid": "a1c8d950-5715-4558-936d-ab9e6eca0794" 10588 } 10589 } 10590] 10591~~~ 10592 10593## RAID 10594 10595### bdev_raid_set_options {#rpc_bdev_raid_set_options} 10596 10597Set options for bdev raid. 10598 10599This RPC can be called at any time, but the new value will only take effect for new raid bdevs. 10600 10601The `process_window_size_kb` parameter defines the size of the "window" (LBA range of the raid bdev) 10602in which a background process like rebuild performs its work. Any positive value is valid, but the value 10603actually used by a raid bdev can be adjusted to the size of the raid bdev or the write unit size. 10604 10605#### Parameters 10606 10607Name | Optional | Type | Description 10608-------------------------- | -------- | ----------- | ----------- 10609process_window_size_kb | Optional | number | Background process (e.g. rebuild) window size in KiB 10610 10611#### Example 10612 10613Example request: 10614 10615~~~json 10616request: 10617{ 10618 "jsonrpc": "2.0", 10619 "method": "bdev_raid_set_options", 10620 "id": 1, 10621 "params": { 10622 "process_window_size_kb": 512 10623 } 10624} 10625~~~ 10626 10627Example response: 10628 10629~~~json 10630{ 10631 "jsonrpc": "2.0", 10632 "id": 1, 10633 "result": true 10634} 10635~~~ 10636 10637### bdev_raid_get_bdevs {#rpc_bdev_raid_get_bdevs} 10638 10639This is used to list all the raid bdev details based on the input category requested. Category should be one 10640of 'all', 'online', 'configuring' or 'offline'. 'all' means all the raid bdevs whether they are online or 10641configuring or offline. 'online' is the raid bdev which is registered with bdev layer. 'configuring' is 10642the raid bdev which does not have full configuration discovered yet. 'offline' is the raid bdev which is 10643not registered with bdev as of now and it has encountered any error or user has requested to offline 10644the raid bdev. 10645 10646#### Parameters 10647 10648Name | Optional | Type | Description 10649----------------------- | -------- | ----------- | ----------- 10650category | Required | string | all or online or configuring or offline 10651 10652#### Example 10653 10654Example request: 10655 10656~~~json 10657{ 10658 "jsonrpc": "2.0", 10659 "method": "bdev_raid_get_bdevs", 10660 "id": 1, 10661 "params": { 10662 "category": "all" 10663 } 10664} 10665~~~ 10666 10667Example response: 10668 10669~~~json 10670{ 10671 "jsonrpc": "2.0", 10672 "id": 1, 10673 "result": [ 10674 { 10675 "name": "RaidBdev0", 10676 "uuid": "7d352e83-fe27-40f2-8fef-64563355e076", 10677 "strip_size_kb": 128, 10678 "state": "online", 10679 "raid_level": "raid0", 10680 "num_base_bdevs": 2, 10681 "num_base_bdevs_discovered": 2, 10682 "num_base_bdevs_operational": 2, 10683 "base_bdevs_list": [ 10684 { 10685 "name": "malloc0", 10686 "uuid": "d2788884-5b3e-4fd7-87ff-6c78177e14ab", 10687 "is_configured": true, 10688 "data_offset": 256, 10689 "data_size": 261888 10690 }, 10691 { 10692 "name": "malloc1", 10693 "uuid": "a81bb1f8-5865-488a-8758-10152017e7d1", 10694 "is_configured": true, 10695 "data_offset": 256, 10696 "data_size": 261888 10697 } 10698 ] 10699 }, 10700 { 10701 "name": "RaidBdev1", 10702 "uuid": "f7cb71ed-2d0e-4240-979e-27b0b7735f36", 10703 "strip_size_kb": 128, 10704 "state": "configuring", 10705 "raid_level": "raid0", 10706 "num_base_bdevs": 2, 10707 "num_base_bdevs_discovered": 1, 10708 "num_base_bdevs_operational": 2, 10709 "base_bdevs_list": [ 10710 { 10711 "name": "malloc2", 10712 "uuid": "f60c20e1-3439-4f89-ae55-965a70333f86", 10713 "is_configured": true, 10714 "data_offset": 256, 10715 "data_size": 261888 10716 } 10717 { 10718 "name": "malloc3", 10719 "uuid": "00000000-0000-0000-0000-000000000000", 10720 "is_configured": false, 10721 "data_offset": 0, 10722 "data_size": 0 10723 } 10724 ] 10725 } 10726 ] 10727} 10728~~~ 10729 10730### bdev_raid_create {#rpc_bdev_raid_create} 10731 10732Constructs new RAID bdev. 10733 10734#### Parameters 10735 10736Name | Optional | Type | Description 10737----------------------- | -------- | ----------- | ----------- 10738name | Required | string | RAID bdev name 10739strip_size_kb | Required | number | Strip size in KB 10740raid_level | Required | string | RAID level 10741base_bdevs | Required | string | Base bdevs name, whitespace separated list in quotes 10742uuid | Optional | string | UUID for this RAID bdev 10743superblock | Optional | boolean | If set, information about raid bdev will be stored in superblock on each base bdev (default: `false`) 10744 10745#### Example 10746 10747Example request: 10748 10749~~~json 10750{ 10751 "jsonrpc": "2.0", 10752 "method": "bdev_raid_create", 10753 "id": 1, 10754 "params": { 10755 "name": "Raid0", 10756 "raid_level": "0", 10757 "base_bdevs": [ 10758 "Malloc0", 10759 "Malloc1", 10760 "Malloc2", 10761 "Malloc3" 10762 ], 10763 "strip_size_kb": 4 10764 } 10765} 10766~~~ 10767 10768Example response: 10769 10770~~~json 10771{ 10772 "jsonrpc": "2.0", 10773 "id": 1, 10774 "result": true 10775} 10776~~~ 10777 10778### bdev_raid_delete {#rpc_bdev_raid_delete} 10779 10780Removes RAID bdev. 10781 10782#### Parameters 10783 10784Name | Optional | Type | Description 10785----------------------- | -------- | ----------- | ----------- 10786name | Required | string | RAID bdev name 10787 10788#### Example 10789 10790Example request: 10791 10792~~~json 10793{ 10794 "jsonrpc": "2.0", 10795 "method": "bdev_raid_delete", 10796 "id": 1, 10797 "params": { 10798 "name": "Raid0" 10799 } 10800} 10801~~~ 10802 10803Example response: 10804 10805~~~json 10806{ 10807 "jsonrpc": "2.0", 10808 "id": 1, 10809 "result": true 10810} 10811~~~ 10812 10813### bdev_raid_add_base_bdev {#rpc_bdev_raid_add_base_bdev} 10814 10815Add base bdev to existing raid bdev. The raid bdev must have an empty base bdev slot. 10816The bdev must be large enough and have the same block size and metadata format as the other base bdevs. 10817 10818#### Parameters 10819 10820Name | Optional | Type | Description 10821----------------------- | -------- | ----------- | ----------- 10822raid_bdev | Required | string | Raid bdev name 10823base_bdev | Required | string | Base bdev name 10824 10825#### Example 10826 10827Example request: 10828 10829~~~json 10830{ 10831 "jsonrpc": "2.0", 10832 "method": "bdev_raid_add_base_bdev", 10833 "id": 1, 10834 "params": { 10835 "raid_bdev": "RaidBdev0", 10836 "base_bdev": "Nvme0n1" 10837 } 10838} 10839~~~ 10840 10841Example response: 10842 10843~~~json 10844{ 10845 "jsonrpc": "2.0", 10846 "id": 1, 10847 "result": true 10848} 10849~~~ 10850### bdev_raid_remove_base_bdev {#rpc_bdev_raid_remove_base_bdev} 10851 10852Remove base bdev from existing raid bdev. 10853 10854#### Parameters 10855 10856Name | Optional | Type | Description 10857----------------------- | -------- | ----------- | ----------- 10858name | Required | string | Base bdev name in RAID 10859 10860#### Example 10861 10862Example request: 10863 10864~~~json 10865{ 10866 "jsonrpc": "2.0", 10867 "method": "bdev_raid_remove_base_bdev", 10868 "id": 1, 10869 "params": { 10870 "name": "Raid0" 10871 } 10872} 10873~~~ 10874 10875Example response: 10876 10877~~~json 10878{ 10879 "jsonrpc": "2.0", 10880 "id": 1, 10881 "result": true 10882} 10883~~~ 10884 10885## SPLIT 10886 10887### bdev_split_create {#rpc_bdev_split_create} 10888 10889This is used to split an underlying block device and create several smaller equal-sized vbdevs. 10890 10891#### Parameters 10892 10893Name | Optional | Type | Description 10894----------------------- | -------- | ----------- | ----------- 10895base_bdev | Required | string | base bdev name 10896split_count | Required | number | number of splits 10897split_size_mb | Optional | number | size in MB to restrict the size 10898 10899#### Example 10900 10901Example request: 10902 10903~~~json 10904{ 10905 "jsonrpc": "2.0", 10906 "method": "bdev_split_create", 10907 "id": 1, 10908 "params": { 10909 "base_bdev": "Malloc0", 10910 "split_count": 4 10911 } 10912} 10913~~~ 10914 10915Example response: 10916 10917~~~json 10918{ 10919 "jsonrpc": "2.0", 10920 "id": 1, 10921 "result": [ 10922 "Malloc0p0", 10923 "Malloc0p1", 10924 "Malloc0p2", 10925 "Malloc0p3" 10926 ] 10927} 10928~~~ 10929 10930### bdev_split_delete {#rpc_bdev_split_delete} 10931 10932This is used to remove the split vbdevs. 10933 10934#### Parameters 10935 10936Name | Optional | Type | Description 10937----------------------- | -------- | ----------- | ----------- 10938base_bdev | Required | string | base bdev name 10939 10940#### Example 10941 10942Example request: 10943 10944~~~json 10945{ 10946 "jsonrpc": "2.0", 10947 "method": "bdev_split_delete", 10948 "id": 1, 10949 "params": { 10950 "base_bdev": "Malloc0" 10951 } 10952} 10953~~~ 10954 10955Example response: 10956 10957~~~json 10958{ 10959 "jsonrpc": "2.0", 10960 "id": 1, 10961 "result": true 10962} 10963~~~ 10964 10965## Uring 10966 10967### bdev_uring_create {#rpc_bdev_uring_create} 10968 10969Create a bdev with io_uring backend. 10970 10971#### Parameters 10972 10973Name | Optional | Type | Description 10974----------------------- | -------- | ----------- | ----------- 10975filename | Required | string | path to device or file (ex: /dev/nvme0n1) 10976name | Required | string | name of bdev 10977block_size | Optional | number | block size of device (If omitted, get the block size from the file) 10978uuid | Optional | string | UUID of new bdev 10979 10980#### Example 10981 10982Example request: 10983 10984~~~json 10985{ 10986 "jsonrpc": "2.0", 10987 "method": "bdev_uring_create", 10988 "id": 1, 10989 "params": { 10990 "name": "bdev_u0", 10991 "filename": "/dev/nvme0n1", 10992 "block_size": 512 10993 } 10994} 10995~~~ 10996 10997Example response: 10998 10999~~~json 11000{ 11001 "jsonrpc": "2.0", 11002 "id": 1, 11003 "result": "bdev_u0" 11004} 11005~~~ 11006 11007### bdev_uring_rescan {#rpc_bdev_uring_rescan} 11008 11009Rescan the size of a uring bdev. 11010 11011#### Parameters 11012 11013Name | Optional | Type | Description 11014---- | -------- | ------ | ----------- 11015name | Required | string | name of uring bdev to rescan 11016 11017#### Example 11018 11019Example request: 11020 11021~~~json 11022{ 11023 "jsonrpc": "2.0", 11024 "method": "bdev_uring_rescan", 11025 "id": 1, 11026 "params": { 11027 "name": "bdev_u0" 11028 } 11029} 11030~~~ 11031 11032Example response: 11033 11034~~~json 11035{ 11036 "jsonrpc": "2.0", 11037 "id": 1, 11038 "result": true 11039} 11040~~~ 11041 11042### bdev_uring_delete {#rpc_bdev_uring_delete} 11043 11044Remove a uring bdev. 11045 11046#### Parameters 11047 11048Name | Optional | Type | Description 11049----------------------- | -------- | ----------- | ----------- 11050name | Required | string | name of uring bdev to delete 11051 11052#### Example 11053 11054Example request: 11055 11056~~~json 11057{ 11058 "jsonrpc": "2.0", 11059 "method": "bdev_uring_delete", 11060 "id": 1, 11061 "params": { 11062 "name": "bdev_u0" 11063 } 11064} 11065~~~ 11066 11067Example response: 11068 11069~~~json 11070{ 11071 "jsonrpc": "2.0", 11072 "id": 1, 11073 "result": true 11074} 11075~~~ 11076 11077## OPAL 11078 11079### bdev_nvme_opal_init {#rpc_bdev_nvme_opal_init} 11080 11081This is used to initialize OPAL of a given NVMe ctrlr, including taking ownership and activating. 11082 11083#### Parameters 11084 11085Name | Optional | Type | Description 11086----------------------- | -------- | ----------- | ----------- 11087nvme_ctrlr_name | Required | string | name of nvme ctrlr 11088password | Required | string | admin password of OPAL 11089 11090#### Example 11091 11092Example request: 11093 11094~~~json 11095{ 11096 "jsonrpc": "2.0", 11097 "method": "bdev_nvme_opal_init", 11098 "id": 1, 11099 "params": { 11100 "nvme_ctrlr_name": "nvme0", 11101 "password": "*****" 11102 } 11103} 11104~~~ 11105 11106Example response: 11107 11108~~~json 11109{ 11110 "jsonrpc": "2.0", 11111 "id": 1, 11112 "result": true 11113} 11114~~~ 11115 11116### bdev_nvme_opal_revert {#rpc_bdev_nvme_opal_revert} 11117 11118This is used to revert OPAL to its factory settings. Erase all user configuration and data. 11119 11120#### Parameters 11121 11122Name | Optional | Type | Description 11123----------------------- | -------- | ----------- | ----------- 11124nvme_ctrlr_name | Required | string | name of nvme ctrlr 11125password | Required | string | admin password of OPAL 11126 11127#### Example 11128 11129Example request: 11130 11131~~~json 11132{ 11133 "jsonrpc": "2.0", 11134 "method": "bdev_nvme_opal_revert", 11135 "id": 1, 11136 "params": { 11137 "nvme_ctrlr_name": "nvme0", 11138 "password": "*****" 11139 } 11140} 11141~~~ 11142 11143Example response: 11144 11145~~~json 11146{ 11147 "jsonrpc": "2.0", 11148 "id": 1, 11149 "result": true 11150} 11151~~~ 11152 11153### bdev_opal_create {#rpc_bdev_opal_create} 11154 11155This is used to create an OPAL virtual bdev. 11156 11157#### Parameters 11158 11159Name | Optional | Type | Description 11160----------------------- | -------- | ----------- | ----------- 11161nvme_ctrlr_name | Required | string | name of nvme ctrlr that supports OPAL 11162nsid | Required | number | namespace ID 11163locking_range_id | Required | number | OPAL locking range ID 11164range_start | Required | number | locking range start LBA 11165range_length | Required | number | locking range length 11166password | Required | string | admin password of OPAL 11167 11168#### Response 11169 11170The response is the name of created OPAL virtual bdev. 11171 11172#### Example 11173 11174Example request: 11175 11176~~~json 11177{ 11178 "jsonrpc": "2.0", 11179 "method": "bdev_opal_create", 11180 "id": 1, 11181 "params": { 11182 "nvme_ctrlr_name": "nvme0", 11183 "nsid": 1, 11184 "locking_range_id": 1, 11185 "range_start": 0, 11186 "range_length": 4096, 11187 "password": "*****" 11188 } 11189} 11190~~~ 11191 11192Example response: 11193 11194~~~json 11195{ 11196 "jsonrpc": "2.0", 11197 "id": 1, 11198 "result": "nvme0n1r1" 11199} 11200~~~ 11201 11202### bdev_opal_get_info {#rpc_bdev_opal_get_info} 11203 11204This is used to get information of a given OPAL bdev. 11205 11206#### Parameters 11207 11208Name | Optional | Type | Description 11209----------------------- | -------- | ----------- | ----------- 11210bdev_name | Required | string | name of OPAL vbdev 11211password | Required | string | admin password 11212 11213#### Response 11214 11215The response is the locking info of OPAL virtual bdev. 11216 11217#### Example 11218 11219Example request: 11220 11221~~~json 11222{ 11223 "jsonrpc": "2.0", 11224 "method": "bdev_opal_get_info", 11225 "id": 1, 11226 "params": { 11227 "bdev_name": "nvme0n1r1", 11228 "password": "*****" 11229 } 11230} 11231~~~ 11232 11233Example response: 11234 11235~~~json 11236{ 11237 "jsonrpc": "2.0", 11238 "id": 1, 11239 "result": { 11240 "name": "nvme0n1r1", 11241 "range_start": 0, 11242 "range_length": 4096, 11243 "read_lock_enabled": true, 11244 "write_lock_enabled": true, 11245 "read_locked": false, 11246 "write_locked": false 11247 } 11248} 11249~~~ 11250 11251### bdev_opal_delete {#rpc_bdev_opal_delete} 11252 11253This is used to delete OPAL vbdev. 11254 11255#### Parameters 11256 11257Name | Optional | Type | Description 11258----------------------- | -------- | ----------- | ----------- 11259bdev_name | Required | string | name of OPAL vbdev 11260password | Required | string | admin password 11261 11262#### Example 11263 11264Example request: 11265 11266~~~json 11267{ 11268 "jsonrpc": "2.0", 11269 "method": "bdev_opal_delete", 11270 "id": 1, 11271 "params": { 11272 "bdev_name": "nvme0n1r1", 11273 "password": "*****" 11274 } 11275} 11276~~~ 11277 11278Example response: 11279 11280~~~json 11281{ 11282 "jsonrpc": "2.0", 11283 "id": 1, 11284 "result": true 11285} 11286~~~ 11287 11288### bdev_opal_new_user {#rpc_bdev_opal_new_user} 11289 11290This enables a new user to the specified opal bdev so that the user can lock/unlock the bdev. 11291Recalling this for the same opal bdev, only the newest user will have the privilege. 11292 11293#### Parameters 11294 11295Name | Optional | Type | Description 11296----------------------- | -------- | ----------- | ----------- 11297bdev_name | Required | string | name of OPAL vbdev 11298admin_password | Required | string | admin password 11299user_id | Required | number | user ID 11300user_password | Required | string | user password 11301 11302#### Example 11303 11304Example request: 11305 11306~~~json 11307{ 11308 "jsonrpc": "2.0", 11309 "method": "bdev_opal_new_user", 11310 "id": 1, 11311 "params": { 11312 "bdev_name": "nvme0n1r1", 11313 "admin_password": "*****", 11314 "user_id": "1", 11315 "user_password": "********" 11316 } 11317} 11318~~~ 11319 11320Example response: 11321 11322~~~json 11323{ 11324 "jsonrpc": "2.0", 11325 "id": 1, 11326 "result": true 11327} 11328~~~ 11329 11330### bdev_opal_set_lock_state {#rpc_bdev_opal_set_lock_state} 11331 11332This is used to lock/unlock specific opal bdev providing user ID and password. 11333 11334#### Parameters 11335 11336Name | Optional | Type | Description 11337----------------------- | -------- | ----------- | ----------- 11338bdev_name | Required | string | name of OPAL vbdev 11339user_id | Required | number | user ID 11340password | Required | string | user password 11341lock_state | Required | string | lock state 11342 11343#### Example 11344 11345Example request: 11346 11347~~~json 11348{ 11349 "jsonrpc": "2.0", 11350 "method": "bdev_opal_set_lock_state", 11351 "id": 1, 11352 "params": { 11353 "bdev_name": "nvme0n1r1", 11354 "user_id": "1", 11355 "user_password": "********", 11356 "lock_state": "rwlock" 11357 } 11358} 11359~~~ 11360 11361Example response: 11362 11363~~~json 11364{ 11365 "jsonrpc": "2.0", 11366 "id": 1, 11367 "result": true 11368} 11369~~~ 11370 11371## Notifications 11372 11373### notify_get_types {#rpc_notify_get_types} 11374 11375Return list of all supported notification types. 11376 11377#### Parameters 11378 11379None 11380 11381#### Response 11382 11383The response is an array of strings - supported RPC notification types. 11384 11385#### Example 11386 11387Example request: 11388 11389~~~json 11390{ 11391 "jsonrpc": "2.0", 11392 "method": "notify_get_types", 11393 "id": 1 11394} 11395~~~ 11396 11397Example response: 11398 11399~~~json 11400{ 11401 "id": 1, 11402 "result": [ 11403 "bdev_register", 11404 "bdev_unregister" 11405 ], 11406 "jsonrpc": "2.0" 11407} 11408~~~ 11409 11410### notify_get_notifications {#notify_get_notifications} 11411 11412Request notifications. Returns array of notifications that happened since the specified id (or first that is available). 11413 11414Notice: Notifications are kept in circular buffer with limited size. Older notifications might be inaccessible 11415due to being overwritten by new ones. 11416 11417#### Parameters 11418 11419Name | Optional | Type | Description 11420----------------------- | -------- | ----------- | ----------- 11421id | Optional | number | First Event ID to fetch (default: first available). 11422max | Optional | number | Maximum number of event to return (default: no limit). 11423 11424#### Response 11425 11426Response is an array of event objects. 11427 11428Name | Optional | Type | Description 11429----------------------- | -------- | ----------- | ----------- 11430id | Optional | number | Event ID. 11431type | Optional | number | Type of the event. 11432ctx | Optional | string | Event context. 11433 11434#### Example 11435 11436Example request: 11437 11438~~~json 11439{ 11440 "id": 1, 11441 "jsonrpc": "2.0", 11442 "method": "notify_get_notifications", 11443 "params": { 11444 "id": 1, 11445 "max": 10 11446 } 11447} 11448 11449~~~ 11450 11451Example response: 11452 11453~~~json 11454{ 11455 "jsonrpc": "2.0", 11456 "id": 1, 11457 "result": [ 11458 { 11459 "ctx": "Malloc0", 11460 "type": "bdev_register", 11461 "id": 1 11462 }, 11463 { 11464 "ctx": "Malloc2", 11465 "type": "bdev_register", 11466 "id": 2 11467 } 11468 ] 11469} 11470~~~ 11471 11472## Linux Userspace Block Device (UBLK) {#jsonrpc_components_ublk} 11473 11474SPDK supports exporting bdevs though Linux ublk. The motivation behind it is to back a Linux kernel block device 11475with an SPDK user space bdev. 11476 11477To export a device over ublk, first make sure the Linux kernel ublk driver is loaded by running 'modprobe ublk_drv'. 11478 11479### ublk_create_target {#rpc_ublk_create_target} 11480 11481Start to create ublk threads and initialize ublk target. It will return an error if user calls this RPC twice without 11482ublk_destroy_target in between. It will use current cpumask in SPDK when user does not specify cpumask option. 11483 11484#### Parameters 11485 11486Name | Optional | Type | Description 11487----------------------- | -------- | ----------- | ----------- 11488cpumask | Optional | string | Cpumask for ublk target 11489 11490#### Response 11491 11492True if ublk target initialization is successful; False if failed. 11493 11494#### Example 11495 11496Example request: 11497 11498~~~json 11499{ 11500 "params": { 11501 "cpumask": "0x2" 11502 }, 11503 "jsonrpc": "2.0", 11504 "method": "ublk_create_target", 11505 "id": 1 11506} 11507~~~ 11508 11509Example response: 11510 11511~~~json 11512{ 11513 "jsonrpc": "2.0", 11514 "id": 1, 11515 "result": true 11516} 11517~~~ 11518 11519### ublk_destroy_target {#rpc_ublk_destroy_target} 11520 11521Release all UBLK devices and destroy ublk target. 11522 11523#### Response 11524 11525True if ublk target destruction is successful; False if failed. 11526 11527#### Example 11528 11529Example request: 11530 11531~~~json 11532{ 11533 "jsonrpc": "2.0", 11534 "method": "ublk_destroy_target", 11535 "id": 1 11536} 11537~~~ 11538 11539Example response: 11540 11541~~~json 11542{ 11543 "jsonrpc": "2.0", 11544 "id": 1, 11545 "result": true 11546} 11547~~~ 11548 11549### ublk_start_disk {#rpc_ublk_start_disk} 11550 11551Start to export one SPDK bdev as a UBLK device 11552 11553#### Parameters 11554 11555Name | Optional | Type | Description 11556----------------------- | -------- | ----------- | ----------- 11557bdev_name | Required | string | Bdev name to export 11558ublk_id | Required | int | Device id 11559queue_depth | Optional | int | Device queue depth 11560num_queues | Optional | int | Total number of device queues 11561 11562#### Response 11563 11564UBLK device ID 11565 11566#### Example 11567 11568Example request: 11569 11570~~~json 11571{ 11572 "params": { 11573 "ublk_id": "1", 11574 "bdev_name": "Malloc1" 11575 }, 11576 "jsonrpc": "2.0", 11577 "method": "ublk_start_disk", 11578 "id": 1 11579} 11580~~~ 11581 11582Example response: 11583 11584~~~json 11585{ 11586 "jsonrpc": "2.0", 11587 "id": 1, 11588 "result": 1 11589} 11590~~~ 11591 11592### ublk_recover_disk {#rpc_ublk_recover_disk} 11593 11594Recover original UBLK device with ID and block device 11595 11596#### Parameters 11597 11598Name | Optional | Type | Description 11599----------------------- | -------- | ----------- | ----------- 11600bdev_name | Required | string | Bdev name to export 11601ublk_id | Required | int | Device id 11602 11603#### Response 11604 11605UBLK device ID 11606 11607#### Example 11608 11609Example request: 11610 11611~~~json 11612{ 11613 "params": { 11614 "ublk_id": "1", 11615 "bdev_name": "Malloc1" 11616 }, 11617 "jsonrpc": "2.0", 11618 "method": "ublk_recover_disk", 11619 "id": 1 11620} 11621~~~ 11622 11623Example response: 11624 11625~~~json 11626{ 11627 "jsonrpc": "2.0", 11628 "id": 1, 11629 "result": 1 11630} 11631 11632### ublk_stop_disk {#rpc_ublk_stop_disk} 11633 11634Delete a UBLK device 11635 11636#### Parameters 11637 11638Name | Optional | Type | Description 11639----------------------- | -------- | ----------- | ----------- 11640ublk_id | Required | int | Device id to delete 11641 11642#### Response 11643 11644True if UBLK device is deleted successfully; False if failed. 11645 11646#### Example 11647 11648Example request: 11649 11650~~~json 11651{ 11652 "params": { 11653 "ublk_id": "1", 11654 }, 11655 "jsonrpc": "2.0", 11656 "method": "ublk_stop_disk", 11657 "id": 1 11658} 11659~~~ 11660 11661Example response: 11662 11663~~~json 11664{ 11665 "jsonrpc": "2.0", 11666 "id": 1, 11667 "result": true 11668} 11669~~~ 11670 11671### ublk_get_disks {#rpc_ublk_get_disks} 11672 11673Display full or specified ublk device list 11674 11675#### Parameters 11676 11677Name | Optional | Type | Description 11678----------------------- | -------- | ----------- | ----------- 11679ublk_id | Optional | int | ublk device id to display 11680 11681#### Response 11682 11683Display ublk device list 11684 11685#### Example 11686 11687Example request: 11688 11689~~~json 11690{ 11691 "jsonrpc": "2.0", 11692 "method": "ublk_get_disks", 11693 "id": 1 11694} 11695~~~ 11696 11697Example response: 11698 11699~~~json 11700{ 11701 "jsonrpc": "2.0", 11702 "id": 1, 11703 "result": [ 11704 { 11705 "ublk_device": "/dev/ublkb1", 11706 "id": 1, 11707 "queue_depth": 512, 11708 "num_queues": 1, 11709 "bdev_name": "Malloc1" 11710 } 11711 ] 11712} 11713~~~ 11714 11715## Linux Network Block Device (NBD) {#jsonrpc_components_nbd} 11716 11717SPDK supports exporting bdevs through Linux nbd. These devices then appear as standard Linux kernel block devices 11718and can be accessed using standard utilities like fdisk. 11719 11720In order to export a device over nbd, first make sure the Linux kernel nbd driver is loaded by running 'modprobe nbd'. 11721 11722### nbd_start_disk {#rpc_nbd_start_disk} 11723 11724Start to export one SPDK bdev as NBD disk 11725 11726#### Parameters 11727 11728Name | Optional | Type | Description 11729----------------------- | -------- | ----------- | ----------- 11730bdev_name | Required | string | Bdev name to export 11731nbd_device | Optional | string | NBD device name to assign 11732 11733#### Response 11734 11735Path of exported NBD disk 11736 11737#### Example 11738 11739Example request: 11740 11741~~~json 11742{ 11743 "params": { 11744 "nbd_device": "/dev/nbd1", 11745 "bdev_name": "Malloc1" 11746 }, 11747 "jsonrpc": "2.0", 11748 "method": "nbd_start_disk", 11749 "id": 1 11750} 11751~~~ 11752 11753Example response: 11754 11755~~~json 11756{ 11757 "jsonrpc": "2.0", 11758 "id": 1, 11759 "result": "/dev/nbd1" 11760} 11761~~~ 11762 11763### nbd_stop_disk {#rpc_nbd_stop_disk} 11764 11765Stop one NBD disk which is based on SPDK bdev. 11766 11767#### Parameters 11768 11769Name | Optional | Type | Description 11770----------------------- | -------- | ----------- | ----------- 11771nbd_device | Required | string | NBD device name to stop 11772 11773#### Example 11774 11775Example request: 11776 11777~~~json 11778{ 11779 "params": { 11780 "nbd_device": "/dev/nbd1", 11781 }, 11782 "jsonrpc": "2.0", 11783 "method": "nbd_stop_disk", 11784 "id": 1 11785} 11786~~~ 11787 11788Example response: 11789 11790~~~json 11791{ 11792 "jsonrpc": "2.0", 11793 "id": 1, 11794 "result": "true" 11795} 11796~~~ 11797 11798### nbd_get_disks {#rpc_nbd_get_disks} 11799 11800Display all or specified NBD device list 11801 11802#### Parameters 11803 11804Name | Optional | Type | Description 11805----------------------- | -------- | ----------- | ----------- 11806nbd_device | Optional | string | NBD device name to display 11807 11808#### Response 11809 11810The response is an array of exported NBD devices and their corresponding SPDK bdev. 11811 11812#### Example 11813 11814Example request: 11815 11816~~~json 11817{ 11818 "jsonrpc": "2.0", 11819 "method": "nbd_get_disks", 11820 "id": 1 11821} 11822~~~ 11823 11824Example response: 11825 11826~~~json 11827{ 11828 "jsonrpc": "2.0", 11829 "id": 1, 11830 "result": [ 11831 { 11832 "bdev_name": "Malloc0", 11833 "nbd_device": "/dev/nbd0" 11834 }, 11835 { 11836 "bdev_name": "Malloc1", 11837 "nbd_device": "/dev/nbd1" 11838 } 11839 ] 11840} 11841~~~ 11842 11843## Blobfs {#jsonrpc_components_blobfs} 11844 11845### blobfs_detect {#rpc_blobfs_detect} 11846 11847Detect whether a blobfs exists on bdev. 11848 11849#### Parameters 11850 11851Name | Optional | Type | Description 11852----------------------- | -------- | ----------- | ----------- 11853bdev_name | Required | string | Block device name to detect blobfs 11854 11855#### Response 11856 11857True if a blobfs exists on the bdev; False otherwise. 11858 11859#### Example 11860 11861Example request: 11862 11863~~~json 11864{ 11865 "jsonrpc": "2.0", 11866 "id": 1, 11867 "method": "blobfs_detect", 11868 "params": { 11869 "bdev_name": "Malloc0" 11870 } 11871} 11872~~~ 11873 11874Example response: 11875 11876~~~json 11877{ 11878 "jsonrpc": "2.0", 11879 "id": 1, 11880 "result": "true" 11881} 11882~~~ 11883 11884### blobfs_create {#rpc_blobfs_create} 11885 11886Build blobfs on bdev. 11887 11888#### Parameters 11889 11890Name | Optional | Type | Description 11891----------------------- | -------- | ----------- | ----------- 11892bdev_name | Required | string | Block device name to create blobfs 11893cluster_sz | Optional | number | Size of cluster in bytes. Must be multiple of 4KiB page size, default and minimal value is 1M. 11894 11895#### Example 11896 11897Example request: 11898 11899~~~json 11900{ 11901 "jsonrpc": "2.0", 11902 "id": 1, 11903 "method": "blobfs_create", 11904 "params": { 11905 "bdev_name": "Malloc0", 11906 "cluster_sz": 1M 11907 } 11908} 11909~~~ 11910 11911Example response: 11912 11913~~~json 11914{ 11915 "jsonrpc": "2.0", 11916 "id": 1, 11917 "result": "true" 11918} 11919~~~ 11920 11921### blobfs_mount {#rpc_blobfs_mount} 11922 11923Mount a blobfs on bdev to one host path through FUSE 11924 11925#### Parameters 11926 11927Name | Optional | Type | Description 11928----------------------- | -------- | ----------- | ----------- 11929bdev_name | Required | string | Block device name where the blobfs is 11930mountpoint | Required | string | Mountpoint path in host to mount blobfs 11931 11932#### Example 11933 11934Example request: 11935 11936~~~json 11937{ 11938 "jsonrpc": "2.0", 11939 "id": 1, 11940 "method": ""blobfs_mount"", 11941 "params": { 11942 "bdev_name": "Malloc0", 11943 "mountpoint": "/mnt/" 11944 } 11945} 11946~~~ 11947 11948Example response: 11949 11950~~~json 11951{ 11952 "jsonrpc": "2.0", 11953 "id": 1, 11954 "result": "true" 11955} 11956~~~ 11957 11958### blobfs_set_cache_size {#rpc_blobfs_set_cache_size} 11959 11960Set cache pool size for blobfs filesystems. This RPC is only permitted when the cache pool is not already initialized. 11961 11962The cache pool is initialized when the first blobfs filesystem is initialized or loaded. It is freed when the all 11963initialized or loaded filesystems are unloaded. 11964 11965#### Parameters 11966 11967Name | Optional | Type | Description 11968----------------------- | -------- | ----------- | ----------- 11969size_in_mb | Required | number | Cache size in megabytes 11970 11971#### Response 11972 11973True if cache size is set successfully; False if failed to set. 11974 11975#### Example 11976 11977Example request: 11978 11979~~~json 11980{ 11981 "jsonrpc": "2.0", 11982 "id": 1, 11983 "method": "blobfs_set_cache_size", 11984 "params": { 11985 "size_in_mb": 512, 11986 } 11987} 11988~~~ 11989 11990Example response: 11991 11992~~~json 11993{ 11994 "jsonrpc": "2.0", 11995 "id": 1, 11996 "result": true 11997} 11998~~~ 11999 12000## Socket layer {#jsonrpc_components_sock} 12001 12002### sock_impl_get_options {#rpc_sock_impl_get_options} 12003 12004Get parameters for the socket layer implementation. 12005 12006#### Parameters 12007 12008Name | Optional | Type | Description 12009----------------------- | -------- | ----------- | ----------- 12010impl_name | Required | string | Name of socket implementation, e.g. posix 12011 12012#### Response 12013 12014Response is an object with current socket layer options for requested implementation. 12015 12016#### Example 12017 12018Example request: 12019 12020~~~json 12021{ 12022 "jsonrpc": "2.0", 12023 "method": "sock_impl_get_options", 12024 "id": 1, 12025 "params": { 12026 "impl_name": "posix" 12027 } 12028} 12029~~~ 12030 12031Example response: 12032 12033~~~json 12034{ 12035 "jsonrpc": "2.0", 12036 "id": 1, 12037 "result": { 12038 "recv_buf_size": 2097152, 12039 "send_buf_size": 2097152, 12040 "enable_recv_pipe": true, 12041 "enable_quickack": true, 12042 "enable_placement_id": 0, 12043 "enable_zerocopy_send_server": true, 12044 "enable_zerocopy_send_client": false, 12045 "zerocopy_threshold": 0, 12046 "tls_version": 13, 12047 "enable_ktls": false 12048 } 12049} 12050~~~ 12051 12052### sock_impl_set_options {#rpc_sock_impl_set_options} 12053 12054Set parameters for the socket layer implementation. 12055 12056#### Parameters 12057 12058Name | Optional | Type | Description 12059--------------------------- | -------- | ----------- | ----------- 12060impl_name | Required | string | Name of socket implementation, e.g. posix 12061recv_buf_size | Optional | number | Size of socket receive buffer in bytes 12062send_buf_size | Optional | number | Size of socket send buffer in bytes 12063enable_recv_pipe | Optional | boolean | Enable or disable receive pipe 12064enable_quick_ack | Optional | boolean | Enable or disable quick ACK 12065enable_placement_id | Optional | number | Enable or disable placement_id. 0:disable,1:incoming_napi,2:incoming_cpu 12066enable_zerocopy_send_server | Optional | boolean | Enable or disable zero copy on send for server sockets 12067enable_zerocopy_send_client | Optional | boolean | Enable or disable zero copy on send for client sockets 12068zerocopy_threshold | Optional | number | Set zerocopy_threshold in bytes. A consecutive sequence of requests' iovecs 12069-- | -- | -- | that fall below this threshold may be sent without zerocopy flag set 12070tls_version | Optional | number | TLS protocol version, e.g. 13 for v1.3 (only applies when impl_name == ssl) 12071enable_ktls | Optional | boolean | Enable or disable Kernel TLS (only applies when impl_name == ssl) 12072 12073#### Response 12074 12075True if socket layer options were set successfully. 12076 12077#### Example 12078 12079Example request: 12080 12081~~~json 12082{ 12083 "jsonrpc": "2.0", 12084 "method": "sock_impl_set_options", 12085 "id": 1, 12086 "params": { 12087 "impl_name": "posix", 12088 "recv_buf_size": 2097152, 12089 "send_buf_size": 2097152, 12090 "enable_recv_pipe": false, 12091 "enable_quick_ack": false, 12092 "enable_placement_id": 0, 12093 "enable_zerocopy_send_server": true, 12094 "enable_zerocopy_send_client": false, 12095 "zerocopy_threshold": 10240, 12096 "tls_version": 13, 12097 "enable_ktls": false 12098 } 12099} 12100~~~ 12101 12102Example response: 12103 12104~~~json 12105{ 12106 "jsonrpc": "2.0", 12107 "id": 1, 12108 "result": true 12109} 12110~~~ 12111 12112### sock_set_default_impl {#rpc_sock_set_default_impl} 12113 12114Set the default sock implementation. 12115 12116#### Parameters 12117 12118Name | Optional | Type | Description 12119----------------------- | -------- | ----------- | ----------- 12120impl_name | Required | string | Name of socket implementation, e.g. posix 12121 12122#### Response 12123 12124True if the default socket layer configuration was set successfully. 12125 12126#### Example 12127 12128Example request: 12129 12130~~~json 12131{ 12132 "jsonrpc": "2.0", 12133 "method": "sock_set_default_impl", 12134 "id": 1, 12135 "params": { 12136 "impl_name": "posix" 12137 } 12138} 12139~~~ 12140 12141Example response: 12142 12143~~~json 12144{ 12145 "jsonrpc": "2.0", 12146 "id": 1, 12147 "result": true 12148} 12149~~~ 12150 12151## Miscellaneous RPC commands 12152 12153### bdev_nvme_send_cmd {#rpc_bdev_nvme_send_cmd} 12154 12155Send NVMe command directly to NVMe controller or namespace. Parameters and responses encoded by base64 urlsafe need further processing. 12156 12157Notice: bdev_nvme_send_cmd requires user to guarantee the correctness of NVMe command itself, and also optional parameters. 12158Illegal command contents or mismatching buffer size may result in unpredictable behavior. 12159 12160#### Parameters 12161 12162Name | Optional | Type | Description 12163----------------------- | -------- | ----------- | ----------- 12164name | Required | string | Name of the operating NVMe controller 12165cmd_type | Required | string | Type of nvme cmd. Valid values are: admin, io 12166data_direction | Required | string | Direction of data transfer. Valid values are: c2h, h2c 12167cmdbuf | Required | string | NVMe command encoded by base64 urlsafe 12168data | Optional | string | Data transferring to controller from host, encoded by base64 urlsafe 12169metadata | Optional | string | Metadata transferring to controller from host, encoded by base64 urlsafe 12170data_len | Optional | number | Data length required to transfer from controller to host 12171metadata_len | Optional | number | Metadata length required to transfer from controller to host 12172timeout_ms | Optional | number | Command execution timeout value, in milliseconds 12173 12174#### Response 12175 12176Name | Type | Description 12177----------------------- | ----------- | ----------- 12178cpl | string | NVMe completion queue entry, encoded by base64 urlsafe 12179data | string | Data transferred from controller to host, encoded by base64 urlsafe 12180metadata | string | Metadata transferred from controller to host, encoded by base64 urlsafe 12181 12182#### Example 12183 12184Example request: 12185 12186~~~json 12187{ 12188 "jsonrpc": "2.0", 12189 "method": "bdev_nvme_send_cmd", 12190 "id": 1, 12191 "params": { 12192 "name": "Nvme0", 12193 "cmd_type": "admin" 12194 "data_direction": "c2h", 12195 "cmdbuf": "BgAAAAEAAAAAAAAAAAAAAAAAAAAAAAAAsGUs9P5_AAAAAAAAABAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA==", 12196 "data_len": 60, 12197 } 12198} 12199~~~ 12200 12201Example response: 12202 12203~~~json 12204{ 12205 "jsonrpc": "2.0", 12206 "id": 1, 12207 "result": { 12208 "cpl": "AAAAAAAAAAARAAAAWrmwABAA==", 12209 "data": "sIjg6AAAAACwiODoAAAAALCI4OgAAAAAAAYAAREAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA" 12210 } 12211 12212} 12213~~~ 12214 12215### vmd_enable {#rpc_enable_vmd} 12216 12217Enable VMD enumeration. 12218 12219#### Parameters 12220 12221This method has no parameters. 12222 12223#### Response 12224 12225Completion status of enumeration is returned as a boolean. 12226 12227### Example 12228 12229Example request: 12230 12231~~~json 12232{ 12233 "jsonrpc": "2.0", 12234 "method": "vmd_enable", 12235 "id": 1 12236} 12237~~~ 12238 12239Example response: 12240 12241~~~json 12242{ 12243 "jsonrpc": "2.0", 12244 "id": 1, 12245 "result": true 12246} 12247~~~ 12248 12249### vmd_remove_device {#rpc_vmd_remove_device} 12250 12251Remove a device behind a VMD. 12252 12253### Parameters 12254 12255Name | Optional | Type | Description 12256----------------------- | -------- | ----------- | ----------- 12257addr | Required | string | Address of the device to remove. 12258 12259### Example 12260 12261~~~json 12262{ 12263 "jsonrpc": "2.0", 12264 "method": "vmd_remove_device", 12265 "params": { 12266 "addr": "5d0505:01:00.0" 12267 } 12268 "id": 1 12269} 12270~~~ 12271 12272Example response: 12273 12274~~~json 12275{ 12276 "jsonrpc": "2.0", 12277 "id": 1, 12278 "result": true 12279} 12280~~~ 12281 12282### vmd_rescan {#rpc_vmd_rescan} 12283 12284Force a rescan of the devices behind VMD. 12285 12286### Parameters 12287 12288This method has no parameters. 12289 12290#### Response 12291 12292The response is the number of new devices found. 12293 12294### Example 12295 12296~~~json 12297{ 12298 "jsonrpc": "2.0", 12299 "method": "vmd_rescan", 12300 "id": 1 12301} 12302~~~ 12303 12304Example response: 12305 12306~~~json 12307{ 12308 "jsonrpc": "2.0", 12309 "id": 1, 12310 "result": { 12311 "count": 1 12312 } 12313} 12314~~~ 12315 12316### spdk_get_version {#rpc_spdk_get_version} 12317 12318Get the version info of the running SPDK application. 12319 12320#### Parameters 12321 12322This method has no parameters. 12323 12324#### Response 12325 12326The response is the version number including major version number, minor version number, patch level number and suffix string. 12327 12328#### Example 12329 12330Example request: 12331 12332~~~json 12333{ 12334 "jsonrpc": "2.0", 12335 "id": 1, 12336 "method": "spdk_get_version" 12337} 12338~~~ 12339 12340Example response: 12341 12342~~~json 12343{ 12344 "jsonrpc": "2.0", 12345 "id": 1, 12346 "result": { 12347 "version": "19.04-pre", 12348 "fields" : { 12349 "major": 19, 12350 "minor": 4, 12351 "patch": 0, 12352 "suffix": "-pre" 12353 } 12354 } 12355} 12356~~~ 12357 12358### framework_get_pci_devices 12359 12360List PCIe devices attached to an SPDK application and the contents of their config space. 12361 12362#### Parameters 12363 12364This method has no parameters. 12365 12366#### Response 12367 12368The response is an array of attached PCIe devices. 12369 12370#### Example 12371 12372Example request: 12373 12374~~~json 12375{ 12376 "jsonrpc": "2.0", 12377 "id": 1, 12378 "method": "framework_get_pci_devices" 12379} 12380~~~ 12381 12382Example response: 12383Note that the config space buffer was trimmed. 12384 12385~~~json 12386{ 12387 "jsonrpc": "2.0", 12388 "id": 1, 12389 "result": { 12390 [ 12391 { 12392 "address": "0000:00:04.0", 12393 "config_space": "8680455807051000...0000000000000000" 12394 }, 12395 { 12396 "address": "0000:00:03.0", 12397 "config_space": "8680455807051000...0000000000000000" 12398 } 12399 ] 12400 } 12401} 12402~~~ 12403 12404### bdev_nvme_add_error_injection {#rpc_bdev_nvme_add_error_injection} 12405 12406Add a NVMe command error injection for a bdev nvme controller. 12407 12408#### Parameters 12409 12410Name | Optional | Type | Description 12411----------------------- | -------- | ----------- | ----------- 12412name | Required | string | Name of the operating NVMe controller 12413cmd_type | Required | string | Type of NVMe command. Valid values are: admin, io 12414opc | Required | number | Opcode for which the error injection is applied 12415do_not_submit | Optional | boolean | Set to true if request should not be submitted to the controller (default false) 12416timeout_in_us | Optional | number | Wait specified microseconds when do_not_submit is true 12417err_count | Optional | number | Number of matching NVMe commands to inject errors 12418sct | Optional | number | Status code type (default 0) 12419sc | Optional | number | Status code (default 0) 12420 12421#### Response 12422 12423true on success 12424 12425#### Example 12426 12427Example request: 12428 12429~~~json 12430{ 12431 "jsonrpc": "2.0", 12432 "method": "bdev_nvme_add_error_injection", 12433 "id": 1, 12434 "params": { 12435 "name": "HotInNvme0", 12436 "opc": 2, 12437 "cmd_type": "io", 12438 "err_count": 1111111, 12439 "sct": 11, 12440 "sc": 33 12441 } 12442} 12443 12444~~~ 12445 12446Example response: 12447 12448~~~json 12449{ 12450 "jsonrpc": "2.0", 12451 "id": 1, 12452 "result": true 12453} 12454 12455~~~ 12456 12457### bdev_nvme_remove_error_injection {#rpc_bdev_nvme_remove_error_injection} 12458 12459Remove a NVMe command error injection. 12460 12461#### Parameters 12462 12463Name | Optional | Type | Description 12464----------------------- | -------- | ----------- | ----------- 12465name | Required | string | Name of the operating NVMe controller 12466cmd_type | Required | string | Type of NVMe command. Valid values are: admin, io 12467opc | Required | number | Opcode for which the error injection is applied 12468 12469#### Response 12470 12471true on success 12472 12473#### Example 12474 12475Example request: 12476 12477~~~json 12478{ 12479 "jsonrpc": "2.0", 12480 "method": "bdev_nvme_remove_error_injection", 12481 "id": 1, 12482 "params": { 12483 "name": "HotInNvme0", 12484 "opc": 2, 12485 "cmd_type": "io" 12486 } 12487} 12488 12489 12490~~~ 12491 12492Example response: 12493 12494~~~json 12495{ 12496 "jsonrpc": "2.0", 12497 "id": 1, 12498 "result": true 12499} 12500 12501~~~ 12502 12503### bdev_daos_create {#rpc_bdev_daos_create} 12504 12505Construct @ref bdev_config_daos 12506 12507#### Parameters 12508 12509Name | Optional | Type | Description 12510----------------------- | -------- | ----------- | ----------- 12511name | Required | string | Bdev name to use 12512pool | Required | string | DAOS pool label or its uuid 12513cont | Required | string | DAOS cont label or its uuid 12514block_size | Required | number | Block size in bytes -must be multiple of 512 12515num_blocks | Required | number | Number of blocks 12516uuid | Optional | string | UUID of new bdev 12517oclass | Optional | string | DAOS object class (default SX) 12518 12519To find more about various object classes please visit [DAOS documentation](https://github.com/daos-stack/daos/blob/master/src/object/README.md). 12520Please note, that DAOS bdev module uses the same CLI flag notation as `dmg` and `daos` commands, 12521for instance, `SX` or `EC_4P2G2` rather than in DAOS header file `OC_SX` or `OC_EC_4P2G2`. 12522 12523#### Result 12524 12525Name of newly created bdev. 12526 12527#### Example 12528 12529Example request: 12530 12531~~~json 12532{ 12533 "params": { 12534 "block_size": 4096, 12535 "num_blocks": 16384, 12536 "name": "daosdev0", 12537 "pool": "test-pool", 12538 "cont": "test-cont", 12539 "oclass": "EC_4P2G2" 12540 }, 12541 "jsonrpc": "2.0", 12542 "method": "bdev_daos_create", 12543 "id": 1 12544} 12545~~~ 12546 12547Example response: 12548 12549~~~json 12550{ 12551 "jsonrpc": "2.0", 12552 "id": 1, 12553 "result": "daosdev0" 12554} 12555~~~ 12556 12557### bdev_daos_delete {#rpc_bdev_daos_delete} 12558 12559Delete @ref bdev_config_daos 12560 12561#### Parameters 12562 12563Name | Optional | Type | Description 12564----------------------- | -------- | ----------- | ----------- 12565name | Required | string | Bdev name 12566 12567#### Example 12568 12569Example request: 12570 12571~~~json 12572{ 12573 "params": { 12574 "name": "daosdev0" 12575 }, 12576 "jsonrpc": "2.0", 12577 "method": "bdev_daos_delete", 12578 "id": 1 12579} 12580~~~ 12581 12582Example response: 12583 12584~~~json 12585{ 12586 "jsonrpc": "2.0", 12587 "id": 1, 12588 "result": true 12589} 12590~~~ 12591 12592### bdev_daos_resize {#rpc_bdev_daos_resize} 12593 12594Resize @ref bdev_config_daos. 12595 12596#### Parameters 12597 12598Name | Optional | Type | Description 12599----------------------- | -------- | ----------- | ----------- 12600name | Required | string | Bdev name 12601new_size | Required | number | Bdev new capacity in MiB 12602 12603#### Example 12604 12605Example request: 12606 12607~~~json 12608{ 12609 "params": { 12610 "name": "daosdev0", 12611 "new_size": 8192 12612 }, 12613 "jsonrpc": "2.0", 12614 "method": "bdev_daos_resize", 12615 "id": 1 12616} 12617~~~ 12618 12619Example response: 12620 12621~~~json 12622{ 12623 "jsonrpc": "2.0", 12624 "id": 1, 12625 "result": true 12626} 12627~~~ 12628 12629### iobuf_set_options {#rpc_iobuf_set_options} 12630 12631Set iobuf buffer pool options. 12632 12633#### Parameters 12634 12635Name | Optional | Type | Description 12636----------------------- | -------- | ----------- | ----------- 12637small_pool_count | Optional | number | Number of small buffers in the global pool 12638large_pool_count | Optional | number | Number of large buffers in the global pool 12639small_bufsize | Optional | number | Size of a small buffer 12640large_bufsize | Optional | number | Size of a small buffer 12641 12642#### Example 12643 12644Example request: 12645 12646~~~json 12647{ 12648 "jsonrpc": "2.0", 12649 "id": 1, 12650 "method": "iobuf_set_options", 12651 "params": { 12652 "small_pool_count": 16383, 12653 "large_pool_count": 2047 12654 } 12655} 12656~~~ 12657 12658Example response: 12659 12660~~~json 12661{ 12662 "jsonrpc": "2.0", 12663 "id": 1, 12664 "result": true 12665} 12666~~~ 12667 12668### iobuf_get_stats {#rpc_iobuf_get_stats} 12669 12670Retrieve iobuf's statistics. 12671 12672#### Parameters 12673 12674None. 12675 12676#### Example 12677 12678Example request: 12679 12680~~~json 12681{ 12682 "jsonrpc": "2.0", 12683 "method": "iobuf_get_stats", 12684 "id": 1 12685} 12686~~~ 12687 12688Example response: 12689 12690~~~json 12691{ 12692 "jsonrpc": "2.0", 12693 "id": 1, 12694 "result": [ 12695 { 12696 "module": "accel", 12697 "small_pool": { 12698 "cache": 0, 12699 "main": 0, 12700 "retry": 0 12701 }, 12702 "large_pool": { 12703 "cache": 0, 12704 "main": 0, 12705 "retry": 0 12706 } 12707 }, 12708 { 12709 "module": "bdev", 12710 "small_pool": { 12711 "cache": 421965, 12712 "main": 1218, 12713 "retry": 0 12714 }, 12715 "large_pool": { 12716 "cache": 0, 12717 "main": 0, 12718 "retry": 0 12719 } 12720 }, 12721 { 12722 "module": "nvmf_TCP", 12723 "small_pool": { 12724 "cache": 7, 12725 "main": 0, 12726 "retry": 0 12727 }, 12728 "large_pool": { 12729 "cache": 0, 12730 "main": 0, 12731 "retry": 0 12732 } 12733 } 12734 ] 12735} 12736~~~ 12737 12738### bdev_nvme_start_mdns_discovery {#rpc_bdev_nvme_start_mdns_discovery} 12739 12740Starts an mDNS based discovery service for the specified service type for the 12741auto-discovery of discovery controllers (NVMe TP-8009). 12742 12743The discovery service will listen for the mDNS discovery events from the 12744Avahi-daemon and will connect to the newly learnt discovery controllers. 12745Then the discovery service will automatically attach to any subsystem found in the 12746discovery log page from the discovery controllers learnt using mDNS. 12747When determining a controller name to use when attaching, it will use 12748the 'name' parameter as a prefix, followed by a unique integer assigned for each of the 12749discovery controllers learnt through mDNS, followed by a unique integer for that discovery 12750service. If the discovery service identifies a subsystem that has been previously 12751attached but is listed with a different path, it will use the same controller name 12752as the previous entry, and connect as a multipath. 12753 12754When the discovery service sees that a subsystem entry has been removed 12755from the log page, it will automatically detach from that controller as well. 12756 12757The 'name' is also used to later stop the discovery service. 12758 12759#### Parameters 12760 12761Name | Optional | Type | Description 12762-------------------------- | -------- | ----------- | ----------- 12763name | Required | string | Prefix for NVMe discovery services found 12764svcname | Required | string | Service to discover: e.g. _nvme-disc._tcp 12765hostnqn | Optional | string | NVMe-oF hostnqn 12766 12767#### Example 12768 12769Example request: 12770 12771~~~json 12772{ 12773 "jsonrpc": "2.0", 12774 "method": "bdev_nvme_start_mdns_discovery", 12775 "id": 1, 12776 "params": { 12777 "name": "cdc_auto", 12778 "svcname": "_nvme-disc._tcp", 12779 "hostnqn": "nqn.2021-12.io.spdk:host1", 12780 } 12781} 12782~~~ 12783 12784Example response: 12785 12786~~~json 12787{ 12788 "jsonrpc": "2.0", 12789 "id": 1, 12790 "result": true 12791} 12792~~~ 12793 12794### bdev_nvme_stop_mdns_discovery {#rpc_bdev_nvme_stop_mdns_discovery} 12795 12796Stops a mDNS discovery service. This includes detaching any controllers that were 12797discovered via the service that is being stopped. 12798 12799#### Parameters 12800 12801Name | Optional | Type | Description 12802-------------------------- | -------- | ----------- | ----------- 12803name | Required | string | Name of mDNS discovery instance to stop 12804 12805#### Example 12806 12807Example request: 12808 12809~~~json 12810{ 12811 "jsonrpc": "2.0", 12812 "method": "bdev_nvme_stop_mdns_discovery", 12813 "id": 1, 12814 "params": { 12815 "name": "cdc_auto" 12816 } 12817} 12818~~~ 12819 12820Example response: 12821 12822~~~json 12823{ 12824 "jsonrpc": "2.0", 12825 "id": 1, 12826 "result": true 12827} 12828~~~ 12829 12830### bdev_nvme_get_mdns_discovery_info {#rpc_bdev_nvme_get_mdns_discovery_info} 12831 12832Get the information about the mDNS discovery service instances. 12833 12834#### Example 12835 12836Example request: 12837~~~json 12838{ 12839 "jsonrpc": "2.0", 12840 "method": "bdev_nvme_get_mdns_discovery_info", 12841 "id": 1 12842} 12843~~~ 12844 12845Example response: 12846 12847~~~json 12848[ 12849 { 12850 "name": "cdc_auto", 12851 "svcname": "_nvme-disc._tcp", 12852 "referrals": [ 12853 { 12854 "name": "cdc_auto0", 12855 "trid": { 12856 "trtype": "TCP", 12857 "adrfam": "IPv4", 12858 "traddr": "66.1.2.21", 12859 "trsvcid": "8009", 12860 "subnqn": "nqn.2014-08.org.nvmexpress.discovery" 12861 } 12862 }, 12863 { 12864 "name": "cdc_auto1", 12865 "trid": { 12866 "trtype": "TCP", 12867 "adrfam": "IPv4", 12868 "traddr": "66.1.1.21", 12869 "trsvcid": "8009", 12870 "subnqn": "nqn.2014-08.org.nvmexpress.discovery" 12871 } 12872 } 12873 ] 12874 } 12875] 12876~~~ 12877 12878### keyring_file_add_key {#rpc_keyring_file_add_key} 12879 12880Add a file-based key to a keyring. 12881 12882#### Parameters 12883 12884Name | Optional | Type | Description 12885-------------------------- | -------- | ----------- | ----------- 12886name | Required | string | Name of the key to add. 12887path | Required | string | Path to a file containing the key. 12888 12889#### Example 12890 12891Example request: 12892 12893~~~json 12894{ 12895 "jsonrpc": "2.0", 12896 "method": "keyring_file_add_key", 12897 "id": 1 12898 "params": { 12899 "name": "key0", 12900 "path": "/path/to/key0" 12901 } 12902} 12903~~~ 12904 12905Example response: 12906 12907~~~json 12908{ 12909 "jsonrpc": "2.0", 12910 "id": 1, 12911 "result": true 12912} 12913~~~ 12914 12915### keyring_file_remove_key {#rpc_keyring_file_remove_key} 12916 12917Remove a file-based key from a keyring. 12918 12919#### Parameters 12920 12921Name | Optional | Type | Description 12922-------------------------- | -------- | ----------- | ----------- 12923name | Required | string | Name of the key to remove. 12924 12925#### Example 12926 12927Example request: 12928 12929~~~json 12930{ 12931 "jsonrpc": "2.0", 12932 "method": "keyring_file_remove_key", 12933 "id": 1 12934 "params": { 12935 "name": "key0" 12936 } 12937} 12938~~~ 12939 12940Example response: 12941 12942~~~json 12943{ 12944 "jsonrpc": "2.0", 12945 "id": 1, 12946 "result": true 12947} 12948~~~ 12949 12950### keyring_get_keys {#rpc_keyring_get_keys} 12951 12952Get a list of available keys. This RPC will only list keys that are currently attached to a 12953keyring. Dynamically loaded keys (via the `probe_key()` callback) will only be included if they're 12954currently in-use (i.e. with active references obtained via `spdk_keyring_get_key()`). 12955 12956#### Example 12957 12958Example request: 12959~~~json 12960{ 12961 "jsonrpc": "2.0", 12962 "method": "keyring_get_keys", 12963 "id": 1 12964} 12965~~~ 12966 12967Example response: 12968 12969~~~json 12970{ 12971 "jsonrpc": "2.0", 12972 "id": 1, 12973 "result": [ 12974 { 12975 "name": "key0", 12976 "module": "keyring_file", 12977 "removed": false, 12978 "probed": false, 12979 "refcnt": 1, 12980 "path": "/path/to/key0" 12981 }, 12982 { 12983 "name": "key1", 12984 "module": "keyring_file", 12985 "removed": false, 12986 "probed": false, 12987 "refcnt": 1, 12988 "path": "/path/to/key1" 12989 } 12990 ] 12991} 12992~~~ 12993 12994### keyring_linux_set_options {#keyring_linux_set_options} 12995 12996Set options of the keyring_linux module. 12997 12998#### Parameters 12999 13000Name | Optional | Type | Description 13001----------------------- | -------- | ----------- | ----------- 13002enable | Optional | boolean | Enable the module. 13003 13004#### Example 13005 13006Example request: 13007~~~json 13008{ 13009 "jsonrpc": "2.0", 13010 "method": "keyring_linux_set_options", 13011 "id": 1 13012 "params": { 13013 "enable": true 13014 } 13015} 13016~~~ 13017 13018Example response: 13019 13020~~~json 13021{ 13022 "jsonrpc": "2.0", 13023 "id": 1, 13024 "result": true 13025} 13026~~~ 13027