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