[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index] [Xen-devel] [PATCH 1/6] docs: add pod variant of xen-pv-channel.7
Add source in pod format for xen-pv-channel.7 This removes the buildtime requirement for pandoc, and subsequently the need for ghc, in the chain for BuildRequires of xen.rpm. Signed-off-by: Olaf Hering <olaf@xxxxxxxxx> --- docs/man/xen-pv-channel.pod.7 | 189 ++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 189 insertions(+) create mode 100644 docs/man/xen-pv-channel.pod.7 diff --git a/docs/man/xen-pv-channel.pod.7 b/docs/man/xen-pv-channel.pod.7 new file mode 100644 index 0000000000..8b0b74aa27 --- /dev/null +++ b/docs/man/xen-pv-channel.pod.7 @@ -0,0 +1,189 @@ +=encoding utf8 + + +=head1 Xen PV Channels + +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 CONFIGI<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 + + + +=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@xxxxxxxxxx> + D: Share clipboard data via an in-guest agent. See: + http://wiki.xenproject.org/wiki/Clipboard_sharing_protocol _______________________________________________ Xen-devel mailing list Xen-devel@xxxxxxxxxxxxx https://lists.xen.org/xen-devel
|
Lists.xenproject.org is hosted with RackSpace, monitoring our |