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