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