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. 3887uuid | Optional | string | UUID of new bdev 3888 3889#### Result 3890 3891Name of newly created bdev. 3892 3893#### Example 3894 3895Example request: 3896 3897~~~json 3898{ 3899 "params": { 3900 "block_size": 4096, 3901 "name": "Aio0", 3902 "filename": "/tmp/aio_bdev_file" 3903 }, 3904 "jsonrpc": "2.0", 3905 "method": "bdev_aio_create", 3906 "id": 1 3907} 3908~~~ 3909 3910Example response: 3911 3912~~~json 3913{ 3914 "jsonrpc": "2.0", 3915 "id": 1, 3916 "result": "Aio0" 3917} 3918~~~ 3919 3920### bdev_aio_rescan {#rpc_bdev_aio_rescan} 3921 3922Rescan the size of @ref bdev_config_aio. 3923 3924#### Parameters 3925 3926Name | Optional | Type | Description 3927----------------------- | -------- | ----------- | ----------- 3928name | Required | string | Bdev name 3929 3930#### Example 3931 3932Example request: 3933 3934~~~json 3935{ 3936 "params": { 3937 "name": "Aio0" 3938 }, 3939 "jsonrpc": "2.0", 3940 "method": "bdev_aio_rescan", 3941 "id": 1 3942} 3943~~~ 3944 3945Example response: 3946 3947~~~json 3948{ 3949 "jsonrpc": "2.0", 3950 "id": 1, 3951 "result": true 3952} 3953~~~ 3954 3955### bdev_aio_delete {#rpc_bdev_aio_delete} 3956 3957Delete @ref bdev_config_aio. 3958 3959#### Parameters 3960 3961Name | Optional | Type | Description 3962----------------------- | -------- | ----------- | ----------- 3963name | Required | string | Bdev name 3964 3965#### Example 3966 3967Example request: 3968 3969~~~json 3970{ 3971 "params": { 3972 "name": "Aio0" 3973 }, 3974 "jsonrpc": "2.0", 3975 "method": "bdev_aio_delete", 3976 "id": 1 3977} 3978~~~ 3979 3980Example response: 3981 3982~~~json 3983{ 3984 "jsonrpc": "2.0", 3985 "id": 1, 3986 "result": true 3987} 3988~~~ 3989 3990### bdev_nvme_set_options {#rpc_bdev_nvme_set_options} 3991 3992Set global parameters for all bdev NVMe. This RPC may only be called before SPDK subsystems have been initialized 3993or any bdev NVMe has been created. 3994 3995Parameters, ctrlr_loss_timeout_sec, reconnect_delay_sec, and fast_io_fail_timeout_sec, are for I/O error resiliency. 3996They can be overridden if they are given by the RPC bdev_nvme_attach_controller. 3997 3998#### Parameters 3999 4000Name | Optional | Type | Description 4001-------------------------- | -------- | ----------- | ----------- 4002action_on_timeout | Optional | string | Action to take on command time out: none, reset or abort 4003timeout_us | Optional | number | Timeout for each command, in microseconds. If 0, don't track timeouts 4004timeout_admin_us | Optional | number | Timeout for each admin command, in microseconds. If 0, treat same as io timeouts ('timeout_us') 4005keep_alive_timeout_ms | Optional | number | Keep alive timeout period in milliseconds, default is 10s 4006arbitration_burst | Optional | number | The value is expressed as a power of two, a value of 111b indicates no limit 4007low_priority_weight | Optional | number | The maximum number of commands that the controller may launch at one time from a low priority queue 4008medium_priority_weight | Optional | number | The maximum number of commands that the controller may launch at one time from a medium priority queue 4009high_priority_weight | Optional | number | The maximum number of commands that the controller may launch at one time from a high priority queue 4010nvme_adminq_poll_period_us | Optional | number | How often the admin queue is polled for asynchronous events in microseconds 4011nvme_ioq_poll_period_us | Optional | number | How often I/O queues are polled for completions, in microseconds. Default: 0 (as fast as possible). 4012io_queue_requests | Optional | number | The number of requests allocated for each NVMe I/O queue. Default: 512. 4013delay_cmd_submit | Optional | boolean | Enable delaying NVMe command submission to allow batching of multiple commands. Default: `true`. 4014transport_retry_count | Optional | number | The number of attempts per I/O in the transport layer before an I/O fails. 4015bdev_retry_count | Optional | number | The number of attempts per I/O in the bdev layer before an I/O fails. -1 means infinite retries. 4016transport_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. 4017ctrlr_loss_timeout_sec | Optional | number | Time to wait until ctrlr is reconnected before deleting ctrlr. -1 means infinite reconnects. 0 means no reconnect. 4018reconnect_delay_sec | Optional | number | Time to delay a reconnect trial. 0 means no reconnect. 4019fast_io_fail_timeout_sec | Optional | number | Time to wait until ctrlr is reconnected before failing I/O to ctrlr. 0 means no such timeout. 4020disable_auto_failback | Optional | boolean | Disable automatic failback. The RPC bdev_nvme_set_preferred_path can be used to do manual failback. 4021generate_uuids | Optional | boolean | Enable generation of UUIDs for NVMe bdevs that do not provide this value themselves. 4022transport_tos | Optional | number | IPv4 Type of Service value. Only applicable for RDMA transport. Default: 0 (no TOS is applied). 4023nvme_error_stat | Optional | boolean | Enable collecting NVMe error counts. 4024rdma_srq_size | Optional | number | Set the size of a shared rdma receive queue. Default: 0 (disabled). 4025io_path_stat | Optional | boolean | Enable collecting I/O stat of each nvme bdev io path. Default: `false`. 4026allow_accel_sequence | Optional | boolean | Allow NVMe bdevs to advertise support for accel sequences if the controller also supports them. Default: `false`. 4027rdma_max_cq_size | Optional | number | Set the maximum size of a rdma completion queue. Default: 0 (unlimited) 4028rdma_cm_event_timeout_ms | Optional | number | Time to wait for RDMA CM events. Default: 0 (0 means using default value of driver). 4029dhchap_digests | Optional | list | List of allowed DH-HMAC-CHAP digests. 4030dhchap_dhgroups | Optional | list | List of allowed DH-HMAC-CHAP DH groups. 4031 4032#### Example 4033 4034Example request: 4035 4036~~~json 4037request: 4038{ 4039 "params": { 4040 "transport_retry_count": 5, 4041 "arbitration_burst": 3, 4042 "low_priority_weight": 8, 4043 "medium_priority_weight":8, 4044 "high_priority_weight": 8, 4045 "nvme_adminq_poll_period_us": 2000, 4046 "timeout_us": 10000000, 4047 "timeout_admin_us": 20000000, 4048 "keep_alive_timeout_ms": 600000, 4049 "action_on_timeout": "reset", 4050 "io_queue_requests" : 2048, 4051 "delay_cmd_submit": true 4052 "dhchap_digests": [ 4053 "sha384", 4054 "sha512" 4055 ], 4056 "dhchap_dhgroups": [ 4057 "ffdhe6144", 4058 "ffdhe8192" 4059 ] 4060 }, 4061 "jsonrpc": "2.0", 4062 "method": "bdev_nvme_set_options", 4063 "id": 1 4064} 4065~~~ 4066 4067Example response: 4068 4069~~~json 4070{ 4071 "jsonrpc": "2.0", 4072 "id": 1, 4073 "result": true 4074} 4075~~~ 4076 4077### bdev_nvme_set_hotplug {#rpc_bdev_nvme_set_hotplug} 4078 4079Change settings of the NVMe hotplug feature. If enabled, PCIe NVMe bdevs will be automatically discovered on insertion 4080and deleted on removal. 4081 4082#### Parameters 4083 4084Name | Optional | Type | Description 4085----------------------- | -------- | ----------- | ----------- 4086enable | Required | string | True to enable, false to disable 4087period_us | Optional | number | How often to poll for hot-insert and hot-remove events. Values: 0 - reset/use default or 1 to 10000000. 4088 4089#### Example 4090 4091Example request: 4092 4093~~~json 4094request: 4095{ 4096 "params": { 4097 "enable": true, 4098 "period_us": 2000 4099 }, 4100 "jsonrpc": "2.0", 4101 "method": "bdev_nvme_set_hotplug", 4102 "id": 1 4103} 4104~~~ 4105 4106Example response: 4107 4108~~~json 4109{ 4110 "jsonrpc": "2.0", 4111 "id": 1, 4112 "result": true 4113} 4114~~~ 4115 4116### bdev_nvme_attach_controller {#rpc_bdev_nvme_attach_controller} 4117 4118Construct @ref bdev_config_nvme. This RPC can also be used to add additional paths to an existing controller to enable 4119multipathing. This is done by specifying the `name` parameter as an existing controller. When adding an additional 4120path, the hostnqn, hostsvcid, hostaddr, prchk_reftag, and prchk_guard_arguments must not be specified and are assumed 4121to have the same value as the existing path. 4122 4123The parameters, `ctrlr_loss_timeout_sec`, `reconnect_delay_sec`, and `fast_io_fail_timeout_sec`, are mutually dependent. 4124If `reconnect_delay_sec` is non-zero, `ctrlr_loss_timeout_sec` has to be -1 or not less than `reconnect_delay_sec`. 4125If `reconnect_delay_sec` is zero, `ctrlr_loss_timeout_sec` has to be zero. 4126If `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. 4127 4128#### Result 4129 4130Array of names of newly created bdevs. 4131 4132#### Parameters 4133 4134Name | Optional | Type | Description 4135-------------------------- | -------- | ----------- | ----------- 4136name | Required | string | Name of the NVMe controller, prefix for each bdev name 4137trtype | Required | string | NVMe-oF target trtype: rdma or pcie 4138traddr | Required | string | NVMe-oF target address: ip or BDF 4139adrfam | Optional | string | NVMe-oF target adrfam: ipv4, ipv6, ib, fc, intra_host 4140trsvcid | Optional | string | NVMe-oF target trsvcid: port number 4141priority | Optional | string | Transport connection priority. Supported by TCP transport with POSIX sock module (see socket(7) man page). 4142subnqn | Optional | string | NVMe-oF target subnqn 4143hostnqn | Optional | string | NVMe-oF target hostnqn 4144hostaddr | Optional | string | NVMe-oF host address: ip address 4145hostsvcid | Optional | string | NVMe-oF host trsvcid: port number 4146prchk_reftag | Optional | bool | Enable checking of PI reference tag for I/O processing 4147prchk_guard | Optional | bool | Enable checking of PI guard for I/O processing 4148hdgst | Optional | bool | Enable TCP header digest 4149ddgst | Optional | bool | Enable TCP data digest 4150fabrics_connect_timeout_us | Optional | number | Timeout for fabrics connect (in microseconds) 4151multipath | Optional | string | Multipathing behavior: disable, failover, multipath. Default is failover. 4152num_io_queues | Optional | number | The number of IO queues to request during initialization. Range: (0, UINT16_MAX + 1], Default is 1024. 4153ctrlr_loss_timeout_sec | Optional | number | Time to wait until ctrlr is reconnected before deleting ctrlr. -1 means infinite reconnects. 0 means no reconnect. 4154reconnect_delay_sec | Optional | number | Time to delay a reconnect trial. 0 means no reconnect. 4155fast_io_fail_timeout_sec | Optional | number | Time to wait until ctrlr is reconnected before failing I/O to ctrlr. 0 means no such timeout. 4156psk | Optional | string | Name of the pre-shared key to be used for TLS (Enables SSL socket implementation for TCP) 4157max_bdevs | Optional | number | The size of the name array for newly created bdevs. Default is 128. 4158dhchap_key | Optional | string | DH-HMAC-CHAP key name. 4159dhchap_ctrlr_key | Optional | string | DH-HMAC-CHAP controller key name. 4160allow_unrecognized_csi | Optional | bool | Allow attaching namespaces with unrecognized command set identifiers. These will only support NVMe passthrough. 4161 4162#### Example 4163 4164Example request: 4165 4166~~~json 4167{ 4168 "params": { 4169 "trtype": "pcie", 4170 "name": "Nvme0", 4171 "traddr": "0000:0a:00.0" 4172 }, 4173 "jsonrpc": "2.0", 4174 "method": "bdev_nvme_attach_controller", 4175 "id": 1 4176} 4177~~~ 4178 4179Example response: 4180 4181~~~json 4182{ 4183 "jsonrpc": "2.0", 4184 "id": 1, 4185 "result": [ 4186 "Nvme0n1" 4187 ] 4188} 4189~~~ 4190 4191### bdev_nvme_get_controllers {#rpc_bdev_nvme_get_controllers} 4192 4193Get information about NVMe controllers. 4194 4195#### Parameters 4196 4197The user may specify no parameters in order to list all NVMe controllers, or one NVMe controller may be 4198specified by name. 4199 4200Name | Optional | Type | Description 4201----------------------- | -------- | ----------- | ----------- 4202name | Optional | string | NVMe controller name 4203 4204#### Response 4205 4206The response is an array of objects containing information about the requested NVMe controllers. 4207 4208#### Example 4209 4210Example request: 4211 4212~~~json 4213{ 4214 "jsonrpc": "2.0", 4215 "id": 1, 4216 "method": "bdev_nvme_get_controllers", 4217 "params": { 4218 "name": "Nvme0" 4219 } 4220} 4221~~~ 4222 4223Example response: 4224 4225~~~json 4226{ 4227 "jsonrpc": "2.0", 4228 "id": 1, 4229 "result": [ 4230 { 4231 "name": "Nvme0", 4232 "trid": { 4233 "trtype": "PCIe", 4234 "traddr": "0000:05:00.0" 4235 }, 4236 "cntlid": 0 4237 } 4238 ] 4239} 4240~~~ 4241 4242### bdev_nvme_detach_controller {#rpc_bdev_nvme_detach_controller} 4243 4244Detach NVMe controller and delete any associated bdevs. Optionally, 4245If all of the transport ID options are specified, only remove that 4246transport path from the specified controller. If that is the only 4247available path for the controller, this will also result in the 4248controller being detached and the associated bdevs being deleted. 4249 4250returns true if the controller and bdevs were successfully destroyed 4251or the address was properly removed, false otherwise. 4252 4253#### Parameters 4254 4255Name | Optional | Type | Description 4256----------------------- | -------- | ----------- | ----------- 4257name | Required | string | Controller name 4258trtype | Optional | string | NVMe-oF target trtype: rdma or tcp 4259traddr | Optional | string | NVMe-oF target address: ip or BDF 4260adrfam | Optional | string | NVMe-oF target adrfam: ipv4, ipv6, ib, fc, intra_host 4261trsvcid | Optional | string | NVMe-oF target trsvcid: port number 4262subnqn | Optional | string | NVMe-oF target subnqn 4263hostaddr | Optional | string | NVMe-oF host address: ip 4264hostsvcid | Optional | string | NVMe-oF host svcid: port number 4265 4266#### Example 4267 4268Example requests: 4269 4270~~~json 4271{ 4272 "params": { 4273 "name": "Nvme0" 4274 }, 4275 "jsonrpc": "2.0", 4276 "method": "bdev_nvme_detach_controller", 4277 "id": 1 4278} 4279~~~ 4280 4281Example response: 4282 4283~~~json 4284{ 4285 "jsonrpc": "2.0", 4286 "id": 1, 4287 "result": true 4288} 4289~~~ 4290 4291### bdev_nvme_reset_controller {#rpc_bdev_nvme_reset_controller} 4292 4293For non NVMe multipath, reset an NVMe controller whose name is given by the `name` parameter. 4294 4295For NVMe multipath, an NVMe bdev controller is created and it aggregates multiple NVMe controllers. 4296The `name` parameter is an NVMe bdev controller name and the `cntlid` parameter is used to identify 4297an NVMe controller in the NVMe bdev controller. Reset only one NVMe-oF controller if the `cntlid` 4298parameter is specified, or all NVMe-oF controllers in an NVMe bdev controller if it is omitted. 4299 4300Returns true if the controller reset was successful, false otherwise. 4301 4302#### Parameters 4303 4304Name | Optional | Type | Description 4305----------------------- | -------- | ----------- | ----------- 4306name | Required | string | NVMe controller name (or NVMe bdev controller name for multipath) 4307cntlid | Optional | number | NVMe controller ID (used as NVMe controller name for multipath) 4308 4309#### Example 4310 4311Example request: 4312 4313~~~json 4314{ 4315 "jsonrpc": "2.0", 4316 "id": 1, 4317 "method": "bdev_nvme_reset_controller", 4318 "params": { 4319 "name": "Nvme0" 4320 } 4321} 4322~~~ 4323 4324Example response: 4325 4326~~~json 4327{ 4328 "jsonrpc": "2.0", 4329 "id": 1, 4330 "result": true 4331} 4332~~~ 4333 4334### bdev_nvme_enable_controller {#rpc_bdev_nvme_enable_controller} 4335 4336For non NVMe multipath, enable an NVMe controller whose name is given by the `name` parameter. 4337 4338For NVMe multipath, an NVMe bdev controller is created and it aggregates multiple NVMe controllers. 4339The `name` parameter is an NVMe bdev controller name and the `cntlid` parameter is used to identify 4340an NVMe controller in the NVMe bdev controller. Enable only one NVMe-oF controller if the `cntlid` 4341parameter is specified, or all NVMe-oF controllers in an NVMe bdev controller if it is omitted. 4342 4343Returns true if the controller enablement was successful or a controller was already enabled, false otherwise. 4344 4345#### Parameters 4346 4347Name | Optional | Type | Description 4348----------------------- | -------- | ----------- | ----------- 4349name | Required | string | NVMe controller name (or NVMe bdev controller name for multipath) 4350cntlid | Optional | number | NVMe controller ID (used as NVMe controller name for multipath) 4351 4352#### Example 4353 4354Example request: 4355 4356~~~json 4357{ 4358 "jsonrpc": "2.0", 4359 "id": 1, 4360 "method": "bdev_nvme_enable_controller", 4361 "params": { 4362 "name": "Nvme0" 4363 } 4364} 4365~~~ 4366 4367Example response: 4368 4369~~~json 4370{ 4371 "jsonrpc": "2.0", 4372 "id": 1, 4373 "result": true 4374} 4375~~~ 4376 4377### bdev_nvme_disable_controller {#rpc_bdev_nvme_disable_controller} 4378 4379For non NVMe multipath, disable an NVMe controller whose name is given by the `name` parameter. 4380 4381For NVMe multipath, an NVMe bdev controller is created and it aggregates multiple NVMe controllers. 4382The `name` parameter is an NVMe bdev controller name and the `cntlid` parameter is used to identify 4383an NVMe controller in the NVMe bdev controller. Disable only one NVMe-oF controller if the `cntlid` 4384parameter is specified, or all NVMe-oF controllers in an NVMe bdev controller if it is omitted. 4385 4386Returns true if the controller disablement was successful or a controller was already disabled, false otherwise. 4387 4388#### Parameters 4389 4390Name | Optional | Type | Description 4391----------------------- | -------- | ----------- | ----------- 4392name | Required | string | NVMe controller name (or NVMe bdev controller name for multipath) 4393cntlid | Optional | number | NVMe controller ID (used as NVMe controller name for multipath) 4394 4395#### Example 4396 4397Example request: 4398 4399~~~json 4400{ 4401 "jsonrpc": "2.0", 4402 "id": 1, 4403 "method": "bdev_nvme_disable_controller", 4404 "params": { 4405 "name": "Nvme0" 4406 } 4407} 4408~~~ 4409 4410Example response: 4411 4412~~~json 4413{ 4414 "jsonrpc": "2.0", 4415 "id": 1, 4416 "result": true 4417} 4418~~~ 4419 4420### bdev_nvme_start_discovery {#rpc_bdev_nvme_start_discovery} 4421 4422Start a discovery service for the discovery subsystem of the specified transport ID. 4423 4424The discovery service will read the discovery log page for the specified 4425discovery subsystem, and automatically attach to any subsystems found in the 4426log page. When determining a controller name to use when attaching, it will use 4427the 'name' parameter as a prefix, followed by a unique integer for that discovery 4428service. If the discovery service identifies a subsystem that has been previously 4429attached but is listed with a different path, it will use the same controller name 4430as the previous entry, and connect as a multipath. 4431 4432When the discovery service sees that a subsystem entry has been removed 4433from the log page, it will automatically detach from that controller as well. 4434 4435The 'name' is also used to later stop the discovery service. 4436 4437#### Parameters 4438 4439Name | Optional | Type | Description 4440-------------------------- | -------- | ----------- | ----------- 4441name | Required | string | Prefix for NVMe controllers 4442trtype | Required | string | NVMe-oF target trtype: rdma or tcp 4443traddr | Required | string | NVMe-oF target address: ip 4444adrfam | Optional | string | NVMe-oF target adrfam: ipv4, ipv6 4445trsvcid | Optional | string | NVMe-oF target trsvcid: port number 4446hostnqn | Optional | string | NVMe-oF target hostnqn 4447wait_for_attach | Optional | bool | Wait to complete until all discovered NVM subsystems are attached 4448attach_timeout_ms | Optional | number | Time to wait until the discovery and all discovered NVM subsystems are attached 4449ctrlr_loss_timeout_sec | Optional | number | Time to wait until ctrlr is reconnected before deleting ctrlr. -1 means infinite reconnects. 0 means no reconnect. 4450reconnect_delay_sec | Optional | number | Time to delay a reconnect trial. 0 means no reconnect. 4451fast_io_fail_timeout_sec | Optional | number | Time to wait until ctrlr is reconnected before failing I/O to ctrlr. 0 means no such timeout. 4452 4453#### Example 4454 4455Example request: 4456 4457~~~json 4458{ 4459 "jsonrpc": "2.0", 4460 "method": "bdev_nvme_start_discovery", 4461 "id": 1, 4462 "params": { 4463 "name": "nvme_auto", 4464 "trtype": "tcp", 4465 "traddr": "127.0.0.1", 4466 "hostnqn": "nqn.2021-12.io.spdk:host1", 4467 "adrfam": "ipv4", 4468 "trsvcid": "4420" 4469 } 4470} 4471~~~ 4472 4473Example response: 4474 4475~~~json 4476{ 4477 "jsonrpc": "2.0", 4478 "id": 1, 4479 "result": true 4480} 4481~~~ 4482 4483### bdev_nvme_stop_discovery {#rpc_bdev_nvme_stop_discovery} 4484 4485Stop a discovery service. This includes detaching any controllers that were 4486discovered via the service that is being stopped. 4487 4488#### Parameters 4489 4490Name | Optional | Type | Description 4491-------------------------- | -------- | ----------- | ----------- 4492name | Required | string | Name of service to stop 4493 4494#### Example 4495 4496Example request: 4497 4498~~~json 4499{ 4500 "jsonrpc": "2.0", 4501 "method": "bdev_nvme_stop_discovery", 4502 "id": 1, 4503 "params": { 4504 "name": "nvme_auto" 4505 } 4506} 4507~~~ 4508 4509Example response: 4510 4511~~~json 4512{ 4513 "jsonrpc": "2.0", 4514 "id": 1, 4515 "result": true 4516} 4517~~~ 4518 4519### bdev_nvme_get_discovery_info {#rpc_bdev_nvme_get_discovery_info} 4520 4521Get information about the discovery service. 4522 4523#### Example 4524 4525Example request: 4526~~~json 4527{ 4528 "jsonrpc": "2.0", 4529 "method": "bdev_nvme_get_discovery_info", 4530 "id": 1 4531} 4532~~~ 4533 4534Example response: 4535 4536~~~json 4537{ 4538 "jsonrpc": "2.0", 4539 "id": 1, 4540 "result": [ 4541 { 4542 "name": "nvme-disc", 4543 "trid": { 4544 "trtype": "TCP", 4545 "adrfam": "IPv4", 4546 "traddr": "127.0.0.1", 4547 "trsvcid": "8009", 4548 "subnqn": "nqn.2014-08.org.nvmexpress.discovery" 4549 }, 4550 "referrals": [] 4551 } 4552 ] 4553} 4554~~~ 4555 4556### bdev_nvme_get_io_paths {#rpc_bdev_nvme_get_io_paths} 4557 4558Display all or the specified NVMe bdev's active I/O paths. 4559 4560#### Parameters 4561 4562Name | Optional | Type | Description 4563----------------------- | -------- | ----------- | ----------- 4564name | Optional | string | Name of the NVMe bdev 4565 4566#### Example 4567 4568Example request: 4569 4570~~~json 4571{ 4572 "jsonrpc": "2.0", 4573 "method": "bdev_nvme_get_io_paths", 4574 "id": 1, 4575 "params": { 4576 "name": "Nvme0n1" 4577 } 4578} 4579~~~ 4580 4581Example response: 4582 4583~~~json 4584{ 4585 "jsonrpc": "2.0", 4586 "id": 1, 4587 "result": { 4588 "poll_groups": [ 4589 { 4590 "thread": "app_thread", 4591 "io_paths": [ 4592 { 4593 "bdev_name": "Nvme0n1", 4594 "cntlid": 0, 4595 "current": true, 4596 "connected": true, 4597 "accessible": true, 4598 "transport": { 4599 "trtype": "RDMA", 4600 "traddr": "1.2.3.4", 4601 "trsvcid": "4420", 4602 "adrfam": "IPv4" 4603 } 4604 } 4605 ] 4606 } 4607 ] 4608 } 4609} 4610~~~ 4611 4612### bdev_nvme_set_preferred_path {#rpc_bdev_nvme_set_preferred_path} 4613 4614Set the preferred I/O path for an NVMe bdev in multipath mode. 4615 4616NOTE: This RPC does not support NVMe bdevs in failover mode. 4617 4618#### Parameters 4619 4620Name | Optional | Type | Description 4621----------------------- | -------- | ----------- | ----------- 4622name | Required | string | Name of the NVMe bdev 4623cntlid | Required | number | NVMe-oF controller ID 4624 4625#### Example 4626 4627Example request: 4628 4629~~~json 4630{ 4631 "jsonrpc": "2.0", 4632 "method": "bdev_nvme_set_preferred_path", 4633 "id": 1, 4634 "params": { 4635 "name": "Nvme0n1", 4636 "cntlid": 0 4637 } 4638} 4639~~~ 4640 4641Example response: 4642 4643~~~json 4644{ 4645 "jsonrpc": "2.0", 4646 "id": 1, 4647 "result": true 4648} 4649~~~ 4650 4651### bdev_nvme_set_multipath_policy {#rpc_bdev_nvme_set_multipath_policy} 4652 4653Set multipath policy of the NVMe bdev in multipath mode or set multipath 4654selector for active-active multipath policy. 4655 4656#### Parameters 4657 4658Name | Optional | Type | Description 4659----------------------- | -------- | ----------- | ----------- 4660name | Required | string | Name of the NVMe bdev 4661policy | Required | string | Multipath policy: active_active or active_passive 4662selector | Optional | string | Multipath selector: round_robin or queue_depth, used in active-active mode. Default is round_robin 4663rr_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. 4664 4665#### Example 4666 4667Example request: 4668 4669~~~json 4670{ 4671 "jsonrpc": "2.0", 4672 "method": "bdev_nvme_set_multipath_policy", 4673 "id": 1, 4674 "params": { 4675 "name": "Nvme0n1", 4676 "policy": "active_passive" 4677 } 4678} 4679~~~ 4680 4681Example response: 4682 4683~~~json 4684{ 4685 "jsonrpc": "2.0", 4686 "id": 1, 4687 "result": true 4688} 4689~~~ 4690 4691### bdev_nvme_get_path_iostat {#rpc_bdev_nvme_get_path_iostat} 4692 4693Get I/O statistics for IO paths of the block device. Call RPC bdev_nvme_set_options to set enable_io_path_stat 4694true before using this RPC. 4695 4696#### Parameters 4697 4698Name | Optional | Type | Description 4699----------------------- | -------- | ----------- | ----------- 4700name | Required | string | Name of the NVMe bdev 4701 4702#### Example 4703 4704Example request: 4705 4706~~~json 4707{ 4708 "jsonrpc": "2.0", 4709 "method": "bdev_nvme_get_path_iostat", 4710 "id": 1, 4711 "params": { 4712 "name": "NVMe0n1" 4713 } 4714} 4715~~~ 4716 4717Example response: 4718 4719~~~json 4720{ 4721 "jsonrpc": "2.0", 4722 "id": 1, 4723 "result": { 4724 "name": "NVMe0n1", 4725 "stats": [ 4726 { 4727 "trid": { 4728 "trtype": "TCP", 4729 "adrfam": "IPv4", 4730 "traddr": "10.169.204.201", 4731 "trsvcid": "4420", 4732 "subnqn": "nqn.2016-06.io.spdk:cnode1" 4733 }, 4734 "stat": { 4735 "bytes_read": 676691968, 4736 "num_read_ops": 165201, 4737 "bytes_written": 0, 4738 "num_write_ops": 0, 4739 "bytes_unmapped": 0, 4740 "num_unmap_ops": 0, 4741 "max_read_latency_ticks": 521487, 4742 "min_read_latency_ticks": 0, 4743 "write_latency_ticks": 0, 4744 "max_write_latency_ticks": 0, 4745 "min_write_latency_ticks": 0, 4746 "unmap_latency_ticks": 0, 4747 "max_unmap_latency_ticks": 0, 4748 "min_unmap_latency_ticks": 0, 4749 "copy_latency_ticks": 0, 4750 "max_copy_latency_ticks": 0, 4751 "min_copy_latency_ticks": 0 4752 } 4753 }, 4754 { 4755 "trid": { 4756 "trtype": "TCP", 4757 "adrfam": "IPv4", 4758 "traddr": "8.8.8.6", 4759 "trsvcid": "4420", 4760 "subnqn": "nqn.2016-06.io.spdk:cnode1" 4761 }, 4762 "stat": { 4763 "bytes_read": 677138432, 4764 "num_read_ops": 165317, 4765 "bytes_written": 0, 4766 "num_write_ops": 0, 4767 "bytes_unmapped": 0, 4768 "num_unmap_ops": 0, 4769 "max_read_latency_ticks": 108525, 4770 "min_read_latency_ticks": 0, 4771 "write_latency_ticks": 0, 4772 "max_write_latency_ticks": 0, 4773 "min_write_latency_ticks": 0, 4774 "unmap_latency_ticks": 0, 4775 "max_unmap_latency_ticks": 0, 4776 "min_unmap_latency_ticks": 0, 4777 "copy_latency_ticks": 0, 4778 "max_copy_latency_ticks": 0, 4779 "min_copy_latency_ticks": 0 4780 } 4781 } 4782 ] 4783 } 4784} 4785~~~ 4786 4787### bdev_nvme_cuse_register {#rpc_bdev_nvme_cuse_register} 4788 4789Register CUSE device on NVMe controller. 4790 4791#### Parameters 4792 4793Name | Optional | Type | Description 4794----------------------- | -------- | ----------- | ----------- 4795name | Required | string | Name of the NVMe controller 4796 4797#### Example 4798 4799Example request: 4800 4801~~~json 4802{ 4803 "jsonrpc": "2.0", 4804 "method": "bdev_nvme_cuse_register", 4805 "id": 1, 4806 "params": { 4807 "name": "Nvme0" 4808 } 4809} 4810~~~ 4811 4812Example response: 4813 4814~~~json 4815{ 4816 "jsonrpc": "2.0", 4817 "id": 1, 4818 "result": true 4819} 4820~~~ 4821 4822### bdev_nvme_cuse_unregister {#rpc_bdev_nvme_cuse_unregister} 4823 4824Unregister CUSE device on NVMe controller. 4825 4826#### Parameters 4827 4828Name | Optional | Type | Description 4829----------------------- | -------- | ----------- | ----------- 4830name | Required | string | Name of the NVMe controller 4831 4832#### Example 4833 4834Example request: 4835 4836~~~json 4837{ 4838 "params": { 4839 "name": "Nvme0" 4840 }, 4841 "jsonrpc": "2.0", 4842 "method": "bdev_nvme_cuse_unregister", 4843 "id": 1 4844} 4845~~~ 4846 4847Example response: 4848 4849~~~json 4850{ 4851 "jsonrpc": "2.0", 4852 "id": 1, 4853 "result": true 4854} 4855~~~ 4856 4857### bdev_zone_block_create {#rpc_bdev_zone_block_create} 4858 4859Creates a virtual zone device on top of existing non-zoned bdev. 4860 4861#### Parameters 4862 4863Name | Optional | Type | Description 4864----------------------- | -------- | ----------- | ----------- 4865name | Required | string | Name of the Zone device 4866base_bdev | Required | string | Name of the Base bdev 4867zone_capacity | Required | number | Zone capacity in blocks 4868optimal_open_zones | Required | number | Number of zones required to reach optimal write speed 4869 4870#### Example 4871 4872Example request: 4873 4874~~~json 4875{ 4876 "jsonrpc": "2.0", 4877 "method": "bdev_zone_block_create", 4878 "id": 1, 4879 "params": { 4880 "name": "zone1", 4881 "base_bdev": "NVMe0n1", 4882 "zone_capacity": 4096, 4883 "optimal_open_zones": 32 4884 } 4885} 4886~~~ 4887 4888Example response: 4889 4890~~~json 4891{ 4892 "jsonrpc": "2.0", 4893 "id": 1, 4894 "result": "zone1" 4895} 4896~~~ 4897 4898### bdev_zone_block_delete {#rpc_bdev_zone_block_delete} 4899 4900Deletes a virtual zone device. 4901 4902#### Parameters 4903 4904Name | Optional | Type | Description 4905----------------------- | -------- | ----------- | ----------- 4906name | Required | string | Name of the Zone device 4907 4908#### Example 4909 4910Example request: 4911 4912~~~json 4913{ 4914 "jsonrpc": "2.0", 4915 "method": "bdev_zone_block_delete", 4916 "id": 1, 4917 "params": { 4918 "name": "zone1" 4919 } 4920} 4921~~~ 4922 4923Example response: 4924 4925~~~json 4926{ 4927 "jsonrpc": "2.0", 4928 "id": 1, 4929 "result": true 4930} 4931~~~ 4932 4933### bdev_nvme_apply_firmware {#rpc_bdev_nvme_apply_firmware} 4934 4935Download and commit firmware to NVMe device. 4936 4937#### Parameters 4938 4939Name | Optional | Type | Description 4940----------------------- | -------- | ----------- | ----------- 4941filename | Required | string | filename of the firmware to download 4942bdev_name | Required | string | Name of the NVMe block device 4943 4944#### Example 4945 4946Example request: 4947 4948~~~json 4949{ 4950 "jsonrpc": "2.0", 4951 "method": "bdev_nvme_apply_firmware", 4952 "id": 1, 4953 "params": { 4954 "filename": "firmware_file", 4955 "bdev_name": "NVMe0n1" 4956 } 4957} 4958~~~ 4959 4960### bdev_nvme_get_transport_statistics {#rpc_bdev_nvme_get_transport_statistics} 4961 4962Get bdev_nvme poll group transport statistics. 4963 4964#### Parameters 4965 4966This RPC method accepts no parameters 4967 4968#### Response 4969 4970The response is an array of objects containing information about transport statistics per NVME poll group. 4971 4972#### Example 4973 4974Example request: 4975 4976~~~json 4977{ 4978 "jsonrpc": "2.0", 4979 "id": 1, 4980 "method": "bdev_nvme_get_transport_statistics", 4981} 4982~~~ 4983 4984Example response: 4985 4986~~~json 4987{ 4988 "jsonrpc": "2.0", 4989 "id": 1, 4990 "result": { 4991 "poll_groups": [ 4992 { 4993 "thread": "nvmf_tgt_poll_group_000", 4994 "transports": [ 4995 { 4996 "trname": "RDMA", 4997 "devices": [ 4998 { 4999 "dev_name": "mlx5_1", 5000 "polls": 137492169, 5001 "idle_polls": 137492169, 5002 "completions": 0, 5003 "queued_requests": 0, 5004 "total_send_wrs": 0, 5005 "send_sq_doorbell_updates": 0, 5006 "total_recv_wrs": 0, 5007 "recv_sq_doorbell_updates": 0 5008 }, 5009 { 5010 "dev_name": "mlx5_0", 5011 "polls": 137985185, 5012 "idle_polls": 137492169, 5013 "completions": 1474593, 5014 "queued_requests": 0, 5015 "total_send_wrs": 1474593, 5016 "send_sq_doorbell_updates": 426147, 5017 "total_recv_wrs": 1474721, 5018 "recv_sq_doorbell_updates": 348445 5019 } 5020 ] 5021 }, 5022 { 5023 "trname": "PCIE", 5024 "polls": 435419831, 5025 "idle_polls": 434901004, 5026 "completions": 1485543, 5027 "cq_doorbell_updates": 518827, 5028 "queued_requests": 0, 5029 "submitted_requests": 1485543, 5030 "sq_doorbell_updates": 516081 5031 } 5032 ] 5033 }, 5034 { 5035 "thread": "nvmf_tgt_poll_group_001", 5036 "transports": [ 5037 { 5038 "trname": "RDMA", 5039 "devices": [ 5040 { 5041 "dev_name": "mlx5_1", 5042 "polls": 140245630, 5043 "idle_polls": 140245630, 5044 "completions": 0, 5045 "queued_requests": 0, 5046 "total_send_wrs": 0, 5047 "send_sq_doorbell_updates": 0, 5048 "total_recv_wrs": 0, 5049 "recv_sq_doorbell_updates": 0 5050 }, 5051 { 5052 "dev_name": "mlx5_0", 5053 "polls": 140751844, 5054 "idle_polls": 140245630, 5055 "completions": 1489298, 5056 "queued_requests": 0, 5057 "total_send_wrs": 1489298, 5058 "send_sq_doorbell_updates": 433510, 5059 "total_recv_wrs": 1489426, 5060 "recv_sq_doorbell_updates": 357956 5061 } 5062 ] 5063 }, 5064 { 5065 "trname": "PCIE", 5066 "polls": 429044294, 5067 "idle_polls": 428525658, 5068 "completions": 1478730, 5069 "cq_doorbell_updates": 518636, 5070 "queued_requests": 0, 5071 "submitted_requests": 1478730, 5072 "sq_doorbell_updates": 511658 5073 } 5074 ] 5075 } 5076 ] 5077 } 5078} 5079~~~ 5080 5081### bdev_nvme_get_controller_health_info {#rpc_bdev_nvme_get_controller_health_info} 5082 5083Display health log of the required NVMe bdev device. 5084 5085#### Parameters 5086 5087Name | Optional | Type | Description 5088----------------------- | -------- | ----------- | ----------- 5089name | Required | string | Name of the NVMe bdev controller 5090 5091#### Response 5092 5093The response is the object containing information about health log of the NVMe controller. 5094 5095#### Example 5096 5097Example request: 5098 5099~~~json 5100{ 5101 "jsonrpc": "2.0", 5102 "method": "bdev_nvme_get_controller_health_info", 5103 "id": 1, 5104 "params": { 5105 "name": "Nvme0" 5106 } 5107} 5108~~~ 5109 5110Example response: 5111 5112~~~json 5113{ 5114 "model_number": "INTEL SSDPE2KX020T8", 5115 "serial_number": "BTLJ72430ARH2P0BGN", 5116 "firmware_revision": "VDV10110", 5117 "traddr": "0000:08:00.0", 5118 "temperature_celsius": 32, 5119 "available_spare_percentage": 99, 5120 "available_spare_threshold_percentage": 10, 5121 "percentage_used": 2, 5122 "data_units_read": 1013408619, 5123 "data_units_written": 346792685, 5124 "host_read_commands": 30457773282, 5125 "host_write_commands": 18949677715, 5126 "controller_busy_time": 4979, 5127 "power_cycles": 49, 5128 "power_on_hours": 31118, 5129 "unsafe_shutdowns": 18, 5130 "media_errors": 17, 5131 "num_err_log_entries": 19, 5132 "warning_temperature_time_minutes": 0, 5133 "critical_composite_temperature_time_minutes": 0 5134} 5135~~~ 5136 5137### bdev_rbd_register_cluster {#rpc_bdev_rbd_register_cluster} 5138 5139This method is available only if SPDK was build with Ceph RBD support. 5140 5141#### Parameters 5142 5143Name | Optional | Type | Description 5144----------------------- | -------- | ----------- | ----------- 5145name | Optional | string | Registered Rados cluster object name 5146user_id | Optional | string | Ceph ID (i.e. admin, not client.admin) 5147config_param | Optional | string map | Explicit librados configuration 5148config_file | Optional | string | File path of librados configuration file 5149key_file | Optional | string | File path of librados key file 5150core_mask | Optional | string | Core mask for librados IO context threads 5151 5152This RPC registers a Rados Cluster object handle which is only known 5153to rbd module, it uses user_id + config_param or user_id + config_file + 5154key_file or user_id + config_param + config_file + key_file to identify 5155a Rados cluster object. 5156 5157When accessing the Ceph cluster as some user other than "admin" (the 5158default), the "user_id" has to be set. 5159 5160The configuration items and secret key can be specified by setting config_param, 5161config_file and key_file, all of them, or none of them. If only config_param is 5162passed, all key/value pairs are passed to rados_conf_set to configure cluster access. 5163In practice, "mon_host" (= list of monitor address+port) and "key" (= the secret key 5164stored in Ceph keyrings) are enough. If config_file and key_file are specified, they must 5165exist with all relevant settings for accessing the Ceph cluster. If config_param, config_file 5166and key_file are specified, get the key/value pairs from config_file first and set to 5167rados_conf_set function, then set pairs in config_param and keyring in key_file. If nothing 5168is specified, it will get configuration file and key file from the default location 5169/etc/ceph/ceph.conf and /etc/ceph/ceph.client.user_id.keyring. 5170 5171#### Result 5172 5173Name of newly created Rados cluster object. 5174 5175#### Example 5176 5177Example request: 5178 5179~~ 5180{ 5181 "params": { 5182 "name": "rbd_cluster", 5183 "user_id": cinder, 5184 "config_file": "/root/ceph_conf/ceph.conf", 5185 "key_file": "/root/ceph_conf/ceph.client.cinder.keyring" 5186 }, 5187 "jsonrpc": "2.0", 5188 "method": "bdev_rbd_register_cluster", 5189 "id": 1 5190} 5191~~ 5192 5193Example response: 5194 5195~~ 5196response: 5197{ 5198 "jsonrpc": "2.0", 5199 "id": 1, 5200 "result": "rbd_cluster" 5201} 5202~~ 5203 5204### bdev_rbd_unregister_cluster {#rpc_bdev_rbd_unregister_cluster} 5205 5206This method is available only if SPDK was build with Ceph RBD support. 5207If there is still rbd bdev using this cluster, the unregisteration operation 5208will fail. 5209 5210#### Result 5211 5212`true` if Rados cluster object with provided name was deleted or `false` otherwise. 5213 5214#### Parameters 5215 5216Name | Optional | Type | Description 5217----------------------- | -------- | ----------- | ------------------------- 5218name | Required | string | Rados cluster object name 5219 5220#### Example 5221 5222Example request: 5223 5224~~ 5225{ 5226 "params": { 5227 "name": "rbd_cluster" 5228 }, 5229 "jsonrpc": "2.0", 5230 "method": "bdev_rbd_unregister_cluster", 5231 "id": 1 5232} 5233~~ 5234 5235Example response: 5236 5237~~ 5238{ 5239 "jsonrpc": "2.0", 5240 "id": 1, 5241 "result": true 5242} 5243~~ 5244 5245### bdev_rbd_get_clusters_info {#rpc_bdev_rbd_get_clusters_info} 5246 5247This method is available only if SPDK was build with Ceph RBD support. 5248 5249#### Result 5250 5251Returns the cluster info of the Rados Cluster name if provided. Otherwise, it 5252returns the cluster info of every registered Raods Cluster name. 5253 5254#### Parameters 5255 5256Name | Optional | Type | Description 5257----------------------- | -------- | ----------- | ------------------------- 5258name | Optional | string | Rados cluster object name 5259 5260#### Example 5261 5262Example request: 5263 5264~~ 5265{ 5266 "params": { 5267 "name": "rbd_cluster" 5268 }, 5269 "jsonrpc": "2.0", 5270 "method": "bdev_rbd_get_clusters_info", 5271 "id": 1 5272} 5273~~ 5274 5275Example response: 5276 5277~~ 5278{ 5279 "jsonrpc": "2.0", 5280 "cluster_name": "rbd_cluster" 5281} 5282~~ 5283 5284### bdev_rbd_create {#rpc_bdev_rbd_create} 5285 5286Create @ref bdev_config_rbd bdev 5287 5288This method is available only if SPDK was build with Ceph RBD support. 5289 5290#### Parameters 5291 5292Name | Optional | Type | Description 5293----------------------- | -------- | ----------- | ----------- 5294name | Optional | string | Bdev name 5295user_id | Optional | string | Ceph ID (i.e. admin, not client.admin) 5296pool_name | Required | string | Pool name 5297rbd_name | Required | string | Image name 5298block_size | Required | number | Block size 5299config | Optional | string map | Explicit librados configuration 5300cluster_name | Optional | string | Rados cluster object name created in this module. 5301uuid | Optional | string | UUID of new bdev 5302 5303If no config is specified, Ceph configuration files must exist with 5304all relevant settings for accessing the pool. If a config map is 5305passed, the configuration files are ignored and instead all key/value 5306pairs are passed to rados_conf_set to configure cluster access. In 5307practice, "mon_host" (= list of monitor address+port) and "key" (= the 5308secret key stored in Ceph keyrings) are enough. 5309 5310When accessing the image as some user other than "admin" (the 5311default), the "user_id" has to be set. 5312 5313If provided with cluster_name option, it will use the Rados cluster object 5314referenced by the name (created by bdev_rbd_register_cluster RPC) and ignores 5315"user_id + config" combination to create its own Rados cluster. In this scenario, 5316all the bdevs will share the same cluster with one connection of Ceph in librbd module. 5317Performance tuning on the I/O workload could be done by estimating how many io_contxt 5318threads and messager threads in Ceph side and how many cores would be reasonable to provide 5319for SPDK to get up to your projections. 5320 5321#### Result 5322 5323Name of newly created bdev. 5324 5325#### Example 5326 5327Example request with `key` from `/etc/ceph/ceph.client.admin.keyring`: 5328 5329~~~json 5330{ 5331 "params": { 5332 "pool_name": "rbd", 5333 "rbd_name": "foo", 5334 "config": { 5335 "mon_host": "192.168.7.1:6789,192.168.7.2:6789", 5336 "key": "AQDwf8db7zR1GRAA5k7NKXjS5S5V4mntwUDnGQ==", 5337 } 5338 "block_size": 4096, 5339 "uuid": "76210ea4-7920-40a0-a07b-8992a7443c76" 5340 }, 5341 "jsonrpc": "2.0", 5342 "method": "bdev_rbd_create", 5343 "id": 1 5344} 5345~~~ 5346 5347Example response: 5348 5349~~~json 5350response: 5351{ 5352 "jsonrpc": "2.0", 5353 "id": 1, 5354 "result": "Ceph0" 5355} 5356~~~ 5357 5358Example request with `cluster_name`: 5359 5360~~ 5361{ 5362 "params": { 5363 "pool_name": "rbd", 5364 "rbd_name": "foo", 5365 "block_size": 4096, 5366 "cluster_name": "rbd_cluster" 5367 }, 5368 "jsonrpc": "2.0", 5369 "method": "bdev_rbd_create", 5370 "id": 1 5371} 5372~~ 5373 5374Example response: 5375 5376~~ 5377response: 5378{ 5379 "jsonrpc": "2.0", 5380 "id": 1, 5381 "result": "Ceph0" 5382} 5383~~ 5384 5385### bdev_rbd_delete {#rpc_bdev_rbd_delete} 5386 5387Delete @ref bdev_config_rbd bdev 5388 5389This method is available only if SPDK was build with Ceph RBD support. 5390 5391#### Result 5392 5393`true` if bdev with provided name was deleted or `false` otherwise. 5394 5395#### Parameters 5396 5397Name | Optional | Type | Description 5398----------------------- | -------- | ----------- | ----------- 5399name | Required | string | Bdev name 5400 5401#### Example 5402 5403Example request: 5404 5405~~~json 5406{ 5407 "params": { 5408 "name": "Rbd0" 5409 }, 5410 "jsonrpc": "2.0", 5411 "method": "bdev_rbd_delete", 5412 "id": 1 5413} 5414~~~ 5415 5416Example response: 5417 5418~~~json 5419{ 5420 "jsonrpc": "2.0", 5421 "id": 1, 5422 "result": true 5423} 5424~~~ 5425 5426### bdev_rbd_resize {#rpc_bdev_rbd_resize} 5427 5428Resize @ref bdev_config_rbd bdev 5429 5430This method is available only if SPDK was build with Ceph RBD support. 5431 5432#### Result 5433 5434`true` if bdev with provided name was resized or `false` otherwise. 5435 5436#### Parameters 5437 5438Name | Optional | Type | Description 5439----------------------- | -------- | ----------- | ----------- 5440name | Required | string | Bdev name 5441new_size | Required | int | New bdev size for resize operation in MiB 5442 5443#### Example 5444 5445Example request: 5446 5447~~~json 5448{ 5449 "params": { 5450 "name": "Rbd0" 5451 "new_size": "4096" 5452 }, 5453 "jsonrpc": "2.0", 5454 "method": "bdev_rbd_resize", 5455 "id": 1 5456} 5457~~~ 5458 5459Example response: 5460 5461~~~json 5462{ 5463 "jsonrpc": "2.0", 5464 "id": 1, 5465 "result": true 5466} 5467~~~ 5468 5469### bdev_delay_create {#rpc_bdev_delay_create} 5470 5471Create delay bdev. This bdev type redirects all IO to it's base bdev and inserts a delay on the completion 5472path to create an artificial drive latency. All latency values supplied to this bdev should be in microseconds. 5473 5474#### Parameters 5475 5476Name | Optional | Type | Description 5477----------------------- | -------- | ----------- | ----------- 5478name | Required | string | Bdev name 5479base_bdev_name | Required | string | Base bdev name 5480avg_read_latency | Required | number | average read latency (us) 5481p99_read_latency | Required | number | p99 read latency (us) 5482avg_write_latency | Required | number | average write latency (us) 5483p99_write_latency | Required | number | p99 write latency (us) 5484uuid | Optional | string | UUID of new bdev 5485 5486#### Result 5487 5488Name of newly created bdev. 5489 5490#### Example 5491 5492Example request: 5493 5494~~~json 5495{ 5496 "params": { 5497 "base_bdev_name": "Null0", 5498 "name": "Delay0", 5499 "avg_read_latency": "15", 5500 "p99_read_latency": "50", 5501 "avg_write_latency": "40", 5502 "p99_write_latency": "110", 5503 }, 5504 "jsonrpc": "2.0", 5505 "method": "bdev_delay_create", 5506 "id": 1 5507} 5508~~~ 5509 5510Example response: 5511 5512~~~json 5513{ 5514 "jsonrpc": "2.0", 5515 "id": 1, 5516 "result": "Delay0" 5517} 5518~~~ 5519 5520### bdev_delay_delete {#rpc_bdev_delay_delete} 5521 5522Delete delay bdev. 5523 5524#### Parameters 5525 5526Name | Optional | Type | Description 5527----------------------- | -------- | ----------- | ----------- 5528name | Required | string | Bdev name 5529 5530#### Example 5531 5532Example request: 5533 5534~~~json 5535{ 5536 "params": { 5537 "name": "Delay0" 5538 }, 5539 "jsonrpc": "2.0", 5540 "method": "bdev_delay_delete", 5541 "id": 1 5542} 5543 5544~~~ 5545 5546Example response: 5547 5548~~~json 5549{ 5550 "jsonrpc": "2.0", 5551 "id": 1, 5552 "result": true 5553} 5554~~~ 5555 5556### bdev_delay_update_latency {#rpc_bdev_delay_update_latency} 5557 5558Update a target latency value associated with a given delay bdev. Any currently 5559outstanding I/O will be completed with the old latency. 5560 5561#### Parameters 5562 5563Name | Optional | Type | Description 5564----------------------- | -------- | ----------- | ----------- 5565delay_bdev_name | Required | string | Name of the delay bdev 5566latency_type | Required | string | One of: avg_read, avg_write, p99_read, p99_write 5567latency_us | Required | number | The new latency value in microseconds 5568 5569#### Result 5570 5571Name of newly created bdev. 5572 5573#### Example 5574 5575Example request: 5576 5577~~~json 5578{ 5579 "params": { 5580 "delay_bdev_name": "Delay0", 5581 "latency_type": "avg_read", 5582 "latency_us": "100", 5583 }, 5584 "jsonrpc": "2.0", 5585 "method": "bdev_delay_update_latency", 5586 "id": 1 5587} 5588~~~ 5589 5590Example response: 5591 5592~~~json 5593{ 5594 "result": "true" 5595} 5596~~~ 5597 5598### bdev_error_create {#rpc_bdev_error_create} 5599 5600Construct error bdev. 5601 5602#### Parameters 5603 5604Name | Optional | Type | Description 5605----------------------- | -------- | ----------- | ----------- 5606base_name | Required | string | Base bdev name 5607uuid | Optional | string | UUID for this bdev 5608 5609#### Example 5610 5611Example request: 5612 5613~~~json 5614{ 5615 "params": { 5616 "base_name": "Malloc0" 5617 }, 5618 "jsonrpc": "2.0", 5619 "method": "bdev_error_create", 5620 "id": 1 5621} 5622~~~ 5623 5624Example response: 5625 5626~~~json 5627{ 5628 "jsonrpc": "2.0", 5629 "id": 1, 5630 "result": true 5631} 5632~~~ 5633 5634### bdev_error_delete {#rpc_bdev_error_delete} 5635 5636Delete error bdev 5637 5638#### Result 5639 5640`true` if bdev with provided name was deleted or `false` otherwise. 5641 5642#### Parameters 5643 5644Name | Optional | Type | Description 5645----------------------- | -------- | ----------- | ----------- 5646name | Required | string | Error bdev name 5647 5648#### Example 5649 5650Example request: 5651 5652~~~json 5653{ 5654 "params": { 5655 "name": "EE_Malloc0" 5656 }, 5657 "jsonrpc": "2.0", 5658 "method": "bdev_error_delete", 5659 "id": 1 5660} 5661~~~ 5662 5663Example response: 5664 5665~~~json 5666{ 5667 "jsonrpc": "2.0", 5668 "id": 1, 5669 "result": true 5670} 5671~~~ 5672 5673### bdev_error_inject_error {#rpc_bdev_error_inject_error} 5674 5675Inject an error via an error bdev. Create an error bdev on base bdev first. Default 'num' 5676value is 1 and if 'num' is set to zero, the specified injection is disabled. 5677 5678#### Parameters 5679 5680Name | Optional | Type | Description 5681----------------------- | -------- | ----------- | ----------- 5682name | Required | string | Name of the error injection bdev 5683io_type | Required | string | io type 'clear' 'read' 'write' 'unmap' 'flush' 'all' 5684error_type | Required | string | error type 'failure' 'pending' 'corrupt_data' 'nomem' 5685num | Optional | int | the number of commands you want to fail.(default:1) 5686queue_depth | Optional | int | the queue depth at which to trigger the error 5687corrupt_offset | Optional | int | the offset in bytes to xor with corrupt_value 5688corrupt_value | Optional | int | the value for xor (1-255, 0 is invalid) 5689 5690#### Example 5691 5692Example request: 5693 5694~~~json 5695{ 5696 "jsonrpc": "2.0", 5697 "method": "bdev_error_inject_error", 5698 "id": 1, 5699 "params": { 5700 "name": "EE_Malloc0", 5701 "io_type": "write", 5702 "error_type": "pending", 5703 "num": 1 5704 } 5705} 5706~~~ 5707 5708Example response: 5709 5710~~~json 5711{ 5712 "jsonrpc": "2.0", 5713 "id": 1, 5714 "result": true 5715} 5716~~~ 5717 5718### bdev_iscsi_set_options {#rpc_bdev_iscsi_set_options} 5719 5720This RPC can be called at any time, but the new value will only take effect for new iSCSI bdevs. 5721 5722#### Parameters 5723 5724Name | Optional | Type | Description 5725-------------------------- | -------- | ----------- | ----------- 5726timeout_sec | Optional | number | Timeout for command, in seconds, if 0, don't track timeout 5727 5728#### Example 5729 5730Example request: 5731 5732~~~json 5733request: 5734{ 5735 "params": { 5736 "timeout_sec": 30 5737 }, 5738 "jsonrpc": "2.0", 5739 "method": "bdev_iscsi_set_options", 5740 "id": 1 5741} 5742~~~ 5743 5744Example response: 5745 5746~~~json 5747{ 5748 "jsonrpc": "2.0", 5749 "id": 1, 5750 "result": true 5751} 5752~~~ 5753 5754### bdev_iscsi_create {#rpc_bdev_iscsi_create} 5755 5756Connect to iSCSI target and create bdev backed by this connection. 5757 5758This method is available only if SPDK was build with iSCSI initiator support. 5759 5760#### Parameters 5761 5762Name | Optional | Type | Description 5763----------------------- | -------- | ----------- | ----------- 5764name | Required | string | Bdev name 5765initiator_iqn | Required | string | IQN name used during connection 5766url | Required | string | iSCSI resource URI 5767 5768#### Result 5769 5770Name of newly created bdev. 5771 5772#### Example 5773 5774Example request: 5775 5776~~~json 5777{ 5778 "params": { 5779 "url": "iscsi://127.0.0.1/iqn.2016-06.io.spdk:disk1/0", 5780 "initiator_iqn": "iqn.2016-06.io.spdk:init", 5781 "name": "iSCSI0" 5782 }, 5783 "jsonrpc": "2.0", 5784 "method": "bdev_iscsi_create", 5785 "id": 1 5786} 5787~~~ 5788 5789Example response: 5790 5791~~~json 5792{ 5793 "jsonrpc": "2.0", 5794 "id": 1, 5795 "result": "iSCSI0" 5796} 5797~~~ 5798 5799### bdev_iscsi_delete {#rpc_bdev_iscsi_delete} 5800 5801Delete iSCSI bdev and terminate connection to target. 5802 5803This method is available only if SPDK was built with iSCSI initiator support. 5804 5805#### Parameters 5806 5807Name | Optional | Type | Description 5808----------------------- | -------- | ----------- | ----------- 5809name | Required | string | Bdev name 5810 5811#### Example 5812 5813Example request: 5814 5815~~~json 5816{ 5817 "params": { 5818 "name": "iSCSI0" 5819 }, 5820 "jsonrpc": "2.0", 5821 "method": "bdev_iscsi_delete", 5822 "id": 1 5823} 5824~~~ 5825 5826Example response: 5827 5828~~~json 5829{ 5830 "jsonrpc": "2.0", 5831 "id": 1, 5832 "result": true 5833} 5834~~~ 5835 5836### bdev_ftl_create {#rpc_bdev_ftl_create} 5837 5838Create FTL bdev. 5839 5840This RPC is subject to change. 5841 5842#### Parameters 5843 5844Name | Optional | Type | Description 5845----------------------- | -------- | ----------- | ----------- 5846name | Required | string | Bdev name 5847base_bdev | Required | string | Name of the base device 5848cache | Required | string | Name of the cache device 5849uuid | Optional | string | UUID of restored bdev (not applicable when creating new instance) 5850core_mask | Optional | string | CPU core(s) possible for placement of the ftl core thread, application main thread by default 5851overprovisioning | Optional | int | Percentage of base device used for relocation, 20% by default 5852fast_shutdown | Optional | bool | When set FTL will minimize persisted data on target application shutdown and rely on shared memory during next load 5853l2p_dram_limit | Optional | int | DRAM limit for most recent L2P addresses (default 2048 MiB) 5854 5855#### Result 5856 5857Name of newly created bdev. 5858 5859#### Example 5860 5861Example request: 5862 5863~~~json 5864{ 5865 "params": { 5866 "name": "ftl0", 5867 "base_bdev": "nvme0n1", 5868 "cache": "nvme1n1", 5869 "uuid": "4a7481ce-786f-41a0-9b86-8f7465c8f4d3", 5870 "core_mask": "[0]", 5871 "overprovisioning": 10 5872 }, 5873 "jsonrpc": "2.0", 5874 "method": "bdev_ftl_create", 5875 "id": 1 5876} 5877~~~ 5878 5879Example response: 5880 5881~~~json 5882{ 5883 "jsonrpc": "2.0", 5884 "id": 1, 5885 "result": { 5886 "name" : "ftl0" 5887 "uuid" : "4a7481ce-786f-41a0-9b86-8f7465c8f4d3" 5888 } 5889} 5890~~~ 5891 5892### bdev_ftl_load {#rpc_bdev_ftl_load} 5893 5894Loads FTL bdev. 5895 5896This RPC is subject to change. 5897 5898#### Parameters 5899 5900Name | Optional | Type | Description 5901----------------------- | -------- | ----------- | ----------- 5902name | Required | string | Bdev name 5903base_bdev | Required | string | Name of the base device 5904cache | Required | string | Name of the cache device 5905uuid | Required | string | UUID of restored bdev 5906core_mask | Optional | string | CPU core(s) possible for placement of the ftl core thread, application main thread by default 5907overprovisioning | Optional | int | Percentage of base device used for relocation, 20% by default 5908fast_shutdown | Optional | bool | When set FTL will minimize persisted data on target application shutdown and rely on shared memory during next load 5909l2p_dram_limit | Optional | int | DRAM limit for most recent L2P addresses (default 2048 MiB) 5910 5911#### Result 5912 5913Name of loaded bdev. 5914 5915#### Example 5916 5917Example request: 5918 5919~~~json 5920{ 5921 "params": { 5922 "name": "ftl0", 5923 "base_bdev": "nvme0n1", 5924 "cache": "nvme1n1", 5925 "uuid": "4a7481ce-786f-41a0-9b86-8f7465c8f4d3", 5926 "core_mask": "[0]", 5927 "overprovisioning": 10 5928 }, 5929 "jsonrpc": "2.0", 5930 "method": "bdev_ftl_load", 5931 "id": 1 5932} 5933~~~ 5934 5935Example response: 5936 5937~~~json 5938{ 5939 "jsonrpc": "2.0", 5940 "id": 1, 5941 "result": { 5942 "name" : "ftl0" 5943 "uuid" : "4a7481ce-786f-41a0-9b86-8f7465c8f4d3" 5944 } 5945} 5946~~~ 5947 5948### bdev_ftl_delete {#rpc_bdev_ftl_delete} 5949 5950Delete FTL bdev. 5951 5952This RPC is subject to change. 5953 5954#### Parameters 5955 5956Name | Optional | Type | Description 5957----------------------- | -------- | ----------- | ----------- 5958name | Required | string | Bdev name 5959fast_shutdown | Optional | bool | When set FTL will minimize persisted data during deletion and rely on shared memory during next load 5960 5961#### Example 5962 5963Example request: 5964 5965~~~json 5966{ 5967 "params": { 5968 "name": "ftl0" 5969 }, 5970 "jsonrpc": "2.0", 5971 "method": "bdev_ftl_delete", 5972 "id": 1 5973} 5974~~~ 5975 5976Example response: 5977 5978~~~json 5979{ 5980 "jsonrpc": "2.0", 5981 "id": 1, 5982 "result": true 5983} 5984~~~ 5985 5986### bdev_ftl_unload {#rpc_bdev_ftl_unload} 5987 5988Unloads FTL bdev. 5989 5990This RPC is subject to change. 5991 5992#### Parameters 5993 5994Name | Optional | Type | Description 5995----------------------- | -------- | ----------- | ----------- 5996name | Required | string | Bdev name 5997fast_shutdown | Optional | bool | When set FTL will minimize persisted data during deletion and rely on shared memory during next load 5998 5999#### Example 6000 6001Example request: 6002 6003~~~json 6004{ 6005 "params": { 6006 "name": "ftl0" 6007 }, 6008 "jsonrpc": "2.0", 6009 "method": "bdev_ftl_unload", 6010 "id": 1 6011} 6012~~~ 6013 6014Example response: 6015 6016~~~json 6017{ 6018 "jsonrpc": "2.0", 6019 "id": 1, 6020 "result": true 6021} 6022~~~ 6023 6024### bdev_ftl_unmap {#rpc_bdev_ftl_unmap} 6025 6026Unmap range of LBAs. 6027 6028This RPC is subject to change. 6029 6030#### Parameters 6031 6032Name | Optional | Type | Description 6033----------------------- | -------- | ----------- | ----------- 6034name | Required | string | Bdev name 6035lba | Required | number | start lba, aligned to 1024 6036num_blocks | Required | number | number of blocks, aligned to 1024 6037 6038#### Example 6039 6040Example request: 6041 6042~~~json 6043{ 6044 "params": { 6045 "name": "ftl0" 6046 "lba": "0" 6047 "num_blocks": "1024" 6048 }, 6049 "jsonrpc": "2.0", 6050 "method": "bdev_ftl_unmap", 6051 "id": 1 6052} 6053~~~ 6054 6055Example response: 6056 6057~~~json 6058{ 6059 "jsonrpc": "2.0", 6060 "id": 1, 6061 "result": true 6062} 6063~~~ 6064 6065### bdev_ftl_get_stats {#rpc_bdev_ftl_get_stats} 6066 6067Get IO statistics for FTL bdev 6068 6069This RPC is subject to change. 6070 6071#### Parameters 6072 6073Name | Optional | Type | Description 6074----------------------- | -------- | ----------- | ----------- 6075name | Required | string | Bdev name 6076 6077#### Response 6078 6079The response is an object containing IO statistics for an FTL instance, split into multiple subobjects: 6080 6081- `user` - contains information about number of IOs, and errors for any incoming requests, 6082- `cmp` - information about IO for the compaction process, 6083- `gc` - information about IO for the garbage collection process, 6084- `md_base` - internal metadata requests to the base FTL device, 6085- `md_nv_cache` - internal metadata requests to the cache device, 6086- `l2p` - requests done on the L2P cache region. 6087 6088Each subobject contains the following information: 6089 6090- `ios` - describes the total number of IOs requested, 6091- `blocks` - the total number of requested blocks, 6092- `errors` - describes the number of detected errors for a given operation, with the following distinctions: 6093 - `media` - media errors, 6094 - `crc` - mismatch in calculated CRC versus saved checksum in the metadata, 6095 - `other` - any other errors. 6096 6097#### Example 6098 6099Example request: 6100 6101~~~json 6102{ 6103 "params": { 6104 "name": "ftl0" 6105 }, 6106 "jsonrpc": "2.0", 6107 "method": "bdev_ftl_get_stats", 6108 "id": 1 6109} 6110~~~ 6111 6112Example response: 6113 6114~~~json 6115{ 6116 "jsonrpc": "2.0", 6117 "id": 1, 6118 "result": { 6119 "name": "ftl0", 6120 "user": { 6121 "read": { 6122 "ios": 0, 6123 "blocks": 0, 6124 "errors": { 6125 "media": 0, 6126 "crc": 0, 6127 "other": 0 6128 } 6129 }, 6130 "write": { 6131 "ios": 318707, 6132 "blocks": 318707, 6133 "errors": { 6134 "media": 0, 6135 "other": 0 6136 } 6137 } 6138 }, 6139 "cmp": { 6140 "read": { 6141 "ios": 0, 6142 "blocks": 0, 6143 "errors": { 6144 "media": 0, 6145 "crc": 0, 6146 "other": 0 6147 } 6148 }, 6149 "write": { 6150 "ios": 0, 6151 "blocks": 0, 6152 "errors": { 6153 "media": 0, 6154 "other": 0 6155 } 6156 } 6157 }, 6158 "gc": { 6159 "read": { 6160 "ios": 0, 6161 "blocks": 0, 6162 "errors": { 6163 "media": 0, 6164 "crc": 0, 6165 "other": 0 6166 } 6167 }, 6168 "write": { 6169 "ios": 0, 6170 "blocks": 0, 6171 "errors": { 6172 "media": 0, 6173 "other": 0 6174 } 6175 } 6176 }, 6177 "md_base": { 6178 "read": { 6179 "ios": 0, 6180 "blocks": 0, 6181 "errors": { 6182 "media": 0, 6183 "crc": 0, 6184 "other": 0 6185 } 6186 }, 6187 "write": { 6188 "ios": 1, 6189 "blocks": 32, 6190 "errors": { 6191 "media": 0, 6192 "other": 0 6193 } 6194 } 6195 }, 6196 "md_nv_cache": { 6197 "read": { 6198 "ios": 0, 6199 "blocks": 0, 6200 "errors": { 6201 "media": 0, 6202 "crc": 0, 6203 "other": 0 6204 } 6205 }, 6206 "write": { 6207 "ios": 1064, 6208 "blocks": 1073896, 6209 "errors": { 6210 "media": 0, 6211 "other": 0 6212 } 6213 } 6214 }, 6215 "l2p": { 6216 "read": { 6217 "ios": 240659, 6218 "blocks": 240659, 6219 "errors": { 6220 "media": 0, 6221 "crc": 0, 6222 "other": 0 6223 } 6224 }, 6225 "write": { 6226 "ios": 235745, 6227 "blocks": 235745, 6228 "errors": { 6229 "media": 0, 6230 "other": 0 6231 } 6232 } 6233 } 6234 } 6235} 6236~~~ 6237 6238### bdev_ftl_get_properties {#rpc_bdev_ftl_get_properties} 6239 6240Get FTL properties 6241 6242#### Parameters 6243 6244Name | Optional | Type | Description 6245----------------------- | -------- | ----------- | ----------- 6246name | Required | string | Bdev name 6247 6248#### Response 6249 6250The response contains FTL bdev properties. Some of them can be modified, other 6251reported as read only. 6252 6253#### Example 6254 6255Example request: 6256 6257~~~json 6258{ 6259 "params": { 6260 "name": "ftl0" 6261 }, 6262 "jsonrpc": "2.0", 6263 "method": "bdev_ftl_get_properties", 6264 "id": 1 6265} 6266~~~ 6267 6268Example response: 6269 6270~~~json 6271{ 6272 "jsonrpc": "2.0", 6273 "id": 1, 6274 "result": { 6275 "name": "ftl0", 6276 "properties": [ 6277 { 6278 "name": "property1", 6279 "value": "Property Value 1", 6280 "unit": "MiB/s", 6281 "desc": "This is an example of read-only property", 6282 "read-only": true 6283 }, 6284 { 6285 "name": "property2", 6286 "value": 17, 6287 "unit": "s", 6288 "desc": "This is an example of FTL modifiable property", 6289 "read-only": false 6290 } 6291 ] 6292 } 6293} 6294~~~ 6295 6296### bdev_ftl_set_property {#rpc_bdev_ftl_set_property} 6297 6298Set FTL property. Trying to set a read-only property will result in an error. 6299 6300#### Parameters 6301 6302Name | Optional | Type | Description 6303----------------------- | -------- | ----------- | ----------- 6304name | Required | string | Bdev name 6305property | Required | string | Name of the property to modify 6306value | Required | string | New value of the property to be set 6307 6308#### Example 6309 6310Example request: 6311 6312~~~json 6313{ 6314 "params": { 6315 "name": "ftl0" 6316 "property": "nv_cache.flush" 6317 "value": "true" 6318 }, 6319 "jsonrpc": "2.0", 6320 "method": "bdev_ftl_set_property", 6321 "id": 1 6322} 6323~~~ 6324 6325Example response: 6326 6327~~~json 6328{ 6329 "jsonrpc": "2.0", 6330 "id": 1, 6331 "result": true 6332} 6333~~~ 6334 6335### bdev_passthru_create {#rpc_bdev_passthru_create} 6336 6337Create passthru bdev. This bdev type redirects all IO to it's base bdev. It has no other purpose than being an example 6338and a starting point in development of new bdev type. 6339 6340#### Parameters 6341 6342Name | Optional | Type | Description 6343----------------------- | -------- | ----------- | ----------- 6344name | Required | string | Bdev name 6345base_bdev_name | Required | string | Base bdev name 6346uuid | Optional | string | UUID of new bdev 6347 6348#### Result 6349 6350Name of newly created bdev. 6351 6352#### Example 6353 6354Example request: 6355 6356~~~json 6357{ 6358 "params": { 6359 "base_bdev_name": "Malloc0", 6360 "name": "Passsthru0" 6361 }, 6362 "jsonrpc": "2.0", 6363 "method": "bdev_passthru_create", 6364 "id": 1 6365} 6366~~~ 6367 6368Example response: 6369 6370~~~json 6371{ 6372 "jsonrpc": "2.0", 6373 "id": 1, 6374 "result": "Passsthru0" 6375} 6376~~~ 6377 6378### bdev_passthru_delete {#rpc_bdev_passthru_delete} 6379 6380Delete passthru bdev. 6381 6382#### Parameters 6383 6384Name | Optional | Type | Description 6385----------------------- | -------- | ----------- | ----------- 6386name | Required | string | Bdev name 6387 6388#### Example 6389 6390Example request: 6391 6392~~~json 6393{ 6394 "params": { 6395 "name": "Passsthru0" 6396 }, 6397 "jsonrpc": "2.0", 6398 "method": "bdev_passthru_delete", 6399 "id": 1 6400} 6401 6402~~~ 6403 6404Example response: 6405 6406~~~json 6407{ 6408 "jsonrpc": "2.0", 6409 "id": 1, 6410 "result": true 6411} 6412~~~ 6413 6414### bdev_xnvme_create {#rpc_bdev_xnvme_create} 6415 6416Create xnvme bdev. This bdev type redirects all IO to its underlying backend. 6417 6418#### Parameters 6419 6420Name | Optional | Type | Description 6421----------------------- | -------- | ----------- | ----------- 6422name | Required | string | name of xNVMe bdev to create 6423filename | Required | string | path to device or file (ex: /dev/nvme0n1) 6424io_mechanism | Required | string | IO mechanism to use (ex: libaio, io_uring, io_uring_cmd, etc.) 6425conserve_cpu | Optional | boolean | Whether or not to conserve CPU when polling (default: false) 6426 6427#### Result 6428 6429Name of newly created bdev. 6430 6431#### Example 6432 6433Example request: 6434 6435~~~json 6436{ 6437 "jsonrpc": "2.0", 6438 "method": "bdev_xnvme_create", 6439 "id": 1, 6440 "params": { 6441 "name": "bdev_ng0n1", 6442 "filename": "/dev/ng0n1", 6443 "io_mechanism": "io_uring_cmd", 6444 "conserve_cpu": false, 6445 } 6446} 6447~~~ 6448 6449Example response: 6450 6451~~~json 6452{ 6453 "jsonrpc": "2.0", 6454 "id": 1, 6455 "result": "bdev_ng0n1" 6456} 6457~~~ 6458 6459### bdev_xnvme_delete {#rpc_bdev_xnvme_delete} 6460 6461Delete xnvme bdev. 6462 6463#### Parameters 6464 6465Name | Optional | Type | Description 6466----------------------- | -------- | ----------- | ----------- 6467name | Required | string | name of xnvme bdev to delete 6468 6469#### Example 6470 6471Example request: 6472 6473~~~json 6474{ 6475 "params": { 6476 "name": "bdev_ng0n1" 6477 }, 6478 "jsonrpc": "2.0", 6479 "method": "bdev_xnvme_delete", 6480 "id": 1 6481} 6482 6483~~~ 6484 6485Example response: 6486 6487~~~json 6488{ 6489 "jsonrpc": "2.0", 6490 "id": 1, 6491 "result": true 6492} 6493~~~ 6494 6495### bdev_virtio_attach_controller {#rpc_bdev_virtio_attach_controller} 6496 6497Create new initiator @ref bdev_config_virtio_scsi or @ref bdev_config_virtio_blk and expose all found bdevs. 6498 6499#### Parameters 6500 6501Name | Optional | Type | Description 6502----------------------- | -------- | ----------- | ----------- 6503name | Required | string | Virtio SCSI base bdev name or Virtio Blk bdev name 6504trtype | Required | string | Virtio target trtype: pci or user 6505traddr | Required | string | target address: BDF or UNIX socket file path 6506dev_type | Required | string | Virtio device type: blk or scsi 6507vq_count | Optional | number | Number of queues this controller will utilize (default: 1) 6508vq_size | Optional | number | Size of each queue. Must be power of 2. (default: 512) 6509 6510In case of Virtio SCSI the `name` parameter will be base name for new created bdevs. For Virtio Blk `name` will be the 6511name of created bdev. 6512 6513`vq_count` and `vq_size` parameters are valid only if `trtype` is `user`. 6514 6515#### Result 6516 6517Array of names of newly created bdevs. 6518 6519#### Example 6520 6521Example request: 6522 6523~~~json 6524{ 6525 "params": { 6526 "name": "VirtioScsi0", 6527 "trtype": "user", 6528 "vq_size": 128, 6529 "dev_type": "scsi", 6530 "traddr": "/tmp/VhostScsi0", 6531 "vq_count": 4 6532 }, 6533 "jsonrpc": "2.0", 6534 "method": "bdev_virtio_attach_controller", 6535 "id": 1 6536} 6537~~~ 6538 6539Example response: 6540 6541~~~json 6542{ 6543 "jsonrpc": "2.0", 6544 "id": 1, 6545 "result": ["VirtioScsi0t2", "VirtioScsi0t4"] 6546} 6547~~~ 6548 6549### bdev_virtio_scsi_get_devices {#rpc_bdev_virtio_scsi_get_devices} 6550 6551Show information about all available Virtio SCSI devices. 6552 6553#### Parameters 6554 6555This method has no parameters. 6556 6557#### Result 6558 6559Array of Virtio SCSI information objects. 6560 6561#### Example 6562 6563Example request: 6564 6565~~~json 6566{ 6567 "jsonrpc": "2.0", 6568 "method": "bdev_virtio_scsi_get_devices", 6569 "id": 1 6570} 6571~~~ 6572 6573Example response: 6574 6575~~~json 6576{ 6577 "jsonrpc": "2.0", 6578 "id": 1, 6579 "result": [ 6580 { 6581 "name": "VirtioScsi0", 6582 "virtio": { 6583 "vq_size": 128, 6584 "vq_count": 4, 6585 "type": "user", 6586 "socket": "/tmp/VhostScsi0" 6587 } 6588 } 6589 ] 6590} 6591~~~ 6592 6593### bdev_virtio_detach_controller {#rpc_bdev_virtio_detach_controller} 6594 6595Remove a Virtio device. This command can be used to remove any type of virtio device. 6596 6597#### Parameters 6598 6599Name | Optional | Type | Description 6600----------------------- | -------- | ----------- | ----------- 6601name | Required | string | Virtio name 6602 6603#### Example 6604 6605Example request: 6606 6607~~~json 6608{ 6609 "params": { 6610 "name": "VirtioUser0" 6611 }, 6612 "jsonrpc": "2.0", 6613 "method": "bdev_virtio_detach_controller", 6614 "id": 1 6615} 6616 6617~~~ 6618 6619Example response: 6620 6621~~~json 6622{ 6623 "jsonrpc": "2.0", 6624 "id": 1, 6625 "result": true 6626} 6627~~~ 6628 6629### bdev_virtio_blk_set_hotplug {#rpc_bdev_virtio_blk_set_hotplug} 6630 6631Enable/Disable the virtio blk hotplug monitor or change the monitor period time 6632 6633#### Parameters 6634 6635Name | Optional | Type | Description 6636----------------------- | -------- | ----------- | ----------- 6637enable | Required | bool | Enable or disable the virtio blk hotplug monitor 6638period-us | Optional | number | The period time of the monitor 6639 6640When the enable is true then the period-us is optional. If user don't set the period time then use the default 6641value. When the enable is false then the period-us is not required. 6642 6643#### Result 6644 6645True the rpc is successful otherwise false 6646 6647#### Example 6648 6649Example request: 6650 6651~~~json 6652{ 6653 "params": { 6654 "enable": "true", 6655 "period-us": "1000000" 6656 }, 6657 "jsonrpc": "2.0", 6658 "method": "bdev_virtio_blk_set_hotplug", 6659 "id": 1 6660} 6661~~~ 6662 6663Example response: 6664 6665~~~json 6666{ 6667 "jsonrpc": "2.0", 6668 "id": 1, 6669 "result": true 6670} 6671~~~ 6672 6673## iSCSI Target {#jsonrpc_components_iscsi_tgt} 6674 6675### iscsi_set_options method {#rpc_iscsi_set_options} 6676 6677Set global parameters for iSCSI targets. 6678 6679This RPC may only be called before SPDK subsystems have been initialized. This RPC can be called only once. 6680 6681#### Parameters 6682 6683Name | Optional | Type | Description 6684------------------------------- | -------- | ------- | ----------- 6685auth_file | Optional | string | Path to CHAP shared secret file (default: "") 6686node_base | Optional | string | Prefix of the name of iSCSI target node (default: "iqn.2016-06.io.spdk") 6687nop_timeout | Optional | number | Timeout in seconds to nop-in request to the initiator (default: 60) 6688nop_in_interval | Optional | number | Time interval in secs between nop-in requests by the target (default: 30) 6689disable_chap | Optional | boolean | CHAP for discovery session should be disabled (default: `false`) 6690require_chap | Optional | boolean | CHAP for discovery session should be required (default: `false`) 6691mutual_chap | Optional | boolean | CHAP for discovery session should be unidirectional (`false`) or bidirectional (`true`) (default: `false`) 6692chap_group | Optional | number | CHAP group ID for discovery session (default: 0) 6693max_sessions | Optional | number | Maximum number of sessions in the host (default: 128) 6694max_queue_depth | Optional | number | Maximum number of outstanding I/Os per queue (default: 64) 6695max_connections_per_session | Optional | number | Session specific parameter, MaxConnections (default: 2) 6696default_time2wait | Optional | number | Session specific parameter, DefaultTime2Wait (default: 2) 6697default_time2retain | Optional | number | Session specific parameter, DefaultTime2Retain (default: 20) 6698first_burst_length | Optional | number | Session specific parameter, FirstBurstLength (default: 8192) 6699immediate_data | Optional | boolean | Session specific parameter, ImmediateData (default: `true`) 6700error_recovery_level | Optional | number | Session specific parameter, ErrorRecoveryLevel (default: 0) 6701allow_duplicated_isid | Optional | boolean | Allow duplicated initiator session ID (default: `false`) 6702max_large_datain_per_connection | Optional | number | Max number of outstanding split read I/Os per connection (default: 64) 6703max_r2t_per_connection | Optional | number | Max number of outstanding R2Ts per connection (default: 4) 6704pdu_pool_size | Optional | number | Number of PDUs in the pool (default: approximately 2 * max_sessions * (max_queue_depth + max_connections_per_session)) 6705immediate_data_pool_size | Optional | number | Number of immediate data buffers in the pool (default: 128 * max_sessions) 6706data_out_pool_size | Optional | number | Number of data out buffers in the pool (default: 16 * max_sessions) 6707 6708To load CHAP shared secret file, its path is required to specify explicitly in the parameter `auth_file`. 6709 6710Parameters `disable_chap` and `require_chap` are mutually exclusive. Parameters `no_discovery_auth`, `req_discovery_auth`, 6711`req_discovery_auth_mutual`, and `discovery_auth_group` are still available instead of `disable_chap`, `require_chap`, 6712`mutual_chap`, and `chap_group`, respectivey but will be removed in future releases. 6713 6714#### Example 6715 6716Example request: 6717 6718~~~json 6719{ 6720 "params": { 6721 "allow_duplicated_isid": true, 6722 "default_time2retain": 60, 6723 "first_burst_length": 8192, 6724 "immediate_data": true, 6725 "node_base": "iqn.2016-06.io.spdk", 6726 "max_sessions": 128, 6727 "nop_timeout": 30, 6728 "nop_in_interval": 30, 6729 "auth_file": "/usr/local/etc/spdk/auth.conf", 6730 "disable_chap": true, 6731 "default_time2wait": 2 6732 }, 6733 "jsonrpc": "2.0", 6734 "method": "iscsi_set_options", 6735 "id": 1 6736} 6737~~~ 6738 6739Example response: 6740 6741~~~json 6742{ 6743 "jsonrpc": "2.0", 6744 "id": 1, 6745 "result": true 6746} 6747~~~ 6748 6749### iscsi_get_options method {#rpc_iscsi_get_options} 6750 6751Show global parameters of iSCSI targets. 6752 6753#### Parameters 6754 6755This method has no parameters. 6756 6757#### Example 6758 6759Example request: 6760 6761~~~json 6762request: 6763{ 6764 "jsonrpc": "2.0", 6765 "method": "iscsi_get_options", 6766 "id": 1 6767} 6768~~~ 6769 6770Example response: 6771 6772~~~json 6773{ 6774 "jsonrpc": "2.0", 6775 "id": 1, 6776 "result": { 6777 "allow_duplicated_isid": true, 6778 "default_time2retain": 60, 6779 "first_burst_length": 8192, 6780 "immediate_data": true, 6781 "node_base": "iqn.2016-06.io.spdk", 6782 "mutual_chap": false, 6783 "nop_in_interval": 30, 6784 "chap_group": 0, 6785 "max_connections_per_session": 2, 6786 "max_queue_depth": 64, 6787 "nop_timeout": 30, 6788 "max_sessions": 128, 6789 "error_recovery_level": 0, 6790 "auth_file": "/usr/local/etc/spdk/auth.conf", 6791 "disable_chap": true, 6792 "default_time2wait": 2, 6793 "require_chap": false, 6794 "max_large_datain_per_connection": 64, 6795 "max_r2t_per_connection": 4 6796 } 6797} 6798~~~ 6799 6800### scsi_get_devices {#rpc_scsi_get_devices} 6801 6802Display SCSI devices 6803 6804#### Parameters 6805 6806This method has no parameters. 6807 6808#### Example 6809 6810Example request: 6811 6812~~~json 6813{ 6814 "jsonrpc": "2.0", 6815 "method": "scsi_get_devices", 6816 "id": 1 6817} 6818~~~ 6819 6820Example response: 6821 6822~~~json 6823{ 6824 "jsonrpc": "2.0", 6825 "id": 1, 6826 "result": [ 6827 { 6828 "id": 0, 6829 "device_name": "iqn.2016-06.io.spdk:Target3" 6830 } 6831 ] 6832} 6833~~~ 6834 6835### iscsi_set_discovery_auth method {#rpc_iscsi_set_discovery_auth} 6836 6837Set CHAP authentication for sessions dynamically. 6838 6839#### Parameters 6840 6841Name | Optional | Type | Description 6842--------------------------- | -------- | --------| ----------- 6843disable_chap | Optional | boolean | CHAP for discovery session should be disabled (default: `false`) 6844require_chap | Optional | boolean | CHAP for discovery session should be required (default: `false`) 6845mutual_chap | Optional | boolean | CHAP for discovery session should be unidirectional (`false`) or bidirectional (`true`) (default: `false`) 6846chap_group | Optional | number | CHAP group ID for discovery session (default: 0) 6847 6848Parameters `disable_chap` and `require_chap` are mutually exclusive. 6849 6850#### Example 6851 6852Example request: 6853 6854~~~json 6855request: 6856{ 6857 "params": { 6858 "chap_group": 1, 6859 "require_chap": true, 6860 "mutual_chap": true 6861 }, 6862 "jsonrpc": "2.0", 6863 "method": "iscsi_set_discovery_auth", 6864 "id": 1 6865} 6866~~~ 6867 6868Example response: 6869 6870~~~json 6871{ 6872 "jsonrpc": "2.0", 6873 "id": 1, 6874 "result": true 6875} 6876~~~ 6877 6878### iscsi_create_auth_group method {#rpc_iscsi_create_auth_group} 6879 6880Create an authentication group for CHAP authentication. 6881 6882#### Parameters 6883 6884Name | Optional | Type | Description 6885--------------------------- | -------- | --------| ----------- 6886tag | Required | number | Authentication group tag (unique, integer > 0) 6887secrets | Optional | array | Array of @ref rpc_iscsi_create_auth_group_secret objects 6888 6889#### secret {#rpc_iscsi_create_auth_group_secret} 6890 6891Name | Optional | Type | Description 6892--------------------------- | ---------| --------| ----------- 6893user | Required | string | Unidirectional CHAP name 6894secret | Required | string | Unidirectional CHAP secret 6895muser | Optional | string | Bidirectional CHAP name 6896msecret | Optional | string | Bidirectional CHAP secret 6897 6898#### Example 6899 6900Example request: 6901 6902~~~json 6903{ 6904 "params": { 6905 "secrets": [ 6906 { 6907 "muser": "mu1", 6908 "secret": "s1", 6909 "user": "u1", 6910 "msecret": "ms1" 6911 } 6912 ], 6913 "tag": 2 6914 }, 6915 "jsonrpc": "2.0", 6916 "method": "iscsi_create_auth_group", 6917 "id": 1 6918} 6919~~~ 6920 6921Example response: 6922 6923~~~json 6924{ 6925 "jsonrpc": "2.0", 6926 "id": 1, 6927 "result": true 6928} 6929~~~ 6930 6931### iscsi_delete_auth_group method {#rpc_iscsi_delete_auth_group} 6932 6933Delete an existing authentication group for CHAP authentication. 6934 6935#### Parameters 6936 6937Name | Optional | Type | Description 6938--------------------------- | -------- | --------| ----------- 6939tag | Required | number | Authentication group tag (unique, integer > 0) 6940 6941#### Example 6942 6943Example request: 6944 6945~~~json 6946{ 6947 "params": { 6948 "tag": 2 6949 }, 6950 "jsonrpc": "2.0", 6951 "method": "iscsi_delete_auth_group", 6952 "id": 1 6953} 6954~~~ 6955 6956Example response: 6957 6958~~~json 6959{ 6960 "jsonrpc": "2.0", 6961 "id": 1, 6962 "result": true 6963} 6964~~~ 6965 6966### iscsi_get_auth_groups {#rpc_iscsi_get_auth_groups} 6967 6968Show information about all existing authentication group for CHAP authentication. 6969 6970#### Parameters 6971 6972This method has no parameters. 6973 6974#### Result 6975 6976Array of objects describing authentication group. 6977 6978Name | Type | Description 6979--------------------------- | --------| ----------- 6980tag | number | Authentication group tag 6981secrets | array | Array of @ref rpc_iscsi_create_auth_group_secret objects 6982 6983#### Example 6984 6985Example request: 6986 6987~~~json 6988{ 6989 "jsonrpc": "2.0", 6990 "method": "iscsi_get_auth_groups", 6991 "id": 1 6992} 6993~~~ 6994 6995Example response: 6996 6997~~~json 6998{ 6999 "jsonrpc": "2.0", 7000 "id": 1, 7001 "result": [ 7002 { 7003 "secrets": [ 7004 { 7005 "muser": "mu1", 7006 "secret": "s1", 7007 "user": "u1", 7008 "msecret": "ms1" 7009 } 7010 ], 7011 "tag": 1 7012 }, 7013 { 7014 "secrets": [ 7015 { 7016 "secret": "s2", 7017 "user": "u2" 7018 } 7019 ], 7020 "tag": 2 7021 } 7022 ] 7023} 7024~~~ 7025 7026### iscsi_auth_group_add_secret {#rpc_iscsi_auth_group_add_secret} 7027 7028Add a secret to an existing authentication group for CHAP authentication. 7029 7030#### Parameters 7031 7032Name | Optional | Type | Description 7033--------------------------- | -------- | --------| ----------- 7034tag | Required | number | Authentication group tag (unique, integer > 0) 7035user | Required | string | Unidirectional CHAP name 7036secret | Required | string | Unidirectional CHAP secret 7037muser | Optional | string | Bidirectional CHAP name 7038msecret | Optional | string | Bidirectional CHAP secret 7039 7040#### Example 7041 7042Example request: 7043 7044~~~json 7045{ 7046 "params": { 7047 "muser": "mu3", 7048 "secret": "s3", 7049 "tag": 2, 7050 "user": "u3", 7051 "msecret": "ms3" 7052 }, 7053 "jsonrpc": "2.0", 7054 "method": "iscsi_auth_group_add_secret", 7055 "id": 1 7056} 7057~~~json 7058 7059Example response: 7060 7061~~~json 7062{ 7063 "jsonrpc": "2.0", 7064 "id": 1, 7065 "result": true 7066} 7067~~~ 7068 7069### iscsi_auth_group_remove_secret {#rpc_iscsi_auth_group_remove_secret} 7070 7071Remove a secret from an existing authentication group for CHAP authentication. 7072 7073#### Parameters 7074 7075Name | Optional | Type | Description 7076--------------------------- | -------- | --------| ----------- 7077tag | Required | number | Authentication group tag (unique, integer > 0) 7078user | Required | string | Unidirectional CHAP name 7079 7080#### Example 7081 7082Example request: 7083 7084~~~json 7085{ 7086 "params": { 7087 "tag": 2, 7088 "user": "u3" 7089 }, 7090 "jsonrpc": "2.0", 7091 "method": "iscsi_auth_group_remove_secret", 7092 "id": 1 7093} 7094~~~ 7095 7096Example response: 7097 7098~~~json 7099{ 7100 "jsonrpc": "2.0", 7101 "id": 1, 7102 "result": true 7103} 7104~~~ 7105 7106### iscsi_get_initiator_groups method {#rpc_iscsi_get_initiator_groups} 7107 7108Show information about all available initiator groups. 7109 7110#### Parameters 7111 7112This method has no parameters. 7113 7114#### Result 7115 7116Array of objects describing initiator groups. 7117 7118Name | Type | Description 7119--------------------------- | --------| ----------- 7120tag | number | Initiator group tag 7121initiators | array | Array of initiator hostnames or IP addresses 7122netmasks | array | Array of initiator netmasks 7123 7124#### Example 7125 7126Example request: 7127 7128~~~json 7129{ 7130 "jsonrpc": "2.0", 7131 "method": "iscsi_get_initiator_groups", 7132 "id": 1 7133} 7134~~~ 7135 7136Example response: 7137 7138~~~json 7139{ 7140 "jsonrpc": "2.0", 7141 "id": 1, 7142 "result": [ 7143 { 7144 "initiators": [ 7145 "iqn.2016-06.io.spdk:host1", 7146 "iqn.2016-06.io.spdk:host2" 7147 ], 7148 "tag": 1, 7149 "netmasks": [ 7150 "192.168.1.0/24" 7151 ] 7152 } 7153 ] 7154} 7155~~~ 7156 7157### iscsi_create_initiator_group method {#rpc_iscsi_create_initiator_group} 7158 7159Add an initiator group. 7160 7161#### Parameters 7162 7163Name | Optional | Type | Description 7164--------------------------- | -------- | --------| ----------- 7165tag | Required | number | Initiator group tag (unique, integer > 0) 7166initiators | Required | array | Not empty array of initiator hostnames or IP addresses 7167netmasks | Required | array | Not empty array of initiator netmasks 7168 7169#### Example 7170 7171Example request: 7172 7173~~~json 7174{ 7175 "params": { 7176 "initiators": [ 7177 "iqn.2016-06.io.spdk:host1", 7178 "iqn.2016-06.io.spdk:host2" 7179 ], 7180 "tag": 1, 7181 "netmasks": [ 7182 "192.168.1.0/24" 7183 ] 7184 }, 7185 "jsonrpc": "2.0", 7186 "method": "iscsi_create_initiator_group", 7187 "id": 1 7188} 7189~~~ 7190 7191Example response: 7192 7193~~~json 7194response: 7195{ 7196 "jsonrpc": "2.0", 7197 "id": 1, 7198 "result": true 7199} 7200~~~ 7201 7202### iscsi_delete_initiator_group method {#rpc_iscsi_delete_initiator_group} 7203 7204Delete an existing initiator group. 7205 7206#### Parameters 7207 7208Name | Optional | Type | Description 7209--------------------------- | -------- | --------| ----------- 7210tag | Required | number | Initiator group tag (unique, integer > 0) 7211 7212#### Example 7213 7214Example request: 7215 7216~~~json 7217{ 7218 "params": { 7219 "tag": 1 7220 }, 7221 "jsonrpc": "2.0", 7222 "method": "iscsi_delete_initiator_group", 7223 "id": 1 7224} 7225~~~ 7226 7227Example response: 7228 7229~~~json 7230{ 7231 "jsonrpc": "2.0", 7232 "id": 1, 7233 "result": true 7234} 7235~~~ 7236 7237### iscsi_initiator_group_add_initiators method {#rpc_iscsi_initiator_group_add_initiators} 7238 7239Add initiators to an existing initiator group. 7240 7241#### Parameters 7242 7243Name | Optional | Type | Description 7244--------------------------- | -------- | --------| ----------- 7245tag | Required | number | Existing initiator group tag. 7246initiators | Optional | array | Array of initiator hostnames or IP addresses 7247netmasks | Optional | array | Array of initiator netmasks 7248 7249#### Example 7250 7251Example request: 7252 7253~~~json 7254request: 7255{ 7256 "params": { 7257 "initiators": [ 7258 "iqn.2016-06.io.spdk:host3" 7259 ], 7260 "tag": 1, 7261 "netmasks": [ 7262 "255.255.255.1" 7263 ] 7264 }, 7265 "jsonrpc": "2.0", 7266 "method": "iscsi_initiator_group_add_initiators", 7267 "id": 1 7268} 7269~~~ 7270 7271Example response: 7272 7273~~~json 7274response: 7275{ 7276 "jsonrpc": "2.0", 7277 "id": 1, 7278 "result": true 7279} 7280~~~ 7281 7282### iscsi_initiator_group_remove_initiators method {#rpc_iscsi_initiator_group_remove_initiators} 7283 7284Remove initiators from an initiator group. 7285 7286#### Parameters 7287 7288Name | Optional | Type | Description 7289--------------------------- | -------- | --------| ----------- 7290tag | Required | number | Existing initiator group tag. 7291initiators | Optional | array | Array of initiator hostnames or IP addresses 7292netmasks | Optional | array | Array of initiator netmasks 7293 7294#### Example 7295 7296Example request: 7297 7298~~~json 7299request: 7300{ 7301 "params": { 7302 "initiators": [ 7303 "iqn.2016-06.io.spdk:host3" 7304 ], 7305 "tag": 1, 7306 "netmasks": [ 7307 "255.255.255.1" 7308 ] 7309 }, 7310 "jsonrpc": "2.0", 7311 "method": "iscsi_initiator_group_remove_initiators", 7312 "id": 1 7313} 7314~~~ 7315 7316Example response: 7317 7318~~~json 7319response: 7320{ 7321 "jsonrpc": "2.0", 7322 "id": 1, 7323 "result": true 7324} 7325~~~ 7326 7327### iscsi_get_target_nodes method {#rpc_iscsi_get_target_nodes} 7328 7329Show information about all available iSCSI target nodes. 7330 7331#### Parameters 7332 7333This method has no parameters. 7334 7335#### Result 7336 7337Array of objects describing target node. 7338 7339Name | Type | Description 7340--------------------------- | --------| ----------- 7341name | string | Target node name (ASCII) 7342alias_name | string | Target node alias name (ASCII) 7343pg_ig_maps | array | Array of Portal_Group_Tag:Initiator_Group_Tag mappings 7344luns | array | Array of Bdev names to LUN ID mappings 7345queue_depth | number | Target queue depth 7346disable_chap | boolean | CHAP authentication should be disabled for this target 7347require_chap | boolean | CHAP authentication should be required for this target 7348mutual_chap | boolean | CHAP authentication should be bidirectional (`true`) or unidirectional (`false`) 7349chap_group | number | Authentication group ID for this target node 7350header_digest | boolean | Header Digest should be required for this target node 7351data_digest | boolean | Data Digest should be required for this target node 7352 7353#### Example 7354 7355Example request: 7356 7357~~~json 7358{ 7359 "jsonrpc": "2.0", 7360 "method": "iscsi_get_target_nodes", 7361 "id": 1 7362} 7363~~~ 7364 7365Example response: 7366 7367~~~json 7368{ 7369 "jsonrpc": "2.0", 7370 "id": 1, 7371 "result": [ 7372 { 7373 "luns": [ 7374 { 7375 "lun_id": 0, 7376 "bdev_name": "Nvme0n1" 7377 } 7378 ], 7379 "mutual_chap": false, 7380 "name": "iqn.2016-06.io.spdk:target1", 7381 "alias_name": "iscsi-target1-alias", 7382 "require_chap": false, 7383 "chap_group": 0, 7384 "pg_ig_maps": [ 7385 { 7386 "ig_tag": 1, 7387 "pg_tag": 1 7388 } 7389 ], 7390 "data_digest": false, 7391 "disable_chap": false, 7392 "header_digest": false, 7393 "queue_depth": 64 7394 } 7395 ] 7396} 7397~~~ 7398 7399### iscsi_create_target_node method {#rpc_iscsi_create_target_node} 7400 7401Add an iSCSI target node. 7402 7403#### Parameters 7404 7405Name | Optional | Type | Description 7406--------------------------- | -------- | --------| ----------- 7407name | Required | string | Target node name (ASCII) 7408alias_name | Required | string | Target node alias name (ASCII) 7409pg_ig_maps | Required | array | Array of (Portal_Group_Tag:Initiator_Group_Tag) mappings 7410luns | Required | array | Array of Bdev names to LUN ID mappings 7411queue_depth | Required | number | Target queue depth 7412disable_chap | Optional | boolean | CHAP authentication should be disabled for this target 7413require_chap | Optional | boolean | CHAP authentication should be required for this target 7414mutual_chap | Optional | boolean | CHAP authentication should be bidirectional (`true`) or unidirectional (`false`) 7415chap_group | Optional | number | Authentication group ID for this target node 7416header_digest | Optional | boolean | Header Digest should be required for this target node 7417data_digest | Optional | boolean | Data Digest should be required for this target node 7418 7419Parameters `disable_chap` and `require_chap` are mutually exclusive. 7420 7421#### Example 7422 7423Example request: 7424 7425~~~json 7426{ 7427 "params": { 7428 "luns": [ 7429 { 7430 "lun_id": 0, 7431 "bdev_name": "Nvme0n1" 7432 } 7433 ], 7434 "mutual_chap": true, 7435 "name": "target2", 7436 "alias_name": "iscsi-target2-alias", 7437 "pg_ig_maps": [ 7438 { 7439 "ig_tag": 1, 7440 "pg_tag": 1 7441 }, 7442 { 7443 "ig_tag": 2, 7444 "pg_tag": 2 7445 } 7446 ], 7447 "data_digest": true, 7448 "disable_chap": true, 7449 "header_digest": true, 7450 "queue_depth": 24 7451 }, 7452 "jsonrpc": "2.0", 7453 "method": "iscsi_create_target_node", 7454 "id": 1 7455} 7456~~~ 7457 7458Example response: 7459 7460~~~json 7461{ 7462 "jsonrpc": "2.0", 7463 "id": 1, 7464 "result": true 7465} 7466~~~ 7467 7468### iscsi_target_node_set_auth method {#rpc_iscsi_target_node_set_auth} 7469 7470Set CHAP authentication to an existing iSCSI target node. 7471 7472#### Parameters 7473 7474Name | Optional | Type | Description 7475--------------------------- | -------- | --------| ----------- 7476name | Required | string | Target node name (ASCII) 7477disable_chap | Optional | boolean | CHAP authentication should be disabled for this target 7478require_chap | Optional | boolean | CHAP authentication should be required for this target 7479mutual_chap | Optional | boolean | CHAP authentication should be bidirectional (`true`) or unidirectional (`false`) 7480chap_group | Optional | number | Authentication group ID for this target node 7481 7482Parameters `disable_chap` and `require_chap` are mutually exclusive. 7483 7484#### Example 7485 7486Example request: 7487 7488~~~json 7489{ 7490 "params": { 7491 "chap_group": 1, 7492 "require_chap": true, 7493 "name": "iqn.2016-06.io.spdk:target1", 7494 "mutual_chap": true 7495 }, 7496 "jsonrpc": "2.0", 7497 "method": "iscsi_target_node_set_auth", 7498 "id": 1 7499} 7500~~~ 7501 7502Example response: 7503 7504~~~json 7505{ 7506 "jsonrpc": "2.0", 7507 "id": 1, 7508 "result": true 7509} 7510~~~ 7511 7512### iscsi_target_node_add_pg_ig_maps method {#rpc_iscsi_target_node_add_pg_ig_maps} 7513 7514Add initiator group to portal group mappings to an existing iSCSI target node. 7515 7516#### Parameters 7517 7518Name | Optional | Type | Description 7519--------------------------- | -------- | --------| ----------- 7520name | Required | string | Target node name (ASCII) 7521pg_ig_maps | Required | array | Not empty array of initiator to portal group mappings objects 7522 7523Portal to Initiator group mappings object: 7524 7525Name | Optional | Type | Description 7526--------------------------- | -------- | --------| ----------- 7527ig_tag | Required | number | Existing initiator group tag 7528pg_tag | Required | number | Existing portal group tag 7529 7530#### Example 7531 7532Example request: 7533 7534~~~json 7535{ 7536 "params": { 7537 "pg_ig_maps": [ 7538 { 7539 "ig_tag": 1, 7540 "pg_tag": 1 7541 }, 7542 { 7543 "ig_tag": 2, 7544 "pg_tag": 2 7545 }, 7546 { 7547 "ig_tag": 3, 7548 "pg_tag": 3 7549 } 7550 ], 7551 "name": "iqn.2016-06.io.spdk:target3" 7552 }, 7553 "jsonrpc": "2.0", 7554 "method": "iscsi_target_node_add_pg_ig_maps", 7555 "id": 1 7556} 7557~~~ 7558 7559Example response: 7560 7561~~~json 7562{ 7563 "jsonrpc": "2.0", 7564 "id": 1, 7565 "result": true 7566} 7567~~~ 7568 7569### iscsi_target_node_remove_pg_ig_maps method {#rpc_iscsi_target_node_remove_pg_ig_maps} 7570 7571Delete initiator group to portal group mappings from an existing iSCSI target node. 7572 7573#### Parameters 7574 7575Name | Optional | Type | Description 7576--------------------------- | -------- | --------| ----------- 7577name | Required | string | Target node name (ASCII) 7578pg_ig_maps | Required | array | Not empty array of Portal to Initiator group mappings objects 7579 7580Portal to Initiator group mappings object: 7581 7582Name | Optional | Type | Description 7583--------------------------- | -------- | --------| ----------- 7584ig_tag | Required | number | Existing initiator group tag 7585pg_tag | Required | number | Existing portal group tag 7586 7587#### Example 7588 7589Example request: 7590 7591~~~json 7592{ 7593 "params": { 7594 "pg_ig_maps": [ 7595 { 7596 "ig_tag": 1, 7597 "pg_tag": 1 7598 }, 7599 { 7600 "ig_tag": 2, 7601 "pg_tag": 2 7602 }, 7603 { 7604 "ig_tag": 3, 7605 "pg_tag": 3 7606 } 7607 ], 7608 "name": "iqn.2016-06.io.spdk:target3" 7609 }, 7610 "jsonrpc": "2.0", 7611 "method": "iscsi_target_node_remove_pg_ig_maps", 7612 "id": 1 7613} 7614~~~ 7615 7616Example response: 7617 7618~~~json 7619{ 7620 "jsonrpc": "2.0", 7621 "id": 1, 7622 "result": true 7623} 7624~~~ 7625 7626### iscsi_delete_target_node method {#rpc_iscsi_delete_target_node} 7627 7628Delete an iSCSI target node. 7629 7630#### Parameters 7631 7632Name | Optional | Type | Description 7633--------------------------- | -------- | --------| ----------- 7634name | Required | string | Target node name (ASCII) 7635 7636#### Example 7637 7638Example request: 7639 7640~~~json 7641{ 7642 "params": { 7643 "name": "iqn.2016-06.io.spdk:target1" 7644 }, 7645 "jsonrpc": "2.0", 7646 "method": "iscsi_delete_target_node", 7647 "id": 1 7648} 7649~~~ 7650 7651Example response: 7652 7653~~~json 7654{ 7655 "jsonrpc": "2.0", 7656 "id": 1, 7657 "result": true 7658} 7659~~~ 7660 7661### iscsi_get_portal_groups method {#rpc_iscsi_get_portal_groups} 7662 7663Show information about all available portal groups. 7664 7665#### Parameters 7666 7667This method has no parameters. 7668 7669#### Example 7670 7671Example request: 7672 7673~~~json 7674request: 7675{ 7676 "jsonrpc": "2.0", 7677 "method": "iscsi_get_portal_groups", 7678 "id": 1 7679} 7680~~~ 7681 7682Example response: 7683 7684~~~json 7685{ 7686 "jsonrpc": "2.0", 7687 "id": 1, 7688 "result": [ 7689 { 7690 "portals": [ 7691 { 7692 "host": "127.0.0.1", 7693 "port": "3260" 7694 } 7695 ], 7696 "tag": 1, 7697 "private": false 7698 } 7699 ] 7700} 7701~~~ 7702 7703### iscsi_create_portal_group method {#rpc_iscsi_create_portal_group} 7704 7705Add a portal group. 7706 7707#### Parameters 7708 7709Name | Optional | Type | Description 7710--------------------------- | -------- | --------| ----------- 7711tag | Required | number | Portal group tag 7712portals | Required | array | Not empty array of portals 7713private | Optional | boolean | When true, portals in this group are not returned by a discovery session. Used for login redirection. (default: `false`) 7714wait | Optional | boolean | When true, do not listen on portals until it is started explicitly. (default: `false`) 7715 7716Portal object 7717 7718Name | Optional | Type | Description 7719--------------------------- | -------- | --------| ----------- 7720host | Required | string | Hostname or IP address 7721port | Required | string | Port number 7722 7723#### Example 7724 7725Example request: 7726 7727~~~json 7728{ 7729 "params": { 7730 "portals": [ 7731 { 7732 "host": "127.0.0.1", 7733 "port": "3260" 7734 } 7735 ], 7736 "tag": 1 7737 }, 7738 "jsonrpc": "2.0", 7739 "method": "iscsi_create_portal_group", 7740 "id": 1 7741} 7742~~~ 7743 7744Example response: 7745 7746~~~json 7747{ 7748 "jsonrpc": "2.0", 7749 "id": 1, 7750 "result": true 7751} 7752~~~ 7753 7754### iscsi_start_portal_group method {#rpc_iscsi_start_portal_group} 7755 7756Start listening on portals if the portal group is not started yet, or do nothing 7757if the portal group already started. Return a success response for both cases. 7758 7759#### Parameters 7760 7761Name | Optional | Type | Description 7762--------------------------- | -------- | --------| ----------- 7763tag | Required | number | Existing portal group tag 7764 7765#### Example 7766 7767Example request: 7768 7769~~~json 7770{ 7771 "params": { 7772 "tag": 1 7773 }, 7774 "jsonrpc": "2.0", 7775 "method": "iscsi_start_portal_group", 7776 "id": 1 7777} 7778~~~ 7779 7780Example response: 7781 7782~~~json 7783{ 7784 "jsonrpc": "2.0", 7785 "id": 1, 7786 "result": true 7787} 7788~~~ 7789 7790### iscsi_delete_portal_group method {#rpc_iscsi_delete_portal_group} 7791 7792Delete an existing portal group. 7793 7794#### Parameters 7795 7796Name | Optional | Type | Description 7797--------------------------- | -------- | --------| ----------- 7798tag | Required | number | Existing portal group tag 7799 7800#### Example 7801 7802Example request: 7803 7804~~~json 7805{ 7806 "params": { 7807 "tag": 1 7808 }, 7809 "jsonrpc": "2.0", 7810 "method": "iscsi_delete_portal_group", 7811 "id": 1 7812} 7813~~~ 7814 7815Example response: 7816 7817~~~json 7818{ 7819 "jsonrpc": "2.0", 7820 "id": 1, 7821 "result": true 7822} 7823~~~ 7824 7825### iscsi_portal_group_set_auth method {#rpc_iscsi_portal_group_set_auth} 7826 7827Set CHAP authentication for discovery sessions specific for the existing iSCSI portal group. 7828This RPC overwrites the setting by the global parameters for the iSCSI portal group. 7829 7830#### Parameters 7831 7832Name | Optional | Type | Description 7833--------------------------- | -------- | --------| ----------- 7834disable_chap | Optional | boolean | CHAP for discovery session should be disabled (default: `false`) 7835require_chap | Optional | boolean | CHAP for discovery session should be required (default: `false`) 7836mutual_chap | Optional | boolean | CHAP for discovery session should be unidirectional (`false`) or bidirectional (`true`) (default: `false`) 7837chap_group | Optional | number | CHAP group ID for discovery session (default: 0) 7838 7839Parameters `disable_chap` and `require_chap` are mutually exclusive. 7840 7841#### Example 7842 7843Example request: 7844 7845~~~json 7846request: 7847{ 7848 "params": { 7849 "tag": 1, 7850 "chap_group": 1, 7851 "require_chap": true, 7852 "mutual_chap": true 7853 }, 7854 "jsonrpc": "2.0", 7855 "method": "iscsi_portal_group_set_auth", 7856 "id": 1 7857} 7858~~~ 7859 7860Example response: 7861 7862~~~json 7863{ 7864 "jsonrpc": "2.0", 7865 "id": 1, 7866 "result": true 7867} 7868~~~ 7869 7870### iscsi_get_connections method {#rpc_iscsi_get_connections} 7871 7872Show information about all active connections. 7873 7874#### Parameters 7875 7876This method has no parameters. 7877 7878#### Results 7879 7880Array of objects describing iSCSI connection. 7881 7882Name | Type | Description 7883--------------------------- | --------| ----------- 7884id | number | Index (used for TTT - Target Transfer Tag) 7885cid | number | CID (Connection ID) 7886tsih | number | TSIH (Target Session Identifying Handle) 7887lcore_id | number | Core number on which the iSCSI connection runs 7888initiator_addr | string | Initiator address 7889target_addr | string | Target address 7890target_node_name | string | Target node name (ASCII) without prefix 7891 7892#### Example 7893 7894Example request: 7895 7896~~~json 7897{ 7898 "jsonrpc": "2.0", 7899 "method": "iscsi_get_connections", 7900 "id": 1 7901} 7902~~~ 7903 7904Example response: 7905 7906~~~json 7907{ 7908 "jsonrpc": "2.0", 7909 "id": 1, 7910 "result": [ 7911 { 7912 "tsih": 4, 7913 "cid": 0, 7914 "target_node_name": "target1", 7915 "lcore_id": 0, 7916 "initiator_addr": "10.0.0.2", 7917 "target_addr": "10.0.0.1", 7918 "id": 0 7919 } 7920 ] 7921} 7922~~~ 7923 7924### iscsi_get_stats method {#iscsi_get_stats} 7925 7926Show stat information of iSCSI connections. 7927 7928#### Parameters 7929 7930This method has no parameters. 7931 7932#### Results 7933 7934Stat information of iSCSI connections. 7935 7936Name | Type | Description 7937--------------------------- | --------| ----------- 7938invalid | number | The number of invalid connections 7939running | number | The number of running connections 7940exiting | number | The number of exiting connections 7941exited | number | The number of exited connections 7942 7943#### Example 7944 7945Example request: 7946 7947~~~json 7948{ 7949 "jsonrpc": "2.0", 7950 "method": "iscsi_get_stats", 7951 "id": 1 7952} 7953~~~ 7954 7955Example response: 7956 7957~~~json 7958{ 7959 "jsonrpc": "2.0", 7960 "id": 1, 7961 "result": 7962 { 7963 "invalid": 0, 7964 "running": 5, 7965 "exiting": 0, 7966 "exited": 0 7967 } 7968 7969} 7970~~~ 7971 7972### iscsi_target_node_add_lun method {#rpc_iscsi_target_node_add_lun} 7973 7974Add an LUN to an existing iSCSI target node. 7975 7976#### Parameters 7977 7978Name | Optional | Type | Description 7979--------------------------- | -------- | --------| ----------- 7980name | Required | string | Target node name (ASCII) 7981bdev_name | Required | string | bdev name to be added as a LUN 7982lun_id | Optional | number | LUN ID (default: first free ID) 7983 7984#### Example 7985 7986Example request: 7987 7988~~~json 7989{ 7990 "params": { 7991 "lun_id": 2, 7992 "name": "iqn.2016-06.io.spdk:target1", 7993 "bdev_name": "Malloc0" 7994 }, 7995 "jsonrpc": "2.0", 7996 "method": "iscsi_target_node_add_lun", 7997 "id": 1 7998} 7999~~~ 8000 8001Example response: 8002 8003~~~json 8004{ 8005 "jsonrpc": "2.0", 8006 "id": 1, 8007 "result": true 8008} 8009~~~ 8010 8011### iscsi_target_node_set_redirect method {#rpc_iscsi_target_node_set_redirect} 8012 8013Update redirect portal of the primary portal group for the target node, 8014 8015#### Parameters 8016 8017Name | Optional | Type | Description 8018--------------------------- | -------- | --------| ----------- 8019name | Required | string | Target node name (ASCII) 8020pg_tag | Required | number | Existing portal group tag 8021redirect_host | Optional | string | Numeric IP address to which the target node is redirected 8022redirect_port | Optional | string | Numeric TCP port to which the target node is redirected 8023 8024If both redirect_host and redirect_port are omitted, clear the redirect portal. 8025 8026#### Example 8027 8028Example request: 8029 8030~~~json 8031{ 8032 "params": { 8033 "name": "iqn.2016-06.io.spdk:target1", 8034 "pg_tag": 1, 8035 "redirect_host": "10.0.0.3", 8036 "redirect_port": "3260" 8037 }, 8038 "jsonrpc": "2.0", 8039 "method": "iscsi_target_node_set_redirect", 8040 "id": 1 8041} 8042~~~ 8043 8044Example response: 8045 8046~~~json 8047{ 8048 "jsonrpc": "2.0", 8049 "id": 1, 8050 "result": true 8051} 8052~~~ 8053 8054### iscsi_target_node_request_logout method {#rpc_iscsi_target_node_request_logout} 8055 8056For the target node, request connections whose portal group tag match to logout, 8057or request all connections to logout if portal group tag is omitted. 8058 8059#### Parameters 8060 8061Name | Optional | Type | Description 8062--------------------------- | -------- | --------| ----------- 8063name | Required | string | Target node name (ASCII) 8064pg_tag | Optional | number | Existing portal group tag 8065 8066#### Example 8067 8068Example request: 8069 8070~~~json 8071{ 8072 "params": { 8073 "name": "iqn.2016-06.io.spdk:target1", 8074 "pg_tag": 1 8075 }, 8076 "jsonrpc": "2.0", 8077 "method": "iscsi_target_node_request_logout", 8078 "id": 1 8079} 8080~~~ 8081 8082Example response: 8083 8084~~~json 8085{ 8086 "jsonrpc": "2.0", 8087 "id": 1, 8088 "result": true 8089} 8090~~~ 8091 8092### iscsi_enable_histogram {#rpc_iscsi_enable_histogram} 8093 8094Control whether collecting data for histogram is enabled for specified iscsi target node. 8095 8096#### Parameters 8097 8098Name | Optional | Type | Description 8099----------------------- | -------- | ----------- | ----------- 8100name | Required | string | Iscsi target node name 8101enable | Required | boolean | Enable or disable histogram on specified target node 8102 8103#### Example 8104 8105Example request: 8106 8107~~~json 8108{ 8109 "jsonrpc": "2.0", 8110 "id": 1, 8111 "method": "iscsi_enable_histogram", 8112 "params": { 8113 "name": "iqn.2016-06.io.spdk:target1" 8114 "enable": true 8115 } 8116} 8117~~~ 8118 8119Example response: 8120 8121~~~json 8122{ 8123 "jsonrpc": "2.0", 8124 "id": 1, 8125 "result": true 8126} 8127~~~ 8128 8129### iscsi_get_histogram {#rpc_iscsi_get_histogram} 8130 8131Get latency histogram for specified iscsi target node. 8132 8133#### Parameters 8134 8135Name | Optional | Type | Description 8136----------------------- | -------- | ----------- | ----------- 8137name | Required | string | Iscsi target node name 8138 8139#### Result 8140 8141Name | Description 8142------------------------| ----------- 8143histogram | Base64 encoded histogram 8144bucket_shift | Granularity of the histogram buckets 8145tsc_rate | Ticks per second 8146 8147#### Example 8148 8149Example request: 8150 8151~~~json 8152{ 8153 "jsonrpc": "2.0", 8154 "id": 1, 8155 "method": "iscsi_get_histogram", 8156 "params": { 8157 "name": "iqn.2016-06.io.spdk:target1" 8158 } 8159} 8160~~~ 8161 8162Example response: 8163Note that histogram field is trimmed, actual encoded histogram length is ~80kb. 8164 8165~~~json 8166{ 8167 "jsonrpc": "2.0", 8168 "id": 1, 8169 "result": { 8170 "histogram": "AAAAAAAAAAAAAA...AAAAAAAAA==", 8171 "tsc_rate": 2300000000, 8172 "bucket_shift": 7 8173 } 8174} 8175~~~ 8176 8177## NVMe-oF Target {#jsonrpc_components_nvmf_tgt} 8178 8179### nvmf_create_transport method {#rpc_nvmf_create_transport} 8180 8181Initialize an NVMe-oF transport with the given options. 8182 8183#### Parameters 8184 8185Name | Optional | Type | Description 8186--------------------------- | -------- | --------| ----------- 8187trtype | Required | string | Transport type (ex. RDMA) 8188tgt_name | Optional | string | Parent NVMe-oF target name. 8189max_queue_depth | Optional | number | Max number of outstanding I/O per queue 8190max_io_qpairs_per_ctrlr | Optional | number | Max number of IO qpairs per controller 8191in_capsule_data_size | Optional | number | Max number of in-capsule data size 8192max_io_size | Optional | number | Max I/O size (bytes) 8193io_unit_size | Optional | number | I/O unit size (bytes) 8194max_aq_depth | Optional | number | Max number of admin cmds per AQ 8195num_shared_buffers | Optional | number | The number of pooled data buffers available to the transport 8196buf_cache_size | Optional | number | The number of shared buffers to reserve for each poll group 8197num_cqe | Optional | number | The number of CQ entries. Only used when no_srq=true (RDMA only) 8198max_srq_depth | Optional | number | The number of elements in a per-thread shared receive queue (RDMA only) 8199no_srq | Optional | boolean | Disable shared receive queue even for devices that support it. (RDMA only) 8200c2h_success | Optional | boolean | Disable C2H success optimization (TCP only) 8201dif_insert_or_strip | Optional | boolean | Enable DIF insert for write I/O and DIF strip for read I/O DIF 8202sock_priority | Optional | number | The socket priority of the connection owned by this transport (TCP only) 8203acceptor_backlog | Optional | number | The number of pending connections allowed in backlog before failing new connection attempts (RDMA only) 8204abort_timeout_sec | Optional | number | Abort execution timeout value, in seconds 8205no_wr_batching | Optional | boolean | Disable work requests batching (RDMA only) 8206control_msg_num | Optional | number | The number of control messages per poll group (TCP only) 8207disable_mappable_bar0 | Optional | boolean | disable client mmap() of BAR0 (VFIO-USER only) 8208disable_adaptive_irq | Optional | boolean | Disable adaptive interrupt feature (VFIO-USER only) 8209disable_shadow_doorbells | Optional | boolean | disable shadow doorbell support (VFIO-USER only) 8210zcopy | Optional | boolean | Use zero-copy operations if the underlying bdev supports them 8211ack_timeout | Optional | number | ACK timeout in milliseconds 8212data_wr_pool_size | Optional | number | RDMA data WR pool size (RDMA only) 8213disable_command_passthru | Optional | boolean | Disallow command passthru. 8214 8215#### Example 8216 8217Example request: 8218 8219~~~json 8220{ 8221 "jsonrpc": "2.0", 8222 "method": "nvmf_create_transport", 8223 "id": 1, 8224 "params": { 8225 "trtype": "RDMA", 8226 "max_queue_depth": 32 8227 } 8228} 8229~~~ 8230 8231Example response: 8232 8233~~~json 8234{ 8235 "jsonrpc": "2.0", 8236 "id": 1, 8237 "result": true 8238} 8239~~~ 8240 8241### nvmf_get_subsystems method {#rpc_nvmf_get_subsystems} 8242 8243#### Parameters 8244 8245Name | Optional | Type | Description 8246--------------------------- | -------- | ------------| ----------- 8247tgt_name | Optional | string | Parent NVMe-oF target name. 8248 8249#### Example 8250 8251Example request: 8252 8253~~~json 8254{ 8255 "jsonrpc": "2.0", 8256 "id": 1, 8257 "method": "nvmf_get_subsystems" 8258} 8259~~~ 8260 8261Example response: 8262 8263~~~json 8264{ 8265 "jsonrpc": "2.0", 8266 "id": 1, 8267 "result": [ 8268 { 8269 "nqn": "nqn.2014-08.org.nvmexpress.discovery", 8270 "subtype": "Discovery" 8271 "listen_addresses": [], 8272 "hosts": [], 8273 "allow_any_host": true 8274 }, 8275 { 8276 "nqn": "nqn.2016-06.io.spdk:cnode1", 8277 "subtype": "NVMe", 8278 "listen_addresses": [ 8279 { 8280 "trtype": "RDMA", 8281 "adrfam": "IPv4", 8282 "traddr": "192.168.0.123", 8283 "trsvcid": "4420" 8284 } 8285 ], 8286 "hosts": [ 8287 {"nqn": "nqn.2016-06.io.spdk:host1"} 8288 ], 8289 "allow_any_host": false, 8290 "serial_number": "abcdef", 8291 "model_number": "ghijklmnop", 8292 "namespaces": [ 8293 {"nsid": 1, "name": "Malloc2"}, 8294 {"nsid": 2, "name": "Nvme0n1"} 8295 ] 8296 } 8297 ] 8298} 8299~~~ 8300 8301### nvmf_create_subsystem method {#rpc_nvmf_create_subsystem} 8302 8303Construct an NVMe over Fabrics target subsystem. 8304 8305#### Parameters 8306 8307Name | Optional | Type | Description 8308-------------------------- | -------- | ----------- | ----------- 8309nqn | Required | string | Subsystem NQN 8310tgt_name | Optional | string | Parent NVMe-oF target name. 8311serial_number | Optional | string | Serial number of virtual controller 8312model_number | Optional | string | Model number of virtual controller 8313max_namespaces | Optional | number | Maximum number of namespaces that can be attached to the subsystem. Default: 32 (also used if user specifies 0) 8314allow_any_host | Optional | boolean | Allow any host (`true`) or enforce allowed host list (`false`). Default: `false`. 8315ana_reporting | Optional | boolean | Enable ANA reporting feature (default: `false`). 8316min_cntlid | Optional | number | Minimum controller ID. Default: 1 8317max_cntlid | Optional | number | Maximum controller ID. Default: 0xffef 8318max_discard_size_kib | Optional | number | Maximum discard size (Kib). Default: 0 8319max_write_zeroes_size_kib | Optional | number | Maximum write_zeroes size (Kib). Default: 0 8320passthrough | Optional | boolean | Use NVMe passthrough for I/O commands and namespace-directed admin commands. Default: `false`. 8321 8322#### Example 8323 8324Example request: 8325 8326~~~json 8327{ 8328 "jsonrpc": "2.0", 8329 "id": 1, 8330 "method": "nvmf_create_subsystem", 8331 "params": { 8332 "nqn": "nqn.2016-06.io.spdk:cnode1", 8333 "allow_any_host": false, 8334 "serial_number": "abcdef", 8335 "model_number": "ghijklmnop" 8336 } 8337} 8338~~~ 8339 8340Example response: 8341 8342~~~json 8343{ 8344 "jsonrpc": "2.0", 8345 "id": 1, 8346 "result": true 8347} 8348~~~ 8349 8350### nvmf_delete_subsystem method {#rpc_nvmf_delete_subsystem} 8351 8352Delete an existing NVMe-oF subsystem. 8353 8354#### Parameters 8355 8356Parameter | Optional | Type | Description 8357---------------------- | -------- | ----------- | ----------- 8358nqn | Required | string | Subsystem NQN to delete. 8359tgt_name | Optional | string | Parent NVMe-oF target name. 8360 8361#### Example 8362 8363Example request: 8364 8365~~~json 8366{ 8367 "jsonrpc": "2.0", 8368 "id": 1, 8369 "method": "nvmf_delete_subsystem", 8370 "params": { 8371 "nqn": "nqn.2016-06.io.spdk:cnode1" 8372 } 8373} 8374~~~ 8375 8376Example response: 8377 8378~~~json 8379{ 8380 "jsonrpc": "2.0", 8381 "id": 1, 8382 "result": true 8383} 8384~~~ 8385 8386### nvmf_subsystem_add_listener method {#rpc_nvmf_subsystem_add_listener} 8387 8388Add a new listen address to an NVMe-oF subsystem. 8389 8390This method will fail if listener with given address already exists. 8391 8392#### Parameters 8393 8394Name | Optional | Type | Description 8395----------------------- | -------- | ----------- | ----------- 8396nqn | Required | string | Subsystem NQN 8397tgt_name | Optional | string | Parent NVMe-oF target name. 8398listen_address | Required | object | @ref rpc_nvmf_listen_address object 8399secure_channel | Optional | bool | Whether all connections immediately attempt to establish a secure channel 8400sock_impl | Optional | string | The socket implementation to use for the listener 8401 8402#### listen_address {#rpc_nvmf_listen_address} 8403 8404The listen_address is used for adding the listeners to the NVMe-oF target 8405and for referring to discovery services on other targets. 8406 8407Name | Optional | Type | Description 8408----------------------- | -------- | ----------- | ----------- 8409trtype | Required | string | Transport type ("RDMA") 8410adrfam | Optional | string | Address family ("IPv4", "IPv6", "IB", or "FC") 8411traddr | Required | string | Transport address 8412trsvcid | Optional | string | Transport service ID (required for RDMA or TCP) 8413 8414#### Example 8415 8416Example request: 8417 8418~~~json 8419{ 8420 "jsonrpc": "2.0", 8421 "id": 1, 8422 "method": "nvmf_subsystem_add_listener", 8423 "params": { 8424 "nqn": "nqn.2016-06.io.spdk:cnode1", 8425 "listen_address": { 8426 "trtype": "RDMA", 8427 "adrfam": "IPv4", 8428 "traddr": "192.168.0.123", 8429 "trsvcid": "4420" 8430 } 8431 } 8432} 8433~~~ 8434 8435Example response: 8436 8437~~~json 8438{ 8439 "jsonrpc": "2.0", 8440 "id": 1, 8441 "result": true 8442} 8443~~~ 8444 8445### nvmf_subsystem_remove_listener method {#rpc_nvmf_subsystem_remove_listener} 8446 8447Remove a listen address from an NVMe-oF subsystem. 8448 8449#### Parameters 8450 8451Name | Optional | Type | Description 8452----------------------- | -------- | ----------- | ----------- 8453nqn | Required | string | Subsystem NQN 8454tgt_name | Optional | string | Parent NVMe-oF target name. 8455listen_address | Required | object | @ref rpc_nvmf_listen_address object 8456 8457#### Example 8458 8459Example request: 8460 8461~~~json 8462{ 8463 "jsonrpc": "2.0", 8464 "id": 1, 8465 "method": "nvmf_subsystem_remove_listener", 8466 "params": { 8467 "nqn": "nqn.2016-06.io.spdk:cnode1", 8468 "listen_address": { 8469 "trtype": "RDMA", 8470 "adrfam": "IPv4", 8471 "traddr": "192.168.0.123", 8472 "trsvcid": "4420" 8473 } 8474 } 8475} 8476~~~ 8477 8478Example response: 8479 8480~~~json 8481{ 8482 "jsonrpc": "2.0", 8483 "id": 1, 8484 "result": true 8485} 8486~~~ 8487 8488### nvmf_subsystem_listener_set_ana_state method {#rpc_nvmf_subsystem_listener_set_ana_state} 8489 8490Set ANA state of a listener for an NVMe-oF subsystem. Only the ANA state of the specified ANA 8491group is updated, or ANA states of all ANA groups if ANA group is not specified. 8492 8493#### Parameters 8494 8495Name | Optional | Type | Description 8496----------------------- | -------- | ----------- | ----------- 8497nqn | Required | string | Subsystem NQN 8498tgt_name | Optional | string | Parent NVMe-oF target name. 8499listen_address | Required | object | @ref rpc_nvmf_listen_address object 8500ana_state | Required | string | ANA state to set ("optimized", "non_optimized", or "inaccessible") 8501anagrpid | Optional | number | ANA group ID 8502 8503#### Example 8504 8505Example request: 8506 8507~~~json 8508{ 8509 "jsonrpc": "2.0", 8510 "id": 1, 8511 "method": "nvmf_subsystem_listener_set_ana_state", 8512 "params": { 8513 "nqn": "nqn.2016-06.io.spdk:cnode1", 8514 "listen_address": { 8515 "trtype": "RDMA", 8516 "adrfam": "IPv4", 8517 "traddr": "192.168.0.123", 8518 "trsvcid": "4420" 8519 }, 8520 "ana_state", "inaccessible" 8521 } 8522} 8523~~~ 8524 8525Example response: 8526 8527~~~json 8528{ 8529 "jsonrpc": "2.0", 8530 "id": 1, 8531 "result": true 8532} 8533~~~ 8534 8535### nvmf_subsystem_add_ns method {#rpc_nvmf_subsystem_add_ns} 8536 8537Add a namespace to a subsystem. The namespace ID is returned as the result. 8538 8539### Parameters 8540 8541Name | Optional | Type | Description 8542----------------------- | -------- | ----------- | ----------- 8543nqn | Required | string | Subsystem NQN 8544namespace | Required | object | @ref rpc_nvmf_namespace object 8545tgt_name | Optional | string | Parent NVMe-oF target name. 8546no_auto_visible | Optional | bool | Namespace is not automatically visible to controllers (default: false) 8547 8548#### namespace {#rpc_nvmf_namespace} 8549 8550Name | Optional | Type | Description 8551----------------------- | -------- | ----------- | ----------- 8552nsid | Optional | number | Namespace ID between 1 and 4294967294, inclusive. Default: Automatically assign NSID. 8553bdev_name | Required | string | Name of bdev to expose as a namespace. 8554nguid | Optional | string | 16-byte namespace globally unique identifier in hexadecimal (e.g. "ABCDEF0123456789ABCDEF0123456789") 8555eui64 | Optional | string | 8-byte namespace EUI-64 in hexadecimal (e.g. "ABCDEF0123456789") 8556uuid | Optional | string | RFC 4122 UUID (e.g. "ceccf520-691e-4b46-9546-34af789907c5") 8557ptpl_file | Optional | string | File path to save/restore persistent reservation information 8558anagrpid | Optional | number | ANA group ID. Default: Namespace ID. 8559 8560#### Example 8561 8562Example request: 8563 8564~~~json 8565{ 8566 "jsonrpc": "2.0", 8567 "id": 1, 8568 "method": "nvmf_subsystem_add_ns", 8569 "params": { 8570 "nqn": "nqn.2016-06.io.spdk:cnode1", 8571 "namespace": { 8572 "nsid": 3, 8573 "bdev_name": "Nvme0n1", 8574 "ptpl_file": "/opt/Nvme0n1PR.json" 8575 } 8576 } 8577} 8578~~~ 8579 8580Example response: 8581 8582~~~json 8583{ 8584 "jsonrpc": "2.0", 8585 "id": 1, 8586 "result": 3 8587} 8588~~~ 8589 8590### nvmf_subsystem_remove_ns method {#rpc_nvmf_subsystem_remove_ns} 8591 8592Remove a namespace from a subsystem. 8593 8594#### Parameters 8595 8596Name | Optional | Type | Description 8597----------------------- | -------- | ----------- | ----------- 8598nqn | Required | string | Subsystem NQN 8599nsid | Required | number | Namespace ID 8600tgt_name | Optional | string | Parent NVMe-oF target name. 8601 8602#### Example 8603 8604Example request: 8605 8606~~~json 8607{ 8608 "jsonrpc": "2.0", 8609 "id": 1, 8610 "method": "nvmf_subsystem_remove_ns", 8611 "params": { 8612 "nqn": "nqn.2016-06.io.spdk:cnode1", 8613 "nsid": 1 8614 } 8615} 8616~~~ 8617 8618Example response: 8619 8620~~~json 8621{ 8622 "jsonrpc": "2.0", 8623 "id": 1, 8624 "result": true 8625} 8626~~~ 8627 8628### nvmf_subsystem_add_host method {#rpc_nvmf_subsystem_add_host} 8629 8630Add a host NQN to the list of allowed hosts. Adding an already allowed host will result in an 8631error. 8632 8633#### Parameters 8634 8635Name | Optional | Type | Description 8636----------------------- | -------- | ----------- | ----------- 8637nqn | Required | string | Subsystem NQN 8638host | Required | string | Host NQN to add to the list of allowed host NQNs 8639tgt_name | Optional | string | Parent NVMe-oF target name. 8640psk | Optional | string | Path to a file containing PSK for TLS connection 8641dhchap_key | Optional | string | DH-HMAC-CHAP key name. 8642dhchap_ctrlr_key | Optional | string | DH-HMAC-CHAP controller key name. 8643 8644#### Example 8645 8646Example request: 8647 8648~~~json 8649{ 8650 "jsonrpc": "2.0", 8651 "id": 1, 8652 "method": "nvmf_subsystem_add_host", 8653 "params": { 8654 "nqn": "nqn.2016-06.io.spdk:cnode1", 8655 "host": "nqn.2016-06.io.spdk:host1", 8656 "dhchap_key": "key0" 8657 } 8658} 8659~~~ 8660 8661Example response: 8662 8663~~~json 8664{ 8665 "jsonrpc": "2.0", 8666 "id": 1, 8667 "result": true 8668} 8669~~~ 8670 8671### nvmf_subsystem_remove_host method {#rpc_nvmf_subsystem_remove_host} 8672 8673Remove a host NQN from the list of allowed hosts. 8674 8675#### Parameters 8676 8677Name | Optional | Type | Description 8678----------------------- | -------- | ----------- | ----------- 8679nqn | Required | string | Subsystem NQN 8680host | Required | string | Host NQN to remove from the list of allowed host NQNs 8681tgt_name | Optional | string | Parent NVMe-oF target name. 8682 8683#### Example 8684 8685Example request: 8686 8687~~~json 8688{ 8689 "jsonrpc": "2.0", 8690 "id": 1, 8691 "method": "nvmf_subsystem_remove_host", 8692 "params": { 8693 "nqn": "nqn.2016-06.io.spdk:cnode1", 8694 "host": "nqn.2016-06.io.spdk:host1" 8695 } 8696} 8697~~~ 8698 8699Example response: 8700 8701~~~json 8702{ 8703 "jsonrpc": "2.0", 8704 "id": 1, 8705 "result": true 8706} 8707~~~ 8708 8709### nvmf_subsystem_allow_any_host method {#rpc_nvmf_subsystem_allow_any_host} 8710 8711Configure a subsystem to allow any host to connect or to enforce the host NQN list. 8712 8713#### Parameters 8714 8715Name | Optional | Type | Description 8716----------------------- | -------- | ----------- | ----------- 8717nqn | Required | string | Subsystem NQN 8718allow_any_host | Required | boolean | Allow any host (`true`) or enforce allowed host list (`false`). 8719tgt_name | Optional | string | Parent NVMe-oF target name. 8720 8721#### Example 8722 8723Example request: 8724 8725~~~json 8726{ 8727 "jsonrpc": "2.0", 8728 "id": 1, 8729 "method": "nvmf_subsystem_allow_any_host", 8730 "params": { 8731 "nqn": "nqn.2016-06.io.spdk:cnode1", 8732 "allow_any_host": true 8733 } 8734} 8735~~~ 8736 8737Example response: 8738 8739~~~json 8740{ 8741 "jsonrpc": "2.0", 8742 "id": 1, 8743 "result": true 8744} 8745~~~ 8746 8747### nvmf_subsystem_get_controllers {#rpc_nvmf_subsystem_get_controllers} 8748 8749#### Parameters 8750 8751Name | Optional | Type | Description 8752----------------------- | -------- | ----------- | ----------- 8753nqn | Required | string | Subsystem NQN 8754tgt_name | Optional | string | Parent NVMe-oF target name. 8755 8756#### Example 8757 8758Example request: 8759 8760~~~json 8761{ 8762 "jsonrpc": "2.0", 8763 "id": 1, 8764 "method": "nvmf_subsystem_get_controllers", 8765 "params": { 8766 "nqn": "nqn.2016-06.io.spdk:cnode1" 8767 } 8768} 8769~~~ 8770 8771Example response: 8772 8773~~~json 8774{ 8775 "jsonrpc": "2.0", 8776 "id": 1, 8777 "result": [ 8778 { 8779 "cntlid": 1, 8780 "hostnqn": "nqn.2016-06.io.spdk:host1", 8781 "hostid": "27dad528-6368-41c3-82d3-0b956b49025d", 8782 "num_io_qpairs": 5 8783 } 8784 ] 8785} 8786~~~ 8787 8788### nvmf_subsystem_get_qpairs {#rpc_nvmf_subsystem_get_qpairs} 8789 8790#### Parameters 8791 8792Name | Optional | Type | Description 8793----------------------- | -------- | ----------- | ----------- 8794nqn | Required | string | Subsystem NQN 8795tgt_name | Optional | string | Parent NVMe-oF target name. 8796 8797#### Example 8798 8799Example request: 8800 8801~~~json 8802{ 8803 "jsonrpc": "2.0", 8804 "id": 1, 8805 "method": "nvmf_subsystem_get_qpairs", 8806 "params": { 8807 "nqn": "nqn.2016-06.io.spdk:cnode1" 8808 } 8809} 8810~~~ 8811 8812Example response: 8813 8814~~~json 8815{ 8816 "jsonrpc": "2.0", 8817 "id": 1, 8818 "result": [ 8819 { 8820 "cntlid": 1, 8821 "qid": 0, 8822 "state": "active", 8823 "listen_address": { 8824 "trtype": "RDMA", 8825 "adrfam": "IPv4", 8826 "traddr": "192.168.0.123", 8827 "trsvcid": "4420" 8828 } 8829 }, 8830 { 8831 "cntlid": 1, 8832 "qid": 1, 8833 "state": "active", 8834 "listen_address": { 8835 "trtype": "RDMA", 8836 "adrfam": "IPv4", 8837 "traddr": "192.168.0.123", 8838 "trsvcid": "4420" 8839 } 8840 } 8841 ] 8842} 8843~~~ 8844 8845### nvmf_subsystem_get_listeners {#rpc_nvmf_subsystem_get_listeners} 8846 8847#### Parameters 8848 8849Name | Optional | Type | Description 8850----------------------- | -------- | ----------- | ----------- 8851nqn | Required | string | Subsystem NQN 8852tgt_name | Optional | string | Parent NVMe-oF target name. 8853 8854#### Example 8855 8856Example request: 8857 8858~~~json 8859{ 8860 "jsonrpc": "2.0", 8861 "id": 1, 8862 "method": "nvmf_subsystem_get_listeners", 8863 "params": { 8864 "nqn": "nqn.2016-06.io.spdk:cnode1" 8865 } 8866} 8867~~~ 8868 8869Example response: 8870 8871~~~json 8872{ 8873 "jsonrpc": "2.0", 8874 "id": 1, 8875 "result": [ 8876 { 8877 "address": { 8878 "trtype": "RDMA", 8879 "adrfam": "IPv4", 8880 "traddr": "192.168.0.123", 8881 "trsvcid": "4420" 8882 }, 8883 "ana_state": "optimized" 8884 } 8885 ] 8886} 8887~~~ 8888 8889### nvmf_ns_add_host {#rpc_nvmf_ns_add_host} 8890 8891Make the specified namespace of the specified subnqn visible to any existing 8892or future controllers with the specified hostnqn. 8893 8894Note: the namespace must have been added with no_auto_visible = false 8895(see @ref rpc_nvmf_subsystem_add_ns). 8896 8897#### Parameters 8898 8899Name | Optional | Type | Description 8900----------------------- | -------- | ----------- | ----------- 8901nqn | Required | string | Subsystem NQN 8902nsid | Required | number | Namespace ID 8903host | Required | string | Host NQN 8904 8905#### Example 8906 8907Example request: 8908 8909~~~json 8910{ 8911 "jsonrpc": "2.0", 8912 "id": 1, 8913 "method": "nvmf_ns_add_host", 8914 "params": { 8915 "nqn": "nqn.2016-06.io.spdk:cnode1", 8916 "nsid": 1, 8917 "host": "nqn.2024-01.io.spdk:host0" 8918 } 8919} 8920~~~ 8921 8922Example response: 8923 8924~~~json 8925{ 8926 "jsonrpc": "2.0", 8927 "id": 1, 8928 "result": true 8929} 8930~~~ 8931 8932### nvmf_ns_remove_host {#rpc_nvmf_ns_remove_host} 8933 8934Make the specified namespace of the specified subnqn not visible to any existing 8935or future controllers with the specified hostnqn. 8936 8937Note: the namespace must have been added to the subsystem with 8938no_auto_visible = false (see @ref rpc_nvmf_subsystem_add_ns). 8939 8940#### Parameters 8941 8942Name | Optional | Type | Description 8943----------------------- | -------- | ----------- | ----------- 8944nqn | Required | string | Subsystem NQN 8945nsid | Required | number | Namespace ID 8946host | Required | string | Host NQN 8947 8948#### Example 8949 8950Example request: 8951 8952~~~json 8953{ 8954 "jsonrpc": "2.0", 8955 "id": 1, 8956 "method": "nvmf_ns_remove_host", 8957 "params": { 8958 "nqn": "nqn.2016-06.io.spdk:cnode1", 8959 "nsid": 1, 8960 "host": "nqn.2024-01.io.spdk:host0" 8961 } 8962} 8963~~~ 8964 8965Example response: 8966 8967~~~json 8968{ 8969 "jsonrpc": "2.0", 8970 "id": 1, 8971 "result": true 8972} 8973~~~ 8974 8975### nvmf_set_max_subsystems {#rpc_nvmf_set_max_subsystems} 8976 8977Set the maximum allowed subsystems for the NVMe-oF target. This RPC may only be called 8978before SPDK subsystems have been initialized. 8979 8980#### Parameters 8981 8982Name | Optional | Type | Description 8983----------------------- | -------- | ----------- | ----------- 8984max_subsystems | Required | number | Maximum number of NVMe-oF subsystems 8985 8986#### Example 8987 8988Example request: 8989 8990~~~json 8991{ 8992 "jsonrpc": "2.0", 8993 "id": 1, 8994 "method": "nvmf_set_max_subsystems", 8995 "params": { 8996 "max_subsystems": 1024 8997 } 8998} 8999~~~ 9000 9001Example response: 9002 9003~~~json 9004{ 9005 "jsonrpc": "2.0", 9006 "id": 1, 9007 "result": true 9008} 9009~~~ 9010 9011### nvmf_discovery_add_referral method {#rpc_nvmf_discovery_add_referral} 9012 9013Add a discovery service referral to an NVMe-oF target. If a referral with the given 9014parameters already exists, no action will be taken. 9015 9016#### Parameters 9017 9018Name | Optional | Type | Description 9019----------------------- | -------- | ----------- | ----------- 9020tgt_name | Optional | string | Parent NVMe-oF target name. 9021address | Required | object | @ref rpc_nvmf_listen_address object 9022secure_channel | Optional | bool | The connection to that discovery subsystem requires a secure channel 9023 9024#### Example 9025 9026Example request: 9027 9028~~~json 9029{ 9030 "jsonrpc": "2.0", 9031 "id": 1, 9032 "method": "nvmf_discovery_add_referral", 9033 "params": { 9034 "address": { 9035 "trtype": "RDMA", 9036 "adrfam": "IPv4", 9037 "traddr": "192.168.0.123", 9038 "trsvcid": "4420" 9039 } 9040 } 9041} 9042~~~ 9043 9044Example response: 9045 9046~~~json 9047{ 9048 "jsonrpc": "2.0", 9049 "id": 1, 9050 "result": true 9051} 9052~~~ 9053 9054### nvmf_discovery_remove_referral method {#rpc_nvmf_discovery_remove_referral} 9055 9056Remove a discovery service referral from an NVMe-oF target. 9057 9058#### Parameters 9059 9060Name | Optional | Type | Description 9061----------------------- | -------- | ----------- | ----------- 9062tgt_name | Optional | string | Parent NVMe-oF target name. 9063address | Required | object | @ref rpc_nvmf_listen_address object 9064 9065#### Example 9066 9067Example request: 9068 9069~~~json 9070{ 9071 "jsonrpc": "2.0", 9072 "id": 1, 9073 "method": "nvmf_discovery_remove_referral", 9074 "params": { 9075 "address": { 9076 "trtype": "RDMA", 9077 "adrfam": "IPv4", 9078 "traddr": "192.168.0.123", 9079 "trsvcid": "4420" 9080 } 9081 } 9082} 9083~~~ 9084 9085Example response: 9086 9087~~~json 9088{ 9089 "jsonrpc": "2.0", 9090 "id": 1, 9091 "result": true 9092} 9093~~~ 9094 9095### nvmf_discovery_get_referrals {#rpc_nvmf_discovery_get_referrals} 9096 9097#### Parameters 9098 9099Name | Optional | Type | Description 9100----------------------- | -------- | ----------- | ----------- 9101tgt_name | Optional | string | Parent NVMe-oF target name. 9102 9103#### Example 9104 9105Example request: 9106 9107~~~json 9108{ 9109 "jsonrpc": "2.0", 9110 "id": 1, 9111 "method": "nvmf_discovery_get_referrals" 9112} 9113~~~ 9114 9115Example response: 9116 9117~~~json 9118{ 9119 "jsonrpc": "2.0", 9120 "id": 1, 9121 "result": [ 9122 { 9123 "address": { 9124 "trtype": "RDMA", 9125 "adrfam": "IPv4", 9126 "traddr": "192.168.0.123", 9127 "trsvcid": "4420" 9128 } 9129 } 9130 ] 9131} 9132~~~ 9133 9134### nvmf_set_config {#rpc_nvmf_set_config} 9135 9136Set global configuration of NVMe-oF target. This RPC may only be called before SPDK subsystems 9137have been initialized. 9138 9139#### Parameters 9140 9141Name | Optional | Type | Description 9142----------------------- | -------- | ----------- | ----------- 9143acceptor_poll_rate | Optional | number | Polling interval of the acceptor for incoming connections (microseconds) 9144admin_cmd_passthru | Optional | object | Admin command passthru configuration 9145poll_groups_mask | Optional | string | Set cpumask for NVMf poll groups 9146discovery_filter | Optional | string | Set discovery filter, possible values are: `match_any` (default) or comma separated values: `transport`, `address`, `svcid` 9147dhchap_digests | Optional | list | List of allowed DH-HMAC-CHAP digests. 9148dhchap_dhgroups | Optional | list | List of allowed DH-HMAC-CHAP DH groups. 9149 9150#### admin_cmd_passthru {#spdk_nvmf_admin_passthru_conf} 9151 9152Name | Optional | Type | Description 9153----------------------- | -------- | ----------- | ----------- 9154identify_ctrlr | Required | bool | If true, enables custom identify handler that reports some identify attributes from the underlying NVMe drive 9155 9156#### Example 9157 9158Example request: 9159 9160~~~json 9161{ 9162 "jsonrpc": "2.0", 9163 "id": 1, 9164 "method": "nvmf_set_config", 9165 "params": { 9166 "acceptor_poll_rate": 10000 9167 } 9168} 9169~~~ 9170 9171Example response: 9172 9173~~~json 9174{ 9175 "jsonrpc": "2.0", 9176 "id": 1, 9177 "result": true 9178} 9179~~~ 9180 9181### nvmf_get_transports method {#rpc_nvmf_get_transports} 9182 9183#### Parameters 9184 9185The user may specify no parameters in order to list all transports, or a transport may be 9186specified by type. 9187 9188Name | Optional | Type | Description 9189--------------------------- | -------- | ------------| ----------- 9190tgt_name | Optional | string | Parent NVMe-oF target name. 9191trtype | Optional | string | Transport type. 9192 9193#### Example 9194 9195Example request: 9196 9197~~~json 9198{ 9199 "jsonrpc": "2.0", 9200 "id": 1, 9201 "method": "nvmf_get_transports" 9202} 9203~~~ 9204 9205Example response: 9206 9207~~~json 9208{ 9209 "jsonrpc": "2.0", 9210 "id": 1, 9211 "result": [ 9212 { 9213 "type": "RDMA". 9214 "max_queue_depth": 128, 9215 "max_io_qpairs_per_ctrlr": 64, 9216 "in_capsule_data_size": 4096, 9217 "max_io_size": 131072, 9218 "io_unit_size": 131072, 9219 "abort_timeout_sec": 1 9220 } 9221 ] 9222} 9223~~~ 9224 9225### nvmf_get_stats method {#rpc_nvmf_get_stats} 9226 9227Retrieve current statistics of the NVMf subsystem. 9228 9229#### Parameters 9230 9231Name | Optional | Type | Description 9232--------------------------- | -------- | ------------| ----------- 9233tgt_name | Optional | string | Parent NVMe-oF target name. 9234 9235#### Response 9236 9237The response is an object containing NVMf subsystem statistics. 9238In the response, `admin_qpairs` and `io_qpairs` are reflecting cumulative queue pair counts while 9239`current_admin_qpairs` and `current_io_qpairs` are showing the current number. 9240 9241#### Example 9242 9243Example request: 9244 9245~~~json 9246{ 9247 "jsonrpc": "2.0", 9248 "method": "nvmf_get_stats", 9249 "id": 1 9250} 9251~~~ 9252 9253Example response: 9254 9255~~~json 9256{ 9257 "jsonrpc": "2.0", 9258 "id": 1, 9259 "result": { 9260 "tick_rate": 2400000000, 9261 "poll_groups": [ 9262 { 9263 "name": "app_thread", 9264 "admin_qpairs": 1, 9265 "io_qpairs": 4, 9266 "current_admin_qpairs": 1, 9267 "current_io_qpairs": 2, 9268 "pending_bdev_io": 1721, 9269 "transports": [ 9270 { 9271 "trtype": "RDMA", 9272 "pending_data_buffer": 12131888, 9273 "devices": [ 9274 { 9275 "name": "mlx5_1", 9276 "polls": 72284105, 9277 "completions": 0, 9278 "requests": 0, 9279 "request_latency": 0, 9280 "pending_free_request": 0, 9281 "pending_rdma_read": 0, 9282 "pending_rdma_write": 0, 9283 "total_send_wrs": 0, 9284 "send_doorbell_updates": 0, 9285 "total_recv_wrs": 0, 9286 "recv_doorbell_updates": 1 9287 }, 9288 { 9289 "name": "mlx5_0", 9290 "polls": 72284105, 9291 "completions": 15165875, 9292 "requests": 7582935, 9293 "request_latency": 1249323766184, 9294 "pending_free_request": 0, 9295 "pending_rdma_read": 337602, 9296 "pending_rdma_write": 0, 9297 "total_send_wrs": 15165875, 9298 "send_doorbell_updates": 1516587, 9299 "total_recv_wrs": 15165875, 9300 "recv_doorbell_updates": 1516587 9301 } 9302 ] 9303 } 9304 ] 9305 } 9306 ] 9307 } 9308} 9309~~~ 9310 9311### nvmf_set_crdt {#rpc_nvmf_set_crdt} 9312 9313Set the 3 CRDT (Command Retry Delay Time) values. For details about 9314CRDT, please refer to the NVMe specification. Currently all the 9315SPDK nvmf subsystems share the same CRDT values. The default values 9316are 0. This rpc can only be invoked in STARTUP stage. All values are 9317in units of 100 milliseconds (same as the NVMe specification). 9318 9319#### Parameters 9320 9321Name | Optional | Type | Description 9322----------------------- | -------- | ----------- | ----------- 9323crdt1 | Optional | number | Command Retry Delay Time 1 9324crdt2 | Optional | number | Command Retry Delay Time 2 9325crdt3 | Optional | number | Command Retry Delay Time 3 9326 9327## Vfio-user Target 9328 9329### vfu_tgt_set_base_path {#rpc_vfu_tgt_set_base_path} 9330 9331Set base path of Unix Domain socket file. 9332 9333#### Parameters 9334 9335Name | Optional | Type | Description 9336----------------------- | -------- | ----------- | ----------- 9337path | Required | string | Base path 9338 9339#### Example 9340 9341Example request: 9342 9343~~~json 9344{ 9345 "params": { 9346 "path": "/var/run/vfu_tgt" 9347 }, 9348 "jsonrpc": "2.0", 9349 "method": "vfu_tgt_set_base_path", 9350 "id": 1 9351} 9352~~~ 9353 9354Example response: 9355 9356~~~json 9357{ 9358 "jsonrpc": "2.0", 9359 "id": 1, 9360 "result": true 9361} 9362~~~ 9363 9364### vfu_virtio_delete_endpoint {#rpc_vfu_virtio_delete_endpoint} 9365 9366Delete PCI device via endpoint name. 9367 9368#### Parameters 9369 9370Name | Optional | Type | Description 9371----------------------- | -------- | ----------- | ----------- 9372name | Required | string | Endpoint name 9373 9374#### Example 9375 9376Example request: 9377 9378~~~json 9379{ 9380 "params": { 9381 "name": "vfu.0" 9382 }, 9383 "jsonrpc": "2.0", 9384 "method": "vfu_virtio_delete_endpoint", 9385 "id": 1 9386} 9387~~~ 9388 9389Example response: 9390 9391~~~json 9392{ 9393 "jsonrpc": "2.0", 9394 "id": 1, 9395 "result": true 9396} 9397~~~ 9398 9399### vfu_virtio_create_blk_endpoint {#rpc_vfu_virtio_create_blk_endpoint} 9400 9401Create vfio-user virtio-blk PCI endpoint. 9402 9403#### Parameters 9404 9405Name | Optional | Type | Description 9406----------------------- | -------- | ----------- | ----------- 9407name | Required | string | Endpoint name 9408bdev_name | Required | string | Block device name 9409cpumask | Optional | string | CPU masks 9410num_queues | Optional | number | Number of queues 9411qsize | Optional | number | Queue size 9412packed_ring | Optional | boolean | Enable packed ring 9413 9414#### Example 9415 9416Example request: 9417 9418~~~json 9419{ 9420 "params": { 9421 "name": "vfu.0", 9422 "bdev_name": "Malloc0", 9423 "cpumask": "0x2", 9424 "num_queues": 4, 9425 "qsize": 256 9426 }, 9427 "jsonrpc": "2.0", 9428 "method": "vfu_virtio_create_blk_endpoint", 9429 "id": 1 9430} 9431~~~ 9432 9433Example response: 9434 9435~~~json 9436{ 9437 "jsonrpc": "2.0", 9438 "id": 1, 9439 "result": true 9440} 9441~~~ 9442 9443### vfu_virtio_scsi_add_target {#rpc_vfu_virtio_scsi_add_target} 9444 9445Add block device to specified SCSI target of vfio-user virtio-scsi PCI endpoint. 9446 9447#### Parameters 9448 9449Name | Optional | Type | Description 9450----------------------- | -------- | ----------- | ----------- 9451name | Required | string | Endpoint name 9452scsi_target_num | Required | number | SCSI target number 9453bdev_name | Required | string | Block device name 9454 9455#### Example 9456 9457Example request: 9458 9459~~~json 9460{ 9461 "params": { 9462 "name": "vfu.0", 9463 "scsi_target_num": 0, 9464 "bdev_name": "Malloc0" 9465 }, 9466 "jsonrpc": "2.0", 9467 "method": "vfu_virtio_scsi_add_target", 9468 "id": 1 9469} 9470~~~ 9471 9472Example response: 9473 9474~~~json 9475{ 9476 "jsonrpc": "2.0", 9477 "id": 1, 9478 "result": true 9479} 9480~~~ 9481 9482### vfu_virtio_scsi_remove_target {#rpc_vfu_virtio_scsi_remove_target} 9483 9484Remove a SCSI target of vfio-user virtio-scsi PCI endpoint. 9485 9486#### Parameters 9487 9488Name | Optional | Type | Description 9489----------------------- | -------- | ----------- | ----------- 9490name | Required | string | Endpoint name 9491scsi_target_num | Required | number | SCSI target number 9492 9493#### Example 9494 9495Example request: 9496 9497~~~json 9498{ 9499 "params": { 9500 "name": "vfu.0", 9501 "scsi_target_num": 0 9502 }, 9503 "jsonrpc": "2.0", 9504 "method": "vfu_virtio_scsi_remove_target", 9505 "id": 1 9506} 9507~~~ 9508 9509Example response: 9510 9511~~~json 9512{ 9513 "jsonrpc": "2.0", 9514 "id": 1, 9515 "result": true 9516} 9517~~~ 9518 9519### vfu_virtio_create_scsi_endpoint {#rpc_vfu_virtio_create_scsi_endpoint} 9520 9521Create vfio-user virtio-scsi PCI endpoint. 9522 9523#### Parameters 9524 9525Name | Optional | Type | Description 9526----------------------- | -------- | ----------- | ----------- 9527name | Required | string | Endpoint name 9528cpumask | Optional | string | CPU masks 9529num_io_queues | Optional | number | Number of IO queues 9530qsize | Optional | number | Queue size 9531packed_ring | Optional | boolean | Enable packed ring 9532 9533#### Example 9534 9535Example request: 9536 9537~~~json 9538{ 9539 "params": { 9540 "name": "vfu.0", 9541 "cpumask": "0x2", 9542 "num_io_queues": 4, 9543 "qsize": 256 9544 }, 9545 "jsonrpc": "2.0", 9546 "method": "vfu_virtio_create_scsi_endpoint", 9547 "id": 1 9548} 9549~~~ 9550 9551Example response: 9552 9553~~~json 9554{ 9555 "jsonrpc": "2.0", 9556 "id": 1, 9557 "result": true 9558} 9559~~~ 9560 9561### vfu_virtio_create_fs_endpoint {#vfu_virtio_create_fs_endpoint} 9562 9563Create vfio-user virtio-fs PCI endpoint. 9564 9565#### Parameters 9566 9567Name | Optional | Type | Description 9568----------------------- | -------- | ----------- | ----------- 9569name | Required | string | Endpoint name 9570fsdev_name | Optional | string | Name of an underlying fsdev 9571tag | Optional | string | Virtio FS tag according to the virtio specification 9572cpumask | Optional | string | CPU masks 9573num_queues | Optional | number | Number of IO queues 9574qsize | Optional | number | Queue size 9575packed_ring | Optional | boolean | Enable packed ring 9576 9577#### Example 9578 9579Example request: 9580 9581~~~json 9582{ 9583 "params": { 9584 "name": "vfu.0", 9585 "fsdev_name": "aio0", 9586 "tag": "virtiofs0", 9587 "cpumask": "0x2", 9588 "num_queues": 4, 9589 "qsize": 256 9590 }, 9591 "jsonrpc": "2.0", 9592 "method": "vfu_virtio_create_fs_endpoint", 9593 "id": 1 9594} 9595~~~ 9596 9597Example response: 9598 9599~~~json 9600{ 9601 "jsonrpc": "2.0", 9602 "id": 1, 9603 "result": true 9604} 9605~~~ 9606 9607## Vhost Target {#jsonrpc_components_vhost_tgt} 9608 9609The following common preconditions need to be met in all target types. 9610 9611Controller name will be used to create UNIX domain socket. This implies that name concatenated with vhost socket 9612directory path needs to be valid UNIX socket name. 9613 9614@ref cpu_mask parameter is used to choose CPU on which pollers will be launched when new initiator is connecting. 9615It must be a subset of application CPU mask. Default value is CPU mask of the application. 9616 9617### vhost_controller_set_coalescing {#rpc_vhost_controller_set_coalescing} 9618 9619Controls interrupt coalescing for specific target. Because `delay_base_us` is used to calculate delay in CPU ticks 9620there is no hardcoded limit for this parameter. Only limitation is that final delay in CPU ticks might not overflow 962132 bit unsigned integer (which is more than 1s @ 4GHz CPU). In real scenarios `delay_base_us` should be much lower 9622than 150us. To disable coalescing set `delay_base_us` to 0. 9623 9624#### Parameters 9625 9626Name | Optional | Type | Description 9627----------------------- | -------- | ----------- | ----------- 9628ctrlr | Required | string | Controller name 9629delay_base_us | Required | number | Base (minimum) coalescing time in microseconds 9630iops_threshold | Required | number | Coalescing activation level greater than 0 in IO per second 9631 9632#### Example 9633 9634Example request: 9635 9636~~~json 9637{ 9638 "params": { 9639 "iops_threshold": 100000, 9640 "ctrlr": "VhostScsi0", 9641 "delay_base_us": 80 9642 }, 9643 "jsonrpc": "2.0", 9644 "method": "vhost_controller_set_coalescing", 9645 "id": 1 9646} 9647~~~ 9648 9649Example response: 9650 9651~~~json 9652{ 9653 "jsonrpc": "2.0", 9654 "id": 1, 9655 "result": true 9656} 9657~~~ 9658 9659### vhost_create_scsi_controller {#rpc_vhost_create_scsi_controller} 9660 9661Construct vhost SCSI target. 9662 9663#### Parameters 9664 9665Name | Optional | Type | Description 9666----------------------- | -------- | ----------- | ----------- 9667ctrlr | Required | string | Controller name 9668cpumask | Optional | string | @ref cpu_mask for this controller 9669delay | Optional | boolean | If true, delay the controller startup. 9670 9671#### Example 9672 9673Example request: 9674 9675~~~json 9676{ 9677 "params": { 9678 "cpumask": "0x2", 9679 "ctrlr": "VhostScsi0", 9680 "delay": true 9681 }, 9682 "jsonrpc": "2.0", 9683 "method": "vhost_create_scsi_controller", 9684 "id": 1 9685} 9686~~~ 9687 9688Example response: 9689 9690~~~json 9691{ 9692 "jsonrpc": "2.0", 9693 "id": 1, 9694 "result": true 9695} 9696~~~ 9697 9698### vhost_start_scsi_controller {#rpc_vhost_start_scsi_controller} 9699 9700Start vhost SCSI controller, if controller is already started, do nothing. 9701 9702#### Parameters 9703 9704Name | Optional | Type | Description 9705----------------------- | -------- | ----------- | ----------- 9706ctrlr | Required | string | Controller name 9707 9708#### Example 9709 9710Example request: 9711 9712~~~json 9713{ 9714 "params": { 9715 "ctrlr": "VhostScsi0", 9716 }, 9717 "jsonrpc": "2.0", 9718 "method": "vhost_start_scsi_controller", 9719 "id": 1 9720} 9721~~~ 9722 9723Example response: 9724 9725~~~json 9726response: 9727{ 9728 "jsonrpc": "2.0", 9729 "id": 1, 9730 "result": true 9731} 9732~~~ 9733 9734### vhost_scsi_controller_add_target {#rpc_vhost_scsi_controller_add_target} 9735 9736In vhost target `ctrlr` create SCSI target with ID `scsi_target_num` and add `bdev_name` as LUN 0. 9737 9738#### Parameters 9739 9740Name | Optional | Type | Description 9741----------------------- | -------- | ----------- | ----------- 9742ctrlr | Required | string | Controller name 9743scsi_target_num | Required | number | SCSI target ID between 0 and 7 or -1 to use first free ID. 9744bdev_name | Required | string | Name of bdev to expose as a LUN 0 9745 9746#### Response 9747 9748SCSI target ID. 9749 9750#### Example 9751 9752Example request: 9753 9754~~~json 9755{ 9756 "params": { 9757 "scsi_target_num": 1, 9758 "bdev_name": "Malloc0", 9759 "ctrlr": "VhostScsi0" 9760 }, 9761 "jsonrpc": "2.0", 9762 "method": "vhost_scsi_controller_add_target", 9763 "id": 1 9764} 9765~~~ 9766 9767Example response: 9768 9769~~~json 9770response: 9771{ 9772 "jsonrpc": "2.0", 9773 "id": 1, 9774 "result": 1 9775} 9776~~~ 9777 9778### vhost_scsi_controller_remove_target {#rpc_vhost_scsi_controller_remove_target} 9779 9780Remove SCSI target ID `scsi_target_num` from vhost target `scsi_target_num`. 9781 9782This method will fail if initiator is connected, but doesn't support hot-remove (the `VIRTIO_SCSI_F_HOTPLUG` is not negotiated). 9783 9784#### Parameters 9785 9786Name | Optional | Type | Description 9787----------------------- | -------- | ----------- | ----------- 9788ctrlr | Required | string | Controller name 9789scsi_target_num | Required | number | SCSI target ID between 0 and 7 9790 9791#### Example 9792 9793Example request: 9794 9795~~~json 9796request: 9797{ 9798 "params": { 9799 "scsi_target_num": 1, 9800 "ctrlr": "VhostScsi0" 9801 }, 9802 "jsonrpc": "2.0", 9803 "method": "vhost_scsi_controller_remove_target", 9804 "id": 1 9805} 9806~~~ 9807 9808Example response: 9809 9810~~~json 9811{ 9812 "jsonrpc": "2.0", 9813 "id": 1, 9814 "result": true 9815} 9816~~~ 9817 9818### virtio_blk_create_transport {#rpc_virtio_blk_create_transport} 9819 9820Create virtio blk transport. 9821 9822#### Parameters 9823 9824Name | Optional | Type | Description 9825----------------------- | -------- | ----------- | ----------- 9826name | Required | string | Transport name 9827 9828#### Example 9829 9830Example request: 9831 9832~~~json 9833{ 9834 "params": { 9835 "name": "vhost_user_blk" 9836 }, 9837 "jsonrpc": "2.0", 9838 "method": "virtio_blk_create_transport", 9839 "id": 1 9840} 9841~~~ 9842 9843Example response: 9844 9845~~~json 9846{ 9847 "jsonrpc": "2.0", 9848 "id": 1, 9849 "result": true 9850} 9851~~~ 9852 9853### virtio_blk_get_transports {#rpc_virtio_blk_get_transports} 9854 9855#### Parameters 9856 9857The user may specify no parameters in order to list all transports, 9858or a transport name may be specified. 9859 9860Name | Optional | Type | Description 9861--------------------------- | -------- | ------------| ----------- 9862name | Optional | string | Transport name. 9863 9864#### Example 9865 9866Example request: 9867 9868~~~json 9869{ 9870 "jsonrpc": "2.0", 9871 "method": "virtio_blk_get_transports", 9872 "id": 1 9873} 9874~~~ 9875 9876Example response: 9877 9878~~~json 9879{ 9880 "jsonrpc": "2.0", 9881 "id": 1, 9882 "result": [ 9883 { 9884 "name": "vhost_user_blk" 9885 } 9886 ] 9887} 9888~~~ 9889 9890### vhost_create_blk_controller {#rpc_vhost_create_blk_controller} 9891 9892Create vhost block controller 9893 9894If `readonly` is `true` then vhost block target will be created as read only and fail any write requests. 9895The `VIRTIO_BLK_F_RO` feature flag will be offered to the initiator. 9896 9897#### Parameters 9898 9899Name | Optional | Type | Description 9900----------------------- | -------- | ----------- | ----------- 9901ctrlr | Required | string | Controller name 9902bdev_name | Required | string | Name of bdev to expose block device 9903readonly | Optional | boolean | If true, this target will be read only (default: false) 9904cpumask | Optional | string | @ref cpu_mask for this controller 9905transport | Optional | string | virtio blk transport name (default: vhost_user_blk) 9906 9907#### Example 9908 9909Example request: 9910 9911~~~json 9912{ 9913 "params": { 9914 "dev_name": "Malloc0", 9915 "ctrlr": "VhostBlk0" 9916 }, 9917 "jsonrpc": "2.0", 9918 "method": "vhost_create_blk_controller", 9919 "id": 1 9920} 9921~~~ 9922 9923Example response: 9924 9925~~~json 9926{ 9927 "jsonrpc": "2.0", 9928 "id": 1, 9929 "result": true 9930} 9931~~~ 9932 9933### vhost_get_controllers {#rpc_vhost_get_controllers} 9934 9935Display information about all or specific vhost controller(s). 9936 9937#### Parameters 9938 9939The user may specify no parameters in order to list all controllers, or a controller may be 9940specified by name. 9941 9942Name | Optional | Type | Description 9943----------------------- | -------- | ----------- | ----------- 9944name | Optional | string | Vhost controller name 9945 9946#### Response {#rpc_vhost_get_controllers_response} 9947 9948Response is an array of objects describing requested controller(s). Common fields are: 9949 9950Name | Type | Description 9951----------------------- | ----------- | ----------- 9952ctrlr | string | Controller name 9953cpumask | string | @ref cpu_mask of this controller 9954delay_base_us | number | Base (minimum) coalescing time in microseconds (0 if disabled) 9955iops_threshold | number | Coalescing activation level 9956backend_specific | object | Backend specific information 9957 9958### Vhost block {#rpc_vhost_get_controllers_blk} 9959 9960`backend_specific` contains one `block` object of type: 9961 9962Name | Type | Description 9963----------------------- | ----------- | ----------- 9964bdev | string | Backing bdev name or Null if bdev is hot-removed 9965readonly | boolean | True if controllers is readonly, false otherwise 9966 9967### Vhost SCSI {#rpc_vhost_get_controllers_scsi} 9968 9969`backend_specific` contains `scsi` array of following objects: 9970 9971Name | Type | Description 9972----------------------- | ----------- | ----------- 9973target_name | string | Name of this SCSI target 9974id | number | Unique SPDK global SCSI target ID 9975scsi_dev_num | number | SCSI target ID initiator will see when scanning this controller 9976luns | array | array of objects describing @ref rpc_vhost_get_controllers_scsi_luns 9977 9978### Vhost SCSI LUN {#rpc_vhost_get_controllers_scsi_luns} 9979 9980Object of type: 9981 9982Name | Type | Description 9983----------------------- | ----------- | ----------- 9984id | number | SCSI LUN ID 9985bdev_name | string | Backing bdev name 9986 9987### Vhost NVMe {#rpc_vhost_get_controllers_nvme} 9988 9989`backend_specific` contains `namespaces` array of following objects: 9990 9991Name | Type | Description 9992----------------------- | ----------- | ----------- 9993nsid | number | Namespace ID 9994bdev | string | Backing bdev name 9995 9996#### Example 9997 9998Example request: 9999 10000~~~json 10001{ 10002 "jsonrpc": "2.0", 10003 "method": "vhost_get_controllers", 10004 "id": 1 10005} 10006~~~ 10007 10008Example response: 10009 10010~~~json 10011{ 10012 "jsonrpc": "2.0", 10013 "id": 1, 10014 "result": [ 10015 { 10016 "cpumask": "0x2", 10017 "backend_specific": { 10018 "block": { 10019 "readonly": false, 10020 "bdev": "Malloc0" 10021 } 10022 }, 10023 "iops_threshold": 60000, 10024 "ctrlr": "VhostBlk0", 10025 "delay_base_us": 100 10026 }, 10027 { 10028 "cpumask": "0x2", 10029 "backend_specific": { 10030 "scsi": [ 10031 { 10032 "target_name": "Target 2", 10033 "luns": [ 10034 { 10035 "id": 0, 10036 "bdev_name": "Malloc1" 10037 } 10038 ], 10039 "id": 0, 10040 "scsi_dev_num": 2 10041 }, 10042 { 10043 "target_name": "Target 5", 10044 "luns": [ 10045 { 10046 "id": 0, 10047 "bdev_name": "Malloc2" 10048 } 10049 ], 10050 "id": 1, 10051 "scsi_dev_num": 5 10052 } 10053 ] 10054 }, 10055 "iops_threshold": 60000, 10056 "ctrlr": "VhostScsi0", 10057 "delay_base_us": 0 10058 }, 10059 { 10060 "cpumask": "0x2", 10061 "backend_specific": { 10062 "namespaces": [ 10063 { 10064 "bdev": "Malloc3", 10065 "nsid": 1 10066 }, 10067 { 10068 "bdev": "Malloc4", 10069 "nsid": 2 10070 } 10071 ] 10072 }, 10073 "iops_threshold": 60000, 10074 "ctrlr": "VhostNvme0", 10075 "delay_base_us": 0 10076 } 10077 ] 10078} 10079~~~ 10080 10081### vhost_delete_controller {#rpc_vhost_delete_controller} 10082 10083Remove vhost target. 10084 10085This call will fail if there is an initiator connected or there is at least one SCSI target configured in case of 10086vhost SCSI target. In the later case please remove all SCSI targets first using @ref rpc_vhost_scsi_controller_remove_target. 10087 10088#### Parameters 10089 10090Name | Optional | Type | Description 10091----------------------- | -------- | ----------- | ----------- 10092ctrlr | Required | string | Controller name 10093 10094#### Example 10095 10096Example request: 10097 10098~~~json 10099{ 10100 "params": { 10101 "ctrlr": "VhostNvme0" 10102 }, 10103 "jsonrpc": "2.0", 10104 "method": "vhost_delete_controller", 10105 "id": 1 10106} 10107~~~ 10108 10109Example response: 10110 10111~~~json 10112{ 10113 "jsonrpc": "2.0", 10114 "id": 1, 10115 "result": true 10116} 10117~~~ 10118 10119## Logical Volume {#jsonrpc_components_lvol} 10120 10121Identification of logical volume store and logical volume is explained first. 10122 10123A logical volume store has a UUID and a name for its identification. 10124The UUID is generated on creation and it can be used as a unique identifier. 10125The name is specified on creation and can be renamed. 10126Either UUID or name is used to access logical volume store in RPCs. 10127 10128A logical volume has a UUID and a name for its identification. 10129The UUID of the logical volume is generated on creation and it can be unique identifier. 10130The alias of the logical volume takes the format _lvs_name/lvol_name_ where: 10131 10132* _lvs_name_ is the name of the logical volume store. 10133* _lvol_name_ is specified on creation and can be renamed. 10134 10135### bdev_lvol_create_lvstore {#rpc_bdev_lvol_create_lvstore} 10136 10137Construct a logical volume store. 10138 10139#### Parameters 10140 10141Name | Optional | Type | Description 10142----------------------------- | -------- | ----------- | ----------- 10143bdev_name | Required | string | Bdev on which to construct logical volume store 10144lvs_name | Required | string | Name of the logical volume store to create 10145cluster_sz | Optional | number | Cluster size of the logical volume store in bytes (Default: 4MiB) 10146clear_method | Optional | string | Change clear method for data region. Available: none, unmap (default), write_zeroes 10147num_md_pages_per_cluster_ratio| Optional | number | Reserved metadata pages per cluster (Default: 100) 10148 10149The num_md_pages_per_cluster_ratio defines the amount of metadata to 10150allocate when the logical volume store is created. The default value 10151is '100', which translates to 1 4KiB per cluster. For the default 4MiB 10152cluster size, this equates to about 0.1% of the underlying block 10153device allocated for metadata. Logical volume stores can be grown, if 10154the size of the underlying block device grows in the future, but only 10155if enough metadata pages were allocated to support the growth. So 10156num_md_pages_per_cluster_ratio should be set to a higher value if 10157wanting to support future growth. For example, 10158num_md_pages_per_cluster_ratio = 200 would support future 2x growth of 10159the logical volume store, and would result in 0.2% of the underlying 10160block device allocated for metadata (with a default 4MiB cluster 10161size). 10162 10163#### Response 10164 10165UUID of the created logical volume store is returned. 10166 10167#### Example 10168 10169Example request: 10170 10171~~~json 10172{ 10173 "jsonrpc": "2.0", 10174 "id": 1, 10175 "method": "bdev_lvol_create_lvstore", 10176 "params": { 10177 "lvs_name": "LVS0", 10178 "bdev_name": "Malloc0", 10179 "clear_method": "write_zeroes" 10180 } 10181} 10182~~~ 10183 10184Example response: 10185 10186~~~json 10187{ 10188 "jsonrpc": "2.0", 10189 "id": 1, 10190 "result": "a9959197-b5e2-4f2d-8095-251ffb6985a5" 10191} 10192~~~ 10193 10194### bdev_lvol_delete_lvstore {#rpc_bdev_lvol_delete_lvstore} 10195 10196Destroy a logical volume store. 10197 10198#### Parameters 10199 10200Name | Optional | Type | Description 10201----------------------- | -------- | ----------- | ----------- 10202uuid | Optional | string | UUID of the logical volume store to destroy 10203lvs_name | Optional | string | Name of the logical volume store to destroy 10204 10205Either uuid or lvs_name must be specified, but not both. 10206 10207#### Example 10208 10209Example request: 10210 10211~~~json 10212{ 10213 "jsonrpc": "2.0", 10214 "method": "bdev_lvol_delete_lvstore", 10215 "id": 1 10216 "params": { 10217 "uuid": "a9959197-b5e2-4f2d-8095-251ffb6985a5" 10218 } 10219} 10220~~~ 10221 10222Example response: 10223 10224~~~json 10225{ 10226 "jsonrpc": "2.0", 10227 "id": 1, 10228 "result": true 10229} 10230~~~ 10231 10232### bdev_lvol_get_lvstores {#rpc_bdev_lvol_get_lvstores} 10233 10234Get a list of logical volume stores. 10235 10236#### Parameters 10237 10238Name | Optional | Type | Description 10239----------------------- | -------- | ----------- | ----------- 10240uuid | Optional | string | UUID of the logical volume store to retrieve information about 10241lvs_name | Optional | string | Name of the logical volume store to retrieve information about 10242 10243Either uuid or lvs_name may be specified, but not both. 10244If both uuid and lvs_name are omitted, information about all logical volume stores is returned. 10245 10246#### Example 10247 10248Example request: 10249 10250~~~json 10251{ 10252 "jsonrpc": "2.0", 10253 "method": "bdev_lvol_get_lvstores", 10254 "id": 1, 10255 "params": { 10256 "lvs_name": "LVS0" 10257 } 10258} 10259~~~ 10260 10261Example response: 10262 10263~~~json 10264{ 10265 "jsonrpc": "2.0", 10266 "id": 1, 10267 "result": [ 10268 { 10269 "uuid": "a9959197-b5e2-4f2d-8095-251ffb6985a5", 10270 "base_bdev": "Malloc0", 10271 "free_clusters": 31, 10272 "cluster_size": 4194304, 10273 "total_data_clusters": 31, 10274 "block_size": 4096, 10275 "name": "LVS0" 10276 } 10277 ] 10278} 10279~~~ 10280 10281### bdev_lvol_rename_lvstore {#rpc_bdev_lvol_rename_lvstore} 10282 10283Rename a logical volume store. 10284 10285#### Parameters 10286 10287Name | Optional | Type | Description 10288----------------------- | -------- | ----------- | ----------- 10289old_name | Required | string | Existing logical volume store name 10290new_name | Required | string | New logical volume store name 10291 10292#### Example 10293 10294Example request: 10295 10296~~~json 10297{ 10298 "jsonrpc": "2.0", 10299 "method": "bdev_lvol_rename_lvstore", 10300 "id": 1, 10301 "params": { 10302 "old_name": "LVS0", 10303 "new_name": "LVS2" 10304 } 10305} 10306~~~ 10307 10308Example response: 10309 10310~~~json 10311{ 10312 "jsonrpc": "2.0", 10313 "id": 1, 10314 "result": true 10315} 10316~~~ 10317 10318### bdev_lvol_grow_lvstore {#rpc_bdev_lvol_grow_lvstore} 10319 10320Grow the logical volume store to fill the underlying bdev 10321 10322#### Parameters 10323 10324Name | Optional | Type | Description 10325----------------------- | -------- | ----------- | ----------- 10326uuid | Optional | string | UUID of the logical volume store to grow 10327lvs_name | Optional | string | Name of the logical volume store to grow 10328 10329Either uuid or lvs_name must be specified, but not both. 10330 10331#### Example 10332 10333Example request: 10334 10335~~~json 10336{ 10337 "jsonrpc": "2.0", 10338 "method": "bdev_lvol_grow_lvstore", 10339 "id": 1 10340 "params": { 10341 "uuid": "a9959197-b5e2-4f2d-8095-251ffb6985a5" 10342 } 10343} 10344~~~ 10345 10346Example response: 10347 10348~~~json 10349{ 10350 "jsonrpc": "2.0", 10351 "id": 1, 10352 "result": true 10353} 10354~~~ 10355 10356### bdev_lvol_create {#rpc_bdev_lvol_create} 10357 10358Create a logical volume on a logical volume store. 10359 10360#### Parameters 10361 10362Name | Optional | Type | Description 10363----------------------- | -------- | ----------- | ----------- 10364lvol_name | Required | string | Name of logical volume to create 10365size_in_mib | Required | number | Desired size of logical volume in MiB 10366thin_provision | Optional | boolean | True to enable thin provisioning 10367uuid | Optional | string | UUID of logical volume store to create logical volume on 10368lvs_name | Optional | string | Name of logical volume store to create logical volume on 10369clear_method | Optional | string | Change default data clusters clear method. Available: none, unmap, write_zeroes 10370 10371Size will be rounded up to a multiple of cluster size. Either uuid or lvs_name must be specified, but not both. 10372lvol_name will be used in the alias of the created logical volume. 10373 10374#### Response 10375 10376UUID of the created logical volume is returned. 10377 10378#### Example 10379 10380Example request: 10381 10382~~~json 10383{ 10384 "jsonrpc": "2.0", 10385 "method": "bdev_lvol_create", 10386 "id": 1, 10387 "params": { 10388 "lvol_name": "LVOL0", 10389 "size_in_mib": 1, 10390 "lvs_name": "LVS0", 10391 "clear_method": "unmap", 10392 "thin_provision": true 10393 } 10394} 10395~~~ 10396 10397Example response: 10398 10399~~~json 10400{ 10401 "jsonrpc": "2.0", 10402 "id": 1, 10403 "result": "1b38702c-7f0c-411e-a962-92c6a5a8a602" 10404} 10405~~~ 10406 10407### bdev_lvol_snapshot {#rpc_bdev_lvol_snapshot} 10408 10409Capture a snapshot of the current state of a logical volume. 10410 10411#### Parameters 10412 10413Name | Optional | Type | Description 10414----------------------- | -------- | ----------- | ----------- 10415lvol_name | Required | string | UUID or alias of the logical volume to create a snapshot from 10416snapshot_name | Required | string | Name for the newly created snapshot 10417 10418#### Response 10419 10420UUID of the created logical volume snapshot is returned. 10421 10422#### Example 10423 10424Example request: 10425 10426~~~json 10427{ 10428 "jsonrpc": "2.0", 10429 "method": "bdev_lvol_snapshot", 10430 "id": 1, 10431 "params": { 10432 "lvol_name": "1b38702c-7f0c-411e-a962-92c6a5a8a602", 10433 "snapshot_name": "SNAP1" 10434 } 10435} 10436~~~ 10437 10438Example response: 10439 10440~~~json 10441{ 10442 "jsonrpc": "2.0", 10443 "id": 1, 10444 "result": "cc8d7fdf-7865-4d1f-9fc6-35da8e368670" 10445} 10446~~~ 10447 10448### bdev_lvol_clone {#rpc_bdev_lvol_clone} 10449 10450Create a logical volume based on a snapshot. 10451 10452#### Parameters 10453 10454Name | Optional | Type | Description 10455----------------------- | -------- | ----------- | ----------- 10456snapshot_name | Required | string | UUID or alias of the snapshot to clone 10457clone_name | Required | string | Name for the logical volume to create 10458 10459#### Response 10460 10461UUID of the created logical volume clone is returned. 10462 10463#### Example 10464 10465Example request: 10466 10467~~~json 10468{ 10469 "jsonrpc": "2.0" 10470 "method": "bdev_lvol_clone", 10471 "id": 1, 10472 "params": { 10473 "snapshot_name": "cc8d7fdf-7865-4d1f-9fc6-35da8e368670", 10474 "clone_name": "CLONE1" 10475 } 10476} 10477~~~ 10478 10479Example response: 10480 10481~~~json 10482{ 10483 "jsonrpc": "2.0", 10484 "id": 1, 10485 "result": "8d87fccc-c278-49f0-9d4c-6237951aca09" 10486} 10487~~~ 10488 10489### bdev_lvol_clone_bdev {#rpc_bdev_lvol_clone_bdev} 10490 10491Create a logical volume based on an external snapshot bdev. The external snapshot bdev 10492is a bdev that will not be written to by any consumer and must not be an lvol in the 10493lvstore as the clone. 10494 10495Regardless of whether the bdev is specified by name or UUID, the bdev UUID will be stored 10496in the logical volume's metadata for use while the lvolstore is loading. For this reason, 10497it is important that the bdev chosen has a static UUID. 10498 10499#### Parameters 10500 10501Name | Optional | Type | Description 10502----------------------- | -------- | ----------- | ----------- 10503bdev | Required | string | Name or UUID for bdev that acts as the external snapshot 10504lvs_name | Required | string | logical volume store name 10505clone_name | Required | string | Name for the logical volume to create 10506 10507#### Response 10508 10509UUID of the created logical volume clone is returned. 10510 10511#### Example 10512 10513Example request: 10514 10515~~~json 10516{ 10517 "jsonrpc": "2.0", 10518 "method": "bdev_lvol_clone_bdev", 10519 "id": 1, 10520 "params": { 10521 "bdev": "e4b40d8b-f623-416d-8234-baf5a4c83cbd", 10522 "lvs_name": "lvs1", 10523 "clone_name": "clone2" 10524 } 10525} 10526~~~ 10527 10528Example response: 10529 10530~~~json 10531{ 10532 "jsonrpc": "2.0", 10533 "id": 1, 10534 "result": "336f662b-08e5-4006-8e06-e2023f7f9886" 10535} 10536~~~ 10537 10538### bdev_lvol_rename {#rpc_bdev_lvol_rename} 10539 10540Rename a logical volume. New name will rename only the alias of the logical volume. 10541 10542#### Parameters 10543 10544Name | Optional | Type | Description 10545----------------------- | -------- | ----------- | ----------- 10546old_name | Required | string | UUID or alias of the existing logical volume 10547new_name | Required | string | New logical volume name 10548 10549#### Example 10550 10551Example request: 10552 10553~~~json 10554{ 10555 "jsonrpc": "2.0", 10556 "method": "bdev_lvol_rename", 10557 "id": 1, 10558 "params": { 10559 "old_name": "067df606-6dbc-4143-a499-0d05855cb3b8", 10560 "new_name": "LVOL2" 10561 } 10562} 10563~~~ 10564 10565Example response: 10566 10567~~~json 10568{ 10569 "jsonrpc": "2.0", 10570 "id": 1, 10571 "result": true 10572} 10573~~~ 10574 10575### bdev_lvol_resize {#rpc_bdev_lvol_resize} 10576 10577Resize a logical volume. 10578 10579#### Parameters 10580 10581Name | Optional | Type | Description 10582----------------------- | -------- | ----------- | ----------- 10583name | Required | string | UUID or alias of the logical volume to resize 10584size_in_mib | Required | number | Desired size of the logical volume in MiB 10585 10586#### Example 10587 10588Example request: 10589 10590~~~json 10591{ 10592 "jsonrpc": "2.0", 10593 "method": "bdev_lvol_resize", 10594 "id": 1, 10595 "params": { 10596 "name": "51638754-ca16-43a7-9f8f-294a0805ab0a", 10597 "size_in_mib": 2 10598 } 10599} 10600~~~ 10601 10602Example response: 10603 10604~~~json 10605{ 10606 "jsonrpc": "2.0", 10607 "id": 1, 10608 "result": true 10609} 10610~~~ 10611 10612### bdev_lvol_set_read_only{#rpc_bdev_lvol_set_read_only} 10613 10614Mark logical volume as read only. 10615 10616#### Parameters 10617 10618Name | Optional | Type | Description 10619----------------------- | -------- | ----------- | ----------- 10620name | Required | string | UUID or alias of the logical volume to set as read only 10621 10622#### Example 10623 10624Example request: 10625 10626~~~json 10627{ 10628 "jsonrpc": "2.0", 10629 "method": "bdev_lvol_set_read_only", 10630 "id": 1, 10631 "params": { 10632 "name": "51638754-ca16-43a7-9f8f-294a0805ab0a", 10633 } 10634} 10635~~~ 10636 10637Example response: 10638 10639~~~json 10640{ 10641 "jsonrpc": "2.0", 10642 "id": 1, 10643 "result": true 10644} 10645~~~ 10646 10647### bdev_lvol_delete {#rpc_bdev_lvol_delete} 10648 10649Destroy a logical volume. 10650 10651#### Parameters 10652 10653Name | Optional | Type | Description 10654----------------------- | -------- | ----------- | ----------- 10655name | Required | string | UUID or alias of the logical volume to destroy 10656 10657#### Example 10658 10659Example request: 10660 10661~~~json 10662{ 10663 "jsonrpc": "2.0", 10664 "method": "bdev_lvol_delete", 10665 "id": 1, 10666 "params": { 10667 "name": "51638754-ca16-43a7-9f8f-294a0805ab0a" 10668 } 10669} 10670~~~ 10671 10672Example response: 10673 10674~~~json 10675{ 10676 "jsonrpc": "2.0", 10677 "id": 1, 10678 "result": true 10679} 10680~~~ 10681 10682### bdev_lvol_inflate {#rpc_bdev_lvol_inflate} 10683 10684Inflate a logical volume. All unallocated clusters are allocated and copied from the parent or zero filled 10685if not allocated in the parent. Then all dependencies on the parent are removed. 10686 10687### Parameters 10688 10689Name | Optional | Type | Description 10690----------------------- | -------- | ----------- | ----------- 10691name | Required | string | UUID or alias of the logical volume to inflate 10692 10693#### Example 10694 10695Example request: 10696 10697~~~json 10698{ 10699 "jsonrpc": "2.0", 10700 "method": "bdev_lvol_inflate", 10701 "id": 1, 10702 "params": { 10703 "name": "8d87fccc-c278-49f0-9d4c-6237951aca09" 10704 } 10705} 10706~~~ 10707 10708Example response: 10709 10710~~~json 10711{ 10712 "jsonrpc": "2.0", 10713 "id": 1, 10714 "result": true 10715} 10716~~~ 10717 10718### bdev_lvol_decouple_parent {#rpc_bdev_lvol_decouple_parent} 10719 10720Decouple the parent of a logical volume. For unallocated clusters which is allocated in the parent, they are 10721allocated and copied from the parent, but for unallocated clusters which is thin provisioned in the parent, 10722they are kept thin provisioned. Then all dependencies on the parent are removed. 10723 10724#### Parameters 10725 10726Name | Optional | Type | Description 10727----------------------- | -------- | ----------- | ----------- 10728name | Required | string | UUID or alias of the logical volume to decouple the parent of it 10729 10730#### Example 10731 10732Example request: 10733 10734~~~json 10735{ 10736 "jsonrpc": "2.0", 10737 "method": "bdev_lvol_decouple_parent", 10738 "id": 1. 10739 "params": { 10740 "name": "8d87fccc-c278-49f0-9d4c-6237951aca09" 10741 } 10742} 10743~~~ 10744 10745Example response: 10746 10747~~~json 10748{ 10749 "jsonrpc": "2.0", 10750 "id": 1, 10751 "result": true 10752} 10753~~~ 10754 10755### bdev_lvol_get_lvols {#rpc_bdev_lvol_get_lvols} 10756 10757Get a list of logical volumes. This list can be limited by lvol store and will display volumes even if 10758they are degraded. Degraded lvols do not have an associated bdev, thus this RPC call may return lvols 10759not returned by `bdev_get_bdevs`. 10760 10761#### Parameters 10762 10763Name | Optional | Type | Description 10764----------------------- | -------- | ----------- | ----------- 10765lvs_uuid | Optional | string | Only show volumes in the logical volume store with this UUID 10766lvs_name | Optional | string | Only show volumes in the logical volume store with this name 10767 10768Either lvs_uuid or lvs_name may be specified, but not both. 10769If both lvs_uuid and lvs_name are omitted, information about lvols in all logical volume stores is returned. 10770 10771#### Example 10772 10773Example request: 10774 10775~~~json 10776{ 10777 "jsonrpc": "2.0", 10778 "method": "bdev_lvol_get_lvols", 10779 "id": 1, 10780 "params": { 10781 "lvs_name": "lvs_test" 10782 } 10783} 10784~~~ 10785 10786Example response: 10787 10788~~~json 10789[ 10790 { 10791 "alias": "lvs_test/lvol1", 10792 "uuid": "b335c368-851d-4099-81e0-018cc494fdf6", 10793 "name": "lvol1", 10794 "is_thin_provisioned": false, 10795 "is_snapshot": false, 10796 "is_clone": false, 10797 "is_esnap_clone": false, 10798 "is_degraded": false, 10799 "lvs": { 10800 "name": "lvs_test", 10801 "uuid": "a1c8d950-5715-4558-936d-ab9e6eca0794" 10802 } 10803 } 10804] 10805~~~ 10806 10807### bdev_lvol_set_parent {#rpc_bdev_lvol_set_parent} 10808 10809Set a snapshot as the parent of a lvol, making the lvol a clone of this snapshot. 10810The previous parent of the lvol, if any, can be another snapshot or an external snapshot; if the 10811lvol is not a clone, it must be thin-provisioned. 10812Lvol and parent snapshot must have the same size and must belong to the same lvol store. 10813 10814#### Parameters 10815 10816Name | Optional | Type | Description 10817----------------------- | -------- | ----------- | ----------- 10818lvol_name | Required | string | UUID or alias of the lvol to set parent of 10819parent_name | Required | string | UUID or alias of the snapshot to become parent of lvol 10820 10821#### Example 10822 10823Example request: 10824 10825~~~json 10826{ 10827 "jsonrpc": "2.0", 10828 "method": "bdev_lvol_set_parent", 10829 "id": 1, 10830 "params": { 10831 "lvol_name": "LVS1/LVOL0", 10832 "parent_name": "LVS1/SNAP0" 10833 } 10834} 10835~~~ 10836 10837Example response: 10838 10839~~~json 10840{ 10841 "jsonrpc": "2.0", 10842 "id": 1, 10843 "result": true 10844} 10845~~~ 10846 10847### bdev_lvol_set_parent_bdev {#rpc_bdev_lvol_set_parent_bdev} 10848 10849Set an external snapshot as the parent of a lvol, making the lvol a clone of this external 10850snapshot (see @ref rpc_bdev_lvol_clone_bdev). 10851The previous parent of the lvol, if any, can be another external snapshot or a snapshot; if the 10852lvol is not a clone, it must be thin-provisioned. 10853The size of the external snapshot device must be an integer multiple of cluster size of lvol's lvolstore. 10854 10855#### Parameters 10856 10857Name | Optional | Type | Description 10858----------------------- | -------- | ----------- | ----------- 10859lvol_name | Required | string | UUID or alias of the lvol to set external parent of 10860parent_name | Required | string | UUID or name of the external snapshot to become parent of lvol 10861 10862#### Example 10863 10864Example request: 10865 10866~~~json 10867{ 10868 "jsonrpc": "2.0", 10869 "method": "bdev_lvol_set_parent_bdev", 10870 "id": 1, 10871 "params": { 10872 "lvol_name": "LVS1/LVOL0", 10873 "parent_name": "e465527b-f412-4f70-a03e-c4a5d608f65e" 10874 } 10875} 10876~~~ 10877 10878Example response: 10879 10880~~~json 10881{ 10882 "jsonrpc": "2.0", 10883 "id": 1, 10884 "result": true 10885} 10886~~~ 10887 10888### bdev_lvol_start_shallow_copy {#rpc_bdev_lvol_start_shallow_copy} 10889 10890Start a shallow copy of an lvol over a given bdev. Only clusters allocated to the lvol will be written on the bdev. 10891Must have: 10892 10893* lvol read only 10894* lvol size less or equal than bdev size 10895* lvstore block size an even multiple of bdev block size 10896 10897#### Result 10898 10899This RPC starts the operation and return an identifier that can be used to query the status of the operation 10900with the RPC @ref rpc_bdev_lvol_check_shallow_copy. 10901 10902#### Parameters 10903 10904Name | Optional | Type | Description 10905----------------------- | -------- | ----------- | ----------- 10906src_lvol_name | Required | string | UUID or alias of lvol to create a copy from 10907dst_bdev_name | Required | string | Name of the bdev that acts as destination for the copy 10908 10909#### Example 10910 10911Example request: 10912 10913~~~json 10914{ 10915 "jsonrpc": "2.0", 10916 "method": "bdev_lvol_start_shallow_copy", 10917 "id": 1, 10918 "params": { 10919 "src_lvol_name": "8a47421a-20cf-444f-845c-d97ad0b0bd8e", 10920 "dst_bdev_name": "Nvme1n1" 10921 } 10922} 10923~~~ 10924 10925Example response: 10926 10927~~~json 10928{ 10929 "jsonrpc": "2.0", 10930 "id": 1, 10931 "result": { 10932 "operation_id": 7 10933 } 10934} 10935~~~ 10936 10937### bdev_lvol_check_shallow_copy {#rpc_bdev_lvol_check_shallow_copy} 10938 10939Get shallow copy status. 10940 10941#### Result 10942 10943Get info about the shallow copy operation identified by operation id. 10944It reports operation's status, which can be `in progress`, `complete` or `error`, 10945the actual number of copied clusters, the total number of clusters to copy and, 10946in case of error, a description. 10947Once the operation is ended and the result has been retrieved, the 10948operation is removed from the internal list of ended operation, so its 10949result cannot be accessed anymore. 10950 10951#### Parameters 10952 10953Name | Optional | Type | Description 10954----------------------- | -------- | ----------- | ----------- 10955operation_id | Required | number | operation identifier 10956 10957#### Example 10958 10959Example request: 10960 10961~~~json 10962{ 10963 "jsonrpc": "2.0", 10964 "method": "bdev_lvol_check_shallow_copy", 10965 "id": 1, 10966 "params": { 10967 "operation_id": 7 10968 } 10969} 10970~~~ 10971 10972Example response: 10973 10974~~~json 10975{ 10976 "jsonrpc": "2.0", 10977 "id": 1, 10978 "result": { 10979 "state": "in progress", 10980 "copied_clusters": 2, 10981 "total_clusters": 4 10982 } 10983} 10984~~~ 10985 10986## RAID 10987 10988### bdev_raid_set_options {#rpc_bdev_raid_set_options} 10989 10990Set options for bdev raid. 10991 10992This RPC can be called at any time, but the new value will only take effect for new raid bdevs. 10993 10994The `process_window_size_kb` parameter defines the size of the "window" (LBA range of the raid bdev) 10995in which a background process like rebuild performs its work. Any positive value is valid, but the value 10996actually used by a raid bdev can be adjusted to the size of the raid bdev or the write unit size. 10997`process_max_bandwidth_mb_sec` parameter defines the maximum bandwidth used by a background process like 10998rebuild. Any positive value or zero is valid, zero means no bandwidth limitation for background process. 10999It can only limit the process bandwidth but doesn't guarantee it can be reached. Changing this value will 11000not affect existing processes, it will only take effect on new processes generated after the RPC is completed. 11001 11002#### Parameters 11003 11004Name | Optional | Type | Description 11005----------------------------- | -------- | ----------- | ----------- 11006process_window_size_kb | Optional | number | Background process (e.g. rebuild) window size in KiB 11007process_max_bandwidth_mb_sec | Optional | number | Background process (e.g. rebuild) maximum bandwidth in MiB/Sec 11008 11009#### Example 11010 11011Example request: 11012 11013~~~json 11014request: 11015{ 11016 "jsonrpc": "2.0", 11017 "method": "bdev_raid_set_options", 11018 "id": 1, 11019 "params": { 11020 "process_window_size_kb": 512, 11021 "process_max_bandwidth_mb_sec": 100 11022 } 11023} 11024~~~ 11025 11026Example response: 11027 11028~~~json 11029{ 11030 "jsonrpc": "2.0", 11031 "id": 1, 11032 "result": true 11033} 11034~~~ 11035 11036### bdev_raid_get_bdevs {#rpc_bdev_raid_get_bdevs} 11037 11038This is used to list all the raid bdev details based on the input category requested. Category should be one 11039of 'all', 'online', 'configuring' or 'offline'. 'all' means all the raid bdevs whether they are online or 11040configuring or offline. 'online' is the raid bdev which is registered with bdev layer. 'configuring' is 11041the raid bdev which does not have full configuration discovered yet. 'offline' is the raid bdev which is 11042not registered with bdev as of now and it has encountered any error or user has requested to offline 11043the raid bdev. 11044 11045#### Parameters 11046 11047Name | Optional | Type | Description 11048----------------------- | -------- | ----------- | ----------- 11049category | Required | string | all or online or configuring or offline 11050 11051#### Example 11052 11053Example request: 11054 11055~~~json 11056{ 11057 "jsonrpc": "2.0", 11058 "method": "bdev_raid_get_bdevs", 11059 "id": 1, 11060 "params": { 11061 "category": "all" 11062 } 11063} 11064~~~ 11065 11066Example response: 11067 11068~~~json 11069{ 11070 "jsonrpc": "2.0", 11071 "id": 1, 11072 "result": [ 11073 { 11074 "name": "RaidBdev0", 11075 "uuid": "7d352e83-fe27-40f2-8fef-64563355e076", 11076 "strip_size_kb": 128, 11077 "state": "online", 11078 "raid_level": "raid0", 11079 "num_base_bdevs": 2, 11080 "num_base_bdevs_discovered": 2, 11081 "num_base_bdevs_operational": 2, 11082 "base_bdevs_list": [ 11083 { 11084 "name": "malloc0", 11085 "uuid": "d2788884-5b3e-4fd7-87ff-6c78177e14ab", 11086 "is_configured": true, 11087 "data_offset": 256, 11088 "data_size": 261888 11089 }, 11090 { 11091 "name": "malloc1", 11092 "uuid": "a81bb1f8-5865-488a-8758-10152017e7d1", 11093 "is_configured": true, 11094 "data_offset": 256, 11095 "data_size": 261888 11096 } 11097 ] 11098 }, 11099 { 11100 "name": "RaidBdev1", 11101 "uuid": "f7cb71ed-2d0e-4240-979e-27b0b7735f36", 11102 "strip_size_kb": 128, 11103 "state": "configuring", 11104 "raid_level": "raid0", 11105 "num_base_bdevs": 2, 11106 "num_base_bdevs_discovered": 1, 11107 "num_base_bdevs_operational": 2, 11108 "base_bdevs_list": [ 11109 { 11110 "name": "malloc2", 11111 "uuid": "f60c20e1-3439-4f89-ae55-965a70333f86", 11112 "is_configured": true, 11113 "data_offset": 256, 11114 "data_size": 261888 11115 } 11116 { 11117 "name": "malloc3", 11118 "uuid": "00000000-0000-0000-0000-000000000000", 11119 "is_configured": false, 11120 "data_offset": 0, 11121 "data_size": 0 11122 } 11123 ] 11124 } 11125 ] 11126} 11127~~~ 11128 11129### bdev_raid_create {#rpc_bdev_raid_create} 11130 11131Constructs new RAID bdev. 11132 11133#### Parameters 11134 11135Name | Optional | Type | Description 11136----------------------- | -------- | ----------- | ----------- 11137name | Required | string | RAID bdev name 11138strip_size_kb | Required | number | Strip size in KB 11139raid_level | Required | string | RAID level 11140base_bdevs | Required | string | Base bdevs name, whitespace separated list in quotes 11141uuid | Optional | string | UUID for this RAID bdev 11142superblock | Optional | boolean | If set, information about raid bdev will be stored in superblock on each base bdev (default: `false`) 11143 11144#### Example 11145 11146Example request: 11147 11148~~~json 11149{ 11150 "jsonrpc": "2.0", 11151 "method": "bdev_raid_create", 11152 "id": 1, 11153 "params": { 11154 "name": "Raid0", 11155 "raid_level": "0", 11156 "base_bdevs": [ 11157 "Malloc0", 11158 "Malloc1", 11159 "Malloc2", 11160 "Malloc3" 11161 ], 11162 "strip_size_kb": 4 11163 } 11164} 11165~~~ 11166 11167Example response: 11168 11169~~~json 11170{ 11171 "jsonrpc": "2.0", 11172 "id": 1, 11173 "result": true 11174} 11175~~~ 11176 11177### bdev_raid_delete {#rpc_bdev_raid_delete} 11178 11179Removes RAID bdev. 11180 11181#### Parameters 11182 11183Name | Optional | Type | Description 11184----------------------- | -------- | ----------- | ----------- 11185name | Required | string | RAID bdev name 11186 11187#### Example 11188 11189Example request: 11190 11191~~~json 11192{ 11193 "jsonrpc": "2.0", 11194 "method": "bdev_raid_delete", 11195 "id": 1, 11196 "params": { 11197 "name": "Raid0" 11198 } 11199} 11200~~~ 11201 11202Example response: 11203 11204~~~json 11205{ 11206 "jsonrpc": "2.0", 11207 "id": 1, 11208 "result": true 11209} 11210~~~ 11211 11212### bdev_raid_add_base_bdev {#rpc_bdev_raid_add_base_bdev} 11213 11214Add base bdev to existing raid bdev. The raid bdev must have an empty base bdev slot. 11215The bdev must be large enough and have the same block size and metadata format as the other base bdevs. 11216 11217#### Parameters 11218 11219Name | Optional | Type | Description 11220----------------------- | -------- | ----------- | ----------- 11221raid_bdev | Required | string | Raid bdev name 11222base_bdev | Required | string | Base bdev name 11223 11224#### Example 11225 11226Example request: 11227 11228~~~json 11229{ 11230 "jsonrpc": "2.0", 11231 "method": "bdev_raid_add_base_bdev", 11232 "id": 1, 11233 "params": { 11234 "raid_bdev": "RaidBdev0", 11235 "base_bdev": "Nvme0n1" 11236 } 11237} 11238~~~ 11239 11240Example response: 11241 11242~~~json 11243{ 11244 "jsonrpc": "2.0", 11245 "id": 1, 11246 "result": true 11247} 11248~~~ 11249### bdev_raid_remove_base_bdev {#rpc_bdev_raid_remove_base_bdev} 11250 11251Remove base bdev from existing raid bdev. 11252 11253#### Parameters 11254 11255Name | Optional | Type | Description 11256----------------------- | -------- | ----------- | ----------- 11257name | Required | string | Base bdev name in RAID 11258 11259#### Example 11260 11261Example request: 11262 11263~~~json 11264{ 11265 "jsonrpc": "2.0", 11266 "method": "bdev_raid_remove_base_bdev", 11267 "id": 1, 11268 "params": { 11269 "name": "Raid0" 11270 } 11271} 11272~~~ 11273 11274Example response: 11275 11276~~~json 11277{ 11278 "jsonrpc": "2.0", 11279 "id": 1, 11280 "result": true 11281} 11282~~~ 11283 11284## SPLIT 11285 11286### bdev_split_create {#rpc_bdev_split_create} 11287 11288This is used to split an underlying block device and create several smaller equal-sized vbdevs. 11289 11290#### Parameters 11291 11292Name | Optional | Type | Description 11293----------------------- | -------- | ----------- | ----------- 11294base_bdev | Required | string | base bdev name 11295split_count | Required | number | number of splits 11296split_size_mb | Optional | number | size in MB to restrict the size 11297 11298#### Example 11299 11300Example request: 11301 11302~~~json 11303{ 11304 "jsonrpc": "2.0", 11305 "method": "bdev_split_create", 11306 "id": 1, 11307 "params": { 11308 "base_bdev": "Malloc0", 11309 "split_count": 4 11310 } 11311} 11312~~~ 11313 11314Example response: 11315 11316~~~json 11317{ 11318 "jsonrpc": "2.0", 11319 "id": 1, 11320 "result": [ 11321 "Malloc0p0", 11322 "Malloc0p1", 11323 "Malloc0p2", 11324 "Malloc0p3" 11325 ] 11326} 11327~~~ 11328 11329### bdev_split_delete {#rpc_bdev_split_delete} 11330 11331This is used to remove the split vbdevs. 11332 11333#### Parameters 11334 11335Name | Optional | Type | Description 11336----------------------- | -------- | ----------- | ----------- 11337base_bdev | Required | string | base bdev name 11338 11339#### Example 11340 11341Example request: 11342 11343~~~json 11344{ 11345 "jsonrpc": "2.0", 11346 "method": "bdev_split_delete", 11347 "id": 1, 11348 "params": { 11349 "base_bdev": "Malloc0" 11350 } 11351} 11352~~~ 11353 11354Example response: 11355 11356~~~json 11357{ 11358 "jsonrpc": "2.0", 11359 "id": 1, 11360 "result": true 11361} 11362~~~ 11363 11364## Uring 11365 11366### bdev_uring_create {#rpc_bdev_uring_create} 11367 11368Create a bdev with io_uring backend. 11369 11370#### Parameters 11371 11372Name | Optional | Type | Description 11373----------------------- | -------- | ----------- | ----------- 11374filename | Required | string | path to device or file (ex: /dev/nvme0n1) 11375name | Required | string | name of bdev 11376block_size | Optional | number | block size of device (If omitted, get the block size from the file) 11377uuid | Optional | string | UUID of new bdev 11378 11379#### Example 11380 11381Example request: 11382 11383~~~json 11384{ 11385 "jsonrpc": "2.0", 11386 "method": "bdev_uring_create", 11387 "id": 1, 11388 "params": { 11389 "name": "bdev_u0", 11390 "filename": "/dev/nvme0n1", 11391 "block_size": 512 11392 } 11393} 11394~~~ 11395 11396Example response: 11397 11398~~~json 11399{ 11400 "jsonrpc": "2.0", 11401 "id": 1, 11402 "result": "bdev_u0" 11403} 11404~~~ 11405 11406### bdev_uring_rescan {#rpc_bdev_uring_rescan} 11407 11408Rescan the size of a uring bdev. 11409 11410#### Parameters 11411 11412Name | Optional | Type | Description 11413---- | -------- | ------ | ----------- 11414name | Required | string | name of uring bdev to rescan 11415 11416#### Example 11417 11418Example request: 11419 11420~~~json 11421{ 11422 "jsonrpc": "2.0", 11423 "method": "bdev_uring_rescan", 11424 "id": 1, 11425 "params": { 11426 "name": "bdev_u0" 11427 } 11428} 11429~~~ 11430 11431Example response: 11432 11433~~~json 11434{ 11435 "jsonrpc": "2.0", 11436 "id": 1, 11437 "result": true 11438} 11439~~~ 11440 11441### bdev_uring_delete {#rpc_bdev_uring_delete} 11442 11443Remove a uring bdev. 11444 11445#### Parameters 11446 11447Name | Optional | Type | Description 11448----------------------- | -------- | ----------- | ----------- 11449name | Required | string | name of uring bdev to delete 11450 11451#### Example 11452 11453Example request: 11454 11455~~~json 11456{ 11457 "jsonrpc": "2.0", 11458 "method": "bdev_uring_delete", 11459 "id": 1, 11460 "params": { 11461 "name": "bdev_u0" 11462 } 11463} 11464~~~ 11465 11466Example response: 11467 11468~~~json 11469{ 11470 "jsonrpc": "2.0", 11471 "id": 1, 11472 "result": true 11473} 11474~~~ 11475 11476## OPAL 11477 11478### bdev_nvme_opal_init {#rpc_bdev_nvme_opal_init} 11479 11480This is used to initialize OPAL of a given NVMe ctrlr, including taking ownership and activating. 11481 11482#### Parameters 11483 11484Name | Optional | Type | Description 11485----------------------- | -------- | ----------- | ----------- 11486nvme_ctrlr_name | Required | string | name of nvme ctrlr 11487password | Required | string | admin password of OPAL 11488 11489#### Example 11490 11491Example request: 11492 11493~~~json 11494{ 11495 "jsonrpc": "2.0", 11496 "method": "bdev_nvme_opal_init", 11497 "id": 1, 11498 "params": { 11499 "nvme_ctrlr_name": "nvme0", 11500 "password": "*****" 11501 } 11502} 11503~~~ 11504 11505Example response: 11506 11507~~~json 11508{ 11509 "jsonrpc": "2.0", 11510 "id": 1, 11511 "result": true 11512} 11513~~~ 11514 11515### bdev_nvme_opal_revert {#rpc_bdev_nvme_opal_revert} 11516 11517This is used to revert OPAL to its factory settings. Erase all user configuration and data. 11518 11519#### Parameters 11520 11521Name | Optional | Type | Description 11522----------------------- | -------- | ----------- | ----------- 11523nvme_ctrlr_name | Required | string | name of nvme ctrlr 11524password | Required | string | admin password of OPAL 11525 11526#### Example 11527 11528Example request: 11529 11530~~~json 11531{ 11532 "jsonrpc": "2.0", 11533 "method": "bdev_nvme_opal_revert", 11534 "id": 1, 11535 "params": { 11536 "nvme_ctrlr_name": "nvme0", 11537 "password": "*****" 11538 } 11539} 11540~~~ 11541 11542Example response: 11543 11544~~~json 11545{ 11546 "jsonrpc": "2.0", 11547 "id": 1, 11548 "result": true 11549} 11550~~~ 11551 11552### bdev_opal_create {#rpc_bdev_opal_create} 11553 11554This is used to create an OPAL virtual bdev. 11555 11556#### Parameters 11557 11558Name | Optional | Type | Description 11559----------------------- | -------- | ----------- | ----------- 11560nvme_ctrlr_name | Required | string | name of nvme ctrlr that supports OPAL 11561nsid | Required | number | namespace ID 11562locking_range_id | Required | number | OPAL locking range ID 11563range_start | Required | number | locking range start LBA 11564range_length | Required | number | locking range length 11565password | Required | string | admin password of OPAL 11566 11567#### Response 11568 11569The response is the name of created OPAL virtual bdev. 11570 11571#### Example 11572 11573Example request: 11574 11575~~~json 11576{ 11577 "jsonrpc": "2.0", 11578 "method": "bdev_opal_create", 11579 "id": 1, 11580 "params": { 11581 "nvme_ctrlr_name": "nvme0", 11582 "nsid": 1, 11583 "locking_range_id": 1, 11584 "range_start": 0, 11585 "range_length": 4096, 11586 "password": "*****" 11587 } 11588} 11589~~~ 11590 11591Example response: 11592 11593~~~json 11594{ 11595 "jsonrpc": "2.0", 11596 "id": 1, 11597 "result": "nvme0n1r1" 11598} 11599~~~ 11600 11601### bdev_opal_get_info {#rpc_bdev_opal_get_info} 11602 11603This is used to get information of a given OPAL bdev. 11604 11605#### Parameters 11606 11607Name | Optional | Type | Description 11608----------------------- | -------- | ----------- | ----------- 11609bdev_name | Required | string | name of OPAL vbdev 11610password | Required | string | admin password 11611 11612#### Response 11613 11614The response is the locking info of OPAL virtual bdev. 11615 11616#### Example 11617 11618Example request: 11619 11620~~~json 11621{ 11622 "jsonrpc": "2.0", 11623 "method": "bdev_opal_get_info", 11624 "id": 1, 11625 "params": { 11626 "bdev_name": "nvme0n1r1", 11627 "password": "*****" 11628 } 11629} 11630~~~ 11631 11632Example response: 11633 11634~~~json 11635{ 11636 "jsonrpc": "2.0", 11637 "id": 1, 11638 "result": { 11639 "name": "nvme0n1r1", 11640 "range_start": 0, 11641 "range_length": 4096, 11642 "read_lock_enabled": true, 11643 "write_lock_enabled": true, 11644 "read_locked": false, 11645 "write_locked": false 11646 } 11647} 11648~~~ 11649 11650### bdev_opal_delete {#rpc_bdev_opal_delete} 11651 11652This is used to delete OPAL vbdev. 11653 11654#### Parameters 11655 11656Name | Optional | Type | Description 11657----------------------- | -------- | ----------- | ----------- 11658bdev_name | Required | string | name of OPAL vbdev 11659password | Required | string | admin password 11660 11661#### Example 11662 11663Example request: 11664 11665~~~json 11666{ 11667 "jsonrpc": "2.0", 11668 "method": "bdev_opal_delete", 11669 "id": 1, 11670 "params": { 11671 "bdev_name": "nvme0n1r1", 11672 "password": "*****" 11673 } 11674} 11675~~~ 11676 11677Example response: 11678 11679~~~json 11680{ 11681 "jsonrpc": "2.0", 11682 "id": 1, 11683 "result": true 11684} 11685~~~ 11686 11687### bdev_opal_new_user {#rpc_bdev_opal_new_user} 11688 11689This enables a new user to the specified opal bdev so that the user can lock/unlock the bdev. 11690Recalling this for the same opal bdev, only the newest user will have the privilege. 11691 11692#### Parameters 11693 11694Name | Optional | Type | Description 11695----------------------- | -------- | ----------- | ----------- 11696bdev_name | Required | string | name of OPAL vbdev 11697admin_password | Required | string | admin password 11698user_id | Required | number | user ID 11699user_password | Required | string | user password 11700 11701#### Example 11702 11703Example request: 11704 11705~~~json 11706{ 11707 "jsonrpc": "2.0", 11708 "method": "bdev_opal_new_user", 11709 "id": 1, 11710 "params": { 11711 "bdev_name": "nvme0n1r1", 11712 "admin_password": "*****", 11713 "user_id": "1", 11714 "user_password": "********" 11715 } 11716} 11717~~~ 11718 11719Example response: 11720 11721~~~json 11722{ 11723 "jsonrpc": "2.0", 11724 "id": 1, 11725 "result": true 11726} 11727~~~ 11728 11729### bdev_opal_set_lock_state {#rpc_bdev_opal_set_lock_state} 11730 11731This is used to lock/unlock specific opal bdev providing user ID and password. 11732 11733#### Parameters 11734 11735Name | Optional | Type | Description 11736----------------------- | -------- | ----------- | ----------- 11737bdev_name | Required | string | name of OPAL vbdev 11738user_id | Required | number | user ID 11739password | Required | string | user password 11740lock_state | Required | string | lock state 11741 11742#### Example 11743 11744Example request: 11745 11746~~~json 11747{ 11748 "jsonrpc": "2.0", 11749 "method": "bdev_opal_set_lock_state", 11750 "id": 1, 11751 "params": { 11752 "bdev_name": "nvme0n1r1", 11753 "user_id": "1", 11754 "user_password": "********", 11755 "lock_state": "rwlock" 11756 } 11757} 11758~~~ 11759 11760Example response: 11761 11762~~~json 11763{ 11764 "jsonrpc": "2.0", 11765 "id": 1, 11766 "result": true 11767} 11768~~~ 11769 11770## Notifications 11771 11772### notify_get_types {#rpc_notify_get_types} 11773 11774Return list of all supported notification types. 11775 11776#### Parameters 11777 11778None 11779 11780#### Response 11781 11782The response is an array of strings - supported RPC notification types. 11783 11784#### Example 11785 11786Example request: 11787 11788~~~json 11789{ 11790 "jsonrpc": "2.0", 11791 "method": "notify_get_types", 11792 "id": 1 11793} 11794~~~ 11795 11796Example response: 11797 11798~~~json 11799{ 11800 "id": 1, 11801 "result": [ 11802 "bdev_register", 11803 "bdev_unregister" 11804 ], 11805 "jsonrpc": "2.0" 11806} 11807~~~ 11808 11809### notify_get_notifications {#notify_get_notifications} 11810 11811Request notifications. Returns array of notifications that happened since the specified id (or first that is available). 11812 11813Notice: Notifications are kept in circular buffer with limited size. Older notifications might be inaccessible 11814due to being overwritten by new ones. 11815 11816#### Parameters 11817 11818Name | Optional | Type | Description 11819----------------------- | -------- | ----------- | ----------- 11820id | Optional | number | First Event ID to fetch (default: first available). 11821max | Optional | number | Maximum number of event to return (default: no limit). 11822 11823#### Response 11824 11825Response is an array of event objects. 11826 11827Name | Optional | Type | Description 11828----------------------- | -------- | ----------- | ----------- 11829id | Optional | number | Event ID. 11830type | Optional | number | Type of the event. 11831ctx | Optional | string | Event context. 11832 11833#### Example 11834 11835Example request: 11836 11837~~~json 11838{ 11839 "id": 1, 11840 "jsonrpc": "2.0", 11841 "method": "notify_get_notifications", 11842 "params": { 11843 "id": 1, 11844 "max": 10 11845 } 11846} 11847 11848~~~ 11849 11850Example response: 11851 11852~~~json 11853{ 11854 "jsonrpc": "2.0", 11855 "id": 1, 11856 "result": [ 11857 { 11858 "ctx": "Malloc0", 11859 "type": "bdev_register", 11860 "id": 1 11861 }, 11862 { 11863 "ctx": "Malloc2", 11864 "type": "bdev_register", 11865 "id": 2 11866 } 11867 ] 11868} 11869~~~ 11870 11871## Linux Userspace Block Device (UBLK) {#jsonrpc_components_ublk} 11872 11873SPDK supports exporting bdevs though Linux ublk. The motivation behind it is to back a Linux kernel block device 11874with an SPDK user space bdev. 11875 11876To export a device over ublk, first make sure the Linux kernel ublk driver is loaded by running 'modprobe ublk_drv'. 11877 11878### ublk_create_target {#rpc_ublk_create_target} 11879 11880Start to create ublk threads and initialize ublk target. It will return an error if user calls this RPC twice without 11881ublk_destroy_target in between. It will use current cpumask in SPDK when user does not specify cpumask option. 11882 11883#### Parameters 11884 11885Name | Optional | Type | Description 11886----------------------- | -------- | ----------- | ----------- 11887cpumask | Optional | string | Cpumask for ublk target 11888disable-user-copy | Optional | boolean | Disable user copy feature 11889 11890#### Response 11891 11892True if ublk target initialization is successful; False if failed. 11893 11894#### Example 11895 11896Example request: 11897 11898~~~json 11899{ 11900 "params": { 11901 "cpumask": "0x2" 11902 }, 11903 "jsonrpc": "2.0", 11904 "method": "ublk_create_target", 11905 "id": 1 11906} 11907~~~ 11908 11909Example response: 11910 11911~~~json 11912{ 11913 "jsonrpc": "2.0", 11914 "id": 1, 11915 "result": true 11916} 11917~~~ 11918 11919### ublk_destroy_target {#rpc_ublk_destroy_target} 11920 11921Release all UBLK devices and destroy ublk target. 11922 11923#### Response 11924 11925True if ublk target destruction is successful; False if failed. 11926 11927#### Example 11928 11929Example request: 11930 11931~~~json 11932{ 11933 "jsonrpc": "2.0", 11934 "method": "ublk_destroy_target", 11935 "id": 1 11936} 11937~~~ 11938 11939Example response: 11940 11941~~~json 11942{ 11943 "jsonrpc": "2.0", 11944 "id": 1, 11945 "result": true 11946} 11947~~~ 11948 11949### ublk_start_disk {#rpc_ublk_start_disk} 11950 11951Start to export one SPDK bdev as a UBLK device 11952 11953#### Parameters 11954 11955Name | Optional | Type | Description 11956----------------------- | -------- | ----------- | ----------- 11957bdev_name | Required | string | Bdev name to export 11958ublk_id | Required | int | Device id 11959queue_depth | Optional | int | Device queue depth 11960num_queues | Optional | int | Total number of device queues 11961 11962#### Response 11963 11964UBLK device ID 11965 11966#### Example 11967 11968Example request: 11969 11970~~~json 11971{ 11972 "params": { 11973 "ublk_id": "1", 11974 "bdev_name": "Malloc1" 11975 }, 11976 "jsonrpc": "2.0", 11977 "method": "ublk_start_disk", 11978 "id": 1 11979} 11980~~~ 11981 11982Example response: 11983 11984~~~json 11985{ 11986 "jsonrpc": "2.0", 11987 "id": 1, 11988 "result": 1 11989} 11990~~~ 11991 11992### ublk_recover_disk {#rpc_ublk_recover_disk} 11993 11994Recover original UBLK device with ID and block device 11995 11996#### Parameters 11997 11998Name | Optional | Type | Description 11999----------------------- | -------- | ----------- | ----------- 12000bdev_name | Required | string | Bdev name to export 12001ublk_id | Required | int | Device id 12002 12003#### Response 12004 12005UBLK device ID 12006 12007#### Example 12008 12009Example request: 12010 12011~~~json 12012{ 12013 "params": { 12014 "ublk_id": "1", 12015 "bdev_name": "Malloc1" 12016 }, 12017 "jsonrpc": "2.0", 12018 "method": "ublk_recover_disk", 12019 "id": 1 12020} 12021~~~ 12022 12023Example response: 12024 12025~~~json 12026{ 12027 "jsonrpc": "2.0", 12028 "id": 1, 12029 "result": 1 12030} 12031~~~ 12032 12033### ublk_stop_disk {#rpc_ublk_stop_disk} 12034 12035Delete a UBLK device 12036 12037#### Parameters 12038 12039Name | Optional | Type | Description 12040----------------------- | -------- | ----------- | ----------- 12041ublk_id | Required | int | Device id to delete 12042 12043#### Response 12044 12045True if UBLK device is deleted successfully; False if failed. 12046 12047#### Example 12048 12049Example request: 12050 12051~~~json 12052{ 12053 "params": { 12054 "ublk_id": "1", 12055 }, 12056 "jsonrpc": "2.0", 12057 "method": "ublk_stop_disk", 12058 "id": 1 12059} 12060~~~ 12061 12062Example response: 12063 12064~~~json 12065{ 12066 "jsonrpc": "2.0", 12067 "id": 1, 12068 "result": true 12069} 12070~~~ 12071 12072### ublk_get_disks {#rpc_ublk_get_disks} 12073 12074Display full or specified ublk device list 12075 12076#### Parameters 12077 12078Name | Optional | Type | Description 12079----------------------- | -------- | ----------- | ----------- 12080ublk_id | Optional | int | ublk device id to display 12081 12082#### Response 12083 12084Display ublk device list 12085 12086#### Example 12087 12088Example request: 12089 12090~~~json 12091{ 12092 "jsonrpc": "2.0", 12093 "method": "ublk_get_disks", 12094 "id": 1 12095} 12096~~~ 12097 12098Example response: 12099 12100~~~json 12101{ 12102 "jsonrpc": "2.0", 12103 "id": 1, 12104 "result": [ 12105 { 12106 "ublk_device": "/dev/ublkb1", 12107 "id": 1, 12108 "queue_depth": 512, 12109 "num_queues": 1, 12110 "bdev_name": "Malloc1" 12111 } 12112 ] 12113} 12114~~~ 12115 12116## Linux Network Block Device (NBD) {#jsonrpc_components_nbd} 12117 12118SPDK supports exporting bdevs through Linux nbd. These devices then appear as standard Linux kernel block devices 12119and can be accessed using standard utilities like fdisk. 12120 12121In order to export a device over nbd, first make sure the Linux kernel nbd driver is loaded by running 'modprobe nbd'. 12122 12123### nbd_start_disk {#rpc_nbd_start_disk} 12124 12125Start to export one SPDK bdev as NBD disk 12126 12127#### Parameters 12128 12129Name | Optional | Type | Description 12130----------------------- | -------- | ----------- | ----------- 12131bdev_name | Required | string | Bdev name to export 12132nbd_device | Optional | string | NBD device name to assign 12133 12134#### Response 12135 12136Path of exported NBD disk 12137 12138#### Example 12139 12140Example request: 12141 12142~~~json 12143{ 12144 "params": { 12145 "nbd_device": "/dev/nbd1", 12146 "bdev_name": "Malloc1" 12147 }, 12148 "jsonrpc": "2.0", 12149 "method": "nbd_start_disk", 12150 "id": 1 12151} 12152~~~ 12153 12154Example response: 12155 12156~~~json 12157{ 12158 "jsonrpc": "2.0", 12159 "id": 1, 12160 "result": "/dev/nbd1" 12161} 12162~~~ 12163 12164### nbd_stop_disk {#rpc_nbd_stop_disk} 12165 12166Stop one NBD disk which is based on SPDK bdev. 12167 12168#### Parameters 12169 12170Name | Optional | Type | Description 12171----------------------- | -------- | ----------- | ----------- 12172nbd_device | Required | string | NBD device name to stop 12173 12174#### Example 12175 12176Example request: 12177 12178~~~json 12179{ 12180 "params": { 12181 "nbd_device": "/dev/nbd1", 12182 }, 12183 "jsonrpc": "2.0", 12184 "method": "nbd_stop_disk", 12185 "id": 1 12186} 12187~~~ 12188 12189Example response: 12190 12191~~~json 12192{ 12193 "jsonrpc": "2.0", 12194 "id": 1, 12195 "result": "true" 12196} 12197~~~ 12198 12199### nbd_get_disks {#rpc_nbd_get_disks} 12200 12201Display all or specified NBD device list 12202 12203#### Parameters 12204 12205Name | Optional | Type | Description 12206----------------------- | -------- | ----------- | ----------- 12207nbd_device | Optional | string | NBD device name to display 12208 12209#### Response 12210 12211The response is an array of exported NBD devices and their corresponding SPDK bdev. 12212 12213#### Example 12214 12215Example request: 12216 12217~~~json 12218{ 12219 "jsonrpc": "2.0", 12220 "method": "nbd_get_disks", 12221 "id": 1 12222} 12223~~~ 12224 12225Example response: 12226 12227~~~json 12228{ 12229 "jsonrpc": "2.0", 12230 "id": 1, 12231 "result": [ 12232 { 12233 "bdev_name": "Malloc0", 12234 "nbd_device": "/dev/nbd0" 12235 }, 12236 { 12237 "bdev_name": "Malloc1", 12238 "nbd_device": "/dev/nbd1" 12239 } 12240 ] 12241} 12242~~~ 12243 12244## Blobfs {#jsonrpc_components_blobfs} 12245 12246### blobfs_detect {#rpc_blobfs_detect} 12247 12248Detect whether a blobfs exists on bdev. 12249 12250#### Parameters 12251 12252Name | Optional | Type | Description 12253----------------------- | -------- | ----------- | ----------- 12254bdev_name | Required | string | Block device name to detect blobfs 12255 12256#### Response 12257 12258True if a blobfs exists on the bdev; False otherwise. 12259 12260#### Example 12261 12262Example request: 12263 12264~~~json 12265{ 12266 "jsonrpc": "2.0", 12267 "id": 1, 12268 "method": "blobfs_detect", 12269 "params": { 12270 "bdev_name": "Malloc0" 12271 } 12272} 12273~~~ 12274 12275Example response: 12276 12277~~~json 12278{ 12279 "jsonrpc": "2.0", 12280 "id": 1, 12281 "result": "true" 12282} 12283~~~ 12284 12285### blobfs_create {#rpc_blobfs_create} 12286 12287Build blobfs on bdev. 12288 12289#### Parameters 12290 12291Name | Optional | Type | Description 12292----------------------- | -------- | ----------- | ----------- 12293bdev_name | Required | string | Block device name to create blobfs 12294cluster_sz | Optional | number | Size of cluster in bytes. Must be multiple of 4KiB page size, default and minimal value is 1M. 12295 12296#### Example 12297 12298Example request: 12299 12300~~~json 12301{ 12302 "jsonrpc": "2.0", 12303 "id": 1, 12304 "method": "blobfs_create", 12305 "params": { 12306 "bdev_name": "Malloc0", 12307 "cluster_sz": 1M 12308 } 12309} 12310~~~ 12311 12312Example response: 12313 12314~~~json 12315{ 12316 "jsonrpc": "2.0", 12317 "id": 1, 12318 "result": "true" 12319} 12320~~~ 12321 12322### blobfs_mount {#rpc_blobfs_mount} 12323 12324Mount a blobfs on bdev to one host path through FUSE 12325 12326#### Parameters 12327 12328Name | Optional | Type | Description 12329----------------------- | -------- | ----------- | ----------- 12330bdev_name | Required | string | Block device name where the blobfs is 12331mountpoint | Required | string | Mountpoint path in host to mount blobfs 12332 12333#### Example 12334 12335Example request: 12336 12337~~~json 12338{ 12339 "jsonrpc": "2.0", 12340 "id": 1, 12341 "method": ""blobfs_mount"", 12342 "params": { 12343 "bdev_name": "Malloc0", 12344 "mountpoint": "/mnt/" 12345 } 12346} 12347~~~ 12348 12349Example response: 12350 12351~~~json 12352{ 12353 "jsonrpc": "2.0", 12354 "id": 1, 12355 "result": "true" 12356} 12357~~~ 12358 12359### blobfs_set_cache_size {#rpc_blobfs_set_cache_size} 12360 12361Set cache pool size for blobfs filesystems. This RPC is only permitted when the cache pool is not already initialized. 12362 12363The cache pool is initialized when the first blobfs filesystem is initialized or loaded. It is freed when the all 12364initialized or loaded filesystems are unloaded. 12365 12366#### Parameters 12367 12368Name | Optional | Type | Description 12369----------------------- | -------- | ----------- | ----------- 12370size_in_mb | Required | number | Cache size in megabytes 12371 12372#### Response 12373 12374True if cache size is set successfully; False if failed to set. 12375 12376#### Example 12377 12378Example request: 12379 12380~~~json 12381{ 12382 "jsonrpc": "2.0", 12383 "id": 1, 12384 "method": "blobfs_set_cache_size", 12385 "params": { 12386 "size_in_mb": 512, 12387 } 12388} 12389~~~ 12390 12391Example response: 12392 12393~~~json 12394{ 12395 "jsonrpc": "2.0", 12396 "id": 1, 12397 "result": true 12398} 12399~~~ 12400 12401## Socket layer {#jsonrpc_components_sock} 12402 12403### sock_impl_get_options {#rpc_sock_impl_get_options} 12404 12405Get parameters for the socket layer implementation. 12406 12407#### Parameters 12408 12409Name | Optional | Type | Description 12410----------------------- | -------- | ----------- | ----------- 12411impl_name | Required | string | Name of socket implementation, e.g. posix 12412 12413#### Response 12414 12415Response is an object with current socket layer options for requested implementation. 12416 12417#### Example 12418 12419Example request: 12420 12421~~~json 12422{ 12423 "jsonrpc": "2.0", 12424 "method": "sock_impl_get_options", 12425 "id": 1, 12426 "params": { 12427 "impl_name": "posix" 12428 } 12429} 12430~~~ 12431 12432Example response: 12433 12434~~~json 12435{ 12436 "jsonrpc": "2.0", 12437 "id": 1, 12438 "result": { 12439 "recv_buf_size": 2097152, 12440 "send_buf_size": 2097152, 12441 "enable_recv_pipe": true, 12442 "enable_quickack": true, 12443 "enable_placement_id": 0, 12444 "enable_zerocopy_send_server": true, 12445 "enable_zerocopy_send_client": false, 12446 "zerocopy_threshold": 0, 12447 "tls_version": 13, 12448 "enable_ktls": false 12449 } 12450} 12451~~~ 12452 12453### sock_impl_set_options {#rpc_sock_impl_set_options} 12454 12455Set parameters for the socket layer implementation. 12456 12457#### Parameters 12458 12459Name | Optional | Type | Description 12460--------------------------- | -------- | ----------- | ----------- 12461impl_name | Required | string | Name of socket implementation, e.g. posix 12462recv_buf_size | Optional | number | Size of socket receive buffer in bytes 12463send_buf_size | Optional | number | Size of socket send buffer in bytes 12464enable_recv_pipe | Optional | boolean | Enable or disable receive pipe 12465enable_quick_ack | Optional | boolean | Enable or disable quick ACK 12466enable_placement_id | Optional | number | Enable or disable placement_id. 0:disable,1:incoming_napi,2:incoming_cpu 12467enable_zerocopy_send_server | Optional | boolean | Enable or disable zero copy on send for server sockets 12468enable_zerocopy_send_client | Optional | boolean | Enable or disable zero copy on send for client sockets 12469zerocopy_threshold | Optional | number | Set zerocopy_threshold in bytes. A consecutive sequence of requests' iovecs 12470-- | -- | -- | that fall below this threshold may be sent without zerocopy flag set 12471tls_version | Optional | number | TLS protocol version, e.g. 13 for v1.3 (only applies when impl_name == ssl) 12472enable_ktls | Optional | boolean | Enable or disable Kernel TLS (only applies when impl_name == ssl) 12473 12474#### Response 12475 12476True if socket layer options were set successfully. 12477 12478#### Example 12479 12480Example request: 12481 12482~~~json 12483{ 12484 "jsonrpc": "2.0", 12485 "method": "sock_impl_set_options", 12486 "id": 1, 12487 "params": { 12488 "impl_name": "posix", 12489 "recv_buf_size": 2097152, 12490 "send_buf_size": 2097152, 12491 "enable_recv_pipe": false, 12492 "enable_quick_ack": false, 12493 "enable_placement_id": 0, 12494 "enable_zerocopy_send_server": true, 12495 "enable_zerocopy_send_client": false, 12496 "zerocopy_threshold": 10240, 12497 "tls_version": 13, 12498 "enable_ktls": false 12499 } 12500} 12501~~~ 12502 12503Example response: 12504 12505~~~json 12506{ 12507 "jsonrpc": "2.0", 12508 "id": 1, 12509 "result": true 12510} 12511~~~ 12512 12513### sock_set_default_impl {#rpc_sock_set_default_impl} 12514 12515Set the default sock implementation. 12516 12517#### Parameters 12518 12519Name | Optional | Type | Description 12520----------------------- | -------- | ----------- | ----------- 12521impl_name | Required | string | Name of socket implementation, e.g. posix 12522 12523#### Response 12524 12525True if the default socket layer configuration was set successfully. 12526 12527#### Example 12528 12529Example request: 12530 12531~~~json 12532{ 12533 "jsonrpc": "2.0", 12534 "method": "sock_set_default_impl", 12535 "id": 1, 12536 "params": { 12537 "impl_name": "posix" 12538 } 12539} 12540~~~ 12541 12542Example response: 12543 12544~~~json 12545{ 12546 "jsonrpc": "2.0", 12547 "id": 1, 12548 "result": true 12549} 12550~~~ 12551 12552### sock_get_default_impl {#rpc_sock_get_default_impl} 12553 12554Get the name of the default sock implementation. 12555 12556#### Parameters 12557 12558This function has no parameters. 12559 12560#### Response 12561 12562The name of the current default socket implementation. 12563 12564#### Example 12565 12566Example request: 12567 12568~~~json 12569{ 12570 "jsonrpc": "2.0", 12571 "method": "sock_get_default_impl", 12572 "id": 1 12573} 12574~~~ 12575 12576Example response: 12577 12578~~~json 12579{ 12580 "jsonrpc": "2.0", 12581 "id": 1, 12582 "result": { 12583 "impl_name": "posix" 12584 } 12585} 12586~~~ 12587 12588## Miscellaneous RPC commands 12589 12590### bdev_nvme_send_cmd {#rpc_bdev_nvme_send_cmd} 12591 12592Send NVMe command directly to NVMe controller or namespace. Parameters and responses encoded by base64 urlsafe need further processing. 12593 12594Notice: bdev_nvme_send_cmd requires user to guarantee the correctness of NVMe command itself, and also optional parameters. 12595Illegal command contents or mismatching buffer size may result in unpredictable behavior. 12596 12597#### Parameters 12598 12599Name | Optional | Type | Description 12600----------------------- | -------- | ----------- | ----------- 12601name | Required | string | Name of the operating NVMe controller 12602cmd_type | Required | string | Type of nvme cmd. Valid values are: admin, io 12603data_direction | Required | string | Direction of data transfer. Valid values are: c2h, h2c 12604cmdbuf | Required | string | NVMe command encoded by base64 urlsafe 12605data | Optional | string | Data transferring to controller from host, encoded by base64 urlsafe 12606metadata | Optional | string | Metadata transferring to controller from host, encoded by base64 urlsafe 12607data_len | Optional | number | Data length required to transfer from controller to host 12608metadata_len | Optional | number | Metadata length required to transfer from controller to host 12609timeout_ms | Optional | number | Command execution timeout value, in milliseconds 12610 12611#### Response 12612 12613Name | Type | Description 12614----------------------- | ----------- | ----------- 12615cpl | string | NVMe completion queue entry, encoded by base64 urlsafe 12616data | string | Data transferred from controller to host, encoded by base64 urlsafe 12617metadata | string | Metadata transferred from controller to host, encoded by base64 urlsafe 12618 12619#### Example 12620 12621Example request: 12622 12623~~~json 12624{ 12625 "jsonrpc": "2.0", 12626 "method": "bdev_nvme_send_cmd", 12627 "id": 1, 12628 "params": { 12629 "name": "Nvme0", 12630 "cmd_type": "admin" 12631 "data_direction": "c2h", 12632 "cmdbuf": "BgAAAAEAAAAAAAAAAAAAAAAAAAAAAAAAsGUs9P5_AAAAAAAAABAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA==", 12633 "data_len": 60, 12634 } 12635} 12636~~~ 12637 12638Example response: 12639 12640~~~json 12641{ 12642 "jsonrpc": "2.0", 12643 "id": 1, 12644 "result": { 12645 "cpl": "AAAAAAAAAAARAAAAWrmwABAA==", 12646 "data": "sIjg6AAAAACwiODoAAAAALCI4OgAAAAAAAYAAREAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA" 12647 } 12648 12649} 12650~~~ 12651 12652### vmd_enable {#rpc_enable_vmd} 12653 12654Enable VMD enumeration. 12655 12656#### Parameters 12657 12658This method has no parameters. 12659 12660#### Response 12661 12662Completion status of enumeration is returned as a boolean. 12663 12664### Example 12665 12666Example request: 12667 12668~~~json 12669{ 12670 "jsonrpc": "2.0", 12671 "method": "vmd_enable", 12672 "id": 1 12673} 12674~~~ 12675 12676Example response: 12677 12678~~~json 12679{ 12680 "jsonrpc": "2.0", 12681 "id": 1, 12682 "result": true 12683} 12684~~~ 12685 12686### vmd_remove_device {#rpc_vmd_remove_device} 12687 12688Remove a device behind a VMD. 12689 12690### Parameters 12691 12692Name | Optional | Type | Description 12693----------------------- | -------- | ----------- | ----------- 12694addr | Required | string | Address of the device to remove. 12695 12696### Example 12697 12698~~~json 12699{ 12700 "jsonrpc": "2.0", 12701 "method": "vmd_remove_device", 12702 "params": { 12703 "addr": "5d0505:01:00.0" 12704 } 12705 "id": 1 12706} 12707~~~ 12708 12709Example response: 12710 12711~~~json 12712{ 12713 "jsonrpc": "2.0", 12714 "id": 1, 12715 "result": true 12716} 12717~~~ 12718 12719### vmd_rescan {#rpc_vmd_rescan} 12720 12721Force a rescan of the devices behind VMD. 12722 12723### Parameters 12724 12725This method has no parameters. 12726 12727#### Response 12728 12729The response is the number of new devices found. 12730 12731### Example 12732 12733~~~json 12734{ 12735 "jsonrpc": "2.0", 12736 "method": "vmd_rescan", 12737 "id": 1 12738} 12739~~~ 12740 12741Example response: 12742 12743~~~json 12744{ 12745 "jsonrpc": "2.0", 12746 "id": 1, 12747 "result": { 12748 "count": 1 12749 } 12750} 12751~~~ 12752 12753### spdk_get_version {#rpc_spdk_get_version} 12754 12755Get the version info of the running SPDK application. 12756 12757#### Parameters 12758 12759This method has no parameters. 12760 12761#### Response 12762 12763The response is the version number including major version number, minor version number, patch level number and suffix string. 12764 12765#### Example 12766 12767Example request: 12768 12769~~~json 12770{ 12771 "jsonrpc": "2.0", 12772 "id": 1, 12773 "method": "spdk_get_version" 12774} 12775~~~ 12776 12777Example response: 12778 12779~~~json 12780{ 12781 "jsonrpc": "2.0", 12782 "id": 1, 12783 "result": { 12784 "version": "19.04-pre", 12785 "fields" : { 12786 "major": 19, 12787 "minor": 4, 12788 "patch": 0, 12789 "suffix": "-pre" 12790 } 12791 } 12792} 12793~~~ 12794 12795### framework_get_pci_devices 12796 12797List PCIe devices attached to an SPDK application and the contents of their config space. 12798 12799#### Parameters 12800 12801This method has no parameters. 12802 12803#### Response 12804 12805The response is an array of attached PCIe devices. 12806 12807#### Example 12808 12809Example request: 12810 12811~~~json 12812{ 12813 "jsonrpc": "2.0", 12814 "id": 1, 12815 "method": "framework_get_pci_devices" 12816} 12817~~~ 12818 12819Example response: 12820Note that the config space buffer was trimmed. 12821 12822~~~json 12823{ 12824 "jsonrpc": "2.0", 12825 "id": 1, 12826 "result": { 12827 [ 12828 { 12829 "address": "0000:00:04.0", 12830 "config_space": "8680455807051000...0000000000000000" 12831 }, 12832 { 12833 "address": "0000:00:03.0", 12834 "config_space": "8680455807051000...0000000000000000" 12835 } 12836 ] 12837 } 12838} 12839~~~ 12840 12841### bdev_nvme_add_error_injection {#rpc_bdev_nvme_add_error_injection} 12842 12843Add a NVMe command error injection for a bdev nvme controller. 12844 12845#### Parameters 12846 12847Name | Optional | Type | Description 12848----------------------- | -------- | ----------- | ----------- 12849name | Required | string | Name of the operating NVMe controller 12850cmd_type | Required | string | Type of NVMe command. Valid values are: admin, io 12851opc | Required | number | Opcode for which the error injection is applied 12852do_not_submit | Optional | boolean | Set to true if request should not be submitted to the controller (default false) 12853timeout_in_us | Optional | number | Wait specified microseconds when do_not_submit is true 12854err_count | Optional | number | Number of matching NVMe commands to inject errors 12855sct | Optional | number | Status code type (default 0) 12856sc | Optional | number | Status code (default 0) 12857 12858#### Response 12859 12860true on success 12861 12862#### Example 12863 12864Example request: 12865 12866~~~json 12867{ 12868 "jsonrpc": "2.0", 12869 "method": "bdev_nvme_add_error_injection", 12870 "id": 1, 12871 "params": { 12872 "name": "HotInNvme0", 12873 "opc": 2, 12874 "cmd_type": "io", 12875 "err_count": 1111111, 12876 "sct": 11, 12877 "sc": 33 12878 } 12879} 12880 12881~~~ 12882 12883Example response: 12884 12885~~~json 12886{ 12887 "jsonrpc": "2.0", 12888 "id": 1, 12889 "result": true 12890} 12891 12892~~~ 12893 12894### bdev_nvme_remove_error_injection {#rpc_bdev_nvme_remove_error_injection} 12895 12896Remove a NVMe command error injection. 12897 12898#### Parameters 12899 12900Name | Optional | Type | Description 12901----------------------- | -------- | ----------- | ----------- 12902name | Required | string | Name of the operating NVMe controller 12903cmd_type | Required | string | Type of NVMe command. Valid values are: admin, io 12904opc | Required | number | Opcode for which the error injection is applied 12905 12906#### Response 12907 12908true on success 12909 12910#### Example 12911 12912Example request: 12913 12914~~~json 12915{ 12916 "jsonrpc": "2.0", 12917 "method": "bdev_nvme_remove_error_injection", 12918 "id": 1, 12919 "params": { 12920 "name": "HotInNvme0", 12921 "opc": 2, 12922 "cmd_type": "io" 12923 } 12924} 12925 12926 12927~~~ 12928 12929Example response: 12930 12931~~~json 12932{ 12933 "jsonrpc": "2.0", 12934 "id": 1, 12935 "result": true 12936} 12937 12938~~~ 12939 12940### bdev_daos_create {#rpc_bdev_daos_create} 12941 12942Construct @ref bdev_config_daos 12943 12944#### Parameters 12945 12946Name | Optional | Type | Description 12947----------------------- | -------- | ----------- | ----------- 12948name | Required | string | Bdev name to use 12949pool | Required | string | DAOS pool label or its uuid 12950cont | Required | string | DAOS cont label or its uuid 12951block_size | Required | number | Block size in bytes -must be multiple of 512 12952num_blocks | Required | number | Number of blocks 12953uuid | Optional | string | UUID of new bdev 12954oclass | Optional | string | DAOS object class (default SX) 12955 12956To find more about various object classes please visit [DAOS documentation](https://github.com/daos-stack/daos/blob/master/src/object/README.md). 12957Please note, that DAOS bdev module uses the same CLI flag notation as `dmg` and `daos` commands, 12958for instance, `SX` or `EC_4P2G2` rather than in DAOS header file `OC_SX` or `OC_EC_4P2G2`. 12959 12960#### Result 12961 12962Name of newly created bdev. 12963 12964#### Example 12965 12966Example request: 12967 12968~~~json 12969{ 12970 "params": { 12971 "block_size": 4096, 12972 "num_blocks": 16384, 12973 "name": "daosdev0", 12974 "pool": "test-pool", 12975 "cont": "test-cont", 12976 "oclass": "EC_4P2G2" 12977 }, 12978 "jsonrpc": "2.0", 12979 "method": "bdev_daos_create", 12980 "id": 1 12981} 12982~~~ 12983 12984Example response: 12985 12986~~~json 12987{ 12988 "jsonrpc": "2.0", 12989 "id": 1, 12990 "result": "daosdev0" 12991} 12992~~~ 12993 12994### bdev_daos_delete {#rpc_bdev_daos_delete} 12995 12996Delete @ref bdev_config_daos 12997 12998#### Parameters 12999 13000Name | Optional | Type | Description 13001----------------------- | -------- | ----------- | ----------- 13002name | Required | string | Bdev name 13003 13004#### Example 13005 13006Example request: 13007 13008~~~json 13009{ 13010 "params": { 13011 "name": "daosdev0" 13012 }, 13013 "jsonrpc": "2.0", 13014 "method": "bdev_daos_delete", 13015 "id": 1 13016} 13017~~~ 13018 13019Example response: 13020 13021~~~json 13022{ 13023 "jsonrpc": "2.0", 13024 "id": 1, 13025 "result": true 13026} 13027~~~ 13028 13029### bdev_daos_resize {#rpc_bdev_daos_resize} 13030 13031Resize @ref bdev_config_daos. 13032 13033#### Parameters 13034 13035Name | Optional | Type | Description 13036----------------------- | -------- | ----------- | ----------- 13037name | Required | string | Bdev name 13038new_size | Required | number | Bdev new capacity in MiB 13039 13040#### Example 13041 13042Example request: 13043 13044~~~json 13045{ 13046 "params": { 13047 "name": "daosdev0", 13048 "new_size": 8192 13049 }, 13050 "jsonrpc": "2.0", 13051 "method": "bdev_daos_resize", 13052 "id": 1 13053} 13054~~~ 13055 13056Example response: 13057 13058~~~json 13059{ 13060 "jsonrpc": "2.0", 13061 "id": 1, 13062 "result": true 13063} 13064~~~ 13065 13066### iobuf_set_options {#rpc_iobuf_set_options} 13067 13068Set iobuf buffer pool options. 13069 13070#### Parameters 13071 13072Name | Optional | Type | Description 13073----------------------- | -------- | ----------- | ----------- 13074small_pool_count | Optional | number | Number of small buffers in the global pool 13075large_pool_count | Optional | number | Number of large buffers in the global pool 13076small_bufsize | Optional | number | Size of a small buffer 13077large_bufsize | Optional | number | Size of a small buffer 13078 13079#### Example 13080 13081Example request: 13082 13083~~~json 13084{ 13085 "jsonrpc": "2.0", 13086 "id": 1, 13087 "method": "iobuf_set_options", 13088 "params": { 13089 "small_pool_count": 16383, 13090 "large_pool_count": 2047 13091 } 13092} 13093~~~ 13094 13095Example response: 13096 13097~~~json 13098{ 13099 "jsonrpc": "2.0", 13100 "id": 1, 13101 "result": true 13102} 13103~~~ 13104 13105### iobuf_get_stats {#rpc_iobuf_get_stats} 13106 13107Retrieve iobuf's statistics. 13108 13109#### Parameters 13110 13111None. 13112 13113#### Example 13114 13115Example request: 13116 13117~~~json 13118{ 13119 "jsonrpc": "2.0", 13120 "method": "iobuf_get_stats", 13121 "id": 1 13122} 13123~~~ 13124 13125Example response: 13126 13127~~~json 13128{ 13129 "jsonrpc": "2.0", 13130 "id": 1, 13131 "result": [ 13132 { 13133 "module": "accel", 13134 "small_pool": { 13135 "cache": 0, 13136 "main": 0, 13137 "retry": 0 13138 }, 13139 "large_pool": { 13140 "cache": 0, 13141 "main": 0, 13142 "retry": 0 13143 } 13144 }, 13145 { 13146 "module": "bdev", 13147 "small_pool": { 13148 "cache": 421965, 13149 "main": 1218, 13150 "retry": 0 13151 }, 13152 "large_pool": { 13153 "cache": 0, 13154 "main": 0, 13155 "retry": 0 13156 } 13157 }, 13158 { 13159 "module": "nvmf_TCP", 13160 "small_pool": { 13161 "cache": 7, 13162 "main": 0, 13163 "retry": 0 13164 }, 13165 "large_pool": { 13166 "cache": 0, 13167 "main": 0, 13168 "retry": 0 13169 } 13170 } 13171 ] 13172} 13173~~~ 13174 13175### bdev_nvme_start_mdns_discovery {#rpc_bdev_nvme_start_mdns_discovery} 13176 13177Starts an mDNS based discovery service for the specified service type for the 13178auto-discovery of discovery controllers (NVMe TP-8009). 13179 13180The discovery service will listen for the mDNS discovery events from the 13181Avahi-daemon and will connect to the newly learnt discovery controllers. 13182Then the discovery service will automatically attach to any subsystem found in the 13183discovery log page from the discovery controllers learnt using mDNS. 13184When determining a controller name to use when attaching, it will use 13185the 'name' parameter as a prefix, followed by a unique integer assigned for each of the 13186discovery controllers learnt through mDNS, followed by a unique integer for that discovery 13187service. If the discovery service identifies a subsystem that has been previously 13188attached but is listed with a different path, it will use the same controller name 13189as the previous entry, and connect as a multipath. 13190 13191When the discovery service sees that a subsystem entry has been removed 13192from the log page, it will automatically detach from that controller as well. 13193 13194The 'name' is also used to later stop the discovery service. 13195 13196#### Parameters 13197 13198Name | Optional | Type | Description 13199-------------------------- | -------- | ----------- | ----------- 13200name | Required | string | Prefix for NVMe discovery services found 13201svcname | Required | string | Service to discover: e.g. _nvme-disc._tcp 13202hostnqn | Optional | string | NVMe-oF hostnqn 13203 13204#### Example 13205 13206Example request: 13207 13208~~~json 13209{ 13210 "jsonrpc": "2.0", 13211 "method": "bdev_nvme_start_mdns_discovery", 13212 "id": 1, 13213 "params": { 13214 "name": "cdc_auto", 13215 "svcname": "_nvme-disc._tcp", 13216 "hostnqn": "nqn.2021-12.io.spdk:host1", 13217 } 13218} 13219~~~ 13220 13221Example response: 13222 13223~~~json 13224{ 13225 "jsonrpc": "2.0", 13226 "id": 1, 13227 "result": true 13228} 13229~~~ 13230 13231### bdev_nvme_stop_mdns_discovery {#rpc_bdev_nvme_stop_mdns_discovery} 13232 13233Stops a mDNS discovery service. This includes detaching any controllers that were 13234discovered via the service that is being stopped. 13235 13236#### Parameters 13237 13238Name | Optional | Type | Description 13239-------------------------- | -------- | ----------- | ----------- 13240name | Required | string | Name of mDNS discovery instance to stop 13241 13242#### Example 13243 13244Example request: 13245 13246~~~json 13247{ 13248 "jsonrpc": "2.0", 13249 "method": "bdev_nvme_stop_mdns_discovery", 13250 "id": 1, 13251 "params": { 13252 "name": "cdc_auto" 13253 } 13254} 13255~~~ 13256 13257Example response: 13258 13259~~~json 13260{ 13261 "jsonrpc": "2.0", 13262 "id": 1, 13263 "result": true 13264} 13265~~~ 13266 13267### bdev_nvme_get_mdns_discovery_info {#rpc_bdev_nvme_get_mdns_discovery_info} 13268 13269Get the information about the mDNS discovery service instances. 13270 13271#### Example 13272 13273Example request: 13274~~~json 13275{ 13276 "jsonrpc": "2.0", 13277 "method": "bdev_nvme_get_mdns_discovery_info", 13278 "id": 1 13279} 13280~~~ 13281 13282Example response: 13283 13284~~~json 13285[ 13286 { 13287 "name": "cdc_auto", 13288 "svcname": "_nvme-disc._tcp", 13289 "referrals": [ 13290 { 13291 "name": "cdc_auto0", 13292 "trid": { 13293 "trtype": "TCP", 13294 "adrfam": "IPv4", 13295 "traddr": "66.1.2.21", 13296 "trsvcid": "8009", 13297 "subnqn": "nqn.2014-08.org.nvmexpress.discovery" 13298 } 13299 }, 13300 { 13301 "name": "cdc_auto1", 13302 "trid": { 13303 "trtype": "TCP", 13304 "adrfam": "IPv4", 13305 "traddr": "66.1.1.21", 13306 "trsvcid": "8009", 13307 "subnqn": "nqn.2014-08.org.nvmexpress.discovery" 13308 } 13309 } 13310 ] 13311 } 13312] 13313~~~ 13314 13315### keyring_file_add_key {#rpc_keyring_file_add_key} 13316 13317Add a file-based key to a keyring. 13318 13319#### Parameters 13320 13321Name | Optional | Type | Description 13322-------------------------- | -------- | ----------- | ----------- 13323name | Required | string | Name of the key to add. 13324path | Required | string | Path to a file containing the key. 13325 13326#### Example 13327 13328Example request: 13329 13330~~~json 13331{ 13332 "jsonrpc": "2.0", 13333 "method": "keyring_file_add_key", 13334 "id": 1 13335 "params": { 13336 "name": "key0", 13337 "path": "/path/to/key0" 13338 } 13339} 13340~~~ 13341 13342Example response: 13343 13344~~~json 13345{ 13346 "jsonrpc": "2.0", 13347 "id": 1, 13348 "result": true 13349} 13350~~~ 13351 13352### keyring_file_remove_key {#rpc_keyring_file_remove_key} 13353 13354Remove a file-based key from a keyring. 13355 13356#### Parameters 13357 13358Name | Optional | Type | Description 13359-------------------------- | -------- | ----------- | ----------- 13360name | Required | string | Name of the key to remove. 13361 13362#### Example 13363 13364Example request: 13365 13366~~~json 13367{ 13368 "jsonrpc": "2.0", 13369 "method": "keyring_file_remove_key", 13370 "id": 1 13371 "params": { 13372 "name": "key0" 13373 } 13374} 13375~~~ 13376 13377Example response: 13378 13379~~~json 13380{ 13381 "jsonrpc": "2.0", 13382 "id": 1, 13383 "result": true 13384} 13385~~~ 13386 13387### keyring_get_keys {#rpc_keyring_get_keys} 13388 13389Get a list of available keys. This RPC will only list keys that are currently attached to a 13390keyring. Dynamically loaded keys (via the `probe_key()` callback) will only be included if they're 13391currently in-use (i.e. with active references obtained via `spdk_keyring_get_key()`). 13392 13393#### Example 13394 13395Example request: 13396~~~json 13397{ 13398 "jsonrpc": "2.0", 13399 "method": "keyring_get_keys", 13400 "id": 1 13401} 13402~~~ 13403 13404Example response: 13405 13406~~~json 13407{ 13408 "jsonrpc": "2.0", 13409 "id": 1, 13410 "result": [ 13411 { 13412 "name": "key0", 13413 "module": "keyring_file", 13414 "removed": false, 13415 "probed": false, 13416 "refcnt": 1, 13417 "path": "/path/to/key0" 13418 }, 13419 { 13420 "name": "key1", 13421 "module": "keyring_file", 13422 "removed": false, 13423 "probed": false, 13424 "refcnt": 1, 13425 "path": "/path/to/key1" 13426 } 13427 ] 13428} 13429~~~ 13430 13431### keyring_linux_set_options {#keyring_linux_set_options} 13432 13433Set options of the keyring_linux module. 13434 13435#### Parameters 13436 13437Name | Optional | Type | Description 13438----------------------- | -------- | ----------- | ----------- 13439enable | Optional | boolean | Enable the module. 13440 13441#### Example 13442 13443Example request: 13444~~~json 13445{ 13446 "jsonrpc": "2.0", 13447 "method": "keyring_linux_set_options", 13448 "id": 1 13449 "params": { 13450 "enable": true 13451 } 13452} 13453~~~ 13454 13455Example response: 13456 13457~~~json 13458{ 13459 "jsonrpc": "2.0", 13460 "id": 1, 13461 "result": true 13462} 13463~~~ 13464 13465### nvmf_publish_mdns_prr {#rpc_nvmf_publish_mdns_prr} 13466 13467This interface is used to publish an NVMf target's service location using mDNS 13468(Multicast DNS) protocol. It allows clients to discover the NVMf target using 13469the published service location. 13470 13471#### Parameters 13472 13473Name | Optional | Type | Description 13474-------------------------- | -------- | ----------- | ----------- 13475tgt_name | Optional | string | Parent NVMe-oF target name. 13476 13477#### Example 13478 13479Example request: 13480 13481~~~json 13482{ 13483 "jsonrpc": "2.0", 13484 "method": "nvmf_publish_mdns_prr", 13485 "id": 1, 13486} 13487~~~ 13488 13489Example response: 13490 13491~~~json 13492{ 13493 "jsonrpc": "2.0", 13494 "id": 1, 13495 "result": true 13496} 13497~~~ 13498 13499### nvmf_stop_mdns_prr {#rpc_nvmf_stop_mdns_prr} 13500 13501This interface is used to stop publishing the NVMf target's service location 13502using mDNS (Multicast DNS) protocol. It removes the published service location, 13503preventing clients from discovering the NVMf target. 13504 13505#### Parameters 13506 13507Name | Optional | Type | Description 13508-------------------------- | -------- | ----------- | ----------- 13509tgt_name | Optional | string | Parent NVMe-oF target name. 13510 13511#### Example 13512 13513Example request: 13514 13515~~~json 13516{ 13517 "jsonrpc": "2.0", 13518 "method": "nvmf_stop_mdns_prr", 13519 "id": 1 13520} 13521~~~ 13522 13523Example response: 13524 13525~~~json 13526{ 13527 "jsonrpc": "2.0", 13528 "id": 1, 13529 "result": true 13530} 13531 13532### fsdev_get_opts {#fsdev_get_opts} 13533 13534Get fsdev module options. 13535 13536#### Parameters 13537 13538None 13539 13540#### Example 13541 13542Example request: 13543~~~json 13544{ 13545 "jsonrpc": "2.0", 13546 "method": "fsdev_get_opts", 13547 "id": 1 13548} 13549~~~ 13550 13551Example response: 13552 13553~~~json 13554{ 13555 "jsonrpc": "2.0", 13556 "id": 1, 13557 "result": { 13558 "fsdev_io_pool_size": 65535, 13559 "fsdev_io_cache_size": 256 13560 } 13561} 13562~~~ 13563 13564### fsdev_set_opts {#fsdev_set_opts} 13565 13566Set fsdev module options. 13567 13568#### Parameters 13569 13570Name | Optional | Type | Description 13571----------------------- | -------- | ----------- | ----------- 13572fsdev_io_pool_size | Required | int | Size of fsdev IO objects pool. 13573fsdev_io_cache_size | Required | int | Size of fsdev IO objects cache per thread. 13574 13575#### Example 13576 13577Example request: 13578~~~json 13579{ 13580 "jsonrpc": "2.0", 13581 "method": "fsdev_get_opts", 13582 "id": 1, 13583 "params": { 13584 "fsdev_io_pool_size": 65535, 13585 "fsdev_io_cache_size": 256 13586 } 13587} 13588~~~ 13589 13590Example response: 13591 13592~~~json 13593{ 13594 "jsonrpc": "2.0", 13595 "id": 1, 13596 "result": { 13597 "fsdev_io_pool_size": 65535, 13598 "fsdev_io_cache_size": 256 13599 } 13600} 13601~~~ 13602 13603### fsdev_aio_create {#fsdev_aio_create} 13604 13605Create an AIO fsdev. 13606 13607#### Parameters 13608 13609Name | Optional | Type | Description 13610----------------------- | -------- | ----------- | ----------- 13611name | Required | string | Name of the AIO fsdev to create. 13612root_path | Required | string | Path on the system directory to be exposed as an SPDK filesystem 13613enable_xattr | Optional | bool | true to enable the extended attributes, false otherwise 13614enable_writeback_cache | Optional | bool | true to enable the writeback cache, false otherwise 13615max_write | Optional | int | Max write size in bytes 13616 13617#### Example 13618 13619Example request: 13620~~~json 13621{ 13622 "jsonrpc": "2.0", 13623 "method": "fsdev_aio_create", 13624 "id": 8, 13625 "params": { 13626 "name": "aio0", 13627 "root_path": "/tmp/vfio-test", 13628 "enable_xattr": false, 13629 "enable_writeback_cache": true, 13630 "max_write": 65535 13631 } 13632} 13633~~~ 13634 13635Example response: 13636 13637~~~json 13638{ 13639 "jsonrpc": "2.0", 13640 "id": 8, 13641 "result": "aio0" 13642} 13643~~~ 13644 13645### fsdev_aio_delete {#fsdev_aio_delete} 13646 13647Delete an AIO fsdev. 13648 13649#### Parameters 13650 13651Name | Optional | Type | Description 13652----------------------- | -------- | ----------- | ----------- 13653name | Required | string | Name of the AIO fsdev to delete. 13654 13655#### Example 13656 13657Example request: 13658~~~json 13659{ 13660 "jsonrpc": "2.0", 13661 "method": "fsdev_aio_delete", 13662 "id": 1, 13663 "params": { 13664 "name": "aio0" 13665 } 13666} 13667~~~ 13668 13669Example response: 13670 13671~~~json 13672{ 13673 "jsonrpc": "2.0", 13674 "id": 1, 13675 "result": true 13676} 13677~~~ 13678