From patchwork Mon Jul 24 14:14:45 2017 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Olaf Hering X-Patchwork-Id: 9859581 Return-Path: Received: from mail.wl.linuxfoundation.org (pdx-wl-mail.web.codeaurora.org [172.30.200.125]) by pdx-korg-patchwork.web.codeaurora.org (Postfix) with ESMTP id 80E71601A1 for ; Mon, 24 Jul 2017 14:17:42 +0000 (UTC) Received: from mail.wl.linuxfoundation.org (localhost [127.0.0.1]) by mail.wl.linuxfoundation.org (Postfix) with ESMTP id 72E4827FB3 for ; Mon, 24 Jul 2017 14:17:42 +0000 (UTC) Received: by mail.wl.linuxfoundation.org (Postfix, from userid 486) id 680282823D; Mon, 24 Jul 2017 14:17:42 +0000 (UTC) X-Spam-Checker-Version: SpamAssassin 3.3.1 (2010-03-16) on pdx-wl-mail.web.codeaurora.org X-Spam-Level: X-Spam-Status: No, score=-4.1 required=2.0 tests=BAYES_00,DKIM_SIGNED, RCVD_IN_DNSWL_MED,T_DKIM_INVALID autolearn=ham version=3.3.1 Received: from lists.xenproject.org (lists.xenproject.org [192.237.175.120]) (using TLSv1.2 with cipher AES128-GCM-SHA256 (128/128 bits)) (No client certificate requested) by mail.wl.linuxfoundation.org (Postfix) with ESMTPS id E279D27FB3 for ; Mon, 24 Jul 2017 14:17:41 +0000 (UTC) Received: from localhost ([127.0.0.1] helo=lists.xenproject.org) by lists.xenproject.org with esmtp (Exim 4.84_2) (envelope-from ) id 1dZe8f-0004db-9a; Mon, 24 Jul 2017 14:15:13 +0000 Received: from mail6.bemta6.messagelabs.com ([193.109.254.103]) by lists.xenproject.org with esmtp (Exim 4.84_2) (envelope-from ) id 1dZe8e-0004dQ-0p for xen-devel@lists.xen.org; Mon, 24 Jul 2017 14:15:12 +0000 Received: from [193.109.254.147] by server-6.bemta-6.messagelabs.com id 4E/DA-03937-FE006795; Mon, 24 Jul 2017 14:15:11 +0000 X-Brightmail-Tracker: H4sIAAAAAAAAA+NgFmpgkeJIrShJLcpLzFFi42IJXDnpju47hrJ Ig2l3FC2WfFzM4sDocXT3b6YAxijWzLyk/IoE1oyNM3qZCuZrVGyctp+9gXGjYhcjFweLwC8m iSUdU9m7GDk5JARyJZ7PfczWxcgBZItIPPmfBlIjJHCISWLv3f+MIDVsAkoSew8eB7NFBFIlZ kztZgGxmQUUJF4838oEYgsL2EmcObqLGcRmEVCV2Lv/KpjNK2AssW/xcjaIXfIS7/qfgtVzCp hIbH36GewGIaCaxqt/mCYw8i5gZFjFqFGcWlSWWqRraKmXVJSZnlGSm5iZo2toYKaXm1pcnJi empOYVKyXnJ+7iREYDgxAsIPxx7KAQ4ySHExKorzL1xVFCvEl5adUZiQWZ8QXleakFh9ilOHg UJLg3fK/NFJIsCg1PbUiLTMHGJgwaQkOHiUR3nsgad7igsTc4sx0iNQpRmOOO30bvjBxvJrw/ xuTEEtefl6qlDjvapBSAZDSjNI8uEGwiLnEKCslzMsIdJoQT0FqUW5mCar8K0ZxDkYlYd6DIF N4MvNK4Pa9AjqFCeiUOTPATilJREhJNTDuiFmyXvhXsfv2fh4NK9s0ln+TvbYURxqG8K0oebe vy/DThWkMJzuFD60Q/hF9Q0R3fvCNR2yRCoxen9aULmVYbNC24yb3Xvmn/5VUvrMc/HRYJZ8n ++sOe+bI2vWLxOazShw2epxQmrnqUs+1G5fCXljYyj+y2H5kd7zKj8/1lywmF21QMXNSYinOS DTUYi4qTgQAQoVkj5MCAAA= X-Env-Sender: olaf@aepfle.de X-Msg-Ref: server-10.tower-27.messagelabs.com!1500905710!85389999!1 X-Originating-IP: [81.169.146.220] X-SpamReason: No, hits=0.0 required=7.0 tests= X-StarScan-Received: X-StarScan-Version: 9.4.25; banners=-,-,- X-VirusChecked: Checked Received: (qmail 36960 invoked from network); 24 Jul 2017 14:15:10 -0000 Received: from mo4-p00-ob.smtp.rzone.de (HELO mo4-p00-ob.smtp.rzone.de) (81.169.146.220) by server-10.tower-27.messagelabs.com with DHE-RSA-AES256-GCM-SHA384 encrypted SMTP; 24 Jul 2017 14:15:10 -0000 DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; t=1500905710; l=5306; s=domk; d=aepfle.de; h=References:In-Reply-To:Date:Subject:Cc:To:From; bh=Tec9IO1zFTeTCglW9+c4focruRt0i4RetH4scM2yJhs=; b=uZ8+fVd2fP5xZ4dJOc0LgloJVGkf5kmOpv1iU0bPj6jXq1F/raAnw8nB70WMCImc5s DuzDYvQ49W/zWnvBoCgb24L0H1ahJmIrjkCScpryAZS6+XLf4QbMmg6ngEcIF6oQIXB/ eapfebx+Q1MXcqj9Dzk0+WLjFFydyWAweFts4= X-RZG-AUTH: :P2EQZWCpfu+qG7CngxMFH1J+yackYocTD1iAi8x+OWi/zfN1cLnAYQz4nWZeYaUqZmDcaKDKWuInYjY1AKYxM/KZ8U5sbA== X-RZG-CLASS-ID: mo00 Received: from sender ([2001:a61:345b:acff:1864:5839:ae0e:f6b6]) by smtp.strato.de (RZmta 41.1 AUTH) with ESMTPSA id 50583et6OEF6LKw (using TLSv1.2 with cipher ECDHE-RSA-AES256-SHA (curve secp521r1 with 521 ECDH bits, eq. 15360 bits RSA)) (Client did not present a certificate); Mon, 24 Jul 2017 16:15:06 +0200 (CEST) From: Olaf Hering To: xen-devel@lists.xen.org, Ian Jackson , Wei Liu Date: Mon, 24 Jul 2017 16:14:45 +0200 Message-Id: <20170724141450.22971-2-olaf@aepfle.de> X-Mailer: git-send-email 2.13.2 In-Reply-To: <20170724141450.22971-1-olaf@aepfle.de> References: <20170724141450.22971-1-olaf@aepfle.de> Cc: Olaf Hering Subject: [Xen-devel] [PATCH 1/6] docs: add pod variant of xen-pv-channel.7 X-BeenThere: xen-devel@lists.xen.org X-Mailman-Version: 2.1.18 Precedence: list List-Id: Xen developer discussion List-Unsubscribe: , List-Post: List-Help: List-Subscribe: , MIME-Version: 1.0 Errors-To: xen-devel-bounces@lists.xen.org Sender: "Xen-devel" X-Virus-Scanned: ClamAV using ClamSMTP 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 --- 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 CONFIGIXEN_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 + D: Share clipboard data via an in-guest agent. See: + http://wiki.xenproject.org/wiki/Clipboard_sharing_protocol