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