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