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# 2539bc6e893SMarkus Armbruster# Since: 0.14 25448685a8eSMarkus Armbruster## 25548685a8eSMarkus Armbruster{ 'struct': 'MigrationInfo', 25648685a8eSMarkus Armbruster 'data': {'*status': 'MigrationStatus', '*ram': 'MigrationStats', 25748685a8eSMarkus Armbruster '*disk': 'MigrationStats', 2583710586cSKirti Wankhede '*vfio': 'VfioStats', 25948685a8eSMarkus Armbruster '*xbzrle-cache': 'XBZRLECacheStats', 26048685a8eSMarkus Armbruster '*total-time': 'int', 26148685a8eSMarkus Armbruster '*expected-downtime': 'int', 26248685a8eSMarkus Armbruster '*downtime': 'int', 26348685a8eSMarkus Armbruster '*setup-time': 'int', 26448685a8eSMarkus Armbruster '*cpu-throttle-percentage': 'int', 26565ace060SAlexey Perevalov '*error-desc': 'str', 2663af8554bSDr. David Alan Gilbert '*blocked-reasons': ['str'], 26765ace060SAlexey Perevalov '*postcopy-blocktime' : 'uint32', 26876e03000SXiao Guangrong '*postcopy-vcpu-blocktime': ['uint32'], 2699aca82baSJuan Quintela '*compression': 'CompressionStats', 2709aca82baSJuan Quintela '*socket-address': ['SocketAddress'] } } 27148685a8eSMarkus Armbruster 27248685a8eSMarkus Armbruster## 27348685a8eSMarkus Armbruster# @query-migrate: 27448685a8eSMarkus Armbruster# 27548685a8eSMarkus Armbruster# Returns information about current migration process. If migration 27648685a8eSMarkus Armbruster# is active there will be another json-object with RAM migration 27748685a8eSMarkus Armbruster# status and if block migration is active another one with block 27848685a8eSMarkus Armbruster# migration status. 27948685a8eSMarkus Armbruster# 28048685a8eSMarkus Armbruster# Returns: @MigrationInfo 28148685a8eSMarkus Armbruster# 2829bc6e893SMarkus Armbruster# Since: 0.14 28348685a8eSMarkus Armbruster# 28437fa48a4SMarkus Armbruster# Examples: 28548685a8eSMarkus Armbruster# 28648685a8eSMarkus Armbruster# 1. Before the first migration 28748685a8eSMarkus Armbruster# 28848685a8eSMarkus Armbruster# -> { "execute": "query-migrate" } 28948685a8eSMarkus Armbruster# <- { "return": {} } 29048685a8eSMarkus Armbruster# 29148685a8eSMarkus Armbruster# 2. Migration is done and has succeeded 29248685a8eSMarkus Armbruster# 29348685a8eSMarkus Armbruster# -> { "execute": "query-migrate" } 29448685a8eSMarkus Armbruster# <- { "return": { 29548685a8eSMarkus Armbruster# "status": "completed", 296be1d2c49Sjialina01# "total-time":12345, 297be1d2c49Sjialina01# "setup-time":12345, 298be1d2c49Sjialina01# "downtime":12345, 29948685a8eSMarkus Armbruster# "ram":{ 30048685a8eSMarkus Armbruster# "transferred":123, 30148685a8eSMarkus Armbruster# "remaining":123, 30248685a8eSMarkus Armbruster# "total":246, 30348685a8eSMarkus Armbruster# "duplicate":123, 30448685a8eSMarkus Armbruster# "normal":123, 30548685a8eSMarkus Armbruster# "normal-bytes":123456, 30648685a8eSMarkus Armbruster# "dirty-sync-count":15 30748685a8eSMarkus Armbruster# } 30848685a8eSMarkus Armbruster# } 30948685a8eSMarkus Armbruster# } 31048685a8eSMarkus Armbruster# 31148685a8eSMarkus Armbruster# 3. Migration is done and has failed 31248685a8eSMarkus Armbruster# 31348685a8eSMarkus Armbruster# -> { "execute": "query-migrate" } 31448685a8eSMarkus Armbruster# <- { "return": { "status": "failed" } } 31548685a8eSMarkus Armbruster# 31648685a8eSMarkus Armbruster# 4. Migration is being performed and is not a block migration: 31748685a8eSMarkus Armbruster# 31848685a8eSMarkus Armbruster# -> { "execute": "query-migrate" } 31948685a8eSMarkus Armbruster# <- { 32048685a8eSMarkus Armbruster# "return":{ 32148685a8eSMarkus Armbruster# "status":"active", 322be1d2c49Sjialina01# "total-time":12345, 323be1d2c49Sjialina01# "setup-time":12345, 324be1d2c49Sjialina01# "expected-downtime":12345, 32548685a8eSMarkus Armbruster# "ram":{ 32648685a8eSMarkus Armbruster# "transferred":123, 32748685a8eSMarkus Armbruster# "remaining":123, 32848685a8eSMarkus Armbruster# "total":246, 32948685a8eSMarkus Armbruster# "duplicate":123, 33048685a8eSMarkus Armbruster# "normal":123, 33148685a8eSMarkus Armbruster# "normal-bytes":123456, 33248685a8eSMarkus Armbruster# "dirty-sync-count":15 33348685a8eSMarkus Armbruster# } 33448685a8eSMarkus Armbruster# } 33548685a8eSMarkus Armbruster# } 33648685a8eSMarkus Armbruster# 33748685a8eSMarkus Armbruster# 5. Migration is being performed and is a block migration: 33848685a8eSMarkus Armbruster# 33948685a8eSMarkus Armbruster# -> { "execute": "query-migrate" } 34048685a8eSMarkus Armbruster# <- { 34148685a8eSMarkus Armbruster# "return":{ 34248685a8eSMarkus Armbruster# "status":"active", 343be1d2c49Sjialina01# "total-time":12345, 344be1d2c49Sjialina01# "setup-time":12345, 345be1d2c49Sjialina01# "expected-downtime":12345, 34648685a8eSMarkus Armbruster# "ram":{ 34748685a8eSMarkus Armbruster# "total":1057024, 34848685a8eSMarkus Armbruster# "remaining":1053304, 34948685a8eSMarkus Armbruster# "transferred":3720, 35048685a8eSMarkus Armbruster# "duplicate":123, 35148685a8eSMarkus Armbruster# "normal":123, 35248685a8eSMarkus Armbruster# "normal-bytes":123456, 35348685a8eSMarkus Armbruster# "dirty-sync-count":15 35448685a8eSMarkus Armbruster# }, 35548685a8eSMarkus Armbruster# "disk":{ 35648685a8eSMarkus Armbruster# "total":20971520, 35748685a8eSMarkus Armbruster# "remaining":20880384, 35848685a8eSMarkus Armbruster# "transferred":91136 35948685a8eSMarkus Armbruster# } 36048685a8eSMarkus Armbruster# } 36148685a8eSMarkus Armbruster# } 36248685a8eSMarkus Armbruster# 36348685a8eSMarkus Armbruster# 6. Migration is being performed and XBZRLE is active: 36448685a8eSMarkus Armbruster# 36548685a8eSMarkus Armbruster# -> { "execute": "query-migrate" } 36648685a8eSMarkus Armbruster# <- { 36748685a8eSMarkus Armbruster# "return":{ 36848685a8eSMarkus Armbruster# "status":"active", 369be1d2c49Sjialina01# "total-time":12345, 370be1d2c49Sjialina01# "setup-time":12345, 371be1d2c49Sjialina01# "expected-downtime":12345, 37248685a8eSMarkus Armbruster# "ram":{ 37348685a8eSMarkus Armbruster# "total":1057024, 37448685a8eSMarkus Armbruster# "remaining":1053304, 37548685a8eSMarkus Armbruster# "transferred":3720, 37648685a8eSMarkus Armbruster# "duplicate":10, 37748685a8eSMarkus Armbruster# "normal":3333, 37848685a8eSMarkus Armbruster# "normal-bytes":3412992, 37948685a8eSMarkus Armbruster# "dirty-sync-count":15 38048685a8eSMarkus Armbruster# }, 38148685a8eSMarkus Armbruster# "xbzrle-cache":{ 38248685a8eSMarkus Armbruster# "cache-size":67108864, 38348685a8eSMarkus Armbruster# "bytes":20971520, 38448685a8eSMarkus Armbruster# "pages":2444343, 38548685a8eSMarkus Armbruster# "cache-miss":2244, 38648685a8eSMarkus Armbruster# "cache-miss-rate":0.123, 387e460a4b1SWei Wang# "encoding-rate":80.1, 38848685a8eSMarkus Armbruster# "overflow":34434 38948685a8eSMarkus Armbruster# } 39048685a8eSMarkus Armbruster# } 39148685a8eSMarkus Armbruster# } 39248685a8eSMarkus Armbruster## 39348685a8eSMarkus Armbruster{ 'command': 'query-migrate', 'returns': 'MigrationInfo' } 39448685a8eSMarkus Armbruster 39548685a8eSMarkus Armbruster## 39648685a8eSMarkus Armbruster# @MigrationCapability: 39748685a8eSMarkus Armbruster# 39848685a8eSMarkus Armbruster# Migration capabilities enumeration 39948685a8eSMarkus Armbruster# 400a937b6aaSMarkus Armbruster# @xbzrle: Migration supports xbzrle (Xor Based Zero Run Length 401a937b6aaSMarkus Armbruster# Encoding). This feature allows us to minimize migration traffic 402a937b6aaSMarkus Armbruster# for certain work loads, by sending compressed difference of the 403a937b6aaSMarkus Armbruster# pages 40448685a8eSMarkus Armbruster# 405a937b6aaSMarkus Armbruster# @rdma-pin-all: Controls whether or not the entire VM memory 406a937b6aaSMarkus Armbruster# footprint is mlock()'d on demand or all at once. Refer to 407a937b6aaSMarkus Armbruster# docs/rdma.txt for usage. Disabled by default. (since 2.0) 40848685a8eSMarkus Armbruster# 409a937b6aaSMarkus Armbruster# @zero-blocks: During storage migration encode blocks of zeroes 410a937b6aaSMarkus Armbruster# efficiently. This essentially saves 1MB of zeroes per block on 411a937b6aaSMarkus Armbruster# the wire. Enabling requires source and target VM to support 412a937b6aaSMarkus Armbruster# this feature. To enable it is sufficient to enable the 413a937b6aaSMarkus Armbruster# capability on the source VM. The feature is disabled by default. 414a937b6aaSMarkus Armbruster# (since 1.6) 41548685a8eSMarkus Armbruster# 416a937b6aaSMarkus Armbruster# @compress: Use multiple compression threads to accelerate live 417a937b6aaSMarkus Armbruster# migration. This feature can help to reduce the migration 418a937b6aaSMarkus Armbruster# traffic, by sending compressed pages. Please note that if 419a937b6aaSMarkus Armbruster# compress and xbzrle are both on, compress only takes effect in 420a937b6aaSMarkus Armbruster# the ram bulk stage, after that, it will be disabled and only 421a937b6aaSMarkus Armbruster# xbzrle takes effect, this can help to minimize migration 422a937b6aaSMarkus Armbruster# traffic. The feature is disabled by default. (since 2.4 ) 42348685a8eSMarkus Armbruster# 424a937b6aaSMarkus Armbruster# @events: generate events for each migration state change (since 2.4 425a937b6aaSMarkus Armbruster# ) 42648685a8eSMarkus Armbruster# 427a937b6aaSMarkus Armbruster# @auto-converge: If enabled, QEMU will automatically throttle down 428a937b6aaSMarkus Armbruster# the guest to speed up convergence of RAM migration. (since 1.6) 42948685a8eSMarkus Armbruster# 430a937b6aaSMarkus Armbruster# @postcopy-ram: Start executing on the migration target before all of 431a937b6aaSMarkus Armbruster# RAM has been migrated, pulling the remaining pages along as 432a937b6aaSMarkus Armbruster# needed. The capacity must have the same setting on both source 433a937b6aaSMarkus Armbruster# and target or migration will not even start. NOTE: If the 434a937b6aaSMarkus Armbruster# migration fails during postcopy the VM will fail. (since 2.6) 43548685a8eSMarkus Armbruster# 436a937b6aaSMarkus Armbruster# @x-colo: If enabled, migration will never end, and the state of the 437a937b6aaSMarkus Armbruster# VM on the primary side will be migrated continuously to the VM 438a937b6aaSMarkus Armbruster# on secondary side, this process is called COarse-Grain LOck 439a937b6aaSMarkus Armbruster# Stepping (COLO) for Non-stop Service. (since 2.8) 44048685a8eSMarkus Armbruster# 441a937b6aaSMarkus Armbruster# @release-ram: if enabled, qemu will free the migrated ram pages on 442a937b6aaSMarkus Armbruster# the source during postcopy-ram migration. (since 2.9) 44348685a8eSMarkus Armbruster# 44448685a8eSMarkus Armbruster# @block: If enabled, QEMU will also migrate the contents of all block 44548685a8eSMarkus Armbruster# devices. Default is disabled. A possible alternative uses 44648685a8eSMarkus Armbruster# mirror jobs to a builtin NBD server on the destination, which 447a937b6aaSMarkus Armbruster# offers more flexibility. (Since 2.10) 44848685a8eSMarkus Armbruster# 44948685a8eSMarkus Armbruster# @return-path: If enabled, migration will use the return path even 45048685a8eSMarkus Armbruster# for precopy. (since 2.10) 45148685a8eSMarkus Armbruster# 452a937b6aaSMarkus Armbruster# @pause-before-switchover: Pause outgoing migration before 453a937b6aaSMarkus Armbruster# serialising device state and before disabling block IO (since 454a937b6aaSMarkus Armbruster# 2.11) 45593fbd031SDr. David Alan Gilbert# 456cbfd6c95SJuan Quintela# @multifd: Use more than one fd for migration (since 4.0) 45730126bbfSJuan Quintela# 45855efc8c2SVladimir Sementsov-Ogievskiy# @dirty-bitmaps: If enabled, QEMU will migrate named dirty bitmaps. 45955efc8c2SVladimir Sementsov-Ogievskiy# (since 2.12) 46055efc8c2SVladimir Sementsov-Ogievskiy# 461f22f928eSAlexey Perevalov# @postcopy-blocktime: Calculate downtime for postcopy live migration 46251f63ec7SPeter Maydell# (since 3.0) 463f22f928eSAlexey Perevalov# 464a937b6aaSMarkus Armbruster# @late-block-activate: If enabled, the destination will not activate 465a937b6aaSMarkus Armbruster# block devices (and thus take locks) immediately at the end of 466a937b6aaSMarkus Armbruster# migration. (since 3.0) 4670f073f44SDr. David Alan Gilbert# 468b0182e53SSteve Sistare# @x-ignore-shared: If enabled, QEMU will not migrate shared memory that is 469b0182e53SSteve Sistare# accessible on the destination machine. (since 4.0) 47018269069SYury Kotov# 471b9d68df6SYury Kotov# @validate-uuid: Send the UUID of the source to allow the destination 472b9d68df6SYury Kotov# to ensure it is the same. (since 4.2) 473b9d68df6SYury Kotov# 474a937b6aaSMarkus Armbruster# @background-snapshot: If enabled, the migration stream will be a 475a937b6aaSMarkus Armbruster# snapshot of the VM exactly at the point when the migration 476a937b6aaSMarkus Armbruster# procedure starts. The VM RAM is saved with running VM. (since 477a937b6aaSMarkus Armbruster# 6.0) 4786e8c25b4SAndrey Gruzdev# 479a937b6aaSMarkus Armbruster# @zero-copy-send: Controls behavior on sending memory pages on 480a937b6aaSMarkus Armbruster# migration. When true, enables a zero-copy mechanism for sending 481a937b6aaSMarkus Armbruster# memory pages, if host supports it. Requires that QEMU be 482a937b6aaSMarkus Armbruster# permitted to use locked memory for guest RAM pages. (since 7.1) 483a937b6aaSMarkus Armbruster# 484a937b6aaSMarkus Armbruster# @postcopy-preempt: If enabled, the migration process will allow 485a937b6aaSMarkus Armbruster# postcopy requests to preempt precopy stream, so postcopy 486a937b6aaSMarkus Armbruster# requests will be handled faster. This is a performance feature 487a937b6aaSMarkus Armbruster# and should not affect the correctness of postcopy migration. 488ce5b0f4aSPeter Xu# (since 7.1) 4891abaec9aSLeonardo Bras# 4906574232fSAvihai Horon# @switchover-ack: If enabled, migration will not stop the source VM 4916574232fSAvihai Horon# and complete the migration until an ACK is received from the 4926574232fSAvihai Horon# destination that it's OK to do so. Exactly when this ACK is 4936574232fSAvihai Horon# sent depends on the migrated devices that use this feature. 4946574232fSAvihai Horon# For example, a device can use it to make sure some of its data 4956574232fSAvihai Horon# is sent and loaded in the destination before doing switchover. 4966574232fSAvihai Horon# This can reduce downtime if devices that support this capability 4976574232fSAvihai Horon# are present. 'return-path' capability must be enabled to use 4986574232fSAvihai Horon# it. (since 8.1) 4996574232fSAvihai Horon# 5009fb49daaSMarkus Armbruster# Features: 501a937b6aaSMarkus Armbruster# 5029fb49daaSMarkus Armbruster# @unstable: Members @x-colo and @x-ignore-shared are experimental. 5039fb49daaSMarkus Armbruster# 50448685a8eSMarkus Armbruster# Since: 1.2 50548685a8eSMarkus Armbruster## 50648685a8eSMarkus Armbruster{ 'enum': 'MigrationCapability', 50748685a8eSMarkus Armbruster 'data': ['xbzrle', 'rdma-pin-all', 'auto-converge', 'zero-blocks', 5089fb49daaSMarkus Armbruster 'compress', 'events', 'postcopy-ram', 5099fb49daaSMarkus Armbruster { 'name': 'x-colo', 'features': [ 'unstable' ] }, 5109fb49daaSMarkus Armbruster 'release-ram', 511cbfd6c95SJuan Quintela 'block', 'return-path', 'pause-before-switchover', 'multifd', 51218269069SYury Kotov 'dirty-bitmaps', 'postcopy-blocktime', 'late-block-activate', 5139fb49daaSMarkus Armbruster { 'name': 'x-ignore-shared', 'features': [ 'unstable' ] }, 5141abaec9aSLeonardo Bras 'validate-uuid', 'background-snapshot', 5156574232fSAvihai Horon 'zero-copy-send', 'postcopy-preempt', 'switchover-ack'] } 51648685a8eSMarkus Armbruster 51748685a8eSMarkus Armbruster## 51848685a8eSMarkus Armbruster# @MigrationCapabilityStatus: 51948685a8eSMarkus Armbruster# 52048685a8eSMarkus Armbruster# Migration capability information 52148685a8eSMarkus Armbruster# 52248685a8eSMarkus Armbruster# @capability: capability enum 52348685a8eSMarkus Armbruster# 52448685a8eSMarkus Armbruster# @state: capability state bool 52548685a8eSMarkus Armbruster# 52648685a8eSMarkus Armbruster# Since: 1.2 52748685a8eSMarkus Armbruster## 52848685a8eSMarkus Armbruster{ 'struct': 'MigrationCapabilityStatus', 52948685a8eSMarkus Armbruster 'data': { 'capability' : 'MigrationCapability', 'state' : 'bool' } } 53048685a8eSMarkus Armbruster 53148685a8eSMarkus Armbruster## 53248685a8eSMarkus Armbruster# @migrate-set-capabilities: 53348685a8eSMarkus Armbruster# 53448685a8eSMarkus Armbruster# Enable/Disable the following migration capabilities (like xbzrle) 53548685a8eSMarkus Armbruster# 53648685a8eSMarkus Armbruster# @capabilities: json array of capability modifications to make 53748685a8eSMarkus Armbruster# 53848685a8eSMarkus Armbruster# Since: 1.2 53948685a8eSMarkus Armbruster# 54048685a8eSMarkus Armbruster# Example: 54148685a8eSMarkus Armbruster# 54248685a8eSMarkus Armbruster# -> { "execute": "migrate-set-capabilities" , "arguments": 54348685a8eSMarkus Armbruster# { "capabilities": [ { "capability": "xbzrle", "state": true } ] } } 54437fa48a4SMarkus Armbruster# <- { "return": {} } 54548685a8eSMarkus Armbruster## 54648685a8eSMarkus Armbruster{ 'command': 'migrate-set-capabilities', 54748685a8eSMarkus Armbruster 'data': { 'capabilities': ['MigrationCapabilityStatus'] } } 54848685a8eSMarkus Armbruster 54948685a8eSMarkus Armbruster## 55048685a8eSMarkus Armbruster# @query-migrate-capabilities: 55148685a8eSMarkus Armbruster# 55248685a8eSMarkus Armbruster# Returns information about the current migration capabilities status 55348685a8eSMarkus Armbruster# 554d93ed1bdSMarkus Armbruster# Returns: @MigrationCapabilityStatus 55548685a8eSMarkus Armbruster# 55648685a8eSMarkus Armbruster# Since: 1.2 55748685a8eSMarkus Armbruster# 55848685a8eSMarkus Armbruster# Example: 55948685a8eSMarkus Armbruster# 56048685a8eSMarkus Armbruster# -> { "execute": "query-migrate-capabilities" } 56148685a8eSMarkus Armbruster# <- { "return": [ 56248685a8eSMarkus Armbruster# {"state": false, "capability": "xbzrle"}, 56348685a8eSMarkus Armbruster# {"state": false, "capability": "rdma-pin-all"}, 56448685a8eSMarkus Armbruster# {"state": false, "capability": "auto-converge"}, 56548685a8eSMarkus Armbruster# {"state": false, "capability": "zero-blocks"}, 56648685a8eSMarkus Armbruster# {"state": false, "capability": "compress"}, 56748685a8eSMarkus Armbruster# {"state": true, "capability": "events"}, 56848685a8eSMarkus Armbruster# {"state": false, "capability": "postcopy-ram"}, 56948685a8eSMarkus Armbruster# {"state": false, "capability": "x-colo"} 57048685a8eSMarkus Armbruster# ]} 57148685a8eSMarkus Armbruster## 57248685a8eSMarkus Armbruster{ 'command': 'query-migrate-capabilities', 'returns': ['MigrationCapabilityStatus']} 57348685a8eSMarkus Armbruster 57448685a8eSMarkus Armbruster## 57596eef042SJuan Quintela# @MultiFDCompression: 57696eef042SJuan Quintela# 57796eef042SJuan Quintela# An enumeration of multifd compression methods. 57896eef042SJuan Quintela# 57996eef042SJuan Quintela# @none: no compression. 580a937b6aaSMarkus Armbruster# 5817ec2c2b3SJuan Quintela# @zlib: use zlib compression method. 582a937b6aaSMarkus Armbruster# 58387dc6f5fSJuan Quintela# @zstd: use zstd compression method. 58496eef042SJuan Quintela# 58596eef042SJuan Quintela# Since: 5.0 58696eef042SJuan Quintela## 58796eef042SJuan Quintela{ 'enum': 'MultiFDCompression', 58887dc6f5fSJuan Quintela 'data': [ 'none', 'zlib', 5898a9f1e1dSMarc-André Lureau { 'name': 'zstd', 'if': 'CONFIG_ZSTD' } ] } 59096eef042SJuan Quintela 59196eef042SJuan Quintela## 5926e9f21a2SPeter Krempa# @BitmapMigrationBitmapAliasTransform: 5936e9f21a2SPeter Krempa# 594a937b6aaSMarkus Armbruster# @persistent: If present, the bitmap will be made persistent or 595a937b6aaSMarkus Armbruster# transient depending on this parameter. 5966e9f21a2SPeter Krempa# 5976e9f21a2SPeter Krempa# Since: 6.0 5986e9f21a2SPeter Krempa## 5996e9f21a2SPeter Krempa{ 'struct': 'BitmapMigrationBitmapAliasTransform', 6006e9f21a2SPeter Krempa 'data': { 6016e9f21a2SPeter Krempa '*persistent': 'bool' 6026e9f21a2SPeter Krempa } } 6036e9f21a2SPeter Krempa 6046e9f21a2SPeter Krempa## 60531e4c354SMax Reitz# @BitmapMigrationBitmapAlias: 60631e4c354SMax Reitz# 60731e4c354SMax Reitz# @name: The name of the bitmap. 60831e4c354SMax Reitz# 60931e4c354SMax Reitz# @alias: An alias name for migration (for example the bitmap name on 61031e4c354SMax Reitz# the opposite site). 61131e4c354SMax Reitz# 612a937b6aaSMarkus Armbruster# @transform: Allows the modification of the migrated bitmap. (since 613a937b6aaSMarkus Armbruster# 6.0) 6146e9f21a2SPeter Krempa# 61531e4c354SMax Reitz# Since: 5.2 61631e4c354SMax Reitz## 61731e4c354SMax Reitz{ 'struct': 'BitmapMigrationBitmapAlias', 61831e4c354SMax Reitz 'data': { 61931e4c354SMax Reitz 'name': 'str', 6206e9f21a2SPeter Krempa 'alias': 'str', 6216e9f21a2SPeter Krempa '*transform': 'BitmapMigrationBitmapAliasTransform' 62231e4c354SMax Reitz } } 62331e4c354SMax Reitz 62431e4c354SMax Reitz## 62531e4c354SMax Reitz# @BitmapMigrationNodeAlias: 62631e4c354SMax Reitz# 62731e4c354SMax Reitz# Maps a block node name and the bitmaps it has to aliases for dirty 62831e4c354SMax Reitz# bitmap migration. 62931e4c354SMax Reitz# 63031e4c354SMax Reitz# @node-name: A block node name. 63131e4c354SMax Reitz# 632a937b6aaSMarkus Armbruster# @alias: An alias block node name for migration (for example the node 633a937b6aaSMarkus Armbruster# name on the opposite site). 63431e4c354SMax Reitz# 63531e4c354SMax Reitz# @bitmaps: Mappings for the bitmaps on this node. 63631e4c354SMax Reitz# 63731e4c354SMax Reitz# Since: 5.2 63831e4c354SMax Reitz## 63931e4c354SMax Reitz{ 'struct': 'BitmapMigrationNodeAlias', 64031e4c354SMax Reitz 'data': { 64131e4c354SMax Reitz 'node-name': 'str', 64231e4c354SMax Reitz 'alias': 'str', 64331e4c354SMax Reitz 'bitmaps': [ 'BitmapMigrationBitmapAlias' ] 64431e4c354SMax Reitz } } 64531e4c354SMax Reitz 64631e4c354SMax Reitz## 64748685a8eSMarkus Armbruster# @MigrationParameter: 64848685a8eSMarkus Armbruster# 64948685a8eSMarkus Armbruster# Migration parameters enumeration 65048685a8eSMarkus Armbruster# 651a937b6aaSMarkus Armbruster# @announce-initial: Initial delay (in milliseconds) before sending 652a937b6aaSMarkus Armbruster# the first announce (Since 4.0) 653ee3d96baSDr. David Alan Gilbert# 654a937b6aaSMarkus Armbruster# @announce-max: Maximum delay (in milliseconds) between packets in 655a937b6aaSMarkus Armbruster# the announcement (Since 4.0) 656ee3d96baSDr. David Alan Gilbert# 657a937b6aaSMarkus Armbruster# @announce-rounds: Number of self-announce packets sent after 658a937b6aaSMarkus Armbruster# migration (Since 4.0) 659ee3d96baSDr. David Alan Gilbert# 660a937b6aaSMarkus Armbruster# @announce-step: Increase in delay (in milliseconds) between 661a937b6aaSMarkus Armbruster# subsequent packets in the announcement (Since 4.0) 662ee3d96baSDr. David Alan Gilbert# 663a937b6aaSMarkus Armbruster# @compress-level: Set the compression level to be used in live 664a937b6aaSMarkus Armbruster# migration, the compression level is an integer between 0 and 9, 665a937b6aaSMarkus Armbruster# where 0 means no compression, 1 means the best compression 666a937b6aaSMarkus Armbruster# speed, and 9 means best compression ratio which will consume 667a937b6aaSMarkus Armbruster# more CPU. 66848685a8eSMarkus Armbruster# 669a937b6aaSMarkus Armbruster# @compress-threads: Set compression thread count to be used in live 670a937b6aaSMarkus Armbruster# migration, the compression thread count is an integer between 1 671a937b6aaSMarkus Armbruster# and 255. 67248685a8eSMarkus Armbruster# 673a937b6aaSMarkus Armbruster# @compress-wait-thread: Controls behavior when all compression 674a937b6aaSMarkus Armbruster# threads are currently busy. If true (default), wait for a free 675a937b6aaSMarkus Armbruster# compression thread to become available; otherwise, send the page 676a937b6aaSMarkus Armbruster# uncompressed. (Since 3.1) 6771d58872aSXiao Guangrong# 678a937b6aaSMarkus Armbruster# @decompress-threads: Set decompression thread count to be used in 679a937b6aaSMarkus Armbruster# live migration, the decompression thread count is an integer 680a937b6aaSMarkus Armbruster# between 1 and 255. Usually, decompression is at least 4 times as 681a937b6aaSMarkus Armbruster# fast as compression, so set the decompress-threads to the number 682a937b6aaSMarkus Armbruster# about 1/4 of compress-threads is adequate. 68348685a8eSMarkus Armbruster# 684a937b6aaSMarkus Armbruster# @throttle-trigger-threshold: The ratio of bytes_dirty_period and 685a937b6aaSMarkus Armbruster# bytes_xfer_period to trigger throttling. It is expressed as 686a937b6aaSMarkus Armbruster# percentage. The default value is 50. (Since 5.0) 687dc14a470SKeqian Zhu# 688a937b6aaSMarkus Armbruster# @cpu-throttle-initial: Initial percentage of time guest cpus are 689a937b6aaSMarkus Armbruster# throttled when migration auto-converge is activated. The 69048685a8eSMarkus Armbruster# default value is 20. (Since 2.7) 69148685a8eSMarkus Armbruster# 69248685a8eSMarkus Armbruster# @cpu-throttle-increment: throttle percentage increase each time 693a937b6aaSMarkus Armbruster# auto-converge detects that migration is not making progress. 694a937b6aaSMarkus Armbruster# The default value is 10. (Since 2.7) 69548685a8eSMarkus Armbruster# 696a937b6aaSMarkus Armbruster# @cpu-throttle-tailslow: Make CPU throttling slower at tail stage At 697a937b6aaSMarkus Armbruster# the tail stage of throttling, the Guest is very sensitive to CPU 698a937b6aaSMarkus Armbruster# percentage while the @cpu-throttle -increment is excessive 699a937b6aaSMarkus Armbruster# usually at tail stage. If this parameter is true, we will 700a937b6aaSMarkus Armbruster# compute the ideal CPU percentage used by the Guest, which may 701a937b6aaSMarkus Armbruster# exactly make the dirty rate match the dirty rate threshold. 702a937b6aaSMarkus Armbruster# Then we will choose a smaller throttle increment between the one 703a937b6aaSMarkus Armbruster# specified by @cpu-throttle-increment and the one generated by 704a937b6aaSMarkus Armbruster# ideal CPU percentage. Therefore, it is compatible to 705a937b6aaSMarkus Armbruster# traditional throttling, meanwhile the throttle increment won't 706a937b6aaSMarkus Armbruster# be excessive at tail stage. The default value is false. (Since 707a937b6aaSMarkus Armbruster# 5.1) 708cbbf8182SKeqian Zhu# 709a937b6aaSMarkus Armbruster# @tls-creds: ID of the 'tls-creds' object that provides credentials 710a937b6aaSMarkus Armbruster# for establishing a TLS connection over the migration data 711a937b6aaSMarkus Armbruster# channel. On the outgoing side of the migration, the credentials 712a937b6aaSMarkus Armbruster# must be for a 'client' endpoint, while for the incoming side the 713a937b6aaSMarkus Armbruster# credentials must be for a 'server' endpoint. Setting this will 714a937b6aaSMarkus Armbruster# enable TLS for all migrations. The default is unset, resulting 715a937b6aaSMarkus Armbruster# in unsecured migration at the QEMU level. (Since 2.7) 71648685a8eSMarkus Armbruster# 717a937b6aaSMarkus Armbruster# @tls-hostname: hostname of the target host for the migration. This 718a937b6aaSMarkus Armbruster# is required when using x509 based TLS credentials and the 719a937b6aaSMarkus Armbruster# migration URI does not already include a hostname. For example 720a937b6aaSMarkus Armbruster# if using fd: or exec: based migration, the hostname must be 721a937b6aaSMarkus Armbruster# provided so that the server's x509 certificate identity can be 722a937b6aaSMarkus Armbruster# validated. (Since 2.7) 72348685a8eSMarkus Armbruster# 724a937b6aaSMarkus Armbruster# @tls-authz: ID of the 'authz' object subclass that provides access 725a937b6aaSMarkus Armbruster# control checking of the TLS x509 certificate distinguished name. 726d2f1d29bSDaniel P. Berrange# This object is only resolved at time of use, so can be deleted 727d2f1d29bSDaniel P. Berrange# and recreated on the fly while the migration server is active. 728d2f1d29bSDaniel P. Berrange# If missing, it will default to denying access (Since 4.0) 729d2f1d29bSDaniel P. Berrange# 730a937b6aaSMarkus Armbruster# @max-bandwidth: to set maximum speed for migration. maximum speed 731a937b6aaSMarkus Armbruster# in bytes per second. (Since 2.8) 73248685a8eSMarkus Armbruster# 733a937b6aaSMarkus Armbruster# @downtime-limit: set maximum tolerated downtime for migration. 734a937b6aaSMarkus Armbruster# maximum downtime in milliseconds (Since 2.8) 73548685a8eSMarkus Armbruster# 736a937b6aaSMarkus Armbruster# @x-checkpoint-delay: The delay time (in ms) between two COLO 737a937b6aaSMarkus Armbruster# checkpoints in periodic mode. (Since 2.8) 73848685a8eSMarkus Armbruster# 73948685a8eSMarkus Armbruster# @block-incremental: Affects how much storage is migrated when the 74048685a8eSMarkus Armbruster# block migration capability is enabled. When false, the entire 741a937b6aaSMarkus Armbruster# storage backing chain is migrated into a flattened image at the 742a937b6aaSMarkus Armbruster# destination; when true, only the active qcow2 layer is migrated 743a937b6aaSMarkus Armbruster# and the destination must already have access to the same backing 744a937b6aaSMarkus Armbruster# chain as was used on the source. (since 2.10) 74548685a8eSMarkus Armbruster# 746cbfd6c95SJuan Quintela# @multifd-channels: Number of channels used to migrate data in 747a937b6aaSMarkus Armbruster# parallel. This is the same number that the number of sockets 748a937b6aaSMarkus Armbruster# used for migration. The default value is 2 (since 4.0) 7494075fb1cSJuan Quintela# 75073af8dd8SJuan Quintela# @xbzrle-cache-size: cache size to be used by XBZRLE migration. It 751a937b6aaSMarkus Armbruster# needs to be a multiple of the target page size and a power of 2 75273af8dd8SJuan Quintela# (Since 2.11) 75373af8dd8SJuan Quintela# 754a937b6aaSMarkus Armbruster# @max-postcopy-bandwidth: Background transfer bandwidth during 755a937b6aaSMarkus Armbruster# postcopy. Defaults to 0 (unlimited). In bytes per second. 7567e555c6cSDr. David Alan Gilbert# (Since 3.0) 7574cbc9c7fSLi Qiang# 758a937b6aaSMarkus Armbruster# @max-cpu-throttle: maximum cpu throttle percentage. Defaults to 99. 759a937b6aaSMarkus Armbruster# (Since 3.1) 760ee3d96baSDr. David Alan Gilbert# 761a937b6aaSMarkus Armbruster# @multifd-compression: Which compression method to use. Defaults to 762a937b6aaSMarkus Armbruster# none. (Since 5.0) 76396eef042SJuan Quintela# 7649004db48SJuan Quintela# @multifd-zlib-level: Set the compression level to be used in live 765a937b6aaSMarkus Armbruster# migration, the compression level is an integer between 0 and 9, 766a937b6aaSMarkus Armbruster# where 0 means no compression, 1 means the best compression 767a937b6aaSMarkus Armbruster# speed, and 9 means best compression ratio which will consume 768a937b6aaSMarkus Armbruster# more CPU. Defaults to 1. (Since 5.0) 7699004db48SJuan Quintela# 7706a9ad154SJuan Quintela# @multifd-zstd-level: Set the compression level to be used in live 771a937b6aaSMarkus Armbruster# migration, the compression level is an integer between 0 and 20, 772a937b6aaSMarkus Armbruster# where 0 means no compression, 1 means the best compression 773a937b6aaSMarkus Armbruster# speed, and 20 means best compression ratio which will consume 774a937b6aaSMarkus Armbruster# more CPU. Defaults to 1. (Since 5.0) 775abb6295bSLeonardo Bras# 77631e4c354SMax Reitz# @block-bitmap-mapping: Maps block nodes and bitmaps on them to 777a937b6aaSMarkus Armbruster# aliases for the purpose of dirty bitmap migration. Such aliases 778a937b6aaSMarkus Armbruster# may for example be the corresponding names on the opposite site. 779a937b6aaSMarkus Armbruster# The mapping must be one-to-one, but not necessarily complete: On 780a937b6aaSMarkus Armbruster# the source, unmapped bitmaps and all bitmaps on unmapped nodes 781a937b6aaSMarkus Armbruster# will be ignored. On the destination, encountering an unmapped 782a937b6aaSMarkus Armbruster# alias in the incoming migration stream will result in a report, 783a937b6aaSMarkus Armbruster# and all further bitmap migration data will then be discarded. 784a937b6aaSMarkus Armbruster# Note that the destination does not know about bitmaps it does 785a937b6aaSMarkus Armbruster# not receive, so there is no limitation or requirement regarding 786a937b6aaSMarkus Armbruster# the number of bitmaps received, or how they are named, or on 787a937b6aaSMarkus Armbruster# which nodes they are placed. By default (when this parameter 788a937b6aaSMarkus Armbruster# has never been set), bitmap names are mapped to themselves. 789a937b6aaSMarkus Armbruster# Nodes are mapped to their block device name if there is one, and 790a937b6aaSMarkus Armbruster# to their node name otherwise. (Since 5.2) 79131e4c354SMax Reitz# 7929fb49daaSMarkus Armbruster# Features: 793a937b6aaSMarkus Armbruster# 7949fb49daaSMarkus Armbruster# @unstable: Member @x-checkpoint-delay is experimental. 7959fb49daaSMarkus Armbruster# 79648685a8eSMarkus Armbruster# Since: 2.4 79748685a8eSMarkus Armbruster## 79848685a8eSMarkus Armbruster{ 'enum': 'MigrationParameter', 799ee3d96baSDr. David Alan Gilbert 'data': ['announce-initial', 'announce-max', 800ee3d96baSDr. David Alan Gilbert 'announce-rounds', 'announce-step', 801ee3d96baSDr. David Alan Gilbert 'compress-level', 'compress-threads', 'decompress-threads', 802dc14a470SKeqian Zhu 'compress-wait-thread', 'throttle-trigger-threshold', 80348685a8eSMarkus Armbruster 'cpu-throttle-initial', 'cpu-throttle-increment', 804cbbf8182SKeqian Zhu 'cpu-throttle-tailslow', 805d2f1d29bSDaniel P. Berrange 'tls-creds', 'tls-hostname', 'tls-authz', 'max-bandwidth', 8069fb49daaSMarkus Armbruster 'downtime-limit', 8079fb49daaSMarkus Armbruster { 'name': 'x-checkpoint-delay', 'features': [ 'unstable' ] }, 8089fb49daaSMarkus Armbruster 'block-incremental', 809cbfd6c95SJuan Quintela 'multifd-channels', 8104cbc9c7fSLi Qiang 'xbzrle-cache-size', 'max-postcopy-bandwidth', 8119004db48SJuan Quintela 'max-cpu-throttle', 'multifd-compression', 81231e4c354SMax Reitz 'multifd-zlib-level' ,'multifd-zstd-level', 81331e4c354SMax Reitz 'block-bitmap-mapping' ] } 81448685a8eSMarkus Armbruster 81548685a8eSMarkus Armbruster## 81648685a8eSMarkus Armbruster# @MigrateSetParameters: 81748685a8eSMarkus Armbruster# 818a937b6aaSMarkus Armbruster# @announce-initial: Initial delay (in milliseconds) before sending 819a937b6aaSMarkus Armbruster# the first announce (Since 4.0) 820ee3d96baSDr. David Alan Gilbert# 821a937b6aaSMarkus Armbruster# @announce-max: Maximum delay (in milliseconds) between packets in 822a937b6aaSMarkus Armbruster# the announcement (Since 4.0) 823ee3d96baSDr. David Alan Gilbert# 824a937b6aaSMarkus Armbruster# @announce-rounds: Number of self-announce packets sent after 825a937b6aaSMarkus Armbruster# migration (Since 4.0) 826ee3d96baSDr. David Alan Gilbert# 827a937b6aaSMarkus Armbruster# @announce-step: Increase in delay (in milliseconds) between 828a937b6aaSMarkus Armbruster# subsequent packets in the announcement (Since 4.0) 829ee3d96baSDr. David Alan Gilbert# 83048685a8eSMarkus Armbruster# @compress-level: compression level 83148685a8eSMarkus Armbruster# 83248685a8eSMarkus Armbruster# @compress-threads: compression thread count 83348685a8eSMarkus Armbruster# 834a937b6aaSMarkus Armbruster# @compress-wait-thread: Controls behavior when all compression 835a937b6aaSMarkus Armbruster# threads are currently busy. If true (default), wait for a free 836a937b6aaSMarkus Armbruster# compression thread to become available; otherwise, send the page 837a937b6aaSMarkus Armbruster# uncompressed. (Since 3.1) 8381d58872aSXiao Guangrong# 83948685a8eSMarkus Armbruster# @decompress-threads: decompression thread count 84048685a8eSMarkus Armbruster# 841a937b6aaSMarkus Armbruster# @throttle-trigger-threshold: The ratio of bytes_dirty_period and 842a937b6aaSMarkus Armbruster# bytes_xfer_period to trigger throttling. It is expressed as 843a937b6aaSMarkus Armbruster# percentage. The default value is 50. (Since 5.0) 844dc14a470SKeqian Zhu# 84548685a8eSMarkus Armbruster# @cpu-throttle-initial: Initial percentage of time guest cpus are 846a937b6aaSMarkus Armbruster# throttled when migration auto-converge is activated. The 847a937b6aaSMarkus Armbruster# default value is 20. (Since 2.7) 84848685a8eSMarkus Armbruster# 84948685a8eSMarkus Armbruster# @cpu-throttle-increment: throttle percentage increase each time 850a937b6aaSMarkus Armbruster# auto-converge detects that migration is not making progress. 851a937b6aaSMarkus Armbruster# The default value is 10. (Since 2.7) 85248685a8eSMarkus Armbruster# 853a937b6aaSMarkus Armbruster# @cpu-throttle-tailslow: Make CPU throttling slower at tail stage At 854a937b6aaSMarkus Armbruster# the tail stage of throttling, the Guest is very sensitive to CPU 855a937b6aaSMarkus Armbruster# percentage while the @cpu-throttle -increment is excessive 856a937b6aaSMarkus Armbruster# usually at tail stage. If this parameter is true, we will 857a937b6aaSMarkus Armbruster# compute the ideal CPU percentage used by the Guest, which may 858a937b6aaSMarkus Armbruster# exactly make the dirty rate match the dirty rate threshold. 859a937b6aaSMarkus Armbruster# Then we will choose a smaller throttle increment between the one 860a937b6aaSMarkus Armbruster# specified by @cpu-throttle-increment and the one generated by 861a937b6aaSMarkus Armbruster# ideal CPU percentage. Therefore, it is compatible to 862a937b6aaSMarkus Armbruster# traditional throttling, meanwhile the throttle increment won't 863a937b6aaSMarkus Armbruster# be excessive at tail stage. The default value is false. (Since 864a937b6aaSMarkus Armbruster# 5.1) 865cbbf8182SKeqian Zhu# 86648685a8eSMarkus Armbruster# @tls-creds: ID of the 'tls-creds' object that provides credentials 86748685a8eSMarkus Armbruster# for establishing a TLS connection over the migration data 86848685a8eSMarkus Armbruster# channel. On the outgoing side of the migration, the credentials 86948685a8eSMarkus Armbruster# must be for a 'client' endpoint, while for the incoming side the 870a937b6aaSMarkus Armbruster# credentials must be for a 'server' endpoint. Setting this to a 871a937b6aaSMarkus Armbruster# non-empty string enables TLS for all migrations. An empty 872a937b6aaSMarkus Armbruster# string means that QEMU will use plain text mode for migration, 873a937b6aaSMarkus Armbruster# rather than TLS (Since 2.9) Previously (since 2.7), this was 874a937b6aaSMarkus Armbruster# reported by omitting tls-creds instead. 87548685a8eSMarkus Armbruster# 87648685a8eSMarkus Armbruster# @tls-hostname: hostname of the target host for the migration. This 87748685a8eSMarkus Armbruster# is required when using x509 based TLS credentials and the 878a937b6aaSMarkus Armbruster# migration URI does not already include a hostname. For example 879a937b6aaSMarkus Armbruster# if using fd: or exec: based migration, the hostname must be 880a937b6aaSMarkus Armbruster# provided so that the server's x509 certificate identity can be 881a937b6aaSMarkus Armbruster# validated. (Since 2.7) An empty string means that QEMU will use 882a937b6aaSMarkus Armbruster# the hostname associated with the migration URI, if any. (Since 883a937b6aaSMarkus Armbruster# 2.9) Previously (since 2.7), this was reported by omitting 88448685a8eSMarkus Armbruster# tls-hostname instead. 88548685a8eSMarkus Armbruster# 886a937b6aaSMarkus Armbruster# @max-bandwidth: to set maximum speed for migration. maximum speed 887a937b6aaSMarkus Armbruster# in bytes per second. (Since 2.8) 88848685a8eSMarkus Armbruster# 889a937b6aaSMarkus Armbruster# @downtime-limit: set maximum tolerated downtime for migration. 890a937b6aaSMarkus Armbruster# maximum downtime in milliseconds (Since 2.8) 89148685a8eSMarkus Armbruster# 892a937b6aaSMarkus Armbruster# @x-checkpoint-delay: the delay time between two COLO checkpoints. 893a937b6aaSMarkus Armbruster# (Since 2.8) 89448685a8eSMarkus Armbruster# 89548685a8eSMarkus Armbruster# @block-incremental: Affects how much storage is migrated when the 89648685a8eSMarkus Armbruster# block migration capability is enabled. When false, the entire 897a937b6aaSMarkus Armbruster# storage backing chain is migrated into a flattened image at the 898a937b6aaSMarkus Armbruster# destination; when true, only the active qcow2 layer is migrated 899a937b6aaSMarkus Armbruster# and the destination must already have access to the same backing 900a937b6aaSMarkus Armbruster# chain as was used on the source. (since 2.10) 90148685a8eSMarkus Armbruster# 902cbfd6c95SJuan Quintela# @multifd-channels: Number of channels used to migrate data in 903a937b6aaSMarkus Armbruster# parallel. This is the same number that the number of sockets 904a937b6aaSMarkus Armbruster# used for migration. The default value is 2 (since 4.0) 9054075fb1cSJuan Quintela# 90673af8dd8SJuan Quintela# @xbzrle-cache-size: cache size to be used by XBZRLE migration. It 907a937b6aaSMarkus Armbruster# needs to be a multiple of the target page size and a power of 2 90873af8dd8SJuan Quintela# (Since 2.11) 9097e555c6cSDr. David Alan Gilbert# 910a937b6aaSMarkus Armbruster# @max-postcopy-bandwidth: Background transfer bandwidth during 911a937b6aaSMarkus Armbruster# postcopy. Defaults to 0 (unlimited). In bytes per second. 9127e555c6cSDr. David Alan Gilbert# (Since 3.0) 9134cbc9c7fSLi Qiang# 914a937b6aaSMarkus Armbruster# @max-cpu-throttle: maximum cpu throttle percentage. The default 915a937b6aaSMarkus Armbruster# value is 99. (Since 3.1) 9164cbc9c7fSLi Qiang# 917a937b6aaSMarkus Armbruster# @multifd-compression: Which compression method to use. Defaults to 918a937b6aaSMarkus Armbruster# none. (Since 5.0) 91996eef042SJuan Quintela# 9209004db48SJuan Quintela# @multifd-zlib-level: Set the compression level to be used in live 921a937b6aaSMarkus Armbruster# migration, the compression level is an integer between 0 and 9, 922a937b6aaSMarkus Armbruster# where 0 means no compression, 1 means the best compression 923a937b6aaSMarkus Armbruster# speed, and 9 means best compression ratio which will consume 924a937b6aaSMarkus Armbruster# more CPU. Defaults to 1. (Since 5.0) 9259004db48SJuan Quintela# 9266a9ad154SJuan Quintela# @multifd-zstd-level: Set the compression level to be used in live 927a937b6aaSMarkus Armbruster# migration, the compression level is an integer between 0 and 20, 928a937b6aaSMarkus Armbruster# where 0 means no compression, 1 means the best compression 929a937b6aaSMarkus Armbruster# speed, and 20 means best compression ratio which will consume 930a937b6aaSMarkus Armbruster# more CPU. Defaults to 1. (Since 5.0) 9316a9ad154SJuan Quintela# 93231e4c354SMax Reitz# @block-bitmap-mapping: Maps block nodes and bitmaps on them to 933a937b6aaSMarkus Armbruster# aliases for the purpose of dirty bitmap migration. Such aliases 934a937b6aaSMarkus Armbruster# may for example be the corresponding names on the opposite site. 935a937b6aaSMarkus Armbruster# The mapping must be one-to-one, but not necessarily complete: On 936a937b6aaSMarkus Armbruster# the source, unmapped bitmaps and all bitmaps on unmapped nodes 937a937b6aaSMarkus Armbruster# will be ignored. On the destination, encountering an unmapped 938a937b6aaSMarkus Armbruster# alias in the incoming migration stream will result in a report, 939a937b6aaSMarkus Armbruster# and all further bitmap migration data will then be discarded. 940a937b6aaSMarkus Armbruster# Note that the destination does not know about bitmaps it does 941a937b6aaSMarkus Armbruster# not receive, so there is no limitation or requirement regarding 942a937b6aaSMarkus Armbruster# the number of bitmaps received, or how they are named, or on 943a937b6aaSMarkus Armbruster# which nodes they are placed. By default (when this parameter 944a937b6aaSMarkus Armbruster# has never been set), bitmap names are mapped to themselves. 945a937b6aaSMarkus Armbruster# Nodes are mapped to their block device name if there is one, and 946a937b6aaSMarkus Armbruster# to their node name otherwise. (Since 5.2) 94731e4c354SMax Reitz# 9489fb49daaSMarkus Armbruster# Features: 949a937b6aaSMarkus Armbruster# 9509fb49daaSMarkus Armbruster# @unstable: Member @x-checkpoint-delay is experimental. 9519fb49daaSMarkus Armbruster# 95256266c6dSMarkus Armbruster# TODO: either fuse back into MigrationParameters, or make 95356266c6dSMarkus Armbruster# MigrationParameters members mandatory 95456266c6dSMarkus Armbruster# 95548685a8eSMarkus Armbruster# Since: 2.4 95648685a8eSMarkus Armbruster## 95748685a8eSMarkus Armbruster{ 'struct': 'MigrateSetParameters', 958ee3d96baSDr. David Alan Gilbert 'data': { '*announce-initial': 'size', 959ee3d96baSDr. David Alan Gilbert '*announce-max': 'size', 960ee3d96baSDr. David Alan Gilbert '*announce-rounds': 'size', 961ee3d96baSDr. David Alan Gilbert '*announce-step': 'size', 962ec17de0aSMarkus Armbruster '*compress-level': 'uint8', 963ec17de0aSMarkus Armbruster '*compress-threads': 'uint8', 9641d58872aSXiao Guangrong '*compress-wait-thread': 'bool', 965ec17de0aSMarkus Armbruster '*decompress-threads': 'uint8', 966ec17de0aSMarkus Armbruster '*throttle-trigger-threshold': 'uint8', 967ec17de0aSMarkus Armbruster '*cpu-throttle-initial': 'uint8', 968ec17de0aSMarkus Armbruster '*cpu-throttle-increment': 'uint8', 969cbbf8182SKeqian Zhu '*cpu-throttle-tailslow': 'bool', 97048685a8eSMarkus Armbruster '*tls-creds': 'StrOrNull', 97148685a8eSMarkus Armbruster '*tls-hostname': 'StrOrNull', 972d2f1d29bSDaniel P. Berrange '*tls-authz': 'StrOrNull', 973ec17de0aSMarkus Armbruster '*max-bandwidth': 'size', 974ec17de0aSMarkus Armbruster '*downtime-limit': 'uint64', 9759fb49daaSMarkus Armbruster '*x-checkpoint-delay': { 'type': 'uint32', 9769fb49daaSMarkus Armbruster 'features': [ 'unstable' ] }, 9774075fb1cSJuan Quintela '*block-incremental': 'bool', 978ec17de0aSMarkus Armbruster '*multifd-channels': 'uint8', 9797e555c6cSDr. David Alan Gilbert '*xbzrle-cache-size': 'size', 9804cbc9c7fSLi Qiang '*max-postcopy-bandwidth': 'size', 981ec17de0aSMarkus Armbruster '*max-cpu-throttle': 'uint8', 9829004db48SJuan Quintela '*multifd-compression': 'MultiFDCompression', 983ec17de0aSMarkus Armbruster '*multifd-zlib-level': 'uint8', 984ec17de0aSMarkus Armbruster '*multifd-zstd-level': 'uint8', 98531e4c354SMax Reitz '*block-bitmap-mapping': [ 'BitmapMigrationNodeAlias' ] } } 98648685a8eSMarkus Armbruster 98748685a8eSMarkus Armbruster## 98848685a8eSMarkus Armbruster# @migrate-set-parameters: 98948685a8eSMarkus Armbruster# 99048685a8eSMarkus Armbruster# Set various migration parameters. 99148685a8eSMarkus Armbruster# 99248685a8eSMarkus Armbruster# Since: 2.4 99348685a8eSMarkus Armbruster# 99448685a8eSMarkus Armbruster# Example: 99548685a8eSMarkus Armbruster# 99648685a8eSMarkus Armbruster# -> { "execute": "migrate-set-parameters" , 99748685a8eSMarkus Armbruster# "arguments": { "compress-level": 1 } } 99837fa48a4SMarkus Armbruster# <- { "return": {} } 99948685a8eSMarkus Armbruster## 100048685a8eSMarkus Armbruster{ 'command': 'migrate-set-parameters', 'boxed': true, 100148685a8eSMarkus Armbruster 'data': 'MigrateSetParameters' } 100248685a8eSMarkus Armbruster 100348685a8eSMarkus Armbruster## 100448685a8eSMarkus Armbruster# @MigrationParameters: 100548685a8eSMarkus Armbruster# 100648685a8eSMarkus Armbruster# The optional members aren't actually optional. 100748685a8eSMarkus Armbruster# 1008a937b6aaSMarkus Armbruster# @announce-initial: Initial delay (in milliseconds) before sending 1009a937b6aaSMarkus Armbruster# the first announce (Since 4.0) 1010ee3d96baSDr. David Alan Gilbert# 1011a937b6aaSMarkus Armbruster# @announce-max: Maximum delay (in milliseconds) between packets in 1012a937b6aaSMarkus Armbruster# the announcement (Since 4.0) 1013ee3d96baSDr. David Alan Gilbert# 1014a937b6aaSMarkus Armbruster# @announce-rounds: Number of self-announce packets sent after 1015a937b6aaSMarkus Armbruster# migration (Since 4.0) 1016ee3d96baSDr. David Alan Gilbert# 1017a937b6aaSMarkus Armbruster# @announce-step: Increase in delay (in milliseconds) between 1018a937b6aaSMarkus Armbruster# subsequent packets in the announcement (Since 4.0) 1019ee3d96baSDr. David Alan Gilbert# 102048685a8eSMarkus Armbruster# @compress-level: compression level 102148685a8eSMarkus Armbruster# 102248685a8eSMarkus Armbruster# @compress-threads: compression thread count 102348685a8eSMarkus Armbruster# 1024a937b6aaSMarkus Armbruster# @compress-wait-thread: Controls behavior when all compression 1025a937b6aaSMarkus Armbruster# threads are currently busy. If true (default), wait for a free 1026a937b6aaSMarkus Armbruster# compression thread to become available; otherwise, send the page 1027a937b6aaSMarkus Armbruster# uncompressed. (Since 3.1) 10281d58872aSXiao Guangrong# 102948685a8eSMarkus Armbruster# @decompress-threads: decompression thread count 103048685a8eSMarkus Armbruster# 1031a937b6aaSMarkus Armbruster# @throttle-trigger-threshold: The ratio of bytes_dirty_period and 1032a937b6aaSMarkus Armbruster# bytes_xfer_period to trigger throttling. It is expressed as 1033a937b6aaSMarkus Armbruster# percentage. The default value is 50. (Since 5.0) 1034dc14a470SKeqian Zhu# 103548685a8eSMarkus Armbruster# @cpu-throttle-initial: Initial percentage of time guest cpus are 1036a937b6aaSMarkus Armbruster# throttled when migration auto-converge is activated. (Since 1037a937b6aaSMarkus Armbruster# 2.7) 103848685a8eSMarkus Armbruster# 103948685a8eSMarkus Armbruster# @cpu-throttle-increment: throttle percentage increase each time 1040a937b6aaSMarkus Armbruster# auto-converge detects that migration is not making progress. 1041a937b6aaSMarkus Armbruster# (Since 2.7) 104248685a8eSMarkus Armbruster# 1043a937b6aaSMarkus Armbruster# @cpu-throttle-tailslow: Make CPU throttling slower at tail stage At 1044a937b6aaSMarkus Armbruster# the tail stage of throttling, the Guest is very sensitive to CPU 1045a937b6aaSMarkus Armbruster# percentage while the @cpu-throttle -increment is excessive 1046a937b6aaSMarkus Armbruster# usually at tail stage. If this parameter is true, we will 1047a937b6aaSMarkus Armbruster# compute the ideal CPU percentage used by the Guest, which may 1048a937b6aaSMarkus Armbruster# exactly make the dirty rate match the dirty rate threshold. 1049a937b6aaSMarkus Armbruster# Then we will choose a smaller throttle increment between the one 1050a937b6aaSMarkus Armbruster# specified by @cpu-throttle-increment and the one generated by 1051a937b6aaSMarkus Armbruster# ideal CPU percentage. Therefore, it is compatible to 1052a937b6aaSMarkus Armbruster# traditional throttling, meanwhile the throttle increment won't 1053a937b6aaSMarkus Armbruster# be excessive at tail stage. The default value is false. (Since 1054a937b6aaSMarkus Armbruster# 5.1) 1055cbbf8182SKeqian Zhu# 105648685a8eSMarkus Armbruster# @tls-creds: ID of the 'tls-creds' object that provides credentials 105748685a8eSMarkus Armbruster# for establishing a TLS connection over the migration data 105848685a8eSMarkus Armbruster# channel. On the outgoing side of the migration, the credentials 105948685a8eSMarkus Armbruster# must be for a 'client' endpoint, while for the incoming side the 1060a937b6aaSMarkus Armbruster# credentials must be for a 'server' endpoint. An empty string 1061a937b6aaSMarkus Armbruster# means that QEMU will use plain text mode for migration, rather 1062a937b6aaSMarkus Armbruster# than TLS (Since 2.7) Note: 2.8 reports this by omitting 1063a937b6aaSMarkus Armbruster# tls-creds instead. 106448685a8eSMarkus Armbruster# 106548685a8eSMarkus Armbruster# @tls-hostname: hostname of the target host for the migration. This 106648685a8eSMarkus Armbruster# is required when using x509 based TLS credentials and the 1067a937b6aaSMarkus Armbruster# migration URI does not already include a hostname. For example 1068a937b6aaSMarkus Armbruster# if using fd: or exec: based migration, the hostname must be 1069a937b6aaSMarkus Armbruster# provided so that the server's x509 certificate identity can be 1070a937b6aaSMarkus Armbruster# validated. (Since 2.7) An empty string means that QEMU will use 1071a937b6aaSMarkus Armbruster# the hostname associated with the migration URI, if any. (Since 1072a937b6aaSMarkus Armbruster# 2.9) Note: 2.8 reports this by omitting tls-hostname instead. 107348685a8eSMarkus Armbruster# 1074a937b6aaSMarkus Armbruster# @tls-authz: ID of the 'authz' object subclass that provides access 1075a937b6aaSMarkus Armbruster# control checking of the TLS x509 certificate distinguished name. 1076a937b6aaSMarkus Armbruster# (Since 4.0) 1077d2f1d29bSDaniel P. Berrange# 1078a937b6aaSMarkus Armbruster# @max-bandwidth: to set maximum speed for migration. maximum speed 1079a937b6aaSMarkus Armbruster# in bytes per second. (Since 2.8) 108048685a8eSMarkus Armbruster# 1081a937b6aaSMarkus Armbruster# @downtime-limit: set maximum tolerated downtime for migration. 1082a937b6aaSMarkus Armbruster# maximum downtime in milliseconds (Since 2.8) 108348685a8eSMarkus Armbruster# 1084a937b6aaSMarkus Armbruster# @x-checkpoint-delay: the delay time between two COLO checkpoints. 1085a937b6aaSMarkus Armbruster# (Since 2.8) 108648685a8eSMarkus Armbruster# 108748685a8eSMarkus Armbruster# @block-incremental: Affects how much storage is migrated when the 108848685a8eSMarkus Armbruster# block migration capability is enabled. When false, the entire 1089a937b6aaSMarkus Armbruster# storage backing chain is migrated into a flattened image at the 1090a937b6aaSMarkus Armbruster# destination; when true, only the active qcow2 layer is migrated 1091a937b6aaSMarkus Armbruster# and the destination must already have access to the same backing 1092a937b6aaSMarkus Armbruster# chain as was used on the source. (since 2.10) 109348685a8eSMarkus Armbruster# 1094cbfd6c95SJuan Quintela# @multifd-channels: Number of channels used to migrate data in 1095a937b6aaSMarkus Armbruster# parallel. This is the same number that the number of sockets 1096a937b6aaSMarkus Armbruster# used for migration. The default value is 2 (since 4.0) 10974075fb1cSJuan Quintela# 109873af8dd8SJuan Quintela# @xbzrle-cache-size: cache size to be used by XBZRLE migration. It 1099a937b6aaSMarkus Armbruster# needs to be a multiple of the target page size and a power of 2 110073af8dd8SJuan Quintela# (Since 2.11) 11017e555c6cSDr. David Alan Gilbert# 1102a937b6aaSMarkus Armbruster# @max-postcopy-bandwidth: Background transfer bandwidth during 1103a937b6aaSMarkus Armbruster# postcopy. Defaults to 0 (unlimited). In bytes per second. 11047e555c6cSDr. David Alan Gilbert# (Since 3.0) 11054cbc9c7fSLi Qiang# 1106a937b6aaSMarkus Armbruster# @max-cpu-throttle: maximum cpu throttle percentage. Defaults to 99. 11074cbc9c7fSLi Qiang# (Since 3.1) 11084cbc9c7fSLi Qiang# 1109a937b6aaSMarkus Armbruster# @multifd-compression: Which compression method to use. Defaults to 1110a937b6aaSMarkus Armbruster# none. (Since 5.0) 111196eef042SJuan Quintela# 11129004db48SJuan Quintela# @multifd-zlib-level: Set the compression level to be used in live 1113a937b6aaSMarkus Armbruster# migration, the compression level is an integer between 0 and 9, 1114a937b6aaSMarkus Armbruster# where 0 means no compression, 1 means the best compression 1115a937b6aaSMarkus Armbruster# speed, and 9 means best compression ratio which will consume 1116a937b6aaSMarkus Armbruster# more CPU. Defaults to 1. (Since 5.0) 11179004db48SJuan Quintela# 11186a9ad154SJuan Quintela# @multifd-zstd-level: Set the compression level to be used in live 1119a937b6aaSMarkus Armbruster# migration, the compression level is an integer between 0 and 20, 1120a937b6aaSMarkus Armbruster# where 0 means no compression, 1 means the best compression 1121a937b6aaSMarkus Armbruster# speed, and 20 means best compression ratio which will consume 1122a937b6aaSMarkus Armbruster# more CPU. Defaults to 1. (Since 5.0) 11236a9ad154SJuan Quintela# 112431e4c354SMax Reitz# @block-bitmap-mapping: Maps block nodes and bitmaps on them to 1125a937b6aaSMarkus Armbruster# aliases for the purpose of dirty bitmap migration. Such aliases 1126a937b6aaSMarkus Armbruster# may for example be the corresponding names on the opposite site. 1127a937b6aaSMarkus Armbruster# The mapping must be one-to-one, but not necessarily complete: On 1128a937b6aaSMarkus Armbruster# the source, unmapped bitmaps and all bitmaps on unmapped nodes 1129a937b6aaSMarkus Armbruster# will be ignored. On the destination, encountering an unmapped 1130a937b6aaSMarkus Armbruster# alias in the incoming migration stream will result in a report, 1131a937b6aaSMarkus Armbruster# and all further bitmap migration data will then be discarded. 1132a937b6aaSMarkus Armbruster# Note that the destination does not know about bitmaps it does 1133a937b6aaSMarkus Armbruster# not receive, so there is no limitation or requirement regarding 1134a937b6aaSMarkus Armbruster# the number of bitmaps received, or how they are named, or on 1135a937b6aaSMarkus Armbruster# which nodes they are placed. By default (when this parameter 1136a937b6aaSMarkus Armbruster# has never been set), bitmap names are mapped to themselves. 1137a937b6aaSMarkus Armbruster# Nodes are mapped to their block device name if there is one, and 1138a937b6aaSMarkus Armbruster# to their node name otherwise. (Since 5.2) 113931e4c354SMax Reitz# 11409fb49daaSMarkus Armbruster# Features: 1141a937b6aaSMarkus Armbruster# 11429fb49daaSMarkus Armbruster# @unstable: Member @x-checkpoint-delay is experimental. 11439fb49daaSMarkus Armbruster# 114448685a8eSMarkus Armbruster# Since: 2.4 114548685a8eSMarkus Armbruster## 114648685a8eSMarkus Armbruster{ 'struct': 'MigrationParameters', 1147ee3d96baSDr. David Alan Gilbert 'data': { '*announce-initial': 'size', 1148ee3d96baSDr. David Alan Gilbert '*announce-max': 'size', 1149ee3d96baSDr. David Alan Gilbert '*announce-rounds': 'size', 1150ee3d96baSDr. David Alan Gilbert '*announce-step': 'size', 1151ee3d96baSDr. David Alan Gilbert '*compress-level': 'uint8', 1152741d4086SJuan Quintela '*compress-threads': 'uint8', 11531d58872aSXiao Guangrong '*compress-wait-thread': 'bool', 1154741d4086SJuan Quintela '*decompress-threads': 'uint8', 1155dc14a470SKeqian Zhu '*throttle-trigger-threshold': 'uint8', 1156741d4086SJuan Quintela '*cpu-throttle-initial': 'uint8', 1157741d4086SJuan Quintela '*cpu-throttle-increment': 'uint8', 1158cbbf8182SKeqian Zhu '*cpu-throttle-tailslow': 'bool', 115948685a8eSMarkus Armbruster '*tls-creds': 'str', 116048685a8eSMarkus Armbruster '*tls-hostname': 'str', 1161d2f1d29bSDaniel P. Berrange '*tls-authz': 'str', 1162741d4086SJuan Quintela '*max-bandwidth': 'size', 1163741d4086SJuan Quintela '*downtime-limit': 'uint64', 11649fb49daaSMarkus Armbruster '*x-checkpoint-delay': { 'type': 'uint32', 11659fb49daaSMarkus Armbruster 'features': [ 'unstable' ] }, 11664075fb1cSJuan Quintela '*block-incremental': 'bool', 1167cbfd6c95SJuan Quintela '*multifd-channels': 'uint8', 11687e555c6cSDr. David Alan Gilbert '*xbzrle-cache-size': 'size', 11694cbc9c7fSLi Qiang '*max-postcopy-bandwidth': 'size', 117096eef042SJuan Quintela '*max-cpu-throttle': 'uint8', 11719004db48SJuan Quintela '*multifd-compression': 'MultiFDCompression', 11726a9ad154SJuan Quintela '*multifd-zlib-level': 'uint8', 117331e4c354SMax Reitz '*multifd-zstd-level': 'uint8', 117431e4c354SMax Reitz '*block-bitmap-mapping': [ 'BitmapMigrationNodeAlias' ] } } 117548685a8eSMarkus Armbruster 117648685a8eSMarkus Armbruster## 117748685a8eSMarkus Armbruster# @query-migrate-parameters: 117848685a8eSMarkus Armbruster# 117948685a8eSMarkus Armbruster# Returns information about the current migration parameters 118048685a8eSMarkus Armbruster# 118148685a8eSMarkus Armbruster# Returns: @MigrationParameters 118248685a8eSMarkus Armbruster# 118348685a8eSMarkus Armbruster# Since: 2.4 118448685a8eSMarkus Armbruster# 118548685a8eSMarkus Armbruster# Example: 118648685a8eSMarkus Armbruster# 118748685a8eSMarkus Armbruster# -> { "execute": "query-migrate-parameters" } 118848685a8eSMarkus Armbruster# <- { "return": { 118948685a8eSMarkus Armbruster# "decompress-threads": 2, 119048685a8eSMarkus Armbruster# "cpu-throttle-increment": 10, 119148685a8eSMarkus Armbruster# "compress-threads": 8, 119248685a8eSMarkus Armbruster# "compress-level": 1, 119348685a8eSMarkus Armbruster# "cpu-throttle-initial": 20, 119448685a8eSMarkus Armbruster# "max-bandwidth": 33554432, 119548685a8eSMarkus Armbruster# "downtime-limit": 300 119648685a8eSMarkus Armbruster# } 119748685a8eSMarkus Armbruster# } 119848685a8eSMarkus Armbruster## 119948685a8eSMarkus Armbruster{ 'command': 'query-migrate-parameters', 120048685a8eSMarkus Armbruster 'returns': 'MigrationParameters' } 120148685a8eSMarkus Armbruster 120248685a8eSMarkus Armbruster## 120348685a8eSMarkus Armbruster# @migrate-start-postcopy: 120448685a8eSMarkus Armbruster# 1205a937b6aaSMarkus Armbruster# Followup to a migration command to switch the migration to postcopy 1206a937b6aaSMarkus Armbruster# mode. The postcopy-ram capability must be set on both source and 1207a937b6aaSMarkus Armbruster# destination before the original migration command. 120848685a8eSMarkus Armbruster# 120948685a8eSMarkus Armbruster# Since: 2.5 121048685a8eSMarkus Armbruster# 121148685a8eSMarkus Armbruster# Example: 121248685a8eSMarkus Armbruster# 121348685a8eSMarkus Armbruster# -> { "execute": "migrate-start-postcopy" } 121448685a8eSMarkus Armbruster# <- { "return": {} } 121548685a8eSMarkus Armbruster## 121648685a8eSMarkus Armbruster{ 'command': 'migrate-start-postcopy' } 121748685a8eSMarkus Armbruster 121848685a8eSMarkus Armbruster## 121948685a8eSMarkus Armbruster# @MIGRATION: 122048685a8eSMarkus Armbruster# 122148685a8eSMarkus Armbruster# Emitted when a migration event happens 122248685a8eSMarkus Armbruster# 122348685a8eSMarkus Armbruster# @status: @MigrationStatus describing the current migration status. 122448685a8eSMarkus Armbruster# 122548685a8eSMarkus Armbruster# Since: 2.4 122648685a8eSMarkus Armbruster# 122748685a8eSMarkus Armbruster# Example: 122848685a8eSMarkus Armbruster# 122948685a8eSMarkus Armbruster# <- {"timestamp": {"seconds": 1432121972, "microseconds": 744001}, 123048685a8eSMarkus Armbruster# "event": "MIGRATION", 123148685a8eSMarkus Armbruster# "data": {"status": "completed"} } 123248685a8eSMarkus Armbruster## 123348685a8eSMarkus Armbruster{ 'event': 'MIGRATION', 123448685a8eSMarkus Armbruster 'data': {'status': 'MigrationStatus'}} 123548685a8eSMarkus Armbruster 123648685a8eSMarkus Armbruster## 123748685a8eSMarkus Armbruster# @MIGRATION_PASS: 123848685a8eSMarkus Armbruster# 1239a937b6aaSMarkus Armbruster# Emitted from the source side of a migration at the start of each 1240a937b6aaSMarkus Armbruster# pass (when it syncs the dirty bitmap) 124148685a8eSMarkus Armbruster# 124248685a8eSMarkus Armbruster# @pass: An incrementing count (starting at 1 on the first pass) 124348685a8eSMarkus Armbruster# 124448685a8eSMarkus Armbruster# Since: 2.6 124548685a8eSMarkus Armbruster# 124648685a8eSMarkus Armbruster# Example: 124748685a8eSMarkus Armbruster# 124837fa48a4SMarkus Armbruster# <- { "timestamp": {"seconds": 1449669631, "microseconds": 239225}, 124948685a8eSMarkus Armbruster# "event": "MIGRATION_PASS", "data": {"pass": 2} } 125048685a8eSMarkus Armbruster## 125148685a8eSMarkus Armbruster{ 'event': 'MIGRATION_PASS', 125248685a8eSMarkus Armbruster 'data': { 'pass': 'int' } } 125348685a8eSMarkus Armbruster 125448685a8eSMarkus Armbruster## 125548685a8eSMarkus Armbruster# @COLOMessage: 125648685a8eSMarkus Armbruster# 125748685a8eSMarkus Armbruster# The message transmission between Primary side and Secondary side. 125848685a8eSMarkus Armbruster# 125948685a8eSMarkus Armbruster# @checkpoint-ready: Secondary VM (SVM) is ready for checkpointing 126048685a8eSMarkus Armbruster# 1261a937b6aaSMarkus Armbruster# @checkpoint-request: Primary VM (PVM) tells SVM to prepare for 1262a937b6aaSMarkus Armbruster# checkpointing 126348685a8eSMarkus Armbruster# 126448685a8eSMarkus Armbruster# @checkpoint-reply: SVM gets PVM's checkpoint request 126548685a8eSMarkus Armbruster# 126648685a8eSMarkus Armbruster# @vmstate-send: VM's state will be sent by PVM. 126748685a8eSMarkus Armbruster# 126848685a8eSMarkus Armbruster# @vmstate-size: The total size of VMstate. 126948685a8eSMarkus Armbruster# 127048685a8eSMarkus Armbruster# @vmstate-received: VM's state has been received by SVM. 127148685a8eSMarkus Armbruster# 127248685a8eSMarkus Armbruster# @vmstate-loaded: VM's state has been loaded by SVM. 127348685a8eSMarkus Armbruster# 127448685a8eSMarkus Armbruster# Since: 2.8 127548685a8eSMarkus Armbruster## 127648685a8eSMarkus Armbruster{ 'enum': 'COLOMessage', 127748685a8eSMarkus Armbruster 'data': [ 'checkpoint-ready', 'checkpoint-request', 'checkpoint-reply', 127848685a8eSMarkus Armbruster 'vmstate-send', 'vmstate-size', 'vmstate-received', 127948685a8eSMarkus Armbruster 'vmstate-loaded' ] } 128048685a8eSMarkus Armbruster 128148685a8eSMarkus Armbruster## 128248685a8eSMarkus Armbruster# @COLOMode: 128348685a8eSMarkus Armbruster# 128441b6b779SZhang Chen# The COLO current mode. 128548685a8eSMarkus Armbruster# 128641b6b779SZhang Chen# @none: COLO is disabled. 128748685a8eSMarkus Armbruster# 128841b6b779SZhang Chen# @primary: COLO node in primary side. 128948685a8eSMarkus Armbruster# 129041b6b779SZhang Chen# @secondary: COLO node in slave side. 129148685a8eSMarkus Armbruster# 129248685a8eSMarkus Armbruster# Since: 2.8 129348685a8eSMarkus Armbruster## 129448685a8eSMarkus Armbruster{ 'enum': 'COLOMode', 129541b6b779SZhang Chen 'data': [ 'none', 'primary', 'secondary'] } 129648685a8eSMarkus Armbruster 129748685a8eSMarkus Armbruster## 129848685a8eSMarkus Armbruster# @FailoverStatus: 129948685a8eSMarkus Armbruster# 130048685a8eSMarkus Armbruster# An enumeration of COLO failover status 130148685a8eSMarkus Armbruster# 130248685a8eSMarkus Armbruster# @none: no failover has ever happened 130348685a8eSMarkus Armbruster# 130448685a8eSMarkus Armbruster# @require: got failover requirement but not handled 130548685a8eSMarkus Armbruster# 130648685a8eSMarkus Armbruster# @active: in the process of doing failover 130748685a8eSMarkus Armbruster# 130848685a8eSMarkus Armbruster# @completed: finish the process of failover 130948685a8eSMarkus Armbruster# 1310a937b6aaSMarkus Armbruster# @relaunch: restart the failover process, from 'none' -> 'completed' 1311a937b6aaSMarkus Armbruster# (Since 2.9) 131248685a8eSMarkus Armbruster# 131348685a8eSMarkus Armbruster# Since: 2.8 131448685a8eSMarkus Armbruster## 131548685a8eSMarkus Armbruster{ 'enum': 'FailoverStatus', 131648685a8eSMarkus Armbruster 'data': [ 'none', 'require', 'active', 'completed', 'relaunch' ] } 131748685a8eSMarkus Armbruster 131848685a8eSMarkus Armbruster## 13199ecff6d6Szhanghailiang# @COLO_EXIT: 13209ecff6d6Szhanghailiang# 13219ecff6d6Szhanghailiang# Emitted when VM finishes COLO mode due to some errors happening or 13229ecff6d6Szhanghailiang# at the request of users. 13239ecff6d6Szhanghailiang# 13249ecff6d6Szhanghailiang# @mode: report COLO mode when COLO exited. 13259ecff6d6Szhanghailiang# 13269ecff6d6Szhanghailiang# @reason: describes the reason for the COLO exit. 13279ecff6d6Szhanghailiang# 13289ecff6d6Szhanghailiang# Since: 3.1 13299ecff6d6Szhanghailiang# 13309ecff6d6Szhanghailiang# Example: 13319ecff6d6Szhanghailiang# 13329ecff6d6Szhanghailiang# <- { "timestamp": {"seconds": 2032141960, "microseconds": 417172}, 13339ecff6d6Szhanghailiang# "event": "COLO_EXIT", "data": {"mode": "primary", "reason": "request" } } 13349ecff6d6Szhanghailiang## 13359ecff6d6Szhanghailiang{ 'event': 'COLO_EXIT', 13369ecff6d6Szhanghailiang 'data': {'mode': 'COLOMode', 'reason': 'COLOExitReason' } } 13379ecff6d6Szhanghailiang 13389ecff6d6Szhanghailiang## 13399ecff6d6Szhanghailiang# @COLOExitReason: 13409ecff6d6Szhanghailiang# 13413a43ac47SZhang Chen# The reason for a COLO exit. 13429ecff6d6Szhanghailiang# 1343a937b6aaSMarkus Armbruster# @none: failover has never happened. This state does not occur in 1344a937b6aaSMarkus Armbruster# the COLO_EXIT event, and is only visible in the result of 13453a43ac47SZhang Chen# query-colo-status. 13469ecff6d6Szhanghailiang# 13473a43ac47SZhang Chen# @request: COLO exit is due to an external request. 13489ecff6d6Szhanghailiang# 13493a43ac47SZhang Chen# @error: COLO exit is due to an internal error. 13503a43ac47SZhang Chen# 13513a43ac47SZhang Chen# @processing: COLO is currently handling a failover (since 4.0). 13529ecff6d6Szhanghailiang# 13539ecff6d6Szhanghailiang# Since: 3.1 13549ecff6d6Szhanghailiang## 13559ecff6d6Szhanghailiang{ 'enum': 'COLOExitReason', 13563a43ac47SZhang Chen 'data': [ 'none', 'request', 'error' , 'processing' ] } 13579ecff6d6Szhanghailiang 13589ecff6d6Szhanghailiang## 135948685a8eSMarkus Armbruster# @x-colo-lost-heartbeat: 136048685a8eSMarkus Armbruster# 1361a937b6aaSMarkus Armbruster# Tell qemu that heartbeat is lost, request it to do takeover 1362a937b6aaSMarkus Armbruster# procedures. If this command is sent to the PVM, the Primary side 1363a937b6aaSMarkus Armbruster# will exit COLO mode. If sent to the Secondary, the Secondary side 1364a937b6aaSMarkus Armbruster# will run failover work, then takes over server operation to become 1365a937b6aaSMarkus Armbruster# the service VM. 136648685a8eSMarkus Armbruster# 13679fb49daaSMarkus Armbruster# Features: 1368a937b6aaSMarkus Armbruster# 13699fb49daaSMarkus Armbruster# @unstable: This command is experimental. 13709fb49daaSMarkus Armbruster# 137148685a8eSMarkus Armbruster# Since: 2.8 137248685a8eSMarkus Armbruster# 137348685a8eSMarkus Armbruster# Example: 137448685a8eSMarkus Armbruster# 137548685a8eSMarkus Armbruster# -> { "execute": "x-colo-lost-heartbeat" } 137648685a8eSMarkus Armbruster# <- { "return": {} } 137748685a8eSMarkus Armbruster## 13789fb49daaSMarkus Armbruster{ 'command': 'x-colo-lost-heartbeat', 137951e47cf8SVladimir Sementsov-Ogievskiy 'features': [ 'unstable' ], 138051e47cf8SVladimir Sementsov-Ogievskiy 'if': 'CONFIG_REPLICATION' } 138148685a8eSMarkus Armbruster 138248685a8eSMarkus Armbruster## 138348685a8eSMarkus Armbruster# @migrate_cancel: 138448685a8eSMarkus Armbruster# 138548685a8eSMarkus Armbruster# Cancel the current executing migration process. 138648685a8eSMarkus Armbruster# 138748685a8eSMarkus Armbruster# Returns: nothing on success 138848685a8eSMarkus Armbruster# 1389a937b6aaSMarkus Armbruster# Notes: This command succeeds even if there is no migration process 1390a937b6aaSMarkus Armbruster# running. 139148685a8eSMarkus Armbruster# 13929bc6e893SMarkus Armbruster# Since: 0.14 139348685a8eSMarkus Armbruster# 139448685a8eSMarkus Armbruster# Example: 139548685a8eSMarkus Armbruster# 139648685a8eSMarkus Armbruster# -> { "execute": "migrate_cancel" } 139748685a8eSMarkus Armbruster# <- { "return": {} } 139848685a8eSMarkus Armbruster## 139948685a8eSMarkus Armbruster{ 'command': 'migrate_cancel' } 140048685a8eSMarkus Armbruster 140148685a8eSMarkus Armbruster## 140289cfc02cSDr. David Alan Gilbert# @migrate-continue: 140389cfc02cSDr. David Alan Gilbert# 140489cfc02cSDr. David Alan Gilbert# Continue migration when it's in a paused state. 140589cfc02cSDr. David Alan Gilbert# 140689cfc02cSDr. David Alan Gilbert# @state: The state the migration is currently expected to be in 140789cfc02cSDr. David Alan Gilbert# 140889cfc02cSDr. David Alan Gilbert# Returns: nothing on success 14094ae65a52SAndrea Bolognani# 141089cfc02cSDr. David Alan Gilbert# Since: 2.11 14114ae65a52SAndrea Bolognani# 141289cfc02cSDr. David Alan Gilbert# Example: 141389cfc02cSDr. David Alan Gilbert# 141489cfc02cSDr. David Alan Gilbert# -> { "execute": "migrate-continue" , "arguments": 141589cfc02cSDr. David Alan Gilbert# { "state": "pre-switchover" } } 141689cfc02cSDr. David Alan Gilbert# <- { "return": {} } 141789cfc02cSDr. David Alan Gilbert## 141889cfc02cSDr. David Alan Gilbert{ 'command': 'migrate-continue', 'data': {'state': 'MigrationStatus'} } 141989cfc02cSDr. David Alan Gilbert 142089cfc02cSDr. David Alan Gilbert## 142148685a8eSMarkus Armbruster# @migrate: 142248685a8eSMarkus Armbruster# 142348685a8eSMarkus Armbruster# Migrates the current running guest to another Virtual Machine. 142448685a8eSMarkus Armbruster# 142548685a8eSMarkus Armbruster# @uri: the Uniform Resource Identifier of the destination VM 142648685a8eSMarkus Armbruster# 142748685a8eSMarkus Armbruster# @blk: do block migration (full disk copy) 142848685a8eSMarkus Armbruster# 142948685a8eSMarkus Armbruster# @inc: incremental disk copy migration 143048685a8eSMarkus Armbruster# 1431a937b6aaSMarkus Armbruster# @detach: this argument exists only for compatibility reasons and is 1432a937b6aaSMarkus Armbruster# ignored by QEMU 143348685a8eSMarkus Armbruster# 143451f63ec7SPeter Maydell# @resume: resume one paused migration, default "off". (since 3.0) 14357a4da28bSPeter Xu# 143648685a8eSMarkus Armbruster# Returns: nothing on success 143748685a8eSMarkus Armbruster# 14389bc6e893SMarkus Armbruster# Since: 0.14 143948685a8eSMarkus Armbruster# 144048685a8eSMarkus Armbruster# Notes: 144148685a8eSMarkus Armbruster# 1442a937b6aaSMarkus Armbruster# 1. The 'query-migrate' command should be used to check migration's 1443a937b6aaSMarkus Armbruster# progress and final result (this information is provided by the 1444a937b6aaSMarkus Armbruster# 'status' member) 144548685a8eSMarkus Armbruster# 144648685a8eSMarkus Armbruster# 2. All boolean arguments default to false 144748685a8eSMarkus Armbruster# 1448a937b6aaSMarkus Armbruster# 3. The user Monitor's "detach" argument is invalid in QMP and should 1449a937b6aaSMarkus Armbruster# not be used 145048685a8eSMarkus Armbruster# 145148685a8eSMarkus Armbruster# Example: 145248685a8eSMarkus Armbruster# 145348685a8eSMarkus Armbruster# -> { "execute": "migrate", "arguments": { "uri": "tcp:0:4446" } } 145448685a8eSMarkus Armbruster# <- { "return": {} } 145548685a8eSMarkus Armbruster## 145648685a8eSMarkus Armbruster{ 'command': 'migrate', 14577a4da28bSPeter Xu 'data': {'uri': 'str', '*blk': 'bool', '*inc': 'bool', 14587a4da28bSPeter Xu '*detach': 'bool', '*resume': 'bool' } } 145948685a8eSMarkus Armbruster 146048685a8eSMarkus Armbruster## 146148685a8eSMarkus Armbruster# @migrate-incoming: 146248685a8eSMarkus Armbruster# 1463a937b6aaSMarkus Armbruster# Start an incoming migration, the qemu must have been started with 1464a937b6aaSMarkus Armbruster# -incoming defer 146548685a8eSMarkus Armbruster# 146648685a8eSMarkus Armbruster# @uri: The Uniform Resource Identifier identifying the source or 146748685a8eSMarkus Armbruster# address to listen on 146848685a8eSMarkus Armbruster# 146948685a8eSMarkus Armbruster# Returns: nothing on success 147048685a8eSMarkus Armbruster# 147148685a8eSMarkus Armbruster# Since: 2.3 147248685a8eSMarkus Armbruster# 147348685a8eSMarkus Armbruster# Notes: 147448685a8eSMarkus Armbruster# 1475a937b6aaSMarkus Armbruster# 1. It's a bad idea to use a string for the uri, but it needs 1476a937b6aaSMarkus Armbruster# to stay compatible with -incoming and the format of the uri 1477a937b6aaSMarkus Armbruster# is already exposed above libvirt. 147848685a8eSMarkus Armbruster# 1479a937b6aaSMarkus Armbruster# 2. QEMU must be started with -incoming defer to allow 1480a937b6aaSMarkus Armbruster# migrate-incoming to be used. 148148685a8eSMarkus Armbruster# 148248685a8eSMarkus Armbruster# 3. The uri format is the same as for -incoming 148348685a8eSMarkus Armbruster# 148448685a8eSMarkus Armbruster# Example: 148548685a8eSMarkus Armbruster# 148648685a8eSMarkus Armbruster# -> { "execute": "migrate-incoming", 148748685a8eSMarkus Armbruster# "arguments": { "uri": "tcp::4446" } } 148848685a8eSMarkus Armbruster# <- { "return": {} } 148948685a8eSMarkus Armbruster## 149048685a8eSMarkus Armbruster{ 'command': 'migrate-incoming', 'data': {'uri': 'str' } } 149148685a8eSMarkus Armbruster 149248685a8eSMarkus Armbruster## 149348685a8eSMarkus Armbruster# @xen-save-devices-state: 149448685a8eSMarkus Armbruster# 1495a937b6aaSMarkus Armbruster# Save the state of all devices to file. The RAM and the block 1496a937b6aaSMarkus Armbruster# devices of the VM are not saved by this command. 149748685a8eSMarkus Armbruster# 149848685a8eSMarkus Armbruster# @filename: the file to save the state of the devices to as binary 1499a937b6aaSMarkus Armbruster# data. See xen-save-devices-state.txt for a description of the 1500a937b6aaSMarkus Armbruster# binary format. 150148685a8eSMarkus Armbruster# 1502a937b6aaSMarkus Armbruster# @live: Optional argument to ask QEMU to treat this command as part 1503a937b6aaSMarkus Armbruster# of a live migration. Default to true. (since 2.11) 15045d6c599fSAnthony PERARD# 150548685a8eSMarkus Armbruster# Returns: Nothing on success 150648685a8eSMarkus Armbruster# 150748685a8eSMarkus Armbruster# Since: 1.1 150848685a8eSMarkus Armbruster# 150948685a8eSMarkus Armbruster# Example: 151048685a8eSMarkus Armbruster# 151148685a8eSMarkus Armbruster# -> { "execute": "xen-save-devices-state", 151248685a8eSMarkus Armbruster# "arguments": { "filename": "/tmp/save" } } 151348685a8eSMarkus Armbruster# <- { "return": {} } 151448685a8eSMarkus Armbruster## 15155d6c599fSAnthony PERARD{ 'command': 'xen-save-devices-state', 15165d6c599fSAnthony PERARD 'data': {'filename': 'str', '*live':'bool' } } 151748685a8eSMarkus Armbruster 151848685a8eSMarkus Armbruster## 151928af9ba2SPhilippe Mathieu-Daudé# @xen-set-global-dirty-log: 152028af9ba2SPhilippe Mathieu-Daudé# 152128af9ba2SPhilippe Mathieu-Daudé# Enable or disable the global dirty log mode. 152228af9ba2SPhilippe Mathieu-Daudé# 152328af9ba2SPhilippe Mathieu-Daudé# @enable: true to enable, false to disable. 152428af9ba2SPhilippe Mathieu-Daudé# 152528af9ba2SPhilippe Mathieu-Daudé# Returns: nothing 152628af9ba2SPhilippe Mathieu-Daudé# 152728af9ba2SPhilippe Mathieu-Daudé# Since: 1.3 152828af9ba2SPhilippe Mathieu-Daudé# 152928af9ba2SPhilippe Mathieu-Daudé# Example: 153028af9ba2SPhilippe Mathieu-Daudé# 153128af9ba2SPhilippe Mathieu-Daudé# -> { "execute": "xen-set-global-dirty-log", 153228af9ba2SPhilippe Mathieu-Daudé# "arguments": { "enable": true } } 153328af9ba2SPhilippe Mathieu-Daudé# <- { "return": {} } 153428af9ba2SPhilippe Mathieu-Daudé## 153528af9ba2SPhilippe Mathieu-Daudé{ 'command': 'xen-set-global-dirty-log', 'data': { 'enable': 'bool' } } 153628af9ba2SPhilippe Mathieu-Daudé 153728af9ba2SPhilippe Mathieu-Daudé## 153828af9ba2SPhilippe Mathieu-Daudé# @xen-load-devices-state: 153928af9ba2SPhilippe Mathieu-Daudé# 1540a937b6aaSMarkus Armbruster# Load the state of all devices from file. The RAM and the block 1541a937b6aaSMarkus Armbruster# devices of the VM are not loaded by this command. 154228af9ba2SPhilippe Mathieu-Daudé# 154328af9ba2SPhilippe Mathieu-Daudé# @filename: the file to load the state of the devices from as binary 1544a937b6aaSMarkus Armbruster# data. See xen-save-devices-state.txt for a description of the 1545a937b6aaSMarkus Armbruster# binary format. 154628af9ba2SPhilippe Mathieu-Daudé# 154728af9ba2SPhilippe Mathieu-Daudé# Since: 2.7 154828af9ba2SPhilippe Mathieu-Daudé# 154928af9ba2SPhilippe Mathieu-Daudé# Example: 155028af9ba2SPhilippe Mathieu-Daudé# 155128af9ba2SPhilippe Mathieu-Daudé# -> { "execute": "xen-load-devices-state", 155228af9ba2SPhilippe Mathieu-Daudé# "arguments": { "filename": "/tmp/resume" } } 155328af9ba2SPhilippe Mathieu-Daudé# <- { "return": {} } 155428af9ba2SPhilippe Mathieu-Daudé## 155528af9ba2SPhilippe Mathieu-Daudé{ 'command': 'xen-load-devices-state', 'data': {'filename': 'str'} } 155628af9ba2SPhilippe Mathieu-Daudé 155728af9ba2SPhilippe Mathieu-Daudé## 155848685a8eSMarkus Armbruster# @xen-set-replication: 155948685a8eSMarkus Armbruster# 156048685a8eSMarkus Armbruster# Enable or disable replication. 156148685a8eSMarkus Armbruster# 156248685a8eSMarkus Armbruster# @enable: true to enable, false to disable. 156348685a8eSMarkus Armbruster# 156448685a8eSMarkus Armbruster# @primary: true for primary or false for secondary. 156548685a8eSMarkus Armbruster# 156648685a8eSMarkus Armbruster# @failover: true to do failover, false to stop. but cannot be 156748685a8eSMarkus Armbruster# specified if 'enable' is true. default value is false. 156848685a8eSMarkus Armbruster# 156948685a8eSMarkus Armbruster# Returns: nothing. 157048685a8eSMarkus Armbruster# 157148685a8eSMarkus Armbruster# Example: 157248685a8eSMarkus Armbruster# 157348685a8eSMarkus Armbruster# -> { "execute": "xen-set-replication", 157448685a8eSMarkus Armbruster# "arguments": {"enable": true, "primary": false} } 157548685a8eSMarkus Armbruster# <- { "return": {} } 157648685a8eSMarkus Armbruster# 157748685a8eSMarkus Armbruster# Since: 2.9 157848685a8eSMarkus Armbruster## 157948685a8eSMarkus Armbruster{ 'command': 'xen-set-replication', 1580335d10cdSMarc-André Lureau 'data': { 'enable': 'bool', 'primary': 'bool', '*failover' : 'bool' }, 15818a9f1e1dSMarc-André Lureau 'if': 'CONFIG_REPLICATION' } 158248685a8eSMarkus Armbruster 158348685a8eSMarkus Armbruster## 158448685a8eSMarkus Armbruster# @ReplicationStatus: 158548685a8eSMarkus Armbruster# 158648685a8eSMarkus Armbruster# The result format for 'query-xen-replication-status'. 158748685a8eSMarkus Armbruster# 158848685a8eSMarkus Armbruster# @error: true if an error happened, false if replication is normal. 158948685a8eSMarkus Armbruster# 1590a937b6aaSMarkus Armbruster# @desc: the human readable error description string, when @error is 1591a937b6aaSMarkus Armbruster# 'true'. 159248685a8eSMarkus Armbruster# 159348685a8eSMarkus Armbruster# Since: 2.9 159448685a8eSMarkus Armbruster## 159548685a8eSMarkus Armbruster{ 'struct': 'ReplicationStatus', 1596335d10cdSMarc-André Lureau 'data': { 'error': 'bool', '*desc': 'str' }, 15978a9f1e1dSMarc-André Lureau 'if': 'CONFIG_REPLICATION' } 159848685a8eSMarkus Armbruster 159948685a8eSMarkus Armbruster## 160048685a8eSMarkus Armbruster# @query-xen-replication-status: 160148685a8eSMarkus Armbruster# 160248685a8eSMarkus Armbruster# Query replication status while the vm is running. 160348685a8eSMarkus Armbruster# 1604f4347129SAndrea Bolognani# Returns: A @ReplicationStatus object showing the status. 160548685a8eSMarkus Armbruster# 160648685a8eSMarkus Armbruster# Example: 160748685a8eSMarkus Armbruster# 160848685a8eSMarkus Armbruster# -> { "execute": "query-xen-replication-status" } 160948685a8eSMarkus Armbruster# <- { "return": { "error": false } } 161048685a8eSMarkus Armbruster# 161148685a8eSMarkus Armbruster# Since: 2.9 161248685a8eSMarkus Armbruster## 161348685a8eSMarkus Armbruster{ 'command': 'query-xen-replication-status', 1614335d10cdSMarc-André Lureau 'returns': 'ReplicationStatus', 16158a9f1e1dSMarc-André Lureau 'if': 'CONFIG_REPLICATION' } 161648685a8eSMarkus Armbruster 161748685a8eSMarkus Armbruster## 161848685a8eSMarkus Armbruster# @xen-colo-do-checkpoint: 161948685a8eSMarkus Armbruster# 162048685a8eSMarkus Armbruster# Xen uses this command to notify replication to trigger a checkpoint. 162148685a8eSMarkus Armbruster# 162248685a8eSMarkus Armbruster# Returns: nothing. 162348685a8eSMarkus Armbruster# 162448685a8eSMarkus Armbruster# Example: 162548685a8eSMarkus Armbruster# 162648685a8eSMarkus Armbruster# -> { "execute": "xen-colo-do-checkpoint" } 162748685a8eSMarkus Armbruster# <- { "return": {} } 162848685a8eSMarkus Armbruster# 162948685a8eSMarkus Armbruster# Since: 2.9 163048685a8eSMarkus Armbruster## 1631335d10cdSMarc-André Lureau{ 'command': 'xen-colo-do-checkpoint', 16328a9f1e1dSMarc-André Lureau 'if': 'CONFIG_REPLICATION' } 163302affd41SPeter Xu 163402affd41SPeter Xu## 1635f56c0065SZhang Chen# @COLOStatus: 1636f56c0065SZhang Chen# 1637f56c0065SZhang Chen# The result format for 'query-colo-status'. 1638f56c0065SZhang Chen# 1639a937b6aaSMarkus Armbruster# @mode: COLO running mode. If COLO is running, this field will 1640a937b6aaSMarkus Armbruster# return 'primary' or 'secondary'. 1641f56c0065SZhang Chen# 16425cc8f9ebSZhang Chen# @last-mode: COLO last running mode. If COLO is running, this field 1643a937b6aaSMarkus Armbruster# will return same like mode field, after failover we can use this 1644a937b6aaSMarkus Armbruster# field to get last colo mode. (since 4.0) 16455ed0decaSZhang Chen# 1646f56c0065SZhang Chen# @reason: describes the reason for the COLO exit. 1647f56c0065SZhang Chen# 1648ea3b23e5SZhang Chen# Since: 3.1 1649f56c0065SZhang Chen## 1650f56c0065SZhang Chen{ 'struct': 'COLOStatus', 16515cc8f9ebSZhang Chen 'data': { 'mode': 'COLOMode', 'last-mode': 'COLOMode', 165251e47cf8SVladimir Sementsov-Ogievskiy 'reason': 'COLOExitReason' }, 165351e47cf8SVladimir Sementsov-Ogievskiy 'if': 'CONFIG_REPLICATION' } 1654f56c0065SZhang Chen 1655f56c0065SZhang Chen## 1656f56c0065SZhang Chen# @query-colo-status: 1657f56c0065SZhang Chen# 1658f56c0065SZhang Chen# Query COLO status while the vm is running. 1659f56c0065SZhang Chen# 1660f56c0065SZhang Chen# Returns: A @COLOStatus object showing the status. 1661f56c0065SZhang Chen# 1662f56c0065SZhang Chen# Example: 1663f56c0065SZhang Chen# 1664f56c0065SZhang Chen# -> { "execute": "query-colo-status" } 166551ec294dSVictor Toso# <- { "return": { "mode": "primary", "last-mode": "none", "reason": "request" } } 1666f56c0065SZhang Chen# 1667ea3b23e5SZhang Chen# Since: 3.1 1668f56c0065SZhang Chen## 1669f56c0065SZhang Chen{ 'command': 'query-colo-status', 167051e47cf8SVladimir Sementsov-Ogievskiy 'returns': 'COLOStatus', 167151e47cf8SVladimir Sementsov-Ogievskiy 'if': 'CONFIG_REPLICATION' } 1672f56c0065SZhang Chen 1673f56c0065SZhang Chen## 167402affd41SPeter Xu# @migrate-recover: 167502affd41SPeter Xu# 167602affd41SPeter Xu# Provide a recovery migration stream URI. 167702affd41SPeter Xu# 167802affd41SPeter Xu# @uri: the URI to be used for the recovery of migration stream. 167902affd41SPeter Xu# 168002affd41SPeter Xu# Returns: nothing. 168102affd41SPeter Xu# 168202affd41SPeter Xu# Example: 168302affd41SPeter Xu# 168402affd41SPeter Xu# -> { "execute": "migrate-recover", 168502affd41SPeter Xu# "arguments": { "uri": "tcp:192.168.1.200:12345" } } 168602affd41SPeter Xu# <- { "return": {} } 168702affd41SPeter Xu# 168851f63ec7SPeter Maydell# Since: 3.0 168902affd41SPeter Xu## 1690b0ddeba2SMarc-André Lureau{ 'command': 'migrate-recover', 1691b0ddeba2SMarc-André Lureau 'data': { 'uri': 'str' }, 169202affd41SPeter Xu 'allow-oob': true } 1693bfbf89c2SPeter Xu 1694bfbf89c2SPeter Xu## 1695bfbf89c2SPeter Xu# @migrate-pause: 1696bfbf89c2SPeter Xu# 1697bfbf89c2SPeter Xu# Pause a migration. Currently it only supports postcopy. 1698bfbf89c2SPeter Xu# 1699bfbf89c2SPeter Xu# Returns: nothing. 1700bfbf89c2SPeter Xu# 1701bfbf89c2SPeter Xu# Example: 1702bfbf89c2SPeter Xu# 1703bfbf89c2SPeter Xu# -> { "execute": "migrate-pause" } 1704bfbf89c2SPeter Xu# <- { "return": {} } 1705bfbf89c2SPeter Xu# 170651f63ec7SPeter Maydell# Since: 3.0 1707bfbf89c2SPeter Xu## 1708bfbf89c2SPeter Xu{ 'command': 'migrate-pause', 'allow-oob': true } 1709d328e6f3SJens Freimann 1710d328e6f3SJens Freimann## 1711d328e6f3SJens Freimann# @UNPLUG_PRIMARY: 1712d328e6f3SJens Freimann# 1713d328e6f3SJens Freimann# Emitted from source side of a migration when migration state is 1714a937b6aaSMarkus Armbruster# WAIT_UNPLUG. Device was unplugged by guest operating system. Device 1715a937b6aaSMarkus Armbruster# resources in QEMU are kept on standby to be able to re-plug it in 1716a937b6aaSMarkus Armbruster# case of migration failure. 1717d328e6f3SJens Freimann# 1718d328e6f3SJens Freimann# @device-id: QEMU device id of the unplugged device 1719d328e6f3SJens Freimann# 1720d328e6f3SJens Freimann# Since: 4.2 1721d328e6f3SJens Freimann# 1722d328e6f3SJens Freimann# Example: 17234ae65a52SAndrea Bolognani# 17240df5e9a3SVictor Toso# <- { "event": "UNPLUG_PRIMARY", 17250df5e9a3SVictor Toso# "data": { "device-id": "hostdev0" }, 17260df5e9a3SVictor Toso# "timestamp": { "seconds": 1265044230, "microseconds": 450486 } } 1727d328e6f3SJens Freimann## 1728d328e6f3SJens Freimann{ 'event': 'UNPLUG_PRIMARY', 1729d328e6f3SJens Freimann 'data': { 'device-id': 'str' } } 17307df3aa30SChuan Zheng 17317df3aa30SChuan Zheng## 173271864eadSHyman Huang(黄勇)# @DirtyRateVcpu: 173371864eadSHyman Huang(黄勇)# 173471864eadSHyman Huang(黄勇)# Dirty rate of vcpu. 173571864eadSHyman Huang(黄勇)# 173671864eadSHyman Huang(黄勇)# @id: vcpu index. 173771864eadSHyman Huang(黄勇)# 173871864eadSHyman Huang(黄勇)# @dirty-rate: dirty rate. 173971864eadSHyman Huang(黄勇)# 1740f78d4ed7SHyman Huang(黄勇)# Since: 6.2 174171864eadSHyman Huang(黄勇)## 174271864eadSHyman Huang(黄勇){ 'struct': 'DirtyRateVcpu', 174371864eadSHyman Huang(黄勇) 'data': { 'id': 'int', 'dirty-rate': 'int64' } } 174471864eadSHyman Huang(黄勇) 174571864eadSHyman Huang(黄勇)## 17467df3aa30SChuan Zheng# @DirtyRateStatus: 17477df3aa30SChuan Zheng# 17485034e3d4SAndrei Gudkov# Dirty page rate measurement status. 17497df3aa30SChuan Zheng# 17505034e3d4SAndrei Gudkov# @unstarted: measuring thread has not been started yet 17517df3aa30SChuan Zheng# 17525034e3d4SAndrei Gudkov# @measuring: measuring thread is running 17537df3aa30SChuan Zheng# 17545034e3d4SAndrei Gudkov# @measured: dirty page rate is measured and the results are available 17557df3aa30SChuan Zheng# 17567df3aa30SChuan Zheng# Since: 5.2 17577df3aa30SChuan Zheng## 17587df3aa30SChuan Zheng{ 'enum': 'DirtyRateStatus', 17597df3aa30SChuan Zheng 'data': [ 'unstarted', 'measuring', 'measured'] } 17604c437254SChuan Zheng 17614c437254SChuan Zheng## 176271864eadSHyman Huang(黄勇)# @DirtyRateMeasureMode: 176371864eadSHyman Huang(黄勇)# 17645034e3d4SAndrei Gudkov# Method used to measure dirty page rate. Differences between 17655034e3d4SAndrei Gudkov# available methods are explained in @calc-dirty-rate. 176671864eadSHyman Huang(黄勇)# 17675034e3d4SAndrei Gudkov# @page-sampling: use page sampling 176871864eadSHyman Huang(黄勇)# 17695034e3d4SAndrei Gudkov# @dirty-ring: use dirty ring 1770826b8bc8SHyman Huang(黄勇)# 17715034e3d4SAndrei Gudkov# @dirty-bitmap: use dirty bitmap 177271864eadSHyman Huang(黄勇)# 1773f78d4ed7SHyman Huang(黄勇)# Since: 6.2 177471864eadSHyman Huang(黄勇)## 177571864eadSHyman Huang(黄勇){ 'enum': 'DirtyRateMeasureMode', 1776826b8bc8SHyman Huang(黄勇) 'data': ['page-sampling', 'dirty-ring', 'dirty-bitmap'] } 177771864eadSHyman Huang(黄勇) 177871864eadSHyman Huang(黄勇)## 17794c437254SChuan Zheng# @DirtyRateInfo: 17804c437254SChuan Zheng# 17815034e3d4SAndrei Gudkov# Information about measured dirty page rate. 17824c437254SChuan Zheng# 1783a937b6aaSMarkus Armbruster# @dirty-rate: an estimate of the dirty page rate of the VM in units 17845034e3d4SAndrei Gudkov# of MiB/s. Value is present only when @status is 'measured'. 17854c437254SChuan Zheng# 17865034e3d4SAndrei Gudkov# @status: current status of dirty page rate measurements 17874c437254SChuan Zheng# 17884c437254SChuan Zheng# @start-time: start time in units of second for calculation 17894c437254SChuan Zheng# 17905034e3d4SAndrei Gudkov# @calc-time: time period for which dirty page rate was measured 17915034e3d4SAndrei Gudkov# (in seconds) 17924c437254SChuan Zheng# 17935034e3d4SAndrei Gudkov# @sample-pages: number of sampled pages per GiB of guest memory. 17945034e3d4SAndrei Gudkov# Valid only in page-sampling mode (Since 6.1) 17957afa08cdSHyman Huang(黄勇)# 17965034e3d4SAndrei Gudkov# @mode: mode that was used to measure dirty page rate (Since 6.2) 17970e21bf24SHyman Huang(黄勇)# 17985034e3d4SAndrei Gudkov# @vcpu-dirty-rate: dirty rate for each vCPU if dirty-ring mode was 1799a937b6aaSMarkus Armbruster# specified (Since 6.2) 18000e21bf24SHyman Huang(黄勇)# 18014c437254SChuan Zheng# Since: 5.2 18024c437254SChuan Zheng## 18034c437254SChuan Zheng{ 'struct': 'DirtyRateInfo', 1804b1a859cfSChuan Zheng 'data': {'*dirty-rate': 'int64', 18054c437254SChuan Zheng 'status': 'DirtyRateStatus', 18064c437254SChuan Zheng 'start-time': 'int64', 18077afa08cdSHyman Huang(黄勇) 'calc-time': 'int64', 18080e21bf24SHyman Huang(黄勇) 'sample-pages': 'uint64', 18090e21bf24SHyman Huang(黄勇) 'mode': 'DirtyRateMeasureMode', 18100e21bf24SHyman Huang(黄勇) '*vcpu-dirty-rate': [ 'DirtyRateVcpu' ] } } 18114c437254SChuan Zheng 18124c437254SChuan Zheng## 18134c437254SChuan Zheng# @calc-dirty-rate: 18144c437254SChuan Zheng# 18155034e3d4SAndrei Gudkov# Start measuring dirty page rate of the VM. Results can be retrieved 18165034e3d4SAndrei Gudkov# with @query-dirty-rate after measurements are completed. 18174c437254SChuan Zheng# 18185034e3d4SAndrei Gudkov# Dirty page rate is the number of pages changed in a given time 18195034e3d4SAndrei Gudkov# period expressed in MiB/s. The following methods of calculation are 18205034e3d4SAndrei Gudkov# available: 18214c437254SChuan Zheng# 18225034e3d4SAndrei Gudkov# 1. In page sampling mode, a random subset of pages are selected and 18235034e3d4SAndrei Gudkov# hashed twice: once at the beginning of measurement time period, 18245034e3d4SAndrei Gudkov# and once again at the end. If two hashes for some page are 18255034e3d4SAndrei Gudkov# different, the page is counted as changed. Since this method 18265034e3d4SAndrei Gudkov# relies on sampling and hashing, calculated dirty page rate is 18275034e3d4SAndrei Gudkov# only an estimate of its true value. Increasing @sample-pages 18285034e3d4SAndrei Gudkov# improves estimation quality at the cost of higher computational 18295034e3d4SAndrei Gudkov# overhead. 18307afa08cdSHyman Huang(黄勇)# 18315034e3d4SAndrei Gudkov# 2. Dirty bitmap mode captures writes to memory (for example by 18325034e3d4SAndrei Gudkov# temporarily revoking write access to all pages) and counting page 18335034e3d4SAndrei Gudkov# faults. Information about modified pages is collected into a 18345034e3d4SAndrei Gudkov# bitmap, where each bit corresponds to one guest page. This mode 18355034e3d4SAndrei Gudkov# requires that KVM accelerator property "dirty-ring-size" is *not* 18365034e3d4SAndrei Gudkov# set. 18375034e3d4SAndrei Gudkov# 18385034e3d4SAndrei Gudkov# 3. Dirty ring mode is similar to dirty bitmap mode, but the 18395034e3d4SAndrei Gudkov# information about modified pages is collected into ring buffer. 18405034e3d4SAndrei Gudkov# This mode tracks page modification per each vCPU separately. It 18415034e3d4SAndrei Gudkov# requires that KVM accelerator property "dirty-ring-size" is set. 18425034e3d4SAndrei Gudkov# 18435034e3d4SAndrei Gudkov# @calc-time: time period in units of second for which dirty page rate 18445034e3d4SAndrei Gudkov# is calculated. Note that larger @calc-time values will 18455034e3d4SAndrei Gudkov# typically result in smaller dirty page rates because page 18465034e3d4SAndrei Gudkov# dirtying is a one-time event. Once some page is counted as 18475034e3d4SAndrei Gudkov# dirty during @calc-time period, further writes to this page will 18485034e3d4SAndrei Gudkov# not increase dirty page rate anymore. 18495034e3d4SAndrei Gudkov# 18505034e3d4SAndrei Gudkov# @sample-pages: number of sampled pages per each GiB of guest memory. 18515034e3d4SAndrei Gudkov# Default value is 512. For 4KiB guest pages this corresponds to 18525034e3d4SAndrei Gudkov# sampling ratio of 0.2%. This argument is used only in page 18535034e3d4SAndrei Gudkov# sampling mode. (Since 6.1) 18545034e3d4SAndrei Gudkov# 18555034e3d4SAndrei Gudkov# @mode: mechanism for tracking dirty pages. Default value is 18565034e3d4SAndrei Gudkov# 'page-sampling'. Others are 'dirty-bitmap' and 'dirty-ring'. 18575034e3d4SAndrei Gudkov# (Since 6.1) 18580e21bf24SHyman Huang(黄勇)# 18594c437254SChuan Zheng# Since: 5.2 18604c437254SChuan Zheng# 18614c437254SChuan Zheng# Example: 18624ae65a52SAndrea Bolognani# 186337fa48a4SMarkus Armbruster# -> {"execute": "calc-dirty-rate", "arguments": {"calc-time": 1, 18647afa08cdSHyman Huang(黄勇)# 'sample-pages': 512} } 186537fa48a4SMarkus Armbruster# <- { "return": {} } 18664c437254SChuan Zheng## 18677afa08cdSHyman Huang(黄勇){ 'command': 'calc-dirty-rate', 'data': {'calc-time': 'int64', 18680e21bf24SHyman Huang(黄勇) '*sample-pages': 'int', 18690e21bf24SHyman Huang(黄勇) '*mode': 'DirtyRateMeasureMode'} } 18704c437254SChuan Zheng 18714c437254SChuan Zheng## 18724c437254SChuan Zheng# @query-dirty-rate: 18734c437254SChuan Zheng# 18745034e3d4SAndrei Gudkov# Query results of the most recent invocation of @calc-dirty-rate. 18754c437254SChuan Zheng# 18764c437254SChuan Zheng# Since: 5.2 18775034e3d4SAndrei Gudkov# 18785034e3d4SAndrei Gudkov# Examples: 18795034e3d4SAndrei Gudkov# 18805034e3d4SAndrei Gudkov# 1. Measurement is in progress: 18815034e3d4SAndrei Gudkov# 18825034e3d4SAndrei Gudkov# <- {"status": "measuring", "sample-pages": 512, 18835034e3d4SAndrei Gudkov# "mode": "page-sampling", "start-time": 3665220, "calc-time": 10} 18845034e3d4SAndrei Gudkov# 18855034e3d4SAndrei Gudkov# 2. Measurement has been completed: 18865034e3d4SAndrei Gudkov# 18875034e3d4SAndrei Gudkov# <- {"status": "measured", "sample-pages": 512, "dirty-rate": 108, 18885034e3d4SAndrei Gudkov# "mode": "page-sampling", "start-time": 3665220, "calc-time": 10} 18894c437254SChuan Zheng## 18904c437254SChuan Zheng{ 'command': 'query-dirty-rate', 'returns': 'DirtyRateInfo' } 18910f0d83a4SDaniel P. Berrangé 18920f0d83a4SDaniel P. Berrangé## 1893f3b2e38cSHyman Huang(黄勇)# @DirtyLimitInfo: 1894f3b2e38cSHyman Huang(黄勇)# 1895f3b2e38cSHyman Huang(黄勇)# Dirty page rate limit information of a virtual CPU. 1896f3b2e38cSHyman Huang(黄勇)# 1897f3b2e38cSHyman Huang(黄勇)# @cpu-index: index of a virtual CPU. 1898f3b2e38cSHyman Huang(黄勇)# 1899f3b2e38cSHyman Huang(黄勇)# @limit-rate: upper limit of dirty page rate (MB/s) for a virtual 1900f3b2e38cSHyman Huang(黄勇)# CPU, 0 means unlimited. 1901f3b2e38cSHyman Huang(黄勇)# 1902f3b2e38cSHyman Huang(黄勇)# @current-rate: current dirty page rate (MB/s) for a virtual CPU. 1903f3b2e38cSHyman Huang(黄勇)# 1904f3b2e38cSHyman Huang(黄勇)# Since: 7.1 1905f3b2e38cSHyman Huang(黄勇)## 1906f3b2e38cSHyman Huang(黄勇){ 'struct': 'DirtyLimitInfo', 1907f3b2e38cSHyman Huang(黄勇) 'data': { 'cpu-index': 'int', 1908f3b2e38cSHyman Huang(黄勇) 'limit-rate': 'uint64', 1909f3b2e38cSHyman Huang(黄勇) 'current-rate': 'uint64' } } 1910f3b2e38cSHyman Huang(黄勇) 1911f3b2e38cSHyman Huang(黄勇)## 1912f3b2e38cSHyman Huang(黄勇)# @set-vcpu-dirty-limit: 1913f3b2e38cSHyman Huang(黄勇)# 1914f3b2e38cSHyman Huang(黄勇)# Set the upper limit of dirty page rate for virtual CPUs. 1915f3b2e38cSHyman Huang(黄勇)# 1916a937b6aaSMarkus Armbruster# Requires KVM with accelerator property "dirty-ring-size" set. A 1917a937b6aaSMarkus Armbruster# virtual CPU's dirty page rate is a measure of its memory load. To 1918a937b6aaSMarkus Armbruster# observe dirty page rates, use @calc-dirty-rate. 1919f3b2e38cSHyman Huang(黄勇)# 1920f3b2e38cSHyman Huang(黄勇)# @cpu-index: index of a virtual CPU, default is all. 1921f3b2e38cSHyman Huang(黄勇)# 1922f3b2e38cSHyman Huang(黄勇)# @dirty-rate: upper limit of dirty page rate (MB/s) for virtual CPUs. 1923f3b2e38cSHyman Huang(黄勇)# 1924f3b2e38cSHyman Huang(黄勇)# Since: 7.1 1925f3b2e38cSHyman Huang(黄勇)# 1926f3b2e38cSHyman Huang(黄勇)# Example: 192737fa48a4SMarkus Armbruster# 192837fa48a4SMarkus Armbruster# -> {"execute": "set-vcpu-dirty-limit"} 1929f3b2e38cSHyman Huang(黄勇)# "arguments": { "dirty-rate": 200, 1930f3b2e38cSHyman Huang(黄勇)# "cpu-index": 1 } } 193137fa48a4SMarkus Armbruster# <- { "return": {} } 1932f3b2e38cSHyman Huang(黄勇)## 1933f3b2e38cSHyman Huang(黄勇){ 'command': 'set-vcpu-dirty-limit', 1934f3b2e38cSHyman Huang(黄勇) 'data': { '*cpu-index': 'int', 1935f3b2e38cSHyman Huang(黄勇) 'dirty-rate': 'uint64' } } 1936f3b2e38cSHyman Huang(黄勇) 1937f3b2e38cSHyman Huang(黄勇)## 1938f3b2e38cSHyman Huang(黄勇)# @cancel-vcpu-dirty-limit: 1939f3b2e38cSHyman Huang(黄勇)# 1940f3b2e38cSHyman Huang(黄勇)# Cancel the upper limit of dirty page rate for virtual CPUs. 1941f3b2e38cSHyman Huang(黄勇)# 1942f3b2e38cSHyman Huang(黄勇)# Cancel the dirty page limit for the vCPU which has been set with 1943f3b2e38cSHyman Huang(黄勇)# set-vcpu-dirty-limit command. Note that this command requires 1944f3b2e38cSHyman Huang(黄勇)# support from dirty ring, same as the "set-vcpu-dirty-limit". 1945f3b2e38cSHyman Huang(黄勇)# 1946f3b2e38cSHyman Huang(黄勇)# @cpu-index: index of a virtual CPU, default is all. 1947f3b2e38cSHyman Huang(黄勇)# 1948f3b2e38cSHyman Huang(黄勇)# Since: 7.1 1949f3b2e38cSHyman Huang(黄勇)# 1950f3b2e38cSHyman Huang(黄勇)# Example: 195137fa48a4SMarkus Armbruster# 195237fa48a4SMarkus Armbruster# -> {"execute": "cancel-vcpu-dirty-limit"}, 1953f3b2e38cSHyman Huang(黄勇)# "arguments": { "cpu-index": 1 } } 195437fa48a4SMarkus Armbruster# <- { "return": {} } 1955f3b2e38cSHyman Huang(黄勇)## 1956f3b2e38cSHyman Huang(黄勇){ 'command': 'cancel-vcpu-dirty-limit', 1957f3b2e38cSHyman Huang(黄勇) 'data': { '*cpu-index': 'int'} } 1958f3b2e38cSHyman Huang(黄勇) 1959f3b2e38cSHyman Huang(黄勇)## 1960f3b2e38cSHyman Huang(黄勇)# @query-vcpu-dirty-limit: 1961f3b2e38cSHyman Huang(黄勇)# 1962a937b6aaSMarkus Armbruster# Returns information about virtual CPU dirty page rate limits, if 1963a937b6aaSMarkus Armbruster# any. 1964f3b2e38cSHyman Huang(黄勇)# 1965f3b2e38cSHyman Huang(黄勇)# Since: 7.1 1966f3b2e38cSHyman Huang(黄勇)# 1967f3b2e38cSHyman Huang(黄勇)# Example: 196837fa48a4SMarkus Armbruster# 196937fa48a4SMarkus Armbruster# -> {"execute": "query-vcpu-dirty-limit"} 197037fa48a4SMarkus Armbruster# <- {"return": [ 197137fa48a4SMarkus Armbruster# { "limit-rate": 60, "current-rate": 3, "cpu-index": 0}, 197237fa48a4SMarkus Armbruster# { "limit-rate": 60, "current-rate": 3, "cpu-index": 1}]} 1973f3b2e38cSHyman Huang(黄勇)## 1974f3b2e38cSHyman Huang(黄勇){ 'command': 'query-vcpu-dirty-limit', 1975f3b2e38cSHyman Huang(黄勇) 'returns': [ 'DirtyLimitInfo' ] } 1976f3b2e38cSHyman Huang(黄勇) 1977f3b2e38cSHyman Huang(黄勇)## 197867132620SJiang Jiacheng# @MigrationThreadInfo: 197967132620SJiang Jiacheng# 198067132620SJiang Jiacheng# Information about migrationthreads 198167132620SJiang Jiacheng# 198267132620SJiang Jiacheng# @name: the name of migration thread 198367132620SJiang Jiacheng# 198467132620SJiang Jiacheng# @thread-id: ID of the underlying host thread 198567132620SJiang Jiacheng# 198667132620SJiang Jiacheng# Since: 7.2 198767132620SJiang Jiacheng## 198867132620SJiang Jiacheng{ 'struct': 'MigrationThreadInfo', 198967132620SJiang Jiacheng 'data': {'name': 'str', 199067132620SJiang Jiacheng 'thread-id': 'int'} } 199167132620SJiang Jiacheng 199267132620SJiang Jiacheng## 199367132620SJiang Jiacheng# @query-migrationthreads: 199467132620SJiang Jiacheng# 199567132620SJiang Jiacheng# Returns information of migration threads 199667132620SJiang Jiacheng# 199767132620SJiang Jiacheng# data: migration thread name 199867132620SJiang Jiacheng# 19997c3def93SMarkus Armbruster# Returns: information about migration threads 200067132620SJiang Jiacheng# 200167132620SJiang Jiacheng# Since: 7.2 200267132620SJiang Jiacheng## 200367132620SJiang Jiacheng{ 'command': 'query-migrationthreads', 200467132620SJiang Jiacheng 'returns': ['MigrationThreadInfo'] } 200567132620SJiang Jiacheng 200667132620SJiang Jiacheng## 20070f0d83a4SDaniel P. Berrangé# @snapshot-save: 20080f0d83a4SDaniel P. Berrangé# 20090f0d83a4SDaniel P. Berrangé# Save a VM snapshot 20100f0d83a4SDaniel P. Berrangé# 20110f0d83a4SDaniel P. Berrangé# @job-id: identifier for the newly created job 2012a937b6aaSMarkus Armbruster# 20130f0d83a4SDaniel P. Berrangé# @tag: name of the snapshot to create 2014a937b6aaSMarkus Armbruster# 20150f0d83a4SDaniel P. Berrangé# @vmstate: block device node name to save vmstate to 2016a937b6aaSMarkus Armbruster# 20170f0d83a4SDaniel P. Berrangé# @devices: list of block device node names to save a snapshot to 20180f0d83a4SDaniel P. Berrangé# 20190f0d83a4SDaniel P. Berrangé# Applications should not assume that the snapshot save is complete 20200f0d83a4SDaniel P. Berrangé# when this command returns. The job commands / events must be used 2021a937b6aaSMarkus Armbruster# to determine completion and to fetch details of any errors that 2022a937b6aaSMarkus Armbruster# arise. 20230f0d83a4SDaniel P. Berrangé# 2024a937b6aaSMarkus Armbruster# Note that execution of the guest CPUs may be stopped during the time 2025a937b6aaSMarkus Armbruster# it takes to save the snapshot. A future version of QEMU may ensure 2026a937b6aaSMarkus Armbruster# CPUs are executing continuously. 20270f0d83a4SDaniel P. Berrangé# 2028a937b6aaSMarkus Armbruster# It is strongly recommended that @devices contain all writable block 2029a937b6aaSMarkus Armbruster# device nodes if a consistent snapshot is required. 20300f0d83a4SDaniel P. Berrangé# 20310f0d83a4SDaniel P. Berrangé# If @tag already exists, an error will be reported 20320f0d83a4SDaniel P. Berrangé# 20330f0d83a4SDaniel P. Berrangé# Returns: nothing 20340f0d83a4SDaniel P. Berrangé# 20350f0d83a4SDaniel P. Berrangé# Example: 20360f0d83a4SDaniel P. Berrangé# 20370f0d83a4SDaniel P. Berrangé# -> { "execute": "snapshot-save", 2038b1ca5322SFabian Holler# "arguments": { 20390f0d83a4SDaniel P. Berrangé# "job-id": "snapsave0", 20400f0d83a4SDaniel P. Berrangé# "tag": "my-snap", 20410f0d83a4SDaniel P. Berrangé# "vmstate": "disk0", 20420f0d83a4SDaniel P. Berrangé# "devices": ["disk0", "disk1"] 20430f0d83a4SDaniel P. Berrangé# } 20440f0d83a4SDaniel P. Berrangé# } 20450f0d83a4SDaniel P. Berrangé# <- { "return": { } } 20460f0d83a4SDaniel P. Berrangé# <- {"event": "JOB_STATUS_CHANGE", 20476e7a37ffSVictor Toso# "timestamp": {"seconds": 1432121972, "microseconds": 744001}, 20480f0d83a4SDaniel P. Berrangé# "data": {"status": "created", "id": "snapsave0"}} 20490f0d83a4SDaniel P. Berrangé# <- {"event": "JOB_STATUS_CHANGE", 20506e7a37ffSVictor Toso# "timestamp": {"seconds": 1432122172, "microseconds": 744001}, 20510f0d83a4SDaniel P. Berrangé# "data": {"status": "running", "id": "snapsave0"}} 20526e7a37ffSVictor Toso# <- {"event": "STOP", 20536e7a37ffSVictor Toso# "timestamp": {"seconds": 1432122372, "microseconds": 744001} } 20546e7a37ffSVictor Toso# <- {"event": "RESUME", 20556e7a37ffSVictor Toso# "timestamp": {"seconds": 1432122572, "microseconds": 744001} } 20560f0d83a4SDaniel P. Berrangé# <- {"event": "JOB_STATUS_CHANGE", 20576e7a37ffSVictor Toso# "timestamp": {"seconds": 1432122772, "microseconds": 744001}, 20580f0d83a4SDaniel P. Berrangé# "data": {"status": "waiting", "id": "snapsave0"}} 20590f0d83a4SDaniel P. Berrangé# <- {"event": "JOB_STATUS_CHANGE", 20606e7a37ffSVictor Toso# "timestamp": {"seconds": 1432122972, "microseconds": 744001}, 20610f0d83a4SDaniel P. Berrangé# "data": {"status": "pending", "id": "snapsave0"}} 20620f0d83a4SDaniel P. Berrangé# <- {"event": "JOB_STATUS_CHANGE", 20636e7a37ffSVictor Toso# "timestamp": {"seconds": 1432123172, "microseconds": 744001}, 20640f0d83a4SDaniel P. Berrangé# "data": {"status": "concluded", "id": "snapsave0"}} 20650f0d83a4SDaniel P. Berrangé# -> {"execute": "query-jobs"} 20660f0d83a4SDaniel P. Berrangé# <- {"return": [{"current-progress": 1, 20670f0d83a4SDaniel P. Berrangé# "status": "concluded", 20680f0d83a4SDaniel P. Berrangé# "total-progress": 1, 20690f0d83a4SDaniel P. Berrangé# "type": "snapshot-save", 20700f0d83a4SDaniel P. Berrangé# "id": "snapsave0"}]} 20710f0d83a4SDaniel P. Berrangé# 20720f0d83a4SDaniel P. Berrangé# Since: 6.0 20730f0d83a4SDaniel P. Berrangé## 20740f0d83a4SDaniel P. Berrangé{ 'command': 'snapshot-save', 20750f0d83a4SDaniel P. Berrangé 'data': { 'job-id': 'str', 20760f0d83a4SDaniel P. Berrangé 'tag': 'str', 20770f0d83a4SDaniel P. Berrangé 'vmstate': 'str', 20780f0d83a4SDaniel P. Berrangé 'devices': ['str'] } } 20790f0d83a4SDaniel P. Berrangé 20800f0d83a4SDaniel P. Berrangé## 20810f0d83a4SDaniel P. Berrangé# @snapshot-load: 20820f0d83a4SDaniel P. Berrangé# 20830f0d83a4SDaniel P. Berrangé# Load a VM snapshot 20840f0d83a4SDaniel P. Berrangé# 20850f0d83a4SDaniel P. Berrangé# @job-id: identifier for the newly created job 2086a937b6aaSMarkus Armbruster# 20870f0d83a4SDaniel P. Berrangé# @tag: name of the snapshot to load. 2088a937b6aaSMarkus Armbruster# 20890f0d83a4SDaniel P. Berrangé# @vmstate: block device node name to load vmstate from 2090a937b6aaSMarkus Armbruster# 20910f0d83a4SDaniel P. Berrangé# @devices: list of block device node names to load a snapshot from 20920f0d83a4SDaniel P. Berrangé# 20930f0d83a4SDaniel P. Berrangé# Applications should not assume that the snapshot load is complete 20940f0d83a4SDaniel P. Berrangé# when this command returns. The job commands / events must be used 2095a937b6aaSMarkus Armbruster# to determine completion and to fetch details of any errors that 2096a937b6aaSMarkus Armbruster# arise. 20970f0d83a4SDaniel P. Berrangé# 20980f0d83a4SDaniel P. Berrangé# Note that execution of the guest CPUs will be stopped during the 20990f0d83a4SDaniel P. Berrangé# time it takes to load the snapshot. 21000f0d83a4SDaniel P. Berrangé# 2101a937b6aaSMarkus Armbruster# It is strongly recommended that @devices contain all writable block 2102a937b6aaSMarkus Armbruster# device nodes that can have changed since the original @snapshot-save 2103a937b6aaSMarkus Armbruster# command execution. 21040f0d83a4SDaniel P. Berrangé# 21050f0d83a4SDaniel P. Berrangé# Returns: nothing 21060f0d83a4SDaniel P. Berrangé# 21070f0d83a4SDaniel P. Berrangé# Example: 21080f0d83a4SDaniel P. Berrangé# 21090f0d83a4SDaniel P. Berrangé# -> { "execute": "snapshot-load", 2110b1ca5322SFabian Holler# "arguments": { 21110f0d83a4SDaniel P. Berrangé# "job-id": "snapload0", 21120f0d83a4SDaniel P. Berrangé# "tag": "my-snap", 21130f0d83a4SDaniel P. Berrangé# "vmstate": "disk0", 21140f0d83a4SDaniel P. Berrangé# "devices": ["disk0", "disk1"] 21150f0d83a4SDaniel P. Berrangé# } 21160f0d83a4SDaniel P. Berrangé# } 21170f0d83a4SDaniel P. Berrangé# <- { "return": { } } 21180f0d83a4SDaniel P. Berrangé# <- {"event": "JOB_STATUS_CHANGE", 21196e7a37ffSVictor Toso# "timestamp": {"seconds": 1472124172, "microseconds": 744001}, 21200f0d83a4SDaniel P. Berrangé# "data": {"status": "created", "id": "snapload0"}} 21210f0d83a4SDaniel P. Berrangé# <- {"event": "JOB_STATUS_CHANGE", 21226e7a37ffSVictor Toso# "timestamp": {"seconds": 1472125172, "microseconds": 744001}, 21230f0d83a4SDaniel P. Berrangé# "data": {"status": "running", "id": "snapload0"}} 21246e7a37ffSVictor Toso# <- {"event": "STOP", 21256e7a37ffSVictor Toso# "timestamp": {"seconds": 1472125472, "microseconds": 744001} } 21266e7a37ffSVictor Toso# <- {"event": "RESUME", 21276e7a37ffSVictor Toso# "timestamp": {"seconds": 1472125872, "microseconds": 744001} } 21280f0d83a4SDaniel P. Berrangé# <- {"event": "JOB_STATUS_CHANGE", 21296e7a37ffSVictor Toso# "timestamp": {"seconds": 1472126172, "microseconds": 744001}, 21300f0d83a4SDaniel P. Berrangé# "data": {"status": "waiting", "id": "snapload0"}} 21310f0d83a4SDaniel P. Berrangé# <- {"event": "JOB_STATUS_CHANGE", 21326e7a37ffSVictor Toso# "timestamp": {"seconds": 1472127172, "microseconds": 744001}, 21330f0d83a4SDaniel P. Berrangé# "data": {"status": "pending", "id": "snapload0"}} 21340f0d83a4SDaniel P. Berrangé# <- {"event": "JOB_STATUS_CHANGE", 21356e7a37ffSVictor Toso# "timestamp": {"seconds": 1472128172, "microseconds": 744001}, 21360f0d83a4SDaniel P. Berrangé# "data": {"status": "concluded", "id": "snapload0"}} 21370f0d83a4SDaniel P. Berrangé# -> {"execute": "query-jobs"} 21380f0d83a4SDaniel P. Berrangé# <- {"return": [{"current-progress": 1, 21390f0d83a4SDaniel P. Berrangé# "status": "concluded", 21400f0d83a4SDaniel P. Berrangé# "total-progress": 1, 21410f0d83a4SDaniel P. Berrangé# "type": "snapshot-load", 21420f0d83a4SDaniel P. Berrangé# "id": "snapload0"}]} 21430f0d83a4SDaniel P. Berrangé# 21440f0d83a4SDaniel P. Berrangé# Since: 6.0 21450f0d83a4SDaniel P. Berrangé## 21460f0d83a4SDaniel P. Berrangé{ 'command': 'snapshot-load', 21470f0d83a4SDaniel P. Berrangé 'data': { 'job-id': 'str', 21480f0d83a4SDaniel P. Berrangé 'tag': 'str', 21490f0d83a4SDaniel P. Berrangé 'vmstate': 'str', 21500f0d83a4SDaniel P. Berrangé 'devices': ['str'] } } 21510f0d83a4SDaniel P. Berrangé 21520f0d83a4SDaniel P. Berrangé## 21530f0d83a4SDaniel P. Berrangé# @snapshot-delete: 21540f0d83a4SDaniel P. Berrangé# 21550f0d83a4SDaniel P. Berrangé# Delete a VM snapshot 21560f0d83a4SDaniel P. Berrangé# 21570f0d83a4SDaniel P. Berrangé# @job-id: identifier for the newly created job 2158a937b6aaSMarkus Armbruster# 21590f0d83a4SDaniel P. Berrangé# @tag: name of the snapshot to delete. 2160a937b6aaSMarkus Armbruster# 21610f0d83a4SDaniel P. Berrangé# @devices: list of block device node names to delete a snapshot from 21620f0d83a4SDaniel P. Berrangé# 21630f0d83a4SDaniel P. Berrangé# Applications should not assume that the snapshot delete is complete 21640f0d83a4SDaniel P. Berrangé# when this command returns. The job commands / events must be used 2165a937b6aaSMarkus Armbruster# to determine completion and to fetch details of any errors that 2166a937b6aaSMarkus Armbruster# arise. 21670f0d83a4SDaniel P. Berrangé# 21680f0d83a4SDaniel P. Berrangé# Returns: nothing 21690f0d83a4SDaniel P. Berrangé# 21700f0d83a4SDaniel P. Berrangé# Example: 21710f0d83a4SDaniel P. Berrangé# 21720f0d83a4SDaniel P. Berrangé# -> { "execute": "snapshot-delete", 2173b1ca5322SFabian Holler# "arguments": { 21740f0d83a4SDaniel P. Berrangé# "job-id": "snapdelete0", 21750f0d83a4SDaniel P. Berrangé# "tag": "my-snap", 21760f0d83a4SDaniel P. Berrangé# "devices": ["disk0", "disk1"] 21770f0d83a4SDaniel P. Berrangé# } 21780f0d83a4SDaniel P. Berrangé# } 21790f0d83a4SDaniel P. Berrangé# <- { "return": { } } 21800f0d83a4SDaniel P. Berrangé# <- {"event": "JOB_STATUS_CHANGE", 21816e7a37ffSVictor Toso# "timestamp": {"seconds": 1442124172, "microseconds": 744001}, 21820f0d83a4SDaniel P. Berrangé# "data": {"status": "created", "id": "snapdelete0"}} 21830f0d83a4SDaniel P. Berrangé# <- {"event": "JOB_STATUS_CHANGE", 21846e7a37ffSVictor Toso# "timestamp": {"seconds": 1442125172, "microseconds": 744001}, 21850f0d83a4SDaniel P. Berrangé# "data": {"status": "running", "id": "snapdelete0"}} 21860f0d83a4SDaniel P. Berrangé# <- {"event": "JOB_STATUS_CHANGE", 21876e7a37ffSVictor Toso# "timestamp": {"seconds": 1442126172, "microseconds": 744001}, 21880f0d83a4SDaniel P. Berrangé# "data": {"status": "waiting", "id": "snapdelete0"}} 21890f0d83a4SDaniel P. Berrangé# <- {"event": "JOB_STATUS_CHANGE", 21906e7a37ffSVictor Toso# "timestamp": {"seconds": 1442127172, "microseconds": 744001}, 21910f0d83a4SDaniel P. Berrangé# "data": {"status": "pending", "id": "snapdelete0"}} 21920f0d83a4SDaniel P. Berrangé# <- {"event": "JOB_STATUS_CHANGE", 21936e7a37ffSVictor Toso# "timestamp": {"seconds": 1442128172, "microseconds": 744001}, 21940f0d83a4SDaniel P. Berrangé# "data": {"status": "concluded", "id": "snapdelete0"}} 21950f0d83a4SDaniel P. Berrangé# -> {"execute": "query-jobs"} 21960f0d83a4SDaniel P. Berrangé# <- {"return": [{"current-progress": 1, 21970f0d83a4SDaniel P. Berrangé# "status": "concluded", 21980f0d83a4SDaniel P. Berrangé# "total-progress": 1, 21990f0d83a4SDaniel P. Berrangé# "type": "snapshot-delete", 22000f0d83a4SDaniel P. Berrangé# "id": "snapdelete0"}]} 22010f0d83a4SDaniel P. Berrangé# 22020f0d83a4SDaniel P. Berrangé# Since: 6.0 22030f0d83a4SDaniel P. Berrangé## 22040f0d83a4SDaniel P. Berrangé{ 'command': 'snapshot-delete', 22050f0d83a4SDaniel P. Berrangé 'data': { 'job-id': 'str', 22060f0d83a4SDaniel P. Berrangé 'tag': 'str', 22070f0d83a4SDaniel P. Berrangé 'devices': ['str'] } } 2208