1# -*- Mode: Python -*- 2# vim: filetype=python 3# 4 5## 6# = Migration 7## 8 9{ 'include': 'common.json' } 10{ 'include': 'sockets.json' } 11 12## 13# @MigrationStats: 14# 15# Detailed migration status. 16# 17# @transferred: amount of bytes already transferred to the target VM 18# 19# @remaining: amount of bytes remaining to be transferred to the 20# target VM 21# 22# @total: total amount of bytes involved in the migration process 23# 24# @duplicate: number of duplicate (zero) pages (since 1.2) 25# 26# @skipped: number of skipped zero pages. Always zero, only provided for 27# compatibility (since 1.5) 28# 29# @normal: number of normal pages (since 1.2) 30# 31# @normal-bytes: number of normal bytes sent (since 1.2) 32# 33# @dirty-pages-rate: number of pages dirtied by second by the guest 34# (since 1.3) 35# 36# @mbps: throughput in megabits/sec. (since 1.6) 37# 38# @dirty-sync-count: number of times that dirty ram was synchronized 39# (since 2.1) 40# 41# @postcopy-requests: The number of page requests received from the 42# destination (since 2.7) 43# 44# @page-size: The number of bytes per page for the various page-based 45# statistics (since 2.10) 46# 47# @multifd-bytes: The number of bytes sent through multifd (since 3.0) 48# 49# @pages-per-second: the number of memory pages transferred per second 50# (Since 4.0) 51# 52# @precopy-bytes: The number of bytes sent in the pre-copy phase 53# (since 7.0). 54# 55# @downtime-bytes: The number of bytes sent while the guest is paused 56# (since 7.0). 57# 58# @postcopy-bytes: The number of bytes sent during the post-copy phase 59# (since 7.0). 60# 61# @dirty-sync-missed-zero-copy: Number of times dirty RAM 62# synchronization could not avoid copying dirty pages. This is 63# between 0 and @dirty-sync-count * @multifd-channels. (since 64# 7.1) 65# 66# Features: 67# 68# @deprecated: Member @skipped is always zero since 1.5.3 69# 70# Since: 0.14 71# 72## 73{ 'struct': 'MigrationStats', 74 'data': {'transferred': 'int', 'remaining': 'int', 'total': 'int' , 75 'duplicate': 'int', 76 'skipped': { 'type': 'int', 'features': [ 'deprecated' ] }, 77 'normal': 'int', 78 'normal-bytes': 'int', 'dirty-pages-rate': 'int', 79 'mbps': 'number', 'dirty-sync-count': 'int', 80 'postcopy-requests': 'int', 'page-size': 'int', 81 'multifd-bytes': 'uint64', 'pages-per-second': 'uint64', 82 'precopy-bytes': 'uint64', 'downtime-bytes': 'uint64', 83 'postcopy-bytes': 'uint64', 84 'dirty-sync-missed-zero-copy': 'uint64' } } 85 86## 87# @XBZRLECacheStats: 88# 89# Detailed XBZRLE migration cache statistics 90# 91# @cache-size: XBZRLE cache size 92# 93# @bytes: amount of bytes already transferred to the target VM 94# 95# @pages: amount of pages transferred to the target VM 96# 97# @cache-miss: number of cache miss 98# 99# @cache-miss-rate: rate of cache miss (since 2.1) 100# 101# @encoding-rate: rate of encoded bytes (since 5.1) 102# 103# @overflow: number of overflows 104# 105# Since: 1.2 106## 107{ 'struct': 'XBZRLECacheStats', 108 'data': {'cache-size': 'size', 'bytes': 'int', 'pages': 'int', 109 'cache-miss': 'int', 'cache-miss-rate': 'number', 110 'encoding-rate': 'number', 'overflow': 'int' } } 111 112## 113# @CompressionStats: 114# 115# Detailed migration compression statistics 116# 117# @pages: amount of pages compressed and transferred to the target VM 118# 119# @busy: count of times that no free thread was available to compress 120# data 121# 122# @busy-rate: rate of thread busy 123# 124# @compressed-size: amount of bytes after compression 125# 126# @compression-rate: rate of compressed size 127# 128# Since: 3.1 129## 130{ 'struct': 'CompressionStats', 131 'data': {'pages': 'int', 'busy': 'int', 'busy-rate': 'number', 132 'compressed-size': 'int', 'compression-rate': 'number' } } 133 134## 135# @MigrationStatus: 136# 137# An enumeration of migration status. 138# 139# @none: no migration has ever happened. 140# 141# @setup: migration process has been initiated. 142# 143# @cancelling: in the process of cancelling migration. 144# 145# @cancelled: cancelling migration is finished. 146# 147# @active: in the process of doing migration. 148# 149# @postcopy-active: like active, but now in postcopy mode. (since 150# 2.5) 151# 152# @postcopy-paused: during postcopy but paused. (since 3.0) 153# 154# @postcopy-recover: trying to recover from a paused postcopy. (since 155# 3.0) 156# 157# @completed: migration is finished. 158# 159# @failed: some error occurred during migration process. 160# 161# @colo: VM is in the process of fault tolerance, VM can not get into 162# this state unless colo capability is enabled for migration. 163# (since 2.8) 164# 165# @pre-switchover: Paused before device serialisation. (since 2.11) 166# 167# @device: During device serialisation when pause-before-switchover is 168# enabled (since 2.11) 169# 170# @wait-unplug: wait for device unplug request by guest OS to be 171# completed. (since 4.2) 172# 173# Since: 2.3 174## 175{ 'enum': 'MigrationStatus', 176 'data': [ 'none', 'setup', 'cancelling', 'cancelled', 177 'active', 'postcopy-active', 'postcopy-paused', 178 'postcopy-recover', 'completed', 'failed', 'colo', 179 'pre-switchover', 'device', 'wait-unplug' ] } 180## 181# @VfioStats: 182# 183# Detailed VFIO devices migration statistics 184# 185# @transferred: amount of bytes transferred to the target VM by VFIO 186# devices 187# 188# Since: 5.2 189## 190{ 'struct': 'VfioStats', 191 'data': {'transferred': 'int' } } 192 193## 194# @MigrationInfo: 195# 196# Information about current migration process. 197# 198# @status: @MigrationStatus describing the current migration status. 199# If this field is not returned, no migration process has been 200# initiated 201# 202# @ram: @MigrationStats containing detailed migration status, only 203# returned if status is 'active' or 'completed'(since 1.2) 204# 205# @disk: @MigrationStats containing detailed disk migration status, 206# only returned if status is 'active' and it is a block migration 207# 208# @xbzrle-cache: @XBZRLECacheStats containing detailed XBZRLE 209# migration statistics, only returned if XBZRLE feature is on and 210# status is 'active' or 'completed' (since 1.2) 211# 212# @total-time: total amount of milliseconds since migration started. 213# If migration has ended, it returns the total migration time. 214# (since 1.2) 215# 216# @downtime: only present when migration finishes correctly total 217# downtime in milliseconds for the guest. (since 1.3) 218# 219# @expected-downtime: only present while migration is active expected 220# downtime in milliseconds for the guest in last walk of the dirty 221# bitmap. (since 1.3) 222# 223# @setup-time: amount of setup time in milliseconds *before* the 224# iterations begin but *after* the QMP command is issued. This is 225# designed to provide an accounting of any activities (such as 226# RDMA pinning) which may be expensive, but do not actually occur 227# during the iterative migration rounds themselves. (since 1.6) 228# 229# @cpu-throttle-percentage: percentage of time guest cpus are being 230# throttled during auto-converge. This is only present when 231# auto-converge has started throttling guest cpus. (Since 2.7) 232# 233# @error-desc: the human readable error description string. Clients 234# should not attempt to parse the error strings. (Since 2.7) 235# 236# @postcopy-blocktime: total time when all vCPU were blocked during 237# postcopy live migration. This is only present when the 238# postcopy-blocktime migration capability is enabled. (Since 3.0) 239# 240# @postcopy-vcpu-blocktime: list of the postcopy blocktime per vCPU. 241# This is only present when the postcopy-blocktime migration 242# capability is enabled. (Since 3.0) 243# 244# @compression: migration compression statistics, only returned if 245# compression feature is on and status is 'active' or 'completed' 246# (Since 3.1) 247# 248# @socket-address: Only used for tcp, to know what the real port is 249# (Since 4.0) 250# 251# @vfio: @VfioStats containing detailed VFIO devices migration 252# statistics, only returned if VFIO device is present, migration 253# is supported by all VFIO devices and status is 'active' or 254# 'completed' (since 5.2) 255# 256# @blocked-reasons: A list of reasons an outgoing migration is 257# blocked. Present and non-empty when migration is blocked. 258# (since 6.0) 259# 260# @dirty-limit-throttle-time-per-round: Maximum throttle time 261# (in microseconds) of virtual CPUs each dirty ring full round, 262# which shows how MigrationCapability dirty-limit affects the 263# guest during live migration. (Since 8.1) 264# 265# @dirty-limit-ring-full-time: Estimated average dirty ring full time 266# (in microseconds) for each dirty ring full round. The value 267# equals the dirty ring memory size divided by the average dirty 268# page rate of the virtual CPU, which can be used to observe the 269# average memory load of the virtual CPU indirectly. Note that 270# zero means guest doesn't dirty memory. (Since 8.1) 271# 272# Features: 273# 274# @deprecated: Member @disk is deprecated because block migration is. 275# Member @compression is deprecated because it is unreliable and 276# untested. It is recommended to use multifd migration, which 277# offers an alternative compression implementation that is 278# reliable and tested. 279# 280# Since: 0.14 281## 282{ 'struct': 'MigrationInfo', 283 'data': {'*status': 'MigrationStatus', '*ram': 'MigrationStats', 284 '*disk': { 'type': 'MigrationStats', 'features': [ 'deprecated' ] }, 285 '*vfio': 'VfioStats', 286 '*xbzrle-cache': 'XBZRLECacheStats', 287 '*total-time': 'int', 288 '*expected-downtime': 'int', 289 '*downtime': 'int', 290 '*setup-time': 'int', 291 '*cpu-throttle-percentage': 'int', 292 '*error-desc': 'str', 293 '*blocked-reasons': ['str'], 294 '*postcopy-blocktime': 'uint32', 295 '*postcopy-vcpu-blocktime': ['uint32'], 296 '*compression': { 'type': 'CompressionStats', 'features': [ 'deprecated' ] }, 297 '*socket-address': ['SocketAddress'], 298 '*dirty-limit-throttle-time-per-round': 'uint64', 299 '*dirty-limit-ring-full-time': 'uint64'} } 300 301## 302# @query-migrate: 303# 304# Returns information about current migration process. If migration 305# is active there will be another json-object with RAM migration 306# status and if block migration is active another one with block 307# migration status. 308# 309# Returns: @MigrationInfo 310# 311# Since: 0.14 312# 313# Examples: 314# 315# 1. Before the first migration 316# 317# -> { "execute": "query-migrate" } 318# <- { "return": {} } 319# 320# 2. Migration is done and has succeeded 321# 322# -> { "execute": "query-migrate" } 323# <- { "return": { 324# "status": "completed", 325# "total-time":12345, 326# "setup-time":12345, 327# "downtime":12345, 328# "ram":{ 329# "transferred":123, 330# "remaining":123, 331# "total":246, 332# "duplicate":123, 333# "normal":123, 334# "normal-bytes":123456, 335# "dirty-sync-count":15 336# } 337# } 338# } 339# 340# 3. Migration is done and has failed 341# 342# -> { "execute": "query-migrate" } 343# <- { "return": { "status": "failed" } } 344# 345# 4. Migration is being performed and is not a block migration: 346# 347# -> { "execute": "query-migrate" } 348# <- { 349# "return":{ 350# "status":"active", 351# "total-time":12345, 352# "setup-time":12345, 353# "expected-downtime":12345, 354# "ram":{ 355# "transferred":123, 356# "remaining":123, 357# "total":246, 358# "duplicate":123, 359# "normal":123, 360# "normal-bytes":123456, 361# "dirty-sync-count":15 362# } 363# } 364# } 365# 366# 5. Migration is being performed and is a block migration: 367# 368# -> { "execute": "query-migrate" } 369# <- { 370# "return":{ 371# "status":"active", 372# "total-time":12345, 373# "setup-time":12345, 374# "expected-downtime":12345, 375# "ram":{ 376# "total":1057024, 377# "remaining":1053304, 378# "transferred":3720, 379# "duplicate":123, 380# "normal":123, 381# "normal-bytes":123456, 382# "dirty-sync-count":15 383# }, 384# "disk":{ 385# "total":20971520, 386# "remaining":20880384, 387# "transferred":91136 388# } 389# } 390# } 391# 392# 6. Migration is being performed and XBZRLE is active: 393# 394# -> { "execute": "query-migrate" } 395# <- { 396# "return":{ 397# "status":"active", 398# "total-time":12345, 399# "setup-time":12345, 400# "expected-downtime":12345, 401# "ram":{ 402# "total":1057024, 403# "remaining":1053304, 404# "transferred":3720, 405# "duplicate":10, 406# "normal":3333, 407# "normal-bytes":3412992, 408# "dirty-sync-count":15 409# }, 410# "xbzrle-cache":{ 411# "cache-size":67108864, 412# "bytes":20971520, 413# "pages":2444343, 414# "cache-miss":2244, 415# "cache-miss-rate":0.123, 416# "encoding-rate":80.1, 417# "overflow":34434 418# } 419# } 420# } 421## 422{ 'command': 'query-migrate', 'returns': 'MigrationInfo' } 423 424## 425# @MigrationCapability: 426# 427# Migration capabilities enumeration 428# 429# @xbzrle: Migration supports xbzrle (Xor Based Zero Run Length 430# Encoding). This feature allows us to minimize migration traffic 431# for certain work loads, by sending compressed difference of the 432# pages 433# 434# @rdma-pin-all: Controls whether or not the entire VM memory 435# footprint is mlock()'d on demand or all at once. Refer to 436# docs/rdma.txt for usage. Disabled by default. (since 2.0) 437# 438# @zero-blocks: During storage migration encode blocks of zeroes 439# efficiently. This essentially saves 1MB of zeroes per block on 440# the wire. Enabling requires source and target VM to support 441# this feature. To enable it is sufficient to enable the 442# capability on the source VM. The feature is disabled by default. 443# (since 1.6) 444# 445# @compress: Use multiple compression threads to accelerate live 446# migration. This feature can help to reduce the migration 447# traffic, by sending compressed pages. Please note that if 448# compress and xbzrle are both on, compress only takes effect in 449# the ram bulk stage, after that, it will be disabled and only 450# xbzrle takes effect, this can help to minimize migration 451# traffic. The feature is disabled by default. (since 2.4) 452# 453# @events: generate events for each migration state change (since 2.4) 454# 455# @auto-converge: If enabled, QEMU will automatically throttle down 456# the guest to speed up convergence of RAM migration. (since 1.6) 457# 458# @postcopy-ram: Start executing on the migration target before all of 459# RAM has been migrated, pulling the remaining pages along as 460# needed. The capacity must have the same setting on both source 461# and target or migration will not even start. NOTE: If the 462# migration fails during postcopy the VM will fail. (since 2.6) 463# 464# @x-colo: If enabled, migration will never end, and the state of the 465# VM on the primary side will be migrated continuously to the VM 466# on secondary side, this process is called COarse-Grain LOck 467# Stepping (COLO) for Non-stop Service. (since 2.8) 468# 469# @release-ram: if enabled, qemu will free the migrated ram pages on 470# the source during postcopy-ram migration. (since 2.9) 471# 472# @block: If enabled, QEMU will also migrate the contents of all block 473# devices. Default is disabled. A possible alternative uses 474# mirror jobs to a builtin NBD server on the destination, which 475# offers more flexibility. (Since 2.10) 476# 477# @return-path: If enabled, migration will use the return path even 478# for precopy. (since 2.10) 479# 480# @pause-before-switchover: Pause outgoing migration before 481# serialising device state and before disabling block IO (since 482# 2.11) 483# 484# @multifd: Use more than one fd for migration (since 4.0) 485# 486# @dirty-bitmaps: If enabled, QEMU will migrate named dirty bitmaps. 487# (since 2.12) 488# 489# @postcopy-blocktime: Calculate downtime for postcopy live migration 490# (since 3.0) 491# 492# @late-block-activate: If enabled, the destination will not activate 493# block devices (and thus take locks) immediately at the end of 494# migration. (since 3.0) 495# 496# @x-ignore-shared: If enabled, QEMU will not migrate shared memory 497# that is accessible on the destination machine. (since 4.0) 498# 499# @validate-uuid: Send the UUID of the source to allow the destination 500# to ensure it is the same. (since 4.2) 501# 502# @background-snapshot: If enabled, the migration stream will be a 503# snapshot of the VM exactly at the point when the migration 504# procedure starts. The VM RAM is saved with running VM. (since 505# 6.0) 506# 507# @zero-copy-send: Controls behavior on sending memory pages on 508# migration. When true, enables a zero-copy mechanism for sending 509# memory pages, if host supports it. Requires that QEMU be 510# permitted to use locked memory for guest RAM pages. (since 7.1) 511# 512# @postcopy-preempt: If enabled, the migration process will allow 513# postcopy requests to preempt precopy stream, so postcopy 514# requests will be handled faster. This is a performance feature 515# and should not affect the correctness of postcopy migration. 516# (since 7.1) 517# 518# @switchover-ack: If enabled, migration will not stop the source VM 519# and complete the migration until an ACK is received from the 520# destination that it's OK to do so. Exactly when this ACK is 521# sent depends on the migrated devices that use this feature. For 522# example, a device can use it to make sure some of its data is 523# sent and loaded in the destination before doing switchover. 524# This can reduce downtime if devices that support this capability 525# are present. 'return-path' capability must be enabled to use 526# it. (since 8.1) 527# 528# @dirty-limit: If enabled, migration will throttle vCPUs as needed to 529# keep their dirty page rate within @vcpu-dirty-limit. This can 530# improve responsiveness of large guests during live migration, 531# and can result in more stable read performance. Requires KVM 532# with accelerator property "dirty-ring-size" set. (Since 8.1) 533# 534# Features: 535# 536# @deprecated: Member @block is deprecated. Use blockdev-mirror with 537# NBD instead. Member @compress is deprecated because it is 538# unreliable and untested. It is recommended to use multifd 539# migration, which offers an alternative compression 540# implementation that is reliable and tested. 541# 542# @unstable: Members @x-colo and @x-ignore-shared are experimental. 543# 544# Since: 1.2 545## 546{ 'enum': 'MigrationCapability', 547 'data': ['xbzrle', 'rdma-pin-all', 'auto-converge', 'zero-blocks', 548 { 'name': 'compress', 'features': [ 'deprecated' ] }, 549 'events', 'postcopy-ram', 550 { 'name': 'x-colo', 'features': [ 'unstable' ] }, 551 'release-ram', 552 { 'name': 'block', 'features': [ 'deprecated' ] }, 553 'return-path', 'pause-before-switchover', 'multifd', 554 'dirty-bitmaps', 'postcopy-blocktime', 'late-block-activate', 555 { 'name': 'x-ignore-shared', 'features': [ 'unstable' ] }, 556 'validate-uuid', 'background-snapshot', 557 'zero-copy-send', 'postcopy-preempt', 'switchover-ack', 558 'dirty-limit'] } 559 560## 561# @MigrationCapabilityStatus: 562# 563# Migration capability information 564# 565# @capability: capability enum 566# 567# @state: capability state bool 568# 569# Since: 1.2 570## 571{ 'struct': 'MigrationCapabilityStatus', 572 'data': { 'capability': 'MigrationCapability', 'state': 'bool' } } 573 574## 575# @migrate-set-capabilities: 576# 577# Enable/Disable the following migration capabilities (like xbzrle) 578# 579# @capabilities: json array of capability modifications to make 580# 581# Since: 1.2 582# 583# Example: 584# 585# -> { "execute": "migrate-set-capabilities" , "arguments": 586# { "capabilities": [ { "capability": "xbzrle", "state": true } ] } } 587# <- { "return": {} } 588## 589{ 'command': 'migrate-set-capabilities', 590 'data': { 'capabilities': ['MigrationCapabilityStatus'] } } 591 592## 593# @query-migrate-capabilities: 594# 595# Returns information about the current migration capabilities status 596# 597# Returns: @MigrationCapabilityStatus 598# 599# Since: 1.2 600# 601# Example: 602# 603# -> { "execute": "query-migrate-capabilities" } 604# <- { "return": [ 605# {"state": false, "capability": "xbzrle"}, 606# {"state": false, "capability": "rdma-pin-all"}, 607# {"state": false, "capability": "auto-converge"}, 608# {"state": false, "capability": "zero-blocks"}, 609# {"state": false, "capability": "compress"}, 610# {"state": true, "capability": "events"}, 611# {"state": false, "capability": "postcopy-ram"}, 612# {"state": false, "capability": "x-colo"} 613# ]} 614## 615{ 'command': 'query-migrate-capabilities', 'returns': ['MigrationCapabilityStatus']} 616 617## 618# @MultiFDCompression: 619# 620# An enumeration of multifd compression methods. 621# 622# @none: no compression. 623# 624# @zlib: use zlib compression method. 625# 626# @zstd: use zstd compression method. 627# 628# Since: 5.0 629## 630{ 'enum': 'MultiFDCompression', 631 'data': [ 'none', 'zlib', 632 { 'name': 'zstd', 'if': 'CONFIG_ZSTD' } ] } 633 634## 635# @MigMode: 636# 637# @normal: the original form of migration. (since 8.2) 638# 639# @cpr-reboot: The migrate command stops the VM and saves state to the URI. 640# After quitting qemu, the user resumes by running qemu -incoming. 641# 642# This mode allows the user to quit qemu, and restart an updated version 643# of qemu. The user may even update and reboot the OS before restarting, 644# as long as the URI persists across a reboot. 645# 646# Unlike normal mode, the use of certain local storage options does not 647# block the migration, but the user must not modify guest block devices 648# between the quit and restart. 649# 650# This mode supports vfio devices provided the user first puts the guest 651# in the suspended runstate, such as by issuing guest-suspend-ram to the 652# qemu guest agent. 653# 654# Best performance is achieved when the memory backend is shared and the 655# @x-ignore-shared migration capability is set, but this is not required. 656# Further, if the user reboots before restarting such a configuration, the 657# shared backend must be be non-volatile across reboot, such as by backing 658# it with a dax device. 659# 660# (since 8.2) 661## 662{ 'enum': 'MigMode', 663 'data': [ 'normal', 'cpr-reboot' ] } 664 665## 666# @BitmapMigrationBitmapAliasTransform: 667# 668# @persistent: If present, the bitmap will be made persistent or 669# transient depending on this parameter. 670# 671# Since: 6.0 672## 673{ 'struct': 'BitmapMigrationBitmapAliasTransform', 674 'data': { 675 '*persistent': 'bool' 676 } } 677 678## 679# @BitmapMigrationBitmapAlias: 680# 681# @name: The name of the bitmap. 682# 683# @alias: An alias name for migration (for example the bitmap name on 684# the opposite site). 685# 686# @transform: Allows the modification of the migrated bitmap. (since 687# 6.0) 688# 689# Since: 5.2 690## 691{ 'struct': 'BitmapMigrationBitmapAlias', 692 'data': { 693 'name': 'str', 694 'alias': 'str', 695 '*transform': 'BitmapMigrationBitmapAliasTransform' 696 } } 697 698## 699# @BitmapMigrationNodeAlias: 700# 701# Maps a block node name and the bitmaps it has to aliases for dirty 702# bitmap migration. 703# 704# @node-name: A block node name. 705# 706# @alias: An alias block node name for migration (for example the node 707# name on the opposite site). 708# 709# @bitmaps: Mappings for the bitmaps on this node. 710# 711# Since: 5.2 712## 713{ 'struct': 'BitmapMigrationNodeAlias', 714 'data': { 715 'node-name': 'str', 716 'alias': 'str', 717 'bitmaps': [ 'BitmapMigrationBitmapAlias' ] 718 } } 719 720## 721# @MigrationParameter: 722# 723# Migration parameters enumeration 724# 725# @announce-initial: Initial delay (in milliseconds) before sending 726# the first announce (Since 4.0) 727# 728# @announce-max: Maximum delay (in milliseconds) between packets in 729# the announcement (Since 4.0) 730# 731# @announce-rounds: Number of self-announce packets sent after 732# migration (Since 4.0) 733# 734# @announce-step: Increase in delay (in milliseconds) between 735# subsequent packets in the announcement (Since 4.0) 736# 737# @compress-level: Set the compression level to be used in live 738# migration, the compression level is an integer between 0 and 9, 739# where 0 means no compression, 1 means the best compression 740# speed, and 9 means best compression ratio which will consume 741# more CPU. 742# 743# @compress-threads: Set compression thread count to be used in live 744# migration, the compression thread count is an integer between 1 745# and 255. 746# 747# @compress-wait-thread: Controls behavior when all compression 748# threads are currently busy. If true (default), wait for a free 749# compression thread to become available; otherwise, send the page 750# uncompressed. (Since 3.1) 751# 752# @decompress-threads: Set decompression thread count to be used in 753# live migration, the decompression thread count is an integer 754# between 1 and 255. Usually, decompression is at least 4 times as 755# fast as compression, so set the decompress-threads to the number 756# about 1/4 of compress-threads is adequate. 757# 758# @throttle-trigger-threshold: The ratio of bytes_dirty_period and 759# bytes_xfer_period to trigger throttling. It is expressed as 760# percentage. The default value is 50. (Since 5.0) 761# 762# @cpu-throttle-initial: Initial percentage of time guest cpus are 763# throttled when migration auto-converge is activated. The 764# default value is 20. (Since 2.7) 765# 766# @cpu-throttle-increment: throttle percentage increase each time 767# auto-converge detects that migration is not making progress. 768# The default value is 10. (Since 2.7) 769# 770# @cpu-throttle-tailslow: Make CPU throttling slower at tail stage At 771# the tail stage of throttling, the Guest is very sensitive to CPU 772# percentage while the @cpu-throttle -increment is excessive 773# usually at tail stage. If this parameter is true, we will 774# compute the ideal CPU percentage used by the Guest, which may 775# exactly make the dirty rate match the dirty rate threshold. 776# Then we will choose a smaller throttle increment between the one 777# specified by @cpu-throttle-increment and the one generated by 778# ideal CPU percentage. Therefore, it is compatible to 779# traditional throttling, meanwhile the throttle increment won't 780# be excessive at tail stage. The default value is false. (Since 781# 5.1) 782# 783# @tls-creds: ID of the 'tls-creds' object that provides credentials 784# for establishing a TLS connection over the migration data 785# channel. On the outgoing side of the migration, the credentials 786# must be for a 'client' endpoint, while for the incoming side the 787# credentials must be for a 'server' endpoint. Setting this will 788# enable TLS for all migrations. The default is unset, resulting 789# in unsecured migration at the QEMU level. (Since 2.7) 790# 791# @tls-hostname: hostname of the target host for the migration. This 792# is required when using x509 based TLS credentials and the 793# migration URI does not already include a hostname. For example 794# if using fd: or exec: based migration, the hostname must be 795# provided so that the server's x509 certificate identity can be 796# validated. (Since 2.7) 797# 798# @tls-authz: ID of the 'authz' object subclass that provides access 799# control checking of the TLS x509 certificate distinguished name. 800# This object is only resolved at time of use, so can be deleted 801# and recreated on the fly while the migration server is active. 802# If missing, it will default to denying access (Since 4.0) 803# 804# @max-bandwidth: to set maximum speed for migration. maximum speed 805# in bytes per second. (Since 2.8) 806# 807# @avail-switchover-bandwidth: to set the available bandwidth that 808# migration can use during switchover phase. NOTE! This does not 809# limit the bandwidth during switchover, but only for calculations when 810# making decisions to switchover. By default, this value is zero, 811# which means QEMU will estimate the bandwidth automatically. This can 812# be set when the estimated value is not accurate, while the user is 813# able to guarantee such bandwidth is available when switching over. 814# When specified correctly, this can make the switchover decision much 815# more accurate. (Since 8.2) 816# 817# @downtime-limit: set maximum tolerated downtime for migration. 818# maximum downtime in milliseconds (Since 2.8) 819# 820# @x-checkpoint-delay: The delay time (in ms) between two COLO 821# checkpoints in periodic mode. (Since 2.8) 822# 823# @block-incremental: Affects how much storage is migrated when the 824# block migration capability is enabled. When false, the entire 825# storage backing chain is migrated into a flattened image at the 826# destination; when true, only the active qcow2 layer is migrated 827# and the destination must already have access to the same backing 828# chain as was used on the source. (since 2.10) 829# 830# @multifd-channels: Number of channels used to migrate data in 831# parallel. This is the same number that the number of sockets 832# used for migration. The default value is 2 (since 4.0) 833# 834# @xbzrle-cache-size: cache size to be used by XBZRLE migration. It 835# needs to be a multiple of the target page size and a power of 2 836# (Since 2.11) 837# 838# @max-postcopy-bandwidth: Background transfer bandwidth during 839# postcopy. Defaults to 0 (unlimited). In bytes per second. 840# (Since 3.0) 841# 842# @max-cpu-throttle: maximum cpu throttle percentage. Defaults to 99. 843# (Since 3.1) 844# 845# @multifd-compression: Which compression method to use. Defaults to 846# none. (Since 5.0) 847# 848# @multifd-zlib-level: Set the compression level to be used in live 849# migration, the compression level is an integer between 0 and 9, 850# where 0 means no compression, 1 means the best compression 851# speed, and 9 means best compression ratio which will consume 852# more CPU. Defaults to 1. (Since 5.0) 853# 854# @multifd-zstd-level: Set the compression level to be used in live 855# migration, the compression level is an integer between 0 and 20, 856# where 0 means no compression, 1 means the best compression 857# speed, and 20 means best compression ratio which will consume 858# more CPU. Defaults to 1. (Since 5.0) 859# 860# @block-bitmap-mapping: Maps block nodes and bitmaps on them to 861# aliases for the purpose of dirty bitmap migration. Such aliases 862# may for example be the corresponding names on the opposite site. 863# The mapping must be one-to-one, but not necessarily complete: On 864# the source, unmapped bitmaps and all bitmaps on unmapped nodes 865# will be ignored. On the destination, encountering an unmapped 866# alias in the incoming migration stream will result in a report, 867# and all further bitmap migration data will then be discarded. 868# Note that the destination does not know about bitmaps it does 869# not receive, so there is no limitation or requirement regarding 870# the number of bitmaps received, or how they are named, or on 871# which nodes they are placed. By default (when this parameter 872# has never been set), bitmap names are mapped to themselves. 873# Nodes are mapped to their block device name if there is one, and 874# to their node name otherwise. (Since 5.2) 875# 876# @x-vcpu-dirty-limit-period: Periodic time (in milliseconds) of dirty 877# limit during live migration. Should be in the range 1 to 1000ms. 878# Defaults to 1000ms. (Since 8.1) 879# 880# @vcpu-dirty-limit: Dirtyrate limit (MB/s) during live migration. 881# Defaults to 1. (Since 8.1) 882# 883# @mode: Migration mode. See description in @MigMode. Default is 'normal'. 884# (Since 8.2) 885# 886# Features: 887# 888# @deprecated: Member @block-incremental is deprecated. Use 889# blockdev-mirror with NBD instead. Members @compress-level, 890# @compress-threads, @decompress-threads and @compress-wait-thread 891# are deprecated because @compression is deprecated. 892# 893# @unstable: Members @x-checkpoint-delay and @x-vcpu-dirty-limit-period 894# are experimental. 895# 896# Since: 2.4 897## 898{ 'enum': 'MigrationParameter', 899 'data': ['announce-initial', 'announce-max', 900 'announce-rounds', 'announce-step', 901 { 'name': 'compress-level', 'features': [ 'deprecated' ] }, 902 { 'name': 'compress-threads', 'features': [ 'deprecated' ] }, 903 { 'name': 'decompress-threads', 'features': [ 'deprecated' ] }, 904 { 'name': 'compress-wait-thread', 'features': [ 'deprecated' ] }, 905 'throttle-trigger-threshold', 906 'cpu-throttle-initial', 'cpu-throttle-increment', 907 'cpu-throttle-tailslow', 908 'tls-creds', 'tls-hostname', 'tls-authz', 'max-bandwidth', 909 'avail-switchover-bandwidth', 'downtime-limit', 910 { 'name': 'x-checkpoint-delay', 'features': [ 'unstable' ] }, 911 { 'name': 'block-incremental', 'features': [ 'deprecated' ] }, 912 'multifd-channels', 913 'xbzrle-cache-size', 'max-postcopy-bandwidth', 914 'max-cpu-throttle', 'multifd-compression', 915 'multifd-zlib-level', 'multifd-zstd-level', 916 'block-bitmap-mapping', 917 { 'name': 'x-vcpu-dirty-limit-period', 'features': ['unstable'] }, 918 'vcpu-dirty-limit', 919 'mode'] } 920 921## 922# @MigrateSetParameters: 923# 924# @announce-initial: Initial delay (in milliseconds) before sending 925# the first announce (Since 4.0) 926# 927# @announce-max: Maximum delay (in milliseconds) between packets in 928# the announcement (Since 4.0) 929# 930# @announce-rounds: Number of self-announce packets sent after 931# migration (Since 4.0) 932# 933# @announce-step: Increase in delay (in milliseconds) between 934# subsequent packets in the announcement (Since 4.0) 935# 936# @compress-level: compression level 937# 938# @compress-threads: compression thread count 939# 940# @compress-wait-thread: Controls behavior when all compression 941# threads are currently busy. If true (default), wait for a free 942# compression thread to become available; otherwise, send the page 943# uncompressed. (Since 3.1) 944# 945# @decompress-threads: decompression thread count 946# 947# @throttle-trigger-threshold: The ratio of bytes_dirty_period and 948# bytes_xfer_period to trigger throttling. It is expressed as 949# percentage. The default value is 50. (Since 5.0) 950# 951# @cpu-throttle-initial: Initial percentage of time guest cpus are 952# throttled when migration auto-converge is activated. The 953# default value is 20. (Since 2.7) 954# 955# @cpu-throttle-increment: throttle percentage increase each time 956# auto-converge detects that migration is not making progress. 957# The default value is 10. (Since 2.7) 958# 959# @cpu-throttle-tailslow: Make CPU throttling slower at tail stage At 960# the tail stage of throttling, the Guest is very sensitive to CPU 961# percentage while the @cpu-throttle -increment is excessive 962# usually at tail stage. If this parameter is true, we will 963# compute the ideal CPU percentage used by the Guest, which may 964# exactly make the dirty rate match the dirty rate threshold. 965# Then we will choose a smaller throttle increment between the one 966# specified by @cpu-throttle-increment and the one generated by 967# ideal CPU percentage. Therefore, it is compatible to 968# traditional throttling, meanwhile the throttle increment won't 969# be excessive at tail stage. The default value is false. (Since 970# 5.1) 971# 972# @tls-creds: ID of the 'tls-creds' object that provides credentials 973# for establishing a TLS connection over the migration data 974# channel. On the outgoing side of the migration, the credentials 975# must be for a 'client' endpoint, while for the incoming side the 976# credentials must be for a 'server' endpoint. Setting this to a 977# non-empty string enables TLS for all migrations. An empty 978# string means that QEMU will use plain text mode for migration, 979# rather than TLS (Since 2.9) Previously (since 2.7), this was 980# reported by omitting tls-creds instead. 981# 982# @tls-hostname: hostname of the target host for the migration. This 983# is required when using x509 based TLS credentials and the 984# migration URI does not already include a hostname. For example 985# if using fd: or exec: based migration, the hostname must be 986# provided so that the server's x509 certificate identity can be 987# validated. (Since 2.7) An empty string means that QEMU will use 988# the hostname associated with the migration URI, if any. (Since 989# 2.9) Previously (since 2.7), this was reported by omitting 990# tls-hostname instead. 991# 992# @tls-authz: ID of the 'authz' object subclass that provides access 993# control checking of the TLS x509 certificate distinguished name. 994# (Since 4.0) 995# 996# @max-bandwidth: to set maximum speed for migration. maximum speed 997# in bytes per second. (Since 2.8) 998# 999# @avail-switchover-bandwidth: to set the available bandwidth that 1000# migration can use during switchover phase. NOTE! This does not 1001# limit the bandwidth during switchover, but only for calculations when 1002# making decisions to switchover. By default, this value is zero, 1003# which means QEMU will estimate the bandwidth automatically. This can 1004# be set when the estimated value is not accurate, while the user is 1005# able to guarantee such bandwidth is available when switching over. 1006# When specified correctly, this can make the switchover decision much 1007# more accurate. (Since 8.2) 1008# 1009# @downtime-limit: set maximum tolerated downtime for migration. 1010# maximum downtime in milliseconds (Since 2.8) 1011# 1012# @x-checkpoint-delay: the delay time between two COLO checkpoints. 1013# (Since 2.8) 1014# 1015# @block-incremental: Affects how much storage is migrated when the 1016# block migration capability is enabled. When false, the entire 1017# storage backing chain is migrated into a flattened image at the 1018# destination; when true, only the active qcow2 layer is migrated 1019# and the destination must already have access to the same backing 1020# chain as was used on the source. (since 2.10) 1021# 1022# @multifd-channels: Number of channels used to migrate data in 1023# parallel. This is the same number that the number of sockets 1024# used for migration. The default value is 2 (since 4.0) 1025# 1026# @xbzrle-cache-size: cache size to be used by XBZRLE migration. It 1027# needs to be a multiple of the target page size and a power of 2 1028# (Since 2.11) 1029# 1030# @max-postcopy-bandwidth: Background transfer bandwidth during 1031# postcopy. Defaults to 0 (unlimited). In bytes per second. 1032# (Since 3.0) 1033# 1034# @max-cpu-throttle: maximum cpu throttle percentage. The default 1035# value is 99. (Since 3.1) 1036# 1037# @multifd-compression: Which compression method to use. Defaults to 1038# none. (Since 5.0) 1039# 1040# @multifd-zlib-level: Set the compression level to be used in live 1041# migration, the compression level is an integer between 0 and 9, 1042# where 0 means no compression, 1 means the best compression 1043# speed, and 9 means best compression ratio which will consume 1044# more CPU. Defaults to 1. (Since 5.0) 1045# 1046# @multifd-zstd-level: Set the compression level to be used in live 1047# migration, the compression level is an integer between 0 and 20, 1048# where 0 means no compression, 1 means the best compression 1049# speed, and 20 means best compression ratio which will consume 1050# more CPU. Defaults to 1. (Since 5.0) 1051# 1052# @block-bitmap-mapping: Maps block nodes and bitmaps on them to 1053# aliases for the purpose of dirty bitmap migration. Such aliases 1054# may for example be the corresponding names on the opposite site. 1055# The mapping must be one-to-one, but not necessarily complete: On 1056# the source, unmapped bitmaps and all bitmaps on unmapped nodes 1057# will be ignored. On the destination, encountering an unmapped 1058# alias in the incoming migration stream will result in a report, 1059# and all further bitmap migration data will then be discarded. 1060# Note that the destination does not know about bitmaps it does 1061# not receive, so there is no limitation or requirement regarding 1062# the number of bitmaps received, or how they are named, or on 1063# which nodes they are placed. By default (when this parameter 1064# has never been set), bitmap names are mapped to themselves. 1065# Nodes are mapped to their block device name if there is one, and 1066# to their node name otherwise. (Since 5.2) 1067# 1068# @x-vcpu-dirty-limit-period: Periodic time (in milliseconds) of dirty 1069# limit during live migration. Should be in the range 1 to 1000ms. 1070# Defaults to 1000ms. (Since 8.1) 1071# 1072# @vcpu-dirty-limit: Dirtyrate limit (MB/s) during live migration. 1073# Defaults to 1. (Since 8.1) 1074# 1075# @mode: Migration mode. See description in @MigMode. Default is 'normal'. 1076# (Since 8.2) 1077# 1078# Features: 1079# 1080# @deprecated: Member @block-incremental is deprecated. Use 1081# blockdev-mirror with NBD instead. Members @compress-level, 1082# @compress-threads, @decompress-threads and @compress-wait-thread 1083# are deprecated because @compression is deprecated. 1084# 1085# @unstable: Members @x-checkpoint-delay and @x-vcpu-dirty-limit-period 1086# are experimental. 1087# 1088# TODO: either fuse back into MigrationParameters, or make 1089# MigrationParameters members mandatory 1090# 1091# Since: 2.4 1092## 1093{ 'struct': 'MigrateSetParameters', 1094 'data': { '*announce-initial': 'size', 1095 '*announce-max': 'size', 1096 '*announce-rounds': 'size', 1097 '*announce-step': 'size', 1098 '*compress-level': { 'type': 'uint8', 1099 'features': [ 'deprecated' ] }, 1100 '*compress-threads': { 'type': 'uint8', 1101 'features': [ 'deprecated' ] }, 1102 '*compress-wait-thread': { 'type': 'bool', 1103 'features': [ 'deprecated' ] }, 1104 '*decompress-threads': { 'type': 'uint8', 1105 'features': [ 'deprecated' ] }, 1106 '*throttle-trigger-threshold': 'uint8', 1107 '*cpu-throttle-initial': 'uint8', 1108 '*cpu-throttle-increment': 'uint8', 1109 '*cpu-throttle-tailslow': 'bool', 1110 '*tls-creds': 'StrOrNull', 1111 '*tls-hostname': 'StrOrNull', 1112 '*tls-authz': 'StrOrNull', 1113 '*max-bandwidth': 'size', 1114 '*avail-switchover-bandwidth': 'size', 1115 '*downtime-limit': 'uint64', 1116 '*x-checkpoint-delay': { 'type': 'uint32', 1117 'features': [ 'unstable' ] }, 1118 '*block-incremental': { 'type': 'bool', 1119 'features': [ 'deprecated' ] }, 1120 '*multifd-channels': 'uint8', 1121 '*xbzrle-cache-size': 'size', 1122 '*max-postcopy-bandwidth': 'size', 1123 '*max-cpu-throttle': 'uint8', 1124 '*multifd-compression': 'MultiFDCompression', 1125 '*multifd-zlib-level': 'uint8', 1126 '*multifd-zstd-level': 'uint8', 1127 '*block-bitmap-mapping': [ 'BitmapMigrationNodeAlias' ], 1128 '*x-vcpu-dirty-limit-period': { 'type': 'uint64', 1129 'features': [ 'unstable' ] }, 1130 '*vcpu-dirty-limit': 'uint64', 1131 '*mode': 'MigMode'} } 1132 1133## 1134# @migrate-set-parameters: 1135# 1136# Set various migration parameters. 1137# 1138# Since: 2.4 1139# 1140# Example: 1141# 1142# -> { "execute": "migrate-set-parameters" , 1143# "arguments": { "multifd-channels": 5 } } 1144# <- { "return": {} } 1145## 1146{ 'command': 'migrate-set-parameters', 'boxed': true, 1147 'data': 'MigrateSetParameters' } 1148 1149## 1150# @MigrationParameters: 1151# 1152# The optional members aren't actually optional. 1153# 1154# @announce-initial: Initial delay (in milliseconds) before sending 1155# the first announce (Since 4.0) 1156# 1157# @announce-max: Maximum delay (in milliseconds) between packets in 1158# the announcement (Since 4.0) 1159# 1160# @announce-rounds: Number of self-announce packets sent after 1161# migration (Since 4.0) 1162# 1163# @announce-step: Increase in delay (in milliseconds) between 1164# subsequent packets in the announcement (Since 4.0) 1165# 1166# @compress-level: compression level 1167# 1168# @compress-threads: compression thread count 1169# 1170# @compress-wait-thread: Controls behavior when all compression 1171# threads are currently busy. If true (default), wait for a free 1172# compression thread to become available; otherwise, send the page 1173# uncompressed. (Since 3.1) 1174# 1175# @decompress-threads: decompression thread count 1176# 1177# @throttle-trigger-threshold: The ratio of bytes_dirty_period and 1178# bytes_xfer_period to trigger throttling. It is expressed as 1179# percentage. The default value is 50. (Since 5.0) 1180# 1181# @cpu-throttle-initial: Initial percentage of time guest cpus are 1182# throttled when migration auto-converge is activated. (Since 1183# 2.7) 1184# 1185# @cpu-throttle-increment: throttle percentage increase each time 1186# auto-converge detects that migration is not making progress. 1187# (Since 2.7) 1188# 1189# @cpu-throttle-tailslow: Make CPU throttling slower at tail stage At 1190# the tail stage of throttling, the Guest is very sensitive to CPU 1191# percentage while the @cpu-throttle -increment is excessive 1192# usually at tail stage. If this parameter is true, we will 1193# compute the ideal CPU percentage used by the Guest, which may 1194# exactly make the dirty rate match the dirty rate threshold. 1195# Then we will choose a smaller throttle increment between the one 1196# specified by @cpu-throttle-increment and the one generated by 1197# ideal CPU percentage. Therefore, it is compatible to 1198# traditional throttling, meanwhile the throttle increment won't 1199# be excessive at tail stage. The default value is false. (Since 1200# 5.1) 1201# 1202# @tls-creds: ID of the 'tls-creds' object that provides credentials 1203# for establishing a TLS connection over the migration data 1204# channel. On the outgoing side of the migration, the credentials 1205# must be for a 'client' endpoint, while for the incoming side the 1206# credentials must be for a 'server' endpoint. An empty string 1207# means that QEMU will use plain text mode for migration, rather 1208# than TLS (Since 2.7) Note: 2.8 reports this by omitting 1209# tls-creds instead. 1210# 1211# @tls-hostname: hostname of the target host for the migration. This 1212# is required when using x509 based TLS credentials and the 1213# migration URI does not already include a hostname. For example 1214# if using fd: or exec: based migration, the hostname must be 1215# provided so that the server's x509 certificate identity can be 1216# validated. (Since 2.7) An empty string means that QEMU will use 1217# the hostname associated with the migration URI, if any. (Since 1218# 2.9) Note: 2.8 reports this by omitting tls-hostname instead. 1219# 1220# @tls-authz: ID of the 'authz' object subclass that provides access 1221# control checking of the TLS x509 certificate distinguished name. 1222# (Since 4.0) 1223# 1224# @max-bandwidth: to set maximum speed for migration. maximum speed 1225# in bytes per second. (Since 2.8) 1226# 1227# @avail-switchover-bandwidth: to set the available bandwidth that 1228# migration can use during switchover phase. NOTE! This does not 1229# limit the bandwidth during switchover, but only for calculations when 1230# making decisions to switchover. By default, this value is zero, 1231# which means QEMU will estimate the bandwidth automatically. This can 1232# be set when the estimated value is not accurate, while the user is 1233# able to guarantee such bandwidth is available when switching over. 1234# When specified correctly, this can make the switchover decision much 1235# more accurate. (Since 8.2) 1236# 1237# @downtime-limit: set maximum tolerated downtime for migration. 1238# maximum downtime in milliseconds (Since 2.8) 1239# 1240# @x-checkpoint-delay: the delay time between two COLO checkpoints. 1241# (Since 2.8) 1242# 1243# @block-incremental: Affects how much storage is migrated when the 1244# block migration capability is enabled. When false, the entire 1245# storage backing chain is migrated into a flattened image at the 1246# destination; when true, only the active qcow2 layer is migrated 1247# and the destination must already have access to the same backing 1248# chain as was used on the source. (since 2.10) 1249# 1250# @multifd-channels: Number of channels used to migrate data in 1251# parallel. This is the same number that the number of sockets 1252# used for migration. The default value is 2 (since 4.0) 1253# 1254# @xbzrle-cache-size: cache size to be used by XBZRLE migration. It 1255# needs to be a multiple of the target page size and a power of 2 1256# (Since 2.11) 1257# 1258# @max-postcopy-bandwidth: Background transfer bandwidth during 1259# postcopy. Defaults to 0 (unlimited). In bytes per second. 1260# (Since 3.0) 1261# 1262# @max-cpu-throttle: maximum cpu throttle percentage. Defaults to 99. 1263# (Since 3.1) 1264# 1265# @multifd-compression: Which compression method to use. Defaults to 1266# none. (Since 5.0) 1267# 1268# @multifd-zlib-level: Set the compression level to be used in live 1269# migration, the compression level is an integer between 0 and 9, 1270# where 0 means no compression, 1 means the best compression 1271# speed, and 9 means best compression ratio which will consume 1272# more CPU. Defaults to 1. (Since 5.0) 1273# 1274# @multifd-zstd-level: Set the compression level to be used in live 1275# migration, the compression level is an integer between 0 and 20, 1276# where 0 means no compression, 1 means the best compression 1277# speed, and 20 means best compression ratio which will consume 1278# more CPU. Defaults to 1. (Since 5.0) 1279# 1280# @block-bitmap-mapping: Maps block nodes and bitmaps on them to 1281# aliases for the purpose of dirty bitmap migration. Such aliases 1282# may for example be the corresponding names on the opposite site. 1283# The mapping must be one-to-one, but not necessarily complete: On 1284# the source, unmapped bitmaps and all bitmaps on unmapped nodes 1285# will be ignored. On the destination, encountering an unmapped 1286# alias in the incoming migration stream will result in a report, 1287# and all further bitmap migration data will then be discarded. 1288# Note that the destination does not know about bitmaps it does 1289# not receive, so there is no limitation or requirement regarding 1290# the number of bitmaps received, or how they are named, or on 1291# which nodes they are placed. By default (when this parameter 1292# has never been set), bitmap names are mapped to themselves. 1293# Nodes are mapped to their block device name if there is one, and 1294# to their node name otherwise. (Since 5.2) 1295# 1296# @x-vcpu-dirty-limit-period: Periodic time (in milliseconds) of dirty 1297# limit during live migration. Should be in the range 1 to 1000ms. 1298# Defaults to 1000ms. (Since 8.1) 1299# 1300# @vcpu-dirty-limit: Dirtyrate limit (MB/s) during live migration. 1301# Defaults to 1. (Since 8.1) 1302# 1303# @mode: Migration mode. See description in @MigMode. Default is 'normal'. 1304# (Since 8.2) 1305# 1306# Features: 1307# 1308# @deprecated: Member @block-incremental is deprecated. Use 1309# blockdev-mirror with NBD instead. Members @compress-level, 1310# @compress-threads, @decompress-threads and @compress-wait-thread 1311# are deprecated because @compression is deprecated. 1312# 1313# @unstable: Members @x-checkpoint-delay and @x-vcpu-dirty-limit-period 1314# are experimental. 1315# 1316# Since: 2.4 1317## 1318{ 'struct': 'MigrationParameters', 1319 'data': { '*announce-initial': 'size', 1320 '*announce-max': 'size', 1321 '*announce-rounds': 'size', 1322 '*announce-step': 'size', 1323 '*compress-level': { 'type': 'uint8', 1324 'features': [ 'deprecated' ] }, 1325 '*compress-threads': { 'type': 'uint8', 1326 'features': [ 'deprecated' ] }, 1327 '*compress-wait-thread': { 'type': 'bool', 1328 'features': [ 'deprecated' ] }, 1329 '*decompress-threads': { 'type': 'uint8', 1330 'features': [ 'deprecated' ] }, 1331 '*throttle-trigger-threshold': 'uint8', 1332 '*cpu-throttle-initial': 'uint8', 1333 '*cpu-throttle-increment': 'uint8', 1334 '*cpu-throttle-tailslow': 'bool', 1335 '*tls-creds': 'str', 1336 '*tls-hostname': 'str', 1337 '*tls-authz': 'str', 1338 '*max-bandwidth': 'size', 1339 '*avail-switchover-bandwidth': 'size', 1340 '*downtime-limit': 'uint64', 1341 '*x-checkpoint-delay': { 'type': 'uint32', 1342 'features': [ 'unstable' ] }, 1343 '*block-incremental': { 'type': 'bool', 1344 'features': [ 'deprecated' ] }, 1345 '*multifd-channels': 'uint8', 1346 '*xbzrle-cache-size': 'size', 1347 '*max-postcopy-bandwidth': 'size', 1348 '*max-cpu-throttle': 'uint8', 1349 '*multifd-compression': 'MultiFDCompression', 1350 '*multifd-zlib-level': 'uint8', 1351 '*multifd-zstd-level': 'uint8', 1352 '*block-bitmap-mapping': [ 'BitmapMigrationNodeAlias' ], 1353 '*x-vcpu-dirty-limit-period': { 'type': 'uint64', 1354 'features': [ 'unstable' ] }, 1355 '*vcpu-dirty-limit': 'uint64', 1356 '*mode': 'MigMode'} } 1357 1358## 1359# @query-migrate-parameters: 1360# 1361# Returns information about the current migration parameters 1362# 1363# Returns: @MigrationParameters 1364# 1365# Since: 2.4 1366# 1367# Example: 1368# 1369# -> { "execute": "query-migrate-parameters" } 1370# <- { "return": { 1371# "multifd-channels": 2, 1372# "cpu-throttle-increment": 10, 1373# "cpu-throttle-initial": 20, 1374# "max-bandwidth": 33554432, 1375# "downtime-limit": 300 1376# } 1377# } 1378## 1379{ 'command': 'query-migrate-parameters', 1380 'returns': 'MigrationParameters' } 1381 1382## 1383# @migrate-start-postcopy: 1384# 1385# Followup to a migration command to switch the migration to postcopy 1386# mode. The postcopy-ram capability must be set on both source and 1387# destination before the original migration command. 1388# 1389# Since: 2.5 1390# 1391# Example: 1392# 1393# -> { "execute": "migrate-start-postcopy" } 1394# <- { "return": {} } 1395## 1396{ 'command': 'migrate-start-postcopy' } 1397 1398## 1399# @MIGRATION: 1400# 1401# Emitted when a migration event happens 1402# 1403# @status: @MigrationStatus describing the current migration status. 1404# 1405# Since: 2.4 1406# 1407# Example: 1408# 1409# <- {"timestamp": {"seconds": 1432121972, "microseconds": 744001}, 1410# "event": "MIGRATION", 1411# "data": {"status": "completed"} } 1412## 1413{ 'event': 'MIGRATION', 1414 'data': {'status': 'MigrationStatus'}} 1415 1416## 1417# @MIGRATION_PASS: 1418# 1419# Emitted from the source side of a migration at the start of each 1420# pass (when it syncs the dirty bitmap) 1421# 1422# @pass: An incrementing count (starting at 1 on the first pass) 1423# 1424# Since: 2.6 1425# 1426# Example: 1427# 1428# <- { "timestamp": {"seconds": 1449669631, "microseconds": 239225}, 1429# "event": "MIGRATION_PASS", "data": {"pass": 2} } 1430## 1431{ 'event': 'MIGRATION_PASS', 1432 'data': { 'pass': 'int' } } 1433 1434## 1435# @COLOMessage: 1436# 1437# The message transmission between Primary side and Secondary side. 1438# 1439# @checkpoint-ready: Secondary VM (SVM) is ready for checkpointing 1440# 1441# @checkpoint-request: Primary VM (PVM) tells SVM to prepare for 1442# checkpointing 1443# 1444# @checkpoint-reply: SVM gets PVM's checkpoint request 1445# 1446# @vmstate-send: VM's state will be sent by PVM. 1447# 1448# @vmstate-size: The total size of VMstate. 1449# 1450# @vmstate-received: VM's state has been received by SVM. 1451# 1452# @vmstate-loaded: VM's state has been loaded by SVM. 1453# 1454# Since: 2.8 1455## 1456{ 'enum': 'COLOMessage', 1457 'data': [ 'checkpoint-ready', 'checkpoint-request', 'checkpoint-reply', 1458 'vmstate-send', 'vmstate-size', 'vmstate-received', 1459 'vmstate-loaded' ] } 1460 1461## 1462# @COLOMode: 1463# 1464# The COLO current mode. 1465# 1466# @none: COLO is disabled. 1467# 1468# @primary: COLO node in primary side. 1469# 1470# @secondary: COLO node in slave side. 1471# 1472# Since: 2.8 1473## 1474{ 'enum': 'COLOMode', 1475 'data': [ 'none', 'primary', 'secondary'] } 1476 1477## 1478# @FailoverStatus: 1479# 1480# An enumeration of COLO failover status 1481# 1482# @none: no failover has ever happened 1483# 1484# @require: got failover requirement but not handled 1485# 1486# @active: in the process of doing failover 1487# 1488# @completed: finish the process of failover 1489# 1490# @relaunch: restart the failover process, from 'none' -> 'completed' 1491# (Since 2.9) 1492# 1493# Since: 2.8 1494## 1495{ 'enum': 'FailoverStatus', 1496 'data': [ 'none', 'require', 'active', 'completed', 'relaunch' ] } 1497 1498## 1499# @COLO_EXIT: 1500# 1501# Emitted when VM finishes COLO mode due to some errors happening or 1502# at the request of users. 1503# 1504# @mode: report COLO mode when COLO exited. 1505# 1506# @reason: describes the reason for the COLO exit. 1507# 1508# Since: 3.1 1509# 1510# Example: 1511# 1512# <- { "timestamp": {"seconds": 2032141960, "microseconds": 417172}, 1513# "event": "COLO_EXIT", "data": {"mode": "primary", "reason": "request" } } 1514## 1515{ 'event': 'COLO_EXIT', 1516 'data': {'mode': 'COLOMode', 'reason': 'COLOExitReason' } } 1517 1518## 1519# @COLOExitReason: 1520# 1521# The reason for a COLO exit. 1522# 1523# @none: failover has never happened. This state does not occur in 1524# the COLO_EXIT event, and is only visible in the result of 1525# query-colo-status. 1526# 1527# @request: COLO exit is due to an external request. 1528# 1529# @error: COLO exit is due to an internal error. 1530# 1531# @processing: COLO is currently handling a failover (since 4.0). 1532# 1533# Since: 3.1 1534## 1535{ 'enum': 'COLOExitReason', 1536 'data': [ 'none', 'request', 'error' , 'processing' ] } 1537 1538## 1539# @x-colo-lost-heartbeat: 1540# 1541# Tell qemu that heartbeat is lost, request it to do takeover 1542# procedures. If this command is sent to the PVM, the Primary side 1543# will exit COLO mode. If sent to the Secondary, the Secondary side 1544# will run failover work, then takes over server operation to become 1545# the service VM. 1546# 1547# Features: 1548# 1549# @unstable: This command is experimental. 1550# 1551# Since: 2.8 1552# 1553# Example: 1554# 1555# -> { "execute": "x-colo-lost-heartbeat" } 1556# <- { "return": {} } 1557## 1558{ 'command': 'x-colo-lost-heartbeat', 1559 'features': [ 'unstable' ], 1560 'if': 'CONFIG_REPLICATION' } 1561 1562## 1563# @migrate_cancel: 1564# 1565# Cancel the current executing migration process. 1566# 1567# Returns: nothing on success 1568# 1569# Notes: This command succeeds even if there is no migration process 1570# running. 1571# 1572# Since: 0.14 1573# 1574# Example: 1575# 1576# -> { "execute": "migrate_cancel" } 1577# <- { "return": {} } 1578## 1579{ 'command': 'migrate_cancel' } 1580 1581## 1582# @migrate-continue: 1583# 1584# Continue migration when it's in a paused state. 1585# 1586# @state: The state the migration is currently expected to be in 1587# 1588# Returns: nothing on success 1589# 1590# Since: 2.11 1591# 1592# Example: 1593# 1594# -> { "execute": "migrate-continue" , "arguments": 1595# { "state": "pre-switchover" } } 1596# <- { "return": {} } 1597## 1598{ 'command': 'migrate-continue', 'data': {'state': 'MigrationStatus'} } 1599 1600## 1601# @MigrationAddressType: 1602# 1603# The migration stream transport mechanisms. 1604# 1605# @socket: Migrate via socket. 1606# 1607# @exec: Direct the migration stream to another process. 1608# 1609# @rdma: Migrate via RDMA. 1610# 1611# @file: Direct the migration stream to a file. 1612# 1613# Since: 8.2 1614## 1615{ 'enum': 'MigrationAddressType', 1616 'data': [ 'socket', 'exec', 'rdma', 'file' ] } 1617 1618## 1619# @FileMigrationArgs: 1620# 1621# @filename: The file to receive the migration stream 1622# 1623# @offset: The file offset where the migration stream will start 1624# 1625# Since: 8.2 1626## 1627{ 'struct': 'FileMigrationArgs', 1628 'data': { 'filename': 'str', 1629 'offset': 'uint64' } } 1630 1631## 1632# @MigrationExecCommand: 1633# 1634# @args: command (list head) and arguments to execute. 1635# 1636# Since: 8.2 1637## 1638{ 'struct': 'MigrationExecCommand', 1639 'data': {'args': [ 'str' ] } } 1640 1641## 1642# @MigrationAddress: 1643# 1644# Migration endpoint configuration. 1645# 1646# @transport: The migration stream transport mechanism 1647# 1648# Since: 8.2 1649## 1650{ 'union': 'MigrationAddress', 1651 'base': { 'transport' : 'MigrationAddressType'}, 1652 'discriminator': 'transport', 1653 'data': { 1654 'socket': 'SocketAddress', 1655 'exec': 'MigrationExecCommand', 1656 'rdma': 'InetSocketAddress', 1657 'file': 'FileMigrationArgs' } } 1658 1659## 1660# @MigrationChannelType: 1661# 1662# The migration channel-type request options. 1663# 1664# @main: Main outbound migration channel. 1665# 1666# Since: 8.1 1667## 1668{ 'enum': 'MigrationChannelType', 1669 'data': [ 'main' ] } 1670 1671## 1672# @MigrationChannel: 1673# 1674# Migration stream channel parameters. 1675# 1676# @channel-type: Channel type for transferring packet information. 1677# 1678# @addr: Migration endpoint configuration on destination interface. 1679# 1680# Since: 8.1 1681## 1682{ 'struct': 'MigrationChannel', 1683 'data': { 1684 'channel-type': 'MigrationChannelType', 1685 'addr': 'MigrationAddress' } } 1686 1687## 1688# @migrate: 1689# 1690# Migrates the current running guest to another Virtual Machine. 1691# 1692# @uri: the Uniform Resource Identifier of the destination VM 1693# 1694# @channels: list of migration stream channels with each stream in the 1695# list connected to a destination interface endpoint. 1696# 1697# @blk: do block migration (full disk copy) 1698# 1699# @inc: incremental disk copy migration 1700# 1701# @detach: this argument exists only for compatibility reasons and is 1702# ignored by QEMU 1703# 1704# @resume: resume one paused migration, default "off". (since 3.0) 1705# 1706# Features: 1707# 1708# @deprecated: Members @inc and @blk are deprecated. Use 1709# blockdev-mirror with NBD instead. 1710# 1711# Returns: nothing on success 1712# 1713# Since: 0.14 1714# 1715# Notes: 1716# 1717# 1. The 'query-migrate' command should be used to check 1718# migration's progress and final result (this information is 1719# provided by the 'status' member) 1720# 1721# 2. All boolean arguments default to false 1722# 1723# 3. The user Monitor's "detach" argument is invalid in QMP and 1724# should not be used 1725# 1726# 4. The uri argument should have the Uniform Resource Identifier 1727# of default destination VM. This connection will be bound to 1728# default network. 1729# 1730# 5. For now, number of migration streams is restricted to one, 1731# i.e number of items in 'channels' list is just 1. 1732# 1733# 6. The 'uri' and 'channels' arguments are mutually exclusive; 1734# exactly one of the two should be present. 1735# 1736# Example: 1737# 1738# -> { "execute": "migrate", "arguments": { "uri": "tcp:0:4446" } } 1739# <- { "return": {} } 1740# 1741# -> { "execute": "migrate", 1742# "arguments": { 1743# "channels": [ { "channel-type": "main", 1744# "addr": { "transport": "socket", 1745# "type": "inet", 1746# "host": "10.12.34.9", 1747# "port": "1050" } } ] } } 1748# <- { "return": {} } 1749# 1750# -> { "execute": "migrate", 1751# "arguments": { 1752# "channels": [ { "channel-type": "main", 1753# "addr": { "transport": "exec", 1754# "args": [ "/bin/nc", "-p", "6000", 1755# "/some/sock" ] } } ] } } 1756# <- { "return": {} } 1757# 1758# -> { "execute": "migrate", 1759# "arguments": { 1760# "channels": [ { "channel-type": "main", 1761# "addr": { "transport": "rdma", 1762# "host": "10.12.34.9", 1763# "port": "1050" } } ] } } 1764# <- { "return": {} } 1765# 1766# -> { "execute": "migrate", 1767# "arguments": { 1768# "channels": [ { "channel-type": "main", 1769# "addr": { "transport": "file", 1770# "filename": "/tmp/migfile", 1771# "offset": "0x1000" } } ] } } 1772# <- { "return": {} } 1773# 1774## 1775{ 'command': 'migrate', 1776 'data': {'*uri': 'str', 1777 '*channels': [ 'MigrationChannel' ], 1778 '*blk': { 'type': 'bool', 'features': [ 'deprecated' ] }, 1779 '*inc': { 'type': 'bool', 'features': [ 'deprecated' ] }, 1780 '*detach': 'bool', '*resume': 'bool' } } 1781 1782## 1783# @migrate-incoming: 1784# 1785# Start an incoming migration, the qemu must have been started with 1786# -incoming defer 1787# 1788# @uri: The Uniform Resource Identifier identifying the source or 1789# address to listen on 1790# 1791# @channels: list of migration stream channels with each stream in the 1792# list connected to a destination interface endpoint. 1793# 1794# Returns: nothing on success 1795# 1796# Since: 2.3 1797# 1798# Notes: 1799# 1800# 1. It's a bad idea to use a string for the uri, but it needs to 1801# stay compatible with -incoming and the format of the uri is 1802# already exposed above libvirt. 1803# 1804# 2. QEMU must be started with -incoming defer to allow 1805# migrate-incoming to be used. 1806# 1807# 3. The uri format is the same as for -incoming 1808# 1809# 4. For now, number of migration streams is restricted to one, 1810# i.e number of items in 'channels' list is just 1. 1811# 1812# 5. The 'uri' and 'channels' arguments are mutually exclusive; 1813# exactly one of the two should be present. 1814# 1815# Example: 1816# 1817# -> { "execute": "migrate-incoming", 1818# "arguments": { "uri": "tcp:0:4446" } } 1819# <- { "return": {} } 1820# 1821# -> { "execute": "migrate-incoming", 1822# "arguments": { 1823# "channels": [ { "channel-type": "main", 1824# "addr": { "transport": "socket", 1825# "type": "inet", 1826# "host": "10.12.34.9", 1827# "port": "1050" } } ] } } 1828# <- { "return": {} } 1829# 1830# -> { "execute": "migrate-incoming", 1831# "arguments": { 1832# "channels": [ { "channel-type": "main", 1833# "addr": { "transport": "exec", 1834# "args": [ "/bin/nc", "-p", "6000", 1835# "/some/sock" ] } } ] } } 1836# <- { "return": {} } 1837# 1838# -> { "execute": "migrate-incoming", 1839# "arguments": { 1840# "channels": [ { "channel-type": "main", 1841# "addr": { "transport": "rdma", 1842# "host": "10.12.34.9", 1843# "port": "1050" } } ] } } 1844# <- { "return": {} } 1845## 1846{ 'command': 'migrate-incoming', 1847 'data': {'*uri': 'str', 1848 '*channels': [ 'MigrationChannel' ] } } 1849 1850## 1851# @xen-save-devices-state: 1852# 1853# Save the state of all devices to file. The RAM and the block 1854# devices of the VM are not saved by this command. 1855# 1856# @filename: the file to save the state of the devices to as binary 1857# data. See xen-save-devices-state.txt for a description of the 1858# binary format. 1859# 1860# @live: Optional argument to ask QEMU to treat this command as part 1861# of a live migration. Default to true. (since 2.11) 1862# 1863# Returns: Nothing on success 1864# 1865# Since: 1.1 1866# 1867# Example: 1868# 1869# -> { "execute": "xen-save-devices-state", 1870# "arguments": { "filename": "/tmp/save" } } 1871# <- { "return": {} } 1872## 1873{ 'command': 'xen-save-devices-state', 1874 'data': {'filename': 'str', '*live':'bool' } } 1875 1876## 1877# @xen-set-global-dirty-log: 1878# 1879# Enable or disable the global dirty log mode. 1880# 1881# @enable: true to enable, false to disable. 1882# 1883# Returns: nothing 1884# 1885# Since: 1.3 1886# 1887# Example: 1888# 1889# -> { "execute": "xen-set-global-dirty-log", 1890# "arguments": { "enable": true } } 1891# <- { "return": {} } 1892## 1893{ 'command': 'xen-set-global-dirty-log', 'data': { 'enable': 'bool' } } 1894 1895## 1896# @xen-load-devices-state: 1897# 1898# Load the state of all devices from file. The RAM and the block 1899# devices of the VM are not loaded by this command. 1900# 1901# @filename: the file to load the state of the devices from as binary 1902# data. See xen-save-devices-state.txt for a description of the 1903# binary format. 1904# 1905# Since: 2.7 1906# 1907# Example: 1908# 1909# -> { "execute": "xen-load-devices-state", 1910# "arguments": { "filename": "/tmp/resume" } } 1911# <- { "return": {} } 1912## 1913{ 'command': 'xen-load-devices-state', 'data': {'filename': 'str'} } 1914 1915## 1916# @xen-set-replication: 1917# 1918# Enable or disable replication. 1919# 1920# @enable: true to enable, false to disable. 1921# 1922# @primary: true for primary or false for secondary. 1923# 1924# @failover: true to do failover, false to stop. but cannot be 1925# specified if 'enable' is true. default value is false. 1926# 1927# Returns: nothing. 1928# 1929# Example: 1930# 1931# -> { "execute": "xen-set-replication", 1932# "arguments": {"enable": true, "primary": false} } 1933# <- { "return": {} } 1934# 1935# Since: 2.9 1936## 1937{ 'command': 'xen-set-replication', 1938 'data': { 'enable': 'bool', 'primary': 'bool', '*failover': 'bool' }, 1939 'if': 'CONFIG_REPLICATION' } 1940 1941## 1942# @ReplicationStatus: 1943# 1944# The result format for 'query-xen-replication-status'. 1945# 1946# @error: true if an error happened, false if replication is normal. 1947# 1948# @desc: the human readable error description string, when @error is 1949# 'true'. 1950# 1951# Since: 2.9 1952## 1953{ 'struct': 'ReplicationStatus', 1954 'data': { 'error': 'bool', '*desc': 'str' }, 1955 'if': 'CONFIG_REPLICATION' } 1956 1957## 1958# @query-xen-replication-status: 1959# 1960# Query replication status while the vm is running. 1961# 1962# Returns: A @ReplicationStatus object showing the status. 1963# 1964# Example: 1965# 1966# -> { "execute": "query-xen-replication-status" } 1967# <- { "return": { "error": false } } 1968# 1969# Since: 2.9 1970## 1971{ 'command': 'query-xen-replication-status', 1972 'returns': 'ReplicationStatus', 1973 'if': 'CONFIG_REPLICATION' } 1974 1975## 1976# @xen-colo-do-checkpoint: 1977# 1978# Xen uses this command to notify replication to trigger a checkpoint. 1979# 1980# Returns: nothing. 1981# 1982# Example: 1983# 1984# -> { "execute": "xen-colo-do-checkpoint" } 1985# <- { "return": {} } 1986# 1987# Since: 2.9 1988## 1989{ 'command': 'xen-colo-do-checkpoint', 1990 'if': 'CONFIG_REPLICATION' } 1991 1992## 1993# @COLOStatus: 1994# 1995# The result format for 'query-colo-status'. 1996# 1997# @mode: COLO running mode. If COLO is running, this field will 1998# return 'primary' or 'secondary'. 1999# 2000# @last-mode: COLO last running mode. If COLO is running, this field 2001# will return same like mode field, after failover we can use this 2002# field to get last colo mode. (since 4.0) 2003# 2004# @reason: describes the reason for the COLO exit. 2005# 2006# Since: 3.1 2007## 2008{ 'struct': 'COLOStatus', 2009 'data': { 'mode': 'COLOMode', 'last-mode': 'COLOMode', 2010 'reason': 'COLOExitReason' }, 2011 'if': 'CONFIG_REPLICATION' } 2012 2013## 2014# @query-colo-status: 2015# 2016# Query COLO status while the vm is running. 2017# 2018# Returns: A @COLOStatus object showing the status. 2019# 2020# Example: 2021# 2022# -> { "execute": "query-colo-status" } 2023# <- { "return": { "mode": "primary", "last-mode": "none", "reason": "request" } } 2024# 2025# Since: 3.1 2026## 2027{ 'command': 'query-colo-status', 2028 'returns': 'COLOStatus', 2029 'if': 'CONFIG_REPLICATION' } 2030 2031## 2032# @migrate-recover: 2033# 2034# Provide a recovery migration stream URI. 2035# 2036# @uri: the URI to be used for the recovery of migration stream. 2037# 2038# Returns: nothing. 2039# 2040# Example: 2041# 2042# -> { "execute": "migrate-recover", 2043# "arguments": { "uri": "tcp:192.168.1.200:12345" } } 2044# <- { "return": {} } 2045# 2046# Since: 3.0 2047## 2048{ 'command': 'migrate-recover', 2049 'data': { 'uri': 'str' }, 2050 'allow-oob': true } 2051 2052## 2053# @migrate-pause: 2054# 2055# Pause a migration. Currently it only supports postcopy. 2056# 2057# Returns: nothing. 2058# 2059# Example: 2060# 2061# -> { "execute": "migrate-pause" } 2062# <- { "return": {} } 2063# 2064# Since: 3.0 2065## 2066{ 'command': 'migrate-pause', 'allow-oob': true } 2067 2068## 2069# @UNPLUG_PRIMARY: 2070# 2071# Emitted from source side of a migration when migration state is 2072# WAIT_UNPLUG. Device was unplugged by guest operating system. Device 2073# resources in QEMU are kept on standby to be able to re-plug it in 2074# case of migration failure. 2075# 2076# @device-id: QEMU device id of the unplugged device 2077# 2078# Since: 4.2 2079# 2080# Example: 2081# 2082# <- { "event": "UNPLUG_PRIMARY", 2083# "data": { "device-id": "hostdev0" }, 2084# "timestamp": { "seconds": 1265044230, "microseconds": 450486 } } 2085## 2086{ 'event': 'UNPLUG_PRIMARY', 2087 'data': { 'device-id': 'str' } } 2088 2089## 2090# @DirtyRateVcpu: 2091# 2092# Dirty rate of vcpu. 2093# 2094# @id: vcpu index. 2095# 2096# @dirty-rate: dirty rate. 2097# 2098# Since: 6.2 2099## 2100{ 'struct': 'DirtyRateVcpu', 2101 'data': { 'id': 'int', 'dirty-rate': 'int64' } } 2102 2103## 2104# @DirtyRateStatus: 2105# 2106# Dirty page rate measurement status. 2107# 2108# @unstarted: measuring thread has not been started yet 2109# 2110# @measuring: measuring thread is running 2111# 2112# @measured: dirty page rate is measured and the results are available 2113# 2114# Since: 5.2 2115## 2116{ 'enum': 'DirtyRateStatus', 2117 'data': [ 'unstarted', 'measuring', 'measured'] } 2118 2119## 2120# @DirtyRateMeasureMode: 2121# 2122# Method used to measure dirty page rate. Differences between 2123# available methods are explained in @calc-dirty-rate. 2124# 2125# @page-sampling: use page sampling 2126# 2127# @dirty-ring: use dirty ring 2128# 2129# @dirty-bitmap: use dirty bitmap 2130# 2131# Since: 6.2 2132## 2133{ 'enum': 'DirtyRateMeasureMode', 2134 'data': ['page-sampling', 'dirty-ring', 'dirty-bitmap'] } 2135 2136## 2137# @TimeUnit: 2138# 2139# Specifies unit in which time-related value is specified. 2140# 2141# @second: value is in seconds 2142# 2143# @millisecond: value is in milliseconds 2144# 2145# Since: 8.2 2146# 2147## 2148{ 'enum': 'TimeUnit', 2149 'data': ['second', 'millisecond'] } 2150 2151## 2152# @DirtyRateInfo: 2153# 2154# Information about measured dirty page rate. 2155# 2156# @dirty-rate: an estimate of the dirty page rate of the VM in units 2157# of MiB/s. Value is present only when @status is 'measured'. 2158# 2159# @status: current status of dirty page rate measurements 2160# 2161# @start-time: start time in units of second for calculation 2162# 2163# @calc-time: time period for which dirty page rate was measured, 2164# expressed and rounded down to @calc-time-unit. 2165# 2166# @calc-time-unit: time unit of @calc-time (Since 8.2) 2167# 2168# @sample-pages: number of sampled pages per GiB of guest memory. 2169# Valid only in page-sampling mode (Since 6.1) 2170# 2171# @mode: mode that was used to measure dirty page rate (Since 6.2) 2172# 2173# @vcpu-dirty-rate: dirty rate for each vCPU if dirty-ring mode was 2174# specified (Since 6.2) 2175# 2176# Since: 5.2 2177## 2178{ 'struct': 'DirtyRateInfo', 2179 'data': {'*dirty-rate': 'int64', 2180 'status': 'DirtyRateStatus', 2181 'start-time': 'int64', 2182 'calc-time': 'int64', 2183 'calc-time-unit': 'TimeUnit', 2184 'sample-pages': 'uint64', 2185 'mode': 'DirtyRateMeasureMode', 2186 '*vcpu-dirty-rate': [ 'DirtyRateVcpu' ] } } 2187 2188## 2189# @calc-dirty-rate: 2190# 2191# Start measuring dirty page rate of the VM. Results can be retrieved 2192# with @query-dirty-rate after measurements are completed. 2193# 2194# Dirty page rate is the number of pages changed in a given time 2195# period expressed in MiB/s. The following methods of calculation are 2196# available: 2197# 2198# 1. In page sampling mode, a random subset of pages are selected and 2199# hashed twice: once at the beginning of measurement time period, 2200# and once again at the end. If two hashes for some page are 2201# different, the page is counted as changed. Since this method 2202# relies on sampling and hashing, calculated dirty page rate is 2203# only an estimate of its true value. Increasing @sample-pages 2204# improves estimation quality at the cost of higher computational 2205# overhead. 2206# 2207# 2. Dirty bitmap mode captures writes to memory (for example by 2208# temporarily revoking write access to all pages) and counting page 2209# faults. Information about modified pages is collected into a 2210# bitmap, where each bit corresponds to one guest page. This mode 2211# requires that KVM accelerator property "dirty-ring-size" is *not* 2212# set. 2213# 2214# 3. Dirty ring mode is similar to dirty bitmap mode, but the 2215# information about modified pages is collected into ring buffer. 2216# This mode tracks page modification per each vCPU separately. It 2217# requires that KVM accelerator property "dirty-ring-size" is set. 2218# 2219# @calc-time: time period for which dirty page rate is calculated. 2220# By default it is specified in seconds, but the unit can be set 2221# explicitly with @calc-time-unit. Note that larger @calc-time 2222# values will typically result in smaller dirty page rates because 2223# page dirtying is a one-time event. Once some page is counted 2224# as dirty during @calc-time period, further writes to this page 2225# will not increase dirty page rate anymore. 2226# 2227# @calc-time-unit: time unit in which @calc-time is specified. 2228# By default it is seconds. (Since 8.2) 2229# 2230# @sample-pages: number of sampled pages per each GiB of guest memory. 2231# Default value is 512. For 4KiB guest pages this corresponds to 2232# sampling ratio of 0.2%. This argument is used only in page 2233# sampling mode. (Since 6.1) 2234# 2235# @mode: mechanism for tracking dirty pages. Default value is 2236# 'page-sampling'. Others are 'dirty-bitmap' and 'dirty-ring'. 2237# (Since 6.1) 2238# 2239# Since: 5.2 2240# 2241# Example: 2242# 2243# -> {"execute": "calc-dirty-rate", "arguments": {"calc-time": 1, 2244# 'sample-pages': 512} } 2245# <- { "return": {} } 2246# 2247# Measure dirty rate using dirty bitmap for 500 milliseconds: 2248# 2249# -> {"execute": "calc-dirty-rate", "arguments": {"calc-time": 500, 2250# "calc-time-unit": "millisecond", "mode": "dirty-bitmap"} } 2251# 2252# <- { "return": {} } 2253## 2254{ 'command': 'calc-dirty-rate', 'data': {'calc-time': 'int64', 2255 '*calc-time-unit': 'TimeUnit', 2256 '*sample-pages': 'int', 2257 '*mode': 'DirtyRateMeasureMode'} } 2258 2259## 2260# @query-dirty-rate: 2261# 2262# Query results of the most recent invocation of @calc-dirty-rate. 2263# 2264# @calc-time-unit: time unit in which to report calculation time. 2265# By default it is reported in seconds. (Since 8.2) 2266# 2267# Since: 5.2 2268# 2269# Examples: 2270# 2271# 1. Measurement is in progress: 2272# 2273# <- {"status": "measuring", "sample-pages": 512, 2274# "mode": "page-sampling", "start-time": 1693900454, "calc-time": 10, 2275# "calc-time-unit": "second"} 2276# 2277# 2. Measurement has been completed: 2278# 2279# <- {"status": "measured", "sample-pages": 512, "dirty-rate": 108, 2280# "mode": "page-sampling", "start-time": 1693900454, "calc-time": 10, 2281# "calc-time-unit": "second"} 2282## 2283{ 'command': 'query-dirty-rate', 'data': {'*calc-time-unit': 'TimeUnit' }, 2284 'returns': 'DirtyRateInfo' } 2285 2286## 2287# @DirtyLimitInfo: 2288# 2289# Dirty page rate limit information of a virtual CPU. 2290# 2291# @cpu-index: index of a virtual CPU. 2292# 2293# @limit-rate: upper limit of dirty page rate (MB/s) for a virtual 2294# CPU, 0 means unlimited. 2295# 2296# @current-rate: current dirty page rate (MB/s) for a virtual CPU. 2297# 2298# Since: 7.1 2299## 2300{ 'struct': 'DirtyLimitInfo', 2301 'data': { 'cpu-index': 'int', 2302 'limit-rate': 'uint64', 2303 'current-rate': 'uint64' } } 2304 2305## 2306# @set-vcpu-dirty-limit: 2307# 2308# Set the upper limit of dirty page rate for virtual CPUs. 2309# 2310# Requires KVM with accelerator property "dirty-ring-size" set. A 2311# virtual CPU's dirty page rate is a measure of its memory load. To 2312# observe dirty page rates, use @calc-dirty-rate. 2313# 2314# @cpu-index: index of a virtual CPU, default is all. 2315# 2316# @dirty-rate: upper limit of dirty page rate (MB/s) for virtual CPUs. 2317# 2318# Since: 7.1 2319# 2320# Example: 2321# 2322# -> {"execute": "set-vcpu-dirty-limit"} 2323# "arguments": { "dirty-rate": 200, 2324# "cpu-index": 1 } } 2325# <- { "return": {} } 2326## 2327{ 'command': 'set-vcpu-dirty-limit', 2328 'data': { '*cpu-index': 'int', 2329 'dirty-rate': 'uint64' } } 2330 2331## 2332# @cancel-vcpu-dirty-limit: 2333# 2334# Cancel the upper limit of dirty page rate for virtual CPUs. 2335# 2336# Cancel the dirty page limit for the vCPU which has been set with 2337# set-vcpu-dirty-limit command. Note that this command requires 2338# support from dirty ring, same as the "set-vcpu-dirty-limit". 2339# 2340# @cpu-index: index of a virtual CPU, default is all. 2341# 2342# Since: 7.1 2343# 2344# Example: 2345# 2346# -> {"execute": "cancel-vcpu-dirty-limit"}, 2347# "arguments": { "cpu-index": 1 } } 2348# <- { "return": {} } 2349## 2350{ 'command': 'cancel-vcpu-dirty-limit', 2351 'data': { '*cpu-index': 'int'} } 2352 2353## 2354# @query-vcpu-dirty-limit: 2355# 2356# Returns information about virtual CPU dirty page rate limits, if 2357# any. 2358# 2359# Since: 7.1 2360# 2361# Example: 2362# 2363# -> {"execute": "query-vcpu-dirty-limit"} 2364# <- {"return": [ 2365# { "limit-rate": 60, "current-rate": 3, "cpu-index": 0}, 2366# { "limit-rate": 60, "current-rate": 3, "cpu-index": 1}]} 2367## 2368{ 'command': 'query-vcpu-dirty-limit', 2369 'returns': [ 'DirtyLimitInfo' ] } 2370 2371## 2372# @MigrationThreadInfo: 2373# 2374# Information about migrationthreads 2375# 2376# @name: the name of migration thread 2377# 2378# @thread-id: ID of the underlying host thread 2379# 2380# Since: 7.2 2381## 2382{ 'struct': 'MigrationThreadInfo', 2383 'data': {'name': 'str', 2384 'thread-id': 'int'} } 2385 2386## 2387# @query-migrationthreads: 2388# 2389# Returns information of migration threads 2390# 2391# data: migration thread name 2392# 2393# Returns: information about migration threads 2394# 2395# Since: 7.2 2396## 2397{ 'command': 'query-migrationthreads', 2398 'returns': ['MigrationThreadInfo'] } 2399 2400## 2401# @snapshot-save: 2402# 2403# Save a VM snapshot 2404# 2405# @job-id: identifier for the newly created job 2406# 2407# @tag: name of the snapshot to create 2408# 2409# @vmstate: block device node name to save vmstate to 2410# 2411# @devices: list of block device node names to save a snapshot to 2412# 2413# Applications should not assume that the snapshot save is complete 2414# when this command returns. The job commands / events must be used 2415# to determine completion and to fetch details of any errors that 2416# arise. 2417# 2418# Note that execution of the guest CPUs may be stopped during the time 2419# it takes to save the snapshot. A future version of QEMU may ensure 2420# CPUs are executing continuously. 2421# 2422# It is strongly recommended that @devices contain all writable block 2423# device nodes if a consistent snapshot is required. 2424# 2425# If @tag already exists, an error will be reported 2426# 2427# Returns: nothing 2428# 2429# Example: 2430# 2431# -> { "execute": "snapshot-save", 2432# "arguments": { 2433# "job-id": "snapsave0", 2434# "tag": "my-snap", 2435# "vmstate": "disk0", 2436# "devices": ["disk0", "disk1"] 2437# } 2438# } 2439# <- { "return": { } } 2440# <- {"event": "JOB_STATUS_CHANGE", 2441# "timestamp": {"seconds": 1432121972, "microseconds": 744001}, 2442# "data": {"status": "created", "id": "snapsave0"}} 2443# <- {"event": "JOB_STATUS_CHANGE", 2444# "timestamp": {"seconds": 1432122172, "microseconds": 744001}, 2445# "data": {"status": "running", "id": "snapsave0"}} 2446# <- {"event": "STOP", 2447# "timestamp": {"seconds": 1432122372, "microseconds": 744001} } 2448# <- {"event": "RESUME", 2449# "timestamp": {"seconds": 1432122572, "microseconds": 744001} } 2450# <- {"event": "JOB_STATUS_CHANGE", 2451# "timestamp": {"seconds": 1432122772, "microseconds": 744001}, 2452# "data": {"status": "waiting", "id": "snapsave0"}} 2453# <- {"event": "JOB_STATUS_CHANGE", 2454# "timestamp": {"seconds": 1432122972, "microseconds": 744001}, 2455# "data": {"status": "pending", "id": "snapsave0"}} 2456# <- {"event": "JOB_STATUS_CHANGE", 2457# "timestamp": {"seconds": 1432123172, "microseconds": 744001}, 2458# "data": {"status": "concluded", "id": "snapsave0"}} 2459# -> {"execute": "query-jobs"} 2460# <- {"return": [{"current-progress": 1, 2461# "status": "concluded", 2462# "total-progress": 1, 2463# "type": "snapshot-save", 2464# "id": "snapsave0"}]} 2465# 2466# Since: 6.0 2467## 2468{ 'command': 'snapshot-save', 2469 'data': { 'job-id': 'str', 2470 'tag': 'str', 2471 'vmstate': 'str', 2472 'devices': ['str'] } } 2473 2474## 2475# @snapshot-load: 2476# 2477# Load a VM snapshot 2478# 2479# @job-id: identifier for the newly created job 2480# 2481# @tag: name of the snapshot to load. 2482# 2483# @vmstate: block device node name to load vmstate from 2484# 2485# @devices: list of block device node names to load a snapshot from 2486# 2487# Applications should not assume that the snapshot load is complete 2488# when this command returns. The job commands / events must be used 2489# to determine completion and to fetch details of any errors that 2490# arise. 2491# 2492# Note that execution of the guest CPUs will be stopped during the 2493# time it takes to load the snapshot. 2494# 2495# It is strongly recommended that @devices contain all writable block 2496# device nodes that can have changed since the original @snapshot-save 2497# command execution. 2498# 2499# Returns: nothing 2500# 2501# Example: 2502# 2503# -> { "execute": "snapshot-load", 2504# "arguments": { 2505# "job-id": "snapload0", 2506# "tag": "my-snap", 2507# "vmstate": "disk0", 2508# "devices": ["disk0", "disk1"] 2509# } 2510# } 2511# <- { "return": { } } 2512# <- {"event": "JOB_STATUS_CHANGE", 2513# "timestamp": {"seconds": 1472124172, "microseconds": 744001}, 2514# "data": {"status": "created", "id": "snapload0"}} 2515# <- {"event": "JOB_STATUS_CHANGE", 2516# "timestamp": {"seconds": 1472125172, "microseconds": 744001}, 2517# "data": {"status": "running", "id": "snapload0"}} 2518# <- {"event": "STOP", 2519# "timestamp": {"seconds": 1472125472, "microseconds": 744001} } 2520# <- {"event": "RESUME", 2521# "timestamp": {"seconds": 1472125872, "microseconds": 744001} } 2522# <- {"event": "JOB_STATUS_CHANGE", 2523# "timestamp": {"seconds": 1472126172, "microseconds": 744001}, 2524# "data": {"status": "waiting", "id": "snapload0"}} 2525# <- {"event": "JOB_STATUS_CHANGE", 2526# "timestamp": {"seconds": 1472127172, "microseconds": 744001}, 2527# "data": {"status": "pending", "id": "snapload0"}} 2528# <- {"event": "JOB_STATUS_CHANGE", 2529# "timestamp": {"seconds": 1472128172, "microseconds": 744001}, 2530# "data": {"status": "concluded", "id": "snapload0"}} 2531# -> {"execute": "query-jobs"} 2532# <- {"return": [{"current-progress": 1, 2533# "status": "concluded", 2534# "total-progress": 1, 2535# "type": "snapshot-load", 2536# "id": "snapload0"}]} 2537# 2538# Since: 6.0 2539## 2540{ 'command': 'snapshot-load', 2541 'data': { 'job-id': 'str', 2542 'tag': 'str', 2543 'vmstate': 'str', 2544 'devices': ['str'] } } 2545 2546## 2547# @snapshot-delete: 2548# 2549# Delete a VM snapshot 2550# 2551# @job-id: identifier for the newly created job 2552# 2553# @tag: name of the snapshot to delete. 2554# 2555# @devices: list of block device node names to delete a snapshot from 2556# 2557# Applications should not assume that the snapshot delete is complete 2558# when this command returns. The job commands / events must be used 2559# to determine completion and to fetch details of any errors that 2560# arise. 2561# 2562# Returns: nothing 2563# 2564# Example: 2565# 2566# -> { "execute": "snapshot-delete", 2567# "arguments": { 2568# "job-id": "snapdelete0", 2569# "tag": "my-snap", 2570# "devices": ["disk0", "disk1"] 2571# } 2572# } 2573# <- { "return": { } } 2574# <- {"event": "JOB_STATUS_CHANGE", 2575# "timestamp": {"seconds": 1442124172, "microseconds": 744001}, 2576# "data": {"status": "created", "id": "snapdelete0"}} 2577# <- {"event": "JOB_STATUS_CHANGE", 2578# "timestamp": {"seconds": 1442125172, "microseconds": 744001}, 2579# "data": {"status": "running", "id": "snapdelete0"}} 2580# <- {"event": "JOB_STATUS_CHANGE", 2581# "timestamp": {"seconds": 1442126172, "microseconds": 744001}, 2582# "data": {"status": "waiting", "id": "snapdelete0"}} 2583# <- {"event": "JOB_STATUS_CHANGE", 2584# "timestamp": {"seconds": 1442127172, "microseconds": 744001}, 2585# "data": {"status": "pending", "id": "snapdelete0"}} 2586# <- {"event": "JOB_STATUS_CHANGE", 2587# "timestamp": {"seconds": 1442128172, "microseconds": 744001}, 2588# "data": {"status": "concluded", "id": "snapdelete0"}} 2589# -> {"execute": "query-jobs"} 2590# <- {"return": [{"current-progress": 1, 2591# "status": "concluded", 2592# "total-progress": 1, 2593# "type": "snapshot-delete", 2594# "id": "snapdelete0"}]} 2595# 2596# Since: 6.0 2597## 2598{ 'command': 'snapshot-delete', 2599 'data': { 'job-id': 'str', 2600 'tag': 'str', 2601 'devices': ['str'] } } 2602