1# JSON-RPC Methods {#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_start_subsystem_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# App Framework {#jsonrpc_components_app} 58 59## kill_instance {#rpc_kill_instance} 60 61Send a signal to the application. 62 63### Parameters 64 65Name | Optional | Type | Description 66----------------------- | -------- | ----------- | ----------- 67sig_name | Required | string | Signal to send (SIGINT, SIGTERM, SIGQUIT, SIGHUP, or SIGKILL) 68 69### Example 70 71Example request: 72~~~ 73{ 74 "jsonrpc": "2.0", 75 "id": 1, 76 "method": "kill_instance", 77 "params": { 78 "sig_name": "SIGINT" 79 } 80} 81~~~ 82 83Example response: 84~~~ 85{ 86 "jsonrpc": "2.0", 87 "id": 1, 88 "result": true 89} 90~~~ 91 92## context_switch_monitor {#rpc_context_switch_monitor} 93 94Query, enable, or disable the context switch monitoring functionality. 95 96### Parameters 97 98Name | Optional | Type | Description 99----------------------- | -------- | ----------- | ----------- 100enabled | Optional | boolean | Enable (`true`) or disable (`false`) monitoring (omit this parameter to query the current state) 101 102### Response 103 104Name | Type | Description 105----------------------- | ----------- | ----------- 106enabled | boolean | The current state of context switch monitoring 107 108### Example 109 110Example request: 111~~~ 112{ 113 "jsonrpc": "2.0", 114 "id": 1, 115 "method": "context_switch_monitor", 116 "params": { 117 "enabled": false 118 } 119} 120~~~ 121 122Example response: 123~~~ 124{ 125 "jsonrpc": "2.0", 126 "id": 1, 127 "result": { 128 "enabled": false 129 } 130} 131~~~ 132 133## start_subsystem_init {#rpc_start_subsystem_init} 134 135Start initialization of SPDK subsystems when it is deferred by starting SPDK application with option -w. 136During its deferral some RPCs can be used to set global parameters for SPDK subsystems. 137This RPC can be called only once. 138 139### Parameters 140 141This method has no parameters. 142 143### Response 144 145Completion status of SPDK subsystem initialization is returned as a boolean. 146 147### Example 148 149Example request: 150~~~ 151{ 152 "jsonrpc": "2.0", 153 "id": 1, 154 "method": "start_subsystem_init" 155} 156~~~ 157 158Example response: 159~~~ 160{ 161 "jsonrpc": "2.0", 162 "id": 1, 163 "result": true 164} 165~~~ 166 167## wait_subsystem_init {#rpc_wait_subsystem_init} 168 169Do not return until all subsystems have been initialized and the RPC system state is running. 170If the application is already running, this call will return immediately. This RPC can be called at any time. 171 172### Parameters 173 174This method has no parameters. 175 176### Response 177 178Returns True when subsystems have been initialized. 179 180### Example 181 182Example request: 183~~~ 184{ 185 "jsonrpc": "2.0", 186 "id": 1, 187 "method": "wait_subsystem_init" 188} 189~~~ 190 191Example response: 192~~~ 193{ 194 "jsonrpc": "2.0", 195 "id": 1, 196 "result": true 197} 198~~~ 199 200## get_rpc_methods {#rpc_get_rpc_methods} 201 202Get an array of supported RPC methods. 203 204### Parameters 205 206Name | Optional | Type | Description 207----------------------- | -------- | ----------- | ----------- 208current | Optional | boolean | Get an array of RPC methods only callable in the current state. 209 210### Response 211 212The response is an array of supported RPC methods. 213 214### Example 215 216Example request: 217~~~ 218{ 219 "jsonrpc": "2.0", 220 "id": 1, 221 "method": "get_rpc_methods" 222} 223~~~ 224 225Example response: 226~~~ 227{ 228 "jsonrpc": "2.0", 229 "id": 1, 230 "result": [ 231 "start_subsystem_init", 232 "get_rpc_methods", 233 "get_scsi_devices", 234 "get_interfaces", 235 "delete_ip_address", 236 "add_ip_address", 237 "get_nbd_disks", 238 "stop_nbd_disk", 239 "start_nbd_disk", 240 "get_trace_flags", 241 "clear_trace_flag", 242 "set_trace_flag", 243 "get_log_level", 244 "set_log_level", 245 "get_log_print_level", 246 "set_log_print_level", 247 "get_iscsi_global_params", 248 "target_node_add_lun", 249 "get_iscsi_connections", 250 "delete_portal_group", 251 "add_portal_group", 252 "get_portal_groups", 253 "delete_target_node", 254 "delete_pg_ig_maps", 255 "add_pg_ig_maps", 256 "construct_target_node", 257 "get_target_nodes", 258 "delete_initiator_group", 259 "delete_initiators_from_initiator_group", 260 "add_initiators_to_initiator_group", 261 "add_initiator_group", 262 "get_initiator_groups", 263 "set_iscsi_options", 264 "set_bdev_options", 265 "set_bdev_qos_limit_iops", 266 "set_bdev_qos_limit", 267 "delete_bdev", 268 "get_bdevs", 269 "get_bdevs_iostat", 270 "get_subsystem_config", 271 "get_subsystems", 272 "context_switch_monitor", 273 "kill_instance", 274 "scan_ioat_copy_engine", 275 "construct_virtio_dev", 276 "construct_virtio_pci_blk_bdev", 277 "construct_virtio_user_blk_bdev", 278 "get_virtio_scsi_devs", 279 "remove_virtio_bdev", 280 "remove_virtio_scsi_bdev", 281 "construct_virtio_pci_scsi_bdev", 282 "construct_virtio_user_scsi_bdev", 283 "delete_aio_bdev", 284 "construct_aio_bdev", 285 "destruct_split_vbdev", 286 "construct_split_vbdev", 287 "bdev_inject_error", 288 "delete_error_bdev", 289 "construct_error_bdev", 290 "construct_passthru_bdev", 291 "apply_nvme_firmware", 292 "delete_nvme_controller", 293 "construct_nvme_bdev", 294 "construct_null_bdev", 295 "delete_malloc_bdev", 296 "construct_malloc_bdev", 297 "get_lvol_stores", 298 "destroy_lvol_bdev", 299 "resize_lvol_bdev", 300 "decouple_parent_lvol_bdev", 301 "inflate_lvol_bdev", 302 "rename_lvol_bdev", 303 "clone_lvol_bdev", 304 "snapshot_lvol_bdev", 305 "construct_lvol_bdev", 306 "destroy_lvol_store", 307 "rename_lvol_store", 308 "construct_lvol_store" 309 ] 310} 311~~~ 312 313## get_subsystems {#rpc_get_subsystems} 314 315Get an array of name and dependency relationship of SPDK subsystems in initialization order. 316 317### Parameters 318 319None 320 321### Response 322 323The response is an array of name and dependency relationship of SPDK subsystems in initialization order. 324 325### Example 326 327Example request: 328~~~ 329{ 330 "jsonrpc": "2.0", 331 "id": 1, 332 "method": "get_subsystems" 333} 334~~~ 335 336Example response: 337~~~ 338{ 339 "jsonrpc": "2.0", 340 "id": 1, 341 "result": [ 342 { 343 "subsystem": "copy", 344 "depends_on": [] 345 }, 346 { 347 "subsystem": "interface", 348 "depends_on": [] 349 }, 350 { 351 "subsystem": "net_framework", 352 "depends_on": [ 353 "interface" 354 ] 355 }, 356 { 357 "subsystem": "bdev", 358 "depends_on": [ 359 "copy" 360 ] 361 }, 362 { 363 "subsystem": "nbd", 364 "depends_on": [ 365 "bdev" 366 ] 367 }, 368 { 369 "subsystem": "nvmf", 370 "depends_on": [ 371 "bdev" 372 ] 373 }, 374 { 375 "subsystem": "scsi", 376 "depends_on": [ 377 "bdev" 378 ] 379 }, 380 { 381 "subsystem": "vhost", 382 "depends_on": [ 383 "scsi" 384 ] 385 }, 386 { 387 "subsystem": "iscsi", 388 "depends_on": [ 389 "scsi" 390 ] 391 } 392 ] 393} 394~~~ 395 396## get_subsystem_config {#rpc_get_subsystem_config} 397 398Get current configuration of the specified SPDK subsystem 399 400### Parameters 401 402Name | Optional | Type | Description 403----------------------- | -------- | ----------- | ----------- 404name | Required | string | SPDK subsystem name 405 406### Response 407 408The response is current configuration of the specified SPDK subsystem. 409Null is returned if it is not retrievable by the get_subsystem_config method and empty array is returned if it is empty. 410 411### Example 412 413Example request: 414~~~ 415{ 416 "jsonrpc": "2.0", 417 "id": 1, 418 "method": "get_subsystem_config", 419 "params": { 420 "name": "bdev" 421 } 422} 423~~~ 424 425Example response: 426~~~ 427{ 428 "jsonrpc": "2.0", 429 "id": 1, 430 "result": [ 431 { 432 "params": { 433 "base_bdev": "Malloc2", 434 "split_size_mb": 0, 435 "split_count": 2 436 }, 437 "method": "construct_split_vbdev" 438 }, 439 { 440 "params": { 441 "trtype": "PCIe", 442 "name": "Nvme1", 443 "traddr": "0000:01:00.0" 444 }, 445 "method": "construct_nvme_bdev" 446 }, 447 { 448 "params": { 449 "trtype": "PCIe", 450 "name": "Nvme2", 451 "traddr": "0000:03:00.0" 452 }, 453 "method": "construct_nvme_bdev" 454 }, 455 { 456 "params": { 457 "block_size": 512, 458 "num_blocks": 131072, 459 "name": "Malloc0", 460 "uuid": "913fc008-79a7-447f-b2c4-c73543638c31" 461 }, 462 "method": "construct_malloc_bdev" 463 }, 464 { 465 "params": { 466 "block_size": 512, 467 "num_blocks": 131072, 468 "name": "Malloc1", 469 "uuid": "dd5b8f6e-b67a-4506-b606-7fff5a859920" 470 }, 471 "method": "construct_malloc_bdev" 472 } 473 ] 474} 475~~~ 476 477# Block Device Abstraction Layer {#jsonrpc_components_bdev} 478 479## set_bdev_options {#rpc_set_bdev_options} 480 481Set global parameters for the block device (bdev) subsystem. This RPC may only be called 482before SPDK subsystems have been initialized. 483 484### Parameters 485 486Name | Optional | Type | Description 487----------------------- | -------- | ----------- | ----------- 488bdev_io_pool_size | Optional | number | Number of spdk_bdev_io structures in shared buffer pool 489bdev_io_cache_size | Optional | number | Maximum number of spdk_bdev_io structures cached per thread 490 491### Example 492 493Example request: 494~~~ 495{ 496 "jsonrpc": "2.0", 497 "id": 1, 498 "method": "set_bdev_options", 499 "params": { 500 "bdev_io_pool_size": 65536, 501 "bdev_io_cache_size": 256 502 } 503} 504~~~ 505 506Example response: 507~~~ 508{ 509 "jsonrpc": "2.0", 510 "id": 1, 511 "result": true 512} 513~~~ 514 515## get_bdevs {#rpc_get_bdevs} 516 517Get information about block devices (bdevs). 518 519### Parameters 520 521The user may specify no parameters in order to list all block devices, or a block device may be 522specified by name. 523 524Name | Optional | Type | Description 525----------------------- | -------- | ----------- | ----------- 526name | Optional | string | Block device name 527 528### Response 529 530The response is an array of objects containing information about the requested block devices. 531 532### Example 533 534Example request: 535~~~ 536{ 537 "jsonrpc": "2.0", 538 "id": 1, 539 "method": "get_bdevs", 540 "params": { 541 "name": "Malloc0" 542 } 543} 544~~~ 545 546Example response: 547~~~ 548{ 549 "jsonrpc": "2.0", 550 "id": 1, 551 "result": [ 552 { 553 "name": "Malloc0", 554 "product_name": "Malloc disk", 555 "block_size": 512, 556 "num_blocks": 20480, 557 "claimed": false, 558 "supported_io_types": { 559 "read": true, 560 "write": true, 561 "unmap": true, 562 "write_zeroes": true, 563 "flush": true, 564 "reset": true, 565 "nvme_admin": false, 566 "nvme_io": false 567 }, 568 "driver_specific": {} 569 } 570 ] 571} 572~~~ 573 574## get_bdevs_iostat {#rpc_get_bdevs_iostat} 575 576Get I/O statistics of block devices (bdevs). 577 578### Parameters 579 580The user may specify no parameters in order to list all block devices, or a block device may be 581specified by name. 582 583Name | Optional | Type | Description 584----------------------- | -------- | ----------- | ----------- 585name | Optional | string | Block device name 586 587### Response 588 589The response is an array of objects containing I/O statistics of the requested block devices. 590 591### Example 592 593Example request: 594~~~ 595{ 596 "jsonrpc": "2.0", 597 "id": 1, 598 "method": "get_bdevs_iostat", 599 "params": { 600 "name": "Nvme0n1" 601 } 602} 603~~~ 604 605Example response: 606~~~ 607{ 608 "jsonrpc": "2.0", 609 "id": 1, 610 "result": [ 611 { 612 "tick_rate": 2200000000 613 }, 614 { 615 "name": "Nvme0n1", 616 "bytes_read": 36864, 617 "num_read_ops": 2, 618 "bytes_written": 0, 619 "num_write_ops": 0, 620 "read_latency_ticks": 178904, 621 "write_latency_ticks": 0, 622 "queue_depth_polling_period": 2, 623 "queue_depth": 0, 624 "io_time": 0, 625 "weighted_io_time": 0 626 } 627 ] 628} 629~~~ 630 631## delete_bdev {#rpc_delete_bdev} 632 633Unregister a block device. 634 635### Parameters 636 637Name | Optional | Type | Description 638----------------------- | -------- | ----------- | ----------- 639name | Required | string | Block device name 640 641### Example 642 643Example request: 644~~~ 645{ 646 "jsonrpc": "2.0", 647 "id": 1, 648 "method": "delete_bdev", 649 "params": { 650 "name": "Malloc0" 651 } 652} 653~~~ 654 655Example response: 656~~~ 657{ 658 "jsonrpc": "2.0", 659 "id": 1, 660 "result": true 661} 662~~~ 663 664## set_bdev_qos_limit {#rpc_set_bdev_qos_limit} 665 666Set the quality of service rate limit on a bdev. 667 668### Parameters 669 670Name | Optional | Type | Description 671----------------------- | -------- | ----------- | ----------- 672name | Required | string | Block device name 673rw_ios_per_sec | Optional | number | Number of R/W I/Os per second to allow. 0 means unlimited. 674rw_mbytes_per_sec | Optional | number | Number of R/W megabytes per second to allow. 0 means unlimited. 675 676### Example 677 678Example request: 679~~~ 680{ 681 "jsonrpc": "2.0", 682 "id": 1, 683 "method": "set_bdev_qos_limit", 684 "params": { 685 "name": "Malloc0" 686 "rw_ios_per_sec": 20000 687 "rw_mbytes_per_sec": 100 688 } 689} 690~~~ 691 692Example response: 693~~~ 694{ 695 "jsonrpc": "2.0", 696 "id": 1, 697 "result": true 698} 699~~~ 700 701## construct_malloc_bdev {#rpc_construct_malloc_bdev} 702 703Construct @ref bdev_config_malloc 704 705### Parameters 706 707Name | Optional | Type | Description 708----------------------- | -------- | ----------- | ----------- 709name | Optional | string | Bdev name to use 710block_size | Required | number | Block size in bytes -must be multiple of 512 711num_blocks | Required | number | Number of blocks 712uuid | Optional | string | UUID of new bdev 713 714### Result 715 716Name of newly created bdev. 717 718### Example 719 720Example request: 721 722~~~ 723{ 724 "params": { 725 "block_size": 4096, 726 "num_blocks": 16384, 727 "name": "Malloc0", 728 "uuid": "2b6601ba-eada-44fb-9a83-a20eb9eb9e90" 729 }, 730 "jsonrpc": "2.0", 731 "method": "construct_malloc_bdev", 732 "id": 1 733} 734~~~ 735 736Example response: 737 738~~~ 739{ 740 "jsonrpc": "2.0", 741 "id": 1, 742 "result": "Malloc0" 743} 744~~~ 745 746## delete_malloc_bdev {#rpc_delete_malloc_bdev} 747 748Delete @ref bdev_config_malloc 749 750### Parameters 751 752Name | Optional | Type | Description 753----------------------- | -------- | ----------- | ----------- 754name | Required | string | Bdev name 755 756### Example 757 758Example request: 759 760~~~ 761{ 762 "params": { 763 "name": "Malloc0" 764 }, 765 "jsonrpc": "2.0", 766 "method": "delete_malloc_bdev", 767 "id": 1 768} 769~~~ 770 771Example response: 772 773~~~ 774{ 775 "jsonrpc": "2.0", 776 "id": 1, 777 "result": true 778} 779~~~ 780 781## construct_null_bdev {#rpc_construct_null_bdev} 782 783Construct @ref bdev_config_null 784 785### Parameters 786 787Name | Optional | Type | Description 788----------------------- | -------- | ----------- | ----------- 789name | Optional | string | Bdev name to use 790block_size | Required | number | Block size in bytes 791num_blocks | Required | number | Number of blocks 792uuid | Optional | string | UUID of new bdev 793 794### Result 795 796Name of newly created bdev. 797 798### Example 799 800Example request: 801 802~~~ 803{ 804 "params": { 805 "block_size": 4096, 806 "num_blocks": 16384, 807 "name": "Null0", 808 "uuid": "2b6601ba-eada-44fb-9a83-a20eb9eb9e90" 809 }, 810 "jsonrpc": "2.0", 811 "method": "construct_null_bdev", 812 "id": 1 813} 814~~~ 815 816Example response: 817 818~~~ 819{ 820 "jsonrpc": "2.0", 821 "id": 1, 822 "result": "Null0" 823} 824~~~ 825 826## delete_null_bdev {#rpc_delete_null_bdev} 827 828Delete @ref bdev_config_null. 829 830### Parameters 831 832Name | Optional | Type | Description 833----------------------- | -------- | ----------- | ----------- 834name | Required | string | Bdev name 835 836### Example 837 838Example request: 839 840~~~ 841{ 842 "params": { 843 "name": "Null0" 844 }, 845 "jsonrpc": "2.0", 846 "method": "delete_null_bdev", 847 "id": 1 848} 849~~~ 850 851Example response: 852 853~~~ 854{ 855 "jsonrpc": "2.0", 856 "id": 1, 857 "result": true 858} 859~~~ 860 861## construct_aio_bdev {#rpc_construct_aio_bdev} 862 863Construct @ref bdev_config_aio. 864 865### Parameters 866 867Name | Optional | Type | Description 868----------------------- | -------- | ----------- | ----------- 869name | Required | string | Bdev name to use 870filename | Required | number | Path to device or file 871block_size | Optional | number | Block size in bytes 872 873### Result 874 875Name of newly created bdev. 876 877### Example 878 879Example request: 880 881~~~ 882{ 883 "params": { 884 "block_size": 4096, 885 "name": "Aio0", 886 "filename": "/tmp/aio_bdev_file" 887 }, 888 "jsonrpc": "2.0", 889 "method": "construct_aio_bdev", 890 "id": 1 891} 892~~~ 893 894Example response: 895 896~~~ 897{ 898 "jsonrpc": "2.0", 899 "id": 1, 900 "result": "Aio0" 901} 902~~~ 903 904## delete_aio_bdev {#rpc_delete_aio_bdev} 905 906Delete @ref bdev_config_aio. 907 908### Parameters 909 910Name | Optional | Type | Description 911----------------------- | -------- | ----------- | ----------- 912name | Required | string | Bdev name 913 914### Example 915 916Example request: 917 918~~~ 919{ 920 "params": { 921 "name": "Aio0" 922 }, 923 "jsonrpc": "2.0", 924 "method": "delete_aio_bdev", 925 "id": 1 926} 927~~~ 928 929Example response: 930 931~~~ 932{ 933 "jsonrpc": "2.0", 934 "id": 1, 935 "result": true 936} 937~~~ 938 939## set_bdev_nvme_options {#rpc_set_bdev_nvme_options} 940 941Set global parameters for all bdev NVMe. This RPC may only be called before SPDK subsystems have been initialized. 942 943### Parameters 944 945Name | Optional | Type | Description 946-------------------------- | -------- | ----------- | ----------- 947action_on_timeout | Optional | string | Action to take on command time out: none, reset or abort 948timeout_us | Optional | number | Timeout for each command, in microseconds. If 0, don't track timeouts 949retry_count | Optional | number | The number of attempts per I/O before an I/O fails 950nvme_adminq_poll_period_us | Optional | number | How often the admin queue is polled for asynchronous events in microsecond 951 952### Example 953 954Example request: 955 956~~~ 957request: 958{ 959 "params": { 960 "retry_count": 5, 961 "nvme_adminq_poll_period_us": 2000, 962 "timeout_us": 10000000, 963 "action_on_timeout": "reset" 964 }, 965 "jsonrpc": "2.0", 966 "method": "set_bdev_nvme_options", 967 "id": 1 968} 969~~~ 970 971Example response: 972 973~~~ 974{ 975 "jsonrpc": "2.0", 976 "id": 1, 977 "result": true 978} 979~~~ 980 981## set_bdev_nvme_hotplug {#rpc_set_bdev_nvme_hotplug} 982 983Change settings of the NVMe hotplug feature. If enabled, PCIe NVMe bdevs will be automatically discovered on insertion 984and deleted on removal. 985 986### Parameters 987 988Name | Optional | Type | Description 989----------------------- | -------- | ----------- | ----------- 990enabled | Required | string | True to enable, false to disable 991period_us | Optional | number | How often to poll for hot-insert and hot-remove events. Values: 0 - reset/use default or 1 to 10000000. 992 993### Example 994 995Example request: 996 997~~~ 998request: 999{ 1000 "params": { 1001 "enabled": true, 1002 "period_us": 2000 1003 }, 1004 "jsonrpc": "2.0", 1005 "method": "set_bdev_nvme_hotplug", 1006 "id": 1 1007} 1008~~~ 1009 1010Example response: 1011 1012~~~ 1013{ 1014 "jsonrpc": "2.0", 1015 "id": 1, 1016 "result": true 1017} 1018~~~ 1019 1020## construct_nvme_bdev {#rpc_construct_nvme_bdev} 1021 1022Construct @ref bdev_config_nvme 1023 1024### Result 1025 1026Array of names of newly created bdevs. 1027 1028### Parameters 1029 1030Name | Optional | Type | Description 1031----------------------- | -------- | ----------- | ----------- 1032name | Required | string | Name of the NVMe controller, prefix for each bdev name 1033trtype | Required | string | NVMe-oF target trtype: rdma or pcie 1034traddr | Required | string | NVMe-oF target address: ip or BDF 1035adrfam | Optional | string | NVMe-oF target adrfam: ipv4, ipv6, ib, fc, intra_host 1036trsvcid | Optional | string | NVMe-oF target trsvcid: port number 1037subnqn | Optional | string | NVMe-oF target subnqn 1038hostnqn | Optional | string | NVMe-oF target hostnqn 1039 1040### Example 1041 1042Example request: 1043 1044~~~ 1045{ 1046 "params": { 1047 "trtype": "pcie", 1048 "name": "Nvme0", 1049 "traddr": "0000:0a:00.0" 1050 }, 1051 "jsonrpc": "2.0", 1052 "method": "construct_nvme_bdev", 1053 "id": 1 1054} 1055~~~ 1056 1057Example response: 1058 1059~~~ 1060{ 1061 "jsonrpc": "2.0", 1062 "id": 1, 1063 "result": [ 1064 "Nvme0n1" 1065 ] 1066} 1067~~~ 1068 1069## get_nvme_controllers {#rpc_get_nvme_controllers} 1070 1071Get information about NVMe controllers. 1072 1073### Parameters 1074 1075The user may specify no parameters in order to list all NVMe controllers, or one NVMe controller may be 1076specified by name. 1077 1078Name | Optional | Type | Description 1079----------------------- | -------- | ----------- | ----------- 1080name | Optional | string | NVMe controller name 1081 1082### Response 1083 1084The response is an array of objects containing information about the requested NVMe controllers. 1085 1086### Example 1087 1088Example request: 1089~~~ 1090{ 1091 "jsonrpc": "2.0", 1092 "id": 1, 1093 "method": "get_nvme_controllers", 1094 "params": { 1095 "name": "Nvme0" 1096 } 1097} 1098~~~ 1099 1100Example response: 1101~~~ 1102{ 1103 "jsonrpc": "2.0", 1104 "id": 1, 1105 "result": [ 1106 { 1107 "name": "Nvme0", 1108 "trid": { 1109 "trtype": "PCIe", 1110 "traddr": "0000:05:00.0" 1111 } 1112 } 1113 ] 1114} 1115~~~ 1116 1117## delete_nvme_controller {#rpc_delete_nvme_controller} 1118 1119Delete NVMe controller. 1120 1121### Parameters 1122 1123Name | Optional | Type | Description 1124----------------------- | -------- | ----------- | ----------- 1125name | Required | string | Controller name 1126 1127### Example 1128 1129Example requests: 1130 1131~~~ 1132{ 1133 "params": { 1134 "name": "Nvme0" 1135 }, 1136 "jsonrpc": "2.0", 1137 "method": "delete_nvme_controller", 1138 "id": 1 1139} 1140~~~ 1141 1142Example response: 1143 1144~~~ 1145{ 1146 "jsonrpc": "2.0", 1147 "id": 1, 1148 "result": true 1149} 1150~~~ 1151 1152## construct_rbd_bdev {#rpc_construct_rbd_bdev} 1153 1154Construct @ref bdev_config_rbd bdev 1155 1156This method is available only if SPDK was build with Ceph RBD support. 1157 1158### Parameters 1159 1160Name | Optional | Type | Description 1161----------------------- | -------- | ----------- | ----------- 1162name | Optional | string | Bdev name 1163pool_name | Required | string | Pool name 1164rbd_name | Required | string | Image name 1165block_size | Required | number | Block size 1166 1167### Result 1168 1169Name of newly created bdev. 1170 1171### Example 1172 1173Example request: 1174 1175~~~ 1176{ 1177 "params": { 1178 "pool_name": "rbd", 1179 "rbd_name": "foo", 1180 "block_size": 4096 1181 }, 1182 "jsonrpc": "2.0", 1183 "method": "construct_rbd_bdev", 1184 "id": 1 1185} 1186~~~ 1187 1188Example response: 1189 1190~~~ 1191response: 1192{ 1193 "jsonrpc": "2.0", 1194 "id": 1, 1195 "result": "Ceph0" 1196} 1197~~~ 1198 1199## delete_rbd_bdev {#rpc_delete_rbd_bdev} 1200 1201Delete @ref bdev_config_rbd bdev 1202 1203This method is available only if SPDK was build with Ceph RBD support. 1204 1205### Result 1206 1207`true` if bdev with provided name was deleted or `false` otherwise. 1208 1209### Parameters 1210 1211Name | Optional | Type | Description 1212----------------------- | -------- | ----------- | ----------- 1213name | Required | string | Bdev name 1214 1215### Example 1216 1217Example request: 1218 1219~~~ 1220{ 1221 "params": { 1222 "name": "Rbd0" 1223 }, 1224 "jsonrpc": "2.0", 1225 "method": "delete_rbd_bdev", 1226 "id": 1 1227} 1228~~~ 1229 1230Example response: 1231 1232~~~ 1233{ 1234 "jsonrpc": "2.0", 1235 "id": 1, 1236 "result": true 1237} 1238~~~ 1239 1240## construct_error_bdev {#rpc_construct_error_bdev} 1241 1242Construct error bdev. 1243 1244### Parameters 1245 1246Name | Optional | Type | Description 1247----------------------- | -------- | ----------- | ----------- 1248base_name | Required | string | Base bdev name 1249 1250### Example 1251 1252Example request: 1253 1254~~~ 1255{ 1256 "params": { 1257 "base_name": "Malloc0" 1258 }, 1259 "jsonrpc": "2.0", 1260 "method": "construct_error_bdev", 1261 "id": 1 1262} 1263~~~ 1264 1265Example response: 1266 1267~~~ 1268{ 1269 "jsonrpc": "2.0", 1270 "id": 1, 1271 "result": true 1272} 1273~~~ 1274 1275## delete_error_bdev {#rpc_delete_error_bdev} 1276 1277Delete error bdev 1278 1279### Result 1280 1281`true` if bdev with provided name was deleted or `false` otherwise. 1282 1283### Parameters 1284 1285Name | Optional | Type | Description 1286----------------------- | -------- | ----------- | ----------- 1287name | Required | string | Error bdev name 1288 1289### Example 1290 1291Example request: 1292 1293~~~ 1294{ 1295 "params": { 1296 "name": "EE_Malloc0" 1297 }, 1298 "jsonrpc": "2.0", 1299 "method": "delete_error_bdev", 1300 "id": 1 1301} 1302~~~ 1303 1304Example response: 1305 1306~~~ 1307{ 1308 "jsonrpc": "2.0", 1309 "id": 1, 1310 "result": true 1311} 1312~~~ 1313 1314## construct_iscsi_bdev {#rpc_construct_iscsi_bdev} 1315 1316Connect to iSCSI target and create bdev backed by this connection. 1317 1318This method is available only if SPDK was build with iSCSI initiator support. 1319 1320### Parameters 1321 1322Name | Optional | Type | Description 1323----------------------- | -------- | ----------- | ----------- 1324name | Required | string | Bdev name 1325initiator_iqn | Required | string | IQN name used during connection 1326url | Required | string | iSCSI resource URI 1327 1328### Result 1329 1330Name of newly created bdev. 1331 1332### Example 1333 1334Example request: 1335 1336~~~ 1337{ 1338 "params": { 1339 "url": "iscsi://127.0.0.1/iqn.2016-06.io.spdk:disk1/0", 1340 "initiator_iqn": "iqn.2016-06.io.spdk:init", 1341 "name": "iSCSI0" 1342 }, 1343 "jsonrpc": "2.0", 1344 "method": "construct_iscsi_bdev", 1345 "id": 1 1346} 1347~~~ 1348 1349Example response: 1350 1351~~~ 1352{ 1353 "jsonrpc": "2.0", 1354 "id": 1, 1355 "result": "iSCSI0" 1356} 1357~~~ 1358 1359## delete_iscsi_bdev {#rpc_delete_iscsi_bdev} 1360 1361Delete iSCSI bdev and terminate connection to target. 1362 1363This method is available only if SPDK was built with iSCSI initiator support. 1364 1365### Parameters 1366 1367Name | Optional | Type | Description 1368----------------------- | -------- | ----------- | ----------- 1369name | Required | string | Bdev name 1370 1371### Example 1372 1373Example request: 1374 1375~~~ 1376{ 1377 "params": { 1378 "name": "iSCSI0" 1379 }, 1380 "jsonrpc": "2.0", 1381 "method": "delete_iscsi_bdev", 1382 "id": 1 1383} 1384~~~ 1385 1386Example response: 1387 1388~~~ 1389{ 1390 "jsonrpc": "2.0", 1391 "id": 1, 1392 "result": true 1393} 1394~~~ 1395 1396 1397## create_pmem_pool {#rpc_create_pmem_pool} 1398 1399Create a @ref bdev_config_pmem blk pool file. It is equivalent of following `pmempool create` command: 1400 1401~~~ 1402pmempool create -s $((num_blocks * block_size)) blk $block_size $pmem_file 1403~~~ 1404 1405This method is available only if SPDK was built with PMDK support. 1406 1407### Parameters 1408 1409Name | Optional | Type | Description 1410----------------------- | -------- | ----------- | ----------- 1411pmem_file | Required | string | Path to new pmem file 1412num_blocks | Required | number | Number of blocks 1413block_size | Required | number | Size of each block in bytes 1414 1415### Example 1416 1417Example request: 1418 1419~~~ 1420{ 1421 "params": { 1422 "block_size": 512, 1423 "num_blocks": 131072, 1424 "pmem_file": "/tmp/pmem_file" 1425 }, 1426 "jsonrpc": "2.0", 1427 "method": "create_pmem_pool", 1428 "id": 1 1429} 1430~~~ 1431 1432Example response: 1433 1434~~~ 1435{ 1436 "jsonrpc": "2.0", 1437 "id": 1, 1438 "result": true 1439} 1440~~~ 1441 1442## pmem_pool_info {#rpc_pmem_pool_info} 1443 1444Retrieve basic information about PMDK memory pool. 1445 1446This method is available only if SPDK was built with PMDK support. 1447 1448### Parameters 1449 1450Name | Optional | Type | Description 1451----------------------- | -------- | ----------- | ----------- 1452pmem_file | Required | string | Path to existing pmem file 1453 1454### Result 1455 1456Array of objects describing memory pool: 1457 1458Name | Type | Description 1459----------------------- | ----------- | ----------- 1460num_blocks | number | Number of blocks 1461block_size | number | Size of each block in bytes 1462 1463### Example 1464 1465Example request: 1466 1467~~~ 1468request: 1469{ 1470 "params": { 1471 "pmem_file": "/tmp/pmem_file" 1472 }, 1473 "jsonrpc": "2.0", 1474 "method": "pmem_pool_info", 1475 "id": 1 1476} 1477~~~ 1478 1479Example response: 1480 1481~~~ 1482{ 1483 "jsonrpc": "2.0", 1484 "id": 1, 1485 "result": [ 1486 { 1487 "block_size": 512, 1488 "num_blocks": 129728 1489 } 1490 ] 1491} 1492~~~ 1493 1494## delete_pmem_pool {#rpc_delete_pmem_pool} 1495 1496Delete pmem pool by removing file `pmem_file`. This method will fail if `pmem_file` is not a 1497valid pmem pool file. 1498 1499This method is available only if SPDK was built with PMDK support. 1500 1501### Parameters 1502 1503Name | Optional | Type | Description 1504----------------------- | -------- | ----------- | ----------- 1505pmem_file | Required | string | Path to new pmem file 1506 1507### Example 1508 1509Example request: 1510 1511~~~ 1512{ 1513 "params": { 1514 "pmem_file": "/tmp/pmem_file" 1515 }, 1516 "jsonrpc": "2.0", 1517 "method": "delete_pmem_pool", 1518 "id": 1 1519} 1520~~~ 1521 1522Example response: 1523 1524~~~ 1525{ 1526 "jsonrpc": "2.0", 1527 "id": 1, 1528 "result": true 1529} 1530~~~ 1531 1532## construct_pmem_bdev {#rpc_construct_pmem_bdev} 1533 1534Construct @ref bdev_config_pmem bdev. 1535 1536This method is available only if SPDK was built with PMDK support. 1537 1538### Parameters 1539 1540Name | Optional | Type | Description 1541----------------------- | -------- | ----------- | ----------- 1542name | Required | string | Bdev name 1543pmem_file | Required | string | Path to existing pmem blk pool file 1544 1545### Result 1546 1547Name of newly created bdev. 1548 1549### Example 1550 1551Example request: 1552 1553~~~ 1554{ 1555 "params": { 1556 "pmem_file": "/tmp/pmem_file", 1557 "name": "Pmem0" 1558 }, 1559 "jsonrpc": "2.0", 1560 "method": "construct_pmem_bdev", 1561 "id": 1 1562} 1563~~~ 1564 1565Example response: 1566 1567~~~ 1568{ 1569 "jsonrpc": "2.0", 1570 "id": 1, 1571 "result": "Pmem0" 1572} 1573~~~ 1574 1575## delete_pmem_bdev {#rpc_delete_pmem_bdev} 1576 1577Delete @ref bdev_config_pmem bdev. This call will not remove backing pool files. 1578 1579This method is available only if SPDK was built with PMDK support. 1580 1581### Result 1582 1583`true` if bdev with provided name was deleted or `false` otherwise. 1584 1585### Parameters 1586 1587Name | Optional | Type | Description 1588----------------------- | -------- | ----------- | ----------- 1589name | Required | string | Bdev name 1590 1591### Example 1592 1593Example request: 1594 1595~~~ 1596{ 1597 "params": { 1598 "name": "Pmem0" 1599 }, 1600 "jsonrpc": "2.0", 1601 "method": "delete_pmem_bdev", 1602 "id": 1 1603} 1604~~~ 1605 1606Example response: 1607 1608~~~ 1609{ 1610 "jsonrpc": "2.0", 1611 "id": 1, 1612 "result": true 1613} 1614~~~ 1615 1616## construct_passthru_bdev {#rpc_construct_passthru_bdev} 1617 1618Create passthru bdev. This bdev type redirects all IO to it's base bdev. It has no other purpose than being an example 1619and a starting point in development of new bdev type. 1620 1621### Parameters 1622 1623Name | Optional | Type | Description 1624----------------------- | -------- | ----------- | ----------- 1625name | Required | string | Bdev name 1626base_bdev_name | Required | string | Base bdev name 1627 1628### Result 1629 1630Name of newly created bdev. 1631 1632### Example 1633 1634Example request: 1635 1636~~~ 1637{ 1638 "params": { 1639 "base_bdev_name": "Malloc0", 1640 "name": "Passsthru0" 1641 }, 1642 "jsonrpc": "2.0", 1643 "method": "construct_passthru_bdev", 1644 "id": 1 1645} 1646~~~ 1647 1648Example response: 1649 1650~~~ 1651{ 1652 "jsonrpc": "2.0", 1653 "id": 1, 1654 "result": "Passsthru0" 1655} 1656~~~ 1657 1658## delete_passthru_bdev {#rpc_delete_passthru_bdev} 1659 1660Delete passthru bdev. 1661 1662### Parameters 1663 1664Name | Optional | Type | Description 1665----------------------- | -------- | ----------- | ----------- 1666name | Required | string | Bdev name 1667 1668### Example 1669 1670Example request: 1671 1672~~~ 1673{ 1674 "params": { 1675 "name": "Passsthru0" 1676 }, 1677 "jsonrpc": "2.0", 1678 "method": "delete_passthru_bdev", 1679 "id": 1 1680} 1681 1682~~~ 1683 1684Example response: 1685 1686~~~ 1687{ 1688 "jsonrpc": "2.0", 1689 "id": 1, 1690 "result": true 1691} 1692~~~ 1693 1694## construct_virtio_dev {#rpc_construct_virtio_dev} 1695 1696Create new initiator @ref bdev_config_virtio_scsi or @ref bdev_config_virtio_blk and expose all found bdevs. 1697 1698### Parameters 1699 1700Name | Optional | Type | Description 1701----------------------- | -------- | ----------- | ----------- 1702name | Required | string | Virtio SCSI base bdev name or Virtio Blk bdev name 1703trtype | Required | string | Virtio target trtype: pci or user 1704traddr | Required | string | target address: BDF or UNIX socket file path 1705dev_type | Required | string | Virtio device type: blk or scsi 1706vq_count | Optional | number | Number of queues this controller will utilize (default: 1) 1707vq_size | Optional | number | Size of each queue. Must be power of 2. (default: 512) 1708 1709In case of Virtio SCSI the `name` parameter will be base name for new created bdevs. For Virtio Blk `name` will be the 1710name of created bdev. 1711 1712`vq_count` and `vq_size` parameters are valid only if `trtype` is `user`. 1713 1714### Result 1715 1716Array of names of newly created bdevs. 1717 1718### Example 1719 1720Example request: 1721 1722~~~ 1723{ 1724 "params": { 1725 "name": "VirtioScsi0", 1726 "trtype": "user", 1727 "vq_size": 128, 1728 "dev_type": "scsi", 1729 "traddr": "/tmp/VhostScsi0", 1730 "vq_count": 4 1731 }, 1732 "jsonrpc": "2.0", 1733 "method": "construct_virtio_dev", 1734 "id": 1 1735} 1736~~~ 1737 1738Example response: 1739 1740~~~ 1741{ 1742 "jsonrpc": "2.0", 1743 "id": 1, 1744 "result": ["VirtioScsi0t2", "VirtioScsi0t4"] 1745} 1746~~~ 1747 1748## construct_virtio_user_scsi_bdev {#rpc_construct_virtio_user_scsi_bdev} 1749 1750This is legacy RPC method. It is equivalent of @ref rpc_construct_virtio_dev with `trtype` set to `user` and `dev_type` set to `scsi`. 1751 1752Because it will be deprecated soon it is intentionally undocumented. 1753 1754 1755## construct_virtio_pci_scsi_bdev {#rpc_construct_virtio_pci_scsi_bdev} 1756 1757This is legacy RPC method. It is equivalent of @ref rpc_construct_virtio_dev with `trtype` set to `pci` and `dev_type` set to `scsi`. 1758 1759Because it will be deprecated soon it is intentionally undocumented. 1760 1761## construct_virtio_user_blk_bdev {#rpc_construct_virtio_user_blk_bdev} 1762 1763This is legacy RPC method. It is equivalent of @ref rpc_construct_virtio_dev with `trtype` set to `user` and `dev_type` set to `blk`. 1764 1765Because it will be deprecated soon it is intentionally undocumented. 1766 1767 1768## construct_virtio_pci_blk_bdev {#rpc_construct_virtio_pci_blk_bdev} 1769 1770This is legacy RPC method. It is equivalent of @ref rpc_construct_virtio_dev with `trtype` set to `pci` and `dev_type` set to `blk`. 1771 1772Because it will be deprecated soon it is intentionally undocumented. 1773 1774## get_virtio_scsi_devs {#rpc_get_virtio_scsi_devs} 1775 1776Show information about all available Virtio SCSI devices. 1777 1778### Parameters 1779 1780This method has no parameters. 1781 1782### Result 1783 1784Array of Virtio SCSI information objects. 1785 1786### Example 1787 1788Example request: 1789 1790~~~ 1791{ 1792 "jsonrpc": "2.0", 1793 "method": "get_virtio_scsi_devs", 1794 "id": 1 1795} 1796~~~ 1797 1798Example response: 1799 1800~~~ 1801{ 1802 "jsonrpc": "2.0", 1803 "id": 1, 1804 "result": [ 1805 { 1806 "name": "VirtioScsi0", 1807 "virtio": { 1808 "vq_size": 128, 1809 "vq_count": 4, 1810 "type": "user", 1811 "socket": "/tmp/VhostScsi0" 1812 } 1813 } 1814 ] 1815} 1816~~~ 1817 1818## remove_virtio_bdev {#rpc_remove_virtio_bdev} 1819 1820Remove a Virtio device. This command can be used to remove any type of virtio device. 1821 1822### Parameters 1823 1824Name | Optional | Type | Description 1825----------------------- | -------- | ----------- | ----------- 1826name | Required | string | Virtio name 1827 1828### Example 1829 1830Example request: 1831 1832~~~ 1833{ 1834 "params": { 1835 "name": "VirtioUser0" 1836 }, 1837 "jsonrpc": "2.0", 1838 "method": "remove_virtio_bdev", 1839 "id": 1 1840} 1841 1842~~~ 1843 1844Example response: 1845 1846~~~ 1847{ 1848 "jsonrpc": "2.0", 1849 "id": 1, 1850 "result": true 1851} 1852~~~ 1853 1854# iSCSI Target {#jsonrpc_components_iscsi_tgt} 1855 1856## set_iscsi_options method {#rpc_set_iscsi_options} 1857 1858Set global parameters for iSCSI targets. 1859 1860This RPC may only be called before SPDK subsystems have been initialized. This RPC can be called only once. 1861 1862### Parameters 1863 1864Name | Optional | Type | Description 1865--------------------------- | -------- | ------- | ----------- 1866auth_file | Optional | string | Path to CHAP shared secret file (default: "") 1867node_base | Optional | string | Prefix of the name of iSCSI target node (default: "iqn.2016-06.io.spdk") 1868nop_timeout | Optional | number | Timeout in seconds to nop-in request to the initiator (default: 60) 1869nop_in_interval | Optional | number | Time interval in secs between nop-in requests by the target (default: 30) 1870disable_chap | Optional | boolean | CHAP for discovery session should be disabled (default: `false`) 1871require_chap | Optional | boolean | CHAP for discovery session should be required (default: `false`) 1872mutual_chap | Optional | boolean | CHAP for discovery session should be unidirectional (`false`) or bidirectional (`true`) (default: `false`) 1873chap_group | Optional | number | CHAP group ID for discovery session (default: 0) 1874max_sessions | Optional | number | Maximum number of sessions in the host (default: 128) 1875max_queue_depth | Optional | number | Maximum number of outstanding I/Os per queue (default: 64) 1876max_connections_per_session | Optional | number | Session specific parameter, MaxConnections (default: 2) 1877default_time2wait | Optional | number | Session specific parameter, DefaultTime2Wait (default: 2) 1878default_time2retain | Optional | number | Session specific parameter, DefaultTime2Retain (default: 20) 1879first_burst_length | Optional | number | Session specific parameter, FirstBurstLength (default: 8192) 1880immediate_data | Optional | boolean | Session specific parameter, ImmediateData (default: `true`) 1881error_recovery_level | Optional | number | Session specific parameter, ErrorRecoveryLevel (default: 0) 1882allow_duplicated_isid | Optional | boolean | Allow duplicated initiator session ID (default: `false`) 1883min_connections_per_core | Optional | number | Allocation unit of connections per core (default: 4) 1884 1885To load CHAP shared secret file, its path is required to specify explicitly in the parameter `auth_file`. 1886 1887Parameters `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. 1888 1889### Example 1890 1891Example request: 1892 1893~~~ 1894{ 1895 "params": { 1896 "allow_duplicated_isid": true, 1897 "default_time2retain": 60, 1898 "first_burst_length": 8192, 1899 "immediate_data": true, 1900 "node_base": "iqn.2016-06.io.spdk", 1901 "max_sessions": 128, 1902 "nop_timeout": 30, 1903 "nop_in_interval": 30, 1904 "auth_file": "/usr/local/etc/spdk/auth.conf", 1905 "disable_chap": true, 1906 "default_time2wait": 2 1907 }, 1908 "jsonrpc": "2.0", 1909 "method": "set_iscsi_options", 1910 "id": 1 1911} 1912~~~ 1913 1914Example response: 1915 1916~~~ 1917{ 1918 "jsonrpc": "2.0", 1919 "id": 1, 1920 "result": true 1921} 1922~~~ 1923 1924## get_iscsi_global_params method {#rpc_get_iscsi_global_params} 1925 1926Show global parameters of iSCSI targets. 1927 1928### Parameters 1929 1930This method has no parameters. 1931 1932### Example 1933 1934Example request: 1935 1936~~~ 1937request: 1938{ 1939 "jsonrpc": "2.0", 1940 "method": "get_iscsi_global_params", 1941 "id": 1 1942} 1943~~~ 1944 1945Example response: 1946 1947~~~ 1948{ 1949 "jsonrpc": "2.0", 1950 "id": 1, 1951 "result": { 1952 "allow_duplicated_isid": true, 1953 "default_time2retain": 60, 1954 "first_burst_length": 8192, 1955 "immediate_data": true, 1956 "node_base": "iqn.2016-06.io.spdk", 1957 "mutual_chap": false, 1958 "nop_in_interval": 30, 1959 "chap_group": 0, 1960 "max_connections_per_session": 2, 1961 "max_queue_depth": 64, 1962 "nop_timeout": 30, 1963 "max_sessions": 128, 1964 "error_recovery_level": 0, 1965 "auth_file": "/usr/local/etc/spdk/auth.conf", 1966 "min_connections_per_core": 4, 1967 "disable_chap": true, 1968 "default_time2wait": 2, 1969 "require_chap": false 1970 } 1971} 1972~~~ 1973## set_iscsi_discovery_auth method {#rpc_set_iscsi_discovery_auth} 1974 1975Set CHAP authentication for sessions dynamically. 1976 1977### Parameters 1978 1979Name | Optional | Type | Description 1980--------------------------- | -------- | --------| ----------- 1981disable_chap | Optional | boolean | CHAP for discovery session should be disabled (default: `false`) 1982require_chap | Optional | boolean | CHAP for discovery session should be required (default: `false`) 1983mutual_chap | Optional | boolean | CHAP for discovery session should be unidirectional (`false`) or bidirectional (`true`) (default: `false`) 1984chap_group | Optional | number | CHAP group ID for discovery session (default: 0) 1985 1986Parameters `disable_chap` and `require_chap` are mutually exclusive. 1987 1988### Example 1989 1990Example request: 1991 1992~~~ 1993request: 1994{ 1995 "params": { 1996 "chap_group": 1, 1997 "require_chap": true, 1998 "mutual_chap": true 1999 }, 2000 "jsonrpc": "2.0", 2001 "method": "set_iscsi_discovery_auth", 2002 "id": 1 2003} 2004~~~ 2005 2006Example response: 2007 2008~~~ 2009{ 2010 "jsonrpc": "2.0", 2011 "id": 1, 2012 "result": true 2013} 2014~~~ 2015 2016## add_iscsi_auth_group method {#rpc_add_iscsi_auth_group} 2017 2018Add an authentication group for CHAP authentication. 2019 2020### Parameters 2021 2022Name | Optional | Type | Description 2023--------------------------- | -------- | --------| ----------- 2024tag | Required | number | Authentication group tag (unique, integer > 0) 2025secrets | Optional | array | Array of @ref rpc_add_iscsi_auth_group_secret objects 2026 2027### secret {#rpc_add_iscsi_auth_group_secret} 2028 2029Name | Optional | Type | Description 2030--------------------------- | ---------| --------| ----------- 2031user | Required | string | Unidirectional CHAP name 2032secret | Required | string | Unidirectional CHAP secret 2033muser | Optional | string | Bidirectional CHAP name 2034msecret | Optional | string | Bidirectional CHAP secret 2035 2036### Example 2037 2038Example request: 2039 2040~~~ 2041{ 2042 "params": { 2043 "secrets": [ 2044 { 2045 "muser": "mu1", 2046 "secret": "s1", 2047 "user": "u1", 2048 "msecret": "ms1" 2049 } 2050 ], 2051 "tag": 2 2052 }, 2053 "jsonrpc": "2.0", 2054 "method": "add_iscsi_auth_group", 2055 "id": 1 2056} 2057~~~ 2058 2059Example response: 2060~~~ 2061{ 2062 "jsonrpc": "2.0", 2063 "id": 1, 2064 "result": true 2065} 2066~~~ 2067 2068## delete_iscsi_auth_group method {#rpc_delete_iscsi_auth_group} 2069 2070Delete an existing authentication group for CHAP authentication. 2071 2072### Parameters 2073 2074Name | Optional | Type | Description 2075--------------------------- | -------- | --------| ----------- 2076tag | Required | number | Authentication group tag (unique, integer > 0) 2077 2078### Example 2079 2080Example request: 2081 2082~~~ 2083{ 2084 "params": { 2085 "tag": 2 2086 }, 2087 "jsonrpc": "2.0", 2088 "method": "delete_iscsi_auth_group", 2089 "id": 1 2090} 2091~~~ 2092 2093Example response: 2094 2095~~~ 2096{ 2097 "jsonrpc": "2.0", 2098 "id": 1, 2099 "result": true 2100} 2101~~~ 2102 2103## get_iscsi_auth_groups {#rpc_get_iscsi_auth_groups} 2104 2105Show information about all existing authentication group for CHAP authentication. 2106 2107### Parameters 2108 2109This method has no parameters. 2110 2111### Result 2112 2113Array of objects describing authentication group. 2114 2115Name | Type | Description 2116--------------------------- | --------| ----------- 2117tag | number | Authentication group tag 2118secrets | array | Array of @ref rpc_add_iscsi_auth_group_secret objects 2119 2120### Example 2121 2122Example request: 2123 2124~~~ 2125{ 2126 "jsonrpc": "2.0", 2127 "method": "get_iscsi_auth_groups", 2128 "id": 1 2129} 2130~~~ 2131Example response: 2132 2133~~~ 2134{ 2135 "jsonrpc": "2.0", 2136 "id": 1, 2137 "result": [ 2138 { 2139 "secrets": [ 2140 { 2141 "muser": "mu1", 2142 "secret": "s1", 2143 "user": "u1", 2144 "msecret": "ms1" 2145 } 2146 ], 2147 "tag": 1 2148 }, 2149 { 2150 "secrets": [ 2151 { 2152 "secret": "s2", 2153 "user": "u2" 2154 } 2155 ], 2156 "tag": 2 2157 } 2158 ] 2159} 2160~~~ 2161 2162## add_secret_to_iscsi_auth_group {#rpc_add_secret_to_iscsi_auth_group} 2163 2164Add a secret to an existing authentication group for CHAP authentication. 2165 2166### Parameters 2167 2168Name | Optional | Type | Description 2169--------------------------- | -------- | --------| ----------- 2170tag | Required | number | Authentication group tag (unique, integer > 0) 2171user | Required | string | Unidirectional CHAP name 2172secret | Required | string | Unidirectional CHAP secret 2173muser | Optional | string | Bidirectional CHAP name 2174msecret | Optional | string | Bidirectional CHAP secret 2175 2176### Example 2177 2178Example request: 2179 2180~~~ 2181{ 2182 "params": { 2183 "muser": "mu3", 2184 "secret": "s3", 2185 "tag": 2, 2186 "user": "u3", 2187 "msecret": "ms3" 2188 }, 2189 "jsonrpc": "2.0", 2190 "method": "add_secret_to_iscsi_auth_group", 2191 "id": 1 2192} 2193~~~ 2194 2195Example response: 2196 2197~~~ 2198{ 2199 "jsonrpc": "2.0", 2200 "id": 1, 2201 "result": true 2202} 2203~~~ 2204 2205## delete_secret_from_iscsi_auth_group {#rpc_delete_secret_from_iscsi_auth_group} 2206 2207Delete a secret from an existing authentication group for CHAP authentication. 2208 2209### Parameters 2210 2211Name | Optional | Type | Description 2212--------------------------- | -------- | --------| ----------- 2213tag | Required | number | Authentication group tag (unique, integer > 0) 2214user | Required | string | Unidirectional CHAP name 2215 2216### Example 2217 2218Example request: 2219 2220~~~ 2221{ 2222 "params": { 2223 "tag": 2, 2224 "user": "u3" 2225 }, 2226 "jsonrpc": "2.0", 2227 "method": "delete_secret_from_iscsi_auth_group", 2228 "id": 1 2229} 2230~~~ 2231 2232Example response: 2233 2234~~~ 2235{ 2236 "jsonrpc": "2.0", 2237 "id": 1, 2238 "result": true 2239} 2240~~~ 2241 2242## get_initiator_groups method {#rpc_get_initiator_groups} 2243 2244Show information about all available initiator groups. 2245 2246### Parameters 2247 2248This method has no parameters. 2249 2250### Result 2251 2252Array of objects describing initiator groups. 2253 2254Name | Type | Description 2255--------------------------- | --------| ----------- 2256tag | number | Initiator group tag 2257initiators | array | Array of initiator hostnames or IP addresses 2258netmasks | array | Array of initiator netmasks 2259 2260### Example 2261 2262Example request: 2263 2264~~~ 2265{ 2266 "jsonrpc": "2.0", 2267 "method": "get_initiator_groups", 2268 "id": 1 2269} 2270~~~ 2271 2272Example response: 2273 2274~~~ 2275{ 2276 "jsonrpc": "2.0", 2277 "id": 1, 2278 "result": [ 2279 { 2280 "initiators": [ 2281 "iqn.2016-06.io.spdk:host1", 2282 "iqn.2016-06.io.spdk:host2" 2283 ], 2284 "tag": 1, 2285 "netmasks": [ 2286 "192.168.1.0/24" 2287 ] 2288 } 2289 ] 2290} 2291~~~ 2292 2293## add_initiator_group method {#rpc_add_initiator_group} 2294 2295Add an initiator group. 2296 2297### Parameters 2298 2299Name | Optional | Type | Description 2300--------------------------- | -------- | --------| ----------- 2301tag | Required | number | Initiator group tag (unique, integer > 0) 2302initiators | Required | array | Not empty array of initiator hostnames or IP addresses 2303netmasks | Required | array | Not empty array of initiator netmasks 2304 2305### Example 2306 2307Example request: 2308 2309~~~ 2310{ 2311 "params": { 2312 "initiators": [ 2313 "iqn.2016-06.io.spdk:host1", 2314 "iqn.2016-06.io.spdk:host2" 2315 ], 2316 "tag": 1, 2317 "netmasks": [ 2318 "192.168.1.0/24" 2319 ] 2320 }, 2321 "jsonrpc": "2.0", 2322 "method": "add_initiator_group", 2323 "id": 1 2324} 2325~~~ 2326 2327Example response: 2328 2329~~~ 2330response: 2331{ 2332 "jsonrpc": "2.0", 2333 "id": 1, 2334 "result": true 2335} 2336~~~ 2337 2338## delete_initiator_group method {#rpc_delete_initiator_group} 2339 2340Delete an existing initiator group. 2341 2342### Parameters 2343 2344Name | Optional | Type | Description 2345--------------------------- | -------- | --------| ----------- 2346tag | Required | number | Initiator group tag (unique, integer > 0) 2347 2348### Example 2349 2350Example request: 2351 2352~~~ 2353{ 2354 "params": { 2355 "tag": 1 2356 }, 2357 "jsonrpc": "2.0", 2358 "method": "delete_initiator_group", 2359 "id": 1 2360} 2361~~~ 2362 2363Example response: 2364 2365~~~ 2366{ 2367 "jsonrpc": "2.0", 2368 "id": 1, 2369 "result": true 2370} 2371~~~ 2372 2373## add_initiators_to_initiator_group method {#rpc_add_initiators_to_initiator_group} 2374 2375Add initiators to an existing initiator group. 2376 2377### Parameters 2378 2379Name | Optional | Type | Description 2380--------------------------- | -------- | --------| ----------- 2381tag | Required | number | Existing initiator group tag. 2382initiators | Optional | array | Array of initiator hostnames or IP addresses 2383netmasks | Optional | array | Array of initiator netmasks 2384 2385### Example 2386 2387Example request: 2388 2389~~~ 2390request: 2391{ 2392 "params": { 2393 "initiators": [ 2394 "iqn.2016-06.io.spdk:host3" 2395 ], 2396 "tag": 1, 2397 "netmasks": [ 2398 "255.255.255.1" 2399 ] 2400 }, 2401 "jsonrpc": "2.0", 2402 "method": "add_initiators_to_initiator_group", 2403 "id": 1 2404} 2405~~~ 2406 2407Example response: 2408 2409~~~ 2410response: 2411{ 2412 "jsonrpc": "2.0", 2413 "id": 1, 2414 "result": true 2415} 2416~~~ 2417 2418## get_target_nodes method {#rpc_get_target_nodes} 2419 2420Show information about all available iSCSI target nodes. 2421 2422### Parameters 2423 2424This method has no parameters. 2425 2426### Result 2427 2428Array of objects describing target node. 2429 2430Name | Type | Description 2431--------------------------- | --------| ----------- 2432name | string | Target node name (ASCII) 2433alias_name | string | Target node alias name (ASCII) 2434pg_ig_maps | array | Array of Portal_Group_Tag:Initiator_Group_Tag mappings 2435luns | array | Array of Bdev names to LUN ID mappings 2436queue_depth | number | Target queue depth 2437disable_chap | boolean | CHAP authentication should be disabled for this target 2438require_chap | boolean | CHAP authentication should be required for this target 2439mutual_chap | boolean | CHAP authentication should be bidirectional (`true`) or unidirectional (`false`) 2440chap_group | number | Authentication group ID for this target node 2441header_digest | boolean | Header Digest should be required for this target node 2442data_digest | boolean | Data Digest should be required for this target node 2443 2444### Example 2445 2446Example request: 2447 2448~~~ 2449{ 2450 "jsonrpc": "2.0", 2451 "method": "get_target_nodes", 2452 "id": 1 2453} 2454~~~ 2455 2456Example response: 2457 2458~~~ 2459{ 2460 "jsonrpc": "2.0", 2461 "id": 1, 2462 "result": [ 2463 { 2464 "luns": [ 2465 { 2466 "lun_id": 0, 2467 "bdev_name": "Nvme0n1" 2468 } 2469 ], 2470 "mutual_chap": false, 2471 "name": "iqn.2016-06.io.spdk:target1", 2472 "alias_name": "iscsi-target1-alias", 2473 "require_chap": false, 2474 "chap_group": 0, 2475 "pg_ig_maps": [ 2476 { 2477 "ig_tag": 1, 2478 "pg_tag": 1 2479 } 2480 ], 2481 "data_digest": false, 2482 "disable_chap": false, 2483 "header_digest": false, 2484 "queue_depth": 64 2485 } 2486 ] 2487} 2488~~~ 2489 2490## construct_target_node method {#rpc_construct_target_node} 2491 2492Add a iSCSI target node. 2493 2494### Parameters 2495 2496Name | Optional | Type | Description 2497--------------------------- | -------- | --------| ----------- 2498name | Required | string | Target node name (ASCII) 2499alias_name | Required | string | Target node alias name (ASCII) 2500pg_ig_maps | Required | array | Array of (Portal_Group_Tag:Initiator_Group_Tag) mappings 2501luns | Required | array | Array of Bdev names to LUN ID mappings 2502queue_depth | Required | number | Target queue depth 2503disable_chap | Optional | boolean | CHAP authentication should be disabled for this target 2504require_chap | Optional | boolean | CHAP authentication should be required for this target 2505mutual_chap | Optional | boolean | CHAP authentication should be bidirectional (`true`) or unidirectional (`false`) 2506chap_group | Optional | number | Authentication group ID for this target node 2507header_digest | Optional | boolean | Header Digest should be required for this target node 2508data_digest | Optional | boolean | Data Digest should be required for this target node 2509 2510Parameters `disable_chap` and `require_chap` are mutually exclusive. 2511 2512### Example 2513 2514Example request: 2515 2516~~~ 2517{ 2518 "params": { 2519 "luns": [ 2520 { 2521 "lun_id": 0, 2522 "bdev_name": "Nvme0n1" 2523 } 2524 ], 2525 "mutual_chap": true, 2526 "name": "target2", 2527 "alias_name": "iscsi-target2-alias", 2528 "pg_ig_maps": [ 2529 { 2530 "ig_tag": 1, 2531 "pg_tag": 1 2532 }, 2533 { 2534 "ig_tag": 2, 2535 "pg_tag": 2 2536 } 2537 ], 2538 "data_digest": true, 2539 "disable_chap": true, 2540 "header_digest": true, 2541 "queue_depth": 24 2542 }, 2543 "jsonrpc": "2.0", 2544 "method": "construct_target_node", 2545 "id": 1 2546} 2547~~~ 2548 2549Example response: 2550 2551~~~ 2552{ 2553 "jsonrpc": "2.0", 2554 "id": 1, 2555 "result": true 2556} 2557~~~ 2558 2559## set_iscsi_target_node_auth method {#rpc_set_iscsi_target_node_auth} 2560 2561Set CHAP authentication to an existing iSCSI target node. 2562 2563### Parameters 2564 2565Name | Optional | Type | Description 2566--------------------------- | -------- | --------| ----------- 2567name | Required | string | Target node name (ASCII) 2568disable_chap | Optional | boolean | CHAP authentication should be disabled for this target 2569require_chap | Optional | boolean | CHAP authentication should be required for this target 2570mutual_chap | Optional | boolean | CHAP authentication should be bidirectional (`true`) or unidirectional (`false`) 2571chap_group | Optional | number | Authentication group ID for this target node 2572 2573Parameters `disable_chap` and `require_chap` are mutually exclusive. 2574 2575### Example 2576 2577Example request: 2578 2579~~~ 2580{ 2581 "params": { 2582 "chap_group": 1, 2583 "require_chap": true, 2584 "name": "iqn.2016-06.io.spdk:target1", 2585 "mutual_chap": true 2586 }, 2587 "jsonrpc": "2.0", 2588 "method": "set_iscsi_target_node_auth", 2589 "id": 1 2590} 2591~~~ 2592 2593Example response: 2594 2595~~~ 2596{ 2597 "jsonrpc": "2.0", 2598 "id": 1, 2599 "result": true 2600} 2601~~~ 2602 2603## add_pg_ig_maps method {#rpc_add_pg_ig_maps} 2604 2605Add initiator group to portal group mappings to an existing iSCSI target node. 2606 2607### Parameters 2608 2609Name | Optional | Type | Description 2610--------------------------- | -------- | --------| ----------- 2611name | Required | string | Target node name (ASCII) 2612pg_ig_maps | Required | array | Not empty array of initiator to portal group mappings objects 2613 2614Portal to Initiator group mappings object: 2615 2616Name | Optional | Type | Description 2617--------------------------- | -------- | --------| ----------- 2618ig_tag | Required | number | Existing initiator group tag 2619pg_tag | Required | number | Existing portal group tag 2620 2621### Example 2622 2623Example request: 2624 2625~~~ 2626{ 2627 "params": { 2628 "pg_ig_maps": [ 2629 { 2630 "ig_tag": 1, 2631 "pg_tag": 1 2632 }, 2633 { 2634 "ig_tag": 2, 2635 "pg_tag": 2 2636 }, 2637 { 2638 "ig_tag": 3, 2639 "pg_tag": 3 2640 } 2641 ], 2642 "name": "iqn.2016-06.io.spdk:target3" 2643 }, 2644 "jsonrpc": "2.0", 2645 "method": "add_pg_ig_maps", 2646 "id": 1 2647} 2648~~~ 2649 2650Example response: 2651 2652~~~ 2653{ 2654 "jsonrpc": "2.0", 2655 "id": 1, 2656 "result": true 2657} 2658~~~ 2659 2660## delete_pg_ig_maps method {#rpc_delete_pg_ig_maps} 2661 2662Delete initiator group to portal group mappings from an existing iSCSI target node. 2663 2664### Parameters 2665 2666Name | Optional | Type | Description 2667--------------------------- | -------- | --------| ----------- 2668name | Required | string | Target node name (ASCII) 2669pg_ig_maps | Required | array | Not empty array of Portal to Initiator group mappings objects 2670 2671Portal to Initiator group mappings object: 2672 2673Name | Optional | Type | Description 2674--------------------------- | -------- | --------| ----------- 2675ig_tag | Required | number | Existing initiator group tag 2676pg_tag | Required | number | Existing portal group tag 2677 2678### Example 2679 2680Example request: 2681 2682~~~ 2683{ 2684 "params": { 2685 "pg_ig_maps": [ 2686 { 2687 "ig_tag": 1, 2688 "pg_tag": 1 2689 }, 2690 { 2691 "ig_tag": 2, 2692 "pg_tag": 2 2693 }, 2694 { 2695 "ig_tag": 3, 2696 "pg_tag": 3 2697 } 2698 ], 2699 "name": "iqn.2016-06.io.spdk:target3" 2700 }, 2701 "jsonrpc": "2.0", 2702 "method": "delete_pg_ig_maps", 2703 "id": 1 2704} 2705~~~ 2706 2707Example response: 2708 2709~~~ 2710{ 2711 "jsonrpc": "2.0", 2712 "id": 1, 2713 "result": true 2714} 2715~~~ 2716 2717## delete_target_node method {#rpc_delete_target_node} 2718 2719Delete a iSCSI target node. 2720 2721### Parameters 2722 2723Name | Optional | Type | Description 2724--------------------------- | -------- | --------| ----------- 2725name | Required | string | Target node name (ASCII) 2726 2727### Example 2728 2729Example request: 2730 2731~~~ 2732{ 2733 "params": { 2734 "name": "iqn.2016-06.io.spdk:target1" 2735 }, 2736 "jsonrpc": "2.0", 2737 "method": "delete_target_node", 2738 "id": 1 2739} 2740~~~ 2741 2742Example response: 2743 2744~~~ 2745{ 2746 "jsonrpc": "2.0", 2747 "id": 1, 2748 "result": true 2749} 2750~~~ 2751 2752## get_portal_groups method {#rpc_get_portal_groups} 2753 2754Show information about all available portal groups. 2755 2756### Parameters 2757 2758This method has no parameters. 2759 2760### Example 2761 2762Example request: 2763 2764~~~ 2765request: 2766{ 2767 "jsonrpc": "2.0", 2768 "method": "get_portal_groups", 2769 "id": 1 2770} 2771~~~ 2772 2773Example response: 2774 2775~~~ 2776{ 2777 "jsonrpc": "2.0", 2778 "id": 1, 2779 "result": [ 2780 { 2781 "portals": [ 2782 { 2783 "cpumask": "0x2", 2784 "host": "127.0.0.1", 2785 "port": "3260" 2786 } 2787 ], 2788 "tag": 1 2789 } 2790 ] 2791} 2792~~~ 2793 2794## add_portal_group method {#rpc_add_portal_group} 2795 2796Add a portal group. 2797 2798### Parameters 2799 2800Name | Optional | Type | Description 2801--------------------------- | -------- | --------| ----------- 2802tag | Required | number | Portal group tag 2803portals | Required | array | Not empty array of portals 2804 2805Portal object 2806 2807Name | Optional | Type | Description 2808--------------------------- | -------- | --------| ----------- 2809host | Required | string | Hostname or IP address 2810port | Required | string | Port number 2811 2812### Example 2813 2814Example request: 2815 2816~~~ 2817{ 2818 "params": { 2819 "portals": [ 2820 { 2821 "host": "127.0.0.1", 2822 "port": "3260" 2823 } 2824 ], 2825 "tag": 1 2826 }, 2827 "jsonrpc": "2.0", 2828 "method": "add_portal_group", 2829 "id": 1 2830} 2831~~~ 2832 2833Example response: 2834 2835~~~ 2836{ 2837 "jsonrpc": "2.0", 2838 "id": 1, 2839 "result": true 2840} 2841~~~ 2842 2843## delete_portal_group method {#rpc_delete_portal_group} 2844 2845Delete an existing portal group. 2846 2847### Parameters 2848 2849Name | Optional | Type | Description 2850--------------------------- | -------- | --------| ----------- 2851tag | Required | number | Existing portal group tag 2852 2853### Example 2854 2855Example request: 2856 2857~~~ 2858{ 2859 "params": { 2860 "tag": 1 2861 }, 2862 "jsonrpc": "2.0", 2863 "method": "delete_portal_group", 2864 "id": 1 2865} 2866~~~ 2867 2868Example response: 2869 2870~~~ 2871{ 2872 "jsonrpc": "2.0", 2873 "id": 1, 2874 "result": true 2875} 2876~~~ 2877 2878## get_iscsi_connections method {#rpc_get_iscsi_connections} 2879 2880Show information about all active connections. 2881 2882### Parameters 2883 2884This method has no parameters. 2885 2886### Results 2887 2888Array of objects describing iSCSI connection. 2889 2890Name | Type | Description 2891--------------------------- | --------| ----------- 2892id | number | Index (used for TTT - Target Transfer Tag) 2893cid | number | CID (Connection ID) 2894tsih | number | TSIH (Target Session Identifying Handle) 2895lcore_id | number | Core number on which the iSCSI connection runs 2896initiator_addr | string | Initiator address 2897target_addr | string | Target address 2898target_node_name | string | Target node name (ASCII) without prefix 2899 2900### Example 2901 2902Example request: 2903 2904~~~ 2905{ 2906 "jsonrpc": "2.0", 2907 "method": "get_iscsi_connections", 2908 "id": 1 2909} 2910~~~ 2911 2912Example response: 2913 2914~~~ 2915{ 2916 "jsonrpc": "2.0", 2917 "id": 1, 2918 "result": [ 2919 { 2920 "tsih": 4, 2921 "cid": 0, 2922 "target_node_name": "target1", 2923 "lcore_id": 0, 2924 "initiator_addr": "10.0.0.2", 2925 "target_addr": "10.0.0.1", 2926 "id": 0 2927 } 2928 ] 2929} 2930~~~ 2931 2932## target_node_add_lun method {#rpc_target_node_add_lun} 2933 2934Add an LUN to an existing iSCSI target node. 2935 2936### Parameters 2937 2938Name | Optional | Type | Description 2939--------------------------- | -------- | --------| ----------- 2940name | Required | string | Target node name (ASCII) 2941bdev_name | Required | string | bdev name to be added as a LUN 2942lun_id | Optional | number | LUN ID (default: first free ID) 2943 2944### Example 2945 2946Example request: 2947 2948~~~ 2949{ 2950 "params": { 2951 "lun_id": 2, 2952 "name": "iqn.2016-06.io.spdk:target1", 2953 "bdev_name": "Malloc0" 2954 }, 2955 "jsonrpc": "2.0", 2956 "method": "target_node_add_lun", 2957 "id": 1 2958} 2959~~~ 2960 2961Example response: 2962 2963~~~ 2964{ 2965 "jsonrpc": "2.0", 2966 "id": 1, 2967 "result": true 2968} 2969~~~ 2970 2971# NVMe-oF Target {#jsonrpc_components_nvmf_tgt} 2972 2973## get_nvmf_subsystems method {#rpc_get_nvmf_subsystems} 2974 2975### Parameters 2976 2977This method has no parameters. 2978 2979### Example 2980 2981Example request: 2982~~~ 2983{ 2984 "jsonrpc": "2.0", 2985 "id": 1, 2986 "method": "get_nvmf_subsystems" 2987} 2988~~~ 2989 2990Example response: 2991~~~ 2992{ 2993 "jsonrpc": "2.0", 2994 "id": 1, 2995 "result": [ 2996 { 2997 "nqn": "nqn.2014-08.org.nvmexpress.discovery", 2998 "subtype": "Discovery" 2999 "listen_addresses": [], 3000 "hosts": [], 3001 "allow_any_host": true 3002 }, 3003 { 3004 "nqn": "nqn.2016-06.io.spdk:cnode1", 3005 "subtype": "NVMe", 3006 "listen_addresses": [ 3007 { 3008 "trtype": "RDMA", 3009 "adrfam": "IPv4", 3010 "traddr": "192.168.0.123", 3011 "trsvcid": "4420" 3012 } 3013 ], 3014 "hosts": [ 3015 {"nqn": "nqn.2016-06.io.spdk:host1"} 3016 ], 3017 "allow_any_host": false, 3018 "serial_number": "abcdef", 3019 "namespaces": [ 3020 {"nsid": 1, "name": "Malloc2"}, 3021 {"nsid": 2, "name": "Nvme0n1"} 3022 ] 3023 } 3024 ] 3025} 3026~~~ 3027 3028## nvmf_subsystem_create method {#rpc_nvmf_subsystem_create} 3029 3030Construct an NVMe over Fabrics target subsystem. 3031 3032### Parameters 3033 3034Name | Optional | Type | Description 3035----------------------- | -------- | ----------- | ----------- 3036nqn | Required | string | Subsystem NQN 3037serial_number | Optional | string | Serial number of virtual controller 3038max_namespaces | Optional | number | Maximum number of namespaces that can be attached to the subsystem. Default: 0 (Unlimited) 3039allow_any_host | Optional | boolean | Allow any host (`true`) or enforce allowed host whitelist (`false`). Default: `false`. 3040 3041### Example 3042 3043Example request: 3044 3045~~~ 3046{ 3047 "jsonrpc": "2.0", 3048 "id": 1, 3049 "method": "nvmf_subsystem_create", 3050 "params": { 3051 "nqn": "nqn.2016-06.io.spdk:cnode1", 3052 "allow_any_host": false, 3053 "serial_number": "abcdef", 3054 } 3055} 3056~~~ 3057 3058Example response: 3059 3060~~~ 3061{ 3062 "jsonrpc": "2.0", 3063 "id": 1, 3064 "result": true 3065} 3066~~~ 3067 3068## delete_nvmf_subsystem method {#rpc_delete_nvmf_subsystem} 3069 3070Delete an existing NVMe-oF subsystem. 3071 3072### Parameters 3073 3074Parameter | Optional | Type | Description 3075---------------------- | -------- | ----------- | ----------- 3076nqn | Required | string | Subsystem NQN to delete. 3077 3078### Example 3079 3080Example request: 3081 3082~~~ 3083{ 3084 "jsonrpc": "2.0", 3085 "id": 1, 3086 "method": "delete_nvmf_subsystem", 3087 "params": { 3088 "nqn": "nqn.2016-06.io.spdk:cnode1" 3089 } 3090} 3091~~~ 3092 3093Example response: 3094 3095~~~ 3096{ 3097 "jsonrpc": "2.0", 3098 "id": 1, 3099 "result": true 3100} 3101~~~ 3102 3103## nvmf_subsystem_add_listener method {#rpc_nvmf_subsystem_add_listener} 3104 3105Add a new listen address to an NVMe-oF subsystem. 3106 3107### Parameters 3108 3109Name | Optional | Type | Description 3110----------------------- | -------- | ----------- | ----------- 3111nqn | Required | string | Subsystem NQN 3112listen_address | Required | object | @ref rpc_nvmf_listen_address object 3113 3114### listen_address {#rpc_nvmf_listen_address} 3115 3116Name | Optional | Type | Description 3117----------------------- | -------- | ----------- | ----------- 3118trtype | Required | string | Transport type ("RDMA") 3119adrfam | Required | string | Address family ("IPv4", "IPv6", "IB", or "FC") 3120traddr | Required | string | Transport address 3121trsvcid | Required | string | Transport service ID 3122 3123### Example 3124 3125Example request: 3126 3127~~~ 3128{ 3129 "jsonrpc": "2.0", 3130 "id": 1, 3131 "method": "nvmf_subsystem_add_listener", 3132 "params": { 3133 "nqn": "nqn.2016-06.io.spdk:cnode1", 3134 "listen_address": { 3135 "trtype": "RDMA", 3136 "adrfam": "IPv4", 3137 "traddr": "192.168.0.123", 3138 "trsvcid: "4420" 3139 } 3140 } 3141} 3142~~~ 3143 3144Example response: 3145 3146~~~ 3147{ 3148 "jsonrpc": "2.0", 3149 "id": 1, 3150 "result": true 3151} 3152~~~ 3153 3154## nvmf_subsystem_add_ns method {#rpc_nvmf_subsystem_add_ns} 3155 3156Add a namespace to a subsystem. The namespace ID is returned as the result. 3157 3158### Parameters 3159 3160Name | Optional | Type | Description 3161----------------------- | -------- | ----------- | ----------- 3162nqn | Required | string | Subsystem NQN 3163namespace | Required | object | @ref rpc_nvmf_namespace object 3164 3165### namespace {#rpc_nvmf_namespace} 3166 3167Name | Optional | Type | Description 3168----------------------- | -------- | ----------- | ----------- 3169nsid | Optional | number | Namespace ID between 1 and 4294967294, inclusive. Default: Automatically assign NSID. 3170bdev_name | Required | string | Name of bdev to expose as a namespace. 3171nguid | Optional | string | 16-byte namespace globally unique identifier in hexadecimal (e.g. "ABCDEF0123456789ABCDEF0123456789") 3172eui64 | Optional | string | 8-byte namespace EUI-64 in hexadecimal (e.g. "ABCDEF0123456789") 3173uuid | Optional | string | RFC 4122 UUID (e.g. "ceccf520-691e-4b46-9546-34af789907c5") 3174 3175### Example 3176 3177Example request: 3178 3179~~~ 3180{ 3181 "jsonrpc": "2.0", 3182 "id": 1, 3183 "method": "nvmf_subsystem_add_ns", 3184 "params": { 3185 "nqn": "nqn.2016-06.io.spdk:cnode1", 3186 "namespace": { 3187 "nsid": 3, 3188 "bdev_name": "Nvme0n1" 3189 } 3190 } 3191} 3192~~~ 3193 3194Example response: 3195 3196~~~ 3197{ 3198 "jsonrpc": "2.0", 3199 "id": 1, 3200 "result": 3 3201} 3202~~~ 3203 3204## nvmf_subsystem_remove_ns method {#rpc_nvmf_subsystem_remove_ns} 3205 3206Remove a namespace from a subsystem. 3207 3208### Parameters 3209 3210Name | Optional | Type | Description 3211----------------------- | -------- | ----------- | ----------- 3212nqn | Required | string | Subsystem NQN 3213nsid | Required | number | Namespace ID 3214 3215### Example 3216 3217Example request: 3218 3219~~~ 3220{ 3221 "jsonrpc": "2.0", 3222 "id": 1, 3223 "method": "nvmf_subsystem_remove_ns", 3224 "params": { 3225 "nqn": "nqn.2016-06.io.spdk:cnode1", 3226 "nsid": 1 3227 } 3228} 3229~~~ 3230 3231Example response: 3232 3233~~~ 3234{ 3235 "jsonrpc": "2.0", 3236 "id": 1, 3237 "result": true 3238} 3239~~~ 3240 3241## nvmf_subsystem_add_host method {#rpc_nvmf_subsystem_add_host} 3242 3243Add a host NQN to the whitelist of allowed hosts. 3244 3245### Parameters 3246 3247Name | Optional | Type | Description 3248----------------------- | -------- | ----------- | ----------- 3249nqn | Required | string | Subsystem NQN 3250host | Required | string | Host NQN to add to the list of allowed host NQNs 3251 3252### Example 3253 3254Example request: 3255 3256~~~ 3257{ 3258 "jsonrpc": "2.0", 3259 "id": 1, 3260 "method": "nvmf_subsystem_add_host", 3261 "params": { 3262 "nqn": "nqn.2016-06.io.spdk:cnode1", 3263 "host": "nqn.2016-06.io.spdk:host1" 3264 } 3265} 3266~~~ 3267 3268Example response: 3269 3270~~~ 3271{ 3272 "jsonrpc": "2.0", 3273 "id": 1, 3274 "result": true 3275} 3276~~~ 3277 3278## nvmf_subsystem_remove_host method {#rpc_nvmf_subsystem_remove_host} 3279 3280Remove a host NQN from the whitelist of allowed hosts. 3281 3282### Parameters 3283 3284Name | Optional | Type | Description 3285----------------------- | -------- | ----------- | ----------- 3286nqn | Required | string | Subsystem NQN 3287host | Required | string | Host NQN to remove from the list of allowed host NQNs 3288 3289### Example 3290 3291Example request: 3292 3293~~~ 3294{ 3295 "jsonrpc": "2.0", 3296 "id": 1, 3297 "method": "nvmf_subsystem_remove_host", 3298 "params": { 3299 "nqn": "nqn.2016-06.io.spdk:cnode1", 3300 "host": "nqn.2016-06.io.spdk:host1" 3301 } 3302} 3303~~~ 3304 3305Example response: 3306 3307~~~ 3308{ 3309 "jsonrpc": "2.0", 3310 "id": 1, 3311 "result": true 3312} 3313~~~ 3314 3315## nvmf_subsystem_allow_any_host method {#rpc_nvmf_subsystem_allow_any_host} 3316 3317Configure a subsystem to allow any host to connect or to enforce the host NQN whitelist. 3318 3319### Parameters 3320 3321Name | Optional | Type | Description 3322----------------------- | -------- | ----------- | ----------- 3323nqn | Required | string | Subsystem NQN 3324allow_any_host | Required | boolean | Allow any host (`true`) or enforce allowed host whitelist (`false`). 3325 3326### Example 3327 3328Example request: 3329 3330~~~ 3331{ 3332 "jsonrpc": "2.0", 3333 "id": 1, 3334 "method": "nvmf_subsystem_allow_any_host", 3335 "params": { 3336 "nqn": "nqn.2016-06.io.spdk:cnode1", 3337 "allow_any_host": true 3338 } 3339} 3340~~~ 3341 3342Example response: 3343 3344~~~ 3345{ 3346 "jsonrpc": "2.0", 3347 "id": 1, 3348 "result": true 3349} 3350~~~ 3351 3352## set_nvmf_target_max_subsystems {#rpc_set_nvmf_target_max_subsystems} 3353 3354Set the maximum allowed subsystems for the NVMe-oF target. This RPC may only be called 3355before SPDK subsystems have been initialized. 3356 3357### Parameters 3358 3359Name | Optional | Type | Description 3360----------------------- | -------- | ----------- | ----------- 3361max_subsystems | Required | number | Maximum number of NVMe-oF subsystems 3362 3363### Example 3364 3365Example request: 3366~~~ 3367{ 3368 "jsonrpc": "2.0", 3369 "id": 1, 3370 "method": "set_nvmf_target_max_subsystems", 3371 "params": { 3372 "max_subsystems": 1024 3373 } 3374} 3375~~~ 3376 3377Example response: 3378~~~ 3379{ 3380 "jsonrpc": "2.0", 3381 "id": 1, 3382 "result": true 3383} 3384~~~ 3385 3386## set_nvmf_target_config {#rpc_set_nvmf_target_config} 3387 3388Set global configuration of NVMe-oF target. This RPC may only be called before SPDK subsystems 3389have been initialized. 3390 3391### Parameters 3392 3393Name | Optional | Type | Description 3394----------------------- | -------- | ----------- | ----------- 3395acceptor_poll_rate | Optional | number | Polling interval of the acceptor for incoming connections (microseconds) 3396 3397### Example 3398 3399Example request: 3400~~~ 3401{ 3402 "jsonrpc": "2.0", 3403 "id": 1, 3404 "method": "set_nvmf_target_config", 3405 "params": { 3406 "acceptor_poll_rate": 10000 3407 } 3408} 3409~~~ 3410 3411Example response: 3412~~~ 3413{ 3414 "jsonrpc": "2.0", 3415 "id": 1, 3416 "result": true 3417} 3418~~~ 3419 3420## get_nvmf_transports method {#rpc_get_nvmf_transports} 3421 3422### Parameters 3423 3424This method has no parameters. 3425 3426### Example 3427 3428Example request: 3429~~~ 3430{ 3431 "jsonrpc": "2.0", 3432 "id": 1, 3433 "method": "get_nvmf_transports" 3434} 3435~~~ 3436 3437Example response: 3438~~~ 3439{ 3440 "jsonrpc": "2.0", 3441 "id": 1, 3442 "result": [ 3443 { 3444 "type": "RDMA". 3445 "max_queue_depth": 128, 3446 "max_qpairs_per_ctrlr": 64, 3447 "in_capsule_data_size": 4096, 3448 "max_io_size": 131072, 3449 "io_unit_size": 131072 3450 } 3451 ] 3452} 3453~~~ 3454 3455# Vhost Target {#jsonrpc_components_vhost_tgt} 3456 3457The following common preconditions need to be met in all target types. 3458 3459Controller name will be used to create UNIX domain socket. This implies that name concatenated with vhost socket 3460directory path needs to be valid UNIX socket name. 3461 3462@ref cpu_mask parameter is used to choose CPU on which pollers will be launched when new initiator is connecting. 3463It must be a subset of application CPU mask. Default value is CPU mask of the application. 3464 3465## set_vhost_controller_coalescing {#rpc_set_vhost_controller_coalescing} 3466 3467Controls interrupt coalescing for specific target. Because `delay_base_us` is used to calculate delay in CPU ticks 3468there is no hardcoded limit for this parameter. Only limitation is that final delay in CPU ticks might not overflow 346932 bit unsigned integer (which is more than 1s @ 4GHz CPU). In real scenarios `delay_base_us` should be much lower 3470than 150us. To disable coalescing set `delay_base_us` to 0. 3471 3472### Parameters 3473 3474Name | Optional | Type | Description 3475----------------------- | -------- | ----------- | ----------- 3476ctrlr | Required | string | Controller name 3477delay_base_us | Required | number | Base (minimum) coalescing time in microseconds 3478iops_threshold | Required | number | Coalescing activation level greater than 0 in IO per second 3479 3480### Example 3481 3482Example request: 3483 3484~~~ 3485{ 3486 "params": { 3487 "iops_threshold": 100000, 3488 "ctrlr": "VhostScsi0", 3489 "delay_base_us": 80 3490 }, 3491 "jsonrpc": "2.0", 3492 "method": "set_vhost_controller_coalescing", 3493 "id": 1 3494} 3495~~~ 3496 3497Example response: 3498 3499~~~ 3500{ 3501 "jsonrpc": "2.0", 3502 "id": 1, 3503 "result": true 3504} 3505~~~ 3506 3507## construct_vhost_scsi_controller {#rpc_construct_vhost_scsi_controller} 3508 3509Construct vhost SCSI target. 3510 3511### Parameters 3512 3513Name | Optional | Type | Description 3514----------------------- | -------- | ----------- | ----------- 3515ctrlr | Required | string | Controller name 3516cpumask | Optional | string | @ref cpu_mask for this controller 3517 3518### Example 3519 3520Example request: 3521 3522~~~ 3523{ 3524 "params": { 3525 "cpumask": "0x2", 3526 "ctrlr": "VhostScsi0" 3527 }, 3528 "jsonrpc": "2.0", 3529 "method": "construct_vhost_scsi_controller", 3530 "id": 1 3531} 3532~~~ 3533 3534Example response: 3535 3536~~~ 3537{ 3538 "jsonrpc": "2.0", 3539 "id": 1, 3540 "result": true 3541} 3542~~~ 3543 3544## add_vhost_scsi_lun {#rpc_add_vhost_scsi_lun} 3545 3546In vhost target `ctrlr` create SCSI target with ID `scsi_target_num` and add `bdev_name` as LUN 0. 3547 3548### Parameters 3549 3550Name | Optional | Type | Description 3551----------------------- | -------- | ----------- | ----------- 3552ctrlr | Required | string | Controller name 3553scsi_target_num | Required | number | SCSI target ID between 0 and 7 3554bdev_name | Required | string | Name of bdev to expose as a LUN 0 3555 3556### Example 3557 3558Example request: 3559 3560~~~ 3561{ 3562 "params": { 3563 "scsi_target_num": 1, 3564 "bdev_name": "Malloc0", 3565 "ctrlr": "VhostScsi0" 3566 }, 3567 "jsonrpc": "2.0", 3568 "method": "add_vhost_scsi_lun", 3569 "id": 1 3570} 3571~~~ 3572 3573Example response: 3574 3575~~~ 3576response: 3577{ 3578 "jsonrpc": "2.0", 3579 "id": 1, 3580 "result": true 3581} 3582~~~ 3583 3584## remove_vhost_scsi_target {#rpc_remove_vhost_scsi_target} 3585 3586Remove SCSI target ID `scsi_target_num` from vhost target `scsi_target_num`. 3587 3588This method will fail if initiator is connected, but doesn't support hot-remove (the `VIRTIO_SCSI_F_HOTPLUG` is not negotiated). 3589 3590### Parameters 3591 3592Name | Optional | Type | Description 3593----------------------- | -------- | ----------- | ----------- 3594ctrlr | Required | string | Controller name 3595scsi_target_num | Required | number | SCSI target ID between 0 and 7 3596 3597### Example 3598 3599Example request: 3600 3601~~~ 3602request: 3603{ 3604 "params": { 3605 "scsi_target_num": 1, 3606 "ctrlr": "VhostScsi0" 3607 }, 3608 "jsonrpc": "2.0", 3609 "method": "remove_vhost_scsi_target", 3610 "id": 1 3611} 3612~~~ 3613 3614Example response: 3615 3616~~~ 3617{ 3618 "jsonrpc": "2.0", 3619 "id": 1, 3620 "result": true 3621} 3622~~~ 3623 3624## construct_vhost_nvme_controller {#rpc_construct_vhost_nvme_controller} 3625 3626Construct empty vhost NVMe controller. 3627 3628### Parameters 3629 3630Name | Optional | Type | Description 3631----------------------- | -------- | ----------- | ----------- 3632ctrlr | Required | string | Controller name 3633io_queues | Required | number | Number between 1 and 31 of IO queues for the controller 3634cpumask | Optional | string | @ref cpu_mask for this controller 3635 3636 3637### Example 3638 3639Example request: 3640 3641~~~ 3642{ 3643 "params": { 3644 "cpumask": "0x2", 3645 "io_queues": 4, 3646 "ctrlr": "VhostNvme0" 3647 }, 3648 "jsonrpc": "2.0", 3649 "method": "construct_vhost_nvme_controller", 3650 "id": 1 3651} 3652~~~ 3653 3654Example response: 3655 3656~~~ 3657{ 3658 "jsonrpc": "2.0", 3659 "id": 1, 3660 "result": true 3661} 3662~~~ 3663 3664## add_vhost_nvme_ns {#rpc_add_vhost_nvme_ns} 3665 3666Add namespace backed by `bdev_name` 3667 3668### Parameters 3669 3670Name | Optional | Type | Description 3671----------------------- | -------- | ----------- | ----------- 3672ctrlr | Required | string | Controller name 3673bdev_name | Required | string | Name of bdev to expose as a namespace 3674cpumask | Optional | string | @ref cpu_mask for this controller 3675 3676### Example 3677 3678Example request: 3679 3680~~~ 3681{ 3682 "params": { 3683 "bdev_name": "Malloc0", 3684 "ctrlr": "VhostNvme0" 3685 }, 3686 "jsonrpc": "2.0", 3687 "method": "add_vhost_nvme_ns", 3688 "id": 1 3689} 3690~~~ 3691 3692Example response: 3693 3694~~~ 3695{ 3696 "jsonrpc": "2.0", 3697 "id": 1, 3698 "result": true 3699} 3700~~~ 3701 3702## construct_vhost_blk_controller {#rpc_construct_vhost_blk_controller} 3703 3704Construct vhost block controller 3705 3706If `readonly` is `true` then vhost block target will be created as read only and fail any write requests. 3707The `VIRTIO_BLK_F_RO` feature flag will be offered to the initiator. 3708 3709### Parameters 3710 3711Name | Optional | Type | Description 3712----------------------- | -------- | ----------- | ----------- 3713ctrlr | Required | string | Controller name 3714bdev_name | Required | string | Name of bdev to expose block device 3715readonly | Optional | boolean | If true, this target will be read only (default: false) 3716cpumask | Optional | string | @ref cpu_mask for this controller 3717 3718 3719### Example 3720 3721Example request: 3722 3723~~~ 3724{ 3725 "params": { 3726 "dev_name": "Malloc0", 3727 "ctrlr": "VhostBlk0" 3728 }, 3729 "jsonrpc": "2.0", 3730 "method": "construct_vhost_blk_controller", 3731 "id": 1 3732} 3733~~~ 3734 3735Example response: 3736 3737~~~ 3738{ 3739 "jsonrpc": "2.0", 3740 "id": 1, 3741 "result": true 3742} 3743~~~ 3744 3745## get_vhost_controllers {#rpc_get_vhost_controllers} 3746 3747Display information about all or specific vhost controller(s). 3748 3749### Parameters 3750 3751The user may specify no parameters in order to list all controllers, or a controller may be 3752specified by name. 3753 3754Name | Optional | Type | Description 3755----------------------- | -------- | ----------- | ----------- 3756name | Optional | string | Vhost controller name 3757 3758 3759### Response {#rpc_get_vhost_controllers_response} 3760 3761Response is an array of objects describing requested controller(s). Common fields are: 3762 3763Name | Type | Description 3764----------------------- | ----------- | ----------- 3765ctrlr | string | Controller name 3766cpumask | string | @ref cpu_mask of this controller 3767delay_base_us | number | Base (minimum) coalescing time in microseconds (0 if disabled) 3768iops_threshold | number | Coalescing activation level 3769backend_specific | object | Backend specific informations 3770 3771### Vhost block {#rpc_get_vhost_controllers_blk} 3772 3773`backend_specific` contains one `block` object of type: 3774 3775Name | Type | Description 3776----------------------- | ----------- | ----------- 3777bdev | string | Backing bdev name or Null if bdev is hot-removed 3778readonly | boolean | True if controllers is readonly, false otherwise 3779 3780### Vhost SCSI {#rpc_get_vhost_controllers_scsi} 3781 3782`backend_specific` contains `scsi` array of following objects: 3783 3784Name | Type | Description 3785----------------------- | ----------- | ----------- 3786target_name | string | Name of this SCSI target 3787id | number | Unique SPDK global SCSI target ID 3788scsi_dev_num | number | SCSI target ID initiator will see when scanning this controller 3789luns | array | array of objects describing @ref rpc_get_vhost_controllers_scsi_luns 3790 3791### Vhost SCSI LUN {#rpc_get_vhost_controllers_scsi_luns} 3792 3793Object of type: 3794 3795Name | Type | Description 3796----------------------- | ----------- | ----------- 3797id | number | SCSI LUN ID 3798bdev_name | string | Backing bdev name 3799 3800### Vhost NVMe {#rpc_get_vhost_controllers_nvme} 3801 3802`backend_specific` contains `namespaces` array of following objects: 3803 3804Name | Type | Description 3805----------------------- | ----------- | ----------- 3806nsid | number | Namespace ID 3807bdev | string | Backing bdev name 3808 3809### Example 3810 3811Example request: 3812 3813~~~ 3814{ 3815 "jsonrpc": "2.0", 3816 "method": "get_vhost_controllers", 3817 "id": 1 3818} 3819~~~ 3820 3821Example response: 3822 3823~~~ 3824{ 3825 "jsonrpc": "2.0", 3826 "id": 1, 3827 "result": [ 3828 { 3829 "cpumask": "0x2", 3830 "backend_specific": { 3831 "block": { 3832 "readonly": false, 3833 "bdev": "Malloc0" 3834 } 3835 }, 3836 "iops_threshold": 60000, 3837 "ctrlr": "VhostBlk0", 3838 "delay_base_us": 100 3839 }, 3840 { 3841 "cpumask": "0x2", 3842 "backend_specific": { 3843 "scsi": [ 3844 { 3845 "target_name": "Target 2", 3846 "luns": [ 3847 { 3848 "id": 0, 3849 "bdev_name": "Malloc1" 3850 } 3851 ], 3852 "id": 0, 3853 "scsi_dev_num": 2 3854 }, 3855 { 3856 "target_name": "Target 5", 3857 "luns": [ 3858 { 3859 "id": 0, 3860 "bdev_name": "Malloc2" 3861 } 3862 ], 3863 "id": 1, 3864 "scsi_dev_num": 5 3865 } 3866 ] 3867 }, 3868 "iops_threshold": 60000, 3869 "ctrlr": "VhostScsi0", 3870 "delay_base_us": 0 3871 }, 3872 { 3873 "cpumask": "0x2", 3874 "backend_specific": { 3875 "namespaces": [ 3876 { 3877 "bdev": "Malloc3", 3878 "nsid": 1 3879 }, 3880 { 3881 "bdev": "Malloc4", 3882 "nsid": 2 3883 } 3884 ] 3885 }, 3886 "iops_threshold": 60000, 3887 "ctrlr": "VhostNvme0", 3888 "delay_base_us": 0 3889 } 3890 ] 3891} 3892~~~ 3893 3894## remove_vhost_controller {#rpc_remove_vhost_controller} 3895 3896Remove vhost target. 3897 3898This call will fail if there is an initiator connected or there is at least one SCSI target configured in case of 3899vhost SCSI target. In the later case please remove all SCSI targets first using @ref rpc_remove_vhost_scsi_target. 3900 3901### Parameters 3902 3903Name | Optional | Type | Description 3904----------------------- | -------- | ----------- | ----------- 3905ctrlr | Required | string | Controller name 3906 3907### Example 3908 3909Example request: 3910 3911~~~ 3912{ 3913 "params": { 3914 "ctrlr": "VhostNvme0" 3915 }, 3916 "jsonrpc": "2.0", 3917 "method": "remove_vhost_controller", 3918 "id": 1 3919} 3920~~~ 3921 3922Example response: 3923 3924~~~ 3925{ 3926 "jsonrpc": "2.0", 3927 "id": 1, 3928 "result": true 3929} 3930~~~ 3931 3932# Logical Volume {#jsonrpc_components_lvol} 3933 3934Identification of logical volume store and logical volume is explained first. 3935 3936A logical volume store has a UUID and a name for its identification. 3937The UUID is generated on creation and it can be used as a unique identifier. 3938The name is specified on creation and can be renamed. 3939Either UUID or name is used to access logical volume store in RPCs. 3940 3941A logical volume has a UUID and a name for its identification. 3942The UUID of the logical volume is generated on creation and it can be unique identifier. 3943The alias of the logical volume takes the format _lvs_name/lvol_name_ where: 3944* _lvs_name_ is the name of the logical volume store. 3945* _lvol_name_ is specified on creation and can be renamed. 3946 3947## construct_lvol_store {#rpc_construct_lvol_store} 3948 3949Construct a logical volume store. 3950 3951### Parameters 3952 3953Name | Optional | Type | Description 3954----------------------- | -------- | ----------- | ----------- 3955bdev_name | Required | string | Bdev on which to construct logical volume store 3956lvs_name | Required | string | Name of the logical volume store to create 3957cluster_sz | Optional | number | Cluster size of the logical volume store in bytes 3958 3959### Response 3960 3961UUID of the created logical volume store is returned. 3962 3963### Example 3964 3965Example request: 3966~~~ 3967{ 3968 "jsonrpc": "2.0", 3969 "id": 1, 3970 "method": "construct_lvol_store", 3971 "params": { 3972 "lvs_name": "LVS0", 3973 "bdev_name": "Malloc0" 3974 } 3975} 3976~~~ 3977 3978Example response: 3979~~~ 3980{ 3981 "jsonrpc": "2.0", 3982 "id": 1, 3983 "result": "a9959197-b5e2-4f2d-8095-251ffb6985a5" 3984} 3985~~~ 3986 3987## destroy_lvol_store {#rpc_destroy_lvol_store} 3988 3989Destroy a logical volume store. 3990 3991### Parameters 3992 3993Name | Optional | Type | Description 3994----------------------- | -------- | ----------- | ----------- 3995uuid | Optional | string | UUID of the logical volume store to destroy 3996lvs_name | Optional | string | Name of the logical volume store to destroy 3997 3998Either uuid or lvs_name must be specified, but not both. 3999 4000### Example 4001 4002Example request: 4003~~~ 4004{ 4005 "jsonrpc": "2.0", 4006 "method": "destroy_lvol_store", 4007 "id": 1 4008 "params": { 4009 "uuid": "a9959197-b5e2-4f2d-8095-251ffb6985a5" 4010 } 4011} 4012~~~ 4013 4014Example response: 4015~~~ 4016{ 4017 "jsonrpc": "2.0", 4018 "id": 1, 4019 "result": true 4020} 4021~~~ 4022 4023## get_lvol_stores {#rpc_get_lvol_stores} 4024 4025Get a list of logical volume stores. 4026 4027### Parameters 4028 4029Name | Optional | Type | Description 4030----------------------- | -------- | ----------- | ----------- 4031uuid | Optional | string | UUID of the logical volume store to retrieve information about 4032lvs_name | Optional | string | Name of the logical volume store to retrieve information about 4033 4034Either uuid or lvs_name may be specified, but not both. 4035If both uuid and lvs_name are omitted, information about all logical volume stores is returned. 4036 4037### Example 4038 4039Example request: 4040~~~ 4041{ 4042 "jsonrpc": "2.0", 4043 "method": "get_lvol_stores", 4044 "id": 1, 4045 "params": { 4046 "lvs_name": "LVS0" 4047 } 4048} 4049~~~ 4050 4051Example response: 4052~~~ 4053{ 4054 "jsonrpc": "2.0", 4055 "id": 1, 4056 "result": [ 4057 { 4058 "uuid": "a9959197-b5e2-4f2d-8095-251ffb6985a5", 4059 "base_bdev": "Malloc0", 4060 "free_clusters": 31, 4061 "cluster_size": 4194304, 4062 "total_data_clusters": 31, 4063 "block_size": 4096, 4064 "name": "LVS0" 4065 } 4066 ] 4067} 4068~~~ 4069 4070## rename_lvol_store {#rpc_rename_lvol_store} 4071 4072Rename a logical volume store. 4073 4074### Parameters 4075 4076Name | Optional | Type | Description 4077----------------------- | -------- | ----------- | ----------- 4078old_name | Required | string | Existing logical volume store name 4079new_name | Required | string | New logical volume store name 4080 4081### Example 4082 4083Example request: 4084~~~ 4085{ 4086 "jsonrpc": "2.0", 4087 "method": "rename_lvol_store", 4088 "id": 1, 4089 "params": { 4090 "old_name": "LVS0", 4091 "new_name": "LVS2" 4092 } 4093} 4094~~~ 4095 4096Example response: 4097~~~ 4098{ 4099 "jsonrpc": "2.0", 4100 "id": 1, 4101 "result": true 4102} 4103~~~ 4104 4105## construct_lvol_bdev {#rpc_construct_lvol_bdev} 4106 4107Create a logical volume on a logical volume store. 4108 4109### Parameters 4110 4111Name | Optional | Type | Description 4112----------------------- | -------- | ----------- | ----------- 4113lvol_name | Required | string | Name of logical volume to create 4114size | Required | number | Desired size of logical volume in bytes 4115thin_provision | Optional | boolean | True to enable thin provisioning 4116uuid | Optional | string | UUID of logical volume store to create logical volume on 4117lvs_name | Optional | string | Name of logical volume store to create logical volume on 4118 4119Size will be rounded up to a multiple of cluster size. Either uuid or lvs_name must be specified, but not both. 4120lvol_name will be used in the alias of the created logical volume. 4121 4122### Response 4123 4124UUID of the created logical volume is returned. 4125 4126### Example 4127 4128Example request: 4129~~~ 4130{ 4131 "jsonrpc": "2.0", 4132 "method": "construct_lvol_bdev", 4133 "id": 1, 4134 "params": { 4135 "lvol_name": "LVOL0", 4136 "size": 1048576, 4137 "lvs_name": "LVS0", 4138 "thin_provision": true 4139 } 4140} 4141~~~ 4142 4143Example response: 4144~~~ 4145{ 4146 "jsonrpc": "2.0", 4147 "id": 1, 4148 "result": "1b38702c-7f0c-411e-a962-92c6a5a8a602" 4149} 4150~~~ 4151 4152## snapshot_lvol_bdev {#rpc_snapshot_lvol_bdev} 4153 4154Capture a snapshot of the current state of a logical volume. 4155 4156### Parameters 4157 4158Name | Optional | Type | Description 4159----------------------- | -------- | ----------- | ----------- 4160lvol_name | Required | string | UUID or alias of the logical volume to create a snapshot from 4161snapshot_name | Required | string | Name for the newly created snapshot 4162 4163### Response 4164 4165UUID of the created logical volume snapshot is returned. 4166 4167### Example 4168 4169Example request: 4170~~~ 4171{ 4172 "jsonrpc": "2.0", 4173 "method": "snapshot_lvol_bdev", 4174 "id": 1, 4175 "params": { 4176 "lvol_name": "1b38702c-7f0c-411e-a962-92c6a5a8a602", 4177 "snapshot_name": "SNAP1" 4178 } 4179} 4180~~~ 4181 4182Example response: 4183~~~ 4184{ 4185 "jsonrpc": "2.0", 4186 "id": 1, 4187 "result": "cc8d7fdf-7865-4d1f-9fc6-35da8e368670" 4188} 4189~~~ 4190 4191## clone_lvol_bdev {#rpc_clone_lvol_bdev} 4192 4193Create a logical volume based on a snapshot. 4194 4195### Parameters 4196 4197Name | Optional | Type | Description 4198----------------------- | -------- | ----------- | ----------- 4199snapshot_name | Required | string | UUID or alias of the snapshot to clone 4200clone_name | Required | string | Name for the logical volume to create 4201 4202### Response 4203 4204UUID of the created logical volume clone is returned. 4205 4206### Example 4207 4208Example request: 4209~~~ 4210{ 4211 "jsonrpc": "2.0" 4212 "method": "clone_lvol_bdev", 4213 "id": 1, 4214 "params": { 4215 "snapshot_name": "cc8d7fdf-7865-4d1f-9fc6-35da8e368670", 4216 "clone_name": "CLONE1" 4217 } 4218} 4219~~~ 4220 4221Example response: 4222~~~ 4223{ 4224 "jsonrpc": "2.0", 4225 "id": 1, 4226 "result": "8d87fccc-c278-49f0-9d4c-6237951aca09" 4227} 4228~~~ 4229 4230## rename_lvol_bdev {#rpc_rename_lvol_bdev} 4231 4232Rename a logical volume. New name will rename only the alias of the logical volume. 4233 4234### Parameters 4235 4236Name | Optional | Type | Description 4237----------------------- | -------- | ----------- | ----------- 4238old_name | Required | string | UUID or alias of the existing logical volume 4239new_name | Required | string | New logical volume name 4240 4241### Example 4242 4243Example request: 4244~~~ 4245{ 4246 "jsonrpc": "2.0", 4247 "method": "rename_lvol_bdev", 4248 "id": 1, 4249 "params": { 4250 "old_name": "067df606-6dbc-4143-a499-0d05855cb3b8", 4251 "new_name": "LVOL2" 4252 } 4253} 4254~~~ 4255 4256Example response: 4257~~~ 4258{ 4259 "jsonrpc": "2.0", 4260 "id": 1, 4261 "result": true 4262} 4263~~~ 4264 4265## resize_lvol_bdev {#rpc_resize_lvol_bdev} 4266 4267Resize a logical volume. 4268 4269### Parameters 4270 4271Name | Optional | Type | Description 4272----------------------- | -------- | ----------- | ----------- 4273name | Required | string | UUID or alias of the logical volume to resize 4274size | Required | number | Desired size of the logical volume in bytes 4275 4276### Example 4277 4278Example request: 4279~~~ 4280{ 4281 "jsonrpc": "2.0", 4282 "method": "resize_lvol_bdev", 4283 "id": 1, 4284 "params": { 4285 "name": "51638754-ca16-43a7-9f8f-294a0805ab0a", 4286 "size": 2097152 4287 } 4288} 4289~~~ 4290 4291Example response: 4292~~~ 4293{ 4294 "jsonrpc": "2.0", 4295 "id": 1, 4296 "result": true 4297} 4298~~~ 4299 4300## destroy_lvol_bdev {#rpc_destroy_lvol_bdev} 4301 4302Destroy a logical volume. 4303 4304### Parameters 4305 4306Name | Optional | Type | Description 4307----------------------- | -------- | ----------- | ----------- 4308name | Required | string | UUID or alias of the logical volume to destroy 4309 4310### Example 4311 4312Example request: 4313~~~ 4314{ 4315 "jsonrpc": "2.0", 4316 "method": "destroy_lvol_bdev", 4317 "id": 1, 4318 "params": { 4319 "name": "51638754-ca16-43a7-9f8f-294a0805ab0a" 4320 } 4321} 4322~~~ 4323 4324Example response: 4325~~~ 4326{ 4327 "jsonrpc": "2.0", 4328 "id": 1, 4329 "result": true 4330} 4331~~~ 4332 4333## inflate_lvol_bdev {#rpc_inflate_lvol_bdev} 4334 4335Inflate 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. 4336 4337### Parameters 4338 4339Name | Optional | Type | Description 4340----------------------- | -------- | ----------- | ----------- 4341name | Required | string | UUID or alias of the logical volume to inflate 4342 4343### Example 4344 4345Example request: 4346~~~ 4347{ 4348 "jsonrpc": "2.0", 4349 "method": "inflate_lvol_bdev", 4350 "id": 1, 4351 "params": { 4352 "name": "8d87fccc-c278-49f0-9d4c-6237951aca09" 4353 } 4354} 4355~~~ 4356 4357Example response: 4358~~~ 4359{ 4360 "jsonrpc": "2.0", 4361 "id": 1, 4362 "result": true 4363} 4364~~~ 4365 4366## decouple_parent_lvol_bdev {#rpc_decouple_parent_lvol_bdev} 4367 4368Decouple 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. 4369 4370### Parameters 4371 4372Name | Optional | Type | Description 4373----------------------- | -------- | ----------- | ----------- 4374name | Required | string | UUID or alias of the logical volume to decouple the parent of it 4375 4376### Example 4377 4378Example request: 4379~~~ 4380{ 4381 "jsonrpc": "2.0", 4382 "method": "decouple_parent_lvol_bdev", 4383 "id": 1. 4384 "params": { 4385 "name": "8d87fccc-c278-49f0-9d4c-6237951aca09" 4386 } 4387} 4388~~~ 4389 4390Example response: 4391~~~ 4392{ 4393 "jsonrpc": "2.0", 4394 "id": 1, 4395 "result": true 4396} 4397~~~ 4398 4399## send_nvme_cmd {#rpc_send_nvme_cmd} 4400 4401Send NVMe command directly to NVMe controller or namespace. Parameters and responses encoded by base64 urlsafe need further processing. 4402 4403Notice: send_nvme_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. 4404 4405### Parameters 4406 4407Name | Optional | Type | Description 4408----------------------- | -------- | ----------- | ----------- 4409name | Required | string | Name of the operating NVMe controller 4410cmd_type | Required | string | Type of nvme cmd. Valid values are: admin, io 4411data_direction | Required | string | Direction of data transfer. Valid values are: c2h, h2c 4412cmdbuf | Required | string | NVMe command encoded by base64 urlsafe 4413data | Optional | string | Data transferring to controller from host, encoded by base64 urlsafe 4414metadata | Optional | string | Metadata transferring to controller from host, encoded by base64 urlsafe 4415data_len | Optional | number | Data length required to transfer from controller to host 4416metadata_len | Optional | number | Metadata length required to transfer from controller to host 4417timeout_ms | Optional | number | Command execution timeout value, in milliseconds 4418 4419### Response 4420 4421Name | Type | Description 4422----------------------- | ----------- | ----------- 4423cpl | string | NVMe completion queue entry, encoded by base64 urlsafe 4424data | string | Data transferred from controller to host, encoded by base64 urlsafe 4425metadata | string | Metadata transferred from controller to host, encoded by base64 urlsafe 4426 4427### Example 4428 4429Example request: 4430~~~ 4431{ 4432 "jsonrpc": "2.0", 4433 "method": "send_nvme_cmd", 4434 "id": 1, 4435 "params": { 4436 "name": "Nvme0", 4437 "cmd_type": "admin" 4438 "data_direction": "c2h", 4439 "cmdbuf": "BgAAAAEAAAAAAAAAAAAAAAAAAAAAAAAAsGUs9P5_AAAAAAAAABAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA==", 4440 "data_len": 60, 4441 } 4442} 4443~~~ 4444 4445Example response: 4446~~~ 4447{ 4448 "jsonrpc": "2.0", 4449 "id": 1, 4450 "result": { 4451 "cpl": "AAAAAAAAAAARAAAAWrmwABAA==", 4452 "data": "sIjg6AAAAACwiODoAAAAALCI4OgAAAAAAAYAAREAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA" 4453 } 4454 4455} 4456~~~ 4457