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