mirror of
https://github.com/xen-project/xen.git
synced 2026-10-29 10:40:03 +01:00
Andrew Cooper
8410fcb54a
The original intent of this patch was to rename xen-vbd-interface.markdown.7 to xen-vbd-interface.pandoc.7 to remove the final markdown file from the docs/ tree. The DOC_MANx lists are broken. They contain MANxSRC-y twice, the first half with a partial %.pod substituation, and the second half with a partial %.markdown substitution. This is also the root cause behind the filtering activity in the uninstall-man$(i)-pages rule. Furthermore, the logic for generating the manpage targets is unnecesserily repetative, owing to the layout of source files in the man/ directory. Therefore, tackle the problem by renaming all of our manpage source files from "$FORMAT.$SECTION" to "$SECTION.$FORMAT". For the two xl.cfg.5 and xl.1 which are preprocessed by autoconf to contain path information, this requires updating configure.ac and .gitignore. The markdown to pandoc conversion is performed as well, as it is also a straight rename. An ancillary benefit of this renaming is that text editors stand a chance of being able to work out the correct mode to use. As for the makefile: 1) Break the MAN_SECTIONS list out of the GENERATE_MANPAGE_RULES loop, as we are going to use it a second time. 2) Do away with the individaul MANxSRC-y variables. Use a single list, derived from all *.pod and *.pandoc files, with their format suffixes removed. 3) Use a $(foreach ...) to generate the DOC_MANx lists, filling them with the correct content. 4) The DOC_HTML and DOC_TXT can now include all manpages with a single substitution, as they don't need to separate the manpages by section-numbered-directory. 5) Fix up the filenames in the manpage metarule to match the renaming. No functional change. Signed-off-by: Andrew Cooper <andrew.cooper3@citrix.com> Acked-by: Ian Jackson <ian.jackson@eu.citrix.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:
|
|
http://wiki.xenproject.org/wiki/Clipboard_sharing_protocol
|