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 } 3158 ] 3159} 3160~~~ 3161 3162### bdev_nvme_detach_controller {#rpc_bdev_nvme_detach_controller} 3163 3164Detach NVMe controller and delete any associated bdevs. Optionally, 3165If all of the transport ID options are specified, only remove that 3166transport path from the specified controller. If that is the only 3167available path for the controller, this will also result in the 3168controller being detached and the associated bdevs being deleted. 3169 3170returns true if the controller and bdevs were successfully destroyed 3171or the address was properly removed, false otherwise. 3172 3173#### Parameters 3174 3175Name | Optional | Type | Description 3176----------------------- | -------- | ----------- | ----------- 3177name | Required | string | Controller name 3178trtype | Optional | string | NVMe-oF target trtype: rdma or tcp 3179traddr | Optional | string | NVMe-oF target address: ip or BDF 3180adrfam | Optional | string | NVMe-oF target adrfam: ipv4, ipv6, ib, fc, intra_host 3181trsvcid | Optional | string | NVMe-oF target trsvcid: port number 3182subnqn | Optional | string | NVMe-oF target subnqn 3183hostaddr | Optional | string | NVMe-oF host address: ip 3184hostsvcid | Optional | string | NVMe-oF host svcid: port number 3185 3186#### Example 3187 3188Example requests: 3189 3190~~~json 3191{ 3192 "params": { 3193 "name": "Nvme0" 3194 }, 3195 "jsonrpc": "2.0", 3196 "method": "bdev_nvme_detach_controller", 3197 "id": 1 3198} 3199~~~ 3200 3201Example response: 3202 3203~~~json 3204{ 3205 "jsonrpc": "2.0", 3206 "id": 1, 3207 "result": true 3208} 3209~~~ 3210 3211### bdev_nvme_reset_controller {#rpc_bdev_nvme_reset_controller} 3212 3213Reset NVMe controller. 3214 3215Returns true if the controller reset was successful, false otherwise. 3216 3217#### Parameters 3218 3219Name | Optional | Type | Description 3220----------------------- | -------- | ----------- | ----------- 3221name | Required | string | NVMe controller name 3222 3223#### Example 3224 3225Example request: 3226 3227~~~json 3228{ 3229 "jsonrpc": "2.0", 3230 "id": 1, 3231 "method": "bdev_nvme_reset_controller", 3232 "params": { 3233 "name": "Nvme0" 3234 } 3235} 3236~~~ 3237 3238Example response: 3239 3240~~~json 3241{ 3242 "jsonrpc": "2.0", 3243 "id": 1, 3244 "result": true 3245} 3246~~~ 3247 3248### bdev_nvme_start_discovery {#rpc_bdev_nvme_start_discovery} 3249 3250Start a discovery service for the discovery subsystem of the specified transport ID. 3251 3252The discovery service will read the discovery log page for the specified 3253discovery subsystem, and automatically attach to any subsystems found in the 3254log page. When determining a controller name to use when attaching, it will use 3255the 'name' parameter as a prefix, followed by a unique integer for that discovery 3256service. If the discovery service identifies a subsystem that has been previously 3257attached but is listed with a different path, it will use the same controller name 3258as the previous entry, and connect as a multipath. 3259 3260When the discovery service sees that a subsystem entry has been removed 3261from the log page, it will automatically detach from that controller as well. 3262 3263The 'name' is also used to later stop the discovery service. 3264 3265#### Parameters 3266 3267Name | Optional | Type | Description 3268-------------------------- | -------- | ----------- | ----------- 3269name | Required | string | Prefix for NVMe controllers 3270trtype | Required | string | NVMe-oF target trtype: rdma or tcp 3271traddr | Required | string | NVMe-oF target address: ip 3272adrfam | Optional | string | NVMe-oF target adrfam: ipv4, ipv6 3273trsvcid | Optional | string | NVMe-oF target trsvcid: port number 3274hostnqn | Optional | string | NVMe-oF target hostnqn 3275wait_for_attach | Optional | bool | Wait to complete until all discovered NVM subsystems are attached 3276ctrlr_loss_timeout_sec | Optional | number | Time to wait until ctrlr is reconnected before deleting ctrlr. -1 means infinite reconnects. 0 means no reconnect. 3277reconnect_delay_sec | Optional | number | Time to delay a reconnect trial. 0 means no reconnect. 3278fast_io_fail_timeout_sec | Optional | number | Time to wait until ctrlr is reconnected before failing I/O to ctrlr. 0 means no such timeout. 3279 3280#### Example 3281 3282Example request: 3283 3284~~~json 3285{ 3286 "jsonrpc": "2.0", 3287 "method": "bdev_nvme_start_discovery", 3288 "id": 1, 3289 "params": { 3290 "name": "nvme_auto", 3291 "trtype": "tcp", 3292 "traddr": "127.0.0.1", 3293 "hostnqn": "nqn.2021-12.io.spdk:host1", 3294 "adrfam": "ipv4", 3295 "trsvcid": "4420" 3296 } 3297} 3298~~~ 3299 3300Example response: 3301 3302~~~json 3303{ 3304 "jsonrpc": "2.0", 3305 "id": 1, 3306 "result": true 3307} 3308~~~ 3309 3310### bdev_nvme_stop_discovery {#rpc_bdev_nvme_stop_discovery} 3311 3312Stop a discovery service. This includes detaching any controllers that were 3313discovered via the service that is being stopped. 3314 3315#### Parameters 3316 3317Name | Optional | Type | Description 3318-------------------------- | -------- | ----------- | ----------- 3319name | Required | string | Name of service to stop 3320 3321#### Example 3322 3323Example request: 3324 3325~~~json 3326{ 3327 "jsonrpc": "2.0", 3328 "method": "bdev_nvme_stop_discovery", 3329 "id": 1, 3330 "params": { 3331 "name": "nvme_auto" 3332 } 3333} 3334~~~ 3335 3336Example response: 3337 3338~~~json 3339{ 3340 "jsonrpc": "2.0", 3341 "id": 1, 3342 "result": true 3343} 3344~~~ 3345 3346### bdev_nvme_cuse_register {#rpc_bdev_nvme_cuse_register} 3347 3348Register CUSE device on NVMe controller. 3349This feature is considered as experimental. 3350 3351#### Parameters 3352 3353Name | Optional | Type | Description 3354----------------------- | -------- | ----------- | ----------- 3355name | Required | string | Name of the NVMe controller 3356dev_path | Required | string | Path to the CUSE controller device, e.g. spdk/nvme0 3357 3358#### Example 3359 3360Example request: 3361 3362~~~json 3363{ 3364 "params": { 3365 "dev_path": "spdk/nvme0", 3366 "name": "Nvme0" 3367 }, 3368 "jsonrpc": "2.0", 3369 "method": "bdev_nvme_cuse_register", 3370 "id": 1 3371} 3372~~~ 3373 3374Example response: 3375 3376~~~json 3377{ 3378 "jsonrpc": "2.0", 3379 "id": 1, 3380 "result": true 3381} 3382~~~ 3383 3384### bdev_nvme_cuse_unregister {#rpc_bdev_nvme_cuse_unregister} 3385 3386Unregister CUSE device on NVMe controller. 3387This feature is considered as experimental. 3388 3389#### Parameters 3390 3391Name | Optional | Type | Description 3392----------------------- | -------- | ----------- | ----------- 3393name | Required | string | Name of the NVMe controller 3394 3395#### Example 3396 3397Example request: 3398 3399~~~json 3400{ 3401 "params": { 3402 "name": "Nvme0" 3403 }, 3404 "jsonrpc": "2.0", 3405 "method": "bdev_nvme_cuse_unregister", 3406 "id": 1 3407} 3408~~~ 3409 3410Example response: 3411 3412~~~json 3413{ 3414 "jsonrpc": "2.0", 3415 "id": 1, 3416 "result": true 3417} 3418~~~ 3419 3420### bdev_zone_block_create {#rpc_bdev_zone_block_create} 3421 3422Creates a virtual zone device on top of existing non-zoned bdev. 3423 3424#### Parameters 3425 3426Name | Optional | Type | Description 3427----------------------- | -------- | ----------- | ----------- 3428name | Required | string | Name of the Zone device 3429base_bdev | Required | string | Name of the Base bdev 3430zone_capacity | Required | number | Zone capacity in blocks 3431optimal_open_zones | Required | number | Number of zones required to reach optimal write speed 3432 3433#### Example 3434 3435Example request: 3436 3437~~~json 3438{ 3439 "jsonrpc": "2.0", 3440 "method": "bdev_zone_block_create", 3441 "id": 1, 3442 "params": { 3443 "name": "zone1", 3444 "base_bdev": "NVMe0n1", 3445 "zone_capacity": 4096, 3446 "optimal_open_zones": 32 3447 } 3448} 3449~~~ 3450 3451Example response: 3452 3453~~~json 3454{ 3455 "jsonrpc": "2.0", 3456 "id": 1, 3457 "result": "zone1" 3458} 3459~~~ 3460 3461### bdev_zone_block_delete {#rpc_bdev_zone_block_delete} 3462 3463Deletes a virtual zone device. 3464 3465#### Parameters 3466 3467Name | Optional | Type | Description 3468----------------------- | -------- | ----------- | ----------- 3469name | Required | string | Name of the Zone device 3470 3471#### Example 3472 3473Example request: 3474 3475~~~json 3476{ 3477 "jsonrpc": "2.0", 3478 "method": "bdev_zone_block_delete", 3479 "id": 1, 3480 "params": { 3481 "name": "zone1" 3482 } 3483} 3484~~~ 3485 3486Example response: 3487 3488~~~json 3489{ 3490 "jsonrpc": "2.0", 3491 "id": 1, 3492 "result": true 3493} 3494~~~ 3495 3496### bdev_nvme_apply_firmware {#rpc_bdev_nvme_apply_firmware} 3497 3498Download and commit firmware to NVMe device. 3499 3500#### Parameters 3501 3502Name | Optional | Type | Description 3503----------------------- | -------- | ----------- | ----------- 3504filename | Required | string | filename of the firmware to download 3505bdev_name | Required | string | Name of the NVMe block device 3506 3507#### Example 3508 3509Example request: 3510 3511~~~json 3512{ 3513 "jsonrpc": "2.0", 3514 "method": "bdev_nvme_apply_firmware", 3515 "id": 1, 3516 "params": { 3517 "filename": "firmware_file", 3518 "bdev_name": "NVMe0n1" 3519 } 3520} 3521~~~ 3522 3523### bdev_nvme_get_transport_statistics {#rpc_bdev_nvme_get_transport_statistics} 3524 3525Get bdev_nvme poll group transport statistics. 3526 3527#### Parameters 3528 3529This RPC method accepts no parameters 3530 3531#### Response 3532 3533The response is an array of objects containing information about transport statistics per NVME poll group. 3534 3535#### Example 3536 3537Example request: 3538 3539~~~json 3540{ 3541 "jsonrpc": "2.0", 3542 "id": 1, 3543 "method": "bdev_nvme_get_transport_statistics", 3544} 3545~~~ 3546 3547Example response: 3548 3549~~~json 3550{ 3551 "jsonrpc": "2.0", 3552 "id": 1, 3553 "result": { 3554 "poll_groups": [ 3555 { 3556 "thread": "nvmf_tgt_poll_group_0", 3557 "transports": [ 3558 { 3559 "trname": "RDMA", 3560 "devices": [ 3561 { 3562 "dev_name": "mlx5_1", 3563 "polls": 137492169, 3564 "idle_polls": 137492169, 3565 "completions": 0, 3566 "queued_requests": 0, 3567 "total_send_wrs": 0, 3568 "send_sq_doorbell_updates": 0, 3569 "total_recv_wrs": 0, 3570 "recv_sq_doorbell_updates": 0 3571 }, 3572 { 3573 "dev_name": "mlx5_0", 3574 "polls": 137985185, 3575 "idle_polls": 137492169, 3576 "completions": 1474593, 3577 "queued_requests": 0, 3578 "total_send_wrs": 1474593, 3579 "send_sq_doorbell_updates": 426147, 3580 "total_recv_wrs": 1474721, 3581 "recv_sq_doorbell_updates": 348445 3582 } 3583 ] 3584 }, 3585 { 3586 "trname": "PCIE", 3587 "polls": 435419831, 3588 "idle_polls": 434901004, 3589 "completions": 1485543, 3590 "cq_doorbell_updates": 518827, 3591 "queued_requests": 0, 3592 "submitted_requests": 1485543, 3593 "sq_doorbell_updates": 516081 3594 } 3595 ] 3596 }, 3597 { 3598 "thread": "nvmf_tgt_poll_group_1", 3599 "transports": [ 3600 { 3601 "trname": "RDMA", 3602 "devices": [ 3603 { 3604 "dev_name": "mlx5_1", 3605 "polls": 140245630, 3606 "idle_polls": 140245630, 3607 "completions": 0, 3608 "queued_requests": 0, 3609 "total_send_wrs": 0, 3610 "send_sq_doorbell_updates": 0, 3611 "total_recv_wrs": 0, 3612 "recv_sq_doorbell_updates": 0 3613 }, 3614 { 3615 "dev_name": "mlx5_0", 3616 "polls": 140751844, 3617 "idle_polls": 140245630, 3618 "completions": 1489298, 3619 "queued_requests": 0, 3620 "total_send_wrs": 1489298, 3621 "send_sq_doorbell_updates": 433510, 3622 "total_recv_wrs": 1489426, 3623 "recv_sq_doorbell_updates": 357956 3624 } 3625 ] 3626 }, 3627 { 3628 "trname": "PCIE", 3629 "polls": 429044294, 3630 "idle_polls": 428525658, 3631 "completions": 1478730, 3632 "cq_doorbell_updates": 518636, 3633 "queued_requests": 0, 3634 "submitted_requests": 1478730, 3635 "sq_doorbell_updates": 511658 3636 } 3637 ] 3638 } 3639 ] 3640 } 3641} 3642~~~ 3643 3644### bdev_nvme_get_controller_health_info {#rpc_bdev_nvme_get_controller_health_info} 3645 3646Display health log of the required NVMe bdev device. 3647 3648#### Parameters 3649 3650Name | Optional | Type | Description 3651----------------------- | -------- | ----------- | ----------- 3652name | Required | string | Name of the NVMe bdev controller 3653 3654#### Response 3655 3656The response is the object containing information about health log of the NVMe controller. 3657 3658#### Example 3659 3660Example request: 3661 3662~~~json 3663{ 3664 "jsonrpc": "2.0", 3665 "method": "bdev_nvme_get_controller_health_info", 3666 "id": 1, 3667 "params": { 3668 "name": "Nvme0" 3669 } 3670} 3671~~~ 3672 3673Example response: 3674 3675~~~json 3676{ 3677 "model_number": "INTEL SSDPE2KX020T8", 3678 "serial_number": "BTLJ72430ARH2P0BGN", 3679 "firmware_revision": "VDV10110", 3680 "traddr": "0000:08:00.0", 3681 "temperature_celsius": 32, 3682 "available_spare_percentage": 99, 3683 "available_spare_threshold_percentage": 10, 3684 "percentage_used": 2, 3685 "data_units_read": 1013408619, 3686 "data_units_written": 346792685, 3687 "host_read_commands": 30457773282, 3688 "host_write_commands": 18949677715, 3689 "controller_busy_time": 4979, 3690 "power_cycles": 49, 3691 "power_on_hours": 31118, 3692 "unsafe_shutdowns": 18, 3693 "media_errors": 17, 3694 "num_err_log_entries": 19, 3695 "warning_temperature_time_minutes": 0, 3696 "critical_composite_temperature_time_minutes": 0 3697} 3698~~~ 3699 3700### bdev_rbd_register_cluster {#rpc_bdev_rbd_register_cluster} 3701 3702This method is available only if SPDK was build with Ceph RBD support. 3703 3704#### Parameters 3705 3706Name | Optional | Type | Description 3707----------------------- | -------- | ----------- | ----------- 3708name | Required | string | Registerd Rados cluster object name 3709user_id | Optional | string | Ceph ID (i.e. admin, not client.admin) 3710config_param | Optional | string map | Explicit librados configuration 3711config_file | Optional | string | File path of libraodos configuration file 3712key_file | Optional | string | File path of libraodos key file 3713 3714This RPC registers a Rados Cluster object handle which is only known 3715to rbd module, it uses user_id + config_param or user_id + config_file + 3716key_file or user_id + config_param + config_file + key_file to identify 3717a Rados cluster object. 3718 3719When accessing the Ceph cluster as some user other than "admin" (the 3720default), the "user_id" has to be set. 3721 3722The configuration items and secret key can be specified by setting config_param, 3723config_file and key_file, all of them, or none of them. If only config_param is 3724passed, all key/value pairs are passed to rados_conf_set to configure cluster access. 3725In practice, "mon_host" (= list of monitor address+port) and "key" (= the secret key 3726stored in Ceph keyrings) are enough. If config_file and key_file are specified, they must 3727exist with all relevant settings for accessing the Ceph cluster. If config_param, config_file 3728and key_file are specified, get the key/value pairs from config_file first and set to 3729rados_conf_set function, then set pairs in config_param and keyring in key_file. If nothing 3730is specified, it will get configuration file and key file from the default location 3731/etc/ceph/ceph.conf and /etc/ceph/ceph.client.user_id.keyring. 3732 3733#### Result 3734 3735Name of newly created Rados cluster object. 3736 3737#### Example 3738 3739Example request: 3740 3741~~ 3742{ 3743 "params": { 3744 "name": "rbd_cluster", 3745 "user_id": cinder, 3746 "config_file": "/root/ceph_conf/ceph.conf", 3747 "key_file": "/root/ceph_conf/ceph.client.cinder.keyring" 3748 }, 3749 "jsonrpc": "2.0", 3750 "method": "bdev_rbd_register_cluster", 3751 "id": 1 3752} 3753~~ 3754 3755Example response: 3756 3757~~ 3758response: 3759{ 3760 "jsonrpc": "2.0", 3761 "id": 1, 3762 "result": "rbd_cluster" 3763} 3764~~ 3765 3766### bdev_rbd_unregister_cluster {#rpc_bdev_rbd_unregister_cluster} 3767 3768This method is available only if SPDK was build with Ceph RBD support. 3769If there is still rbd bdev using this cluster, the unregisteration operation 3770will fail. 3771 3772#### Result 3773 3774`true` if Rados cluster object with provided name was deleted or `false` otherwise. 3775 3776#### Parameters 3777 3778Name | Optional | Type | Description 3779----------------------- | -------- | ----------- | ------------------------- 3780name | Required | string | Rados cluster object name 3781 3782#### Example 3783 3784Example request: 3785 3786~~ 3787{ 3788 "params": { 3789 "name": "rbd_cluster" 3790 }, 3791 "jsonrpc": "2.0", 3792 "method": "bdev_rbd_unregister_cluster", 3793 "id": 1 3794} 3795~~ 3796 3797Example response: 3798 3799~~ 3800{ 3801 "jsonrpc": "2.0", 3802 "id": 1, 3803 "result": true 3804} 3805~~ 3806 3807### bdev_rbd_get_clusters_info {#rpc_bdev_rbd_get_clusters_info} 3808 3809This method is available only if SPDK was build with Ceph RBD support. 3810 3811#### Result 3812 3813Returns the cluster info of the Rados Cluster name if provided. Otherwise, it 3814returns the cluster info of every registered Raods Cluster name. 3815 3816#### Parameters 3817 3818Name | Optional | Type | Description 3819----------------------- | -------- | ----------- | ------------------------- 3820name | Optional | string | Rados cluster object name 3821 3822#### Example 3823 3824Example request: 3825 3826~~ 3827{ 3828 "params": { 3829 "name": "rbd_cluster" 3830 }, 3831 "jsonrpc": "2.0", 3832 "method": "bdev_rbd_get_clusters_info", 3833 "id": 1 3834} 3835~~ 3836 3837Example response: 3838 3839~~ 3840{ 3841 "jsonrpc": "2.0", 3842 "cluster_name": "rbd_cluster" 3843} 3844~~ 3845 3846### bdev_rbd_create {#rpc_bdev_rbd_create} 3847 3848Create @ref bdev_config_rbd bdev 3849 3850This method is available only if SPDK was build with Ceph RBD support. 3851 3852#### Parameters 3853 3854Name | Optional | Type | Description 3855----------------------- | -------- | ----------- | ----------- 3856name | Optional | string | Bdev name 3857user_id | Optional | string | Ceph ID (i.e. admin, not client.admin) 3858pool_name | Required | string | Pool name 3859rbd_name | Required | string | Image name 3860block_size | Required | number | Block size 3861config | Optional | string map | Explicit librados configuration 3862cluster_name | Optional | string | Rados cluster object name created in this module. 3863uuid | Optional | string | UUID of new bdev 3864 3865If no config is specified, Ceph configuration files must exist with 3866all relevant settings for accessing the pool. If a config map is 3867passed, the configuration files are ignored and instead all key/value 3868pairs are passed to rados_conf_set to configure cluster access. In 3869practice, "mon_host" (= list of monitor address+port) and "key" (= the 3870secret key stored in Ceph keyrings) are enough. 3871 3872When accessing the image as some user other than "admin" (the 3873default), the "user_id" has to be set. 3874 3875If provided with cluster_name option, it will use the Rados cluster object 3876referenced by the name (created by bdev_rbd_register_cluster RPC) and ignores 3877"user_id + config" combination to create its own Rados cluster. 3878 3879#### Result 3880 3881Name of newly created bdev. 3882 3883#### Example 3884 3885Example request with `key` from `/etc/ceph/ceph.client.admin.keyring`: 3886 3887~~~json 3888{ 3889 "params": { 3890 "pool_name": "rbd", 3891 "rbd_name": "foo", 3892 "config": { 3893 "mon_host": "192.168.7.1:6789,192.168.7.2:6789", 3894 "key": "AQDwf8db7zR1GRAA5k7NKXjS5S5V4mntwUDnGQ==", 3895 } 3896 "block_size": 4096, 3897 "uuid": "76210ea4-7920-40a0-a07b-8992a7443c76" 3898 }, 3899 "jsonrpc": "2.0", 3900 "method": "bdev_rbd_create", 3901 "id": 1 3902} 3903~~~ 3904 3905Example response: 3906 3907~~~json 3908response: 3909{ 3910 "jsonrpc": "2.0", 3911 "id": 1, 3912 "result": "Ceph0" 3913} 3914~~~ 3915 3916Example request with `cluster_name`: 3917 3918~~ 3919{ 3920 "params": { 3921 "pool_name": "rbd", 3922 "rbd_name": "foo", 3923 "block_size": 4096, 3924 "cluster_name": "rbd_cluster" 3925 }, 3926 "jsonrpc": "2.0", 3927 "method": "bdev_rbd_create", 3928 "id": 1 3929} 3930~~ 3931 3932Example response: 3933 3934~~ 3935response: 3936{ 3937 "jsonrpc": "2.0", 3938 "id": 1, 3939 "result": "Ceph0" 3940} 3941~~ 3942 3943### bdev_rbd_delete {#rpc_bdev_rbd_delete} 3944 3945Delete @ref bdev_config_rbd bdev 3946 3947This method is available only if SPDK was build with Ceph RBD support. 3948 3949#### Result 3950 3951`true` if bdev with provided name was deleted or `false` otherwise. 3952 3953#### Parameters 3954 3955Name | Optional | Type | Description 3956----------------------- | -------- | ----------- | ----------- 3957name | Required | string | Bdev name 3958 3959#### Example 3960 3961Example request: 3962 3963~~~json 3964{ 3965 "params": { 3966 "name": "Rbd0" 3967 }, 3968 "jsonrpc": "2.0", 3969 "method": "bdev_rbd_delete", 3970 "id": 1 3971} 3972~~~ 3973 3974Example response: 3975 3976~~~json 3977{ 3978 "jsonrpc": "2.0", 3979 "id": 1, 3980 "result": true 3981} 3982~~~ 3983 3984### bdev_rbd_resize {#rpc_bdev_rbd_resize} 3985 3986Resize @ref bdev_config_rbd bdev 3987 3988This method is available only if SPDK was build with Ceph RBD support. 3989 3990#### Result 3991 3992`true` if bdev with provided name was resized or `false` otherwise. 3993 3994#### Parameters 3995 3996Name | Optional | Type | Description 3997----------------------- | -------- | ----------- | ----------- 3998name | Required | string | Bdev name 3999new_size | Required | int | New bdev size for resize operation in MiB 4000 4001#### Example 4002 4003Example request: 4004 4005~~~json 4006{ 4007 "params": { 4008 "name": "Rbd0" 4009 "new_size": "4096" 4010 }, 4011 "jsonrpc": "2.0", 4012 "method": "bdev_rbd_resize", 4013 "id": 1 4014} 4015~~~ 4016 4017Example response: 4018 4019~~~json 4020{ 4021 "jsonrpc": "2.0", 4022 "id": 1, 4023 "result": true 4024} 4025~~~ 4026 4027### bdev_delay_create {#rpc_bdev_delay_create} 4028 4029Create delay bdev. This bdev type redirects all IO to it's base bdev and inserts a delay on the completion 4030path to create an artificial drive latency. All latency values supplied to this bdev should be in microseconds. 4031 4032#### Parameters 4033 4034Name | Optional | Type | Description 4035----------------------- | -------- | ----------- | ----------- 4036name | Required | string | Bdev name 4037base_bdev_name | Required | string | Base bdev name 4038avg_read_latency | Required | number | average read latency (us) 4039p99_read_latency | Required | number | p99 read latency (us) 4040avg_write_latency | Required | number | average write latency (us) 4041p99_write_latency | Required | number | p99 write latency (us) 4042 4043#### Result 4044 4045Name of newly created bdev. 4046 4047#### Example 4048 4049Example request: 4050 4051~~~json 4052{ 4053 "params": { 4054 "base_bdev_name": "Null0", 4055 "name": "Delay0", 4056 "avg_read_latency": "15", 4057 "p99_read_latency": "50", 4058 "avg_write_latency": "40", 4059 "p99_write_latency": "110", 4060 }, 4061 "jsonrpc": "2.0", 4062 "method": "bdev_delay_create", 4063 "id": 1 4064} 4065~~~ 4066 4067Example response: 4068 4069~~~json 4070{ 4071 "jsonrpc": "2.0", 4072 "id": 1, 4073 "result": "Delay0" 4074} 4075~~~ 4076 4077### bdev_delay_delete {#rpc_bdev_delay_delete} 4078 4079Delete delay bdev. 4080 4081#### Parameters 4082 4083Name | Optional | Type | Description 4084----------------------- | -------- | ----------- | ----------- 4085name | Required | string | Bdev name 4086 4087#### Example 4088 4089Example request: 4090 4091~~~json 4092{ 4093 "params": { 4094 "name": "Delay0" 4095 }, 4096 "jsonrpc": "2.0", 4097 "method": "bdev_delay_delete", 4098 "id": 1 4099} 4100 4101~~~ 4102 4103Example response: 4104 4105~~~json 4106{ 4107 "jsonrpc": "2.0", 4108 "id": 1, 4109 "result": true 4110} 4111~~~ 4112 4113### bdev_delay_update_latency {#rpc_bdev_delay_update_latency} 4114 4115Update a target latency value associated with a given delay bdev. Any currently 4116outstanding I/O will be completed with the old latency. 4117 4118#### Parameters 4119 4120Name | Optional | Type | Description 4121----------------------- | -------- | ----------- | ----------- 4122delay_bdev_name | Required | string | Name of the delay bdev 4123latency_type | Required | string | One of: avg_read, avg_write, p99_read, p99_write 4124latency_us | Required | number | The new latency value in microseconds 4125 4126#### Result 4127 4128Name of newly created bdev. 4129 4130#### Example 4131 4132Example request: 4133 4134~~~json 4135{ 4136 "params": { 4137 "delay_bdev_name": "Delay0", 4138 "latency_type": "avg_read", 4139 "latency_us": "100", 4140 }, 4141 "jsonrpc": "2.0", 4142 "method": "bdev_delay_update_latency", 4143 "id": 1 4144} 4145~~~ 4146 4147Example response: 4148 4149~~~json 4150{ 4151 "result": "true" 4152} 4153~~~ 4154 4155### bdev_error_create {#rpc_bdev_error_create} 4156 4157Construct error bdev. 4158 4159#### Parameters 4160 4161Name | Optional | Type | Description 4162----------------------- | -------- | ----------- | ----------- 4163base_name | Required | string | Base bdev name 4164 4165#### Example 4166 4167Example request: 4168 4169~~~json 4170{ 4171 "params": { 4172 "base_name": "Malloc0" 4173 }, 4174 "jsonrpc": "2.0", 4175 "method": "bdev_error_create", 4176 "id": 1 4177} 4178~~~ 4179 4180Example response: 4181 4182~~~json 4183{ 4184 "jsonrpc": "2.0", 4185 "id": 1, 4186 "result": true 4187} 4188~~~ 4189 4190### bdev_error_delete {#rpc_bdev_error_delete} 4191 4192Delete error bdev 4193 4194#### Result 4195 4196`true` if bdev with provided name was deleted or `false` otherwise. 4197 4198#### Parameters 4199 4200Name | Optional | Type | Description 4201----------------------- | -------- | ----------- | ----------- 4202name | Required | string | Error bdev name 4203 4204#### Example 4205 4206Example request: 4207 4208~~~json 4209{ 4210 "params": { 4211 "name": "EE_Malloc0" 4212 }, 4213 "jsonrpc": "2.0", 4214 "method": "bdev_error_delete", 4215 "id": 1 4216} 4217~~~ 4218 4219Example response: 4220 4221~~~json 4222{ 4223 "jsonrpc": "2.0", 4224 "id": 1, 4225 "result": true 4226} 4227~~~ 4228 4229### bdev_error_inject_error {#rpc_bdev_error_inject_error} 4230 4231Inject an error via an error bdev. Create an error bdev on base bdev first. Default 'num' 4232value is 1 and if 'num' is set to zero, the specified injection is disabled. 4233 4234#### Parameters 4235 4236Name | Optional | Type | Description 4237----------------------- | -------- | ----------- | ----------- 4238name | Required | string | Name of the error injection bdev 4239io_type | Required | string | io type 'clear' 'read' 'write' 'unmap' 'flush' 'all' 4240error_type | Required | string | error type 'failure' 'pending' 4241num | Optional | int | the number of commands you want to fail.(default:1) 4242 4243#### Example 4244 4245Example request: 4246 4247~~~json 4248{ 4249 "jsonrpc": "2.0", 4250 "method": "bdev_error_inject_error", 4251 "id": 1, 4252 "params": { 4253 "name": "EE_Malloc0", 4254 "io_type": "write", 4255 "error_type": "pending", 4256 "num": 1 4257 } 4258} 4259~~~ 4260 4261Example response: 4262 4263~~~json 4264{ 4265 "jsonrpc": "2.0", 4266 "id": 1, 4267 "result": true 4268} 4269~~~ 4270 4271### bdev_iscsi_create {#rpc_bdev_iscsi_create} 4272 4273Connect to iSCSI target and create bdev backed by this connection. 4274 4275This method is available only if SPDK was build with iSCSI initiator support. 4276 4277#### Parameters 4278 4279Name | Optional | Type | Description 4280----------------------- | -------- | ----------- | ----------- 4281name | Required | string | Bdev name 4282initiator_iqn | Required | string | IQN name used during connection 4283url | Required | string | iSCSI resource URI 4284 4285#### Result 4286 4287Name of newly created bdev. 4288 4289#### Example 4290 4291Example request: 4292 4293~~~json 4294{ 4295 "params": { 4296 "url": "iscsi://127.0.0.1/iqn.2016-06.io.spdk:disk1/0", 4297 "initiator_iqn": "iqn.2016-06.io.spdk:init", 4298 "name": "iSCSI0" 4299 }, 4300 "jsonrpc": "2.0", 4301 "method": "bdev_iscsi_create", 4302 "id": 1 4303} 4304~~~ 4305 4306Example response: 4307 4308~~~json 4309{ 4310 "jsonrpc": "2.0", 4311 "id": 1, 4312 "result": "iSCSI0" 4313} 4314~~~ 4315 4316### bdev_iscsi_delete {#rpc_bdev_iscsi_delete} 4317 4318Delete iSCSI bdev and terminate connection to target. 4319 4320This method is available only if SPDK was built with iSCSI initiator support. 4321 4322#### Parameters 4323 4324Name | Optional | Type | Description 4325----------------------- | -------- | ----------- | ----------- 4326name | Required | string | Bdev name 4327 4328#### Example 4329 4330Example request: 4331 4332~~~json 4333{ 4334 "params": { 4335 "name": "iSCSI0" 4336 }, 4337 "jsonrpc": "2.0", 4338 "method": "bdev_iscsi_delete", 4339 "id": 1 4340} 4341~~~ 4342 4343Example response: 4344 4345~~~json 4346{ 4347 "jsonrpc": "2.0", 4348 "id": 1, 4349 "result": true 4350} 4351~~~ 4352 4353### bdev_ftl_create {#rpc_bdev_ftl_create} 4354 4355Create FTL bdev. 4356 4357This RPC is subject to change. 4358 4359#### Parameters 4360 4361Name | Optional | Type | Description 4362----------------------- | -------- | ----------- | ----------- 4363name | Required | string | Bdev name 4364trtype | Required | string | Transport type 4365traddr | Required | string | NVMe target address 4366punits | Required | string | Parallel unit range in the form of start-end e.g 4-8 4367uuid | Optional | string | UUID of restored bdev (not applicable when creating new instance) 4368cache | Optional | string | Name of the bdev to be used as a write buffer cache 4369 4370#### Result 4371 4372Name of newly created bdev. 4373 4374#### Example 4375 4376Example request: 4377 4378~~~json 4379{ 4380 "params": { 4381 "name": "nvme0" 4382 "trtype" "pcie" 4383 "traddr": "0000:00:04.0" 4384 "punits": "0-3" 4385 "uuid": "4a7481ce-786f-41a0-9b86-8f7465c8f4d3" 4386 }, 4387 "jsonrpc": "2.0", 4388 "method": "bdev_ftl_create", 4389 "id": 1 4390} 4391~~~ 4392 4393Example response: 4394 4395~~~json 4396{ 4397 "jsonrpc": "2.0", 4398 "id": 1, 4399 "result": { 4400 "name" : "nvme0" 4401 "uuid" : "4a7481ce-786f-41a0-9b86-8f7465c8f4d3" 4402 } 4403} 4404~~~ 4405 4406### bdev_ftl_delete {#rpc_bdev_ftl_delete} 4407 4408Delete FTL bdev. 4409 4410This RPC is subject to change. 4411 4412#### Parameters 4413 4414Name | Optional | Type | Description 4415----------------------- | -------- | ----------- | ----------- 4416name | Required | string | Bdev name 4417 4418#### Example 4419 4420Example request: 4421 4422~~~json 4423{ 4424 "params": { 4425 "name": "nvme0" 4426 }, 4427 "jsonrpc": "2.0", 4428 "method": "bdev_ftl_delete", 4429 "id": 1 4430} 4431~~~ 4432 4433Example response: 4434 4435~~~json 4436{ 4437 "jsonrpc": "2.0", 4438 "id": 1, 4439 "result": true 4440} 4441~~~ 4442 4443### bdev_pmem_create_pool {#rpc_bdev_pmem_create_pool} 4444 4445Create a @ref bdev_config_pmem blk pool file. It is equivalent of following `pmempool create` command: 4446 4447~~~bash 4448pmempool create -s $((num_blocks * block_size)) blk $block_size $pmem_file 4449~~~ 4450 4451This method is available only if SPDK was built with PMDK support. 4452 4453#### Parameters 4454 4455Name | Optional | Type | Description 4456----------------------- | -------- | ----------- | ----------- 4457pmem_file | Required | string | Path to new pmem file 4458num_blocks | Required | number | Number of blocks 4459block_size | Required | number | Size of each block in bytes 4460 4461#### Example 4462 4463Example request: 4464 4465~~~json 4466{ 4467 "params": { 4468 "block_size": 512, 4469 "num_blocks": 131072, 4470 "pmem_file": "/tmp/pmem_file" 4471 }, 4472 "jsonrpc": "2.0", 4473 "method": "bdev_pmem_create_pool", 4474 "id": 1 4475} 4476~~~ 4477 4478Example response: 4479 4480~~~json 4481{ 4482 "jsonrpc": "2.0", 4483 "id": 1, 4484 "result": true 4485} 4486~~~ 4487 4488### bdev_pmem_get_pool_info {#rpc_bdev_pmem_get_pool_info} 4489 4490Retrieve basic information about PMDK memory pool. 4491 4492This method is available only if SPDK was built with PMDK support. 4493 4494#### Parameters 4495 4496Name | Optional | Type | Description 4497----------------------- | -------- | ----------- | ----------- 4498pmem_file | Required | string | Path to existing pmem file 4499 4500#### Result 4501 4502Array of objects describing memory pool: 4503 4504Name | Type | Description 4505----------------------- | ----------- | ----------- 4506num_blocks | number | Number of blocks 4507block_size | number | Size of each block in bytes 4508 4509#### Example 4510 4511Example request: 4512 4513~~~json 4514request: 4515{ 4516 "params": { 4517 "pmem_file": "/tmp/pmem_file" 4518 }, 4519 "jsonrpc": "2.0", 4520 "method": "bdev_pmem_get_pool_info", 4521 "id": 1 4522} 4523~~~ 4524 4525Example response: 4526 4527~~~json 4528{ 4529 "jsonrpc": "2.0", 4530 "id": 1, 4531 "result": [ 4532 { 4533 "block_size": 512, 4534 "num_blocks": 129728 4535 } 4536 ] 4537} 4538~~~ 4539 4540### bdev_pmem_delete_pool {#rpc_bdev_pmem_delete_pool} 4541 4542Delete pmem pool by removing file `pmem_file`. This method will fail if `pmem_file` is not a 4543valid pmem pool file. 4544 4545This method is available only if SPDK was built with PMDK support. 4546 4547#### Parameters 4548 4549Name | Optional | Type | Description 4550----------------------- | -------- | ----------- | ----------- 4551pmem_file | Required | string | Path to new pmem file 4552 4553#### Example 4554 4555Example request: 4556 4557~~~json 4558{ 4559 "params": { 4560 "pmem_file": "/tmp/pmem_file" 4561 }, 4562 "jsonrpc": "2.0", 4563 "method": "bdev_pmem_delete_pool", 4564 "id": 1 4565} 4566~~~ 4567 4568Example response: 4569 4570~~~json 4571{ 4572 "jsonrpc": "2.0", 4573 "id": 1, 4574 "result": true 4575} 4576~~~ 4577 4578### bdev_pmem_create {#rpc_bdev_pmem_create} 4579 4580Construct @ref bdev_config_pmem bdev. 4581 4582This method is available only if SPDK was built with PMDK support. 4583 4584#### Parameters 4585 4586Name | Optional | Type | Description 4587----------------------- | -------- | ----------- | ----------- 4588name | Required | string | Bdev name 4589pmem_file | Required | string | Path to existing pmem blk pool file 4590 4591#### Result 4592 4593Name of newly created bdev. 4594 4595#### Example 4596 4597Example request: 4598 4599~~~json 4600{ 4601 "params": { 4602 "pmem_file": "/tmp/pmem_file", 4603 "name": "Pmem0" 4604 }, 4605 "jsonrpc": "2.0", 4606 "method": "bdev_pmem_create", 4607 "id": 1 4608} 4609~~~ 4610 4611Example response: 4612 4613~~~json 4614{ 4615 "jsonrpc": "2.0", 4616 "id": 1, 4617 "result": "Pmem0" 4618} 4619~~~ 4620 4621### bdev_pmem_delete {#rpc_bdev_pmem_delete} 4622 4623Delete @ref bdev_config_pmem bdev. This call will not remove backing pool files. 4624 4625This method is available only if SPDK was built with PMDK support. 4626 4627#### Result 4628 4629`true` if bdev with provided name was deleted or `false` otherwise. 4630 4631#### Parameters 4632 4633Name | Optional | Type | Description 4634----------------------- | -------- | ----------- | ----------- 4635name | Required | string | Bdev name 4636 4637#### Example 4638 4639Example request: 4640 4641~~~json 4642{ 4643 "params": { 4644 "name": "Pmem0" 4645 }, 4646 "jsonrpc": "2.0", 4647 "method": "bdev_pmem_delete", 4648 "id": 1 4649} 4650~~~ 4651 4652Example response: 4653 4654~~~json 4655{ 4656 "jsonrpc": "2.0", 4657 "id": 1, 4658 "result": true 4659} 4660~~~ 4661 4662### bdev_passthru_create {#rpc_bdev_passthru_create} 4663 4664Create passthru bdev. This bdev type redirects all IO to it's base bdev. It has no other purpose than being an example 4665and a starting point in development of new bdev type. 4666 4667#### Parameters 4668 4669Name | Optional | Type | Description 4670----------------------- | -------- | ----------- | ----------- 4671name | Required | string | Bdev name 4672base_bdev_name | Required | string | Base bdev name 4673 4674#### Result 4675 4676Name of newly created bdev. 4677 4678#### Example 4679 4680Example request: 4681 4682~~~json 4683{ 4684 "params": { 4685 "base_bdev_name": "Malloc0", 4686 "name": "Passsthru0" 4687 }, 4688 "jsonrpc": "2.0", 4689 "method": "bdev_passthru_create", 4690 "id": 1 4691} 4692~~~ 4693 4694Example response: 4695 4696~~~json 4697{ 4698 "jsonrpc": "2.0", 4699 "id": 1, 4700 "result": "Passsthru0" 4701} 4702~~~ 4703 4704### bdev_passthru_delete {#rpc_bdev_passthru_delete} 4705 4706Delete passthru bdev. 4707 4708#### Parameters 4709 4710Name | Optional | Type | Description 4711----------------------- | -------- | ----------- | ----------- 4712name | Required | string | Bdev name 4713 4714#### Example 4715 4716Example request: 4717 4718~~~json 4719{ 4720 "params": { 4721 "name": "Passsthru0" 4722 }, 4723 "jsonrpc": "2.0", 4724 "method": "bdev_passthru_delete", 4725 "id": 1 4726} 4727 4728~~~ 4729 4730Example response: 4731 4732~~~json 4733{ 4734 "jsonrpc": "2.0", 4735 "id": 1, 4736 "result": true 4737} 4738~~~ 4739 4740### bdev_virtio_attach_controller {#rpc_bdev_virtio_attach_controller} 4741 4742Create new initiator @ref bdev_config_virtio_scsi or @ref bdev_config_virtio_blk and expose all found bdevs. 4743 4744#### Parameters 4745 4746Name | Optional | Type | Description 4747----------------------- | -------- | ----------- | ----------- 4748name | Required | string | Virtio SCSI base bdev name or Virtio Blk bdev name 4749trtype | Required | string | Virtio target trtype: pci or user 4750traddr | Required | string | target address: BDF or UNIX socket file path 4751dev_type | Required | string | Virtio device type: blk or scsi 4752vq_count | Optional | number | Number of queues this controller will utilize (default: 1) 4753vq_size | Optional | number | Size of each queue. Must be power of 2. (default: 512) 4754 4755In case of Virtio SCSI the `name` parameter will be base name for new created bdevs. For Virtio Blk `name` will be the 4756name of created bdev. 4757 4758`vq_count` and `vq_size` parameters are valid only if `trtype` is `user`. 4759 4760#### Result 4761 4762Array of names of newly created bdevs. 4763 4764#### Example 4765 4766Example request: 4767 4768~~~json 4769{ 4770 "params": { 4771 "name": "VirtioScsi0", 4772 "trtype": "user", 4773 "vq_size": 128, 4774 "dev_type": "scsi", 4775 "traddr": "/tmp/VhostScsi0", 4776 "vq_count": 4 4777 }, 4778 "jsonrpc": "2.0", 4779 "method": "bdev_virtio_attach_controller", 4780 "id": 1 4781} 4782~~~ 4783 4784Example response: 4785 4786~~~json 4787{ 4788 "jsonrpc": "2.0", 4789 "id": 1, 4790 "result": ["VirtioScsi0t2", "VirtioScsi0t4"] 4791} 4792~~~ 4793 4794### bdev_virtio_scsi_get_devices {#rpc_bdev_virtio_scsi_get_devices} 4795 4796Show information about all available Virtio SCSI devices. 4797 4798#### Parameters 4799 4800This method has no parameters. 4801 4802#### Result 4803 4804Array of Virtio SCSI information objects. 4805 4806#### Example 4807 4808Example request: 4809 4810~~~json 4811{ 4812 "jsonrpc": "2.0", 4813 "method": "bdev_virtio_scsi_get_devices", 4814 "id": 1 4815} 4816~~~ 4817 4818Example response: 4819 4820~~~json 4821{ 4822 "jsonrpc": "2.0", 4823 "id": 1, 4824 "result": [ 4825 { 4826 "name": "VirtioScsi0", 4827 "virtio": { 4828 "vq_size": 128, 4829 "vq_count": 4, 4830 "type": "user", 4831 "socket": "/tmp/VhostScsi0" 4832 } 4833 } 4834 ] 4835} 4836~~~ 4837 4838### bdev_virtio_detach_controller {#rpc_bdev_virtio_detach_controller} 4839 4840Remove a Virtio device. This command can be used to remove any type of virtio device. 4841 4842#### Parameters 4843 4844Name | Optional | Type | Description 4845----------------------- | -------- | ----------- | ----------- 4846name | Required | string | Virtio name 4847 4848#### Example 4849 4850Example request: 4851 4852~~~json 4853{ 4854 "params": { 4855 "name": "VirtioUser0" 4856 }, 4857 "jsonrpc": "2.0", 4858 "method": "bdev_virtio_detach_controller", 4859 "id": 1 4860} 4861 4862~~~ 4863 4864Example response: 4865 4866~~~json 4867{ 4868 "jsonrpc": "2.0", 4869 "id": 1, 4870 "result": true 4871} 4872~~~ 4873 4874### bdev_virtio_blk_set_hotplug {#rpc_bdev_virtio_blk_set_hotplug} 4875 4876Enable/Disable the virtio blk hotplug monitor or change the monitor period time 4877 4878#### Parameters 4879 4880Name | Optional | Type | Description 4881----------------------- | -------- | ----------- | ----------- 4882enable | Required | bool | Enable or disable the virtio blk hotplug monitor 4883period-us | Optional | number | The period time of the monitor 4884 4885When the enable is true then the period-us is optional. If user don't set the period time then use the default 4886value. When the enable is false then the period-us is not required. 4887 4888#### Result 4889 4890True the rpc is successful otherwise false 4891 4892#### Example 4893 4894Example request: 4895 4896~~~json 4897{ 4898 "params": { 4899 "enable": "true", 4900 "period-us": "1000000" 4901 }, 4902 "jsonrpc": "2.0", 4903 "method": "bdev_virtio_blk_set_hotplug", 4904 "id": 1 4905} 4906~~~ 4907 4908Example response: 4909 4910~~~json 4911{ 4912 "jsonrpc": "2.0", 4913 "id": 1, 4914 "result": true 4915} 4916~~~ 4917 4918## iSCSI Target {#jsonrpc_components_iscsi_tgt} 4919 4920### iscsi_set_options method {#rpc_iscsi_set_options} 4921 4922Set global parameters for iSCSI targets. 4923 4924This RPC may only be called before SPDK subsystems have been initialized. This RPC can be called only once. 4925 4926#### Parameters 4927 4928Name | Optional | Type | Description 4929------------------------------- | -------- | ------- | ----------- 4930auth_file | Optional | string | Path to CHAP shared secret file (default: "") 4931node_base | Optional | string | Prefix of the name of iSCSI target node (default: "iqn.2016-06.io.spdk") 4932nop_timeout | Optional | number | Timeout in seconds to nop-in request to the initiator (default: 60) 4933nop_in_interval | Optional | number | Time interval in secs between nop-in requests by the target (default: 30) 4934disable_chap | Optional | boolean | CHAP for discovery session should be disabled (default: `false`) 4935require_chap | Optional | boolean | CHAP for discovery session should be required (default: `false`) 4936mutual_chap | Optional | boolean | CHAP for discovery session should be unidirectional (`false`) or bidirectional (`true`) (default: `false`) 4937chap_group | Optional | number | CHAP group ID for discovery session (default: 0) 4938max_sessions | Optional | number | Maximum number of sessions in the host (default: 128) 4939max_queue_depth | Optional | number | Maximum number of outstanding I/Os per queue (default: 64) 4940max_connections_per_session | Optional | number | Session specific parameter, MaxConnections (default: 2) 4941default_time2wait | Optional | number | Session specific parameter, DefaultTime2Wait (default: 2) 4942default_time2retain | Optional | number | Session specific parameter, DefaultTime2Retain (default: 20) 4943first_burst_length | Optional | number | Session specific parameter, FirstBurstLength (default: 8192) 4944immediate_data | Optional | boolean | Session specific parameter, ImmediateData (default: `true`) 4945error_recovery_level | Optional | number | Session specific parameter, ErrorRecoveryLevel (default: 0) 4946allow_duplicated_isid | Optional | boolean | Allow duplicated initiator session ID (default: `false`) 4947max_large_datain_per_connection | Optional | number | Max number of outstanding split read I/Os per connection (default: 64) 4948max_r2t_per_connection | Optional | number | Max number of outstanding R2Ts per connection (default: 4) 4949pdu_pool_size | Optional | number | Number of PDUs in the pool (default: approximately 2 * max_sessions * (max_queue_depth + max_connections_per_session)) 4950immediate_data_pool_size | Optional | number | Number of immediate data buffers in the pool (default: 128 * max_sessions) 4951data_out_pool_size | Optional | number | Number of data out buffers in the pool (default: 16 * max_sessions) 4952 4953To load CHAP shared secret file, its path is required to specify explicitly in the parameter `auth_file`. 4954 4955Parameters `disable_chap` and `require_chap` are mutually exclusive. Parameters `no_discovery_auth`, `req_discovery_auth`, 4956`req_discovery_auth_mutual`, and `discovery_auth_group` are still available instead of `disable_chap`, `require_chap`, 4957`mutual_chap`, and `chap_group`, respectivey but will be removed in future releases. 4958 4959#### Example 4960 4961Example request: 4962 4963~~~json 4964{ 4965 "params": { 4966 "allow_duplicated_isid": true, 4967 "default_time2retain": 60, 4968 "first_burst_length": 8192, 4969 "immediate_data": true, 4970 "node_base": "iqn.2016-06.io.spdk", 4971 "max_sessions": 128, 4972 "nop_timeout": 30, 4973 "nop_in_interval": 30, 4974 "auth_file": "/usr/local/etc/spdk/auth.conf", 4975 "disable_chap": true, 4976 "default_time2wait": 2 4977 }, 4978 "jsonrpc": "2.0", 4979 "method": "iscsi_set_options", 4980 "id": 1 4981} 4982~~~ 4983 4984Example response: 4985 4986~~~json 4987{ 4988 "jsonrpc": "2.0", 4989 "id": 1, 4990 "result": true 4991} 4992~~~ 4993 4994### iscsi_get_options method {#rpc_iscsi_get_options} 4995 4996Show global parameters of iSCSI targets. 4997 4998#### Parameters 4999 5000This method has no parameters. 5001 5002#### Example 5003 5004Example request: 5005 5006~~~json 5007request: 5008{ 5009 "jsonrpc": "2.0", 5010 "method": "iscsi_get_options", 5011 "id": 1 5012} 5013~~~ 5014 5015Example response: 5016 5017~~~json 5018{ 5019 "jsonrpc": "2.0", 5020 "id": 1, 5021 "result": { 5022 "allow_duplicated_isid": true, 5023 "default_time2retain": 60, 5024 "first_burst_length": 8192, 5025 "immediate_data": true, 5026 "node_base": "iqn.2016-06.io.spdk", 5027 "mutual_chap": false, 5028 "nop_in_interval": 30, 5029 "chap_group": 0, 5030 "max_connections_per_session": 2, 5031 "max_queue_depth": 64, 5032 "nop_timeout": 30, 5033 "max_sessions": 128, 5034 "error_recovery_level": 0, 5035 "auth_file": "/usr/local/etc/spdk/auth.conf", 5036 "disable_chap": true, 5037 "default_time2wait": 2, 5038 "require_chap": false, 5039 "max_large_datain_per_connection": 64, 5040 "max_r2t_per_connection": 4 5041 } 5042} 5043~~~ 5044 5045### scsi_get_devices {#rpc_scsi_get_devices} 5046 5047Display SCSI devices 5048 5049#### Parameters 5050 5051This method has no parameters. 5052 5053#### Example 5054 5055Example request: 5056 5057~~~json 5058{ 5059 "jsonrpc": "2.0", 5060 "method": "scsi_get_devices", 5061 "id": 1 5062} 5063~~~ 5064 5065Example response: 5066 5067~~~json 5068{ 5069 "jsonrpc": "2.0", 5070 "id": 1, 5071 "result": [ 5072 { 5073 "id": 0, 5074 "device_name": "iqn.2016-06.io.spdk:Target3" 5075 } 5076 ] 5077} 5078~~~ 5079 5080### iscsi_set_discovery_auth method {#rpc_iscsi_set_discovery_auth} 5081 5082Set CHAP authentication for sessions dynamically. 5083 5084#### Parameters 5085 5086Name | Optional | Type | Description 5087--------------------------- | -------- | --------| ----------- 5088disable_chap | Optional | boolean | CHAP for discovery session should be disabled (default: `false`) 5089require_chap | Optional | boolean | CHAP for discovery session should be required (default: `false`) 5090mutual_chap | Optional | boolean | CHAP for discovery session should be unidirectional (`false`) or bidirectional (`true`) (default: `false`) 5091chap_group | Optional | number | CHAP group ID for discovery session (default: 0) 5092 5093Parameters `disable_chap` and `require_chap` are mutually exclusive. 5094 5095#### Example 5096 5097Example request: 5098 5099~~~json 5100request: 5101{ 5102 "params": { 5103 "chap_group": 1, 5104 "require_chap": true, 5105 "mutual_chap": true 5106 }, 5107 "jsonrpc": "2.0", 5108 "method": "iscsi_set_discovery_auth", 5109 "id": 1 5110} 5111~~~ 5112 5113Example response: 5114 5115~~~json 5116{ 5117 "jsonrpc": "2.0", 5118 "id": 1, 5119 "result": true 5120} 5121~~~ 5122 5123### iscsi_create_auth_group method {#rpc_iscsi_create_auth_group} 5124 5125Create an authentication group for CHAP authentication. 5126 5127#### Parameters 5128 5129Name | Optional | Type | Description 5130--------------------------- | -------- | --------| ----------- 5131tag | Required | number | Authentication group tag (unique, integer > 0) 5132secrets | Optional | array | Array of @ref rpc_iscsi_create_auth_group_secret objects 5133 5134#### secret {#rpc_iscsi_create_auth_group_secret} 5135 5136Name | Optional | Type | Description 5137--------------------------- | ---------| --------| ----------- 5138user | Required | string | Unidirectional CHAP name 5139secret | Required | string | Unidirectional CHAP secret 5140muser | Optional | string | Bidirectional CHAP name 5141msecret | Optional | string | Bidirectional CHAP secret 5142 5143#### Example 5144 5145Example request: 5146 5147~~~json 5148{ 5149 "params": { 5150 "secrets": [ 5151 { 5152 "muser": "mu1", 5153 "secret": "s1", 5154 "user": "u1", 5155 "msecret": "ms1" 5156 } 5157 ], 5158 "tag": 2 5159 }, 5160 "jsonrpc": "2.0", 5161 "method": "iscsi_create_auth_group", 5162 "id": 1 5163} 5164~~~ 5165 5166Example response: 5167 5168~~~json 5169{ 5170 "jsonrpc": "2.0", 5171 "id": 1, 5172 "result": true 5173} 5174~~~ 5175 5176### iscsi_delete_auth_group method {#rpc_iscsi_delete_auth_group} 5177 5178Delete an existing authentication group for CHAP authentication. 5179 5180#### Parameters 5181 5182Name | Optional | Type | Description 5183--------------------------- | -------- | --------| ----------- 5184tag | Required | number | Authentication group tag (unique, integer > 0) 5185 5186#### Example 5187 5188Example request: 5189 5190~~~json 5191{ 5192 "params": { 5193 "tag": 2 5194 }, 5195 "jsonrpc": "2.0", 5196 "method": "iscsi_delete_auth_group", 5197 "id": 1 5198} 5199~~~ 5200 5201Example response: 5202 5203~~~json 5204{ 5205 "jsonrpc": "2.0", 5206 "id": 1, 5207 "result": true 5208} 5209~~~ 5210 5211### iscsi_get_auth_groups {#rpc_iscsi_get_auth_groups} 5212 5213Show information about all existing authentication group for CHAP authentication. 5214 5215#### Parameters 5216 5217This method has no parameters. 5218 5219#### Result 5220 5221Array of objects describing authentication group. 5222 5223Name | Type | Description 5224--------------------------- | --------| ----------- 5225tag | number | Authentication group tag 5226secrets | array | Array of @ref rpc_iscsi_create_auth_group_secret objects 5227 5228#### Example 5229 5230Example request: 5231 5232~~~json 5233{ 5234 "jsonrpc": "2.0", 5235 "method": "iscsi_get_auth_groups", 5236 "id": 1 5237} 5238~~~ 5239 5240Example response: 5241 5242~~~json 5243{ 5244 "jsonrpc": "2.0", 5245 "id": 1, 5246 "result": [ 5247 { 5248 "secrets": [ 5249 { 5250 "muser": "mu1", 5251 "secret": "s1", 5252 "user": "u1", 5253 "msecret": "ms1" 5254 } 5255 ], 5256 "tag": 1 5257 }, 5258 { 5259 "secrets": [ 5260 { 5261 "secret": "s2", 5262 "user": "u2" 5263 } 5264 ], 5265 "tag": 2 5266 } 5267 ] 5268} 5269~~~ 5270 5271### iscsi_auth_group_add_secret {#rpc_iscsi_auth_group_add_secret} 5272 5273Add a secret to an existing authentication group for CHAP authentication. 5274 5275#### Parameters 5276 5277Name | Optional | Type | Description 5278--------------------------- | -------- | --------| ----------- 5279tag | Required | number | Authentication group tag (unique, integer > 0) 5280user | Required | string | Unidirectional CHAP name 5281secret | Required | string | Unidirectional CHAP secret 5282muser | Optional | string | Bidirectional CHAP name 5283msecret | Optional | string | Bidirectional CHAP secret 5284 5285#### Example 5286 5287Example request: 5288 5289~~~json 5290{ 5291 "params": { 5292 "muser": "mu3", 5293 "secret": "s3", 5294 "tag": 2, 5295 "user": "u3", 5296 "msecret": "ms3" 5297 }, 5298 "jsonrpc": "2.0", 5299 "method": "iscsi_auth_group_add_secret", 5300 "id": 1 5301} 5302~~~json 5303 5304Example response: 5305 5306~~~json 5307{ 5308 "jsonrpc": "2.0", 5309 "id": 1, 5310 "result": true 5311} 5312~~~ 5313 5314### iscsi_auth_group_remove_secret {#rpc_iscsi_auth_group_remove_secret} 5315 5316Remove a secret from an existing authentication group for CHAP authentication. 5317 5318#### Parameters 5319 5320Name | Optional | Type | Description 5321--------------------------- | -------- | --------| ----------- 5322tag | Required | number | Authentication group tag (unique, integer > 0) 5323user | Required | string | Unidirectional CHAP name 5324 5325#### Example 5326 5327Example request: 5328 5329~~~json 5330{ 5331 "params": { 5332 "tag": 2, 5333 "user": "u3" 5334 }, 5335 "jsonrpc": "2.0", 5336 "method": "iscsi_auth_group_remove_secret", 5337 "id": 1 5338} 5339~~~ 5340 5341Example response: 5342 5343~~~json 5344{ 5345 "jsonrpc": "2.0", 5346 "id": 1, 5347 "result": true 5348} 5349~~~ 5350 5351### iscsi_get_initiator_groups method {#rpc_iscsi_get_initiator_groups} 5352 5353Show information about all available initiator groups. 5354 5355#### Parameters 5356 5357This method has no parameters. 5358 5359#### Result 5360 5361Array of objects describing initiator groups. 5362 5363Name | Type | Description 5364--------------------------- | --------| ----------- 5365tag | number | Initiator group tag 5366initiators | array | Array of initiator hostnames or IP addresses 5367netmasks | array | Array of initiator netmasks 5368 5369#### Example 5370 5371Example request: 5372 5373~~~json 5374{ 5375 "jsonrpc": "2.0", 5376 "method": "iscsi_get_initiator_groups", 5377 "id": 1 5378} 5379~~~ 5380 5381Example response: 5382 5383~~~json 5384{ 5385 "jsonrpc": "2.0", 5386 "id": 1, 5387 "result": [ 5388 { 5389 "initiators": [ 5390 "iqn.2016-06.io.spdk:host1", 5391 "iqn.2016-06.io.spdk:host2" 5392 ], 5393 "tag": 1, 5394 "netmasks": [ 5395 "192.168.1.0/24" 5396 ] 5397 } 5398 ] 5399} 5400~~~ 5401 5402### iscsi_create_initiator_group method {#rpc_iscsi_create_initiator_group} 5403 5404Add an initiator group. 5405 5406#### Parameters 5407 5408Name | Optional | Type | Description 5409--------------------------- | -------- | --------| ----------- 5410tag | Required | number | Initiator group tag (unique, integer > 0) 5411initiators | Required | array | Not empty array of initiator hostnames or IP addresses 5412netmasks | Required | array | Not empty array of initiator netmasks 5413 5414#### Example 5415 5416Example request: 5417 5418~~~json 5419{ 5420 "params": { 5421 "initiators": [ 5422 "iqn.2016-06.io.spdk:host1", 5423 "iqn.2016-06.io.spdk:host2" 5424 ], 5425 "tag": 1, 5426 "netmasks": [ 5427 "192.168.1.0/24" 5428 ] 5429 }, 5430 "jsonrpc": "2.0", 5431 "method": "iscsi_create_initiator_group", 5432 "id": 1 5433} 5434~~~ 5435 5436Example response: 5437 5438~~~json 5439response: 5440{ 5441 "jsonrpc": "2.0", 5442 "id": 1, 5443 "result": true 5444} 5445~~~ 5446 5447### iscsi_delete_initiator_group method {#rpc_iscsi_delete_initiator_group} 5448 5449Delete an existing initiator group. 5450 5451#### Parameters 5452 5453Name | Optional | Type | Description 5454--------------------------- | -------- | --------| ----------- 5455tag | Required | number | Initiator group tag (unique, integer > 0) 5456 5457#### Example 5458 5459Example request: 5460 5461~~~json 5462{ 5463 "params": { 5464 "tag": 1 5465 }, 5466 "jsonrpc": "2.0", 5467 "method": "iscsi_delete_initiator_group", 5468 "id": 1 5469} 5470~~~ 5471 5472Example response: 5473 5474~~~json 5475{ 5476 "jsonrpc": "2.0", 5477 "id": 1, 5478 "result": true 5479} 5480~~~ 5481 5482### iscsi_initiator_group_add_initiators method {#rpc_iscsi_initiator_group_add_initiators} 5483 5484Add initiators to an existing initiator group. 5485 5486#### Parameters 5487 5488Name | Optional | Type | Description 5489--------------------------- | -------- | --------| ----------- 5490tag | Required | number | Existing initiator group tag. 5491initiators | Optional | array | Array of initiator hostnames or IP addresses 5492netmasks | Optional | array | Array of initiator netmasks 5493 5494#### Example 5495 5496Example request: 5497 5498~~~json 5499request: 5500{ 5501 "params": { 5502 "initiators": [ 5503 "iqn.2016-06.io.spdk:host3" 5504 ], 5505 "tag": 1, 5506 "netmasks": [ 5507 "255.255.255.1" 5508 ] 5509 }, 5510 "jsonrpc": "2.0", 5511 "method": "iscsi_initiator_group_add_initiators", 5512 "id": 1 5513} 5514~~~ 5515 5516Example response: 5517 5518~~~json 5519response: 5520{ 5521 "jsonrpc": "2.0", 5522 "id": 1, 5523 "result": true 5524} 5525~~~ 5526 5527### iscsi_initiator_group_remove_initiators method {#rpc_iscsi_initiator_group_remove_initiators} 5528 5529Remove initiators from an initiator group. 5530 5531#### Parameters 5532 5533Name | Optional | Type | Description 5534--------------------------- | -------- | --------| ----------- 5535tag | Required | number | Existing initiator group tag. 5536initiators | Optional | array | Array of initiator hostnames or IP addresses 5537netmasks | Optional | array | Array of initiator netmasks 5538 5539#### Example 5540 5541Example request: 5542 5543~~~json 5544request: 5545{ 5546 "params": { 5547 "initiators": [ 5548 "iqn.2016-06.io.spdk:host3" 5549 ], 5550 "tag": 1, 5551 "netmasks": [ 5552 "255.255.255.1" 5553 ] 5554 }, 5555 "jsonrpc": "2.0", 5556 "method": "iscsi_initiator_group_remove_initiators", 5557 "id": 1 5558} 5559~~~ 5560 5561Example response: 5562 5563~~~json 5564response: 5565{ 5566 "jsonrpc": "2.0", 5567 "id": 1, 5568 "result": true 5569} 5570~~~ 5571 5572### iscsi_get_target_nodes method {#rpc_iscsi_get_target_nodes} 5573 5574Show information about all available iSCSI target nodes. 5575 5576#### Parameters 5577 5578This method has no parameters. 5579 5580#### Result 5581 5582Array of objects describing target node. 5583 5584Name | Type | Description 5585--------------------------- | --------| ----------- 5586name | string | Target node name (ASCII) 5587alias_name | string | Target node alias name (ASCII) 5588pg_ig_maps | array | Array of Portal_Group_Tag:Initiator_Group_Tag mappings 5589luns | array | Array of Bdev names to LUN ID mappings 5590queue_depth | number | Target queue depth 5591disable_chap | boolean | CHAP authentication should be disabled for this target 5592require_chap | boolean | CHAP authentication should be required for this target 5593mutual_chap | boolean | CHAP authentication should be bidirectional (`true`) or unidirectional (`false`) 5594chap_group | number | Authentication group ID for this target node 5595header_digest | boolean | Header Digest should be required for this target node 5596data_digest | boolean | Data Digest should be required for this target node 5597 5598#### Example 5599 5600Example request: 5601 5602~~~json 5603{ 5604 "jsonrpc": "2.0", 5605 "method": "iscsi_get_target_nodes", 5606 "id": 1 5607} 5608~~~ 5609 5610Example response: 5611 5612~~~json 5613{ 5614 "jsonrpc": "2.0", 5615 "id": 1, 5616 "result": [ 5617 { 5618 "luns": [ 5619 { 5620 "lun_id": 0, 5621 "bdev_name": "Nvme0n1" 5622 } 5623 ], 5624 "mutual_chap": false, 5625 "name": "iqn.2016-06.io.spdk:target1", 5626 "alias_name": "iscsi-target1-alias", 5627 "require_chap": false, 5628 "chap_group": 0, 5629 "pg_ig_maps": [ 5630 { 5631 "ig_tag": 1, 5632 "pg_tag": 1 5633 } 5634 ], 5635 "data_digest": false, 5636 "disable_chap": false, 5637 "header_digest": false, 5638 "queue_depth": 64 5639 } 5640 ] 5641} 5642~~~ 5643 5644### iscsi_create_target_node method {#rpc_iscsi_create_target_node} 5645 5646Add an iSCSI target node. 5647 5648#### Parameters 5649 5650Name | Optional | Type | Description 5651--------------------------- | -------- | --------| ----------- 5652name | Required | string | Target node name (ASCII) 5653alias_name | Required | string | Target node alias name (ASCII) 5654pg_ig_maps | Required | array | Array of (Portal_Group_Tag:Initiator_Group_Tag) mappings 5655luns | Required | array | Array of Bdev names to LUN ID mappings 5656queue_depth | Required | number | Target queue depth 5657disable_chap | Optional | boolean | CHAP authentication should be disabled for this target 5658require_chap | Optional | boolean | CHAP authentication should be required for this target 5659mutual_chap | Optional | boolean | CHAP authentication should be bidirectional (`true`) or unidirectional (`false`) 5660chap_group | Optional | number | Authentication group ID for this target node 5661header_digest | Optional | boolean | Header Digest should be required for this target node 5662data_digest | Optional | boolean | Data Digest should be required for this target node 5663 5664Parameters `disable_chap` and `require_chap` are mutually exclusive. 5665 5666#### Example 5667 5668Example request: 5669 5670~~~json 5671{ 5672 "params": { 5673 "luns": [ 5674 { 5675 "lun_id": 0, 5676 "bdev_name": "Nvme0n1" 5677 } 5678 ], 5679 "mutual_chap": true, 5680 "name": "target2", 5681 "alias_name": "iscsi-target2-alias", 5682 "pg_ig_maps": [ 5683 { 5684 "ig_tag": 1, 5685 "pg_tag": 1 5686 }, 5687 { 5688 "ig_tag": 2, 5689 "pg_tag": 2 5690 } 5691 ], 5692 "data_digest": true, 5693 "disable_chap": true, 5694 "header_digest": true, 5695 "queue_depth": 24 5696 }, 5697 "jsonrpc": "2.0", 5698 "method": "iscsi_create_target_node", 5699 "id": 1 5700} 5701~~~ 5702 5703Example response: 5704 5705~~~json 5706{ 5707 "jsonrpc": "2.0", 5708 "id": 1, 5709 "result": true 5710} 5711~~~ 5712 5713### iscsi_target_node_set_auth method {#rpc_iscsi_target_node_set_auth} 5714 5715Set CHAP authentication to an existing iSCSI target node. 5716 5717#### Parameters 5718 5719Name | Optional | Type | Description 5720--------------------------- | -------- | --------| ----------- 5721name | Required | string | Target node name (ASCII) 5722disable_chap | Optional | boolean | CHAP authentication should be disabled for this target 5723require_chap | Optional | boolean | CHAP authentication should be required for this target 5724mutual_chap | Optional | boolean | CHAP authentication should be bidirectional (`true`) or unidirectional (`false`) 5725chap_group | Optional | number | Authentication group ID for this target node 5726 5727Parameters `disable_chap` and `require_chap` are mutually exclusive. 5728 5729#### Example 5730 5731Example request: 5732 5733~~~json 5734{ 5735 "params": { 5736 "chap_group": 1, 5737 "require_chap": true, 5738 "name": "iqn.2016-06.io.spdk:target1", 5739 "mutual_chap": true 5740 }, 5741 "jsonrpc": "2.0", 5742 "method": "iscsi_target_node_set_auth", 5743 "id": 1 5744} 5745~~~ 5746 5747Example response: 5748 5749~~~json 5750{ 5751 "jsonrpc": "2.0", 5752 "id": 1, 5753 "result": true 5754} 5755~~~ 5756 5757### iscsi_target_node_add_pg_ig_maps method {#rpc_iscsi_target_node_add_pg_ig_maps} 5758 5759Add initiator group to portal group mappings to an existing iSCSI target node. 5760 5761#### Parameters 5762 5763Name | Optional | Type | Description 5764--------------------------- | -------- | --------| ----------- 5765name | Required | string | Target node name (ASCII) 5766pg_ig_maps | Required | array | Not empty array of initiator to portal group mappings objects 5767 5768Portal to Initiator group mappings object: 5769 5770Name | Optional | Type | Description 5771--------------------------- | -------- | --------| ----------- 5772ig_tag | Required | number | Existing initiator group tag 5773pg_tag | Required | number | Existing portal group tag 5774 5775#### Example 5776 5777Example request: 5778 5779~~~json 5780{ 5781 "params": { 5782 "pg_ig_maps": [ 5783 { 5784 "ig_tag": 1, 5785 "pg_tag": 1 5786 }, 5787 { 5788 "ig_tag": 2, 5789 "pg_tag": 2 5790 }, 5791 { 5792 "ig_tag": 3, 5793 "pg_tag": 3 5794 } 5795 ], 5796 "name": "iqn.2016-06.io.spdk:target3" 5797 }, 5798 "jsonrpc": "2.0", 5799 "method": "iscsi_target_node_add_pg_ig_maps", 5800 "id": 1 5801} 5802~~~ 5803 5804Example response: 5805 5806~~~json 5807{ 5808 "jsonrpc": "2.0", 5809 "id": 1, 5810 "result": true 5811} 5812~~~ 5813 5814### iscsi_target_node_remove_pg_ig_maps method {#rpc_iscsi_target_node_remove_pg_ig_maps} 5815 5816Delete initiator group to portal group mappings from an existing iSCSI target node. 5817 5818#### Parameters 5819 5820Name | Optional | Type | Description 5821--------------------------- | -------- | --------| ----------- 5822name | Required | string | Target node name (ASCII) 5823pg_ig_maps | Required | array | Not empty array of Portal to Initiator group mappings objects 5824 5825Portal to Initiator group mappings object: 5826 5827Name | Optional | Type | Description 5828--------------------------- | -------- | --------| ----------- 5829ig_tag | Required | number | Existing initiator group tag 5830pg_tag | Required | number | Existing portal group tag 5831 5832#### Example 5833 5834Example request: 5835 5836~~~json 5837{ 5838 "params": { 5839 "pg_ig_maps": [ 5840 { 5841 "ig_tag": 1, 5842 "pg_tag": 1 5843 }, 5844 { 5845 "ig_tag": 2, 5846 "pg_tag": 2 5847 }, 5848 { 5849 "ig_tag": 3, 5850 "pg_tag": 3 5851 } 5852 ], 5853 "name": "iqn.2016-06.io.spdk:target3" 5854 }, 5855 "jsonrpc": "2.0", 5856 "method": "iscsi_target_node_remove_pg_ig_maps", 5857 "id": 1 5858} 5859~~~ 5860 5861Example response: 5862 5863~~~json 5864{ 5865 "jsonrpc": "2.0", 5866 "id": 1, 5867 "result": true 5868} 5869~~~ 5870 5871### iscsi_delete_target_node method {#rpc_iscsi_delete_target_node} 5872 5873Delete an iSCSI target node. 5874 5875#### Parameters 5876 5877Name | Optional | Type | Description 5878--------------------------- | -------- | --------| ----------- 5879name | Required | string | Target node name (ASCII) 5880 5881#### Example 5882 5883Example request: 5884 5885~~~json 5886{ 5887 "params": { 5888 "name": "iqn.2016-06.io.spdk:target1" 5889 }, 5890 "jsonrpc": "2.0", 5891 "method": "iscsi_delete_target_node", 5892 "id": 1 5893} 5894~~~ 5895 5896Example response: 5897 5898~~~json 5899{ 5900 "jsonrpc": "2.0", 5901 "id": 1, 5902 "result": true 5903} 5904~~~ 5905 5906### iscsi_get_portal_groups method {#rpc_iscsi_get_portal_groups} 5907 5908Show information about all available portal groups. 5909 5910#### Parameters 5911 5912This method has no parameters. 5913 5914#### Example 5915 5916Example request: 5917 5918~~~json 5919request: 5920{ 5921 "jsonrpc": "2.0", 5922 "method": "iscsi_get_portal_groups", 5923 "id": 1 5924} 5925~~~ 5926 5927Example response: 5928 5929~~~json 5930{ 5931 "jsonrpc": "2.0", 5932 "id": 1, 5933 "result": [ 5934 { 5935 "portals": [ 5936 { 5937 "host": "127.0.0.1", 5938 "port": "3260" 5939 } 5940 ], 5941 "tag": 1, 5942 "private": false 5943 } 5944 ] 5945} 5946~~~ 5947 5948### iscsi_create_portal_group method {#rpc_iscsi_create_portal_group} 5949 5950Add a portal group. 5951 5952#### Parameters 5953 5954Name | Optional | Type | Description 5955--------------------------- | -------- | --------| ----------- 5956tag | Required | number | Portal group tag 5957portals | Required | array | Not empty array of portals 5958private | Optional | boolean | When true, portals in this group are not returned by a discovery session. Used for login redirection. (default: `false`) 5959wait | Optional | boolean | When true, do not listen on portals until it is started explicitly. (default: `false`) 5960 5961Portal object 5962 5963Name | Optional | Type | Description 5964--------------------------- | -------- | --------| ----------- 5965host | Required | string | Hostname or IP address 5966port | Required | string | Port number 5967 5968#### Example 5969 5970Example request: 5971 5972~~~json 5973{ 5974 "params": { 5975 "portals": [ 5976 { 5977 "host": "127.0.0.1", 5978 "port": "3260" 5979 } 5980 ], 5981 "tag": 1 5982 }, 5983 "jsonrpc": "2.0", 5984 "method": "iscsi_create_portal_group", 5985 "id": 1 5986} 5987~~~ 5988 5989Example response: 5990 5991~~~json 5992{ 5993 "jsonrpc": "2.0", 5994 "id": 1, 5995 "result": true 5996} 5997~~~ 5998 5999### iscsi_start_portal_group method {#rpc_iscsi_start_portal_group} 6000 6001Start listening on portals if the portal group is not started yet, or do nothing 6002if the portal group already started. Return a success response for both cases. 6003 6004#### Parameters 6005 6006Name | Optional | Type | Description 6007--------------------------- | -------- | --------| ----------- 6008tag | Required | number | Existing portal group tag 6009 6010#### Example 6011 6012Example request: 6013 6014~~~json 6015{ 6016 "params": { 6017 "tag": 1 6018 }, 6019 "jsonrpc": "2.0", 6020 "method": "iscsi_start_portal_group", 6021 "id": 1 6022} 6023~~~ 6024 6025Example response: 6026 6027~~~json 6028{ 6029 "jsonrpc": "2.0", 6030 "id": 1, 6031 "result": true 6032} 6033~~~ 6034 6035### iscsi_delete_portal_group method {#rpc_iscsi_delete_portal_group} 6036 6037Delete an existing portal group. 6038 6039#### Parameters 6040 6041Name | Optional | Type | Description 6042--------------------------- | -------- | --------| ----------- 6043tag | Required | number | Existing portal group tag 6044 6045#### Example 6046 6047Example request: 6048 6049~~~json 6050{ 6051 "params": { 6052 "tag": 1 6053 }, 6054 "jsonrpc": "2.0", 6055 "method": "iscsi_delete_portal_group", 6056 "id": 1 6057} 6058~~~ 6059 6060Example response: 6061 6062~~~json 6063{ 6064 "jsonrpc": "2.0", 6065 "id": 1, 6066 "result": true 6067} 6068~~~ 6069 6070### iscsi_portal_group_set_auth method {#rpc_iscsi_portal_group_set_auth} 6071 6072Set CHAP authentication for discovery sessions specific for the existing iSCSI portal group. 6073This RPC overwrites the setting by the global parameters for the iSCSI portal group. 6074 6075#### Parameters 6076 6077Name | Optional | Type | Description 6078--------------------------- | -------- | --------| ----------- 6079disable_chap | Optional | boolean | CHAP for discovery session should be disabled (default: `false`) 6080require_chap | Optional | boolean | CHAP for discovery session should be required (default: `false`) 6081mutual_chap | Optional | boolean | CHAP for discovery session should be unidirectional (`false`) or bidirectional (`true`) (default: `false`) 6082chap_group | Optional | number | CHAP group ID for discovery session (default: 0) 6083 6084Parameters `disable_chap` and `require_chap` are mutually exclusive. 6085 6086#### Example 6087 6088Example request: 6089 6090~~~json 6091request: 6092{ 6093 "params": { 6094 "tag": 1, 6095 "chap_group": 1, 6096 "require_chap": true, 6097 "mutual_chap": true 6098 }, 6099 "jsonrpc": "2.0", 6100 "method": "iscsi_portal_group_set_auth", 6101 "id": 1 6102} 6103~~~ 6104 6105Example response: 6106 6107~~~json 6108{ 6109 "jsonrpc": "2.0", 6110 "id": 1, 6111 "result": true 6112} 6113~~~ 6114 6115### iscsi_get_connections method {#rpc_iscsi_get_connections} 6116 6117Show information about all active connections. 6118 6119#### Parameters 6120 6121This method has no parameters. 6122 6123#### Results 6124 6125Array of objects describing iSCSI connection. 6126 6127Name | Type | Description 6128--------------------------- | --------| ----------- 6129id | number | Index (used for TTT - Target Transfer Tag) 6130cid | number | CID (Connection ID) 6131tsih | number | TSIH (Target Session Identifying Handle) 6132lcore_id | number | Core number on which the iSCSI connection runs 6133initiator_addr | string | Initiator address 6134target_addr | string | Target address 6135target_node_name | string | Target node name (ASCII) without prefix 6136 6137#### Example 6138 6139Example request: 6140 6141~~~json 6142{ 6143 "jsonrpc": "2.0", 6144 "method": "iscsi_get_connections", 6145 "id": 1 6146} 6147~~~ 6148 6149Example response: 6150 6151~~~json 6152{ 6153 "jsonrpc": "2.0", 6154 "id": 1, 6155 "result": [ 6156 { 6157 "tsih": 4, 6158 "cid": 0, 6159 "target_node_name": "target1", 6160 "lcore_id": 0, 6161 "initiator_addr": "10.0.0.2", 6162 "target_addr": "10.0.0.1", 6163 "id": 0 6164 } 6165 ] 6166} 6167~~~ 6168 6169### iscsi_target_node_add_lun method {#rpc_iscsi_target_node_add_lun} 6170 6171Add an LUN to an existing iSCSI target node. 6172 6173#### Parameters 6174 6175Name | Optional | Type | Description 6176--------------------------- | -------- | --------| ----------- 6177name | Required | string | Target node name (ASCII) 6178bdev_name | Required | string | bdev name to be added as a LUN 6179lun_id | Optional | number | LUN ID (default: first free ID) 6180 6181#### Example 6182 6183Example request: 6184 6185~~~json 6186{ 6187 "params": { 6188 "lun_id": 2, 6189 "name": "iqn.2016-06.io.spdk:target1", 6190 "bdev_name": "Malloc0" 6191 }, 6192 "jsonrpc": "2.0", 6193 "method": "iscsi_target_node_add_lun", 6194 "id": 1 6195} 6196~~~ 6197 6198Example response: 6199 6200~~~json 6201{ 6202 "jsonrpc": "2.0", 6203 "id": 1, 6204 "result": true 6205} 6206~~~ 6207 6208### iscsi_target_node_set_redirect method {#rpc_iscsi_target_node_set_redirect} 6209 6210Update redirect portal of the primary portal group for the target node, 6211 6212#### Parameters 6213 6214Name | Optional | Type | Description 6215--------------------------- | -------- | --------| ----------- 6216name | Required | string | Target node name (ASCII) 6217pg_tag | Required | number | Existing portal group tag 6218redirect_host | Optional | string | Numeric IP address to which the target node is redirected 6219redirect_port | Optional | string | Numeric TCP port to which the target node is redirected 6220 6221If both redirect_host and redirect_port are omitted, clear the redirect portal. 6222 6223#### Example 6224 6225Example request: 6226 6227~~~json 6228{ 6229 "params": { 6230 "name": "iqn.2016-06.io.spdk:target1", 6231 "pg_tag": 1, 6232 "redirect_host": "10.0.0.3", 6233 "redirect_port": "3260" 6234 }, 6235 "jsonrpc": "2.0", 6236 "method": "iscsi_target_node_set_redirect", 6237 "id": 1 6238} 6239~~~ 6240 6241Example response: 6242 6243~~~json 6244{ 6245 "jsonrpc": "2.0", 6246 "id": 1, 6247 "result": true 6248} 6249~~~ 6250 6251### iscsi_target_node_request_logout method {#rpc_iscsi_target_node_request_logout} 6252 6253For the target node, request connections whose portal group tag match to logout, 6254or request all connections to logout if portal group tag is omitted. 6255 6256#### Parameters 6257 6258Name | Optional | Type | Description 6259--------------------------- | -------- | --------| ----------- 6260name | Required | string | Target node name (ASCII) 6261pg_tag | Optional | number | Existing portal group tag 6262 6263#### Example 6264 6265Example request: 6266 6267~~~json 6268{ 6269 "params": { 6270 "name": "iqn.2016-06.io.spdk:target1", 6271 "pg_tag": 1 6272 }, 6273 "jsonrpc": "2.0", 6274 "method": "iscsi_target_node_request_logout", 6275 "id": 1 6276} 6277~~~ 6278 6279Example response: 6280 6281~~~json 6282{ 6283 "jsonrpc": "2.0", 6284 "id": 1, 6285 "result": true 6286} 6287~~~ 6288 6289## NVMe-oF Target {#jsonrpc_components_nvmf_tgt} 6290 6291### nvmf_create_transport method {#rpc_nvmf_create_transport} 6292 6293Initialize an NVMe-oF transport with the given options. 6294 6295#### Parameters 6296 6297Name | Optional | Type | Description 6298--------------------------- | -------- | --------| ----------- 6299trtype | Required | string | Transport type (ex. RDMA) 6300tgt_name | Optional | string | Parent NVMe-oF target name. 6301max_queue_depth | Optional | number | Max number of outstanding I/O per queue 6302max_io_qpairs_per_ctrlr | Optional | number | Max number of IO qpairs per controller 6303in_capsule_data_size | Optional | number | Max number of in-capsule data size 6304max_io_size | Optional | number | Max I/O size (bytes) 6305io_unit_size | Optional | number | I/O unit size (bytes) 6306max_aq_depth | Optional | number | Max number of admin cmds per AQ 6307num_shared_buffers | Optional | number | The number of pooled data buffers available to the transport 6308buf_cache_size | Optional | number | The number of shared buffers to reserve for each poll group 6309num_cqe | Optional | number | The number of CQ entires. Only used when no_srq=true (RDMA only) 6310max_srq_depth | Optional | number | The number of elements in a per-thread shared receive queue (RDMA only) 6311no_srq | Optional | boolean | Disable shared receive queue even for devices that support it. (RDMA only) 6312c2h_success | Optional | boolean | Disable C2H success optimization (TCP only) 6313dif_insert_or_strip | Optional | boolean | Enable DIF insert for write I/O and DIF strip for read I/O DIF 6314sock_priority | Optional | number | The socket priority of the connection owned by this transport (TCP only) 6315acceptor_backlog | Optional | number | The number of pending connections allowed in backlog before failing new connection attempts (RDMA only) 6316abort_timeout_sec | Optional | number | Abort execution timeout value, in seconds 6317no_wr_batching | Optional | boolean | Disable work requests batching (RDMA only) 6318control_msg_num | Optional | number | The number of control messages per poll group (TCP only) 6319disable_mappable_bar0 | Optional | boolean | disable client mmap() of BAR0 (VFIO-USER only) 6320disable_adaptive_irq | Optional | boolean | Disable adaptive interrupt feature (VFIO-USER only) 6321disable_shadow_doorbells | Optional | boolean | disable shadow doorbell support (VFIO-USER only) 6322zcopy | Optional | boolean | Use zero-copy operations if the underlying bdev supports them 6323 6324#### Example 6325 6326Example request: 6327 6328~~~json 6329{ 6330 "jsonrpc": "2.0", 6331 "method": "nvmf_create_transport", 6332 "id": 1, 6333 "params": { 6334 "trtype": "RDMA", 6335 "max_queue_depth": 32 6336 } 6337} 6338~~~ 6339 6340Example response: 6341 6342~~~json 6343{ 6344 "jsonrpc": "2.0", 6345 "id": 1, 6346 "result": true 6347} 6348~~~ 6349 6350### nvmf_get_subsystems method {#rpc_nvmf_get_subsystems} 6351 6352#### Parameters 6353 6354Name | Optional | Type | Description 6355--------------------------- | -------- | ------------| ----------- 6356tgt_name | Optional | string | Parent NVMe-oF target name. 6357 6358#### Example 6359 6360Example request: 6361 6362~~~json 6363{ 6364 "jsonrpc": "2.0", 6365 "id": 1, 6366 "method": "nvmf_get_subsystems" 6367} 6368~~~ 6369 6370Example response: 6371 6372~~~json 6373{ 6374 "jsonrpc": "2.0", 6375 "id": 1, 6376 "result": [ 6377 { 6378 "nqn": "nqn.2014-08.org.nvmexpress.discovery", 6379 "subtype": "Discovery" 6380 "listen_addresses": [], 6381 "hosts": [], 6382 "allow_any_host": true 6383 }, 6384 { 6385 "nqn": "nqn.2016-06.io.spdk:cnode1", 6386 "subtype": "NVMe", 6387 "listen_addresses": [ 6388 { 6389 "trtype": "RDMA", 6390 "adrfam": "IPv4", 6391 "traddr": "192.168.0.123", 6392 "trsvcid": "4420" 6393 } 6394 ], 6395 "hosts": [ 6396 {"nqn": "nqn.2016-06.io.spdk:host1"} 6397 ], 6398 "allow_any_host": false, 6399 "serial_number": "abcdef", 6400 "model_number": "ghijklmnop", 6401 "namespaces": [ 6402 {"nsid": 1, "name": "Malloc2"}, 6403 {"nsid": 2, "name": "Nvme0n1"} 6404 ] 6405 } 6406 ] 6407} 6408~~~ 6409 6410### nvmf_create_subsystem method {#rpc_nvmf_create_subsystem} 6411 6412Construct an NVMe over Fabrics target subsystem. 6413 6414#### Parameters 6415 6416Name | Optional | Type | Description 6417----------------------- | -------- | ----------- | ----------- 6418nqn | Required | string | Subsystem NQN 6419tgt_name | Optional | string | Parent NVMe-oF target name. 6420serial_number | Optional | string | Serial number of virtual controller 6421model_number | Optional | string | Model number of virtual controller 6422max_namespaces | Optional | number | Maximum number of namespaces that can be attached to the subsystem. Default: 0 (Unlimited) 6423allow_any_host | Optional | boolean | Allow any host (`true`) or enforce allowed host list (`false`). Default: `false`. 6424ana_reporting | Optional | boolean | Enable ANA reporting feature (default: `false`). 6425min_cntlid | Optional | number | Minimum controller ID. Default: 1 6426max_cntlid | Optional | number | Maximum controller ID. Default: 0xffef 6427 6428#### Example 6429 6430Example request: 6431 6432~~~json 6433{ 6434 "jsonrpc": "2.0", 6435 "id": 1, 6436 "method": "nvmf_create_subsystem", 6437 "params": { 6438 "nqn": "nqn.2016-06.io.spdk:cnode1", 6439 "allow_any_host": false, 6440 "serial_number": "abcdef", 6441 "model_number": "ghijklmnop" 6442 } 6443} 6444~~~ 6445 6446Example response: 6447 6448~~~json 6449{ 6450 "jsonrpc": "2.0", 6451 "id": 1, 6452 "result": true 6453} 6454~~~ 6455 6456### nvmf_delete_subsystem method {#rpc_nvmf_delete_subsystem} 6457 6458Delete an existing NVMe-oF subsystem. 6459 6460#### Parameters 6461 6462Parameter | Optional | Type | Description 6463---------------------- | -------- | ----------- | ----------- 6464nqn | Required | string | Subsystem NQN to delete. 6465tgt_name | Optional | string | Parent NVMe-oF target name. 6466 6467#### Example 6468 6469Example request: 6470 6471~~~json 6472{ 6473 "jsonrpc": "2.0", 6474 "id": 1, 6475 "method": "nvmf_delete_subsystem", 6476 "params": { 6477 "nqn": "nqn.2016-06.io.spdk:cnode1" 6478 } 6479} 6480~~~ 6481 6482Example response: 6483 6484~~~json 6485{ 6486 "jsonrpc": "2.0", 6487 "id": 1, 6488 "result": true 6489} 6490~~~ 6491 6492### nvmf_subsystem_add_listener method {#rpc_nvmf_subsystem_add_listener} 6493 6494Add a new listen address to an NVMe-oF subsystem. 6495 6496#### Parameters 6497 6498Name | Optional | Type | Description 6499----------------------- | -------- | ----------- | ----------- 6500nqn | Required | string | Subsystem NQN 6501tgt_name | Optional | string | Parent NVMe-oF target name. 6502listen_address | Required | object | @ref rpc_nvmf_listen_address object 6503 6504#### listen_address {#rpc_nvmf_listen_address} 6505 6506Name | Optional | Type | Description 6507----------------------- | -------- | ----------- | ----------- 6508trtype | Required | string | Transport type ("RDMA") 6509adrfam | Required | string | Address family ("IPv4", "IPv6", "IB", or "FC") 6510traddr | Required | string | Transport address 6511trsvcid | Optional | string | Transport service ID (required for RDMA or TCP) 6512 6513#### Example 6514 6515Example request: 6516 6517~~~json 6518{ 6519 "jsonrpc": "2.0", 6520 "id": 1, 6521 "method": "nvmf_subsystem_add_listener", 6522 "params": { 6523 "nqn": "nqn.2016-06.io.spdk:cnode1", 6524 "listen_address": { 6525 "trtype": "RDMA", 6526 "adrfam": "IPv4", 6527 "traddr": "192.168.0.123", 6528 "trsvcid": "4420" 6529 } 6530 } 6531} 6532~~~ 6533 6534Example response: 6535 6536~~~json 6537{ 6538 "jsonrpc": "2.0", 6539 "id": 1, 6540 "result": true 6541} 6542~~~ 6543 6544### nvmf_subsystem_remove_listener method {#rpc_nvmf_subsystem_remove_listener} 6545 6546Remove a listen address from an NVMe-oF subsystem. 6547 6548#### Parameters 6549 6550Name | Optional | Type | Description 6551----------------------- | -------- | ----------- | ----------- 6552nqn | Required | string | Subsystem NQN 6553tgt_name | Optional | string | Parent NVMe-oF target name. 6554listen_address | Required | object | @ref rpc_nvmf_listen_address object 6555 6556#### Example 6557 6558Example request: 6559 6560~~~json 6561{ 6562 "jsonrpc": "2.0", 6563 "id": 1, 6564 "method": "nvmf_subsystem_remove_listener", 6565 "params": { 6566 "nqn": "nqn.2016-06.io.spdk:cnode1", 6567 "listen_address": { 6568 "trtype": "RDMA", 6569 "adrfam": "IPv4", 6570 "traddr": "192.168.0.123", 6571 "trsvcid": "4420" 6572 } 6573 } 6574} 6575~~~ 6576 6577Example response: 6578 6579~~~json 6580{ 6581 "jsonrpc": "2.0", 6582 "id": 1, 6583 "result": true 6584} 6585~~~ 6586 6587### nvmf_subsystem_listener_set_ana_state method {#rpc_nvmf_subsystem_listener_set_ana_state} 6588 6589Set ANA state of a listener for an NVMe-oF subsystem. Only the ANA state of the specified ANA 6590group is updated, or ANA states of all ANA groups if ANA group is not specified. 6591 6592#### Parameters 6593 6594Name | Optional | Type | Description 6595----------------------- | -------- | ----------- | ----------- 6596nqn | Required | string | Subsystem NQN 6597tgt_name | Optional | string | Parent NVMe-oF target name. 6598listen_address | Required | object | @ref rpc_nvmf_listen_address object 6599ana_state | Required | string | ANA state to set ("optimized", "non_optimized", or "inaccessible") 6600anagrpid | Optional | number | ANA group ID 6601 6602#### Example 6603 6604Example request: 6605 6606~~~json 6607{ 6608 "jsonrpc": "2.0", 6609 "id": 1, 6610 "method": "nvmf_subsystem_listener_set_ana_state", 6611 "params": { 6612 "nqn": "nqn.2016-06.io.spdk:cnode1", 6613 "listen_address": { 6614 "trtype": "RDMA", 6615 "adrfam": "IPv4", 6616 "traddr": "192.168.0.123", 6617 "trsvcid": "4420" 6618 }, 6619 "ana_state", "inaccessible" 6620 } 6621} 6622~~~ 6623 6624Example response: 6625 6626~~~json 6627{ 6628 "jsonrpc": "2.0", 6629 "id": 1, 6630 "result": true 6631} 6632~~~ 6633 6634### nvmf_subsystem_add_ns method {#rpc_nvmf_subsystem_add_ns} 6635 6636Add a namespace to a subsystem. The namespace ID is returned as the result. 6637 6638### Parameters 6639 6640Name | Optional | Type | Description 6641----------------------- | -------- | ----------- | ----------- 6642nqn | Required | string | Subsystem NQN 6643namespace | Required | object | @ref rpc_nvmf_namespace object 6644tgt_name | Optional | string | Parent NVMe-oF target name. 6645 6646#### namespace {#rpc_nvmf_namespace} 6647 6648Name | Optional | Type | Description 6649----------------------- | -------- | ----------- | ----------- 6650nsid | Optional | number | Namespace ID between 1 and 4294967294, inclusive. Default: Automatically assign NSID. 6651bdev_name | Required | string | Name of bdev to expose as a namespace. 6652nguid | Optional | string | 16-byte namespace globally unique identifier in hexadecimal (e.g. "ABCDEF0123456789ABCDEF0123456789") 6653eui64 | Optional | string | 8-byte namespace EUI-64 in hexadecimal (e.g. "ABCDEF0123456789") 6654uuid | Optional | string | RFC 4122 UUID (e.g. "ceccf520-691e-4b46-9546-34af789907c5") 6655ptpl_file | Optional | string | File path to save/restore persistent reservation information 6656anagrpid | Optional | number | ANA group ID. Default: Namespace ID. 6657 6658#### Example 6659 6660Example request: 6661 6662~~~json 6663{ 6664 "jsonrpc": "2.0", 6665 "id": 1, 6666 "method": "nvmf_subsystem_add_ns", 6667 "params": { 6668 "nqn": "nqn.2016-06.io.spdk:cnode1", 6669 "namespace": { 6670 "nsid": 3, 6671 "bdev_name": "Nvme0n1", 6672 "ptpl_file": "/opt/Nvme0n1PR.json" 6673 } 6674 } 6675} 6676~~~ 6677 6678Example response: 6679 6680~~~json 6681{ 6682 "jsonrpc": "2.0", 6683 "id": 1, 6684 "result": 3 6685} 6686~~~ 6687 6688### nvmf_subsystem_remove_ns method {#rpc_nvmf_subsystem_remove_ns} 6689 6690Remove a namespace from a subsystem. 6691 6692#### Parameters 6693 6694Name | Optional | Type | Description 6695----------------------- | -------- | ----------- | ----------- 6696nqn | Required | string | Subsystem NQN 6697nsid | Required | number | Namespace ID 6698tgt_name | Optional | string | Parent NVMe-oF target name. 6699 6700#### Example 6701 6702Example request: 6703 6704~~~json 6705{ 6706 "jsonrpc": "2.0", 6707 "id": 1, 6708 "method": "nvmf_subsystem_remove_ns", 6709 "params": { 6710 "nqn": "nqn.2016-06.io.spdk:cnode1", 6711 "nsid": 1 6712 } 6713} 6714~~~ 6715 6716Example response: 6717 6718~~~json 6719{ 6720 "jsonrpc": "2.0", 6721 "id": 1, 6722 "result": true 6723} 6724~~~ 6725 6726### nvmf_subsystem_add_host method {#rpc_nvmf_subsystem_add_host} 6727 6728Add a host NQN to the list of allowed hosts. 6729 6730#### Parameters 6731 6732Name | Optional | Type | Description 6733----------------------- | -------- | ----------- | ----------- 6734nqn | Required | string | Subsystem NQN 6735host | Required | string | Host NQN to add to the list of allowed host NQNs 6736tgt_name | Optional | string | Parent NVMe-oF target name. 6737 6738#### Example 6739 6740Example request: 6741 6742~~~json 6743{ 6744 "jsonrpc": "2.0", 6745 "id": 1, 6746 "method": "nvmf_subsystem_add_host", 6747 "params": { 6748 "nqn": "nqn.2016-06.io.spdk:cnode1", 6749 "host": "nqn.2016-06.io.spdk:host1" 6750 } 6751} 6752~~~ 6753 6754Example response: 6755 6756~~~json 6757{ 6758 "jsonrpc": "2.0", 6759 "id": 1, 6760 "result": true 6761} 6762~~~ 6763 6764### nvmf_subsystem_remove_host method {#rpc_nvmf_subsystem_remove_host} 6765 6766Remove a host NQN from the list of allowed hosts. 6767 6768#### Parameters 6769 6770Name | Optional | Type | Description 6771----------------------- | -------- | ----------- | ----------- 6772nqn | Required | string | Subsystem NQN 6773host | Required | string | Host NQN to remove from the list of allowed host NQNs 6774tgt_name | Optional | string | Parent NVMe-oF target name. 6775 6776#### Example 6777 6778Example request: 6779 6780~~~json 6781{ 6782 "jsonrpc": "2.0", 6783 "id": 1, 6784 "method": "nvmf_subsystem_remove_host", 6785 "params": { 6786 "nqn": "nqn.2016-06.io.spdk:cnode1", 6787 "host": "nqn.2016-06.io.spdk:host1" 6788 } 6789} 6790~~~ 6791 6792Example response: 6793 6794~~~json 6795{ 6796 "jsonrpc": "2.0", 6797 "id": 1, 6798 "result": true 6799} 6800~~~ 6801 6802### nvmf_subsystem_allow_any_host method {#rpc_nvmf_subsystem_allow_any_host} 6803 6804Configure a subsystem to allow any host to connect or to enforce the host NQN list. 6805 6806#### Parameters 6807 6808Name | Optional | Type | Description 6809----------------------- | -------- | ----------- | ----------- 6810nqn | Required | string | Subsystem NQN 6811allow_any_host | Required | boolean | Allow any host (`true`) or enforce allowed host list (`false`). 6812tgt_name | Optional | string | Parent NVMe-oF target name. 6813 6814#### Example 6815 6816Example request: 6817 6818~~~json 6819{ 6820 "jsonrpc": "2.0", 6821 "id": 1, 6822 "method": "nvmf_subsystem_allow_any_host", 6823 "params": { 6824 "nqn": "nqn.2016-06.io.spdk:cnode1", 6825 "allow_any_host": true 6826 } 6827} 6828~~~ 6829 6830Example response: 6831 6832~~~json 6833{ 6834 "jsonrpc": "2.0", 6835 "id": 1, 6836 "result": true 6837} 6838~~~ 6839 6840### nvmf_subsystem_get_controllers {#rpc_nvmf_subsystem_get_controllers} 6841 6842#### Parameters 6843 6844Name | Optional | Type | Description 6845----------------------- | -------- | ----------- | ----------- 6846nqn | Required | string | Subsystem NQN 6847tgt_name | Optional | string | Parent NVMe-oF target name. 6848 6849#### Example 6850 6851Example request: 6852 6853~~~json 6854{ 6855 "jsonrpc": "2.0", 6856 "id": 1, 6857 "method": "nvmf_subsystem_get_controllers", 6858 "params": { 6859 "nqn": "nqn.2016-06.io.spdk:cnode1" 6860 } 6861} 6862~~~ 6863 6864Example response: 6865 6866~~~json 6867{ 6868 "jsonrpc": "2.0", 6869 "id": 1, 6870 "result": [ 6871 { 6872 "cntlid": 1, 6873 "hostnqn": "nqn.2016-06.io.spdk:host1", 6874 "hostid": "27dad528-6368-41c3-82d3-0b956b49025d", 6875 "num_io_qpairs": 5 6876 } 6877 ] 6878} 6879~~~ 6880 6881### nvmf_subsystem_get_qpairs {#rpc_nvmf_subsystem_get_qpairs} 6882 6883#### Parameters 6884 6885Name | Optional | Type | Description 6886----------------------- | -------- | ----------- | ----------- 6887nqn | Required | string | Subsystem NQN 6888tgt_name | Optional | string | Parent NVMe-oF target name. 6889 6890#### Example 6891 6892Example request: 6893 6894~~~json 6895{ 6896 "jsonrpc": "2.0", 6897 "id": 1, 6898 "method": "nvmf_subsystem_get_qpairs", 6899 "params": { 6900 "nqn": "nqn.2016-06.io.spdk:cnode1" 6901 } 6902} 6903~~~ 6904 6905Example response: 6906 6907~~~json 6908{ 6909 "jsonrpc": "2.0", 6910 "id": 1, 6911 "result": [ 6912 { 6913 "cntlid": 1, 6914 "qid": 0, 6915 "state": "active", 6916 "listen_address": { 6917 "trtype": "RDMA", 6918 "adrfam": "IPv4", 6919 "traddr": "192.168.0.123", 6920 "trsvcid": "4420" 6921 } 6922 }, 6923 { 6924 "cntlid": 1, 6925 "qid": 1, 6926 "state": "active", 6927 "listen_address": { 6928 "trtype": "RDMA", 6929 "adrfam": "IPv4", 6930 "traddr": "192.168.0.123", 6931 "trsvcid": "4420" 6932 } 6933 } 6934 ] 6935} 6936~~~ 6937 6938### nvmf_subsystem_get_listeners {#rpc_nvmf_subsystem_get_listeners} 6939 6940#### Parameters 6941 6942Name | Optional | Type | Description 6943----------------------- | -------- | ----------- | ----------- 6944nqn | Required | string | Subsystem NQN 6945tgt_name | Optional | string | Parent NVMe-oF target name. 6946 6947#### Example 6948 6949Example request: 6950 6951~~~json 6952{ 6953 "jsonrpc": "2.0", 6954 "id": 1, 6955 "method": "nvmf_subsystem_get_listeners", 6956 "params": { 6957 "nqn": "nqn.2016-06.io.spdk:cnode1" 6958 } 6959} 6960~~~ 6961 6962Example response: 6963 6964~~~json 6965{ 6966 "jsonrpc": "2.0", 6967 "id": 1, 6968 "result": [ 6969 { 6970 "address": { 6971 "trtype": "RDMA", 6972 "adrfam": "IPv4", 6973 "traddr": "192.168.0.123", 6974 "trsvcid": "4420" 6975 }, 6976 "ana_state": "optimized" 6977 } 6978 ] 6979} 6980~~~ 6981 6982### nvmf_set_max_subsystems {#rpc_nvmf_set_max_subsystems} 6983 6984Set the maximum allowed subsystems for the NVMe-oF target. This RPC may only be called 6985before SPDK subsystems have been initialized. 6986 6987#### Parameters 6988 6989Name | Optional | Type | Description 6990----------------------- | -------- | ----------- | ----------- 6991max_subsystems | Required | number | Maximum number of NVMe-oF subsystems 6992 6993#### Example 6994 6995Example request: 6996 6997~~~json 6998{ 6999 "jsonrpc": "2.0", 7000 "id": 1, 7001 "method": "nvmf_set_max_subsystems", 7002 "params": { 7003 "max_subsystems": 1024 7004 } 7005} 7006~~~ 7007 7008Example response: 7009 7010~~~json 7011{ 7012 "jsonrpc": "2.0", 7013 "id": 1, 7014 "result": true 7015} 7016~~~ 7017 7018### nvmf_set_config {#rpc_nvmf_set_config} 7019 7020Set global configuration of NVMe-oF target. This RPC may only be called before SPDK subsystems 7021have been initialized. 7022 7023#### Parameters 7024 7025Name | Optional | Type | Description 7026----------------------- | -------- | ----------- | ----------- 7027acceptor_poll_rate | Optional | number | Polling interval of the acceptor for incoming connections (microseconds) 7028admin_cmd_passthru | Optional | object | Admin command passthru configuration 7029poll_groups_mask | Optional | string | Set cpumask for NVMf poll groups 7030discovery_filter | Optional | string | Set discovery filter, possible values are: `match_any` (default) or comma separated values: `transport`, `address`, `svcid` 7031 7032#### admin_cmd_passthru {#spdk_nvmf_admin_passthru_conf} 7033 7034Name | Optional | Type | Description 7035----------------------- | -------- | ----------- | ----------- 7036identify_ctrlr | Required | bool | If true, enables custom identify handler that reports some identify attributes from the underlying NVMe drive 7037 7038#### Example 7039 7040Example request: 7041 7042~~~json 7043{ 7044 "jsonrpc": "2.0", 7045 "id": 1, 7046 "method": "nvmf_set_config", 7047 "params": { 7048 "acceptor_poll_rate": 10000 7049 } 7050} 7051~~~ 7052 7053Example response: 7054 7055~~~json 7056{ 7057 "jsonrpc": "2.0", 7058 "id": 1, 7059 "result": true 7060} 7061~~~ 7062 7063### nvmf_get_transports method {#rpc_nvmf_get_transports} 7064 7065#### Parameters 7066 7067The user may specify no parameters in order to list all transports, or a transport may be 7068specified by type. 7069 7070Name | Optional | Type | Description 7071--------------------------- | -------- | ------------| ----------- 7072tgt_name | Optional | string | Parent NVMe-oF target name. 7073trtype | Optional | string | Transport type. 7074 7075#### Example 7076 7077Example request: 7078 7079~~~json 7080{ 7081 "jsonrpc": "2.0", 7082 "id": 1, 7083 "method": "nvmf_get_transports" 7084} 7085~~~ 7086 7087Example response: 7088 7089~~~json 7090{ 7091 "jsonrpc": "2.0", 7092 "id": 1, 7093 "result": [ 7094 { 7095 "type": "RDMA". 7096 "max_queue_depth": 128, 7097 "max_io_qpairs_per_ctrlr": 64, 7098 "in_capsule_data_size": 4096, 7099 "max_io_size": 131072, 7100 "io_unit_size": 131072, 7101 "abort_timeout_sec": 1 7102 } 7103 ] 7104} 7105~~~ 7106 7107### nvmf_get_stats method {#rpc_nvmf_get_stats} 7108 7109Retrieve current statistics of the NVMf subsystem. 7110 7111#### Parameters 7112 7113Name | Optional | Type | Description 7114--------------------------- | -------- | ------------| ----------- 7115tgt_name | Optional | string | Parent NVMe-oF target name. 7116 7117#### Response 7118 7119The response is an object containing NVMf subsystem statistics. 7120In the response, `admin_qpairs` and `io_qpairs` are reflecting cumulative queue pair counts while 7121`current_admin_qpairs` and `current_io_qpairs` are showing the current number. 7122 7123#### Example 7124 7125Example request: 7126 7127~~~json 7128{ 7129 "jsonrpc": "2.0", 7130 "method": "nvmf_get_stats", 7131 "id": 1 7132} 7133~~~ 7134 7135Example response: 7136 7137~~~json 7138{ 7139 "jsonrpc": "2.0", 7140 "id": 1, 7141 "result": { 7142 "tick_rate": 2400000000, 7143 "poll_groups": [ 7144 { 7145 "name": "app_thread", 7146 "admin_qpairs": 1, 7147 "io_qpairs": 4, 7148 "current_admin_qpairs": 1, 7149 "current_io_qpairs": 2, 7150 "pending_bdev_io": 1721, 7151 "transports": [ 7152 { 7153 "trtype": "RDMA", 7154 "pending_data_buffer": 12131888, 7155 "devices": [ 7156 { 7157 "name": "mlx5_1", 7158 "polls": 72284105, 7159 "completions": 0, 7160 "requests": 0, 7161 "request_latency": 0, 7162 "pending_free_request": 0, 7163 "pending_rdma_read": 0, 7164 "pending_rdma_write": 0, 7165 "total_send_wrs": 0, 7166 "send_doorbell_updates": 0, 7167 "total_recv_wrs": 0, 7168 "recv_doorbell_updates": 1 7169 }, 7170 { 7171 "name": "mlx5_0", 7172 "polls": 72284105, 7173 "completions": 15165875, 7174 "requests": 7582935, 7175 "request_latency": 1249323766184, 7176 "pending_free_request": 0, 7177 "pending_rdma_read": 337602, 7178 "pending_rdma_write": 0, 7179 "total_send_wrs": 15165875, 7180 "send_doorbell_updates": 1516587, 7181 "total_recv_wrs": 15165875, 7182 "recv_doorbell_updates": 1516587 7183 } 7184 ] 7185 } 7186 ] 7187 } 7188 ] 7189 } 7190} 7191~~~ 7192 7193### nvmf_set_crdt {#rpc_nvmf_set_crdt} 7194 7195Set the 3 CRDT (Command Retry Delay Time) values. For details about 7196CRDT, please refer to the NVMe specification. Currently all the 7197SPDK nvmf subsystems share the same CRDT values. The default values 7198are 0. This rpc can only be invoked in STARTUP stage. All values are 7199in units of 100 milliseconds (same as the NVMe specification). 7200 7201#### Parameters 7202 7203Name | Optional | Type | Description 7204----------------------- | -------- | ----------- | ----------- 7205crdt1 | Optional | number | Command Retry Delay Time 1 7206crdt2 | Optional | number | Command Retry Delay Time 2 7207crdt3 | Optional | number | Command Retry Delay Time 3 7208 7209## Vhost Target {#jsonrpc_components_vhost_tgt} 7210 7211The following common preconditions need to be met in all target types. 7212 7213Controller name will be used to create UNIX domain socket. This implies that name concatenated with vhost socket 7214directory path needs to be valid UNIX socket name. 7215 7216@ref cpu_mask parameter is used to choose CPU on which pollers will be launched when new initiator is connecting. 7217It must be a subset of application CPU mask. Default value is CPU mask of the application. 7218 7219### vhost_controller_set_coalescing {#rpc_vhost_controller_set_coalescing} 7220 7221Controls interrupt coalescing for specific target. Because `delay_base_us` is used to calculate delay in CPU ticks 7222there is no hardcoded limit for this parameter. Only limitation is that final delay in CPU ticks might not overflow 722332 bit unsigned integer (which is more than 1s @ 4GHz CPU). In real scenarios `delay_base_us` should be much lower 7224than 150us. To disable coalescing set `delay_base_us` to 0. 7225 7226#### Parameters 7227 7228Name | Optional | Type | Description 7229----------------------- | -------- | ----------- | ----------- 7230ctrlr | Required | string | Controller name 7231delay_base_us | Required | number | Base (minimum) coalescing time in microseconds 7232iops_threshold | Required | number | Coalescing activation level greater than 0 in IO per second 7233 7234#### Example 7235 7236Example request: 7237 7238~~~json 7239{ 7240 "params": { 7241 "iops_threshold": 100000, 7242 "ctrlr": "VhostScsi0", 7243 "delay_base_us": 80 7244 }, 7245 "jsonrpc": "2.0", 7246 "method": "vhost_controller_set_coalescing", 7247 "id": 1 7248} 7249~~~ 7250 7251Example response: 7252 7253~~~json 7254{ 7255 "jsonrpc": "2.0", 7256 "id": 1, 7257 "result": true 7258} 7259~~~ 7260 7261### vhost_create_scsi_controller {#rpc_vhost_create_scsi_controller} 7262 7263Construct vhost SCSI target. 7264 7265#### Parameters 7266 7267Name | Optional | Type | Description 7268----------------------- | -------- | ----------- | ----------- 7269ctrlr | Required | string | Controller name 7270cpumask | Optional | string | @ref cpu_mask for this controller 7271 7272#### Example 7273 7274Example request: 7275 7276~~~json 7277{ 7278 "params": { 7279 "cpumask": "0x2", 7280 "ctrlr": "VhostScsi0" 7281 }, 7282 "jsonrpc": "2.0", 7283 "method": "vhost_create_scsi_controller", 7284 "id": 1 7285} 7286~~~ 7287 7288Example response: 7289 7290~~~json 7291{ 7292 "jsonrpc": "2.0", 7293 "id": 1, 7294 "result": true 7295} 7296~~~ 7297 7298### vhost_scsi_controller_add_target {#rpc_vhost_scsi_controller_add_target} 7299 7300In vhost target `ctrlr` create SCSI target with ID `scsi_target_num` and add `bdev_name` as LUN 0. 7301 7302#### Parameters 7303 7304Name | Optional | Type | Description 7305----------------------- | -------- | ----------- | ----------- 7306ctrlr | Required | string | Controller name 7307scsi_target_num | Required | number | SCSI target ID between 0 and 7 or -1 to use first free ID. 7308bdev_name | Required | string | Name of bdev to expose as a LUN 0 7309 7310#### Response 7311 7312SCSI target ID. 7313 7314#### Example 7315 7316Example request: 7317 7318~~~json 7319{ 7320 "params": { 7321 "scsi_target_num": 1, 7322 "bdev_name": "Malloc0", 7323 "ctrlr": "VhostScsi0" 7324 }, 7325 "jsonrpc": "2.0", 7326 "method": "vhost_scsi_controller_add_target", 7327 "id": 1 7328} 7329~~~ 7330 7331Example response: 7332 7333~~~json 7334response: 7335{ 7336 "jsonrpc": "2.0", 7337 "id": 1, 7338 "result": 1 7339} 7340~~~ 7341 7342### vhost_scsi_controller_remove_target {#rpc_vhost_scsi_controller_remove_target} 7343 7344Remove SCSI target ID `scsi_target_num` from vhost target `scsi_target_num`. 7345 7346This method will fail if initiator is connected, but doesn't support hot-remove (the `VIRTIO_SCSI_F_HOTPLUG` is not negotiated). 7347 7348#### Parameters 7349 7350Name | Optional | Type | Description 7351----------------------- | -------- | ----------- | ----------- 7352ctrlr | Required | string | Controller name 7353scsi_target_num | Required | number | SCSI target ID between 0 and 7 7354 7355#### Example 7356 7357Example request: 7358 7359~~~json 7360request: 7361{ 7362 "params": { 7363 "scsi_target_num": 1, 7364 "ctrlr": "VhostScsi0" 7365 }, 7366 "jsonrpc": "2.0", 7367 "method": "vhost_scsi_controller_remove_target", 7368 "id": 1 7369} 7370~~~ 7371 7372Example response: 7373 7374~~~json 7375{ 7376 "jsonrpc": "2.0", 7377 "id": 1, 7378 "result": true 7379} 7380~~~ 7381 7382### vhost_create_blk_controller {#rpc_vhost_create_blk_controller} 7383 7384Create vhost block controller 7385 7386If `readonly` is `true` then vhost block target will be created as read only and fail any write requests. 7387The `VIRTIO_BLK_F_RO` feature flag will be offered to the initiator. 7388 7389#### Parameters 7390 7391Name | Optional | Type | Description 7392----------------------- | -------- | ----------- | ----------- 7393ctrlr | Required | string | Controller name 7394bdev_name | Required | string | Name of bdev to expose block device 7395readonly | Optional | boolean | If true, this target will be read only (default: false) 7396cpumask | Optional | string | @ref cpu_mask for this controller 7397 7398#### Example 7399 7400Example request: 7401 7402~~~json 7403{ 7404 "params": { 7405 "dev_name": "Malloc0", 7406 "ctrlr": "VhostBlk0" 7407 }, 7408 "jsonrpc": "2.0", 7409 "method": "vhost_create_blk_controller", 7410 "id": 1 7411} 7412~~~ 7413 7414Example response: 7415 7416~~~json 7417{ 7418 "jsonrpc": "2.0", 7419 "id": 1, 7420 "result": true 7421} 7422~~~ 7423 7424### vhost_get_controllers {#rpc_vhost_get_controllers} 7425 7426Display information about all or specific vhost controller(s). 7427 7428#### Parameters 7429 7430The user may specify no parameters in order to list all controllers, or a controller may be 7431specified by name. 7432 7433Name | Optional | Type | Description 7434----------------------- | -------- | ----------- | ----------- 7435name | Optional | string | Vhost controller name 7436 7437#### Response {#rpc_vhost_get_controllers_response} 7438 7439Response is an array of objects describing requested controller(s). Common fields are: 7440 7441Name | Type | Description 7442----------------------- | ----------- | ----------- 7443ctrlr | string | Controller name 7444cpumask | string | @ref cpu_mask of this controller 7445delay_base_us | number | Base (minimum) coalescing time in microseconds (0 if disabled) 7446iops_threshold | number | Coalescing activation level 7447backend_specific | object | Backend specific informations 7448 7449### Vhost block {#rpc_vhost_get_controllers_blk} 7450 7451`backend_specific` contains one `block` object of type: 7452 7453Name | Type | Description 7454----------------------- | ----------- | ----------- 7455bdev | string | Backing bdev name or Null if bdev is hot-removed 7456readonly | boolean | True if controllers is readonly, false otherwise 7457 7458### Vhost SCSI {#rpc_vhost_get_controllers_scsi} 7459 7460`backend_specific` contains `scsi` array of following objects: 7461 7462Name | Type | Description 7463----------------------- | ----------- | ----------- 7464target_name | string | Name of this SCSI target 7465id | number | Unique SPDK global SCSI target ID 7466scsi_dev_num | number | SCSI target ID initiator will see when scanning this controller 7467luns | array | array of objects describing @ref rpc_vhost_get_controllers_scsi_luns 7468 7469### Vhost SCSI LUN {#rpc_vhost_get_controllers_scsi_luns} 7470 7471Object of type: 7472 7473Name | Type | Description 7474----------------------- | ----------- | ----------- 7475id | number | SCSI LUN ID 7476bdev_name | string | Backing bdev name 7477 7478### Vhost NVMe {#rpc_vhost_get_controllers_nvme} 7479 7480`backend_specific` contains `namespaces` array of following objects: 7481 7482Name | Type | Description 7483----------------------- | ----------- | ----------- 7484nsid | number | Namespace ID 7485bdev | string | Backing bdev name 7486 7487#### Example 7488 7489Example request: 7490 7491~~~json 7492{ 7493 "jsonrpc": "2.0", 7494 "method": "vhost_get_controllers", 7495 "id": 1 7496} 7497~~~ 7498 7499Example response: 7500 7501~~~json 7502{ 7503 "jsonrpc": "2.0", 7504 "id": 1, 7505 "result": [ 7506 { 7507 "cpumask": "0x2", 7508 "backend_specific": { 7509 "block": { 7510 "readonly": false, 7511 "bdev": "Malloc0" 7512 } 7513 }, 7514 "iops_threshold": 60000, 7515 "ctrlr": "VhostBlk0", 7516 "delay_base_us": 100 7517 }, 7518 { 7519 "cpumask": "0x2", 7520 "backend_specific": { 7521 "scsi": [ 7522 { 7523 "target_name": "Target 2", 7524 "luns": [ 7525 { 7526 "id": 0, 7527 "bdev_name": "Malloc1" 7528 } 7529 ], 7530 "id": 0, 7531 "scsi_dev_num": 2 7532 }, 7533 { 7534 "target_name": "Target 5", 7535 "luns": [ 7536 { 7537 "id": 0, 7538 "bdev_name": "Malloc2" 7539 } 7540 ], 7541 "id": 1, 7542 "scsi_dev_num": 5 7543 } 7544 ] 7545 }, 7546 "iops_threshold": 60000, 7547 "ctrlr": "VhostScsi0", 7548 "delay_base_us": 0 7549 }, 7550 { 7551 "cpumask": "0x2", 7552 "backend_specific": { 7553 "namespaces": [ 7554 { 7555 "bdev": "Malloc3", 7556 "nsid": 1 7557 }, 7558 { 7559 "bdev": "Malloc4", 7560 "nsid": 2 7561 } 7562 ] 7563 }, 7564 "iops_threshold": 60000, 7565 "ctrlr": "VhostNvme0", 7566 "delay_base_us": 0 7567 } 7568 ] 7569} 7570~~~ 7571 7572### vhost_delete_controller {#rpc_vhost_delete_controller} 7573 7574Remove vhost target. 7575 7576This call will fail if there is an initiator connected or there is at least one SCSI target configured in case of 7577vhost SCSI target. In the later case please remove all SCSI targets first using @ref rpc_vhost_scsi_controller_remove_target. 7578 7579#### Parameters 7580 7581Name | Optional | Type | Description 7582----------------------- | -------- | ----------- | ----------- 7583ctrlr | Required | string | Controller name 7584 7585#### Example 7586 7587Example request: 7588 7589~~~json 7590{ 7591 "params": { 7592 "ctrlr": "VhostNvme0" 7593 }, 7594 "jsonrpc": "2.0", 7595 "method": "vhost_delete_controller", 7596 "id": 1 7597} 7598~~~ 7599 7600Example response: 7601 7602~~~json 7603{ 7604 "jsonrpc": "2.0", 7605 "id": 1, 7606 "result": true 7607} 7608~~~ 7609 7610## Logical Volume {#jsonrpc_components_lvol} 7611 7612Identification of logical volume store and logical volume is explained first. 7613 7614A logical volume store has a UUID and a name for its identification. 7615The UUID is generated on creation and it can be used as a unique identifier. 7616The name is specified on creation and can be renamed. 7617Either UUID or name is used to access logical volume store in RPCs. 7618 7619A logical volume has a UUID and a name for its identification. 7620The UUID of the logical volume is generated on creation and it can be unique identifier. 7621The alias of the logical volume takes the format _lvs_name/lvol_name_ where: 7622 7623* _lvs_name_ is the name of the logical volume store. 7624* _lvol_name_ is specified on creation and can be renamed. 7625 7626### bdev_lvol_create_lvstore {#rpc_bdev_lvol_create_lvstore} 7627 7628Construct a logical volume store. 7629 7630#### Parameters 7631 7632Name | Optional | Type | Description 7633----------------------- | -------- | ----------- | ----------- 7634bdev_name | Required | string | Bdev on which to construct logical volume store 7635lvs_name | Required | string | Name of the logical volume store to create 7636cluster_sz | Optional | number | Cluster size of the logical volume store in bytes 7637clear_method | Optional | string | Change clear method for data region. Available: none, unmap (default), write_zeroes 7638 7639#### Response 7640 7641UUID of the created logical volume store is returned. 7642 7643#### Example 7644 7645Example request: 7646 7647~~~json 7648{ 7649 "jsonrpc": "2.0", 7650 "id": 1, 7651 "method": "bdev_lvol_create_lvstore", 7652 "params": { 7653 "lvs_name": "LVS0", 7654 "bdev_name": "Malloc0" 7655 "clear_method": "write_zeroes" 7656 } 7657} 7658~~~ 7659 7660Example response: 7661 7662~~~json 7663{ 7664 "jsonrpc": "2.0", 7665 "id": 1, 7666 "result": "a9959197-b5e2-4f2d-8095-251ffb6985a5" 7667} 7668~~~ 7669 7670### bdev_lvol_delete_lvstore {#rpc_bdev_lvol_delete_lvstore} 7671 7672Destroy a logical volume store. 7673 7674#### Parameters 7675 7676Name | Optional | Type | Description 7677----------------------- | -------- | ----------- | ----------- 7678uuid | Optional | string | UUID of the logical volume store to destroy 7679lvs_name | Optional | string | Name of the logical volume store to destroy 7680 7681Either uuid or lvs_name must be specified, but not both. 7682 7683#### Example 7684 7685Example request: 7686 7687~~~json 7688{ 7689 "jsonrpc": "2.0", 7690 "method": "bdev_lvol_delete_lvstore", 7691 "id": 1 7692 "params": { 7693 "uuid": "a9959197-b5e2-4f2d-8095-251ffb6985a5" 7694 } 7695} 7696~~~ 7697 7698Example response: 7699 7700~~~json 7701{ 7702 "jsonrpc": "2.0", 7703 "id": 1, 7704 "result": true 7705} 7706~~~ 7707 7708### bdev_lvol_get_lvstores {#rpc_bdev_lvol_get_lvstores} 7709 7710Get a list of logical volume stores. 7711 7712#### Parameters 7713 7714Name | Optional | Type | Description 7715----------------------- | -------- | ----------- | ----------- 7716uuid | Optional | string | UUID of the logical volume store to retrieve information about 7717lvs_name | Optional | string | Name of the logical volume store to retrieve information about 7718 7719Either uuid or lvs_name may be specified, but not both. 7720If both uuid and lvs_name are omitted, information about all logical volume stores is returned. 7721 7722#### Example 7723 7724Example request: 7725 7726~~~json 7727{ 7728 "jsonrpc": "2.0", 7729 "method": "bdev_lvol_get_lvstores", 7730 "id": 1, 7731 "params": { 7732 "lvs_name": "LVS0" 7733 } 7734} 7735~~~ 7736 7737Example response: 7738 7739~~~json 7740{ 7741 "jsonrpc": "2.0", 7742 "id": 1, 7743 "result": [ 7744 { 7745 "uuid": "a9959197-b5e2-4f2d-8095-251ffb6985a5", 7746 "base_bdev": "Malloc0", 7747 "free_clusters": 31, 7748 "cluster_size": 4194304, 7749 "total_data_clusters": 31, 7750 "block_size": 4096, 7751 "name": "LVS0" 7752 } 7753 ] 7754} 7755~~~ 7756 7757### bdev_lvol_rename_lvstore {#rpc_bdev_lvol_rename_lvstore} 7758 7759Rename a logical volume store. 7760 7761#### Parameters 7762 7763Name | Optional | Type | Description 7764----------------------- | -------- | ----------- | ----------- 7765old_name | Required | string | Existing logical volume store name 7766new_name | Required | string | New logical volume store name 7767 7768#### Example 7769 7770Example request: 7771 7772~~~json 7773{ 7774 "jsonrpc": "2.0", 7775 "method": "bdev_lvol_rename_lvstore", 7776 "id": 1, 7777 "params": { 7778 "old_name": "LVS0", 7779 "new_name": "LVS2" 7780 } 7781} 7782~~~ 7783 7784Example response: 7785 7786~~~json 7787{ 7788 "jsonrpc": "2.0", 7789 "id": 1, 7790 "result": true 7791} 7792~~~ 7793 7794### bdev_lvol_create {#rpc_bdev_lvol_create} 7795 7796Create a logical volume on a logical volume store. 7797 7798#### Parameters 7799 7800Name | Optional | Type | Description 7801----------------------- | -------- | ----------- | ----------- 7802lvol_name | Required | string | Name of logical volume to create 7803size | Required | number | Desired size of logical volume in bytes 7804thin_provision | Optional | boolean | True to enable thin provisioning 7805uuid | Optional | string | UUID of logical volume store to create logical volume on 7806lvs_name | Optional | string | Name of logical volume store to create logical volume on 7807clear_method | Optional | string | Change default data clusters clear method. Available: none, unmap, write_zeroes 7808 7809Size will be rounded up to a multiple of cluster size. Either uuid or lvs_name must be specified, but not both. 7810lvol_name will be used in the alias of the created logical volume. 7811 7812#### Response 7813 7814UUID of the created logical volume is returned. 7815 7816#### Example 7817 7818Example request: 7819 7820~~~json 7821{ 7822 "jsonrpc": "2.0", 7823 "method": "bdev_lvol_create", 7824 "id": 1, 7825 "params": { 7826 "lvol_name": "LVOL0", 7827 "size": 1048576, 7828 "lvs_name": "LVS0", 7829 "clear_method": "unmap", 7830 "thin_provision": true 7831 } 7832} 7833~~~ 7834 7835Example response: 7836 7837~~~json 7838{ 7839 "jsonrpc": "2.0", 7840 "id": 1, 7841 "result": "1b38702c-7f0c-411e-a962-92c6a5a8a602" 7842} 7843~~~ 7844 7845### bdev_lvol_snapshot {#rpc_bdev_lvol_snapshot} 7846 7847Capture a snapshot of the current state of a logical volume. 7848 7849#### Parameters 7850 7851Name | Optional | Type | Description 7852----------------------- | -------- | ----------- | ----------- 7853lvol_name | Required | string | UUID or alias of the logical volume to create a snapshot from 7854snapshot_name | Required | string | Name for the newly created snapshot 7855 7856#### Response 7857 7858UUID of the created logical volume snapshot is returned. 7859 7860#### Example 7861 7862Example request: 7863 7864~~~json 7865{ 7866 "jsonrpc": "2.0", 7867 "method": "bdev_lvol_snapshot", 7868 "id": 1, 7869 "params": { 7870 "lvol_name": "1b38702c-7f0c-411e-a962-92c6a5a8a602", 7871 "snapshot_name": "SNAP1" 7872 } 7873} 7874~~~ 7875 7876Example response: 7877 7878~~~json 7879{ 7880 "jsonrpc": "2.0", 7881 "id": 1, 7882 "result": "cc8d7fdf-7865-4d1f-9fc6-35da8e368670" 7883} 7884~~~ 7885 7886### bdev_lvol_clone {#rpc_bdev_lvol_clone} 7887 7888Create a logical volume based on a snapshot. 7889 7890#### Parameters 7891 7892Name | Optional | Type | Description 7893----------------------- | -------- | ----------- | ----------- 7894snapshot_name | Required | string | UUID or alias of the snapshot to clone 7895clone_name | Required | string | Name for the logical volume to create 7896 7897#### Response 7898 7899UUID of the created logical volume clone is returned. 7900 7901#### Example 7902 7903Example request: 7904 7905~~~json 7906{ 7907 "jsonrpc": "2.0" 7908 "method": "bdev_lvol_clone", 7909 "id": 1, 7910 "params": { 7911 "snapshot_name": "cc8d7fdf-7865-4d1f-9fc6-35da8e368670", 7912 "clone_name": "CLONE1" 7913 } 7914} 7915~~~ 7916 7917Example response: 7918 7919~~~json 7920{ 7921 "jsonrpc": "2.0", 7922 "id": 1, 7923 "result": "8d87fccc-c278-49f0-9d4c-6237951aca09" 7924} 7925~~~ 7926 7927### bdev_lvol_rename {#rpc_bdev_lvol_rename} 7928 7929Rename a logical volume. New name will rename only the alias of the logical volume. 7930 7931#### Parameters 7932 7933Name | Optional | Type | Description 7934----------------------- | -------- | ----------- | ----------- 7935old_name | Required | string | UUID or alias of the existing logical volume 7936new_name | Required | string | New logical volume name 7937 7938#### Example 7939 7940Example request: 7941 7942~~~json 7943{ 7944 "jsonrpc": "2.0", 7945 "method": "bdev_lvol_rename", 7946 "id": 1, 7947 "params": { 7948 "old_name": "067df606-6dbc-4143-a499-0d05855cb3b8", 7949 "new_name": "LVOL2" 7950 } 7951} 7952~~~ 7953 7954Example response: 7955 7956~~~json 7957{ 7958 "jsonrpc": "2.0", 7959 "id": 1, 7960 "result": true 7961} 7962~~~ 7963 7964### bdev_lvol_resize {#rpc_bdev_lvol_resize} 7965 7966Resize a logical volume. 7967 7968#### Parameters 7969 7970Name | Optional | Type | Description 7971----------------------- | -------- | ----------- | ----------- 7972name | Required | string | UUID or alias of the logical volume to resize 7973size | Required | number | Desired size of the logical volume in bytes 7974 7975#### Example 7976 7977Example request: 7978 7979~~~json 7980{ 7981 "jsonrpc": "2.0", 7982 "method": "bdev_lvol_resize", 7983 "id": 1, 7984 "params": { 7985 "name": "51638754-ca16-43a7-9f8f-294a0805ab0a", 7986 "size": 2097152 7987 } 7988} 7989~~~ 7990 7991Example response: 7992 7993~~~json 7994{ 7995 "jsonrpc": "2.0", 7996 "id": 1, 7997 "result": true 7998} 7999~~~ 8000 8001### bdev_lvol_set_read_only{#rpc_bdev_lvol_set_read_only} 8002 8003Mark logical volume as read only. 8004 8005#### Parameters 8006 8007Name | Optional | Type | Description 8008----------------------- | -------- | ----------- | ----------- 8009name | Required | string | UUID or alias of the logical volume to set as read only 8010 8011#### Example 8012 8013Example request: 8014 8015~~~json 8016{ 8017 "jsonrpc": "2.0", 8018 "method": "bdev_lvol_set_read_only", 8019 "id": 1, 8020 "params": { 8021 "name": "51638754-ca16-43a7-9f8f-294a0805ab0a", 8022 } 8023} 8024~~~ 8025 8026Example response: 8027 8028~~~json 8029{ 8030 "jsonrpc": "2.0", 8031 "id": 1, 8032 "result": true 8033} 8034~~~ 8035 8036### bdev_lvol_delete {#rpc_bdev_lvol_delete} 8037 8038Destroy a logical volume. 8039 8040#### Parameters 8041 8042Name | Optional | Type | Description 8043----------------------- | -------- | ----------- | ----------- 8044name | Required | string | UUID or alias of the logical volume to destroy 8045 8046#### Example 8047 8048Example request: 8049 8050~~~json 8051{ 8052 "jsonrpc": "2.0", 8053 "method": "bdev_lvol_delete", 8054 "id": 1, 8055 "params": { 8056 "name": "51638754-ca16-43a7-9f8f-294a0805ab0a" 8057 } 8058} 8059~~~ 8060 8061Example response: 8062 8063~~~json 8064{ 8065 "jsonrpc": "2.0", 8066 "id": 1, 8067 "result": true 8068} 8069~~~ 8070 8071### bdev_lvol_inflate {#rpc_bdev_lvol_inflate} 8072 8073Inflate a logical volume. All unallocated clusters are allocated and copied from the parent or zero filled 8074if not allocated in the parent. Then all dependencies on the parent are removed. 8075 8076### Parameters 8077 8078Name | Optional | Type | Description 8079----------------------- | -------- | ----------- | ----------- 8080name | Required | string | UUID or alias of the logical volume to inflate 8081 8082#### Example 8083 8084Example request: 8085 8086~~~json 8087{ 8088 "jsonrpc": "2.0", 8089 "method": "bdev_lvol_inflate", 8090 "id": 1, 8091 "params": { 8092 "name": "8d87fccc-c278-49f0-9d4c-6237951aca09" 8093 } 8094} 8095~~~ 8096 8097Example response: 8098 8099~~~json 8100{ 8101 "jsonrpc": "2.0", 8102 "id": 1, 8103 "result": true 8104} 8105~~~ 8106 8107### bdev_lvol_decouple_parent {#rpc_bdev_lvol_decouple_parent} 8108 8109Decouple the parent of a logical volume. For unallocated clusters which is allocated in the parent, they are 8110allocated and copied from the parent, but for unallocated clusters which is thin provisioned in the parent, 8111they are kept thin provisioned. Then all dependencies on the parent are removed. 8112 8113#### Parameters 8114 8115Name | Optional | Type | Description 8116----------------------- | -------- | ----------- | ----------- 8117name | Required | string | UUID or alias of the logical volume to decouple the parent of it 8118 8119#### Example 8120 8121Example request: 8122 8123~~~json 8124{ 8125 "jsonrpc": "2.0", 8126 "method": "bdev_lvol_decouple_parent", 8127 "id": 1. 8128 "params": { 8129 "name": "8d87fccc-c278-49f0-9d4c-6237951aca09" 8130 } 8131} 8132~~~ 8133 8134Example response: 8135 8136~~~json 8137{ 8138 "jsonrpc": "2.0", 8139 "id": 1, 8140 "result": true 8141} 8142~~~ 8143 8144## RAID 8145 8146### bdev_raid_get_bdevs {#rpc_bdev_raid_get_bdevs} 8147 8148This is used to list all the raid bdev names based on the input category requested. Category should be one 8149of 'all', 'online', 'configuring' or 'offline'. 'all' means all the raid bdevs whether they are online or 8150configuring or offline. 'online' is the raid bdev which is registered with bdev layer. 'configuring' is 8151the raid bdev which does not have full configuration discovered yet. 'offline' is the raid bdev which is 8152not registered with bdev as of now and it has encountered any error or user has requested to offline 8153the raid bdev. 8154 8155#### Parameters 8156 8157Name | Optional | Type | Description 8158----------------------- | -------- | ----------- | ----------- 8159category | Required | string | all or online or configuring or offline 8160 8161#### Example 8162 8163Example request: 8164 8165~~~json 8166{ 8167 "jsonrpc": "2.0", 8168 "method": "bdev_raid_get_bdevs", 8169 "id": 1, 8170 "params": { 8171 "category": "all" 8172 } 8173} 8174~~~ 8175 8176Example response: 8177 8178~~~json 8179{ 8180 "jsonrpc": "2.0", 8181 "id": 1, 8182 "result": [ 8183 "Raid0" 8184 ] 8185} 8186~~~ 8187 8188### bdev_raid_create {#rpc_bdev_raid_create} 8189 8190Constructs new RAID bdev. 8191 8192#### Parameters 8193 8194Name | Optional | Type | Description 8195----------------------- | -------- | ----------- | ----------- 8196name | Required | string | RAID bdev name 8197strip_size_kb | Required | number | Strip size in KB 8198raid_level | Required | string | RAID level 8199base_bdevs | Required | string | Base bdevs name, whitespace separated list in quotes 8200 8201#### Example 8202 8203Example request: 8204 8205~~~json 8206{ 8207 "jsonrpc": "2.0", 8208 "method": "bdev_raid_create", 8209 "id": 1, 8210 "params": { 8211 "name": "Raid0", 8212 "raid_level": "0", 8213 "base_bdevs": [ 8214 "Malloc0", 8215 "Malloc1", 8216 "Malloc2", 8217 "Malloc3" 8218 ], 8219 "strip_size_kb": 4 8220 } 8221} 8222~~~ 8223 8224Example response: 8225 8226~~~json 8227{ 8228 "jsonrpc": "2.0", 8229 "id": 1, 8230 "result": true 8231} 8232~~~ 8233 8234### bdev_raid_delete {#rpc_bdev_raid_delete} 8235 8236Removes RAID bdev. 8237 8238#### Parameters 8239 8240Name | Optional | Type | Description 8241----------------------- | -------- | ----------- | ----------- 8242name | Required | string | RAID bdev name 8243 8244#### Example 8245 8246Example request: 8247 8248~~~json 8249{ 8250 "jsonrpc": "2.0", 8251 "method": "bdev_raid_delete", 8252 "id": 1, 8253 "params": { 8254 "name": "Raid0" 8255 } 8256} 8257~~~ 8258 8259Example response: 8260 8261~~~json 8262{ 8263 "jsonrpc": "2.0", 8264 "id": 1, 8265 "result": true 8266} 8267~~~ 8268 8269## SPLIT 8270 8271### bdev_split_create {#rpc_bdev_split_create} 8272 8273This is used to split an underlying block device and create several smaller equal-sized vbdevs. 8274 8275#### Parameters 8276 8277Name | Optional | Type | Description 8278----------------------- | -------- | ----------- | ----------- 8279base_bdev | Required | string | base bdev name 8280split_count | Required | number | number of splits 8281split_size_mb | Optional | number | size in MB to restrict the size 8282 8283#### Example 8284 8285Example request: 8286 8287~~~json 8288{ 8289 "jsonrpc": "2.0", 8290 "method": "bdev_split_create", 8291 "id": 1, 8292 "params": { 8293 "base_bdev": "Malloc0", 8294 "split_count": 4 8295 } 8296} 8297~~~ 8298 8299Example response: 8300 8301~~~json 8302{ 8303 "jsonrpc": "2.0", 8304 "id": 1, 8305 "result": [ 8306 "Malloc0p0", 8307 "Malloc0p1", 8308 "Malloc0p2", 8309 "Malloc0p3" 8310 ] 8311} 8312~~~ 8313 8314### bdev_split_delete {#rpc_bdev_split_delete} 8315 8316This is used to remove the split vbdevs. 8317 8318#### Parameters 8319 8320Name | Optional | Type | Description 8321----------------------- | -------- | ----------- | ----------- 8322base_bdev | Required | string | base bdev name 8323 8324#### Example 8325 8326Example request: 8327 8328~~~json 8329{ 8330 "jsonrpc": "2.0", 8331 "method": "bdev_split_delete", 8332 "id": 1, 8333 "params": { 8334 "base_bdev": "Malloc0" 8335 } 8336} 8337~~~ 8338 8339Example response: 8340 8341~~~json 8342{ 8343 "jsonrpc": "2.0", 8344 "id": 1, 8345 "result": true 8346} 8347~~~ 8348 8349## Uring 8350 8351### bdev_uring_create {#rpc_bdev_uring_create} 8352 8353Create a bdev with io_uring backend. 8354 8355#### Parameters 8356 8357Name | Optional | Type | Description 8358----------------------- | -------- | ----------- | ----------- 8359filename | Required | string | path to device or file (ex: /dev/nvme0n1) 8360name | Required | string | name of bdev 8361block_size | Optional | number | block size of device (If omitted, get the block size from the file) 8362 8363#### Example 8364 8365Example request: 8366 8367~~~json 8368{ 8369 "jsonrpc": "2.0", 8370 "method": "bdev_uring_create", 8371 "id": 1, 8372 "params": { 8373 "name": "bdev_u0", 8374 "filename": "/dev/nvme0n1", 8375 "block_size": 512 8376 } 8377} 8378~~~ 8379 8380Example response: 8381 8382~~~json 8383{ 8384 "jsonrpc": "2.0", 8385 "id": 1, 8386 "result": "bdev_u0" 8387} 8388~~~ 8389 8390### bdev_uring_delete {#rpc_bdev_uring_delete} 8391 8392Remove a uring bdev. 8393 8394#### Parameters 8395 8396Name | Optional | Type | Description 8397----------------------- | -------- | ----------- | ----------- 8398name | Required | string | name of uring bdev to delete 8399 8400#### Example 8401 8402Example request: 8403 8404~~~json 8405{ 8406 "jsonrpc": "2.0", 8407 "method": "bdev_uring_delete", 8408 "id": 1, 8409 "params": { 8410 "name": "bdev_u0" 8411 } 8412} 8413~~~ 8414 8415Example response: 8416 8417~~~json 8418{ 8419 "jsonrpc": "2.0", 8420 "id": 1, 8421 "result": true 8422} 8423~~~ 8424 8425## OPAL 8426 8427### bdev_nvme_opal_init {#rpc_bdev_nvme_opal_init} 8428 8429This is used to initialize OPAL of a given NVMe ctrlr, including taking ownership and activating. 8430 8431#### Parameters 8432 8433Name | Optional | Type | Description 8434----------------------- | -------- | ----------- | ----------- 8435nvme_ctrlr_name | Required | string | name of nvme ctrlr 8436password | Required | string | admin password of OPAL 8437 8438#### Example 8439 8440Example request: 8441 8442~~~json 8443{ 8444 "jsonrpc": "2.0", 8445 "method": "bdev_nvme_opal_init", 8446 "id": 1, 8447 "params": { 8448 "nvme_ctrlr_name": "nvme0", 8449 "password": "*****" 8450 } 8451} 8452~~~ 8453 8454Example response: 8455 8456~~~json 8457{ 8458 "jsonrpc": "2.0", 8459 "id": 1, 8460 "result": true 8461} 8462~~~ 8463 8464### bdev_nvme_opal_revert {#rpc_bdev_nvme_opal_revert} 8465 8466This is used to revert OPAL to its factory settings. Erase all user configuration and data. 8467 8468#### Parameters 8469 8470Name | Optional | Type | Description 8471----------------------- | -------- | ----------- | ----------- 8472nvme_ctrlr_name | Required | string | name of nvme ctrlr 8473password | Required | string | admin password of OPAL 8474 8475#### Example 8476 8477Example request: 8478 8479~~~json 8480{ 8481 "jsonrpc": "2.0", 8482 "method": "bdev_nvme_opal_revert", 8483 "id": 1, 8484 "params": { 8485 "nvme_ctrlr_name": "nvme0", 8486 "password": "*****" 8487 } 8488} 8489~~~ 8490 8491Example response: 8492 8493~~~json 8494{ 8495 "jsonrpc": "2.0", 8496 "id": 1, 8497 "result": true 8498} 8499~~~ 8500 8501### bdev_opal_create {#rpc_bdev_opal_create} 8502 8503This is used to create an OPAL virtual bdev. 8504 8505#### Parameters 8506 8507Name | Optional | Type | Description 8508----------------------- | -------- | ----------- | ----------- 8509nvme_ctrlr_name | Required | string | name of nvme ctrlr that supports OPAL 8510nsid | Required | number | namespace ID 8511locking_range_id | Required | number | OPAL locking range ID 8512range_start | Required | number | locking range start LBA 8513range_length | Required | number | locking range length 8514password | Required | string | admin password of OPAL 8515 8516#### Response 8517 8518The response is the name of created OPAL virtual bdev. 8519 8520#### Example 8521 8522Example request: 8523 8524~~~json 8525{ 8526 "jsonrpc": "2.0", 8527 "method": "bdev_opal_create", 8528 "id": 1, 8529 "params": { 8530 "nvme_ctrlr_name": "nvme0", 8531 "nsid": 1, 8532 "locking_range_id": 1, 8533 "range_start": 0, 8534 "range_length": 4096, 8535 "password": "*****" 8536 } 8537} 8538~~~ 8539 8540Example response: 8541 8542~~~json 8543{ 8544 "jsonrpc": "2.0", 8545 "id": 1, 8546 "result": "nvme0n1r1" 8547} 8548~~~ 8549 8550### bdev_opal_get_info {#rpc_bdev_opal_get_info} 8551 8552This is used to get information of a given OPAL bdev. 8553 8554#### Parameters 8555 8556Name | Optional | Type | Description 8557----------------------- | -------- | ----------- | ----------- 8558bdev_name | Required | string | name of OPAL vbdev 8559password | Required | string | admin password 8560 8561#### Response 8562 8563The response is the locking info of OPAL virtual bdev. 8564 8565#### Example 8566 8567Example request: 8568 8569~~~json 8570{ 8571 "jsonrpc": "2.0", 8572 "method": "bdev_opal_get_info", 8573 "id": 1, 8574 "params": { 8575 "bdev_name": "nvme0n1r1", 8576 "password": "*****" 8577 } 8578} 8579~~~ 8580 8581Example response: 8582 8583~~~json 8584{ 8585 "jsonrpc": "2.0", 8586 "id": 1, 8587 "result": { 8588 "name": "nvme0n1r1", 8589 "range_start": 0, 8590 "range_length": 4096, 8591 "read_lock_enabled": true, 8592 "write_lock_enabled": true, 8593 "read_locked": false, 8594 "write_locked": false 8595 } 8596} 8597~~~ 8598 8599### bdev_opal_delete {#rpc_bdev_opal_delete} 8600 8601This is used to delete OPAL vbdev. 8602 8603#### Parameters 8604 8605Name | Optional | Type | Description 8606----------------------- | -------- | ----------- | ----------- 8607bdev_name | Required | string | name of OPAL vbdev 8608password | Required | string | admin password 8609 8610#### Example 8611 8612Example request: 8613 8614~~~json 8615{ 8616 "jsonrpc": "2.0", 8617 "method": "bdev_opal_delete", 8618 "id": 1, 8619 "params": { 8620 "bdev_name": "nvme0n1r1", 8621 "password": "*****" 8622 } 8623} 8624~~~ 8625 8626Example response: 8627 8628~~~json 8629{ 8630 "jsonrpc": "2.0", 8631 "id": 1, 8632 "result": true 8633} 8634~~~ 8635 8636### bdev_opal_new_user {#rpc_bdev_opal_new_user} 8637 8638This enables a new user to the specified opal bdev so that the user can lock/unlock the bdev. 8639Recalling this for the same opal bdev, only the newest user will have the privilege. 8640 8641#### Parameters 8642 8643Name | Optional | Type | Description 8644----------------------- | -------- | ----------- | ----------- 8645bdev_name | Required | string | name of OPAL vbdev 8646admin_password | Required | string | admin password 8647user_id | Required | number | user ID 8648user_password | Required | string | user password 8649 8650#### Example 8651 8652Example request: 8653 8654~~~json 8655{ 8656 "jsonrpc": "2.0", 8657 "method": "bdev_opal_new_user", 8658 "id": 1, 8659 "params": { 8660 "bdev_name": "nvme0n1r1", 8661 "admin_password": "*****", 8662 "user_id": "1", 8663 "user_password": "********" 8664 } 8665} 8666~~~ 8667 8668Example response: 8669 8670~~~json 8671{ 8672 "jsonrpc": "2.0", 8673 "id": 1, 8674 "result": true 8675} 8676~~~ 8677 8678### bdev_opal_set_lock_state {#rpc_bdev_opal_set_lock_state} 8679 8680This is used to lock/unlock specific opal bdev providing user ID and password. 8681 8682#### Parameters 8683 8684Name | Optional | Type | Description 8685----------------------- | -------- | ----------- | ----------- 8686bdev_name | Required | string | name of OPAL vbdev 8687user_id | Required | number | user ID 8688password | Required | string | user password 8689lock_state | Required | string | lock state 8690 8691#### Example 8692 8693Example request: 8694 8695~~~json 8696{ 8697 "jsonrpc": "2.0", 8698 "method": "bdev_opal_set_lock_state", 8699 "id": 1, 8700 "params": { 8701 "bdev_name": "nvme0n1r1", 8702 "user_id": "1", 8703 "user_password": "********", 8704 "lock_state": "rwlock" 8705 } 8706} 8707~~~ 8708 8709Example response: 8710 8711~~~json 8712{ 8713 "jsonrpc": "2.0", 8714 "id": 1, 8715 "result": true 8716} 8717~~~ 8718 8719## Notifications 8720 8721### notify_get_types {#rpc_notify_get_types} 8722 8723Return list of all supported notification types. 8724 8725#### Parameters 8726 8727None 8728 8729#### Response 8730 8731The response is an array of strings - supported RPC notification types. 8732 8733#### Example 8734 8735Example request: 8736 8737~~~json 8738{ 8739 "jsonrpc": "2.0", 8740 "method": "notify_get_types", 8741 "id": 1 8742} 8743~~~ 8744 8745Example response: 8746 8747~~~json 8748{ 8749 "id": 1, 8750 "result": [ 8751 "bdev_register", 8752 "bdev_unregister" 8753 ], 8754 "jsonrpc": "2.0" 8755} 8756~~~ 8757 8758### notify_get_notifications {#notify_get_notifications} 8759 8760Request notifications. Returns array of notifications that happend since the specified id (or first that is available). 8761 8762Notice: Notifications are kept in circular buffer with limited size. Older notifications might be inaccessible 8763due to being overwritten by new ones. 8764 8765#### Parameters 8766 8767Name | Optional | Type | Description 8768----------------------- | -------- | ----------- | ----------- 8769id | Optional | number | First Event ID to fetch (default: first available). 8770max | Optional | number | Maximum number of event to return (default: no limit). 8771 8772#### Response 8773 8774Response is an array of event objects. 8775 8776Name | Optional | Type | Description 8777----------------------- | -------- | ----------- | ----------- 8778id | Optional | number | Event ID. 8779type | Optional | number | Type of the event. 8780ctx | Optional | string | Event context. 8781 8782#### Example 8783 8784Example request: 8785 8786~~~json 8787{ 8788 "id": 1, 8789 "jsonrpc": "2.0", 8790 "method": "notify_get_notifications", 8791 "params": { 8792 "id": 1, 8793 "max": 10 8794 } 8795} 8796 8797~~~ 8798 8799Example response: 8800 8801~~~json 8802{ 8803 "jsonrpc": "2.0", 8804 "id": 1, 8805 "result": [ 8806 { 8807 "ctx": "Malloc0", 8808 "type": "bdev_register", 8809 "id": 1 8810 }, 8811 { 8812 "ctx": "Malloc2", 8813 "type": "bdev_register", 8814 "id": 2 8815 } 8816 ] 8817} 8818~~~ 8819 8820## Linux Network Block Device (NBD) {#jsonrpc_components_nbd} 8821 8822SPDK supports exporting bdevs through Linux nbd. These devices then appear as standard Linux kernel block devices 8823and can be accessed using standard utilities like fdisk. 8824 8825In order to export a device over nbd, first make sure the Linux kernel nbd driver is loaded by running 'modprobe nbd'. 8826 8827### nbd_start_disk {#rpc_nbd_start_disk} 8828 8829Start to export one SPDK bdev as NBD disk 8830 8831#### Parameters 8832 8833Name | Optional | Type | Description 8834----------------------- | -------- | ----------- | ----------- 8835bdev_name | Required | string | Bdev name to export 8836nbd_device | Optional | string | NBD device name to assign 8837 8838#### Response 8839 8840Path of exported NBD disk 8841 8842#### Example 8843 8844Example request: 8845 8846~~~json 8847{ 8848 "params": { 8849 "nbd_device": "/dev/nbd1", 8850 "bdev_name": "Malloc1" 8851 }, 8852 "jsonrpc": "2.0", 8853 "method": "nbd_start_disk", 8854 "id": 1 8855} 8856~~~ 8857 8858Example response: 8859 8860~~~json 8861{ 8862 "jsonrpc": "2.0", 8863 "id": 1, 8864 "result": "/dev/nbd1" 8865} 8866~~~ 8867 8868### nbd_stop_disk {#rpc_nbd_stop_disk} 8869 8870Stop one NBD disk which is based on SPDK bdev. 8871 8872#### Parameters 8873 8874Name | Optional | Type | Description 8875----------------------- | -------- | ----------- | ----------- 8876nbd_device | Required | string | NBD device name to stop 8877 8878#### Example 8879 8880Example request: 8881 8882~~~json 8883{ 8884 "params": { 8885 "nbd_device": "/dev/nbd1", 8886 }, 8887 "jsonrpc": "2.0", 8888 "method": "nbd_stop_disk", 8889 "id": 1 8890} 8891~~~ 8892 8893Example response: 8894 8895~~~json 8896{ 8897 "jsonrpc": "2.0", 8898 "id": 1, 8899 "result": "true" 8900} 8901~~~ 8902 8903### nbd_get_disks {#rpc_nbd_get_disks} 8904 8905Display all or specified NBD device list 8906 8907#### Parameters 8908 8909Name | Optional | Type | Description 8910----------------------- | -------- | ----------- | ----------- 8911nbd_device | Optional | string | NBD device name to display 8912 8913#### Response 8914 8915The response is an array of exported NBD devices and their corresponding SPDK bdev. 8916 8917#### Example 8918 8919Example request: 8920 8921~~~json 8922{ 8923 "jsonrpc": "2.0", 8924 "method": "nbd_get_disks", 8925 "id": 1 8926} 8927~~~ 8928 8929Example response: 8930 8931~~~json 8932{ 8933 "jsonrpc": "2.0", 8934 "id": 1, 8935 "result": [ 8936 { 8937 "bdev_name": "Malloc0", 8938 "nbd_device": "/dev/nbd0" 8939 }, 8940 { 8941 "bdev_name": "Malloc1", 8942 "nbd_device": "/dev/nbd1" 8943 } 8944 ] 8945} 8946~~~ 8947 8948## Blobfs {#jsonrpc_components_blobfs} 8949 8950### blobfs_detect {#rpc_blobfs_detect} 8951 8952Detect whether a blobfs exists on bdev. 8953 8954#### Parameters 8955 8956Name | Optional | Type | Description 8957----------------------- | -------- | ----------- | ----------- 8958bdev_name | Required | string | Block device name to detect blobfs 8959 8960#### Response 8961 8962True if a blobfs exists on the bdev; False otherwise. 8963 8964#### Example 8965 8966Example request: 8967 8968~~~json 8969{ 8970 "jsonrpc": "2.0", 8971 "id": 1, 8972 "method": "blobfs_detect", 8973 "params": { 8974 "bdev_name": "Malloc0" 8975 } 8976} 8977~~~ 8978 8979Example response: 8980 8981~~~json 8982{ 8983 "jsonrpc": "2.0", 8984 "id": 1, 8985 "result": "true" 8986} 8987~~~ 8988 8989### blobfs_create {#rpc_blobfs_create} 8990 8991Build blobfs on bdev. 8992 8993#### Parameters 8994 8995Name | Optional | Type | Description 8996----------------------- | -------- | ----------- | ----------- 8997bdev_name | Required | string | Block device name to create blobfs 8998cluster_sz | Optional | number | Size of cluster in bytes. Must be multiple of 4KiB page size, default and minimal value is 1M. 8999 9000#### Example 9001 9002Example request: 9003 9004~~~json 9005{ 9006 "jsonrpc": "2.0", 9007 "id": 1, 9008 "method": "blobfs_create", 9009 "params": { 9010 "bdev_name": "Malloc0", 9011 "cluster_sz": 1M 9012 } 9013} 9014~~~ 9015 9016Example response: 9017 9018~~~json 9019{ 9020 "jsonrpc": "2.0", 9021 "id": 1, 9022 "result": "true" 9023} 9024~~~ 9025 9026### blobfs_mount {#rpc_blobfs_mount} 9027 9028Mount a blobfs on bdev to one host path through FUSE 9029 9030#### Parameters 9031 9032Name | Optional | Type | Description 9033----------------------- | -------- | ----------- | ----------- 9034bdev_name | Required | string | Block device name where the blobfs is 9035mountpoint | Required | string | Mountpoint path in host to mount blobfs 9036 9037#### Example 9038 9039Example request: 9040 9041~~~json 9042{ 9043 "jsonrpc": "2.0", 9044 "id": 1, 9045 "method": ""blobfs_mount"", 9046 "params": { 9047 "bdev_name": "Malloc0", 9048 "mountpoint": "/mnt/" 9049 } 9050} 9051~~~ 9052 9053Example response: 9054 9055~~~json 9056{ 9057 "jsonrpc": "2.0", 9058 "id": 1, 9059 "result": "true" 9060} 9061~~~ 9062 9063### blobfs_set_cache_size {#rpc_blobfs_set_cache_size} 9064 9065Set cache pool size for blobfs filesystems. This RPC is only permitted when the cache pool is not already initialized. 9066 9067The cache pool is initialized when the first blobfs filesystem is initialized or loaded. It is freed when the all 9068initialized or loaded filesystems are unloaded. 9069 9070#### Parameters 9071 9072Name | Optional | Type | Description 9073----------------------- | -------- | ----------- | ----------- 9074size_in_mb | Required | number | Cache size in megabytes 9075 9076#### Response 9077 9078True if cache size is set successfully; False if failed to set. 9079 9080#### Example 9081 9082Example request: 9083 9084~~~json 9085{ 9086 "jsonrpc": "2.0", 9087 "id": 1, 9088 "method": "blobfs_set_cache_size", 9089 "params": { 9090 "size_in_mb": 512, 9091 } 9092} 9093~~~ 9094 9095Example response: 9096 9097~~~json 9098{ 9099 "jsonrpc": "2.0", 9100 "id": 1, 9101 "result": true 9102} 9103~~~ 9104 9105## Socket layer {#jsonrpc_components_sock} 9106 9107### sock_impl_get_options {#rpc_sock_impl_get_options} 9108 9109Get parameters for the socket layer implementation. 9110 9111#### Parameters 9112 9113Name | Optional | Type | Description 9114----------------------- | -------- | ----------- | ----------- 9115impl_name | Required | string | Name of socket implementation, e.g. posix 9116 9117#### Response 9118 9119Response is an object with current socket layer options for requested implementation. 9120 9121#### Example 9122 9123Example request: 9124 9125~~~json 9126{ 9127 "jsonrpc": "2.0", 9128 "method": "sock_impl_get_options", 9129 "id": 1, 9130 "params": { 9131 "impl_name": "posix" 9132 } 9133} 9134~~~ 9135 9136Example response: 9137 9138~~~json 9139{ 9140 "jsonrpc": "2.0", 9141 "id": 1, 9142 "result": { 9143 "recv_buf_size": 2097152, 9144 "send_buf_size": 2097152, 9145 "enable_recv_pipe": true, 9146 "enable_quickack": true, 9147 "enable_placement_id": 0, 9148 "enable_zerocopy_send_server": true, 9149 "enable_zerocopy_send_client": false 9150 } 9151} 9152~~~ 9153 9154### sock_impl_set_options {#rpc_sock_impl_set_options} 9155 9156Set parameters for the socket layer implementation. 9157 9158#### Parameters 9159 9160Name | Optional | Type | Description 9161--------------------------- | -------- | ----------- | ----------- 9162impl_name | Required | string | Name of socket implementation, e.g. posix 9163recv_buf_size | Optional | number | Size of socket receive buffer in bytes 9164send_buf_size | Optional | number | Size of socket send buffer in bytes 9165enable_recv_pipe | Optional | boolean | Enable or disable receive pipe 9166enable_quick_ack | Optional | boolean | Enable or disable quick ACK 9167enable_placement_id | Optional | number | Enable or disable placement_id. 0:disable,1:incoming_napi,2:incoming_cpu 9168enable_zerocopy_send_server | Optional | boolean | Enable or disable zero copy on send for server sockets 9169enable_zerocopy_send_client | Optional | boolean | Enable or disable zero copy on send for client sockets 9170 9171#### Response 9172 9173True if socket layer options were set successfully. 9174 9175#### Example 9176 9177Example request: 9178 9179~~~json 9180{ 9181 "jsonrpc": "2.0", 9182 "method": "sock_impl_set_options", 9183 "id": 1, 9184 "params": { 9185 "impl_name": "posix", 9186 "recv_buf_size": 2097152, 9187 "send_buf_size": 2097152, 9188 "enable_recv_pipe": false, 9189 "enable_quick_ack": false, 9190 "enable_placement_id": 0, 9191 "enable_zerocopy_send_server": true, 9192 "enable_zerocopy_send_client": false 9193 } 9194} 9195~~~ 9196 9197Example response: 9198 9199~~~json 9200{ 9201 "jsonrpc": "2.0", 9202 "id": 1, 9203 "result": true 9204} 9205~~~ 9206 9207### sock_set_default_impl {#rpc_sock_set_default_impl} 9208 9209Set the default sock implementation. 9210 9211#### Parameters 9212 9213Name | Optional | Type | Description 9214----------------------- | -------- | ----------- | ----------- 9215impl_name | Required | string | Name of socket implementation, e.g. posix 9216 9217#### Response 9218 9219True if the default socket layer configuration was set successfully. 9220 9221#### Example 9222 9223Example request: 9224 9225~~~json 9226{ 9227 "jsonrpc": "2.0", 9228 "method": "sock_set_default_impl", 9229 "id": 1, 9230 "params": { 9231 "impl_name": "posix" 9232 } 9233} 9234~~~ 9235 9236Example response: 9237 9238~~~json 9239{ 9240 "jsonrpc": "2.0", 9241 "id": 1, 9242 "result": true 9243} 9244~~~ 9245 9246## Miscellaneous RPC commands 9247 9248### bdev_nvme_send_cmd {#rpc_bdev_nvme_send_cmd} 9249 9250Send NVMe command directly to NVMe controller or namespace. Parameters and responses encoded by base64 urlsafe need further processing. 9251 9252Notice: bdev_nvme_send_cmd requires user to guarentee the correctness of NVMe command itself, and also optional parameters. 9253Illegal command contents or mismatching buffer size may result in unpredictable behavior. 9254 9255#### Parameters 9256 9257Name | Optional | Type | Description 9258----------------------- | -------- | ----------- | ----------- 9259name | Required | string | Name of the operating NVMe controller 9260cmd_type | Required | string | Type of nvme cmd. Valid values are: admin, io 9261data_direction | Required | string | Direction of data transfer. Valid values are: c2h, h2c 9262cmdbuf | Required | string | NVMe command encoded by base64 urlsafe 9263data | Optional | string | Data transferring to controller from host, encoded by base64 urlsafe 9264metadata | Optional | string | Metadata transferring to controller from host, encoded by base64 urlsafe 9265data_len | Optional | number | Data length required to transfer from controller to host 9266metadata_len | Optional | number | Metadata length required to transfer from controller to host 9267timeout_ms | Optional | number | Command execution timeout value, in milliseconds 9268 9269#### Response 9270 9271Name | Type | Description 9272----------------------- | ----------- | ----------- 9273cpl | string | NVMe completion queue entry, encoded by base64 urlsafe 9274data | string | Data transferred from controller to host, encoded by base64 urlsafe 9275metadata | string | Metadata transferred from controller to host, encoded by base64 urlsafe 9276 9277#### Example 9278 9279Example request: 9280 9281~~~json 9282{ 9283 "jsonrpc": "2.0", 9284 "method": "bdev_nvme_send_cmd", 9285 "id": 1, 9286 "params": { 9287 "name": "Nvme0", 9288 "cmd_type": "admin" 9289 "data_direction": "c2h", 9290 "cmdbuf": "BgAAAAEAAAAAAAAAAAAAAAAAAAAAAAAAsGUs9P5_AAAAAAAAABAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA==", 9291 "data_len": 60, 9292 } 9293} 9294~~~ 9295 9296Example response: 9297 9298~~~json 9299{ 9300 "jsonrpc": "2.0", 9301 "id": 1, 9302 "result": { 9303 "cpl": "AAAAAAAAAAARAAAAWrmwABAA==", 9304 "data": "sIjg6AAAAACwiODoAAAAALCI4OgAAAAAAAYAAREAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA" 9305 } 9306 9307} 9308~~~ 9309 9310### enable_vmd {#rpc_enable_vmd} 9311 9312Enable VMD enumeration. 9313 9314#### Parameters 9315 9316This method has no parameters. 9317 9318#### Response 9319 9320Completion status of enumeration is returned as a boolean. 9321 9322### Example 9323 9324Example request: 9325 9326~~~json 9327{ 9328 "jsonrpc": "2.0", 9329 "method": "enable_vmd", 9330 "id": 1 9331} 9332~~~ 9333 9334Example response: 9335 9336~~~json 9337{ 9338 "jsonrpc": "2.0", 9339 "id": 1, 9340 "result": true 9341} 9342~~~ 9343 9344### spdk_get_version {#rpc_spdk_get_version} 9345 9346Get the version info of the running SPDK application. 9347 9348#### Parameters 9349 9350This method has no parameters. 9351 9352#### Response 9353 9354The response is the version number including major version number, minor version number, patch level number and suffix string. 9355 9356#### Example 9357 9358Example request: 9359~~ 9360{ 9361 "jsonrpc": "2.0", 9362 "id": 1, 9363 "method": "spdk_get_version" 9364} 9365~~ 9366 9367Example response: 9368~~ 9369{ 9370 "jsonrpc": "2.0", 9371 "id": 1, 9372 "result": { 9373 "version": "19.04-pre", 9374 "fields" : { 9375 "major": 19, 9376 "minor": 4, 9377 "patch": 0, 9378 "suffix": "-pre" 9379 } 9380 } 9381} 9382~~ 9383 9384### framework_get_pci_devices 9385 9386List PCIe devices attached to an SPDK application and the contents of their config space. 9387 9388#### Parameters 9389 9390This method has no parameters. 9391 9392#### Response 9393 9394The response is an array of attached PCIe devices. 9395 9396#### Example 9397 9398Example request: 9399~~ 9400{ 9401 "jsonrpc": "2.0", 9402 "id": 1, 9403 "method": "framework_get_pci_devices" 9404} 9405~~ 9406 9407Example response: 9408Note that the config space buffer was trimmed. 9409~~ 9410{ 9411 "jsonrpc": "2.0", 9412 "id": 1, 9413 "result": { 9414 [ 9415 { 9416 "address": "0000:00:04.0", 9417 "config_space": "8680455807051000...0000000000000000" 9418 }, 9419 { 9420 "address": "0000:00:03.0", 9421 "config_space": "8680455807051000...0000000000000000" 9422 } 9423 ] 9424 } 9425} 9426~~ 9427 9428### bdev_nvme_add_error_injection {#rpc_bdev_nvme_add_error_injection} 9429 9430Add a NVMe command error injection for a bdev nvme controller. 9431 9432#### Parameters 9433 9434Name | Optional | Type | Description 9435----------------------- | -------- | ----------- | ----------- 9436name | Required | string | Name of the operating NVMe controller 9437cmd_type | Required | string | Type of NVMe command. Valid values are: admin, io 9438opc | Required | number | Opcode for which the error injection is applied 9439do_not_submit | Optional | boolean | Set to true if request should not be submitted to the controller (default false) 9440timeout_in_us | Optional | number | Wait specified microseconds when do_not_submit is true 9441err_count | Optional | number | Number of matching NVMe commands to inject errors 9442sct | Optional | number | Status code type (default 0) 9443sc | Optional | number | Status code (default 0) 9444 9445#### Response 9446 9447true on success 9448 9449#### Example 9450 9451Example request: 9452 9453~~~json 9454{ 9455 "jsonrpc": "2.0", 9456 "method": "bdev_nvme_add_error_injection", 9457 "id": 1, 9458 "params": { 9459 "name": "HotInNvme0", 9460 "opc": 2, 9461 "cmd_type": "io", 9462 "err_count": 1111111, 9463 "sct": 11, 9464 "sc": 33 9465 } 9466} 9467 9468~~~ 9469 9470Example response: 9471 9472~~~json 9473{ 9474 "jsonrpc": "2.0", 9475 "id": 1, 9476 "result": true 9477} 9478 9479~~~ 9480 9481### bdev_nvme_remove_error_injection {#rpc_bdev_nvme_remove_error_injection} 9482 9483Remove a NVMe command error injection. 9484 9485#### Parameters 9486 9487Name | Optional | Type | Description 9488----------------------- | -------- | ----------- | ----------- 9489name | Required | string | Name of the operating NVMe controller 9490cmd_type | Required | string | Type of NVMe command. Valid values are: admin, io 9491opc | Required | number | Opcode for which the error injection is applied 9492 9493#### Response 9494 9495true on success 9496 9497#### Example 9498 9499Example request: 9500 9501~~~json 9502{ 9503 "jsonrpc": "2.0", 9504 "method": "bdev_nvme_remove_error_injection", 9505 "id": 1, 9506 "params": { 9507 "name": "HotInNvme0", 9508 "opc": 2, 9509 "cmd_type": "io" 9510 } 9511} 9512 9513 9514~~~ 9515 9516Example response: 9517 9518~~~json 9519{ 9520 "jsonrpc": "2.0", 9521 "id": 1, 9522 "result": true 9523} 9524 9525~~~ 9526