Re: More doc updates needed for new migrate argument @channels

Re: More doc updates needed for new migrate argument @channels

[Peter Xu]

On Fri, May 03, 2024 at 09:13:27AM -0400, Steven Sistare wrote:
> On 5/3/2024 8:49 AM, Fabiano Rosas wrote:
> > Markus Armbruster <armbru@redhat.com> writes:
> > 
> > > Commit 074dbce5fcce (migration: New migrate and migrate-incoming
> > > argument 'channels') and its fixup commit 57fd4b4e1075 made command
> > > migrate argument @uri optional and mutually exclusive with @channels.
> > > 
> > > But documentation still talks about "the migration URI" in several
> > > places.
> > > 
> > > * MigrationCapability @mapped-ram:
> > > 
> > >      # @mapped-ram: Migrate using fixed offsets in the migration file for
> > >      #     each RAM page.  Requires a migration URI that supports seeking,
> > >      #     such as a file.  (since 9.0)
> > > 
> > >    I guess it requires the migration destination (@uri or @channels) to
> > >    support seeking.
> > 
> > This is ambiguous. The migration destination is usually the VM at the
> > end of the migration, not the medium to where the migration stream is
> > written to.
> > 
> > One option is to just add the mention to channel all around: "Requires a
> > migration URI or channel that supports seeking".
> > 
> > > 
> > > * MigMode @cpr-reboot:
> > > 
> > >      # @cpr-reboot: The migrate command stops the VM and saves state to the
> > >      #     URI.  After quitting QEMU, the user resumes by running QEMU
> > >      #     -incoming.
> > >      #
> > >      #     This mode allows the user to quit QEMU, optionally update and
> > >      #     reboot the OS, and restart QEMU.  If the user reboots, the URI
> > >      #     must persist across the reboot, such as by using a file.
> > > 
> > >    I guess this saves to the migration destination (@uri or @channels).
> > > 
> > > * Migration Parameter @tls-hostname and its two buddies
> > > 
> > >      # @tls-hostname: migration target's hostname for validating the
> > >      #     server's x509 certificate identity.  If empty, QEMU will use the
> > >      #     hostname from the migration URI, if any.  A non-empty value is
> > >      #     required when using x509 based TLS credentials and the migration
> > >      #     URI does not include a hostname, such as fd: or exec: based
> > >      #     migration.  (Since 2.7)
> > >      #
> > >      #     Note: empty value works only since 2.9.
> > > 
> > >    What's the default when we're using @channels instead of @uri?
> > 
> > The same, both URI and channels get put in the same structure before
> > taking the hostname.
> > 
> > > 
> > > * migrate-recover
> > > 
> > >      ##
> > >      # @migrate-recover:
> > >      #
> > >      # Provide a recovery migration stream URI.
> > >      #
> > >      # @uri: the URI to be used for the recovery of migration stream.
> > > 
> > >    Should this command be extended to accept @channels?
> > 
> > Yes.
> > 
> > > 
> > > * docs/devel/migration/CPR.rst
> > > 
> > >    Didn't look closely.  Let's discuss the others first, then come back
> > >    to this one.
> > > 
> > > * HMP migrate
> > > 
> > >    Fine, because this still only supports URI syntax.
> > > 
> > > * CLI option "-incoming defer"
> > > 
> > >          "-incoming defer\n" \
> > >          "                wait for the URI to be specified via migrate_incoming\n",
> > > 
> > >    and
> > > 
> > >      ``-incoming defer``
> > >          Wait for the URI to be specified via migrate\_incoming. The monitor
> > >          can be used to change settings (such as migration parameters) prior
> > >          to issuing the migrate\_incoming to allow the migration to begin.
> > > 
> > >    I figure we should call it "the migration source" instead of "the URI"
> > >    here.
> > 
> > I think it's worse. We need a proper way to refer exclusively to "the
> > thing that the user passes as an argument to the migrate command".
> 
> Agreed.  My thoughts:
> 
> "migration URI" -> "migration URI/channel"
> or
> "migration URI" -> "migration stream"

"stream" might imply more on the protocol itself to me, e.g. how the
migration headers are defined, rather than the entity / fabric we use to
send the data stream?

Maybe we can simply do s/URI/channel/? As "channel" can also imply the URI
in this case as yet another (old) format to specify the migration channels.
It's like we always use QIOChannels underneath whatever way we specify the
channels (either URI or the new "channels" API).

I also copied qemu-devel starting from now.

Thanks,

-- 
Peter Xu

Re: More doc updates needed for new migrate argument @channels

[Fabiano Rosas]

Peter Xu <peterx@redhat.com> writes:

