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