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# App Framework {#jsonrpc_components_app} 9 10## kill_instance {#rpc_kill_instance} 11 12Send a signal to the application. 13 14### Parameters 15 16Name | Optional | Type | Description 17----------------------- | -------- | ----------- | ----------- 18sig_name | Required | string | Signal to send (SIGINT, SIGTERM, SIGQUIT, SIGHUP, or SIGKILL) 19 20### Example 21 22Example request: 23~~~ 24{ 25 "jsonrpc": "2.0", 26 "id": 1, 27 "method": "kill_instance", 28 "params": { 29 "sig_name": "SIGINT" 30 } 31} 32~~~ 33 34Example response: 35~~~ 36{ 37 "jsonrpc": "2.0", 38 "id": 1, 39 "result": true 40} 41~~~ 42 43## context_switch_monitor {#rpc_context_switch_monitor} 44 45Query, enable, or disable the context switch monitoring functionality. 46 47### Parameters 48 49Name | Optional | Type | Description 50----------------------- | -------- | ----------- | ----------- 51enabled | Optional | boolean | Enable (`true`) or disable (`false`) monitoring (omit this parameter to query the current state) 52 53### Response 54 55The current state of context switch monitoring is returned as a boolean. 56 57### Example 58 59Example request: 60~~~ 61{ 62 "jsonrpc": "2.0", 63 "id": 1, 64 "method": "context_switch_monitor", 65 "params": { 66 "enabled": false 67 } 68} 69~~~ 70 71Example response: 72~~~ 73{ 74 "jsonrpc": "2.0", 75 "id": 1, 76 "result": false 77} 78~~~ 79 80 81# Block Device Abstraction Layer {#jsonrpc_components_bdev} 82 83## set_bdev_options {#rpc_set_bdev_options} 84 85Set global parameters for the block device (bdev) subsystem. This RPC may only be called 86before subsystems have been initialized. 87 88### Parameters 89 90Name | Optional | Type | Description 91----------------------- | -------- | ----------- | ----------- 92bdev_io_pool_size | Optional | number | Number of spdk_bdev_io structures in shared buffer pool 93bdev_io_cache_size | Optional | number | Maximum number of spdk_bdev_io structures cached per thread 94 95### Example 96 97Example request: 98~~~ 99{ 100 "jsonrpc": "2.0", 101 "id": 1, 102 "method": "set_bdev_options", 103 "params": { 104 "bdev_io_pool_size": 65536, 105 "bdev_io_cache_size": 256 106 } 107} 108~~~ 109 110Example response: 111~~~ 112{ 113 "jsonrpc": "2.0", 114 "id": 1, 115 "result": true 116} 117~~~ 118 119## get_bdevs {#rpc_get_bdevs} 120 121Get information about block devices (bdevs). 122 123### Parameters 124 125The user may specify no parameters in order to list all block devices, or a block device may be 126specified by name. 127 128Name | Optional | Type | Description 129----------------------- | -------- | ----------- | ----------- 130name | Optional | string | Block device name 131 132### Response 133 134The response is an array of objects containing information about the requested block devices. 135 136### Example 137 138Example request: 139~~~ 140{ 141 "jsonrpc": "2.0", 142 "id": 1, 143 "method": "get_bdevs", 144 "params": { 145 "name": "Malloc0" 146 } 147} 148~~~ 149 150Example response: 151~~~ 152{ 153 "jsonrpc": "2.0", 154 "id": 1, 155 "result": [ 156 { 157 "name": "Malloc0", 158 "product_name": "Malloc disk", 159 "block_size": 512, 160 "num_blocks": 20480, 161 "claimed": false, 162 "supported_io_types": { 163 "read": true, 164 "write": true, 165 "unmap": true, 166 "write_zeroes": true, 167 "flush": true, 168 "reset": true, 169 "nvme_admin": false, 170 "nvme_io": false 171 }, 172 "driver_specific": {} 173 } 174 ] 175} 176~~~ 177 178## get_bdevs_iostat {#rpc_get_bdevs_iostat} 179 180Get I/O statistics of block devices (bdevs). 181 182### Parameters 183 184The user may specify no parameters in order to list all block devices, or a block device may be 185specified by name. 186 187Name | Optional | Type | Description 188----------------------- | -------- | ----------- | ----------- 189name | Optional | string | Block device name 190 191### Response 192 193The response is an array of objects containing I/O statistics of the requested block devices. 194 195### Example 196 197Example request: 198~~~ 199{ 200 "jsonrpc": "2.0", 201 "id": 1, 202 "method": "get_bdevs_iostat", 203 "params": { 204 "name": "Nvme0n1" 205 } 206} 207~~~ 208 209Example response: 210~~~ 211{ 212 "jsonrpc": "2.0", 213 "id": 1, 214 "result": [ 215 { 216 "name": "Nvme0n1", 217 "bytes_read": 34051522560, 218 "num_read_ops": 8312910, 219 "bytes_written": 0, 220 "num_write_ops": 0 221 } 222 ] 223} 224~~~ 225 226## delete_bdev {#rpc_delete_bdev} 227 228Unregister a block device. 229 230### Example 231 232Example request: 233~~~ 234{ 235 "jsonrpc": "2.0", 236 "id": 1, 237 "method": "delete_bdev", 238 "params": { 239 "name": "Malloc0" 240 } 241} 242~~~ 243 244Example response: 245~~~ 246{ 247 "jsonrpc": "2.0", 248 "id": 1, 249 "result": true 250} 251~~~ 252 253### Parameters 254 255Name | Optional | Type | Description 256----------------------- | -------- | ----------- | ----------- 257name | Required | string | Block device name 258 259## set_bdev_qos_limit_iops {#rpc_set_bdev_qos_limit_iops} 260 261Set an IOPS-based quality of service rate limit on a bdev. 262 263### Parameters 264 265Name | Optional | Type | Description 266----------------------- | -------- | ----------- | ----------- 267name | Required | string | Block device name 268ios_per_sec | Required | number | Number of I/Os per second to allow. 0 means unlimited. 269 270### Example 271 272Example request: 273~~~ 274{ 275 "jsonrpc": "2.0", 276 "id": 1, 277 "method": "set_bdev_qos_limit_iops", 278 "params": { 279 "name": "Malloc0" 280 "ios_per_sec": 20000 281 } 282} 283~~~ 284 285Example response: 286~~~ 287{ 288 "jsonrpc": "2.0", 289 "id": 1, 290 "result": true 291} 292~~~ 293 294# NVMe-oF Target {#jsonrpc_components_nvmf_tgt} 295 296## get_nvmf_subsystems method {#rpc_get_nvmf_subsystems} 297 298### Parameters 299 300This method has no parameters. 301 302### Example 303 304Example request: 305~~~ 306{ 307 "jsonrpc": "2.0", 308 "id": 1, 309 "method": "get_nvmf_subsystems" 310} 311~~~ 312 313Example response: 314~~~ 315{ 316 "jsonrpc": "2.0", 317 "id": 1, 318 "result": [ 319 { 320 "nqn": "nqn.2014-08.org.nvmexpress.discovery", 321 "subtype": "Discovery" 322 "listen_addresses": [], 323 "hosts": [], 324 "allow_any_host": true 325 }, 326 { 327 "nqn": "nqn.2016-06.io.spdk:cnode1", 328 "subtype": "NVMe", 329 "listen_addresses": [ 330 { 331 "trtype": "RDMA", 332 "adrfam": "IPv4", 333 "traddr": "192.168.0.123", 334 "trsvcid": "4420" 335 } 336 ], 337 "hosts": [ 338 {"nqn": "nqn.2016-06.io.spdk:host1"} 339 ], 340 "allow_any_host": false, 341 "serial_number": "abcdef", 342 "namespaces": [ 343 {"nsid": 1, "name": "Malloc2"}, 344 {"nsid": 2, "name": "Nvme0n1"} 345 ] 346 } 347 ] 348} 349~~~ 350 351## construct_nvmf_subsystem method {#rpc_construct_nvmf_subsystem} 352 353Construct an NVMe over Fabrics target subsystem. 354 355### Parameters 356 357Name | Optional | Type | Description 358----------------------- | -------- | ----------- | ----------- 359nqn | Required | string | Subsystem NQN 360listen_addresses | Optional | array | Array of @ref rpc_construct_nvmf_subsystem_listen_address objects 361hosts | Optional | array | Array of strings containing allowed host NQNs. Default: No hosts allowed. 362allow_any_host | Optional | boolean | Allow any host (`true`) or enforce allowed host whitelist (`false`). Default: `false`. 363serial_number | Required | string | Serial number of virtual controller 364namespaces | Optional | array | Array of @ref rpc_construct_nvmf_subsystem_namespace objects. Default: No namespaces. 365max_namespaces | Optional | number | Maximum number of namespaces that can be attached to the subsystem. Default: 0 (Unlimited) 366 367### listen_address {#rpc_construct_nvmf_subsystem_listen_address} 368 369Name | Optional | Type | Description 370----------------------- | -------- | ----------- | ----------- 371trtype | Required | string | Transport type ("RDMA") 372adrfam | Required | string | Address family ("IPv4", "IPv6", "IB", or "FC") 373traddr | Required | string | Transport address 374trsvcid | Required | string | Transport service ID 375 376### namespace {#rpc_construct_nvmf_subsystem_namespace} 377 378Name | Optional | Type | Description 379----------------------- | -------- | ----------- | ----------- 380nsid | Optional | number | Namespace ID between 1 and 4294967294, inclusive. Default: Automatically assign NSID. 381bdev_name | Required | string | Name of bdev to expose as a namespace. 382nguid | Optional | string | 16-byte namespace globally unique identifier in hexadecimal (e.g. "ABCDEF0123456789ABCDEF0123456789") 383eui64 | Optional | string | 8-byte namespace EUI-64 in hexadecimal (e.g. "ABCDEF0123456789") 384uuid | Optional | string | RFC 4122 UUID (e.g. "ceccf520-691e-4b46-9546-34af789907c5") 385 386### Example 387 388Example request: 389 390~~~ 391{ 392 "jsonrpc": "2.0", 393 "id": 1, 394 "method": "construct_nvmf_subsystem", 395 "params": { 396 "nqn": "nqn.2016-06.io.spdk:cnode1", 397 "listen_addresses": [ 398 { 399 "trtype": "RDMA", 400 "adrfam": "IPv4", 401 "traddr": "192.168.0.123", 402 "trsvcid: "4420" 403 } 404 ], 405 "hosts": [ 406 "nqn.2016-06.io.spdk:host1", 407 "nqn.2016-06.io.spdk:host2" 408 ], 409 "allow_any_host": false, 410 "serial_number": "abcdef", 411 "namespaces": [ 412 {"nsid": 1, "name": "Malloc2"}, 413 {"nsid": 2, "name": "Nvme0n1"} 414 ] 415 } 416} 417~~~ 418 419Example response: 420 421~~~ 422{ 423 "jsonrpc": "2.0", 424 "id": 1, 425 "result": true 426} 427~~~ 428 429## delete_nvmf_subsystem method {#rpc_delete_nvmf_subsystem} 430 431Delete an existing NVMe-oF subsystem. 432 433### Parameters 434 435Parameter | Optional | Type | Description 436---------------------- | -------- | ----------- | ----------- 437nqn | Required | string | Subsystem NQN to delete. 438 439### Example 440 441Example request: 442 443~~~ 444{ 445 "jsonrpc": "2.0", 446 "id": 1, 447 "method": "delete_nvmf_subsystem", 448 "params": { 449 "nqn": "nqn.2016-06.io.spdk:cnode1" 450 } 451} 452~~~ 453 454Example response: 455 456~~~ 457{ 458 "jsonrpc": "2.0", 459 "id": 1, 460 "result": true 461} 462~~~ 463 464## nvmf_subsystem_add_listener method {#rpc_nvmf_subsystem_add_listener} 465 466Add a new listen address to an NVMe-oF subsystem. 467 468### Parameters 469 470Name | Optional | Type | Description 471----------------------- | -------- | ----------- | ----------- 472nqn | Required | string | Subsystem NQN 473listen_address | Required | object | @ref rpc_construct_nvmf_subsystem_listen_address object 474 475### Example 476 477Example request: 478 479~~~ 480{ 481 "jsonrpc": "2.0", 482 "id": 1, 483 "method": "nvmf_subsystem_add_listener", 484 "params": { 485 "nqn": "nqn.2016-06.io.spdk:cnode1", 486 "listen_address": { 487 "trtype": "RDMA", 488 "adrfam": "IPv4", 489 "traddr": "192.168.0.123", 490 "trsvcid: "4420" 491 } 492 } 493} 494~~~ 495 496Example response: 497 498~~~ 499{ 500 "jsonrpc": "2.0", 501 "id": 1, 502 "result": true 503} 504~~~ 505 506## nvmf_subsystem_add_ns method {#rpc_nvmf_subsystem_add_ns} 507 508Add a namespace to a subsystem. The namespace ID is returned as the result. 509 510### Parameters 511 512Name | Optional | Type | Description 513----------------------- | -------- | ----------- | ----------- 514nqn | Required | string | Subsystem NQN 515namespace | Required | object | @ref rpc_construct_nvmf_subsystem_namespace object 516 517### Example 518 519Example request: 520 521~~~ 522{ 523 "jsonrpc": "2.0", 524 "id": 1, 525 "method": "nvmf_subsystem_add_ns", 526 "params": { 527 "nqn": "nqn.2016-06.io.spdk:cnode1", 528 "namespace": { 529 "nsid": 3, 530 "bdev_name": "Nvme0n1" 531 } 532 } 533} 534~~~ 535 536Example response: 537 538~~~ 539{ 540 "jsonrpc": "2.0", 541 "id": 1, 542 "result": 3 543} 544~~~ 545 546## nvmf_subsystem_remove_ns method {#rpc_nvmf_subsystem_remove_ns} 547 548Remove a namespace from a subsystem. 549 550### Parameters 551 552Name | Optional | Type | Description 553----------------------- | -------- | ----------- | ----------- 554nqn | Required | string | Subsystem NQN 555nsid | Required | number | Namespace ID 556 557### Example 558 559Example request: 560 561~~~ 562{ 563 "jsonrpc": "2.0", 564 "id": 1, 565 "method": "nvmf_subsystem_remove_ns", 566 "params": { 567 "nqn": "nqn.2016-06.io.spdk:cnode1", 568 "nsid": 1 569 } 570} 571~~~ 572 573Example response: 574 575~~~ 576{ 577 "jsonrpc": "2.0", 578 "id": 1, 579 "result": true 580} 581~~~ 582 583## nvmf_subsystem_add_host method {#rpc_nvmf_subsystem_add_host} 584 585Add a host NQN to the whitelist of allowed hosts. 586 587### Parameters 588 589Name | Optional | Type | Description 590----------------------- | -------- | ----------- | ----------- 591nqn | Required | string | Subsystem NQN 592host | Required | string | Host NQN to add to the list of allowed host NQNs 593 594### Example 595 596Example request: 597 598~~~ 599{ 600 "jsonrpc": "2.0", 601 "id": 1, 602 "method": "nvmf_subsystem_add_host", 603 "params": { 604 "nqn": "nqn.2016-06.io.spdk:cnode1", 605 "host": "nqn.2016-06.io.spdk:host1" 606 } 607} 608~~~ 609 610Example response: 611 612~~~ 613{ 614 "jsonrpc": "2.0", 615 "id": 1, 616 "result": true 617} 618~~~ 619 620## nvmf_subsystem_remove_host method {#rpc_nvmf_subsystem_remove_host} 621 622Remove a host NQN from the whitelist of allowed hosts. 623 624### Parameters 625 626Name | Optional | Type | Description 627----------------------- | -------- | ----------- | ----------- 628nqn | Required | string | Subsystem NQN 629host | Required | string | Host NQN to remove from the list of allowed host NQNs 630 631### Example 632 633Example request: 634 635~~~ 636{ 637 "jsonrpc": "2.0", 638 "id": 1, 639 "method": "nvmf_subsystem_remove_host", 640 "params": { 641 "nqn": "nqn.2016-06.io.spdk:cnode1", 642 "host": "nqn.2016-06.io.spdk:host1" 643 } 644} 645~~~ 646 647Example response: 648 649~~~ 650{ 651 "jsonrpc": "2.0", 652 "id": 1, 653 "result": true 654} 655~~~ 656 657## nvmf_subsystem_allow_any_host method {#rpc_nvmf_subsystem_allow_any_host} 658 659Configure a subsystem to allow any host to connect or to enforce the host NQN whitelist. 660 661### Parameters 662 663Name | Optional | Type | Description 664----------------------- | -------- | ----------- | ----------- 665nqn | Required | string | Subsystem NQN 666allow_any_host | Required | boolean | Allow any host (`true`) or enforce allowed host whitelist (`false`). 667 668### Example 669 670Example request: 671 672~~~ 673{ 674 "jsonrpc": "2.0", 675 "id": 1, 676 "method": "nvmf_subsystem_allow_any_host", 677 "params": { 678 "nqn": "nqn.2016-06.io.spdk:cnode1", 679 "allow_any_host": true 680 } 681} 682~~~ 683 684Example response: 685 686~~~ 687{ 688 "jsonrpc": "2.0", 689 "id": 1, 690 "result": true 691} 692~~~ 693