We are going to implement local-migration feature: some devices will be
able to transfer open file descriptors through migration stream (which
must UNIX domain socket for that purpose).  This allows to transfer the
whole backend state without reconnecting and restarting the backend
service. For example, virtio-net will migrate its attached TAP netdev,
together with its connected file descriptors.

In this commit we introduce a migration parameter, which enables
the feature for supporting devices (no one at the moment).

Signed-off-by: Vladimir Sementsov-Ogievskiy <vsementsov@yandex-team.ru>
---
 include/migration/misc.h |  2 ++
 migration/options.c      | 18 +++++++++++++++++-
 qapi/migration.json      | 14 ++++++++++++--
 3 files changed, 31 insertions(+), 3 deletions(-)

diff --git a/include/migration/misc.h b/include/migration/misc.h
index e26d418a6e..f9b6a67129 100644
--- a/include/migration/misc.h
+++ b/include/migration/misc.h
@@ -152,4 +152,6 @@ bool multifd_device_state_save_thread_should_exit(void);
 void multifd_abort_device_state_save_threads(void);
 bool multifd_join_device_state_save_threads(void);
 
+bool migrate_local(void);
+
 #endif
diff --git a/migration/options.c b/migration/options.c
index 1ffe85a2d8..92144da3ac 100644
--- a/migration/options.c
+++ b/migration/options.c
@@ -13,6 +13,7 @@
 
 #include "qemu/osdep.h"
 #include "qemu/error-report.h"
+#include "qapi/util.h"
 #include "exec/target_page.h"
 #include "qapi/clone-visitor.h"
 #include "qapi/error.h"
@@ -24,6 +25,7 @@
 #include "migration/colo.h"
 #include "migration/cpr.h"
 #include "migration/misc.h"
+#include "migration/options.h"
 #include "migration.h"
 #include "migration-stats.h"
 #include "qemu-file.h"
@@ -336,6 +338,12 @@ bool migrate_mapped_ram(void)
     return s->capabilities[MIGRATION_CAPABILITY_MAPPED_RAM];
 }
 
+bool migrate_local(void)
+{
+    MigrationState *s = migrate_get_current();
+    return s->parameters.local;
+}
+
 bool migrate_ignore_shared(void)
 {
     MigrationState *s = migrate_get_current();
@@ -1047,7 +1055,7 @@ static void migrate_mark_all_params_present(MigrationParameters *p)
         &p->has_announce_step, &p->has_block_bitmap_mapping,
         &p->has_x_vcpu_dirty_limit_period, &p->has_vcpu_dirty_limit,
         &p->has_mode, &p->has_zero_page_detection, &p->has_direct_io,
-        &p->has_cpr_exec_command,
+        &p->has_cpr_exec_command, &p->has_local,
     };
 
     len = ARRAY_SIZE(has_fields);
@@ -1386,6 +1394,10 @@ static void migrate_params_test_apply(MigrationParameters *params,
     if (params->has_cpr_exec_command) {
         dest->cpr_exec_command = params->cpr_exec_command;
     }
+
+    if (params->has_local) {
+        dest->local = params->local;
+    }
 }
 
 static void migrate_params_apply(MigrationParameters *params)
@@ -1514,6 +1526,10 @@ static void migrate_params_apply(MigrationParameters *params)
         s->parameters.cpr_exec_command =
             QAPI_CLONE(strList, params->cpr_exec_command);
     }
+
+    if (params->has_local) {
+        s->parameters.local = params->local;
+    }
 }
 
 void qmp_migrate_set_parameters(MigrationParameters *params, Error **errp)
diff --git a/qapi/migration.json b/qapi/migration.json
index f925e5541b..f110bd8399 100644
--- a/qapi/migration.json
+++ b/qapi/migration.json
@@ -828,7 +828,8 @@
            'mode',
            'zero-page-detection',
            'direct-io',
-           'cpr-exec-command'] }
+           'cpr-exec-command',
+           'local'] }
 
 ##
 # @migrate-set-parameters:
@@ -1004,6 +1005,14 @@
 #     is @cpr-exec.  The first list element is the program's filename,
 #     the remainder its arguments.  (Since 10.2)
 #
+# @local: Enable local migration feature for devices that support
+#     it.  The feature is for local migation only and rely on the
+#     channel support for passing file desciptors (it must be a UNIX
+#     socket).  In general that means that backend state and its file
+#     descriptors are passed to the destination in the migration
+#     channel.  Individual devices declare the support for local
+#     migration by per-device local-migration option.  (Since 11.0)
+#
 # Features:
 #
 # @unstable: Members @x-checkpoint-delay and
@@ -1043,7 +1052,8 @@
             '*mode': 'MigMode',
             '*zero-page-detection': 'ZeroPageDetection',
             '*direct-io': 'bool',
-            '*cpr-exec-command': [ 'str' ]} }
+            '*cpr-exec-command': [ 'str' ],
+            '*local': 'bool' } }
 
 ##
 # @query-migrate-parameters:
-- 
2.52.0

