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### accel_set_driver {#rpc_accel_set_driver} 1908 1909Select platform driver to execute operation chains. Until a driver is selected, all operations are 1910executed through accel modules. 1911 1912#### Parameters 1913 1914Name | Optional | Type | Description 1915----------------------- |----------| ----------- | ----------------- 1916name | Required | string | Name of the platform driver 1917 1918#### Example 1919 1920Example request: 1921 1922~~~json 1923{ 1924 "jsonrpc": "2.0", 1925 "method": "accel_set_driver", 1926 "id": 1 1927 "params": { 1928 "name": "xeon" 1929 } 1930} 1931~~~ 1932 1933Example response: 1934 1935~~~json 1936{ 1937 "jsonrpc": "2.0", 1938 "id": 1, 1939 "result": true 1940} 1941~~~ 1942 1943### compressdev_scan_accel_module {#rpc_compressdev_scan_accel_module} 1944 1945Set config and enable compressdev accel module offload. 1946Select the DPDK polled mode driver (pmd) for the accel compress module, 19470 = auto-select, 1= QAT only, 2 = mlx5_pci only. 1948 1949#### Parameters 1950 1951Name | Optional | Type | Description 1952----------------------- | -------- | ----------- | ----------- 1953pmd | Required | int | pmd selection 1954 1955#### Example 1956 1957Example request: 1958 1959~~~json 1960{ 1961 "params": { 1962 "pmd": 1 1963 }, 1964 "jsonrpc": "2.0", 1965 "method": "compressdev_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### dsa_scan_accel_module {#rpc_dsa_scan_accel_module} 1981 1982Set config and enable dsa accel module offload. 1983This feature is considered as experimental. 1984 1985#### Parameters 1986 1987Name | Optional | Type | Description 1988----------------------- | -------- | ----------- | ----------- 1989config_kernel_mode | Optional | Boolean | If set, will use kernel idxd driver. 1990 1991#### Example 1992 1993Example request: 1994 1995~~~json 1996{ 1997 "params": { 1998 "config_kernel_mode": false 1999 }, 2000 "jsonrpc": "2.0", 2001 "method": "dsa_scan_accel_module", 2002 "id": 1 2003} 2004~~~ 2005 2006Example response: 2007 2008~~~json 2009{ 2010 "jsonrpc": "2.0", 2011 "id": 1, 2012 "result": true 2013} 2014~~~ 2015 2016### iaa_scan_accel_module {#rpc_iaa_scan_accel_module} 2017 2018Enable IAA accel module offload. 2019This feature is considered as experimental. 2020 2021#### Parameters 2022 2023None 2024 2025#### Example 2026 2027Example request: 2028 2029~~~json 2030{ 2031 "jsonrpc": "2.0", 2032 "method": "iaa_scan_accel_module", 2033 "id": 1 2034} 2035~~~ 2036 2037Example response: 2038 2039~~~json 2040{ 2041 "jsonrpc": "2.0", 2042 "id": 1, 2043 "result": true 2044} 2045~~~ 2046 2047### ioat_scan_accel_module {#rpc_ioat_scan_accel_module} 2048 2049Enable ioat accel module offload. 2050 2051#### Parameters 2052 2053None 2054 2055#### Example 2056 2057Example request: 2058 2059~~~json 2060{ 2061 "jsonrpc": "2.0", 2062 "method": "ioat_scan_accel_module", 2063 "id": 1 2064} 2065~~~ 2066 2067Example response: 2068 2069~~~json 2070{ 2071 "jsonrpc": "2.0", 2072 "id": 1, 2073 "result": true 2074} 2075~~~ 2076 2077### dpdk_cryptodev_scan_accel_module {#rpc_dpdk_cryptodev_scan_accel_module} 2078 2079Enable dpdk_cryptodev accel offload 2080 2081#### Parameters 2082 2083None 2084 2085#### Example 2086 2087Example request: 2088 2089~~~json 2090{ 2091 "jsonrpc": "2.0", 2092 "method": "dpdk_cryptodev_scan_accel_module", 2093 "id": 1 2094} 2095~~~ 2096 2097Example response: 2098 2099~~~json 2100{ 2101 "jsonrpc": "2.0", 2102 "id": 1, 2103 "result": true 2104} 2105~~~ 2106 2107### dpdk_cryptodev_set_driver {#rpc_dpdk_cryptodev_set_driver} 2108 2109Set the DPDK cryptodev driver 2110 2111#### Parameters 2112 2113Name | Optional | Type | Description 2114----------------------- |----------|--------| ----------- 2115crypto_pmd | Required | string | The driver, can be one of crypto_aesni_mb, crypto_qat or mlx5_pci 2116 2117#### Example 2118 2119Example request: 2120 2121~~~json 2122{ 2123 "jsonrpc": "2.0", 2124 "method": "dpdk_cryptodev_set_driver", 2125 "id": 1, 2126 "params": { 2127 "crypto_pmd": "crypto_aesni_mb" 2128 } 2129} 2130~~~ 2131 2132Example response: 2133 2134~~~json 2135{ 2136 "jsonrpc": "2.0", 2137 "id": 1, 2138 "result": true 2139} 2140~~~ 2141 2142### dpdk_cryptodev_get_driver {#rpc_dpdk_cryptodev_get_driver} 2143 2144Get the DPDK cryptodev driver 2145 2146#### Parameters 2147 2148None 2149 2150#### Example 2151 2152Example request: 2153 2154~~~json 2155{ 2156 "jsonrpc": "2.0", 2157 "method": "dpdk_cryptodev_get_driver", 2158 "id": 1 2159} 2160~~~ 2161 2162Example response: 2163 2164~~~json 2165{ 2166 "jsonrpc": "2.0", 2167 "id": 1, 2168 "result": "crypto_aesni_mb" 2169} 2170~~~ 2171 2172### mlx5_scan_accel_module {#rpc_mlx5_scan_accel_module} 2173 2174Enable mlx5 accel offload 2175 2176#### Parameters 2177 2178Name | Optional | Type | Description 2179----------------------- | -------- |--------| ----------- 2180qp_size | Optional | number | qpair size 2181num_requests | Optional | number | Size of the shared requests pool 2182 2183#### Example 2184 2185Example request: 2186 2187~~~json 2188{ 2189 "jsonrpc": "2.0", 2190 "method": "mlx5_scan_accel_module", 2191 "id": 1, 2192 "params": { 2193 "qp_size": 256, 2194 "num_requests": 2047 2195 } 2196} 2197~~~ 2198 2199Example response: 2200 2201~~~json 2202{ 2203 "jsonrpc": "2.0", 2204 "id": 1, 2205 "result": true 2206} 2207~~~ 2208 2209## Block Device Abstraction Layer {#jsonrpc_components_bdev} 2210 2211### bdev_set_options {#rpc_bdev_set_options} 2212 2213Set global parameters for the block device (bdev) subsystem. This RPC may only be called 2214before SPDK subsystems have been initialized. 2215 2216#### Parameters 2217 2218Name | Optional | Type | Description 2219----------------------- | -------- | ----------- | ----------- 2220bdev_io_pool_size | Optional | number | Number of spdk_bdev_io structures in shared buffer pool 2221bdev_io_cache_size | Optional | number | Maximum number of spdk_bdev_io structures cached per thread 2222bdev_auto_examine | Optional | boolean | If set to false, the bdev layer will not examine every disks automatically 2223 2224#### Example 2225 2226Example request: 2227 2228~~~json 2229{ 2230 "jsonrpc": "2.0", 2231 "id": 1, 2232 "method": "bdev_set_options", 2233 "params": { 2234 "bdev_io_pool_size": 65536, 2235 "bdev_io_cache_size": 256 2236 } 2237} 2238~~~ 2239 2240Example response: 2241 2242~~~json 2243{ 2244 "jsonrpc": "2.0", 2245 "id": 1, 2246 "result": true 2247} 2248~~~ 2249 2250### bdev_get_bdevs {#rpc_bdev_get_bdevs} 2251 2252Get information about block devices (bdevs). 2253 2254#### Parameters 2255 2256The user may specify no parameters in order to list all block devices, or a block device may be 2257specified by name. If a timeout is specified, the method will block until a bdev with a specified 2258name appears or the timeout expires. By default, the timeout is zero, meaning the method returns 2259immediately whether the bdev exists or not. 2260 2261Name | Optional | Type | Description 2262----------------------- | -------- | ----------- | ----------- 2263name | Optional | string | Block device name 2264timeout | Optional | number | Time (ms) to wait for a bdev with specified name to appear 2265 2266#### Response 2267 2268The response is an array of objects containing information about the requested block devices. 2269 2270#### Example 2271 2272Example request: 2273 2274~~~json 2275{ 2276 "jsonrpc": "2.0", 2277 "id": 1, 2278 "method": "bdev_get_bdevs", 2279 "params": { 2280 "name": "Malloc0" 2281 } 2282} 2283~~~ 2284 2285Example response: 2286 2287~~~json 2288{ 2289 "jsonrpc": "2.0", 2290 "id": 1, 2291 "result": [ 2292 { 2293 "name": "Malloc0", 2294 "product_name": "Malloc disk", 2295 "block_size": 512, 2296 "num_blocks": 20480, 2297 "claimed": false, 2298 "zoned": false, 2299 "supported_io_types": { 2300 "read": true, 2301 "write": true, 2302 "unmap": true, 2303 "write_zeroes": true, 2304 "flush": true, 2305 "reset": true, 2306 "nvme_admin": false, 2307 "nvme_io": false 2308 }, 2309 "driver_specific": {} 2310 } 2311 ] 2312} 2313~~~ 2314 2315### bdev_examine {#rpc_bdev_examine} 2316 2317Request that the bdev layer examines the given bdev for metadata and creates 2318new bdevs if metadata is found. This is only necessary if `auto_examine` has 2319been set to false using `bdev_set_options`. By default, `auto_examine` is true 2320and bdev examination is automatic. 2321 2322#### Parameters 2323 2324Name | Optional | Type | Description 2325----------------------- | -------- | ----------- | ----------- 2326name | Required | string | Block device name 2327 2328#### Response 2329 2330The response is an array of objects containing I/O statistics of the requested block devices. 2331 2332#### Example 2333 2334Example request: 2335 2336~~~json 2337{ 2338 "jsonrpc": "2.0", 2339 "id": 1, 2340 "method": "bdev_examine", 2341 "params": { 2342 "name": "Nvme0n1" 2343 } 2344} 2345~~~ 2346 2347Example response: 2348 2349~~~json 2350{ 2351 "jsonrpc": "2.0", 2352 "id": 1, 2353 "result": true 2354} 2355~~~ 2356 2357### bdev_wait_for_examine {#rpc_bdev_wait_for_examine} 2358 2359Report when all bdevs have been examined by every bdev module. 2360 2361#### Parameters 2362 2363None 2364 2365#### Response 2366 2367The response is sent when all bdev modules had a chance to examine every bdev. 2368 2369#### Example 2370 2371Example request: 2372 2373~~~json 2374{ 2375 "jsonrpc": "2.0", 2376 "method": "bdev_wait_for_examine", 2377 "id": 1 2378} 2379~~~ 2380 2381Example response: 2382 2383~~~json 2384{ 2385 "jsonrpc": "2.0", 2386 "id": 1, 2387 "result": true 2388} 2389~~~ 2390 2391### bdev_get_iostat {#rpc_bdev_get_iostat} 2392 2393Get I/O statistics of block devices (bdevs). 2394 2395#### Parameters 2396 2397The user may specify no parameters in order to list all block devices, or a block device may be 2398specified by name. 2399 2400Name | Optional | Type | Description 2401----------------------- | -------- | ----------- | ----------- 2402name | Optional | string | Block device name 2403per_channel | Optional | bool | Display per channel data for specified block device. 2404 2405#### Response 2406 2407The response is an array of objects containing I/O statistics of the requested block devices. 2408 2409#### Example 2410 2411Example request: 2412 2413~~~json 2414{ 2415 "jsonrpc": "2.0", 2416 "id": 1, 2417 "method": "bdev_get_iostat", 2418 "params": { 2419 "name": "Nvme0n1", 2420 "per_channel": false 2421 } 2422} 2423~~~ 2424 2425Example response: 2426 2427~~~json 2428{ 2429 "jsonrpc": "2.0", 2430 "id": 1, 2431 "result": { 2432 "tick_rate": 2200000000, 2433 "bdevs" : [ 2434 { 2435 "name": "Nvme0n1", 2436 "bytes_read": 36864, 2437 "num_read_ops": 2, 2438 "bytes_written": 0, 2439 "num_write_ops": 0, 2440 "bytes_unmapped": 0, 2441 "num_unmap_ops": 0, 2442 "read_latency_ticks": 178904, 2443 "write_latency_ticks": 0, 2444 "unmap_latency_ticks": 0, 2445 "queue_depth_polling_period": 2, 2446 "queue_depth": 0, 2447 "io_time": 0, 2448 "weighted_io_time": 0 2449 } 2450 ] 2451 } 2452} 2453~~~ 2454 2455### bdev_reset_iostat {#rpc_bdev_reset_iostat} 2456 2457Reset I/O statistics of block devices (bdevs). Note that if one consumer resets I/O statistics, 2458it affects all other consumers. 2459 2460#### Parameters 2461 2462The user may specify no parameters in order to reset I/O statistics for all block devices, or 2463a block device may be specified by name. 2464 2465Name | Optional | Type | Description 2466----------------------- | -------- | ----------- | ----------- 2467name | Optional | string | Block device name 2468mode | Optional | string | Mode to reset I/O statistics: all, maxmin (default: all) 2469 2470#### Example 2471 2472Example request: 2473 2474~~~json 2475{ 2476 "jsonrpc": "2.0", 2477 "id": 1, 2478 "method": "bdev_reset_iostat", 2479 "params": { 2480 "name": "Nvme0n1" 2481 } 2482} 2483~~~ 2484 2485Example response: 2486 2487~~~json 2488{ 2489 "jsonrpc": "2.0", 2490 "id": 1, 2491 "result": true 2492} 2493~~~ 2494 2495### bdev_enable_histogram {#rpc_bdev_enable_histogram} 2496 2497Control whether collecting data for histogram is enabled for specified bdev. 2498 2499#### Parameters 2500 2501Name | Optional | Type | Description 2502----------------------- | -------- | ----------- | ----------- 2503name | Required | string | Block device name 2504enable | Required | boolean | Enable or disable histogram on specified device 2505 2506#### Example 2507 2508Example request: 2509 2510~~~json 2511{ 2512 "jsonrpc": "2.0", 2513 "id": 1, 2514 "method": "bdev_enable_histogram", 2515 "params": { 2516 "name": "Nvme0n1" 2517 "enable": true 2518 } 2519} 2520~~~ 2521 2522Example response: 2523 2524~~~json 2525{ 2526 "jsonrpc": "2.0", 2527 "id": 1, 2528 "result": true 2529} 2530~~~ 2531 2532### bdev_get_histogram {#rpc_bdev_get_histogram} 2533 2534Get latency histogram for specified bdev. 2535 2536#### Parameters 2537 2538Name | Optional | Type | Description 2539----------------------- | -------- | ----------- | ----------- 2540name | Required | string | Block device name 2541 2542#### Result 2543 2544Name | Description 2545------------------------| ----------- 2546histogram | Base64 encoded histogram 2547bucket_shift | Granularity of the histogram buckets 2548tsc_rate | Ticks per second 2549 2550#### Example 2551 2552Example request: 2553 2554~~~json 2555{ 2556 "jsonrpc": "2.0", 2557 "id": 1, 2558 "method": "bdev_get_histogram", 2559 "params": { 2560 "name": "Nvme0n1" 2561 } 2562} 2563~~~ 2564 2565Example response: 2566Note that histogram field is trimmed, actual encoded histogram length is ~80kb. 2567 2568~~~json 2569{ 2570 "jsonrpc": "2.0", 2571 "id": 1, 2572 "result": { 2573 "histogram": "AAAAAAAAAAAAAA...AAAAAAAAA==", 2574 "tsc_rate": 2300000000, 2575 "bucket_shift": 7 2576 } 2577} 2578~~~ 2579 2580### bdev_set_qos_limit {#rpc_bdev_set_qos_limit} 2581 2582Set the quality of service rate limit on a bdev. 2583 2584#### Parameters 2585 2586Name | Optional | Type | Description 2587----------------------- | -------- | ----------- | ----------- 2588name | Required | string | Block device name 2589rw_ios_per_sec | Optional | number | Number of R/W I/Os per second to allow. 0 means unlimited. 2590rw_mbytes_per_sec | Optional | number | Number of R/W megabytes per second to allow. 0 means unlimited. 2591r_mbytes_per_sec | Optional | number | Number of Read megabytes per second to allow. 0 means unlimited. 2592w_mbytes_per_sec | Optional | number | Number of Write megabytes per second to allow. 0 means unlimited. 2593 2594#### Example 2595 2596Example request: 2597 2598~~~json 2599{ 2600 "jsonrpc": "2.0", 2601 "id": 1, 2602 "method": "bdev_set_qos_limit", 2603 "params": { 2604 "name": "Malloc0" 2605 "rw_ios_per_sec": 20000 2606 "rw_mbytes_per_sec": 100 2607 "r_mbytes_per_sec": 50 2608 "w_mbytes_per_sec": 50 2609 } 2610} 2611~~~ 2612 2613Example response: 2614 2615~~~json 2616{ 2617 "jsonrpc": "2.0", 2618 "id": 1, 2619 "result": true 2620} 2621~~~ 2622 2623### bdev_set_qd_sampling_period {#rpc_bdev_set_qd_sampling_period} 2624 2625Enable queue depth tracking on a specified bdev. 2626 2627#### Parameters 2628 2629Name | Optional | Type | Description 2630----------------------- | -------- | ----------- | ----------- 2631name | Required | string | Block device name 2632period | Required | int | period (in microseconds).If set to 0, polling will be disabled. 2633 2634#### Example 2635 2636Example request: 2637 2638~~~json 2639{ 2640 "jsonrpc": "2.0", 2641 "method": "bdev_set_qd_sampling_period", 2642 "id": 1, 2643 "params": { 2644 "name": "Malloc0", 2645 "period": 20 2646 } 2647} 2648~~~ 2649 2650Example response: 2651 2652~~~json 2653{ 2654 "jsonrpc": "2.0", 2655 "id": 1, 2656 "result": true 2657} 2658~~~ 2659 2660### bdev_compress_create {#rpc_bdev_compress_create} 2661 2662Create a new compress bdev on a given base bdev. 2663 2664#### Parameters 2665 2666Name | Optional | Type | Description 2667----------------------- | -------- | ----------- | ----------- 2668base_bdev_name | Required | string | Name of the base bdev 2669pm_path | Required | string | Path to persistent memory 2670lb_size | Optional | int | Compressed vol logical block size (512 or 4096) 2671 2672#### Result 2673 2674Name of newly created bdev. 2675 2676#### Example 2677 2678Example request: 2679 2680~~~json 2681{ 2682 "params": { 2683 "base_bdev_name": "Nvme0n1", 2684 "pm_path": "/pm_files", 2685 "lb_size": 4096 2686 }, 2687 "jsonrpc": "2.0", 2688 "method": "bdev_compress_create", 2689 "id": 1 2690} 2691~~~ 2692 2693### bdev_compress_delete {#rpc_bdev_compress_delete} 2694 2695Delete a compressed bdev. 2696 2697#### Parameters 2698 2699Name | Optional | Type | Description 2700----------------------- | -------- | ----------- | ----------- 2701name | Required | string | Name of the compress bdev 2702 2703#### Example 2704 2705Example request: 2706 2707~~~json 2708{ 2709 "params": { 2710 "name": "COMP_Nvme0n1" 2711 }, 2712 "jsonrpc": "2.0", 2713 "method": "bdev_compress_delete", 2714 "id": 1 2715} 2716~~~ 2717 2718Example response: 2719 2720~~~json 2721{ 2722 "jsonrpc": "2.0", 2723 "id": 1, 2724 "result": true 2725} 2726~~~ 2727 2728### bdev_compress_get_orphans {#rpc_bdev_compress_get_orphans} 2729 2730Get a list of compressed volumes that are missing their pmem metadata. 2731 2732#### Parameters 2733 2734Name | Optional | Type | Description 2735----------------------- | -------- | ----------- | ----------- 2736name | Required | string | Name of the compress bdev 2737 2738#### Example 2739 2740Example request: 2741 2742~~~json 2743{ 2744 "params": { 2745 "name": "COMP_Nvme0n1" 2746 }, 2747 "jsonrpc": "2.0", 2748 "method": "bdev_compress_get_orphans", 2749 "id": 1 2750} 2751~~~ 2752 2753Example response: 2754 2755~~~json 2756{ 2757 "jsonrpc": "2.0", 2758 "id": 1, 2759 "name": "COMP_Nvme0n1" 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 | Optional | number | Desired size of logical volume in bytes (Deprecated. Please use size_in_mib instead.) 9636size_in_mib | Optional | number | Desired size of logical volume in MiB 9637thin_provision | Optional | boolean | True to enable thin provisioning 9638uuid | Optional | string | UUID of logical volume store to create logical volume on 9639lvs_name | Optional | string | Name of logical volume store to create logical volume on 9640clear_method | Optional | string | Change default data clusters clear method. Available: none, unmap, write_zeroes 9641 9642Size will be rounded up to a multiple of cluster size. Either uuid or lvs_name must be specified, but not both. 9643lvol_name will be used in the alias of the created logical volume. 9644 9645#### Response 9646 9647UUID of the created logical volume is returned. 9648 9649#### Example 9650 9651Example request: 9652 9653~~~json 9654{ 9655 "jsonrpc": "2.0", 9656 "method": "bdev_lvol_create", 9657 "id": 1, 9658 "params": { 9659 "lvol_name": "LVOL0", 9660 "size_in_mib": 1, 9661 "lvs_name": "LVS0", 9662 "clear_method": "unmap", 9663 "thin_provision": true 9664 } 9665} 9666~~~ 9667 9668Example response: 9669 9670~~~json 9671{ 9672 "jsonrpc": "2.0", 9673 "id": 1, 9674 "result": "1b38702c-7f0c-411e-a962-92c6a5a8a602" 9675} 9676~~~ 9677 9678### bdev_lvol_snapshot {#rpc_bdev_lvol_snapshot} 9679 9680Capture a snapshot of the current state of a logical volume. 9681 9682#### Parameters 9683 9684Name | Optional | Type | Description 9685----------------------- | -------- | ----------- | ----------- 9686lvol_name | Required | string | UUID or alias of the logical volume to create a snapshot from 9687snapshot_name | Required | string | Name for the newly created snapshot 9688 9689#### Response 9690 9691UUID of the created logical volume snapshot is returned. 9692 9693#### Example 9694 9695Example request: 9696 9697~~~json 9698{ 9699 "jsonrpc": "2.0", 9700 "method": "bdev_lvol_snapshot", 9701 "id": 1, 9702 "params": { 9703 "lvol_name": "1b38702c-7f0c-411e-a962-92c6a5a8a602", 9704 "snapshot_name": "SNAP1" 9705 } 9706} 9707~~~ 9708 9709Example response: 9710 9711~~~json 9712{ 9713 "jsonrpc": "2.0", 9714 "id": 1, 9715 "result": "cc8d7fdf-7865-4d1f-9fc6-35da8e368670" 9716} 9717~~~ 9718 9719### bdev_lvol_clone {#rpc_bdev_lvol_clone} 9720 9721Create a logical volume based on a snapshot. 9722 9723#### Parameters 9724 9725Name | Optional | Type | Description 9726----------------------- | -------- | ----------- | ----------- 9727snapshot_name | Required | string | UUID or alias of the snapshot to clone 9728clone_name | Required | string | Name for the logical volume to create 9729 9730#### Response 9731 9732UUID of the created logical volume clone is returned. 9733 9734#### Example 9735 9736Example request: 9737 9738~~~json 9739{ 9740 "jsonrpc": "2.0" 9741 "method": "bdev_lvol_clone", 9742 "id": 1, 9743 "params": { 9744 "snapshot_name": "cc8d7fdf-7865-4d1f-9fc6-35da8e368670", 9745 "clone_name": "CLONE1" 9746 } 9747} 9748~~~ 9749 9750Example response: 9751 9752~~~json 9753{ 9754 "jsonrpc": "2.0", 9755 "id": 1, 9756 "result": "8d87fccc-c278-49f0-9d4c-6237951aca09" 9757} 9758~~~ 9759 9760### bdev_lvol_rename {#rpc_bdev_lvol_rename} 9761 9762Rename a logical volume. New name will rename only the alias of the logical volume. 9763 9764#### Parameters 9765 9766Name | Optional | Type | Description 9767----------------------- | -------- | ----------- | ----------- 9768old_name | Required | string | UUID or alias of the existing logical volume 9769new_name | Required | string | New logical volume name 9770 9771#### Example 9772 9773Example request: 9774 9775~~~json 9776{ 9777 "jsonrpc": "2.0", 9778 "method": "bdev_lvol_rename", 9779 "id": 1, 9780 "params": { 9781 "old_name": "067df606-6dbc-4143-a499-0d05855cb3b8", 9782 "new_name": "LVOL2" 9783 } 9784} 9785~~~ 9786 9787Example response: 9788 9789~~~json 9790{ 9791 "jsonrpc": "2.0", 9792 "id": 1, 9793 "result": true 9794} 9795~~~ 9796 9797### bdev_lvol_resize {#rpc_bdev_lvol_resize} 9798 9799Resize a logical volume. 9800 9801#### Parameters 9802 9803Name | Optional | Type | Description 9804----------------------- | -------- | ----------- | ----------- 9805name | Required | string | UUID or alias of the logical volume to resize 9806size | Optional | number | Desired size of the logical volume in bytes (Deprecated. Please use size_in_mib instead.) 9807size_in_mib | Optional | number | Desired size of the logical volume in MiB 9808 9809#### Example 9810 9811Example request: 9812 9813~~~json 9814{ 9815 "jsonrpc": "2.0", 9816 "method": "bdev_lvol_resize", 9817 "id": 1, 9818 "params": { 9819 "name": "51638754-ca16-43a7-9f8f-294a0805ab0a", 9820 "size_in_mib": 2 9821 } 9822} 9823~~~ 9824 9825Example response: 9826 9827~~~json 9828{ 9829 "jsonrpc": "2.0", 9830 "id": 1, 9831 "result": true 9832} 9833~~~ 9834 9835### bdev_lvol_set_read_only{#rpc_bdev_lvol_set_read_only} 9836 9837Mark logical volume as read only. 9838 9839#### Parameters 9840 9841Name | Optional | Type | Description 9842----------------------- | -------- | ----------- | ----------- 9843name | Required | string | UUID or alias of the logical volume to set as read only 9844 9845#### Example 9846 9847Example request: 9848 9849~~~json 9850{ 9851 "jsonrpc": "2.0", 9852 "method": "bdev_lvol_set_read_only", 9853 "id": 1, 9854 "params": { 9855 "name": "51638754-ca16-43a7-9f8f-294a0805ab0a", 9856 } 9857} 9858~~~ 9859 9860Example response: 9861 9862~~~json 9863{ 9864 "jsonrpc": "2.0", 9865 "id": 1, 9866 "result": true 9867} 9868~~~ 9869 9870### bdev_lvol_delete {#rpc_bdev_lvol_delete} 9871 9872Destroy a logical volume. 9873 9874#### Parameters 9875 9876Name | Optional | Type | Description 9877----------------------- | -------- | ----------- | ----------- 9878name | Required | string | UUID or alias of the logical volume to destroy 9879 9880#### Example 9881 9882Example request: 9883 9884~~~json 9885{ 9886 "jsonrpc": "2.0", 9887 "method": "bdev_lvol_delete", 9888 "id": 1, 9889 "params": { 9890 "name": "51638754-ca16-43a7-9f8f-294a0805ab0a" 9891 } 9892} 9893~~~ 9894 9895Example response: 9896 9897~~~json 9898{ 9899 "jsonrpc": "2.0", 9900 "id": 1, 9901 "result": true 9902} 9903~~~ 9904 9905### bdev_lvol_inflate {#rpc_bdev_lvol_inflate} 9906 9907Inflate a logical volume. All unallocated clusters are allocated and copied from the parent or zero filled 9908if not allocated in the parent. Then all dependencies on the parent are removed. 9909 9910### Parameters 9911 9912Name | Optional | Type | Description 9913----------------------- | -------- | ----------- | ----------- 9914name | Required | string | UUID or alias of the logical volume to inflate 9915 9916#### Example 9917 9918Example request: 9919 9920~~~json 9921{ 9922 "jsonrpc": "2.0", 9923 "method": "bdev_lvol_inflate", 9924 "id": 1, 9925 "params": { 9926 "name": "8d87fccc-c278-49f0-9d4c-6237951aca09" 9927 } 9928} 9929~~~ 9930 9931Example response: 9932 9933~~~json 9934{ 9935 "jsonrpc": "2.0", 9936 "id": 1, 9937 "result": true 9938} 9939~~~ 9940 9941### bdev_lvol_decouple_parent {#rpc_bdev_lvol_decouple_parent} 9942 9943Decouple the parent of a logical volume. For unallocated clusters which is allocated in the parent, they are 9944allocated and copied from the parent, but for unallocated clusters which is thin provisioned in the parent, 9945they are kept thin provisioned. Then all dependencies on the parent are removed. 9946 9947#### Parameters 9948 9949Name | Optional | Type | Description 9950----------------------- | -------- | ----------- | ----------- 9951name | Required | string | UUID or alias of the logical volume to decouple the parent of it 9952 9953#### Example 9954 9955Example request: 9956 9957~~~json 9958{ 9959 "jsonrpc": "2.0", 9960 "method": "bdev_lvol_decouple_parent", 9961 "id": 1. 9962 "params": { 9963 "name": "8d87fccc-c278-49f0-9d4c-6237951aca09" 9964 } 9965} 9966~~~ 9967 9968Example response: 9969 9970~~~json 9971{ 9972 "jsonrpc": "2.0", 9973 "id": 1, 9974 "result": true 9975} 9976~~~ 9977 9978## RAID 9979 9980### bdev_raid_get_bdevs {#rpc_bdev_raid_get_bdevs} 9981 9982This is used to list all the raid bdev details based on the input category requested. Category should be one 9983of 'all', 'online', 'configuring' or 'offline'. 'all' means all the raid bdevs whether they are online or 9984configuring or offline. 'online' is the raid bdev which is registered with bdev layer. 'configuring' is 9985the raid bdev which does not have full configuration discovered yet. 'offline' is the raid bdev which is 9986not registered with bdev as of now and it has encountered any error or user has requested to offline 9987the raid bdev. 9988 9989#### Parameters 9990 9991Name | Optional | Type | Description 9992----------------------- | -------- | ----------- | ----------- 9993category | Required | string | all or online or configuring or offline 9994 9995#### Example 9996 9997Example request: 9998 9999~~~json 10000{ 10001 "jsonrpc": "2.0", 10002 "method": "bdev_raid_get_bdevs", 10003 "id": 1, 10004 "params": { 10005 "category": "all" 10006 } 10007} 10008~~~ 10009 10010Example response: 10011 10012~~~json 10013{ 10014 "jsonrpc": "2.0", 10015 "id": 1, 10016 "result": [ 10017 { 10018 "name": "RaidBdev0", 10019 "strip_size_kb": 128, 10020 "state": "online", 10021 "raid_level": "raid0", 10022 "num_base_bdevs": 2, 10023 "num_base_bdevs_discovered": 2, 10024 "base_bdevs_list": [ 10025 "malloc0", 10026 "malloc1" 10027 ] 10028 }, 10029 { 10030 "name": "RaidBdev1", 10031 "strip_size_kb": 128, 10032 "state": "configuring", 10033 "raid_level": "raid0", 10034 "num_base_bdevs": 2, 10035 "num_base_bdevs_discovered": 1, 10036 "base_bdevs_list": [ 10037 "malloc2", 10038 null 10039 ] 10040 } 10041 ] 10042} 10043~~~ 10044 10045### bdev_raid_create {#rpc_bdev_raid_create} 10046 10047Constructs new RAID bdev. 10048 10049#### Parameters 10050 10051Name | Optional | Type | Description 10052----------------------- | -------- | ----------- | ----------- 10053name | Required | string | RAID bdev name 10054strip_size_kb | Required | number | Strip size in KB 10055raid_level | Required | string | RAID level 10056base_bdevs | Required | string | Base bdevs name, whitespace separated list in quotes 10057 10058#### Example 10059 10060Example request: 10061 10062~~~json 10063{ 10064 "jsonrpc": "2.0", 10065 "method": "bdev_raid_create", 10066 "id": 1, 10067 "params": { 10068 "name": "Raid0", 10069 "raid_level": "0", 10070 "base_bdevs": [ 10071 "Malloc0", 10072 "Malloc1", 10073 "Malloc2", 10074 "Malloc3" 10075 ], 10076 "strip_size_kb": 4 10077 } 10078} 10079~~~ 10080 10081Example response: 10082 10083~~~json 10084{ 10085 "jsonrpc": "2.0", 10086 "id": 1, 10087 "result": true 10088} 10089~~~ 10090 10091### bdev_raid_delete {#rpc_bdev_raid_delete} 10092 10093Removes RAID bdev. 10094 10095#### Parameters 10096 10097Name | Optional | Type | Description 10098----------------------- | -------- | ----------- | ----------- 10099name | Required | string | RAID bdev name 10100 10101#### Example 10102 10103Example request: 10104 10105~~~json 10106{ 10107 "jsonrpc": "2.0", 10108 "method": "bdev_raid_delete", 10109 "id": 1, 10110 "params": { 10111 "name": "Raid0" 10112 } 10113} 10114~~~ 10115 10116Example response: 10117 10118~~~json 10119{ 10120 "jsonrpc": "2.0", 10121 "id": 1, 10122 "result": true 10123} 10124~~~ 10125 10126## SPLIT 10127 10128### bdev_split_create {#rpc_bdev_split_create} 10129 10130This is used to split an underlying block device and create several smaller equal-sized vbdevs. 10131 10132#### Parameters 10133 10134Name | Optional | Type | Description 10135----------------------- | -------- | ----------- | ----------- 10136base_bdev | Required | string | base bdev name 10137split_count | Required | number | number of splits 10138split_size_mb | Optional | number | size in MB to restrict the size 10139 10140#### Example 10141 10142Example request: 10143 10144~~~json 10145{ 10146 "jsonrpc": "2.0", 10147 "method": "bdev_split_create", 10148 "id": 1, 10149 "params": { 10150 "base_bdev": "Malloc0", 10151 "split_count": 4 10152 } 10153} 10154~~~ 10155 10156Example response: 10157 10158~~~json 10159{ 10160 "jsonrpc": "2.0", 10161 "id": 1, 10162 "result": [ 10163 "Malloc0p0", 10164 "Malloc0p1", 10165 "Malloc0p2", 10166 "Malloc0p3" 10167 ] 10168} 10169~~~ 10170 10171### bdev_split_delete {#rpc_bdev_split_delete} 10172 10173This is used to remove the split vbdevs. 10174 10175#### Parameters 10176 10177Name | Optional | Type | Description 10178----------------------- | -------- | ----------- | ----------- 10179base_bdev | Required | string | base bdev name 10180 10181#### Example 10182 10183Example request: 10184 10185~~~json 10186{ 10187 "jsonrpc": "2.0", 10188 "method": "bdev_split_delete", 10189 "id": 1, 10190 "params": { 10191 "base_bdev": "Malloc0" 10192 } 10193} 10194~~~ 10195 10196Example response: 10197 10198~~~json 10199{ 10200 "jsonrpc": "2.0", 10201 "id": 1, 10202 "result": true 10203} 10204~~~ 10205 10206## Uring 10207 10208### bdev_uring_create {#rpc_bdev_uring_create} 10209 10210Create a bdev with io_uring backend. 10211 10212#### Parameters 10213 10214Name | Optional | Type | Description 10215----------------------- | -------- | ----------- | ----------- 10216filename | Required | string | path to device or file (ex: /dev/nvme0n1) 10217name | Required | string | name of bdev 10218block_size | Optional | number | block size of device (If omitted, get the block size from the file) 10219 10220#### Example 10221 10222Example request: 10223 10224~~~json 10225{ 10226 "jsonrpc": "2.0", 10227 "method": "bdev_uring_create", 10228 "id": 1, 10229 "params": { 10230 "name": "bdev_u0", 10231 "filename": "/dev/nvme0n1", 10232 "block_size": 512 10233 } 10234} 10235~~~ 10236 10237Example response: 10238 10239~~~json 10240{ 10241 "jsonrpc": "2.0", 10242 "id": 1, 10243 "result": "bdev_u0" 10244} 10245~~~ 10246 10247### bdev_uring_delete {#rpc_bdev_uring_delete} 10248 10249Remove a uring bdev. 10250 10251#### Parameters 10252 10253Name | Optional | Type | Description 10254----------------------- | -------- | ----------- | ----------- 10255name | Required | string | name of uring bdev to delete 10256 10257#### Example 10258 10259Example request: 10260 10261~~~json 10262{ 10263 "jsonrpc": "2.0", 10264 "method": "bdev_uring_delete", 10265 "id": 1, 10266 "params": { 10267 "name": "bdev_u0" 10268 } 10269} 10270~~~ 10271 10272Example response: 10273 10274~~~json 10275{ 10276 "jsonrpc": "2.0", 10277 "id": 1, 10278 "result": true 10279} 10280~~~ 10281 10282## OPAL 10283 10284### bdev_nvme_opal_init {#rpc_bdev_nvme_opal_init} 10285 10286This is used to initialize OPAL of a given NVMe ctrlr, including taking ownership and activating. 10287 10288#### Parameters 10289 10290Name | Optional | Type | Description 10291----------------------- | -------- | ----------- | ----------- 10292nvme_ctrlr_name | Required | string | name of nvme ctrlr 10293password | Required | string | admin password of OPAL 10294 10295#### Example 10296 10297Example request: 10298 10299~~~json 10300{ 10301 "jsonrpc": "2.0", 10302 "method": "bdev_nvme_opal_init", 10303 "id": 1, 10304 "params": { 10305 "nvme_ctrlr_name": "nvme0", 10306 "password": "*****" 10307 } 10308} 10309~~~ 10310 10311Example response: 10312 10313~~~json 10314{ 10315 "jsonrpc": "2.0", 10316 "id": 1, 10317 "result": true 10318} 10319~~~ 10320 10321### bdev_nvme_opal_revert {#rpc_bdev_nvme_opal_revert} 10322 10323This is used to revert OPAL to its factory settings. Erase all user configuration and data. 10324 10325#### Parameters 10326 10327Name | Optional | Type | Description 10328----------------------- | -------- | ----------- | ----------- 10329nvme_ctrlr_name | Required | string | name of nvme ctrlr 10330password | Required | string | admin password of OPAL 10331 10332#### Example 10333 10334Example request: 10335 10336~~~json 10337{ 10338 "jsonrpc": "2.0", 10339 "method": "bdev_nvme_opal_revert", 10340 "id": 1, 10341 "params": { 10342 "nvme_ctrlr_name": "nvme0", 10343 "password": "*****" 10344 } 10345} 10346~~~ 10347 10348Example response: 10349 10350~~~json 10351{ 10352 "jsonrpc": "2.0", 10353 "id": 1, 10354 "result": true 10355} 10356~~~ 10357 10358### bdev_opal_create {#rpc_bdev_opal_create} 10359 10360This is used to create an OPAL virtual bdev. 10361 10362#### Parameters 10363 10364Name | Optional | Type | Description 10365----------------------- | -------- | ----------- | ----------- 10366nvme_ctrlr_name | Required | string | name of nvme ctrlr that supports OPAL 10367nsid | Required | number | namespace ID 10368locking_range_id | Required | number | OPAL locking range ID 10369range_start | Required | number | locking range start LBA 10370range_length | Required | number | locking range length 10371password | Required | string | admin password of OPAL 10372 10373#### Response 10374 10375The response is the name of created OPAL virtual bdev. 10376 10377#### Example 10378 10379Example request: 10380 10381~~~json 10382{ 10383 "jsonrpc": "2.0", 10384 "method": "bdev_opal_create", 10385 "id": 1, 10386 "params": { 10387 "nvme_ctrlr_name": "nvme0", 10388 "nsid": 1, 10389 "locking_range_id": 1, 10390 "range_start": 0, 10391 "range_length": 4096, 10392 "password": "*****" 10393 } 10394} 10395~~~ 10396 10397Example response: 10398 10399~~~json 10400{ 10401 "jsonrpc": "2.0", 10402 "id": 1, 10403 "result": "nvme0n1r1" 10404} 10405~~~ 10406 10407### bdev_opal_get_info {#rpc_bdev_opal_get_info} 10408 10409This is used to get information of a given OPAL bdev. 10410 10411#### Parameters 10412 10413Name | Optional | Type | Description 10414----------------------- | -------- | ----------- | ----------- 10415bdev_name | Required | string | name of OPAL vbdev 10416password | Required | string | admin password 10417 10418#### Response 10419 10420The response is the locking info of OPAL virtual bdev. 10421 10422#### Example 10423 10424Example request: 10425 10426~~~json 10427{ 10428 "jsonrpc": "2.0", 10429 "method": "bdev_opal_get_info", 10430 "id": 1, 10431 "params": { 10432 "bdev_name": "nvme0n1r1", 10433 "password": "*****" 10434 } 10435} 10436~~~ 10437 10438Example response: 10439 10440~~~json 10441{ 10442 "jsonrpc": "2.0", 10443 "id": 1, 10444 "result": { 10445 "name": "nvme0n1r1", 10446 "range_start": 0, 10447 "range_length": 4096, 10448 "read_lock_enabled": true, 10449 "write_lock_enabled": true, 10450 "read_locked": false, 10451 "write_locked": false 10452 } 10453} 10454~~~ 10455 10456### bdev_opal_delete {#rpc_bdev_opal_delete} 10457 10458This is used to delete OPAL vbdev. 10459 10460#### Parameters 10461 10462Name | Optional | Type | Description 10463----------------------- | -------- | ----------- | ----------- 10464bdev_name | Required | string | name of OPAL vbdev 10465password | Required | string | admin password 10466 10467#### Example 10468 10469Example request: 10470 10471~~~json 10472{ 10473 "jsonrpc": "2.0", 10474 "method": "bdev_opal_delete", 10475 "id": 1, 10476 "params": { 10477 "bdev_name": "nvme0n1r1", 10478 "password": "*****" 10479 } 10480} 10481~~~ 10482 10483Example response: 10484 10485~~~json 10486{ 10487 "jsonrpc": "2.0", 10488 "id": 1, 10489 "result": true 10490} 10491~~~ 10492 10493### bdev_opal_new_user {#rpc_bdev_opal_new_user} 10494 10495This enables a new user to the specified opal bdev so that the user can lock/unlock the bdev. 10496Recalling this for the same opal bdev, only the newest user will have the privilege. 10497 10498#### Parameters 10499 10500Name | Optional | Type | Description 10501----------------------- | -------- | ----------- | ----------- 10502bdev_name | Required | string | name of OPAL vbdev 10503admin_password | Required | string | admin password 10504user_id | Required | number | user ID 10505user_password | Required | string | user password 10506 10507#### Example 10508 10509Example request: 10510 10511~~~json 10512{ 10513 "jsonrpc": "2.0", 10514 "method": "bdev_opal_new_user", 10515 "id": 1, 10516 "params": { 10517 "bdev_name": "nvme0n1r1", 10518 "admin_password": "*****", 10519 "user_id": "1", 10520 "user_password": "********" 10521 } 10522} 10523~~~ 10524 10525Example response: 10526 10527~~~json 10528{ 10529 "jsonrpc": "2.0", 10530 "id": 1, 10531 "result": true 10532} 10533~~~ 10534 10535### bdev_opal_set_lock_state {#rpc_bdev_opal_set_lock_state} 10536 10537This is used to lock/unlock specific opal bdev providing user ID and password. 10538 10539#### Parameters 10540 10541Name | Optional | Type | Description 10542----------------------- | -------- | ----------- | ----------- 10543bdev_name | Required | string | name of OPAL vbdev 10544user_id | Required | number | user ID 10545password | Required | string | user password 10546lock_state | Required | string | lock state 10547 10548#### Example 10549 10550Example request: 10551 10552~~~json 10553{ 10554 "jsonrpc": "2.0", 10555 "method": "bdev_opal_set_lock_state", 10556 "id": 1, 10557 "params": { 10558 "bdev_name": "nvme0n1r1", 10559 "user_id": "1", 10560 "user_password": "********", 10561 "lock_state": "rwlock" 10562 } 10563} 10564~~~ 10565 10566Example response: 10567 10568~~~json 10569{ 10570 "jsonrpc": "2.0", 10571 "id": 1, 10572 "result": true 10573} 10574~~~ 10575 10576## Notifications 10577 10578### notify_get_types {#rpc_notify_get_types} 10579 10580Return list of all supported notification types. 10581 10582#### Parameters 10583 10584None 10585 10586#### Response 10587 10588The response is an array of strings - supported RPC notification types. 10589 10590#### Example 10591 10592Example request: 10593 10594~~~json 10595{ 10596 "jsonrpc": "2.0", 10597 "method": "notify_get_types", 10598 "id": 1 10599} 10600~~~ 10601 10602Example response: 10603 10604~~~json 10605{ 10606 "id": 1, 10607 "result": [ 10608 "bdev_register", 10609 "bdev_unregister" 10610 ], 10611 "jsonrpc": "2.0" 10612} 10613~~~ 10614 10615### notify_get_notifications {#notify_get_notifications} 10616 10617Request notifications. Returns array of notifications that happened since the specified id (or first that is available). 10618 10619Notice: Notifications are kept in circular buffer with limited size. Older notifications might be inaccessible 10620due to being overwritten by new ones. 10621 10622#### Parameters 10623 10624Name | Optional | Type | Description 10625----------------------- | -------- | ----------- | ----------- 10626id | Optional | number | First Event ID to fetch (default: first available). 10627max | Optional | number | Maximum number of event to return (default: no limit). 10628 10629#### Response 10630 10631Response is an array of event objects. 10632 10633Name | Optional | Type | Description 10634----------------------- | -------- | ----------- | ----------- 10635id | Optional | number | Event ID. 10636type | Optional | number | Type of the event. 10637ctx | Optional | string | Event context. 10638 10639#### Example 10640 10641Example request: 10642 10643~~~json 10644{ 10645 "id": 1, 10646 "jsonrpc": "2.0", 10647 "method": "notify_get_notifications", 10648 "params": { 10649 "id": 1, 10650 "max": 10 10651 } 10652} 10653 10654~~~ 10655 10656Example response: 10657 10658~~~json 10659{ 10660 "jsonrpc": "2.0", 10661 "id": 1, 10662 "result": [ 10663 { 10664 "ctx": "Malloc0", 10665 "type": "bdev_register", 10666 "id": 1 10667 }, 10668 { 10669 "ctx": "Malloc2", 10670 "type": "bdev_register", 10671 "id": 2 10672 } 10673 ] 10674} 10675~~~ 10676 10677## Linux Userspace Block Device (UBLK) {#jsonrpc_components_ublk} 10678 10679SPDK supports exporting bdevs though Linux ublk. The motivation behind it is to back a Linux kernel block device 10680with an SPDK user space bdev. 10681 10682To export a device over ublk, first make sure the Linux kernel ublk driver is loaded by running 'modprobe ublk_drv'. 10683 10684### ublk_create_target {#rpc_ublk_create_target} 10685 10686Start to create ublk threads and initialize ublk target. It will return an error if user calls this RPC twice without 10687ublk_destroy_target in between. It will use current cpumask in SPDK when user does not specify cpumask option. 10688 10689#### Parameters 10690 10691Name | Optional | Type | Description 10692----------------------- | -------- | ----------- | ----------- 10693cpumask | Optional | string | Cpumask for ublk target 10694 10695#### Response 10696 10697True if ublk target initialization is successful; False if failed. 10698 10699#### Example 10700 10701Example request: 10702 10703~~~json 10704{ 10705 "params": { 10706 "cpumask": "0x2" 10707 }, 10708 "jsonrpc": "2.0", 10709 "method": "ublk_create_target", 10710 "id": 1 10711} 10712~~~ 10713 10714Example response: 10715 10716~~~json 10717{ 10718 "jsonrpc": "2.0", 10719 "id": 1, 10720 "result": true 10721} 10722~~~ 10723 10724### ublk_destroy_target {#rpc_ublk_destroy_target} 10725 10726Release all UBLK devices and destroy ublk target. 10727 10728#### Response 10729 10730True if ublk target destruction is successful; False if failed. 10731 10732#### Example 10733 10734Example request: 10735 10736~~~json 10737{ 10738 "jsonrpc": "2.0", 10739 "method": "ublk_destroy_target", 10740 "id": 1 10741} 10742~~~ 10743 10744Example response: 10745 10746~~~json 10747{ 10748 "jsonrpc": "2.0", 10749 "id": 1, 10750 "result": true 10751} 10752~~~ 10753 10754### ublk_start_disk {#rpc_ublk_start_disk} 10755 10756Start to export one SPDK bdev as a UBLK device 10757 10758#### Parameters 10759 10760Name | Optional | Type | Description 10761----------------------- | -------- | ----------- | ----------- 10762bdev_name | Required | string | Bdev name to export 10763ublk_id | Required | int | Device id 10764queue_depth | Optional | int | Device queue depth 10765num_queues | Optional | int | Total number of device queues 10766 10767#### Response 10768 10769UBLK device ID 10770 10771#### Example 10772 10773Example request: 10774 10775~~~json 10776{ 10777 "params": { 10778 "ublk_id": "1", 10779 "bdev_name": "Malloc1" 10780 }, 10781 "jsonrpc": "2.0", 10782 "method": "ublk_start_disk", 10783 "id": 1 10784} 10785~~~ 10786 10787Example response: 10788 10789~~~json 10790{ 10791 "jsonrpc": "2.0", 10792 "id": 1, 10793 "result": 1 10794} 10795~~~ 10796 10797### ublk_stop_disk {#rpc_ublk_stop_disk} 10798 10799Delete a UBLK device 10800 10801#### Parameters 10802 10803Name | Optional | Type | Description 10804----------------------- | -------- | ----------- | ----------- 10805ublk_id | Required | int | Device id to delete 10806 10807#### Response 10808 10809True if UBLK device is deleted successfully; False if failed. 10810 10811#### Example 10812 10813Example request: 10814 10815~~~json 10816{ 10817 "params": { 10818 "ublk_id": "1", 10819 }, 10820 "jsonrpc": "2.0", 10821 "method": "ublk_stop_disk", 10822 "id": 1 10823} 10824~~~ 10825 10826Example response: 10827 10828~~~json 10829{ 10830 "jsonrpc": "2.0", 10831 "id": 1, 10832 "result": true 10833} 10834~~~ 10835 10836### ublk_get_disks {#rpc_ublk_get_disks} 10837 10838Display full or specified ublk device list 10839 10840#### Parameters 10841 10842Name | Optional | Type | Description 10843----------------------- | -------- | ----------- | ----------- 10844ublk_id | Optional | int | ublk device id to display 10845 10846#### Response 10847 10848Display ublk device list 10849 10850#### Example 10851 10852Example request: 10853 10854~~~json 10855{ 10856 "jsonrpc": "2.0", 10857 "method": "ublk_get_disks", 10858 "id": 1 10859} 10860~~~ 10861 10862Example response: 10863 10864~~~json 10865{ 10866 "jsonrpc": "2.0", 10867 "id": 1, 10868 "result": [ 10869 { 10870 "ublk_device": "/dev/ublkb1", 10871 "id": 1, 10872 "queue_depth": 512, 10873 "num_queues": 1, 10874 "bdev_name": "Malloc1" 10875 } 10876 ] 10877} 10878~~~ 10879 10880## Linux Network Block Device (NBD) {#jsonrpc_components_nbd} 10881 10882SPDK supports exporting bdevs through Linux nbd. These devices then appear as standard Linux kernel block devices 10883and can be accessed using standard utilities like fdisk. 10884 10885In order to export a device over nbd, first make sure the Linux kernel nbd driver is loaded by running 'modprobe nbd'. 10886 10887### nbd_start_disk {#rpc_nbd_start_disk} 10888 10889Start to export one SPDK bdev as NBD disk 10890 10891#### Parameters 10892 10893Name | Optional | Type | Description 10894----------------------- | -------- | ----------- | ----------- 10895bdev_name | Required | string | Bdev name to export 10896nbd_device | Optional | string | NBD device name to assign 10897 10898#### Response 10899 10900Path of exported NBD disk 10901 10902#### Example 10903 10904Example request: 10905 10906~~~json 10907{ 10908 "params": { 10909 "nbd_device": "/dev/nbd1", 10910 "bdev_name": "Malloc1" 10911 }, 10912 "jsonrpc": "2.0", 10913 "method": "nbd_start_disk", 10914 "id": 1 10915} 10916~~~ 10917 10918Example response: 10919 10920~~~json 10921{ 10922 "jsonrpc": "2.0", 10923 "id": 1, 10924 "result": "/dev/nbd1" 10925} 10926~~~ 10927 10928### nbd_stop_disk {#rpc_nbd_stop_disk} 10929 10930Stop one NBD disk which is based on SPDK bdev. 10931 10932#### Parameters 10933 10934Name | Optional | Type | Description 10935----------------------- | -------- | ----------- | ----------- 10936nbd_device | Required | string | NBD device name to stop 10937 10938#### Example 10939 10940Example request: 10941 10942~~~json 10943{ 10944 "params": { 10945 "nbd_device": "/dev/nbd1", 10946 }, 10947 "jsonrpc": "2.0", 10948 "method": "nbd_stop_disk", 10949 "id": 1 10950} 10951~~~ 10952 10953Example response: 10954 10955~~~json 10956{ 10957 "jsonrpc": "2.0", 10958 "id": 1, 10959 "result": "true" 10960} 10961~~~ 10962 10963### nbd_get_disks {#rpc_nbd_get_disks} 10964 10965Display all or specified NBD device list 10966 10967#### Parameters 10968 10969Name | Optional | Type | Description 10970----------------------- | -------- | ----------- | ----------- 10971nbd_device | Optional | string | NBD device name to display 10972 10973#### Response 10974 10975The response is an array of exported NBD devices and their corresponding SPDK bdev. 10976 10977#### Example 10978 10979Example request: 10980 10981~~~json 10982{ 10983 "jsonrpc": "2.0", 10984 "method": "nbd_get_disks", 10985 "id": 1 10986} 10987~~~ 10988 10989Example response: 10990 10991~~~json 10992{ 10993 "jsonrpc": "2.0", 10994 "id": 1, 10995 "result": [ 10996 { 10997 "bdev_name": "Malloc0", 10998 "nbd_device": "/dev/nbd0" 10999 }, 11000 { 11001 "bdev_name": "Malloc1", 11002 "nbd_device": "/dev/nbd1" 11003 } 11004 ] 11005} 11006~~~ 11007 11008## Blobfs {#jsonrpc_components_blobfs} 11009 11010### blobfs_detect {#rpc_blobfs_detect} 11011 11012Detect whether a blobfs exists on bdev. 11013 11014#### Parameters 11015 11016Name | Optional | Type | Description 11017----------------------- | -------- | ----------- | ----------- 11018bdev_name | Required | string | Block device name to detect blobfs 11019 11020#### Response 11021 11022True if a blobfs exists on the bdev; False otherwise. 11023 11024#### Example 11025 11026Example request: 11027 11028~~~json 11029{ 11030 "jsonrpc": "2.0", 11031 "id": 1, 11032 "method": "blobfs_detect", 11033 "params": { 11034 "bdev_name": "Malloc0" 11035 } 11036} 11037~~~ 11038 11039Example response: 11040 11041~~~json 11042{ 11043 "jsonrpc": "2.0", 11044 "id": 1, 11045 "result": "true" 11046} 11047~~~ 11048 11049### blobfs_create {#rpc_blobfs_create} 11050 11051Build blobfs on bdev. 11052 11053#### Parameters 11054 11055Name | Optional | Type | Description 11056----------------------- | -------- | ----------- | ----------- 11057bdev_name | Required | string | Block device name to create blobfs 11058cluster_sz | Optional | number | Size of cluster in bytes. Must be multiple of 4KiB page size, default and minimal value is 1M. 11059 11060#### Example 11061 11062Example request: 11063 11064~~~json 11065{ 11066 "jsonrpc": "2.0", 11067 "id": 1, 11068 "method": "blobfs_create", 11069 "params": { 11070 "bdev_name": "Malloc0", 11071 "cluster_sz": 1M 11072 } 11073} 11074~~~ 11075 11076Example response: 11077 11078~~~json 11079{ 11080 "jsonrpc": "2.0", 11081 "id": 1, 11082 "result": "true" 11083} 11084~~~ 11085 11086### blobfs_mount {#rpc_blobfs_mount} 11087 11088Mount a blobfs on bdev to one host path through FUSE 11089 11090#### Parameters 11091 11092Name | Optional | Type | Description 11093----------------------- | -------- | ----------- | ----------- 11094bdev_name | Required | string | Block device name where the blobfs is 11095mountpoint | Required | string | Mountpoint path in host to mount blobfs 11096 11097#### Example 11098 11099Example request: 11100 11101~~~json 11102{ 11103 "jsonrpc": "2.0", 11104 "id": 1, 11105 "method": ""blobfs_mount"", 11106 "params": { 11107 "bdev_name": "Malloc0", 11108 "mountpoint": "/mnt/" 11109 } 11110} 11111~~~ 11112 11113Example response: 11114 11115~~~json 11116{ 11117 "jsonrpc": "2.0", 11118 "id": 1, 11119 "result": "true" 11120} 11121~~~ 11122 11123### blobfs_set_cache_size {#rpc_blobfs_set_cache_size} 11124 11125Set cache pool size for blobfs filesystems. This RPC is only permitted when the cache pool is not already initialized. 11126 11127The cache pool is initialized when the first blobfs filesystem is initialized or loaded. It is freed when the all 11128initialized or loaded filesystems are unloaded. 11129 11130#### Parameters 11131 11132Name | Optional | Type | Description 11133----------------------- | -------- | ----------- | ----------- 11134size_in_mb | Required | number | Cache size in megabytes 11135 11136#### Response 11137 11138True if cache size is set successfully; False if failed to set. 11139 11140#### Example 11141 11142Example request: 11143 11144~~~json 11145{ 11146 "jsonrpc": "2.0", 11147 "id": 1, 11148 "method": "blobfs_set_cache_size", 11149 "params": { 11150 "size_in_mb": 512, 11151 } 11152} 11153~~~ 11154 11155Example response: 11156 11157~~~json 11158{ 11159 "jsonrpc": "2.0", 11160 "id": 1, 11161 "result": true 11162} 11163~~~ 11164 11165## Socket layer {#jsonrpc_components_sock} 11166 11167### sock_impl_get_options {#rpc_sock_impl_get_options} 11168 11169Get parameters for the socket layer implementation. 11170 11171#### Parameters 11172 11173Name | Optional | Type | Description 11174----------------------- | -------- | ----------- | ----------- 11175impl_name | Required | string | Name of socket implementation, e.g. posix 11176 11177#### Response 11178 11179Response is an object with current socket layer options for requested implementation. 11180 11181#### Example 11182 11183Example request: 11184 11185~~~json 11186{ 11187 "jsonrpc": "2.0", 11188 "method": "sock_impl_get_options", 11189 "id": 1, 11190 "params": { 11191 "impl_name": "posix" 11192 } 11193} 11194~~~ 11195 11196Example response: 11197 11198~~~json 11199{ 11200 "jsonrpc": "2.0", 11201 "id": 1, 11202 "result": { 11203 "recv_buf_size": 2097152, 11204 "send_buf_size": 2097152, 11205 "enable_recv_pipe": true, 11206 "enable_quickack": true, 11207 "enable_placement_id": 0, 11208 "enable_zerocopy_send_server": true, 11209 "enable_zerocopy_send_client": false, 11210 "zerocopy_threshold": 0, 11211 "tls_version": 13, 11212 "enable_ktls": false, 11213 "psk_key": "1234567890ABCDEF", 11214 "psk_identity": "psk.spdk.io" 11215 } 11216} 11217~~~ 11218 11219### sock_impl_set_options {#rpc_sock_impl_set_options} 11220 11221Set parameters for the socket layer implementation. 11222 11223#### Parameters 11224 11225Name | Optional | Type | Description 11226--------------------------- | -------- | ----------- | ----------- 11227impl_name | Required | string | Name of socket implementation, e.g. posix 11228recv_buf_size | Optional | number | Size of socket receive buffer in bytes 11229send_buf_size | Optional | number | Size of socket send buffer in bytes 11230enable_recv_pipe | Optional | boolean | Enable or disable receive pipe 11231enable_quick_ack | Optional | boolean | Enable or disable quick ACK 11232enable_placement_id | Optional | number | Enable or disable placement_id. 0:disable,1:incoming_napi,2:incoming_cpu 11233enable_zerocopy_send_server | Optional | boolean | Enable or disable zero copy on send for server sockets 11234enable_zerocopy_send_client | Optional | boolean | Enable or disable zero copy on send for client sockets 11235zerocopy_threshold | Optional | number | Set zerocopy_threshold in bytes. A consecutive sequence of requests' iovecs 11236-- | -- | -- | that fall below this threshold may be sent without zerocopy flag set 11237tls_version | Optional | number | TLS protocol version, e.g. 13 for v1.3 (only applies when impl_name == ssl) 11238enable_ktls | Optional | boolean | Enable or disable Kernel TLS (only applies when impl_name == ssl) 11239psk_key | Optional | string | Default PSK KEY in hexadecimal digits, e.g. 1234567890ABCDEF (only applies when impl_name == ssl) 11240psk_identity | Optional | string | Default PSK ID, e.g. psk.spdk.io (only applies when impl_name == ssl) 11241 11242#### Response 11243 11244True if socket layer options were set successfully. 11245 11246#### Example 11247 11248Example request: 11249 11250~~~json 11251{ 11252 "jsonrpc": "2.0", 11253 "method": "sock_impl_set_options", 11254 "id": 1, 11255 "params": { 11256 "impl_name": "posix", 11257 "recv_buf_size": 2097152, 11258 "send_buf_size": 2097152, 11259 "enable_recv_pipe": false, 11260 "enable_quick_ack": false, 11261 "enable_placement_id": 0, 11262 "enable_zerocopy_send_server": true, 11263 "enable_zerocopy_send_client": false, 11264 "zerocopy_threshold": 10240, 11265 "tls_version": 13, 11266 "enable_ktls": false, 11267 "psk_key": "1234567890ABCDEF", 11268 "psk_identity": "psk.spdk.io" 11269 } 11270} 11271~~~ 11272 11273Example response: 11274 11275~~~json 11276{ 11277 "jsonrpc": "2.0", 11278 "id": 1, 11279 "result": true 11280} 11281~~~ 11282 11283### sock_set_default_impl {#rpc_sock_set_default_impl} 11284 11285Set the default sock implementation. 11286 11287#### Parameters 11288 11289Name | Optional | Type | Description 11290----------------------- | -------- | ----------- | ----------- 11291impl_name | Required | string | Name of socket implementation, e.g. posix 11292 11293#### Response 11294 11295True if the default socket layer configuration was set successfully. 11296 11297#### Example 11298 11299Example request: 11300 11301~~~json 11302{ 11303 "jsonrpc": "2.0", 11304 "method": "sock_set_default_impl", 11305 "id": 1, 11306 "params": { 11307 "impl_name": "posix" 11308 } 11309} 11310~~~ 11311 11312Example response: 11313 11314~~~json 11315{ 11316 "jsonrpc": "2.0", 11317 "id": 1, 11318 "result": true 11319} 11320~~~ 11321 11322## Miscellaneous RPC commands 11323 11324### bdev_nvme_send_cmd {#rpc_bdev_nvme_send_cmd} 11325 11326Send NVMe command directly to NVMe controller or namespace. Parameters and responses encoded by base64 urlsafe need further processing. 11327 11328Notice: bdev_nvme_send_cmd requires user to guarantee the correctness of NVMe command itself, and also optional parameters. 11329Illegal command contents or mismatching buffer size may result in unpredictable behavior. 11330 11331#### Parameters 11332 11333Name | Optional | Type | Description 11334----------------------- | -------- | ----------- | ----------- 11335name | Required | string | Name of the operating NVMe controller 11336cmd_type | Required | string | Type of nvme cmd. Valid values are: admin, io 11337data_direction | Required | string | Direction of data transfer. Valid values are: c2h, h2c 11338cmdbuf | Required | string | NVMe command encoded by base64 urlsafe 11339data | Optional | string | Data transferring to controller from host, encoded by base64 urlsafe 11340metadata | Optional | string | Metadata transferring to controller from host, encoded by base64 urlsafe 11341data_len | Optional | number | Data length required to transfer from controller to host 11342metadata_len | Optional | number | Metadata length required to transfer from controller to host 11343timeout_ms | Optional | number | Command execution timeout value, in milliseconds 11344 11345#### Response 11346 11347Name | Type | Description 11348----------------------- | ----------- | ----------- 11349cpl | string | NVMe completion queue entry, encoded by base64 urlsafe 11350data | string | Data transferred from controller to host, encoded by base64 urlsafe 11351metadata | string | Metadata transferred from controller to host, encoded by base64 urlsafe 11352 11353#### Example 11354 11355Example request: 11356 11357~~~json 11358{ 11359 "jsonrpc": "2.0", 11360 "method": "bdev_nvme_send_cmd", 11361 "id": 1, 11362 "params": { 11363 "name": "Nvme0", 11364 "cmd_type": "admin" 11365 "data_direction": "c2h", 11366 "cmdbuf": "BgAAAAEAAAAAAAAAAAAAAAAAAAAAAAAAsGUs9P5_AAAAAAAAABAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA==", 11367 "data_len": 60, 11368 } 11369} 11370~~~ 11371 11372Example response: 11373 11374~~~json 11375{ 11376 "jsonrpc": "2.0", 11377 "id": 1, 11378 "result": { 11379 "cpl": "AAAAAAAAAAARAAAAWrmwABAA==", 11380 "data": "sIjg6AAAAACwiODoAAAAALCI4OgAAAAAAAYAAREAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA" 11381 } 11382 11383} 11384~~~ 11385 11386### vmd_enable {#rpc_enable_vmd} 11387 11388Enable VMD enumeration. 11389 11390#### Parameters 11391 11392This method has no parameters. 11393 11394#### Response 11395 11396Completion status of enumeration is returned as a boolean. 11397 11398### Example 11399 11400Example request: 11401 11402~~~json 11403{ 11404 "jsonrpc": "2.0", 11405 "method": "vmd_enable", 11406 "id": 1 11407} 11408~~~ 11409 11410Example response: 11411 11412~~~json 11413{ 11414 "jsonrpc": "2.0", 11415 "id": 1, 11416 "result": true 11417} 11418~~~ 11419 11420### vmd_remove_device {#rpc_vmd_remove_device} 11421 11422Remove a device behind a VMD. 11423 11424### Parameters 11425 11426Name | Optional | Type | Description 11427----------------------- | -------- | ----------- | ----------- 11428addr | Required | string | Address of the device to remove. 11429 11430### Example 11431 11432~~~json 11433{ 11434 "jsonrpc": "2.0", 11435 "method": "vmd_remove_device", 11436 "params": { 11437 "addr": "5d0505:01:00.0" 11438 } 11439 "id": 1 11440} 11441~~~ 11442 11443Example response: 11444 11445~~~json 11446{ 11447 "jsonrpc": "2.0", 11448 "id": 1, 11449 "result": true 11450} 11451~~~ 11452 11453### vmd_rescan {#rpc_vmd_rescan} 11454 11455Force a rescan of the devices behind VMD. 11456 11457### Parameters 11458 11459This method has no parameters. 11460 11461#### Response 11462 11463The response is the number of new devices found. 11464 11465### Example 11466 11467~~~json 11468{ 11469 "jsonrpc": "2.0", 11470 "method": "vmd_rescan", 11471 "id": 1 11472} 11473~~~ 11474 11475Example response: 11476 11477~~~json 11478{ 11479 "jsonrpc": "2.0", 11480 "id": 1, 11481 "result": { 11482 "count": 1 11483 } 11484} 11485~~~ 11486 11487### spdk_get_version {#rpc_spdk_get_version} 11488 11489Get the version info of the running SPDK application. 11490 11491#### Parameters 11492 11493This method has no parameters. 11494 11495#### Response 11496 11497The response is the version number including major version number, minor version number, patch level number and suffix string. 11498 11499#### Example 11500 11501Example request: 11502 11503~~~json 11504{ 11505 "jsonrpc": "2.0", 11506 "id": 1, 11507 "method": "spdk_get_version" 11508} 11509~~~ 11510 11511Example response: 11512 11513~~~json 11514{ 11515 "jsonrpc": "2.0", 11516 "id": 1, 11517 "result": { 11518 "version": "19.04-pre", 11519 "fields" : { 11520 "major": 19, 11521 "minor": 4, 11522 "patch": 0, 11523 "suffix": "-pre" 11524 } 11525 } 11526} 11527~~~ 11528 11529### framework_get_pci_devices 11530 11531List PCIe devices attached to an SPDK application and the contents of their config space. 11532 11533#### Parameters 11534 11535This method has no parameters. 11536 11537#### Response 11538 11539The response is an array of attached PCIe devices. 11540 11541#### Example 11542 11543Example request: 11544 11545~~~json 11546{ 11547 "jsonrpc": "2.0", 11548 "id": 1, 11549 "method": "framework_get_pci_devices" 11550} 11551~~~ 11552 11553Example response: 11554Note that the config space buffer was trimmed. 11555 11556~~~json 11557{ 11558 "jsonrpc": "2.0", 11559 "id": 1, 11560 "result": { 11561 [ 11562 { 11563 "address": "0000:00:04.0", 11564 "config_space": "8680455807051000...0000000000000000" 11565 }, 11566 { 11567 "address": "0000:00:03.0", 11568 "config_space": "8680455807051000...0000000000000000" 11569 } 11570 ] 11571 } 11572} 11573~~~ 11574 11575### bdev_nvme_add_error_injection {#rpc_bdev_nvme_add_error_injection} 11576 11577Add a NVMe command error injection for a bdev nvme controller. 11578 11579#### Parameters 11580 11581Name | Optional | Type | Description 11582----------------------- | -------- | ----------- | ----------- 11583name | Required | string | Name of the operating NVMe controller 11584cmd_type | Required | string | Type of NVMe command. Valid values are: admin, io 11585opc | Required | number | Opcode for which the error injection is applied 11586do_not_submit | Optional | boolean | Set to true if request should not be submitted to the controller (default false) 11587timeout_in_us | Optional | number | Wait specified microseconds when do_not_submit is true 11588err_count | Optional | number | Number of matching NVMe commands to inject errors 11589sct | Optional | number | Status code type (default 0) 11590sc | Optional | number | Status code (default 0) 11591 11592#### Response 11593 11594true on success 11595 11596#### Example 11597 11598Example request: 11599 11600~~~json 11601{ 11602 "jsonrpc": "2.0", 11603 "method": "bdev_nvme_add_error_injection", 11604 "id": 1, 11605 "params": { 11606 "name": "HotInNvme0", 11607 "opc": 2, 11608 "cmd_type": "io", 11609 "err_count": 1111111, 11610 "sct": 11, 11611 "sc": 33 11612 } 11613} 11614 11615~~~ 11616 11617Example response: 11618 11619~~~json 11620{ 11621 "jsonrpc": "2.0", 11622 "id": 1, 11623 "result": true 11624} 11625 11626~~~ 11627 11628### bdev_nvme_remove_error_injection {#rpc_bdev_nvme_remove_error_injection} 11629 11630Remove a NVMe command error injection. 11631 11632#### Parameters 11633 11634Name | Optional | Type | Description 11635----------------------- | -------- | ----------- | ----------- 11636name | Required | string | Name of the operating NVMe controller 11637cmd_type | Required | string | Type of NVMe command. Valid values are: admin, io 11638opc | Required | number | Opcode for which the error injection is applied 11639 11640#### Response 11641 11642true on success 11643 11644#### Example 11645 11646Example request: 11647 11648~~~json 11649{ 11650 "jsonrpc": "2.0", 11651 "method": "bdev_nvme_remove_error_injection", 11652 "id": 1, 11653 "params": { 11654 "name": "HotInNvme0", 11655 "opc": 2, 11656 "cmd_type": "io" 11657 } 11658} 11659 11660 11661~~~ 11662 11663Example response: 11664 11665~~~json 11666{ 11667 "jsonrpc": "2.0", 11668 "id": 1, 11669 "result": true 11670} 11671 11672~~~ 11673 11674### bdev_daos_create {#rpc_bdev_daos_create} 11675 11676Construct @ref bdev_config_daos 11677 11678#### Parameters 11679 11680Name | Optional | Type | Description 11681----------------------- | -------- | ----------- | ----------- 11682name | Required | string | Bdev name to use 11683pool | Required | string | DAOS pool label or its uuid 11684cont | Required | string | DAOS cont label or its uuid 11685block_size | Required | number | Block size in bytes -must be multiple of 512 11686num_blocks | Required | number | Number of blocks 11687uuid | Optional | string | UUID of new bdev 11688oclass | Optional | string | DAOS object class (default SX) 11689 11690To find more about various object classes please visit [DAOS documentation](https://github.com/daos-stack/daos/blob/master/src/object/README.md). 11691Please note, that DAOS bdev module uses the same CLI flag notation as `dmg` and `daos` commands, 11692for instance, `SX` or `EC_4P2G2` rather than in DAOS header file `OC_SX` or `OC_EC_4P2G2`. 11693 11694#### Result 11695 11696Name of newly created bdev. 11697 11698#### Example 11699 11700Example request: 11701 11702~~~json 11703{ 11704 "params": { 11705 "block_size": 4096, 11706 "num_blocks": 16384, 11707 "name": "daosdev0", 11708 "pool": "test-pool", 11709 "cont": "test-cont", 11710 "oclass": "EC_4P2G2" 11711 }, 11712 "jsonrpc": "2.0", 11713 "method": "bdev_daos_create", 11714 "id": 1 11715} 11716~~~ 11717 11718Example response: 11719 11720~~~json 11721{ 11722 "jsonrpc": "2.0", 11723 "id": 1, 11724 "result": "daosdev0" 11725} 11726~~~ 11727 11728### bdev_daos_delete {#rpc_bdev_daos_delete} 11729 11730Delete @ref bdev_config_daos 11731 11732#### Parameters 11733 11734Name | Optional | Type | Description 11735----------------------- | -------- | ----------- | ----------- 11736name | Required | string | Bdev name 11737 11738#### Example 11739 11740Example request: 11741 11742~~~json 11743{ 11744 "params": { 11745 "name": "daosdev0" 11746 }, 11747 "jsonrpc": "2.0", 11748 "method": "bdev_daos_delete", 11749 "id": 1 11750} 11751~~~ 11752 11753Example response: 11754 11755~~~json 11756{ 11757 "jsonrpc": "2.0", 11758 "id": 1, 11759 "result": true 11760} 11761~~~ 11762 11763### bdev_daos_resize {#rpc_bdev_daos_resize} 11764 11765Resize @ref bdev_config_daos. 11766 11767#### Parameters 11768 11769Name | Optional | Type | Description 11770----------------------- | -------- | ----------- | ----------- 11771name | Required | string | Bdev name 11772new_size | Required | number | Bdev new capacity in MB 11773 11774#### Example 11775 11776Example request: 11777 11778~~~json 11779{ 11780 "params": { 11781 "name": "daosdev0", 11782 "new_size": 8192 11783 }, 11784 "jsonrpc": "2.0", 11785 "method": "bdev_daos_resize", 11786 "id": 1 11787} 11788~~~ 11789 11790Example response: 11791 11792~~~json 11793{ 11794 "jsonrpc": "2.0", 11795 "id": 1, 11796 "result": true 11797} 11798~~~ 11799 11800### iobuf_set_options {#rpc_iobuf_set_options} 11801 11802Set iobuf buffer pool options. 11803 11804#### Parameters 11805 11806Name | Optional | Type | Description 11807----------------------- | -------- | ----------- | ----------- 11808small_pool_count | Optional | number | Number of small buffers in the global pool 11809large_pool_count | Optional | number | Number of large buffers in the global pool 11810small_bufsize | Optional | number | Size of a small buffer 11811large_bufsize | Optional | number | Size of a small buffer 11812 11813#### Example 11814 11815Example request: 11816 11817~~~json 11818{ 11819 "jsonrpc": "2.0", 11820 "id": 1, 11821 "method": "iobuf_set_options", 11822 "params": { 11823 "small_pool_count": 16383, 11824 "large_pool_count": 2047 11825 } 11826} 11827~~~ 11828 11829Example response: 11830 11831~~~json 11832{ 11833 "jsonrpc": "2.0", 11834 "id": 1, 11835 "result": true 11836} 11837~~~ 11838 11839### bdev_nvme_start_mdns_discovery {#rpc_bdev_nvme_start_mdns_discovery} 11840 11841Starts an mDNS based discovery service for the specified service type for the 11842auto-discovery of discovery controllers (NVMe TP-8009). 11843 11844The discovery service will listen for the mDNS discovery events from the 11845Avahi-daemon and will connect to the newly learnt discovery controllers. 11846Then the discovery service will automatically attach to any subsystem found in the 11847discovery log page from the discovery controllers learnt using mDNS. 11848When determining a controller name to use when attaching, it will use 11849the 'name' parameter as a prefix, followed by a unique integer assigned for each of the 11850discovery controllers learnt through mDNS, followed by a unique integer for that discovery 11851service. If the discovery service identifies a subsystem that has been previously 11852attached but is listed with a different path, it will use the same controller name 11853as the previous entry, and connect as a multipath. 11854 11855When the discovery service sees that a subsystem entry has been removed 11856from the log page, it will automatically detach from that controller as well. 11857 11858The 'name' is also used to later stop the discovery service. 11859 11860#### Parameters 11861 11862Name | Optional | Type | Description 11863-------------------------- | -------- | ----------- | ----------- 11864name | Required | string | Prefix for NVMe discovery services found 11865svcname | Required | string | Service to discover: e.g. _nvme-disc._tcp 11866hostnqn | Optional | string | NVMe-oF hostnqn 11867 11868#### Example 11869 11870Example request: 11871 11872~~~json 11873{ 11874 "jsonrpc": "2.0", 11875 "method": "bdev_nvme_start_mdns_discovery", 11876 "id": 1, 11877 "params": { 11878 "name": "cdc_auto", 11879 "svcname": "_nvme-disc._tcp", 11880 "hostnqn": "nqn.2021-12.io.spdk:host1", 11881 } 11882} 11883~~~ 11884 11885Example response: 11886 11887~~~json 11888{ 11889 "jsonrpc": "2.0", 11890 "id": 1, 11891 "result": true 11892} 11893~~~ 11894 11895### bdev_nvme_stop_mdns_discovery {#rpc_bdev_nvme_stop_mdns_discovery} 11896 11897Stops a mDNS discovery service. This includes detaching any controllers that were 11898discovered via the service that is being stopped. 11899 11900#### Parameters 11901 11902Name | Optional | Type | Description 11903-------------------------- | -------- | ----------- | ----------- 11904name | Required | string | Name of mDNS discovery instance to stop 11905 11906#### Example 11907 11908Example request: 11909 11910~~~json 11911{ 11912 "jsonrpc": "2.0", 11913 "method": "bdev_nvme_stop_mdns_discovery", 11914 "id": 1, 11915 "params": { 11916 "name": "cdc_auto" 11917 } 11918} 11919~~~ 11920 11921Example response: 11922 11923~~~json 11924{ 11925 "jsonrpc": "2.0", 11926 "id": 1, 11927 "result": true 11928} 11929~~~ 11930 11931### bdev_nvme_get_mdns_discovery_info {#rpc_bdev_nvme_get_mdns_discovery_info} 11932 11933Get the information about the mDNS discovery service instances. 11934 11935#### Example 11936 11937Example request: 11938~~~json 11939{ 11940 "jsonrpc": "2.0", 11941 "method": "bdev_nvme_get_mdns_discovery_info", 11942 "id": 1 11943} 11944~~~ 11945 11946Example response: 11947 11948~~~json 11949[ 11950 { 11951 "name": "cdc_auto", 11952 "svcname": "_nvme-disc._tcp", 11953 "referrals": [ 11954 { 11955 "name": "cdc_auto0", 11956 "trid": { 11957 "trtype": "TCP", 11958 "adrfam": "IPv4", 11959 "traddr": "66.1.2.21", 11960 "trsvcid": "8009", 11961 "subnqn": "nqn.2014-08.org.nvmexpress.discovery" 11962 } 11963 }, 11964 { 11965 "name": "cdc_auto1", 11966 "trid": { 11967 "trtype": "TCP", 11968 "adrfam": "IPv4", 11969 "traddr": "66.1.1.21", 11970 "trsvcid": "8009", 11971 "subnqn": "nqn.2014-08.org.nvmexpress.discovery" 11972 } 11973 } 11974 ] 11975 } 11976] 11977~~~ 11978