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