7e555c6c58
Limit the background transfer bandwidth during the postcopy phase to the value set on this new parameter. The default, 0, corresponds to the existing behaviour which is unlimited bandwidth. Signed-off-by: Dr. David Alan Gilbert <dgilbert@redhat.com> Message-Id: <20180613102642.23995-2-dgilbert@redhat.com> Reviewed-by: Peter Xu <peterx@redhat.com> Signed-off-by: Dr. David Alan Gilbert <dgilbert@redhat.com>
1248 lines
38 KiB
Python
1248 lines
38 KiB
Python
# -*- Mode: Python -*-
|
|
#
|
|
|
|
##
|
|
# = Migration
|
|
##
|
|
|
|
{ 'include': 'common.json' }
|
|
|
|
##
|
|
# @MigrationStats:
|
|
#
|
|
# Detailed migration status.
|
|
#
|
|
# @transferred: amount of bytes already transferred to the target VM
|
|
#
|
|
# @remaining: amount of bytes remaining to be transferred to the target VM
|
|
#
|
|
# @total: total amount of bytes involved in the migration process
|
|
#
|
|
# @duplicate: number of duplicate (zero) pages (since 1.2)
|
|
#
|
|
# @skipped: number of skipped zero pages (since 1.5)
|
|
#
|
|
# @normal: number of normal pages (since 1.2)
|
|
#
|
|
# @normal-bytes: number of normal bytes sent (since 1.2)
|
|
#
|
|
# @dirty-pages-rate: number of pages dirtied by second by the
|
|
# guest (since 1.3)
|
|
#
|
|
# @mbps: throughput in megabits/sec. (since 1.6)
|
|
#
|
|
# @dirty-sync-count: number of times that dirty ram was synchronized (since 2.1)
|
|
#
|
|
# @postcopy-requests: The number of page requests received from the destination
|
|
# (since 2.7)
|
|
#
|
|
# @page-size: The number of bytes per page for the various page-based
|
|
# statistics (since 2.10)
|
|
#
|
|
# Since: 0.14.0
|
|
##
|
|
{ 'struct': 'MigrationStats',
|
|
'data': {'transferred': 'int', 'remaining': 'int', 'total': 'int' ,
|
|
'duplicate': 'int', 'skipped': 'int', 'normal': 'int',
|
|
'normal-bytes': 'int', 'dirty-pages-rate' : 'int',
|
|
'mbps' : 'number', 'dirty-sync-count' : 'int',
|
|
'postcopy-requests' : 'int', 'page-size' : 'int' } }
|
|
|
|
##
|
|
# @XBZRLECacheStats:
|
|
#
|
|
# Detailed XBZRLE migration cache statistics
|
|
#
|
|
# @cache-size: XBZRLE cache size
|
|
#
|
|
# @bytes: amount of bytes already transferred to the target VM
|
|
#
|
|
# @pages: amount of pages transferred to the target VM
|
|
#
|
|
# @cache-miss: number of cache miss
|
|
#
|
|
# @cache-miss-rate: rate of cache miss (since 2.1)
|
|
#
|
|
# @overflow: number of overflows
|
|
#
|
|
# Since: 1.2
|
|
##
|
|
{ 'struct': 'XBZRLECacheStats',
|
|
'data': {'cache-size': 'int', 'bytes': 'int', 'pages': 'int',
|
|
'cache-miss': 'int', 'cache-miss-rate': 'number',
|
|
'overflow': 'int' } }
|
|
|
|
##
|
|
# @MigrationStatus:
|
|
#
|
|
# An enumeration of migration status.
|
|
#
|
|
# @none: no migration has ever happened.
|
|
#
|
|
# @setup: migration process has been initiated.
|
|
#
|
|
# @cancelling: in the process of cancelling migration.
|
|
#
|
|
# @cancelled: cancelling migration is finished.
|
|
#
|
|
# @active: in the process of doing migration.
|
|
#
|
|
# @postcopy-active: like active, but now in postcopy mode. (since 2.5)
|
|
#
|
|
# @postcopy-paused: during postcopy but paused. (since 3.0)
|
|
#
|
|
# @postcopy-recover: trying to recover from a paused postcopy. (since 3.0)
|
|
#
|
|
# @completed: migration is finished.
|
|
#
|
|
# @failed: some error occurred during migration process.
|
|
#
|
|
# @colo: VM is in the process of fault tolerance, VM can not get into this
|
|
# state unless colo capability is enabled for migration. (since 2.8)
|
|
#
|
|
# @pre-switchover: Paused before device serialisation. (since 2.11)
|
|
#
|
|
# @device: During device serialisation when pause-before-switchover is enabled
|
|
# (since 2.11)
|
|
#
|
|
# Since: 2.3
|
|
#
|
|
##
|
|
{ 'enum': 'MigrationStatus',
|
|
'data': [ 'none', 'setup', 'cancelling', 'cancelled',
|
|
'active', 'postcopy-active', 'postcopy-paused',
|
|
'postcopy-recover', 'completed', 'failed', 'colo',
|
|
'pre-switchover', 'device' ] }
|
|
|
|
##
|
|
# @MigrationInfo:
|
|
#
|
|
# Information about current migration process.
|
|
#
|
|
# @status: @MigrationStatus describing the current migration status.
|
|
# If this field is not returned, no migration process
|
|
# has been initiated
|
|
#
|
|
# @ram: @MigrationStats containing detailed migration
|
|
# status, only returned if status is 'active' or
|
|
# 'completed'(since 1.2)
|
|
#
|
|
# @disk: @MigrationStats containing detailed disk migration
|
|
# status, only returned if status is 'active' and it is a block
|
|
# migration
|
|
#
|
|
# @xbzrle-cache: @XBZRLECacheStats containing detailed XBZRLE
|
|
# migration statistics, only returned if XBZRLE feature is on and
|
|
# status is 'active' or 'completed' (since 1.2)
|
|
#
|
|
# @total-time: total amount of milliseconds since migration started.
|
|
# If migration has ended, it returns the total migration
|
|
# time. (since 1.2)
|
|
#
|
|
# @downtime: only present when migration finishes correctly
|
|
# total downtime in milliseconds for the guest.
|
|
# (since 1.3)
|
|
#
|
|
# @expected-downtime: only present while migration is active
|
|
# expected downtime in milliseconds for the guest in last walk
|
|
# of the dirty bitmap. (since 1.3)
|
|
#
|
|
# @setup-time: amount of setup time in milliseconds _before_ the
|
|
# iterations begin but _after_ the QMP command is issued. This is designed
|
|
# to provide an accounting of any activities (such as RDMA pinning) which
|
|
# may be expensive, but do not actually occur during the iterative
|
|
# migration rounds themselves. (since 1.6)
|
|
#
|
|
# @cpu-throttle-percentage: percentage of time guest cpus are being
|
|
# throttled during auto-converge. This is only present when auto-converge
|
|
# has started throttling guest cpus. (Since 2.7)
|
|
#
|
|
# @error-desc: the human readable error description string, when
|
|
# @status is 'failed'. Clients should not attempt to parse the
|
|
# error strings. (Since 2.7)
|
|
#
|
|
# @postcopy-blocktime: total time when all vCPU were blocked during postcopy
|
|
# live migration. This is only present when the postcopy-blocktime
|
|
# migration capability is enabled. (Since 3.0)
|
|
#
|
|
# @postcopy-vcpu-blocktime: list of the postcopy blocktime per vCPU. This is
|
|
# only present when the postcopy-blocktime migration capability
|
|
# is enabled. (Since 3.0)
|
|
#
|
|
#
|
|
# Since: 0.14.0
|
|
##
|
|
{ 'struct': 'MigrationInfo',
|
|
'data': {'*status': 'MigrationStatus', '*ram': 'MigrationStats',
|
|
'*disk': 'MigrationStats',
|
|
'*xbzrle-cache': 'XBZRLECacheStats',
|
|
'*total-time': 'int',
|
|
'*expected-downtime': 'int',
|
|
'*downtime': 'int',
|
|
'*setup-time': 'int',
|
|
'*cpu-throttle-percentage': 'int',
|
|
'*error-desc': 'str',
|
|
'*postcopy-blocktime' : 'uint32',
|
|
'*postcopy-vcpu-blocktime': ['uint32']} }
|
|
|
|
##
|
|
# @query-migrate:
|
|
#
|
|
# Returns information about current migration process. If migration
|
|
# is active there will be another json-object with RAM migration
|
|
# status and if block migration is active another one with block
|
|
# migration status.
|
|
#
|
|
# Returns: @MigrationInfo
|
|
#
|
|
# Since: 0.14.0
|
|
#
|
|
# Example:
|
|
#
|
|
# 1. Before the first migration
|
|
#
|
|
# -> { "execute": "query-migrate" }
|
|
# <- { "return": {} }
|
|
#
|
|
# 2. Migration is done and has succeeded
|
|
#
|
|
# -> { "execute": "query-migrate" }
|
|
# <- { "return": {
|
|
# "status": "completed",
|
|
# "ram":{
|
|
# "transferred":123,
|
|
# "remaining":123,
|
|
# "total":246,
|
|
# "total-time":12345,
|
|
# "setup-time":12345,
|
|
# "downtime":12345,
|
|
# "duplicate":123,
|
|
# "normal":123,
|
|
# "normal-bytes":123456,
|
|
# "dirty-sync-count":15
|
|
# }
|
|
# }
|
|
# }
|
|
#
|
|
# 3. Migration is done and has failed
|
|
#
|
|
# -> { "execute": "query-migrate" }
|
|
# <- { "return": { "status": "failed" } }
|
|
#
|
|
# 4. Migration is being performed and is not a block migration:
|
|
#
|
|
# -> { "execute": "query-migrate" }
|
|
# <- {
|
|
# "return":{
|
|
# "status":"active",
|
|
# "ram":{
|
|
# "transferred":123,
|
|
# "remaining":123,
|
|
# "total":246,
|
|
# "total-time":12345,
|
|
# "setup-time":12345,
|
|
# "expected-downtime":12345,
|
|
# "duplicate":123,
|
|
# "normal":123,
|
|
# "normal-bytes":123456,
|
|
# "dirty-sync-count":15
|
|
# }
|
|
# }
|
|
# }
|
|
#
|
|
# 5. Migration is being performed and is a block migration:
|
|
#
|
|
# -> { "execute": "query-migrate" }
|
|
# <- {
|
|
# "return":{
|
|
# "status":"active",
|
|
# "ram":{
|
|
# "total":1057024,
|
|
# "remaining":1053304,
|
|
# "transferred":3720,
|
|
# "total-time":12345,
|
|
# "setup-time":12345,
|
|
# "expected-downtime":12345,
|
|
# "duplicate":123,
|
|
# "normal":123,
|
|
# "normal-bytes":123456,
|
|
# "dirty-sync-count":15
|
|
# },
|
|
# "disk":{
|
|
# "total":20971520,
|
|
# "remaining":20880384,
|
|
# "transferred":91136
|
|
# }
|
|
# }
|
|
# }
|
|
#
|
|
# 6. Migration is being performed and XBZRLE is active:
|
|
#
|
|
# -> { "execute": "query-migrate" }
|
|
# <- {
|
|
# "return":{
|
|
# "status":"active",
|
|
# "capabilities" : [ { "capability": "xbzrle", "state" : true } ],
|
|
# "ram":{
|
|
# "total":1057024,
|
|
# "remaining":1053304,
|
|
# "transferred":3720,
|
|
# "total-time":12345,
|
|
# "setup-time":12345,
|
|
# "expected-downtime":12345,
|
|
# "duplicate":10,
|
|
# "normal":3333,
|
|
# "normal-bytes":3412992,
|
|
# "dirty-sync-count":15
|
|
# },
|
|
# "xbzrle-cache":{
|
|
# "cache-size":67108864,
|
|
# "bytes":20971520,
|
|
# "pages":2444343,
|
|
# "cache-miss":2244,
|
|
# "cache-miss-rate":0.123,
|
|
# "overflow":34434
|
|
# }
|
|
# }
|
|
# }
|
|
#
|
|
##
|
|
{ 'command': 'query-migrate', 'returns': 'MigrationInfo' }
|
|
|
|
##
|
|
# @MigrationCapability:
|
|
#
|
|
# Migration capabilities enumeration
|
|
#
|
|
# @xbzrle: Migration supports xbzrle (Xor Based Zero Run Length Encoding).
|
|
# This feature allows us to minimize migration traffic for certain work
|
|
# loads, by sending compressed difference of the pages
|
|
#
|
|
# @rdma-pin-all: Controls whether or not the entire VM memory footprint is
|
|
# mlock()'d on demand or all at once. Refer to docs/rdma.txt for usage.
|
|
# Disabled by default. (since 2.0)
|
|
#
|
|
# @zero-blocks: During storage migration encode blocks of zeroes efficiently. This
|
|
# essentially saves 1MB of zeroes per block on the wire. Enabling requires
|
|
# source and target VM to support this feature. To enable it is sufficient
|
|
# to enable the capability on the source VM. The feature is disabled by
|
|
# default. (since 1.6)
|
|
#
|
|
# @compress: Use multiple compression threads to accelerate live migration.
|
|
# This feature can help to reduce the migration traffic, by sending
|
|
# compressed pages. Please note that if compress and xbzrle are both
|
|
# on, compress only takes effect in the ram bulk stage, after that,
|
|
# it will be disabled and only xbzrle takes effect, this can help to
|
|
# minimize migration traffic. The feature is disabled by default.
|
|
# (since 2.4 )
|
|
#
|
|
# @events: generate events for each migration state change
|
|
# (since 2.4 )
|
|
#
|
|
# @auto-converge: If enabled, QEMU will automatically throttle down the guest
|
|
# to speed up convergence of RAM migration. (since 1.6)
|
|
#
|
|
# @postcopy-ram: Start executing on the migration target before all of RAM has
|
|
# been migrated, pulling the remaining pages along as needed. The
|
|
# capacity must have the same setting on both source and target
|
|
# or migration will not even start. NOTE: If the migration fails during
|
|
# postcopy the VM will fail. (since 2.6)
|
|
#
|
|
# @x-colo: If enabled, migration will never end, and the state of the VM on the
|
|
# primary side will be migrated continuously to the VM on secondary
|
|
# side, this process is called COarse-Grain LOck Stepping (COLO) for
|
|
# Non-stop Service. (since 2.8)
|
|
#
|
|
# @release-ram: if enabled, qemu will free the migrated ram pages on the source
|
|
# during postcopy-ram migration. (since 2.9)
|
|
#
|
|
# @block: If enabled, QEMU will also migrate the contents of all block
|
|
# devices. Default is disabled. A possible alternative uses
|
|
# mirror jobs to a builtin NBD server on the destination, which
|
|
# offers more flexibility.
|
|
# (Since 2.10)
|
|
#
|
|
# @return-path: If enabled, migration will use the return path even
|
|
# for precopy. (since 2.10)
|
|
#
|
|
# @pause-before-switchover: Pause outgoing migration before serialising device
|
|
# state and before disabling block IO (since 2.11)
|
|
#
|
|
# @x-multifd: Use more than one fd for migration (since 2.11)
|
|
#
|
|
# @dirty-bitmaps: If enabled, QEMU will migrate named dirty bitmaps.
|
|
# (since 2.12)
|
|
#
|
|
# @postcopy-blocktime: Calculate downtime for postcopy live migration
|
|
# (since 3.0)
|
|
#
|
|
# @late-block-activate: If enabled, the destination will not activate block
|
|
# devices (and thus take locks) immediately at the end of migration.
|
|
# (since 3.0)
|
|
#
|
|
# Since: 1.2
|
|
##
|
|
{ 'enum': 'MigrationCapability',
|
|
'data': ['xbzrle', 'rdma-pin-all', 'auto-converge', 'zero-blocks',
|
|
'compress', 'events', 'postcopy-ram', 'x-colo', 'release-ram',
|
|
'block', 'return-path', 'pause-before-switchover', 'x-multifd',
|
|
'dirty-bitmaps', 'postcopy-blocktime', 'late-block-activate' ] }
|
|
|
|
##
|
|
# @MigrationCapabilityStatus:
|
|
#
|
|
# Migration capability information
|
|
#
|
|
# @capability: capability enum
|
|
#
|
|
# @state: capability state bool
|
|
#
|
|
# Since: 1.2
|
|
##
|
|
{ 'struct': 'MigrationCapabilityStatus',
|
|
'data': { 'capability' : 'MigrationCapability', 'state' : 'bool' } }
|
|
|
|
##
|
|
# @migrate-set-capabilities:
|
|
#
|
|
# Enable/Disable the following migration capabilities (like xbzrle)
|
|
#
|
|
# @capabilities: json array of capability modifications to make
|
|
#
|
|
# Since: 1.2
|
|
#
|
|
# Example:
|
|
#
|
|
# -> { "execute": "migrate-set-capabilities" , "arguments":
|
|
# { "capabilities": [ { "capability": "xbzrle", "state": true } ] } }
|
|
#
|
|
##
|
|
{ 'command': 'migrate-set-capabilities',
|
|
'data': { 'capabilities': ['MigrationCapabilityStatus'] } }
|
|
|
|
##
|
|
# @query-migrate-capabilities:
|
|
#
|
|
# Returns information about the current migration capabilities status
|
|
#
|
|
# Returns: @MigrationCapabilitiesStatus
|
|
#
|
|
# Since: 1.2
|
|
#
|
|
# Example:
|
|
#
|
|
# -> { "execute": "query-migrate-capabilities" }
|
|
# <- { "return": [
|
|
# {"state": false, "capability": "xbzrle"},
|
|
# {"state": false, "capability": "rdma-pin-all"},
|
|
# {"state": false, "capability": "auto-converge"},
|
|
# {"state": false, "capability": "zero-blocks"},
|
|
# {"state": false, "capability": "compress"},
|
|
# {"state": true, "capability": "events"},
|
|
# {"state": false, "capability": "postcopy-ram"},
|
|
# {"state": false, "capability": "x-colo"}
|
|
# ]}
|
|
#
|
|
##
|
|
{ 'command': 'query-migrate-capabilities', 'returns': ['MigrationCapabilityStatus']}
|
|
|
|
##
|
|
# @MigrationParameter:
|
|
#
|
|
# Migration parameters enumeration
|
|
#
|
|
# @compress-level: Set the compression level to be used in live migration,
|
|
# the compression level is an integer between 0 and 9, where 0 means
|
|
# no compression, 1 means the best compression speed, and 9 means best
|
|
# compression ratio which will consume more CPU.
|
|
#
|
|
# @compress-threads: Set compression thread count to be used in live migration,
|
|
# the compression thread count is an integer between 1 and 255.
|
|
#
|
|
# @decompress-threads: Set decompression thread count to be used in live
|
|
# migration, the decompression thread count is an integer between 1
|
|
# and 255. Usually, decompression is at least 4 times as fast as
|
|
# compression, so set the decompress-threads to the number about 1/4
|
|
# of compress-threads is adequate.
|
|
#
|
|
# @cpu-throttle-initial: Initial percentage of time guest cpus are throttled
|
|
# when migration auto-converge is activated. The
|
|
# default value is 20. (Since 2.7)
|
|
#
|
|
# @cpu-throttle-increment: throttle percentage increase each time
|
|
# auto-converge detects that migration is not making
|
|
# progress. The default value is 10. (Since 2.7)
|
|
#
|
|
# @tls-creds: ID of the 'tls-creds' object that provides credentials for
|
|
# establishing a TLS connection over the migration data channel.
|
|
# On the outgoing side of the migration, the credentials must
|
|
# be for a 'client' endpoint, while for the incoming side the
|
|
# credentials must be for a 'server' endpoint. Setting this
|
|
# will enable TLS for all migrations. The default is unset,
|
|
# resulting in unsecured migration at the QEMU level. (Since 2.7)
|
|
#
|
|
# @tls-hostname: hostname of the target host for the migration. This is
|
|
# required when using x509 based TLS credentials and the
|
|
# migration URI does not already include a hostname. For
|
|
# example if using fd: or exec: based migration, the
|
|
# hostname must be provided so that the server's x509
|
|
# certificate identity can be validated. (Since 2.7)
|
|
#
|
|
# @max-bandwidth: to set maximum speed for migration. maximum speed in
|
|
# bytes per second. (Since 2.8)
|
|
#
|
|
# @downtime-limit: set maximum tolerated downtime for migration. maximum
|
|
# downtime in milliseconds (Since 2.8)
|
|
#
|
|
# @x-checkpoint-delay: The delay time (in ms) between two COLO checkpoints in
|
|
# periodic mode. (Since 2.8)
|
|
#
|
|
# @block-incremental: Affects how much storage is migrated when the
|
|
# block migration capability is enabled. When false, the entire
|
|
# storage backing chain is migrated into a flattened image at
|
|
# the destination; when true, only the active qcow2 layer is
|
|
# migrated and the destination must already have access to the
|
|
# same backing chain as was used on the source. (since 2.10)
|
|
#
|
|
# @x-multifd-channels: Number of channels used to migrate data in
|
|
# parallel. This is the same number that the
|
|
# number of sockets used for migration. The
|
|
# default value is 2 (since 2.11)
|
|
#
|
|
# @x-multifd-page-count: Number of pages sent together to a thread.
|
|
# The default value is 16 (since 2.11)
|
|
#
|
|
# @xbzrle-cache-size: cache size to be used by XBZRLE migration. It
|
|
# needs to be a multiple of the target page size
|
|
# and a power of 2
|
|
# (Since 2.11)
|
|
#
|
|
# @max-postcopy-bandwidth: Background transfer bandwidth during postcopy.
|
|
# Defaults to 0 (unlimited). In bytes per second.
|
|
# (Since 3.0)
|
|
# Since: 2.4
|
|
##
|
|
{ 'enum': 'MigrationParameter',
|
|
'data': ['compress-level', 'compress-threads', 'decompress-threads',
|
|
'cpu-throttle-initial', 'cpu-throttle-increment',
|
|
'tls-creds', 'tls-hostname', 'max-bandwidth',
|
|
'downtime-limit', 'x-checkpoint-delay', 'block-incremental',
|
|
'x-multifd-channels', 'x-multifd-page-count',
|
|
'xbzrle-cache-size', 'max-postcopy-bandwidth' ] }
|
|
|
|
##
|
|
# @MigrateSetParameters:
|
|
#
|
|
# @compress-level: compression level
|
|
#
|
|
# @compress-threads: compression thread count
|
|
#
|
|
# @decompress-threads: decompression thread count
|
|
#
|
|
# @cpu-throttle-initial: Initial percentage of time guest cpus are
|
|
# throttled when migration auto-converge is activated.
|
|
# The default value is 20. (Since 2.7)
|
|
#
|
|
# @cpu-throttle-increment: throttle percentage increase each time
|
|
# auto-converge detects that migration is not making
|
|
# progress. The default value is 10. (Since 2.7)
|
|
#
|
|
# @tls-creds: ID of the 'tls-creds' object that provides credentials
|
|
# for establishing a TLS connection over the migration data
|
|
# channel. On the outgoing side of the migration, the credentials
|
|
# must be for a 'client' endpoint, while for the incoming side the
|
|
# credentials must be for a 'server' endpoint. Setting this
|
|
# to a non-empty string enables TLS for all migrations.
|
|
# An empty string means that QEMU will use plain text mode for
|
|
# migration, rather than TLS (Since 2.9)
|
|
# Previously (since 2.7), this was reported by omitting
|
|
# tls-creds instead.
|
|
#
|
|
# @tls-hostname: hostname of the target host for the migration. This
|
|
# is required when using x509 based TLS credentials and the
|
|
# migration URI does not already include a hostname. For
|
|
# example if using fd: or exec: based migration, the
|
|
# hostname must be provided so that the server's x509
|
|
# certificate identity can be validated. (Since 2.7)
|
|
# An empty string means that QEMU will use the hostname
|
|
# associated with the migration URI, if any. (Since 2.9)
|
|
# Previously (since 2.7), this was reported by omitting
|
|
# tls-hostname instead.
|
|
#
|
|
# @max-bandwidth: to set maximum speed for migration. maximum speed in
|
|
# bytes per second. (Since 2.8)
|
|
#
|
|
# @downtime-limit: set maximum tolerated downtime for migration. maximum
|
|
# downtime in milliseconds (Since 2.8)
|
|
#
|
|
# @x-checkpoint-delay: the delay time between two COLO checkpoints. (Since 2.8)
|
|
#
|
|
# @block-incremental: Affects how much storage is migrated when the
|
|
# block migration capability is enabled. When false, the entire
|
|
# storage backing chain is migrated into a flattened image at
|
|
# the destination; when true, only the active qcow2 layer is
|
|
# migrated and the destination must already have access to the
|
|
# same backing chain as was used on the source. (since 2.10)
|
|
#
|
|
# @x-multifd-channels: Number of channels used to migrate data in
|
|
# parallel. This is the same number that the
|
|
# number of sockets used for migration. The
|
|
# default value is 2 (since 2.11)
|
|
#
|
|
# @x-multifd-page-count: Number of pages sent together to a thread.
|
|
# The default value is 16 (since 2.11)
|
|
#
|
|
# @xbzrle-cache-size: cache size to be used by XBZRLE migration. It
|
|
# needs to be a multiple of the target page size
|
|
# and a power of 2
|
|
# (Since 2.11)
|
|
#
|
|
# @max-postcopy-bandwidth: Background transfer bandwidth during postcopy.
|
|
# Defaults to 0 (unlimited). In bytes per second.
|
|
# (Since 3.0)
|
|
# Since: 2.4
|
|
##
|
|
# TODO either fuse back into MigrationParameters, or make
|
|
# MigrationParameters members mandatory
|
|
{ 'struct': 'MigrateSetParameters',
|
|
'data': { '*compress-level': 'int',
|
|
'*compress-threads': 'int',
|
|
'*decompress-threads': 'int',
|
|
'*cpu-throttle-initial': 'int',
|
|
'*cpu-throttle-increment': 'int',
|
|
'*tls-creds': 'StrOrNull',
|
|
'*tls-hostname': 'StrOrNull',
|
|
'*max-bandwidth': 'int',
|
|
'*downtime-limit': 'int',
|
|
'*x-checkpoint-delay': 'int',
|
|
'*block-incremental': 'bool',
|
|
'*x-multifd-channels': 'int',
|
|
'*x-multifd-page-count': 'int',
|
|
'*xbzrle-cache-size': 'size',
|
|
'*max-postcopy-bandwidth': 'size' } }
|
|
|
|
##
|
|
# @migrate-set-parameters:
|
|
#
|
|
# Set various migration parameters.
|
|
#
|
|
# Since: 2.4
|
|
#
|
|
# Example:
|
|
#
|
|
# -> { "execute": "migrate-set-parameters" ,
|
|
# "arguments": { "compress-level": 1 } }
|
|
#
|
|
##
|
|
{ 'command': 'migrate-set-parameters', 'boxed': true,
|
|
'data': 'MigrateSetParameters' }
|
|
|
|
##
|
|
# @MigrationParameters:
|
|
#
|
|
# The optional members aren't actually optional.
|
|
#
|
|
# @compress-level: compression level
|
|
#
|
|
# @compress-threads: compression thread count
|
|
#
|
|
# @decompress-threads: decompression thread count
|
|
#
|
|
# @cpu-throttle-initial: Initial percentage of time guest cpus are
|
|
# throttled when migration auto-converge is activated.
|
|
# (Since 2.7)
|
|
#
|
|
# @cpu-throttle-increment: throttle percentage increase each time
|
|
# auto-converge detects that migration is not making
|
|
# progress. (Since 2.7)
|
|
#
|
|
# @tls-creds: ID of the 'tls-creds' object that provides credentials
|
|
# for establishing a TLS connection over the migration data
|
|
# channel. On the outgoing side of the migration, the credentials
|
|
# must be for a 'client' endpoint, while for the incoming side the
|
|
# credentials must be for a 'server' endpoint.
|
|
# An empty string means that QEMU will use plain text mode for
|
|
# migration, rather than TLS (Since 2.7)
|
|
# Note: 2.8 reports this by omitting tls-creds instead.
|
|
#
|
|
# @tls-hostname: hostname of the target host for the migration. This
|
|
# is required when using x509 based TLS credentials and the
|
|
# migration URI does not already include a hostname. For
|
|
# example if using fd: or exec: based migration, the
|
|
# hostname must be provided so that the server's x509
|
|
# certificate identity can be validated. (Since 2.7)
|
|
# An empty string means that QEMU will use the hostname
|
|
# associated with the migration URI, if any. (Since 2.9)
|
|
# Note: 2.8 reports this by omitting tls-hostname instead.
|
|
#
|
|
# @max-bandwidth: to set maximum speed for migration. maximum speed in
|
|
# bytes per second. (Since 2.8)
|
|
#
|
|
# @downtime-limit: set maximum tolerated downtime for migration. maximum
|
|
# downtime in milliseconds (Since 2.8)
|
|
#
|
|
# @x-checkpoint-delay: the delay time between two COLO checkpoints. (Since 2.8)
|
|
#
|
|
# @block-incremental: Affects how much storage is migrated when the
|
|
# block migration capability is enabled. When false, the entire
|
|
# storage backing chain is migrated into a flattened image at
|
|
# the destination; when true, only the active qcow2 layer is
|
|
# migrated and the destination must already have access to the
|
|
# same backing chain as was used on the source. (since 2.10)
|
|
#
|
|
# @x-multifd-channels: Number of channels used to migrate data in
|
|
# parallel. This is the same number that the
|
|
# number of sockets used for migration.
|
|
# The default value is 2 (since 2.11)
|
|
#
|
|
# @x-multifd-page-count: Number of pages sent together to a thread.
|
|
# The default value is 16 (since 2.11)
|
|
#
|
|
# @xbzrle-cache-size: cache size to be used by XBZRLE migration. It
|
|
# needs to be a multiple of the target page size
|
|
# and a power of 2
|
|
# (Since 2.11)
|
|
#
|
|
# @max-postcopy-bandwidth: Background transfer bandwidth during postcopy.
|
|
# Defaults to 0 (unlimited). In bytes per second.
|
|
# (Since 3.0)
|
|
# Since: 2.4
|
|
##
|
|
{ 'struct': 'MigrationParameters',
|
|
'data': { '*compress-level': 'uint8',
|
|
'*compress-threads': 'uint8',
|
|
'*decompress-threads': 'uint8',
|
|
'*cpu-throttle-initial': 'uint8',
|
|
'*cpu-throttle-increment': 'uint8',
|
|
'*tls-creds': 'str',
|
|
'*tls-hostname': 'str',
|
|
'*max-bandwidth': 'size',
|
|
'*downtime-limit': 'uint64',
|
|
'*x-checkpoint-delay': 'uint32',
|
|
'*block-incremental': 'bool' ,
|
|
'*x-multifd-channels': 'uint8',
|
|
'*x-multifd-page-count': 'uint32',
|
|
'*xbzrle-cache-size': 'size',
|
|
'*max-postcopy-bandwidth': 'size' } }
|
|
|
|
##
|
|
# @query-migrate-parameters:
|
|
#
|
|
# Returns information about the current migration parameters
|
|
#
|
|
# Returns: @MigrationParameters
|
|
#
|
|
# Since: 2.4
|
|
#
|
|
# Example:
|
|
#
|
|
# -> { "execute": "query-migrate-parameters" }
|
|
# <- { "return": {
|
|
# "decompress-threads": 2,
|
|
# "cpu-throttle-increment": 10,
|
|
# "compress-threads": 8,
|
|
# "compress-level": 1,
|
|
# "cpu-throttle-initial": 20,
|
|
# "max-bandwidth": 33554432,
|
|
# "downtime-limit": 300
|
|
# }
|
|
# }
|
|
#
|
|
##
|
|
{ 'command': 'query-migrate-parameters',
|
|
'returns': 'MigrationParameters' }
|
|
|
|
##
|
|
# @client_migrate_info:
|
|
#
|
|
# Set migration information for remote display. This makes the server
|
|
# ask the client to automatically reconnect using the new parameters
|
|
# once migration finished successfully. Only implemented for SPICE.
|
|
#
|
|
# @protocol: must be "spice"
|
|
# @hostname: migration target hostname
|
|
# @port: spice tcp port for plaintext channels
|
|
# @tls-port: spice tcp port for tls-secured channels
|
|
# @cert-subject: server certificate subject
|
|
#
|
|
# Since: 0.14.0
|
|
#
|
|
# Example:
|
|
#
|
|
# -> { "execute": "client_migrate_info",
|
|
# "arguments": { "protocol": "spice",
|
|
# "hostname": "virt42.lab.kraxel.org",
|
|
# "port": 1234 } }
|
|
# <- { "return": {} }
|
|
#
|
|
##
|
|
{ 'command': 'client_migrate_info',
|
|
'data': { 'protocol': 'str', 'hostname': 'str', '*port': 'int',
|
|
'*tls-port': 'int', '*cert-subject': 'str' } }
|
|
|
|
##
|
|
# @migrate-start-postcopy:
|
|
#
|
|
# Followup to a migration command to switch the migration to postcopy mode.
|
|
# The postcopy-ram capability must be set on both source and destination
|
|
# before the original migration command.
|
|
#
|
|
# Since: 2.5
|
|
#
|
|
# Example:
|
|
#
|
|
# -> { "execute": "migrate-start-postcopy" }
|
|
# <- { "return": {} }
|
|
#
|
|
##
|
|
{ 'command': 'migrate-start-postcopy' }
|
|
|
|
##
|
|
# @MIGRATION:
|
|
#
|
|
# Emitted when a migration event happens
|
|
#
|
|
# @status: @MigrationStatus describing the current migration status.
|
|
#
|
|
# Since: 2.4
|
|
#
|
|
# Example:
|
|
#
|
|
# <- {"timestamp": {"seconds": 1432121972, "microseconds": 744001},
|
|
# "event": "MIGRATION",
|
|
# "data": {"status": "completed"} }
|
|
#
|
|
##
|
|
{ 'event': 'MIGRATION',
|
|
'data': {'status': 'MigrationStatus'}}
|
|
|
|
##
|
|
# @MIGRATION_PASS:
|
|
#
|
|
# Emitted from the source side of a migration at the start of each pass
|
|
# (when it syncs the dirty bitmap)
|
|
#
|
|
# @pass: An incrementing count (starting at 1 on the first pass)
|
|
#
|
|
# Since: 2.6
|
|
#
|
|
# Example:
|
|
#
|
|
# { "timestamp": {"seconds": 1449669631, "microseconds": 239225},
|
|
# "event": "MIGRATION_PASS", "data": {"pass": 2} }
|
|
#
|
|
##
|
|
{ 'event': 'MIGRATION_PASS',
|
|
'data': { 'pass': 'int' } }
|
|
|
|
##
|
|
# @COLOMessage:
|
|
#
|
|
# The message transmission between Primary side and Secondary side.
|
|
#
|
|
# @checkpoint-ready: Secondary VM (SVM) is ready for checkpointing
|
|
#
|
|
# @checkpoint-request: Primary VM (PVM) tells SVM to prepare for checkpointing
|
|
#
|
|
# @checkpoint-reply: SVM gets PVM's checkpoint request
|
|
#
|
|
# @vmstate-send: VM's state will be sent by PVM.
|
|
#
|
|
# @vmstate-size: The total size of VMstate.
|
|
#
|
|
# @vmstate-received: VM's state has been received by SVM.
|
|
#
|
|
# @vmstate-loaded: VM's state has been loaded by SVM.
|
|
#
|
|
# Since: 2.8
|
|
##
|
|
{ 'enum': 'COLOMessage',
|
|
'data': [ 'checkpoint-ready', 'checkpoint-request', 'checkpoint-reply',
|
|
'vmstate-send', 'vmstate-size', 'vmstate-received',
|
|
'vmstate-loaded' ] }
|
|
|
|
##
|
|
# @COLOMode:
|
|
#
|
|
# The colo mode
|
|
#
|
|
# @unknown: unknown mode
|
|
#
|
|
# @primary: master side
|
|
#
|
|
# @secondary: slave side
|
|
#
|
|
# Since: 2.8
|
|
##
|
|
{ 'enum': 'COLOMode',
|
|
'data': [ 'unknown', 'primary', 'secondary'] }
|
|
|
|
##
|
|
# @FailoverStatus:
|
|
#
|
|
# An enumeration of COLO failover status
|
|
#
|
|
# @none: no failover has ever happened
|
|
#
|
|
# @require: got failover requirement but not handled
|
|
#
|
|
# @active: in the process of doing failover
|
|
#
|
|
# @completed: finish the process of failover
|
|
#
|
|
# @relaunch: restart the failover process, from 'none' -> 'completed' (Since 2.9)
|
|
#
|
|
# Since: 2.8
|
|
##
|
|
{ 'enum': 'FailoverStatus',
|
|
'data': [ 'none', 'require', 'active', 'completed', 'relaunch' ] }
|
|
|
|
##
|
|
# @x-colo-lost-heartbeat:
|
|
#
|
|
# Tell qemu that heartbeat is lost, request it to do takeover procedures.
|
|
# If this command is sent to the PVM, the Primary side will exit COLO mode.
|
|
# If sent to the Secondary, the Secondary side will run failover work,
|
|
# then takes over server operation to become the service VM.
|
|
#
|
|
# Since: 2.8
|
|
#
|
|
# Example:
|
|
#
|
|
# -> { "execute": "x-colo-lost-heartbeat" }
|
|
# <- { "return": {} }
|
|
#
|
|
##
|
|
{ 'command': 'x-colo-lost-heartbeat' }
|
|
|
|
##
|
|
# @migrate_cancel:
|
|
#
|
|
# Cancel the current executing migration process.
|
|
#
|
|
# Returns: nothing on success
|
|
#
|
|
# Notes: This command succeeds even if there is no migration process running.
|
|
#
|
|
# Since: 0.14.0
|
|
#
|
|
# Example:
|
|
#
|
|
# -> { "execute": "migrate_cancel" }
|
|
# <- { "return": {} }
|
|
#
|
|
##
|
|
{ 'command': 'migrate_cancel' }
|
|
|
|
##
|
|
# @migrate-continue:
|
|
#
|
|
# Continue migration when it's in a paused state.
|
|
#
|
|
# @state: The state the migration is currently expected to be in
|
|
#
|
|
# Returns: nothing on success
|
|
# Since: 2.11
|
|
# Example:
|
|
#
|
|
# -> { "execute": "migrate-continue" , "arguments":
|
|
# { "state": "pre-switchover" } }
|
|
# <- { "return": {} }
|
|
##
|
|
{ 'command': 'migrate-continue', 'data': {'state': 'MigrationStatus'} }
|
|
|
|
##
|
|
# @migrate_set_downtime:
|
|
#
|
|
# Set maximum tolerated downtime for migration.
|
|
#
|
|
# @value: maximum downtime in seconds
|
|
#
|
|
# Returns: nothing on success
|
|
#
|
|
# Notes: This command is deprecated in favor of 'migrate-set-parameters'
|
|
#
|
|
# Since: 0.14.0
|
|
#
|
|
# Example:
|
|
#
|
|
# -> { "execute": "migrate_set_downtime", "arguments": { "value": 0.1 } }
|
|
# <- { "return": {} }
|
|
#
|
|
##
|
|
{ 'command': 'migrate_set_downtime', 'data': {'value': 'number'} }
|
|
|
|
##
|
|
# @migrate_set_speed:
|
|
#
|
|
# Set maximum speed for migration.
|
|
#
|
|
# @value: maximum speed in bytes per second.
|
|
#
|
|
# Returns: nothing on success
|
|
#
|
|
# Notes: This command is deprecated in favor of 'migrate-set-parameters'
|
|
#
|
|
# Since: 0.14.0
|
|
#
|
|
# Example:
|
|
#
|
|
# -> { "execute": "migrate_set_speed", "arguments": { "value": 1024 } }
|
|
# <- { "return": {} }
|
|
#
|
|
##
|
|
{ 'command': 'migrate_set_speed', 'data': {'value': 'int'} }
|
|
|
|
##
|
|
# @migrate-set-cache-size:
|
|
#
|
|
# Set cache size to be used by XBZRLE migration
|
|
#
|
|
# @value: cache size in bytes
|
|
#
|
|
# The size will be rounded down to the nearest power of 2.
|
|
# The cache size can be modified before and during ongoing migration
|
|
#
|
|
# Returns: nothing on success
|
|
#
|
|
# Notes: This command is deprecated in favor of 'migrate-set-parameters'
|
|
#
|
|
# Since: 1.2
|
|
#
|
|
# Example:
|
|
#
|
|
# -> { "execute": "migrate-set-cache-size",
|
|
# "arguments": { "value": 536870912 } }
|
|
# <- { "return": {} }
|
|
#
|
|
##
|
|
{ 'command': 'migrate-set-cache-size', 'data': {'value': 'int'} }
|
|
|
|
##
|
|
# @query-migrate-cache-size:
|
|
#
|
|
# Query migration XBZRLE cache size
|
|
#
|
|
# Returns: XBZRLE cache size in bytes
|
|
#
|
|
# Notes: This command is deprecated in favor of 'query-migrate-parameters'
|
|
#
|
|
# Since: 1.2
|
|
#
|
|
# Example:
|
|
#
|
|
# -> { "execute": "query-migrate-cache-size" }
|
|
# <- { "return": 67108864 }
|
|
#
|
|
##
|
|
{ 'command': 'query-migrate-cache-size', 'returns': 'int' }
|
|
|
|
##
|
|
# @migrate:
|
|
#
|
|
# Migrates the current running guest to another Virtual Machine.
|
|
#
|
|
# @uri: the Uniform Resource Identifier of the destination VM
|
|
#
|
|
# @blk: do block migration (full disk copy)
|
|
#
|
|
# @inc: incremental disk copy migration
|
|
#
|
|
# @detach: this argument exists only for compatibility reasons and
|
|
# is ignored by QEMU
|
|
#
|
|
# @resume: resume one paused migration, default "off". (since 3.0)
|
|
#
|
|
# Returns: nothing on success
|
|
#
|
|
# Since: 0.14.0
|
|
#
|
|
# Notes:
|
|
#
|
|
# 1. The 'query-migrate' command should be used to check migration's progress
|
|
# and final result (this information is provided by the 'status' member)
|
|
#
|
|
# 2. All boolean arguments default to false
|
|
#
|
|
# 3. The user Monitor's "detach" argument is invalid in QMP and should not
|
|
# be used
|
|
#
|
|
# Example:
|
|
#
|
|
# -> { "execute": "migrate", "arguments": { "uri": "tcp:0:4446" } }
|
|
# <- { "return": {} }
|
|
#
|
|
##
|
|
{ 'command': 'migrate',
|
|
'data': {'uri': 'str', '*blk': 'bool', '*inc': 'bool',
|
|
'*detach': 'bool', '*resume': 'bool' } }
|
|
|
|
##
|
|
# @migrate-incoming:
|
|
#
|
|
# Start an incoming migration, the qemu must have been started
|
|
# with -incoming defer
|
|
#
|
|
# @uri: The Uniform Resource Identifier identifying the source or
|
|
# address to listen on
|
|
#
|
|
# Returns: nothing on success
|
|
#
|
|
# Since: 2.3
|
|
#
|
|
# Notes:
|
|
#
|
|
# 1. It's a bad idea to use a string for the uri, but it needs to stay
|
|
# compatible with -incoming and the format of the uri is already exposed
|
|
# above libvirt.
|
|
#
|
|
# 2. QEMU must be started with -incoming defer to allow migrate-incoming to
|
|
# be used.
|
|
#
|
|
# 3. The uri format is the same as for -incoming
|
|
#
|
|
# Example:
|
|
#
|
|
# -> { "execute": "migrate-incoming",
|
|
# "arguments": { "uri": "tcp::4446" } }
|
|
# <- { "return": {} }
|
|
#
|
|
##
|
|
{ 'command': 'migrate-incoming', 'data': {'uri': 'str' } }
|
|
|
|
##
|
|
# @xen-save-devices-state:
|
|
#
|
|
# Save the state of all devices to file. The RAM and the block devices
|
|
# of the VM are not saved by this command.
|
|
#
|
|
# @filename: the file to save the state of the devices to as binary
|
|
# data. See xen-save-devices-state.txt for a description of the binary
|
|
# format.
|
|
#
|
|
# @live: Optional argument to ask QEMU to treat this command as part of a live
|
|
# migration. Default to true. (since 2.11)
|
|
#
|
|
# Returns: Nothing on success
|
|
#
|
|
# Since: 1.1
|
|
#
|
|
# Example:
|
|
#
|
|
# -> { "execute": "xen-save-devices-state",
|
|
# "arguments": { "filename": "/tmp/save" } }
|
|
# <- { "return": {} }
|
|
#
|
|
##
|
|
{ 'command': 'xen-save-devices-state',
|
|
'data': {'filename': 'str', '*live':'bool' } }
|
|
|
|
##
|
|
# @xen-set-replication:
|
|
#
|
|
# Enable or disable replication.
|
|
#
|
|
# @enable: true to enable, false to disable.
|
|
#
|
|
# @primary: true for primary or false for secondary.
|
|
#
|
|
# @failover: true to do failover, false to stop. but cannot be
|
|
# specified if 'enable' is true. default value is false.
|
|
#
|
|
# Returns: nothing.
|
|
#
|
|
# Example:
|
|
#
|
|
# -> { "execute": "xen-set-replication",
|
|
# "arguments": {"enable": true, "primary": false} }
|
|
# <- { "return": {} }
|
|
#
|
|
# Since: 2.9
|
|
##
|
|
{ 'command': 'xen-set-replication',
|
|
'data': { 'enable': 'bool', 'primary': 'bool', '*failover' : 'bool' } }
|
|
|
|
##
|
|
# @ReplicationStatus:
|
|
#
|
|
# The result format for 'query-xen-replication-status'.
|
|
#
|
|
# @error: true if an error happened, false if replication is normal.
|
|
#
|
|
# @desc: the human readable error description string, when
|
|
# @error is 'true'.
|
|
#
|
|
# Since: 2.9
|
|
##
|
|
{ 'struct': 'ReplicationStatus',
|
|
'data': { 'error': 'bool', '*desc': 'str' } }
|
|
|
|
##
|
|
# @query-xen-replication-status:
|
|
#
|
|
# Query replication status while the vm is running.
|
|
#
|
|
# Returns: A @ReplicationResult object showing the status.
|
|
#
|
|
# Example:
|
|
#
|
|
# -> { "execute": "query-xen-replication-status" }
|
|
# <- { "return": { "error": false } }
|
|
#
|
|
# Since: 2.9
|
|
##
|
|
{ 'command': 'query-xen-replication-status',
|
|
'returns': 'ReplicationStatus' }
|
|
|
|
##
|
|
# @xen-colo-do-checkpoint:
|
|
#
|
|
# Xen uses this command to notify replication to trigger a checkpoint.
|
|
#
|
|
# Returns: nothing.
|
|
#
|
|
# Example:
|
|
#
|
|
# -> { "execute": "xen-colo-do-checkpoint" }
|
|
# <- { "return": {} }
|
|
#
|
|
# Since: 2.9
|
|
##
|
|
{ 'command': 'xen-colo-do-checkpoint' }
|
|
|
|
##
|
|
# @migrate-recover:
|
|
#
|
|
# Provide a recovery migration stream URI.
|
|
#
|
|
# @uri: the URI to be used for the recovery of migration stream.
|
|
#
|
|
# Returns: nothing.
|
|
#
|
|
# Example:
|
|
#
|
|
# -> { "execute": "migrate-recover",
|
|
# "arguments": { "uri": "tcp:192.168.1.200:12345" } }
|
|
# <- { "return": {} }
|
|
#
|
|
# Since: 3.0
|
|
##
|
|
{ 'command': 'migrate-recover', 'data': { 'uri': 'str' },
|
|
'allow-oob': true }
|
|
|
|
##
|
|
# @migrate-pause:
|
|
#
|
|
# Pause a migration. Currently it only supports postcopy.
|
|
#
|
|
# Returns: nothing.
|
|
#
|
|
# Example:
|
|
#
|
|
# -> { "execute": "migrate-pause" }
|
|
# <- { "return": {} }
|
|
#
|
|
# Since: 3.0
|
|
##
|
|
{ 'command': 'migrate-pause', 'allow-oob': true }
|