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