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, 3 = uadk 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 (required if controller key is specified) 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 (required if controller key is specified) 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_set_keys {#rpc_nvmf_subsystem_set_keys} 8748 8749Set keys required for a host to connect to a given subsystem. This will overwrite the keys set by 8750`nvmf_subsystem_add_host`. If none of the keys are provided, host's keys will be cleared, allowing 8751it to connect without authentication. 8752 8753#### Parameters 8754 8755Name | Optional | Type | Description 8756----------------------- | -------- | ----------- | ----------- 8757nqn | Required | string | Subsystem NQN 8758host | Required | string | Host NQN 8759tgt_name | Optional | string | NVMe-oF target name 8760dhchap_key | Optional | string | DH-HMAC-CHAP key name (required if controller key is specified) 8761dhchap_ctrlr_key | Optional | string | DH-HMAC-CHAP controller key name 8762 8763#### Example 8764 8765Example request: 8766 8767~~~json 8768{ 8769 "jsonrpc": "2.0", 8770 "id": 1, 8771 "method": "nvmf_subsystem_set_keys", 8772 "params": { 8773 "nqn": "nqn.2024-06.io.spdk:cnode1", 8774 "host": "nqn.2024-06.io.spdk:host1", 8775 "dhchap_key": "key0", 8776 "dchap_ctrlr_key": "key1" 8777 } 8778} 8779~~~ 8780 8781Example response: 8782 8783~~~json 8784{ 8785 "jsonrpc": "2.0", 8786 "id": 1, 8787 "result": true 8788} 8789~~~ 8790 8791### nvmf_subsystem_get_controllers {#rpc_nvmf_subsystem_get_controllers} 8792 8793#### Parameters 8794 8795Name | Optional | Type | Description 8796----------------------- | -------- | ----------- | ----------- 8797nqn | Required | string | Subsystem NQN 8798tgt_name | Optional | string | Parent NVMe-oF target name. 8799 8800#### Example 8801 8802Example request: 8803 8804~~~json 8805{ 8806 "jsonrpc": "2.0", 8807 "id": 1, 8808 "method": "nvmf_subsystem_get_controllers", 8809 "params": { 8810 "nqn": "nqn.2016-06.io.spdk:cnode1" 8811 } 8812} 8813~~~ 8814 8815Example response: 8816 8817~~~json 8818{ 8819 "jsonrpc": "2.0", 8820 "id": 1, 8821 "result": [ 8822 { 8823 "cntlid": 1, 8824 "hostnqn": "nqn.2016-06.io.spdk:host1", 8825 "hostid": "27dad528-6368-41c3-82d3-0b956b49025d", 8826 "num_io_qpairs": 5 8827 } 8828 ] 8829} 8830~~~ 8831 8832### nvmf_subsystem_get_qpairs {#rpc_nvmf_subsystem_get_qpairs} 8833 8834#### Parameters 8835 8836Name | Optional | Type | Description 8837----------------------- | -------- | ----------- | ----------- 8838nqn | Required | string | Subsystem NQN 8839tgt_name | Optional | string | Parent NVMe-oF target name. 8840 8841#### Example 8842 8843Example request: 8844 8845~~~json 8846{ 8847 "jsonrpc": "2.0", 8848 "id": 1, 8849 "method": "nvmf_subsystem_get_qpairs", 8850 "params": { 8851 "nqn": "nqn.2016-06.io.spdk:cnode1" 8852 } 8853} 8854~~~ 8855 8856Example response: 8857 8858~~~json 8859{ 8860 "jsonrpc": "2.0", 8861 "id": 1, 8862 "result": [ 8863 { 8864 "cntlid": 1, 8865 "qid": 0, 8866 "state": "active", 8867 "listen_address": { 8868 "trtype": "RDMA", 8869 "adrfam": "IPv4", 8870 "traddr": "192.168.0.123", 8871 "trsvcid": "4420" 8872 } 8873 }, 8874 { 8875 "cntlid": 1, 8876 "qid": 1, 8877 "state": "active", 8878 "listen_address": { 8879 "trtype": "RDMA", 8880 "adrfam": "IPv4", 8881 "traddr": "192.168.0.123", 8882 "trsvcid": "4420" 8883 } 8884 } 8885 ] 8886} 8887~~~ 8888 8889### nvmf_subsystem_get_listeners {#rpc_nvmf_subsystem_get_listeners} 8890 8891#### Parameters 8892 8893Name | Optional | Type | Description 8894----------------------- | -------- | ----------- | ----------- 8895nqn | Required | string | Subsystem NQN 8896tgt_name | Optional | string | Parent NVMe-oF target name. 8897 8898#### Example 8899 8900Example request: 8901 8902~~~json 8903{ 8904 "jsonrpc": "2.0", 8905 "id": 1, 8906 "method": "nvmf_subsystem_get_listeners", 8907 "params": { 8908 "nqn": "nqn.2016-06.io.spdk:cnode1" 8909 } 8910} 8911~~~ 8912 8913Example response: 8914 8915~~~json 8916{ 8917 "jsonrpc": "2.0", 8918 "id": 1, 8919 "result": [ 8920 { 8921 "address": { 8922 "trtype": "RDMA", 8923 "adrfam": "IPv4", 8924 "traddr": "192.168.0.123", 8925 "trsvcid": "4420" 8926 }, 8927 "ana_state": "optimized" 8928 } 8929 ] 8930} 8931~~~ 8932 8933### nvmf_ns_add_host {#rpc_nvmf_ns_add_host} 8934 8935Make the specified namespace of the specified subnqn visible to any existing 8936or future controllers with the specified hostnqn. 8937 8938Note: the namespace must have been added with no_auto_visible = false 8939(see @ref rpc_nvmf_subsystem_add_ns). 8940 8941#### Parameters 8942 8943Name | Optional | Type | Description 8944----------------------- | -------- | ----------- | ----------- 8945nqn | Required | string | Subsystem NQN 8946nsid | Required | number | Namespace ID 8947host | Required | string | Host NQN 8948 8949#### Example 8950 8951Example request: 8952 8953~~~json 8954{ 8955 "jsonrpc": "2.0", 8956 "id": 1, 8957 "method": "nvmf_ns_add_host", 8958 "params": { 8959 "nqn": "nqn.2016-06.io.spdk:cnode1", 8960 "nsid": 1, 8961 "host": "nqn.2024-01.io.spdk:host0" 8962 } 8963} 8964~~~ 8965 8966Example response: 8967 8968~~~json 8969{ 8970 "jsonrpc": "2.0", 8971 "id": 1, 8972 "result": true 8973} 8974~~~ 8975 8976### nvmf_ns_remove_host {#rpc_nvmf_ns_remove_host} 8977 8978Make the specified namespace of the specified subnqn not visible to any existing 8979or future controllers with the specified hostnqn. 8980 8981Note: the namespace must have been added to the subsystem with 8982no_auto_visible = false (see @ref rpc_nvmf_subsystem_add_ns). 8983 8984#### Parameters 8985 8986Name | Optional | Type | Description 8987----------------------- | -------- | ----------- | ----------- 8988nqn | Required | string | Subsystem NQN 8989nsid | Required | number | Namespace ID 8990host | Required | string | Host NQN 8991 8992#### Example 8993 8994Example request: 8995 8996~~~json 8997{ 8998 "jsonrpc": "2.0", 8999 "id": 1, 9000 "method": "nvmf_ns_remove_host", 9001 "params": { 9002 "nqn": "nqn.2016-06.io.spdk:cnode1", 9003 "nsid": 1, 9004 "host": "nqn.2024-01.io.spdk:host0" 9005 } 9006} 9007~~~ 9008 9009Example response: 9010 9011~~~json 9012{ 9013 "jsonrpc": "2.0", 9014 "id": 1, 9015 "result": true 9016} 9017~~~ 9018 9019### nvmf_set_max_subsystems {#rpc_nvmf_set_max_subsystems} 9020 9021Set the maximum allowed subsystems for the NVMe-oF target. This RPC may only be called 9022before SPDK subsystems have been initialized. 9023 9024#### Parameters 9025 9026Name | Optional | Type | Description 9027----------------------- | -------- | ----------- | ----------- 9028max_subsystems | Required | number | Maximum number of NVMe-oF subsystems 9029 9030#### Example 9031 9032Example request: 9033 9034~~~json 9035{ 9036 "jsonrpc": "2.0", 9037 "id": 1, 9038 "method": "nvmf_set_max_subsystems", 9039 "params": { 9040 "max_subsystems": 1024 9041 } 9042} 9043~~~ 9044 9045Example response: 9046 9047~~~json 9048{ 9049 "jsonrpc": "2.0", 9050 "id": 1, 9051 "result": true 9052} 9053~~~ 9054 9055### nvmf_discovery_add_referral method {#rpc_nvmf_discovery_add_referral} 9056 9057Add a discovery service referral to an NVMe-oF target. If a referral with the given 9058parameters already exists, no action will be taken. 9059 9060#### Parameters 9061 9062Name | Optional | Type | Description 9063----------------------- | -------- | ----------- | ----------- 9064tgt_name | Optional | string | Parent NVMe-oF target name. 9065address | Required | object | @ref rpc_nvmf_listen_address object 9066secure_channel | Optional | bool | The connection to that discovery subsystem requires a secure channel 9067 9068#### Example 9069 9070Example request: 9071 9072~~~json 9073{ 9074 "jsonrpc": "2.0", 9075 "id": 1, 9076 "method": "nvmf_discovery_add_referral", 9077 "params": { 9078 "address": { 9079 "trtype": "RDMA", 9080 "adrfam": "IPv4", 9081 "traddr": "192.168.0.123", 9082 "trsvcid": "4420" 9083 } 9084 } 9085} 9086~~~ 9087 9088Example response: 9089 9090~~~json 9091{ 9092 "jsonrpc": "2.0", 9093 "id": 1, 9094 "result": true 9095} 9096~~~ 9097 9098### nvmf_discovery_remove_referral method {#rpc_nvmf_discovery_remove_referral} 9099 9100Remove a discovery service referral from an NVMe-oF target. 9101 9102#### Parameters 9103 9104Name | Optional | Type | Description 9105----------------------- | -------- | ----------- | ----------- 9106tgt_name | Optional | string | Parent NVMe-oF target name. 9107address | Required | object | @ref rpc_nvmf_listen_address object 9108 9109#### Example 9110 9111Example request: 9112 9113~~~json 9114{ 9115 "jsonrpc": "2.0", 9116 "id": 1, 9117 "method": "nvmf_discovery_remove_referral", 9118 "params": { 9119 "address": { 9120 "trtype": "RDMA", 9121 "adrfam": "IPv4", 9122 "traddr": "192.168.0.123", 9123 "trsvcid": "4420" 9124 } 9125 } 9126} 9127~~~ 9128 9129Example response: 9130 9131~~~json 9132{ 9133 "jsonrpc": "2.0", 9134 "id": 1, 9135 "result": true 9136} 9137~~~ 9138 9139### nvmf_discovery_get_referrals {#rpc_nvmf_discovery_get_referrals} 9140 9141#### Parameters 9142 9143Name | Optional | Type | Description 9144----------------------- | -------- | ----------- | ----------- 9145tgt_name | Optional | string | Parent NVMe-oF target name. 9146 9147#### Example 9148 9149Example request: 9150 9151~~~json 9152{ 9153 "jsonrpc": "2.0", 9154 "id": 1, 9155 "method": "nvmf_discovery_get_referrals" 9156} 9157~~~ 9158 9159Example response: 9160 9161~~~json 9162{ 9163 "jsonrpc": "2.0", 9164 "id": 1, 9165 "result": [ 9166 { 9167 "address": { 9168 "trtype": "RDMA", 9169 "adrfam": "IPv4", 9170 "traddr": "192.168.0.123", 9171 "trsvcid": "4420" 9172 } 9173 } 9174 ] 9175} 9176~~~ 9177 9178### nvmf_set_config {#rpc_nvmf_set_config} 9179 9180Set global configuration of NVMe-oF target. This RPC may only be called before SPDK subsystems 9181have been initialized. 9182 9183#### Parameters 9184 9185Name | Optional | Type | Description 9186----------------------- | -------- | ----------- | ----------- 9187acceptor_poll_rate | Optional | number | Polling interval of the acceptor for incoming connections (microseconds) 9188admin_cmd_passthru | Optional | object | Admin command passthru configuration 9189poll_groups_mask | Optional | string | Set cpumask for NVMf poll groups 9190discovery_filter | Optional | string | Set discovery filter, possible values are: `match_any` (default) or comma separated values: `transport`, `address`, `svcid` 9191dhchap_digests | Optional | list | List of allowed DH-HMAC-CHAP digests. 9192dhchap_dhgroups | Optional | list | List of allowed DH-HMAC-CHAP DH groups. 9193 9194#### admin_cmd_passthru {#spdk_nvmf_admin_passthru_conf} 9195 9196Name | Optional | Type | Description 9197----------------------- | -------- | ----------- | ----------- 9198identify_ctrlr | Required | bool | If true, enables custom identify handler that reports some identify attributes from the underlying NVMe drive 9199 9200#### Example 9201 9202Example request: 9203 9204~~~json 9205{ 9206 "jsonrpc": "2.0", 9207 "id": 1, 9208 "method": "nvmf_set_config", 9209 "params": { 9210 "acceptor_poll_rate": 10000 9211 } 9212} 9213~~~ 9214 9215Example response: 9216 9217~~~json 9218{ 9219 "jsonrpc": "2.0", 9220 "id": 1, 9221 "result": true 9222} 9223~~~ 9224 9225### nvmf_get_transports method {#rpc_nvmf_get_transports} 9226 9227#### Parameters 9228 9229The user may specify no parameters in order to list all transports, or a transport may be 9230specified by type. 9231 9232Name | Optional | Type | Description 9233--------------------------- | -------- | ------------| ----------- 9234tgt_name | Optional | string | Parent NVMe-oF target name. 9235trtype | Optional | string | Transport type. 9236 9237#### Example 9238 9239Example request: 9240 9241~~~json 9242{ 9243 "jsonrpc": "2.0", 9244 "id": 1, 9245 "method": "nvmf_get_transports" 9246} 9247~~~ 9248 9249Example response: 9250 9251~~~json 9252{ 9253 "jsonrpc": "2.0", 9254 "id": 1, 9255 "result": [ 9256 { 9257 "type": "RDMA". 9258 "max_queue_depth": 128, 9259 "max_io_qpairs_per_ctrlr": 64, 9260 "in_capsule_data_size": 4096, 9261 "max_io_size": 131072, 9262 "io_unit_size": 131072, 9263 "abort_timeout_sec": 1 9264 } 9265 ] 9266} 9267~~~ 9268 9269### nvmf_get_stats method {#rpc_nvmf_get_stats} 9270 9271Retrieve current statistics of the NVMf subsystem. 9272 9273#### Parameters 9274 9275Name | Optional | Type | Description 9276--------------------------- | -------- | ------------| ----------- 9277tgt_name | Optional | string | Parent NVMe-oF target name. 9278 9279#### Response 9280 9281The response is an object containing NVMf subsystem statistics. 9282In the response, `admin_qpairs` and `io_qpairs` are reflecting cumulative queue pair counts while 9283`current_admin_qpairs` and `current_io_qpairs` are showing the current number. 9284 9285#### Example 9286 9287Example request: 9288 9289~~~json 9290{ 9291 "jsonrpc": "2.0", 9292 "method": "nvmf_get_stats", 9293 "id": 1 9294} 9295~~~ 9296 9297Example response: 9298 9299~~~json 9300{ 9301 "jsonrpc": "2.0", 9302 "id": 1, 9303 "result": { 9304 "tick_rate": 2400000000, 9305 "poll_groups": [ 9306 { 9307 "name": "app_thread", 9308 "admin_qpairs": 1, 9309 "io_qpairs": 4, 9310 "current_admin_qpairs": 1, 9311 "current_io_qpairs": 2, 9312 "pending_bdev_io": 1721, 9313 "transports": [ 9314 { 9315 "trtype": "RDMA", 9316 "pending_data_buffer": 12131888, 9317 "devices": [ 9318 { 9319 "name": "mlx5_1", 9320 "polls": 72284105, 9321 "completions": 0, 9322 "requests": 0, 9323 "request_latency": 0, 9324 "pending_free_request": 0, 9325 "pending_rdma_read": 0, 9326 "pending_rdma_write": 0, 9327 "total_send_wrs": 0, 9328 "send_doorbell_updates": 0, 9329 "total_recv_wrs": 0, 9330 "recv_doorbell_updates": 1 9331 }, 9332 { 9333 "name": "mlx5_0", 9334 "polls": 72284105, 9335 "completions": 15165875, 9336 "requests": 7582935, 9337 "request_latency": 1249323766184, 9338 "pending_free_request": 0, 9339 "pending_rdma_read": 337602, 9340 "pending_rdma_write": 0, 9341 "total_send_wrs": 15165875, 9342 "send_doorbell_updates": 1516587, 9343 "total_recv_wrs": 15165875, 9344 "recv_doorbell_updates": 1516587 9345 } 9346 ] 9347 } 9348 ] 9349 } 9350 ] 9351 } 9352} 9353~~~ 9354 9355### nvmf_set_crdt {#rpc_nvmf_set_crdt} 9356 9357Set the 3 CRDT (Command Retry Delay Time) values. For details about 9358CRDT, please refer to the NVMe specification. Currently all the 9359SPDK nvmf subsystems share the same CRDT values. The default values 9360are 0. This rpc can only be invoked in STARTUP stage. All values are 9361in units of 100 milliseconds (same as the NVMe specification). 9362 9363#### Parameters 9364 9365Name | Optional | Type | Description 9366----------------------- | -------- | ----------- | ----------- 9367crdt1 | Optional | number | Command Retry Delay Time 1 9368crdt2 | Optional | number | Command Retry Delay Time 2 9369crdt3 | Optional | number | Command Retry Delay Time 3 9370 9371## Vfio-user Target 9372 9373### vfu_tgt_set_base_path {#rpc_vfu_tgt_set_base_path} 9374 9375Set base path of Unix Domain socket file. 9376 9377#### Parameters 9378 9379Name | Optional | Type | Description 9380----------------------- | -------- | ----------- | ----------- 9381path | Required | string | Base path 9382 9383#### Example 9384 9385Example request: 9386 9387~~~json 9388{ 9389 "params": { 9390 "path": "/var/run/vfu_tgt" 9391 }, 9392 "jsonrpc": "2.0", 9393 "method": "vfu_tgt_set_base_path", 9394 "id": 1 9395} 9396~~~ 9397 9398Example response: 9399 9400~~~json 9401{ 9402 "jsonrpc": "2.0", 9403 "id": 1, 9404 "result": true 9405} 9406~~~ 9407 9408### vfu_virtio_delete_endpoint {#rpc_vfu_virtio_delete_endpoint} 9409 9410Delete PCI device via endpoint name. 9411 9412#### Parameters 9413 9414Name | Optional | Type | Description 9415----------------------- | -------- | ----------- | ----------- 9416name | Required | string | Endpoint name 9417 9418#### Example 9419 9420Example request: 9421 9422~~~json 9423{ 9424 "params": { 9425 "name": "vfu.0" 9426 }, 9427 "jsonrpc": "2.0", 9428 "method": "vfu_virtio_delete_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_create_blk_endpoint {#rpc_vfu_virtio_create_blk_endpoint} 9444 9445Create vfio-user virtio-blk PCI endpoint. 9446 9447#### Parameters 9448 9449Name | Optional | Type | Description 9450----------------------- | -------- | ----------- | ----------- 9451name | Required | string | Endpoint name 9452bdev_name | Required | string | Block device name 9453cpumask | Optional | string | CPU masks 9454num_queues | Optional | number | Number of queues 9455qsize | Optional | number | Queue size 9456packed_ring | Optional | boolean | Enable packed ring 9457 9458#### Example 9459 9460Example request: 9461 9462~~~json 9463{ 9464 "params": { 9465 "name": "vfu.0", 9466 "bdev_name": "Malloc0", 9467 "cpumask": "0x2", 9468 "num_queues": 4, 9469 "qsize": 256 9470 }, 9471 "jsonrpc": "2.0", 9472 "method": "vfu_virtio_create_blk_endpoint", 9473 "id": 1 9474} 9475~~~ 9476 9477Example response: 9478 9479~~~json 9480{ 9481 "jsonrpc": "2.0", 9482 "id": 1, 9483 "result": true 9484} 9485~~~ 9486 9487### vfu_virtio_scsi_add_target {#rpc_vfu_virtio_scsi_add_target} 9488 9489Add block device to specified SCSI target of vfio-user virtio-scsi PCI endpoint. 9490 9491#### Parameters 9492 9493Name | Optional | Type | Description 9494----------------------- | -------- | ----------- | ----------- 9495name | Required | string | Endpoint name 9496scsi_target_num | Required | number | SCSI target number 9497bdev_name | Required | string | Block device name 9498 9499#### Example 9500 9501Example request: 9502 9503~~~json 9504{ 9505 "params": { 9506 "name": "vfu.0", 9507 "scsi_target_num": 0, 9508 "bdev_name": "Malloc0" 9509 }, 9510 "jsonrpc": "2.0", 9511 "method": "vfu_virtio_scsi_add_target", 9512 "id": 1 9513} 9514~~~ 9515 9516Example response: 9517 9518~~~json 9519{ 9520 "jsonrpc": "2.0", 9521 "id": 1, 9522 "result": true 9523} 9524~~~ 9525 9526### vfu_virtio_scsi_remove_target {#rpc_vfu_virtio_scsi_remove_target} 9527 9528Remove a SCSI target of vfio-user virtio-scsi PCI endpoint. 9529 9530#### Parameters 9531 9532Name | Optional | Type | Description 9533----------------------- | -------- | ----------- | ----------- 9534name | Required | string | Endpoint name 9535scsi_target_num | Required | number | SCSI target number 9536 9537#### Example 9538 9539Example request: 9540 9541~~~json 9542{ 9543 "params": { 9544 "name": "vfu.0", 9545 "scsi_target_num": 0 9546 }, 9547 "jsonrpc": "2.0", 9548 "method": "vfu_virtio_scsi_remove_target", 9549 "id": 1 9550} 9551~~~ 9552 9553Example response: 9554 9555~~~json 9556{ 9557 "jsonrpc": "2.0", 9558 "id": 1, 9559 "result": true 9560} 9561~~~ 9562 9563### vfu_virtio_create_scsi_endpoint {#rpc_vfu_virtio_create_scsi_endpoint} 9564 9565Create vfio-user virtio-scsi PCI endpoint. 9566 9567#### Parameters 9568 9569Name | Optional | Type | Description 9570----------------------- | -------- | ----------- | ----------- 9571name | Required | string | Endpoint name 9572cpumask | Optional | string | CPU masks 9573num_io_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 "cpumask": "0x2", 9586 "num_io_queues": 4, 9587 "qsize": 256 9588 }, 9589 "jsonrpc": "2.0", 9590 "method": "vfu_virtio_create_scsi_endpoint", 9591 "id": 1 9592} 9593~~~ 9594 9595Example response: 9596 9597~~~json 9598{ 9599 "jsonrpc": "2.0", 9600 "id": 1, 9601 "result": true 9602} 9603~~~ 9604 9605### vfu_virtio_create_fs_endpoint {#vfu_virtio_create_fs_endpoint} 9606 9607Create vfio-user virtio-fs PCI endpoint. 9608 9609#### Parameters 9610 9611Name | Optional | Type | Description 9612----------------------- | -------- | ----------- | ----------- 9613name | Required | string | Endpoint name 9614fsdev_name | Optional | string | Name of an underlying fsdev 9615tag | Optional | string | Virtio FS tag according to the virtio specification 9616cpumask | Optional | string | CPU masks 9617num_queues | Optional | number | Number of IO queues 9618qsize | Optional | number | Queue size 9619packed_ring | Optional | boolean | Enable packed ring 9620 9621#### Example 9622 9623Example request: 9624 9625~~~json 9626{ 9627 "params": { 9628 "name": "vfu.0", 9629 "fsdev_name": "aio0", 9630 "tag": "virtiofs0", 9631 "cpumask": "0x2", 9632 "num_queues": 4, 9633 "qsize": 256 9634 }, 9635 "jsonrpc": "2.0", 9636 "method": "vfu_virtio_create_fs_endpoint", 9637 "id": 1 9638} 9639~~~ 9640 9641Example response: 9642 9643~~~json 9644{ 9645 "jsonrpc": "2.0", 9646 "id": 1, 9647 "result": true 9648} 9649~~~ 9650 9651## Vhost Target {#jsonrpc_components_vhost_tgt} 9652 9653The following common preconditions need to be met in all target types. 9654 9655Controller name will be used to create UNIX domain socket. This implies that name concatenated with vhost socket 9656directory path needs to be valid UNIX socket name. 9657 9658@ref cpu_mask parameter is used to choose CPU on which pollers will be launched when new initiator is connecting. 9659It must be a subset of application CPU mask. Default value is CPU mask of the application. 9660 9661### vhost_controller_set_coalescing {#rpc_vhost_controller_set_coalescing} 9662 9663Controls interrupt coalescing for specific target. Because `delay_base_us` is used to calculate delay in CPU ticks 9664there is no hardcoded limit for this parameter. Only limitation is that final delay in CPU ticks might not overflow 966532 bit unsigned integer (which is more than 1s @ 4GHz CPU). In real scenarios `delay_base_us` should be much lower 9666than 150us. To disable coalescing set `delay_base_us` to 0. 9667 9668#### Parameters 9669 9670Name | Optional | Type | Description 9671----------------------- | -------- | ----------- | ----------- 9672ctrlr | Required | string | Controller name 9673delay_base_us | Required | number | Base (minimum) coalescing time in microseconds 9674iops_threshold | Required | number | Coalescing activation level greater than 0 in IO per second 9675 9676#### Example 9677 9678Example request: 9679 9680~~~json 9681{ 9682 "params": { 9683 "iops_threshold": 100000, 9684 "ctrlr": "VhostScsi0", 9685 "delay_base_us": 80 9686 }, 9687 "jsonrpc": "2.0", 9688 "method": "vhost_controller_set_coalescing", 9689 "id": 1 9690} 9691~~~ 9692 9693Example response: 9694 9695~~~json 9696{ 9697 "jsonrpc": "2.0", 9698 "id": 1, 9699 "result": true 9700} 9701~~~ 9702 9703### vhost_create_scsi_controller {#rpc_vhost_create_scsi_controller} 9704 9705Construct vhost SCSI target. 9706 9707#### Parameters 9708 9709Name | Optional | Type | Description 9710----------------------- | -------- | ----------- | ----------- 9711ctrlr | Required | string | Controller name 9712cpumask | Optional | string | @ref cpu_mask for this controller 9713delay | Optional | boolean | If true, delay the controller startup. 9714 9715#### Example 9716 9717Example request: 9718 9719~~~json 9720{ 9721 "params": { 9722 "cpumask": "0x2", 9723 "ctrlr": "VhostScsi0", 9724 "delay": true 9725 }, 9726 "jsonrpc": "2.0", 9727 "method": "vhost_create_scsi_controller", 9728 "id": 1 9729} 9730~~~ 9731 9732Example response: 9733 9734~~~json 9735{ 9736 "jsonrpc": "2.0", 9737 "id": 1, 9738 "result": true 9739} 9740~~~ 9741 9742### vhost_start_scsi_controller {#rpc_vhost_start_scsi_controller} 9743 9744Start vhost SCSI controller, if controller is already started, do nothing. 9745 9746#### Parameters 9747 9748Name | Optional | Type | Description 9749----------------------- | -------- | ----------- | ----------- 9750ctrlr | Required | string | Controller name 9751 9752#### Example 9753 9754Example request: 9755 9756~~~json 9757{ 9758 "params": { 9759 "ctrlr": "VhostScsi0", 9760 }, 9761 "jsonrpc": "2.0", 9762 "method": "vhost_start_scsi_controller", 9763 "id": 1 9764} 9765~~~ 9766 9767Example response: 9768 9769~~~json 9770response: 9771{ 9772 "jsonrpc": "2.0", 9773 "id": 1, 9774 "result": true 9775} 9776~~~ 9777 9778### vhost_scsi_controller_add_target {#rpc_vhost_scsi_controller_add_target} 9779 9780In vhost target `ctrlr` create SCSI target with ID `scsi_target_num` and add `bdev_name` as LUN 0. 9781 9782#### Parameters 9783 9784Name | Optional | Type | Description 9785----------------------- | -------- | ----------- | ----------- 9786ctrlr | Required | string | Controller name 9787scsi_target_num | Required | number | SCSI target ID between 0 and 7 or -1 to use first free ID. 9788bdev_name | Required | string | Name of bdev to expose as a LUN 0 9789 9790#### Response 9791 9792SCSI target ID. 9793 9794#### Example 9795 9796Example request: 9797 9798~~~json 9799{ 9800 "params": { 9801 "scsi_target_num": 1, 9802 "bdev_name": "Malloc0", 9803 "ctrlr": "VhostScsi0" 9804 }, 9805 "jsonrpc": "2.0", 9806 "method": "vhost_scsi_controller_add_target", 9807 "id": 1 9808} 9809~~~ 9810 9811Example response: 9812 9813~~~json 9814response: 9815{ 9816 "jsonrpc": "2.0", 9817 "id": 1, 9818 "result": 1 9819} 9820~~~ 9821 9822### vhost_scsi_controller_remove_target {#rpc_vhost_scsi_controller_remove_target} 9823 9824Remove SCSI target ID `scsi_target_num` from vhost target `scsi_target_num`. 9825 9826This method will fail if initiator is connected, but doesn't support hot-remove (the `VIRTIO_SCSI_F_HOTPLUG` is not negotiated). 9827 9828#### Parameters 9829 9830Name | Optional | Type | Description 9831----------------------- | -------- | ----------- | ----------- 9832ctrlr | Required | string | Controller name 9833scsi_target_num | Required | number | SCSI target ID between 0 and 7 9834 9835#### Example 9836 9837Example request: 9838 9839~~~json 9840request: 9841{ 9842 "params": { 9843 "scsi_target_num": 1, 9844 "ctrlr": "VhostScsi0" 9845 }, 9846 "jsonrpc": "2.0", 9847 "method": "vhost_scsi_controller_remove_target", 9848 "id": 1 9849} 9850~~~ 9851 9852Example response: 9853 9854~~~json 9855{ 9856 "jsonrpc": "2.0", 9857 "id": 1, 9858 "result": true 9859} 9860~~~ 9861 9862### virtio_blk_create_transport {#rpc_virtio_blk_create_transport} 9863 9864Create virtio blk transport. 9865 9866#### Parameters 9867 9868Name | Optional | Type | Description 9869----------------------- | -------- | ----------- | ----------- 9870name | Required | string | Transport name 9871 9872#### Example 9873 9874Example request: 9875 9876~~~json 9877{ 9878 "params": { 9879 "name": "vhost_user_blk" 9880 }, 9881 "jsonrpc": "2.0", 9882 "method": "virtio_blk_create_transport", 9883 "id": 1 9884} 9885~~~ 9886 9887Example response: 9888 9889~~~json 9890{ 9891 "jsonrpc": "2.0", 9892 "id": 1, 9893 "result": true 9894} 9895~~~ 9896 9897### virtio_blk_get_transports {#rpc_virtio_blk_get_transports} 9898 9899#### Parameters 9900 9901The user may specify no parameters in order to list all transports, 9902or a transport name may be specified. 9903 9904Name | Optional | Type | Description 9905--------------------------- | -------- | ------------| ----------- 9906name | Optional | string | Transport name. 9907 9908#### Example 9909 9910Example request: 9911 9912~~~json 9913{ 9914 "jsonrpc": "2.0", 9915 "method": "virtio_blk_get_transports", 9916 "id": 1 9917} 9918~~~ 9919 9920Example response: 9921 9922~~~json 9923{ 9924 "jsonrpc": "2.0", 9925 "id": 1, 9926 "result": [ 9927 { 9928 "name": "vhost_user_blk" 9929 } 9930 ] 9931} 9932~~~ 9933 9934### vhost_create_blk_controller {#rpc_vhost_create_blk_controller} 9935 9936Create vhost block controller 9937 9938If `readonly` is `true` then vhost block target will be created as read only and fail any write requests. 9939The `VIRTIO_BLK_F_RO` feature flag will be offered to the initiator. 9940 9941#### Parameters 9942 9943Name | Optional | Type | Description 9944----------------------- | -------- | ----------- | ----------- 9945ctrlr | Required | string | Controller name 9946bdev_name | Required | string | Name of bdev to expose block device 9947readonly | Optional | boolean | If true, this target will be read only (default: false) 9948cpumask | Optional | string | @ref cpu_mask for this controller 9949transport | Optional | string | virtio blk transport name (default: vhost_user_blk) 9950 9951#### Example 9952 9953Example request: 9954 9955~~~json 9956{ 9957 "params": { 9958 "dev_name": "Malloc0", 9959 "ctrlr": "VhostBlk0" 9960 }, 9961 "jsonrpc": "2.0", 9962 "method": "vhost_create_blk_controller", 9963 "id": 1 9964} 9965~~~ 9966 9967Example response: 9968 9969~~~json 9970{ 9971 "jsonrpc": "2.0", 9972 "id": 1, 9973 "result": true 9974} 9975~~~ 9976 9977### vhost_get_controllers {#rpc_vhost_get_controllers} 9978 9979Display information about all or specific vhost controller(s). 9980 9981#### Parameters 9982 9983The user may specify no parameters in order to list all controllers, or a controller may be 9984specified by name. 9985 9986Name | Optional | Type | Description 9987----------------------- | -------- | ----------- | ----------- 9988name | Optional | string | Vhost controller name 9989 9990#### Response {#rpc_vhost_get_controllers_response} 9991 9992Response is an array of objects describing requested controller(s). Common fields are: 9993 9994Name | Type | Description 9995----------------------- | ----------- | ----------- 9996ctrlr | string | Controller name 9997cpumask | string | @ref cpu_mask of this controller 9998delay_base_us | number | Base (minimum) coalescing time in microseconds (0 if disabled) 9999iops_threshold | number | Coalescing activation level 10000backend_specific | object | Backend specific information 10001 10002### Vhost block {#rpc_vhost_get_controllers_blk} 10003 10004`backend_specific` contains one `block` object of type: 10005 10006Name | Type | Description 10007----------------------- | ----------- | ----------- 10008bdev | string | Backing bdev name or Null if bdev is hot-removed 10009readonly | boolean | True if controllers is readonly, false otherwise 10010 10011### Vhost SCSI {#rpc_vhost_get_controllers_scsi} 10012 10013`backend_specific` contains `scsi` array of following objects: 10014 10015Name | Type | Description 10016----------------------- | ----------- | ----------- 10017target_name | string | Name of this SCSI target 10018id | number | Unique SPDK global SCSI target ID 10019scsi_dev_num | number | SCSI target ID initiator will see when scanning this controller 10020luns | array | array of objects describing @ref rpc_vhost_get_controllers_scsi_luns 10021 10022### Vhost SCSI LUN {#rpc_vhost_get_controllers_scsi_luns} 10023 10024Object of type: 10025 10026Name | Type | Description 10027----------------------- | ----------- | ----------- 10028id | number | SCSI LUN ID 10029bdev_name | string | Backing bdev name 10030 10031### Vhost NVMe {#rpc_vhost_get_controllers_nvme} 10032 10033`backend_specific` contains `namespaces` array of following objects: 10034 10035Name | Type | Description 10036----------------------- | ----------- | ----------- 10037nsid | number | Namespace ID 10038bdev | string | Backing bdev name 10039 10040#### Example 10041 10042Example request: 10043 10044~~~json 10045{ 10046 "jsonrpc": "2.0", 10047 "method": "vhost_get_controllers", 10048 "id": 1 10049} 10050~~~ 10051 10052Example response: 10053 10054~~~json 10055{ 10056 "jsonrpc": "2.0", 10057 "id": 1, 10058 "result": [ 10059 { 10060 "cpumask": "0x2", 10061 "backend_specific": { 10062 "block": { 10063 "readonly": false, 10064 "bdev": "Malloc0" 10065 } 10066 }, 10067 "iops_threshold": 60000, 10068 "ctrlr": "VhostBlk0", 10069 "delay_base_us": 100 10070 }, 10071 { 10072 "cpumask": "0x2", 10073 "backend_specific": { 10074 "scsi": [ 10075 { 10076 "target_name": "Target 2", 10077 "luns": [ 10078 { 10079 "id": 0, 10080 "bdev_name": "Malloc1" 10081 } 10082 ], 10083 "id": 0, 10084 "scsi_dev_num": 2 10085 }, 10086 { 10087 "target_name": "Target 5", 10088 "luns": [ 10089 { 10090 "id": 0, 10091 "bdev_name": "Malloc2" 10092 } 10093 ], 10094 "id": 1, 10095 "scsi_dev_num": 5 10096 } 10097 ] 10098 }, 10099 "iops_threshold": 60000, 10100 "ctrlr": "VhostScsi0", 10101 "delay_base_us": 0 10102 }, 10103 { 10104 "cpumask": "0x2", 10105 "backend_specific": { 10106 "namespaces": [ 10107 { 10108 "bdev": "Malloc3", 10109 "nsid": 1 10110 }, 10111 { 10112 "bdev": "Malloc4", 10113 "nsid": 2 10114 } 10115 ] 10116 }, 10117 "iops_threshold": 60000, 10118 "ctrlr": "VhostNvme0", 10119 "delay_base_us": 0 10120 } 10121 ] 10122} 10123~~~ 10124 10125### vhost_delete_controller {#rpc_vhost_delete_controller} 10126 10127Remove vhost target. 10128 10129This call will fail if there is an initiator connected or there is at least one SCSI target configured in case of 10130vhost SCSI target. In the later case please remove all SCSI targets first using @ref rpc_vhost_scsi_controller_remove_target. 10131 10132#### Parameters 10133 10134Name | Optional | Type | Description 10135----------------------- | -------- | ----------- | ----------- 10136ctrlr | Required | string | Controller name 10137 10138#### Example 10139 10140Example request: 10141 10142~~~json 10143{ 10144 "params": { 10145 "ctrlr": "VhostNvme0" 10146 }, 10147 "jsonrpc": "2.0", 10148 "method": "vhost_delete_controller", 10149 "id": 1 10150} 10151~~~ 10152 10153Example response: 10154 10155~~~json 10156{ 10157 "jsonrpc": "2.0", 10158 "id": 1, 10159 "result": true 10160} 10161~~~ 10162 10163## Logical Volume {#jsonrpc_components_lvol} 10164 10165Identification of logical volume store and logical volume is explained first. 10166 10167A logical volume store has a UUID and a name for its identification. 10168The UUID is generated on creation and it can be used as a unique identifier. 10169The name is specified on creation and can be renamed. 10170Either UUID or name is used to access logical volume store in RPCs. 10171 10172A logical volume has a UUID and a name for its identification. 10173The UUID of the logical volume is generated on creation and it can be unique identifier. 10174The alias of the logical volume takes the format _lvs_name/lvol_name_ where: 10175 10176* _lvs_name_ is the name of the logical volume store. 10177* _lvol_name_ is specified on creation and can be renamed. 10178 10179### bdev_lvol_create_lvstore {#rpc_bdev_lvol_create_lvstore} 10180 10181Construct a logical volume store. 10182 10183#### Parameters 10184 10185Name | Optional | Type | Description 10186----------------------------- | -------- | ----------- | ----------- 10187bdev_name | Required | string | Bdev on which to construct logical volume store 10188lvs_name | Required | string | Name of the logical volume store to create 10189cluster_sz | Optional | number | Cluster size of the logical volume store in bytes (Default: 4MiB) 10190clear_method | Optional | string | Change clear method for data region. Available: none, unmap (default), write_zeroes 10191num_md_pages_per_cluster_ratio| Optional | number | Reserved metadata pages per cluster (Default: 100) 10192 10193The num_md_pages_per_cluster_ratio defines the amount of metadata to 10194allocate when the logical volume store is created. The default value 10195is '100', which translates to 1 4KiB per cluster. For the default 4MiB 10196cluster size, this equates to about 0.1% of the underlying block 10197device allocated for metadata. Logical volume stores can be grown, if 10198the size of the underlying block device grows in the future, but only 10199if enough metadata pages were allocated to support the growth. So 10200num_md_pages_per_cluster_ratio should be set to a higher value if 10201wanting to support future growth. For example, 10202num_md_pages_per_cluster_ratio = 200 would support future 2x growth of 10203the logical volume store, and would result in 0.2% of the underlying 10204block device allocated for metadata (with a default 4MiB cluster 10205size). 10206 10207#### Response 10208 10209UUID of the created logical volume store is returned. 10210 10211#### Example 10212 10213Example request: 10214 10215~~~json 10216{ 10217 "jsonrpc": "2.0", 10218 "id": 1, 10219 "method": "bdev_lvol_create_lvstore", 10220 "params": { 10221 "lvs_name": "LVS0", 10222 "bdev_name": "Malloc0", 10223 "clear_method": "write_zeroes" 10224 } 10225} 10226~~~ 10227 10228Example response: 10229 10230~~~json 10231{ 10232 "jsonrpc": "2.0", 10233 "id": 1, 10234 "result": "a9959197-b5e2-4f2d-8095-251ffb6985a5" 10235} 10236~~~ 10237 10238### bdev_lvol_delete_lvstore {#rpc_bdev_lvol_delete_lvstore} 10239 10240Destroy a logical volume store. 10241 10242#### Parameters 10243 10244Name | Optional | Type | Description 10245----------------------- | -------- | ----------- | ----------- 10246uuid | Optional | string | UUID of the logical volume store to destroy 10247lvs_name | Optional | string | Name of the logical volume store to destroy 10248 10249Either uuid or lvs_name must be specified, but not both. 10250 10251#### Example 10252 10253Example request: 10254 10255~~~json 10256{ 10257 "jsonrpc": "2.0", 10258 "method": "bdev_lvol_delete_lvstore", 10259 "id": 1 10260 "params": { 10261 "uuid": "a9959197-b5e2-4f2d-8095-251ffb6985a5" 10262 } 10263} 10264~~~ 10265 10266Example response: 10267 10268~~~json 10269{ 10270 "jsonrpc": "2.0", 10271 "id": 1, 10272 "result": true 10273} 10274~~~ 10275 10276### bdev_lvol_get_lvstores {#rpc_bdev_lvol_get_lvstores} 10277 10278Get a list of logical volume stores. 10279 10280#### Parameters 10281 10282Name | Optional | Type | Description 10283----------------------- | -------- | ----------- | ----------- 10284uuid | Optional | string | UUID of the logical volume store to retrieve information about 10285lvs_name | Optional | string | Name of the logical volume store to retrieve information about 10286 10287Either uuid or lvs_name may be specified, but not both. 10288If both uuid and lvs_name are omitted, information about all logical volume stores is returned. 10289 10290#### Example 10291 10292Example request: 10293 10294~~~json 10295{ 10296 "jsonrpc": "2.0", 10297 "method": "bdev_lvol_get_lvstores", 10298 "id": 1, 10299 "params": { 10300 "lvs_name": "LVS0" 10301 } 10302} 10303~~~ 10304 10305Example response: 10306 10307~~~json 10308{ 10309 "jsonrpc": "2.0", 10310 "id": 1, 10311 "result": [ 10312 { 10313 "uuid": "a9959197-b5e2-4f2d-8095-251ffb6985a5", 10314 "base_bdev": "Malloc0", 10315 "free_clusters": 31, 10316 "cluster_size": 4194304, 10317 "total_data_clusters": 31, 10318 "block_size": 4096, 10319 "name": "LVS0" 10320 } 10321 ] 10322} 10323~~~ 10324 10325### bdev_lvol_rename_lvstore {#rpc_bdev_lvol_rename_lvstore} 10326 10327Rename a logical volume store. 10328 10329#### Parameters 10330 10331Name | Optional | Type | Description 10332----------------------- | -------- | ----------- | ----------- 10333old_name | Required | string | Existing logical volume store name 10334new_name | Required | string | New logical volume store name 10335 10336#### Example 10337 10338Example request: 10339 10340~~~json 10341{ 10342 "jsonrpc": "2.0", 10343 "method": "bdev_lvol_rename_lvstore", 10344 "id": 1, 10345 "params": { 10346 "old_name": "LVS0", 10347 "new_name": "LVS2" 10348 } 10349} 10350~~~ 10351 10352Example response: 10353 10354~~~json 10355{ 10356 "jsonrpc": "2.0", 10357 "id": 1, 10358 "result": true 10359} 10360~~~ 10361 10362### bdev_lvol_grow_lvstore {#rpc_bdev_lvol_grow_lvstore} 10363 10364Grow the logical volume store to fill the underlying bdev 10365 10366#### Parameters 10367 10368Name | Optional | Type | Description 10369----------------------- | -------- | ----------- | ----------- 10370uuid | Optional | string | UUID of the logical volume store to grow 10371lvs_name | Optional | string | Name of the logical volume store to grow 10372 10373Either uuid or lvs_name must be specified, but not both. 10374 10375#### Example 10376 10377Example request: 10378 10379~~~json 10380{ 10381 "jsonrpc": "2.0", 10382 "method": "bdev_lvol_grow_lvstore", 10383 "id": 1 10384 "params": { 10385 "uuid": "a9959197-b5e2-4f2d-8095-251ffb6985a5" 10386 } 10387} 10388~~~ 10389 10390Example response: 10391 10392~~~json 10393{ 10394 "jsonrpc": "2.0", 10395 "id": 1, 10396 "result": true 10397} 10398~~~ 10399 10400### bdev_lvol_create {#rpc_bdev_lvol_create} 10401 10402Create a logical volume on a logical volume store. 10403 10404#### Parameters 10405 10406Name | Optional | Type | Description 10407----------------------- | -------- | ----------- | ----------- 10408lvol_name | Required | string | Name of logical volume to create 10409size_in_mib | Required | number | Desired size of logical volume in MiB 10410thin_provision | Optional | boolean | True to enable thin provisioning 10411uuid | Optional | string | UUID of logical volume store to create logical volume on 10412lvs_name | Optional | string | Name of logical volume store to create logical volume on 10413clear_method | Optional | string | Change default data clusters clear method. Available: none, unmap, write_zeroes 10414 10415Size will be rounded up to a multiple of cluster size. Either uuid or lvs_name must be specified, but not both. 10416lvol_name will be used in the alias of the created logical volume. 10417 10418#### Response 10419 10420UUID of the created logical volume is returned. 10421 10422#### Example 10423 10424Example request: 10425 10426~~~json 10427{ 10428 "jsonrpc": "2.0", 10429 "method": "bdev_lvol_create", 10430 "id": 1, 10431 "params": { 10432 "lvol_name": "LVOL0", 10433 "size_in_mib": 1, 10434 "lvs_name": "LVS0", 10435 "clear_method": "unmap", 10436 "thin_provision": true 10437 } 10438} 10439~~~ 10440 10441Example response: 10442 10443~~~json 10444{ 10445 "jsonrpc": "2.0", 10446 "id": 1, 10447 "result": "1b38702c-7f0c-411e-a962-92c6a5a8a602" 10448} 10449~~~ 10450 10451### bdev_lvol_snapshot {#rpc_bdev_lvol_snapshot} 10452 10453Capture a snapshot of the current state of a logical volume. 10454 10455#### Parameters 10456 10457Name | Optional | Type | Description 10458----------------------- | -------- | ----------- | ----------- 10459lvol_name | Required | string | UUID or alias of the logical volume to create a snapshot from 10460snapshot_name | Required | string | Name for the newly created snapshot 10461 10462#### Response 10463 10464UUID of the created logical volume snapshot is returned. 10465 10466#### Example 10467 10468Example request: 10469 10470~~~json 10471{ 10472 "jsonrpc": "2.0", 10473 "method": "bdev_lvol_snapshot", 10474 "id": 1, 10475 "params": { 10476 "lvol_name": "1b38702c-7f0c-411e-a962-92c6a5a8a602", 10477 "snapshot_name": "SNAP1" 10478 } 10479} 10480~~~ 10481 10482Example response: 10483 10484~~~json 10485{ 10486 "jsonrpc": "2.0", 10487 "id": 1, 10488 "result": "cc8d7fdf-7865-4d1f-9fc6-35da8e368670" 10489} 10490~~~ 10491 10492### bdev_lvol_clone {#rpc_bdev_lvol_clone} 10493 10494Create a logical volume based on a snapshot. 10495 10496#### Parameters 10497 10498Name | Optional | Type | Description 10499----------------------- | -------- | ----------- | ----------- 10500snapshot_name | Required | string | UUID or alias of the snapshot to clone 10501clone_name | Required | string | Name for the logical volume to create 10502 10503#### Response 10504 10505UUID of the created logical volume clone is returned. 10506 10507#### Example 10508 10509Example request: 10510 10511~~~json 10512{ 10513 "jsonrpc": "2.0" 10514 "method": "bdev_lvol_clone", 10515 "id": 1, 10516 "params": { 10517 "snapshot_name": "cc8d7fdf-7865-4d1f-9fc6-35da8e368670", 10518 "clone_name": "CLONE1" 10519 } 10520} 10521~~~ 10522 10523Example response: 10524 10525~~~json 10526{ 10527 "jsonrpc": "2.0", 10528 "id": 1, 10529 "result": "8d87fccc-c278-49f0-9d4c-6237951aca09" 10530} 10531~~~ 10532 10533### bdev_lvol_clone_bdev {#rpc_bdev_lvol_clone_bdev} 10534 10535Create a logical volume based on an external snapshot bdev. The external snapshot bdev 10536is a bdev that will not be written to by any consumer and must not be an lvol in the 10537lvstore as the clone. 10538 10539Regardless of whether the bdev is specified by name or UUID, the bdev UUID will be stored 10540in the logical volume's metadata for use while the lvolstore is loading. For this reason, 10541it is important that the bdev chosen has a static UUID. 10542 10543#### Parameters 10544 10545Name | Optional | Type | Description 10546----------------------- | -------- | ----------- | ----------- 10547bdev | Required | string | Name or UUID for bdev that acts as the external snapshot 10548lvs_name | Required | string | logical volume store name 10549clone_name | Required | string | Name for the logical volume to create 10550 10551#### Response 10552 10553UUID of the created logical volume clone is returned. 10554 10555#### Example 10556 10557Example request: 10558 10559~~~json 10560{ 10561 "jsonrpc": "2.0", 10562 "method": "bdev_lvol_clone_bdev", 10563 "id": 1, 10564 "params": { 10565 "bdev": "e4b40d8b-f623-416d-8234-baf5a4c83cbd", 10566 "lvs_name": "lvs1", 10567 "clone_name": "clone2" 10568 } 10569} 10570~~~ 10571 10572Example response: 10573 10574~~~json 10575{ 10576 "jsonrpc": "2.0", 10577 "id": 1, 10578 "result": "336f662b-08e5-4006-8e06-e2023f7f9886" 10579} 10580~~~ 10581 10582### bdev_lvol_rename {#rpc_bdev_lvol_rename} 10583 10584Rename a logical volume. New name will rename only the alias of the logical volume. 10585 10586#### Parameters 10587 10588Name | Optional | Type | Description 10589----------------------- | -------- | ----------- | ----------- 10590old_name | Required | string | UUID or alias of the existing logical volume 10591new_name | Required | string | New logical volume name 10592 10593#### Example 10594 10595Example request: 10596 10597~~~json 10598{ 10599 "jsonrpc": "2.0", 10600 "method": "bdev_lvol_rename", 10601 "id": 1, 10602 "params": { 10603 "old_name": "067df606-6dbc-4143-a499-0d05855cb3b8", 10604 "new_name": "LVOL2" 10605 } 10606} 10607~~~ 10608 10609Example response: 10610 10611~~~json 10612{ 10613 "jsonrpc": "2.0", 10614 "id": 1, 10615 "result": true 10616} 10617~~~ 10618 10619### bdev_lvol_resize {#rpc_bdev_lvol_resize} 10620 10621Resize a logical volume. 10622 10623#### Parameters 10624 10625Name | Optional | Type | Description 10626----------------------- | -------- | ----------- | ----------- 10627name | Required | string | UUID or alias of the logical volume to resize 10628size_in_mib | Required | number | Desired size of the logical volume in MiB 10629 10630#### Example 10631 10632Example request: 10633 10634~~~json 10635{ 10636 "jsonrpc": "2.0", 10637 "method": "bdev_lvol_resize", 10638 "id": 1, 10639 "params": { 10640 "name": "51638754-ca16-43a7-9f8f-294a0805ab0a", 10641 "size_in_mib": 2 10642 } 10643} 10644~~~ 10645 10646Example response: 10647 10648~~~json 10649{ 10650 "jsonrpc": "2.0", 10651 "id": 1, 10652 "result": true 10653} 10654~~~ 10655 10656### bdev_lvol_set_read_only{#rpc_bdev_lvol_set_read_only} 10657 10658Mark logical volume as read only. 10659 10660#### Parameters 10661 10662Name | Optional | Type | Description 10663----------------------- | -------- | ----------- | ----------- 10664name | Required | string | UUID or alias of the logical volume to set as read only 10665 10666#### Example 10667 10668Example request: 10669 10670~~~json 10671{ 10672 "jsonrpc": "2.0", 10673 "method": "bdev_lvol_set_read_only", 10674 "id": 1, 10675 "params": { 10676 "name": "51638754-ca16-43a7-9f8f-294a0805ab0a", 10677 } 10678} 10679~~~ 10680 10681Example response: 10682 10683~~~json 10684{ 10685 "jsonrpc": "2.0", 10686 "id": 1, 10687 "result": true 10688} 10689~~~ 10690 10691### bdev_lvol_delete {#rpc_bdev_lvol_delete} 10692 10693Destroy a logical volume. 10694 10695#### Parameters 10696 10697Name | Optional | Type | Description 10698----------------------- | -------- | ----------- | ----------- 10699name | Required | string | UUID or alias of the logical volume to destroy 10700 10701#### Example 10702 10703Example request: 10704 10705~~~json 10706{ 10707 "jsonrpc": "2.0", 10708 "method": "bdev_lvol_delete", 10709 "id": 1, 10710 "params": { 10711 "name": "51638754-ca16-43a7-9f8f-294a0805ab0a" 10712 } 10713} 10714~~~ 10715 10716Example response: 10717 10718~~~json 10719{ 10720 "jsonrpc": "2.0", 10721 "id": 1, 10722 "result": true 10723} 10724~~~ 10725 10726### bdev_lvol_inflate {#rpc_bdev_lvol_inflate} 10727 10728Inflate a logical volume. All unallocated clusters are allocated and copied from the parent or zero filled 10729if not allocated in the parent. Then all dependencies on the parent are removed. 10730 10731### Parameters 10732 10733Name | Optional | Type | Description 10734----------------------- | -------- | ----------- | ----------- 10735name | Required | string | UUID or alias of the logical volume to inflate 10736 10737#### Example 10738 10739Example request: 10740 10741~~~json 10742{ 10743 "jsonrpc": "2.0", 10744 "method": "bdev_lvol_inflate", 10745 "id": 1, 10746 "params": { 10747 "name": "8d87fccc-c278-49f0-9d4c-6237951aca09" 10748 } 10749} 10750~~~ 10751 10752Example response: 10753 10754~~~json 10755{ 10756 "jsonrpc": "2.0", 10757 "id": 1, 10758 "result": true 10759} 10760~~~ 10761 10762### bdev_lvol_decouple_parent {#rpc_bdev_lvol_decouple_parent} 10763 10764Decouple the parent of a logical volume. For unallocated clusters which is allocated in the parent, they are 10765allocated and copied from the parent, but for unallocated clusters which is thin provisioned in the parent, 10766they are kept thin provisioned. Then all dependencies on the parent are removed. 10767 10768#### Parameters 10769 10770Name | Optional | Type | Description 10771----------------------- | -------- | ----------- | ----------- 10772name | Required | string | UUID or alias of the logical volume to decouple the parent of it 10773 10774#### Example 10775 10776Example request: 10777 10778~~~json 10779{ 10780 "jsonrpc": "2.0", 10781 "method": "bdev_lvol_decouple_parent", 10782 "id": 1. 10783 "params": { 10784 "name": "8d87fccc-c278-49f0-9d4c-6237951aca09" 10785 } 10786} 10787~~~ 10788 10789Example response: 10790 10791~~~json 10792{ 10793 "jsonrpc": "2.0", 10794 "id": 1, 10795 "result": true 10796} 10797~~~ 10798 10799### bdev_lvol_get_lvols {#rpc_bdev_lvol_get_lvols} 10800 10801Get a list of logical volumes. This list can be limited by lvol store and will display volumes even if 10802they are degraded. Degraded lvols do not have an associated bdev, thus this RPC call may return lvols 10803not returned by `bdev_get_bdevs`. 10804 10805#### Parameters 10806 10807Name | Optional | Type | Description 10808----------------------- | -------- | ----------- | ----------- 10809lvs_uuid | Optional | string | Only show volumes in the logical volume store with this UUID 10810lvs_name | Optional | string | Only show volumes in the logical volume store with this name 10811 10812Either lvs_uuid or lvs_name may be specified, but not both. 10813If both lvs_uuid and lvs_name are omitted, information about lvols in all logical volume stores is returned. 10814 10815#### Example 10816 10817Example request: 10818 10819~~~json 10820{ 10821 "jsonrpc": "2.0", 10822 "method": "bdev_lvol_get_lvols", 10823 "id": 1, 10824 "params": { 10825 "lvs_name": "lvs_test" 10826 } 10827} 10828~~~ 10829 10830Example response: 10831 10832~~~json 10833[ 10834 { 10835 "alias": "lvs_test/lvol1", 10836 "uuid": "b335c368-851d-4099-81e0-018cc494fdf6", 10837 "name": "lvol1", 10838 "is_thin_provisioned": false, 10839 "is_snapshot": false, 10840 "is_clone": false, 10841 "is_esnap_clone": false, 10842 "is_degraded": false, 10843 "lvs": { 10844 "name": "lvs_test", 10845 "uuid": "a1c8d950-5715-4558-936d-ab9e6eca0794" 10846 } 10847 } 10848] 10849~~~ 10850 10851### bdev_lvol_set_parent {#rpc_bdev_lvol_set_parent} 10852 10853Set a snapshot as the parent of a lvol, making the lvol a clone of this snapshot. 10854The previous parent of the lvol, if any, can be another snapshot or an external snapshot; if the 10855lvol is not a clone, it must be thin-provisioned. 10856Lvol and parent snapshot must have the same size and must belong to the same lvol store. 10857 10858#### Parameters 10859 10860Name | Optional | Type | Description 10861----------------------- | -------- | ----------- | ----------- 10862lvol_name | Required | string | UUID or alias of the lvol to set parent of 10863parent_name | Required | string | UUID or alias of the snapshot to become parent of lvol 10864 10865#### Example 10866 10867Example request: 10868 10869~~~json 10870{ 10871 "jsonrpc": "2.0", 10872 "method": "bdev_lvol_set_parent", 10873 "id": 1, 10874 "params": { 10875 "lvol_name": "LVS1/LVOL0", 10876 "parent_name": "LVS1/SNAP0" 10877 } 10878} 10879~~~ 10880 10881Example response: 10882 10883~~~json 10884{ 10885 "jsonrpc": "2.0", 10886 "id": 1, 10887 "result": true 10888} 10889~~~ 10890 10891### bdev_lvol_set_parent_bdev {#rpc_bdev_lvol_set_parent_bdev} 10892 10893Set an external snapshot as the parent of a lvol, making the lvol a clone of this external 10894snapshot (see @ref rpc_bdev_lvol_clone_bdev). 10895The previous parent of the lvol, if any, can be another external snapshot or a snapshot; if the 10896lvol is not a clone, it must be thin-provisioned. 10897The size of the external snapshot device must be an integer multiple of cluster size of lvol's lvolstore. 10898 10899#### Parameters 10900 10901Name | Optional | Type | Description 10902----------------------- | -------- | ----------- | ----------- 10903lvol_name | Required | string | UUID or alias of the lvol to set external parent of 10904parent_name | Required | string | UUID or name of the external snapshot to become parent of lvol 10905 10906#### Example 10907 10908Example request: 10909 10910~~~json 10911{ 10912 "jsonrpc": "2.0", 10913 "method": "bdev_lvol_set_parent_bdev", 10914 "id": 1, 10915 "params": { 10916 "lvol_name": "LVS1/LVOL0", 10917 "parent_name": "e465527b-f412-4f70-a03e-c4a5d608f65e" 10918 } 10919} 10920~~~ 10921 10922Example response: 10923 10924~~~json 10925{ 10926 "jsonrpc": "2.0", 10927 "id": 1, 10928 "result": true 10929} 10930~~~ 10931 10932### bdev_lvol_start_shallow_copy {#rpc_bdev_lvol_start_shallow_copy} 10933 10934Start a shallow copy of an lvol over a given bdev. Only clusters allocated to the lvol will be written on the bdev. 10935Must have: 10936 10937* lvol read only 10938* lvol size less or equal than bdev size 10939* lvstore block size an even multiple of bdev block size 10940 10941#### Result 10942 10943This RPC starts the operation and return an identifier that can be used to query the status of the operation 10944with the RPC @ref rpc_bdev_lvol_check_shallow_copy. 10945 10946#### Parameters 10947 10948Name | Optional | Type | Description 10949----------------------- | -------- | ----------- | ----------- 10950src_lvol_name | Required | string | UUID or alias of lvol to create a copy from 10951dst_bdev_name | Required | string | Name of the bdev that acts as destination for the copy 10952 10953#### Example 10954 10955Example request: 10956 10957~~~json 10958{ 10959 "jsonrpc": "2.0", 10960 "method": "bdev_lvol_start_shallow_copy", 10961 "id": 1, 10962 "params": { 10963 "src_lvol_name": "8a47421a-20cf-444f-845c-d97ad0b0bd8e", 10964 "dst_bdev_name": "Nvme1n1" 10965 } 10966} 10967~~~ 10968 10969Example response: 10970 10971~~~json 10972{ 10973 "jsonrpc": "2.0", 10974 "id": 1, 10975 "result": { 10976 "operation_id": 7 10977 } 10978} 10979~~~ 10980 10981### bdev_lvol_check_shallow_copy {#rpc_bdev_lvol_check_shallow_copy} 10982 10983Get shallow copy status. 10984 10985#### Result 10986 10987Get info about the shallow copy operation identified by operation id. 10988It reports operation's status, which can be `in progress`, `complete` or `error`, 10989the actual number of copied clusters, the total number of clusters to copy and, 10990in case of error, a description. 10991Once the operation is ended and the result has been retrieved, the 10992operation is removed from the internal list of ended operation, so its 10993result cannot be accessed anymore. 10994 10995#### Parameters 10996 10997Name | Optional | Type | Description 10998----------------------- | -------- | ----------- | ----------- 10999operation_id | Required | number | operation identifier 11000 11001#### Example 11002 11003Example request: 11004 11005~~~json 11006{ 11007 "jsonrpc": "2.0", 11008 "method": "bdev_lvol_check_shallow_copy", 11009 "id": 1, 11010 "params": { 11011 "operation_id": 7 11012 } 11013} 11014~~~ 11015 11016Example response: 11017 11018~~~json 11019{ 11020 "jsonrpc": "2.0", 11021 "id": 1, 11022 "result": { 11023 "state": "in progress", 11024 "copied_clusters": 2, 11025 "total_clusters": 4 11026 } 11027} 11028~~~ 11029 11030## RAID 11031 11032### bdev_raid_set_options {#rpc_bdev_raid_set_options} 11033 11034Set options for bdev raid. 11035 11036This RPC can be called at any time, but the new value will only take effect for new raid bdevs. 11037 11038The `process_window_size_kb` parameter defines the size of the "window" (LBA range of the raid bdev) 11039in which a background process like rebuild performs its work. Any positive value is valid, but the value 11040actually used by a raid bdev can be adjusted to the size of the raid bdev or the write unit size. 11041`process_max_bandwidth_mb_sec` parameter defines the maximum bandwidth used by a background process like 11042rebuild. Any positive value or zero is valid, zero means no bandwidth limitation for background process. 11043It can only limit the process bandwidth but doesn't guarantee it can be reached. Changing this value will 11044not affect existing processes, it will only take effect on new processes generated after the RPC is completed. 11045 11046#### Parameters 11047 11048Name | Optional | Type | Description 11049----------------------------- | -------- | ----------- | ----------- 11050process_window_size_kb | Optional | number | Background process (e.g. rebuild) window size in KiB 11051process_max_bandwidth_mb_sec | Optional | number | Background process (e.g. rebuild) maximum bandwidth in MiB/Sec 11052 11053#### Example 11054 11055Example request: 11056 11057~~~json 11058request: 11059{ 11060 "jsonrpc": "2.0", 11061 "method": "bdev_raid_set_options", 11062 "id": 1, 11063 "params": { 11064 "process_window_size_kb": 512, 11065 "process_max_bandwidth_mb_sec": 100 11066 } 11067} 11068~~~ 11069 11070Example response: 11071 11072~~~json 11073{ 11074 "jsonrpc": "2.0", 11075 "id": 1, 11076 "result": true 11077} 11078~~~ 11079 11080### bdev_raid_get_bdevs {#rpc_bdev_raid_get_bdevs} 11081 11082This is used to list all the raid bdev details based on the input category requested. Category should be one 11083of 'all', 'online', 'configuring' or 'offline'. 'all' means all the raid bdevs whether they are online or 11084configuring or offline. 'online' is the raid bdev which is registered with bdev layer. 'configuring' is 11085the raid bdev which does not have full configuration discovered yet. 'offline' is the raid bdev which is 11086not registered with bdev as of now and it has encountered any error or user has requested to offline 11087the raid bdev. 11088 11089#### Parameters 11090 11091Name | Optional | Type | Description 11092----------------------- | -------- | ----------- | ----------- 11093category | Required | string | all or online or configuring or offline 11094 11095#### Example 11096 11097Example request: 11098 11099~~~json 11100{ 11101 "jsonrpc": "2.0", 11102 "method": "bdev_raid_get_bdevs", 11103 "id": 1, 11104 "params": { 11105 "category": "all" 11106 } 11107} 11108~~~ 11109 11110Example response: 11111 11112~~~json 11113{ 11114 "jsonrpc": "2.0", 11115 "id": 1, 11116 "result": [ 11117 { 11118 "name": "RaidBdev0", 11119 "uuid": "7d352e83-fe27-40f2-8fef-64563355e076", 11120 "strip_size_kb": 128, 11121 "state": "online", 11122 "raid_level": "raid0", 11123 "num_base_bdevs": 2, 11124 "num_base_bdevs_discovered": 2, 11125 "num_base_bdevs_operational": 2, 11126 "base_bdevs_list": [ 11127 { 11128 "name": "malloc0", 11129 "uuid": "d2788884-5b3e-4fd7-87ff-6c78177e14ab", 11130 "is_configured": true, 11131 "data_offset": 256, 11132 "data_size": 261888 11133 }, 11134 { 11135 "name": "malloc1", 11136 "uuid": "a81bb1f8-5865-488a-8758-10152017e7d1", 11137 "is_configured": true, 11138 "data_offset": 256, 11139 "data_size": 261888 11140 } 11141 ] 11142 }, 11143 { 11144 "name": "RaidBdev1", 11145 "uuid": "f7cb71ed-2d0e-4240-979e-27b0b7735f36", 11146 "strip_size_kb": 128, 11147 "state": "configuring", 11148 "raid_level": "raid0", 11149 "num_base_bdevs": 2, 11150 "num_base_bdevs_discovered": 1, 11151 "num_base_bdevs_operational": 2, 11152 "base_bdevs_list": [ 11153 { 11154 "name": "malloc2", 11155 "uuid": "f60c20e1-3439-4f89-ae55-965a70333f86", 11156 "is_configured": true, 11157 "data_offset": 256, 11158 "data_size": 261888 11159 } 11160 { 11161 "name": "malloc3", 11162 "uuid": "00000000-0000-0000-0000-000000000000", 11163 "is_configured": false, 11164 "data_offset": 0, 11165 "data_size": 0 11166 } 11167 ] 11168 } 11169 ] 11170} 11171~~~ 11172 11173### bdev_raid_create {#rpc_bdev_raid_create} 11174 11175Constructs new RAID bdev. 11176 11177#### Parameters 11178 11179Name | Optional | Type | Description 11180----------------------- | -------- | ----------- | ----------- 11181name | Required | string | RAID bdev name 11182strip_size_kb | Required | number | Strip size in KB 11183raid_level | Required | string | RAID level 11184base_bdevs | Required | string | Base bdevs name, whitespace separated list in quotes 11185uuid | Optional | string | UUID for this RAID bdev 11186superblock | Optional | boolean | If set, information about raid bdev will be stored in superblock on each base bdev (default: `false`) 11187 11188#### Example 11189 11190Example request: 11191 11192~~~json 11193{ 11194 "jsonrpc": "2.0", 11195 "method": "bdev_raid_create", 11196 "id": 1, 11197 "params": { 11198 "name": "Raid0", 11199 "raid_level": "0", 11200 "base_bdevs": [ 11201 "Malloc0", 11202 "Malloc1", 11203 "Malloc2", 11204 "Malloc3" 11205 ], 11206 "strip_size_kb": 4 11207 } 11208} 11209~~~ 11210 11211Example response: 11212 11213~~~json 11214{ 11215 "jsonrpc": "2.0", 11216 "id": 1, 11217 "result": true 11218} 11219~~~ 11220 11221### bdev_raid_delete {#rpc_bdev_raid_delete} 11222 11223Removes RAID bdev. 11224 11225#### Parameters 11226 11227Name | Optional | Type | Description 11228----------------------- | -------- | ----------- | ----------- 11229name | Required | string | RAID bdev name 11230 11231#### Example 11232 11233Example request: 11234 11235~~~json 11236{ 11237 "jsonrpc": "2.0", 11238 "method": "bdev_raid_delete", 11239 "id": 1, 11240 "params": { 11241 "name": "Raid0" 11242 } 11243} 11244~~~ 11245 11246Example response: 11247 11248~~~json 11249{ 11250 "jsonrpc": "2.0", 11251 "id": 1, 11252 "result": true 11253} 11254~~~ 11255 11256### bdev_raid_add_base_bdev {#rpc_bdev_raid_add_base_bdev} 11257 11258Add base bdev to existing raid bdev. The raid bdev must have an empty base bdev slot. 11259The bdev must be large enough and have the same block size and metadata format as the other base bdevs. 11260 11261#### Parameters 11262 11263Name | Optional | Type | Description 11264----------------------- | -------- | ----------- | ----------- 11265raid_bdev | Required | string | Raid bdev name 11266base_bdev | Required | string | Base bdev name 11267 11268#### Example 11269 11270Example request: 11271 11272~~~json 11273{ 11274 "jsonrpc": "2.0", 11275 "method": "bdev_raid_add_base_bdev", 11276 "id": 1, 11277 "params": { 11278 "raid_bdev": "RaidBdev0", 11279 "base_bdev": "Nvme0n1" 11280 } 11281} 11282~~~ 11283 11284Example response: 11285 11286~~~json 11287{ 11288 "jsonrpc": "2.0", 11289 "id": 1, 11290 "result": true 11291} 11292~~~ 11293### bdev_raid_remove_base_bdev {#rpc_bdev_raid_remove_base_bdev} 11294 11295Remove base bdev from existing raid bdev. 11296 11297#### Parameters 11298 11299Name | Optional | Type | Description 11300----------------------- | -------- | ----------- | ----------- 11301name | Required | string | Base bdev name in RAID 11302 11303#### Example 11304 11305Example request: 11306 11307~~~json 11308{ 11309 "jsonrpc": "2.0", 11310 "method": "bdev_raid_remove_base_bdev", 11311 "id": 1, 11312 "params": { 11313 "name": "Raid0" 11314 } 11315} 11316~~~ 11317 11318Example response: 11319 11320~~~json 11321{ 11322 "jsonrpc": "2.0", 11323 "id": 1, 11324 "result": true 11325} 11326~~~ 11327 11328## SPLIT 11329 11330### bdev_split_create {#rpc_bdev_split_create} 11331 11332This is used to split an underlying block device and create several smaller equal-sized vbdevs. 11333 11334#### Parameters 11335 11336Name | Optional | Type | Description 11337----------------------- | -------- | ----------- | ----------- 11338base_bdev | Required | string | base bdev name 11339split_count | Required | number | number of splits 11340split_size_mb | Optional | number | size in MB to restrict the size 11341 11342#### Example 11343 11344Example request: 11345 11346~~~json 11347{ 11348 "jsonrpc": "2.0", 11349 "method": "bdev_split_create", 11350 "id": 1, 11351 "params": { 11352 "base_bdev": "Malloc0", 11353 "split_count": 4 11354 } 11355} 11356~~~ 11357 11358Example response: 11359 11360~~~json 11361{ 11362 "jsonrpc": "2.0", 11363 "id": 1, 11364 "result": [ 11365 "Malloc0p0", 11366 "Malloc0p1", 11367 "Malloc0p2", 11368 "Malloc0p3" 11369 ] 11370} 11371~~~ 11372 11373### bdev_split_delete {#rpc_bdev_split_delete} 11374 11375This is used to remove the split vbdevs. 11376 11377#### Parameters 11378 11379Name | Optional | Type | Description 11380----------------------- | -------- | ----------- | ----------- 11381base_bdev | Required | string | base bdev name 11382 11383#### Example 11384 11385Example request: 11386 11387~~~json 11388{ 11389 "jsonrpc": "2.0", 11390 "method": "bdev_split_delete", 11391 "id": 1, 11392 "params": { 11393 "base_bdev": "Malloc0" 11394 } 11395} 11396~~~ 11397 11398Example response: 11399 11400~~~json 11401{ 11402 "jsonrpc": "2.0", 11403 "id": 1, 11404 "result": true 11405} 11406~~~ 11407 11408## Uring 11409 11410### bdev_uring_create {#rpc_bdev_uring_create} 11411 11412Create a bdev with io_uring backend. 11413 11414#### Parameters 11415 11416Name | Optional | Type | Description 11417----------------------- | -------- | ----------- | ----------- 11418filename | Required | string | path to device or file (ex: /dev/nvme0n1) 11419name | Required | string | name of bdev 11420block_size | Optional | number | block size of device (If omitted, get the block size from the file) 11421uuid | Optional | string | UUID of new bdev 11422 11423#### Example 11424 11425Example request: 11426 11427~~~json 11428{ 11429 "jsonrpc": "2.0", 11430 "method": "bdev_uring_create", 11431 "id": 1, 11432 "params": { 11433 "name": "bdev_u0", 11434 "filename": "/dev/nvme0n1", 11435 "block_size": 512 11436 } 11437} 11438~~~ 11439 11440Example response: 11441 11442~~~json 11443{ 11444 "jsonrpc": "2.0", 11445 "id": 1, 11446 "result": "bdev_u0" 11447} 11448~~~ 11449 11450### bdev_uring_rescan {#rpc_bdev_uring_rescan} 11451 11452Rescan the size of a uring bdev. 11453 11454#### Parameters 11455 11456Name | Optional | Type | Description 11457---- | -------- | ------ | ----------- 11458name | Required | string | name of uring bdev to rescan 11459 11460#### Example 11461 11462Example request: 11463 11464~~~json 11465{ 11466 "jsonrpc": "2.0", 11467 "method": "bdev_uring_rescan", 11468 "id": 1, 11469 "params": { 11470 "name": "bdev_u0" 11471 } 11472} 11473~~~ 11474 11475Example response: 11476 11477~~~json 11478{ 11479 "jsonrpc": "2.0", 11480 "id": 1, 11481 "result": true 11482} 11483~~~ 11484 11485### bdev_uring_delete {#rpc_bdev_uring_delete} 11486 11487Remove a uring bdev. 11488 11489#### Parameters 11490 11491Name | Optional | Type | Description 11492----------------------- | -------- | ----------- | ----------- 11493name | Required | string | name of uring bdev to delete 11494 11495#### Example 11496 11497Example request: 11498 11499~~~json 11500{ 11501 "jsonrpc": "2.0", 11502 "method": "bdev_uring_delete", 11503 "id": 1, 11504 "params": { 11505 "name": "bdev_u0" 11506 } 11507} 11508~~~ 11509 11510Example response: 11511 11512~~~json 11513{ 11514 "jsonrpc": "2.0", 11515 "id": 1, 11516 "result": true 11517} 11518~~~ 11519 11520## OPAL 11521 11522### bdev_nvme_opal_init {#rpc_bdev_nvme_opal_init} 11523 11524This is used to initialize OPAL of a given NVMe ctrlr, including taking ownership and activating. 11525 11526#### Parameters 11527 11528Name | Optional | Type | Description 11529----------------------- | -------- | ----------- | ----------- 11530nvme_ctrlr_name | Required | string | name of nvme ctrlr 11531password | Required | string | admin password of OPAL 11532 11533#### Example 11534 11535Example request: 11536 11537~~~json 11538{ 11539 "jsonrpc": "2.0", 11540 "method": "bdev_nvme_opal_init", 11541 "id": 1, 11542 "params": { 11543 "nvme_ctrlr_name": "nvme0", 11544 "password": "*****" 11545 } 11546} 11547~~~ 11548 11549Example response: 11550 11551~~~json 11552{ 11553 "jsonrpc": "2.0", 11554 "id": 1, 11555 "result": true 11556} 11557~~~ 11558 11559### bdev_nvme_opal_revert {#rpc_bdev_nvme_opal_revert} 11560 11561This is used to revert OPAL to its factory settings. Erase all user configuration and data. 11562 11563#### Parameters 11564 11565Name | Optional | Type | Description 11566----------------------- | -------- | ----------- | ----------- 11567nvme_ctrlr_name | Required | string | name of nvme ctrlr 11568password | Required | string | admin password of OPAL 11569 11570#### Example 11571 11572Example request: 11573 11574~~~json 11575{ 11576 "jsonrpc": "2.0", 11577 "method": "bdev_nvme_opal_revert", 11578 "id": 1, 11579 "params": { 11580 "nvme_ctrlr_name": "nvme0", 11581 "password": "*****" 11582 } 11583} 11584~~~ 11585 11586Example response: 11587 11588~~~json 11589{ 11590 "jsonrpc": "2.0", 11591 "id": 1, 11592 "result": true 11593} 11594~~~ 11595 11596### bdev_opal_create {#rpc_bdev_opal_create} 11597 11598This is used to create an OPAL virtual bdev. 11599 11600#### Parameters 11601 11602Name | Optional | Type | Description 11603----------------------- | -------- | ----------- | ----------- 11604nvme_ctrlr_name | Required | string | name of nvme ctrlr that supports OPAL 11605nsid | Required | number | namespace ID 11606locking_range_id | Required | number | OPAL locking range ID 11607range_start | Required | number | locking range start LBA 11608range_length | Required | number | locking range length 11609password | Required | string | admin password of OPAL 11610 11611#### Response 11612 11613The response is the name of created OPAL virtual bdev. 11614 11615#### Example 11616 11617Example request: 11618 11619~~~json 11620{ 11621 "jsonrpc": "2.0", 11622 "method": "bdev_opal_create", 11623 "id": 1, 11624 "params": { 11625 "nvme_ctrlr_name": "nvme0", 11626 "nsid": 1, 11627 "locking_range_id": 1, 11628 "range_start": 0, 11629 "range_length": 4096, 11630 "password": "*****" 11631 } 11632} 11633~~~ 11634 11635Example response: 11636 11637~~~json 11638{ 11639 "jsonrpc": "2.0", 11640 "id": 1, 11641 "result": "nvme0n1r1" 11642} 11643~~~ 11644 11645### bdev_opal_get_info {#rpc_bdev_opal_get_info} 11646 11647This is used to get information of a given OPAL bdev. 11648 11649#### Parameters 11650 11651Name | Optional | Type | Description 11652----------------------- | -------- | ----------- | ----------- 11653bdev_name | Required | string | name of OPAL vbdev 11654password | Required | string | admin password 11655 11656#### Response 11657 11658The response is the locking info of OPAL virtual bdev. 11659 11660#### Example 11661 11662Example request: 11663 11664~~~json 11665{ 11666 "jsonrpc": "2.0", 11667 "method": "bdev_opal_get_info", 11668 "id": 1, 11669 "params": { 11670 "bdev_name": "nvme0n1r1", 11671 "password": "*****" 11672 } 11673} 11674~~~ 11675 11676Example response: 11677 11678~~~json 11679{ 11680 "jsonrpc": "2.0", 11681 "id": 1, 11682 "result": { 11683 "name": "nvme0n1r1", 11684 "range_start": 0, 11685 "range_length": 4096, 11686 "read_lock_enabled": true, 11687 "write_lock_enabled": true, 11688 "read_locked": false, 11689 "write_locked": false 11690 } 11691} 11692~~~ 11693 11694### bdev_opal_delete {#rpc_bdev_opal_delete} 11695 11696This is used to delete OPAL vbdev. 11697 11698#### Parameters 11699 11700Name | Optional | Type | Description 11701----------------------- | -------- | ----------- | ----------- 11702bdev_name | Required | string | name of OPAL vbdev 11703password | Required | string | admin password 11704 11705#### Example 11706 11707Example request: 11708 11709~~~json 11710{ 11711 "jsonrpc": "2.0", 11712 "method": "bdev_opal_delete", 11713 "id": 1, 11714 "params": { 11715 "bdev_name": "nvme0n1r1", 11716 "password": "*****" 11717 } 11718} 11719~~~ 11720 11721Example response: 11722 11723~~~json 11724{ 11725 "jsonrpc": "2.0", 11726 "id": 1, 11727 "result": true 11728} 11729~~~ 11730 11731### bdev_opal_new_user {#rpc_bdev_opal_new_user} 11732 11733This enables a new user to the specified opal bdev so that the user can lock/unlock the bdev. 11734Recalling this for the same opal bdev, only the newest user will have the privilege. 11735 11736#### Parameters 11737 11738Name | Optional | Type | Description 11739----------------------- | -------- | ----------- | ----------- 11740bdev_name | Required | string | name of OPAL vbdev 11741admin_password | Required | string | admin password 11742user_id | Required | number | user ID 11743user_password | Required | string | user password 11744 11745#### Example 11746 11747Example request: 11748 11749~~~json 11750{ 11751 "jsonrpc": "2.0", 11752 "method": "bdev_opal_new_user", 11753 "id": 1, 11754 "params": { 11755 "bdev_name": "nvme0n1r1", 11756 "admin_password": "*****", 11757 "user_id": "1", 11758 "user_password": "********" 11759 } 11760} 11761~~~ 11762 11763Example response: 11764 11765~~~json 11766{ 11767 "jsonrpc": "2.0", 11768 "id": 1, 11769 "result": true 11770} 11771~~~ 11772 11773### bdev_opal_set_lock_state {#rpc_bdev_opal_set_lock_state} 11774 11775This is used to lock/unlock specific opal bdev providing user ID and password. 11776 11777#### Parameters 11778 11779Name | Optional | Type | Description 11780----------------------- | -------- | ----------- | ----------- 11781bdev_name | Required | string | name of OPAL vbdev 11782user_id | Required | number | user ID 11783password | Required | string | user password 11784lock_state | Required | string | lock state 11785 11786#### Example 11787 11788Example request: 11789 11790~~~json 11791{ 11792 "jsonrpc": "2.0", 11793 "method": "bdev_opal_set_lock_state", 11794 "id": 1, 11795 "params": { 11796 "bdev_name": "nvme0n1r1", 11797 "user_id": "1", 11798 "user_password": "********", 11799 "lock_state": "rwlock" 11800 } 11801} 11802~~~ 11803 11804Example response: 11805 11806~~~json 11807{ 11808 "jsonrpc": "2.0", 11809 "id": 1, 11810 "result": true 11811} 11812~~~ 11813 11814## Notifications 11815 11816### notify_get_types {#rpc_notify_get_types} 11817 11818Return list of all supported notification types. 11819 11820#### Parameters 11821 11822None 11823 11824#### Response 11825 11826The response is an array of strings - supported RPC notification types. 11827 11828#### Example 11829 11830Example request: 11831 11832~~~json 11833{ 11834 "jsonrpc": "2.0", 11835 "method": "notify_get_types", 11836 "id": 1 11837} 11838~~~ 11839 11840Example response: 11841 11842~~~json 11843{ 11844 "id": 1, 11845 "result": [ 11846 "bdev_register", 11847 "bdev_unregister" 11848 ], 11849 "jsonrpc": "2.0" 11850} 11851~~~ 11852 11853### notify_get_notifications {#notify_get_notifications} 11854 11855Request notifications. Returns array of notifications that happened since the specified id (or first that is available). 11856 11857Notice: Notifications are kept in circular buffer with limited size. Older notifications might be inaccessible 11858due to being overwritten by new ones. 11859 11860#### Parameters 11861 11862Name | Optional | Type | Description 11863----------------------- | -------- | ----------- | ----------- 11864id | Optional | number | First Event ID to fetch (default: first available). 11865max | Optional | number | Maximum number of event to return (default: no limit). 11866 11867#### Response 11868 11869Response is an array of event objects. 11870 11871Name | Optional | Type | Description 11872----------------------- | -------- | ----------- | ----------- 11873id | Optional | number | Event ID. 11874type | Optional | number | Type of the event. 11875ctx | Optional | string | Event context. 11876 11877#### Example 11878 11879Example request: 11880 11881~~~json 11882{ 11883 "id": 1, 11884 "jsonrpc": "2.0", 11885 "method": "notify_get_notifications", 11886 "params": { 11887 "id": 1, 11888 "max": 10 11889 } 11890} 11891 11892~~~ 11893 11894Example response: 11895 11896~~~json 11897{ 11898 "jsonrpc": "2.0", 11899 "id": 1, 11900 "result": [ 11901 { 11902 "ctx": "Malloc0", 11903 "type": "bdev_register", 11904 "id": 1 11905 }, 11906 { 11907 "ctx": "Malloc2", 11908 "type": "bdev_register", 11909 "id": 2 11910 } 11911 ] 11912} 11913~~~ 11914 11915## Linux Userspace Block Device (UBLK) {#jsonrpc_components_ublk} 11916 11917SPDK supports exporting bdevs though Linux ublk. The motivation behind it is to back a Linux kernel block device 11918with an SPDK user space bdev. 11919 11920To export a device over ublk, first make sure the Linux kernel ublk driver is loaded by running 'modprobe ublk_drv'. 11921 11922### ublk_create_target {#rpc_ublk_create_target} 11923 11924Start to create ublk threads and initialize ublk target. It will return an error if user calls this RPC twice without 11925ublk_destroy_target in between. It will use current cpumask in SPDK when user does not specify cpumask option. 11926 11927#### Parameters 11928 11929Name | Optional | Type | Description 11930----------------------- | -------- | ----------- | ----------- 11931cpumask | Optional | string | Cpumask for ublk target 11932disable-user-copy | Optional | boolean | Disable user copy feature 11933 11934#### Response 11935 11936True if ublk target initialization is successful; False if failed. 11937 11938#### Example 11939 11940Example request: 11941 11942~~~json 11943{ 11944 "params": { 11945 "cpumask": "0x2" 11946 }, 11947 "jsonrpc": "2.0", 11948 "method": "ublk_create_target", 11949 "id": 1 11950} 11951~~~ 11952 11953Example response: 11954 11955~~~json 11956{ 11957 "jsonrpc": "2.0", 11958 "id": 1, 11959 "result": true 11960} 11961~~~ 11962 11963### ublk_destroy_target {#rpc_ublk_destroy_target} 11964 11965Release all UBLK devices and destroy ublk target. 11966 11967#### Response 11968 11969True if ublk target destruction is successful; False if failed. 11970 11971#### Example 11972 11973Example request: 11974 11975~~~json 11976{ 11977 "jsonrpc": "2.0", 11978 "method": "ublk_destroy_target", 11979 "id": 1 11980} 11981~~~ 11982 11983Example response: 11984 11985~~~json 11986{ 11987 "jsonrpc": "2.0", 11988 "id": 1, 11989 "result": true 11990} 11991~~~ 11992 11993### ublk_start_disk {#rpc_ublk_start_disk} 11994 11995Start to export one SPDK bdev as a UBLK device 11996 11997#### Parameters 11998 11999Name | Optional | Type | Description 12000----------------------- | -------- | ----------- | ----------- 12001bdev_name | Required | string | Bdev name to export 12002ublk_id | Required | int | Device id 12003queue_depth | Optional | int | Device queue depth 12004num_queues | Optional | int | Total number of device queues 12005 12006#### Response 12007 12008UBLK device ID 12009 12010#### Example 12011 12012Example request: 12013 12014~~~json 12015{ 12016 "params": { 12017 "ublk_id": "1", 12018 "bdev_name": "Malloc1" 12019 }, 12020 "jsonrpc": "2.0", 12021 "method": "ublk_start_disk", 12022 "id": 1 12023} 12024~~~ 12025 12026Example response: 12027 12028~~~json 12029{ 12030 "jsonrpc": "2.0", 12031 "id": 1, 12032 "result": 1 12033} 12034~~~ 12035 12036### ublk_recover_disk {#rpc_ublk_recover_disk} 12037 12038Recover original UBLK device with ID and block device 12039 12040#### Parameters 12041 12042Name | Optional | Type | Description 12043----------------------- | -------- | ----------- | ----------- 12044bdev_name | Required | string | Bdev name to export 12045ublk_id | Required | int | Device id 12046 12047#### Response 12048 12049UBLK device ID 12050 12051#### Example 12052 12053Example request: 12054 12055~~~json 12056{ 12057 "params": { 12058 "ublk_id": "1", 12059 "bdev_name": "Malloc1" 12060 }, 12061 "jsonrpc": "2.0", 12062 "method": "ublk_recover_disk", 12063 "id": 1 12064} 12065~~~ 12066 12067Example response: 12068 12069~~~json 12070{ 12071 "jsonrpc": "2.0", 12072 "id": 1, 12073 "result": 1 12074} 12075~~~ 12076 12077### ublk_stop_disk {#rpc_ublk_stop_disk} 12078 12079Delete a UBLK device 12080 12081#### Parameters 12082 12083Name | Optional | Type | Description 12084----------------------- | -------- | ----------- | ----------- 12085ublk_id | Required | int | Device id to delete 12086 12087#### Response 12088 12089True if UBLK device is deleted successfully; False if failed. 12090 12091#### Example 12092 12093Example request: 12094 12095~~~json 12096{ 12097 "params": { 12098 "ublk_id": "1", 12099 }, 12100 "jsonrpc": "2.0", 12101 "method": "ublk_stop_disk", 12102 "id": 1 12103} 12104~~~ 12105 12106Example response: 12107 12108~~~json 12109{ 12110 "jsonrpc": "2.0", 12111 "id": 1, 12112 "result": true 12113} 12114~~~ 12115 12116### ublk_get_disks {#rpc_ublk_get_disks} 12117 12118Display full or specified ublk device list 12119 12120#### Parameters 12121 12122Name | Optional | Type | Description 12123----------------------- | -------- | ----------- | ----------- 12124ublk_id | Optional | int | ublk device id to display 12125 12126#### Response 12127 12128Display ublk device list 12129 12130#### Example 12131 12132Example request: 12133 12134~~~json 12135{ 12136 "jsonrpc": "2.0", 12137 "method": "ublk_get_disks", 12138 "id": 1 12139} 12140~~~ 12141 12142Example response: 12143 12144~~~json 12145{ 12146 "jsonrpc": "2.0", 12147 "id": 1, 12148 "result": [ 12149 { 12150 "ublk_device": "/dev/ublkb1", 12151 "id": 1, 12152 "queue_depth": 512, 12153 "num_queues": 1, 12154 "bdev_name": "Malloc1" 12155 } 12156 ] 12157} 12158~~~ 12159 12160## Linux Network Block Device (NBD) {#jsonrpc_components_nbd} 12161 12162SPDK supports exporting bdevs through Linux nbd. These devices then appear as standard Linux kernel block devices 12163and can be accessed using standard utilities like fdisk. 12164 12165In order to export a device over nbd, first make sure the Linux kernel nbd driver is loaded by running 'modprobe nbd'. 12166 12167### nbd_start_disk {#rpc_nbd_start_disk} 12168 12169Start to export one SPDK bdev as NBD disk 12170 12171#### Parameters 12172 12173Name | Optional | Type | Description 12174----------------------- | -------- | ----------- | ----------- 12175bdev_name | Required | string | Bdev name to export 12176nbd_device | Optional | string | NBD device name to assign 12177 12178#### Response 12179 12180Path of exported NBD disk 12181 12182#### Example 12183 12184Example request: 12185 12186~~~json 12187{ 12188 "params": { 12189 "nbd_device": "/dev/nbd1", 12190 "bdev_name": "Malloc1" 12191 }, 12192 "jsonrpc": "2.0", 12193 "method": "nbd_start_disk", 12194 "id": 1 12195} 12196~~~ 12197 12198Example response: 12199 12200~~~json 12201{ 12202 "jsonrpc": "2.0", 12203 "id": 1, 12204 "result": "/dev/nbd1" 12205} 12206~~~ 12207 12208### nbd_stop_disk {#rpc_nbd_stop_disk} 12209 12210Stop one NBD disk which is based on SPDK bdev. 12211 12212#### Parameters 12213 12214Name | Optional | Type | Description 12215----------------------- | -------- | ----------- | ----------- 12216nbd_device | Required | string | NBD device name to stop 12217 12218#### Example 12219 12220Example request: 12221 12222~~~json 12223{ 12224 "params": { 12225 "nbd_device": "/dev/nbd1", 12226 }, 12227 "jsonrpc": "2.0", 12228 "method": "nbd_stop_disk", 12229 "id": 1 12230} 12231~~~ 12232 12233Example response: 12234 12235~~~json 12236{ 12237 "jsonrpc": "2.0", 12238 "id": 1, 12239 "result": "true" 12240} 12241~~~ 12242 12243### nbd_get_disks {#rpc_nbd_get_disks} 12244 12245Display all or specified NBD device list 12246 12247#### Parameters 12248 12249Name | Optional | Type | Description 12250----------------------- | -------- | ----------- | ----------- 12251nbd_device | Optional | string | NBD device name to display 12252 12253#### Response 12254 12255The response is an array of exported NBD devices and their corresponding SPDK bdev. 12256 12257#### Example 12258 12259Example request: 12260 12261~~~json 12262{ 12263 "jsonrpc": "2.0", 12264 "method": "nbd_get_disks", 12265 "id": 1 12266} 12267~~~ 12268 12269Example response: 12270 12271~~~json 12272{ 12273 "jsonrpc": "2.0", 12274 "id": 1, 12275 "result": [ 12276 { 12277 "bdev_name": "Malloc0", 12278 "nbd_device": "/dev/nbd0" 12279 }, 12280 { 12281 "bdev_name": "Malloc1", 12282 "nbd_device": "/dev/nbd1" 12283 } 12284 ] 12285} 12286~~~ 12287 12288## Blobfs {#jsonrpc_components_blobfs} 12289 12290### blobfs_detect {#rpc_blobfs_detect} 12291 12292Detect whether a blobfs exists on bdev. 12293 12294#### Parameters 12295 12296Name | Optional | Type | Description 12297----------------------- | -------- | ----------- | ----------- 12298bdev_name | Required | string | Block device name to detect blobfs 12299 12300#### Response 12301 12302True if a blobfs exists on the bdev; False otherwise. 12303 12304#### Example 12305 12306Example request: 12307 12308~~~json 12309{ 12310 "jsonrpc": "2.0", 12311 "id": 1, 12312 "method": "blobfs_detect", 12313 "params": { 12314 "bdev_name": "Malloc0" 12315 } 12316} 12317~~~ 12318 12319Example response: 12320 12321~~~json 12322{ 12323 "jsonrpc": "2.0", 12324 "id": 1, 12325 "result": "true" 12326} 12327~~~ 12328 12329### blobfs_create {#rpc_blobfs_create} 12330 12331Build blobfs on bdev. 12332 12333#### Parameters 12334 12335Name | Optional | Type | Description 12336----------------------- | -------- | ----------- | ----------- 12337bdev_name | Required | string | Block device name to create blobfs 12338cluster_sz | Optional | number | Size of cluster in bytes. Must be multiple of 4KiB page size, default and minimal value is 1M. 12339 12340#### Example 12341 12342Example request: 12343 12344~~~json 12345{ 12346 "jsonrpc": "2.0", 12347 "id": 1, 12348 "method": "blobfs_create", 12349 "params": { 12350 "bdev_name": "Malloc0", 12351 "cluster_sz": 1M 12352 } 12353} 12354~~~ 12355 12356Example response: 12357 12358~~~json 12359{ 12360 "jsonrpc": "2.0", 12361 "id": 1, 12362 "result": "true" 12363} 12364~~~ 12365 12366### blobfs_mount {#rpc_blobfs_mount} 12367 12368Mount a blobfs on bdev to one host path through FUSE 12369 12370#### Parameters 12371 12372Name | Optional | Type | Description 12373----------------------- | -------- | ----------- | ----------- 12374bdev_name | Required | string | Block device name where the blobfs is 12375mountpoint | Required | string | Mountpoint path in host to mount blobfs 12376 12377#### Example 12378 12379Example request: 12380 12381~~~json 12382{ 12383 "jsonrpc": "2.0", 12384 "id": 1, 12385 "method": ""blobfs_mount"", 12386 "params": { 12387 "bdev_name": "Malloc0", 12388 "mountpoint": "/mnt/" 12389 } 12390} 12391~~~ 12392 12393Example response: 12394 12395~~~json 12396{ 12397 "jsonrpc": "2.0", 12398 "id": 1, 12399 "result": "true" 12400} 12401~~~ 12402 12403### blobfs_set_cache_size {#rpc_blobfs_set_cache_size} 12404 12405Set cache pool size for blobfs filesystems. This RPC is only permitted when the cache pool is not already initialized. 12406 12407The cache pool is initialized when the first blobfs filesystem is initialized or loaded. It is freed when the all 12408initialized or loaded filesystems are unloaded. 12409 12410#### Parameters 12411 12412Name | Optional | Type | Description 12413----------------------- | -------- | ----------- | ----------- 12414size_in_mb | Required | number | Cache size in megabytes 12415 12416#### Response 12417 12418True if cache size is set successfully; False if failed to set. 12419 12420#### Example 12421 12422Example request: 12423 12424~~~json 12425{ 12426 "jsonrpc": "2.0", 12427 "id": 1, 12428 "method": "blobfs_set_cache_size", 12429 "params": { 12430 "size_in_mb": 512, 12431 } 12432} 12433~~~ 12434 12435Example response: 12436 12437~~~json 12438{ 12439 "jsonrpc": "2.0", 12440 "id": 1, 12441 "result": true 12442} 12443~~~ 12444 12445## Socket layer {#jsonrpc_components_sock} 12446 12447### sock_impl_get_options {#rpc_sock_impl_get_options} 12448 12449Get parameters for the socket layer implementation. 12450 12451#### Parameters 12452 12453Name | Optional | Type | Description 12454----------------------- | -------- | ----------- | ----------- 12455impl_name | Required | string | Name of socket implementation, e.g. posix 12456 12457#### Response 12458 12459Response is an object with current socket layer options for requested implementation. 12460 12461#### Example 12462 12463Example request: 12464 12465~~~json 12466{ 12467 "jsonrpc": "2.0", 12468 "method": "sock_impl_get_options", 12469 "id": 1, 12470 "params": { 12471 "impl_name": "posix" 12472 } 12473} 12474~~~ 12475 12476Example response: 12477 12478~~~json 12479{ 12480 "jsonrpc": "2.0", 12481 "id": 1, 12482 "result": { 12483 "recv_buf_size": 2097152, 12484 "send_buf_size": 2097152, 12485 "enable_recv_pipe": true, 12486 "enable_quickack": true, 12487 "enable_placement_id": 0, 12488 "enable_zerocopy_send_server": true, 12489 "enable_zerocopy_send_client": false, 12490 "zerocopy_threshold": 0, 12491 "tls_version": 13, 12492 "enable_ktls": false 12493 } 12494} 12495~~~ 12496 12497### sock_impl_set_options {#rpc_sock_impl_set_options} 12498 12499Set parameters for the socket layer implementation. 12500 12501#### Parameters 12502 12503Name | Optional | Type | Description 12504--------------------------- | -------- | ----------- | ----------- 12505impl_name | Required | string | Name of socket implementation, e.g. posix 12506recv_buf_size | Optional | number | Size of socket receive buffer in bytes 12507send_buf_size | Optional | number | Size of socket send buffer in bytes 12508enable_recv_pipe | Optional | boolean | Enable or disable receive pipe 12509enable_quick_ack | Optional | boolean | Enable or disable quick ACK 12510enable_placement_id | Optional | number | Enable or disable placement_id. 0:disable,1:incoming_napi,2:incoming_cpu 12511enable_zerocopy_send_server | Optional | boolean | Enable or disable zero copy on send for server sockets 12512enable_zerocopy_send_client | Optional | boolean | Enable or disable zero copy on send for client sockets 12513zerocopy_threshold | Optional | number | Set zerocopy_threshold in bytes. A consecutive sequence of requests' iovecs 12514-- | -- | -- | that fall below this threshold may be sent without zerocopy flag set 12515tls_version | Optional | number | TLS protocol version, e.g. 13 for v1.3 (only applies when impl_name == ssl) 12516enable_ktls | Optional | boolean | Enable or disable Kernel TLS (only applies when impl_name == ssl) 12517 12518#### Response 12519 12520True if socket layer options were set successfully. 12521 12522#### Example 12523 12524Example request: 12525 12526~~~json 12527{ 12528 "jsonrpc": "2.0", 12529 "method": "sock_impl_set_options", 12530 "id": 1, 12531 "params": { 12532 "impl_name": "posix", 12533 "recv_buf_size": 2097152, 12534 "send_buf_size": 2097152, 12535 "enable_recv_pipe": false, 12536 "enable_quick_ack": false, 12537 "enable_placement_id": 0, 12538 "enable_zerocopy_send_server": true, 12539 "enable_zerocopy_send_client": false, 12540 "zerocopy_threshold": 10240, 12541 "tls_version": 13, 12542 "enable_ktls": false 12543 } 12544} 12545~~~ 12546 12547Example response: 12548 12549~~~json 12550{ 12551 "jsonrpc": "2.0", 12552 "id": 1, 12553 "result": true 12554} 12555~~~ 12556 12557### sock_set_default_impl {#rpc_sock_set_default_impl} 12558 12559Set the default sock implementation. 12560 12561#### Parameters 12562 12563Name | Optional | Type | Description 12564----------------------- | -------- | ----------- | ----------- 12565impl_name | Required | string | Name of socket implementation, e.g. posix 12566 12567#### Response 12568 12569True if the default socket layer configuration was set successfully. 12570 12571#### Example 12572 12573Example request: 12574 12575~~~json 12576{ 12577 "jsonrpc": "2.0", 12578 "method": "sock_set_default_impl", 12579 "id": 1, 12580 "params": { 12581 "impl_name": "posix" 12582 } 12583} 12584~~~ 12585 12586Example response: 12587 12588~~~json 12589{ 12590 "jsonrpc": "2.0", 12591 "id": 1, 12592 "result": true 12593} 12594~~~ 12595 12596### sock_get_default_impl {#rpc_sock_get_default_impl} 12597 12598Get the name of the default sock implementation. 12599 12600#### Parameters 12601 12602This function has no parameters. 12603 12604#### Response 12605 12606The name of the current default socket implementation. 12607 12608#### Example 12609 12610Example request: 12611 12612~~~json 12613{ 12614 "jsonrpc": "2.0", 12615 "method": "sock_get_default_impl", 12616 "id": 1 12617} 12618~~~ 12619 12620Example response: 12621 12622~~~json 12623{ 12624 "jsonrpc": "2.0", 12625 "id": 1, 12626 "result": { 12627 "impl_name": "posix" 12628 } 12629} 12630~~~ 12631 12632## Miscellaneous RPC commands 12633 12634### bdev_nvme_send_cmd {#rpc_bdev_nvme_send_cmd} 12635 12636Send NVMe command directly to NVMe controller or namespace. Parameters and responses encoded by base64 urlsafe need further processing. 12637 12638Notice: bdev_nvme_send_cmd requires user to guarantee the correctness of NVMe command itself, and also optional parameters. 12639Illegal command contents or mismatching buffer size may result in unpredictable behavior. 12640 12641#### Parameters 12642 12643Name | Optional | Type | Description 12644----------------------- | -------- | ----------- | ----------- 12645name | Required | string | Name of the operating NVMe controller 12646cmd_type | Required | string | Type of nvme cmd. Valid values are: admin, io 12647data_direction | Required | string | Direction of data transfer. Valid values are: c2h, h2c 12648cmdbuf | Required | string | NVMe command encoded by base64 urlsafe 12649data | Optional | string | Data transferring to controller from host, encoded by base64 urlsafe 12650metadata | Optional | string | Metadata transferring to controller from host, encoded by base64 urlsafe 12651data_len | Optional | number | Data length required to transfer from controller to host 12652metadata_len | Optional | number | Metadata length required to transfer from controller to host 12653timeout_ms | Optional | number | Command execution timeout value, in milliseconds 12654 12655#### Response 12656 12657Name | Type | Description 12658----------------------- | ----------- | ----------- 12659cpl | string | NVMe completion queue entry, encoded by base64 urlsafe 12660data | string | Data transferred from controller to host, encoded by base64 urlsafe 12661metadata | string | Metadata transferred from controller to host, encoded by base64 urlsafe 12662 12663#### Example 12664 12665Example request: 12666 12667~~~json 12668{ 12669 "jsonrpc": "2.0", 12670 "method": "bdev_nvme_send_cmd", 12671 "id": 1, 12672 "params": { 12673 "name": "Nvme0", 12674 "cmd_type": "admin" 12675 "data_direction": "c2h", 12676 "cmdbuf": "BgAAAAEAAAAAAAAAAAAAAAAAAAAAAAAAsGUs9P5_AAAAAAAAABAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA==", 12677 "data_len": 60, 12678 } 12679} 12680~~~ 12681 12682Example response: 12683 12684~~~json 12685{ 12686 "jsonrpc": "2.0", 12687 "id": 1, 12688 "result": { 12689 "cpl": "AAAAAAAAAAARAAAAWrmwABAA==", 12690 "data": "sIjg6AAAAACwiODoAAAAALCI4OgAAAAAAAYAAREAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA" 12691 } 12692 12693} 12694~~~ 12695 12696### vmd_enable {#rpc_enable_vmd} 12697 12698Enable VMD enumeration. 12699 12700#### Parameters 12701 12702This method has no parameters. 12703 12704#### Response 12705 12706Completion status of enumeration is returned as a boolean. 12707 12708### Example 12709 12710Example request: 12711 12712~~~json 12713{ 12714 "jsonrpc": "2.0", 12715 "method": "vmd_enable", 12716 "id": 1 12717} 12718~~~ 12719 12720Example response: 12721 12722~~~json 12723{ 12724 "jsonrpc": "2.0", 12725 "id": 1, 12726 "result": true 12727} 12728~~~ 12729 12730### vmd_remove_device {#rpc_vmd_remove_device} 12731 12732Remove a device behind a VMD. 12733 12734### Parameters 12735 12736Name | Optional | Type | Description 12737----------------------- | -------- | ----------- | ----------- 12738addr | Required | string | Address of the device to remove. 12739 12740### Example 12741 12742~~~json 12743{ 12744 "jsonrpc": "2.0", 12745 "method": "vmd_remove_device", 12746 "params": { 12747 "addr": "5d0505:01:00.0" 12748 } 12749 "id": 1 12750} 12751~~~ 12752 12753Example response: 12754 12755~~~json 12756{ 12757 "jsonrpc": "2.0", 12758 "id": 1, 12759 "result": true 12760} 12761~~~ 12762 12763### vmd_rescan {#rpc_vmd_rescan} 12764 12765Force a rescan of the devices behind VMD. 12766 12767### Parameters 12768 12769This method has no parameters. 12770 12771#### Response 12772 12773The response is the number of new devices found. 12774 12775### Example 12776 12777~~~json 12778{ 12779 "jsonrpc": "2.0", 12780 "method": "vmd_rescan", 12781 "id": 1 12782} 12783~~~ 12784 12785Example response: 12786 12787~~~json 12788{ 12789 "jsonrpc": "2.0", 12790 "id": 1, 12791 "result": { 12792 "count": 1 12793 } 12794} 12795~~~ 12796 12797### spdk_get_version {#rpc_spdk_get_version} 12798 12799Get the version info of the running SPDK application. 12800 12801#### Parameters 12802 12803This method has no parameters. 12804 12805#### Response 12806 12807The response is the version number including major version number, minor version number, patch level number and suffix string. 12808 12809#### Example 12810 12811Example request: 12812 12813~~~json 12814{ 12815 "jsonrpc": "2.0", 12816 "id": 1, 12817 "method": "spdk_get_version" 12818} 12819~~~ 12820 12821Example response: 12822 12823~~~json 12824{ 12825 "jsonrpc": "2.0", 12826 "id": 1, 12827 "result": { 12828 "version": "19.04-pre", 12829 "fields" : { 12830 "major": 19, 12831 "minor": 4, 12832 "patch": 0, 12833 "suffix": "-pre" 12834 } 12835 } 12836} 12837~~~ 12838 12839### framework_get_pci_devices 12840 12841List PCIe devices attached to an SPDK application and the contents of their config space. 12842 12843#### Parameters 12844 12845This method has no parameters. 12846 12847#### Response 12848 12849The response is an array of attached PCIe devices. 12850 12851#### Example 12852 12853Example request: 12854 12855~~~json 12856{ 12857 "jsonrpc": "2.0", 12858 "id": 1, 12859 "method": "framework_get_pci_devices" 12860} 12861~~~ 12862 12863Example response: 12864Note that the config space buffer was trimmed. 12865 12866~~~json 12867{ 12868 "jsonrpc": "2.0", 12869 "id": 1, 12870 "result": { 12871 [ 12872 { 12873 "address": "0000:00:04.0", 12874 "config_space": "8680455807051000...0000000000000000" 12875 }, 12876 { 12877 "address": "0000:00:03.0", 12878 "config_space": "8680455807051000...0000000000000000" 12879 } 12880 ] 12881 } 12882} 12883~~~ 12884 12885### bdev_nvme_add_error_injection {#rpc_bdev_nvme_add_error_injection} 12886 12887Add a NVMe command error injection for a bdev nvme controller. 12888 12889#### Parameters 12890 12891Name | Optional | Type | Description 12892----------------------- | -------- | ----------- | ----------- 12893name | Required | string | Name of the operating NVMe controller 12894cmd_type | Required | string | Type of NVMe command. Valid values are: admin, io 12895opc | Required | number | Opcode for which the error injection is applied 12896do_not_submit | Optional | boolean | Set to true if request should not be submitted to the controller (default false) 12897timeout_in_us | Optional | number | Wait specified microseconds when do_not_submit is true 12898err_count | Optional | number | Number of matching NVMe commands to inject errors 12899sct | Optional | number | Status code type (default 0) 12900sc | Optional | number | Status code (default 0) 12901 12902#### Response 12903 12904true on success 12905 12906#### Example 12907 12908Example request: 12909 12910~~~json 12911{ 12912 "jsonrpc": "2.0", 12913 "method": "bdev_nvme_add_error_injection", 12914 "id": 1, 12915 "params": { 12916 "name": "HotInNvme0", 12917 "opc": 2, 12918 "cmd_type": "io", 12919 "err_count": 1111111, 12920 "sct": 11, 12921 "sc": 33 12922 } 12923} 12924 12925~~~ 12926 12927Example response: 12928 12929~~~json 12930{ 12931 "jsonrpc": "2.0", 12932 "id": 1, 12933 "result": true 12934} 12935 12936~~~ 12937 12938### bdev_nvme_remove_error_injection {#rpc_bdev_nvme_remove_error_injection} 12939 12940Remove a NVMe command error injection. 12941 12942#### Parameters 12943 12944Name | Optional | Type | Description 12945----------------------- | -------- | ----------- | ----------- 12946name | Required | string | Name of the operating NVMe controller 12947cmd_type | Required | string | Type of NVMe command. Valid values are: admin, io 12948opc | Required | number | Opcode for which the error injection is applied 12949 12950#### Response 12951 12952true on success 12953 12954#### Example 12955 12956Example request: 12957 12958~~~json 12959{ 12960 "jsonrpc": "2.0", 12961 "method": "bdev_nvme_remove_error_injection", 12962 "id": 1, 12963 "params": { 12964 "name": "HotInNvme0", 12965 "opc": 2, 12966 "cmd_type": "io" 12967 } 12968} 12969 12970 12971~~~ 12972 12973Example response: 12974 12975~~~json 12976{ 12977 "jsonrpc": "2.0", 12978 "id": 1, 12979 "result": true 12980} 12981 12982~~~ 12983 12984### bdev_daos_create {#rpc_bdev_daos_create} 12985 12986Construct @ref bdev_config_daos 12987 12988#### Parameters 12989 12990Name | Optional | Type | Description 12991----------------------- | -------- | ----------- | ----------- 12992name | Required | string | Bdev name to use 12993pool | Required | string | DAOS pool label or its uuid 12994cont | Required | string | DAOS cont label or its uuid 12995block_size | Required | number | Block size in bytes -must be multiple of 512 12996num_blocks | Required | number | Number of blocks 12997uuid | Optional | string | UUID of new bdev 12998oclass | Optional | string | DAOS object class (default SX) 12999 13000To find more about various object classes please visit [DAOS documentation](https://github.com/daos-stack/daos/blob/master/src/object/README.md). 13001Please note, that DAOS bdev module uses the same CLI flag notation as `dmg` and `daos` commands, 13002for instance, `SX` or `EC_4P2G2` rather than in DAOS header file `OC_SX` or `OC_EC_4P2G2`. 13003 13004#### Result 13005 13006Name of newly created bdev. 13007 13008#### Example 13009 13010Example request: 13011 13012~~~json 13013{ 13014 "params": { 13015 "block_size": 4096, 13016 "num_blocks": 16384, 13017 "name": "daosdev0", 13018 "pool": "test-pool", 13019 "cont": "test-cont", 13020 "oclass": "EC_4P2G2" 13021 }, 13022 "jsonrpc": "2.0", 13023 "method": "bdev_daos_create", 13024 "id": 1 13025} 13026~~~ 13027 13028Example response: 13029 13030~~~json 13031{ 13032 "jsonrpc": "2.0", 13033 "id": 1, 13034 "result": "daosdev0" 13035} 13036~~~ 13037 13038### bdev_daos_delete {#rpc_bdev_daos_delete} 13039 13040Delete @ref bdev_config_daos 13041 13042#### Parameters 13043 13044Name | Optional | Type | Description 13045----------------------- | -------- | ----------- | ----------- 13046name | Required | string | Bdev name 13047 13048#### Example 13049 13050Example request: 13051 13052~~~json 13053{ 13054 "params": { 13055 "name": "daosdev0" 13056 }, 13057 "jsonrpc": "2.0", 13058 "method": "bdev_daos_delete", 13059 "id": 1 13060} 13061~~~ 13062 13063Example response: 13064 13065~~~json 13066{ 13067 "jsonrpc": "2.0", 13068 "id": 1, 13069 "result": true 13070} 13071~~~ 13072 13073### bdev_daos_resize {#rpc_bdev_daos_resize} 13074 13075Resize @ref bdev_config_daos. 13076 13077#### Parameters 13078 13079Name | Optional | Type | Description 13080----------------------- | -------- | ----------- | ----------- 13081name | Required | string | Bdev name 13082new_size | Required | number | Bdev new capacity in MiB 13083 13084#### Example 13085 13086Example request: 13087 13088~~~json 13089{ 13090 "params": { 13091 "name": "daosdev0", 13092 "new_size": 8192 13093 }, 13094 "jsonrpc": "2.0", 13095 "method": "bdev_daos_resize", 13096 "id": 1 13097} 13098~~~ 13099 13100Example response: 13101 13102~~~json 13103{ 13104 "jsonrpc": "2.0", 13105 "id": 1, 13106 "result": true 13107} 13108~~~ 13109 13110### iobuf_set_options {#rpc_iobuf_set_options} 13111 13112Set iobuf buffer pool options. 13113 13114#### Parameters 13115 13116Name | Optional | Type | Description 13117----------------------- | -------- | ----------- | ----------- 13118small_pool_count | Optional | number | Number of small buffers in the global pool 13119large_pool_count | Optional | number | Number of large buffers in the global pool 13120small_bufsize | Optional | number | Size of a small buffer 13121large_bufsize | Optional | number | Size of a small buffer 13122 13123#### Example 13124 13125Example request: 13126 13127~~~json 13128{ 13129 "jsonrpc": "2.0", 13130 "id": 1, 13131 "method": "iobuf_set_options", 13132 "params": { 13133 "small_pool_count": 16383, 13134 "large_pool_count": 2047 13135 } 13136} 13137~~~ 13138 13139Example response: 13140 13141~~~json 13142{ 13143 "jsonrpc": "2.0", 13144 "id": 1, 13145 "result": true 13146} 13147~~~ 13148 13149### iobuf_get_stats {#rpc_iobuf_get_stats} 13150 13151Retrieve iobuf's statistics. 13152 13153#### Parameters 13154 13155None. 13156 13157#### Example 13158 13159Example request: 13160 13161~~~json 13162{ 13163 "jsonrpc": "2.0", 13164 "method": "iobuf_get_stats", 13165 "id": 1 13166} 13167~~~ 13168 13169Example response: 13170 13171~~~json 13172{ 13173 "jsonrpc": "2.0", 13174 "id": 1, 13175 "result": [ 13176 { 13177 "module": "accel", 13178 "small_pool": { 13179 "cache": 0, 13180 "main": 0, 13181 "retry": 0 13182 }, 13183 "large_pool": { 13184 "cache": 0, 13185 "main": 0, 13186 "retry": 0 13187 } 13188 }, 13189 { 13190 "module": "bdev", 13191 "small_pool": { 13192 "cache": 421965, 13193 "main": 1218, 13194 "retry": 0 13195 }, 13196 "large_pool": { 13197 "cache": 0, 13198 "main": 0, 13199 "retry": 0 13200 } 13201 }, 13202 { 13203 "module": "nvmf_TCP", 13204 "small_pool": { 13205 "cache": 7, 13206 "main": 0, 13207 "retry": 0 13208 }, 13209 "large_pool": { 13210 "cache": 0, 13211 "main": 0, 13212 "retry": 0 13213 } 13214 } 13215 ] 13216} 13217~~~ 13218 13219### bdev_nvme_start_mdns_discovery {#rpc_bdev_nvme_start_mdns_discovery} 13220 13221Starts an mDNS based discovery service for the specified service type for the 13222auto-discovery of discovery controllers (NVMe TP-8009). 13223 13224The discovery service will listen for the mDNS discovery events from the 13225Avahi-daemon and will connect to the newly learnt discovery controllers. 13226Then the discovery service will automatically attach to any subsystem found in the 13227discovery log page from the discovery controllers learnt using mDNS. 13228When determining a controller name to use when attaching, it will use 13229the 'name' parameter as a prefix, followed by a unique integer assigned for each of the 13230discovery controllers learnt through mDNS, followed by a unique integer for that discovery 13231service. If the discovery service identifies a subsystem that has been previously 13232attached but is listed with a different path, it will use the same controller name 13233as the previous entry, and connect as a multipath. 13234 13235When the discovery service sees that a subsystem entry has been removed 13236from the log page, it will automatically detach from that controller as well. 13237 13238The 'name' is also used to later stop the discovery service. 13239 13240#### Parameters 13241 13242Name | Optional | Type | Description 13243-------------------------- | -------- | ----------- | ----------- 13244name | Required | string | Prefix for NVMe discovery services found 13245svcname | Required | string | Service to discover: e.g. _nvme-disc._tcp 13246hostnqn | Optional | string | NVMe-oF hostnqn 13247 13248#### Example 13249 13250Example request: 13251 13252~~~json 13253{ 13254 "jsonrpc": "2.0", 13255 "method": "bdev_nvme_start_mdns_discovery", 13256 "id": 1, 13257 "params": { 13258 "name": "cdc_auto", 13259 "svcname": "_nvme-disc._tcp", 13260 "hostnqn": "nqn.2021-12.io.spdk:host1", 13261 } 13262} 13263~~~ 13264 13265Example response: 13266 13267~~~json 13268{ 13269 "jsonrpc": "2.0", 13270 "id": 1, 13271 "result": true 13272} 13273~~~ 13274 13275### bdev_nvme_stop_mdns_discovery {#rpc_bdev_nvme_stop_mdns_discovery} 13276 13277Stops a mDNS discovery service. This includes detaching any controllers that were 13278discovered via the service that is being stopped. 13279 13280#### Parameters 13281 13282Name | Optional | Type | Description 13283-------------------------- | -------- | ----------- | ----------- 13284name | Required | string | Name of mDNS discovery instance to stop 13285 13286#### Example 13287 13288Example request: 13289 13290~~~json 13291{ 13292 "jsonrpc": "2.0", 13293 "method": "bdev_nvme_stop_mdns_discovery", 13294 "id": 1, 13295 "params": { 13296 "name": "cdc_auto" 13297 } 13298} 13299~~~ 13300 13301Example response: 13302 13303~~~json 13304{ 13305 "jsonrpc": "2.0", 13306 "id": 1, 13307 "result": true 13308} 13309~~~ 13310 13311### bdev_nvme_get_mdns_discovery_info {#rpc_bdev_nvme_get_mdns_discovery_info} 13312 13313Get the information about the mDNS discovery service instances. 13314 13315#### Example 13316 13317Example request: 13318~~~json 13319{ 13320 "jsonrpc": "2.0", 13321 "method": "bdev_nvme_get_mdns_discovery_info", 13322 "id": 1 13323} 13324~~~ 13325 13326Example response: 13327 13328~~~json 13329[ 13330 { 13331 "name": "cdc_auto", 13332 "svcname": "_nvme-disc._tcp", 13333 "referrals": [ 13334 { 13335 "name": "cdc_auto0", 13336 "trid": { 13337 "trtype": "TCP", 13338 "adrfam": "IPv4", 13339 "traddr": "66.1.2.21", 13340 "trsvcid": "8009", 13341 "subnqn": "nqn.2014-08.org.nvmexpress.discovery" 13342 } 13343 }, 13344 { 13345 "name": "cdc_auto1", 13346 "trid": { 13347 "trtype": "TCP", 13348 "adrfam": "IPv4", 13349 "traddr": "66.1.1.21", 13350 "trsvcid": "8009", 13351 "subnqn": "nqn.2014-08.org.nvmexpress.discovery" 13352 } 13353 } 13354 ] 13355 } 13356] 13357~~~ 13358 13359### keyring_file_add_key {#rpc_keyring_file_add_key} 13360 13361Add a file-based key to a keyring. 13362 13363#### Parameters 13364 13365Name | Optional | Type | Description 13366-------------------------- | -------- | ----------- | ----------- 13367name | Required | string | Name of the key to add. 13368path | Required | string | Path to a file containing the key. 13369 13370#### Example 13371 13372Example request: 13373 13374~~~json 13375{ 13376 "jsonrpc": "2.0", 13377 "method": "keyring_file_add_key", 13378 "id": 1 13379 "params": { 13380 "name": "key0", 13381 "path": "/path/to/key0" 13382 } 13383} 13384~~~ 13385 13386Example response: 13387 13388~~~json 13389{ 13390 "jsonrpc": "2.0", 13391 "id": 1, 13392 "result": true 13393} 13394~~~ 13395 13396### keyring_file_remove_key {#rpc_keyring_file_remove_key} 13397 13398Remove a file-based key from a keyring. 13399 13400#### Parameters 13401 13402Name | Optional | Type | Description 13403-------------------------- | -------- | ----------- | ----------- 13404name | Required | string | Name of the key to remove. 13405 13406#### Example 13407 13408Example request: 13409 13410~~~json 13411{ 13412 "jsonrpc": "2.0", 13413 "method": "keyring_file_remove_key", 13414 "id": 1 13415 "params": { 13416 "name": "key0" 13417 } 13418} 13419~~~ 13420 13421Example response: 13422 13423~~~json 13424{ 13425 "jsonrpc": "2.0", 13426 "id": 1, 13427 "result": true 13428} 13429~~~ 13430 13431### keyring_get_keys {#rpc_keyring_get_keys} 13432 13433Get a list of available keys. This RPC will only list keys that are currently attached to a 13434keyring. Dynamically loaded keys (via the `probe_key()` callback) will only be included if they're 13435currently in-use (i.e. with active references obtained via `spdk_keyring_get_key()`). 13436 13437#### Example 13438 13439Example request: 13440~~~json 13441{ 13442 "jsonrpc": "2.0", 13443 "method": "keyring_get_keys", 13444 "id": 1 13445} 13446~~~ 13447 13448Example response: 13449 13450~~~json 13451{ 13452 "jsonrpc": "2.0", 13453 "id": 1, 13454 "result": [ 13455 { 13456 "name": "key0", 13457 "module": "keyring_file", 13458 "removed": false, 13459 "probed": false, 13460 "refcnt": 1, 13461 "path": "/path/to/key0" 13462 }, 13463 { 13464 "name": "key1", 13465 "module": "keyring_file", 13466 "removed": false, 13467 "probed": false, 13468 "refcnt": 1, 13469 "path": "/path/to/key1" 13470 } 13471 ] 13472} 13473~~~ 13474 13475### keyring_linux_set_options {#keyring_linux_set_options} 13476 13477Set options of the keyring_linux module. 13478 13479#### Parameters 13480 13481Name | Optional | Type | Description 13482----------------------- | -------- | ----------- | ----------- 13483enable | Optional | boolean | Enable the module. 13484 13485#### Example 13486 13487Example request: 13488~~~json 13489{ 13490 "jsonrpc": "2.0", 13491 "method": "keyring_linux_set_options", 13492 "id": 1 13493 "params": { 13494 "enable": true 13495 } 13496} 13497~~~ 13498 13499Example response: 13500 13501~~~json 13502{ 13503 "jsonrpc": "2.0", 13504 "id": 1, 13505 "result": true 13506} 13507~~~ 13508 13509### nvmf_publish_mdns_prr {#rpc_nvmf_publish_mdns_prr} 13510 13511This interface is used to publish an NVMf target's service location using mDNS 13512(Multicast DNS) protocol. It allows clients to discover the NVMf target using 13513the published service location. 13514 13515#### Parameters 13516 13517Name | Optional | Type | Description 13518-------------------------- | -------- | ----------- | ----------- 13519tgt_name | Optional | string | Parent NVMe-oF target name. 13520 13521#### Example 13522 13523Example request: 13524 13525~~~json 13526{ 13527 "jsonrpc": "2.0", 13528 "method": "nvmf_publish_mdns_prr", 13529 "id": 1, 13530} 13531~~~ 13532 13533Example response: 13534 13535~~~json 13536{ 13537 "jsonrpc": "2.0", 13538 "id": 1, 13539 "result": true 13540} 13541~~~ 13542 13543### nvmf_stop_mdns_prr {#rpc_nvmf_stop_mdns_prr} 13544 13545This interface is used to stop publishing the NVMf target's service location 13546using mDNS (Multicast DNS) protocol. It removes the published service location, 13547preventing clients from discovering the NVMf target. 13548 13549#### Parameters 13550 13551Name | Optional | Type | Description 13552-------------------------- | -------- | ----------- | ----------- 13553tgt_name | Optional | string | Parent NVMe-oF target name. 13554 13555#### Example 13556 13557Example request: 13558 13559~~~json 13560{ 13561 "jsonrpc": "2.0", 13562 "method": "nvmf_stop_mdns_prr", 13563 "id": 1 13564} 13565~~~ 13566 13567Example response: 13568 13569~~~json 13570{ 13571 "jsonrpc": "2.0", 13572 "id": 1, 13573 "result": true 13574} 13575 13576### fsdev_get_opts {#fsdev_get_opts} 13577 13578Get fsdev module options. 13579 13580#### Parameters 13581 13582None 13583 13584#### Example 13585 13586Example request: 13587~~~json 13588{ 13589 "jsonrpc": "2.0", 13590 "method": "fsdev_get_opts", 13591 "id": 1 13592} 13593~~~ 13594 13595Example response: 13596 13597~~~json 13598{ 13599 "jsonrpc": "2.0", 13600 "id": 1, 13601 "result": { 13602 "fsdev_io_pool_size": 65535, 13603 "fsdev_io_cache_size": 256 13604 } 13605} 13606~~~ 13607 13608### fsdev_set_opts {#fsdev_set_opts} 13609 13610Set fsdev module options. 13611 13612#### Parameters 13613 13614Name | Optional | Type | Description 13615----------------------- | -------- | ----------- | ----------- 13616fsdev_io_pool_size | Required | int | Size of fsdev IO objects pool. 13617fsdev_io_cache_size | Required | int | Size of fsdev IO objects cache per thread. 13618 13619#### Example 13620 13621Example request: 13622~~~json 13623{ 13624 "jsonrpc": "2.0", 13625 "method": "fsdev_get_opts", 13626 "id": 1, 13627 "params": { 13628 "fsdev_io_pool_size": 65535, 13629 "fsdev_io_cache_size": 256 13630 } 13631} 13632~~~ 13633 13634Example response: 13635 13636~~~json 13637{ 13638 "jsonrpc": "2.0", 13639 "id": 1, 13640 "result": { 13641 "fsdev_io_pool_size": 65535, 13642 "fsdev_io_cache_size": 256 13643 } 13644} 13645~~~ 13646 13647### fsdev_aio_create {#fsdev_aio_create} 13648 13649Create an AIO fsdev. 13650 13651#### Parameters 13652 13653Name | Optional | Type | Description 13654----------------------- | -------- | ----------- | ----------- 13655name | Required | string | Name of the AIO fsdev to create. 13656root_path | Required | string | Path on the system directory to be exposed as an SPDK filesystem 13657enable_xattr | Optional | bool | true to enable the extended attributes, false otherwise 13658enable_writeback_cache | Optional | bool | true to enable the writeback cache, false otherwise 13659max_write | Optional | int | Max write size in bytes 13660 13661#### Example 13662 13663Example request: 13664~~~json 13665{ 13666 "jsonrpc": "2.0", 13667 "method": "fsdev_aio_create", 13668 "id": 8, 13669 "params": { 13670 "name": "aio0", 13671 "root_path": "/tmp/vfio-test", 13672 "enable_xattr": false, 13673 "enable_writeback_cache": true, 13674 "max_write": 65535 13675 } 13676} 13677~~~ 13678 13679Example response: 13680 13681~~~json 13682{ 13683 "jsonrpc": "2.0", 13684 "id": 8, 13685 "result": "aio0" 13686} 13687~~~ 13688 13689### fsdev_aio_delete {#fsdev_aio_delete} 13690 13691Delete an AIO fsdev. 13692 13693#### Parameters 13694 13695Name | Optional | Type | Description 13696----------------------- | -------- | ----------- | ----------- 13697name | Required | string | Name of the AIO fsdev to delete. 13698 13699#### Example 13700 13701Example request: 13702~~~json 13703{ 13704 "jsonrpc": "2.0", 13705 "method": "fsdev_aio_delete", 13706 "id": 1, 13707 "params": { 13708 "name": "aio0" 13709 } 13710} 13711~~~ 13712 13713Example response: 13714 13715~~~json 13716{ 13717 "jsonrpc": "2.0", 13718 "id": 1, 13719 "result": true 13720} 13721~~~ 13722