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. 6282 6283#### Parameters 6284 6285Name | Optional | Type | Description 6286----------------------- | -------- | ----------- | ----------- 6287nqn | Required | string | Subsystem NQN 6288tgt_name | Optional | string | Parent NVMe-oF target name. 6289listen_address | Required | object | @ref rpc_nvmf_listen_address object 6290ana_state | Required | string | ANA state to set ("optimized", "non_optimized", or "inaccessible") 6291 6292#### Example 6293 6294Example request: 6295 6296~~~ 6297{ 6298 "jsonrpc": "2.0", 6299 "id": 1, 6300 "method": "nvmf_subsystem_listener_set_ana_state", 6301 "params": { 6302 "nqn": "nqn.2016-06.io.spdk:cnode1", 6303 "listen_address": { 6304 "trtype": "RDMA", 6305 "adrfam": "IPv4", 6306 "traddr": "192.168.0.123", 6307 "trsvcid": "4420" 6308 }, 6309 "ana_state", "inaccessible" 6310 } 6311} 6312~~~ 6313 6314Example response: 6315 6316~~~ 6317{ 6318 "jsonrpc": "2.0", 6319 "id": 1, 6320 "result": true 6321} 6322~~~ 6323 6324### nvmf_subsystem_add_ns method {#rpc_nvmf_subsystem_add_ns} 6325 6326Add a namespace to a subsystem. The namespace ID is returned as the result. 6327 6328### Parameters 6329 6330Name | Optional | Type | Description 6331----------------------- | -------- | ----------- | ----------- 6332nqn | Required | string | Subsystem NQN 6333namespace | Required | object | @ref rpc_nvmf_namespace object 6334tgt_name | Optional | string | Parent NVMe-oF target name. 6335 6336#### namespace {#rpc_nvmf_namespace} 6337 6338Name | Optional | Type | Description 6339----------------------- | -------- | ----------- | ----------- 6340nsid | Optional | number | Namespace ID between 1 and 4294967294, inclusive. Default: Automatically assign NSID. 6341bdev_name | Required | string | Name of bdev to expose as a namespace. 6342nguid | Optional | string | 16-byte namespace globally unique identifier in hexadecimal (e.g. "ABCDEF0123456789ABCDEF0123456789") 6343eui64 | Optional | string | 8-byte namespace EUI-64 in hexadecimal (e.g. "ABCDEF0123456789") 6344uuid | Optional | string | RFC 4122 UUID (e.g. "ceccf520-691e-4b46-9546-34af789907c5") 6345ptpl_file | Optional | string | File path to save/restore persistent reservation information 6346 6347#### Example 6348 6349Example request: 6350 6351~~~ 6352{ 6353 "jsonrpc": "2.0", 6354 "id": 1, 6355 "method": "nvmf_subsystem_add_ns", 6356 "params": { 6357 "nqn": "nqn.2016-06.io.spdk:cnode1", 6358 "namespace": { 6359 "nsid": 3, 6360 "bdev_name": "Nvme0n1", 6361 "ptpl_file": "/opt/Nvme0n1PR.json" 6362 } 6363 } 6364} 6365~~~ 6366 6367Example response: 6368 6369~~~ 6370{ 6371 "jsonrpc": "2.0", 6372 "id": 1, 6373 "result": 3 6374} 6375~~~ 6376 6377### nvmf_subsystem_remove_ns method {#rpc_nvmf_subsystem_remove_ns} 6378 6379Remove a namespace from a subsystem. 6380 6381#### Parameters 6382 6383Name | Optional | Type | Description 6384----------------------- | -------- | ----------- | ----------- 6385nqn | Required | string | Subsystem NQN 6386nsid | Required | number | Namespace ID 6387tgt_name | Optional | string | Parent NVMe-oF target name. 6388 6389#### Example 6390 6391Example request: 6392 6393~~~ 6394{ 6395 "jsonrpc": "2.0", 6396 "id": 1, 6397 "method": "nvmf_subsystem_remove_ns", 6398 "params": { 6399 "nqn": "nqn.2016-06.io.spdk:cnode1", 6400 "nsid": 1 6401 } 6402} 6403~~~ 6404 6405Example response: 6406 6407~~~ 6408{ 6409 "jsonrpc": "2.0", 6410 "id": 1, 6411 "result": true 6412} 6413~~~ 6414 6415### nvmf_subsystem_add_host method {#rpc_nvmf_subsystem_add_host} 6416 6417Add a host NQN to the list of allowed hosts. 6418 6419#### Parameters 6420 6421Name | Optional | Type | Description 6422----------------------- | -------- | ----------- | ----------- 6423nqn | Required | string | Subsystem NQN 6424host | Required | string | Host NQN to add to the list of allowed host NQNs 6425tgt_name | Optional | string | Parent NVMe-oF target name. 6426 6427#### Example 6428 6429Example request: 6430 6431~~~ 6432{ 6433 "jsonrpc": "2.0", 6434 "id": 1, 6435 "method": "nvmf_subsystem_add_host", 6436 "params": { 6437 "nqn": "nqn.2016-06.io.spdk:cnode1", 6438 "host": "nqn.2016-06.io.spdk:host1" 6439 } 6440} 6441~~~ 6442 6443Example response: 6444 6445~~~ 6446{ 6447 "jsonrpc": "2.0", 6448 "id": 1, 6449 "result": true 6450} 6451~~~ 6452 6453### nvmf_subsystem_remove_host method {#rpc_nvmf_subsystem_remove_host} 6454 6455Remove a host NQN from the list of allowed hosts. 6456 6457#### Parameters 6458 6459Name | Optional | Type | Description 6460----------------------- | -------- | ----------- | ----------- 6461nqn | Required | string | Subsystem NQN 6462host | Required | string | Host NQN to remove from the list of allowed host NQNs 6463tgt_name | Optional | string | Parent NVMe-oF target name. 6464 6465#### Example 6466 6467Example request: 6468 6469~~~ 6470{ 6471 "jsonrpc": "2.0", 6472 "id": 1, 6473 "method": "nvmf_subsystem_remove_host", 6474 "params": { 6475 "nqn": "nqn.2016-06.io.spdk:cnode1", 6476 "host": "nqn.2016-06.io.spdk:host1" 6477 } 6478} 6479~~~ 6480 6481Example response: 6482 6483~~~ 6484{ 6485 "jsonrpc": "2.0", 6486 "id": 1, 6487 "result": true 6488} 6489~~~ 6490 6491### nvmf_subsystem_allow_any_host method {#rpc_nvmf_subsystem_allow_any_host} 6492 6493Configure a subsystem to allow any host to connect or to enforce the host NQN list. 6494 6495#### Parameters 6496 6497Name | Optional | Type | Description 6498----------------------- | -------- | ----------- | ----------- 6499nqn | Required | string | Subsystem NQN 6500allow_any_host | Required | boolean | Allow any host (`true`) or enforce allowed host list (`false`). 6501tgt_name | Optional | string | Parent NVMe-oF target name. 6502 6503#### Example 6504 6505Example request: 6506 6507~~~ 6508{ 6509 "jsonrpc": "2.0", 6510 "id": 1, 6511 "method": "nvmf_subsystem_allow_any_host", 6512 "params": { 6513 "nqn": "nqn.2016-06.io.spdk:cnode1", 6514 "allow_any_host": true 6515 } 6516} 6517~~~ 6518 6519Example response: 6520 6521~~~ 6522{ 6523 "jsonrpc": "2.0", 6524 "id": 1, 6525 "result": true 6526} 6527~~~ 6528 6529### nvmf_subsystem_get_controllers {#rpc_nvmf_subsystem_get_controllers} 6530 6531#### Parameters 6532 6533Name | Optional | Type | Description 6534----------------------- | -------- | ----------- | ----------- 6535nqn | Required | string | Subsystem NQN 6536tgt_name | Optional | string | Parent NVMe-oF target name. 6537 6538#### Example 6539 6540Example request: 6541 6542~~~ 6543{ 6544 "jsonrpc": "2.0", 6545 "id": 1, 6546 "method": "nvmf_subsystem_get_controllers", 6547 "params": { 6548 "nqn": "nqn.2016-06.io.spdk:cnode1" 6549 } 6550} 6551~~~ 6552 6553Example response: 6554 6555~~~ 6556{ 6557 "jsonrpc": "2.0", 6558 "id": 1, 6559 "result": [ 6560 { 6561 "cntlid": 1, 6562 "hostnqn": "nqn.2016-06.io.spdk:host1", 6563 "hostid": "27dad528-6368-41c3-82d3-0b956b49025d", 6564 "num_io_qpairs": 5 6565 } 6566 ] 6567} 6568~~~ 6569 6570### nvmf_subsystem_get_qpairs {#rpc_nvmf_subsystem_get_qpairs} 6571 6572#### Parameters 6573 6574Name | Optional | Type | Description 6575----------------------- | -------- | ----------- | ----------- 6576nqn | Required | string | Subsystem NQN 6577tgt_name | Optional | string | Parent NVMe-oF target name. 6578 6579#### Example 6580 6581Example request: 6582 6583~~~ 6584{ 6585 "jsonrpc": "2.0", 6586 "id": 1, 6587 "method": "nvmf_subsystem_get_qpairs", 6588 "params": { 6589 "nqn": "nqn.2016-06.io.spdk:cnode1" 6590 } 6591} 6592~~~ 6593 6594Example response: 6595 6596~~~ 6597{ 6598 "jsonrpc": "2.0", 6599 "id": 1, 6600 "result": [ 6601 { 6602 "cntlid": 1, 6603 "qid": 0, 6604 "state": "active", 6605 "listen_address": { 6606 "trtype": "RDMA", 6607 "adrfam": "IPv4", 6608 "traddr": "192.168.0.123", 6609 "trsvcid": "4420" 6610 } 6611 }, 6612 { 6613 "cntlid": 1, 6614 "qid": 1, 6615 "state": "active", 6616 "listen_address": { 6617 "trtype": "RDMA", 6618 "adrfam": "IPv4", 6619 "traddr": "192.168.0.123", 6620 "trsvcid": "4420" 6621 } 6622 } 6623 ] 6624} 6625~~~ 6626 6627### nvmf_subsystem_get_listeners {#rpc_nvmf_subsystem_get_listeners} 6628 6629#### Parameters 6630 6631Name | Optional | Type | Description 6632----------------------- | -------- | ----------- | ----------- 6633nqn | Required | string | Subsystem NQN 6634tgt_name | Optional | string | Parent NVMe-oF target name. 6635 6636#### Example 6637 6638Example request: 6639 6640~~~ 6641{ 6642 "jsonrpc": "2.0", 6643 "id": 1, 6644 "method": "nvmf_subsystem_get_listeners", 6645 "params": { 6646 "nqn": "nqn.2016-06.io.spdk:cnode1" 6647 } 6648} 6649~~~ 6650 6651Example response: 6652 6653~~~ 6654{ 6655 "jsonrpc": "2.0", 6656 "id": 1, 6657 "result": [ 6658 { 6659 "address": { 6660 "trtype": "RDMA", 6661 "adrfam": "IPv4", 6662 "traddr": "192.168.0.123", 6663 "trsvcid": "4420" 6664 }, 6665 "ana_state": "optimized" 6666 } 6667 ] 6668} 6669~~~ 6670 6671### nvmf_set_max_subsystems {#rpc_nvmf_set_max_subsystems} 6672 6673Set the maximum allowed subsystems for the NVMe-oF target. This RPC may only be called 6674before SPDK subsystems have been initialized. 6675 6676#### Parameters 6677 6678Name | Optional | Type | Description 6679----------------------- | -------- | ----------- | ----------- 6680max_subsystems | Required | number | Maximum number of NVMe-oF subsystems 6681 6682#### Example 6683 6684Example request: 6685 6686~~~ 6687{ 6688 "jsonrpc": "2.0", 6689 "id": 1, 6690 "method": "nvmf_set_max_subsystems", 6691 "params": { 6692 "max_subsystems": 1024 6693 } 6694} 6695~~~ 6696 6697Example response: 6698 6699~~~ 6700{ 6701 "jsonrpc": "2.0", 6702 "id": 1, 6703 "result": true 6704} 6705~~~ 6706 6707### nvmf_set_config {#rpc_nvmf_set_config} 6708 6709Set global configuration of NVMe-oF target. This RPC may only be called before SPDK subsystems 6710have been initialized. 6711 6712#### Parameters 6713 6714Name | Optional | Type | Description 6715----------------------- | -------- | ----------- | ----------- 6716acceptor_poll_rate | Optional | number | Polling interval of the acceptor for incoming connections (microseconds) 6717admin_cmd_passthru | Optional | object | Admin command passthru configuration 6718poll_groups_mask | Optional | string | Set cpumask for NVMf poll groups 6719 6720#### admin_cmd_passthru {#spdk_nvmf_admin_passthru_conf} 6721 6722Name | Optional | Type | Description 6723----------------------- | -------- | ----------- | ----------- 6724identify_ctrlr | Required | bool | If true, enables custom identify handler that reports some identify attributes from the underlying NVMe drive 6725 6726#### Example 6727 6728Example request: 6729 6730~~~ 6731{ 6732 "jsonrpc": "2.0", 6733 "id": 1, 6734 "method": "nvmf_set_config", 6735 "params": { 6736 "acceptor_poll_rate": 10000 6737 } 6738} 6739~~~ 6740 6741Example response: 6742 6743~~~ 6744{ 6745 "jsonrpc": "2.0", 6746 "id": 1, 6747 "result": true 6748} 6749~~~ 6750 6751### nvmf_get_transports method {#rpc_nvmf_get_transports} 6752 6753#### Parameters 6754 6755Name | Optional | Type | Description 6756--------------------------- | -------- | ------------| ----------- 6757tgt_name | Optional | string | Parent NVMe-oF target name. 6758 6759#### Example 6760 6761Example request: 6762 6763~~~ 6764{ 6765 "jsonrpc": "2.0", 6766 "id": 1, 6767 "method": "nvmf_get_transports" 6768} 6769~~~ 6770 6771Example response: 6772 6773~~~ 6774{ 6775 "jsonrpc": "2.0", 6776 "id": 1, 6777 "result": [ 6778 { 6779 "type": "RDMA". 6780 "max_queue_depth": 128, 6781 "max_io_qpairs_per_ctrlr": 64, 6782 "in_capsule_data_size": 4096, 6783 "max_io_size": 131072, 6784 "io_unit_size": 131072, 6785 "abort_timeout_sec": 1 6786 } 6787 ] 6788} 6789~~~ 6790 6791### nvmf_get_stats method {#rpc_nvmf_get_stats} 6792 6793Retrieve current statistics of the NVMf subsystem. 6794 6795#### Parameters 6796 6797Name | Optional | Type | Description 6798--------------------------- | -------- | ------------| ----------- 6799tgt_name | Optional | string | Parent NVMe-oF target name. 6800 6801#### Response 6802 6803The response is an object containing NVMf subsystem statistics. 6804In the response, `admin_qpairs` and `io_qpairs` are reflecting cumulative queue pair counts while 6805`current_admin_qpairs` and `current_io_qpairs` are showing the current number. 6806 6807#### Example 6808 6809Example request: 6810~~~ 6811{ 6812 "jsonrpc": "2.0", 6813 "method": "nvmf_get_stats", 6814 "id": 1 6815} 6816~~~ 6817 6818Example response: 6819~~~ 6820{ 6821 "jsonrpc": "2.0", 6822 "id": 1, 6823 "result": { 6824 "tick_rate": 2400000000, 6825 "poll_groups": [ 6826 { 6827 "name": "app_thread", 6828 "admin_qpairs": 1, 6829 "io_qpairs": 4, 6830 "current_admin_qpairs": 1, 6831 "current_io_qpairs": 2, 6832 "pending_bdev_io": 1721, 6833 "transports": [ 6834 { 6835 "trtype": "RDMA", 6836 "pending_data_buffer": 12131888, 6837 "devices": [ 6838 { 6839 "name": "mlx5_1", 6840 "polls": 72284105, 6841 "completions": 0, 6842 "requests": 0, 6843 "request_latency": 0, 6844 "pending_free_request": 0, 6845 "pending_rdma_read": 0, 6846 "pending_rdma_write": 0, 6847 "total_send_wrs": 0, 6848 "send_doorbell_updates": 0, 6849 "total_recv_wrs": 0, 6850 "recv_doorbell_updates": 1 6851 }, 6852 { 6853 "name": "mlx5_0", 6854 "polls": 72284105, 6855 "completions": 15165875, 6856 "requests": 7582935, 6857 "request_latency": 1249323766184, 6858 "pending_free_request": 0, 6859 "pending_rdma_read": 337602, 6860 "pending_rdma_write": 0, 6861 "total_send_wrs": 15165875, 6862 "send_doorbell_updates": 1516587, 6863 "total_recv_wrs": 15165875, 6864 "recv_doorbell_updates": 1516587 6865 } 6866 ] 6867 } 6868 ] 6869 } 6870 ] 6871 } 6872} 6873~~~ 6874 6875### nvmf_set_crdt {#rpc_nvmf_set_crdt} 6876 6877Set the 3 CRDT (Command Retry Delay Time) values. For details about 6878CRDT, please refer to the NVMe specification. Currently all the 6879SPDK nvmf subsystems share the same CRDT values. The default values 6880are 0. This rpc can only be invoked in STARTUP stage. All values are 6881in units of 100 milliseconds (same as the NVMe specification). 6882 6883#### Parameters 6884 6885Name | Optional | Type | Description 6886----------------------- | -------- | ----------- | ----------- 6887crdt1 | Optional | number | Command Retry Delay Time 1 6888crdt2 | Optional | number | Command Retry Delay Time 2 6889crdt3 | Optional | number | Command Retry Delay Time 3 6890 6891## Vhost Target {#jsonrpc_components_vhost_tgt} 6892 6893The following common preconditions need to be met in all target types. 6894 6895Controller name will be used to create UNIX domain socket. This implies that name concatenated with vhost socket 6896directory path needs to be valid UNIX socket name. 6897 6898@ref cpu_mask parameter is used to choose CPU on which pollers will be launched when new initiator is connecting. 6899It must be a subset of application CPU mask. Default value is CPU mask of the application. 6900 6901### vhost_controller_set_coalescing {#rpc_vhost_controller_set_coalescing} 6902 6903Controls interrupt coalescing for specific target. Because `delay_base_us` is used to calculate delay in CPU ticks 6904there is no hardcoded limit for this parameter. Only limitation is that final delay in CPU ticks might not overflow 690532 bit unsigned integer (which is more than 1s @ 4GHz CPU). In real scenarios `delay_base_us` should be much lower 6906than 150us. To disable coalescing set `delay_base_us` to 0. 6907 6908#### Parameters 6909 6910Name | Optional | Type | Description 6911----------------------- | -------- | ----------- | ----------- 6912ctrlr | Required | string | Controller name 6913delay_base_us | Required | number | Base (minimum) coalescing time in microseconds 6914iops_threshold | Required | number | Coalescing activation level greater than 0 in IO per second 6915 6916#### Example 6917 6918Example request: 6919 6920~~~ 6921{ 6922 "params": { 6923 "iops_threshold": 100000, 6924 "ctrlr": "VhostScsi0", 6925 "delay_base_us": 80 6926 }, 6927 "jsonrpc": "2.0", 6928 "method": "vhost_controller_set_coalescing", 6929 "id": 1 6930} 6931~~~ 6932 6933Example response: 6934 6935~~~ 6936{ 6937 "jsonrpc": "2.0", 6938 "id": 1, 6939 "result": true 6940} 6941~~~ 6942 6943### vhost_create_scsi_controller {#rpc_vhost_create_scsi_controller} 6944 6945Construct vhost SCSI target. 6946 6947#### Parameters 6948 6949Name | Optional | Type | Description 6950----------------------- | -------- | ----------- | ----------- 6951ctrlr | Required | string | Controller name 6952cpumask | Optional | string | @ref cpu_mask for this controller 6953 6954#### Example 6955 6956Example request: 6957 6958~~~ 6959{ 6960 "params": { 6961 "cpumask": "0x2", 6962 "ctrlr": "VhostScsi0" 6963 }, 6964 "jsonrpc": "2.0", 6965 "method": "vhost_create_scsi_controller", 6966 "id": 1 6967} 6968~~~ 6969 6970Example response: 6971 6972~~~ 6973{ 6974 "jsonrpc": "2.0", 6975 "id": 1, 6976 "result": true 6977} 6978~~~ 6979 6980### vhost_scsi_controller_add_target {#rpc_vhost_scsi_controller_add_target} 6981 6982In vhost target `ctrlr` create SCSI target with ID `scsi_target_num` and add `bdev_name` as LUN 0. 6983 6984#### Parameters 6985 6986Name | Optional | Type | Description 6987----------------------- | -------- | ----------- | ----------- 6988ctrlr | Required | string | Controller name 6989scsi_target_num | Required | number | SCSI target ID between 0 and 7 or -1 to use first free ID. 6990bdev_name | Required | string | Name of bdev to expose as a LUN 0 6991 6992#### Response 6993 6994SCSI target ID. 6995 6996#### Example 6997 6998Example request: 6999 7000~~~ 7001{ 7002 "params": { 7003 "scsi_target_num": 1, 7004 "bdev_name": "Malloc0", 7005 "ctrlr": "VhostScsi0" 7006 }, 7007 "jsonrpc": "2.0", 7008 "method": "vhost_scsi_controller_add_target", 7009 "id": 1 7010} 7011~~~ 7012 7013Example response: 7014 7015~~~ 7016response: 7017{ 7018 "jsonrpc": "2.0", 7019 "id": 1, 7020 "result": 1 7021} 7022~~~ 7023 7024### vhost_scsi_controller_remove_target {#rpc_vhost_scsi_controller_remove_target} 7025 7026Remove SCSI target ID `scsi_target_num` from vhost target `scsi_target_num`. 7027 7028This method will fail if initiator is connected, but doesn't support hot-remove (the `VIRTIO_SCSI_F_HOTPLUG` is not negotiated). 7029 7030#### Parameters 7031 7032Name | Optional | Type | Description 7033----------------------- | -------- | ----------- | ----------- 7034ctrlr | Required | string | Controller name 7035scsi_target_num | Required | number | SCSI target ID between 0 and 7 7036 7037#### Example 7038 7039Example request: 7040 7041~~~ 7042request: 7043{ 7044 "params": { 7045 "scsi_target_num": 1, 7046 "ctrlr": "VhostScsi0" 7047 }, 7048 "jsonrpc": "2.0", 7049 "method": "vhost_scsi_controller_remove_target", 7050 "id": 1 7051} 7052~~~ 7053 7054Example response: 7055 7056~~~ 7057{ 7058 "jsonrpc": "2.0", 7059 "id": 1, 7060 "result": true 7061} 7062~~~ 7063 7064### vhost_create_blk_controller {#rpc_vhost_create_blk_controller} 7065 7066Create vhost block controller 7067 7068If `readonly` is `true` then vhost block target will be created as read only and fail any write requests. 7069The `VIRTIO_BLK_F_RO` feature flag will be offered to the initiator. 7070 7071#### Parameters 7072 7073Name | Optional | Type | Description 7074----------------------- | -------- | ----------- | ----------- 7075ctrlr | Required | string | Controller name 7076bdev_name | Required | string | Name of bdev to expose block device 7077readonly | Optional | boolean | If true, this target will be read only (default: false) 7078cpumask | Optional | string | @ref cpu_mask for this controller 7079 7080#### Example 7081 7082Example request: 7083 7084~~~ 7085{ 7086 "params": { 7087 "dev_name": "Malloc0", 7088 "ctrlr": "VhostBlk0" 7089 }, 7090 "jsonrpc": "2.0", 7091 "method": "vhost_create_blk_controller", 7092 "id": 1 7093} 7094~~~ 7095 7096Example response: 7097 7098~~~ 7099{ 7100 "jsonrpc": "2.0", 7101 "id": 1, 7102 "result": true 7103} 7104~~~ 7105 7106### vhost_get_controllers {#rpc_vhost_get_controllers} 7107 7108Display information about all or specific vhost controller(s). 7109 7110#### Parameters 7111 7112The user may specify no parameters in order to list all controllers, or a controller may be 7113specified by name. 7114 7115Name | Optional | Type | Description 7116----------------------- | -------- | ----------- | ----------- 7117name | Optional | string | Vhost controller name 7118 7119#### Response {#rpc_vhost_get_controllers_response} 7120 7121Response is an array of objects describing requested controller(s). Common fields are: 7122 7123Name | Type | Description 7124----------------------- | ----------- | ----------- 7125ctrlr | string | Controller name 7126cpumask | string | @ref cpu_mask of this controller 7127delay_base_us | number | Base (minimum) coalescing time in microseconds (0 if disabled) 7128iops_threshold | number | Coalescing activation level 7129backend_specific | object | Backend specific informations 7130 7131### Vhost block {#rpc_vhost_get_controllers_blk} 7132 7133`backend_specific` contains one `block` object of type: 7134 7135Name | Type | Description 7136----------------------- | ----------- | ----------- 7137bdev | string | Backing bdev name or Null if bdev is hot-removed 7138readonly | boolean | True if controllers is readonly, false otherwise 7139 7140### Vhost SCSI {#rpc_vhost_get_controllers_scsi} 7141 7142`backend_specific` contains `scsi` array of following objects: 7143 7144Name | Type | Description 7145----------------------- | ----------- | ----------- 7146target_name | string | Name of this SCSI target 7147id | number | Unique SPDK global SCSI target ID 7148scsi_dev_num | number | SCSI target ID initiator will see when scanning this controller 7149luns | array | array of objects describing @ref rpc_vhost_get_controllers_scsi_luns 7150 7151### Vhost SCSI LUN {#rpc_vhost_get_controllers_scsi_luns} 7152 7153Object of type: 7154 7155Name | Type | Description 7156----------------------- | ----------- | ----------- 7157id | number | SCSI LUN ID 7158bdev_name | string | Backing bdev name 7159 7160### Vhost NVMe {#rpc_vhost_get_controllers_nvme} 7161 7162`backend_specific` contains `namespaces` array of following objects: 7163 7164Name | Type | Description 7165----------------------- | ----------- | ----------- 7166nsid | number | Namespace ID 7167bdev | string | Backing bdev name 7168 7169#### Example 7170 7171Example request: 7172 7173~~~ 7174{ 7175 "jsonrpc": "2.0", 7176 "method": "vhost_get_controllers", 7177 "id": 1 7178} 7179~~~ 7180 7181Example response: 7182 7183~~~ 7184{ 7185 "jsonrpc": "2.0", 7186 "id": 1, 7187 "result": [ 7188 { 7189 "cpumask": "0x2", 7190 "backend_specific": { 7191 "block": { 7192 "readonly": false, 7193 "bdev": "Malloc0" 7194 } 7195 }, 7196 "iops_threshold": 60000, 7197 "ctrlr": "VhostBlk0", 7198 "delay_base_us": 100 7199 }, 7200 { 7201 "cpumask": "0x2", 7202 "backend_specific": { 7203 "scsi": [ 7204 { 7205 "target_name": "Target 2", 7206 "luns": [ 7207 { 7208 "id": 0, 7209 "bdev_name": "Malloc1" 7210 } 7211 ], 7212 "id": 0, 7213 "scsi_dev_num": 2 7214 }, 7215 { 7216 "target_name": "Target 5", 7217 "luns": [ 7218 { 7219 "id": 0, 7220 "bdev_name": "Malloc2" 7221 } 7222 ], 7223 "id": 1, 7224 "scsi_dev_num": 5 7225 } 7226 ] 7227 }, 7228 "iops_threshold": 60000, 7229 "ctrlr": "VhostScsi0", 7230 "delay_base_us": 0 7231 }, 7232 { 7233 "cpumask": "0x2", 7234 "backend_specific": { 7235 "namespaces": [ 7236 { 7237 "bdev": "Malloc3", 7238 "nsid": 1 7239 }, 7240 { 7241 "bdev": "Malloc4", 7242 "nsid": 2 7243 } 7244 ] 7245 }, 7246 "iops_threshold": 60000, 7247 "ctrlr": "VhostNvme0", 7248 "delay_base_us": 0 7249 } 7250 ] 7251} 7252~~~ 7253 7254### vhost_delete_controller {#rpc_vhost_delete_controller} 7255 7256Remove vhost target. 7257 7258This call will fail if there is an initiator connected or there is at least one SCSI target configured in case of 7259vhost SCSI target. In the later case please remove all SCSI targets first using @ref rpc_vhost_scsi_controller_remove_target. 7260 7261#### Parameters 7262 7263Name | Optional | Type | Description 7264----------------------- | -------- | ----------- | ----------- 7265ctrlr | Required | string | Controller name 7266 7267#### Example 7268 7269Example request: 7270 7271~~~ 7272{ 7273 "params": { 7274 "ctrlr": "VhostNvme0" 7275 }, 7276 "jsonrpc": "2.0", 7277 "method": "vhost_delete_controller", 7278 "id": 1 7279} 7280~~~ 7281 7282Example response: 7283 7284~~~ 7285{ 7286 "jsonrpc": "2.0", 7287 "id": 1, 7288 "result": true 7289} 7290~~~ 7291 7292## Logical Volume {#jsonrpc_components_lvol} 7293 7294Identification of logical volume store and logical volume is explained first. 7295 7296A logical volume store has a UUID and a name for its identification. 7297The UUID is generated on creation and it can be used as a unique identifier. 7298The name is specified on creation and can be renamed. 7299Either UUID or name is used to access logical volume store in RPCs. 7300 7301A logical volume has a UUID and a name for its identification. 7302The UUID of the logical volume is generated on creation and it can be unique identifier. 7303The alias of the logical volume takes the format _lvs_name/lvol_name_ where: 7304 7305* _lvs_name_ is the name of the logical volume store. 7306* _lvol_name_ is specified on creation and can be renamed. 7307 7308### bdev_lvol_create_lvstore {#rpc_bdev_lvol_create_lvstore} 7309 7310Construct a logical volume store. 7311 7312#### Parameters 7313 7314Name | Optional | Type | Description 7315----------------------- | -------- | ----------- | ----------- 7316bdev_name | Required | string | Bdev on which to construct logical volume store 7317lvs_name | Required | string | Name of the logical volume store to create 7318cluster_sz | Optional | number | Cluster size of the logical volume store in bytes 7319clear_method | Optional | string | Change clear method for data region. Available: none, unmap (default), write_zeroes 7320 7321#### Response 7322 7323UUID of the created logical volume store is returned. 7324 7325#### Example 7326 7327Example request: 7328 7329~~~ 7330{ 7331 "jsonrpc": "2.0", 7332 "id": 1, 7333 "method": "bdev_lvol_create_lvstore", 7334 "params": { 7335 "lvs_name": "LVS0", 7336 "bdev_name": "Malloc0" 7337 "clear_method": "write_zeroes" 7338 } 7339} 7340~~~ 7341 7342Example response: 7343 7344~~~ 7345{ 7346 "jsonrpc": "2.0", 7347 "id": 1, 7348 "result": "a9959197-b5e2-4f2d-8095-251ffb6985a5" 7349} 7350~~~ 7351 7352### bdev_lvol_delete_lvstore {#rpc_bdev_lvol_delete_lvstore} 7353 7354Destroy a logical volume store. 7355 7356#### Parameters 7357 7358Name | Optional | Type | Description 7359----------------------- | -------- | ----------- | ----------- 7360uuid | Optional | string | UUID of the logical volume store to destroy 7361lvs_name | Optional | string | Name of the logical volume store to destroy 7362 7363Either uuid or lvs_name must be specified, but not both. 7364 7365#### Example 7366 7367Example request: 7368 7369~~~ 7370{ 7371 "jsonrpc": "2.0", 7372 "method": "bdev_lvol_delete_lvstore", 7373 "id": 1 7374 "params": { 7375 "uuid": "a9959197-b5e2-4f2d-8095-251ffb6985a5" 7376 } 7377} 7378~~~ 7379 7380Example response: 7381 7382~~~ 7383{ 7384 "jsonrpc": "2.0", 7385 "id": 1, 7386 "result": true 7387} 7388~~~ 7389 7390### bdev_lvol_get_lvstores {#rpc_bdev_lvol_get_lvstores} 7391 7392Get a list of logical volume stores. 7393 7394#### Parameters 7395 7396Name | Optional | Type | Description 7397----------------------- | -------- | ----------- | ----------- 7398uuid | Optional | string | UUID of the logical volume store to retrieve information about 7399lvs_name | Optional | string | Name of the logical volume store to retrieve information about 7400 7401Either uuid or lvs_name may be specified, but not both. 7402If both uuid and lvs_name are omitted, information about all logical volume stores is returned. 7403 7404#### Example 7405 7406Example request: 7407 7408~~~ 7409{ 7410 "jsonrpc": "2.0", 7411 "method": "bdev_lvol_get_lvstores", 7412 "id": 1, 7413 "params": { 7414 "lvs_name": "LVS0" 7415 } 7416} 7417~~~ 7418 7419Example response: 7420 7421~~~ 7422{ 7423 "jsonrpc": "2.0", 7424 "id": 1, 7425 "result": [ 7426 { 7427 "uuid": "a9959197-b5e2-4f2d-8095-251ffb6985a5", 7428 "base_bdev": "Malloc0", 7429 "free_clusters": 31, 7430 "cluster_size": 4194304, 7431 "total_data_clusters": 31, 7432 "block_size": 4096, 7433 "name": "LVS0" 7434 } 7435 ] 7436} 7437~~~ 7438 7439### bdev_lvol_rename_lvstore {#rpc_bdev_lvol_rename_lvstore} 7440 7441Rename a logical volume store. 7442 7443#### Parameters 7444 7445Name | Optional | Type | Description 7446----------------------- | -------- | ----------- | ----------- 7447old_name | Required | string | Existing logical volume store name 7448new_name | Required | string | New logical volume store name 7449 7450#### Example 7451 7452Example request: 7453 7454~~~ 7455{ 7456 "jsonrpc": "2.0", 7457 "method": "bdev_lvol_rename_lvstore", 7458 "id": 1, 7459 "params": { 7460 "old_name": "LVS0", 7461 "new_name": "LVS2" 7462 } 7463} 7464~~~ 7465 7466Example response: 7467 7468~~~ 7469{ 7470 "jsonrpc": "2.0", 7471 "id": 1, 7472 "result": true 7473} 7474~~~ 7475 7476### bdev_lvol_create {#rpc_bdev_lvol_create} 7477 7478Create a logical volume on a logical volume store. 7479 7480#### Parameters 7481 7482Name | Optional | Type | Description 7483----------------------- | -------- | ----------- | ----------- 7484lvol_name | Required | string | Name of logical volume to create 7485size | Required | number | Desired size of logical volume in bytes 7486thin_provision | Optional | boolean | True to enable thin provisioning 7487uuid | Optional | string | UUID of logical volume store to create logical volume on 7488lvs_name | Optional | string | Name of logical volume store to create logical volume on 7489clear_method | Optional | string | Change default data clusters clear method. Available: none, unmap, write_zeroes 7490 7491Size will be rounded up to a multiple of cluster size. Either uuid or lvs_name must be specified, but not both. 7492lvol_name will be used in the alias of the created logical volume. 7493 7494#### Response 7495 7496UUID of the created logical volume is returned. 7497 7498#### Example 7499 7500Example request: 7501 7502~~~ 7503{ 7504 "jsonrpc": "2.0", 7505 "method": "bdev_lvol_create", 7506 "id": 1, 7507 "params": { 7508 "lvol_name": "LVOL0", 7509 "size": 1048576, 7510 "lvs_name": "LVS0", 7511 "clear_method": "unmap", 7512 "thin_provision": true 7513 } 7514} 7515~~~ 7516 7517Example response: 7518 7519~~~ 7520{ 7521 "jsonrpc": "2.0", 7522 "id": 1, 7523 "result": "1b38702c-7f0c-411e-a962-92c6a5a8a602" 7524} 7525~~~ 7526 7527### bdev_lvol_snapshot {#rpc_bdev_lvol_snapshot} 7528 7529Capture a snapshot of the current state of a logical volume. 7530 7531#### Parameters 7532 7533Name | Optional | Type | Description 7534----------------------- | -------- | ----------- | ----------- 7535lvol_name | Required | string | UUID or alias of the logical volume to create a snapshot from 7536snapshot_name | Required | string | Name for the newly created snapshot 7537 7538#### Response 7539 7540UUID of the created logical volume snapshot is returned. 7541 7542#### Example 7543 7544Example request: 7545 7546~~~ 7547{ 7548 "jsonrpc": "2.0", 7549 "method": "bdev_lvol_snapshot", 7550 "id": 1, 7551 "params": { 7552 "lvol_name": "1b38702c-7f0c-411e-a962-92c6a5a8a602", 7553 "snapshot_name": "SNAP1" 7554 } 7555} 7556~~~ 7557 7558Example response: 7559 7560~~~ 7561{ 7562 "jsonrpc": "2.0", 7563 "id": 1, 7564 "result": "cc8d7fdf-7865-4d1f-9fc6-35da8e368670" 7565} 7566~~~ 7567 7568### bdev_lvol_clone {#rpc_bdev_lvol_clone} 7569 7570Create a logical volume based on a snapshot. 7571 7572#### Parameters 7573 7574Name | Optional | Type | Description 7575----------------------- | -------- | ----------- | ----------- 7576snapshot_name | Required | string | UUID or alias of the snapshot to clone 7577clone_name | Required | string | Name for the logical volume to create 7578 7579#### Response 7580 7581UUID of the created logical volume clone is returned. 7582 7583#### Example 7584 7585Example request: 7586 7587~~~ 7588{ 7589 "jsonrpc": "2.0" 7590 "method": "bdev_lvol_clone", 7591 "id": 1, 7592 "params": { 7593 "snapshot_name": "cc8d7fdf-7865-4d1f-9fc6-35da8e368670", 7594 "clone_name": "CLONE1" 7595 } 7596} 7597~~~ 7598 7599Example response: 7600 7601~~~ 7602{ 7603 "jsonrpc": "2.0", 7604 "id": 1, 7605 "result": "8d87fccc-c278-49f0-9d4c-6237951aca09" 7606} 7607~~~ 7608 7609### bdev_lvol_rename {#rpc_bdev_lvol_rename} 7610 7611Rename a logical volume. New name will rename only the alias of the logical volume. 7612 7613#### Parameters 7614 7615Name | Optional | Type | Description 7616----------------------- | -------- | ----------- | ----------- 7617old_name | Required | string | UUID or alias of the existing logical volume 7618new_name | Required | string | New logical volume name 7619 7620#### Example 7621 7622Example request: 7623 7624~~~ 7625{ 7626 "jsonrpc": "2.0", 7627 "method": "bdev_lvol_rename", 7628 "id": 1, 7629 "params": { 7630 "old_name": "067df606-6dbc-4143-a499-0d05855cb3b8", 7631 "new_name": "LVOL2" 7632 } 7633} 7634~~~ 7635 7636Example response: 7637 7638~~~ 7639{ 7640 "jsonrpc": "2.0", 7641 "id": 1, 7642 "result": true 7643} 7644~~~ 7645 7646### bdev_lvol_resize {#rpc_bdev_lvol_resize} 7647 7648Resize a logical volume. 7649 7650#### Parameters 7651 7652Name | Optional | Type | Description 7653----------------------- | -------- | ----------- | ----------- 7654name | Required | string | UUID or alias of the logical volume to resize 7655size | Required | number | Desired size of the logical volume in bytes 7656 7657#### Example 7658 7659Example request: 7660 7661~~~ 7662{ 7663 "jsonrpc": "2.0", 7664 "method": "bdev_lvol_resize", 7665 "id": 1, 7666 "params": { 7667 "name": "51638754-ca16-43a7-9f8f-294a0805ab0a", 7668 "size": 2097152 7669 } 7670} 7671~~~ 7672 7673Example response: 7674 7675~~~ 7676{ 7677 "jsonrpc": "2.0", 7678 "id": 1, 7679 "result": true 7680} 7681~~~ 7682 7683### bdev_lvol_set_read_only{#rpc_bdev_lvol_set_read_only} 7684 7685Mark logical volume as read only. 7686 7687#### Parameters 7688 7689Name | Optional | Type | Description 7690----------------------- | -------- | ----------- | ----------- 7691name | Required | string | UUID or alias of the logical volume to set as read only 7692 7693#### Example 7694 7695Example request: 7696 7697~~~ 7698{ 7699 "jsonrpc": "2.0", 7700 "method": "bdev_lvol_set_read_only", 7701 "id": 1, 7702 "params": { 7703 "name": "51638754-ca16-43a7-9f8f-294a0805ab0a", 7704 } 7705} 7706~~~ 7707 7708Example response: 7709 7710~~~ 7711{ 7712 "jsonrpc": "2.0", 7713 "id": 1, 7714 "result": true 7715} 7716~~~ 7717 7718### bdev_lvol_delete {#rpc_bdev_lvol_delete} 7719 7720Destroy a logical volume. 7721 7722#### Parameters 7723 7724Name | Optional | Type | Description 7725----------------------- | -------- | ----------- | ----------- 7726name | Required | string | UUID or alias of the logical volume to destroy 7727 7728#### Example 7729 7730Example request: 7731 7732~~~ 7733{ 7734 "jsonrpc": "2.0", 7735 "method": "bdev_lvol_delete", 7736 "id": 1, 7737 "params": { 7738 "name": "51638754-ca16-43a7-9f8f-294a0805ab0a" 7739 } 7740} 7741~~~ 7742 7743Example response: 7744 7745~~~ 7746{ 7747 "jsonrpc": "2.0", 7748 "id": 1, 7749 "result": true 7750} 7751~~~ 7752 7753### bdev_lvol_inflate {#rpc_bdev_lvol_inflate} 7754 7755Inflate a logical volume. All unallocated clusters are allocated and copied from the parent or zero filled 7756if not allocated in the parent. Then all dependencies on the parent are removed. 7757 7758### Parameters 7759 7760Name | Optional | Type | Description 7761----------------------- | -------- | ----------- | ----------- 7762name | Required | string | UUID or alias of the logical volume to inflate 7763 7764#### Example 7765 7766Example request: 7767 7768~~~ 7769{ 7770 "jsonrpc": "2.0", 7771 "method": "bdev_lvol_inflate", 7772 "id": 1, 7773 "params": { 7774 "name": "8d87fccc-c278-49f0-9d4c-6237951aca09" 7775 } 7776} 7777~~~ 7778 7779Example response: 7780 7781~~~ 7782{ 7783 "jsonrpc": "2.0", 7784 "id": 1, 7785 "result": true 7786} 7787~~~ 7788 7789### bdev_lvol_decouple_parent {#rpc_bdev_lvol_decouple_parent} 7790 7791Decouple the parent of a logical volume. For unallocated clusters which is allocated in the parent, they are 7792allocated and copied from the parent, but for unallocated clusters which is thin provisioned in the parent, 7793they are kept thin provisioned. Then all dependencies on the parent are removed. 7794 7795#### Parameters 7796 7797Name | Optional | Type | Description 7798----------------------- | -------- | ----------- | ----------- 7799name | Required | string | UUID or alias of the logical volume to decouple the parent of it 7800 7801#### Example 7802 7803Example request: 7804 7805~~~ 7806{ 7807 "jsonrpc": "2.0", 7808 "method": "bdev_lvol_decouple_parent", 7809 "id": 1. 7810 "params": { 7811 "name": "8d87fccc-c278-49f0-9d4c-6237951aca09" 7812 } 7813} 7814~~~ 7815 7816Example response: 7817 7818~~~ 7819{ 7820 "jsonrpc": "2.0", 7821 "id": 1, 7822 "result": true 7823} 7824~~~ 7825 7826## RAID 7827 7828### bdev_raid_get_bdevs {#rpc_bdev_raid_get_bdevs} 7829 7830This is used to list all the raid bdev names based on the input category requested. Category should be one 7831of 'all', 'online', 'configuring' or 'offline'. 'all' means all the raid bdevs whether they are online or 7832configuring or offline. 'online' is the raid bdev which is registered with bdev layer. 'configuring' is 7833the raid bdev which does not have full configuration discovered yet. 'offline' is the raid bdev which is 7834not registered with bdev as of now and it has encountered any error or user has requested to offline 7835the raid bdev. 7836 7837#### Parameters 7838 7839Name | Optional | Type | Description 7840----------------------- | -------- | ----------- | ----------- 7841category | Required | string | all or online or configuring or offline 7842 7843#### Example 7844 7845Example request: 7846 7847~~~ 7848{ 7849 "jsonrpc": "2.0", 7850 "method": "bdev_raid_get_bdevs", 7851 "id": 1, 7852 "params": { 7853 "category": "all" 7854 } 7855} 7856~~~ 7857 7858Example response: 7859 7860~~~ 7861{ 7862 "jsonrpc": "2.0", 7863 "id": 1, 7864 "result": [ 7865 "Raid0" 7866 ] 7867} 7868~~~ 7869 7870### bdev_raid_create {#rpc_bdev_raid_create} 7871 7872Constructs new RAID bdev. 7873 7874#### Parameters 7875 7876Name | Optional | Type | Description 7877----------------------- | -------- | ----------- | ----------- 7878name | Required | string | RAID bdev name 7879strip_size_kb | Required | number | Strip size in KB 7880raid_level | Required | string | RAID level 7881base_bdevs | Required | string | Base bdevs name, whitespace separated list in quotes 7882 7883#### Example 7884 7885Example request: 7886 7887~~~ 7888{ 7889 "jsonrpc": "2.0", 7890 "method": "bdev_raid_create", 7891 "id": 1, 7892 "params": { 7893 "name": "Raid0", 7894 "raid_level": "0", 7895 "base_bdevs": [ 7896 "Malloc0", 7897 "Malloc1", 7898 "Malloc2", 7899 "Malloc3" 7900 ], 7901 "strip_size_kb": 4 7902 } 7903} 7904~~~ 7905 7906Example response: 7907 7908~~~ 7909{ 7910 "jsonrpc": "2.0", 7911 "id": 1, 7912 "result": true 7913} 7914~~~ 7915 7916### bdev_raid_delete {#rpc_bdev_raid_delete} 7917 7918Removes RAID bdev. 7919 7920#### Parameters 7921 7922Name | Optional | Type | Description 7923----------------------- | -------- | ----------- | ----------- 7924name | Required | string | RAID bdev name 7925 7926#### Example 7927 7928Example request: 7929 7930~~~ 7931{ 7932 "jsonrpc": "2.0", 7933 "method": "bdev_raid_delete", 7934 "id": 1, 7935 "params": { 7936 "name": "Raid0" 7937 } 7938} 7939~~~ 7940 7941Example response: 7942 7943~~~ 7944{ 7945 "jsonrpc": "2.0", 7946 "id": 1, 7947 "result": true 7948} 7949~~~ 7950 7951## SPLIT 7952 7953### bdev_split_create {#rpc_bdev_split_create} 7954 7955This is used to split an underlying block device and create several smaller equal-sized vbdevs. 7956 7957#### Parameters 7958 7959Name | Optional | Type | Description 7960----------------------- | -------- | ----------- | ----------- 7961base_bdev | Required | string | base bdev name 7962split_count | Required | number | number of splits 7963split_size_mb | Optional | number | size in MB to restrict the size 7964 7965#### Example 7966 7967Example request: 7968 7969~~~ 7970{ 7971 "jsonrpc": "2.0", 7972 "method": "bdev_split_create", 7973 "id": 1, 7974 "params": { 7975 "base_bdev": "Malloc0", 7976 "split_count": 4 7977 } 7978} 7979~~~ 7980 7981Example response: 7982 7983~~~ 7984{ 7985 "jsonrpc": "2.0", 7986 "id": 1, 7987 "result": [ 7988 "Malloc0p0", 7989 "Malloc0p1", 7990 "Malloc0p2", 7991 "Malloc0p3" 7992 ] 7993} 7994~~~ 7995 7996### bdev_split_delete {#rpc_bdev_split_delete} 7997 7998This is used to remove the split vbdevs. 7999 8000#### Parameters 8001 8002Name | Optional | Type | Description 8003----------------------- | -------- | ----------- | ----------- 8004base_bdev | Required | string | base bdev name 8005 8006#### Example 8007 8008Example request: 8009 8010~~~ 8011{ 8012 "jsonrpc": "2.0", 8013 "method": "bdev_split_delete", 8014 "id": 1, 8015 "params": { 8016 "base_bdev": "Malloc0" 8017 } 8018} 8019~~~ 8020 8021Example response: 8022 8023~~~ 8024{ 8025 "jsonrpc": "2.0", 8026 "id": 1, 8027 "result": true 8028} 8029~~~ 8030 8031## Uring 8032 8033### bdev_uring_create {#rpc_bdev_uring_create} 8034 8035Create a bdev with io_uring backend. 8036 8037#### Parameters 8038 8039Name | Optional | Type | Description 8040----------------------- | -------- | ----------- | ----------- 8041filename | Required | string | path to device or file (ex: /dev/nvme0n1) 8042name | Required | string | name of bdev 8043block_size | Optional | number | block size of device (If omitted, get the block size from the file) 8044 8045#### Example 8046 8047Example request: 8048 8049~~~ 8050{ 8051 "jsonrpc": "2.0", 8052 "method": "bdev_uring_create", 8053 "id": 1, 8054 "params": { 8055 "name": "bdev_u0", 8056 "filename": "/dev/nvme0n1", 8057 "block_size": 512 8058 } 8059} 8060~~~ 8061 8062Example response: 8063 8064~~~ 8065{ 8066 "jsonrpc": "2.0", 8067 "id": 1, 8068 "result": "bdev_u0" 8069} 8070~~~ 8071 8072### bdev_uring_delete {#rpc_bdev_uring_delete} 8073 8074Remove a uring bdev. 8075 8076#### Parameters 8077 8078Name | Optional | Type | Description 8079----------------------- | -------- | ----------- | ----------- 8080name | Required | string | name of uring bdev to delete 8081 8082#### Example 8083 8084Example request: 8085 8086~~~ 8087{ 8088 "jsonrpc": "2.0", 8089 "method": "bdev_uring_delete", 8090 "id": 1, 8091 "params": { 8092 "name": "bdev_u0" 8093 } 8094} 8095~~~ 8096 8097Example response: 8098 8099~~~ 8100{ 8101 "jsonrpc": "2.0", 8102 "id": 1, 8103 "result": true 8104} 8105~~~ 8106 8107## OPAL 8108 8109### bdev_nvme_opal_init {#rpc_bdev_nvme_opal_init} 8110 8111This is used to initialize OPAL of a given NVMe ctrlr, including taking ownership and activating. 8112 8113#### Parameters 8114 8115Name | Optional | Type | Description 8116----------------------- | -------- | ----------- | ----------- 8117nvme_ctrlr_name | Required | string | name of nvme ctrlr 8118password | Required | string | admin password of OPAL 8119 8120#### Example 8121 8122Example request: 8123 8124~~~ 8125{ 8126 "jsonrpc": "2.0", 8127 "method": "bdev_nvme_opal_init", 8128 "id": 1, 8129 "params": { 8130 "nvme_ctrlr_name": "nvme0", 8131 "password": "*****" 8132 } 8133} 8134~~~ 8135 8136Example response: 8137 8138~~~ 8139{ 8140 "jsonrpc": "2.0", 8141 "id": 1, 8142 "result": true 8143} 8144~~~ 8145 8146### bdev_nvme_opal_revert {#rpc_bdev_nvme_opal_revert} 8147 8148This is used to revert OPAL to its factory settings. Erase all user configuration and data. 8149 8150#### Parameters 8151 8152Name | Optional | Type | Description 8153----------------------- | -------- | ----------- | ----------- 8154nvme_ctrlr_name | Required | string | name of nvme ctrlr 8155password | Required | string | admin password of OPAL 8156 8157#### Example 8158 8159Example request: 8160 8161~~~ 8162{ 8163 "jsonrpc": "2.0", 8164 "method": "bdev_nvme_opal_revert", 8165 "id": 1, 8166 "params": { 8167 "nvme_ctrlr_name": "nvme0", 8168 "password": "*****" 8169 } 8170} 8171~~~ 8172 8173Example response: 8174 8175~~~ 8176{ 8177 "jsonrpc": "2.0", 8178 "id": 1, 8179 "result": true 8180} 8181~~~ 8182 8183### bdev_opal_create {#rpc_bdev_opal_create} 8184 8185This is used to create an OPAL virtual bdev. 8186 8187#### Parameters 8188 8189Name | Optional | Type | Description 8190----------------------- | -------- | ----------- | ----------- 8191nvme_ctrlr_name | Required | string | name of nvme ctrlr that supports OPAL 8192nsid | Required | number | namespace ID 8193locking_range_id | Required | number | OPAL locking range ID 8194range_start | Required | number | locking range start LBA 8195range_length | Required | number | locking range length 8196password | Required | string | admin password of OPAL 8197 8198#### Response 8199 8200The response is the name of created OPAL virtual bdev. 8201 8202#### Example 8203 8204Example request: 8205 8206~~~ 8207{ 8208 "jsonrpc": "2.0", 8209 "method": "bdev_opal_create", 8210 "id": 1, 8211 "params": { 8212 "nvme_ctrlr_name": "nvme0", 8213 "nsid": 1, 8214 "locking_range_id": 1, 8215 "range_start": 0, 8216 "range_length": 4096, 8217 "password": "*****" 8218 } 8219} 8220~~~ 8221 8222Example response: 8223 8224~~~ 8225{ 8226 "jsonrpc": "2.0", 8227 "id": 1, 8228 "result": "nvme0n1r1" 8229} 8230~~~ 8231 8232### bdev_opal_get_info {#rpc_bdev_opal_get_info} 8233 8234This is used to get information of a given OPAL bdev. 8235 8236#### Parameters 8237 8238Name | Optional | Type | Description 8239----------------------- | -------- | ----------- | ----------- 8240bdev_name | Required | string | name of OPAL vbdev 8241password | Required | string | admin password 8242 8243#### Response 8244 8245The response is the locking info of OPAL virtual bdev. 8246 8247#### Example 8248 8249Example request: 8250 8251~~~ 8252{ 8253 "jsonrpc": "2.0", 8254 "method": "bdev_opal_get_info", 8255 "id": 1, 8256 "params": { 8257 "bdev_name": "nvme0n1r1", 8258 "password": "*****" 8259 } 8260} 8261~~~ 8262 8263Example response: 8264 8265~~~ 8266{ 8267 "jsonrpc": "2.0", 8268 "id": 1, 8269 "result": { 8270 "name": "nvme0n1r1", 8271 "range_start": 0, 8272 "range_length": 4096, 8273 "read_lock_enabled": true, 8274 "write_lock_enabled": true, 8275 "read_locked": false, 8276 "write_locked": false 8277 } 8278} 8279~~~ 8280 8281### bdev_opal_delete {#rpc_bdev_opal_delete} 8282 8283This is used to delete OPAL vbdev. 8284 8285#### Parameters 8286 8287Name | Optional | Type | Description 8288----------------------- | -------- | ----------- | ----------- 8289bdev_name | Required | string | name of OPAL vbdev 8290password | Required | string | admin password 8291 8292#### Example 8293 8294Example request: 8295 8296~~~ 8297{ 8298 "jsonrpc": "2.0", 8299 "method": "bdev_opal_delete", 8300 "id": 1, 8301 "params": { 8302 "bdev_name": "nvme0n1r1", 8303 "password": "*****" 8304 } 8305} 8306~~~ 8307 8308Example response: 8309 8310~~~ 8311{ 8312 "jsonrpc": "2.0", 8313 "id": 1, 8314 "result": true 8315} 8316~~~ 8317 8318### bdev_opal_new_user {#rpc_bdev_opal_new_user} 8319 8320This enables a new user to the specified opal bdev so that the user can lock/unlock the bdev. 8321Recalling this for the same opal bdev, only the newest user will have the privilege. 8322 8323#### Parameters 8324 8325Name | Optional | Type | Description 8326----------------------- | -------- | ----------- | ----------- 8327bdev_name | Required | string | name of OPAL vbdev 8328admin_password | Required | string | admin password 8329user_id | Required | number | user ID 8330user_password | Required | string | user password 8331 8332#### Example 8333 8334Example request: 8335 8336~~~ 8337{ 8338 "jsonrpc": "2.0", 8339 "method": "bdev_opal_new_user", 8340 "id": 1, 8341 "params": { 8342 "bdev_name": "nvme0n1r1", 8343 "admin_password": "*****", 8344 "user_id": "1", 8345 "user_password": "********" 8346 } 8347} 8348~~~ 8349 8350Example response: 8351 8352~~~ 8353{ 8354 "jsonrpc": "2.0", 8355 "id": 1, 8356 "result": true 8357} 8358~~~ 8359 8360### bdev_opal_set_lock_state {#rpc_bdev_opal_set_lock_state} 8361 8362This is used to lock/unlock specific opal bdev providing user ID and password. 8363 8364#### Parameters 8365 8366Name | Optional | Type | Description 8367----------------------- | -------- | ----------- | ----------- 8368bdev_name | Required | string | name of OPAL vbdev 8369user_id | Required | number | user ID 8370password | Required | string | user password 8371lock_state | Required | string | lock state 8372 8373#### Example 8374 8375Example request: 8376 8377~~~ 8378{ 8379 "jsonrpc": "2.0", 8380 "method": "bdev_opal_set_lock_state", 8381 "id": 1, 8382 "params": { 8383 "bdev_name": "nvme0n1r1", 8384 "user_id": "1", 8385 "user_password": "********", 8386 "lock_state": "rwlock" 8387 } 8388} 8389~~~ 8390 8391Example response: 8392 8393~~~ 8394{ 8395 "jsonrpc": "2.0", 8396 "id": 1, 8397 "result": true 8398} 8399~~~ 8400 8401## Notifications 8402 8403### notify_get_types {#rpc_notify_get_types} 8404 8405Return list of all supported notification types. 8406 8407#### Parameters 8408 8409None 8410 8411#### Response 8412 8413The response is an array of strings - supported RPC notification types. 8414 8415#### Example 8416 8417Example request: 8418 8419~~~ 8420{ 8421 "jsonrpc": "2.0", 8422 "method": "notify_get_types", 8423 "id": 1 8424} 8425~~~ 8426 8427Example response: 8428 8429~~~ 8430{ 8431 "id": 1, 8432 "result": [ 8433 "bdev_register", 8434 "bdev_unregister" 8435 ], 8436 "jsonrpc": "2.0" 8437} 8438~~~ 8439 8440### notify_get_notifications {#notify_get_notifications} 8441 8442Request notifications. Returns array of notifications that happend since the specified id (or first that is available). 8443 8444Notice: Notifications are kept in circular buffer with limited size. Older notifications might be inaccesible 8445due to being overwritten by new ones. 8446 8447#### Parameters 8448 8449Name | Optional | Type | Description 8450----------------------- | -------- | ----------- | ----------- 8451id | Optional | number | First Event ID to fetch (default: first available). 8452max | Optional | number | Maximum number of event to return (default: no limit). 8453 8454#### Response 8455 8456Response is an array of event objects. 8457 8458Name | Optional | Type | Description 8459----------------------- | -------- | ----------- | ----------- 8460id | Optional | number | Event ID. 8461type | Optional | number | Type of the event. 8462ctx | Optional | string | Event context. 8463 8464#### Example 8465 8466Example request: 8467 8468~~~ 8469{ 8470 "id": 1, 8471 "jsonrpc": "2.0", 8472 "method": "notify_get_notifications", 8473 "params": { 8474 "id": 1, 8475 "max": 10 8476 } 8477} 8478 8479~~~ 8480 8481Example response: 8482 8483~~~ 8484{ 8485 "jsonrpc": "2.0", 8486 "id": 1, 8487 "result": [ 8488 { 8489 "ctx": "Malloc0", 8490 "type": "bdev_register", 8491 "id": 1 8492 }, 8493 { 8494 "ctx": "Malloc2", 8495 "type": "bdev_register", 8496 "id": 2 8497 } 8498 ] 8499} 8500~~~ 8501 8502## Linux Network Block Device (NBD) {#jsonrpc_components_nbd} 8503 8504SPDK supports exporting bdevs through Linux nbd. These devices then appear as standard Linux kernel block devices 8505and can be accessed using standard utilities like fdisk. 8506 8507In order to export a device over nbd, first make sure the Linux kernel nbd driver is loaded by running 'modprobe nbd'. 8508 8509### nbd_start_disk {#rpc_nbd_start_disk} 8510 8511Start to export one SPDK bdev as NBD disk 8512 8513#### Parameters 8514 8515Name | Optional | Type | Description 8516----------------------- | -------- | ----------- | ----------- 8517bdev_name | Required | string | Bdev name to export 8518nbd_device | Optional | string | NBD device name to assign 8519 8520#### Response 8521 8522Path of exported NBD disk 8523 8524#### Example 8525 8526Example request: 8527 8528~~~ 8529{ 8530 "params": { 8531 "nbd_device": "/dev/nbd1", 8532 "bdev_name": "Malloc1" 8533 }, 8534 "jsonrpc": "2.0", 8535 "method": "nbd_start_disk", 8536 "id": 1 8537} 8538~~~ 8539 8540Example response: 8541 8542~~~ 8543{ 8544 "jsonrpc": "2.0", 8545 "id": 1, 8546 "result": "/dev/nbd1" 8547} 8548~~~ 8549 8550### nbd_stop_disk {#rpc_nbd_stop_disk} 8551 8552Stop one NBD disk which is based on SPDK bdev. 8553 8554#### Parameters 8555 8556Name | Optional | Type | Description 8557----------------------- | -------- | ----------- | ----------- 8558nbd_device | Required | string | NBD device name to stop 8559 8560#### Example 8561 8562Example request: 8563 8564~~~ 8565{ 8566 "params": { 8567 "nbd_device": "/dev/nbd1", 8568 }, 8569 "jsonrpc": "2.0", 8570 "method": "nbd_stop_disk", 8571 "id": 1 8572} 8573~~~ 8574 8575Example response: 8576 8577~~~ 8578{ 8579 "jsonrpc": "2.0", 8580 "id": 1, 8581 "result": "true" 8582} 8583~~~ 8584 8585### nbd_get_disks {#rpc_nbd_get_disks} 8586 8587Display all or specified NBD device list 8588 8589#### Parameters 8590 8591Name | Optional | Type | Description 8592----------------------- | -------- | ----------- | ----------- 8593nbd_device | Optional | string | NBD device name to display 8594 8595#### Response 8596 8597The response is an array of exported NBD devices and their corresponding SPDK bdev. 8598 8599#### Example 8600 8601Example request: 8602 8603~~~ 8604{ 8605 "jsonrpc": "2.0", 8606 "method": "nbd_get_disks", 8607 "id": 1 8608} 8609~~~ 8610 8611Example response: 8612 8613~~~ 8614{ 8615 "jsonrpc": "2.0", 8616 "id": 1, 8617 "result": [ 8618 { 8619 "bdev_name": "Malloc0", 8620 "nbd_device": "/dev/nbd0" 8621 }, 8622 { 8623 "bdev_name": "Malloc1", 8624 "nbd_device": "/dev/nbd1" 8625 } 8626 ] 8627} 8628~~~ 8629 8630## Blobfs {#jsonrpc_components_blobfs} 8631 8632### blobfs_detect {#rpc_blobfs_detect} 8633 8634Detect whether a blobfs exists on bdev. 8635 8636#### Parameters 8637 8638Name | Optional | Type | Description 8639----------------------- | -------- | ----------- | ----------- 8640bdev_name | Required | string | Block device name to detect blobfs 8641 8642#### Response 8643 8644True if a blobfs exists on the bdev; False otherwise. 8645 8646#### Example 8647 8648Example request: 8649 8650~~~ 8651{ 8652 "jsonrpc": "2.0", 8653 "id": 1, 8654 "method": "blobfs_detect", 8655 "params": { 8656 "bdev_name": "Malloc0" 8657 } 8658} 8659~~~ 8660 8661Example response: 8662 8663~~~ 8664{ 8665 "jsonrpc": "2.0", 8666 "id": 1, 8667 "result": "true" 8668} 8669~~~ 8670 8671### blobfs_create {#rpc_blobfs_create} 8672 8673Build blobfs on bdev. 8674 8675#### Parameters 8676 8677Name | Optional | Type | Description 8678----------------------- | -------- | ----------- | ----------- 8679bdev_name | Required | string | Block device name to create blobfs 8680cluster_sz | Optional | number | Size of cluster in bytes. Must be multiple of 4KiB page size, default and minimal value is 1M. 8681 8682#### Example 8683 8684Example request: 8685 8686~~~ 8687{ 8688 "jsonrpc": "2.0", 8689 "id": 1, 8690 "method": "blobfs_create", 8691 "params": { 8692 "bdev_name": "Malloc0", 8693 "cluster_sz": 1M 8694 } 8695} 8696~~~ 8697 8698Example response: 8699 8700~~~ 8701{ 8702 "jsonrpc": "2.0", 8703 "id": 1, 8704 "result": "true" 8705} 8706~~~ 8707 8708### blobfs_mount {#rpc_blobfs_mount} 8709 8710Mount a blobfs on bdev to one host path through FUSE 8711 8712#### Parameters 8713 8714Name | Optional | Type | Description 8715----------------------- | -------- | ----------- | ----------- 8716bdev_name | Required | string | Block device name where the blobfs is 8717mountpoint | Required | string | Mountpoint path in host to mount blobfs 8718 8719#### Example 8720 8721Example request: 8722 8723~~~ 8724{ 8725 "jsonrpc": "2.0", 8726 "id": 1, 8727 "method": ""blobfs_mount"", 8728 "params": { 8729 "bdev_name": "Malloc0", 8730 "mountpoint": "/mnt/" 8731 } 8732} 8733~~~ 8734 8735Example response: 8736 8737~~~ 8738{ 8739 "jsonrpc": "2.0", 8740 "id": 1, 8741 "result": "true" 8742} 8743~~~ 8744 8745### blobfs_set_cache_size {#rpc_blobfs_set_cache_size} 8746 8747Set cache pool size for blobfs filesystems. This RPC is only permitted when the cache pool is not already initialized. 8748 8749The cache pool is initialized when the first blobfs filesystem is initialized or loaded. It is freed when the all 8750initialized or loaded filesystems are unloaded. 8751 8752#### Parameters 8753 8754Name | Optional | Type | Description 8755----------------------- | -------- | ----------- | ----------- 8756size_in_mb | Required | number | Cache size in megabytes 8757 8758#### Response 8759 8760True if cache size is set successfully; False if failed to set. 8761 8762#### Example 8763 8764Example request: 8765 8766~~~ 8767{ 8768 "jsonrpc": "2.0", 8769 "id": 1, 8770 "method": "blobfs_set_cache_size", 8771 "params": { 8772 "size_in_mb": 512, 8773 } 8774} 8775~~~ 8776 8777Example response: 8778 8779~~~ 8780{ 8781 "jsonrpc": "2.0", 8782 "id": 1, 8783 "result": true 8784} 8785~~~ 8786 8787## Socket layer {#jsonrpc_components_sock} 8788 8789### sock_impl_get_options {#rpc_sock_impl_get_options} 8790 8791Get parameters for the socket layer implementation. 8792 8793#### Parameters 8794 8795Name | Optional | Type | Description 8796----------------------- | -------- | ----------- | ----------- 8797impl_name | Required | string | Name of socket implementation, e.g. posix 8798 8799#### Response 8800 8801Response is an object with current socket layer options for requested implementation. 8802 8803#### Example 8804 8805Example request: 8806 8807~~~ 8808{ 8809 "jsonrpc": "2.0", 8810 "method": "sock_impl_get_options", 8811 "id": 1, 8812 "params": { 8813 "impl_name": "posix" 8814 } 8815} 8816~~~ 8817 8818Example response: 8819 8820~~~ 8821{ 8822 "jsonrpc": "2.0", 8823 "id": 1, 8824 "result": { 8825 "recv_buf_size": 2097152, 8826 "send_buf_size": 2097152, 8827 "enable_recv_pipe": true, 8828 "enable_quickack": true, 8829 "enable_placement_id": 0, 8830 "enable_zerocopy_send_server": true, 8831 "enable_zerocopy_send_client": false 8832 } 8833} 8834~~~ 8835 8836### sock_impl_set_options {#rpc_sock_impl_set_options} 8837 8838Set parameters for the socket layer implementation. 8839 8840#### Parameters 8841 8842Name | Optional | Type | Description 8843--------------------------- | -------- | ----------- | ----------- 8844impl_name | Required | string | Name of socket implementation, e.g. posix 8845recv_buf_size | Optional | number | Size of socket receive buffer in bytes 8846send_buf_size | Optional | number | Size of socket send buffer in bytes 8847enable_recv_pipe | Optional | boolean | Enable or disable receive pipe 8848enable_quick_ack | Optional | boolean | Enable or disable quick ACK 8849enable_placement_id | Optional | number | Enable or disable placement_id. 0:disable,1:incoming_napi,2:incoming_cpu 8850enable_zerocopy_send_server | Optional | boolean | Enable or disable zero copy on send for server sockets 8851enable_zerocopy_send_client | Optional | boolean | Enable or disable zero copy on send for client sockets 8852 8853#### Response 8854 8855True if socket layer options were set successfully. 8856 8857#### Example 8858 8859Example request: 8860 8861~~~ 8862{ 8863 "jsonrpc": "2.0", 8864 "method": "sock_impl_set_options", 8865 "id": 1, 8866 "params": { 8867 "impl_name": "posix", 8868 "recv_buf_size": 2097152, 8869 "send_buf_size": 2097152, 8870 "enable_recv_pipe": false, 8871 "enable_quick_ack": false, 8872 "enable_placement_id": 0, 8873 "enable_zerocopy_send_server": true, 8874 "enable_zerocopy_send_client": false 8875 } 8876} 8877~~~ 8878 8879Example response: 8880 8881~~~ 8882{ 8883 "jsonrpc": "2.0", 8884 "id": 1, 8885 "result": true 8886} 8887~~~ 8888 8889### sock_set_default_impl {#rpc_sock_set_default_impl} 8890 8891Set the default sock implementation. 8892 8893#### Parameters 8894 8895Name | Optional | Type | Description 8896----------------------- | -------- | ----------- | ----------- 8897impl_name | Required | string | Name of socket implementation, e.g. posix 8898 8899#### Response 8900 8901True if the default socket layer configuration was set successfully. 8902 8903#### Example 8904 8905Example request: 8906 8907~~~ 8908{ 8909 "jsonrpc": "2.0", 8910 "method": "sock_set_default_impl", 8911 "id": 1, 8912 "params": { 8913 "impl_name": "posix" 8914 } 8915} 8916~~~ 8917 8918Example response: 8919 8920~~~ 8921{ 8922 "jsonrpc": "2.0", 8923 "id": 1, 8924 "result": true 8925} 8926~~~ 8927 8928## Miscellaneous RPC commands 8929 8930### bdev_nvme_send_cmd {#rpc_bdev_nvme_send_cmd} 8931 8932Send NVMe command directly to NVMe controller or namespace. Parameters and responses encoded by base64 urlsafe need further processing. 8933 8934Notice: bdev_nvme_send_cmd requires user to guarentee the correctness of NVMe command itself, and also optional parameters. 8935Illegal command contents or mismatching buffer size may result in unpredictable behavior. 8936 8937#### Parameters 8938 8939Name | Optional | Type | Description 8940----------------------- | -------- | ----------- | ----------- 8941name | Required | string | Name of the operating NVMe controller 8942cmd_type | Required | string | Type of nvme cmd. Valid values are: admin, io 8943data_direction | Required | string | Direction of data transfer. Valid values are: c2h, h2c 8944cmdbuf | Required | string | NVMe command encoded by base64 urlsafe 8945data | Optional | string | Data transferring to controller from host, encoded by base64 urlsafe 8946metadata | Optional | string | Metadata transferring to controller from host, encoded by base64 urlsafe 8947data_len | Optional | number | Data length required to transfer from controller to host 8948metadata_len | Optional | number | Metadata length required to transfer from controller to host 8949timeout_ms | Optional | number | Command execution timeout value, in milliseconds 8950 8951#### Response 8952 8953Name | Type | Description 8954----------------------- | ----------- | ----------- 8955cpl | string | NVMe completion queue entry, encoded by base64 urlsafe 8956data | string | Data transferred from controller to host, encoded by base64 urlsafe 8957metadata | string | Metadata transferred from controller to host, encoded by base64 urlsafe 8958 8959#### Example 8960 8961Example request: 8962 8963~~~ 8964{ 8965 "jsonrpc": "2.0", 8966 "method": "bdev_nvme_send_cmd", 8967 "id": 1, 8968 "params": { 8969 "name": "Nvme0", 8970 "cmd_type": "admin" 8971 "data_direction": "c2h", 8972 "cmdbuf": "BgAAAAEAAAAAAAAAAAAAAAAAAAAAAAAAsGUs9P5_AAAAAAAAABAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA==", 8973 "data_len": 60, 8974 } 8975} 8976~~~ 8977 8978Example response: 8979 8980~~~ 8981{ 8982 "jsonrpc": "2.0", 8983 "id": 1, 8984 "result": { 8985 "cpl": "AAAAAAAAAAARAAAAWrmwABAA==", 8986 "data": "sIjg6AAAAACwiODoAAAAALCI4OgAAAAAAAYAAREAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA" 8987 } 8988 8989} 8990~~~ 8991 8992### enable_vmd {#rpc_enable_vmd} 8993 8994Enable VMD enumeration. 8995 8996#### Parameters 8997 8998This method has no parameters. 8999 9000#### Response 9001 9002Completion status of enumeration is returned as a boolean. 9003 9004### Example 9005 9006Example request: 9007 9008~~~ 9009{ 9010 "jsonrpc": "2.0", 9011 "method": "enable_vmd", 9012 "id": 1 9013} 9014~~~ 9015 9016Example response: 9017 9018~~~ 9019{ 9020 "jsonrpc": "2.0", 9021 "id": 1, 9022 "result": true 9023} 9024~~~ 9025 9026### spdk_get_version {#rpc_spdk_get_version} 9027 9028Get the version info of the running SPDK application. 9029 9030#### Parameters 9031 9032This method has no parameters. 9033 9034#### Response 9035 9036The response is the version number including major version number, minor version number, patch level number and suffix string. 9037 9038#### Example 9039 9040Example request: 9041~~ 9042{ 9043 "jsonrpc": "2.0", 9044 "id": 1, 9045 "method": "spdk_get_version" 9046} 9047~~ 9048 9049Example response: 9050~~ 9051{ 9052 "jsonrpc": "2.0", 9053 "id": 1, 9054 "result": { 9055 "version": "19.04-pre", 9056 "fields" : { 9057 "major": 19, 9058 "minor": 4, 9059 "patch": 0, 9060 "suffix": "-pre" 9061 } 9062 } 9063} 9064~~ 9065