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