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