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 target VM 20# 21# @total: total amount of bytes involved in the migration process 22# 23# @duplicate: number of duplicate (zero) pages (since 1.2) 24# 25# @skipped: number of skipped zero pages (since 1.5) 26# 27# @normal: number of normal pages (since 1.2) 28# 29# @normal-bytes: number of normal bytes sent (since 1.2) 30# 31# @dirty-pages-rate: number of pages dirtied by second by the 32# guest (since 1.3) 33# 34# @mbps: throughput in megabits/sec. (since 1.6) 35# 36# @dirty-sync-count: number of times that dirty ram was synchronized (since 2.1) 37# 38# @postcopy-requests: The number of page requests received from the destination 39# (since 2.7) 40# 41# @page-size: The number of bytes per page for the various page-based 42# statistics (since 2.10) 43# 44# @multifd-bytes: The number of bytes sent through multifd (since 3.0) 45# 46# @pages-per-second: the number of memory pages transferred per second 47# (Since 4.0) 48# 49# @precopy-bytes: The number of bytes sent in the pre-copy phase 50# (since 7.0). 51# 52# @downtime-bytes: The number of bytes sent while the guest is paused 53# (since 7.0). 54# 55# @postcopy-bytes: The number of bytes sent during the post-copy phase 56# (since 7.0). 57# 58# Since: 0.14 59## 60{ 'struct': 'MigrationStats', 61 'data': {'transferred': 'int', 'remaining': 'int', 'total': 'int' , 62 'duplicate': 'int', 'skipped': 'int', 'normal': 'int', 63 'normal-bytes': 'int', 'dirty-pages-rate' : 'int', 64 'mbps' : 'number', 'dirty-sync-count' : 'int', 65 'postcopy-requests' : 'int', 'page-size' : 'int', 66 'multifd-bytes' : 'uint64', 'pages-per-second' : 'uint64', 67 'precopy-bytes' : 'uint64', 'downtime-bytes' : 'uint64', 68 'postcopy-bytes' : 'uint64' } } 69 70## 71# @XBZRLECacheStats: 72# 73# Detailed XBZRLE migration cache statistics 74# 75# @cache-size: XBZRLE cache size 76# 77# @bytes: amount of bytes already transferred to the target VM 78# 79# @pages: amount of pages transferred to the target VM 80# 81# @cache-miss: number of cache miss 82# 83# @cache-miss-rate: rate of cache miss (since 2.1) 84# 85# @encoding-rate: rate of encoded bytes (since 5.1) 86# 87# @overflow: number of overflows 88# 89# Since: 1.2 90## 91{ 'struct': 'XBZRLECacheStats', 92 'data': {'cache-size': 'size', 'bytes': 'int', 'pages': 'int', 93 'cache-miss': 'int', 'cache-miss-rate': 'number', 94 'encoding-rate': 'number', 'overflow': 'int' } } 95 96## 97# @CompressionStats: 98# 99# Detailed migration compression statistics 100# 101# @pages: amount of pages compressed and transferred to the target VM 102# 103# @busy: count of times that no free thread was available to compress data 104# 105# @busy-rate: rate of thread busy 106# 107# @compressed-size: amount of bytes after compression 108# 109# @compression-rate: rate of compressed size 110# 111# Since: 3.1 112## 113{ 'struct': 'CompressionStats', 114 'data': {'pages': 'int', 'busy': 'int', 'busy-rate': 'number', 115 'compressed-size': 'int', 'compression-rate': 'number' } } 116 117## 118# @MigrationStatus: 119# 120# An enumeration of migration status. 121# 122# @none: no migration has ever happened. 123# 124# @setup: migration process has been initiated. 125# 126# @cancelling: in the process of cancelling migration. 127# 128# @cancelled: cancelling migration is finished. 129# 130# @active: in the process of doing migration. 131# 132# @postcopy-active: like active, but now in postcopy mode. (since 2.5) 133# 134# @postcopy-paused: during postcopy but paused. (since 3.0) 135# 136# @postcopy-recover: trying to recover from a paused postcopy. (since 3.0) 137# 138# @completed: migration is finished. 139# 140# @failed: some error occurred during migration process. 141# 142# @colo: VM is in the process of fault tolerance, VM can not get into this 143# state unless colo capability is enabled for migration. (since 2.8) 144# 145# @pre-switchover: Paused before device serialisation. (since 2.11) 146# 147# @device: During device serialisation when pause-before-switchover is enabled 148# (since 2.11) 149# 150# @wait-unplug: wait for device unplug request by guest OS to be completed. 151# (since 4.2) 152# 153# Since: 2.3 154## 155{ 'enum': 'MigrationStatus', 156 'data': [ 'none', 'setup', 'cancelling', 'cancelled', 157 'active', 'postcopy-active', 'postcopy-paused', 158 'postcopy-recover', 'completed', 'failed', 'colo', 159 'pre-switchover', 'device', 'wait-unplug' ] } 160## 161# @VfioStats: 162# 163# Detailed VFIO devices migration statistics 164# 165# @transferred: amount of bytes transferred to the target VM by VFIO devices 166# 167# Since: 5.2 168## 169{ 'struct': 'VfioStats', 170 'data': {'transferred': 'int' } } 171 172## 173# @MigrationInfo: 174# 175# Information about current migration process. 176# 177# @status: @MigrationStatus describing the current migration status. 178# If this field is not returned, no migration process 179# has been initiated 180# 181# @ram: @MigrationStats containing detailed migration 182# status, only returned if status is 'active' or 183# 'completed'(since 1.2) 184# 185# @disk: @MigrationStats containing detailed disk migration 186# status, only returned if status is 'active' and it is a block 187# migration 188# 189# @xbzrle-cache: @XBZRLECacheStats containing detailed XBZRLE 190# migration statistics, only returned if XBZRLE feature is on and 191# status is 'active' or 'completed' (since 1.2) 192# 193# @total-time: total amount of milliseconds since migration started. 194# If migration has ended, it returns the total migration 195# time. (since 1.2) 196# 197# @downtime: only present when migration finishes correctly 198# total downtime in milliseconds for the guest. 199# (since 1.3) 200# 201# @expected-downtime: only present while migration is active 202# expected downtime in milliseconds for the guest in last walk 203# of the dirty bitmap. (since 1.3) 204# 205# @setup-time: amount of setup time in milliseconds *before* the 206# iterations begin but *after* the QMP command is issued. This is designed 207# to provide an accounting of any activities (such as RDMA pinning) which 208# may be expensive, but do not actually occur during the iterative 209# migration rounds themselves. (since 1.6) 210# 211# @cpu-throttle-percentage: percentage of time guest cpus are being 212# throttled during auto-converge. This is only present when auto-converge 213# has started throttling guest cpus. (Since 2.7) 214# 215# @error-desc: the human readable error description string, when 216# @status is 'failed'. Clients should not attempt to parse the 217# error strings. (Since 2.7) 218# 219# @postcopy-blocktime: total time when all vCPU were blocked during postcopy 220# live migration. This is only present when the postcopy-blocktime 221# migration capability is enabled. (Since 3.0) 222# 223# @postcopy-vcpu-blocktime: list of the postcopy blocktime per vCPU. This is 224# only present when the postcopy-blocktime migration capability 225# is enabled. (Since 3.0) 226# 227# @compression: migration compression statistics, only returned if compression 228# feature is on and status is 'active' or 'completed' (Since 3.1) 229# 230# @socket-address: Only used for tcp, to know what the real port is (Since 4.0) 231# 232# @vfio: @VfioStats containing detailed VFIO devices migration statistics, 233# only returned if VFIO device is present, migration is supported by all 234# VFIO devices and status is 'active' or 'completed' (since 5.2) 235# 236# @blocked-reasons: A list of reasons an outgoing migration is blocked. 237# Present and non-empty when migration is blocked. 238# (since 6.0) 239# 240# Since: 0.14 241## 242{ 'struct': 'MigrationInfo', 243 'data': {'*status': 'MigrationStatus', '*ram': 'MigrationStats', 244 '*disk': 'MigrationStats', 245 '*vfio': 'VfioStats', 246 '*xbzrle-cache': 'XBZRLECacheStats', 247 '*total-time': 'int', 248 '*expected-downtime': 'int', 249 '*downtime': 'int', 250 '*setup-time': 'int', 251 '*cpu-throttle-percentage': 'int', 252 '*error-desc': 'str', 253 '*blocked-reasons': ['str'], 254 '*postcopy-blocktime' : 'uint32', 255 '*postcopy-vcpu-blocktime': ['uint32'], 256 '*compression': 'CompressionStats', 257 '*socket-address': ['SocketAddress'] } } 258 259## 260# @query-migrate: 261# 262# Returns information about current migration process. If migration 263# is active there will be another json-object with RAM migration 264# status and if block migration is active another one with block 265# migration status. 266# 267# Returns: @MigrationInfo 268# 269# Since: 0.14 270# 271# Example: 272# 273# 1. Before the first migration 274# 275# -> { "execute": "query-migrate" } 276# <- { "return": {} } 277# 278# 2. Migration is done and has succeeded 279# 280# -> { "execute": "query-migrate" } 281# <- { "return": { 282# "status": "completed", 283# "total-time":12345, 284# "setup-time":12345, 285# "downtime":12345, 286# "ram":{ 287# "transferred":123, 288# "remaining":123, 289# "total":246, 290# "duplicate":123, 291# "normal":123, 292# "normal-bytes":123456, 293# "dirty-sync-count":15 294# } 295# } 296# } 297# 298# 3. Migration is done and has failed 299# 300# -> { "execute": "query-migrate" } 301# <- { "return": { "status": "failed" } } 302# 303# 4. Migration is being performed and is not a block migration: 304# 305# -> { "execute": "query-migrate" } 306# <- { 307# "return":{ 308# "status":"active", 309# "total-time":12345, 310# "setup-time":12345, 311# "expected-downtime":12345, 312# "ram":{ 313# "transferred":123, 314# "remaining":123, 315# "total":246, 316# "duplicate":123, 317# "normal":123, 318# "normal-bytes":123456, 319# "dirty-sync-count":15 320# } 321# } 322# } 323# 324# 5. Migration is being performed and is a block migration: 325# 326# -> { "execute": "query-migrate" } 327# <- { 328# "return":{ 329# "status":"active", 330# "total-time":12345, 331# "setup-time":12345, 332# "expected-downtime":12345, 333# "ram":{ 334# "total":1057024, 335# "remaining":1053304, 336# "transferred":3720, 337# "duplicate":123, 338# "normal":123, 339# "normal-bytes":123456, 340# "dirty-sync-count":15 341# }, 342# "disk":{ 343# "total":20971520, 344# "remaining":20880384, 345# "transferred":91136 346# } 347# } 348# } 349# 350# 6. Migration is being performed and XBZRLE is active: 351# 352# -> { "execute": "query-migrate" } 353# <- { 354# "return":{ 355# "status":"active", 356# "total-time":12345, 357# "setup-time":12345, 358# "expected-downtime":12345, 359# "ram":{ 360# "total":1057024, 361# "remaining":1053304, 362# "transferred":3720, 363# "duplicate":10, 364# "normal":3333, 365# "normal-bytes":3412992, 366# "dirty-sync-count":15 367# }, 368# "xbzrle-cache":{ 369# "cache-size":67108864, 370# "bytes":20971520, 371# "pages":2444343, 372# "cache-miss":2244, 373# "cache-miss-rate":0.123, 374# "encoding-rate":80.1, 375# "overflow":34434 376# } 377# } 378# } 379# 380## 381{ 'command': 'query-migrate', 'returns': 'MigrationInfo' } 382 383## 384# @MigrationCapability: 385# 386# Migration capabilities enumeration 387# 388# @xbzrle: Migration supports xbzrle (Xor Based Zero Run Length Encoding). 389# This feature allows us to minimize migration traffic for certain work 390# loads, by sending compressed difference of the pages 391# 392# @rdma-pin-all: Controls whether or not the entire VM memory footprint is 393# mlock()'d on demand or all at once. Refer to docs/rdma.txt for usage. 394# Disabled by default. (since 2.0) 395# 396# @zero-blocks: During storage migration encode blocks of zeroes efficiently. This 397# essentially saves 1MB of zeroes per block on the wire. Enabling requires 398# source and target VM to support this feature. To enable it is sufficient 399# to enable the capability on the source VM. The feature is disabled by 400# default. (since 1.6) 401# 402# @compress: Use multiple compression threads to accelerate live migration. 403# This feature can help to reduce the migration traffic, by sending 404# compressed pages. Please note that if compress and xbzrle are both 405# on, compress only takes effect in the ram bulk stage, after that, 406# it will be disabled and only xbzrle takes effect, this can help to 407# minimize migration traffic. The feature is disabled by default. 408# (since 2.4 ) 409# 410# @events: generate events for each migration state change 411# (since 2.4 ) 412# 413# @auto-converge: If enabled, QEMU will automatically throttle down the guest 414# to speed up convergence of RAM migration. (since 1.6) 415# 416# @postcopy-ram: Start executing on the migration target before all of RAM has 417# been migrated, pulling the remaining pages along as needed. The 418# capacity must have the same setting on both source and target 419# or migration will not even start. NOTE: If the migration fails during 420# postcopy the VM will fail. (since 2.6) 421# 422# @x-colo: If enabled, migration will never end, and the state of the VM on the 423# primary side will be migrated continuously to the VM on secondary 424# side, this process is called COarse-Grain LOck Stepping (COLO) for 425# Non-stop Service. (since 2.8) 426# 427# @release-ram: if enabled, qemu will free the migrated ram pages on the source 428# during postcopy-ram migration. (since 2.9) 429# 430# @block: If enabled, QEMU will also migrate the contents of all block 431# devices. Default is disabled. A possible alternative uses 432# mirror jobs to a builtin NBD server on the destination, which 433# offers more flexibility. 434# (Since 2.10) 435# 436# @return-path: If enabled, migration will use the return path even 437# for precopy. (since 2.10) 438# 439# @pause-before-switchover: Pause outgoing migration before serialising device 440# state and before disabling block IO (since 2.11) 441# 442# @multifd: Use more than one fd for migration (since 4.0) 443# 444# @dirty-bitmaps: If enabled, QEMU will migrate named dirty bitmaps. 445# (since 2.12) 446# 447# @postcopy-blocktime: Calculate downtime for postcopy live migration 448# (since 3.0) 449# 450# @late-block-activate: If enabled, the destination will not activate block 451# devices (and thus take locks) immediately at the end of migration. 452# (since 3.0) 453# 454# @x-ignore-shared: If enabled, QEMU will not migrate shared memory (since 4.0) 455# 456# @validate-uuid: Send the UUID of the source to allow the destination 457# to ensure it is the same. (since 4.2) 458# 459# @background-snapshot: If enabled, the migration stream will be a snapshot 460# of the VM exactly at the point when the migration 461# procedure starts. The VM RAM is saved with running VM. 462# (since 6.0) 463# 464# Features: 465# @unstable: Members @x-colo and @x-ignore-shared are experimental. 466# 467# Since: 1.2 468## 469{ 'enum': 'MigrationCapability', 470 'data': ['xbzrle', 'rdma-pin-all', 'auto-converge', 'zero-blocks', 471 'compress', 'events', 'postcopy-ram', 472 { 'name': 'x-colo', 'features': [ 'unstable' ] }, 473 'release-ram', 474 'block', 'return-path', 'pause-before-switchover', 'multifd', 475 'dirty-bitmaps', 'postcopy-blocktime', 'late-block-activate', 476 { 'name': 'x-ignore-shared', 'features': [ 'unstable' ] }, 477 'validate-uuid', 'background-snapshot'] } 478 479## 480# @MigrationCapabilityStatus: 481# 482# Migration capability information 483# 484# @capability: capability enum 485# 486# @state: capability state bool 487# 488# Since: 1.2 489## 490{ 'struct': 'MigrationCapabilityStatus', 491 'data': { 'capability' : 'MigrationCapability', 'state' : 'bool' } } 492 493## 494# @migrate-set-capabilities: 495# 496# Enable/Disable the following migration capabilities (like xbzrle) 497# 498# @capabilities: json array of capability modifications to make 499# 500# Since: 1.2 501# 502# Example: 503# 504# -> { "execute": "migrate-set-capabilities" , "arguments": 505# { "capabilities": [ { "capability": "xbzrle", "state": true } ] } } 506# 507## 508{ 'command': 'migrate-set-capabilities', 509 'data': { 'capabilities': ['MigrationCapabilityStatus'] } } 510 511## 512# @query-migrate-capabilities: 513# 514# Returns information about the current migration capabilities status 515# 516# Returns: @MigrationCapabilitiesStatus 517# 518# Since: 1.2 519# 520# Example: 521# 522# -> { "execute": "query-migrate-capabilities" } 523# <- { "return": [ 524# {"state": false, "capability": "xbzrle"}, 525# {"state": false, "capability": "rdma-pin-all"}, 526# {"state": false, "capability": "auto-converge"}, 527# {"state": false, "capability": "zero-blocks"}, 528# {"state": false, "capability": "compress"}, 529# {"state": true, "capability": "events"}, 530# {"state": false, "capability": "postcopy-ram"}, 531# {"state": false, "capability": "x-colo"} 532# ]} 533# 534## 535{ 'command': 'query-migrate-capabilities', 'returns': ['MigrationCapabilityStatus']} 536 537## 538# @MultiFDCompression: 539# 540# An enumeration of multifd compression methods. 541# 542# @none: no compression. 543# @zlib: use zlib compression method. 544# @zstd: use zstd compression method. 545# 546# Since: 5.0 547## 548{ 'enum': 'MultiFDCompression', 549 'data': [ 'none', 'zlib', 550 { 'name': 'zstd', 'if': 'CONFIG_ZSTD' } ] } 551 552## 553# @BitmapMigrationBitmapAliasTransform: 554# 555# @persistent: If present, the bitmap will be made persistent 556# or transient depending on this parameter. 557# 558# Since: 6.0 559## 560{ 'struct': 'BitmapMigrationBitmapAliasTransform', 561 'data': { 562 '*persistent': 'bool' 563 } } 564 565## 566# @BitmapMigrationBitmapAlias: 567# 568# @name: The name of the bitmap. 569# 570# @alias: An alias name for migration (for example the bitmap name on 571# the opposite site). 572# 573# @transform: Allows the modification of the migrated bitmap. 574# (since 6.0) 575# 576# Since: 5.2 577## 578{ 'struct': 'BitmapMigrationBitmapAlias', 579 'data': { 580 'name': 'str', 581 'alias': 'str', 582 '*transform': 'BitmapMigrationBitmapAliasTransform' 583 } } 584 585## 586# @BitmapMigrationNodeAlias: 587# 588# Maps a block node name and the bitmaps it has to aliases for dirty 589# bitmap migration. 590# 591# @node-name: A block node name. 592# 593# @alias: An alias block node name for migration (for example the 594# node name on the opposite site). 595# 596# @bitmaps: Mappings for the bitmaps on this node. 597# 598# Since: 5.2 599## 600{ 'struct': 'BitmapMigrationNodeAlias', 601 'data': { 602 'node-name': 'str', 603 'alias': 'str', 604 'bitmaps': [ 'BitmapMigrationBitmapAlias' ] 605 } } 606 607## 608# @MigrationParameter: 609# 610# Migration parameters enumeration 611# 612# @announce-initial: Initial delay (in milliseconds) before sending the first 613# announce (Since 4.0) 614# 615# @announce-max: Maximum delay (in milliseconds) between packets in the 616# announcement (Since 4.0) 617# 618# @announce-rounds: Number of self-announce packets sent after migration 619# (Since 4.0) 620# 621# @announce-step: Increase in delay (in milliseconds) between subsequent 622# packets in the announcement (Since 4.0) 623# 624# @compress-level: Set the compression level to be used in live migration, 625# the compression level is an integer between 0 and 9, where 0 means 626# no compression, 1 means the best compression speed, and 9 means best 627# compression ratio which will consume more CPU. 628# 629# @compress-threads: Set compression thread count to be used in live migration, 630# the compression thread count is an integer between 1 and 255. 631# 632# @compress-wait-thread: Controls behavior when all compression threads are 633# currently busy. If true (default), wait for a free 634# compression thread to become available; otherwise, 635# send the page uncompressed. (Since 3.1) 636# 637# @decompress-threads: Set decompression thread count to be used in live 638# migration, the decompression thread count is an integer between 1 639# and 255. Usually, decompression is at least 4 times as fast as 640# compression, so set the decompress-threads to the number about 1/4 641# of compress-threads is adequate. 642# 643# @throttle-trigger-threshold: The ratio of bytes_dirty_period and bytes_xfer_period 644# to trigger throttling. It is expressed as percentage. 645# The default value is 50. (Since 5.0) 646# 647# @cpu-throttle-initial: Initial percentage of time guest cpus are throttled 648# when migration auto-converge is activated. The 649# default value is 20. (Since 2.7) 650# 651# @cpu-throttle-increment: throttle percentage increase each time 652# auto-converge detects that migration is not making 653# progress. The default value is 10. (Since 2.7) 654# 655# @cpu-throttle-tailslow: Make CPU throttling slower at tail stage 656# At the tail stage of throttling, the Guest is very 657# sensitive to CPU percentage while the @cpu-throttle 658# -increment is excessive usually at tail stage. 659# If this parameter is true, we will compute the ideal 660# CPU percentage used by the Guest, which may exactly make 661# the dirty rate match the dirty rate threshold. Then we 662# will choose a smaller throttle increment between the 663# one specified by @cpu-throttle-increment and the one 664# generated by ideal CPU percentage. 665# Therefore, it is compatible to traditional throttling, 666# meanwhile the throttle increment won't be excessive 667# at tail stage. 668# The default value is false. (Since 5.1) 669# 670# @tls-creds: ID of the 'tls-creds' object that provides credentials for 671# establishing a TLS connection over the migration data channel. 672# On the outgoing side of the migration, the credentials must 673# be for a 'client' endpoint, while for the incoming side the 674# credentials must be for a 'server' endpoint. Setting this 675# will enable TLS for all migrations. The default is unset, 676# resulting in unsecured migration at the QEMU level. (Since 2.7) 677# 678# @tls-hostname: hostname of the target host for the migration. This is 679# required when using x509 based TLS credentials and the 680# migration URI does not already include a hostname. For 681# example if using fd: or exec: based migration, the 682# hostname must be provided so that the server's x509 683# certificate identity can be validated. (Since 2.7) 684# 685# @tls-authz: ID of the 'authz' object subclass that provides access control 686# checking of the TLS x509 certificate distinguished name. 687# This object is only resolved at time of use, so can be deleted 688# and recreated on the fly while the migration server is active. 689# If missing, it will default to denying access (Since 4.0) 690# 691# @max-bandwidth: to set maximum speed for migration. maximum speed in 692# bytes per second. (Since 2.8) 693# 694# @downtime-limit: set maximum tolerated downtime for migration. maximum 695# downtime in milliseconds (Since 2.8) 696# 697# @x-checkpoint-delay: The delay time (in ms) between two COLO checkpoints in 698# periodic mode. (Since 2.8) 699# 700# @block-incremental: Affects how much storage is migrated when the 701# block migration capability is enabled. When false, the entire 702# storage backing chain is migrated into a flattened image at 703# the destination; when true, only the active qcow2 layer is 704# migrated and the destination must already have access to the 705# same backing chain as was used on the source. (since 2.10) 706# 707# @multifd-channels: Number of channels used to migrate data in 708# parallel. This is the same number that the 709# number of sockets used for migration. The 710# default value is 2 (since 4.0) 711# 712# @xbzrle-cache-size: cache size to be used by XBZRLE migration. It 713# needs to be a multiple of the target page size 714# and a power of 2 715# (Since 2.11) 716# 717# @max-postcopy-bandwidth: Background transfer bandwidth during postcopy. 718# Defaults to 0 (unlimited). In bytes per second. 719# (Since 3.0) 720# 721# @max-cpu-throttle: maximum cpu throttle percentage. 722# Defaults to 99. (Since 3.1) 723# 724# @multifd-compression: Which compression method to use. 725# Defaults to none. (Since 5.0) 726# 727# @multifd-zlib-level: Set the compression level to be used in live 728# migration, the compression level is an integer between 0 729# and 9, where 0 means no compression, 1 means the best 730# compression speed, and 9 means best compression ratio which 731# will consume more CPU. 732# Defaults to 1. (Since 5.0) 733# 734# @multifd-zstd-level: Set the compression level to be used in live 735# migration, the compression level is an integer between 0 736# and 20, where 0 means no compression, 1 means the best 737# compression speed, and 20 means best compression ratio which 738# will consume more CPU. 739# Defaults to 1. (Since 5.0) 740# 741# @block-bitmap-mapping: Maps block nodes and bitmaps on them to 742# aliases for the purpose of dirty bitmap migration. Such 743# aliases may for example be the corresponding names on the 744# opposite site. 745# The mapping must be one-to-one, but not necessarily 746# complete: On the source, unmapped bitmaps and all bitmaps 747# on unmapped nodes will be ignored. On the destination, 748# encountering an unmapped alias in the incoming migration 749# stream will result in a report, and all further bitmap 750# migration data will then be discarded. 751# Note that the destination does not know about bitmaps it 752# does not receive, so there is no limitation or requirement 753# regarding the number of bitmaps received, or how they are 754# named, or on which nodes they are placed. 755# By default (when this parameter has never been set), bitmap 756# names are mapped to themselves. Nodes are mapped to their 757# block device name if there is one, and to their node name 758# otherwise. (Since 5.2) 759# 760# Features: 761# @unstable: Member @x-checkpoint-delay is experimental. 762# 763# Since: 2.4 764## 765{ 'enum': 'MigrationParameter', 766 'data': ['announce-initial', 'announce-max', 767 'announce-rounds', 'announce-step', 768 'compress-level', 'compress-threads', 'decompress-threads', 769 'compress-wait-thread', 'throttle-trigger-threshold', 770 'cpu-throttle-initial', 'cpu-throttle-increment', 771 'cpu-throttle-tailslow', 772 'tls-creds', 'tls-hostname', 'tls-authz', 'max-bandwidth', 773 'downtime-limit', 774 { 'name': 'x-checkpoint-delay', 'features': [ 'unstable' ] }, 775 'block-incremental', 776 'multifd-channels', 777 'xbzrle-cache-size', 'max-postcopy-bandwidth', 778 'max-cpu-throttle', 'multifd-compression', 779 'multifd-zlib-level' ,'multifd-zstd-level', 780 'block-bitmap-mapping' ] } 781 782## 783# @MigrateSetParameters: 784# 785# @announce-initial: Initial delay (in milliseconds) before sending the first 786# announce (Since 4.0) 787# 788# @announce-max: Maximum delay (in milliseconds) between packets in the 789# announcement (Since 4.0) 790# 791# @announce-rounds: Number of self-announce packets sent after migration 792# (Since 4.0) 793# 794# @announce-step: Increase in delay (in milliseconds) between subsequent 795# packets in the announcement (Since 4.0) 796# 797# @compress-level: compression level 798# 799# @compress-threads: compression thread count 800# 801# @compress-wait-thread: Controls behavior when all compression threads are 802# currently busy. If true (default), wait for a free 803# compression thread to become available; otherwise, 804# send the page uncompressed. (Since 3.1) 805# 806# @decompress-threads: decompression thread count 807# 808# @throttle-trigger-threshold: The ratio of bytes_dirty_period and bytes_xfer_period 809# to trigger throttling. It is expressed as percentage. 810# The default value is 50. (Since 5.0) 811# 812# @cpu-throttle-initial: Initial percentage of time guest cpus are 813# throttled when migration auto-converge is activated. 814# The default value is 20. (Since 2.7) 815# 816# @cpu-throttle-increment: throttle percentage increase each time 817# auto-converge detects that migration is not making 818# progress. The default value is 10. (Since 2.7) 819# 820# @cpu-throttle-tailslow: Make CPU throttling slower at tail stage 821# At the tail stage of throttling, the Guest is very 822# sensitive to CPU percentage while the @cpu-throttle 823# -increment is excessive usually at tail stage. 824# If this parameter is true, we will compute the ideal 825# CPU percentage used by the Guest, which may exactly make 826# the dirty rate match the dirty rate threshold. Then we 827# will choose a smaller throttle increment between the 828# one specified by @cpu-throttle-increment and the one 829# generated by ideal CPU percentage. 830# Therefore, it is compatible to traditional throttling, 831# meanwhile the throttle increment won't be excessive 832# at tail stage. 833# The default value is false. (Since 5.1) 834# 835# @tls-creds: ID of the 'tls-creds' object that provides credentials 836# for establishing a TLS connection over the migration data 837# channel. On the outgoing side of the migration, the credentials 838# must be for a 'client' endpoint, while for the incoming side the 839# credentials must be for a 'server' endpoint. Setting this 840# to a non-empty string enables TLS for all migrations. 841# An empty string means that QEMU will use plain text mode for 842# migration, rather than TLS (Since 2.9) 843# Previously (since 2.7), this was reported by omitting 844# tls-creds instead. 845# 846# @tls-hostname: hostname of the target host for the migration. This 847# is required when using x509 based TLS credentials and the 848# migration URI does not already include a hostname. For 849# example if using fd: or exec: based migration, the 850# hostname must be provided so that the server's x509 851# certificate identity can be validated. (Since 2.7) 852# An empty string means that QEMU will use the hostname 853# associated with the migration URI, if any. (Since 2.9) 854# Previously (since 2.7), this was reported by omitting 855# tls-hostname instead. 856# 857# @max-bandwidth: to set maximum speed for migration. maximum speed in 858# bytes per second. (Since 2.8) 859# 860# @downtime-limit: set maximum tolerated downtime for migration. maximum 861# downtime in milliseconds (Since 2.8) 862# 863# @x-checkpoint-delay: the delay time between two COLO checkpoints. (Since 2.8) 864# 865# @block-incremental: Affects how much storage is migrated when the 866# block migration capability is enabled. When false, the entire 867# storage backing chain is migrated into a flattened image at 868# the destination; when true, only the active qcow2 layer is 869# migrated and the destination must already have access to the 870# same backing chain as was used on the source. (since 2.10) 871# 872# @multifd-channels: Number of channels used to migrate data in 873# parallel. This is the same number that the 874# number of sockets used for migration. The 875# default value is 2 (since 4.0) 876# 877# @xbzrle-cache-size: cache size to be used by XBZRLE migration. It 878# needs to be a multiple of the target page size 879# and a power of 2 880# (Since 2.11) 881# 882# @max-postcopy-bandwidth: Background transfer bandwidth during postcopy. 883# Defaults to 0 (unlimited). In bytes per second. 884# (Since 3.0) 885# 886# @max-cpu-throttle: maximum cpu throttle percentage. 887# The default value is 99. (Since 3.1) 888# 889# @multifd-compression: Which compression method to use. 890# Defaults to none. (Since 5.0) 891# 892# @multifd-zlib-level: Set the compression level to be used in live 893# migration, the compression level is an integer between 0 894# and 9, where 0 means no compression, 1 means the best 895# compression speed, and 9 means best compression ratio which 896# will consume more CPU. 897# Defaults to 1. (Since 5.0) 898# 899# @multifd-zstd-level: Set the compression level to be used in live 900# migration, the compression level is an integer between 0 901# and 20, where 0 means no compression, 1 means the best 902# compression speed, and 20 means best compression ratio which 903# will consume more CPU. 904# Defaults to 1. (Since 5.0) 905# 906# @block-bitmap-mapping: Maps block nodes and bitmaps on them to 907# aliases for the purpose of dirty bitmap migration. Such 908# aliases may for example be the corresponding names on the 909# opposite site. 910# The mapping must be one-to-one, but not necessarily 911# complete: On the source, unmapped bitmaps and all bitmaps 912# on unmapped nodes will be ignored. On the destination, 913# encountering an unmapped alias in the incoming migration 914# stream will result in a report, and all further bitmap 915# migration data will then be discarded. 916# Note that the destination does not know about bitmaps it 917# does not receive, so there is no limitation or requirement 918# regarding the number of bitmaps received, or how they are 919# named, or on which nodes they are placed. 920# By default (when this parameter has never been set), bitmap 921# names are mapped to themselves. Nodes are mapped to their 922# block device name if there is one, and to their node name 923# otherwise. (Since 5.2) 924# 925# Features: 926# @unstable: Member @x-checkpoint-delay is experimental. 927# 928# Since: 2.4 929## 930# TODO either fuse back into MigrationParameters, or make 931# MigrationParameters members mandatory 932{ 'struct': 'MigrateSetParameters', 933 'data': { '*announce-initial': 'size', 934 '*announce-max': 'size', 935 '*announce-rounds': 'size', 936 '*announce-step': 'size', 937 '*compress-level': 'uint8', 938 '*compress-threads': 'uint8', 939 '*compress-wait-thread': 'bool', 940 '*decompress-threads': 'uint8', 941 '*throttle-trigger-threshold': 'uint8', 942 '*cpu-throttle-initial': 'uint8', 943 '*cpu-throttle-increment': 'uint8', 944 '*cpu-throttle-tailslow': 'bool', 945 '*tls-creds': 'StrOrNull', 946 '*tls-hostname': 'StrOrNull', 947 '*tls-authz': 'StrOrNull', 948 '*max-bandwidth': 'size', 949 '*downtime-limit': 'uint64', 950 '*x-checkpoint-delay': { 'type': 'uint32', 951 'features': [ 'unstable' ] }, 952 '*block-incremental': 'bool', 953 '*multifd-channels': 'uint8', 954 '*xbzrle-cache-size': 'size', 955 '*max-postcopy-bandwidth': 'size', 956 '*max-cpu-throttle': 'uint8', 957 '*multifd-compression': 'MultiFDCompression', 958 '*multifd-zlib-level': 'uint8', 959 '*multifd-zstd-level': 'uint8', 960 '*block-bitmap-mapping': [ 'BitmapMigrationNodeAlias' ] } } 961 962## 963# @migrate-set-parameters: 964# 965# Set various migration parameters. 966# 967# Since: 2.4 968# 969# Example: 970# 971# -> { "execute": "migrate-set-parameters" , 972# "arguments": { "compress-level": 1 } } 973# 974## 975{ 'command': 'migrate-set-parameters', 'boxed': true, 976 'data': 'MigrateSetParameters' } 977 978## 979# @MigrationParameters: 980# 981# The optional members aren't actually optional. 982# 983# @announce-initial: Initial delay (in milliseconds) before sending the 984# first announce (Since 4.0) 985# 986# @announce-max: Maximum delay (in milliseconds) between packets in the 987# announcement (Since 4.0) 988# 989# @announce-rounds: Number of self-announce packets sent after migration 990# (Since 4.0) 991# 992# @announce-step: Increase in delay (in milliseconds) between subsequent 993# packets in the announcement (Since 4.0) 994# 995# @compress-level: compression level 996# 997# @compress-threads: compression thread count 998# 999# @compress-wait-thread: Controls behavior when all compression threads are 1000# currently busy. If true (default), wait for a free 1001# compression thread to become available; otherwise, 1002# send the page uncompressed. (Since 3.1) 1003# 1004# @decompress-threads: decompression thread count 1005# 1006# @throttle-trigger-threshold: The ratio of bytes_dirty_period and bytes_xfer_period 1007# to trigger throttling. It is expressed as percentage. 1008# The default value is 50. (Since 5.0) 1009# 1010# @cpu-throttle-initial: Initial percentage of time guest cpus are 1011# throttled when migration auto-converge is activated. 1012# (Since 2.7) 1013# 1014# @cpu-throttle-increment: throttle percentage increase each time 1015# auto-converge detects that migration is not making 1016# progress. (Since 2.7) 1017# 1018# @cpu-throttle-tailslow: Make CPU throttling slower at tail stage 1019# At the tail stage of throttling, the Guest is very 1020# sensitive to CPU percentage while the @cpu-throttle 1021# -increment is excessive usually at tail stage. 1022# If this parameter is true, we will compute the ideal 1023# CPU percentage used by the Guest, which may exactly make 1024# the dirty rate match the dirty rate threshold. Then we 1025# will choose a smaller throttle increment between the 1026# one specified by @cpu-throttle-increment and the one 1027# generated by ideal CPU percentage. 1028# Therefore, it is compatible to traditional throttling, 1029# meanwhile the throttle increment won't be excessive 1030# at tail stage. 1031# The default value is false. (Since 5.1) 1032# 1033# @tls-creds: ID of the 'tls-creds' object that provides credentials 1034# for establishing a TLS connection over the migration data 1035# channel. On the outgoing side of the migration, the credentials 1036# must be for a 'client' endpoint, while for the incoming side the 1037# credentials must be for a 'server' endpoint. 1038# An empty string means that QEMU will use plain text mode for 1039# migration, rather than TLS (Since 2.7) 1040# Note: 2.8 reports this by omitting tls-creds instead. 1041# 1042# @tls-hostname: hostname of the target host for the migration. This 1043# is required when using x509 based TLS credentials and the 1044# migration URI does not already include a hostname. For 1045# example if using fd: or exec: based migration, the 1046# hostname must be provided so that the server's x509 1047# certificate identity can be validated. (Since 2.7) 1048# An empty string means that QEMU will use the hostname 1049# associated with the migration URI, if any. (Since 2.9) 1050# Note: 2.8 reports this by omitting tls-hostname instead. 1051# 1052# @tls-authz: ID of the 'authz' object subclass that provides access control 1053# checking of the TLS x509 certificate distinguished name. (Since 1054# 4.0) 1055# 1056# @max-bandwidth: to set maximum speed for migration. maximum speed in 1057# bytes per second. (Since 2.8) 1058# 1059# @downtime-limit: set maximum tolerated downtime for migration. maximum 1060# downtime in milliseconds (Since 2.8) 1061# 1062# @x-checkpoint-delay: the delay time between two COLO checkpoints. (Since 2.8) 1063# 1064# @block-incremental: Affects how much storage is migrated when the 1065# block migration capability is enabled. When false, the entire 1066# storage backing chain is migrated into a flattened image at 1067# the destination; when true, only the active qcow2 layer is 1068# migrated and the destination must already have access to the 1069# same backing chain as was used on the source. (since 2.10) 1070# 1071# @multifd-channels: Number of channels used to migrate data in 1072# parallel. This is the same number that the 1073# number of sockets used for migration. 1074# The default value is 2 (since 4.0) 1075# 1076# @xbzrle-cache-size: cache size to be used by XBZRLE migration. It 1077# needs to be a multiple of the target page size 1078# and a power of 2 1079# (Since 2.11) 1080# 1081# @max-postcopy-bandwidth: Background transfer bandwidth during postcopy. 1082# Defaults to 0 (unlimited). In bytes per second. 1083# (Since 3.0) 1084# 1085# @max-cpu-throttle: maximum cpu throttle percentage. 1086# Defaults to 99. 1087# (Since 3.1) 1088# 1089# @multifd-compression: Which compression method to use. 1090# Defaults to none. (Since 5.0) 1091# 1092# @multifd-zlib-level: Set the compression level to be used in live 1093# migration, the compression level is an integer between 0 1094# and 9, where 0 means no compression, 1 means the best 1095# compression speed, and 9 means best compression ratio which 1096# will consume more CPU. 1097# Defaults to 1. (Since 5.0) 1098# 1099# @multifd-zstd-level: Set the compression level to be used in live 1100# migration, the compression level is an integer between 0 1101# and 20, where 0 means no compression, 1 means the best 1102# compression speed, and 20 means best compression ratio which 1103# will consume more CPU. 1104# Defaults to 1. (Since 5.0) 1105# 1106# @block-bitmap-mapping: Maps block nodes and bitmaps on them to 1107# aliases for the purpose of dirty bitmap migration. Such 1108# aliases may for example be the corresponding names on the 1109# opposite site. 1110# The mapping must be one-to-one, but not necessarily 1111# complete: On the source, unmapped bitmaps and all bitmaps 1112# on unmapped nodes will be ignored. On the destination, 1113# encountering an unmapped alias in the incoming migration 1114# stream will result in a report, and all further bitmap 1115# migration data will then be discarded. 1116# Note that the destination does not know about bitmaps it 1117# does not receive, so there is no limitation or requirement 1118# regarding the number of bitmaps received, or how they are 1119# named, or on which nodes they are placed. 1120# By default (when this parameter has never been set), bitmap 1121# names are mapped to themselves. Nodes are mapped to their 1122# block device name if there is one, and to their node name 1123# otherwise. (Since 5.2) 1124# 1125# Features: 1126# @unstable: Member @x-checkpoint-delay is experimental. 1127# 1128# Since: 2.4 1129## 1130{ 'struct': 'MigrationParameters', 1131 'data': { '*announce-initial': 'size', 1132 '*announce-max': 'size', 1133 '*announce-rounds': 'size', 1134 '*announce-step': 'size', 1135 '*compress-level': 'uint8', 1136 '*compress-threads': 'uint8', 1137 '*compress-wait-thread': 'bool', 1138 '*decompress-threads': 'uint8', 1139 '*throttle-trigger-threshold': 'uint8', 1140 '*cpu-throttle-initial': 'uint8', 1141 '*cpu-throttle-increment': 'uint8', 1142 '*cpu-throttle-tailslow': 'bool', 1143 '*tls-creds': 'str', 1144 '*tls-hostname': 'str', 1145 '*tls-authz': 'str', 1146 '*max-bandwidth': 'size', 1147 '*downtime-limit': 'uint64', 1148 '*x-checkpoint-delay': { 'type': 'uint32', 1149 'features': [ 'unstable' ] }, 1150 '*block-incremental': 'bool', 1151 '*multifd-channels': 'uint8', 1152 '*xbzrle-cache-size': 'size', 1153 '*max-postcopy-bandwidth': 'size', 1154 '*max-cpu-throttle': 'uint8', 1155 '*multifd-compression': 'MultiFDCompression', 1156 '*multifd-zlib-level': 'uint8', 1157 '*multifd-zstd-level': 'uint8', 1158 '*block-bitmap-mapping': [ 'BitmapMigrationNodeAlias' ] } } 1159 1160## 1161# @query-migrate-parameters: 1162# 1163# Returns information about the current migration parameters 1164# 1165# Returns: @MigrationParameters 1166# 1167# Since: 2.4 1168# 1169# Example: 1170# 1171# -> { "execute": "query-migrate-parameters" } 1172# <- { "return": { 1173# "decompress-threads": 2, 1174# "cpu-throttle-increment": 10, 1175# "compress-threads": 8, 1176# "compress-level": 1, 1177# "cpu-throttle-initial": 20, 1178# "max-bandwidth": 33554432, 1179# "downtime-limit": 300 1180# } 1181# } 1182# 1183## 1184{ 'command': 'query-migrate-parameters', 1185 'returns': 'MigrationParameters' } 1186 1187## 1188# @client_migrate_info: 1189# 1190# Set migration information for remote display. This makes the server 1191# ask the client to automatically reconnect using the new parameters 1192# once migration finished successfully. Only implemented for SPICE. 1193# 1194# @protocol: must be "spice" 1195# @hostname: migration target hostname 1196# @port: spice tcp port for plaintext channels 1197# @tls-port: spice tcp port for tls-secured channels 1198# @cert-subject: server certificate subject 1199# 1200# Since: 0.14 1201# 1202# Example: 1203# 1204# -> { "execute": "client_migrate_info", 1205# "arguments": { "protocol": "spice", 1206# "hostname": "virt42.lab.kraxel.org", 1207# "port": 1234 } } 1208# <- { "return": {} } 1209# 1210## 1211{ 'command': 'client_migrate_info', 1212 'data': { 'protocol': 'str', 'hostname': 'str', '*port': 'int', 1213 '*tls-port': 'int', '*cert-subject': 'str' } } 1214 1215## 1216# @migrate-start-postcopy: 1217# 1218# Followup to a migration command to switch the migration to postcopy mode. 1219# The postcopy-ram capability must be set on both source and destination 1220# before the original migration command. 1221# 1222# Since: 2.5 1223# 1224# Example: 1225# 1226# -> { "execute": "migrate-start-postcopy" } 1227# <- { "return": {} } 1228# 1229## 1230{ 'command': 'migrate-start-postcopy' } 1231 1232## 1233# @MIGRATION: 1234# 1235# Emitted when a migration event happens 1236# 1237# @status: @MigrationStatus describing the current migration status. 1238# 1239# Since: 2.4 1240# 1241# Example: 1242# 1243# <- {"timestamp": {"seconds": 1432121972, "microseconds": 744001}, 1244# "event": "MIGRATION", 1245# "data": {"status": "completed"} } 1246# 1247## 1248{ 'event': 'MIGRATION', 1249 'data': {'status': 'MigrationStatus'}} 1250 1251## 1252# @MIGRATION_PASS: 1253# 1254# Emitted from the source side of a migration at the start of each pass 1255# (when it syncs the dirty bitmap) 1256# 1257# @pass: An incrementing count (starting at 1 on the first pass) 1258# 1259# Since: 2.6 1260# 1261# Example: 1262# 1263# { "timestamp": {"seconds": 1449669631, "microseconds": 239225}, 1264# "event": "MIGRATION_PASS", "data": {"pass": 2} } 1265# 1266## 1267{ 'event': 'MIGRATION_PASS', 1268 'data': { 'pass': 'int' } } 1269 1270## 1271# @COLOMessage: 1272# 1273# The message transmission between Primary side and Secondary side. 1274# 1275# @checkpoint-ready: Secondary VM (SVM) is ready for checkpointing 1276# 1277# @checkpoint-request: Primary VM (PVM) tells SVM to prepare for checkpointing 1278# 1279# @checkpoint-reply: SVM gets PVM's checkpoint request 1280# 1281# @vmstate-send: VM's state will be sent by PVM. 1282# 1283# @vmstate-size: The total size of VMstate. 1284# 1285# @vmstate-received: VM's state has been received by SVM. 1286# 1287# @vmstate-loaded: VM's state has been loaded by SVM. 1288# 1289# Since: 2.8 1290## 1291{ 'enum': 'COLOMessage', 1292 'data': [ 'checkpoint-ready', 'checkpoint-request', 'checkpoint-reply', 1293 'vmstate-send', 'vmstate-size', 'vmstate-received', 1294 'vmstate-loaded' ] } 1295 1296## 1297# @COLOMode: 1298# 1299# The COLO current mode. 1300# 1301# @none: COLO is disabled. 1302# 1303# @primary: COLO node in primary side. 1304# 1305# @secondary: COLO node in slave side. 1306# 1307# Since: 2.8 1308## 1309{ 'enum': 'COLOMode', 1310 'data': [ 'none', 'primary', 'secondary'] } 1311 1312## 1313# @FailoverStatus: 1314# 1315# An enumeration of COLO failover status 1316# 1317# @none: no failover has ever happened 1318# 1319# @require: got failover requirement but not handled 1320# 1321# @active: in the process of doing failover 1322# 1323# @completed: finish the process of failover 1324# 1325# @relaunch: restart the failover process, from 'none' -> 'completed' (Since 2.9) 1326# 1327# Since: 2.8 1328## 1329{ 'enum': 'FailoverStatus', 1330 'data': [ 'none', 'require', 'active', 'completed', 'relaunch' ] } 1331 1332## 1333# @COLO_EXIT: 1334# 1335# Emitted when VM finishes COLO mode due to some errors happening or 1336# at the request of users. 1337# 1338# @mode: report COLO mode when COLO exited. 1339# 1340# @reason: describes the reason for the COLO exit. 1341# 1342# Since: 3.1 1343# 1344# Example: 1345# 1346# <- { "timestamp": {"seconds": 2032141960, "microseconds": 417172}, 1347# "event": "COLO_EXIT", "data": {"mode": "primary", "reason": "request" } } 1348# 1349## 1350{ 'event': 'COLO_EXIT', 1351 'data': {'mode': 'COLOMode', 'reason': 'COLOExitReason' } } 1352 1353## 1354# @COLOExitReason: 1355# 1356# The reason for a COLO exit. 1357# 1358# @none: failover has never happened. This state does not occur 1359# in the COLO_EXIT event, and is only visible in the result of 1360# query-colo-status. 1361# 1362# @request: COLO exit is due to an external request. 1363# 1364# @error: COLO exit is due to an internal error. 1365# 1366# @processing: COLO is currently handling a failover (since 4.0). 1367# 1368# Since: 3.1 1369## 1370{ 'enum': 'COLOExitReason', 1371 'data': [ 'none', 'request', 'error' , 'processing' ] } 1372 1373## 1374# @x-colo-lost-heartbeat: 1375# 1376# Tell qemu that heartbeat is lost, request it to do takeover procedures. 1377# If this command is sent to the PVM, the Primary side will exit COLO mode. 1378# If sent to the Secondary, the Secondary side will run failover work, 1379# then takes over server operation to become the service VM. 1380# 1381# Features: 1382# @unstable: This command is experimental. 1383# 1384# Since: 2.8 1385# 1386# Example: 1387# 1388# -> { "execute": "x-colo-lost-heartbeat" } 1389# <- { "return": {} } 1390# 1391## 1392{ 'command': 'x-colo-lost-heartbeat', 1393 'features': [ 'unstable' ] } 1394 1395## 1396# @migrate_cancel: 1397# 1398# Cancel the current executing migration process. 1399# 1400# Returns: nothing on success 1401# 1402# Notes: This command succeeds even if there is no migration process running. 1403# 1404# Since: 0.14 1405# 1406# Example: 1407# 1408# -> { "execute": "migrate_cancel" } 1409# <- { "return": {} } 1410# 1411## 1412{ 'command': 'migrate_cancel' } 1413 1414## 1415# @migrate-continue: 1416# 1417# Continue migration when it's in a paused state. 1418# 1419# @state: The state the migration is currently expected to be in 1420# 1421# Returns: nothing on success 1422# 1423# Since: 2.11 1424# 1425# Example: 1426# 1427# -> { "execute": "migrate-continue" , "arguments": 1428# { "state": "pre-switchover" } } 1429# <- { "return": {} } 1430## 1431{ 'command': 'migrate-continue', 'data': {'state': 'MigrationStatus'} } 1432 1433## 1434# @migrate: 1435# 1436# Migrates the current running guest to another Virtual Machine. 1437# 1438# @uri: the Uniform Resource Identifier of the destination VM 1439# 1440# @blk: do block migration (full disk copy) 1441# 1442# @inc: incremental disk copy migration 1443# 1444# @detach: this argument exists only for compatibility reasons and 1445# is ignored by QEMU 1446# 1447# @resume: resume one paused migration, default "off". (since 3.0) 1448# 1449# Returns: nothing on success 1450# 1451# Since: 0.14 1452# 1453# Notes: 1454# 1455# 1. The 'query-migrate' command should be used to check migration's progress 1456# and final result (this information is provided by the 'status' member) 1457# 1458# 2. All boolean arguments default to false 1459# 1460# 3. The user Monitor's "detach" argument is invalid in QMP and should not 1461# be used 1462# 1463# Example: 1464# 1465# -> { "execute": "migrate", "arguments": { "uri": "tcp:0:4446" } } 1466# <- { "return": {} } 1467# 1468## 1469{ 'command': 'migrate', 1470 'data': {'uri': 'str', '*blk': 'bool', '*inc': 'bool', 1471 '*detach': 'bool', '*resume': 'bool' } } 1472 1473## 1474# @migrate-incoming: 1475# 1476# Start an incoming migration, the qemu must have been started 1477# with -incoming defer 1478# 1479# @uri: The Uniform Resource Identifier identifying the source or 1480# address to listen on 1481# 1482# Returns: nothing on success 1483# 1484# Since: 2.3 1485# 1486# Notes: 1487# 1488# 1. It's a bad idea to use a string for the uri, but it needs to stay 1489# compatible with -incoming and the format of the uri is already exposed 1490# above libvirt. 1491# 1492# 2. QEMU must be started with -incoming defer to allow migrate-incoming to 1493# be used. 1494# 1495# 3. The uri format is the same as for -incoming 1496# 1497# Example: 1498# 1499# -> { "execute": "migrate-incoming", 1500# "arguments": { "uri": "tcp::4446" } } 1501# <- { "return": {} } 1502# 1503## 1504{ 'command': 'migrate-incoming', 'data': {'uri': 'str' } } 1505 1506## 1507# @xen-save-devices-state: 1508# 1509# Save the state of all devices to file. The RAM and the block devices 1510# of the VM are not saved by this command. 1511# 1512# @filename: the file to save the state of the devices to as binary 1513# data. See xen-save-devices-state.txt for a description of the binary 1514# format. 1515# 1516# @live: Optional argument to ask QEMU to treat this command as part of a live 1517# migration. Default to true. (since 2.11) 1518# 1519# Returns: Nothing on success 1520# 1521# Since: 1.1 1522# 1523# Example: 1524# 1525# -> { "execute": "xen-save-devices-state", 1526# "arguments": { "filename": "/tmp/save" } } 1527# <- { "return": {} } 1528# 1529## 1530{ 'command': 'xen-save-devices-state', 1531 'data': {'filename': 'str', '*live':'bool' } } 1532 1533## 1534# @xen-set-global-dirty-log: 1535# 1536# Enable or disable the global dirty log mode. 1537# 1538# @enable: true to enable, false to disable. 1539# 1540# Returns: nothing 1541# 1542# Since: 1.3 1543# 1544# Example: 1545# 1546# -> { "execute": "xen-set-global-dirty-log", 1547# "arguments": { "enable": true } } 1548# <- { "return": {} } 1549# 1550## 1551{ 'command': 'xen-set-global-dirty-log', 'data': { 'enable': 'bool' } } 1552 1553## 1554# @xen-load-devices-state: 1555# 1556# Load the state of all devices from file. The RAM and the block devices 1557# of the VM are not loaded by this command. 1558# 1559# @filename: the file to load the state of the devices from as binary 1560# data. See xen-save-devices-state.txt for a description of the binary 1561# format. 1562# 1563# Since: 2.7 1564# 1565# Example: 1566# 1567# -> { "execute": "xen-load-devices-state", 1568# "arguments": { "filename": "/tmp/resume" } } 1569# <- { "return": {} } 1570# 1571## 1572{ 'command': 'xen-load-devices-state', 'data': {'filename': 'str'} } 1573 1574## 1575# @xen-set-replication: 1576# 1577# Enable or disable replication. 1578# 1579# @enable: true to enable, false to disable. 1580# 1581# @primary: true for primary or false for secondary. 1582# 1583# @failover: true to do failover, false to stop. but cannot be 1584# specified if 'enable' is true. default value is false. 1585# 1586# Returns: nothing. 1587# 1588# Example: 1589# 1590# -> { "execute": "xen-set-replication", 1591# "arguments": {"enable": true, "primary": false} } 1592# <- { "return": {} } 1593# 1594# Since: 2.9 1595## 1596{ 'command': 'xen-set-replication', 1597 'data': { 'enable': 'bool', 'primary': 'bool', '*failover' : 'bool' }, 1598 'if': 'CONFIG_REPLICATION' } 1599 1600## 1601# @ReplicationStatus: 1602# 1603# The result format for 'query-xen-replication-status'. 1604# 1605# @error: true if an error happened, false if replication is normal. 1606# 1607# @desc: the human readable error description string, when 1608# @error is 'true'. 1609# 1610# Since: 2.9 1611## 1612{ 'struct': 'ReplicationStatus', 1613 'data': { 'error': 'bool', '*desc': 'str' }, 1614 'if': 'CONFIG_REPLICATION' } 1615 1616## 1617# @query-xen-replication-status: 1618# 1619# Query replication status while the vm is running. 1620# 1621# Returns: A @ReplicationStatus object showing the status. 1622# 1623# Example: 1624# 1625# -> { "execute": "query-xen-replication-status" } 1626# <- { "return": { "error": false } } 1627# 1628# Since: 2.9 1629## 1630{ 'command': 'query-xen-replication-status', 1631 'returns': 'ReplicationStatus', 1632 'if': 'CONFIG_REPLICATION' } 1633 1634## 1635# @xen-colo-do-checkpoint: 1636# 1637# Xen uses this command to notify replication to trigger a checkpoint. 1638# 1639# Returns: nothing. 1640# 1641# Example: 1642# 1643# -> { "execute": "xen-colo-do-checkpoint" } 1644# <- { "return": {} } 1645# 1646# Since: 2.9 1647## 1648{ 'command': 'xen-colo-do-checkpoint', 1649 'if': 'CONFIG_REPLICATION' } 1650 1651## 1652# @COLOStatus: 1653# 1654# The result format for 'query-colo-status'. 1655# 1656# @mode: COLO running mode. If COLO is running, this field will return 1657# 'primary' or 'secondary'. 1658# 1659# @last-mode: COLO last running mode. If COLO is running, this field 1660# will return same like mode field, after failover we can 1661# use this field to get last colo mode. (since 4.0) 1662# 1663# @reason: describes the reason for the COLO exit. 1664# 1665# Since: 3.1 1666## 1667{ 'struct': 'COLOStatus', 1668 'data': { 'mode': 'COLOMode', 'last-mode': 'COLOMode', 1669 'reason': 'COLOExitReason' } } 1670 1671## 1672# @query-colo-status: 1673# 1674# Query COLO status while the vm is running. 1675# 1676# Returns: A @COLOStatus object showing the status. 1677# 1678# Example: 1679# 1680# -> { "execute": "query-colo-status" } 1681# <- { "return": { "mode": "primary", "last-mode": "none", "reason": "request" } } 1682# 1683# Since: 3.1 1684## 1685{ 'command': 'query-colo-status', 1686 'returns': 'COLOStatus' } 1687 1688## 1689# @migrate-recover: 1690# 1691# Provide a recovery migration stream URI. 1692# 1693# @uri: the URI to be used for the recovery of migration stream. 1694# 1695# Returns: nothing. 1696# 1697# Example: 1698# 1699# -> { "execute": "migrate-recover", 1700# "arguments": { "uri": "tcp:192.168.1.200:12345" } } 1701# <- { "return": {} } 1702# 1703# Since: 3.0 1704## 1705{ 'command': 'migrate-recover', 1706 'data': { 'uri': 'str' }, 1707 'allow-oob': true } 1708 1709## 1710# @migrate-pause: 1711# 1712# Pause a migration. Currently it only supports postcopy. 1713# 1714# Returns: nothing. 1715# 1716# Example: 1717# 1718# -> { "execute": "migrate-pause" } 1719# <- { "return": {} } 1720# 1721# Since: 3.0 1722## 1723{ 'command': 'migrate-pause', 'allow-oob': true } 1724 1725## 1726# @UNPLUG_PRIMARY: 1727# 1728# Emitted from source side of a migration when migration state is 1729# WAIT_UNPLUG. Device was unplugged by guest operating system. 1730# Device resources in QEMU are kept on standby to be able to re-plug it in case 1731# of migration failure. 1732# 1733# @device-id: QEMU device id of the unplugged device 1734# 1735# Since: 4.2 1736# 1737# Example: 1738# 1739# <- { "event": "UNPLUG_PRIMARY", 1740# "data": { "device-id": "hostdev0" }, 1741# "timestamp": { "seconds": 1265044230, "microseconds": 450486 } } 1742# 1743## 1744{ 'event': 'UNPLUG_PRIMARY', 1745 'data': { 'device-id': 'str' } } 1746 1747## 1748# @DirtyRateVcpu: 1749# 1750# Dirty rate of vcpu. 1751# 1752# @id: vcpu index. 1753# 1754# @dirty-rate: dirty rate. 1755# 1756# Since: 6.2 1757## 1758{ 'struct': 'DirtyRateVcpu', 1759 'data': { 'id': 'int', 'dirty-rate': 'int64' } } 1760 1761## 1762# @DirtyRateStatus: 1763# 1764# An enumeration of dirtyrate status. 1765# 1766# @unstarted: the dirtyrate thread has not been started. 1767# 1768# @measuring: the dirtyrate thread is measuring. 1769# 1770# @measured: the dirtyrate thread has measured and results are available. 1771# 1772# Since: 5.2 1773## 1774{ 'enum': 'DirtyRateStatus', 1775 'data': [ 'unstarted', 'measuring', 'measured'] } 1776 1777## 1778# @DirtyRateMeasureMode: 1779# 1780# An enumeration of mode of measuring dirtyrate. 1781# 1782# @page-sampling: calculate dirtyrate by sampling pages. 1783# 1784# @dirty-ring: calculate dirtyrate by dirty ring. 1785# 1786# @dirty-bitmap: calculate dirtyrate by dirty bitmap. 1787# 1788# Since: 6.2 1789## 1790{ 'enum': 'DirtyRateMeasureMode', 1791 'data': ['page-sampling', 'dirty-ring', 'dirty-bitmap'] } 1792 1793## 1794# @DirtyRateInfo: 1795# 1796# Information about current dirty page rate of vm. 1797# 1798# @dirty-rate: an estimate of the dirty page rate of the VM in units of 1799# MB/s, present only when estimating the rate has completed. 1800# 1801# @status: status containing dirtyrate query status includes 1802# 'unstarted' or 'measuring' or 'measured' 1803# 1804# @start-time: start time in units of second for calculation 1805# 1806# @calc-time: time in units of second for sample dirty pages 1807# 1808# @sample-pages: page count per GB for sample dirty pages 1809# the default value is 512 (since 6.1) 1810# 1811# @mode: mode containing method of calculate dirtyrate includes 1812# 'page-sampling' and 'dirty-ring' (Since 6.2) 1813# 1814# @vcpu-dirty-rate: dirtyrate for each vcpu if dirty-ring 1815# mode specified (Since 6.2) 1816# 1817# Since: 5.2 1818## 1819{ 'struct': 'DirtyRateInfo', 1820 'data': {'*dirty-rate': 'int64', 1821 'status': 'DirtyRateStatus', 1822 'start-time': 'int64', 1823 'calc-time': 'int64', 1824 'sample-pages': 'uint64', 1825 'mode': 'DirtyRateMeasureMode', 1826 '*vcpu-dirty-rate': [ 'DirtyRateVcpu' ] } } 1827 1828## 1829# @calc-dirty-rate: 1830# 1831# start calculating dirty page rate for vm 1832# 1833# @calc-time: time in units of second for sample dirty pages 1834# 1835# @sample-pages: page count per GB for sample dirty pages 1836# the default value is 512 (since 6.1) 1837# 1838# @mode: mechanism of calculating dirtyrate includes 1839# 'page-sampling' and 'dirty-ring' (Since 6.1) 1840# 1841# Since: 5.2 1842# 1843# Example: 1844# 1845# {"execute": "calc-dirty-rate", "arguments": {"calc-time": 1, 1846# 'sample-pages': 512} } 1847# 1848## 1849{ 'command': 'calc-dirty-rate', 'data': {'calc-time': 'int64', 1850 '*sample-pages': 'int', 1851 '*mode': 'DirtyRateMeasureMode'} } 1852 1853## 1854# @query-dirty-rate: 1855# 1856# query dirty page rate in units of MB/s for vm 1857# 1858# Since: 5.2 1859## 1860{ 'command': 'query-dirty-rate', 'returns': 'DirtyRateInfo' } 1861 1862## 1863# @snapshot-save: 1864# 1865# Save a VM snapshot 1866# 1867# @job-id: identifier for the newly created job 1868# @tag: name of the snapshot to create 1869# @vmstate: block device node name to save vmstate to 1870# @devices: list of block device node names to save a snapshot to 1871# 1872# Applications should not assume that the snapshot save is complete 1873# when this command returns. The job commands / events must be used 1874# to determine completion and to fetch details of any errors that arise. 1875# 1876# Note that execution of the guest CPUs may be stopped during the 1877# time it takes to save the snapshot. A future version of QEMU 1878# may ensure CPUs are executing continuously. 1879# 1880# It is strongly recommended that @devices contain all writable 1881# block device nodes if a consistent snapshot is required. 1882# 1883# If @tag already exists, an error will be reported 1884# 1885# Returns: nothing 1886# 1887# Example: 1888# 1889# -> { "execute": "snapshot-save", 1890# "arguments": { 1891# "job-id": "snapsave0", 1892# "tag": "my-snap", 1893# "vmstate": "disk0", 1894# "devices": ["disk0", "disk1"] 1895# } 1896# } 1897# <- { "return": { } } 1898# <- {"event": "JOB_STATUS_CHANGE", 1899# "data": {"status": "created", "id": "snapsave0"}} 1900# <- {"event": "JOB_STATUS_CHANGE", 1901# "data": {"status": "running", "id": "snapsave0"}} 1902# <- {"event": "STOP"} 1903# <- {"event": "RESUME"} 1904# <- {"event": "JOB_STATUS_CHANGE", 1905# "data": {"status": "waiting", "id": "snapsave0"}} 1906# <- {"event": "JOB_STATUS_CHANGE", 1907# "data": {"status": "pending", "id": "snapsave0"}} 1908# <- {"event": "JOB_STATUS_CHANGE", 1909# "data": {"status": "concluded", "id": "snapsave0"}} 1910# -> {"execute": "query-jobs"} 1911# <- {"return": [{"current-progress": 1, 1912# "status": "concluded", 1913# "total-progress": 1, 1914# "type": "snapshot-save", 1915# "id": "snapsave0"}]} 1916# 1917# Since: 6.0 1918## 1919{ 'command': 'snapshot-save', 1920 'data': { 'job-id': 'str', 1921 'tag': 'str', 1922 'vmstate': 'str', 1923 'devices': ['str'] } } 1924 1925## 1926# @snapshot-load: 1927# 1928# Load a VM snapshot 1929# 1930# @job-id: identifier for the newly created job 1931# @tag: name of the snapshot to load. 1932# @vmstate: block device node name to load vmstate from 1933# @devices: list of block device node names to load a snapshot from 1934# 1935# Applications should not assume that the snapshot load is complete 1936# when this command returns. The job commands / events must be used 1937# to determine completion and to fetch details of any errors that arise. 1938# 1939# Note that execution of the guest CPUs will be stopped during the 1940# time it takes to load the snapshot. 1941# 1942# It is strongly recommended that @devices contain all writable 1943# block device nodes that can have changed since the original 1944# @snapshot-save command execution. 1945# 1946# Returns: nothing 1947# 1948# Example: 1949# 1950# -> { "execute": "snapshot-load", 1951# "arguments": { 1952# "job-id": "snapload0", 1953# "tag": "my-snap", 1954# "vmstate": "disk0", 1955# "devices": ["disk0", "disk1"] 1956# } 1957# } 1958# <- { "return": { } } 1959# <- {"event": "JOB_STATUS_CHANGE", 1960# "data": {"status": "created", "id": "snapload0"}} 1961# <- {"event": "JOB_STATUS_CHANGE", 1962# "data": {"status": "running", "id": "snapload0"}} 1963# <- {"event": "STOP"} 1964# <- {"event": "RESUME"} 1965# <- {"event": "JOB_STATUS_CHANGE", 1966# "data": {"status": "waiting", "id": "snapload0"}} 1967# <- {"event": "JOB_STATUS_CHANGE", 1968# "data": {"status": "pending", "id": "snapload0"}} 1969# <- {"event": "JOB_STATUS_CHANGE", 1970# "data": {"status": "concluded", "id": "snapload0"}} 1971# -> {"execute": "query-jobs"} 1972# <- {"return": [{"current-progress": 1, 1973# "status": "concluded", 1974# "total-progress": 1, 1975# "type": "snapshot-load", 1976# "id": "snapload0"}]} 1977# 1978# Since: 6.0 1979## 1980{ 'command': 'snapshot-load', 1981 'data': { 'job-id': 'str', 1982 'tag': 'str', 1983 'vmstate': 'str', 1984 'devices': ['str'] } } 1985 1986## 1987# @snapshot-delete: 1988# 1989# Delete a VM snapshot 1990# 1991# @job-id: identifier for the newly created job 1992# @tag: name of the snapshot to delete. 1993# @devices: list of block device node names to delete a snapshot from 1994# 1995# Applications should not assume that the snapshot delete is complete 1996# when this command returns. The job commands / events must be used 1997# to determine completion and to fetch details of any errors that arise. 1998# 1999# Returns: nothing 2000# 2001# Example: 2002# 2003# -> { "execute": "snapshot-delete", 2004# "arguments": { 2005# "job-id": "snapdelete0", 2006# "tag": "my-snap", 2007# "devices": ["disk0", "disk1"] 2008# } 2009# } 2010# <- { "return": { } } 2011# <- {"event": "JOB_STATUS_CHANGE", 2012# "data": {"status": "created", "id": "snapdelete0"}} 2013# <- {"event": "JOB_STATUS_CHANGE", 2014# "data": {"status": "running", "id": "snapdelete0"}} 2015# <- {"event": "JOB_STATUS_CHANGE", 2016# "data": {"status": "waiting", "id": "snapdelete0"}} 2017# <- {"event": "JOB_STATUS_CHANGE", 2018# "data": {"status": "pending", "id": "snapdelete0"}} 2019# <- {"event": "JOB_STATUS_CHANGE", 2020# "data": {"status": "concluded", "id": "snapdelete0"}} 2021# -> {"execute": "query-jobs"} 2022# <- {"return": [{"current-progress": 1, 2023# "status": "concluded", 2024# "total-progress": 1, 2025# "type": "snapshot-delete", 2026# "id": "snapdelete0"}]} 2027# 2028# Since: 6.0 2029## 2030{ 'command': 'snapshot-delete', 2031 'data': { 'job-id': 'str', 2032 'tag': 'str', 2033 'devices': ['str'] } } 2034