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