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