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 27# for 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. 505# (since 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# @mapped-ram: Migrate using fixed offsets in the migration file for 535# each RAM page. Requires a migration URI that supports seeking, 536# such as a file. (since 9.0) 537# 538# Features: 539# 540# @deprecated: Member @block is deprecated. Use blockdev-mirror with 541# NBD instead. Member @compress is deprecated because it is 542# unreliable and untested. It is recommended to use multifd 543# migration, which offers an alternative compression 544# implementation that is reliable and tested. 545# 546# @unstable: Members @x-colo and @x-ignore-shared are experimental. 547# 548# Since: 1.2 549## 550{ 'enum': 'MigrationCapability', 551 'data': ['xbzrle', 'rdma-pin-all', 'auto-converge', 'zero-blocks', 552 { 'name': 'compress', 'features': [ 'deprecated' ] }, 553 'events', 'postcopy-ram', 554 { 'name': 'x-colo', 'features': [ 'unstable' ] }, 555 'release-ram', 556 { 'name': 'block', 'features': [ 'deprecated' ] }, 557 'return-path', 'pause-before-switchover', 'multifd', 558 'dirty-bitmaps', 'postcopy-blocktime', 'late-block-activate', 559 { 'name': 'x-ignore-shared', 'features': [ 'unstable' ] }, 560 'validate-uuid', 'background-snapshot', 561 'zero-copy-send', 'postcopy-preempt', 'switchover-ack', 562 'dirty-limit', 'mapped-ram'] } 563 564## 565# @MigrationCapabilityStatus: 566# 567# Migration capability information 568# 569# @capability: capability enum 570# 571# @state: capability state bool 572# 573# Since: 1.2 574## 575{ 'struct': 'MigrationCapabilityStatus', 576 'data': { 'capability': 'MigrationCapability', 'state': 'bool' } } 577 578## 579# @migrate-set-capabilities: 580# 581# Enable/Disable the following migration capabilities (like xbzrle) 582# 583# @capabilities: json array of capability modifications to make 584# 585# Since: 1.2 586# 587# Example: 588# 589# -> { "execute": "migrate-set-capabilities" , "arguments": 590# { "capabilities": [ { "capability": "xbzrle", "state": true } ] } } 591# <- { "return": {} } 592## 593{ 'command': 'migrate-set-capabilities', 594 'data': { 'capabilities': ['MigrationCapabilityStatus'] } } 595 596## 597# @query-migrate-capabilities: 598# 599# Returns information about the current migration capabilities status 600# 601# Returns: @MigrationCapabilityStatus 602# 603# Since: 1.2 604# 605# Example: 606# 607# -> { "execute": "query-migrate-capabilities" } 608# <- { "return": [ 609# {"state": false, "capability": "xbzrle"}, 610# {"state": false, "capability": "rdma-pin-all"}, 611# {"state": false, "capability": "auto-converge"}, 612# {"state": false, "capability": "zero-blocks"}, 613# {"state": false, "capability": "compress"}, 614# {"state": true, "capability": "events"}, 615# {"state": false, "capability": "postcopy-ram"}, 616# {"state": false, "capability": "x-colo"} 617# ]} 618## 619{ 'command': 'query-migrate-capabilities', 'returns': ['MigrationCapabilityStatus']} 620 621## 622# @MultiFDCompression: 623# 624# An enumeration of multifd compression methods. 625# 626# @none: no compression. 627# 628# @zlib: use zlib compression method. 629# 630# @zstd: use zstd compression method. 631# 632# Since: 5.0 633## 634{ 'enum': 'MultiFDCompression', 635 'data': [ 'none', 'zlib', 636 { 'name': 'zstd', 'if': 'CONFIG_ZSTD' } ] } 637 638## 639# @MigMode: 640# 641# @normal: the original form of migration. (since 8.2) 642# 643# @cpr-reboot: The migrate command stops the VM and saves state to the 644# URI. After quitting QEMU, the user resumes by running QEMU 645# -incoming. 646# 647# This mode allows the user to quit QEMU, optionally update and 648# reboot the OS, and restart QEMU. If the user reboots, the URI 649# must persist across the reboot, such as by using a file. 650# 651# Unlike normal mode, the use of certain local storage options 652# does not block the migration, but the user must not modify the 653# contents of guest block devices between the quit and restart. 654# 655# This mode supports VFIO devices provided the user first puts the 656# guest in the suspended runstate, such as by issuing 657# guest-suspend-ram to the QEMU guest agent. 658# 659# Best performance is achieved when the memory backend is shared 660# and the @x-ignore-shared migration capability is set, but this 661# is not required. Further, if the user reboots before restarting 662# such a configuration, the shared memory must persist across the 663# reboot, such as by backing it with a dax device. 664# 665# @cpr-reboot may not be used with postcopy, background-snapshot, 666# or COLO. 667# 668# (since 8.2) 669## 670{ 'enum': 'MigMode', 671 'data': [ 'normal', 'cpr-reboot' ] } 672 673## 674# @ZeroPageDetection: 675# 676# @none: Do not perform zero page checking. 677# 678# @legacy: Perform zero page checking in main migration thread. 679# 680# @multifd: Perform zero page checking in multifd sender thread if 681# multifd migration is enabled, else in the main migration thread 682# as for @legacy. 683# 684# Since: 9.0 685## 686{ 'enum': 'ZeroPageDetection', 687 'data': [ 'none', 'legacy', 'multifd' ] } 688 689## 690# @BitmapMigrationBitmapAliasTransform: 691# 692# @persistent: If present, the bitmap will be made persistent or 693# transient depending on this parameter. 694# 695# Since: 6.0 696## 697{ 'struct': 'BitmapMigrationBitmapAliasTransform', 698 'data': { 699 '*persistent': 'bool' 700 } } 701 702## 703# @BitmapMigrationBitmapAlias: 704# 705# @name: The name of the bitmap. 706# 707# @alias: An alias name for migration (for example the bitmap name on 708# the opposite site). 709# 710# @transform: Allows the modification of the migrated bitmap. (since 711# 6.0) 712# 713# Since: 5.2 714## 715{ 'struct': 'BitmapMigrationBitmapAlias', 716 'data': { 717 'name': 'str', 718 'alias': 'str', 719 '*transform': 'BitmapMigrationBitmapAliasTransform' 720 } } 721 722## 723# @BitmapMigrationNodeAlias: 724# 725# Maps a block node name and the bitmaps it has to aliases for dirty 726# bitmap migration. 727# 728# @node-name: A block node name. 729# 730# @alias: An alias block node name for migration (for example the node 731# name on the opposite site). 732# 733# @bitmaps: Mappings for the bitmaps on this node. 734# 735# Since: 5.2 736## 737{ 'struct': 'BitmapMigrationNodeAlias', 738 'data': { 739 'node-name': 'str', 740 'alias': 'str', 741 'bitmaps': [ 'BitmapMigrationBitmapAlias' ] 742 } } 743 744## 745# @MigrationParameter: 746# 747# Migration parameters enumeration 748# 749# @announce-initial: Initial delay (in milliseconds) before sending 750# the first announce (Since 4.0) 751# 752# @announce-max: Maximum delay (in milliseconds) between packets in 753# the announcement (Since 4.0) 754# 755# @announce-rounds: Number of self-announce packets sent after 756# migration (Since 4.0) 757# 758# @announce-step: Increase in delay (in milliseconds) between 759# subsequent packets in the announcement (Since 4.0) 760# 761# @compress-level: Set the compression level to be used in live 762# migration, the compression level is an integer between 0 and 9, 763# where 0 means no compression, 1 means the best compression 764# speed, and 9 means best compression ratio which will consume 765# more CPU. 766# 767# @compress-threads: Set compression thread count to be used in live 768# migration, the compression thread count is an integer between 1 769# and 255. 770# 771# @compress-wait-thread: Controls behavior when all compression 772# threads are currently busy. If true (default), wait for a free 773# compression thread to become available; otherwise, send the page 774# uncompressed. (Since 3.1) 775# 776# @decompress-threads: Set decompression thread count to be used in 777# live migration, the decompression thread count is an integer 778# between 1 and 255. Usually, decompression is at least 4 times as 779# fast as compression, so set the decompress-threads to the number 780# about 1/4 of compress-threads is adequate. 781# 782# @throttle-trigger-threshold: The ratio of bytes_dirty_period and 783# bytes_xfer_period to trigger throttling. It is expressed as 784# percentage. The default value is 50. (Since 5.0) 785# 786# @cpu-throttle-initial: Initial percentage of time guest cpus are 787# throttled when migration auto-converge is activated. The 788# default value is 20. (Since 2.7) 789# 790# @cpu-throttle-increment: throttle percentage increase each time 791# auto-converge detects that migration is not making progress. 792# The default value is 10. (Since 2.7) 793# 794# @cpu-throttle-tailslow: Make CPU throttling slower at tail stage At 795# the tail stage of throttling, the Guest is very sensitive to CPU 796# percentage while the @cpu-throttle -increment is excessive 797# usually at tail stage. If this parameter is true, we will 798# compute the ideal CPU percentage used by the Guest, which may 799# exactly make the dirty rate match the dirty rate threshold. 800# Then we will choose a smaller throttle increment between the one 801# specified by @cpu-throttle-increment and the one generated by 802# ideal CPU percentage. Therefore, it is compatible to 803# traditional throttling, meanwhile the throttle increment won't 804# be excessive at tail stage. The default value is false. (Since 805# 5.1) 806# 807# @tls-creds: ID of the 'tls-creds' object that provides credentials 808# for establishing a TLS connection over the migration data 809# channel. On the outgoing side of the migration, the credentials 810# must be for a 'client' endpoint, while for the incoming side the 811# credentials must be for a 'server' endpoint. Setting this to a 812# non-empty string enables TLS for all migrations. An empty 813# string means that QEMU will use plain text mode for migration, 814# rather than TLS. (Since 2.7) 815# 816# @tls-hostname: migration target's hostname for validating the 817# server's x509 certificate identity. If empty, QEMU will use the 818# hostname from the migration URI, if any. A non-empty value is 819# required when using x509 based TLS credentials and the migration 820# URI does not include a hostname, such as fd: or exec: based 821# migration. (Since 2.7) 822# 823# Note: empty value works only since 2.9. 824# 825# @tls-authz: ID of the 'authz' object subclass that provides access 826# control checking of the TLS x509 certificate distinguished name. 827# This object is only resolved at time of use, so can be deleted 828# and recreated on the fly while the migration server is active. 829# If missing, it will default to denying access (Since 4.0) 830# 831# @max-bandwidth: maximum speed for migration, in bytes per second. 832# (Since 2.8) 833# 834# @avail-switchover-bandwidth: to set the available bandwidth that 835# migration can use during switchover phase. NOTE! This does not 836# limit the bandwidth during switchover, but only for calculations 837# when making decisions to switchover. By default, this value is 838# zero, which means QEMU will estimate the bandwidth 839# automatically. This can be set when the estimated value is not 840# accurate, while the user is able to guarantee such bandwidth is 841# available when switching over. When specified correctly, this 842# can make the switchover decision much more accurate. 843# (Since 8.2) 844# 845# @downtime-limit: set maximum tolerated downtime for migration. 846# maximum downtime in milliseconds (Since 2.8) 847# 848# @x-checkpoint-delay: The delay time (in ms) between two COLO 849# checkpoints in periodic mode. (Since 2.8) 850# 851# @block-incremental: Affects how much storage is migrated when the 852# block migration capability is enabled. When false, the entire 853# storage backing chain is migrated into a flattened image at the 854# destination; when true, only the active qcow2 layer is migrated 855# and the destination must already have access to the same backing 856# chain as was used on the source. (since 2.10) 857# 858# @multifd-channels: Number of channels used to migrate data in 859# parallel. This is the same number that the number of sockets 860# used for migration. The default value is 2 (since 4.0) 861# 862# @xbzrle-cache-size: cache size to be used by XBZRLE migration. It 863# needs to be a multiple of the target page size and a power of 2 864# (Since 2.11) 865# 866# @max-postcopy-bandwidth: Background transfer bandwidth during 867# postcopy. Defaults to 0 (unlimited). In bytes per second. 868# (Since 3.0) 869# 870# @max-cpu-throttle: maximum cpu throttle percentage. Defaults to 99. 871# (Since 3.1) 872# 873# @multifd-compression: Which compression method to use. Defaults to 874# none. (Since 5.0) 875# 876# @multifd-zlib-level: Set the compression level to be used in live 877# migration, the compression level is an integer between 0 and 9, 878# where 0 means no compression, 1 means the best compression 879# speed, and 9 means best compression ratio which will consume 880# more CPU. Defaults to 1. (Since 5.0) 881# 882# @multifd-zstd-level: Set the compression level to be used in live 883# migration, the compression level is an integer between 0 and 20, 884# where 0 means no compression, 1 means the best compression 885# speed, and 20 means best compression ratio which will consume 886# more CPU. Defaults to 1. (Since 5.0) 887# 888# @block-bitmap-mapping: Maps block nodes and bitmaps on them to 889# aliases for the purpose of dirty bitmap migration. Such aliases 890# may for example be the corresponding names on the opposite site. 891# The mapping must be one-to-one, but not necessarily complete: On 892# the source, unmapped bitmaps and all bitmaps on unmapped nodes 893# will be ignored. On the destination, encountering an unmapped 894# alias in the incoming migration stream will result in a report, 895# and all further bitmap migration data will then be discarded. 896# Note that the destination does not know about bitmaps it does 897# not receive, so there is no limitation or requirement regarding 898# the number of bitmaps received, or how they are named, or on 899# which nodes they are placed. By default (when this parameter 900# has never been set), bitmap names are mapped to themselves. 901# Nodes are mapped to their block device name if there is one, and 902# to their node name otherwise. (Since 5.2) 903# 904# @x-vcpu-dirty-limit-period: Periodic time (in milliseconds) of dirty 905# limit during live migration. Should be in the range 1 to 906# 1000ms. Defaults to 1000ms. (Since 8.1) 907# 908# @vcpu-dirty-limit: Dirtyrate limit (MB/s) during live migration. 909# Defaults to 1. (Since 8.1) 910# 911# @mode: Migration mode. See description in @MigMode. Default is 912# 'normal'. (Since 8.2) 913# 914# @zero-page-detection: Whether and how to detect zero pages. 915# See description in @ZeroPageDetection. Default is 'multifd'. 916# (since 9.0) 917# 918# Features: 919# 920# @deprecated: Member @block-incremental is deprecated. Use 921# blockdev-mirror with NBD instead. Members @compress-level, 922# @compress-threads, @decompress-threads and @compress-wait-thread 923# are deprecated because @compression is deprecated. 924# 925# @unstable: Members @x-checkpoint-delay and 926# @x-vcpu-dirty-limit-period are experimental. 927# 928# Since: 2.4 929## 930{ 'enum': 'MigrationParameter', 931 'data': ['announce-initial', 'announce-max', 932 'announce-rounds', 'announce-step', 933 { 'name': 'compress-level', 'features': [ 'deprecated' ] }, 934 { 'name': 'compress-threads', 'features': [ 'deprecated' ] }, 935 { 'name': 'decompress-threads', 'features': [ 'deprecated' ] }, 936 { 'name': 'compress-wait-thread', 'features': [ 'deprecated' ] }, 937 'throttle-trigger-threshold', 938 'cpu-throttle-initial', 'cpu-throttle-increment', 939 'cpu-throttle-tailslow', 940 'tls-creds', 'tls-hostname', 'tls-authz', 'max-bandwidth', 941 'avail-switchover-bandwidth', 'downtime-limit', 942 { 'name': 'x-checkpoint-delay', 'features': [ 'unstable' ] }, 943 { 'name': 'block-incremental', 'features': [ 'deprecated' ] }, 944 'multifd-channels', 945 'xbzrle-cache-size', 'max-postcopy-bandwidth', 946 'max-cpu-throttle', 'multifd-compression', 947 'multifd-zlib-level', 'multifd-zstd-level', 948 'block-bitmap-mapping', 949 { 'name': 'x-vcpu-dirty-limit-period', 'features': ['unstable'] }, 950 'vcpu-dirty-limit', 951 'mode', 952 'zero-page-detection'] } 953 954## 955# @MigrateSetParameters: 956# 957# @announce-initial: Initial delay (in milliseconds) before sending 958# the first announce (Since 4.0) 959# 960# @announce-max: Maximum delay (in milliseconds) between packets in 961# the announcement (Since 4.0) 962# 963# @announce-rounds: Number of self-announce packets sent after 964# migration (Since 4.0) 965# 966# @announce-step: Increase in delay (in milliseconds) between 967# subsequent packets in the announcement (Since 4.0) 968# 969# @compress-level: Set the compression level to be used in live 970# migration, the compression level is an integer between 0 and 9, 971# where 0 means no compression, 1 means the best compression 972# speed, and 9 means best compression ratio which will consume 973# more CPU. 974# 975# @compress-threads: Set compression thread count to be used in live 976# migration, the compression thread count is an integer between 1 977# and 255. 978# 979# @compress-wait-thread: Controls behavior when all compression 980# threads are currently busy. If true (default), wait for a free 981# compression thread to become available; otherwise, send the page 982# uncompressed. (Since 3.1) 983# 984# @decompress-threads: Set decompression thread count to be used in 985# live migration, the decompression thread count is an integer 986# between 1 and 255. Usually, decompression is at least 4 times as 987# fast as compression, so set the decompress-threads to the number 988# about 1/4 of compress-threads is adequate. 989# 990# @throttle-trigger-threshold: The ratio of bytes_dirty_period and 991# bytes_xfer_period to trigger throttling. It is expressed as 992# percentage. The default value is 50. (Since 5.0) 993# 994# @cpu-throttle-initial: Initial percentage of time guest cpus are 995# throttled when migration auto-converge is activated. The 996# default value is 20. (Since 2.7) 997# 998# @cpu-throttle-increment: throttle percentage increase each time 999# auto-converge detects that migration is not making progress. 1000# The default value is 10. (Since 2.7) 1001# 1002# @cpu-throttle-tailslow: Make CPU throttling slower at tail stage At 1003# the tail stage of throttling, the Guest is very sensitive to CPU 1004# percentage while the @cpu-throttle -increment is excessive 1005# usually at tail stage. If this parameter is true, we will 1006# compute the ideal CPU percentage used by the Guest, which may 1007# exactly make the dirty rate match the dirty rate threshold. 1008# Then we will choose a smaller throttle increment between the one 1009# specified by @cpu-throttle-increment and the one generated by 1010# ideal CPU percentage. Therefore, it is compatible to 1011# traditional throttling, meanwhile the throttle increment won't 1012# be excessive at tail stage. The default value is false. (Since 1013# 5.1) 1014# 1015# @tls-creds: ID of the 'tls-creds' object that provides credentials 1016# for establishing a TLS connection over the migration data 1017# channel. On the outgoing side of the migration, the credentials 1018# must be for a 'client' endpoint, while for the incoming side the 1019# credentials must be for a 'server' endpoint. Setting this to a 1020# non-empty string enables TLS for all migrations. An empty 1021# string means that QEMU will use plain text mode for migration, 1022# rather than TLS. This is the default. (Since 2.7) 1023# 1024# @tls-hostname: migration target's hostname for validating the 1025# server's x509 certificate identity. If empty, QEMU will use the 1026# hostname from the migration URI, if any. A non-empty value is 1027# required when using x509 based TLS credentials and the migration 1028# URI does not include a hostname, such as fd: or exec: based 1029# migration. (Since 2.7) 1030# 1031# Note: empty value works only since 2.9. 1032# 1033# @tls-authz: ID of the 'authz' object subclass that provides access 1034# control checking of the TLS x509 certificate distinguished name. 1035# This object is only resolved at time of use, so can be deleted 1036# and recreated on the fly while the migration server is active. 1037# If missing, it will default to denying access (Since 4.0) 1038# 1039# @max-bandwidth: maximum speed for migration, in bytes per second. 1040# (Since 2.8) 1041# 1042# @avail-switchover-bandwidth: to set the available bandwidth that 1043# migration can use during switchover phase. NOTE! This does not 1044# limit the bandwidth during switchover, but only for calculations 1045# when making decisions to switchover. By default, this value is 1046# zero, which means QEMU will estimate the bandwidth 1047# automatically. This can be set when the estimated value is not 1048# accurate, while the user is able to guarantee such bandwidth is 1049# available when switching over. When specified correctly, this 1050# can make the switchover decision much more accurate. 1051# (Since 8.2) 1052# 1053# @downtime-limit: set maximum tolerated downtime for migration. 1054# maximum downtime in milliseconds (Since 2.8) 1055# 1056# @x-checkpoint-delay: The delay time (in ms) between two COLO 1057# checkpoints in periodic mode. (Since 2.8) 1058# 1059# @block-incremental: Affects how much storage is migrated when the 1060# block migration capability is enabled. When false, the entire 1061# storage backing chain is migrated into a flattened image at the 1062# destination; when true, only the active qcow2 layer is migrated 1063# and the destination must already have access to the same backing 1064# chain as was used on the source. (since 2.10) 1065# 1066# @multifd-channels: Number of channels used to migrate data in 1067# parallel. This is the same number that the number of sockets 1068# used for migration. The default value is 2 (since 4.0) 1069# 1070# @xbzrle-cache-size: cache size to be used by XBZRLE migration. It 1071# needs to be a multiple of the target page size and a power of 2 1072# (Since 2.11) 1073# 1074# @max-postcopy-bandwidth: Background transfer bandwidth during 1075# postcopy. Defaults to 0 (unlimited). In bytes per second. 1076# (Since 3.0) 1077# 1078# @max-cpu-throttle: maximum cpu throttle percentage. Defaults to 99. 1079# (Since 3.1) 1080# 1081# @multifd-compression: Which compression method to use. Defaults to 1082# none. (Since 5.0) 1083# 1084# @multifd-zlib-level: Set the compression level to be used in live 1085# migration, the compression level is an integer between 0 and 9, 1086# where 0 means no compression, 1 means the best compression 1087# speed, and 9 means best compression ratio which will consume 1088# more CPU. Defaults to 1. (Since 5.0) 1089# 1090# @multifd-zstd-level: Set the compression level to be used in live 1091# migration, the compression level is an integer between 0 and 20, 1092# where 0 means no compression, 1 means the best compression 1093# speed, and 20 means best compression ratio which will consume 1094# more CPU. Defaults to 1. (Since 5.0) 1095# 1096# @block-bitmap-mapping: Maps block nodes and bitmaps on them to 1097# aliases for the purpose of dirty bitmap migration. Such aliases 1098# may for example be the corresponding names on the opposite site. 1099# The mapping must be one-to-one, but not necessarily complete: On 1100# the source, unmapped bitmaps and all bitmaps on unmapped nodes 1101# will be ignored. On the destination, encountering an unmapped 1102# alias in the incoming migration stream will result in a report, 1103# and all further bitmap migration data will then be discarded. 1104# Note that the destination does not know about bitmaps it does 1105# not receive, so there is no limitation or requirement regarding 1106# the number of bitmaps received, or how they are named, or on 1107# which nodes they are placed. By default (when this parameter 1108# has never been set), bitmap names are mapped to themselves. 1109# Nodes are mapped to their block device name if there is one, and 1110# to their node name otherwise. (Since 5.2) 1111# 1112# @x-vcpu-dirty-limit-period: Periodic time (in milliseconds) of dirty 1113# limit during live migration. Should be in the range 1 to 1114# 1000ms. Defaults to 1000ms. (Since 8.1) 1115# 1116# @vcpu-dirty-limit: Dirtyrate limit (MB/s) during live migration. 1117# Defaults to 1. (Since 8.1) 1118# 1119# @mode: Migration mode. See description in @MigMode. Default is 1120# 'normal'. (Since 8.2) 1121# 1122# @zero-page-detection: Whether and how to detect zero pages. 1123# See description in @ZeroPageDetection. Default is 'multifd'. 1124# (since 9.0) 1125# 1126# Features: 1127# 1128# @deprecated: Member @block-incremental is deprecated. Use 1129# blockdev-mirror with NBD instead. Members @compress-level, 1130# @compress-threads, @decompress-threads and @compress-wait-thread 1131# are deprecated because @compression is deprecated. 1132# 1133# @unstable: Members @x-checkpoint-delay and 1134# @x-vcpu-dirty-limit-period are experimental. 1135# 1136# TODO: either fuse back into MigrationParameters, or make 1137# MigrationParameters members mandatory 1138# 1139# Since: 2.4 1140## 1141{ 'struct': 'MigrateSetParameters', 1142 'data': { '*announce-initial': 'size', 1143 '*announce-max': 'size', 1144 '*announce-rounds': 'size', 1145 '*announce-step': 'size', 1146 '*compress-level': { 'type': 'uint8', 1147 'features': [ 'deprecated' ] }, 1148 '*compress-threads': { 'type': 'uint8', 1149 'features': [ 'deprecated' ] }, 1150 '*compress-wait-thread': { 'type': 'bool', 1151 'features': [ 'deprecated' ] }, 1152 '*decompress-threads': { 'type': 'uint8', 1153 'features': [ 'deprecated' ] }, 1154 '*throttle-trigger-threshold': 'uint8', 1155 '*cpu-throttle-initial': 'uint8', 1156 '*cpu-throttle-increment': 'uint8', 1157 '*cpu-throttle-tailslow': 'bool', 1158 '*tls-creds': 'StrOrNull', 1159 '*tls-hostname': 'StrOrNull', 1160 '*tls-authz': 'StrOrNull', 1161 '*max-bandwidth': 'size', 1162 '*avail-switchover-bandwidth': 'size', 1163 '*downtime-limit': 'uint64', 1164 '*x-checkpoint-delay': { 'type': 'uint32', 1165 'features': [ 'unstable' ] }, 1166 '*block-incremental': { 'type': 'bool', 1167 'features': [ 'deprecated' ] }, 1168 '*multifd-channels': 'uint8', 1169 '*xbzrle-cache-size': 'size', 1170 '*max-postcopy-bandwidth': 'size', 1171 '*max-cpu-throttle': 'uint8', 1172 '*multifd-compression': 'MultiFDCompression', 1173 '*multifd-zlib-level': 'uint8', 1174 '*multifd-zstd-level': 'uint8', 1175 '*block-bitmap-mapping': [ 'BitmapMigrationNodeAlias' ], 1176 '*x-vcpu-dirty-limit-period': { 'type': 'uint64', 1177 'features': [ 'unstable' ] }, 1178 '*vcpu-dirty-limit': 'uint64', 1179 '*mode': 'MigMode', 1180 '*zero-page-detection': 'ZeroPageDetection'} } 1181 1182## 1183# @migrate-set-parameters: 1184# 1185# Set various migration parameters. 1186# 1187# Since: 2.4 1188# 1189# Example: 1190# 1191# -> { "execute": "migrate-set-parameters" , 1192# "arguments": { "multifd-channels": 5 } } 1193# <- { "return": {} } 1194## 1195{ 'command': 'migrate-set-parameters', 'boxed': true, 1196 'data': 'MigrateSetParameters' } 1197 1198## 1199# @MigrationParameters: 1200# 1201# The optional members aren't actually optional. 1202# 1203# @announce-initial: Initial delay (in milliseconds) before sending 1204# the first announce (Since 4.0) 1205# 1206# @announce-max: Maximum delay (in milliseconds) between packets in 1207# the announcement (Since 4.0) 1208# 1209# @announce-rounds: Number of self-announce packets sent after 1210# migration (Since 4.0) 1211# 1212# @announce-step: Increase in delay (in milliseconds) between 1213# subsequent packets in the announcement (Since 4.0) 1214# 1215# @compress-level: compression level 1216# 1217# @compress-threads: compression thread count 1218# 1219# @compress-wait-thread: Controls behavior when all compression 1220# threads are currently busy. If true (default), wait for a free 1221# compression thread to become available; otherwise, send the page 1222# uncompressed. (Since 3.1) 1223# 1224# @decompress-threads: decompression thread count 1225# 1226# @throttle-trigger-threshold: The ratio of bytes_dirty_period and 1227# bytes_xfer_period to trigger throttling. It is expressed as 1228# percentage. The default value is 50. (Since 5.0) 1229# 1230# @cpu-throttle-initial: Initial percentage of time guest cpus are 1231# throttled when migration auto-converge is activated. (Since 1232# 2.7) 1233# 1234# @cpu-throttle-increment: throttle percentage increase each time 1235# auto-converge detects that migration is not making progress. 1236# (Since 2.7) 1237# 1238# @cpu-throttle-tailslow: Make CPU throttling slower at tail stage At 1239# the tail stage of throttling, the Guest is very sensitive to CPU 1240# percentage while the @cpu-throttle -increment is excessive 1241# usually at tail stage. If this parameter is true, we will 1242# compute the ideal CPU percentage used by the Guest, which may 1243# exactly make the dirty rate match the dirty rate threshold. 1244# Then we will choose a smaller throttle increment between the one 1245# specified by @cpu-throttle-increment and the one generated by 1246# ideal CPU percentage. Therefore, it is compatible to 1247# traditional throttling, meanwhile the throttle increment won't 1248# be excessive at tail stage. The default value is false. (Since 1249# 5.1) 1250# 1251# @tls-creds: ID of the 'tls-creds' object that provides credentials 1252# for establishing a TLS connection over the migration data 1253# channel. On the outgoing side of the migration, the credentials 1254# must be for a 'client' endpoint, while for the incoming side the 1255# credentials must be for a 'server' endpoint. An empty string 1256# means that QEMU will use plain text mode for migration, rather 1257# than TLS. (Since 2.7) 1258# 1259# Note: 2.8 omits empty @tls-creds instead. 1260# 1261# @tls-hostname: migration target's hostname for validating the 1262# server's x509 certificate identity. If empty, QEMU will use the 1263# hostname from the migration URI, if any. (Since 2.7) 1264# 1265# Note: 2.8 omits empty @tls-hostname instead. 1266# 1267# @tls-authz: ID of the 'authz' object subclass that provides access 1268# control checking of the TLS x509 certificate distinguished name. 1269# (Since 4.0) 1270# 1271# @max-bandwidth: maximum speed for migration, in bytes per second. 1272# (Since 2.8) 1273# 1274# @avail-switchover-bandwidth: to set the available bandwidth that 1275# migration can use during switchover phase. NOTE! This does not 1276# limit the bandwidth during switchover, but only for calculations 1277# when making decisions to switchover. By default, this value is 1278# zero, which means QEMU will estimate the bandwidth 1279# automatically. This can be set when the estimated value is not 1280# accurate, while the user is able to guarantee such bandwidth is 1281# available when switching over. When specified correctly, this 1282# can make the switchover decision much more accurate. 1283# (Since 8.2) 1284# 1285# @downtime-limit: set maximum tolerated downtime for migration. 1286# maximum downtime in milliseconds (Since 2.8) 1287# 1288# @x-checkpoint-delay: the delay time between two COLO checkpoints. 1289# (Since 2.8) 1290# 1291# @block-incremental: Affects how much storage is migrated when the 1292# block migration capability is enabled. When false, the entire 1293# storage backing chain is migrated into a flattened image at the 1294# destination; when true, only the active qcow2 layer is migrated 1295# and the destination must already have access to the same backing 1296# chain as was used on the source. (since 2.10) 1297# 1298# @multifd-channels: Number of channels used to migrate data in 1299# parallel. This is the same number that the number of sockets 1300# used for migration. The default value is 2 (since 4.0) 1301# 1302# @xbzrle-cache-size: cache size to be used by XBZRLE migration. It 1303# needs to be a multiple of the target page size and a power of 2 1304# (Since 2.11) 1305# 1306# @max-postcopy-bandwidth: Background transfer bandwidth during 1307# postcopy. Defaults to 0 (unlimited). In bytes per second. 1308# (Since 3.0) 1309# 1310# @max-cpu-throttle: maximum cpu throttle percentage. Defaults to 99. 1311# (Since 3.1) 1312# 1313# @multifd-compression: Which compression method to use. Defaults to 1314# none. (Since 5.0) 1315# 1316# @multifd-zlib-level: Set the compression level to be used in live 1317# migration, the compression level is an integer between 0 and 9, 1318# where 0 means no compression, 1 means the best compression 1319# speed, and 9 means best compression ratio which will consume 1320# more CPU. Defaults to 1. (Since 5.0) 1321# 1322# @multifd-zstd-level: Set the compression level to be used in live 1323# migration, the compression level is an integer between 0 and 20, 1324# where 0 means no compression, 1 means the best compression 1325# speed, and 20 means best compression ratio which will consume 1326# more CPU. Defaults to 1. (Since 5.0) 1327# 1328# @block-bitmap-mapping: Maps block nodes and bitmaps on them to 1329# aliases for the purpose of dirty bitmap migration. Such aliases 1330# may for example be the corresponding names on the opposite site. 1331# The mapping must be one-to-one, but not necessarily complete: On 1332# the source, unmapped bitmaps and all bitmaps on unmapped nodes 1333# will be ignored. On the destination, encountering an unmapped 1334# alias in the incoming migration stream will result in a report, 1335# and all further bitmap migration data will then be discarded. 1336# Note that the destination does not know about bitmaps it does 1337# not receive, so there is no limitation or requirement regarding 1338# the number of bitmaps received, or how they are named, or on 1339# which nodes they are placed. By default (when this parameter 1340# has never been set), bitmap names are mapped to themselves. 1341# Nodes are mapped to their block device name if there is one, and 1342# to their node name otherwise. (Since 5.2) 1343# 1344# @x-vcpu-dirty-limit-period: Periodic time (in milliseconds) of dirty 1345# limit during live migration. Should be in the range 1 to 1346# 1000ms. Defaults to 1000ms. (Since 8.1) 1347# 1348# @vcpu-dirty-limit: Dirtyrate limit (MB/s) during live migration. 1349# Defaults to 1. (Since 8.1) 1350# 1351# @mode: Migration mode. See description in @MigMode. Default is 1352# 'normal'. (Since 8.2) 1353# 1354# @zero-page-detection: Whether and how to detect zero pages. 1355# See description in @ZeroPageDetection. Default is 'multifd'. 1356# (since 9.0) 1357# 1358# Features: 1359# 1360# @deprecated: Member @block-incremental is deprecated. Use 1361# blockdev-mirror with NBD instead. Members @compress-level, 1362# @compress-threads, @decompress-threads and @compress-wait-thread 1363# are deprecated because @compression is deprecated. 1364# 1365# @unstable: Members @x-checkpoint-delay and 1366# @x-vcpu-dirty-limit-period are experimental. 1367# 1368# Since: 2.4 1369## 1370{ 'struct': 'MigrationParameters', 1371 'data': { '*announce-initial': 'size', 1372 '*announce-max': 'size', 1373 '*announce-rounds': 'size', 1374 '*announce-step': 'size', 1375 '*compress-level': { 'type': 'uint8', 1376 'features': [ 'deprecated' ] }, 1377 '*compress-threads': { 'type': 'uint8', 1378 'features': [ 'deprecated' ] }, 1379 '*compress-wait-thread': { 'type': 'bool', 1380 'features': [ 'deprecated' ] }, 1381 '*decompress-threads': { 'type': 'uint8', 1382 'features': [ 'deprecated' ] }, 1383 '*throttle-trigger-threshold': 'uint8', 1384 '*cpu-throttle-initial': 'uint8', 1385 '*cpu-throttle-increment': 'uint8', 1386 '*cpu-throttle-tailslow': 'bool', 1387 '*tls-creds': 'str', 1388 '*tls-hostname': 'str', 1389 '*tls-authz': 'str', 1390 '*max-bandwidth': 'size', 1391 '*avail-switchover-bandwidth': 'size', 1392 '*downtime-limit': 'uint64', 1393 '*x-checkpoint-delay': { 'type': 'uint32', 1394 'features': [ 'unstable' ] }, 1395 '*block-incremental': { 'type': 'bool', 1396 'features': [ 'deprecated' ] }, 1397 '*multifd-channels': 'uint8', 1398 '*xbzrle-cache-size': 'size', 1399 '*max-postcopy-bandwidth': 'size', 1400 '*max-cpu-throttle': 'uint8', 1401 '*multifd-compression': 'MultiFDCompression', 1402 '*multifd-zlib-level': 'uint8', 1403 '*multifd-zstd-level': 'uint8', 1404 '*block-bitmap-mapping': [ 'BitmapMigrationNodeAlias' ], 1405 '*x-vcpu-dirty-limit-period': { 'type': 'uint64', 1406 'features': [ 'unstable' ] }, 1407 '*vcpu-dirty-limit': 'uint64', 1408 '*mode': 'MigMode', 1409 '*zero-page-detection': 'ZeroPageDetection'} } 1410 1411## 1412# @query-migrate-parameters: 1413# 1414# Returns information about the current migration parameters 1415# 1416# Returns: @MigrationParameters 1417# 1418# Since: 2.4 1419# 1420# Example: 1421# 1422# -> { "execute": "query-migrate-parameters" } 1423# <- { "return": { 1424# "multifd-channels": 2, 1425# "cpu-throttle-increment": 10, 1426# "cpu-throttle-initial": 20, 1427# "max-bandwidth": 33554432, 1428# "downtime-limit": 300 1429# } 1430# } 1431## 1432{ 'command': 'query-migrate-parameters', 1433 'returns': 'MigrationParameters' } 1434 1435## 1436# @migrate-start-postcopy: 1437# 1438# Followup to a migration command to switch the migration to postcopy 1439# mode. The postcopy-ram capability must be set on both source and 1440# destination before the original migration command. 1441# 1442# Since: 2.5 1443# 1444# Example: 1445# 1446# -> { "execute": "migrate-start-postcopy" } 1447# <- { "return": {} } 1448## 1449{ 'command': 'migrate-start-postcopy' } 1450 1451## 1452# @MIGRATION: 1453# 1454# Emitted when a migration event happens 1455# 1456# @status: @MigrationStatus describing the current migration status. 1457# 1458# Since: 2.4 1459# 1460# Example: 1461# 1462# <- {"timestamp": {"seconds": 1432121972, "microseconds": 744001}, 1463# "event": "MIGRATION", 1464# "data": {"status": "completed"} } 1465## 1466{ 'event': 'MIGRATION', 1467 'data': {'status': 'MigrationStatus'}} 1468 1469## 1470# @MIGRATION_PASS: 1471# 1472# Emitted from the source side of a migration at the start of each 1473# pass (when it syncs the dirty bitmap) 1474# 1475# @pass: An incrementing count (starting at 1 on the first pass) 1476# 1477# Since: 2.6 1478# 1479# Example: 1480# 1481# <- { "timestamp": {"seconds": 1449669631, "microseconds": 239225}, 1482# "event": "MIGRATION_PASS", "data": {"pass": 2} } 1483## 1484{ 'event': 'MIGRATION_PASS', 1485 'data': { 'pass': 'int' } } 1486 1487## 1488# @COLOMessage: 1489# 1490# The message transmission between Primary side and Secondary side. 1491# 1492# @checkpoint-ready: Secondary VM (SVM) is ready for checkpointing 1493# 1494# @checkpoint-request: Primary VM (PVM) tells SVM to prepare for 1495# checkpointing 1496# 1497# @checkpoint-reply: SVM gets PVM's checkpoint request 1498# 1499# @vmstate-send: VM's state will be sent by PVM. 1500# 1501# @vmstate-size: The total size of VMstate. 1502# 1503# @vmstate-received: VM's state has been received by SVM. 1504# 1505# @vmstate-loaded: VM's state has been loaded by SVM. 1506# 1507# Since: 2.8 1508## 1509{ 'enum': 'COLOMessage', 1510 'data': [ 'checkpoint-ready', 'checkpoint-request', 'checkpoint-reply', 1511 'vmstate-send', 'vmstate-size', 'vmstate-received', 1512 'vmstate-loaded' ] } 1513 1514## 1515# @COLOMode: 1516# 1517# The COLO current mode. 1518# 1519# @none: COLO is disabled. 1520# 1521# @primary: COLO node in primary side. 1522# 1523# @secondary: COLO node in slave side. 1524# 1525# Since: 2.8 1526## 1527{ 'enum': 'COLOMode', 1528 'data': [ 'none', 'primary', 'secondary'] } 1529 1530## 1531# @FailoverStatus: 1532# 1533# An enumeration of COLO failover status 1534# 1535# @none: no failover has ever happened 1536# 1537# @require: got failover requirement but not handled 1538# 1539# @active: in the process of doing failover 1540# 1541# @completed: finish the process of failover 1542# 1543# @relaunch: restart the failover process, from 'none' -> 'completed' 1544# (Since 2.9) 1545# 1546# Since: 2.8 1547## 1548{ 'enum': 'FailoverStatus', 1549 'data': [ 'none', 'require', 'active', 'completed', 'relaunch' ] } 1550 1551## 1552# @COLO_EXIT: 1553# 1554# Emitted when VM finishes COLO mode due to some errors happening or 1555# at the request of users. 1556# 1557# @mode: report COLO mode when COLO exited. 1558# 1559# @reason: describes the reason for the COLO exit. 1560# 1561# Since: 3.1 1562# 1563# Example: 1564# 1565# <- { "timestamp": {"seconds": 2032141960, "microseconds": 417172}, 1566# "event": "COLO_EXIT", "data": {"mode": "primary", "reason": "request" } } 1567## 1568{ 'event': 'COLO_EXIT', 1569 'data': {'mode': 'COLOMode', 'reason': 'COLOExitReason' } } 1570 1571## 1572# @COLOExitReason: 1573# 1574# The reason for a COLO exit. 1575# 1576# @none: failover has never happened. This state does not occur in 1577# the COLO_EXIT event, and is only visible in the result of 1578# query-colo-status. 1579# 1580# @request: COLO exit is due to an external request. 1581# 1582# @error: COLO exit is due to an internal error. 1583# 1584# @processing: COLO is currently handling a failover (since 4.0). 1585# 1586# Since: 3.1 1587## 1588{ 'enum': 'COLOExitReason', 1589 'data': [ 'none', 'request', 'error' , 'processing' ] } 1590 1591## 1592# @x-colo-lost-heartbeat: 1593# 1594# Tell qemu that heartbeat is lost, request it to do takeover 1595# procedures. If this command is sent to the PVM, the Primary side 1596# will exit COLO mode. If sent to the Secondary, the Secondary side 1597# will run failover work, then takes over server operation to become 1598# the service VM. 1599# 1600# Features: 1601# 1602# @unstable: This command is experimental. 1603# 1604# Since: 2.8 1605# 1606# Example: 1607# 1608# -> { "execute": "x-colo-lost-heartbeat" } 1609# <- { "return": {} } 1610## 1611{ 'command': 'x-colo-lost-heartbeat', 1612 'features': [ 'unstable' ], 1613 'if': 'CONFIG_REPLICATION' } 1614 1615## 1616# @migrate_cancel: 1617# 1618# Cancel the current executing migration process. 1619# 1620# Notes: This command succeeds even if there is no migration process 1621# running. 1622# 1623# Since: 0.14 1624# 1625# Example: 1626# 1627# -> { "execute": "migrate_cancel" } 1628# <- { "return": {} } 1629## 1630{ 'command': 'migrate_cancel' } 1631 1632## 1633# @migrate-continue: 1634# 1635# Continue migration when it's in a paused state. 1636# 1637# @state: The state the migration is currently expected to be in 1638# 1639# Since: 2.11 1640# 1641# Example: 1642# 1643# -> { "execute": "migrate-continue" , "arguments": 1644# { "state": "pre-switchover" } } 1645# <- { "return": {} } 1646## 1647{ 'command': 'migrate-continue', 'data': {'state': 'MigrationStatus'} } 1648 1649## 1650# @MigrationAddressType: 1651# 1652# The migration stream transport mechanisms. 1653# 1654# @socket: Migrate via socket. 1655# 1656# @exec: Direct the migration stream to another process. 1657# 1658# @rdma: Migrate via RDMA. 1659# 1660# @file: Direct the migration stream to a file. 1661# 1662# Since: 8.2 1663## 1664{ 'enum': 'MigrationAddressType', 1665 'data': [ 'socket', 'exec', 'rdma', 'file' ] } 1666 1667## 1668# @FileMigrationArgs: 1669# 1670# @filename: The file to receive the migration stream 1671# 1672# @offset: The file offset where the migration stream will start 1673# 1674# Since: 8.2 1675## 1676{ 'struct': 'FileMigrationArgs', 1677 'data': { 'filename': 'str', 1678 'offset': 'uint64' } } 1679 1680## 1681# @MigrationExecCommand: 1682# 1683# @args: command (list head) and arguments to execute. 1684# 1685# Since: 8.2 1686## 1687{ 'struct': 'MigrationExecCommand', 1688 'data': {'args': [ 'str' ] } } 1689 1690## 1691# @MigrationAddress: 1692# 1693# Migration endpoint configuration. 1694# 1695# @transport: The migration stream transport mechanism 1696# 1697# Since: 8.2 1698## 1699{ 'union': 'MigrationAddress', 1700 'base': { 'transport' : 'MigrationAddressType'}, 1701 'discriminator': 'transport', 1702 'data': { 1703 'socket': 'SocketAddress', 1704 'exec': 'MigrationExecCommand', 1705 'rdma': 'InetSocketAddress', 1706 'file': 'FileMigrationArgs' } } 1707 1708## 1709# @MigrationChannelType: 1710# 1711# The migration channel-type request options. 1712# 1713# @main: Main outbound migration channel. 1714# 1715# Since: 8.1 1716## 1717{ 'enum': 'MigrationChannelType', 1718 'data': [ 'main' ] } 1719 1720## 1721# @MigrationChannel: 1722# 1723# Migration stream channel parameters. 1724# 1725# @channel-type: Channel type for transferring packet information. 1726# 1727# @addr: Migration endpoint configuration on destination interface. 1728# 1729# Since: 8.1 1730## 1731{ 'struct': 'MigrationChannel', 1732 'data': { 1733 'channel-type': 'MigrationChannelType', 1734 'addr': 'MigrationAddress' } } 1735 1736## 1737# @migrate: 1738# 1739# Migrates the current running guest to another Virtual Machine. 1740# 1741# @uri: the Uniform Resource Identifier of the destination VM 1742# 1743# @channels: list of migration stream channels with each stream in the 1744# list connected to a destination interface endpoint. 1745# 1746# @blk: do block migration (full disk copy) 1747# 1748# @inc: incremental disk copy migration 1749# 1750# @detach: this argument exists only for compatibility reasons and is 1751# ignored by QEMU 1752# 1753# @resume: resume one paused migration, default "off". (since 3.0) 1754# 1755# Features: 1756# 1757# @deprecated: Members @inc and @blk are deprecated. Use 1758# blockdev-mirror with NBD instead. 1759# 1760# Since: 0.14 1761# 1762# Notes: 1763# 1764# 1. The 'query-migrate' command should be used to check 1765# migration's progress and final result (this information is 1766# provided by the 'status' member) 1767# 1768# 2. All boolean arguments default to false 1769# 1770# 3. The user Monitor's "detach" argument is invalid in QMP and 1771# should not be used 1772# 1773# 4. The uri argument should have the Uniform Resource Identifier 1774# of default destination VM. This connection will be bound to 1775# default network. 1776# 1777# 5. For now, number of migration streams is restricted to one, 1778# i.e. number of items in 'channels' list is just 1. 1779# 1780# 6. The 'uri' and 'channels' arguments are mutually exclusive; 1781# exactly one of the two should be present. 1782# 1783# Example: 1784# 1785# -> { "execute": "migrate", "arguments": { "uri": "tcp:0:4446" } } 1786# <- { "return": {} } 1787# 1788# -> { "execute": "migrate", 1789# "arguments": { 1790# "channels": [ { "channel-type": "main", 1791# "addr": { "transport": "socket", 1792# "type": "inet", 1793# "host": "10.12.34.9", 1794# "port": "1050" } } ] } } 1795# <- { "return": {} } 1796# 1797# -> { "execute": "migrate", 1798# "arguments": { 1799# "channels": [ { "channel-type": "main", 1800# "addr": { "transport": "exec", 1801# "args": [ "/bin/nc", "-p", "6000", 1802# "/some/sock" ] } } ] } } 1803# <- { "return": {} } 1804# 1805# -> { "execute": "migrate", 1806# "arguments": { 1807# "channels": [ { "channel-type": "main", 1808# "addr": { "transport": "rdma", 1809# "host": "10.12.34.9", 1810# "port": "1050" } } ] } } 1811# <- { "return": {} } 1812# 1813# -> { "execute": "migrate", 1814# "arguments": { 1815# "channels": [ { "channel-type": "main", 1816# "addr": { "transport": "file", 1817# "filename": "/tmp/migfile", 1818# "offset": "0x1000" } } ] } } 1819# <- { "return": {} } 1820# 1821## 1822{ 'command': 'migrate', 1823 'data': {'*uri': 'str', 1824 '*channels': [ 'MigrationChannel' ], 1825 '*blk': { 'type': 'bool', 'features': [ 'deprecated' ] }, 1826 '*inc': { 'type': 'bool', 'features': [ 'deprecated' ] }, 1827 '*detach': 'bool', '*resume': 'bool' } } 1828 1829## 1830# @migrate-incoming: 1831# 1832# Start an incoming migration, the qemu must have been started with 1833# -incoming defer 1834# 1835# @uri: The Uniform Resource Identifier identifying the source or 1836# address to listen on 1837# 1838# @channels: list of migration stream channels with each stream in the 1839# list connected to a destination interface endpoint. 1840# 1841# Since: 2.3 1842# 1843# Notes: 1844# 1845# 1. It's a bad idea to use a string for the uri, but it needs to 1846# stay compatible with -incoming and the format of the uri is 1847# already exposed above libvirt. 1848# 1849# 2. QEMU must be started with -incoming defer to allow 1850# migrate-incoming to be used. 1851# 1852# 3. The uri format is the same as for -incoming 1853# 1854# 4. For now, number of migration streams is restricted to one, 1855# i.e. number of items in 'channels' list is just 1. 1856# 1857# 5. The 'uri' and 'channels' arguments are mutually exclusive; 1858# exactly one of the two should be present. 1859# 1860# Example: 1861# 1862# -> { "execute": "migrate-incoming", 1863# "arguments": { "uri": "tcp:0:4446" } } 1864# <- { "return": {} } 1865# 1866# -> { "execute": "migrate-incoming", 1867# "arguments": { 1868# "channels": [ { "channel-type": "main", 1869# "addr": { "transport": "socket", 1870# "type": "inet", 1871# "host": "10.12.34.9", 1872# "port": "1050" } } ] } } 1873# <- { "return": {} } 1874# 1875# -> { "execute": "migrate-incoming", 1876# "arguments": { 1877# "channels": [ { "channel-type": "main", 1878# "addr": { "transport": "exec", 1879# "args": [ "/bin/nc", "-p", "6000", 1880# "/some/sock" ] } } ] } } 1881# <- { "return": {} } 1882# 1883# -> { "execute": "migrate-incoming", 1884# "arguments": { 1885# "channels": [ { "channel-type": "main", 1886# "addr": { "transport": "rdma", 1887# "host": "10.12.34.9", 1888# "port": "1050" } } ] } } 1889# <- { "return": {} } 1890## 1891{ 'command': 'migrate-incoming', 1892 'data': {'*uri': 'str', 1893 '*channels': [ 'MigrationChannel' ] } } 1894 1895## 1896# @xen-save-devices-state: 1897# 1898# Save the state of all devices to file. The RAM and the block 1899# devices of the VM are not saved by this command. 1900# 1901# @filename: the file to save the state of the devices to as binary 1902# data. See xen-save-devices-state.txt for a description of the 1903# binary format. 1904# 1905# @live: Optional argument to ask QEMU to treat this command as part 1906# of a live migration. Default to true. (since 2.11) 1907# 1908# Since: 1.1 1909# 1910# Example: 1911# 1912# -> { "execute": "xen-save-devices-state", 1913# "arguments": { "filename": "/tmp/save" } } 1914# <- { "return": {} } 1915## 1916{ 'command': 'xen-save-devices-state', 1917 'data': {'filename': 'str', '*live':'bool' } } 1918 1919## 1920# @xen-set-global-dirty-log: 1921# 1922# Enable or disable the global dirty log mode. 1923# 1924# @enable: true to enable, false to disable. 1925# 1926# Since: 1.3 1927# 1928# Example: 1929# 1930# -> { "execute": "xen-set-global-dirty-log", 1931# "arguments": { "enable": true } } 1932# <- { "return": {} } 1933## 1934{ 'command': 'xen-set-global-dirty-log', 'data': { 'enable': 'bool' } } 1935 1936## 1937# @xen-load-devices-state: 1938# 1939# Load the state of all devices from file. The RAM and the block 1940# devices of the VM are not loaded by this command. 1941# 1942# @filename: the file to load the state of the devices from as binary 1943# data. See xen-save-devices-state.txt for a description of the 1944# binary format. 1945# 1946# Since: 2.7 1947# 1948# Example: 1949# 1950# -> { "execute": "xen-load-devices-state", 1951# "arguments": { "filename": "/tmp/resume" } } 1952# <- { "return": {} } 1953## 1954{ 'command': 'xen-load-devices-state', 'data': {'filename': 'str'} } 1955 1956## 1957# @xen-set-replication: 1958# 1959# Enable or disable replication. 1960# 1961# @enable: true to enable, false to disable. 1962# 1963# @primary: true for primary or false for secondary. 1964# 1965# @failover: true to do failover, false to stop. Cannot be specified 1966# if 'enable' is true. Default value is false. 1967# 1968# Example: 1969# 1970# -> { "execute": "xen-set-replication", 1971# "arguments": {"enable": true, "primary": false} } 1972# <- { "return": {} } 1973# 1974# Since: 2.9 1975## 1976{ 'command': 'xen-set-replication', 1977 'data': { 'enable': 'bool', 'primary': 'bool', '*failover': 'bool' }, 1978 'if': 'CONFIG_REPLICATION' } 1979 1980## 1981# @ReplicationStatus: 1982# 1983# The result format for 'query-xen-replication-status'. 1984# 1985# @error: true if an error happened, false if replication is normal. 1986# 1987# @desc: the human readable error description string, when @error is 1988# 'true'. 1989# 1990# Since: 2.9 1991## 1992{ 'struct': 'ReplicationStatus', 1993 'data': { 'error': 'bool', '*desc': 'str' }, 1994 'if': 'CONFIG_REPLICATION' } 1995 1996## 1997# @query-xen-replication-status: 1998# 1999# Query replication status while the vm is running. 2000# 2001# Returns: A @ReplicationStatus object showing the status. 2002# 2003# Example: 2004# 2005# -> { "execute": "query-xen-replication-status" } 2006# <- { "return": { "error": false } } 2007# 2008# Since: 2.9 2009## 2010{ 'command': 'query-xen-replication-status', 2011 'returns': 'ReplicationStatus', 2012 'if': 'CONFIG_REPLICATION' } 2013 2014## 2015# @xen-colo-do-checkpoint: 2016# 2017# Xen uses this command to notify replication to trigger a checkpoint. 2018# 2019# Example: 2020# 2021# -> { "execute": "xen-colo-do-checkpoint" } 2022# <- { "return": {} } 2023# 2024# Since: 2.9 2025## 2026{ 'command': 'xen-colo-do-checkpoint', 2027 'if': 'CONFIG_REPLICATION' } 2028 2029## 2030# @COLOStatus: 2031# 2032# The result format for 'query-colo-status'. 2033# 2034# @mode: COLO running mode. If COLO is running, this field will 2035# return 'primary' or 'secondary'. 2036# 2037# @last-mode: COLO last running mode. If COLO is running, this field 2038# will return same like mode field, after failover we can use this 2039# field to get last colo mode. (since 4.0) 2040# 2041# @reason: describes the reason for the COLO exit. 2042# 2043# Since: 3.1 2044## 2045{ 'struct': 'COLOStatus', 2046 'data': { 'mode': 'COLOMode', 'last-mode': 'COLOMode', 2047 'reason': 'COLOExitReason' }, 2048 'if': 'CONFIG_REPLICATION' } 2049 2050## 2051# @query-colo-status: 2052# 2053# Query COLO status while the vm is running. 2054# 2055# Returns: A @COLOStatus object showing the status. 2056# 2057# Example: 2058# 2059# -> { "execute": "query-colo-status" } 2060# <- { "return": { "mode": "primary", "last-mode": "none", "reason": "request" } } 2061# 2062# Since: 3.1 2063## 2064{ 'command': 'query-colo-status', 2065 'returns': 'COLOStatus', 2066 'if': 'CONFIG_REPLICATION' } 2067 2068## 2069# @migrate-recover: 2070# 2071# Provide a recovery migration stream URI. 2072# 2073# @uri: the URI to be used for the recovery of migration stream. 2074# 2075# Example: 2076# 2077# -> { "execute": "migrate-recover", 2078# "arguments": { "uri": "tcp:192.168.1.200:12345" } } 2079# <- { "return": {} } 2080# 2081# Since: 3.0 2082## 2083{ 'command': 'migrate-recover', 2084 'data': { 'uri': 'str' }, 2085 'allow-oob': true } 2086 2087## 2088# @migrate-pause: 2089# 2090# Pause a migration. Currently it only supports postcopy. 2091# 2092# Example: 2093# 2094# -> { "execute": "migrate-pause" } 2095# <- { "return": {} } 2096# 2097# Since: 3.0 2098## 2099{ 'command': 'migrate-pause', 'allow-oob': true } 2100 2101## 2102# @UNPLUG_PRIMARY: 2103# 2104# Emitted from source side of a migration when migration state is 2105# WAIT_UNPLUG. Device was unplugged by guest operating system. Device 2106# resources in QEMU are kept on standby to be able to re-plug it in 2107# case of migration failure. 2108# 2109# @device-id: QEMU device id of the unplugged device 2110# 2111# Since: 4.2 2112# 2113# Example: 2114# 2115# <- { "event": "UNPLUG_PRIMARY", 2116# "data": { "device-id": "hostdev0" }, 2117# "timestamp": { "seconds": 1265044230, "microseconds": 450486 } } 2118## 2119{ 'event': 'UNPLUG_PRIMARY', 2120 'data': { 'device-id': 'str' } } 2121 2122## 2123# @DirtyRateVcpu: 2124# 2125# Dirty rate of vcpu. 2126# 2127# @id: vcpu index. 2128# 2129# @dirty-rate: dirty rate. 2130# 2131# Since: 6.2 2132## 2133{ 'struct': 'DirtyRateVcpu', 2134 'data': { 'id': 'int', 'dirty-rate': 'int64' } } 2135 2136## 2137# @DirtyRateStatus: 2138# 2139# Dirty page rate measurement status. 2140# 2141# @unstarted: measuring thread has not been started yet 2142# 2143# @measuring: measuring thread is running 2144# 2145# @measured: dirty page rate is measured and the results are available 2146# 2147# Since: 5.2 2148## 2149{ 'enum': 'DirtyRateStatus', 2150 'data': [ 'unstarted', 'measuring', 'measured'] } 2151 2152## 2153# @DirtyRateMeasureMode: 2154# 2155# Method used to measure dirty page rate. Differences between 2156# available methods are explained in @calc-dirty-rate. 2157# 2158# @page-sampling: use page sampling 2159# 2160# @dirty-ring: use dirty ring 2161# 2162# @dirty-bitmap: use dirty bitmap 2163# 2164# Since: 6.2 2165## 2166{ 'enum': 'DirtyRateMeasureMode', 2167 'data': ['page-sampling', 'dirty-ring', 'dirty-bitmap'] } 2168 2169## 2170# @TimeUnit: 2171# 2172# Specifies unit in which time-related value is specified. 2173# 2174# @second: value is in seconds 2175# 2176# @millisecond: value is in milliseconds 2177# 2178# Since: 8.2 2179# 2180## 2181{ 'enum': 'TimeUnit', 2182 'data': ['second', 'millisecond'] } 2183 2184## 2185# @DirtyRateInfo: 2186# 2187# Information about measured dirty page rate. 2188# 2189# @dirty-rate: an estimate of the dirty page rate of the VM in units 2190# of MiB/s. Value is present only when @status is 'measured'. 2191# 2192# @status: current status of dirty page rate measurements 2193# 2194# @start-time: start time in units of second for calculation 2195# 2196# @calc-time: time period for which dirty page rate was measured, 2197# expressed and rounded down to @calc-time-unit. 2198# 2199# @calc-time-unit: time unit of @calc-time (Since 8.2) 2200# 2201# @sample-pages: number of sampled pages per GiB of guest memory. 2202# Valid only in page-sampling mode (Since 6.1) 2203# 2204# @mode: mode that was used to measure dirty page rate (Since 6.2) 2205# 2206# @vcpu-dirty-rate: dirty rate for each vCPU if dirty-ring mode was 2207# specified (Since 6.2) 2208# 2209# Since: 5.2 2210## 2211{ 'struct': 'DirtyRateInfo', 2212 'data': {'*dirty-rate': 'int64', 2213 'status': 'DirtyRateStatus', 2214 'start-time': 'int64', 2215 'calc-time': 'int64', 2216 'calc-time-unit': 'TimeUnit', 2217 'sample-pages': 'uint64', 2218 'mode': 'DirtyRateMeasureMode', 2219 '*vcpu-dirty-rate': [ 'DirtyRateVcpu' ] } } 2220 2221## 2222# @calc-dirty-rate: 2223# 2224# Start measuring dirty page rate of the VM. Results can be retrieved 2225# with @query-dirty-rate after measurements are completed. 2226# 2227# Dirty page rate is the number of pages changed in a given time 2228# period expressed in MiB/s. The following methods of calculation are 2229# available: 2230# 2231# 1. In page sampling mode, a random subset of pages are selected and 2232# hashed twice: once at the beginning of measurement time period, 2233# and once again at the end. If two hashes for some page are 2234# different, the page is counted as changed. Since this method 2235# relies on sampling and hashing, calculated dirty page rate is 2236# only an estimate of its true value. Increasing @sample-pages 2237# improves estimation quality at the cost of higher computational 2238# overhead. 2239# 2240# 2. Dirty bitmap mode captures writes to memory (for example by 2241# temporarily revoking write access to all pages) and counting page 2242# faults. Information about modified pages is collected into a 2243# bitmap, where each bit corresponds to one guest page. This mode 2244# requires that KVM accelerator property "dirty-ring-size" is *not* 2245# set. 2246# 2247# 3. Dirty ring mode is similar to dirty bitmap mode, but the 2248# information about modified pages is collected into ring buffer. 2249# This mode tracks page modification per each vCPU separately. It 2250# requires that KVM accelerator property "dirty-ring-size" is set. 2251# 2252# @calc-time: time period for which dirty page rate is calculated. 2253# By default it is specified in seconds, but the unit can be set 2254# explicitly with @calc-time-unit. Note that larger @calc-time 2255# values will typically result in smaller dirty page rates because 2256# page dirtying is a one-time event. Once some page is counted 2257# as dirty during @calc-time period, further writes to this page 2258# will not increase dirty page rate anymore. 2259# 2260# @calc-time-unit: time unit in which @calc-time is specified. 2261# By default it is seconds. (Since 8.2) 2262# 2263# @sample-pages: number of sampled pages per each GiB of guest memory. 2264# Default value is 512. For 4KiB guest pages this corresponds to 2265# sampling ratio of 0.2%. This argument is used only in page 2266# sampling mode. (Since 6.1) 2267# 2268# @mode: mechanism for tracking dirty pages. Default value is 2269# 'page-sampling'. Others are 'dirty-bitmap' and 'dirty-ring'. 2270# (Since 6.1) 2271# 2272# Since: 5.2 2273# 2274# Example: 2275# 2276# -> {"execute": "calc-dirty-rate", "arguments": {"calc-time": 1, 2277# 'sample-pages': 512} } 2278# <- { "return": {} } 2279# 2280# Measure dirty rate using dirty bitmap for 500 milliseconds: 2281# 2282# -> {"execute": "calc-dirty-rate", "arguments": {"calc-time": 500, 2283# "calc-time-unit": "millisecond", "mode": "dirty-bitmap"} } 2284# 2285# <- { "return": {} } 2286## 2287{ 'command': 'calc-dirty-rate', 'data': {'calc-time': 'int64', 2288 '*calc-time-unit': 'TimeUnit', 2289 '*sample-pages': 'int', 2290 '*mode': 'DirtyRateMeasureMode'} } 2291 2292## 2293# @query-dirty-rate: 2294# 2295# Query results of the most recent invocation of @calc-dirty-rate. 2296# 2297# @calc-time-unit: time unit in which to report calculation time. 2298# By default it is reported in seconds. (Since 8.2) 2299# 2300# Since: 5.2 2301# 2302# Examples: 2303# 2304# 1. Measurement is in progress: 2305# 2306# <- {"status": "measuring", "sample-pages": 512, 2307# "mode": "page-sampling", "start-time": 1693900454, "calc-time": 10, 2308# "calc-time-unit": "second"} 2309# 2310# 2. Measurement has been completed: 2311# 2312# <- {"status": "measured", "sample-pages": 512, "dirty-rate": 108, 2313# "mode": "page-sampling", "start-time": 1693900454, "calc-time": 10, 2314# "calc-time-unit": "second"} 2315## 2316{ 'command': 'query-dirty-rate', 'data': {'*calc-time-unit': 'TimeUnit' }, 2317 'returns': 'DirtyRateInfo' } 2318 2319## 2320# @DirtyLimitInfo: 2321# 2322# Dirty page rate limit information of a virtual CPU. 2323# 2324# @cpu-index: index of a virtual CPU. 2325# 2326# @limit-rate: upper limit of dirty page rate (MB/s) for a virtual 2327# CPU, 0 means unlimited. 2328# 2329# @current-rate: current dirty page rate (MB/s) for a virtual CPU. 2330# 2331# Since: 7.1 2332## 2333{ 'struct': 'DirtyLimitInfo', 2334 'data': { 'cpu-index': 'int', 2335 'limit-rate': 'uint64', 2336 'current-rate': 'uint64' } } 2337 2338## 2339# @set-vcpu-dirty-limit: 2340# 2341# Set the upper limit of dirty page rate for virtual CPUs. 2342# 2343# Requires KVM with accelerator property "dirty-ring-size" set. A 2344# virtual CPU's dirty page rate is a measure of its memory load. To 2345# observe dirty page rates, use @calc-dirty-rate. 2346# 2347# @cpu-index: index of a virtual CPU, default is all. 2348# 2349# @dirty-rate: upper limit of dirty page rate (MB/s) for virtual CPUs. 2350# 2351# Since: 7.1 2352# 2353# Example: 2354# 2355# -> {"execute": "set-vcpu-dirty-limit"} 2356# "arguments": { "dirty-rate": 200, 2357# "cpu-index": 1 } } 2358# <- { "return": {} } 2359## 2360{ 'command': 'set-vcpu-dirty-limit', 2361 'data': { '*cpu-index': 'int', 2362 'dirty-rate': 'uint64' } } 2363 2364## 2365# @cancel-vcpu-dirty-limit: 2366# 2367# Cancel the upper limit of dirty page rate for virtual CPUs. 2368# 2369# Cancel the dirty page limit for the vCPU which has been set with 2370# set-vcpu-dirty-limit command. Note that this command requires 2371# support from dirty ring, same as the "set-vcpu-dirty-limit". 2372# 2373# @cpu-index: index of a virtual CPU, default is all. 2374# 2375# Since: 7.1 2376# 2377# Example: 2378# 2379# -> {"execute": "cancel-vcpu-dirty-limit"}, 2380# "arguments": { "cpu-index": 1 } } 2381# <- { "return": {} } 2382## 2383{ 'command': 'cancel-vcpu-dirty-limit', 2384 'data': { '*cpu-index': 'int'} } 2385 2386## 2387# @query-vcpu-dirty-limit: 2388# 2389# Returns information about virtual CPU dirty page rate limits, if 2390# any. 2391# 2392# Since: 7.1 2393# 2394# Example: 2395# 2396# -> {"execute": "query-vcpu-dirty-limit"} 2397# <- {"return": [ 2398# { "limit-rate": 60, "current-rate": 3, "cpu-index": 0}, 2399# { "limit-rate": 60, "current-rate": 3, "cpu-index": 1}]} 2400## 2401{ 'command': 'query-vcpu-dirty-limit', 2402 'returns': [ 'DirtyLimitInfo' ] } 2403 2404## 2405# @MigrationThreadInfo: 2406# 2407# Information about migrationthreads 2408# 2409# @name: the name of migration thread 2410# 2411# @thread-id: ID of the underlying host thread 2412# 2413# Since: 7.2 2414## 2415{ 'struct': 'MigrationThreadInfo', 2416 'data': {'name': 'str', 2417 'thread-id': 'int'} } 2418 2419## 2420# @query-migrationthreads: 2421# 2422# Returns information of migration threads 2423# 2424# Returns: @MigrationThreadInfo 2425# 2426# Since: 7.2 2427## 2428{ 'command': 'query-migrationthreads', 2429 'returns': ['MigrationThreadInfo'] } 2430 2431## 2432# @snapshot-save: 2433# 2434# Save a VM snapshot 2435# 2436# @job-id: identifier for the newly created job 2437# 2438# @tag: name of the snapshot to create 2439# 2440# @vmstate: block device node name to save vmstate to 2441# 2442# @devices: list of block device node names to save a snapshot to 2443# 2444# Applications should not assume that the snapshot save is complete 2445# when this command returns. The job commands / events must be used 2446# to determine completion and to fetch details of any errors that 2447# arise. 2448# 2449# Note that execution of the guest CPUs may be stopped during the time 2450# it takes to save the snapshot. A future version of QEMU may ensure 2451# CPUs are executing continuously. 2452# 2453# It is strongly recommended that @devices contain all writable block 2454# device nodes if a consistent snapshot is required. 2455# 2456# If @tag already exists, an error will be reported 2457# 2458# Example: 2459# 2460# -> { "execute": "snapshot-save", 2461# "arguments": { 2462# "job-id": "snapsave0", 2463# "tag": "my-snap", 2464# "vmstate": "disk0", 2465# "devices": ["disk0", "disk1"] 2466# } 2467# } 2468# <- { "return": { } } 2469# <- {"event": "JOB_STATUS_CHANGE", 2470# "timestamp": {"seconds": 1432121972, "microseconds": 744001}, 2471# "data": {"status": "created", "id": "snapsave0"}} 2472# <- {"event": "JOB_STATUS_CHANGE", 2473# "timestamp": {"seconds": 1432122172, "microseconds": 744001}, 2474# "data": {"status": "running", "id": "snapsave0"}} 2475# <- {"event": "STOP", 2476# "timestamp": {"seconds": 1432122372, "microseconds": 744001} } 2477# <- {"event": "RESUME", 2478# "timestamp": {"seconds": 1432122572, "microseconds": 744001} } 2479# <- {"event": "JOB_STATUS_CHANGE", 2480# "timestamp": {"seconds": 1432122772, "microseconds": 744001}, 2481# "data": {"status": "waiting", "id": "snapsave0"}} 2482# <- {"event": "JOB_STATUS_CHANGE", 2483# "timestamp": {"seconds": 1432122972, "microseconds": 744001}, 2484# "data": {"status": "pending", "id": "snapsave0"}} 2485# <- {"event": "JOB_STATUS_CHANGE", 2486# "timestamp": {"seconds": 1432123172, "microseconds": 744001}, 2487# "data": {"status": "concluded", "id": "snapsave0"}} 2488# -> {"execute": "query-jobs"} 2489# <- {"return": [{"current-progress": 1, 2490# "status": "concluded", 2491# "total-progress": 1, 2492# "type": "snapshot-save", 2493# "id": "snapsave0"}]} 2494# 2495# Since: 6.0 2496## 2497{ 'command': 'snapshot-save', 2498 'data': { 'job-id': 'str', 2499 'tag': 'str', 2500 'vmstate': 'str', 2501 'devices': ['str'] } } 2502 2503## 2504# @snapshot-load: 2505# 2506# Load a VM snapshot 2507# 2508# @job-id: identifier for the newly created job 2509# 2510# @tag: name of the snapshot to load. 2511# 2512# @vmstate: block device node name to load vmstate from 2513# 2514# @devices: list of block device node names to load a snapshot from 2515# 2516# Applications should not assume that the snapshot load is complete 2517# when this command returns. The job commands / events must be used 2518# to determine completion and to fetch details of any errors that 2519# arise. 2520# 2521# Note that execution of the guest CPUs will be stopped during the 2522# time it takes to load the snapshot. 2523# 2524# It is strongly recommended that @devices contain all writable block 2525# device nodes that can have changed since the original @snapshot-save 2526# command execution. 2527# 2528# Example: 2529# 2530# -> { "execute": "snapshot-load", 2531# "arguments": { 2532# "job-id": "snapload0", 2533# "tag": "my-snap", 2534# "vmstate": "disk0", 2535# "devices": ["disk0", "disk1"] 2536# } 2537# } 2538# <- { "return": { } } 2539# <- {"event": "JOB_STATUS_CHANGE", 2540# "timestamp": {"seconds": 1472124172, "microseconds": 744001}, 2541# "data": {"status": "created", "id": "snapload0"}} 2542# <- {"event": "JOB_STATUS_CHANGE", 2543# "timestamp": {"seconds": 1472125172, "microseconds": 744001}, 2544# "data": {"status": "running", "id": "snapload0"}} 2545# <- {"event": "STOP", 2546# "timestamp": {"seconds": 1472125472, "microseconds": 744001} } 2547# <- {"event": "RESUME", 2548# "timestamp": {"seconds": 1472125872, "microseconds": 744001} } 2549# <- {"event": "JOB_STATUS_CHANGE", 2550# "timestamp": {"seconds": 1472126172, "microseconds": 744001}, 2551# "data": {"status": "waiting", "id": "snapload0"}} 2552# <- {"event": "JOB_STATUS_CHANGE", 2553# "timestamp": {"seconds": 1472127172, "microseconds": 744001}, 2554# "data": {"status": "pending", "id": "snapload0"}} 2555# <- {"event": "JOB_STATUS_CHANGE", 2556# "timestamp": {"seconds": 1472128172, "microseconds": 744001}, 2557# "data": {"status": "concluded", "id": "snapload0"}} 2558# -> {"execute": "query-jobs"} 2559# <- {"return": [{"current-progress": 1, 2560# "status": "concluded", 2561# "total-progress": 1, 2562# "type": "snapshot-load", 2563# "id": "snapload0"}]} 2564# 2565# Since: 6.0 2566## 2567{ 'command': 'snapshot-load', 2568 'data': { 'job-id': 'str', 2569 'tag': 'str', 2570 'vmstate': 'str', 2571 'devices': ['str'] } } 2572 2573## 2574# @snapshot-delete: 2575# 2576# Delete a VM snapshot 2577# 2578# @job-id: identifier for the newly created job 2579# 2580# @tag: name of the snapshot to delete. 2581# 2582# @devices: list of block device node names to delete a snapshot from 2583# 2584# Applications should not assume that the snapshot delete is complete 2585# when this command returns. The job commands / events must be used 2586# to determine completion and to fetch details of any errors that 2587# arise. 2588# 2589# Example: 2590# 2591# -> { "execute": "snapshot-delete", 2592# "arguments": { 2593# "job-id": "snapdelete0", 2594# "tag": "my-snap", 2595# "devices": ["disk0", "disk1"] 2596# } 2597# } 2598# <- { "return": { } } 2599# <- {"event": "JOB_STATUS_CHANGE", 2600# "timestamp": {"seconds": 1442124172, "microseconds": 744001}, 2601# "data": {"status": "created", "id": "snapdelete0"}} 2602# <- {"event": "JOB_STATUS_CHANGE", 2603# "timestamp": {"seconds": 1442125172, "microseconds": 744001}, 2604# "data": {"status": "running", "id": "snapdelete0"}} 2605# <- {"event": "JOB_STATUS_CHANGE", 2606# "timestamp": {"seconds": 1442126172, "microseconds": 744001}, 2607# "data": {"status": "waiting", "id": "snapdelete0"}} 2608# <- {"event": "JOB_STATUS_CHANGE", 2609# "timestamp": {"seconds": 1442127172, "microseconds": 744001}, 2610# "data": {"status": "pending", "id": "snapdelete0"}} 2611# <- {"event": "JOB_STATUS_CHANGE", 2612# "timestamp": {"seconds": 1442128172, "microseconds": 744001}, 2613# "data": {"status": "concluded", "id": "snapdelete0"}} 2614# -> {"execute": "query-jobs"} 2615# <- {"return": [{"current-progress": 1, 2616# "status": "concluded", 2617# "total-progress": 1, 2618# "type": "snapshot-delete", 2619# "id": "snapdelete0"}]} 2620# 2621# Since: 6.0 2622## 2623{ 'command': 'snapshot-delete', 2624 'data': { 'job-id': 'str', 2625 'tag': 'str', 2626 'devices': ['str'] } } 2627