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