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