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