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