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