On Thu, Feb 19, 2026 at 02:55:24PM +0300, Vladimir Sementsov-Ogievskiy wrote:
> We are going to implement local-migration feature: some devices will be
> able to transfer open file descriptors through migration stream (which
> must UNIX domain socket for that purpose).  This allows to transfer the
> whole backend state without reconnecting and restarting the backend
> service. For example, virtio-net will migrate its attached TAP netdev,
> together with its connected file descriptors.
> 
> In this commit we introduce a migration parameter, which enables
> the feature for supporting devices (no one at the moment).
> 
> Signed-off-by: Vladimir Sementsov-Ogievskiy <vsementsov@yandex-team.ru>

Reviewed-by: Peter Xu <peterx@redhat.com>

PS: one nitpick is maybe we don't need to spell out the per-device option
in the doc of "local", it also doesn't need to be called "local-migration"
on every device if it will be presnet.. no strong feelings.

Thanks,

-- 
Peter Xu

On 20.02.26 00:43, Peter Xu wrote:
> On Thu, Feb 19, 2026 at 02:55:24PM +0300, Vladimir Sementsov-Ogievskiy wrote:
>> We are going to implement local-migration feature: some devices will be
>> able to transfer open file descriptors through migration stream (which
>> must UNIX domain socket for that purpose).  This allows to transfer the
>> whole backend state without reconnecting and restarting the backend
>> service. For example, virtio-net will migrate its attached TAP netdev,
>> together with its connected file descriptors.
>>
>> In this commit we introduce a migration parameter, which enables
>> the feature for supporting devices (no one at the moment).
>>
>> Signed-off-by: Vladimir Sementsov-Ogievskiy <vsementsov@yandex-team.ru>
> 
> Reviewed-by: Peter Xu <peterx@redhat.com>
> 
> PS: one nitpick is maybe we don't need to spell out the per-device option
> in the doc of "local", it also doesn't need to be called "local-migration"
> on every device if it will be presnet.. no strong feelings.
> 

I thought about it.. But couldn't come up with a more generic phrase.
And I think it's bad to omit the fact that the parameter doesn't
automatically enable the feature without some flag on device side.

+#     channel.  Individual devices declare the support for local
+#     migration by per-device local-migration option.  (Since 11.0)

Hmm. After merging at least virtio-net/TAP migration we can write:

     In general devices may have an option (like local-migration
     for virtio-net) which in conjunction with "local" set to true
     enables the local-migration feature for that device.

And to be prepared for it now:

     In general devices may have an option which in conjunction with
     "local" set to true enables the local-migration feature for that
     device.

-- 
Best regards,
Vladimir

On Fri, Feb 20, 2026 at 10:56:50AM +0300, Vladimir Sementsov-Ogievskiy wrote:
> On 20.02.26 00:43, Peter Xu wrote:
> > On Thu, Feb 19, 2026 at 02:55:24PM +0300, Vladimir Sementsov-Ogievskiy wrote:
> > > We are going to implement local-migration feature: some devices will be
> > > able to transfer open file descriptors through migration stream (which
> > > must UNIX domain socket for that purpose).  This allows to transfer the
> > > whole backend state without reconnecting and restarting the backend
> > > service. For example, virtio-net will migrate its attached TAP netdev,
> > > together with its connected file descriptors.
> > > 
> > > In this commit we introduce a migration parameter, which enables
> > > the feature for supporting devices (no one at the moment).
> > > 
> > > Signed-off-by: Vladimir Sementsov-Ogievskiy <vsementsov@yandex-team.ru>
> > 
> > Reviewed-by: Peter Xu <peterx@redhat.com>
> > 
> > PS: one nitpick is maybe we don't need to spell out the per-device option
> > in the doc of "local", it also doesn't need to be called "local-migration"
> > on every device if it will be presnet.. no strong feelings.
> > 
> 
> I thought about it.. But couldn't come up with a more generic phrase.
> And I think it's bad to omit the fact that the parameter doesn't
> automatically enable the feature without some flag on device side.
> 
> +#     channel.  Individual devices declare the support for local
> +#     migration by per-device local-migration option.  (Since 11.0)
> 
> Hmm. After merging at least virtio-net/TAP migration we can write:
> 
>     In general devices may have an option (like local-migration
>     for virtio-net) which in conjunction with "local" set to true
>     enables the local-migration feature for that device.
> 
> And to be prepared for it now:
> 
>     In general devices may have an option which in conjunction with
>     "local" set to true enables the local-migration feature for that
>     device.

Yep, this looks good.  The per-device option is not required IMHO, so "may
have" is accurate to me.

For example, when we introduce a completely new device, it can support
migrate_is_local() since the first day, then it doesn't need the per device
knob.

OTOH, the global "local" parameter is needed only because we want a promise
from the user that this is a local migration, instead of relying on URI
being unix sockets.  One example is in kubevirt AFAIU we use unix sockets
even for remote migrations (where the unix socket will only be used as a
proxy to route things outside of the container).  Hence "local" deduces
"unix sockets", not vice versa.

Thanks,

-- 
Peter Xu