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