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