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