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