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