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# 267b24d326SJuan Quintela# @skipped: number of skipped zero pages. Always zero, only provided for 277b24d326SJuan Quintela# compatibility (since 1.5) 2848685a8eSMarkus Armbruster# 2948685a8eSMarkus Armbruster# @normal: number of normal pages (since 1.2) 3048685a8eSMarkus Armbruster# 3148685a8eSMarkus Armbruster# @normal-bytes: number of normal bytes sent (since 1.2) 3248685a8eSMarkus Armbruster# 33a937b6aaSMarkus Armbruster# @dirty-pages-rate: number of pages dirtied by second by the guest 34a937b6aaSMarkus Armbruster# (since 1.3) 3548685a8eSMarkus Armbruster# 3648685a8eSMarkus Armbruster# @mbps: throughput in megabits/sec. (since 1.6) 3748685a8eSMarkus Armbruster# 38a937b6aaSMarkus Armbruster# @dirty-sync-count: number of times that dirty ram was synchronized 39a937b6aaSMarkus Armbruster# (since 2.1) 4048685a8eSMarkus Armbruster# 41a937b6aaSMarkus Armbruster# @postcopy-requests: The number of page requests received from the 42a937b6aaSMarkus Armbruster# destination (since 2.7) 4348685a8eSMarkus Armbruster# 4448685a8eSMarkus Armbruster# @page-size: The number of bytes per page for the various page-based 4548685a8eSMarkus Armbruster# statistics (since 2.10) 4648685a8eSMarkus Armbruster# 47a61c45bdSJuan Quintela# @multifd-bytes: The number of bytes sent through multifd (since 3.0) 48a61c45bdSJuan Quintela# 49aecbfe9cSXiao Guangrong# @pages-per-second: the number of memory pages transferred per second 50aecbfe9cSXiao Guangrong# (Since 4.0) 51aecbfe9cSXiao Guangrong# 52ae680668SDavid Edmondson# @precopy-bytes: The number of bytes sent in the pre-copy phase 53ae680668SDavid Edmondson# (since 7.0). 54ae680668SDavid Edmondson# 55ae680668SDavid Edmondson# @downtime-bytes: The number of bytes sent while the guest is paused 56ae680668SDavid Edmondson# (since 7.0). 57ae680668SDavid Edmondson# 58ae680668SDavid Edmondson# @postcopy-bytes: The number of bytes sent during the post-copy phase 59ae680668SDavid Edmondson# (since 7.0). 60ae680668SDavid Edmondson# 61a937b6aaSMarkus Armbruster# @dirty-sync-missed-zero-copy: Number of times dirty RAM 62a937b6aaSMarkus Armbruster# synchronization could not avoid copying dirty pages. This is 63a937b6aaSMarkus Armbruster# between 0 and @dirty-sync-count * @multifd-channels. (since 64a937b6aaSMarkus Armbruster# 7.1) 65a937b6aaSMarkus Armbruster# 667b24d326SJuan Quintela# Features: 677b24d326SJuan Quintela# 687b24d326SJuan Quintela# @deprecated: Member @skipped is always zero since 1.5.3 697b24d326SJuan Quintela# 709bc6e893SMarkus Armbruster# Since: 0.14 717b24d326SJuan Quintela# 7248685a8eSMarkus Armbruster## 7348685a8eSMarkus Armbruster{ 'struct': 'MigrationStats', 7448685a8eSMarkus Armbruster 'data': {'transferred': 'int', 'remaining': 'int', 'total': 'int' , 757b24d326SJuan Quintela 'duplicate': 'int', 767b24d326SJuan Quintela 'skipped': { 'type': 'int', 'features': [ 'deprecated' ] }, 777b24d326SJuan Quintela 'normal': 'int', 7848685a8eSMarkus Armbruster 'normal-bytes': 'int', 'dirty-pages-rate': 'int', 7948685a8eSMarkus Armbruster 'mbps': 'number', 'dirty-sync-count': 'int', 80a61c45bdSJuan Quintela 'postcopy-requests': 'int', 'page-size': 'int', 81ae680668SDavid Edmondson 'multifd-bytes': 'uint64', 'pages-per-second': 'uint64', 82ae680668SDavid Edmondson 'precopy-bytes': 'uint64', 'downtime-bytes': 'uint64', 83cf20c897SLeonardo Bras 'postcopy-bytes': 'uint64', 84cf20c897SLeonardo Bras 'dirty-sync-missed-zero-copy': 'uint64' } } 8548685a8eSMarkus Armbruster 8648685a8eSMarkus Armbruster## 8748685a8eSMarkus Armbruster# @XBZRLECacheStats: 8848685a8eSMarkus Armbruster# 8948685a8eSMarkus Armbruster# Detailed XBZRLE migration cache statistics 9048685a8eSMarkus Armbruster# 9148685a8eSMarkus Armbruster# @cache-size: XBZRLE cache size 9248685a8eSMarkus Armbruster# 9348685a8eSMarkus Armbruster# @bytes: amount of bytes already transferred to the target VM 9448685a8eSMarkus Armbruster# 9548685a8eSMarkus Armbruster# @pages: amount of pages transferred to the target VM 9648685a8eSMarkus Armbruster# 9748685a8eSMarkus Armbruster# @cache-miss: number of cache miss 9848685a8eSMarkus Armbruster# 9948685a8eSMarkus Armbruster# @cache-miss-rate: rate of cache miss (since 2.1) 10048685a8eSMarkus Armbruster# 101e460a4b1SWei Wang# @encoding-rate: rate of encoded bytes (since 5.1) 102e460a4b1SWei Wang# 10348685a8eSMarkus Armbruster# @overflow: number of overflows 10448685a8eSMarkus Armbruster# 10548685a8eSMarkus Armbruster# Since: 1.2 10648685a8eSMarkus Armbruster## 10748685a8eSMarkus Armbruster{ 'struct': 'XBZRLECacheStats', 1088b9407a0SMarkus Armbruster 'data': {'cache-size': 'size', 'bytes': 'int', 'pages': 'int', 10948685a8eSMarkus Armbruster 'cache-miss': 'int', 'cache-miss-rate': 'number', 110e460a4b1SWei Wang 'encoding-rate': 'number', 'overflow': 'int' } } 11148685a8eSMarkus Armbruster 11248685a8eSMarkus Armbruster## 11376e03000SXiao Guangrong# @CompressionStats: 11476e03000SXiao Guangrong# 11576e03000SXiao Guangrong# Detailed migration compression statistics 11676e03000SXiao Guangrong# 11776e03000SXiao Guangrong# @pages: amount of pages compressed and transferred to the target VM 11876e03000SXiao Guangrong# 119a937b6aaSMarkus Armbruster# @busy: count of times that no free thread was available to compress 120a937b6aaSMarkus Armbruster# data 12176e03000SXiao Guangrong# 12276e03000SXiao Guangrong# @busy-rate: rate of thread busy 12376e03000SXiao Guangrong# 12476e03000SXiao Guangrong# @compressed-size: amount of bytes after compression 12576e03000SXiao Guangrong# 12676e03000SXiao Guangrong# @compression-rate: rate of compressed size 12776e03000SXiao Guangrong# 12876e03000SXiao Guangrong# Since: 3.1 12976e03000SXiao Guangrong## 13076e03000SXiao Guangrong{ 'struct': 'CompressionStats', 13176e03000SXiao Guangrong 'data': {'pages': 'int', 'busy': 'int', 'busy-rate': 'number', 13276e03000SXiao Guangrong 'compressed-size': 'int', 'compression-rate': 'number' } } 13376e03000SXiao Guangrong 13476e03000SXiao Guangrong## 13548685a8eSMarkus Armbruster# @MigrationStatus: 13648685a8eSMarkus Armbruster# 13748685a8eSMarkus Armbruster# An enumeration of migration status. 13848685a8eSMarkus Armbruster# 13948685a8eSMarkus Armbruster# @none: no migration has ever happened. 14048685a8eSMarkus Armbruster# 14148685a8eSMarkus Armbruster# @setup: migration process has been initiated. 14248685a8eSMarkus Armbruster# 14348685a8eSMarkus Armbruster# @cancelling: in the process of cancelling migration. 14448685a8eSMarkus Armbruster# 14548685a8eSMarkus Armbruster# @cancelled: cancelling migration is finished. 14648685a8eSMarkus Armbruster# 14748685a8eSMarkus Armbruster# @active: in the process of doing migration. 14848685a8eSMarkus Armbruster# 149a937b6aaSMarkus Armbruster# @postcopy-active: like active, but now in postcopy mode. (since 150a937b6aaSMarkus Armbruster# 2.5) 15148685a8eSMarkus Armbruster# 15251f63ec7SPeter Maydell# @postcopy-paused: during postcopy but paused. (since 3.0) 153a688d2c1SPeter Xu# 154a937b6aaSMarkus Armbruster# @postcopy-recover: trying to recover from a paused postcopy. (since 155a937b6aaSMarkus Armbruster# 3.0) 156135b87b4SPeter Xu# 15748685a8eSMarkus Armbruster# @completed: migration is finished. 15848685a8eSMarkus Armbruster# 15948685a8eSMarkus Armbruster# @failed: some error occurred during migration process. 16048685a8eSMarkus Armbruster# 161a937b6aaSMarkus Armbruster# @colo: VM is in the process of fault tolerance, VM can not get into 162a937b6aaSMarkus Armbruster# this state unless colo capability is enabled for migration. 163a937b6aaSMarkus Armbruster# (since 2.8) 16448685a8eSMarkus Armbruster# 16531e06077SDr. David Alan Gilbert# @pre-switchover: Paused before device serialisation. (since 2.11) 16631e06077SDr. David Alan Gilbert# 167a937b6aaSMarkus Armbruster# @device: During device serialisation when pause-before-switchover is 168a937b6aaSMarkus Armbruster# enabled (since 2.11) 16931e06077SDr. David Alan Gilbert# 170a937b6aaSMarkus Armbruster# @wait-unplug: wait for device unplug request by guest OS to be 171a937b6aaSMarkus Armbruster# completed. (since 4.2) 172c7e0acd5SJens Freimann# 17348685a8eSMarkus Armbruster# Since: 2.3 17448685a8eSMarkus Armbruster## 17548685a8eSMarkus Armbruster{ 'enum': 'MigrationStatus', 17648685a8eSMarkus Armbruster 'data': [ 'none', 'setup', 'cancelling', 'cancelled', 177a688d2c1SPeter Xu 'active', 'postcopy-active', 'postcopy-paused', 178135b87b4SPeter Xu 'postcopy-recover', 'completed', 'failed', 'colo', 179c7e0acd5SJens Freimann 'pre-switchover', 'device', 'wait-unplug' ] } 1803710586cSKirti Wankhede## 1813710586cSKirti Wankhede# @VfioStats: 1823710586cSKirti Wankhede# 1833710586cSKirti Wankhede# Detailed VFIO devices migration statistics 1843710586cSKirti Wankhede# 185a937b6aaSMarkus Armbruster# @transferred: amount of bytes transferred to the target VM by VFIO 186a937b6aaSMarkus Armbruster# devices 1873710586cSKirti Wankhede# 1883710586cSKirti Wankhede# Since: 5.2 1893710586cSKirti Wankhede## 1903710586cSKirti Wankhede{ 'struct': 'VfioStats', 1913710586cSKirti Wankhede 'data': {'transferred': 'int' } } 19248685a8eSMarkus Armbruster 19348685a8eSMarkus Armbruster## 19448685a8eSMarkus Armbruster# @MigrationInfo: 19548685a8eSMarkus Armbruster# 19648685a8eSMarkus Armbruster# Information about current migration process. 19748685a8eSMarkus Armbruster# 19848685a8eSMarkus Armbruster# @status: @MigrationStatus describing the current migration status. 199a937b6aaSMarkus Armbruster# If this field is not returned, no migration process has been 200a937b6aaSMarkus Armbruster# initiated 20148685a8eSMarkus Armbruster# 202a937b6aaSMarkus Armbruster# @ram: @MigrationStats containing detailed migration status, only 203a937b6aaSMarkus Armbruster# returned if status is 'active' or 'completed'(since 1.2) 20448685a8eSMarkus Armbruster# 205a937b6aaSMarkus Armbruster# @disk: @MigrationStats containing detailed disk migration status, 206a937b6aaSMarkus Armbruster# only returned if status is 'active' and it is a block migration 20748685a8eSMarkus Armbruster# 20848685a8eSMarkus Armbruster# @xbzrle-cache: @XBZRLECacheStats containing detailed XBZRLE 20948685a8eSMarkus Armbruster# migration statistics, only returned if XBZRLE feature is on and 21048685a8eSMarkus Armbruster# status is 'active' or 'completed' (since 1.2) 21148685a8eSMarkus Armbruster# 21248685a8eSMarkus Armbruster# @total-time: total amount of milliseconds since migration started. 213a937b6aaSMarkus Armbruster# If migration has ended, it returns the total migration time. 214a937b6aaSMarkus Armbruster# (since 1.2) 21548685a8eSMarkus Armbruster# 216a937b6aaSMarkus Armbruster# @downtime: only present when migration finishes correctly total 217a937b6aaSMarkus Armbruster# downtime in milliseconds for the guest. (since 1.3) 21848685a8eSMarkus Armbruster# 219a937b6aaSMarkus Armbruster# @expected-downtime: only present while migration is active expected 220a937b6aaSMarkus Armbruster# downtime in milliseconds for the guest in last walk of the dirty 221a937b6aaSMarkus Armbruster# bitmap. (since 1.3) 22248685a8eSMarkus Armbruster# 223a660eed4SPeter Maydell# @setup-time: amount of setup time in milliseconds *before* the 224a937b6aaSMarkus Armbruster# iterations begin but *after* the QMP command is issued. This is 225a937b6aaSMarkus Armbruster# designed to provide an accounting of any activities (such as 226a937b6aaSMarkus Armbruster# RDMA pinning) which may be expensive, but do not actually occur 227a937b6aaSMarkus Armbruster# during the iterative migration rounds themselves. (since 1.6) 22848685a8eSMarkus Armbruster# 22948685a8eSMarkus Armbruster# @cpu-throttle-percentage: percentage of time guest cpus are being 230a937b6aaSMarkus Armbruster# throttled during auto-converge. This is only present when 231a937b6aaSMarkus Armbruster# auto-converge has started throttling guest cpus. (Since 2.7) 23248685a8eSMarkus Armbruster# 233c94143e5SPeter Xu# @error-desc: the human readable error description string. Clients 234c94143e5SPeter Xu# should not attempt to parse the error strings. (Since 2.7) 23548685a8eSMarkus Armbruster# 236a937b6aaSMarkus Armbruster# @postcopy-blocktime: total time when all vCPU were blocked during 237a937b6aaSMarkus Armbruster# postcopy live migration. This is only present when the 238a937b6aaSMarkus Armbruster# postcopy-blocktime migration capability is enabled. (Since 3.0) 23965ace060SAlexey Perevalov# 240a937b6aaSMarkus Armbruster# @postcopy-vcpu-blocktime: list of the postcopy blocktime per vCPU. 241a937b6aaSMarkus Armbruster# This is only present when the postcopy-blocktime migration 242a937b6aaSMarkus Armbruster# capability is enabled. (Since 3.0) 24365ace060SAlexey Perevalov# 244a937b6aaSMarkus Armbruster# @compression: migration compression statistics, only returned if 245a937b6aaSMarkus Armbruster# compression feature is on and status is 'active' or 'completed' 246a937b6aaSMarkus Armbruster# (Since 3.1) 24765ace060SAlexey Perevalov# 248a937b6aaSMarkus Armbruster# @socket-address: Only used for tcp, to know what the real port is 249a937b6aaSMarkus Armbruster# (Since 4.0) 2509aca82baSJuan Quintela# 251a937b6aaSMarkus Armbruster# @vfio: @VfioStats containing detailed VFIO devices migration 252a937b6aaSMarkus Armbruster# statistics, only returned if VFIO device is present, migration 253a937b6aaSMarkus Armbruster# is supported by all VFIO devices and status is 'active' or 254a937b6aaSMarkus Armbruster# 'completed' (since 5.2) 2553710586cSKirti Wankhede# 256a937b6aaSMarkus Armbruster# @blocked-reasons: A list of reasons an outgoing migration is 257a937b6aaSMarkus Armbruster# blocked. Present and non-empty when migration is blocked. 258e11ce6c0SMarkus Armbruster# (since 6.0) 259e11ce6c0SMarkus Armbruster# 2608abc8115SHyman Huang(黄勇)# @dirty-limit-throttle-time-per-round: Maximum throttle time 2618abc8115SHyman Huang(黄勇)# (in microseconds) of virtual CPUs each dirty ring full round, 2628abc8115SHyman Huang(黄勇)# which shows how MigrationCapability dirty-limit affects the 2638abc8115SHyman Huang(黄勇)# guest during live migration. (Since 8.1) 26415699cf5SHyman Huang(黄勇)# 2658abc8115SHyman Huang(黄勇)# @dirty-limit-ring-full-time: Estimated average dirty ring full time 2668abc8115SHyman Huang(黄勇)# (in microseconds) for each dirty ring full round. The value 2678abc8115SHyman Huang(黄勇)# equals the dirty ring memory size divided by the average dirty 2688abc8115SHyman Huang(黄勇)# page rate of the virtual CPU, which can be used to observe the 2698abc8115SHyman Huang(黄勇)# average memory load of the virtual CPU indirectly. Note that 2708abc8115SHyman Huang(黄勇)# zero means guest doesn't dirty memory. (Since 8.1) 27115699cf5SHyman Huang(黄勇)# 27266db46caSJuan Quintela# Features: 27366db46caSJuan Quintela# 27466db46caSJuan Quintela# @deprecated: Member @disk is deprecated because block migration is. 275864128dfSJuan Quintela# Member @compression is deprecated because it is unreliable and 276864128dfSJuan Quintela# untested. It is recommended to use multifd migration, which 277864128dfSJuan Quintela# offers an alternative compression implementation that is 278864128dfSJuan Quintela# reliable and tested. 27966db46caSJuan Quintela# 2809bc6e893SMarkus Armbruster# Since: 0.14 28148685a8eSMarkus Armbruster## 28248685a8eSMarkus Armbruster{ 'struct': 'MigrationInfo', 28348685a8eSMarkus Armbruster 'data': {'*status': 'MigrationStatus', '*ram': 'MigrationStats', 28466db46caSJuan Quintela '*disk': { 'type': 'MigrationStats', 'features': [ 'deprecated' ] }, 2853710586cSKirti Wankhede '*vfio': 'VfioStats', 28648685a8eSMarkus Armbruster '*xbzrle-cache': 'XBZRLECacheStats', 28748685a8eSMarkus Armbruster '*total-time': 'int', 28848685a8eSMarkus Armbruster '*expected-downtime': 'int', 28948685a8eSMarkus Armbruster '*downtime': 'int', 29048685a8eSMarkus Armbruster '*setup-time': 'int', 29148685a8eSMarkus Armbruster '*cpu-throttle-percentage': 'int', 29265ace060SAlexey Perevalov '*error-desc': 'str', 2933af8554bSDr. David Alan Gilbert '*blocked-reasons': ['str'], 29465ace060SAlexey Perevalov '*postcopy-blocktime': 'uint32', 29576e03000SXiao Guangrong '*postcopy-vcpu-blocktime': ['uint32'], 296864128dfSJuan Quintela '*compression': { 'type': 'CompressionStats', 'features': [ 'deprecated' ] }, 29715699cf5SHyman Huang(黄勇) '*socket-address': ['SocketAddress'], 29815699cf5SHyman Huang(黄勇) '*dirty-limit-throttle-time-per-round': 'uint64', 29915699cf5SHyman Huang(黄勇) '*dirty-limit-ring-full-time': 'uint64'} } 30048685a8eSMarkus Armbruster 30148685a8eSMarkus Armbruster## 30248685a8eSMarkus Armbruster# @query-migrate: 30348685a8eSMarkus Armbruster# 30448685a8eSMarkus Armbruster# Returns information about current migration process. If migration 30548685a8eSMarkus Armbruster# is active there will be another json-object with RAM migration 30648685a8eSMarkus Armbruster# status and if block migration is active another one with block 30748685a8eSMarkus Armbruster# migration status. 30848685a8eSMarkus Armbruster# 30948685a8eSMarkus Armbruster# Returns: @MigrationInfo 31048685a8eSMarkus Armbruster# 3119bc6e893SMarkus Armbruster# Since: 0.14 31248685a8eSMarkus Armbruster# 31337fa48a4SMarkus Armbruster# Examples: 31448685a8eSMarkus Armbruster# 31548685a8eSMarkus Armbruster# 1. Before the first migration 31648685a8eSMarkus Armbruster# 31748685a8eSMarkus Armbruster# -> { "execute": "query-migrate" } 31848685a8eSMarkus Armbruster# <- { "return": {} } 31948685a8eSMarkus Armbruster# 32048685a8eSMarkus Armbruster# 2. Migration is done and has succeeded 32148685a8eSMarkus Armbruster# 32248685a8eSMarkus Armbruster# -> { "execute": "query-migrate" } 32348685a8eSMarkus Armbruster# <- { "return": { 32448685a8eSMarkus Armbruster# "status": "completed", 325be1d2c49Sjialina01# "total-time":12345, 326be1d2c49Sjialina01# "setup-time":12345, 327be1d2c49Sjialina01# "downtime":12345, 32848685a8eSMarkus Armbruster# "ram":{ 32948685a8eSMarkus Armbruster# "transferred":123, 33048685a8eSMarkus Armbruster# "remaining":123, 33148685a8eSMarkus Armbruster# "total":246, 33248685a8eSMarkus Armbruster# "duplicate":123, 33348685a8eSMarkus Armbruster# "normal":123, 33448685a8eSMarkus Armbruster# "normal-bytes":123456, 33548685a8eSMarkus Armbruster# "dirty-sync-count":15 33648685a8eSMarkus Armbruster# } 33748685a8eSMarkus Armbruster# } 33848685a8eSMarkus Armbruster# } 33948685a8eSMarkus Armbruster# 34048685a8eSMarkus Armbruster# 3. Migration is done and has failed 34148685a8eSMarkus Armbruster# 34248685a8eSMarkus Armbruster# -> { "execute": "query-migrate" } 34348685a8eSMarkus Armbruster# <- { "return": { "status": "failed" } } 34448685a8eSMarkus Armbruster# 34548685a8eSMarkus Armbruster# 4. Migration is being performed and is not a block migration: 34648685a8eSMarkus Armbruster# 34748685a8eSMarkus Armbruster# -> { "execute": "query-migrate" } 34848685a8eSMarkus Armbruster# <- { 34948685a8eSMarkus Armbruster# "return":{ 35048685a8eSMarkus Armbruster# "status":"active", 351be1d2c49Sjialina01# "total-time":12345, 352be1d2c49Sjialina01# "setup-time":12345, 353be1d2c49Sjialina01# "expected-downtime":12345, 35448685a8eSMarkus Armbruster# "ram":{ 35548685a8eSMarkus Armbruster# "transferred":123, 35648685a8eSMarkus Armbruster# "remaining":123, 35748685a8eSMarkus Armbruster# "total":246, 35848685a8eSMarkus Armbruster# "duplicate":123, 35948685a8eSMarkus Armbruster# "normal":123, 36048685a8eSMarkus Armbruster# "normal-bytes":123456, 36148685a8eSMarkus Armbruster# "dirty-sync-count":15 36248685a8eSMarkus Armbruster# } 36348685a8eSMarkus Armbruster# } 36448685a8eSMarkus Armbruster# } 36548685a8eSMarkus Armbruster# 36648685a8eSMarkus Armbruster# 5. Migration is being performed and is a block migration: 36748685a8eSMarkus Armbruster# 36848685a8eSMarkus Armbruster# -> { "execute": "query-migrate" } 36948685a8eSMarkus Armbruster# <- { 37048685a8eSMarkus Armbruster# "return":{ 37148685a8eSMarkus Armbruster# "status":"active", 372be1d2c49Sjialina01# "total-time":12345, 373be1d2c49Sjialina01# "setup-time":12345, 374be1d2c49Sjialina01# "expected-downtime":12345, 37548685a8eSMarkus Armbruster# "ram":{ 37648685a8eSMarkus Armbruster# "total":1057024, 37748685a8eSMarkus Armbruster# "remaining":1053304, 37848685a8eSMarkus Armbruster# "transferred":3720, 37948685a8eSMarkus Armbruster# "duplicate":123, 38048685a8eSMarkus Armbruster# "normal":123, 38148685a8eSMarkus Armbruster# "normal-bytes":123456, 38248685a8eSMarkus Armbruster# "dirty-sync-count":15 38348685a8eSMarkus Armbruster# }, 38448685a8eSMarkus Armbruster# "disk":{ 38548685a8eSMarkus Armbruster# "total":20971520, 38648685a8eSMarkus Armbruster# "remaining":20880384, 38748685a8eSMarkus Armbruster# "transferred":91136 38848685a8eSMarkus Armbruster# } 38948685a8eSMarkus Armbruster# } 39048685a8eSMarkus Armbruster# } 39148685a8eSMarkus Armbruster# 39248685a8eSMarkus Armbruster# 6. Migration is being performed and XBZRLE is active: 39348685a8eSMarkus Armbruster# 39448685a8eSMarkus Armbruster# -> { "execute": "query-migrate" } 39548685a8eSMarkus Armbruster# <- { 39648685a8eSMarkus Armbruster# "return":{ 39748685a8eSMarkus Armbruster# "status":"active", 398be1d2c49Sjialina01# "total-time":12345, 399be1d2c49Sjialina01# "setup-time":12345, 400be1d2c49Sjialina01# "expected-downtime":12345, 40148685a8eSMarkus Armbruster# "ram":{ 40248685a8eSMarkus Armbruster# "total":1057024, 40348685a8eSMarkus Armbruster# "remaining":1053304, 40448685a8eSMarkus Armbruster# "transferred":3720, 40548685a8eSMarkus Armbruster# "duplicate":10, 40648685a8eSMarkus Armbruster# "normal":3333, 40748685a8eSMarkus Armbruster# "normal-bytes":3412992, 40848685a8eSMarkus Armbruster# "dirty-sync-count":15 40948685a8eSMarkus Armbruster# }, 41048685a8eSMarkus Armbruster# "xbzrle-cache":{ 41148685a8eSMarkus Armbruster# "cache-size":67108864, 41248685a8eSMarkus Armbruster# "bytes":20971520, 41348685a8eSMarkus Armbruster# "pages":2444343, 41448685a8eSMarkus Armbruster# "cache-miss":2244, 41548685a8eSMarkus Armbruster# "cache-miss-rate":0.123, 416e460a4b1SWei Wang# "encoding-rate":80.1, 41748685a8eSMarkus Armbruster# "overflow":34434 41848685a8eSMarkus Armbruster# } 41948685a8eSMarkus Armbruster# } 42048685a8eSMarkus Armbruster# } 42148685a8eSMarkus Armbruster## 42248685a8eSMarkus Armbruster{ 'command': 'query-migrate', 'returns': 'MigrationInfo' } 42348685a8eSMarkus Armbruster 42448685a8eSMarkus Armbruster## 42548685a8eSMarkus Armbruster# @MigrationCapability: 42648685a8eSMarkus Armbruster# 42748685a8eSMarkus Armbruster# Migration capabilities enumeration 42848685a8eSMarkus Armbruster# 429a937b6aaSMarkus Armbruster# @xbzrle: Migration supports xbzrle (Xor Based Zero Run Length 430a937b6aaSMarkus Armbruster# Encoding). This feature allows us to minimize migration traffic 431a937b6aaSMarkus Armbruster# for certain work loads, by sending compressed difference of the 432a937b6aaSMarkus Armbruster# pages 43348685a8eSMarkus Armbruster# 434a937b6aaSMarkus Armbruster# @rdma-pin-all: Controls whether or not the entire VM memory 435a937b6aaSMarkus Armbruster# footprint is mlock()'d on demand or all at once. Refer to 436a937b6aaSMarkus Armbruster# docs/rdma.txt for usage. Disabled by default. (since 2.0) 43748685a8eSMarkus Armbruster# 438a937b6aaSMarkus Armbruster# @zero-blocks: During storage migration encode blocks of zeroes 439a937b6aaSMarkus Armbruster# efficiently. This essentially saves 1MB of zeroes per block on 440a937b6aaSMarkus Armbruster# the wire. Enabling requires source and target VM to support 441a937b6aaSMarkus Armbruster# this feature. To enable it is sufficient to enable the 442a937b6aaSMarkus Armbruster# capability on the source VM. The feature is disabled by default. 443a937b6aaSMarkus Armbruster# (since 1.6) 44448685a8eSMarkus Armbruster# 445a937b6aaSMarkus Armbruster# @compress: Use multiple compression threads to accelerate live 446a937b6aaSMarkus Armbruster# migration. This feature can help to reduce the migration 447a937b6aaSMarkus Armbruster# traffic, by sending compressed pages. Please note that if 448a937b6aaSMarkus Armbruster# compress and xbzrle are both on, compress only takes effect in 449a937b6aaSMarkus Armbruster# the ram bulk stage, after that, it will be disabled and only 450a937b6aaSMarkus Armbruster# xbzrle takes effect, this can help to minimize migration 451a937b6aaSMarkus Armbruster# traffic. The feature is disabled by default. (since 2.4) 45248685a8eSMarkus Armbruster# 453e4ceec29SJuan Quintela# @events: generate events for each migration state change (since 2.4) 45448685a8eSMarkus Armbruster# 455a937b6aaSMarkus Armbruster# @auto-converge: If enabled, QEMU will automatically throttle down 456a937b6aaSMarkus Armbruster# the guest to speed up convergence of RAM migration. (since 1.6) 45748685a8eSMarkus Armbruster# 458a937b6aaSMarkus Armbruster# @postcopy-ram: Start executing on the migration target before all of 459a937b6aaSMarkus Armbruster# RAM has been migrated, pulling the remaining pages along as 460a937b6aaSMarkus Armbruster# needed. The capacity must have the same setting on both source 461a937b6aaSMarkus Armbruster# and target or migration will not even start. NOTE: If the 462a937b6aaSMarkus Armbruster# migration fails during postcopy the VM will fail. (since 2.6) 46348685a8eSMarkus Armbruster# 464a937b6aaSMarkus Armbruster# @x-colo: If enabled, migration will never end, and the state of the 465a937b6aaSMarkus Armbruster# VM on the primary side will be migrated continuously to the VM 466a937b6aaSMarkus Armbruster# on secondary side, this process is called COarse-Grain LOck 467a937b6aaSMarkus Armbruster# Stepping (COLO) for Non-stop Service. (since 2.8) 46848685a8eSMarkus Armbruster# 469a937b6aaSMarkus Armbruster# @release-ram: if enabled, qemu will free the migrated ram pages on 470a937b6aaSMarkus Armbruster# the source during postcopy-ram migration. (since 2.9) 47148685a8eSMarkus Armbruster# 47248685a8eSMarkus Armbruster# @block: If enabled, QEMU will also migrate the contents of all block 47348685a8eSMarkus Armbruster# devices. Default is disabled. A possible alternative uses 47448685a8eSMarkus Armbruster# mirror jobs to a builtin NBD server on the destination, which 475a937b6aaSMarkus Armbruster# offers more flexibility. (Since 2.10) 47648685a8eSMarkus Armbruster# 47748685a8eSMarkus Armbruster# @return-path: If enabled, migration will use the return path even 47848685a8eSMarkus Armbruster# for precopy. (since 2.10) 47948685a8eSMarkus Armbruster# 480a937b6aaSMarkus Armbruster# @pause-before-switchover: Pause outgoing migration before 481a937b6aaSMarkus Armbruster# serialising device state and before disabling block IO (since 482a937b6aaSMarkus Armbruster# 2.11) 48393fbd031SDr. David Alan Gilbert# 484cbfd6c95SJuan Quintela# @multifd: Use more than one fd for migration (since 4.0) 48530126bbfSJuan Quintela# 48655efc8c2SVladimir Sementsov-Ogievskiy# @dirty-bitmaps: If enabled, QEMU will migrate named dirty bitmaps. 48755efc8c2SVladimir Sementsov-Ogievskiy# (since 2.12) 48855efc8c2SVladimir Sementsov-Ogievskiy# 489f22f928eSAlexey Perevalov# @postcopy-blocktime: Calculate downtime for postcopy live migration 49051f63ec7SPeter Maydell# (since 3.0) 491f22f928eSAlexey Perevalov# 492a937b6aaSMarkus Armbruster# @late-block-activate: If enabled, the destination will not activate 493a937b6aaSMarkus Armbruster# block devices (and thus take locks) immediately at the end of 494a937b6aaSMarkus Armbruster# migration. (since 3.0) 4950f073f44SDr. David Alan Gilbert# 4969e272073SMarkus Armbruster# @x-ignore-shared: If enabled, QEMU will not migrate shared memory 4979e272073SMarkus Armbruster# that is accessible on the destination machine. (since 4.0) 49818269069SYury Kotov# 499b9d68df6SYury Kotov# @validate-uuid: Send the UUID of the source to allow the destination 500b9d68df6SYury Kotov# to ensure it is the same. (since 4.2) 501b9d68df6SYury Kotov# 502a937b6aaSMarkus Armbruster# @background-snapshot: If enabled, the migration stream will be a 503a937b6aaSMarkus Armbruster# snapshot of the VM exactly at the point when the migration 504a937b6aaSMarkus Armbruster# procedure starts. The VM RAM is saved with running VM. (since 505a937b6aaSMarkus Armbruster# 6.0) 5066e8c25b4SAndrey Gruzdev# 507a937b6aaSMarkus Armbruster# @zero-copy-send: Controls behavior on sending memory pages on 508a937b6aaSMarkus Armbruster# migration. When true, enables a zero-copy mechanism for sending 509a937b6aaSMarkus Armbruster# memory pages, if host supports it. Requires that QEMU be 510a937b6aaSMarkus Armbruster# permitted to use locked memory for guest RAM pages. (since 7.1) 511a937b6aaSMarkus Armbruster# 512a937b6aaSMarkus Armbruster# @postcopy-preempt: If enabled, the migration process will allow 513a937b6aaSMarkus Armbruster# postcopy requests to preempt precopy stream, so postcopy 514a937b6aaSMarkus Armbruster# requests will be handled faster. This is a performance feature 515a937b6aaSMarkus Armbruster# and should not affect the correctness of postcopy migration. 516ce5b0f4aSPeter Xu# (since 7.1) 5171abaec9aSLeonardo Bras# 5186574232fSAvihai Horon# @switchover-ack: If enabled, migration will not stop the source VM 5196574232fSAvihai Horon# and complete the migration until an ACK is received from the 5206574232fSAvihai Horon# destination that it's OK to do so. Exactly when this ACK is 5219e272073SMarkus Armbruster# sent depends on the migrated devices that use this feature. For 5229e272073SMarkus Armbruster# example, a device can use it to make sure some of its data is 5239e272073SMarkus Armbruster# sent and loaded in the destination before doing switchover. 5246574232fSAvihai Horon# This can reduce downtime if devices that support this capability 5256574232fSAvihai Horon# are present. 'return-path' capability must be enabled to use 5266574232fSAvihai Horon# it. (since 8.1) 5276574232fSAvihai Horon# 528ef965377SHyman Huang(黄勇)# @dirty-limit: If enabled, migration will throttle vCPUs as needed to 529ef965377SHyman Huang(黄勇)# keep their dirty page rate within @vcpu-dirty-limit. This can 530ef965377SHyman Huang(黄勇)# improve responsiveness of large guests during live migration, 531ef965377SHyman Huang(黄勇)# and can result in more stable read performance. Requires KVM 532ef965377SHyman Huang(黄勇)# with accelerator property "dirty-ring-size" set. (Since 8.1) 533dc623955SHyman Huang(黄勇)# 5349fb49daaSMarkus Armbruster# Features: 535a937b6aaSMarkus Armbruster# 53666db46caSJuan Quintela# @deprecated: Member @block is deprecated. Use blockdev-mirror with 537dee70f51SHan Han# NBD instead. Member @compress is deprecated because it is 538864128dfSJuan Quintela# unreliable and untested. It is recommended to use multifd 539864128dfSJuan Quintela# migration, which offers an alternative compression 540864128dfSJuan Quintela# implementation that is reliable and tested. 54166db46caSJuan Quintela# 5429fb49daaSMarkus Armbruster# @unstable: Members @x-colo and @x-ignore-shared are experimental. 5439fb49daaSMarkus Armbruster# 54448685a8eSMarkus Armbruster# Since: 1.2 54548685a8eSMarkus Armbruster## 54648685a8eSMarkus Armbruster{ 'enum': 'MigrationCapability', 54748685a8eSMarkus Armbruster 'data': ['xbzrle', 'rdma-pin-all', 'auto-converge', 'zero-blocks', 548864128dfSJuan Quintela { 'name': 'compress', 'features': [ 'deprecated' ] }, 549864128dfSJuan Quintela 'events', 'postcopy-ram', 5509fb49daaSMarkus Armbruster { 'name': 'x-colo', 'features': [ 'unstable' ] }, 5519fb49daaSMarkus Armbruster 'release-ram', 55266db46caSJuan Quintela { 'name': 'block', 'features': [ 'deprecated' ] }, 55366db46caSJuan Quintela 'return-path', 'pause-before-switchover', 'multifd', 55418269069SYury Kotov 'dirty-bitmaps', 'postcopy-blocktime', 'late-block-activate', 5559fb49daaSMarkus Armbruster { 'name': 'x-ignore-shared', 'features': [ 'unstable' ] }, 5561abaec9aSLeonardo Bras 'validate-uuid', 'background-snapshot', 557dc623955SHyman Huang(黄勇) 'zero-copy-send', 'postcopy-preempt', 'switchover-ack', 558dc623955SHyman Huang(黄勇) 'dirty-limit'] } 55948685a8eSMarkus Armbruster 56048685a8eSMarkus Armbruster## 56148685a8eSMarkus Armbruster# @MigrationCapabilityStatus: 56248685a8eSMarkus Armbruster# 56348685a8eSMarkus Armbruster# Migration capability information 56448685a8eSMarkus Armbruster# 56548685a8eSMarkus Armbruster# @capability: capability enum 56648685a8eSMarkus Armbruster# 56748685a8eSMarkus Armbruster# @state: capability state bool 56848685a8eSMarkus Armbruster# 56948685a8eSMarkus Armbruster# Since: 1.2 57048685a8eSMarkus Armbruster## 57148685a8eSMarkus Armbruster{ 'struct': 'MigrationCapabilityStatus', 57248685a8eSMarkus Armbruster 'data': { 'capability': 'MigrationCapability', 'state': 'bool' } } 57348685a8eSMarkus Armbruster 57448685a8eSMarkus Armbruster## 57548685a8eSMarkus Armbruster# @migrate-set-capabilities: 57648685a8eSMarkus Armbruster# 57748685a8eSMarkus Armbruster# Enable/Disable the following migration capabilities (like xbzrle) 57848685a8eSMarkus Armbruster# 57948685a8eSMarkus Armbruster# @capabilities: json array of capability modifications to make 58048685a8eSMarkus Armbruster# 58148685a8eSMarkus Armbruster# Since: 1.2 58248685a8eSMarkus Armbruster# 58348685a8eSMarkus Armbruster# Example: 58448685a8eSMarkus Armbruster# 58548685a8eSMarkus Armbruster# -> { "execute": "migrate-set-capabilities" , "arguments": 58648685a8eSMarkus Armbruster# { "capabilities": [ { "capability": "xbzrle", "state": true } ] } } 58737fa48a4SMarkus Armbruster# <- { "return": {} } 58848685a8eSMarkus Armbruster## 58948685a8eSMarkus Armbruster{ 'command': 'migrate-set-capabilities', 59048685a8eSMarkus Armbruster 'data': { 'capabilities': ['MigrationCapabilityStatus'] } } 59148685a8eSMarkus Armbruster 59248685a8eSMarkus Armbruster## 59348685a8eSMarkus Armbruster# @query-migrate-capabilities: 59448685a8eSMarkus Armbruster# 59548685a8eSMarkus Armbruster# Returns information about the current migration capabilities status 59648685a8eSMarkus Armbruster# 597d93ed1bdSMarkus Armbruster# Returns: @MigrationCapabilityStatus 59848685a8eSMarkus Armbruster# 59948685a8eSMarkus Armbruster# Since: 1.2 60048685a8eSMarkus Armbruster# 60148685a8eSMarkus Armbruster# Example: 60248685a8eSMarkus Armbruster# 60348685a8eSMarkus Armbruster# -> { "execute": "query-migrate-capabilities" } 60448685a8eSMarkus Armbruster# <- { "return": [ 60548685a8eSMarkus Armbruster# {"state": false, "capability": "xbzrle"}, 60648685a8eSMarkus Armbruster# {"state": false, "capability": "rdma-pin-all"}, 60748685a8eSMarkus Armbruster# {"state": false, "capability": "auto-converge"}, 60848685a8eSMarkus Armbruster# {"state": false, "capability": "zero-blocks"}, 60948685a8eSMarkus Armbruster# {"state": false, "capability": "compress"}, 61048685a8eSMarkus Armbruster# {"state": true, "capability": "events"}, 61148685a8eSMarkus Armbruster# {"state": false, "capability": "postcopy-ram"}, 61248685a8eSMarkus Armbruster# {"state": false, "capability": "x-colo"} 61348685a8eSMarkus Armbruster# ]} 61448685a8eSMarkus Armbruster## 61548685a8eSMarkus Armbruster{ 'command': 'query-migrate-capabilities', 'returns': ['MigrationCapabilityStatus']} 61648685a8eSMarkus Armbruster 61748685a8eSMarkus Armbruster## 61896eef042SJuan Quintela# @MultiFDCompression: 61996eef042SJuan Quintela# 62096eef042SJuan Quintela# An enumeration of multifd compression methods. 62196eef042SJuan Quintela# 62296eef042SJuan Quintela# @none: no compression. 623a937b6aaSMarkus Armbruster# 6247ec2c2b3SJuan Quintela# @zlib: use zlib compression method. 625a937b6aaSMarkus Armbruster# 62687dc6f5fSJuan Quintela# @zstd: use zstd compression method. 62796eef042SJuan Quintela# 62896eef042SJuan Quintela# Since: 5.0 62996eef042SJuan Quintela## 63096eef042SJuan Quintela{ 'enum': 'MultiFDCompression', 63187dc6f5fSJuan Quintela 'data': [ 'none', 'zlib', 6328a9f1e1dSMarc-André Lureau { 'name': 'zstd', 'if': 'CONFIG_ZSTD' } ] } 63396eef042SJuan Quintela 63496eef042SJuan Quintela## 635eea1e5c9SSteve Sistare# @MigMode: 636eea1e5c9SSteve Sistare# 637eea1e5c9SSteve Sistare# @normal: the original form of migration. (since 8.2) 638eea1e5c9SSteve Sistare# 639a87e6451SSteve Sistare# @cpr-reboot: The migrate command saves state to a file, allowing one to 640a87e6451SSteve Sistare# quit qemu, reboot to an updated kernel, and restart an updated 641a87e6451SSteve Sistare# version of qemu. The caller must specify a migration URI 642a87e6451SSteve Sistare# that writes to and reads from a file. Unlike normal mode, 643a87e6451SSteve Sistare# the use of certain local storage options does not block the 644a87e6451SSteve Sistare# migration, but the caller must not modify guest block devices 645a87e6451SSteve Sistare# between the quit and restart. To avoid saving guest RAM to the 646a87e6451SSteve Sistare# file, the memory backend must be shared, and the @x-ignore-shared 647a87e6451SSteve Sistare# migration capability must be set. Guest RAM must be non-volatile 648a87e6451SSteve Sistare# across reboot, such as by backing it with a dax device, but this 649a87e6451SSteve Sistare# is not enforced. The restarted qemu arguments must match those 650a87e6451SSteve Sistare# used to initially start qemu, plus the -incoming option. 651a87e6451SSteve Sistare# (since 8.2) 652eea1e5c9SSteve Sistare## 653eea1e5c9SSteve Sistare{ 'enum': 'MigMode', 654a87e6451SSteve Sistare 'data': [ 'normal', 'cpr-reboot' ] } 655eea1e5c9SSteve Sistare 656eea1e5c9SSteve Sistare## 6576e9f21a2SPeter Krempa# @BitmapMigrationBitmapAliasTransform: 6586e9f21a2SPeter Krempa# 659a937b6aaSMarkus Armbruster# @persistent: If present, the bitmap will be made persistent or 660a937b6aaSMarkus Armbruster# transient depending on this parameter. 6616e9f21a2SPeter Krempa# 6626e9f21a2SPeter Krempa# Since: 6.0 6636e9f21a2SPeter Krempa## 6646e9f21a2SPeter Krempa{ 'struct': 'BitmapMigrationBitmapAliasTransform', 6656e9f21a2SPeter Krempa 'data': { 6666e9f21a2SPeter Krempa '*persistent': 'bool' 6676e9f21a2SPeter Krempa } } 6686e9f21a2SPeter Krempa 6696e9f21a2SPeter Krempa## 67031e4c354SMax Reitz# @BitmapMigrationBitmapAlias: 67131e4c354SMax Reitz# 67231e4c354SMax Reitz# @name: The name of the bitmap. 67331e4c354SMax Reitz# 67431e4c354SMax Reitz# @alias: An alias name for migration (for example the bitmap name on 67531e4c354SMax Reitz# the opposite site). 67631e4c354SMax Reitz# 677a937b6aaSMarkus Armbruster# @transform: Allows the modification of the migrated bitmap. (since 678a937b6aaSMarkus Armbruster# 6.0) 6796e9f21a2SPeter Krempa# 68031e4c354SMax Reitz# Since: 5.2 68131e4c354SMax Reitz## 68231e4c354SMax Reitz{ 'struct': 'BitmapMigrationBitmapAlias', 68331e4c354SMax Reitz 'data': { 68431e4c354SMax Reitz 'name': 'str', 6856e9f21a2SPeter Krempa 'alias': 'str', 6866e9f21a2SPeter Krempa '*transform': 'BitmapMigrationBitmapAliasTransform' 68731e4c354SMax Reitz } } 68831e4c354SMax Reitz 68931e4c354SMax Reitz## 69031e4c354SMax Reitz# @BitmapMigrationNodeAlias: 69131e4c354SMax Reitz# 69231e4c354SMax Reitz# Maps a block node name and the bitmaps it has to aliases for dirty 69331e4c354SMax Reitz# bitmap migration. 69431e4c354SMax Reitz# 69531e4c354SMax Reitz# @node-name: A block node name. 69631e4c354SMax Reitz# 697a937b6aaSMarkus Armbruster# @alias: An alias block node name for migration (for example the node 698a937b6aaSMarkus Armbruster# name on the opposite site). 69931e4c354SMax Reitz# 70031e4c354SMax Reitz# @bitmaps: Mappings for the bitmaps on this node. 70131e4c354SMax Reitz# 70231e4c354SMax Reitz# Since: 5.2 70331e4c354SMax Reitz## 70431e4c354SMax Reitz{ 'struct': 'BitmapMigrationNodeAlias', 70531e4c354SMax Reitz 'data': { 70631e4c354SMax Reitz 'node-name': 'str', 70731e4c354SMax Reitz 'alias': 'str', 70831e4c354SMax Reitz 'bitmaps': [ 'BitmapMigrationBitmapAlias' ] 70931e4c354SMax Reitz } } 71031e4c354SMax Reitz 71131e4c354SMax Reitz## 71248685a8eSMarkus Armbruster# @MigrationParameter: 71348685a8eSMarkus Armbruster# 71448685a8eSMarkus Armbruster# Migration parameters enumeration 71548685a8eSMarkus Armbruster# 716a937b6aaSMarkus Armbruster# @announce-initial: Initial delay (in milliseconds) before sending 717a937b6aaSMarkus Armbruster# the first announce (Since 4.0) 718ee3d96baSDr. David Alan Gilbert# 719a937b6aaSMarkus Armbruster# @announce-max: Maximum delay (in milliseconds) between packets in 720a937b6aaSMarkus Armbruster# the announcement (Since 4.0) 721ee3d96baSDr. David Alan Gilbert# 722a937b6aaSMarkus Armbruster# @announce-rounds: Number of self-announce packets sent after 723a937b6aaSMarkus Armbruster# migration (Since 4.0) 724ee3d96baSDr. David Alan Gilbert# 725a937b6aaSMarkus Armbruster# @announce-step: Increase in delay (in milliseconds) between 726a937b6aaSMarkus Armbruster# subsequent packets in the announcement (Since 4.0) 727ee3d96baSDr. David Alan Gilbert# 728a937b6aaSMarkus Armbruster# @compress-level: Set the compression level to be used in live 729a937b6aaSMarkus Armbruster# migration, the compression level is an integer between 0 and 9, 730a937b6aaSMarkus Armbruster# where 0 means no compression, 1 means the best compression 731a937b6aaSMarkus Armbruster# speed, and 9 means best compression ratio which will consume 732a937b6aaSMarkus Armbruster# more CPU. 73348685a8eSMarkus Armbruster# 734a937b6aaSMarkus Armbruster# @compress-threads: Set compression thread count to be used in live 735a937b6aaSMarkus Armbruster# migration, the compression thread count is an integer between 1 736a937b6aaSMarkus Armbruster# and 255. 73748685a8eSMarkus Armbruster# 738a937b6aaSMarkus Armbruster# @compress-wait-thread: Controls behavior when all compression 739a937b6aaSMarkus Armbruster# threads are currently busy. If true (default), wait for a free 740a937b6aaSMarkus Armbruster# compression thread to become available; otherwise, send the page 741a937b6aaSMarkus Armbruster# uncompressed. (Since 3.1) 7421d58872aSXiao Guangrong# 743a937b6aaSMarkus Armbruster# @decompress-threads: Set decompression thread count to be used in 744a937b6aaSMarkus Armbruster# live migration, the decompression thread count is an integer 745a937b6aaSMarkus Armbruster# between 1 and 255. Usually, decompression is at least 4 times as 746a937b6aaSMarkus Armbruster# fast as compression, so set the decompress-threads to the number 747a937b6aaSMarkus Armbruster# about 1/4 of compress-threads is adequate. 74848685a8eSMarkus Armbruster# 749a937b6aaSMarkus Armbruster# @throttle-trigger-threshold: The ratio of bytes_dirty_period and 750a937b6aaSMarkus Armbruster# bytes_xfer_period to trigger throttling. It is expressed as 751a937b6aaSMarkus Armbruster# percentage. The default value is 50. (Since 5.0) 752dc14a470SKeqian Zhu# 753a937b6aaSMarkus Armbruster# @cpu-throttle-initial: Initial percentage of time guest cpus are 754a937b6aaSMarkus Armbruster# throttled when migration auto-converge is activated. The 75548685a8eSMarkus Armbruster# default value is 20. (Since 2.7) 75648685a8eSMarkus Armbruster# 75748685a8eSMarkus Armbruster# @cpu-throttle-increment: throttle percentage increase each time 758a937b6aaSMarkus Armbruster# auto-converge detects that migration is not making progress. 759a937b6aaSMarkus Armbruster# The default value is 10. (Since 2.7) 76048685a8eSMarkus Armbruster# 761a937b6aaSMarkus Armbruster# @cpu-throttle-tailslow: Make CPU throttling slower at tail stage At 762a937b6aaSMarkus Armbruster# the tail stage of throttling, the Guest is very sensitive to CPU 763a937b6aaSMarkus Armbruster# percentage while the @cpu-throttle -increment is excessive 764a937b6aaSMarkus Armbruster# usually at tail stage. If this parameter is true, we will 765a937b6aaSMarkus Armbruster# compute the ideal CPU percentage used by the Guest, which may 766a937b6aaSMarkus Armbruster# exactly make the dirty rate match the dirty rate threshold. 767a937b6aaSMarkus Armbruster# Then we will choose a smaller throttle increment between the one 768a937b6aaSMarkus Armbruster# specified by @cpu-throttle-increment and the one generated by 769a937b6aaSMarkus Armbruster# ideal CPU percentage. Therefore, it is compatible to 770a937b6aaSMarkus Armbruster# traditional throttling, meanwhile the throttle increment won't 771a937b6aaSMarkus Armbruster# be excessive at tail stage. The default value is false. (Since 772a937b6aaSMarkus Armbruster# 5.1) 773cbbf8182SKeqian Zhu# 774a937b6aaSMarkus Armbruster# @tls-creds: ID of the 'tls-creds' object that provides credentials 775a937b6aaSMarkus Armbruster# for establishing a TLS connection over the migration data 776a937b6aaSMarkus Armbruster# channel. On the outgoing side of the migration, the credentials 777a937b6aaSMarkus Armbruster# must be for a 'client' endpoint, while for the incoming side the 778a937b6aaSMarkus Armbruster# credentials must be for a 'server' endpoint. Setting this will 779a937b6aaSMarkus Armbruster# enable TLS for all migrations. The default is unset, resulting 780a937b6aaSMarkus Armbruster# in unsecured migration at the QEMU level. (Since 2.7) 78148685a8eSMarkus Armbruster# 782a937b6aaSMarkus Armbruster# @tls-hostname: hostname of the target host for the migration. This 783a937b6aaSMarkus Armbruster# is required when using x509 based TLS credentials and the 784a937b6aaSMarkus Armbruster# migration URI does not already include a hostname. For example 785a937b6aaSMarkus Armbruster# if using fd: or exec: based migration, the hostname must be 786a937b6aaSMarkus Armbruster# provided so that the server's x509 certificate identity can be 787a937b6aaSMarkus Armbruster# validated. (Since 2.7) 78848685a8eSMarkus Armbruster# 789a937b6aaSMarkus Armbruster# @tls-authz: ID of the 'authz' object subclass that provides access 790a937b6aaSMarkus Armbruster# control checking of the TLS x509 certificate distinguished name. 791d2f1d29bSDaniel P. Berrange# This object is only resolved at time of use, so can be deleted 792d2f1d29bSDaniel P. Berrange# and recreated on the fly while the migration server is active. 793d2f1d29bSDaniel P. Berrange# If missing, it will default to denying access (Since 4.0) 794d2f1d29bSDaniel P. Berrange# 795a937b6aaSMarkus Armbruster# @max-bandwidth: to set maximum speed for migration. maximum speed 796a937b6aaSMarkus Armbruster# in bytes per second. (Since 2.8) 79748685a8eSMarkus Armbruster# 7988b239597SPeter Xu# @avail-switchover-bandwidth: to set the available bandwidth that 7998b239597SPeter Xu# migration can use during switchover phase. NOTE! This does not 8008b239597SPeter Xu# limit the bandwidth during switchover, but only for calculations when 8018b239597SPeter Xu# making decisions to switchover. By default, this value is zero, 8028b239597SPeter Xu# which means QEMU will estimate the bandwidth automatically. This can 8038b239597SPeter Xu# be set when the estimated value is not accurate, while the user is 8048b239597SPeter Xu# able to guarantee such bandwidth is available when switching over. 8058b239597SPeter Xu# When specified correctly, this can make the switchover decision much 8068b239597SPeter Xu# more accurate. (Since 8.2) 8078b239597SPeter Xu# 808a937b6aaSMarkus Armbruster# @downtime-limit: set maximum tolerated downtime for migration. 809a937b6aaSMarkus Armbruster# maximum downtime in milliseconds (Since 2.8) 81048685a8eSMarkus Armbruster# 811a937b6aaSMarkus Armbruster# @x-checkpoint-delay: The delay time (in ms) between two COLO 812a937b6aaSMarkus Armbruster# checkpoints in periodic mode. (Since 2.8) 81348685a8eSMarkus Armbruster# 81448685a8eSMarkus Armbruster# @block-incremental: Affects how much storage is migrated when the 81548685a8eSMarkus Armbruster# block migration capability is enabled. When false, the entire 816a937b6aaSMarkus Armbruster# storage backing chain is migrated into a flattened image at the 817a937b6aaSMarkus Armbruster# destination; when true, only the active qcow2 layer is migrated 818a937b6aaSMarkus Armbruster# and the destination must already have access to the same backing 819a937b6aaSMarkus Armbruster# chain as was used on the source. (since 2.10) 82048685a8eSMarkus Armbruster# 821cbfd6c95SJuan Quintela# @multifd-channels: Number of channels used to migrate data in 822a937b6aaSMarkus Armbruster# parallel. This is the same number that the number of sockets 823a937b6aaSMarkus Armbruster# used for migration. The default value is 2 (since 4.0) 8244075fb1cSJuan Quintela# 82573af8dd8SJuan Quintela# @xbzrle-cache-size: cache size to be used by XBZRLE migration. It 826a937b6aaSMarkus Armbruster# needs to be a multiple of the target page size and a power of 2 82773af8dd8SJuan Quintela# (Since 2.11) 82873af8dd8SJuan Quintela# 829a937b6aaSMarkus Armbruster# @max-postcopy-bandwidth: Background transfer bandwidth during 830a937b6aaSMarkus Armbruster# postcopy. Defaults to 0 (unlimited). In bytes per second. 8317e555c6cSDr. David Alan Gilbert# (Since 3.0) 8324cbc9c7fSLi Qiang# 833a937b6aaSMarkus Armbruster# @max-cpu-throttle: maximum cpu throttle percentage. Defaults to 99. 834a937b6aaSMarkus Armbruster# (Since 3.1) 835ee3d96baSDr. David Alan Gilbert# 836a937b6aaSMarkus Armbruster# @multifd-compression: Which compression method to use. Defaults to 837a937b6aaSMarkus Armbruster# none. (Since 5.0) 83896eef042SJuan Quintela# 8399004db48SJuan Quintela# @multifd-zlib-level: Set the compression level to be used in live 840a937b6aaSMarkus Armbruster# migration, the compression level is an integer between 0 and 9, 841a937b6aaSMarkus Armbruster# where 0 means no compression, 1 means the best compression 842a937b6aaSMarkus Armbruster# speed, and 9 means best compression ratio which will consume 843a937b6aaSMarkus Armbruster# more CPU. Defaults to 1. (Since 5.0) 8449004db48SJuan Quintela# 8456a9ad154SJuan Quintela# @multifd-zstd-level: Set the compression level to be used in live 846a937b6aaSMarkus Armbruster# migration, the compression level is an integer between 0 and 20, 847a937b6aaSMarkus Armbruster# where 0 means no compression, 1 means the best compression 848a937b6aaSMarkus Armbruster# speed, and 20 means best compression ratio which will consume 849a937b6aaSMarkus Armbruster# more CPU. Defaults to 1. (Since 5.0) 850abb6295bSLeonardo Bras# 85131e4c354SMax Reitz# @block-bitmap-mapping: Maps block nodes and bitmaps on them to 852a937b6aaSMarkus Armbruster# aliases for the purpose of dirty bitmap migration. Such aliases 853a937b6aaSMarkus Armbruster# may for example be the corresponding names on the opposite site. 854a937b6aaSMarkus Armbruster# The mapping must be one-to-one, but not necessarily complete: On 855a937b6aaSMarkus Armbruster# the source, unmapped bitmaps and all bitmaps on unmapped nodes 856a937b6aaSMarkus Armbruster# will be ignored. On the destination, encountering an unmapped 857a937b6aaSMarkus Armbruster# alias in the incoming migration stream will result in a report, 858a937b6aaSMarkus Armbruster# and all further bitmap migration data will then be discarded. 859a937b6aaSMarkus Armbruster# Note that the destination does not know about bitmaps it does 860a937b6aaSMarkus Armbruster# not receive, so there is no limitation or requirement regarding 861a937b6aaSMarkus Armbruster# the number of bitmaps received, or how they are named, or on 862a937b6aaSMarkus Armbruster# which nodes they are placed. By default (when this parameter 863a937b6aaSMarkus Armbruster# has never been set), bitmap names are mapped to themselves. 864a937b6aaSMarkus Armbruster# Nodes are mapped to their block device name if there is one, and 865a937b6aaSMarkus Armbruster# to their node name otherwise. (Since 5.2) 86631e4c354SMax Reitz# 8678abc8115SHyman Huang(黄勇)# @x-vcpu-dirty-limit-period: Periodic time (in milliseconds) of dirty 8688abc8115SHyman Huang(黄勇)# limit during live migration. Should be in the range 1 to 1000ms. 8698abc8115SHyman Huang(黄勇)# Defaults to 1000ms. (Since 8.1) 8704d807857SHyman Huang(黄勇)# 87109f9ec99SHyman Huang(黄勇)# @vcpu-dirty-limit: Dirtyrate limit (MB/s) during live migration. 87209f9ec99SHyman Huang(黄勇)# Defaults to 1. (Since 8.1) 87309f9ec99SHyman Huang(黄勇)# 874eea1e5c9SSteve Sistare# @mode: Migration mode. See description in @MigMode. Default is 'normal'. 875eea1e5c9SSteve Sistare# (Since 8.2) 876eea1e5c9SSteve Sistare# 8779fb49daaSMarkus Armbruster# Features: 878a937b6aaSMarkus Armbruster# 87966db46caSJuan Quintela# @deprecated: Member @block-incremental is deprecated. Use 880864128dfSJuan Quintela# blockdev-mirror with NBD instead. Members @compress-level, 881864128dfSJuan Quintela# @compress-threads, @decompress-threads and @compress-wait-thread 882864128dfSJuan Quintela# are deprecated because @compression is deprecated. 88366db46caSJuan Quintela# 8844d807857SHyman Huang(黄勇)# @unstable: Members @x-checkpoint-delay and @x-vcpu-dirty-limit-period 8854d807857SHyman Huang(黄勇)# are experimental. 8869fb49daaSMarkus Armbruster# 88748685a8eSMarkus Armbruster# Since: 2.4 88848685a8eSMarkus Armbruster## 88948685a8eSMarkus Armbruster{ 'enum': 'MigrationParameter', 890ee3d96baSDr. David Alan Gilbert 'data': ['announce-initial', 'announce-max', 891ee3d96baSDr. David Alan Gilbert 'announce-rounds', 'announce-step', 892864128dfSJuan Quintela { 'name': 'compress-level', 'features': [ 'deprecated' ] }, 893864128dfSJuan Quintela { 'name': 'compress-threads', 'features': [ 'deprecated' ] }, 894864128dfSJuan Quintela { 'name': 'decompress-threads', 'features': [ 'deprecated' ] }, 895864128dfSJuan Quintela { 'name': 'compress-wait-thread', 'features': [ 'deprecated' ] }, 896864128dfSJuan Quintela 'throttle-trigger-threshold', 89748685a8eSMarkus Armbruster 'cpu-throttle-initial', 'cpu-throttle-increment', 898cbbf8182SKeqian Zhu 'cpu-throttle-tailslow', 899d2f1d29bSDaniel P. Berrange 'tls-creds', 'tls-hostname', 'tls-authz', 'max-bandwidth', 9008b239597SPeter Xu 'avail-switchover-bandwidth', 'downtime-limit', 9019fb49daaSMarkus Armbruster { 'name': 'x-checkpoint-delay', 'features': [ 'unstable' ] }, 90266db46caSJuan Quintela { 'name': 'block-incremental', 'features': [ 'deprecated' ] }, 903cbfd6c95SJuan Quintela 'multifd-channels', 9044cbc9c7fSLi Qiang 'xbzrle-cache-size', 'max-postcopy-bandwidth', 9059004db48SJuan Quintela 'max-cpu-throttle', 'multifd-compression', 90631e4c354SMax Reitz 'multifd-zlib-level', 'multifd-zstd-level', 9074d807857SHyman Huang(黄勇) 'block-bitmap-mapping', 90809f9ec99SHyman Huang(黄勇) { 'name': 'x-vcpu-dirty-limit-period', 'features': ['unstable'] }, 909eea1e5c9SSteve Sistare 'vcpu-dirty-limit', 910eea1e5c9SSteve Sistare 'mode'] } 91148685a8eSMarkus Armbruster 91248685a8eSMarkus Armbruster## 91348685a8eSMarkus Armbruster# @MigrateSetParameters: 91448685a8eSMarkus Armbruster# 915a937b6aaSMarkus Armbruster# @announce-initial: Initial delay (in milliseconds) before sending 916a937b6aaSMarkus Armbruster# the first announce (Since 4.0) 917ee3d96baSDr. David Alan Gilbert# 918a937b6aaSMarkus Armbruster# @announce-max: Maximum delay (in milliseconds) between packets in 919a937b6aaSMarkus Armbruster# the announcement (Since 4.0) 920ee3d96baSDr. David Alan Gilbert# 921a937b6aaSMarkus Armbruster# @announce-rounds: Number of self-announce packets sent after 922a937b6aaSMarkus Armbruster# migration (Since 4.0) 923ee3d96baSDr. David Alan Gilbert# 924a937b6aaSMarkus Armbruster# @announce-step: Increase in delay (in milliseconds) between 925a937b6aaSMarkus Armbruster# subsequent packets in the announcement (Since 4.0) 926ee3d96baSDr. David Alan Gilbert# 92748685a8eSMarkus Armbruster# @compress-level: compression level 92848685a8eSMarkus Armbruster# 92948685a8eSMarkus Armbruster# @compress-threads: compression thread count 93048685a8eSMarkus Armbruster# 931a937b6aaSMarkus Armbruster# @compress-wait-thread: Controls behavior when all compression 932a937b6aaSMarkus Armbruster# threads are currently busy. If true (default), wait for a free 933a937b6aaSMarkus Armbruster# compression thread to become available; otherwise, send the page 934a937b6aaSMarkus Armbruster# uncompressed. (Since 3.1) 9351d58872aSXiao Guangrong# 93648685a8eSMarkus Armbruster# @decompress-threads: decompression thread count 93748685a8eSMarkus Armbruster# 938a937b6aaSMarkus Armbruster# @throttle-trigger-threshold: The ratio of bytes_dirty_period and 939a937b6aaSMarkus Armbruster# bytes_xfer_period to trigger throttling. It is expressed as 940a937b6aaSMarkus Armbruster# percentage. The default value is 50. (Since 5.0) 941dc14a470SKeqian Zhu# 94248685a8eSMarkus Armbruster# @cpu-throttle-initial: Initial percentage of time guest cpus are 943a937b6aaSMarkus Armbruster# throttled when migration auto-converge is activated. The 944a937b6aaSMarkus Armbruster# default value is 20. (Since 2.7) 94548685a8eSMarkus Armbruster# 94648685a8eSMarkus Armbruster# @cpu-throttle-increment: throttle percentage increase each time 947a937b6aaSMarkus Armbruster# auto-converge detects that migration is not making progress. 948a937b6aaSMarkus Armbruster# The default value is 10. (Since 2.7) 94948685a8eSMarkus Armbruster# 950a937b6aaSMarkus Armbruster# @cpu-throttle-tailslow: Make CPU throttling slower at tail stage At 951a937b6aaSMarkus Armbruster# the tail stage of throttling, the Guest is very sensitive to CPU 952a937b6aaSMarkus Armbruster# percentage while the @cpu-throttle -increment is excessive 953a937b6aaSMarkus Armbruster# usually at tail stage. If this parameter is true, we will 954a937b6aaSMarkus Armbruster# compute the ideal CPU percentage used by the Guest, which may 955a937b6aaSMarkus Armbruster# exactly make the dirty rate match the dirty rate threshold. 956a937b6aaSMarkus Armbruster# Then we will choose a smaller throttle increment between the one 957a937b6aaSMarkus Armbruster# specified by @cpu-throttle-increment and the one generated by 958a937b6aaSMarkus Armbruster# ideal CPU percentage. Therefore, it is compatible to 959a937b6aaSMarkus Armbruster# traditional throttling, meanwhile the throttle increment won't 960a937b6aaSMarkus Armbruster# be excessive at tail stage. The default value is false. (Since 961a937b6aaSMarkus Armbruster# 5.1) 962cbbf8182SKeqian Zhu# 96348685a8eSMarkus Armbruster# @tls-creds: ID of the 'tls-creds' object that provides credentials 96448685a8eSMarkus Armbruster# for establishing a TLS connection over the migration data 96548685a8eSMarkus Armbruster# channel. On the outgoing side of the migration, the credentials 96648685a8eSMarkus Armbruster# must be for a 'client' endpoint, while for the incoming side the 967a937b6aaSMarkus Armbruster# credentials must be for a 'server' endpoint. Setting this to a 968a937b6aaSMarkus Armbruster# non-empty string enables TLS for all migrations. An empty 969a937b6aaSMarkus Armbruster# string means that QEMU will use plain text mode for migration, 970a937b6aaSMarkus Armbruster# rather than TLS (Since 2.9) Previously (since 2.7), this was 971a937b6aaSMarkus Armbruster# reported by omitting tls-creds instead. 97248685a8eSMarkus Armbruster# 97348685a8eSMarkus Armbruster# @tls-hostname: hostname of the target host for the migration. This 97448685a8eSMarkus Armbruster# is required when using x509 based TLS credentials and the 975a937b6aaSMarkus Armbruster# migration URI does not already include a hostname. For example 976a937b6aaSMarkus Armbruster# if using fd: or exec: based migration, the hostname must be 977a937b6aaSMarkus Armbruster# provided so that the server's x509 certificate identity can be 978a937b6aaSMarkus Armbruster# validated. (Since 2.7) An empty string means that QEMU will use 979a937b6aaSMarkus Armbruster# the hostname associated with the migration URI, if any. (Since 980a937b6aaSMarkus Armbruster# 2.9) Previously (since 2.7), this was reported by omitting 98148685a8eSMarkus Armbruster# tls-hostname instead. 98248685a8eSMarkus Armbruster# 98366fcb9d6SPeter Xu# @tls-authz: ID of the 'authz' object subclass that provides access 98466fcb9d6SPeter Xu# control checking of the TLS x509 certificate distinguished name. 98566fcb9d6SPeter Xu# (Since 4.0) 98666fcb9d6SPeter Xu# 987a937b6aaSMarkus Armbruster# @max-bandwidth: to set maximum speed for migration. maximum speed 988a937b6aaSMarkus Armbruster# in bytes per second. (Since 2.8) 98948685a8eSMarkus Armbruster# 9908b239597SPeter Xu# @avail-switchover-bandwidth: to set the available bandwidth that 9918b239597SPeter Xu# migration can use during switchover phase. NOTE! This does not 9928b239597SPeter Xu# limit the bandwidth during switchover, but only for calculations when 9938b239597SPeter Xu# making decisions to switchover. By default, this value is zero, 9948b239597SPeter Xu# which means QEMU will estimate the bandwidth automatically. This can 9958b239597SPeter Xu# be set when the estimated value is not accurate, while the user is 9968b239597SPeter Xu# able to guarantee such bandwidth is available when switching over. 9978b239597SPeter Xu# When specified correctly, this can make the switchover decision much 9988b239597SPeter Xu# more accurate. (Since 8.2) 9998b239597SPeter Xu# 1000a937b6aaSMarkus Armbruster# @downtime-limit: set maximum tolerated downtime for migration. 1001a937b6aaSMarkus Armbruster# maximum downtime in milliseconds (Since 2.8) 100248685a8eSMarkus Armbruster# 1003a937b6aaSMarkus Armbruster# @x-checkpoint-delay: the delay time between two COLO checkpoints. 1004a937b6aaSMarkus Armbruster# (Since 2.8) 100548685a8eSMarkus Armbruster# 100648685a8eSMarkus Armbruster# @block-incremental: Affects how much storage is migrated when the 100748685a8eSMarkus Armbruster# block migration capability is enabled. When false, the entire 1008a937b6aaSMarkus Armbruster# storage backing chain is migrated into a flattened image at the 1009a937b6aaSMarkus Armbruster# destination; when true, only the active qcow2 layer is migrated 1010a937b6aaSMarkus Armbruster# and the destination must already have access to the same backing 1011a937b6aaSMarkus Armbruster# chain as was used on the source. (since 2.10) 101248685a8eSMarkus Armbruster# 1013cbfd6c95SJuan Quintela# @multifd-channels: Number of channels used to migrate data in 1014a937b6aaSMarkus Armbruster# parallel. This is the same number that the number of sockets 1015a937b6aaSMarkus Armbruster# used for migration. The default value is 2 (since 4.0) 10164075fb1cSJuan Quintela# 101773af8dd8SJuan Quintela# @xbzrle-cache-size: cache size to be used by XBZRLE migration. It 1018a937b6aaSMarkus Armbruster# needs to be a multiple of the target page size and a power of 2 101973af8dd8SJuan Quintela# (Since 2.11) 10207e555c6cSDr. David Alan Gilbert# 1021a937b6aaSMarkus Armbruster# @max-postcopy-bandwidth: Background transfer bandwidth during 1022a937b6aaSMarkus Armbruster# postcopy. Defaults to 0 (unlimited). In bytes per second. 10237e555c6cSDr. David Alan Gilbert# (Since 3.0) 10244cbc9c7fSLi Qiang# 1025a937b6aaSMarkus Armbruster# @max-cpu-throttle: maximum cpu throttle percentage. The default 1026a937b6aaSMarkus Armbruster# value is 99. (Since 3.1) 10274cbc9c7fSLi Qiang# 1028a937b6aaSMarkus Armbruster# @multifd-compression: Which compression method to use. Defaults to 1029a937b6aaSMarkus Armbruster# none. (Since 5.0) 103096eef042SJuan Quintela# 10319004db48SJuan Quintela# @multifd-zlib-level: Set the compression level to be used in live 1032a937b6aaSMarkus Armbruster# migration, the compression level is an integer between 0 and 9, 1033a937b6aaSMarkus Armbruster# where 0 means no compression, 1 means the best compression 1034a937b6aaSMarkus Armbruster# speed, and 9 means best compression ratio which will consume 1035a937b6aaSMarkus Armbruster# more CPU. Defaults to 1. (Since 5.0) 10369004db48SJuan Quintela# 10376a9ad154SJuan Quintela# @multifd-zstd-level: Set the compression level to be used in live 1038a937b6aaSMarkus Armbruster# migration, the compression level is an integer between 0 and 20, 1039a937b6aaSMarkus Armbruster# where 0 means no compression, 1 means the best compression 1040a937b6aaSMarkus Armbruster# speed, and 20 means best compression ratio which will consume 1041a937b6aaSMarkus Armbruster# more CPU. Defaults to 1. (Since 5.0) 10426a9ad154SJuan Quintela# 104331e4c354SMax Reitz# @block-bitmap-mapping: Maps block nodes and bitmaps on them to 1044a937b6aaSMarkus Armbruster# aliases for the purpose of dirty bitmap migration. Such aliases 1045a937b6aaSMarkus Armbruster# may for example be the corresponding names on the opposite site. 1046a937b6aaSMarkus Armbruster# The mapping must be one-to-one, but not necessarily complete: On 1047a937b6aaSMarkus Armbruster# the source, unmapped bitmaps and all bitmaps on unmapped nodes 1048a937b6aaSMarkus Armbruster# will be ignored. On the destination, encountering an unmapped 1049a937b6aaSMarkus Armbruster# alias in the incoming migration stream will result in a report, 1050a937b6aaSMarkus Armbruster# and all further bitmap migration data will then be discarded. 1051a937b6aaSMarkus Armbruster# Note that the destination does not know about bitmaps it does 1052a937b6aaSMarkus Armbruster# not receive, so there is no limitation or requirement regarding 1053a937b6aaSMarkus Armbruster# the number of bitmaps received, or how they are named, or on 1054a937b6aaSMarkus Armbruster# which nodes they are placed. By default (when this parameter 1055a937b6aaSMarkus Armbruster# has never been set), bitmap names are mapped to themselves. 1056a937b6aaSMarkus Armbruster# Nodes are mapped to their block device name if there is one, and 1057a937b6aaSMarkus Armbruster# to their node name otherwise. (Since 5.2) 105831e4c354SMax Reitz# 10598abc8115SHyman Huang(黄勇)# @x-vcpu-dirty-limit-period: Periodic time (in milliseconds) of dirty 10608abc8115SHyman Huang(黄勇)# limit during live migration. Should be in the range 1 to 1000ms. 10618abc8115SHyman Huang(黄勇)# Defaults to 1000ms. (Since 8.1) 10624d807857SHyman Huang(黄勇)# 106309f9ec99SHyman Huang(黄勇)# @vcpu-dirty-limit: Dirtyrate limit (MB/s) during live migration. 106409f9ec99SHyman Huang(黄勇)# Defaults to 1. (Since 8.1) 106509f9ec99SHyman Huang(黄勇)# 1066eea1e5c9SSteve Sistare# @mode: Migration mode. See description in @MigMode. Default is 'normal'. 1067eea1e5c9SSteve Sistare# (Since 8.2) 1068eea1e5c9SSteve Sistare# 10699fb49daaSMarkus Armbruster# Features: 1070a937b6aaSMarkus Armbruster# 107166db46caSJuan Quintela# @deprecated: Member @block-incremental is deprecated. Use 1072864128dfSJuan Quintela# blockdev-mirror with NBD instead. Members @compress-level, 1073864128dfSJuan Quintela# @compress-threads, @decompress-threads and @compress-wait-thread 1074864128dfSJuan Quintela# are deprecated because @compression is deprecated. 107566db46caSJuan Quintela# 10764d807857SHyman Huang(黄勇)# @unstable: Members @x-checkpoint-delay and @x-vcpu-dirty-limit-period 10774d807857SHyman Huang(黄勇)# are experimental. 10789fb49daaSMarkus Armbruster# 107956266c6dSMarkus Armbruster# TODO: either fuse back into MigrationParameters, or make 108056266c6dSMarkus Armbruster# MigrationParameters members mandatory 108156266c6dSMarkus Armbruster# 108248685a8eSMarkus Armbruster# Since: 2.4 108348685a8eSMarkus Armbruster## 108448685a8eSMarkus Armbruster{ 'struct': 'MigrateSetParameters', 1085ee3d96baSDr. David Alan Gilbert 'data': { '*announce-initial': 'size', 1086ee3d96baSDr. David Alan Gilbert '*announce-max': 'size', 1087ee3d96baSDr. David Alan Gilbert '*announce-rounds': 'size', 1088ee3d96baSDr. David Alan Gilbert '*announce-step': 'size', 1089864128dfSJuan Quintela '*compress-level': { 'type': 'uint8', 1090864128dfSJuan Quintela 'features': [ 'deprecated' ] }, 1091864128dfSJuan Quintela '*compress-threads': { 'type': 'uint8', 1092864128dfSJuan Quintela 'features': [ 'deprecated' ] }, 1093864128dfSJuan Quintela '*compress-wait-thread': { 'type': 'bool', 1094864128dfSJuan Quintela 'features': [ 'deprecated' ] }, 1095864128dfSJuan Quintela '*decompress-threads': { 'type': 'uint8', 1096864128dfSJuan Quintela 'features': [ 'deprecated' ] }, 1097ec17de0aSMarkus Armbruster '*throttle-trigger-threshold': 'uint8', 1098ec17de0aSMarkus Armbruster '*cpu-throttle-initial': 'uint8', 1099ec17de0aSMarkus Armbruster '*cpu-throttle-increment': 'uint8', 1100cbbf8182SKeqian Zhu '*cpu-throttle-tailslow': 'bool', 110148685a8eSMarkus Armbruster '*tls-creds': 'StrOrNull', 110248685a8eSMarkus Armbruster '*tls-hostname': 'StrOrNull', 1103d2f1d29bSDaniel P. Berrange '*tls-authz': 'StrOrNull', 1104ec17de0aSMarkus Armbruster '*max-bandwidth': 'size', 11058b239597SPeter Xu '*avail-switchover-bandwidth': 'size', 1106ec17de0aSMarkus Armbruster '*downtime-limit': 'uint64', 11079fb49daaSMarkus Armbruster '*x-checkpoint-delay': { 'type': 'uint32', 11089fb49daaSMarkus Armbruster 'features': [ 'unstable' ] }, 110966db46caSJuan Quintela '*block-incremental': { 'type': 'bool', 111066db46caSJuan Quintela 'features': [ 'deprecated' ] }, 1111ec17de0aSMarkus Armbruster '*multifd-channels': 'uint8', 11127e555c6cSDr. David Alan Gilbert '*xbzrle-cache-size': 'size', 11134cbc9c7fSLi Qiang '*max-postcopy-bandwidth': 'size', 1114ec17de0aSMarkus Armbruster '*max-cpu-throttle': 'uint8', 11159004db48SJuan Quintela '*multifd-compression': 'MultiFDCompression', 1116ec17de0aSMarkus Armbruster '*multifd-zlib-level': 'uint8', 1117ec17de0aSMarkus Armbruster '*multifd-zstd-level': 'uint8', 11184d807857SHyman Huang(黄勇) '*block-bitmap-mapping': [ 'BitmapMigrationNodeAlias' ], 11194d807857SHyman Huang(黄勇) '*x-vcpu-dirty-limit-period': { 'type': 'uint64', 112009f9ec99SHyman Huang(黄勇) 'features': [ 'unstable' ] }, 1121eea1e5c9SSteve Sistare '*vcpu-dirty-limit': 'uint64', 1122eea1e5c9SSteve Sistare '*mode': 'MigMode'} } 112348685a8eSMarkus Armbruster 112448685a8eSMarkus Armbruster## 112548685a8eSMarkus Armbruster# @migrate-set-parameters: 112648685a8eSMarkus Armbruster# 112748685a8eSMarkus Armbruster# Set various migration parameters. 112848685a8eSMarkus Armbruster# 112948685a8eSMarkus Armbruster# Since: 2.4 113048685a8eSMarkus Armbruster# 113148685a8eSMarkus Armbruster# Example: 113248685a8eSMarkus Armbruster# 113348685a8eSMarkus Armbruster# -> { "execute": "migrate-set-parameters" , 1134864128dfSJuan Quintela# "arguments": { "multifd-channels": 5 } } 113537fa48a4SMarkus Armbruster# <- { "return": {} } 113648685a8eSMarkus Armbruster## 113748685a8eSMarkus Armbruster{ 'command': 'migrate-set-parameters', 'boxed': true, 113848685a8eSMarkus Armbruster 'data': 'MigrateSetParameters' } 113948685a8eSMarkus Armbruster 114048685a8eSMarkus Armbruster## 114148685a8eSMarkus Armbruster# @MigrationParameters: 114248685a8eSMarkus Armbruster# 114348685a8eSMarkus Armbruster# The optional members aren't actually optional. 114448685a8eSMarkus Armbruster# 1145a937b6aaSMarkus Armbruster# @announce-initial: Initial delay (in milliseconds) before sending 1146a937b6aaSMarkus Armbruster# the first announce (Since 4.0) 1147ee3d96baSDr. David Alan Gilbert# 1148a937b6aaSMarkus Armbruster# @announce-max: Maximum delay (in milliseconds) between packets in 1149a937b6aaSMarkus Armbruster# the announcement (Since 4.0) 1150ee3d96baSDr. David Alan Gilbert# 1151a937b6aaSMarkus Armbruster# @announce-rounds: Number of self-announce packets sent after 1152a937b6aaSMarkus Armbruster# migration (Since 4.0) 1153ee3d96baSDr. David Alan Gilbert# 1154a937b6aaSMarkus Armbruster# @announce-step: Increase in delay (in milliseconds) between 1155a937b6aaSMarkus Armbruster# subsequent packets in the announcement (Since 4.0) 1156ee3d96baSDr. David Alan Gilbert# 115748685a8eSMarkus Armbruster# @compress-level: compression level 115848685a8eSMarkus Armbruster# 115948685a8eSMarkus Armbruster# @compress-threads: compression thread count 116048685a8eSMarkus Armbruster# 1161a937b6aaSMarkus Armbruster# @compress-wait-thread: Controls behavior when all compression 1162a937b6aaSMarkus Armbruster# threads are currently busy. If true (default), wait for a free 1163a937b6aaSMarkus Armbruster# compression thread to become available; otherwise, send the page 1164a937b6aaSMarkus Armbruster# uncompressed. (Since 3.1) 11651d58872aSXiao Guangrong# 116648685a8eSMarkus Armbruster# @decompress-threads: decompression thread count 116748685a8eSMarkus Armbruster# 1168a937b6aaSMarkus Armbruster# @throttle-trigger-threshold: The ratio of bytes_dirty_period and 1169a937b6aaSMarkus Armbruster# bytes_xfer_period to trigger throttling. It is expressed as 1170a937b6aaSMarkus Armbruster# percentage. The default value is 50. (Since 5.0) 1171dc14a470SKeqian Zhu# 117248685a8eSMarkus Armbruster# @cpu-throttle-initial: Initial percentage of time guest cpus are 1173a937b6aaSMarkus Armbruster# throttled when migration auto-converge is activated. (Since 1174a937b6aaSMarkus Armbruster# 2.7) 117548685a8eSMarkus Armbruster# 117648685a8eSMarkus Armbruster# @cpu-throttle-increment: throttle percentage increase each time 1177a937b6aaSMarkus Armbruster# auto-converge detects that migration is not making progress. 1178a937b6aaSMarkus Armbruster# (Since 2.7) 117948685a8eSMarkus Armbruster# 1180a937b6aaSMarkus Armbruster# @cpu-throttle-tailslow: Make CPU throttling slower at tail stage At 1181a937b6aaSMarkus Armbruster# the tail stage of throttling, the Guest is very sensitive to CPU 1182a937b6aaSMarkus Armbruster# percentage while the @cpu-throttle -increment is excessive 1183a937b6aaSMarkus Armbruster# usually at tail stage. If this parameter is true, we will 1184a937b6aaSMarkus Armbruster# compute the ideal CPU percentage used by the Guest, which may 1185a937b6aaSMarkus Armbruster# exactly make the dirty rate match the dirty rate threshold. 1186a937b6aaSMarkus Armbruster# Then we will choose a smaller throttle increment between the one 1187a937b6aaSMarkus Armbruster# specified by @cpu-throttle-increment and the one generated by 1188a937b6aaSMarkus Armbruster# ideal CPU percentage. Therefore, it is compatible to 1189a937b6aaSMarkus Armbruster# traditional throttling, meanwhile the throttle increment won't 1190a937b6aaSMarkus Armbruster# be excessive at tail stage. The default value is false. (Since 1191a937b6aaSMarkus Armbruster# 5.1) 1192cbbf8182SKeqian Zhu# 119348685a8eSMarkus Armbruster# @tls-creds: ID of the 'tls-creds' object that provides credentials 119448685a8eSMarkus Armbruster# for establishing a TLS connection over the migration data 119548685a8eSMarkus Armbruster# channel. On the outgoing side of the migration, the credentials 119648685a8eSMarkus Armbruster# must be for a 'client' endpoint, while for the incoming side the 1197a937b6aaSMarkus Armbruster# credentials must be for a 'server' endpoint. An empty string 1198a937b6aaSMarkus Armbruster# means that QEMU will use plain text mode for migration, rather 1199a937b6aaSMarkus Armbruster# than TLS (Since 2.7) Note: 2.8 reports this by omitting 1200a937b6aaSMarkus Armbruster# tls-creds instead. 120148685a8eSMarkus Armbruster# 120248685a8eSMarkus Armbruster# @tls-hostname: hostname of the target host for the migration. This 120348685a8eSMarkus Armbruster# is required when using x509 based TLS credentials and the 1204a937b6aaSMarkus Armbruster# migration URI does not already include a hostname. For example 1205a937b6aaSMarkus Armbruster# if using fd: or exec: based migration, the hostname must be 1206a937b6aaSMarkus Armbruster# provided so that the server's x509 certificate identity can be 1207a937b6aaSMarkus Armbruster# validated. (Since 2.7) An empty string means that QEMU will use 1208a937b6aaSMarkus Armbruster# the hostname associated with the migration URI, if any. (Since 1209a937b6aaSMarkus Armbruster# 2.9) Note: 2.8 reports this by omitting tls-hostname instead. 121048685a8eSMarkus Armbruster# 1211a937b6aaSMarkus Armbruster# @tls-authz: ID of the 'authz' object subclass that provides access 1212a937b6aaSMarkus Armbruster# control checking of the TLS x509 certificate distinguished name. 1213a937b6aaSMarkus Armbruster# (Since 4.0) 1214d2f1d29bSDaniel P. Berrange# 1215a937b6aaSMarkus Armbruster# @max-bandwidth: to set maximum speed for migration. maximum speed 1216a937b6aaSMarkus Armbruster# in bytes per second. (Since 2.8) 121748685a8eSMarkus Armbruster# 12188b239597SPeter Xu# @avail-switchover-bandwidth: to set the available bandwidth that 12198b239597SPeter Xu# migration can use during switchover phase. NOTE! This does not 12208b239597SPeter Xu# limit the bandwidth during switchover, but only for calculations when 12218b239597SPeter Xu# making decisions to switchover. By default, this value is zero, 12228b239597SPeter Xu# which means QEMU will estimate the bandwidth automatically. This can 12238b239597SPeter Xu# be set when the estimated value is not accurate, while the user is 12248b239597SPeter Xu# able to guarantee such bandwidth is available when switching over. 12258b239597SPeter Xu# When specified correctly, this can make the switchover decision much 12268b239597SPeter Xu# more accurate. (Since 8.2) 12278b239597SPeter Xu# 1228a937b6aaSMarkus Armbruster# @downtime-limit: set maximum tolerated downtime for migration. 1229a937b6aaSMarkus Armbruster# maximum downtime in milliseconds (Since 2.8) 123048685a8eSMarkus Armbruster# 1231a937b6aaSMarkus Armbruster# @x-checkpoint-delay: the delay time between two COLO checkpoints. 1232a937b6aaSMarkus Armbruster# (Since 2.8) 123348685a8eSMarkus Armbruster# 123448685a8eSMarkus Armbruster# @block-incremental: Affects how much storage is migrated when the 123548685a8eSMarkus Armbruster# block migration capability is enabled. When false, the entire 1236a937b6aaSMarkus Armbruster# storage backing chain is migrated into a flattened image at the 1237a937b6aaSMarkus Armbruster# destination; when true, only the active qcow2 layer is migrated 1238a937b6aaSMarkus Armbruster# and the destination must already have access to the same backing 1239a937b6aaSMarkus Armbruster# chain as was used on the source. (since 2.10) 124048685a8eSMarkus Armbruster# 1241cbfd6c95SJuan Quintela# @multifd-channels: Number of channels used to migrate data in 1242a937b6aaSMarkus Armbruster# parallel. This is the same number that the number of sockets 1243a937b6aaSMarkus Armbruster# used for migration. The default value is 2 (since 4.0) 12444075fb1cSJuan Quintela# 124573af8dd8SJuan Quintela# @xbzrle-cache-size: cache size to be used by XBZRLE migration. It 1246a937b6aaSMarkus Armbruster# needs to be a multiple of the target page size and a power of 2 124773af8dd8SJuan Quintela# (Since 2.11) 12487e555c6cSDr. David Alan Gilbert# 1249a937b6aaSMarkus Armbruster# @max-postcopy-bandwidth: Background transfer bandwidth during 1250a937b6aaSMarkus Armbruster# postcopy. Defaults to 0 (unlimited). In bytes per second. 12517e555c6cSDr. David Alan Gilbert# (Since 3.0) 12524cbc9c7fSLi Qiang# 1253a937b6aaSMarkus Armbruster# @max-cpu-throttle: maximum cpu throttle percentage. Defaults to 99. 12544cbc9c7fSLi Qiang# (Since 3.1) 12554cbc9c7fSLi Qiang# 1256a937b6aaSMarkus Armbruster# @multifd-compression: Which compression method to use. Defaults to 1257a937b6aaSMarkus Armbruster# none. (Since 5.0) 125896eef042SJuan Quintela# 12599004db48SJuan Quintela# @multifd-zlib-level: Set the compression level to be used in live 1260a937b6aaSMarkus Armbruster# migration, the compression level is an integer between 0 and 9, 1261a937b6aaSMarkus Armbruster# where 0 means no compression, 1 means the best compression 1262a937b6aaSMarkus Armbruster# speed, and 9 means best compression ratio which will consume 1263a937b6aaSMarkus Armbruster# more CPU. Defaults to 1. (Since 5.0) 12649004db48SJuan Quintela# 12656a9ad154SJuan Quintela# @multifd-zstd-level: Set the compression level to be used in live 1266a937b6aaSMarkus Armbruster# migration, the compression level is an integer between 0 and 20, 1267a937b6aaSMarkus Armbruster# where 0 means no compression, 1 means the best compression 1268a937b6aaSMarkus Armbruster# speed, and 20 means best compression ratio which will consume 1269a937b6aaSMarkus Armbruster# more CPU. Defaults to 1. (Since 5.0) 12706a9ad154SJuan Quintela# 127131e4c354SMax Reitz# @block-bitmap-mapping: Maps block nodes and bitmaps on them to 1272a937b6aaSMarkus Armbruster# aliases for the purpose of dirty bitmap migration. Such aliases 1273a937b6aaSMarkus Armbruster# may for example be the corresponding names on the opposite site. 1274a937b6aaSMarkus Armbruster# The mapping must be one-to-one, but not necessarily complete: On 1275a937b6aaSMarkus Armbruster# the source, unmapped bitmaps and all bitmaps on unmapped nodes 1276a937b6aaSMarkus Armbruster# will be ignored. On the destination, encountering an unmapped 1277a937b6aaSMarkus Armbruster# alias in the incoming migration stream will result in a report, 1278a937b6aaSMarkus Armbruster# and all further bitmap migration data will then be discarded. 1279a937b6aaSMarkus Armbruster# Note that the destination does not know about bitmaps it does 1280a937b6aaSMarkus Armbruster# not receive, so there is no limitation or requirement regarding 1281a937b6aaSMarkus Armbruster# the number of bitmaps received, or how they are named, or on 1282a937b6aaSMarkus Armbruster# which nodes they are placed. By default (when this parameter 1283a937b6aaSMarkus Armbruster# has never been set), bitmap names are mapped to themselves. 1284a937b6aaSMarkus Armbruster# Nodes are mapped to their block device name if there is one, and 1285a937b6aaSMarkus Armbruster# to their node name otherwise. (Since 5.2) 128631e4c354SMax Reitz# 12878abc8115SHyman Huang(黄勇)# @x-vcpu-dirty-limit-period: Periodic time (in milliseconds) of dirty 12888abc8115SHyman Huang(黄勇)# limit during live migration. Should be in the range 1 to 1000ms. 12898abc8115SHyman Huang(黄勇)# Defaults to 1000ms. (Since 8.1) 12904d807857SHyman Huang(黄勇)# 129109f9ec99SHyman Huang(黄勇)# @vcpu-dirty-limit: Dirtyrate limit (MB/s) during live migration. 129209f9ec99SHyman Huang(黄勇)# Defaults to 1. (Since 8.1) 129309f9ec99SHyman Huang(黄勇)# 1294eea1e5c9SSteve Sistare# @mode: Migration mode. See description in @MigMode. Default is 'normal'. 1295eea1e5c9SSteve Sistare# (Since 8.2) 1296eea1e5c9SSteve Sistare# 12979fb49daaSMarkus Armbruster# Features: 1298a937b6aaSMarkus Armbruster# 129966db46caSJuan Quintela# @deprecated: Member @block-incremental is deprecated. Use 1300864128dfSJuan Quintela# blockdev-mirror with NBD instead. Members @compress-level, 1301864128dfSJuan Quintela# @compress-threads, @decompress-threads and @compress-wait-thread 1302864128dfSJuan Quintela# are deprecated because @compression is deprecated. 130366db46caSJuan Quintela# 13044d807857SHyman Huang(黄勇)# @unstable: Members @x-checkpoint-delay and @x-vcpu-dirty-limit-period 13054d807857SHyman Huang(黄勇)# are experimental. 13069fb49daaSMarkus Armbruster# 130748685a8eSMarkus Armbruster# Since: 2.4 130848685a8eSMarkus Armbruster## 130948685a8eSMarkus Armbruster{ 'struct': 'MigrationParameters', 1310ee3d96baSDr. David Alan Gilbert 'data': { '*announce-initial': 'size', 1311ee3d96baSDr. David Alan Gilbert '*announce-max': 'size', 1312ee3d96baSDr. David Alan Gilbert '*announce-rounds': 'size', 1313ee3d96baSDr. David Alan Gilbert '*announce-step': 'size', 1314864128dfSJuan Quintela '*compress-level': { 'type': 'uint8', 1315864128dfSJuan Quintela 'features': [ 'deprecated' ] }, 1316864128dfSJuan Quintela '*compress-threads': { 'type': 'uint8', 1317864128dfSJuan Quintela 'features': [ 'deprecated' ] }, 1318864128dfSJuan Quintela '*compress-wait-thread': { 'type': 'bool', 1319864128dfSJuan Quintela 'features': [ 'deprecated' ] }, 1320864128dfSJuan Quintela '*decompress-threads': { 'type': 'uint8', 1321864128dfSJuan Quintela 'features': [ 'deprecated' ] }, 1322dc14a470SKeqian Zhu '*throttle-trigger-threshold': 'uint8', 1323741d4086SJuan Quintela '*cpu-throttle-initial': 'uint8', 1324741d4086SJuan Quintela '*cpu-throttle-increment': 'uint8', 1325cbbf8182SKeqian Zhu '*cpu-throttle-tailslow': 'bool', 132648685a8eSMarkus Armbruster '*tls-creds': 'str', 132748685a8eSMarkus Armbruster '*tls-hostname': 'str', 1328d2f1d29bSDaniel P. Berrange '*tls-authz': 'str', 1329741d4086SJuan Quintela '*max-bandwidth': 'size', 13308b239597SPeter Xu '*avail-switchover-bandwidth': 'size', 1331741d4086SJuan Quintela '*downtime-limit': 'uint64', 13329fb49daaSMarkus Armbruster '*x-checkpoint-delay': { 'type': 'uint32', 13339fb49daaSMarkus Armbruster 'features': [ 'unstable' ] }, 133466db46caSJuan Quintela '*block-incremental': { 'type': 'bool', 133566db46caSJuan Quintela 'features': [ 'deprecated' ] }, 1336cbfd6c95SJuan Quintela '*multifd-channels': 'uint8', 13377e555c6cSDr. David Alan Gilbert '*xbzrle-cache-size': 'size', 13384cbc9c7fSLi Qiang '*max-postcopy-bandwidth': 'size', 133996eef042SJuan Quintela '*max-cpu-throttle': 'uint8', 13409004db48SJuan Quintela '*multifd-compression': 'MultiFDCompression', 13416a9ad154SJuan Quintela '*multifd-zlib-level': 'uint8', 134231e4c354SMax Reitz '*multifd-zstd-level': 'uint8', 13434d807857SHyman Huang(黄勇) '*block-bitmap-mapping': [ 'BitmapMigrationNodeAlias' ], 13444d807857SHyman Huang(黄勇) '*x-vcpu-dirty-limit-period': { 'type': 'uint64', 134509f9ec99SHyman Huang(黄勇) 'features': [ 'unstable' ] }, 1346eea1e5c9SSteve Sistare '*vcpu-dirty-limit': 'uint64', 1347eea1e5c9SSteve Sistare '*mode': 'MigMode'} } 134848685a8eSMarkus Armbruster 134948685a8eSMarkus Armbruster## 135048685a8eSMarkus Armbruster# @query-migrate-parameters: 135148685a8eSMarkus Armbruster# 135248685a8eSMarkus Armbruster# Returns information about the current migration parameters 135348685a8eSMarkus Armbruster# 135448685a8eSMarkus Armbruster# Returns: @MigrationParameters 135548685a8eSMarkus Armbruster# 135648685a8eSMarkus Armbruster# Since: 2.4 135748685a8eSMarkus Armbruster# 135848685a8eSMarkus Armbruster# Example: 135948685a8eSMarkus Armbruster# 136048685a8eSMarkus Armbruster# -> { "execute": "query-migrate-parameters" } 136148685a8eSMarkus Armbruster# <- { "return": { 1362864128dfSJuan Quintela# "multifd-channels": 2, 136348685a8eSMarkus Armbruster# "cpu-throttle-increment": 10, 136448685a8eSMarkus Armbruster# "cpu-throttle-initial": 20, 136548685a8eSMarkus Armbruster# "max-bandwidth": 33554432, 136648685a8eSMarkus Armbruster# "downtime-limit": 300 136748685a8eSMarkus Armbruster# } 136848685a8eSMarkus Armbruster# } 136948685a8eSMarkus Armbruster## 137048685a8eSMarkus Armbruster{ 'command': 'query-migrate-parameters', 137148685a8eSMarkus Armbruster 'returns': 'MigrationParameters' } 137248685a8eSMarkus Armbruster 137348685a8eSMarkus Armbruster## 137448685a8eSMarkus Armbruster# @migrate-start-postcopy: 137548685a8eSMarkus Armbruster# 1376a937b6aaSMarkus Armbruster# Followup to a migration command to switch the migration to postcopy 1377a937b6aaSMarkus Armbruster# mode. The postcopy-ram capability must be set on both source and 1378a937b6aaSMarkus Armbruster# destination before the original migration command. 137948685a8eSMarkus Armbruster# 138048685a8eSMarkus Armbruster# Since: 2.5 138148685a8eSMarkus Armbruster# 138248685a8eSMarkus Armbruster# Example: 138348685a8eSMarkus Armbruster# 138448685a8eSMarkus Armbruster# -> { "execute": "migrate-start-postcopy" } 138548685a8eSMarkus Armbruster# <- { "return": {} } 138648685a8eSMarkus Armbruster## 138748685a8eSMarkus Armbruster{ 'command': 'migrate-start-postcopy' } 138848685a8eSMarkus Armbruster 138948685a8eSMarkus Armbruster## 139048685a8eSMarkus Armbruster# @MIGRATION: 139148685a8eSMarkus Armbruster# 139248685a8eSMarkus Armbruster# Emitted when a migration event happens 139348685a8eSMarkus Armbruster# 139448685a8eSMarkus Armbruster# @status: @MigrationStatus describing the current migration status. 139548685a8eSMarkus Armbruster# 139648685a8eSMarkus Armbruster# Since: 2.4 139748685a8eSMarkus Armbruster# 139848685a8eSMarkus Armbruster# Example: 139948685a8eSMarkus Armbruster# 140048685a8eSMarkus Armbruster# <- {"timestamp": {"seconds": 1432121972, "microseconds": 744001}, 140148685a8eSMarkus Armbruster# "event": "MIGRATION", 140248685a8eSMarkus Armbruster# "data": {"status": "completed"} } 140348685a8eSMarkus Armbruster## 140448685a8eSMarkus Armbruster{ 'event': 'MIGRATION', 140548685a8eSMarkus Armbruster 'data': {'status': 'MigrationStatus'}} 140648685a8eSMarkus Armbruster 140748685a8eSMarkus Armbruster## 140848685a8eSMarkus Armbruster# @MIGRATION_PASS: 140948685a8eSMarkus Armbruster# 1410a937b6aaSMarkus Armbruster# Emitted from the source side of a migration at the start of each 1411a937b6aaSMarkus Armbruster# pass (when it syncs the dirty bitmap) 141248685a8eSMarkus Armbruster# 141348685a8eSMarkus Armbruster# @pass: An incrementing count (starting at 1 on the first pass) 141448685a8eSMarkus Armbruster# 141548685a8eSMarkus Armbruster# Since: 2.6 141648685a8eSMarkus Armbruster# 141748685a8eSMarkus Armbruster# Example: 141848685a8eSMarkus Armbruster# 141937fa48a4SMarkus Armbruster# <- { "timestamp": {"seconds": 1449669631, "microseconds": 239225}, 142048685a8eSMarkus Armbruster# "event": "MIGRATION_PASS", "data": {"pass": 2} } 142148685a8eSMarkus Armbruster## 142248685a8eSMarkus Armbruster{ 'event': 'MIGRATION_PASS', 142348685a8eSMarkus Armbruster 'data': { 'pass': 'int' } } 142448685a8eSMarkus Armbruster 142548685a8eSMarkus Armbruster## 142648685a8eSMarkus Armbruster# @COLOMessage: 142748685a8eSMarkus Armbruster# 142848685a8eSMarkus Armbruster# The message transmission between Primary side and Secondary side. 142948685a8eSMarkus Armbruster# 143048685a8eSMarkus Armbruster# @checkpoint-ready: Secondary VM (SVM) is ready for checkpointing 143148685a8eSMarkus Armbruster# 1432a937b6aaSMarkus Armbruster# @checkpoint-request: Primary VM (PVM) tells SVM to prepare for 1433a937b6aaSMarkus Armbruster# checkpointing 143448685a8eSMarkus Armbruster# 143548685a8eSMarkus Armbruster# @checkpoint-reply: SVM gets PVM's checkpoint request 143648685a8eSMarkus Armbruster# 143748685a8eSMarkus Armbruster# @vmstate-send: VM's state will be sent by PVM. 143848685a8eSMarkus Armbruster# 143948685a8eSMarkus Armbruster# @vmstate-size: The total size of VMstate. 144048685a8eSMarkus Armbruster# 144148685a8eSMarkus Armbruster# @vmstate-received: VM's state has been received by SVM. 144248685a8eSMarkus Armbruster# 144348685a8eSMarkus Armbruster# @vmstate-loaded: VM's state has been loaded by SVM. 144448685a8eSMarkus Armbruster# 144548685a8eSMarkus Armbruster# Since: 2.8 144648685a8eSMarkus Armbruster## 144748685a8eSMarkus Armbruster{ 'enum': 'COLOMessage', 144848685a8eSMarkus Armbruster 'data': [ 'checkpoint-ready', 'checkpoint-request', 'checkpoint-reply', 144948685a8eSMarkus Armbruster 'vmstate-send', 'vmstate-size', 'vmstate-received', 145048685a8eSMarkus Armbruster 'vmstate-loaded' ] } 145148685a8eSMarkus Armbruster 145248685a8eSMarkus Armbruster## 145348685a8eSMarkus Armbruster# @COLOMode: 145448685a8eSMarkus Armbruster# 145541b6b779SZhang Chen# The COLO current mode. 145648685a8eSMarkus Armbruster# 145741b6b779SZhang Chen# @none: COLO is disabled. 145848685a8eSMarkus Armbruster# 145941b6b779SZhang Chen# @primary: COLO node in primary side. 146048685a8eSMarkus Armbruster# 146141b6b779SZhang Chen# @secondary: COLO node in slave side. 146248685a8eSMarkus Armbruster# 146348685a8eSMarkus Armbruster# Since: 2.8 146448685a8eSMarkus Armbruster## 146548685a8eSMarkus Armbruster{ 'enum': 'COLOMode', 146641b6b779SZhang Chen 'data': [ 'none', 'primary', 'secondary'] } 146748685a8eSMarkus Armbruster 146848685a8eSMarkus Armbruster## 146948685a8eSMarkus Armbruster# @FailoverStatus: 147048685a8eSMarkus Armbruster# 147148685a8eSMarkus Armbruster# An enumeration of COLO failover status 147248685a8eSMarkus Armbruster# 147348685a8eSMarkus Armbruster# @none: no failover has ever happened 147448685a8eSMarkus Armbruster# 147548685a8eSMarkus Armbruster# @require: got failover requirement but not handled 147648685a8eSMarkus Armbruster# 147748685a8eSMarkus Armbruster# @active: in the process of doing failover 147848685a8eSMarkus Armbruster# 147948685a8eSMarkus Armbruster# @completed: finish the process of failover 148048685a8eSMarkus Armbruster# 1481a937b6aaSMarkus Armbruster# @relaunch: restart the failover process, from 'none' -> 'completed' 1482a937b6aaSMarkus Armbruster# (Since 2.9) 148348685a8eSMarkus Armbruster# 148448685a8eSMarkus Armbruster# Since: 2.8 148548685a8eSMarkus Armbruster## 148648685a8eSMarkus Armbruster{ 'enum': 'FailoverStatus', 148748685a8eSMarkus Armbruster 'data': [ 'none', 'require', 'active', 'completed', 'relaunch' ] } 148848685a8eSMarkus Armbruster 148948685a8eSMarkus Armbruster## 14909ecff6d6Szhanghailiang# @COLO_EXIT: 14919ecff6d6Szhanghailiang# 14929ecff6d6Szhanghailiang# Emitted when VM finishes COLO mode due to some errors happening or 14939ecff6d6Szhanghailiang# at the request of users. 14949ecff6d6Szhanghailiang# 14959ecff6d6Szhanghailiang# @mode: report COLO mode when COLO exited. 14969ecff6d6Szhanghailiang# 14979ecff6d6Szhanghailiang# @reason: describes the reason for the COLO exit. 14989ecff6d6Szhanghailiang# 14999ecff6d6Szhanghailiang# Since: 3.1 15009ecff6d6Szhanghailiang# 15019ecff6d6Szhanghailiang# Example: 15029ecff6d6Szhanghailiang# 15039ecff6d6Szhanghailiang# <- { "timestamp": {"seconds": 2032141960, "microseconds": 417172}, 15049ecff6d6Szhanghailiang# "event": "COLO_EXIT", "data": {"mode": "primary", "reason": "request" } } 15059ecff6d6Szhanghailiang## 15069ecff6d6Szhanghailiang{ 'event': 'COLO_EXIT', 15079ecff6d6Szhanghailiang 'data': {'mode': 'COLOMode', 'reason': 'COLOExitReason' } } 15089ecff6d6Szhanghailiang 15099ecff6d6Szhanghailiang## 15109ecff6d6Szhanghailiang# @COLOExitReason: 15119ecff6d6Szhanghailiang# 15123a43ac47SZhang Chen# The reason for a COLO exit. 15139ecff6d6Szhanghailiang# 1514a937b6aaSMarkus Armbruster# @none: failover has never happened. This state does not occur in 1515a937b6aaSMarkus Armbruster# the COLO_EXIT event, and is only visible in the result of 15163a43ac47SZhang Chen# query-colo-status. 15179ecff6d6Szhanghailiang# 15183a43ac47SZhang Chen# @request: COLO exit is due to an external request. 15199ecff6d6Szhanghailiang# 15203a43ac47SZhang Chen# @error: COLO exit is due to an internal error. 15213a43ac47SZhang Chen# 15223a43ac47SZhang Chen# @processing: COLO is currently handling a failover (since 4.0). 15239ecff6d6Szhanghailiang# 15249ecff6d6Szhanghailiang# Since: 3.1 15259ecff6d6Szhanghailiang## 15269ecff6d6Szhanghailiang{ 'enum': 'COLOExitReason', 15273a43ac47SZhang Chen 'data': [ 'none', 'request', 'error' , 'processing' ] } 15289ecff6d6Szhanghailiang 15299ecff6d6Szhanghailiang## 153048685a8eSMarkus Armbruster# @x-colo-lost-heartbeat: 153148685a8eSMarkus Armbruster# 1532a937b6aaSMarkus Armbruster# Tell qemu that heartbeat is lost, request it to do takeover 1533a937b6aaSMarkus Armbruster# procedures. If this command is sent to the PVM, the Primary side 1534a937b6aaSMarkus Armbruster# will exit COLO mode. If sent to the Secondary, the Secondary side 1535a937b6aaSMarkus Armbruster# will run failover work, then takes over server operation to become 1536a937b6aaSMarkus Armbruster# the service VM. 153748685a8eSMarkus Armbruster# 15389fb49daaSMarkus Armbruster# Features: 1539a937b6aaSMarkus Armbruster# 15409fb49daaSMarkus Armbruster# @unstable: This command is experimental. 15419fb49daaSMarkus Armbruster# 154248685a8eSMarkus Armbruster# Since: 2.8 154348685a8eSMarkus Armbruster# 154448685a8eSMarkus Armbruster# Example: 154548685a8eSMarkus Armbruster# 154648685a8eSMarkus Armbruster# -> { "execute": "x-colo-lost-heartbeat" } 154748685a8eSMarkus Armbruster# <- { "return": {} } 154848685a8eSMarkus Armbruster## 15499fb49daaSMarkus Armbruster{ 'command': 'x-colo-lost-heartbeat', 155051e47cf8SVladimir Sementsov-Ogievskiy 'features': [ 'unstable' ], 155151e47cf8SVladimir Sementsov-Ogievskiy 'if': 'CONFIG_REPLICATION' } 155248685a8eSMarkus Armbruster 155348685a8eSMarkus Armbruster## 155448685a8eSMarkus Armbruster# @migrate_cancel: 155548685a8eSMarkus Armbruster# 155648685a8eSMarkus Armbruster# Cancel the current executing migration process. 155748685a8eSMarkus Armbruster# 155848685a8eSMarkus Armbruster# Returns: nothing on success 155948685a8eSMarkus Armbruster# 1560a937b6aaSMarkus Armbruster# Notes: This command succeeds even if there is no migration process 1561a937b6aaSMarkus Armbruster# running. 156248685a8eSMarkus Armbruster# 15639bc6e893SMarkus Armbruster# Since: 0.14 156448685a8eSMarkus Armbruster# 156548685a8eSMarkus Armbruster# Example: 156648685a8eSMarkus Armbruster# 156748685a8eSMarkus Armbruster# -> { "execute": "migrate_cancel" } 156848685a8eSMarkus Armbruster# <- { "return": {} } 156948685a8eSMarkus Armbruster## 157048685a8eSMarkus Armbruster{ 'command': 'migrate_cancel' } 157148685a8eSMarkus Armbruster 157248685a8eSMarkus Armbruster## 157389cfc02cSDr. David Alan Gilbert# @migrate-continue: 157489cfc02cSDr. David Alan Gilbert# 157589cfc02cSDr. David Alan Gilbert# Continue migration when it's in a paused state. 157689cfc02cSDr. David Alan Gilbert# 157789cfc02cSDr. David Alan Gilbert# @state: The state the migration is currently expected to be in 157889cfc02cSDr. David Alan Gilbert# 157989cfc02cSDr. David Alan Gilbert# Returns: nothing on success 15804ae65a52SAndrea Bolognani# 158189cfc02cSDr. David Alan Gilbert# Since: 2.11 15824ae65a52SAndrea Bolognani# 158389cfc02cSDr. David Alan Gilbert# Example: 158489cfc02cSDr. David Alan Gilbert# 158589cfc02cSDr. David Alan Gilbert# -> { "execute": "migrate-continue" , "arguments": 158689cfc02cSDr. David Alan Gilbert# { "state": "pre-switchover" } } 158789cfc02cSDr. David Alan Gilbert# <- { "return": {} } 158889cfc02cSDr. David Alan Gilbert## 158989cfc02cSDr. David Alan Gilbert{ 'command': 'migrate-continue', 'data': {'state': 'MigrationStatus'} } 159089cfc02cSDr. David Alan Gilbert 159189cfc02cSDr. David Alan Gilbert## 1592e034f883SHet Gala# @MigrationAddressType: 1593e034f883SHet Gala# 1594e034f883SHet Gala# The migration stream transport mechanisms. 1595e034f883SHet Gala# 1596e034f883SHet Gala# @socket: Migrate via socket. 1597e034f883SHet Gala# 1598e034f883SHet Gala# @exec: Direct the migration stream to another process. 1599e034f883SHet Gala# 1600e034f883SHet Gala# @rdma: Migrate via RDMA. 1601e034f883SHet Gala# 1602e034f883SHet Gala# @file: Direct the migration stream to a file. 1603e034f883SHet Gala# 160437507c14SMarkus Armbruster# Since: 8.2 1605e034f883SHet Gala## 1606e034f883SHet Gala{ 'enum': 'MigrationAddressType', 1607e034f883SHet Gala 'data': [ 'socket', 'exec', 'rdma', 'file' ] } 1608e034f883SHet Gala 1609e034f883SHet Gala## 1610e034f883SHet Gala# @FileMigrationArgs: 1611e034f883SHet Gala# 1612e034f883SHet Gala# @filename: The file to receive the migration stream 1613e034f883SHet Gala# 1614e034f883SHet Gala# @offset: The file offset where the migration stream will start 1615e034f883SHet Gala# 161637507c14SMarkus Armbruster# Since: 8.2 1617e034f883SHet Gala## 1618e034f883SHet Gala{ 'struct': 'FileMigrationArgs', 1619e034f883SHet Gala 'data': { 'filename': 'str', 1620e034f883SHet Gala 'offset': 'uint64' } } 1621e034f883SHet Gala 1622e034f883SHet Gala## 1623e034f883SHet Gala# @MigrationExecCommand: 1624e034f883SHet Gala# 1625e034f883SHet Gala# @args: command (list head) and arguments to execute. 1626e034f883SHet Gala# 162737507c14SMarkus Armbruster# Since: 8.2 1628e034f883SHet Gala## 1629e034f883SHet Gala{ 'struct': 'MigrationExecCommand', 1630e034f883SHet Gala 'data': {'args': [ 'str' ] } } 1631e034f883SHet Gala 1632e034f883SHet Gala## 1633e034f883SHet Gala# @MigrationAddress: 1634e034f883SHet Gala# 1635e034f883SHet Gala# Migration endpoint configuration. 1636e034f883SHet Gala# 163789a2273bSMarkus Armbruster# @transport: The migration stream transport mechanism 163889a2273bSMarkus Armbruster# 163937507c14SMarkus Armbruster# Since: 8.2 1640e034f883SHet Gala## 1641e034f883SHet Gala{ 'union': 'MigrationAddress', 1642e034f883SHet Gala 'base': { 'transport' : 'MigrationAddressType'}, 1643e034f883SHet Gala 'discriminator': 'transport', 1644e034f883SHet Gala 'data': { 1645e034f883SHet Gala 'socket': 'SocketAddress', 1646e034f883SHet Gala 'exec': 'MigrationExecCommand', 1647e034f883SHet Gala 'rdma': 'InetSocketAddress', 1648e034f883SHet Gala 'file': 'FileMigrationArgs' } } 1649e034f883SHet Gala 1650e034f883SHet Gala## 1651074dbce5SHet Gala# @MigrationChannelType: 1652074dbce5SHet Gala# 1653074dbce5SHet Gala# The migration channel-type request options. 1654074dbce5SHet Gala# 1655074dbce5SHet Gala# @main: Main outbound migration channel. 1656074dbce5SHet Gala# 165737507c14SMarkus Armbruster# Since: 8.1 1658074dbce5SHet Gala## 1659074dbce5SHet Gala{ 'enum': 'MigrationChannelType', 1660074dbce5SHet Gala 'data': [ 'main' ] } 1661074dbce5SHet Gala 1662074dbce5SHet Gala## 1663074dbce5SHet Gala# @MigrationChannel: 1664074dbce5SHet Gala# 1665074dbce5SHet Gala# Migration stream channel parameters. 1666074dbce5SHet Gala# 16674061c334SMichael Tokarev# @channel-type: Channel type for transferring packet information. 1668074dbce5SHet Gala# 1669074dbce5SHet Gala# @addr: Migration endpoint configuration on destination interface. 1670074dbce5SHet Gala# 167137507c14SMarkus Armbruster# Since: 8.1 1672074dbce5SHet Gala## 1673074dbce5SHet Gala{ 'struct': 'MigrationChannel', 1674074dbce5SHet Gala 'data': { 1675074dbce5SHet Gala 'channel-type': 'MigrationChannelType', 1676074dbce5SHet Gala 'addr': 'MigrationAddress' } } 1677074dbce5SHet Gala 1678074dbce5SHet Gala## 167948685a8eSMarkus Armbruster# @migrate: 168048685a8eSMarkus Armbruster# 168148685a8eSMarkus Armbruster# Migrates the current running guest to another Virtual Machine. 168248685a8eSMarkus Armbruster# 168348685a8eSMarkus Armbruster# @uri: the Uniform Resource Identifier of the destination VM 168448685a8eSMarkus Armbruster# 1685074dbce5SHet Gala# @channels: list of migration stream channels with each stream in the 1686074dbce5SHet Gala# list connected to a destination interface endpoint. 1687074dbce5SHet Gala# 168848685a8eSMarkus Armbruster# @blk: do block migration (full disk copy) 168948685a8eSMarkus Armbruster# 169048685a8eSMarkus Armbruster# @inc: incremental disk copy migration 169148685a8eSMarkus Armbruster# 1692a937b6aaSMarkus Armbruster# @detach: this argument exists only for compatibility reasons and is 1693a937b6aaSMarkus Armbruster# ignored by QEMU 169448685a8eSMarkus Armbruster# 169551f63ec7SPeter Maydell# @resume: resume one paused migration, default "off". (since 3.0) 16967a4da28bSPeter Xu# 169740101f32SJuan Quintela# Features: 169840101f32SJuan Quintela# 16998846b5bfSJuan Quintela# @deprecated: Members @inc and @blk are deprecated. Use 17008846b5bfSJuan Quintela# blockdev-mirror with NBD instead. 170140101f32SJuan Quintela# 170248685a8eSMarkus Armbruster# Returns: nothing on success 170348685a8eSMarkus Armbruster# 17049bc6e893SMarkus Armbruster# Since: 0.14 170548685a8eSMarkus Armbruster# 170648685a8eSMarkus Armbruster# Notes: 170748685a8eSMarkus Armbruster# 17081ed1d4d6SMarkus Armbruster# 1. The 'query-migrate' command should be used to check 17091ed1d4d6SMarkus Armbruster# migration's progress and final result (this information is 17101ed1d4d6SMarkus Armbruster# provided by the 'status' member) 171148685a8eSMarkus Armbruster# 171248685a8eSMarkus Armbruster# 2. All boolean arguments default to false 171348685a8eSMarkus Armbruster# 17141ed1d4d6SMarkus Armbruster# 3. The user Monitor's "detach" argument is invalid in QMP and 17151ed1d4d6SMarkus Armbruster# should not be used 171648685a8eSMarkus Armbruster# 17171ed1d4d6SMarkus Armbruster# 4. The uri argument should have the Uniform Resource Identifier 17181ed1d4d6SMarkus Armbruster# of default destination VM. This connection will be bound to 17191ed1d4d6SMarkus Armbruster# default network. 1720074dbce5SHet Gala# 17211ed1d4d6SMarkus Armbruster# 5. For now, number of migration streams is restricted to one, 17221ed1d4d6SMarkus Armbruster# i.e number of items in 'channels' list is just 1. 1723074dbce5SHet Gala# 1724074dbce5SHet Gala# 6. The 'uri' and 'channels' arguments are mutually exclusive; 1725074dbce5SHet Gala# exactly one of the two should be present. 1726074dbce5SHet Gala# 172748685a8eSMarkus Armbruster# Example: 172848685a8eSMarkus Armbruster# 172948685a8eSMarkus Armbruster# -> { "execute": "migrate", "arguments": { "uri": "tcp:0:4446" } } 173048685a8eSMarkus Armbruster# <- { "return": {} } 1731*3cee17e7SHet Gala# 1732074dbce5SHet Gala# -> { "execute": "migrate", 1733074dbce5SHet Gala# "arguments": { 1734074dbce5SHet Gala# "channels": [ { "channel-type": "main", 1735074dbce5SHet Gala# "addr": { "transport": "socket", 1736074dbce5SHet Gala# "type": "inet", 1737074dbce5SHet Gala# "host": "10.12.34.9", 1738074dbce5SHet Gala# "port": "1050" } } ] } } 1739074dbce5SHet Gala# <- { "return": {} } 1740074dbce5SHet Gala# 1741074dbce5SHet Gala# -> { "execute": "migrate", 1742074dbce5SHet Gala# "arguments": { 1743074dbce5SHet Gala# "channels": [ { "channel-type": "main", 1744074dbce5SHet Gala# "addr": { "transport": "exec", 1745074dbce5SHet Gala# "args": [ "/bin/nc", "-p", "6000", 1746074dbce5SHet Gala# "/some/sock" ] } } ] } } 1747074dbce5SHet Gala# <- { "return": {} } 1748074dbce5SHet Gala# 1749074dbce5SHet Gala# -> { "execute": "migrate", 1750074dbce5SHet Gala# "arguments": { 1751074dbce5SHet Gala# "channels": [ { "channel-type": "main", 1752074dbce5SHet Gala# "addr": { "transport": "rdma", 1753074dbce5SHet Gala# "host": "10.12.34.9", 1754074dbce5SHet Gala# "port": "1050" } } ] } } 1755074dbce5SHet Gala# <- { "return": {} } 1756074dbce5SHet Gala# 1757074dbce5SHet Gala# -> { "execute": "migrate", 1758074dbce5SHet Gala# "arguments": { 1759074dbce5SHet Gala# "channels": [ { "channel-type": "main", 1760074dbce5SHet Gala# "addr": { "transport": "file", 1761074dbce5SHet Gala# "filename": "/tmp/migfile", 1762074dbce5SHet Gala# "offset": "0x1000" } } ] } } 1763074dbce5SHet Gala# <- { "return": {} } 1764074dbce5SHet Gala# 176548685a8eSMarkus Armbruster## 176648685a8eSMarkus Armbruster{ 'command': 'migrate', 176757fd4b4eSHet Gala 'data': {'*uri': 'str', 1768074dbce5SHet Gala '*channels': [ 'MigrationChannel' ], 17698846b5bfSJuan Quintela '*blk': { 'type': 'bool', 'features': [ 'deprecated' ] }, 177040101f32SJuan Quintela '*inc': { 'type': 'bool', 'features': [ 'deprecated' ] }, 17717a4da28bSPeter Xu '*detach': 'bool', '*resume': 'bool' } } 177248685a8eSMarkus Armbruster 177348685a8eSMarkus Armbruster## 177448685a8eSMarkus Armbruster# @migrate-incoming: 177548685a8eSMarkus Armbruster# 1776a937b6aaSMarkus Armbruster# Start an incoming migration, the qemu must have been started with 1777a937b6aaSMarkus Armbruster# -incoming defer 177848685a8eSMarkus Armbruster# 177948685a8eSMarkus Armbruster# @uri: The Uniform Resource Identifier identifying the source or 178048685a8eSMarkus Armbruster# address to listen on 178148685a8eSMarkus Armbruster# 1782074dbce5SHet Gala# @channels: list of migration stream channels with each stream in the 1783074dbce5SHet Gala# list connected to a destination interface endpoint. 1784074dbce5SHet Gala# 178548685a8eSMarkus Armbruster# Returns: nothing on success 178648685a8eSMarkus Armbruster# 178748685a8eSMarkus Armbruster# Since: 2.3 178848685a8eSMarkus Armbruster# 178948685a8eSMarkus Armbruster# Notes: 179048685a8eSMarkus Armbruster# 17911ed1d4d6SMarkus Armbruster# 1. It's a bad idea to use a string for the uri, but it needs to 17921ed1d4d6SMarkus Armbruster# stay compatible with -incoming and the format of the uri is 17931ed1d4d6SMarkus Armbruster# already exposed above libvirt. 179448685a8eSMarkus Armbruster# 1795a937b6aaSMarkus Armbruster# 2. QEMU must be started with -incoming defer to allow 1796a937b6aaSMarkus Armbruster# migrate-incoming to be used. 179748685a8eSMarkus Armbruster# 179848685a8eSMarkus Armbruster# 3. The uri format is the same as for -incoming 179948685a8eSMarkus Armbruster# 1800*3cee17e7SHet Gala# 4. For now, number of migration streams is restricted to one, 18011ed1d4d6SMarkus Armbruster# i.e number of items in 'channels' list is just 1. 1802074dbce5SHet Gala# 1803*3cee17e7SHet Gala# 5. The 'uri' and 'channels' arguments are mutually exclusive; 1804074dbce5SHet Gala# exactly one of the two should be present. 1805074dbce5SHet Gala# 180648685a8eSMarkus Armbruster# Example: 180748685a8eSMarkus Armbruster# 180848685a8eSMarkus Armbruster# -> { "execute": "migrate-incoming", 1809*3cee17e7SHet Gala# "arguments": { "uri": "tcp:0:4446" } } 181048685a8eSMarkus Armbruster# <- { "return": {} } 1811074dbce5SHet Gala# 1812*3cee17e7SHet Gala# -> { "execute": "migrate-incoming", 1813074dbce5SHet Gala# "arguments": { 1814074dbce5SHet Gala# "channels": [ { "channel-type": "main", 1815074dbce5SHet Gala# "addr": { "transport": "socket", 1816074dbce5SHet Gala# "type": "inet", 1817074dbce5SHet Gala# "host": "10.12.34.9", 1818074dbce5SHet Gala# "port": "1050" } } ] } } 1819074dbce5SHet Gala# <- { "return": {} } 1820074dbce5SHet Gala# 1821*3cee17e7SHet Gala# -> { "execute": "migrate-incoming", 1822074dbce5SHet Gala# "arguments": { 1823074dbce5SHet Gala# "channels": [ { "channel-type": "main", 1824074dbce5SHet Gala# "addr": { "transport": "exec", 1825074dbce5SHet Gala# "args": [ "/bin/nc", "-p", "6000", 1826074dbce5SHet Gala# "/some/sock" ] } } ] } } 1827074dbce5SHet Gala# <- { "return": {} } 1828074dbce5SHet Gala# 1829*3cee17e7SHet Gala# -> { "execute": "migrate-incoming", 1830074dbce5SHet Gala# "arguments": { 1831074dbce5SHet Gala# "channels": [ { "channel-type": "main", 1832074dbce5SHet Gala# "addr": { "transport": "rdma", 1833074dbce5SHet Gala# "host": "10.12.34.9", 1834074dbce5SHet Gala# "port": "1050" } } ] } } 1835074dbce5SHet Gala# <- { "return": {} } 183648685a8eSMarkus Armbruster## 1837074dbce5SHet Gala{ 'command': 'migrate-incoming', 1838074dbce5SHet Gala 'data': {'*uri': 'str', 1839074dbce5SHet Gala '*channels': [ 'MigrationChannel' ] } } 184048685a8eSMarkus Armbruster 184148685a8eSMarkus Armbruster## 184248685a8eSMarkus Armbruster# @xen-save-devices-state: 184348685a8eSMarkus Armbruster# 1844a937b6aaSMarkus Armbruster# Save the state of all devices to file. The RAM and the block 1845a937b6aaSMarkus Armbruster# devices of the VM are not saved by this command. 184648685a8eSMarkus Armbruster# 184748685a8eSMarkus Armbruster# @filename: the file to save the state of the devices to as binary 1848a937b6aaSMarkus Armbruster# data. See xen-save-devices-state.txt for a description of the 1849a937b6aaSMarkus Armbruster# binary format. 185048685a8eSMarkus Armbruster# 1851a937b6aaSMarkus Armbruster# @live: Optional argument to ask QEMU to treat this command as part 1852a937b6aaSMarkus Armbruster# of a live migration. Default to true. (since 2.11) 18535d6c599fSAnthony PERARD# 185448685a8eSMarkus Armbruster# Returns: Nothing on success 185548685a8eSMarkus Armbruster# 185648685a8eSMarkus Armbruster# Since: 1.1 185748685a8eSMarkus Armbruster# 185848685a8eSMarkus Armbruster# Example: 185948685a8eSMarkus Armbruster# 186048685a8eSMarkus Armbruster# -> { "execute": "xen-save-devices-state", 186148685a8eSMarkus Armbruster# "arguments": { "filename": "/tmp/save" } } 186248685a8eSMarkus Armbruster# <- { "return": {} } 186348685a8eSMarkus Armbruster## 18645d6c599fSAnthony PERARD{ 'command': 'xen-save-devices-state', 18655d6c599fSAnthony PERARD 'data': {'filename': 'str', '*live':'bool' } } 186648685a8eSMarkus Armbruster 186748685a8eSMarkus Armbruster## 186828af9ba2SPhilippe Mathieu-Daudé# @xen-set-global-dirty-log: 186928af9ba2SPhilippe Mathieu-Daudé# 187028af9ba2SPhilippe Mathieu-Daudé# Enable or disable the global dirty log mode. 187128af9ba2SPhilippe Mathieu-Daudé# 187228af9ba2SPhilippe Mathieu-Daudé# @enable: true to enable, false to disable. 187328af9ba2SPhilippe Mathieu-Daudé# 187428af9ba2SPhilippe Mathieu-Daudé# Returns: nothing 187528af9ba2SPhilippe Mathieu-Daudé# 187628af9ba2SPhilippe Mathieu-Daudé# Since: 1.3 187728af9ba2SPhilippe Mathieu-Daudé# 187828af9ba2SPhilippe Mathieu-Daudé# Example: 187928af9ba2SPhilippe Mathieu-Daudé# 188028af9ba2SPhilippe Mathieu-Daudé# -> { "execute": "xen-set-global-dirty-log", 188128af9ba2SPhilippe Mathieu-Daudé# "arguments": { "enable": true } } 188228af9ba2SPhilippe Mathieu-Daudé# <- { "return": {} } 188328af9ba2SPhilippe Mathieu-Daudé## 188428af9ba2SPhilippe Mathieu-Daudé{ 'command': 'xen-set-global-dirty-log', 'data': { 'enable': 'bool' } } 188528af9ba2SPhilippe Mathieu-Daudé 188628af9ba2SPhilippe Mathieu-Daudé## 188728af9ba2SPhilippe Mathieu-Daudé# @xen-load-devices-state: 188828af9ba2SPhilippe Mathieu-Daudé# 1889a937b6aaSMarkus Armbruster# Load the state of all devices from file. The RAM and the block 1890a937b6aaSMarkus Armbruster# devices of the VM are not loaded by this command. 189128af9ba2SPhilippe Mathieu-Daudé# 189228af9ba2SPhilippe Mathieu-Daudé# @filename: the file to load the state of the devices from as binary 1893a937b6aaSMarkus Armbruster# data. See xen-save-devices-state.txt for a description of the 1894a937b6aaSMarkus Armbruster# binary format. 189528af9ba2SPhilippe Mathieu-Daudé# 189628af9ba2SPhilippe Mathieu-Daudé# Since: 2.7 189728af9ba2SPhilippe Mathieu-Daudé# 189828af9ba2SPhilippe Mathieu-Daudé# Example: 189928af9ba2SPhilippe Mathieu-Daudé# 190028af9ba2SPhilippe Mathieu-Daudé# -> { "execute": "xen-load-devices-state", 190128af9ba2SPhilippe Mathieu-Daudé# "arguments": { "filename": "/tmp/resume" } } 190228af9ba2SPhilippe Mathieu-Daudé# <- { "return": {} } 190328af9ba2SPhilippe Mathieu-Daudé## 190428af9ba2SPhilippe Mathieu-Daudé{ 'command': 'xen-load-devices-state', 'data': {'filename': 'str'} } 190528af9ba2SPhilippe Mathieu-Daudé 190628af9ba2SPhilippe Mathieu-Daudé## 190748685a8eSMarkus Armbruster# @xen-set-replication: 190848685a8eSMarkus Armbruster# 190948685a8eSMarkus Armbruster# Enable or disable replication. 191048685a8eSMarkus Armbruster# 191148685a8eSMarkus Armbruster# @enable: true to enable, false to disable. 191248685a8eSMarkus Armbruster# 191348685a8eSMarkus Armbruster# @primary: true for primary or false for secondary. 191448685a8eSMarkus Armbruster# 191548685a8eSMarkus Armbruster# @failover: true to do failover, false to stop. but cannot be 191648685a8eSMarkus Armbruster# specified if 'enable' is true. default value is false. 191748685a8eSMarkus Armbruster# 191848685a8eSMarkus Armbruster# Returns: nothing. 191948685a8eSMarkus Armbruster# 192048685a8eSMarkus Armbruster# Example: 192148685a8eSMarkus Armbruster# 192248685a8eSMarkus Armbruster# -> { "execute": "xen-set-replication", 192348685a8eSMarkus Armbruster# "arguments": {"enable": true, "primary": false} } 192448685a8eSMarkus Armbruster# <- { "return": {} } 192548685a8eSMarkus Armbruster# 192648685a8eSMarkus Armbruster# Since: 2.9 192748685a8eSMarkus Armbruster## 192848685a8eSMarkus Armbruster{ 'command': 'xen-set-replication', 1929335d10cdSMarc-André Lureau 'data': { 'enable': 'bool', 'primary': 'bool', '*failover': 'bool' }, 19308a9f1e1dSMarc-André Lureau 'if': 'CONFIG_REPLICATION' } 193148685a8eSMarkus Armbruster 193248685a8eSMarkus Armbruster## 193348685a8eSMarkus Armbruster# @ReplicationStatus: 193448685a8eSMarkus Armbruster# 193548685a8eSMarkus Armbruster# The result format for 'query-xen-replication-status'. 193648685a8eSMarkus Armbruster# 193748685a8eSMarkus Armbruster# @error: true if an error happened, false if replication is normal. 193848685a8eSMarkus Armbruster# 1939a937b6aaSMarkus Armbruster# @desc: the human readable error description string, when @error is 1940a937b6aaSMarkus Armbruster# 'true'. 194148685a8eSMarkus Armbruster# 194248685a8eSMarkus Armbruster# Since: 2.9 194348685a8eSMarkus Armbruster## 194448685a8eSMarkus Armbruster{ 'struct': 'ReplicationStatus', 1945335d10cdSMarc-André Lureau 'data': { 'error': 'bool', '*desc': 'str' }, 19468a9f1e1dSMarc-André Lureau 'if': 'CONFIG_REPLICATION' } 194748685a8eSMarkus Armbruster 194848685a8eSMarkus Armbruster## 194948685a8eSMarkus Armbruster# @query-xen-replication-status: 195048685a8eSMarkus Armbruster# 195148685a8eSMarkus Armbruster# Query replication status while the vm is running. 195248685a8eSMarkus Armbruster# 1953f4347129SAndrea Bolognani# Returns: A @ReplicationStatus object showing the status. 195448685a8eSMarkus Armbruster# 195548685a8eSMarkus Armbruster# Example: 195648685a8eSMarkus Armbruster# 195748685a8eSMarkus Armbruster# -> { "execute": "query-xen-replication-status" } 195848685a8eSMarkus Armbruster# <- { "return": { "error": false } } 195948685a8eSMarkus Armbruster# 196048685a8eSMarkus Armbruster# Since: 2.9 196148685a8eSMarkus Armbruster## 196248685a8eSMarkus Armbruster{ 'command': 'query-xen-replication-status', 1963335d10cdSMarc-André Lureau 'returns': 'ReplicationStatus', 19648a9f1e1dSMarc-André Lureau 'if': 'CONFIG_REPLICATION' } 196548685a8eSMarkus Armbruster 196648685a8eSMarkus Armbruster## 196748685a8eSMarkus Armbruster# @xen-colo-do-checkpoint: 196848685a8eSMarkus Armbruster# 196948685a8eSMarkus Armbruster# Xen uses this command to notify replication to trigger a checkpoint. 197048685a8eSMarkus Armbruster# 197148685a8eSMarkus Armbruster# Returns: nothing. 197248685a8eSMarkus Armbruster# 197348685a8eSMarkus Armbruster# Example: 197448685a8eSMarkus Armbruster# 197548685a8eSMarkus Armbruster# -> { "execute": "xen-colo-do-checkpoint" } 197648685a8eSMarkus Armbruster# <- { "return": {} } 197748685a8eSMarkus Armbruster# 197848685a8eSMarkus Armbruster# Since: 2.9 197948685a8eSMarkus Armbruster## 1980335d10cdSMarc-André Lureau{ 'command': 'xen-colo-do-checkpoint', 19818a9f1e1dSMarc-André Lureau 'if': 'CONFIG_REPLICATION' } 198202affd41SPeter Xu 198302affd41SPeter Xu## 1984f56c0065SZhang Chen# @COLOStatus: 1985f56c0065SZhang Chen# 1986f56c0065SZhang Chen# The result format for 'query-colo-status'. 1987f56c0065SZhang Chen# 1988a937b6aaSMarkus Armbruster# @mode: COLO running mode. If COLO is running, this field will 1989a937b6aaSMarkus Armbruster# return 'primary' or 'secondary'. 1990f56c0065SZhang Chen# 19915cc8f9ebSZhang Chen# @last-mode: COLO last running mode. If COLO is running, this field 1992a937b6aaSMarkus Armbruster# will return same like mode field, after failover we can use this 1993a937b6aaSMarkus Armbruster# field to get last colo mode. (since 4.0) 19945ed0decaSZhang Chen# 1995f56c0065SZhang Chen# @reason: describes the reason for the COLO exit. 1996f56c0065SZhang Chen# 1997ea3b23e5SZhang Chen# Since: 3.1 1998f56c0065SZhang Chen## 1999f56c0065SZhang Chen{ 'struct': 'COLOStatus', 20005cc8f9ebSZhang Chen 'data': { 'mode': 'COLOMode', 'last-mode': 'COLOMode', 200151e47cf8SVladimir Sementsov-Ogievskiy 'reason': 'COLOExitReason' }, 200251e47cf8SVladimir Sementsov-Ogievskiy 'if': 'CONFIG_REPLICATION' } 2003f56c0065SZhang Chen 2004f56c0065SZhang Chen## 2005f56c0065SZhang Chen# @query-colo-status: 2006f56c0065SZhang Chen# 2007f56c0065SZhang Chen# Query COLO status while the vm is running. 2008f56c0065SZhang Chen# 2009f56c0065SZhang Chen# Returns: A @COLOStatus object showing the status. 2010f56c0065SZhang Chen# 2011f56c0065SZhang Chen# Example: 2012f56c0065SZhang Chen# 2013f56c0065SZhang Chen# -> { "execute": "query-colo-status" } 201451ec294dSVictor Toso# <- { "return": { "mode": "primary", "last-mode": "none", "reason": "request" } } 2015f56c0065SZhang Chen# 2016ea3b23e5SZhang Chen# Since: 3.1 2017f56c0065SZhang Chen## 2018f56c0065SZhang Chen{ 'command': 'query-colo-status', 201951e47cf8SVladimir Sementsov-Ogievskiy 'returns': 'COLOStatus', 202051e47cf8SVladimir Sementsov-Ogievskiy 'if': 'CONFIG_REPLICATION' } 2021f56c0065SZhang Chen 2022f56c0065SZhang Chen## 202302affd41SPeter Xu# @migrate-recover: 202402affd41SPeter Xu# 202502affd41SPeter Xu# Provide a recovery migration stream URI. 202602affd41SPeter Xu# 202702affd41SPeter Xu# @uri: the URI to be used for the recovery of migration stream. 202802affd41SPeter Xu# 202902affd41SPeter Xu# Returns: nothing. 203002affd41SPeter Xu# 203102affd41SPeter Xu# Example: 203202affd41SPeter Xu# 203302affd41SPeter Xu# -> { "execute": "migrate-recover", 203402affd41SPeter Xu# "arguments": { "uri": "tcp:192.168.1.200:12345" } } 203502affd41SPeter Xu# <- { "return": {} } 203602affd41SPeter Xu# 203751f63ec7SPeter Maydell# Since: 3.0 203802affd41SPeter Xu## 2039b0ddeba2SMarc-André Lureau{ 'command': 'migrate-recover', 2040b0ddeba2SMarc-André Lureau 'data': { 'uri': 'str' }, 204102affd41SPeter Xu 'allow-oob': true } 2042bfbf89c2SPeter Xu 2043bfbf89c2SPeter Xu## 2044bfbf89c2SPeter Xu# @migrate-pause: 2045bfbf89c2SPeter Xu# 2046bfbf89c2SPeter Xu# Pause a migration. Currently it only supports postcopy. 2047bfbf89c2SPeter Xu# 2048bfbf89c2SPeter Xu# Returns: nothing. 2049bfbf89c2SPeter Xu# 2050bfbf89c2SPeter Xu# Example: 2051bfbf89c2SPeter Xu# 2052bfbf89c2SPeter Xu# -> { "execute": "migrate-pause" } 2053bfbf89c2SPeter Xu# <- { "return": {} } 2054bfbf89c2SPeter Xu# 205551f63ec7SPeter Maydell# Since: 3.0 2056bfbf89c2SPeter Xu## 2057bfbf89c2SPeter Xu{ 'command': 'migrate-pause', 'allow-oob': true } 2058d328e6f3SJens Freimann 2059d328e6f3SJens Freimann## 2060d328e6f3SJens Freimann# @UNPLUG_PRIMARY: 2061d328e6f3SJens Freimann# 2062d328e6f3SJens Freimann# Emitted from source side of a migration when migration state is 2063a937b6aaSMarkus Armbruster# WAIT_UNPLUG. Device was unplugged by guest operating system. Device 2064a937b6aaSMarkus Armbruster# resources in QEMU are kept on standby to be able to re-plug it in 2065a937b6aaSMarkus Armbruster# case of migration failure. 2066d328e6f3SJens Freimann# 2067d328e6f3SJens Freimann# @device-id: QEMU device id of the unplugged device 2068d328e6f3SJens Freimann# 2069d328e6f3SJens Freimann# Since: 4.2 2070d328e6f3SJens Freimann# 2071d328e6f3SJens Freimann# Example: 20724ae65a52SAndrea Bolognani# 20730df5e9a3SVictor Toso# <- { "event": "UNPLUG_PRIMARY", 20740df5e9a3SVictor Toso# "data": { "device-id": "hostdev0" }, 20750df5e9a3SVictor Toso# "timestamp": { "seconds": 1265044230, "microseconds": 450486 } } 2076d328e6f3SJens Freimann## 2077d328e6f3SJens Freimann{ 'event': 'UNPLUG_PRIMARY', 2078d328e6f3SJens Freimann 'data': { 'device-id': 'str' } } 20797df3aa30SChuan Zheng 20807df3aa30SChuan Zheng## 208171864eadSHyman Huang(黄勇)# @DirtyRateVcpu: 208271864eadSHyman Huang(黄勇)# 208371864eadSHyman Huang(黄勇)# Dirty rate of vcpu. 208471864eadSHyman Huang(黄勇)# 208571864eadSHyman Huang(黄勇)# @id: vcpu index. 208671864eadSHyman Huang(黄勇)# 208771864eadSHyman Huang(黄勇)# @dirty-rate: dirty rate. 208871864eadSHyman Huang(黄勇)# 2089f78d4ed7SHyman Huang(黄勇)# Since: 6.2 209071864eadSHyman Huang(黄勇)## 209171864eadSHyman Huang(黄勇){ 'struct': 'DirtyRateVcpu', 209271864eadSHyman Huang(黄勇) 'data': { 'id': 'int', 'dirty-rate': 'int64' } } 209371864eadSHyman Huang(黄勇) 209471864eadSHyman Huang(黄勇)## 20957df3aa30SChuan Zheng# @DirtyRateStatus: 20967df3aa30SChuan Zheng# 20975034e3d4SAndrei Gudkov# Dirty page rate measurement status. 20987df3aa30SChuan Zheng# 20995034e3d4SAndrei Gudkov# @unstarted: measuring thread has not been started yet 21007df3aa30SChuan Zheng# 21015034e3d4SAndrei Gudkov# @measuring: measuring thread is running 21027df3aa30SChuan Zheng# 21035034e3d4SAndrei Gudkov# @measured: dirty page rate is measured and the results are available 21047df3aa30SChuan Zheng# 21057df3aa30SChuan Zheng# Since: 5.2 21067df3aa30SChuan Zheng## 21077df3aa30SChuan Zheng{ 'enum': 'DirtyRateStatus', 21087df3aa30SChuan Zheng 'data': [ 'unstarted', 'measuring', 'measured'] } 21094c437254SChuan Zheng 21104c437254SChuan Zheng## 211171864eadSHyman Huang(黄勇)# @DirtyRateMeasureMode: 211271864eadSHyman Huang(黄勇)# 21135034e3d4SAndrei Gudkov# Method used to measure dirty page rate. Differences between 21145034e3d4SAndrei Gudkov# available methods are explained in @calc-dirty-rate. 211571864eadSHyman Huang(黄勇)# 21165034e3d4SAndrei Gudkov# @page-sampling: use page sampling 211771864eadSHyman Huang(黄勇)# 21185034e3d4SAndrei Gudkov# @dirty-ring: use dirty ring 2119826b8bc8SHyman Huang(黄勇)# 21205034e3d4SAndrei Gudkov# @dirty-bitmap: use dirty bitmap 212171864eadSHyman Huang(黄勇)# 2122f78d4ed7SHyman Huang(黄勇)# Since: 6.2 212371864eadSHyman Huang(黄勇)## 212471864eadSHyman Huang(黄勇){ 'enum': 'DirtyRateMeasureMode', 2125826b8bc8SHyman Huang(黄勇) 'data': ['page-sampling', 'dirty-ring', 'dirty-bitmap'] } 212671864eadSHyman Huang(黄勇) 212771864eadSHyman Huang(黄勇)## 212834a68001SAndrei Gudkov# @TimeUnit: 212934a68001SAndrei Gudkov# 213034a68001SAndrei Gudkov# Specifies unit in which time-related value is specified. 213134a68001SAndrei Gudkov# 213234a68001SAndrei Gudkov# @second: value is in seconds 213334a68001SAndrei Gudkov# 213434a68001SAndrei Gudkov# @millisecond: value is in milliseconds 213534a68001SAndrei Gudkov# 213637507c14SMarkus Armbruster# Since: 8.2 213734a68001SAndrei Gudkov# 213834a68001SAndrei Gudkov## 213934a68001SAndrei Gudkov{ 'enum': 'TimeUnit', 214034a68001SAndrei Gudkov 'data': ['second', 'millisecond'] } 214134a68001SAndrei Gudkov 214234a68001SAndrei Gudkov## 21434c437254SChuan Zheng# @DirtyRateInfo: 21444c437254SChuan Zheng# 21455034e3d4SAndrei Gudkov# Information about measured dirty page rate. 21464c437254SChuan Zheng# 2147a937b6aaSMarkus Armbruster# @dirty-rate: an estimate of the dirty page rate of the VM in units 21485034e3d4SAndrei Gudkov# of MiB/s. Value is present only when @status is 'measured'. 21494c437254SChuan Zheng# 21505034e3d4SAndrei Gudkov# @status: current status of dirty page rate measurements 21514c437254SChuan Zheng# 21524c437254SChuan Zheng# @start-time: start time in units of second for calculation 21534c437254SChuan Zheng# 215434a68001SAndrei Gudkov# @calc-time: time period for which dirty page rate was measured, 215534a68001SAndrei Gudkov# expressed and rounded down to @calc-time-unit. 215634a68001SAndrei Gudkov# 215734a68001SAndrei Gudkov# @calc-time-unit: time unit of @calc-time (Since 8.2) 21584c437254SChuan Zheng# 21595034e3d4SAndrei Gudkov# @sample-pages: number of sampled pages per GiB of guest memory. 21605034e3d4SAndrei Gudkov# Valid only in page-sampling mode (Since 6.1) 21617afa08cdSHyman Huang(黄勇)# 21625034e3d4SAndrei Gudkov# @mode: mode that was used to measure dirty page rate (Since 6.2) 21630e21bf24SHyman Huang(黄勇)# 21645034e3d4SAndrei Gudkov# @vcpu-dirty-rate: dirty rate for each vCPU if dirty-ring mode was 2165a937b6aaSMarkus Armbruster# specified (Since 6.2) 21660e21bf24SHyman Huang(黄勇)# 21674c437254SChuan Zheng# Since: 5.2 21684c437254SChuan Zheng## 21694c437254SChuan Zheng{ 'struct': 'DirtyRateInfo', 2170b1a859cfSChuan Zheng 'data': {'*dirty-rate': 'int64', 21714c437254SChuan Zheng 'status': 'DirtyRateStatus', 21724c437254SChuan Zheng 'start-time': 'int64', 21737afa08cdSHyman Huang(黄勇) 'calc-time': 'int64', 217434a68001SAndrei Gudkov 'calc-time-unit': 'TimeUnit', 21750e21bf24SHyman Huang(黄勇) 'sample-pages': 'uint64', 21760e21bf24SHyman Huang(黄勇) 'mode': 'DirtyRateMeasureMode', 21770e21bf24SHyman Huang(黄勇) '*vcpu-dirty-rate': [ 'DirtyRateVcpu' ] } } 21784c437254SChuan Zheng 21794c437254SChuan Zheng## 21804c437254SChuan Zheng# @calc-dirty-rate: 21814c437254SChuan Zheng# 21825034e3d4SAndrei Gudkov# Start measuring dirty page rate of the VM. Results can be retrieved 21835034e3d4SAndrei Gudkov# with @query-dirty-rate after measurements are completed. 21844c437254SChuan Zheng# 21855034e3d4SAndrei Gudkov# Dirty page rate is the number of pages changed in a given time 21865034e3d4SAndrei Gudkov# period expressed in MiB/s. The following methods of calculation are 21875034e3d4SAndrei Gudkov# available: 21884c437254SChuan Zheng# 21895034e3d4SAndrei Gudkov# 1. In page sampling mode, a random subset of pages are selected and 21905034e3d4SAndrei Gudkov# hashed twice: once at the beginning of measurement time period, 21915034e3d4SAndrei Gudkov# and once again at the end. If two hashes for some page are 21925034e3d4SAndrei Gudkov# different, the page is counted as changed. Since this method 21935034e3d4SAndrei Gudkov# relies on sampling and hashing, calculated dirty page rate is 21945034e3d4SAndrei Gudkov# only an estimate of its true value. Increasing @sample-pages 21955034e3d4SAndrei Gudkov# improves estimation quality at the cost of higher computational 21965034e3d4SAndrei Gudkov# overhead. 21977afa08cdSHyman Huang(黄勇)# 21985034e3d4SAndrei Gudkov# 2. Dirty bitmap mode captures writes to memory (for example by 21995034e3d4SAndrei Gudkov# temporarily revoking write access to all pages) and counting page 22005034e3d4SAndrei Gudkov# faults. Information about modified pages is collected into a 22015034e3d4SAndrei Gudkov# bitmap, where each bit corresponds to one guest page. This mode 22025034e3d4SAndrei Gudkov# requires that KVM accelerator property "dirty-ring-size" is *not* 22035034e3d4SAndrei Gudkov# set. 22045034e3d4SAndrei Gudkov# 22055034e3d4SAndrei Gudkov# 3. Dirty ring mode is similar to dirty bitmap mode, but the 22065034e3d4SAndrei Gudkov# information about modified pages is collected into ring buffer. 22075034e3d4SAndrei Gudkov# This mode tracks page modification per each vCPU separately. It 22085034e3d4SAndrei Gudkov# requires that KVM accelerator property "dirty-ring-size" is set. 22095034e3d4SAndrei Gudkov# 221034a68001SAndrei Gudkov# @calc-time: time period for which dirty page rate is calculated. 221134a68001SAndrei Gudkov# By default it is specified in seconds, but the unit can be set 221234a68001SAndrei Gudkov# explicitly with @calc-time-unit. Note that larger @calc-time 221334a68001SAndrei Gudkov# values will typically result in smaller dirty page rates because 221434a68001SAndrei Gudkov# page dirtying is a one-time event. Once some page is counted 221534a68001SAndrei Gudkov# as dirty during @calc-time period, further writes to this page 221634a68001SAndrei Gudkov# will not increase dirty page rate anymore. 221734a68001SAndrei Gudkov# 221834a68001SAndrei Gudkov# @calc-time-unit: time unit in which @calc-time is specified. 221934a68001SAndrei Gudkov# By default it is seconds. (Since 8.2) 22205034e3d4SAndrei Gudkov# 22215034e3d4SAndrei Gudkov# @sample-pages: number of sampled pages per each GiB of guest memory. 22225034e3d4SAndrei Gudkov# Default value is 512. For 4KiB guest pages this corresponds to 22235034e3d4SAndrei Gudkov# sampling ratio of 0.2%. This argument is used only in page 22245034e3d4SAndrei Gudkov# sampling mode. (Since 6.1) 22255034e3d4SAndrei Gudkov# 22265034e3d4SAndrei Gudkov# @mode: mechanism for tracking dirty pages. Default value is 22275034e3d4SAndrei Gudkov# 'page-sampling'. Others are 'dirty-bitmap' and 'dirty-ring'. 22285034e3d4SAndrei Gudkov# (Since 6.1) 22290e21bf24SHyman Huang(黄勇)# 22304c437254SChuan Zheng# Since: 5.2 22314c437254SChuan Zheng# 22324c437254SChuan Zheng# Example: 22334ae65a52SAndrea Bolognani# 223437fa48a4SMarkus Armbruster# -> {"execute": "calc-dirty-rate", "arguments": {"calc-time": 1, 22357afa08cdSHyman Huang(黄勇)# 'sample-pages': 512} } 223637fa48a4SMarkus Armbruster# <- { "return": {} } 223734a68001SAndrei Gudkov# 223834a68001SAndrei Gudkov# Measure dirty rate using dirty bitmap for 500 milliseconds: 223934a68001SAndrei Gudkov# 224034a68001SAndrei Gudkov# -> {"execute": "calc-dirty-rate", "arguments": {"calc-time": 500, 224134a68001SAndrei Gudkov# "calc-time-unit": "millisecond", "mode": "dirty-bitmap"} } 224234a68001SAndrei Gudkov# 224334a68001SAndrei Gudkov# <- { "return": {} } 22444c437254SChuan Zheng## 22457afa08cdSHyman Huang(黄勇){ 'command': 'calc-dirty-rate', 'data': {'calc-time': 'int64', 224634a68001SAndrei Gudkov '*calc-time-unit': 'TimeUnit', 22470e21bf24SHyman Huang(黄勇) '*sample-pages': 'int', 22480e21bf24SHyman Huang(黄勇) '*mode': 'DirtyRateMeasureMode'} } 22494c437254SChuan Zheng 22504c437254SChuan Zheng## 22514c437254SChuan Zheng# @query-dirty-rate: 22524c437254SChuan Zheng# 22535034e3d4SAndrei Gudkov# Query results of the most recent invocation of @calc-dirty-rate. 22544c437254SChuan Zheng# 225534a68001SAndrei Gudkov# @calc-time-unit: time unit in which to report calculation time. 225634a68001SAndrei Gudkov# By default it is reported in seconds. (Since 8.2) 225734a68001SAndrei Gudkov# 22584c437254SChuan Zheng# Since: 5.2 22595034e3d4SAndrei Gudkov# 22605034e3d4SAndrei Gudkov# Examples: 22615034e3d4SAndrei Gudkov# 22625034e3d4SAndrei Gudkov# 1. Measurement is in progress: 22635034e3d4SAndrei Gudkov# 22645034e3d4SAndrei Gudkov# <- {"status": "measuring", "sample-pages": 512, 2265320a6cccSAndrei Gudkov# "mode": "page-sampling", "start-time": 1693900454, "calc-time": 10, 226634a68001SAndrei Gudkov# "calc-time-unit": "second"} 22675034e3d4SAndrei Gudkov# 22685034e3d4SAndrei Gudkov# 2. Measurement has been completed: 22695034e3d4SAndrei Gudkov# 22705034e3d4SAndrei Gudkov# <- {"status": "measured", "sample-pages": 512, "dirty-rate": 108, 2271320a6cccSAndrei Gudkov# "mode": "page-sampling", "start-time": 1693900454, "calc-time": 10, 227234a68001SAndrei Gudkov# "calc-time-unit": "second"} 22734c437254SChuan Zheng## 227434a68001SAndrei Gudkov{ 'command': 'query-dirty-rate', 'data': {'*calc-time-unit': 'TimeUnit' }, 227534a68001SAndrei Gudkov 'returns': 'DirtyRateInfo' } 22760f0d83a4SDaniel P. Berrangé 22770f0d83a4SDaniel P. Berrangé## 2278f3b2e38cSHyman Huang(黄勇)# @DirtyLimitInfo: 2279f3b2e38cSHyman Huang(黄勇)# 2280f3b2e38cSHyman Huang(黄勇)# Dirty page rate limit information of a virtual CPU. 2281f3b2e38cSHyman Huang(黄勇)# 2282f3b2e38cSHyman Huang(黄勇)# @cpu-index: index of a virtual CPU. 2283f3b2e38cSHyman Huang(黄勇)# 2284f3b2e38cSHyman Huang(黄勇)# @limit-rate: upper limit of dirty page rate (MB/s) for a virtual 2285f3b2e38cSHyman Huang(黄勇)# CPU, 0 means unlimited. 2286f3b2e38cSHyman Huang(黄勇)# 2287f3b2e38cSHyman Huang(黄勇)# @current-rate: current dirty page rate (MB/s) for a virtual CPU. 2288f3b2e38cSHyman Huang(黄勇)# 2289f3b2e38cSHyman Huang(黄勇)# Since: 7.1 2290f3b2e38cSHyman Huang(黄勇)## 2291f3b2e38cSHyman Huang(黄勇){ 'struct': 'DirtyLimitInfo', 2292f3b2e38cSHyman Huang(黄勇) 'data': { 'cpu-index': 'int', 2293f3b2e38cSHyman Huang(黄勇) 'limit-rate': 'uint64', 2294f3b2e38cSHyman Huang(黄勇) 'current-rate': 'uint64' } } 2295f3b2e38cSHyman Huang(黄勇) 2296f3b2e38cSHyman Huang(黄勇)## 2297f3b2e38cSHyman Huang(黄勇)# @set-vcpu-dirty-limit: 2298f3b2e38cSHyman Huang(黄勇)# 2299f3b2e38cSHyman Huang(黄勇)# Set the upper limit of dirty page rate for virtual CPUs. 2300f3b2e38cSHyman Huang(黄勇)# 2301a937b6aaSMarkus Armbruster# Requires KVM with accelerator property "dirty-ring-size" set. A 2302a937b6aaSMarkus Armbruster# virtual CPU's dirty page rate is a measure of its memory load. To 2303a937b6aaSMarkus Armbruster# observe dirty page rates, use @calc-dirty-rate. 2304f3b2e38cSHyman Huang(黄勇)# 2305f3b2e38cSHyman Huang(黄勇)# @cpu-index: index of a virtual CPU, default is all. 2306f3b2e38cSHyman Huang(黄勇)# 2307f3b2e38cSHyman Huang(黄勇)# @dirty-rate: upper limit of dirty page rate (MB/s) for virtual CPUs. 2308f3b2e38cSHyman Huang(黄勇)# 2309f3b2e38cSHyman Huang(黄勇)# Since: 7.1 2310f3b2e38cSHyman Huang(黄勇)# 2311f3b2e38cSHyman Huang(黄勇)# Example: 231237fa48a4SMarkus Armbruster# 231337fa48a4SMarkus Armbruster# -> {"execute": "set-vcpu-dirty-limit"} 2314f3b2e38cSHyman Huang(黄勇)# "arguments": { "dirty-rate": 200, 2315f3b2e38cSHyman Huang(黄勇)# "cpu-index": 1 } } 231637fa48a4SMarkus Armbruster# <- { "return": {} } 2317f3b2e38cSHyman Huang(黄勇)## 2318f3b2e38cSHyman Huang(黄勇){ 'command': 'set-vcpu-dirty-limit', 2319f3b2e38cSHyman Huang(黄勇) 'data': { '*cpu-index': 'int', 2320f3b2e38cSHyman Huang(黄勇) 'dirty-rate': 'uint64' } } 2321f3b2e38cSHyman Huang(黄勇) 2322f3b2e38cSHyman Huang(黄勇)## 2323f3b2e38cSHyman Huang(黄勇)# @cancel-vcpu-dirty-limit: 2324f3b2e38cSHyman Huang(黄勇)# 2325f3b2e38cSHyman Huang(黄勇)# Cancel the upper limit of dirty page rate for virtual CPUs. 2326f3b2e38cSHyman Huang(黄勇)# 2327f3b2e38cSHyman Huang(黄勇)# Cancel the dirty page limit for the vCPU which has been set with 2328f3b2e38cSHyman Huang(黄勇)# set-vcpu-dirty-limit command. Note that this command requires 2329f3b2e38cSHyman Huang(黄勇)# support from dirty ring, same as the "set-vcpu-dirty-limit". 2330f3b2e38cSHyman Huang(黄勇)# 2331f3b2e38cSHyman Huang(黄勇)# @cpu-index: index of a virtual CPU, default is all. 2332f3b2e38cSHyman Huang(黄勇)# 2333f3b2e38cSHyman Huang(黄勇)# Since: 7.1 2334f3b2e38cSHyman Huang(黄勇)# 2335f3b2e38cSHyman Huang(黄勇)# Example: 233637fa48a4SMarkus Armbruster# 233737fa48a4SMarkus Armbruster# -> {"execute": "cancel-vcpu-dirty-limit"}, 2338f3b2e38cSHyman Huang(黄勇)# "arguments": { "cpu-index": 1 } } 233937fa48a4SMarkus Armbruster# <- { "return": {} } 2340f3b2e38cSHyman Huang(黄勇)## 2341f3b2e38cSHyman Huang(黄勇){ 'command': 'cancel-vcpu-dirty-limit', 2342f3b2e38cSHyman Huang(黄勇) 'data': { '*cpu-index': 'int'} } 2343f3b2e38cSHyman Huang(黄勇) 2344f3b2e38cSHyman Huang(黄勇)## 2345f3b2e38cSHyman Huang(黄勇)# @query-vcpu-dirty-limit: 2346f3b2e38cSHyman Huang(黄勇)# 2347a937b6aaSMarkus Armbruster# Returns information about virtual CPU dirty page rate limits, if 2348a937b6aaSMarkus Armbruster# any. 2349f3b2e38cSHyman Huang(黄勇)# 2350f3b2e38cSHyman Huang(黄勇)# Since: 7.1 2351f3b2e38cSHyman Huang(黄勇)# 2352f3b2e38cSHyman Huang(黄勇)# Example: 235337fa48a4SMarkus Armbruster# 235437fa48a4SMarkus Armbruster# -> {"execute": "query-vcpu-dirty-limit"} 235537fa48a4SMarkus Armbruster# <- {"return": [ 235637fa48a4SMarkus Armbruster# { "limit-rate": 60, "current-rate": 3, "cpu-index": 0}, 235737fa48a4SMarkus Armbruster# { "limit-rate": 60, "current-rate": 3, "cpu-index": 1}]} 2358f3b2e38cSHyman Huang(黄勇)## 2359f3b2e38cSHyman Huang(黄勇){ 'command': 'query-vcpu-dirty-limit', 2360f3b2e38cSHyman Huang(黄勇) 'returns': [ 'DirtyLimitInfo' ] } 2361f3b2e38cSHyman Huang(黄勇) 2362f3b2e38cSHyman Huang(黄勇)## 236367132620SJiang Jiacheng# @MigrationThreadInfo: 236467132620SJiang Jiacheng# 236567132620SJiang Jiacheng# Information about migrationthreads 236667132620SJiang Jiacheng# 236767132620SJiang Jiacheng# @name: the name of migration thread 236867132620SJiang Jiacheng# 236967132620SJiang Jiacheng# @thread-id: ID of the underlying host thread 237067132620SJiang Jiacheng# 237167132620SJiang Jiacheng# Since: 7.2 237267132620SJiang Jiacheng## 237367132620SJiang Jiacheng{ 'struct': 'MigrationThreadInfo', 237467132620SJiang Jiacheng 'data': {'name': 'str', 237567132620SJiang Jiacheng 'thread-id': 'int'} } 237667132620SJiang Jiacheng 237767132620SJiang Jiacheng## 237867132620SJiang Jiacheng# @query-migrationthreads: 237967132620SJiang Jiacheng# 238067132620SJiang Jiacheng# Returns information of migration threads 238167132620SJiang Jiacheng# 238267132620SJiang Jiacheng# data: migration thread name 238367132620SJiang Jiacheng# 23847c3def93SMarkus Armbruster# Returns: information about migration threads 238567132620SJiang Jiacheng# 238667132620SJiang Jiacheng# Since: 7.2 238767132620SJiang Jiacheng## 238867132620SJiang Jiacheng{ 'command': 'query-migrationthreads', 238967132620SJiang Jiacheng 'returns': ['MigrationThreadInfo'] } 239067132620SJiang Jiacheng 239167132620SJiang Jiacheng## 23920f0d83a4SDaniel P. Berrangé# @snapshot-save: 23930f0d83a4SDaniel P. Berrangé# 23940f0d83a4SDaniel P. Berrangé# Save a VM snapshot 23950f0d83a4SDaniel P. Berrangé# 23960f0d83a4SDaniel P. Berrangé# @job-id: identifier for the newly created job 2397a937b6aaSMarkus Armbruster# 23980f0d83a4SDaniel P. Berrangé# @tag: name of the snapshot to create 2399a937b6aaSMarkus Armbruster# 24000f0d83a4SDaniel P. Berrangé# @vmstate: block device node name to save vmstate to 2401a937b6aaSMarkus Armbruster# 24020f0d83a4SDaniel P. Berrangé# @devices: list of block device node names to save a snapshot to 24030f0d83a4SDaniel P. Berrangé# 24040f0d83a4SDaniel P. Berrangé# Applications should not assume that the snapshot save is complete 24050f0d83a4SDaniel P. Berrangé# when this command returns. The job commands / events must be used 2406a937b6aaSMarkus Armbruster# to determine completion and to fetch details of any errors that 2407a937b6aaSMarkus Armbruster# arise. 24080f0d83a4SDaniel P. Berrangé# 2409a937b6aaSMarkus Armbruster# Note that execution of the guest CPUs may be stopped during the time 2410a937b6aaSMarkus Armbruster# it takes to save the snapshot. A future version of QEMU may ensure 2411a937b6aaSMarkus Armbruster# CPUs are executing continuously. 24120f0d83a4SDaniel P. Berrangé# 2413a937b6aaSMarkus Armbruster# It is strongly recommended that @devices contain all writable block 2414a937b6aaSMarkus Armbruster# device nodes if a consistent snapshot is required. 24150f0d83a4SDaniel P. Berrangé# 24160f0d83a4SDaniel P. Berrangé# If @tag already exists, an error will be reported 24170f0d83a4SDaniel P. Berrangé# 24180f0d83a4SDaniel P. Berrangé# Returns: nothing 24190f0d83a4SDaniel P. Berrangé# 24200f0d83a4SDaniel P. Berrangé# Example: 24210f0d83a4SDaniel P. Berrangé# 24220f0d83a4SDaniel P. Berrangé# -> { "execute": "snapshot-save", 2423b1ca5322SFabian Holler# "arguments": { 24240f0d83a4SDaniel P. Berrangé# "job-id": "snapsave0", 24250f0d83a4SDaniel P. Berrangé# "tag": "my-snap", 24260f0d83a4SDaniel P. Berrangé# "vmstate": "disk0", 24270f0d83a4SDaniel P. Berrangé# "devices": ["disk0", "disk1"] 24280f0d83a4SDaniel P. Berrangé# } 24290f0d83a4SDaniel P. Berrangé# } 24300f0d83a4SDaniel P. Berrangé# <- { "return": { } } 24310f0d83a4SDaniel P. Berrangé# <- {"event": "JOB_STATUS_CHANGE", 24326e7a37ffSVictor Toso# "timestamp": {"seconds": 1432121972, "microseconds": 744001}, 24330f0d83a4SDaniel P. Berrangé# "data": {"status": "created", "id": "snapsave0"}} 24340f0d83a4SDaniel P. Berrangé# <- {"event": "JOB_STATUS_CHANGE", 24356e7a37ffSVictor Toso# "timestamp": {"seconds": 1432122172, "microseconds": 744001}, 24360f0d83a4SDaniel P. Berrangé# "data": {"status": "running", "id": "snapsave0"}} 24376e7a37ffSVictor Toso# <- {"event": "STOP", 24386e7a37ffSVictor Toso# "timestamp": {"seconds": 1432122372, "microseconds": 744001} } 24396e7a37ffSVictor Toso# <- {"event": "RESUME", 24406e7a37ffSVictor Toso# "timestamp": {"seconds": 1432122572, "microseconds": 744001} } 24410f0d83a4SDaniel P. Berrangé# <- {"event": "JOB_STATUS_CHANGE", 24426e7a37ffSVictor Toso# "timestamp": {"seconds": 1432122772, "microseconds": 744001}, 24430f0d83a4SDaniel P. Berrangé# "data": {"status": "waiting", "id": "snapsave0"}} 24440f0d83a4SDaniel P. Berrangé# <- {"event": "JOB_STATUS_CHANGE", 24456e7a37ffSVictor Toso# "timestamp": {"seconds": 1432122972, "microseconds": 744001}, 24460f0d83a4SDaniel P. Berrangé# "data": {"status": "pending", "id": "snapsave0"}} 24470f0d83a4SDaniel P. Berrangé# <- {"event": "JOB_STATUS_CHANGE", 24486e7a37ffSVictor Toso# "timestamp": {"seconds": 1432123172, "microseconds": 744001}, 24490f0d83a4SDaniel P. Berrangé# "data": {"status": "concluded", "id": "snapsave0"}} 24500f0d83a4SDaniel P. Berrangé# -> {"execute": "query-jobs"} 24510f0d83a4SDaniel P. Berrangé# <- {"return": [{"current-progress": 1, 24520f0d83a4SDaniel P. Berrangé# "status": "concluded", 24530f0d83a4SDaniel P. Berrangé# "total-progress": 1, 24540f0d83a4SDaniel P. Berrangé# "type": "snapshot-save", 24550f0d83a4SDaniel P. Berrangé# "id": "snapsave0"}]} 24560f0d83a4SDaniel P. Berrangé# 24570f0d83a4SDaniel P. Berrangé# Since: 6.0 24580f0d83a4SDaniel P. Berrangé## 24590f0d83a4SDaniel P. Berrangé{ 'command': 'snapshot-save', 24600f0d83a4SDaniel P. Berrangé 'data': { 'job-id': 'str', 24610f0d83a4SDaniel P. Berrangé 'tag': 'str', 24620f0d83a4SDaniel P. Berrangé 'vmstate': 'str', 24630f0d83a4SDaniel P. Berrangé 'devices': ['str'] } } 24640f0d83a4SDaniel P. Berrangé 24650f0d83a4SDaniel P. Berrangé## 24660f0d83a4SDaniel P. Berrangé# @snapshot-load: 24670f0d83a4SDaniel P. Berrangé# 24680f0d83a4SDaniel P. Berrangé# Load a VM snapshot 24690f0d83a4SDaniel P. Berrangé# 24700f0d83a4SDaniel P. Berrangé# @job-id: identifier for the newly created job 2471a937b6aaSMarkus Armbruster# 24720f0d83a4SDaniel P. Berrangé# @tag: name of the snapshot to load. 2473a937b6aaSMarkus Armbruster# 24740f0d83a4SDaniel P. Berrangé# @vmstate: block device node name to load vmstate from 2475a937b6aaSMarkus Armbruster# 24760f0d83a4SDaniel P. Berrangé# @devices: list of block device node names to load a snapshot from 24770f0d83a4SDaniel P. Berrangé# 24780f0d83a4SDaniel P. Berrangé# Applications should not assume that the snapshot load is complete 24790f0d83a4SDaniel P. Berrangé# when this command returns. The job commands / events must be used 2480a937b6aaSMarkus Armbruster# to determine completion and to fetch details of any errors that 2481a937b6aaSMarkus Armbruster# arise. 24820f0d83a4SDaniel P. Berrangé# 24830f0d83a4SDaniel P. Berrangé# Note that execution of the guest CPUs will be stopped during the 24840f0d83a4SDaniel P. Berrangé# time it takes to load the snapshot. 24850f0d83a4SDaniel P. Berrangé# 2486a937b6aaSMarkus Armbruster# It is strongly recommended that @devices contain all writable block 2487a937b6aaSMarkus Armbruster# device nodes that can have changed since the original @snapshot-save 2488a937b6aaSMarkus Armbruster# command execution. 24890f0d83a4SDaniel P. Berrangé# 24900f0d83a4SDaniel P. Berrangé# Returns: nothing 24910f0d83a4SDaniel P. Berrangé# 24920f0d83a4SDaniel P. Berrangé# Example: 24930f0d83a4SDaniel P. Berrangé# 24940f0d83a4SDaniel P. Berrangé# -> { "execute": "snapshot-load", 2495b1ca5322SFabian Holler# "arguments": { 24960f0d83a4SDaniel P. Berrangé# "job-id": "snapload0", 24970f0d83a4SDaniel P. Berrangé# "tag": "my-snap", 24980f0d83a4SDaniel P. Berrangé# "vmstate": "disk0", 24990f0d83a4SDaniel P. Berrangé# "devices": ["disk0", "disk1"] 25000f0d83a4SDaniel P. Berrangé# } 25010f0d83a4SDaniel P. Berrangé# } 25020f0d83a4SDaniel P. Berrangé# <- { "return": { } } 25030f0d83a4SDaniel P. Berrangé# <- {"event": "JOB_STATUS_CHANGE", 25046e7a37ffSVictor Toso# "timestamp": {"seconds": 1472124172, "microseconds": 744001}, 25050f0d83a4SDaniel P. Berrangé# "data": {"status": "created", "id": "snapload0"}} 25060f0d83a4SDaniel P. Berrangé# <- {"event": "JOB_STATUS_CHANGE", 25076e7a37ffSVictor Toso# "timestamp": {"seconds": 1472125172, "microseconds": 744001}, 25080f0d83a4SDaniel P. Berrangé# "data": {"status": "running", "id": "snapload0"}} 25096e7a37ffSVictor Toso# <- {"event": "STOP", 25106e7a37ffSVictor Toso# "timestamp": {"seconds": 1472125472, "microseconds": 744001} } 25116e7a37ffSVictor Toso# <- {"event": "RESUME", 25126e7a37ffSVictor Toso# "timestamp": {"seconds": 1472125872, "microseconds": 744001} } 25130f0d83a4SDaniel P. Berrangé# <- {"event": "JOB_STATUS_CHANGE", 25146e7a37ffSVictor Toso# "timestamp": {"seconds": 1472126172, "microseconds": 744001}, 25150f0d83a4SDaniel P. Berrangé# "data": {"status": "waiting", "id": "snapload0"}} 25160f0d83a4SDaniel P. Berrangé# <- {"event": "JOB_STATUS_CHANGE", 25176e7a37ffSVictor Toso# "timestamp": {"seconds": 1472127172, "microseconds": 744001}, 25180f0d83a4SDaniel P. Berrangé# "data": {"status": "pending", "id": "snapload0"}} 25190f0d83a4SDaniel P. Berrangé# <- {"event": "JOB_STATUS_CHANGE", 25206e7a37ffSVictor Toso# "timestamp": {"seconds": 1472128172, "microseconds": 744001}, 25210f0d83a4SDaniel P. Berrangé# "data": {"status": "concluded", "id": "snapload0"}} 25220f0d83a4SDaniel P. Berrangé# -> {"execute": "query-jobs"} 25230f0d83a4SDaniel P. Berrangé# <- {"return": [{"current-progress": 1, 25240f0d83a4SDaniel P. Berrangé# "status": "concluded", 25250f0d83a4SDaniel P. Berrangé# "total-progress": 1, 25260f0d83a4SDaniel P. Berrangé# "type": "snapshot-load", 25270f0d83a4SDaniel P. Berrangé# "id": "snapload0"}]} 25280f0d83a4SDaniel P. Berrangé# 25290f0d83a4SDaniel P. Berrangé# Since: 6.0 25300f0d83a4SDaniel P. Berrangé## 25310f0d83a4SDaniel P. Berrangé{ 'command': 'snapshot-load', 25320f0d83a4SDaniel P. Berrangé 'data': { 'job-id': 'str', 25330f0d83a4SDaniel P. Berrangé 'tag': 'str', 25340f0d83a4SDaniel P. Berrangé 'vmstate': 'str', 25350f0d83a4SDaniel P. Berrangé 'devices': ['str'] } } 25360f0d83a4SDaniel P. Berrangé 25370f0d83a4SDaniel P. Berrangé## 25380f0d83a4SDaniel P. Berrangé# @snapshot-delete: 25390f0d83a4SDaniel P. Berrangé# 25400f0d83a4SDaniel P. Berrangé# Delete a VM snapshot 25410f0d83a4SDaniel P. Berrangé# 25420f0d83a4SDaniel P. Berrangé# @job-id: identifier for the newly created job 2543a937b6aaSMarkus Armbruster# 25440f0d83a4SDaniel P. Berrangé# @tag: name of the snapshot to delete. 2545a937b6aaSMarkus Armbruster# 25460f0d83a4SDaniel P. Berrangé# @devices: list of block device node names to delete a snapshot from 25470f0d83a4SDaniel P. Berrangé# 25480f0d83a4SDaniel P. Berrangé# Applications should not assume that the snapshot delete is complete 25490f0d83a4SDaniel P. Berrangé# when this command returns. The job commands / events must be used 2550a937b6aaSMarkus Armbruster# to determine completion and to fetch details of any errors that 2551a937b6aaSMarkus Armbruster# arise. 25520f0d83a4SDaniel P. Berrangé# 25530f0d83a4SDaniel P. Berrangé# Returns: nothing 25540f0d83a4SDaniel P. Berrangé# 25550f0d83a4SDaniel P. Berrangé# Example: 25560f0d83a4SDaniel P. Berrangé# 25570f0d83a4SDaniel P. Berrangé# -> { "execute": "snapshot-delete", 2558b1ca5322SFabian Holler# "arguments": { 25590f0d83a4SDaniel P. Berrangé# "job-id": "snapdelete0", 25600f0d83a4SDaniel P. Berrangé# "tag": "my-snap", 25610f0d83a4SDaniel P. Berrangé# "devices": ["disk0", "disk1"] 25620f0d83a4SDaniel P. Berrangé# } 25630f0d83a4SDaniel P. Berrangé# } 25640f0d83a4SDaniel P. Berrangé# <- { "return": { } } 25650f0d83a4SDaniel P. Berrangé# <- {"event": "JOB_STATUS_CHANGE", 25666e7a37ffSVictor Toso# "timestamp": {"seconds": 1442124172, "microseconds": 744001}, 25670f0d83a4SDaniel P. Berrangé# "data": {"status": "created", "id": "snapdelete0"}} 25680f0d83a4SDaniel P. Berrangé# <- {"event": "JOB_STATUS_CHANGE", 25696e7a37ffSVictor Toso# "timestamp": {"seconds": 1442125172, "microseconds": 744001}, 25700f0d83a4SDaniel P. Berrangé# "data": {"status": "running", "id": "snapdelete0"}} 25710f0d83a4SDaniel P. Berrangé# <- {"event": "JOB_STATUS_CHANGE", 25726e7a37ffSVictor Toso# "timestamp": {"seconds": 1442126172, "microseconds": 744001}, 25730f0d83a4SDaniel P. Berrangé# "data": {"status": "waiting", "id": "snapdelete0"}} 25740f0d83a4SDaniel P. Berrangé# <- {"event": "JOB_STATUS_CHANGE", 25756e7a37ffSVictor Toso# "timestamp": {"seconds": 1442127172, "microseconds": 744001}, 25760f0d83a4SDaniel P. Berrangé# "data": {"status": "pending", "id": "snapdelete0"}} 25770f0d83a4SDaniel P. Berrangé# <- {"event": "JOB_STATUS_CHANGE", 25786e7a37ffSVictor Toso# "timestamp": {"seconds": 1442128172, "microseconds": 744001}, 25790f0d83a4SDaniel P. Berrangé# "data": {"status": "concluded", "id": "snapdelete0"}} 25800f0d83a4SDaniel P. Berrangé# -> {"execute": "query-jobs"} 25810f0d83a4SDaniel P. Berrangé# <- {"return": [{"current-progress": 1, 25820f0d83a4SDaniel P. Berrangé# "status": "concluded", 25830f0d83a4SDaniel P. Berrangé# "total-progress": 1, 25840f0d83a4SDaniel P. Berrangé# "type": "snapshot-delete", 25850f0d83a4SDaniel P. Berrangé# "id": "snapdelete0"}]} 25860f0d83a4SDaniel P. Berrangé# 25870f0d83a4SDaniel P. Berrangé# Since: 6.0 25880f0d83a4SDaniel P. Berrangé## 25890f0d83a4SDaniel P. Berrangé{ 'command': 'snapshot-delete', 25900f0d83a4SDaniel P. Berrangé 'data': { 'job-id': 'str', 25910f0d83a4SDaniel P. Berrangé 'tag': 'str', 25920f0d83a4SDaniel P. Berrangé 'devices': ['str'] } } 2593