> On Fri, May 03, 2024 at 09:13:27AM -0400, Steven Sistare wrote:
>> On 5/3/2024 8:49 AM, Fabiano Rosas wrote:
>> > Markus Armbruster <armbru@redhat.com> writes:
>> > 
>> > > Commit 074dbce5fcce (migration: New migrate and migrate-incoming
>> > > argument 'channels') and its fixup commit 57fd4b4e1075 made command
>> > > migrate argument @uri optional and mutually exclusive with @channels.
>> > > 
>> > > But documentation still talks about "the migration URI" in several
>> > > places.
>> > > 
>> > > * MigrationCapability @mapped-ram:
>> > > 
>> > >      # @mapped-ram: Migrate using fixed offsets in the migration file for
>> > >      #     each RAM page.  Requires a migration URI that supports seeking,
>> > >      #     such as a file.  (since 9.0)
>> > > 
>> > >    I guess it requires the migration destination (@uri or @channels) to
>> > >    support seeking.
>> > 
>> > This is ambiguous. The migration destination is usually the VM at the
>> > end of the migration, not the medium to where the migration stream is
>> > written to.
>> > 
>> > One option is to just add the mention to channel all around: "Requires a
>> > migration URI or channel that supports seeking".
>> > 
>> > > 
>> > > * MigMode @cpr-reboot:
>> > > 
>> > >      # @cpr-reboot: The migrate command stops the VM and saves state to the
>> > >      #     URI.  After quitting QEMU, the user resumes by running QEMU
>> > >      #     -incoming.
>> > >      #
>> > >      #     This mode allows the user to quit QEMU, optionally update and
>> > >      #     reboot the OS, and restart QEMU.  If the user reboots, the URI
>> > >      #     must persist across the reboot, such as by using a file.
>> > > 
>> > >    I guess this saves to the migration destination (@uri or @channels).
>> > > 
>> > > * Migration Parameter @tls-hostname and its two buddies
>> > > 
>> > >      # @tls-hostname: migration target's hostname for validating the
>> > >      #     server's x509 certificate identity.  If empty, QEMU will use the
>> > >      #     hostname from the migration URI, if any.  A non-empty value is
>> > >      #     required when using x509 based TLS credentials and the migration
>> > >      #     URI does not include a hostname, such as fd: or exec: based
>> > >      #     migration.  (Since 2.7)
>> > >      #
>> > >      #     Note: empty value works only since 2.9.
>> > > 
>> > >    What's the default when we're using @channels instead of @uri?
>> > 
>> > The same, both URI and channels get put in the same structure before
>> > taking the hostname.
>> > 
>> > > 
>> > > * migrate-recover
>> > > 
>> > >      ##
>> > >      # @migrate-recover:
>> > >      #
>> > >      # Provide a recovery migration stream URI.
>> > >      #
>> > >      # @uri: the URI to be used for the recovery of migration stream.
>> > > 
>> > >    Should this command be extended to accept @channels?
>> > 
>> > Yes.
>> > 
>> > > 
>> > > * docs/devel/migration/CPR.rst
>> > > 
>> > >    Didn't look closely.  Let's discuss the others first, then come back
>> > >    to this one.
>> > > 
>> > > * HMP migrate
>> > > 
>> > >    Fine, because this still only supports URI syntax.
>> > > 
>> > > * CLI option "-incoming defer"
>> > > 
>> > >          "-incoming defer\n" \
>> > >          "                wait for the URI to be specified via migrate_incoming\n",
>> > > 
>> > >    and
>> > > 
>> > >      ``-incoming defer``
>> > >          Wait for the URI to be specified via migrate\_incoming. The monitor
>> > >          can be used to change settings (such as migration parameters) prior
>> > >          to issuing the migrate\_incoming to allow the migration to begin.
>> > > 
>> > >    I figure we should call it "the migration source" instead of "the URI"
>> > >    here.
>> > 
>> > I think it's worse. We need a proper way to refer exclusively to "the
>> > thing that the user passes as an argument to the migrate command".
>> 
>> Agreed.  My thoughts:
>> 
>> "migration URI" -> "migration URI/channel"
>> or
>> "migration URI" -> "migration stream"
>
> "stream" might imply more on the protocol itself to me, e.g. how the
> migration headers are defined, rather than the entity / fabric we use to
> send the data stream?
>
> Maybe we can simply do s/URI/channel/? As "channel" can also imply the URI
> in this case as yet another (old) format to specify the migration channels.
> It's like we always use QIOChannels underneath whatever way we specify the
> channels (either URI or the new "channels" API).

I'm fine with just "channel". "URI/channel" is ok as well.

Do we intend to deprecate the URI usage via QMP? Or are going to support
the two ways indefinitely? Keep URI for HMP-only?

If the MigrationAddress API ends up being the only one, then maybe it
makes sense to stop using URI all over.

>
> I also copied qemu-devel starting from now.
>
> Thanks,

Re: More doc updates needed for new migrate argument @channels

[Markus Armbruster]

Peter Xu <peterx@redhat.com> writes:

[...]

> I also copied qemu-devel starting from now.

My bad, I messed that up!

Re: More doc updates needed for new migrate argument @channels

[Peter Xu]

On Mon, May 06, 2024 at 06:58:00AM +0200, Markus Armbruster wrote:
> Peter Xu <peterx@redhat.com> writes:
> 
> [...]
> 
> > I also copied qemu-devel starting from now.
> 
> My bad, I messed that up!

Het, do you want to send a patch?

Thanks,

-- 
Peter Xu

Re: More doc updates needed for new migrate argument @channels

[Het Gala]

On 06/05/24 9:10 pm, Peter Xu wrote:
> !-------------------------------------------------------------------|
>    CAUTION: External Email
>
> |-------------------------------------------------------------------!
>
> On Mon, May 06, 2024 at 06:58:00AM +0200, Markus Armbruster wrote:
>> Peter Xu <peterx@redhat.com> writes:
>>
>> [...]
>>
>>> I also copied qemu-devel starting from now.
>> My bad, I messed that up!
> Het, do you want to send a patch?
>
> Thanks,
Hi Fabiano, Peter. Sorry for joining late to this discussion.
Was out of touch for quite sometime from the qemu upstream community.
Will definitely try to send a patch for the 'channels' documentation
changes soon in Qemu, as discussed above.

Regards,
Het Gala