148685a8eSMarkus Armbruster# -*- Mode: Python -*- 2f7160f32SAndrea Bolognani# vim: filetype=python 348685a8eSMarkus Armbruster# 448685a8eSMarkus Armbruster 548685a8eSMarkus Armbruster## 648685a8eSMarkus Armbruster# = Migration 748685a8eSMarkus Armbruster## 848685a8eSMarkus Armbruster 948685a8eSMarkus Armbruster{ 'include': 'common.json' } 109aca82baSJuan Quintela{ 'include': 'sockets.json' } 1148685a8eSMarkus Armbruster 1248685a8eSMarkus Armbruster## 1348685a8eSMarkus Armbruster# @MigrationStats: 1448685a8eSMarkus Armbruster# 1548685a8eSMarkus Armbruster# Detailed migration status. 1648685a8eSMarkus Armbruster# 1748685a8eSMarkus Armbruster# @transferred: amount of bytes already transferred to the target VM 1848685a8eSMarkus Armbruster# 19a937b6aaSMarkus Armbruster# @remaining: amount of bytes remaining to be transferred to the 20a937b6aaSMarkus Armbruster# target VM 2148685a8eSMarkus Armbruster# 2248685a8eSMarkus Armbruster# @total: total amount of bytes involved in the migration process 2348685a8eSMarkus Armbruster# 2448685a8eSMarkus Armbruster# @duplicate: number of duplicate (zero) pages (since 1.2) 2548685a8eSMarkus Armbruster# 2648685a8eSMarkus Armbruster# @skipped: number of skipped zero pages (since 1.5) 2748685a8eSMarkus Armbruster# 2848685a8eSMarkus Armbruster# @normal: number of normal pages (since 1.2) 2948685a8eSMarkus Armbruster# 3048685a8eSMarkus Armbruster# @normal-bytes: number of normal bytes sent (since 1.2) 3148685a8eSMarkus Armbruster# 32a937b6aaSMarkus Armbruster# @dirty-pages-rate: number of pages dirtied by second by the guest 33a937b6aaSMarkus Armbruster# (since 1.3) 3448685a8eSMarkus Armbruster# 3548685a8eSMarkus Armbruster# @mbps: throughput in megabits/sec. (since 1.6) 3648685a8eSMarkus Armbruster# 37a937b6aaSMarkus Armbruster# @dirty-sync-count: number of times that dirty ram was synchronized 38a937b6aaSMarkus Armbruster# (since 2.1) 3948685a8eSMarkus Armbruster# 40a937b6aaSMarkus Armbruster# @postcopy-requests: The number of page requests received from the 41a937b6aaSMarkus Armbruster# destination (since 2.7) 4248685a8eSMarkus Armbruster# 4348685a8eSMarkus Armbruster# @page-size: The number of bytes per page for the various page-based 4448685a8eSMarkus Armbruster# statistics (since 2.10) 4548685a8eSMarkus Armbruster# 46a61c45bdSJuan Quintela# @multifd-bytes: The number of bytes sent through multifd (since 3.0) 47a61c45bdSJuan Quintela# 48aecbfe9cSXiao Guangrong# @pages-per-second: the number of memory pages transferred per second 49aecbfe9cSXiao Guangrong# (Since 4.0) 50aecbfe9cSXiao Guangrong# 51ae680668SDavid Edmondson# @precopy-bytes: The number of bytes sent in the pre-copy phase 52ae680668SDavid Edmondson# (since 7.0). 53ae680668SDavid Edmondson# 54ae680668SDavid Edmondson# @downtime-bytes: The number of bytes sent while the guest is paused 55ae680668SDavid Edmondson# (since 7.0). 56ae680668SDavid Edmondson# 57ae680668SDavid Edmondson# @postcopy-bytes: The number of bytes sent during the post-copy phase 58ae680668SDavid Edmondson# (since 7.0). 59ae680668SDavid Edmondson# 60a937b6aaSMarkus Armbruster# @dirty-sync-missed-zero-copy: Number of times dirty RAM 61a937b6aaSMarkus Armbruster# synchronization could not avoid copying dirty pages. This is 62a937b6aaSMarkus Armbruster# between 0 and @dirty-sync-count * @multifd-channels. (since 63a937b6aaSMarkus Armbruster# 7.1) 64a937b6aaSMarkus Armbruster# 659bc6e893SMarkus Armbruster# Since: 0.14 6648685a8eSMarkus Armbruster## 6748685a8eSMarkus Armbruster{ 'struct': 'MigrationStats', 6848685a8eSMarkus Armbruster 'data': {'transferred': 'int', 'remaining': 'int', 'total': 'int' , 6948685a8eSMarkus Armbruster 'duplicate': 'int', 'skipped': 'int', 'normal': 'int', 7048685a8eSMarkus Armbruster 'normal-bytes': 'int', 'dirty-pages-rate': 'int', 7148685a8eSMarkus Armbruster 'mbps': 'number', 'dirty-sync-count': 'int', 72a61c45bdSJuan Quintela 'postcopy-requests': 'int', 'page-size': 'int', 73ae680668SDavid Edmondson 'multifd-bytes': 'uint64', 'pages-per-second': 'uint64', 74ae680668SDavid Edmondson 'precopy-bytes': 'uint64', 'downtime-bytes': 'uint64', 75cf20c897SLeonardo Bras 'postcopy-bytes': 'uint64', 76cf20c897SLeonardo Bras 'dirty-sync-missed-zero-copy': 'uint64' } } 7748685a8eSMarkus Armbruster 7848685a8eSMarkus Armbruster## 7948685a8eSMarkus Armbruster# @XBZRLECacheStats: 8048685a8eSMarkus Armbruster# 8148685a8eSMarkus Armbruster# Detailed XBZRLE migration cache statistics 8248685a8eSMarkus Armbruster# 8348685a8eSMarkus Armbruster# @cache-size: XBZRLE cache size 8448685a8eSMarkus Armbruster# 8548685a8eSMarkus Armbruster# @bytes: amount of bytes already transferred to the target VM 8648685a8eSMarkus Armbruster# 8748685a8eSMarkus Armbruster# @pages: amount of pages transferred to the target VM 8848685a8eSMarkus Armbruster# 8948685a8eSMarkus Armbruster# @cache-miss: number of cache miss 9048685a8eSMarkus Armbruster# 9148685a8eSMarkus Armbruster# @cache-miss-rate: rate of cache miss (since 2.1) 9248685a8eSMarkus Armbruster# 93e460a4b1SWei Wang# @encoding-rate: rate of encoded bytes (since 5.1) 94e460a4b1SWei Wang# 9548685a8eSMarkus Armbruster# @overflow: number of overflows 9648685a8eSMarkus Armbruster# 9748685a8eSMarkus Armbruster# Since: 1.2 9848685a8eSMarkus Armbruster## 9948685a8eSMarkus Armbruster{ 'struct': 'XBZRLECacheStats', 1008b9407a0SMarkus Armbruster 'data': {'cache-size': 'size', 'bytes': 'int', 'pages': 'int', 10148685a8eSMarkus Armbruster 'cache-miss': 'int', 'cache-miss-rate': 'number', 102e460a4b1SWei Wang 'encoding-rate': 'number', 'overflow': 'int' } } 10348685a8eSMarkus Armbruster 10448685a8eSMarkus Armbruster## 10576e03000SXiao Guangrong# @CompressionStats: 10676e03000SXiao Guangrong# 10776e03000SXiao Guangrong# Detailed migration compression statistics 10876e03000SXiao Guangrong# 10976e03000SXiao Guangrong# @pages: amount of pages compressed and transferred to the target VM 11076e03000SXiao Guangrong# 111a937b6aaSMarkus Armbruster# @busy: count of times that no free thread was available to compress 112a937b6aaSMarkus Armbruster# data 11376e03000SXiao Guangrong# 11476e03000SXiao Guangrong# @busy-rate: rate of thread busy 11576e03000SXiao Guangrong# 11676e03000SXiao Guangrong# @compressed-size: amount of bytes after compression 11776e03000SXiao Guangrong# 11876e03000SXiao Guangrong# @compression-rate: rate of compressed size 11976e03000SXiao Guangrong# 12076e03000SXiao Guangrong# Since: 3.1 12176e03000SXiao Guangrong## 12276e03000SXiao Guangrong{ 'struct': 'CompressionStats', 12376e03000SXiao Guangrong 'data': {'pages': 'int', 'busy': 'int', 'busy-rate': 'number', 12476e03000SXiao Guangrong 'compressed-size': 'int', 'compression-rate': 'number' } } 12576e03000SXiao Guangrong 12676e03000SXiao Guangrong## 12748685a8eSMarkus Armbruster# @MigrationStatus: 12848685a8eSMarkus Armbruster# 12948685a8eSMarkus Armbruster# An enumeration of migration status. 13048685a8eSMarkus Armbruster# 13148685a8eSMarkus Armbruster# @none: no migration has ever happened. 13248685a8eSMarkus Armbruster# 13348685a8eSMarkus Armbruster# @setup: migration process has been initiated. 13448685a8eSMarkus Armbruster# 13548685a8eSMarkus Armbruster# @cancelling: in the process of cancelling migration. 13648685a8eSMarkus Armbruster# 13748685a8eSMarkus Armbruster# @cancelled: cancelling migration is finished. 13848685a8eSMarkus Armbruster# 13948685a8eSMarkus Armbruster# @active: in the process of doing migration. 14048685a8eSMarkus Armbruster# 141a937b6aaSMarkus Armbruster# @postcopy-active: like active, but now in postcopy mode. (since 142a937b6aaSMarkus Armbruster# 2.5) 14348685a8eSMarkus Armbruster# 14451f63ec7SPeter Maydell# @postcopy-paused: during postcopy but paused. (since 3.0) 145a688d2c1SPeter Xu# 146a937b6aaSMarkus Armbruster# @postcopy-recover: trying to recover from a paused postcopy. (since 147a937b6aaSMarkus Armbruster# 3.0) 148135b87b4SPeter Xu# 14948685a8eSMarkus Armbruster# @completed: migration is finished. 15048685a8eSMarkus Armbruster# 15148685a8eSMarkus Armbruster# @failed: some error occurred during migration process. 15248685a8eSMarkus Armbruster# 153a937b6aaSMarkus Armbruster# @colo: VM is in the process of fault tolerance, VM can not get into 154a937b6aaSMarkus Armbruster# this state unless colo capability is enabled for migration. 155a937b6aaSMarkus Armbruster# (since 2.8) 15648685a8eSMarkus Armbruster# 15731e06077SDr. David Alan Gilbert# @pre-switchover: Paused before device serialisation. (since 2.11) 15831e06077SDr. David Alan Gilbert# 159a937b6aaSMarkus Armbruster# @device: During device serialisation when pause-before-switchover is 160a937b6aaSMarkus Armbruster# enabled (since 2.11) 16131e06077SDr. David Alan Gilbert# 162a937b6aaSMarkus Armbruster# @wait-unplug: wait for device unplug request by guest OS to be 163a937b6aaSMarkus Armbruster# completed. (since 4.2) 164c7e0acd5SJens Freimann# 16548685a8eSMarkus Armbruster# Since: 2.3 16648685a8eSMarkus Armbruster## 16748685a8eSMarkus Armbruster{ 'enum': 'MigrationStatus', 16848685a8eSMarkus Armbruster 'data': [ 'none', 'setup', 'cancelling', 'cancelled', 169a688d2c1SPeter Xu 'active', 'postcopy-active', 'postcopy-paused', 170135b87b4SPeter Xu 'postcopy-recover', 'completed', 'failed', 'colo', 171c7e0acd5SJens Freimann 'pre-switchover', 'device', 'wait-unplug' ] } 1723710586cSKirti Wankhede## 1733710586cSKirti Wankhede# @VfioStats: 1743710586cSKirti Wankhede# 1753710586cSKirti Wankhede# Detailed VFIO devices migration statistics 1763710586cSKirti Wankhede# 177a937b6aaSMarkus Armbruster# @transferred: amount of bytes transferred to the target VM by VFIO 178a937b6aaSMarkus Armbruster# devices 1793710586cSKirti Wankhede# 1803710586cSKirti Wankhede# Since: 5.2 1813710586cSKirti Wankhede## 1823710586cSKirti Wankhede{ 'struct': 'VfioStats', 1833710586cSKirti Wankhede 'data': {'transferred': 'int' } } 18448685a8eSMarkus Armbruster 18548685a8eSMarkus Armbruster## 18648685a8eSMarkus Armbruster# @MigrationInfo: 18748685a8eSMarkus Armbruster# 18848685a8eSMarkus Armbruster# Information about current migration process. 18948685a8eSMarkus Armbruster# 19048685a8eSMarkus Armbruster# @status: @MigrationStatus describing the current migration status. 191a937b6aaSMarkus Armbruster# If this field is not returned, no migration process has been 192a937b6aaSMarkus Armbruster# initiated 19348685a8eSMarkus Armbruster# 194a937b6aaSMarkus Armbruster# @ram: @MigrationStats containing detailed migration status, only 195a937b6aaSMarkus Armbruster# returned if status is 'active' or 'completed'(since 1.2) 19648685a8eSMarkus Armbruster# 197a937b6aaSMarkus Armbruster# @disk: @MigrationStats containing detailed disk migration status, 198a937b6aaSMarkus Armbruster# only returned if status is 'active' and it is a block migration 19948685a8eSMarkus Armbruster# 20048685a8eSMarkus Armbruster# @xbzrle-cache: @XBZRLECacheStats containing detailed XBZRLE 20148685a8eSMarkus Armbruster# migration statistics, only returned if XBZRLE feature is on and 20248685a8eSMarkus Armbruster# status is 'active' or 'completed' (since 1.2) 20348685a8eSMarkus Armbruster# 20448685a8eSMarkus Armbruster# @total-time: total amount of milliseconds since migration started. 205a937b6aaSMarkus Armbruster# If migration has ended, it returns the total migration time. 206a937b6aaSMarkus Armbruster# (since 1.2) 20748685a8eSMarkus Armbruster# 208a937b6aaSMarkus Armbruster# @downtime: only present when migration finishes correctly total 209a937b6aaSMarkus Armbruster# downtime in milliseconds for the guest. (since 1.3) 21048685a8eSMarkus Armbruster# 211a937b6aaSMarkus Armbruster# @expected-downtime: only present while migration is active expected 212a937b6aaSMarkus Armbruster# downtime in milliseconds for the guest in last walk of the dirty 213a937b6aaSMarkus Armbruster# bitmap. (since 1.3) 21448685a8eSMarkus Armbruster# 215a660eed4SPeter Maydell# @setup-time: amount of setup time in milliseconds *before* the 216a937b6aaSMarkus Armbruster# iterations begin but *after* the QMP command is issued. This is 217a937b6aaSMarkus Armbruster# designed to provide an accounting of any activities (such as 218a937b6aaSMarkus Armbruster# RDMA pinning) which may be expensive, but do not actually occur 219a937b6aaSMarkus Armbruster# during the iterative migration rounds themselves. (since 1.6) 22048685a8eSMarkus Armbruster# 22148685a8eSMarkus Armbruster# @cpu-throttle-percentage: percentage of time guest cpus are being 222a937b6aaSMarkus Armbruster# throttled during auto-converge. This is only present when 223a937b6aaSMarkus Armbruster# auto-converge has started throttling guest cpus. (Since 2.7) 22448685a8eSMarkus Armbruster# 22548685a8eSMarkus Armbruster# @error-desc: the human readable error description string, when 22648685a8eSMarkus Armbruster# @status is 'failed'. Clients should not attempt to parse the 22748685a8eSMarkus Armbruster# error strings. (Since 2.7) 22848685a8eSMarkus Armbruster# 229a937b6aaSMarkus Armbruster# @postcopy-blocktime: total time when all vCPU were blocked during 230a937b6aaSMarkus Armbruster# postcopy live migration. This is only present when the 231a937b6aaSMarkus Armbruster# postcopy-blocktime migration capability is enabled. (Since 3.0) 23265ace060SAlexey Perevalov# 233a937b6aaSMarkus Armbruster# @postcopy-vcpu-blocktime: list of the postcopy blocktime per vCPU. 234a937b6aaSMarkus Armbruster# This is only present when the postcopy-blocktime migration 235a937b6aaSMarkus Armbruster# capability is enabled. (Since 3.0) 23665ace060SAlexey Perevalov# 237a937b6aaSMarkus Armbruster# @compression: migration compression statistics, only returned if 238a937b6aaSMarkus Armbruster# compression feature is on and status is 'active' or 'completed' 239a937b6aaSMarkus Armbruster# (Since 3.1) 24065ace060SAlexey Perevalov# 241a937b6aaSMarkus Armbruster# @socket-address: Only used for tcp, to know what the real port is 242a937b6aaSMarkus Armbruster# (Since 4.0) 2439aca82baSJuan Quintela# 244a937b6aaSMarkus Armbruster# @vfio: @VfioStats containing detailed VFIO devices migration 245a937b6aaSMarkus Armbruster# statistics, only returned if VFIO device is present, migration 246a937b6aaSMarkus Armbruster# is supported by all VFIO devices and status is 'active' or 247a937b6aaSMarkus Armbruster# 'completed' (since 5.2) 2483710586cSKirti Wankhede# 249a937b6aaSMarkus Armbruster# @blocked-reasons: A list of reasons an outgoing migration is 250a937b6aaSMarkus Armbruster# blocked. Present and non-empty when migration is blocked. 251e11ce6c0SMarkus Armbruster# (since 6.0) 252e11ce6c0SMarkus Armbruster# 25315699cf5SHyman Huang(黄勇)# @dirty-limit-throttle-time-per-round: Maximum throttle time (in microseconds) of virtual 25415699cf5SHyman Huang(黄勇)# CPUs each dirty ring full round, which shows how 25515699cf5SHyman Huang(黄勇)# MigrationCapability dirty-limit affects the guest 25615699cf5SHyman Huang(黄勇)# during live migration. (since 8.1) 25715699cf5SHyman Huang(黄勇)# 25815699cf5SHyman Huang(黄勇)# @dirty-limit-ring-full-time: Estimated average dirty ring full time (in microseconds) 25915699cf5SHyman Huang(黄勇)# each dirty ring full round, note that the value equals 26015699cf5SHyman Huang(黄勇)# dirty ring memory size divided by average dirty page rate 26115699cf5SHyman Huang(黄勇)# of virtual CPU, which can be used to observe the average 26215699cf5SHyman Huang(黄勇)# memory load of virtual CPU indirectly. Note that zero 26315699cf5SHyman Huang(黄勇)# means guest doesn't dirty memory (since 8.1) 26415699cf5SHyman Huang(黄勇)# 2659bc6e893SMarkus Armbruster# Since: 0.14 26648685a8eSMarkus Armbruster## 26748685a8eSMarkus Armbruster{ 'struct': 'MigrationInfo', 26848685a8eSMarkus Armbruster 'data': {'*status': 'MigrationStatus', '*ram': 'MigrationStats', 26948685a8eSMarkus Armbruster '*disk': 'MigrationStats', 2703710586cSKirti Wankhede '*vfio': 'VfioStats', 27148685a8eSMarkus Armbruster '*xbzrle-cache': 'XBZRLECacheStats', 27248685a8eSMarkus Armbruster '*total-time': 'int', 27348685a8eSMarkus Armbruster '*expected-downtime': 'int', 27448685a8eSMarkus Armbruster '*downtime': 'int', 27548685a8eSMarkus Armbruster '*setup-time': 'int', 27648685a8eSMarkus Armbruster '*cpu-throttle-percentage': 'int', 27765ace060SAlexey Perevalov '*error-desc': 'str', 2783af8554bSDr. David Alan Gilbert '*blocked-reasons': ['str'], 27965ace060SAlexey Perevalov '*postcopy-blocktime': 'uint32', 28076e03000SXiao Guangrong '*postcopy-vcpu-blocktime': ['uint32'], 2819aca82baSJuan Quintela '*compression': 'CompressionStats', 28215699cf5SHyman Huang(黄勇) '*socket-address': ['SocketAddress'], 28315699cf5SHyman Huang(黄勇) '*dirty-limit-throttle-time-per-round': 'uint64', 28415699cf5SHyman Huang(黄勇) '*dirty-limit-ring-full-time': 'uint64'} } 28548685a8eSMarkus Armbruster 28648685a8eSMarkus Armbruster## 28748685a8eSMarkus Armbruster# @query-migrate: 28848685a8eSMarkus Armbruster# 28948685a8eSMarkus Armbruster# Returns information about current migration process. If migration 29048685a8eSMarkus Armbruster# is active there will be another json-object with RAM migration 29148685a8eSMarkus Armbruster# status and if block migration is active another one with block 29248685a8eSMarkus Armbruster# migration status. 29348685a8eSMarkus Armbruster# 29448685a8eSMarkus Armbruster# Returns: @MigrationInfo 29548685a8eSMarkus Armbruster# 2969bc6e893SMarkus Armbruster# Since: 0.14 29748685a8eSMarkus Armbruster# 29837fa48a4SMarkus Armbruster# Examples: 29948685a8eSMarkus Armbruster# 30048685a8eSMarkus Armbruster# 1. Before the first migration 30148685a8eSMarkus Armbruster# 30248685a8eSMarkus Armbruster# -> { "execute": "query-migrate" } 30348685a8eSMarkus Armbruster# <- { "return": {} } 30448685a8eSMarkus Armbruster# 30548685a8eSMarkus Armbruster# 2. Migration is done and has succeeded 30648685a8eSMarkus Armbruster# 30748685a8eSMarkus Armbruster# -> { "execute": "query-migrate" } 30848685a8eSMarkus Armbruster# <- { "return": { 30948685a8eSMarkus Armbruster# "status": "completed", 310be1d2c49Sjialina01# "total-time":12345, 311be1d2c49Sjialina01# "setup-time":12345, 312be1d2c49Sjialina01# "downtime":12345, 31348685a8eSMarkus Armbruster# "ram":{ 31448685a8eSMarkus Armbruster# "transferred":123, 31548685a8eSMarkus Armbruster# "remaining":123, 31648685a8eSMarkus Armbruster# "total":246, 31748685a8eSMarkus Armbruster# "duplicate":123, 31848685a8eSMarkus Armbruster# "normal":123, 31948685a8eSMarkus Armbruster# "normal-bytes":123456, 32048685a8eSMarkus Armbruster# "dirty-sync-count":15 32148685a8eSMarkus Armbruster# } 32248685a8eSMarkus Armbruster# } 32348685a8eSMarkus Armbruster# } 32448685a8eSMarkus Armbruster# 32548685a8eSMarkus Armbruster# 3. Migration is done and has failed 32648685a8eSMarkus Armbruster# 32748685a8eSMarkus Armbruster# -> { "execute": "query-migrate" } 32848685a8eSMarkus Armbruster# <- { "return": { "status": "failed" } } 32948685a8eSMarkus Armbruster# 33048685a8eSMarkus Armbruster# 4. Migration is being performed and is not a block migration: 33148685a8eSMarkus Armbruster# 33248685a8eSMarkus Armbruster# -> { "execute": "query-migrate" } 33348685a8eSMarkus Armbruster# <- { 33448685a8eSMarkus Armbruster# "return":{ 33548685a8eSMarkus Armbruster# "status":"active", 336be1d2c49Sjialina01# "total-time":12345, 337be1d2c49Sjialina01# "setup-time":12345, 338be1d2c49Sjialina01# "expected-downtime":12345, 33948685a8eSMarkus Armbruster# "ram":{ 34048685a8eSMarkus Armbruster# "transferred":123, 34148685a8eSMarkus Armbruster# "remaining":123, 34248685a8eSMarkus Armbruster# "total":246, 34348685a8eSMarkus Armbruster# "duplicate":123, 34448685a8eSMarkus Armbruster# "normal":123, 34548685a8eSMarkus Armbruster# "normal-bytes":123456, 34648685a8eSMarkus Armbruster# "dirty-sync-count":15 34748685a8eSMarkus Armbruster# } 34848685a8eSMarkus Armbruster# } 34948685a8eSMarkus Armbruster# } 35048685a8eSMarkus Armbruster# 35148685a8eSMarkus Armbruster# 5. Migration is being performed and is a block migration: 35248685a8eSMarkus Armbruster# 35348685a8eSMarkus Armbruster# -> { "execute": "query-migrate" } 35448685a8eSMarkus Armbruster# <- { 35548685a8eSMarkus Armbruster# "return":{ 35648685a8eSMarkus Armbruster# "status":"active", 357be1d2c49Sjialina01# "total-time":12345, 358be1d2c49Sjialina01# "setup-time":12345, 359be1d2c49Sjialina01# "expected-downtime":12345, 36048685a8eSMarkus Armbruster# "ram":{ 36148685a8eSMarkus Armbruster# "total":1057024, 36248685a8eSMarkus Armbruster# "remaining":1053304, 36348685a8eSMarkus Armbruster# "transferred":3720, 36448685a8eSMarkus Armbruster# "duplicate":123, 36548685a8eSMarkus Armbruster# "normal":123, 36648685a8eSMarkus Armbruster# "normal-bytes":123456, 36748685a8eSMarkus Armbruster# "dirty-sync-count":15 36848685a8eSMarkus Armbruster# }, 36948685a8eSMarkus Armbruster# "disk":{ 37048685a8eSMarkus Armbruster# "total":20971520, 37148685a8eSMarkus Armbruster# "remaining":20880384, 37248685a8eSMarkus Armbruster# "transferred":91136 37348685a8eSMarkus Armbruster# } 37448685a8eSMarkus Armbruster# } 37548685a8eSMarkus Armbruster# } 37648685a8eSMarkus Armbruster# 37748685a8eSMarkus Armbruster# 6. Migration is being performed and XBZRLE is active: 37848685a8eSMarkus Armbruster# 37948685a8eSMarkus Armbruster# -> { "execute": "query-migrate" } 38048685a8eSMarkus Armbruster# <- { 38148685a8eSMarkus Armbruster# "return":{ 38248685a8eSMarkus Armbruster# "status":"active", 383be1d2c49Sjialina01# "total-time":12345, 384be1d2c49Sjialina01# "setup-time":12345, 385be1d2c49Sjialina01# "expected-downtime":12345, 38648685a8eSMarkus Armbruster# "ram":{ 38748685a8eSMarkus Armbruster# "total":1057024, 38848685a8eSMarkus Armbruster# "remaining":1053304, 38948685a8eSMarkus Armbruster# "transferred":3720, 39048685a8eSMarkus Armbruster# "duplicate":10, 39148685a8eSMarkus Armbruster# "normal":3333, 39248685a8eSMarkus Armbruster# "normal-bytes":3412992, 39348685a8eSMarkus Armbruster# "dirty-sync-count":15 39448685a8eSMarkus Armbruster# }, 39548685a8eSMarkus Armbruster# "xbzrle-cache":{ 39648685a8eSMarkus Armbruster# "cache-size":67108864, 39748685a8eSMarkus Armbruster# "bytes":20971520, 39848685a8eSMarkus Armbruster# "pages":2444343, 39948685a8eSMarkus Armbruster# "cache-miss":2244, 40048685a8eSMarkus Armbruster# "cache-miss-rate":0.123, 401e460a4b1SWei Wang# "encoding-rate":80.1, 40248685a8eSMarkus Armbruster# "overflow":34434 40348685a8eSMarkus Armbruster# } 40448685a8eSMarkus Armbruster# } 40548685a8eSMarkus Armbruster# } 40648685a8eSMarkus Armbruster## 40748685a8eSMarkus Armbruster{ 'command': 'query-migrate', 'returns': 'MigrationInfo' } 40848685a8eSMarkus Armbruster 40948685a8eSMarkus Armbruster## 41048685a8eSMarkus Armbruster# @MigrationCapability: 41148685a8eSMarkus Armbruster# 41248685a8eSMarkus Armbruster# Migration capabilities enumeration 41348685a8eSMarkus Armbruster# 414a937b6aaSMarkus Armbruster# @xbzrle: Migration supports xbzrle (Xor Based Zero Run Length 415a937b6aaSMarkus Armbruster# Encoding). This feature allows us to minimize migration traffic 416a937b6aaSMarkus Armbruster# for certain work loads, by sending compressed difference of the 417a937b6aaSMarkus Armbruster# pages 41848685a8eSMarkus Armbruster# 419a937b6aaSMarkus Armbruster# @rdma-pin-all: Controls whether or not the entire VM memory 420a937b6aaSMarkus Armbruster# footprint is mlock()'d on demand or all at once. Refer to 421a937b6aaSMarkus Armbruster# docs/rdma.txt for usage. Disabled by default. (since 2.0) 42248685a8eSMarkus Armbruster# 423a937b6aaSMarkus Armbruster# @zero-blocks: During storage migration encode blocks of zeroes 424a937b6aaSMarkus Armbruster# efficiently. This essentially saves 1MB of zeroes per block on 425a937b6aaSMarkus Armbruster# the wire. Enabling requires source and target VM to support 426a937b6aaSMarkus Armbruster# this feature. To enable it is sufficient to enable the 427a937b6aaSMarkus Armbruster# capability on the source VM. The feature is disabled by default. 428a937b6aaSMarkus Armbruster# (since 1.6) 42948685a8eSMarkus Armbruster# 430a937b6aaSMarkus Armbruster# @compress: Use multiple compression threads to accelerate live 431a937b6aaSMarkus Armbruster# migration. This feature can help to reduce the migration 432a937b6aaSMarkus Armbruster# traffic, by sending compressed pages. Please note that if 433a937b6aaSMarkus Armbruster# compress and xbzrle are both on, compress only takes effect in 434a937b6aaSMarkus Armbruster# the ram bulk stage, after that, it will be disabled and only 435a937b6aaSMarkus Armbruster# xbzrle takes effect, this can help to minimize migration 436a937b6aaSMarkus Armbruster# traffic. The feature is disabled by default. (since 2.4 ) 43748685a8eSMarkus Armbruster# 438a937b6aaSMarkus Armbruster# @events: generate events for each migration state change (since 2.4 439a937b6aaSMarkus Armbruster# ) 44048685a8eSMarkus Armbruster# 441a937b6aaSMarkus Armbruster# @auto-converge: If enabled, QEMU will automatically throttle down 442a937b6aaSMarkus Armbruster# the guest to speed up convergence of RAM migration. (since 1.6) 44348685a8eSMarkus Armbruster# 444a937b6aaSMarkus Armbruster# @postcopy-ram: Start executing on the migration target before all of 445a937b6aaSMarkus Armbruster# RAM has been migrated, pulling the remaining pages along as 446a937b6aaSMarkus Armbruster# needed. The capacity must have the same setting on both source 447a937b6aaSMarkus Armbruster# and target or migration will not even start. NOTE: If the 448a937b6aaSMarkus Armbruster# migration fails during postcopy the VM will fail. (since 2.6) 44948685a8eSMarkus Armbruster# 450a937b6aaSMarkus Armbruster# @x-colo: If enabled, migration will never end, and the state of the 451a937b6aaSMarkus Armbruster# VM on the primary side will be migrated continuously to the VM 452a937b6aaSMarkus Armbruster# on secondary side, this process is called COarse-Grain LOck 453a937b6aaSMarkus Armbruster# Stepping (COLO) for Non-stop Service. (since 2.8) 45448685a8eSMarkus Armbruster# 455a937b6aaSMarkus Armbruster# @release-ram: if enabled, qemu will free the migrated ram pages on 456a937b6aaSMarkus Armbruster# the source during postcopy-ram migration. (since 2.9) 45748685a8eSMarkus Armbruster# 45848685a8eSMarkus Armbruster# @block: If enabled, QEMU will also migrate the contents of all block 45948685a8eSMarkus Armbruster# devices. Default is disabled. A possible alternative uses 46048685a8eSMarkus Armbruster# mirror jobs to a builtin NBD server on the destination, which 461a937b6aaSMarkus Armbruster# offers more flexibility. (Since 2.10) 46248685a8eSMarkus Armbruster# 46348685a8eSMarkus Armbruster# @return-path: If enabled, migration will use the return path even 46448685a8eSMarkus Armbruster# for precopy. (since 2.10) 46548685a8eSMarkus Armbruster# 466a937b6aaSMarkus Armbruster# @pause-before-switchover: Pause outgoing migration before 467a937b6aaSMarkus Armbruster# serialising device state and before disabling block IO (since 468a937b6aaSMarkus Armbruster# 2.11) 46993fbd031SDr. David Alan Gilbert# 470cbfd6c95SJuan Quintela# @multifd: Use more than one fd for migration (since 4.0) 47130126bbfSJuan Quintela# 47255efc8c2SVladimir Sementsov-Ogievskiy# @dirty-bitmaps: If enabled, QEMU will migrate named dirty bitmaps. 47355efc8c2SVladimir Sementsov-Ogievskiy# (since 2.12) 47455efc8c2SVladimir Sementsov-Ogievskiy# 475f22f928eSAlexey Perevalov# @postcopy-blocktime: Calculate downtime for postcopy live migration 47651f63ec7SPeter Maydell# (since 3.0) 477f22f928eSAlexey Perevalov# 478a937b6aaSMarkus Armbruster# @late-block-activate: If enabled, the destination will not activate 479a937b6aaSMarkus Armbruster# block devices (and thus take locks) immediately at the end of 480a937b6aaSMarkus Armbruster# migration. (since 3.0) 4810f073f44SDr. David Alan Gilbert# 482b0182e53SSteve Sistare# @x-ignore-shared: If enabled, QEMU will not migrate shared memory that is 483b0182e53SSteve Sistare# accessible on the destination machine. (since 4.0) 48418269069SYury Kotov# 485b9d68df6SYury Kotov# @validate-uuid: Send the UUID of the source to allow the destination 486b9d68df6SYury Kotov# to ensure it is the same. (since 4.2) 487b9d68df6SYury Kotov# 488a937b6aaSMarkus Armbruster# @background-snapshot: If enabled, the migration stream will be a 489a937b6aaSMarkus Armbruster# snapshot of the VM exactly at the point when the migration 490a937b6aaSMarkus Armbruster# procedure starts. The VM RAM is saved with running VM. (since 491a937b6aaSMarkus Armbruster# 6.0) 4926e8c25b4SAndrey Gruzdev# 493a937b6aaSMarkus Armbruster# @zero-copy-send: Controls behavior on sending memory pages on 494a937b6aaSMarkus Armbruster# migration. When true, enables a zero-copy mechanism for sending 495a937b6aaSMarkus Armbruster# memory pages, if host supports it. Requires that QEMU be 496a937b6aaSMarkus Armbruster# permitted to use locked memory for guest RAM pages. (since 7.1) 497a937b6aaSMarkus Armbruster# 498a937b6aaSMarkus Armbruster# @postcopy-preempt: If enabled, the migration process will allow 499a937b6aaSMarkus Armbruster# postcopy requests to preempt precopy stream, so postcopy 500a937b6aaSMarkus Armbruster# requests will be handled faster. This is a performance feature 501a937b6aaSMarkus Armbruster# and should not affect the correctness of postcopy migration. 502ce5b0f4aSPeter Xu# (since 7.1) 5031abaec9aSLeonardo Bras# 5046574232fSAvihai Horon# @switchover-ack: If enabled, migration will not stop the source VM 5056574232fSAvihai Horon# and complete the migration until an ACK is received from the 5066574232fSAvihai Horon# destination that it's OK to do so. Exactly when this ACK is 5076574232fSAvihai Horon# sent depends on the migrated devices that use this feature. 5086574232fSAvihai Horon# For example, a device can use it to make sure some of its data 5096574232fSAvihai Horon# is sent and loaded in the destination before doing switchover. 5106574232fSAvihai Horon# This can reduce downtime if devices that support this capability 5116574232fSAvihai Horon# are present. 'return-path' capability must be enabled to use 5126574232fSAvihai Horon# it. (since 8.1) 5136574232fSAvihai Horon# 514dc623955SHyman Huang(黄勇)# @dirty-limit: If enabled, migration will use the dirty-limit algo to 515dc623955SHyman Huang(黄勇)# throttle down guest instead of auto-converge algo. 516dc623955SHyman Huang(黄勇)# Throttle algo only works when vCPU's dirtyrate greater 517dc623955SHyman Huang(黄勇)# than 'vcpu-dirty-limit', read processes in guest os 518dc623955SHyman Huang(黄勇)# aren't penalized any more, so this algo can improve 519dc623955SHyman Huang(黄勇)# performance of vCPU during live migration. This is an 520dc623955SHyman Huang(黄勇)# optional performance feature and should not affect the 521dc623955SHyman Huang(黄勇)# correctness of the existing auto-converge algo. 522dc623955SHyman Huang(黄勇)# (since 8.1) 523dc623955SHyman Huang(黄勇)# 5249fb49daaSMarkus Armbruster# Features: 525a937b6aaSMarkus Armbruster# 5269fb49daaSMarkus Armbruster# @unstable: Members @x-colo and @x-ignore-shared are experimental. 5279fb49daaSMarkus Armbruster# 52848685a8eSMarkus Armbruster# Since: 1.2 52948685a8eSMarkus Armbruster## 53048685a8eSMarkus Armbruster{ 'enum': 'MigrationCapability', 53148685a8eSMarkus Armbruster 'data': ['xbzrle', 'rdma-pin-all', 'auto-converge', 'zero-blocks', 5329fb49daaSMarkus Armbruster 'compress', 'events', 'postcopy-ram', 5339fb49daaSMarkus Armbruster { 'name': 'x-colo', 'features': [ 'unstable' ] }, 5349fb49daaSMarkus Armbruster 'release-ram', 535cbfd6c95SJuan Quintela 'block', 'return-path', 'pause-before-switchover', 'multifd', 53618269069SYury Kotov 'dirty-bitmaps', 'postcopy-blocktime', 'late-block-activate', 5379fb49daaSMarkus Armbruster { 'name': 'x-ignore-shared', 'features': [ 'unstable' ] }, 5381abaec9aSLeonardo Bras 'validate-uuid', 'background-snapshot', 539dc623955SHyman Huang(黄勇) 'zero-copy-send', 'postcopy-preempt', 'switchover-ack', 540dc623955SHyman Huang(黄勇) 'dirty-limit'] } 54148685a8eSMarkus Armbruster 54248685a8eSMarkus Armbruster## 54348685a8eSMarkus Armbruster# @MigrationCapabilityStatus: 54448685a8eSMarkus Armbruster# 54548685a8eSMarkus Armbruster# Migration capability information 54648685a8eSMarkus Armbruster# 54748685a8eSMarkus Armbruster# @capability: capability enum 54848685a8eSMarkus Armbruster# 54948685a8eSMarkus Armbruster# @state: capability state bool 55048685a8eSMarkus Armbruster# 55148685a8eSMarkus Armbruster# Since: 1.2 55248685a8eSMarkus Armbruster## 55348685a8eSMarkus Armbruster{ 'struct': 'MigrationCapabilityStatus', 55448685a8eSMarkus Armbruster 'data': { 'capability': 'MigrationCapability', 'state': 'bool' } } 55548685a8eSMarkus Armbruster 55648685a8eSMarkus Armbruster## 55748685a8eSMarkus Armbruster# @migrate-set-capabilities: 55848685a8eSMarkus Armbruster# 55948685a8eSMarkus Armbruster# Enable/Disable the following migration capabilities (like xbzrle) 56048685a8eSMarkus Armbruster# 56148685a8eSMarkus Armbruster# @capabilities: json array of capability modifications to make 56248685a8eSMarkus Armbruster# 56348685a8eSMarkus Armbruster# Since: 1.2 56448685a8eSMarkus Armbruster# 56548685a8eSMarkus Armbruster# Example: 56648685a8eSMarkus Armbruster# 56748685a8eSMarkus Armbruster# -> { "execute": "migrate-set-capabilities" , "arguments": 56848685a8eSMarkus Armbruster# { "capabilities": [ { "capability": "xbzrle", "state": true } ] } } 56937fa48a4SMarkus Armbruster# <- { "return": {} } 57048685a8eSMarkus Armbruster## 57148685a8eSMarkus Armbruster{ 'command': 'migrate-set-capabilities', 57248685a8eSMarkus Armbruster 'data': { 'capabilities': ['MigrationCapabilityStatus'] } } 57348685a8eSMarkus Armbruster 57448685a8eSMarkus Armbruster## 57548685a8eSMarkus Armbruster# @query-migrate-capabilities: 57648685a8eSMarkus Armbruster# 57748685a8eSMarkus Armbruster# Returns information about the current migration capabilities status 57848685a8eSMarkus Armbruster# 579d93ed1bdSMarkus Armbruster# Returns: @MigrationCapabilityStatus 58048685a8eSMarkus Armbruster# 58148685a8eSMarkus Armbruster# Since: 1.2 58248685a8eSMarkus Armbruster# 58348685a8eSMarkus Armbruster# Example: 58448685a8eSMarkus Armbruster# 58548685a8eSMarkus Armbruster# -> { "execute": "query-migrate-capabilities" } 58648685a8eSMarkus Armbruster# <- { "return": [ 58748685a8eSMarkus Armbruster# {"state": false, "capability": "xbzrle"}, 58848685a8eSMarkus Armbruster# {"state": false, "capability": "rdma-pin-all"}, 58948685a8eSMarkus Armbruster# {"state": false, "capability": "auto-converge"}, 59048685a8eSMarkus Armbruster# {"state": false, "capability": "zero-blocks"}, 59148685a8eSMarkus Armbruster# {"state": false, "capability": "compress"}, 59248685a8eSMarkus Armbruster# {"state": true, "capability": "events"}, 59348685a8eSMarkus Armbruster# {"state": false, "capability": "postcopy-ram"}, 59448685a8eSMarkus Armbruster# {"state": false, "capability": "x-colo"} 59548685a8eSMarkus Armbruster# ]} 59648685a8eSMarkus Armbruster## 59748685a8eSMarkus Armbruster{ 'command': 'query-migrate-capabilities', 'returns': ['MigrationCapabilityStatus']} 59848685a8eSMarkus Armbruster 59948685a8eSMarkus Armbruster## 60096eef042SJuan Quintela# @MultiFDCompression: 60196eef042SJuan Quintela# 60296eef042SJuan Quintela# An enumeration of multifd compression methods. 60396eef042SJuan Quintela# 60496eef042SJuan Quintela# @none: no compression. 605a937b6aaSMarkus Armbruster# 6067ec2c2b3SJuan Quintela# @zlib: use zlib compression method. 607a937b6aaSMarkus Armbruster# 60887dc6f5fSJuan Quintela# @zstd: use zstd compression method. 60996eef042SJuan Quintela# 61096eef042SJuan Quintela# Since: 5.0 61196eef042SJuan Quintela## 61296eef042SJuan Quintela{ 'enum': 'MultiFDCompression', 61387dc6f5fSJuan Quintela 'data': [ 'none', 'zlib', 6148a9f1e1dSMarc-André Lureau { 'name': 'zstd', 'if': 'CONFIG_ZSTD' } ] } 61596eef042SJuan Quintela 61696eef042SJuan Quintela## 6176e9f21a2SPeter Krempa# @BitmapMigrationBitmapAliasTransform: 6186e9f21a2SPeter Krempa# 619a937b6aaSMarkus Armbruster# @persistent: If present, the bitmap will be made persistent or 620a937b6aaSMarkus Armbruster# transient depending on this parameter. 6216e9f21a2SPeter Krempa# 6226e9f21a2SPeter Krempa# Since: 6.0 6236e9f21a2SPeter Krempa## 6246e9f21a2SPeter Krempa{ 'struct': 'BitmapMigrationBitmapAliasTransform', 6256e9f21a2SPeter Krempa 'data': { 6266e9f21a2SPeter Krempa '*persistent': 'bool' 6276e9f21a2SPeter Krempa } } 6286e9f21a2SPeter Krempa 6296e9f21a2SPeter Krempa## 63031e4c354SMax Reitz# @BitmapMigrationBitmapAlias: 63131e4c354SMax Reitz# 63231e4c354SMax Reitz# @name: The name of the bitmap. 63331e4c354SMax Reitz# 63431e4c354SMax Reitz# @alias: An alias name for migration (for example the bitmap name on 63531e4c354SMax Reitz# the opposite site). 63631e4c354SMax Reitz# 637a937b6aaSMarkus Armbruster# @transform: Allows the modification of the migrated bitmap. (since 638a937b6aaSMarkus Armbruster# 6.0) 6396e9f21a2SPeter Krempa# 64031e4c354SMax Reitz# Since: 5.2 64131e4c354SMax Reitz## 64231e4c354SMax Reitz{ 'struct': 'BitmapMigrationBitmapAlias', 64331e4c354SMax Reitz 'data': { 64431e4c354SMax Reitz 'name': 'str', 6456e9f21a2SPeter Krempa 'alias': 'str', 6466e9f21a2SPeter Krempa '*transform': 'BitmapMigrationBitmapAliasTransform' 64731e4c354SMax Reitz } } 64831e4c354SMax Reitz 64931e4c354SMax Reitz## 65031e4c354SMax Reitz# @BitmapMigrationNodeAlias: 65131e4c354SMax Reitz# 65231e4c354SMax Reitz# Maps a block node name and the bitmaps it has to aliases for dirty 65331e4c354SMax Reitz# bitmap migration. 65431e4c354SMax Reitz# 65531e4c354SMax Reitz# @node-name: A block node name. 65631e4c354SMax Reitz# 657a937b6aaSMarkus Armbruster# @alias: An alias block node name for migration (for example the node 658a937b6aaSMarkus Armbruster# name on the opposite site). 65931e4c354SMax Reitz# 66031e4c354SMax Reitz# @bitmaps: Mappings for the bitmaps on this node. 66131e4c354SMax Reitz# 66231e4c354SMax Reitz# Since: 5.2 66331e4c354SMax Reitz## 66431e4c354SMax Reitz{ 'struct': 'BitmapMigrationNodeAlias', 66531e4c354SMax Reitz 'data': { 66631e4c354SMax Reitz 'node-name': 'str', 66731e4c354SMax Reitz 'alias': 'str', 66831e4c354SMax Reitz 'bitmaps': [ 'BitmapMigrationBitmapAlias' ] 66931e4c354SMax Reitz } } 67031e4c354SMax Reitz 67131e4c354SMax Reitz## 67248685a8eSMarkus Armbruster# @MigrationParameter: 67348685a8eSMarkus Armbruster# 67448685a8eSMarkus Armbruster# Migration parameters enumeration 67548685a8eSMarkus Armbruster# 676a937b6aaSMarkus Armbruster# @announce-initial: Initial delay (in milliseconds) before sending 677a937b6aaSMarkus Armbruster# the first announce (Since 4.0) 678ee3d96baSDr. David Alan Gilbert# 679a937b6aaSMarkus Armbruster# @announce-max: Maximum delay (in milliseconds) between packets in 680a937b6aaSMarkus Armbruster# the announcement (Since 4.0) 681ee3d96baSDr. David Alan Gilbert# 682a937b6aaSMarkus Armbruster# @announce-rounds: Number of self-announce packets sent after 683a937b6aaSMarkus Armbruster# migration (Since 4.0) 684ee3d96baSDr. David Alan Gilbert# 685a937b6aaSMarkus Armbruster# @announce-step: Increase in delay (in milliseconds) between 686a937b6aaSMarkus Armbruster# subsequent packets in the announcement (Since 4.0) 687ee3d96baSDr. David Alan Gilbert# 688a937b6aaSMarkus Armbruster# @compress-level: Set the compression level to be used in live 689a937b6aaSMarkus Armbruster# migration, the compression level is an integer between 0 and 9, 690a937b6aaSMarkus Armbruster# where 0 means no compression, 1 means the best compression 691a937b6aaSMarkus Armbruster# speed, and 9 means best compression ratio which will consume 692a937b6aaSMarkus Armbruster# more CPU. 69348685a8eSMarkus Armbruster# 694a937b6aaSMarkus Armbruster# @compress-threads: Set compression thread count to be used in live 695a937b6aaSMarkus Armbruster# migration, the compression thread count is an integer between 1 696a937b6aaSMarkus Armbruster# and 255. 69748685a8eSMarkus Armbruster# 698a937b6aaSMarkus Armbruster# @compress-wait-thread: Controls behavior when all compression 699a937b6aaSMarkus Armbruster# threads are currently busy. If true (default), wait for a free 700a937b6aaSMarkus Armbruster# compression thread to become available; otherwise, send the page 701a937b6aaSMarkus Armbruster# uncompressed. (Since 3.1) 7021d58872aSXiao Guangrong# 703a937b6aaSMarkus Armbruster# @decompress-threads: Set decompression thread count to be used in 704a937b6aaSMarkus Armbruster# live migration, the decompression thread count is an integer 705a937b6aaSMarkus Armbruster# between 1 and 255. Usually, decompression is at least 4 times as 706a937b6aaSMarkus Armbruster# fast as compression, so set the decompress-threads to the number 707a937b6aaSMarkus Armbruster# about 1/4 of compress-threads is adequate. 70848685a8eSMarkus Armbruster# 709a937b6aaSMarkus Armbruster# @throttle-trigger-threshold: The ratio of bytes_dirty_period and 710a937b6aaSMarkus Armbruster# bytes_xfer_period to trigger throttling. It is expressed as 711a937b6aaSMarkus Armbruster# percentage. The default value is 50. (Since 5.0) 712dc14a470SKeqian Zhu# 713a937b6aaSMarkus Armbruster# @cpu-throttle-initial: Initial percentage of time guest cpus are 714a937b6aaSMarkus Armbruster# throttled when migration auto-converge is activated. The 71548685a8eSMarkus Armbruster# default value is 20. (Since 2.7) 71648685a8eSMarkus Armbruster# 71748685a8eSMarkus Armbruster# @cpu-throttle-increment: throttle percentage increase each time 718a937b6aaSMarkus Armbruster# auto-converge detects that migration is not making progress. 719a937b6aaSMarkus Armbruster# The default value is 10. (Since 2.7) 72048685a8eSMarkus Armbruster# 721a937b6aaSMarkus Armbruster# @cpu-throttle-tailslow: Make CPU throttling slower at tail stage At 722a937b6aaSMarkus Armbruster# the tail stage of throttling, the Guest is very sensitive to CPU 723a937b6aaSMarkus Armbruster# percentage while the @cpu-throttle -increment is excessive 724a937b6aaSMarkus Armbruster# usually at tail stage. If this parameter is true, we will 725a937b6aaSMarkus Armbruster# compute the ideal CPU percentage used by the Guest, which may 726a937b6aaSMarkus Armbruster# exactly make the dirty rate match the dirty rate threshold. 727a937b6aaSMarkus Armbruster# Then we will choose a smaller throttle increment between the one 728a937b6aaSMarkus Armbruster# specified by @cpu-throttle-increment and the one generated by 729a937b6aaSMarkus Armbruster# ideal CPU percentage. Therefore, it is compatible to 730a937b6aaSMarkus Armbruster# traditional throttling, meanwhile the throttle increment won't 731a937b6aaSMarkus Armbruster# be excessive at tail stage. The default value is false. (Since 732a937b6aaSMarkus Armbruster# 5.1) 733cbbf8182SKeqian Zhu# 734a937b6aaSMarkus Armbruster# @tls-creds: ID of the 'tls-creds' object that provides credentials 735a937b6aaSMarkus Armbruster# for establishing a TLS connection over the migration data 736a937b6aaSMarkus Armbruster# channel. On the outgoing side of the migration, the credentials 737a937b6aaSMarkus Armbruster# must be for a 'client' endpoint, while for the incoming side the 738a937b6aaSMarkus Armbruster# credentials must be for a 'server' endpoint. Setting this will 739a937b6aaSMarkus Armbruster# enable TLS for all migrations. The default is unset, resulting 740a937b6aaSMarkus Armbruster# in unsecured migration at the QEMU level. (Since 2.7) 74148685a8eSMarkus Armbruster# 742a937b6aaSMarkus Armbruster# @tls-hostname: hostname of the target host for the migration. This 743a937b6aaSMarkus Armbruster# is required when using x509 based TLS credentials and the 744a937b6aaSMarkus Armbruster# migration URI does not already include a hostname. For example 745a937b6aaSMarkus Armbruster# if using fd: or exec: based migration, the hostname must be 746a937b6aaSMarkus Armbruster# provided so that the server's x509 certificate identity can be 747a937b6aaSMarkus Armbruster# validated. (Since 2.7) 74848685a8eSMarkus Armbruster# 749a937b6aaSMarkus Armbruster# @tls-authz: ID of the 'authz' object subclass that provides access 750a937b6aaSMarkus Armbruster# control checking of the TLS x509 certificate distinguished name. 751d2f1d29bSDaniel P. Berrange# This object is only resolved at time of use, so can be deleted 752d2f1d29bSDaniel P. Berrange# and recreated on the fly while the migration server is active. 753d2f1d29bSDaniel P. Berrange# If missing, it will default to denying access (Since 4.0) 754d2f1d29bSDaniel P. Berrange# 755a937b6aaSMarkus Armbruster# @max-bandwidth: to set maximum speed for migration. maximum speed 756a937b6aaSMarkus Armbruster# in bytes per second. (Since 2.8) 75748685a8eSMarkus Armbruster# 758a937b6aaSMarkus Armbruster# @downtime-limit: set maximum tolerated downtime for migration. 759a937b6aaSMarkus Armbruster# maximum downtime in milliseconds (Since 2.8) 76048685a8eSMarkus Armbruster# 761a937b6aaSMarkus Armbruster# @x-checkpoint-delay: The delay time (in ms) between two COLO 762a937b6aaSMarkus Armbruster# checkpoints in periodic mode. (Since 2.8) 76348685a8eSMarkus Armbruster# 76448685a8eSMarkus Armbruster# @block-incremental: Affects how much storage is migrated when the 76548685a8eSMarkus Armbruster# block migration capability is enabled. When false, the entire 766a937b6aaSMarkus Armbruster# storage backing chain is migrated into a flattened image at the 767a937b6aaSMarkus Armbruster# destination; when true, only the active qcow2 layer is migrated 768a937b6aaSMarkus Armbruster# and the destination must already have access to the same backing 769a937b6aaSMarkus Armbruster# chain as was used on the source. (since 2.10) 77048685a8eSMarkus Armbruster# 771cbfd6c95SJuan Quintela# @multifd-channels: Number of channels used to migrate data in 772a937b6aaSMarkus Armbruster# parallel. This is the same number that the number of sockets 773a937b6aaSMarkus Armbruster# used for migration. The default value is 2 (since 4.0) 7744075fb1cSJuan Quintela# 77573af8dd8SJuan Quintela# @xbzrle-cache-size: cache size to be used by XBZRLE migration. It 776a937b6aaSMarkus Armbruster# needs to be a multiple of the target page size and a power of 2 77773af8dd8SJuan Quintela# (Since 2.11) 77873af8dd8SJuan Quintela# 779a937b6aaSMarkus Armbruster# @max-postcopy-bandwidth: Background transfer bandwidth during 780a937b6aaSMarkus Armbruster# postcopy. Defaults to 0 (unlimited). In bytes per second. 7817e555c6cSDr. David Alan Gilbert# (Since 3.0) 7824cbc9c7fSLi Qiang# 783a937b6aaSMarkus Armbruster# @max-cpu-throttle: maximum cpu throttle percentage. Defaults to 99. 784a937b6aaSMarkus Armbruster# (Since 3.1) 785ee3d96baSDr. David Alan Gilbert# 786a937b6aaSMarkus Armbruster# @multifd-compression: Which compression method to use. Defaults to 787a937b6aaSMarkus Armbruster# none. (Since 5.0) 78896eef042SJuan Quintela# 7899004db48SJuan Quintela# @multifd-zlib-level: Set the compression level to be used in live 790a937b6aaSMarkus Armbruster# migration, the compression level is an integer between 0 and 9, 791a937b6aaSMarkus Armbruster# where 0 means no compression, 1 means the best compression 792a937b6aaSMarkus Armbruster# speed, and 9 means best compression ratio which will consume 793a937b6aaSMarkus Armbruster# more CPU. Defaults to 1. (Since 5.0) 7949004db48SJuan Quintela# 7956a9ad154SJuan Quintela# @multifd-zstd-level: Set the compression level to be used in live 796a937b6aaSMarkus Armbruster# migration, the compression level is an integer between 0 and 20, 797a937b6aaSMarkus Armbruster# where 0 means no compression, 1 means the best compression 798a937b6aaSMarkus Armbruster# speed, and 20 means best compression ratio which will consume 799a937b6aaSMarkus Armbruster# more CPU. Defaults to 1. (Since 5.0) 800abb6295bSLeonardo Bras# 80131e4c354SMax Reitz# @block-bitmap-mapping: Maps block nodes and bitmaps on them to 802a937b6aaSMarkus Armbruster# aliases for the purpose of dirty bitmap migration. Such aliases 803a937b6aaSMarkus Armbruster# may for example be the corresponding names on the opposite site. 804a937b6aaSMarkus Armbruster# The mapping must be one-to-one, but not necessarily complete: On 805a937b6aaSMarkus Armbruster# the source, unmapped bitmaps and all bitmaps on unmapped nodes 806a937b6aaSMarkus Armbruster# will be ignored. On the destination, encountering an unmapped 807a937b6aaSMarkus Armbruster# alias in the incoming migration stream will result in a report, 808a937b6aaSMarkus Armbruster# and all further bitmap migration data will then be discarded. 809a937b6aaSMarkus Armbruster# Note that the destination does not know about bitmaps it does 810a937b6aaSMarkus Armbruster# not receive, so there is no limitation or requirement regarding 811a937b6aaSMarkus Armbruster# the number of bitmaps received, or how they are named, or on 812a937b6aaSMarkus Armbruster# which nodes they are placed. By default (when this parameter 813a937b6aaSMarkus Armbruster# has never been set), bitmap names are mapped to themselves. 814a937b6aaSMarkus Armbruster# Nodes are mapped to their block device name if there is one, and 815a937b6aaSMarkus Armbruster# to their node name otherwise. (Since 5.2) 81631e4c354SMax Reitz# 8174d807857SHyman Huang(黄勇)# @x-vcpu-dirty-limit-period: Periodic time (in milliseconds) of dirty limit during 8184d807857SHyman Huang(黄勇)# live migration. Should be in the range 1 to 1000ms, 8194d807857SHyman Huang(黄勇)# defaults to 1000ms. (Since 8.1) 8204d807857SHyman Huang(黄勇)# 82109f9ec99SHyman Huang(黄勇)# @vcpu-dirty-limit: Dirtyrate limit (MB/s) during live migration. 82209f9ec99SHyman Huang(黄勇)# Defaults to 1. (Since 8.1) 82309f9ec99SHyman Huang(黄勇)# 8249fb49daaSMarkus Armbruster# Features: 825a937b6aaSMarkus Armbruster# 8264d807857SHyman Huang(黄勇)# @unstable: Members @x-checkpoint-delay and @x-vcpu-dirty-limit-period 8274d807857SHyman Huang(黄勇)# are experimental. 8289fb49daaSMarkus Armbruster# 82948685a8eSMarkus Armbruster# Since: 2.4 83048685a8eSMarkus Armbruster## 83148685a8eSMarkus Armbruster{ 'enum': 'MigrationParameter', 832ee3d96baSDr. David Alan Gilbert 'data': ['announce-initial', 'announce-max', 833ee3d96baSDr. David Alan Gilbert 'announce-rounds', 'announce-step', 834ee3d96baSDr. David Alan Gilbert 'compress-level', 'compress-threads', 'decompress-threads', 835dc14a470SKeqian Zhu 'compress-wait-thread', 'throttle-trigger-threshold', 83648685a8eSMarkus Armbruster 'cpu-throttle-initial', 'cpu-throttle-increment', 837cbbf8182SKeqian Zhu 'cpu-throttle-tailslow', 838d2f1d29bSDaniel P. Berrange 'tls-creds', 'tls-hostname', 'tls-authz', 'max-bandwidth', 8399fb49daaSMarkus Armbruster 'downtime-limit', 8409fb49daaSMarkus Armbruster { 'name': 'x-checkpoint-delay', 'features': [ 'unstable' ] }, 8419fb49daaSMarkus Armbruster 'block-incremental', 842cbfd6c95SJuan Quintela 'multifd-channels', 8434cbc9c7fSLi Qiang 'xbzrle-cache-size', 'max-postcopy-bandwidth', 8449004db48SJuan Quintela 'max-cpu-throttle', 'multifd-compression', 84531e4c354SMax Reitz 'multifd-zlib-level', 'multifd-zstd-level', 8464d807857SHyman Huang(黄勇) 'block-bitmap-mapping', 84709f9ec99SHyman Huang(黄勇) { 'name': 'x-vcpu-dirty-limit-period', 'features': ['unstable'] }, 84809f9ec99SHyman Huang(黄勇) 'vcpu-dirty-limit'] } 84948685a8eSMarkus Armbruster 85048685a8eSMarkus Armbruster## 85148685a8eSMarkus Armbruster# @MigrateSetParameters: 85248685a8eSMarkus Armbruster# 853a937b6aaSMarkus Armbruster# @announce-initial: Initial delay (in milliseconds) before sending 854a937b6aaSMarkus Armbruster# the first announce (Since 4.0) 855ee3d96baSDr. David Alan Gilbert# 856a937b6aaSMarkus Armbruster# @announce-max: Maximum delay (in milliseconds) between packets in 857a937b6aaSMarkus Armbruster# the announcement (Since 4.0) 858ee3d96baSDr. David Alan Gilbert# 859a937b6aaSMarkus Armbruster# @announce-rounds: Number of self-announce packets sent after 860a937b6aaSMarkus Armbruster# migration (Since 4.0) 861ee3d96baSDr. David Alan Gilbert# 862a937b6aaSMarkus Armbruster# @announce-step: Increase in delay (in milliseconds) between 863a937b6aaSMarkus Armbruster# subsequent packets in the announcement (Since 4.0) 864ee3d96baSDr. David Alan Gilbert# 86548685a8eSMarkus Armbruster# @compress-level: compression level 86648685a8eSMarkus Armbruster# 86748685a8eSMarkus Armbruster# @compress-threads: compression thread count 86848685a8eSMarkus Armbruster# 869a937b6aaSMarkus Armbruster# @compress-wait-thread: Controls behavior when all compression 870a937b6aaSMarkus Armbruster# threads are currently busy. If true (default), wait for a free 871a937b6aaSMarkus Armbruster# compression thread to become available; otherwise, send the page 872a937b6aaSMarkus Armbruster# uncompressed. (Since 3.1) 8731d58872aSXiao Guangrong# 87448685a8eSMarkus Armbruster# @decompress-threads: decompression thread count 87548685a8eSMarkus Armbruster# 876a937b6aaSMarkus Armbruster# @throttle-trigger-threshold: The ratio of bytes_dirty_period and 877a937b6aaSMarkus Armbruster# bytes_xfer_period to trigger throttling. It is expressed as 878a937b6aaSMarkus Armbruster# percentage. The default value is 50. (Since 5.0) 879dc14a470SKeqian Zhu# 88048685a8eSMarkus Armbruster# @cpu-throttle-initial: Initial percentage of time guest cpus are 881a937b6aaSMarkus Armbruster# throttled when migration auto-converge is activated. The 882a937b6aaSMarkus Armbruster# default value is 20. (Since 2.7) 88348685a8eSMarkus Armbruster# 88448685a8eSMarkus Armbruster# @cpu-throttle-increment: throttle percentage increase each time 885a937b6aaSMarkus Armbruster# auto-converge detects that migration is not making progress. 886a937b6aaSMarkus Armbruster# The default value is 10. (Since 2.7) 88748685a8eSMarkus Armbruster# 888a937b6aaSMarkus Armbruster# @cpu-throttle-tailslow: Make CPU throttling slower at tail stage At 889a937b6aaSMarkus Armbruster# the tail stage of throttling, the Guest is very sensitive to CPU 890a937b6aaSMarkus Armbruster# percentage while the @cpu-throttle -increment is excessive 891a937b6aaSMarkus Armbruster# usually at tail stage. If this parameter is true, we will 892a937b6aaSMarkus Armbruster# compute the ideal CPU percentage used by the Guest, which may 893a937b6aaSMarkus Armbruster# exactly make the dirty rate match the dirty rate threshold. 894a937b6aaSMarkus Armbruster# Then we will choose a smaller throttle increment between the one 895a937b6aaSMarkus Armbruster# specified by @cpu-throttle-increment and the one generated by 896a937b6aaSMarkus Armbruster# ideal CPU percentage. Therefore, it is compatible to 897a937b6aaSMarkus Armbruster# traditional throttling, meanwhile the throttle increment won't 898a937b6aaSMarkus Armbruster# be excessive at tail stage. The default value is false. (Since 899a937b6aaSMarkus Armbruster# 5.1) 900cbbf8182SKeqian Zhu# 90148685a8eSMarkus Armbruster# @tls-creds: ID of the 'tls-creds' object that provides credentials 90248685a8eSMarkus Armbruster# for establishing a TLS connection over the migration data 90348685a8eSMarkus Armbruster# channel. On the outgoing side of the migration, the credentials 90448685a8eSMarkus Armbruster# must be for a 'client' endpoint, while for the incoming side the 905a937b6aaSMarkus Armbruster# credentials must be for a 'server' endpoint. Setting this to a 906a937b6aaSMarkus Armbruster# non-empty string enables TLS for all migrations. An empty 907a937b6aaSMarkus Armbruster# string means that QEMU will use plain text mode for migration, 908a937b6aaSMarkus Armbruster# rather than TLS (Since 2.9) Previously (since 2.7), this was 909a937b6aaSMarkus Armbruster# reported by omitting tls-creds instead. 91048685a8eSMarkus Armbruster# 91148685a8eSMarkus Armbruster# @tls-hostname: hostname of the target host for the migration. This 91248685a8eSMarkus Armbruster# is required when using x509 based TLS credentials and the 913a937b6aaSMarkus Armbruster# migration URI does not already include a hostname. For example 914a937b6aaSMarkus Armbruster# if using fd: or exec: based migration, the hostname must be 915a937b6aaSMarkus Armbruster# provided so that the server's x509 certificate identity can be 916a937b6aaSMarkus Armbruster# validated. (Since 2.7) An empty string means that QEMU will use 917a937b6aaSMarkus Armbruster# the hostname associated with the migration URI, if any. (Since 918a937b6aaSMarkus Armbruster# 2.9) Previously (since 2.7), this was reported by omitting 91948685a8eSMarkus Armbruster# tls-hostname instead. 92048685a8eSMarkus Armbruster# 921a937b6aaSMarkus Armbruster# @max-bandwidth: to set maximum speed for migration. maximum speed 922a937b6aaSMarkus Armbruster# in bytes per second. (Since 2.8) 92348685a8eSMarkus Armbruster# 924a937b6aaSMarkus Armbruster# @downtime-limit: set maximum tolerated downtime for migration. 925a937b6aaSMarkus Armbruster# maximum downtime in milliseconds (Since 2.8) 92648685a8eSMarkus Armbruster# 927a937b6aaSMarkus Armbruster# @x-checkpoint-delay: the delay time between two COLO checkpoints. 928a937b6aaSMarkus Armbruster# (Since 2.8) 92948685a8eSMarkus Armbruster# 93048685a8eSMarkus Armbruster# @block-incremental: Affects how much storage is migrated when the 93148685a8eSMarkus Armbruster# block migration capability is enabled. When false, the entire 932a937b6aaSMarkus Armbruster# storage backing chain is migrated into a flattened image at the 933a937b6aaSMarkus Armbruster# destination; when true, only the active qcow2 layer is migrated 934a937b6aaSMarkus Armbruster# and the destination must already have access to the same backing 935a937b6aaSMarkus Armbruster# chain as was used on the source. (since 2.10) 93648685a8eSMarkus Armbruster# 937cbfd6c95SJuan Quintela# @multifd-channels: Number of channels used to migrate data in 938a937b6aaSMarkus Armbruster# parallel. This is the same number that the number of sockets 939a937b6aaSMarkus Armbruster# used for migration. The default value is 2 (since 4.0) 9404075fb1cSJuan Quintela# 94173af8dd8SJuan Quintela# @xbzrle-cache-size: cache size to be used by XBZRLE migration. It 942a937b6aaSMarkus Armbruster# needs to be a multiple of the target page size and a power of 2 94373af8dd8SJuan Quintela# (Since 2.11) 9447e555c6cSDr. David Alan Gilbert# 945a937b6aaSMarkus Armbruster# @max-postcopy-bandwidth: Background transfer bandwidth during 946a937b6aaSMarkus Armbruster# postcopy. Defaults to 0 (unlimited). In bytes per second. 9477e555c6cSDr. David Alan Gilbert# (Since 3.0) 9484cbc9c7fSLi Qiang# 949a937b6aaSMarkus Armbruster# @max-cpu-throttle: maximum cpu throttle percentage. The default 950a937b6aaSMarkus Armbruster# value is 99. (Since 3.1) 9514cbc9c7fSLi Qiang# 952a937b6aaSMarkus Armbruster# @multifd-compression: Which compression method to use. Defaults to 953a937b6aaSMarkus Armbruster# none. (Since 5.0) 95496eef042SJuan Quintela# 9559004db48SJuan Quintela# @multifd-zlib-level: Set the compression level to be used in live 956a937b6aaSMarkus Armbruster# migration, the compression level is an integer between 0 and 9, 957a937b6aaSMarkus Armbruster# where 0 means no compression, 1 means the best compression 958a937b6aaSMarkus Armbruster# speed, and 9 means best compression ratio which will consume 959a937b6aaSMarkus Armbruster# more CPU. Defaults to 1. (Since 5.0) 9609004db48SJuan Quintela# 9616a9ad154SJuan Quintela# @multifd-zstd-level: Set the compression level to be used in live 962a937b6aaSMarkus Armbruster# migration, the compression level is an integer between 0 and 20, 963a937b6aaSMarkus Armbruster# where 0 means no compression, 1 means the best compression 964a937b6aaSMarkus Armbruster# speed, and 20 means best compression ratio which will consume 965a937b6aaSMarkus Armbruster# more CPU. Defaults to 1. (Since 5.0) 9666a9ad154SJuan Quintela# 96731e4c354SMax Reitz# @block-bitmap-mapping: Maps block nodes and bitmaps on them to 968a937b6aaSMarkus Armbruster# aliases for the purpose of dirty bitmap migration. Such aliases 969a937b6aaSMarkus Armbruster# may for example be the corresponding names on the opposite site. 970a937b6aaSMarkus Armbruster# The mapping must be one-to-one, but not necessarily complete: On 971a937b6aaSMarkus Armbruster# the source, unmapped bitmaps and all bitmaps on unmapped nodes 972a937b6aaSMarkus Armbruster# will be ignored. On the destination, encountering an unmapped 973a937b6aaSMarkus Armbruster# alias in the incoming migration stream will result in a report, 974a937b6aaSMarkus Armbruster# and all further bitmap migration data will then be discarded. 975a937b6aaSMarkus Armbruster# Note that the destination does not know about bitmaps it does 976a937b6aaSMarkus Armbruster# not receive, so there is no limitation or requirement regarding 977a937b6aaSMarkus Armbruster# the number of bitmaps received, or how they are named, or on 978a937b6aaSMarkus Armbruster# which nodes they are placed. By default (when this parameter 979a937b6aaSMarkus Armbruster# has never been set), bitmap names are mapped to themselves. 980a937b6aaSMarkus Armbruster# Nodes are mapped to their block device name if there is one, and 981a937b6aaSMarkus Armbruster# to their node name otherwise. (Since 5.2) 98231e4c354SMax Reitz# 9834d807857SHyman Huang(黄勇)# @x-vcpu-dirty-limit-period: Periodic time (in milliseconds) of dirty limit during 9844d807857SHyman Huang(黄勇)# live migration. Should be in the range 1 to 1000ms, 9854d807857SHyman Huang(黄勇)# defaults to 1000ms. (Since 8.1) 9864d807857SHyman Huang(黄勇)# 98709f9ec99SHyman Huang(黄勇)# @vcpu-dirty-limit: Dirtyrate limit (MB/s) during live migration. 98809f9ec99SHyman Huang(黄勇)# Defaults to 1. (Since 8.1) 98909f9ec99SHyman Huang(黄勇)# 9909fb49daaSMarkus Armbruster# Features: 991a937b6aaSMarkus Armbruster# 9924d807857SHyman Huang(黄勇)# @unstable: Members @x-checkpoint-delay and @x-vcpu-dirty-limit-period 9934d807857SHyman Huang(黄勇)# are experimental. 9949fb49daaSMarkus Armbruster# 99556266c6dSMarkus Armbruster# TODO: either fuse back into MigrationParameters, or make 99656266c6dSMarkus Armbruster# MigrationParameters members mandatory 99756266c6dSMarkus Armbruster# 99848685a8eSMarkus Armbruster# Since: 2.4 99948685a8eSMarkus Armbruster## 100048685a8eSMarkus Armbruster{ 'struct': 'MigrateSetParameters', 1001ee3d96baSDr. David Alan Gilbert 'data': { '*announce-initial': 'size', 1002ee3d96baSDr. David Alan Gilbert '*announce-max': 'size', 1003ee3d96baSDr. David Alan Gilbert '*announce-rounds': 'size', 1004ee3d96baSDr. David Alan Gilbert '*announce-step': 'size', 1005ec17de0aSMarkus Armbruster '*compress-level': 'uint8', 1006ec17de0aSMarkus Armbruster '*compress-threads': 'uint8', 10071d58872aSXiao Guangrong '*compress-wait-thread': 'bool', 1008ec17de0aSMarkus Armbruster '*decompress-threads': 'uint8', 1009ec17de0aSMarkus Armbruster '*throttle-trigger-threshold': 'uint8', 1010ec17de0aSMarkus Armbruster '*cpu-throttle-initial': 'uint8', 1011ec17de0aSMarkus Armbruster '*cpu-throttle-increment': 'uint8', 1012cbbf8182SKeqian Zhu '*cpu-throttle-tailslow': 'bool', 101348685a8eSMarkus Armbruster '*tls-creds': 'StrOrNull', 101448685a8eSMarkus Armbruster '*tls-hostname': 'StrOrNull', 1015d2f1d29bSDaniel P. Berrange '*tls-authz': 'StrOrNull', 1016ec17de0aSMarkus Armbruster '*max-bandwidth': 'size', 1017ec17de0aSMarkus Armbruster '*downtime-limit': 'uint64', 10189fb49daaSMarkus Armbruster '*x-checkpoint-delay': { 'type': 'uint32', 10199fb49daaSMarkus Armbruster 'features': [ 'unstable' ] }, 10204075fb1cSJuan Quintela '*block-incremental': 'bool', 1021ec17de0aSMarkus Armbruster '*multifd-channels': 'uint8', 10227e555c6cSDr. David Alan Gilbert '*xbzrle-cache-size': 'size', 10234cbc9c7fSLi Qiang '*max-postcopy-bandwidth': 'size', 1024ec17de0aSMarkus Armbruster '*max-cpu-throttle': 'uint8', 10259004db48SJuan Quintela '*multifd-compression': 'MultiFDCompression', 1026ec17de0aSMarkus Armbruster '*multifd-zlib-level': 'uint8', 1027ec17de0aSMarkus Armbruster '*multifd-zstd-level': 'uint8', 10284d807857SHyman Huang(黄勇) '*block-bitmap-mapping': [ 'BitmapMigrationNodeAlias' ], 10294d807857SHyman Huang(黄勇) '*x-vcpu-dirty-limit-period': { 'type': 'uint64', 103009f9ec99SHyman Huang(黄勇) 'features': [ 'unstable' ] }, 103109f9ec99SHyman Huang(黄勇) '*vcpu-dirty-limit': 'uint64'} } 103248685a8eSMarkus Armbruster 103348685a8eSMarkus Armbruster## 103448685a8eSMarkus Armbruster# @migrate-set-parameters: 103548685a8eSMarkus Armbruster# 103648685a8eSMarkus Armbruster# Set various migration parameters. 103748685a8eSMarkus Armbruster# 103848685a8eSMarkus Armbruster# Since: 2.4 103948685a8eSMarkus Armbruster# 104048685a8eSMarkus Armbruster# Example: 104148685a8eSMarkus Armbruster# 104248685a8eSMarkus Armbruster# -> { "execute": "migrate-set-parameters" , 104348685a8eSMarkus Armbruster# "arguments": { "compress-level": 1 } } 104437fa48a4SMarkus Armbruster# <- { "return": {} } 104548685a8eSMarkus Armbruster## 104648685a8eSMarkus Armbruster{ 'command': 'migrate-set-parameters', 'boxed': true, 104748685a8eSMarkus Armbruster 'data': 'MigrateSetParameters' } 104848685a8eSMarkus Armbruster 104948685a8eSMarkus Armbruster## 105048685a8eSMarkus Armbruster# @MigrationParameters: 105148685a8eSMarkus Armbruster# 105248685a8eSMarkus Armbruster# The optional members aren't actually optional. 105348685a8eSMarkus Armbruster# 1054a937b6aaSMarkus Armbruster# @announce-initial: Initial delay (in milliseconds) before sending 1055a937b6aaSMarkus Armbruster# the first announce (Since 4.0) 1056ee3d96baSDr. David Alan Gilbert# 1057a937b6aaSMarkus Armbruster# @announce-max: Maximum delay (in milliseconds) between packets in 1058a937b6aaSMarkus Armbruster# the announcement (Since 4.0) 1059ee3d96baSDr. David Alan Gilbert# 1060a937b6aaSMarkus Armbruster# @announce-rounds: Number of self-announce packets sent after 1061a937b6aaSMarkus Armbruster# migration (Since 4.0) 1062ee3d96baSDr. David Alan Gilbert# 1063a937b6aaSMarkus Armbruster# @announce-step: Increase in delay (in milliseconds) between 1064a937b6aaSMarkus Armbruster# subsequent packets in the announcement (Since 4.0) 1065ee3d96baSDr. David Alan Gilbert# 106648685a8eSMarkus Armbruster# @compress-level: compression level 106748685a8eSMarkus Armbruster# 106848685a8eSMarkus Armbruster# @compress-threads: compression thread count 106948685a8eSMarkus Armbruster# 1070a937b6aaSMarkus Armbruster# @compress-wait-thread: Controls behavior when all compression 1071a937b6aaSMarkus Armbruster# threads are currently busy. If true (default), wait for a free 1072a937b6aaSMarkus Armbruster# compression thread to become available; otherwise, send the page 1073a937b6aaSMarkus Armbruster# uncompressed. (Since 3.1) 10741d58872aSXiao Guangrong# 107548685a8eSMarkus Armbruster# @decompress-threads: decompression thread count 107648685a8eSMarkus Armbruster# 1077a937b6aaSMarkus Armbruster# @throttle-trigger-threshold: The ratio of bytes_dirty_period and 1078a937b6aaSMarkus Armbruster# bytes_xfer_period to trigger throttling. It is expressed as 1079a937b6aaSMarkus Armbruster# percentage. The default value is 50. (Since 5.0) 1080dc14a470SKeqian Zhu# 108148685a8eSMarkus Armbruster# @cpu-throttle-initial: Initial percentage of time guest cpus are 1082a937b6aaSMarkus Armbruster# throttled when migration auto-converge is activated. (Since 1083a937b6aaSMarkus Armbruster# 2.7) 108448685a8eSMarkus Armbruster# 108548685a8eSMarkus Armbruster# @cpu-throttle-increment: throttle percentage increase each time 1086a937b6aaSMarkus Armbruster# auto-converge detects that migration is not making progress. 1087a937b6aaSMarkus Armbruster# (Since 2.7) 108848685a8eSMarkus Armbruster# 1089a937b6aaSMarkus Armbruster# @cpu-throttle-tailslow: Make CPU throttling slower at tail stage At 1090a937b6aaSMarkus Armbruster# the tail stage of throttling, the Guest is very sensitive to CPU 1091a937b6aaSMarkus Armbruster# percentage while the @cpu-throttle -increment is excessive 1092a937b6aaSMarkus Armbruster# usually at tail stage. If this parameter is true, we will 1093a937b6aaSMarkus Armbruster# compute the ideal CPU percentage used by the Guest, which may 1094a937b6aaSMarkus Armbruster# exactly make the dirty rate match the dirty rate threshold. 1095a937b6aaSMarkus Armbruster# Then we will choose a smaller throttle increment between the one 1096a937b6aaSMarkus Armbruster# specified by @cpu-throttle-increment and the one generated by 1097a937b6aaSMarkus Armbruster# ideal CPU percentage. Therefore, it is compatible to 1098a937b6aaSMarkus Armbruster# traditional throttling, meanwhile the throttle increment won't 1099a937b6aaSMarkus Armbruster# be excessive at tail stage. The default value is false. (Since 1100a937b6aaSMarkus Armbruster# 5.1) 1101cbbf8182SKeqian Zhu# 110248685a8eSMarkus Armbruster# @tls-creds: ID of the 'tls-creds' object that provides credentials 110348685a8eSMarkus Armbruster# for establishing a TLS connection over the migration data 110448685a8eSMarkus Armbruster# channel. On the outgoing side of the migration, the credentials 110548685a8eSMarkus Armbruster# must be for a 'client' endpoint, while for the incoming side the 1106a937b6aaSMarkus Armbruster# credentials must be for a 'server' endpoint. An empty string 1107a937b6aaSMarkus Armbruster# means that QEMU will use plain text mode for migration, rather 1108a937b6aaSMarkus Armbruster# than TLS (Since 2.7) Note: 2.8 reports this by omitting 1109a937b6aaSMarkus Armbruster# tls-creds instead. 111048685a8eSMarkus Armbruster# 111148685a8eSMarkus Armbruster# @tls-hostname: hostname of the target host for the migration. This 111248685a8eSMarkus Armbruster# is required when using x509 based TLS credentials and the 1113a937b6aaSMarkus Armbruster# migration URI does not already include a hostname. For example 1114a937b6aaSMarkus Armbruster# if using fd: or exec: based migration, the hostname must be 1115a937b6aaSMarkus Armbruster# provided so that the server's x509 certificate identity can be 1116a937b6aaSMarkus Armbruster# validated. (Since 2.7) An empty string means that QEMU will use 1117a937b6aaSMarkus Armbruster# the hostname associated with the migration URI, if any. (Since 1118a937b6aaSMarkus Armbruster# 2.9) Note: 2.8 reports this by omitting tls-hostname instead. 111948685a8eSMarkus Armbruster# 1120a937b6aaSMarkus Armbruster# @tls-authz: ID of the 'authz' object subclass that provides access 1121a937b6aaSMarkus Armbruster# control checking of the TLS x509 certificate distinguished name. 1122a937b6aaSMarkus Armbruster# (Since 4.0) 1123d2f1d29bSDaniel P. Berrange# 1124a937b6aaSMarkus Armbruster# @max-bandwidth: to set maximum speed for migration. maximum speed 1125a937b6aaSMarkus Armbruster# in bytes per second. (Since 2.8) 112648685a8eSMarkus Armbruster# 1127a937b6aaSMarkus Armbruster# @downtime-limit: set maximum tolerated downtime for migration. 1128a937b6aaSMarkus Armbruster# maximum downtime in milliseconds (Since 2.8) 112948685a8eSMarkus Armbruster# 1130a937b6aaSMarkus Armbruster# @x-checkpoint-delay: the delay time between two COLO checkpoints. 1131a937b6aaSMarkus Armbruster# (Since 2.8) 113248685a8eSMarkus Armbruster# 113348685a8eSMarkus Armbruster# @block-incremental: Affects how much storage is migrated when the 113448685a8eSMarkus Armbruster# block migration capability is enabled. When false, the entire 1135a937b6aaSMarkus Armbruster# storage backing chain is migrated into a flattened image at the 1136a937b6aaSMarkus Armbruster# destination; when true, only the active qcow2 layer is migrated 1137a937b6aaSMarkus Armbruster# and the destination must already have access to the same backing 1138a937b6aaSMarkus Armbruster# chain as was used on the source. (since 2.10) 113948685a8eSMarkus Armbruster# 1140cbfd6c95SJuan Quintela# @multifd-channels: Number of channels used to migrate data in 1141a937b6aaSMarkus Armbruster# parallel. This is the same number that the number of sockets 1142a937b6aaSMarkus Armbruster# used for migration. The default value is 2 (since 4.0) 11434075fb1cSJuan Quintela# 114473af8dd8SJuan Quintela# @xbzrle-cache-size: cache size to be used by XBZRLE migration. It 1145a937b6aaSMarkus Armbruster# needs to be a multiple of the target page size and a power of 2 114673af8dd8SJuan Quintela# (Since 2.11) 11477e555c6cSDr. David Alan Gilbert# 1148a937b6aaSMarkus Armbruster# @max-postcopy-bandwidth: Background transfer bandwidth during 1149a937b6aaSMarkus Armbruster# postcopy. Defaults to 0 (unlimited). In bytes per second. 11507e555c6cSDr. David Alan Gilbert# (Since 3.0) 11514cbc9c7fSLi Qiang# 1152a937b6aaSMarkus Armbruster# @max-cpu-throttle: maximum cpu throttle percentage. Defaults to 99. 11534cbc9c7fSLi Qiang# (Since 3.1) 11544cbc9c7fSLi Qiang# 1155a937b6aaSMarkus Armbruster# @multifd-compression: Which compression method to use. Defaults to 1156a937b6aaSMarkus Armbruster# none. (Since 5.0) 115796eef042SJuan Quintela# 11589004db48SJuan Quintela# @multifd-zlib-level: Set the compression level to be used in live 1159a937b6aaSMarkus Armbruster# migration, the compression level is an integer between 0 and 9, 1160a937b6aaSMarkus Armbruster# where 0 means no compression, 1 means the best compression 1161a937b6aaSMarkus Armbruster# speed, and 9 means best compression ratio which will consume 1162a937b6aaSMarkus Armbruster# more CPU. Defaults to 1. (Since 5.0) 11639004db48SJuan Quintela# 11646a9ad154SJuan Quintela# @multifd-zstd-level: Set the compression level to be used in live 1165a937b6aaSMarkus Armbruster# migration, the compression level is an integer between 0 and 20, 1166a937b6aaSMarkus Armbruster# where 0 means no compression, 1 means the best compression 1167a937b6aaSMarkus Armbruster# speed, and 20 means best compression ratio which will consume 1168a937b6aaSMarkus Armbruster# more CPU. Defaults to 1. (Since 5.0) 11696a9ad154SJuan Quintela# 117031e4c354SMax Reitz# @block-bitmap-mapping: Maps block nodes and bitmaps on them to 1171a937b6aaSMarkus Armbruster# aliases for the purpose of dirty bitmap migration. Such aliases 1172a937b6aaSMarkus Armbruster# may for example be the corresponding names on the opposite site. 1173a937b6aaSMarkus Armbruster# The mapping must be one-to-one, but not necessarily complete: On 1174a937b6aaSMarkus Armbruster# the source, unmapped bitmaps and all bitmaps on unmapped nodes 1175a937b6aaSMarkus Armbruster# will be ignored. On the destination, encountering an unmapped 1176a937b6aaSMarkus Armbruster# alias in the incoming migration stream will result in a report, 1177a937b6aaSMarkus Armbruster# and all further bitmap migration data will then be discarded. 1178a937b6aaSMarkus Armbruster# Note that the destination does not know about bitmaps it does 1179a937b6aaSMarkus Armbruster# not receive, so there is no limitation or requirement regarding 1180a937b6aaSMarkus Armbruster# the number of bitmaps received, or how they are named, or on 1181a937b6aaSMarkus Armbruster# which nodes they are placed. By default (when this parameter 1182a937b6aaSMarkus Armbruster# has never been set), bitmap names are mapped to themselves. 1183a937b6aaSMarkus Armbruster# Nodes are mapped to their block device name if there is one, and 1184a937b6aaSMarkus Armbruster# to their node name otherwise. (Since 5.2) 118531e4c354SMax Reitz# 11864d807857SHyman Huang(黄勇)# @x-vcpu-dirty-limit-period: Periodic time (in milliseconds) of dirty limit during 11874d807857SHyman Huang(黄勇)# live migration. Should be in the range 1 to 1000ms, 11884d807857SHyman Huang(黄勇)# defaults to 1000ms. (Since 8.1) 11894d807857SHyman Huang(黄勇)# 119009f9ec99SHyman Huang(黄勇)# @vcpu-dirty-limit: Dirtyrate limit (MB/s) during live migration. 119109f9ec99SHyman Huang(黄勇)# Defaults to 1. (Since 8.1) 119209f9ec99SHyman Huang(黄勇)# 11939fb49daaSMarkus Armbruster# Features: 1194a937b6aaSMarkus Armbruster# 11954d807857SHyman Huang(黄勇)# @unstable: Members @x-checkpoint-delay and @x-vcpu-dirty-limit-period 11964d807857SHyman Huang(黄勇)# are experimental. 11979fb49daaSMarkus Armbruster# 119848685a8eSMarkus Armbruster# Since: 2.4 119948685a8eSMarkus Armbruster## 120048685a8eSMarkus Armbruster{ 'struct': 'MigrationParameters', 1201ee3d96baSDr. David Alan Gilbert 'data': { '*announce-initial': 'size', 1202ee3d96baSDr. David Alan Gilbert '*announce-max': 'size', 1203ee3d96baSDr. David Alan Gilbert '*announce-rounds': 'size', 1204ee3d96baSDr. David Alan Gilbert '*announce-step': 'size', 1205ee3d96baSDr. David Alan Gilbert '*compress-level': 'uint8', 1206741d4086SJuan Quintela '*compress-threads': 'uint8', 12071d58872aSXiao Guangrong '*compress-wait-thread': 'bool', 1208741d4086SJuan Quintela '*decompress-threads': 'uint8', 1209dc14a470SKeqian Zhu '*throttle-trigger-threshold': 'uint8', 1210741d4086SJuan Quintela '*cpu-throttle-initial': 'uint8', 1211741d4086SJuan Quintela '*cpu-throttle-increment': 'uint8', 1212cbbf8182SKeqian Zhu '*cpu-throttle-tailslow': 'bool', 121348685a8eSMarkus Armbruster '*tls-creds': 'str', 121448685a8eSMarkus Armbruster '*tls-hostname': 'str', 1215d2f1d29bSDaniel P. Berrange '*tls-authz': 'str', 1216741d4086SJuan Quintela '*max-bandwidth': 'size', 1217741d4086SJuan Quintela '*downtime-limit': 'uint64', 12189fb49daaSMarkus Armbruster '*x-checkpoint-delay': { 'type': 'uint32', 12199fb49daaSMarkus Armbruster 'features': [ 'unstable' ] }, 12204075fb1cSJuan Quintela '*block-incremental': 'bool', 1221cbfd6c95SJuan Quintela '*multifd-channels': 'uint8', 12227e555c6cSDr. David Alan Gilbert '*xbzrle-cache-size': 'size', 12234cbc9c7fSLi Qiang '*max-postcopy-bandwidth': 'size', 122496eef042SJuan Quintela '*max-cpu-throttle': 'uint8', 12259004db48SJuan Quintela '*multifd-compression': 'MultiFDCompression', 12266a9ad154SJuan Quintela '*multifd-zlib-level': 'uint8', 122731e4c354SMax Reitz '*multifd-zstd-level': 'uint8', 12284d807857SHyman Huang(黄勇) '*block-bitmap-mapping': [ 'BitmapMigrationNodeAlias' ], 12294d807857SHyman Huang(黄勇) '*x-vcpu-dirty-limit-period': { 'type': 'uint64', 123009f9ec99SHyman Huang(黄勇) 'features': [ 'unstable' ] }, 123109f9ec99SHyman Huang(黄勇) '*vcpu-dirty-limit': 'uint64'} } 123248685a8eSMarkus Armbruster 123348685a8eSMarkus Armbruster## 123448685a8eSMarkus Armbruster# @query-migrate-parameters: 123548685a8eSMarkus Armbruster# 123648685a8eSMarkus Armbruster# Returns information about the current migration parameters 123748685a8eSMarkus Armbruster# 123848685a8eSMarkus Armbruster# Returns: @MigrationParameters 123948685a8eSMarkus Armbruster# 124048685a8eSMarkus Armbruster# Since: 2.4 124148685a8eSMarkus Armbruster# 124248685a8eSMarkus Armbruster# Example: 124348685a8eSMarkus Armbruster# 124448685a8eSMarkus Armbruster# -> { "execute": "query-migrate-parameters" } 124548685a8eSMarkus Armbruster# <- { "return": { 124648685a8eSMarkus Armbruster# "decompress-threads": 2, 124748685a8eSMarkus Armbruster# "cpu-throttle-increment": 10, 124848685a8eSMarkus Armbruster# "compress-threads": 8, 124948685a8eSMarkus Armbruster# "compress-level": 1, 125048685a8eSMarkus Armbruster# "cpu-throttle-initial": 20, 125148685a8eSMarkus Armbruster# "max-bandwidth": 33554432, 125248685a8eSMarkus Armbruster# "downtime-limit": 300 125348685a8eSMarkus Armbruster# } 125448685a8eSMarkus Armbruster# } 125548685a8eSMarkus Armbruster## 125648685a8eSMarkus Armbruster{ 'command': 'query-migrate-parameters', 125748685a8eSMarkus Armbruster 'returns': 'MigrationParameters' } 125848685a8eSMarkus Armbruster 125948685a8eSMarkus Armbruster## 126048685a8eSMarkus Armbruster# @migrate-start-postcopy: 126148685a8eSMarkus Armbruster# 1262a937b6aaSMarkus Armbruster# Followup to a migration command to switch the migration to postcopy 1263a937b6aaSMarkus Armbruster# mode. The postcopy-ram capability must be set on both source and 1264a937b6aaSMarkus Armbruster# destination before the original migration command. 126548685a8eSMarkus Armbruster# 126648685a8eSMarkus Armbruster# Since: 2.5 126748685a8eSMarkus Armbruster# 126848685a8eSMarkus Armbruster# Example: 126948685a8eSMarkus Armbruster# 127048685a8eSMarkus Armbruster# -> { "execute": "migrate-start-postcopy" } 127148685a8eSMarkus Armbruster# <- { "return": {} } 127248685a8eSMarkus Armbruster## 127348685a8eSMarkus Armbruster{ 'command': 'migrate-start-postcopy' } 127448685a8eSMarkus Armbruster 127548685a8eSMarkus Armbruster## 127648685a8eSMarkus Armbruster# @MIGRATION: 127748685a8eSMarkus Armbruster# 127848685a8eSMarkus Armbruster# Emitted when a migration event happens 127948685a8eSMarkus Armbruster# 128048685a8eSMarkus Armbruster# @status: @MigrationStatus describing the current migration status. 128148685a8eSMarkus Armbruster# 128248685a8eSMarkus Armbruster# Since: 2.4 128348685a8eSMarkus Armbruster# 128448685a8eSMarkus Armbruster# Example: 128548685a8eSMarkus Armbruster# 128648685a8eSMarkus Armbruster# <- {"timestamp": {"seconds": 1432121972, "microseconds": 744001}, 128748685a8eSMarkus Armbruster# "event": "MIGRATION", 128848685a8eSMarkus Armbruster# "data": {"status": "completed"} } 128948685a8eSMarkus Armbruster## 129048685a8eSMarkus Armbruster{ 'event': 'MIGRATION', 129148685a8eSMarkus Armbruster 'data': {'status': 'MigrationStatus'}} 129248685a8eSMarkus Armbruster 129348685a8eSMarkus Armbruster## 129448685a8eSMarkus Armbruster# @MIGRATION_PASS: 129548685a8eSMarkus Armbruster# 1296a937b6aaSMarkus Armbruster# Emitted from the source side of a migration at the start of each 1297a937b6aaSMarkus Armbruster# pass (when it syncs the dirty bitmap) 129848685a8eSMarkus Armbruster# 129948685a8eSMarkus Armbruster# @pass: An incrementing count (starting at 1 on the first pass) 130048685a8eSMarkus Armbruster# 130148685a8eSMarkus Armbruster# Since: 2.6 130248685a8eSMarkus Armbruster# 130348685a8eSMarkus Armbruster# Example: 130448685a8eSMarkus Armbruster# 130537fa48a4SMarkus Armbruster# <- { "timestamp": {"seconds": 1449669631, "microseconds": 239225}, 130648685a8eSMarkus Armbruster# "event": "MIGRATION_PASS", "data": {"pass": 2} } 130748685a8eSMarkus Armbruster## 130848685a8eSMarkus Armbruster{ 'event': 'MIGRATION_PASS', 130948685a8eSMarkus Armbruster 'data': { 'pass': 'int' } } 131048685a8eSMarkus Armbruster 131148685a8eSMarkus Armbruster## 131248685a8eSMarkus Armbruster# @COLOMessage: 131348685a8eSMarkus Armbruster# 131448685a8eSMarkus Armbruster# The message transmission between Primary side and Secondary side. 131548685a8eSMarkus Armbruster# 131648685a8eSMarkus Armbruster# @checkpoint-ready: Secondary VM (SVM) is ready for checkpointing 131748685a8eSMarkus Armbruster# 1318a937b6aaSMarkus Armbruster# @checkpoint-request: Primary VM (PVM) tells SVM to prepare for 1319a937b6aaSMarkus Armbruster# checkpointing 132048685a8eSMarkus Armbruster# 132148685a8eSMarkus Armbruster# @checkpoint-reply: SVM gets PVM's checkpoint request 132248685a8eSMarkus Armbruster# 132348685a8eSMarkus Armbruster# @vmstate-send: VM's state will be sent by PVM. 132448685a8eSMarkus Armbruster# 132548685a8eSMarkus Armbruster# @vmstate-size: The total size of VMstate. 132648685a8eSMarkus Armbruster# 132748685a8eSMarkus Armbruster# @vmstate-received: VM's state has been received by SVM. 132848685a8eSMarkus Armbruster# 132948685a8eSMarkus Armbruster# @vmstate-loaded: VM's state has been loaded by SVM. 133048685a8eSMarkus Armbruster# 133148685a8eSMarkus Armbruster# Since: 2.8 133248685a8eSMarkus Armbruster## 133348685a8eSMarkus Armbruster{ 'enum': 'COLOMessage', 133448685a8eSMarkus Armbruster 'data': [ 'checkpoint-ready', 'checkpoint-request', 'checkpoint-reply', 133548685a8eSMarkus Armbruster 'vmstate-send', 'vmstate-size', 'vmstate-received', 133648685a8eSMarkus Armbruster 'vmstate-loaded' ] } 133748685a8eSMarkus Armbruster 133848685a8eSMarkus Armbruster## 133948685a8eSMarkus Armbruster# @COLOMode: 134048685a8eSMarkus Armbruster# 134141b6b779SZhang Chen# The COLO current mode. 134248685a8eSMarkus Armbruster# 134341b6b779SZhang Chen# @none: COLO is disabled. 134448685a8eSMarkus Armbruster# 134541b6b779SZhang Chen# @primary: COLO node in primary side. 134648685a8eSMarkus Armbruster# 134741b6b779SZhang Chen# @secondary: COLO node in slave side. 134848685a8eSMarkus Armbruster# 134948685a8eSMarkus Armbruster# Since: 2.8 135048685a8eSMarkus Armbruster## 135148685a8eSMarkus Armbruster{ 'enum': 'COLOMode', 135241b6b779SZhang Chen 'data': [ 'none', 'primary', 'secondary'] } 135348685a8eSMarkus Armbruster 135448685a8eSMarkus Armbruster## 135548685a8eSMarkus Armbruster# @FailoverStatus: 135648685a8eSMarkus Armbruster# 135748685a8eSMarkus Armbruster# An enumeration of COLO failover status 135848685a8eSMarkus Armbruster# 135948685a8eSMarkus Armbruster# @none: no failover has ever happened 136048685a8eSMarkus Armbruster# 136148685a8eSMarkus Armbruster# @require: got failover requirement but not handled 136248685a8eSMarkus Armbruster# 136348685a8eSMarkus Armbruster# @active: in the process of doing failover 136448685a8eSMarkus Armbruster# 136548685a8eSMarkus Armbruster# @completed: finish the process of failover 136648685a8eSMarkus Armbruster# 1367a937b6aaSMarkus Armbruster# @relaunch: restart the failover process, from 'none' -> 'completed' 1368a937b6aaSMarkus Armbruster# (Since 2.9) 136948685a8eSMarkus Armbruster# 137048685a8eSMarkus Armbruster# Since: 2.8 137148685a8eSMarkus Armbruster## 137248685a8eSMarkus Armbruster{ 'enum': 'FailoverStatus', 137348685a8eSMarkus Armbruster 'data': [ 'none', 'require', 'active', 'completed', 'relaunch' ] } 137448685a8eSMarkus Armbruster 137548685a8eSMarkus Armbruster## 13769ecff6d6Szhanghailiang# @COLO_EXIT: 13779ecff6d6Szhanghailiang# 13789ecff6d6Szhanghailiang# Emitted when VM finishes COLO mode due to some errors happening or 13799ecff6d6Szhanghailiang# at the request of users. 13809ecff6d6Szhanghailiang# 13819ecff6d6Szhanghailiang# @mode: report COLO mode when COLO exited. 13829ecff6d6Szhanghailiang# 13839ecff6d6Szhanghailiang# @reason: describes the reason for the COLO exit. 13849ecff6d6Szhanghailiang# 13859ecff6d6Szhanghailiang# Since: 3.1 13869ecff6d6Szhanghailiang# 13879ecff6d6Szhanghailiang# Example: 13889ecff6d6Szhanghailiang# 13899ecff6d6Szhanghailiang# <- { "timestamp": {"seconds": 2032141960, "microseconds": 417172}, 13909ecff6d6Szhanghailiang# "event": "COLO_EXIT", "data": {"mode": "primary", "reason": "request" } } 13919ecff6d6Szhanghailiang## 13929ecff6d6Szhanghailiang{ 'event': 'COLO_EXIT', 13939ecff6d6Szhanghailiang 'data': {'mode': 'COLOMode', 'reason': 'COLOExitReason' } } 13949ecff6d6Szhanghailiang 13959ecff6d6Szhanghailiang## 13969ecff6d6Szhanghailiang# @COLOExitReason: 13979ecff6d6Szhanghailiang# 13983a43ac47SZhang Chen# The reason for a COLO exit. 13999ecff6d6Szhanghailiang# 1400a937b6aaSMarkus Armbruster# @none: failover has never happened. This state does not occur in 1401a937b6aaSMarkus Armbruster# the COLO_EXIT event, and is only visible in the result of 14023a43ac47SZhang Chen# query-colo-status. 14039ecff6d6Szhanghailiang# 14043a43ac47SZhang Chen# @request: COLO exit is due to an external request. 14059ecff6d6Szhanghailiang# 14063a43ac47SZhang Chen# @error: COLO exit is due to an internal error. 14073a43ac47SZhang Chen# 14083a43ac47SZhang Chen# @processing: COLO is currently handling a failover (since 4.0). 14099ecff6d6Szhanghailiang# 14109ecff6d6Szhanghailiang# Since: 3.1 14119ecff6d6Szhanghailiang## 14129ecff6d6Szhanghailiang{ 'enum': 'COLOExitReason', 14133a43ac47SZhang Chen 'data': [ 'none', 'request', 'error' , 'processing' ] } 14149ecff6d6Szhanghailiang 14159ecff6d6Szhanghailiang## 141648685a8eSMarkus Armbruster# @x-colo-lost-heartbeat: 141748685a8eSMarkus Armbruster# 1418a937b6aaSMarkus Armbruster# Tell qemu that heartbeat is lost, request it to do takeover 1419a937b6aaSMarkus Armbruster# procedures. If this command is sent to the PVM, the Primary side 1420a937b6aaSMarkus Armbruster# will exit COLO mode. If sent to the Secondary, the Secondary side 1421a937b6aaSMarkus Armbruster# will run failover work, then takes over server operation to become 1422a937b6aaSMarkus Armbruster# the service VM. 142348685a8eSMarkus Armbruster# 14249fb49daaSMarkus Armbruster# Features: 1425a937b6aaSMarkus Armbruster# 14269fb49daaSMarkus Armbruster# @unstable: This command is experimental. 14279fb49daaSMarkus Armbruster# 142848685a8eSMarkus Armbruster# Since: 2.8 142948685a8eSMarkus Armbruster# 143048685a8eSMarkus Armbruster# Example: 143148685a8eSMarkus Armbruster# 143248685a8eSMarkus Armbruster# -> { "execute": "x-colo-lost-heartbeat" } 143348685a8eSMarkus Armbruster# <- { "return": {} } 143448685a8eSMarkus Armbruster## 14359fb49daaSMarkus Armbruster{ 'command': 'x-colo-lost-heartbeat', 143651e47cf8SVladimir Sementsov-Ogievskiy 'features': [ 'unstable' ], 143751e47cf8SVladimir Sementsov-Ogievskiy 'if': 'CONFIG_REPLICATION' } 143848685a8eSMarkus Armbruster 143948685a8eSMarkus Armbruster## 144048685a8eSMarkus Armbruster# @migrate_cancel: 144148685a8eSMarkus Armbruster# 144248685a8eSMarkus Armbruster# Cancel the current executing migration process. 144348685a8eSMarkus Armbruster# 144448685a8eSMarkus Armbruster# Returns: nothing on success 144548685a8eSMarkus Armbruster# 1446a937b6aaSMarkus Armbruster# Notes: This command succeeds even if there is no migration process 1447a937b6aaSMarkus Armbruster# running. 144848685a8eSMarkus Armbruster# 14499bc6e893SMarkus Armbruster# Since: 0.14 145048685a8eSMarkus Armbruster# 145148685a8eSMarkus Armbruster# Example: 145248685a8eSMarkus Armbruster# 145348685a8eSMarkus Armbruster# -> { "execute": "migrate_cancel" } 145448685a8eSMarkus Armbruster# <- { "return": {} } 145548685a8eSMarkus Armbruster## 145648685a8eSMarkus Armbruster{ 'command': 'migrate_cancel' } 145748685a8eSMarkus Armbruster 145848685a8eSMarkus Armbruster## 145989cfc02cSDr. David Alan Gilbert# @migrate-continue: 146089cfc02cSDr. David Alan Gilbert# 146189cfc02cSDr. David Alan Gilbert# Continue migration when it's in a paused state. 146289cfc02cSDr. David Alan Gilbert# 146389cfc02cSDr. David Alan Gilbert# @state: The state the migration is currently expected to be in 146489cfc02cSDr. David Alan Gilbert# 146589cfc02cSDr. David Alan Gilbert# Returns: nothing on success 14664ae65a52SAndrea Bolognani# 146789cfc02cSDr. David Alan Gilbert# Since: 2.11 14684ae65a52SAndrea Bolognani# 146989cfc02cSDr. David Alan Gilbert# Example: 147089cfc02cSDr. David Alan Gilbert# 147189cfc02cSDr. David Alan Gilbert# -> { "execute": "migrate-continue" , "arguments": 147289cfc02cSDr. David Alan Gilbert# { "state": "pre-switchover" } } 147389cfc02cSDr. David Alan Gilbert# <- { "return": {} } 147489cfc02cSDr. David Alan Gilbert## 147589cfc02cSDr. David Alan Gilbert{ 'command': 'migrate-continue', 'data': {'state': 'MigrationStatus'} } 147689cfc02cSDr. David Alan Gilbert 147789cfc02cSDr. David Alan Gilbert## 147848685a8eSMarkus Armbruster# @migrate: 147948685a8eSMarkus Armbruster# 148048685a8eSMarkus Armbruster# Migrates the current running guest to another Virtual Machine. 148148685a8eSMarkus Armbruster# 148248685a8eSMarkus Armbruster# @uri: the Uniform Resource Identifier of the destination VM 148348685a8eSMarkus Armbruster# 148448685a8eSMarkus Armbruster# @blk: do block migration (full disk copy) 148548685a8eSMarkus Armbruster# 148648685a8eSMarkus Armbruster# @inc: incremental disk copy migration 148748685a8eSMarkus Armbruster# 1488a937b6aaSMarkus Armbruster# @detach: this argument exists only for compatibility reasons and is 1489a937b6aaSMarkus Armbruster# ignored by QEMU 149048685a8eSMarkus Armbruster# 149151f63ec7SPeter Maydell# @resume: resume one paused migration, default "off". (since 3.0) 14927a4da28bSPeter Xu# 149348685a8eSMarkus Armbruster# Returns: nothing on success 149448685a8eSMarkus Armbruster# 14959bc6e893SMarkus Armbruster# Since: 0.14 149648685a8eSMarkus Armbruster# 149748685a8eSMarkus Armbruster# Notes: 149848685a8eSMarkus Armbruster# 1499a937b6aaSMarkus Armbruster# 1. The 'query-migrate' command should be used to check migration's 1500a937b6aaSMarkus Armbruster# progress and final result (this information is provided by the 1501a937b6aaSMarkus Armbruster# 'status' member) 150248685a8eSMarkus Armbruster# 150348685a8eSMarkus Armbruster# 2. All boolean arguments default to false 150448685a8eSMarkus Armbruster# 1505a937b6aaSMarkus Armbruster# 3. The user Monitor's "detach" argument is invalid in QMP and should 1506a937b6aaSMarkus Armbruster# not be used 150748685a8eSMarkus Armbruster# 150848685a8eSMarkus Armbruster# Example: 150948685a8eSMarkus Armbruster# 151048685a8eSMarkus Armbruster# -> { "execute": "migrate", "arguments": { "uri": "tcp:0:4446" } } 151148685a8eSMarkus Armbruster# <- { "return": {} } 151248685a8eSMarkus Armbruster## 151348685a8eSMarkus Armbruster{ 'command': 'migrate', 15147a4da28bSPeter Xu 'data': {'uri': 'str', '*blk': 'bool', '*inc': 'bool', 15157a4da28bSPeter Xu '*detach': 'bool', '*resume': 'bool' } } 151648685a8eSMarkus Armbruster 151748685a8eSMarkus Armbruster## 151848685a8eSMarkus Armbruster# @migrate-incoming: 151948685a8eSMarkus Armbruster# 1520a937b6aaSMarkus Armbruster# Start an incoming migration, the qemu must have been started with 1521a937b6aaSMarkus Armbruster# -incoming defer 152248685a8eSMarkus Armbruster# 152348685a8eSMarkus Armbruster# @uri: The Uniform Resource Identifier identifying the source or 152448685a8eSMarkus Armbruster# address to listen on 152548685a8eSMarkus Armbruster# 152648685a8eSMarkus Armbruster# Returns: nothing on success 152748685a8eSMarkus Armbruster# 152848685a8eSMarkus Armbruster# Since: 2.3 152948685a8eSMarkus Armbruster# 153048685a8eSMarkus Armbruster# Notes: 153148685a8eSMarkus Armbruster# 1532a937b6aaSMarkus Armbruster# 1. It's a bad idea to use a string for the uri, but it needs 1533a937b6aaSMarkus Armbruster# to stay compatible with -incoming and the format of the uri 1534a937b6aaSMarkus Armbruster# is already exposed above libvirt. 153548685a8eSMarkus Armbruster# 1536a937b6aaSMarkus Armbruster# 2. QEMU must be started with -incoming defer to allow 1537a937b6aaSMarkus Armbruster# migrate-incoming to be used. 153848685a8eSMarkus Armbruster# 153948685a8eSMarkus Armbruster# 3. The uri format is the same as for -incoming 154048685a8eSMarkus Armbruster# 154148685a8eSMarkus Armbruster# Example: 154248685a8eSMarkus Armbruster# 154348685a8eSMarkus Armbruster# -> { "execute": "migrate-incoming", 154448685a8eSMarkus Armbruster# "arguments": { "uri": "tcp::4446" } } 154548685a8eSMarkus Armbruster# <- { "return": {} } 154648685a8eSMarkus Armbruster## 154748685a8eSMarkus Armbruster{ 'command': 'migrate-incoming', 'data': {'uri': 'str' } } 154848685a8eSMarkus Armbruster 154948685a8eSMarkus Armbruster## 155048685a8eSMarkus Armbruster# @xen-save-devices-state: 155148685a8eSMarkus Armbruster# 1552a937b6aaSMarkus Armbruster# Save the state of all devices to file. The RAM and the block 1553a937b6aaSMarkus Armbruster# devices of the VM are not saved by this command. 155448685a8eSMarkus Armbruster# 155548685a8eSMarkus Armbruster# @filename: the file to save the state of the devices to as binary 1556a937b6aaSMarkus Armbruster# data. See xen-save-devices-state.txt for a description of the 1557a937b6aaSMarkus Armbruster# binary format. 155848685a8eSMarkus Armbruster# 1559a937b6aaSMarkus Armbruster# @live: Optional argument to ask QEMU to treat this command as part 1560a937b6aaSMarkus Armbruster# of a live migration. Default to true. (since 2.11) 15615d6c599fSAnthony PERARD# 156248685a8eSMarkus Armbruster# Returns: Nothing on success 156348685a8eSMarkus Armbruster# 156448685a8eSMarkus Armbruster# Since: 1.1 156548685a8eSMarkus Armbruster# 156648685a8eSMarkus Armbruster# Example: 156748685a8eSMarkus Armbruster# 156848685a8eSMarkus Armbruster# -> { "execute": "xen-save-devices-state", 156948685a8eSMarkus Armbruster# "arguments": { "filename": "/tmp/save" } } 157048685a8eSMarkus Armbruster# <- { "return": {} } 157148685a8eSMarkus Armbruster## 15725d6c599fSAnthony PERARD{ 'command': 'xen-save-devices-state', 15735d6c599fSAnthony PERARD 'data': {'filename': 'str', '*live':'bool' } } 157448685a8eSMarkus Armbruster 157548685a8eSMarkus Armbruster## 157628af9ba2SPhilippe Mathieu-Daudé# @xen-set-global-dirty-log: 157728af9ba2SPhilippe Mathieu-Daudé# 157828af9ba2SPhilippe Mathieu-Daudé# Enable or disable the global dirty log mode. 157928af9ba2SPhilippe Mathieu-Daudé# 158028af9ba2SPhilippe Mathieu-Daudé# @enable: true to enable, false to disable. 158128af9ba2SPhilippe Mathieu-Daudé# 158228af9ba2SPhilippe Mathieu-Daudé# Returns: nothing 158328af9ba2SPhilippe Mathieu-Daudé# 158428af9ba2SPhilippe Mathieu-Daudé# Since: 1.3 158528af9ba2SPhilippe Mathieu-Daudé# 158628af9ba2SPhilippe Mathieu-Daudé# Example: 158728af9ba2SPhilippe Mathieu-Daudé# 158828af9ba2SPhilippe Mathieu-Daudé# -> { "execute": "xen-set-global-dirty-log", 158928af9ba2SPhilippe Mathieu-Daudé# "arguments": { "enable": true } } 159028af9ba2SPhilippe Mathieu-Daudé# <- { "return": {} } 159128af9ba2SPhilippe Mathieu-Daudé## 159228af9ba2SPhilippe Mathieu-Daudé{ 'command': 'xen-set-global-dirty-log', 'data': { 'enable': 'bool' } } 159328af9ba2SPhilippe Mathieu-Daudé 159428af9ba2SPhilippe Mathieu-Daudé## 159528af9ba2SPhilippe Mathieu-Daudé# @xen-load-devices-state: 159628af9ba2SPhilippe Mathieu-Daudé# 1597a937b6aaSMarkus Armbruster# Load the state of all devices from file. The RAM and the block 1598a937b6aaSMarkus Armbruster# devices of the VM are not loaded by this command. 159928af9ba2SPhilippe Mathieu-Daudé# 160028af9ba2SPhilippe Mathieu-Daudé# @filename: the file to load the state of the devices from as binary 1601a937b6aaSMarkus Armbruster# data. See xen-save-devices-state.txt for a description of the 1602a937b6aaSMarkus Armbruster# binary format. 160328af9ba2SPhilippe Mathieu-Daudé# 160428af9ba2SPhilippe Mathieu-Daudé# Since: 2.7 160528af9ba2SPhilippe Mathieu-Daudé# 160628af9ba2SPhilippe Mathieu-Daudé# Example: 160728af9ba2SPhilippe Mathieu-Daudé# 160828af9ba2SPhilippe Mathieu-Daudé# -> { "execute": "xen-load-devices-state", 160928af9ba2SPhilippe Mathieu-Daudé# "arguments": { "filename": "/tmp/resume" } } 161028af9ba2SPhilippe Mathieu-Daudé# <- { "return": {} } 161128af9ba2SPhilippe Mathieu-Daudé## 161228af9ba2SPhilippe Mathieu-Daudé{ 'command': 'xen-load-devices-state', 'data': {'filename': 'str'} } 161328af9ba2SPhilippe Mathieu-Daudé 161428af9ba2SPhilippe Mathieu-Daudé## 161548685a8eSMarkus Armbruster# @xen-set-replication: 161648685a8eSMarkus Armbruster# 161748685a8eSMarkus Armbruster# Enable or disable replication. 161848685a8eSMarkus Armbruster# 161948685a8eSMarkus Armbruster# @enable: true to enable, false to disable. 162048685a8eSMarkus Armbruster# 162148685a8eSMarkus Armbruster# @primary: true for primary or false for secondary. 162248685a8eSMarkus Armbruster# 162348685a8eSMarkus Armbruster# @failover: true to do failover, false to stop. but cannot be 162448685a8eSMarkus Armbruster# specified if 'enable' is true. default value is false. 162548685a8eSMarkus Armbruster# 162648685a8eSMarkus Armbruster# Returns: nothing. 162748685a8eSMarkus Armbruster# 162848685a8eSMarkus Armbruster# Example: 162948685a8eSMarkus Armbruster# 163048685a8eSMarkus Armbruster# -> { "execute": "xen-set-replication", 163148685a8eSMarkus Armbruster# "arguments": {"enable": true, "primary": false} } 163248685a8eSMarkus Armbruster# <- { "return": {} } 163348685a8eSMarkus Armbruster# 163448685a8eSMarkus Armbruster# Since: 2.9 163548685a8eSMarkus Armbruster## 163648685a8eSMarkus Armbruster{ 'command': 'xen-set-replication', 1637335d10cdSMarc-André Lureau 'data': { 'enable': 'bool', 'primary': 'bool', '*failover': 'bool' }, 16388a9f1e1dSMarc-André Lureau 'if': 'CONFIG_REPLICATION' } 163948685a8eSMarkus Armbruster 164048685a8eSMarkus Armbruster## 164148685a8eSMarkus Armbruster# @ReplicationStatus: 164248685a8eSMarkus Armbruster# 164348685a8eSMarkus Armbruster# The result format for 'query-xen-replication-status'. 164448685a8eSMarkus Armbruster# 164548685a8eSMarkus Armbruster# @error: true if an error happened, false if replication is normal. 164648685a8eSMarkus Armbruster# 1647a937b6aaSMarkus Armbruster# @desc: the human readable error description string, when @error is 1648a937b6aaSMarkus Armbruster# 'true'. 164948685a8eSMarkus Armbruster# 165048685a8eSMarkus Armbruster# Since: 2.9 165148685a8eSMarkus Armbruster## 165248685a8eSMarkus Armbruster{ 'struct': 'ReplicationStatus', 1653335d10cdSMarc-André Lureau 'data': { 'error': 'bool', '*desc': 'str' }, 16548a9f1e1dSMarc-André Lureau 'if': 'CONFIG_REPLICATION' } 165548685a8eSMarkus Armbruster 165648685a8eSMarkus Armbruster## 165748685a8eSMarkus Armbruster# @query-xen-replication-status: 165848685a8eSMarkus Armbruster# 165948685a8eSMarkus Armbruster# Query replication status while the vm is running. 166048685a8eSMarkus Armbruster# 1661f4347129SAndrea Bolognani# Returns: A @ReplicationStatus object showing the status. 166248685a8eSMarkus Armbruster# 166348685a8eSMarkus Armbruster# Example: 166448685a8eSMarkus Armbruster# 166548685a8eSMarkus Armbruster# -> { "execute": "query-xen-replication-status" } 166648685a8eSMarkus Armbruster# <- { "return": { "error": false } } 166748685a8eSMarkus Armbruster# 166848685a8eSMarkus Armbruster# Since: 2.9 166948685a8eSMarkus Armbruster## 167048685a8eSMarkus Armbruster{ 'command': 'query-xen-replication-status', 1671335d10cdSMarc-André Lureau 'returns': 'ReplicationStatus', 16728a9f1e1dSMarc-André Lureau 'if': 'CONFIG_REPLICATION' } 167348685a8eSMarkus Armbruster 167448685a8eSMarkus Armbruster## 167548685a8eSMarkus Armbruster# @xen-colo-do-checkpoint: 167648685a8eSMarkus Armbruster# 167748685a8eSMarkus Armbruster# Xen uses this command to notify replication to trigger a checkpoint. 167848685a8eSMarkus Armbruster# 167948685a8eSMarkus Armbruster# Returns: nothing. 168048685a8eSMarkus Armbruster# 168148685a8eSMarkus Armbruster# Example: 168248685a8eSMarkus Armbruster# 168348685a8eSMarkus Armbruster# -> { "execute": "xen-colo-do-checkpoint" } 168448685a8eSMarkus Armbruster# <- { "return": {} } 168548685a8eSMarkus Armbruster# 168648685a8eSMarkus Armbruster# Since: 2.9 168748685a8eSMarkus Armbruster## 1688335d10cdSMarc-André Lureau{ 'command': 'xen-colo-do-checkpoint', 16898a9f1e1dSMarc-André Lureau 'if': 'CONFIG_REPLICATION' } 169002affd41SPeter Xu 169102affd41SPeter Xu## 1692f56c0065SZhang Chen# @COLOStatus: 1693f56c0065SZhang Chen# 1694f56c0065SZhang Chen# The result format for 'query-colo-status'. 1695f56c0065SZhang Chen# 1696a937b6aaSMarkus Armbruster# @mode: COLO running mode. If COLO is running, this field will 1697a937b6aaSMarkus Armbruster# return 'primary' or 'secondary'. 1698f56c0065SZhang Chen# 16995cc8f9ebSZhang Chen# @last-mode: COLO last running mode. If COLO is running, this field 1700a937b6aaSMarkus Armbruster# will return same like mode field, after failover we can use this 1701a937b6aaSMarkus Armbruster# field to get last colo mode. (since 4.0) 17025ed0decaSZhang Chen# 1703f56c0065SZhang Chen# @reason: describes the reason for the COLO exit. 1704f56c0065SZhang Chen# 1705ea3b23e5SZhang Chen# Since: 3.1 1706f56c0065SZhang Chen## 1707f56c0065SZhang Chen{ 'struct': 'COLOStatus', 17085cc8f9ebSZhang Chen 'data': { 'mode': 'COLOMode', 'last-mode': 'COLOMode', 170951e47cf8SVladimir Sementsov-Ogievskiy 'reason': 'COLOExitReason' }, 171051e47cf8SVladimir Sementsov-Ogievskiy 'if': 'CONFIG_REPLICATION' } 1711f56c0065SZhang Chen 1712f56c0065SZhang Chen## 1713f56c0065SZhang Chen# @query-colo-status: 1714f56c0065SZhang Chen# 1715f56c0065SZhang Chen# Query COLO status while the vm is running. 1716f56c0065SZhang Chen# 1717f56c0065SZhang Chen# Returns: A @COLOStatus object showing the status. 1718f56c0065SZhang Chen# 1719f56c0065SZhang Chen# Example: 1720f56c0065SZhang Chen# 1721f56c0065SZhang Chen# -> { "execute": "query-colo-status" } 172251ec294dSVictor Toso# <- { "return": { "mode": "primary", "last-mode": "none", "reason": "request" } } 1723f56c0065SZhang Chen# 1724ea3b23e5SZhang Chen# Since: 3.1 1725f56c0065SZhang Chen## 1726f56c0065SZhang Chen{ 'command': 'query-colo-status', 172751e47cf8SVladimir Sementsov-Ogievskiy 'returns': 'COLOStatus', 172851e47cf8SVladimir Sementsov-Ogievskiy 'if': 'CONFIG_REPLICATION' } 1729f56c0065SZhang Chen 1730f56c0065SZhang Chen## 173102affd41SPeter Xu# @migrate-recover: 173202affd41SPeter Xu# 173302affd41SPeter Xu# Provide a recovery migration stream URI. 173402affd41SPeter Xu# 173502affd41SPeter Xu# @uri: the URI to be used for the recovery of migration stream. 173602affd41SPeter Xu# 173702affd41SPeter Xu# Returns: nothing. 173802affd41SPeter Xu# 173902affd41SPeter Xu# Example: 174002affd41SPeter Xu# 174102affd41SPeter Xu# -> { "execute": "migrate-recover", 174202affd41SPeter Xu# "arguments": { "uri": "tcp:192.168.1.200:12345" } } 174302affd41SPeter Xu# <- { "return": {} } 174402affd41SPeter Xu# 174551f63ec7SPeter Maydell# Since: 3.0 174602affd41SPeter Xu## 1747b0ddeba2SMarc-André Lureau{ 'command': 'migrate-recover', 1748b0ddeba2SMarc-André Lureau 'data': { 'uri': 'str' }, 174902affd41SPeter Xu 'allow-oob': true } 1750bfbf89c2SPeter Xu 1751bfbf89c2SPeter Xu## 1752bfbf89c2SPeter Xu# @migrate-pause: 1753bfbf89c2SPeter Xu# 1754bfbf89c2SPeter Xu# Pause a migration. Currently it only supports postcopy. 1755bfbf89c2SPeter Xu# 1756bfbf89c2SPeter Xu# Returns: nothing. 1757bfbf89c2SPeter Xu# 1758bfbf89c2SPeter Xu# Example: 1759bfbf89c2SPeter Xu# 1760bfbf89c2SPeter Xu# -> { "execute": "migrate-pause" } 1761bfbf89c2SPeter Xu# <- { "return": {} } 1762bfbf89c2SPeter Xu# 176351f63ec7SPeter Maydell# Since: 3.0 1764bfbf89c2SPeter Xu## 1765bfbf89c2SPeter Xu{ 'command': 'migrate-pause', 'allow-oob': true } 1766d328e6f3SJens Freimann 1767d328e6f3SJens Freimann## 1768d328e6f3SJens Freimann# @UNPLUG_PRIMARY: 1769d328e6f3SJens Freimann# 1770d328e6f3SJens Freimann# Emitted from source side of a migration when migration state is 1771a937b6aaSMarkus Armbruster# WAIT_UNPLUG. Device was unplugged by guest operating system. Device 1772a937b6aaSMarkus Armbruster# resources in QEMU are kept on standby to be able to re-plug it in 1773a937b6aaSMarkus Armbruster# case of migration failure. 1774d328e6f3SJens Freimann# 1775d328e6f3SJens Freimann# @device-id: QEMU device id of the unplugged device 1776d328e6f3SJens Freimann# 1777d328e6f3SJens Freimann# Since: 4.2 1778d328e6f3SJens Freimann# 1779d328e6f3SJens Freimann# Example: 17804ae65a52SAndrea Bolognani# 17810df5e9a3SVictor Toso# <- { "event": "UNPLUG_PRIMARY", 17820df5e9a3SVictor Toso# "data": { "device-id": "hostdev0" }, 17830df5e9a3SVictor Toso# "timestamp": { "seconds": 1265044230, "microseconds": 450486 } } 1784d328e6f3SJens Freimann## 1785d328e6f3SJens Freimann{ 'event': 'UNPLUG_PRIMARY', 1786d328e6f3SJens Freimann 'data': { 'device-id': 'str' } } 17877df3aa30SChuan Zheng 17887df3aa30SChuan Zheng## 178971864eadSHyman Huang(黄勇)# @DirtyRateVcpu: 179071864eadSHyman Huang(黄勇)# 179171864eadSHyman Huang(黄勇)# Dirty rate of vcpu. 179271864eadSHyman Huang(黄勇)# 179371864eadSHyman Huang(黄勇)# @id: vcpu index. 179471864eadSHyman Huang(黄勇)# 179571864eadSHyman Huang(黄勇)# @dirty-rate: dirty rate. 179671864eadSHyman Huang(黄勇)# 1797f78d4ed7SHyman Huang(黄勇)# Since: 6.2 179871864eadSHyman Huang(黄勇)## 179971864eadSHyman Huang(黄勇){ 'struct': 'DirtyRateVcpu', 180071864eadSHyman Huang(黄勇) 'data': { 'id': 'int', 'dirty-rate': 'int64' } } 180171864eadSHyman Huang(黄勇) 180271864eadSHyman Huang(黄勇)## 18037df3aa30SChuan Zheng# @DirtyRateStatus: 18047df3aa30SChuan Zheng# 18055034e3d4SAndrei Gudkov# Dirty page rate measurement status. 18067df3aa30SChuan Zheng# 18075034e3d4SAndrei Gudkov# @unstarted: measuring thread has not been started yet 18087df3aa30SChuan Zheng# 18095034e3d4SAndrei Gudkov# @measuring: measuring thread is running 18107df3aa30SChuan Zheng# 18115034e3d4SAndrei Gudkov# @measured: dirty page rate is measured and the results are available 18127df3aa30SChuan Zheng# 18137df3aa30SChuan Zheng# Since: 5.2 18147df3aa30SChuan Zheng## 18157df3aa30SChuan Zheng{ 'enum': 'DirtyRateStatus', 18167df3aa30SChuan Zheng 'data': [ 'unstarted', 'measuring', 'measured'] } 18174c437254SChuan Zheng 18184c437254SChuan Zheng## 181971864eadSHyman Huang(黄勇)# @DirtyRateMeasureMode: 182071864eadSHyman Huang(黄勇)# 18215034e3d4SAndrei Gudkov# Method used to measure dirty page rate. Differences between 18225034e3d4SAndrei Gudkov# available methods are explained in @calc-dirty-rate. 182371864eadSHyman Huang(黄勇)# 18245034e3d4SAndrei Gudkov# @page-sampling: use page sampling 182571864eadSHyman Huang(黄勇)# 18265034e3d4SAndrei Gudkov# @dirty-ring: use dirty ring 1827826b8bc8SHyman Huang(黄勇)# 18285034e3d4SAndrei Gudkov# @dirty-bitmap: use dirty bitmap 182971864eadSHyman Huang(黄勇)# 1830f78d4ed7SHyman Huang(黄勇)# Since: 6.2 183171864eadSHyman Huang(黄勇)## 183271864eadSHyman Huang(黄勇){ 'enum': 'DirtyRateMeasureMode', 1833826b8bc8SHyman Huang(黄勇) 'data': ['page-sampling', 'dirty-ring', 'dirty-bitmap'] } 183471864eadSHyman Huang(黄勇) 183571864eadSHyman Huang(黄勇)## 18364c437254SChuan Zheng# @DirtyRateInfo: 18374c437254SChuan Zheng# 18385034e3d4SAndrei Gudkov# Information about measured dirty page rate. 18394c437254SChuan Zheng# 1840a937b6aaSMarkus Armbruster# @dirty-rate: an estimate of the dirty page rate of the VM in units 18415034e3d4SAndrei Gudkov# of MiB/s. Value is present only when @status is 'measured'. 18424c437254SChuan Zheng# 18435034e3d4SAndrei Gudkov# @status: current status of dirty page rate measurements 18444c437254SChuan Zheng# 18454c437254SChuan Zheng# @start-time: start time in units of second for calculation 18464c437254SChuan Zheng# 18475034e3d4SAndrei Gudkov# @calc-time: time period for which dirty page rate was measured 18485034e3d4SAndrei Gudkov# (in seconds) 18494c437254SChuan Zheng# 18505034e3d4SAndrei Gudkov# @sample-pages: number of sampled pages per GiB of guest memory. 18515034e3d4SAndrei Gudkov# Valid only in page-sampling mode (Since 6.1) 18527afa08cdSHyman Huang(黄勇)# 18535034e3d4SAndrei Gudkov# @mode: mode that was used to measure dirty page rate (Since 6.2) 18540e21bf24SHyman Huang(黄勇)# 18555034e3d4SAndrei Gudkov# @vcpu-dirty-rate: dirty rate for each vCPU if dirty-ring mode was 1856a937b6aaSMarkus Armbruster# specified (Since 6.2) 18570e21bf24SHyman Huang(黄勇)# 18584c437254SChuan Zheng# Since: 5.2 18594c437254SChuan Zheng## 18604c437254SChuan Zheng{ 'struct': 'DirtyRateInfo', 1861b1a859cfSChuan Zheng 'data': {'*dirty-rate': 'int64', 18624c437254SChuan Zheng 'status': 'DirtyRateStatus', 18634c437254SChuan Zheng 'start-time': 'int64', 18647afa08cdSHyman Huang(黄勇) 'calc-time': 'int64', 18650e21bf24SHyman Huang(黄勇) 'sample-pages': 'uint64', 18660e21bf24SHyman Huang(黄勇) 'mode': 'DirtyRateMeasureMode', 18670e21bf24SHyman Huang(黄勇) '*vcpu-dirty-rate': [ 'DirtyRateVcpu' ] } } 18684c437254SChuan Zheng 18694c437254SChuan Zheng## 18704c437254SChuan Zheng# @calc-dirty-rate: 18714c437254SChuan Zheng# 18725034e3d4SAndrei Gudkov# Start measuring dirty page rate of the VM. Results can be retrieved 18735034e3d4SAndrei Gudkov# with @query-dirty-rate after measurements are completed. 18744c437254SChuan Zheng# 18755034e3d4SAndrei Gudkov# Dirty page rate is the number of pages changed in a given time 18765034e3d4SAndrei Gudkov# period expressed in MiB/s. The following methods of calculation are 18775034e3d4SAndrei Gudkov# available: 18784c437254SChuan Zheng# 18795034e3d4SAndrei Gudkov# 1. In page sampling mode, a random subset of pages are selected and 18805034e3d4SAndrei Gudkov# hashed twice: once at the beginning of measurement time period, 18815034e3d4SAndrei Gudkov# and once again at the end. If two hashes for some page are 18825034e3d4SAndrei Gudkov# different, the page is counted as changed. Since this method 18835034e3d4SAndrei Gudkov# relies on sampling and hashing, calculated dirty page rate is 18845034e3d4SAndrei Gudkov# only an estimate of its true value. Increasing @sample-pages 18855034e3d4SAndrei Gudkov# improves estimation quality at the cost of higher computational 18865034e3d4SAndrei Gudkov# overhead. 18877afa08cdSHyman Huang(黄勇)# 18885034e3d4SAndrei Gudkov# 2. Dirty bitmap mode captures writes to memory (for example by 18895034e3d4SAndrei Gudkov# temporarily revoking write access to all pages) and counting page 18905034e3d4SAndrei Gudkov# faults. Information about modified pages is collected into a 18915034e3d4SAndrei Gudkov# bitmap, where each bit corresponds to one guest page. This mode 18925034e3d4SAndrei Gudkov# requires that KVM accelerator property "dirty-ring-size" is *not* 18935034e3d4SAndrei Gudkov# set. 18945034e3d4SAndrei Gudkov# 18955034e3d4SAndrei Gudkov# 3. Dirty ring mode is similar to dirty bitmap mode, but the 18965034e3d4SAndrei Gudkov# information about modified pages is collected into ring buffer. 18975034e3d4SAndrei Gudkov# This mode tracks page modification per each vCPU separately. It 18985034e3d4SAndrei Gudkov# requires that KVM accelerator property "dirty-ring-size" is set. 18995034e3d4SAndrei Gudkov# 19005034e3d4SAndrei Gudkov# @calc-time: time period in units of second for which dirty page rate 19015034e3d4SAndrei Gudkov# is calculated. Note that larger @calc-time values will 19025034e3d4SAndrei Gudkov# typically result in smaller dirty page rates because page 19035034e3d4SAndrei Gudkov# dirtying is a one-time event. Once some page is counted as 19045034e3d4SAndrei Gudkov# dirty during @calc-time period, further writes to this page will 19055034e3d4SAndrei Gudkov# not increase dirty page rate anymore. 19065034e3d4SAndrei Gudkov# 19075034e3d4SAndrei Gudkov# @sample-pages: number of sampled pages per each GiB of guest memory. 19085034e3d4SAndrei Gudkov# Default value is 512. For 4KiB guest pages this corresponds to 19095034e3d4SAndrei Gudkov# sampling ratio of 0.2%. This argument is used only in page 19105034e3d4SAndrei Gudkov# sampling mode. (Since 6.1) 19115034e3d4SAndrei Gudkov# 19125034e3d4SAndrei Gudkov# @mode: mechanism for tracking dirty pages. Default value is 19135034e3d4SAndrei Gudkov# 'page-sampling'. Others are 'dirty-bitmap' and 'dirty-ring'. 19145034e3d4SAndrei Gudkov# (Since 6.1) 19150e21bf24SHyman Huang(黄勇)# 19164c437254SChuan Zheng# Since: 5.2 19174c437254SChuan Zheng# 19184c437254SChuan Zheng# Example: 19194ae65a52SAndrea Bolognani# 192037fa48a4SMarkus Armbruster# -> {"execute": "calc-dirty-rate", "arguments": {"calc-time": 1, 19217afa08cdSHyman Huang(黄勇)# 'sample-pages': 512} } 192237fa48a4SMarkus Armbruster# <- { "return": {} } 19234c437254SChuan Zheng## 19247afa08cdSHyman Huang(黄勇){ 'command': 'calc-dirty-rate', 'data': {'calc-time': 'int64', 19250e21bf24SHyman Huang(黄勇) '*sample-pages': 'int', 19260e21bf24SHyman Huang(黄勇) '*mode': 'DirtyRateMeasureMode'} } 19274c437254SChuan Zheng 19284c437254SChuan Zheng## 19294c437254SChuan Zheng# @query-dirty-rate: 19304c437254SChuan Zheng# 19315034e3d4SAndrei Gudkov# Query results of the most recent invocation of @calc-dirty-rate. 19324c437254SChuan Zheng# 19334c437254SChuan Zheng# Since: 5.2 19345034e3d4SAndrei Gudkov# 19355034e3d4SAndrei Gudkov# Examples: 19365034e3d4SAndrei Gudkov# 19375034e3d4SAndrei Gudkov# 1. Measurement is in progress: 19385034e3d4SAndrei Gudkov# 19395034e3d4SAndrei Gudkov# <- {"status": "measuring", "sample-pages": 512, 19405034e3d4SAndrei Gudkov# "mode": "page-sampling", "start-time": 3665220, "calc-time": 10} 19415034e3d4SAndrei Gudkov# 19425034e3d4SAndrei Gudkov# 2. Measurement has been completed: 19435034e3d4SAndrei Gudkov# 19445034e3d4SAndrei Gudkov# <- {"status": "measured", "sample-pages": 512, "dirty-rate": 108, 19455034e3d4SAndrei Gudkov# "mode": "page-sampling", "start-time": 3665220, "calc-time": 10} 19464c437254SChuan Zheng## 19474c437254SChuan Zheng{ 'command': 'query-dirty-rate', 'returns': 'DirtyRateInfo' } 19480f0d83a4SDaniel P. Berrangé 19490f0d83a4SDaniel P. Berrangé## 1950f3b2e38cSHyman Huang(黄勇)# @DirtyLimitInfo: 1951f3b2e38cSHyman Huang(黄勇)# 1952f3b2e38cSHyman Huang(黄勇)# Dirty page rate limit information of a virtual CPU. 1953f3b2e38cSHyman Huang(黄勇)# 1954f3b2e38cSHyman Huang(黄勇)# @cpu-index: index of a virtual CPU. 1955f3b2e38cSHyman Huang(黄勇)# 1956f3b2e38cSHyman Huang(黄勇)# @limit-rate: upper limit of dirty page rate (MB/s) for a virtual 1957f3b2e38cSHyman Huang(黄勇)# CPU, 0 means unlimited. 1958f3b2e38cSHyman Huang(黄勇)# 1959f3b2e38cSHyman Huang(黄勇)# @current-rate: current dirty page rate (MB/s) for a virtual CPU. 1960f3b2e38cSHyman Huang(黄勇)# 1961f3b2e38cSHyman Huang(黄勇)# Since: 7.1 1962f3b2e38cSHyman Huang(黄勇)## 1963f3b2e38cSHyman Huang(黄勇){ 'struct': 'DirtyLimitInfo', 1964f3b2e38cSHyman Huang(黄勇) 'data': { 'cpu-index': 'int', 1965f3b2e38cSHyman Huang(黄勇) 'limit-rate': 'uint64', 1966f3b2e38cSHyman Huang(黄勇) 'current-rate': 'uint64' } } 1967f3b2e38cSHyman Huang(黄勇) 1968f3b2e38cSHyman Huang(黄勇)## 1969f3b2e38cSHyman Huang(黄勇)# @set-vcpu-dirty-limit: 1970f3b2e38cSHyman Huang(黄勇)# 1971f3b2e38cSHyman Huang(黄勇)# Set the upper limit of dirty page rate for virtual CPUs. 1972f3b2e38cSHyman Huang(黄勇)# 1973a937b6aaSMarkus Armbruster# Requires KVM with accelerator property "dirty-ring-size" set. A 1974a937b6aaSMarkus Armbruster# virtual CPU's dirty page rate is a measure of its memory load. To 1975a937b6aaSMarkus Armbruster# observe dirty page rates, use @calc-dirty-rate. 1976f3b2e38cSHyman Huang(黄勇)# 1977f3b2e38cSHyman Huang(黄勇)# @cpu-index: index of a virtual CPU, default is all. 1978f3b2e38cSHyman Huang(黄勇)# 1979f3b2e38cSHyman Huang(黄勇)# @dirty-rate: upper limit of dirty page rate (MB/s) for virtual CPUs. 1980f3b2e38cSHyman Huang(黄勇)# 1981f3b2e38cSHyman Huang(黄勇)# Since: 7.1 1982f3b2e38cSHyman Huang(黄勇)# 1983f3b2e38cSHyman Huang(黄勇)# Example: 198437fa48a4SMarkus Armbruster# 198537fa48a4SMarkus Armbruster# -> {"execute": "set-vcpu-dirty-limit"} 1986f3b2e38cSHyman Huang(黄勇)# "arguments": { "dirty-rate": 200, 1987f3b2e38cSHyman Huang(黄勇)# "cpu-index": 1 } } 198837fa48a4SMarkus Armbruster# <- { "return": {} } 1989f3b2e38cSHyman Huang(黄勇)## 1990f3b2e38cSHyman Huang(黄勇){ 'command': 'set-vcpu-dirty-limit', 1991f3b2e38cSHyman Huang(黄勇) 'data': { '*cpu-index': 'int', 1992f3b2e38cSHyman Huang(黄勇) 'dirty-rate': 'uint64' } } 1993f3b2e38cSHyman Huang(黄勇) 1994f3b2e38cSHyman Huang(黄勇)## 1995f3b2e38cSHyman Huang(黄勇)# @cancel-vcpu-dirty-limit: 1996f3b2e38cSHyman Huang(黄勇)# 1997f3b2e38cSHyman Huang(黄勇)# Cancel the upper limit of dirty page rate for virtual CPUs. 1998f3b2e38cSHyman Huang(黄勇)# 1999f3b2e38cSHyman Huang(黄勇)# Cancel the dirty page limit for the vCPU which has been set with 2000f3b2e38cSHyman Huang(黄勇)# set-vcpu-dirty-limit command. Note that this command requires 2001f3b2e38cSHyman Huang(黄勇)# support from dirty ring, same as the "set-vcpu-dirty-limit". 2002f3b2e38cSHyman Huang(黄勇)# 2003f3b2e38cSHyman Huang(黄勇)# @cpu-index: index of a virtual CPU, default is all. 2004f3b2e38cSHyman Huang(黄勇)# 2005f3b2e38cSHyman Huang(黄勇)# Since: 7.1 2006f3b2e38cSHyman Huang(黄勇)# 2007f3b2e38cSHyman Huang(黄勇)# Example: 200837fa48a4SMarkus Armbruster# 200937fa48a4SMarkus Armbruster# -> {"execute": "cancel-vcpu-dirty-limit"}, 2010f3b2e38cSHyman Huang(黄勇)# "arguments": { "cpu-index": 1 } } 201137fa48a4SMarkus Armbruster# <- { "return": {} } 2012f3b2e38cSHyman Huang(黄勇)## 2013f3b2e38cSHyman Huang(黄勇){ 'command': 'cancel-vcpu-dirty-limit', 2014f3b2e38cSHyman Huang(黄勇) 'data': { '*cpu-index': 'int'} } 2015f3b2e38cSHyman Huang(黄勇) 2016f3b2e38cSHyman Huang(黄勇)## 2017f3b2e38cSHyman Huang(黄勇)# @query-vcpu-dirty-limit: 2018f3b2e38cSHyman Huang(黄勇)# 2019a937b6aaSMarkus Armbruster# Returns information about virtual CPU dirty page rate limits, if 2020a937b6aaSMarkus Armbruster# any. 2021f3b2e38cSHyman Huang(黄勇)# 2022f3b2e38cSHyman Huang(黄勇)# Since: 7.1 2023f3b2e38cSHyman Huang(黄勇)# 2024f3b2e38cSHyman Huang(黄勇)# Example: 202537fa48a4SMarkus Armbruster# 202637fa48a4SMarkus Armbruster# -> {"execute": "query-vcpu-dirty-limit"} 202737fa48a4SMarkus Armbruster# <- {"return": [ 202837fa48a4SMarkus Armbruster# { "limit-rate": 60, "current-rate": 3, "cpu-index": 0}, 202937fa48a4SMarkus Armbruster# { "limit-rate": 60, "current-rate": 3, "cpu-index": 1}]} 2030f3b2e38cSHyman Huang(黄勇)## 2031f3b2e38cSHyman Huang(黄勇){ 'command': 'query-vcpu-dirty-limit', 2032f3b2e38cSHyman Huang(黄勇) 'returns': [ 'DirtyLimitInfo' ] } 2033f3b2e38cSHyman Huang(黄勇) 2034f3b2e38cSHyman Huang(黄勇)## 203567132620SJiang Jiacheng# @MigrationThreadInfo: 203667132620SJiang Jiacheng# 203767132620SJiang Jiacheng# Information about migrationthreads 203867132620SJiang Jiacheng# 203967132620SJiang Jiacheng# @name: the name of migration thread 204067132620SJiang Jiacheng# 204167132620SJiang Jiacheng# @thread-id: ID of the underlying host thread 204267132620SJiang Jiacheng# 204367132620SJiang Jiacheng# Since: 7.2 204467132620SJiang Jiacheng## 204567132620SJiang Jiacheng{ 'struct': 'MigrationThreadInfo', 204667132620SJiang Jiacheng 'data': {'name': 'str', 204767132620SJiang Jiacheng 'thread-id': 'int'} } 204867132620SJiang Jiacheng 204967132620SJiang Jiacheng## 205067132620SJiang Jiacheng# @query-migrationthreads: 205167132620SJiang Jiacheng# 205267132620SJiang Jiacheng# Returns information of migration threads 205367132620SJiang Jiacheng# 205467132620SJiang Jiacheng# data: migration thread name 205567132620SJiang Jiacheng# 20567c3def93SMarkus Armbruster# Returns: information about migration threads 205767132620SJiang Jiacheng# 205867132620SJiang Jiacheng# Since: 7.2 205967132620SJiang Jiacheng## 206067132620SJiang Jiacheng{ 'command': 'query-migrationthreads', 206167132620SJiang Jiacheng 'returns': ['MigrationThreadInfo'] } 206267132620SJiang Jiacheng 206367132620SJiang Jiacheng## 20640f0d83a4SDaniel P. Berrangé# @snapshot-save: 20650f0d83a4SDaniel P. Berrangé# 20660f0d83a4SDaniel P. Berrangé# Save a VM snapshot 20670f0d83a4SDaniel P. Berrangé# 20680f0d83a4SDaniel P. Berrangé# @job-id: identifier for the newly created job 2069a937b6aaSMarkus Armbruster# 20700f0d83a4SDaniel P. Berrangé# @tag: name of the snapshot to create 2071a937b6aaSMarkus Armbruster# 20720f0d83a4SDaniel P. Berrangé# @vmstate: block device node name to save vmstate to 2073a937b6aaSMarkus Armbruster# 20740f0d83a4SDaniel P. Berrangé# @devices: list of block device node names to save a snapshot to 20750f0d83a4SDaniel P. Berrangé# 20760f0d83a4SDaniel P. Berrangé# Applications should not assume that the snapshot save is complete 20770f0d83a4SDaniel P. Berrangé# when this command returns. The job commands / events must be used 2078a937b6aaSMarkus Armbruster# to determine completion and to fetch details of any errors that 2079a937b6aaSMarkus Armbruster# arise. 20800f0d83a4SDaniel P. Berrangé# 2081a937b6aaSMarkus Armbruster# Note that execution of the guest CPUs may be stopped during the time 2082a937b6aaSMarkus Armbruster# it takes to save the snapshot. A future version of QEMU may ensure 2083a937b6aaSMarkus Armbruster# CPUs are executing continuously. 20840f0d83a4SDaniel P. Berrangé# 2085a937b6aaSMarkus Armbruster# It is strongly recommended that @devices contain all writable block 2086a937b6aaSMarkus Armbruster# device nodes if a consistent snapshot is required. 20870f0d83a4SDaniel P. Berrangé# 20880f0d83a4SDaniel P. Berrangé# If @tag already exists, an error will be reported 20890f0d83a4SDaniel P. Berrangé# 20900f0d83a4SDaniel P. Berrangé# Returns: nothing 20910f0d83a4SDaniel P. Berrangé# 20920f0d83a4SDaniel P. Berrangé# Example: 20930f0d83a4SDaniel P. Berrangé# 20940f0d83a4SDaniel P. Berrangé# -> { "execute": "snapshot-save", 2095b1ca5322SFabian Holler# "arguments": { 20960f0d83a4SDaniel P. Berrangé# "job-id": "snapsave0", 20970f0d83a4SDaniel P. Berrangé# "tag": "my-snap", 20980f0d83a4SDaniel P. Berrangé# "vmstate": "disk0", 20990f0d83a4SDaniel P. Berrangé# "devices": ["disk0", "disk1"] 21000f0d83a4SDaniel P. Berrangé# } 21010f0d83a4SDaniel P. Berrangé# } 21020f0d83a4SDaniel P. Berrangé# <- { "return": { } } 21030f0d83a4SDaniel P. Berrangé# <- {"event": "JOB_STATUS_CHANGE", 21046e7a37ffSVictor Toso# "timestamp": {"seconds": 1432121972, "microseconds": 744001}, 21050f0d83a4SDaniel P. Berrangé# "data": {"status": "created", "id": "snapsave0"}} 21060f0d83a4SDaniel P. Berrangé# <- {"event": "JOB_STATUS_CHANGE", 21076e7a37ffSVictor Toso# "timestamp": {"seconds": 1432122172, "microseconds": 744001}, 21080f0d83a4SDaniel P. Berrangé# "data": {"status": "running", "id": "snapsave0"}} 21096e7a37ffSVictor Toso# <- {"event": "STOP", 21106e7a37ffSVictor Toso# "timestamp": {"seconds": 1432122372, "microseconds": 744001} } 21116e7a37ffSVictor Toso# <- {"event": "RESUME", 21126e7a37ffSVictor Toso# "timestamp": {"seconds": 1432122572, "microseconds": 744001} } 21130f0d83a4SDaniel P. Berrangé# <- {"event": "JOB_STATUS_CHANGE", 21146e7a37ffSVictor Toso# "timestamp": {"seconds": 1432122772, "microseconds": 744001}, 21150f0d83a4SDaniel P. Berrangé# "data": {"status": "waiting", "id": "snapsave0"}} 21160f0d83a4SDaniel P. Berrangé# <- {"event": "JOB_STATUS_CHANGE", 21176e7a37ffSVictor Toso# "timestamp": {"seconds": 1432122972, "microseconds": 744001}, 21180f0d83a4SDaniel P. Berrangé# "data": {"status": "pending", "id": "snapsave0"}} 21190f0d83a4SDaniel P. Berrangé# <- {"event": "JOB_STATUS_CHANGE", 21206e7a37ffSVictor Toso# "timestamp": {"seconds": 1432123172, "microseconds": 744001}, 21210f0d83a4SDaniel P. Berrangé# "data": {"status": "concluded", "id": "snapsave0"}} 21220f0d83a4SDaniel P. Berrangé# -> {"execute": "query-jobs"} 21230f0d83a4SDaniel P. Berrangé# <- {"return": [{"current-progress": 1, 21240f0d83a4SDaniel P. Berrangé# "status": "concluded", 21250f0d83a4SDaniel P. Berrangé# "total-progress": 1, 21260f0d83a4SDaniel P. Berrangé# "type": "snapshot-save", 21270f0d83a4SDaniel P. Berrangé# "id": "snapsave0"}]} 21280f0d83a4SDaniel P. Berrangé# 21290f0d83a4SDaniel P. Berrangé# Since: 6.0 21300f0d83a4SDaniel P. Berrangé## 21310f0d83a4SDaniel P. Berrangé{ 'command': 'snapshot-save', 21320f0d83a4SDaniel P. Berrangé 'data': { 'job-id': 'str', 21330f0d83a4SDaniel P. Berrangé 'tag': 'str', 21340f0d83a4SDaniel P. Berrangé 'vmstate': 'str', 21350f0d83a4SDaniel P. Berrangé 'devices': ['str'] } } 21360f0d83a4SDaniel P. Berrangé 21370f0d83a4SDaniel P. Berrangé## 21380f0d83a4SDaniel P. Berrangé# @snapshot-load: 21390f0d83a4SDaniel P. Berrangé# 21400f0d83a4SDaniel P. Berrangé# Load a VM snapshot 21410f0d83a4SDaniel P. Berrangé# 21420f0d83a4SDaniel P. Berrangé# @job-id: identifier for the newly created job 2143a937b6aaSMarkus Armbruster# 21440f0d83a4SDaniel P. Berrangé# @tag: name of the snapshot to load. 2145a937b6aaSMarkus Armbruster# 21460f0d83a4SDaniel P. Berrangé# @vmstate: block device node name to load vmstate from 2147a937b6aaSMarkus Armbruster# 21480f0d83a4SDaniel P. Berrangé# @devices: list of block device node names to load a snapshot from 21490f0d83a4SDaniel P. Berrangé# 21500f0d83a4SDaniel P. Berrangé# Applications should not assume that the snapshot load is complete 21510f0d83a4SDaniel P. Berrangé# when this command returns. The job commands / events must be used 2152a937b6aaSMarkus Armbruster# to determine completion and to fetch details of any errors that 2153a937b6aaSMarkus Armbruster# arise. 21540f0d83a4SDaniel P. Berrangé# 21550f0d83a4SDaniel P. Berrangé# Note that execution of the guest CPUs will be stopped during the 21560f0d83a4SDaniel P. Berrangé# time it takes to load the snapshot. 21570f0d83a4SDaniel P. Berrangé# 2158a937b6aaSMarkus Armbruster# It is strongly recommended that @devices contain all writable block 2159a937b6aaSMarkus Armbruster# device nodes that can have changed since the original @snapshot-save 2160a937b6aaSMarkus Armbruster# command execution. 21610f0d83a4SDaniel P. Berrangé# 21620f0d83a4SDaniel P. Berrangé# Returns: nothing 21630f0d83a4SDaniel P. Berrangé# 21640f0d83a4SDaniel P. Berrangé# Example: 21650f0d83a4SDaniel P. Berrangé# 21660f0d83a4SDaniel P. Berrangé# -> { "execute": "snapshot-load", 2167b1ca5322SFabian Holler# "arguments": { 21680f0d83a4SDaniel P. Berrangé# "job-id": "snapload0", 21690f0d83a4SDaniel P. Berrangé# "tag": "my-snap", 21700f0d83a4SDaniel P. Berrangé# "vmstate": "disk0", 21710f0d83a4SDaniel P. Berrangé# "devices": ["disk0", "disk1"] 21720f0d83a4SDaniel P. Berrangé# } 21730f0d83a4SDaniel P. Berrangé# } 21740f0d83a4SDaniel P. Berrangé# <- { "return": { } } 21750f0d83a4SDaniel P. Berrangé# <- {"event": "JOB_STATUS_CHANGE", 21766e7a37ffSVictor Toso# "timestamp": {"seconds": 1472124172, "microseconds": 744001}, 21770f0d83a4SDaniel P. Berrangé# "data": {"status": "created", "id": "snapload0"}} 21780f0d83a4SDaniel P. Berrangé# <- {"event": "JOB_STATUS_CHANGE", 21796e7a37ffSVictor Toso# "timestamp": {"seconds": 1472125172, "microseconds": 744001}, 21800f0d83a4SDaniel P. Berrangé# "data": {"status": "running", "id": "snapload0"}} 21816e7a37ffSVictor Toso# <- {"event": "STOP", 21826e7a37ffSVictor Toso# "timestamp": {"seconds": 1472125472, "microseconds": 744001} } 21836e7a37ffSVictor Toso# <- {"event": "RESUME", 21846e7a37ffSVictor Toso# "timestamp": {"seconds": 1472125872, "microseconds": 744001} } 21850f0d83a4SDaniel P. Berrangé# <- {"event": "JOB_STATUS_CHANGE", 21866e7a37ffSVictor Toso# "timestamp": {"seconds": 1472126172, "microseconds": 744001}, 21870f0d83a4SDaniel P. Berrangé# "data": {"status": "waiting", "id": "snapload0"}} 21880f0d83a4SDaniel P. Berrangé# <- {"event": "JOB_STATUS_CHANGE", 21896e7a37ffSVictor Toso# "timestamp": {"seconds": 1472127172, "microseconds": 744001}, 21900f0d83a4SDaniel P. Berrangé# "data": {"status": "pending", "id": "snapload0"}} 21910f0d83a4SDaniel P. Berrangé# <- {"event": "JOB_STATUS_CHANGE", 21926e7a37ffSVictor Toso# "timestamp": {"seconds": 1472128172, "microseconds": 744001}, 21930f0d83a4SDaniel P. Berrangé# "data": {"status": "concluded", "id": "snapload0"}} 21940f0d83a4SDaniel P. Berrangé# -> {"execute": "query-jobs"} 21950f0d83a4SDaniel P. Berrangé# <- {"return": [{"current-progress": 1, 21960f0d83a4SDaniel P. Berrangé# "status": "concluded", 21970f0d83a4SDaniel P. Berrangé# "total-progress": 1, 21980f0d83a4SDaniel P. Berrangé# "type": "snapshot-load", 21990f0d83a4SDaniel P. Berrangé# "id": "snapload0"}]} 22000f0d83a4SDaniel P. Berrangé# 22010f0d83a4SDaniel P. Berrangé# Since: 6.0 22020f0d83a4SDaniel P. Berrangé## 22030f0d83a4SDaniel P. Berrangé{ 'command': 'snapshot-load', 22040f0d83a4SDaniel P. Berrangé 'data': { 'job-id': 'str', 22050f0d83a4SDaniel P. Berrangé 'tag': 'str', 22060f0d83a4SDaniel P. Berrangé 'vmstate': 'str', 22070f0d83a4SDaniel P. Berrangé 'devices': ['str'] } } 22080f0d83a4SDaniel P. Berrangé 22090f0d83a4SDaniel P. Berrangé## 22100f0d83a4SDaniel P. Berrangé# @snapshot-delete: 22110f0d83a4SDaniel P. Berrangé# 22120f0d83a4SDaniel P. Berrangé# Delete a VM snapshot 22130f0d83a4SDaniel P. Berrangé# 22140f0d83a4SDaniel P. Berrangé# @job-id: identifier for the newly created job 2215a937b6aaSMarkus Armbruster# 22160f0d83a4SDaniel P. Berrangé# @tag: name of the snapshot to delete. 2217a937b6aaSMarkus Armbruster# 22180f0d83a4SDaniel P. Berrangé# @devices: list of block device node names to delete a snapshot from 22190f0d83a4SDaniel P. Berrangé# 22200f0d83a4SDaniel P. Berrangé# Applications should not assume that the snapshot delete is complete 22210f0d83a4SDaniel P. Berrangé# when this command returns. The job commands / events must be used 2222a937b6aaSMarkus Armbruster# to determine completion and to fetch details of any errors that 2223a937b6aaSMarkus Armbruster# arise. 22240f0d83a4SDaniel P. Berrangé# 22250f0d83a4SDaniel P. Berrangé# Returns: nothing 22260f0d83a4SDaniel P. Berrangé# 22270f0d83a4SDaniel P. Berrangé# Example: 22280f0d83a4SDaniel P. Berrangé# 22290f0d83a4SDaniel P. Berrangé# -> { "execute": "snapshot-delete", 2230b1ca5322SFabian Holler# "arguments": { 22310f0d83a4SDaniel P. Berrangé# "job-id": "snapdelete0", 22320f0d83a4SDaniel P. Berrangé# "tag": "my-snap", 22330f0d83a4SDaniel P. Berrangé# "devices": ["disk0", "disk1"] 22340f0d83a4SDaniel P. Berrangé# } 22350f0d83a4SDaniel P. Berrangé# } 22360f0d83a4SDaniel P. Berrangé# <- { "return": { } } 22370f0d83a4SDaniel P. Berrangé# <- {"event": "JOB_STATUS_CHANGE", 22386e7a37ffSVictor Toso# "timestamp": {"seconds": 1442124172, "microseconds": 744001}, 22390f0d83a4SDaniel P. Berrangé# "data": {"status": "created", "id": "snapdelete0"}} 22400f0d83a4SDaniel P. Berrangé# <- {"event": "JOB_STATUS_CHANGE", 22416e7a37ffSVictor Toso# "timestamp": {"seconds": 1442125172, "microseconds": 744001}, 22420f0d83a4SDaniel P. Berrangé# "data": {"status": "running", "id": "snapdelete0"}} 22430f0d83a4SDaniel P. Berrangé# <- {"event": "JOB_STATUS_CHANGE", 22446e7a37ffSVictor Toso# "timestamp": {"seconds": 1442126172, "microseconds": 744001}, 22450f0d83a4SDaniel P. Berrangé# "data": {"status": "waiting", "id": "snapdelete0"}} 22460f0d83a4SDaniel P. Berrangé# <- {"event": "JOB_STATUS_CHANGE", 22476e7a37ffSVictor Toso# "timestamp": {"seconds": 1442127172, "microseconds": 744001}, 22480f0d83a4SDaniel P. Berrangé# "data": {"status": "pending", "id": "snapdelete0"}} 22490f0d83a4SDaniel P. Berrangé# <- {"event": "JOB_STATUS_CHANGE", 22506e7a37ffSVictor Toso# "timestamp": {"seconds": 1442128172, "microseconds": 744001}, 22510f0d83a4SDaniel P. Berrangé# "data": {"status": "concluded", "id": "snapdelete0"}} 22520f0d83a4SDaniel P. Berrangé# -> {"execute": "query-jobs"} 22530f0d83a4SDaniel P. Berrangé# <- {"return": [{"current-progress": 1, 22540f0d83a4SDaniel P. Berrangé# "status": "concluded", 22550f0d83a4SDaniel P. Berrangé# "total-progress": 1, 22560f0d83a4SDaniel P. Berrangé# "type": "snapshot-delete", 22570f0d83a4SDaniel P. Berrangé# "id": "snapdelete0"}]} 22580f0d83a4SDaniel P. Berrangé# 22590f0d83a4SDaniel P. Berrangé# Since: 6.0 22600f0d83a4SDaniel P. Berrangé## 22610f0d83a4SDaniel P. Berrangé{ 'command': 'snapshot-delete', 22620f0d83a4SDaniel P. Berrangé 'data': { 'job-id': 'str', 22630f0d83a4SDaniel P. Berrangé 'tag': 'str', 22640f0d83a4SDaniel P. Berrangé 'devices': ['str'] } } 2265