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