mirror of
https://github.com/xen-project/xen.git
synced 2026-10-28 02:01:24 +01:00
Lars Kurth
f8abe4fe3c
Specifically * xen.org to xenproject.org * http to https * Replaced pages where page has moved (including on xen pages as well as external pages) * Removed some URLs (e.g. downloads for Linux PV drivers) Tested-by: Lars Kurth <lars.kurth@citrix.com> Signed-off-by: Lars Kurth <lars.kurth@citrix.com> Acked-by: Andrew Cooper <andrew.cooper3@citrix.com> Acked-by: Wei Liu <wl@xen.org> Release-acked-by: Juergen Gross <jgross@suse.com>
190 lines
4.4 KiB
INI
190 lines
4.4 KiB
INI
=encoding utf8
|
|
|
|
=head1 NAME
|
|
|
|
xen-pv-channel - Xen PV Channels
|
|
|
|
=head1 DESCRIPTION
|
|
|
|
A channel is a low-bandwidth private byte stream similar to a serial
|
|
link. Typical uses of channels are
|
|
|
|
=over
|
|
|
|
=item 1.
|
|
|
|
to provide initial configuration information to a VM on boot
|
|
(example use: CloudStack's cloud-early-config service)
|
|
|
|
|
|
=item 2.
|
|
|
|
to signal/query an in-guest agent
|
|
(example use: oVirt's guest agent)
|
|
|
|
|
|
=back
|
|
|
|
Channels are similar to virtio-serial devices and emulated serial links.
|
|
Channels are intended to be used in the implementation of libvirt s
|
|
when running on Xen.
|
|
|
|
Note: if an application requires a high-bandwidth link then it should use
|
|
vchan instead.
|
|
|
|
|
|
=head2 How to use channels: an example
|
|
|
|
Consider a cloud deployment where VMs are cloned from pre-made templates,
|
|
and customised on first boot by an in-guest agent which sets the IP address,
|
|
hostname, ssh keys etc. To install the system the cloud administrator would
|
|
first:
|
|
|
|
=over
|
|
|
|
=item 1.
|
|
|
|
Install a guest as normal (no channel configuration necessary)
|
|
|
|
|
|
=item 2.
|
|
|
|
Install the in-guest agent specific to the cloud software. This will
|
|
prepare the guest to communicate over the channel, and also prepare
|
|
the guest to be cloned safely (sometimes known as "sysprepping")
|
|
|
|
|
|
=item 3.
|
|
|
|
Shutdown the guest
|
|
|
|
|
|
=item 4.
|
|
|
|
Register the guest as a template with the cloud orchestration software
|
|
|
|
|
|
=item 5.
|
|
|
|
Install the cloud orchestration agent in dom0
|
|
|
|
|
|
=back
|
|
|
|
At runtime, when a cloud tenant requests that a VM is created from the template,
|
|
the sequence of events would be: (assuming a Linux domU)
|
|
|
|
=over
|
|
|
|
=item 1.
|
|
|
|
A VM is "cloned" from the template
|
|
|
|
|
|
=item 2.
|
|
|
|
A unique Unix domain socket path in dom0 is allocated
|
|
(e.g. /my/cloud/software/talk/to/domain/)
|
|
|
|
|
|
=item 3.
|
|
|
|
Domain configuration is created for the VM, listing the channel
|
|
name expected by the in-guest agent. In xl syntax this would be:
|
|
|
|
channel = [ "connection=socket, name=org.my.cloud.software.agent.version1, path = /my/cloud/software/talk/to/domain/" ]
|
|
|
|
=item 4.
|
|
|
|
The VM is started
|
|
|
|
|
|
=item 5.
|
|
|
|
In dom0 the cloud orchestration agent connects to the Unix domain
|
|
socket, writes a handshake message and waits for a reply
|
|
|
|
|
|
=item 6.
|
|
|
|
Assuming the guest kernel has CONFIG_HVC_XEN_FRONTEND set then the console
|
|
driver will generate a hotplug event
|
|
|
|
|
|
=item 7.
|
|
|
|
A udev rule is activated by the hotplug event.
|
|
|
|
The udev rule would look something like:
|
|
|
|
SUBSYSTEM=="xen", DEVPATH=="/devices/console-[0-9]", RUN+="xen-console-setup"
|
|
|
|
where the "xen-console-setup" script would read the channel name and
|
|
make a symlink in /dev/xen-channel/org.my.cloud.software.agent.version1
|
|
pointing to /dev/hvcN. N is the same number as the number in "/devices/console-[0-9]".
|
|
In other words, "/devices/console-2" maps to /dev/hvc2.
|
|
|
|
|
|
=item 8.
|
|
|
|
The in-guest agent uses inotify to see the creation of the /dev/xen-channel
|
|
symlink and opens the device.
|
|
|
|
|
|
=item 9.
|
|
|
|
The in-guest agent completes the handshake with the dom0 agent
|
|
|
|
|
|
=item 10.
|
|
|
|
The dom0 agent transmits the unique VM configuration: hostname, IP
|
|
address, ssh keys etc etc
|
|
|
|
|
|
=item 11.
|
|
|
|
The in-guest agent receives the configuration and applies it.
|
|
|
|
|
|
=back
|
|
|
|
Using channels avoids having to use a temporary disk device or network
|
|
connection.
|
|
|
|
|
|
=head2 Design recommendations and pitfalls
|
|
|
|
It's necessary to install channel-specific software (an "agent") into the guest
|
|
before you can use a channel. By default a channel will appear as a device
|
|
which could be mistaken for a serial port or regular console. It is known
|
|
that some software will proactively seek out serial ports and issue AT commands
|
|
at them; make sure such software is disabled!
|
|
|
|
Since channels are identified by names, application authors must ensure their
|
|
channel names are unique to avoid clashes. We recommend that channel names
|
|
include parts unique to the application such as a domain names. To assist
|
|
prevent clashes we recommend authors add their names to our global channel
|
|
registry at the end of this document.
|
|
|
|
|
|
=head2 Limitations
|
|
|
|
Hotplug and unplug of channels is not currently implemented.
|
|
|
|
|
|
=head2 Channel name registry
|
|
|
|
It is important that channel names are globally unique. To help ensure
|
|
that no-one's name clashes with yours, please add yours to this list.
|
|
|
|
Key:
|
|
N: Name
|
|
C: Contact
|
|
D: Short description of use, possibly including a URL to your software or API
|
|
|
|
N: org.xenproject.guest.clipboard.0.1
|
|
C: David Scott <dave.scott@citrix.com>
|
|
D: Share clipboard data via an in-guest agent. See:
|
|
https://wiki.xenproject.org/wiki/Clipboard_sharing_protocol
|