From patchwork Mon Jul 24 14:14:48 2017 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Olaf Hering X-Patchwork-Id: 9859575 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 EEFB3601A1 for ; Mon, 24 Jul 2017 14:17:38 +0000 (UTC) Received: from mail.wl.linuxfoundation.org (localhost [127.0.0.1]) by mail.wl.linuxfoundation.org (Postfix) with ESMTP id E0C0B27FA3 for ; Mon, 24 Jul 2017 14:17:38 +0000 (UTC) Received: by mail.wl.linuxfoundation.org (Postfix, from userid 486) id D56CC281B7; Mon, 24 Jul 2017 14:17:38 +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 BDA3C27FB3 for ; Mon, 24 Jul 2017 14:17:37 +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 1dZe8m-0004fl-Nx; Mon, 24 Jul 2017 14:15:20 +0000 Received: from mail6.bemta3.messagelabs.com ([195.245.230.39]) by lists.xenproject.org with esmtp (Exim 4.84_2) (envelope-from ) id 1dZe8l-0004fW-Cr for xen-devel@lists.xen.org; Mon, 24 Jul 2017 14:15:19 +0000 Received: from [85.158.137.68] by server-7.bemta-3.messagelabs.com id 65/FD-02177-6F006795; Mon, 24 Jul 2017 14:15:18 +0000 X-Brightmail-Tracker: H4sIAAAAAAAAA+NgFvrPLMWRWlGSWpSXmKPExsUSuHLSLd2vDGW RBh8fWFgs+biYxYHR4+ju30wBjFGsmXlJ+RUJrBlLm/awFZxUqzi49SBrA+MT+S5GTg4WgV9M EjeOJ4LYEgK5Es/nPmbrYuQAskUknvxP62Lk4hASOMQkcWniKVaQGjYBJYm9B48zgtgiAqkSM 6Z2s4DYzAIKEi+eb2UCsYUF3CSaVx1ngZivKnF6znSwOK+AscTk6a/ZIHbJS7zrfwoW5xQwkd j69DM7iC0EVNN49Q/TBEbeBYwMqxg1ilOLylKLdI3M9JKKMtMzSnITM3N0DQ2M9XJTi4sT01N zEpOK9ZLzczcxAoOhnoGBcQdjw16/Q4ySHExKorzL1xVFCvEl5adUZiQWZ8QXleakFh9ilOHg UJLgtf9fGikkWJSanlqRlpkDDEuYtAQHj5II7z2QNG9xQWJucWY6ROoUozHHnb4NX5g4Xk34/ 41JiCUvPy9VSpx3NUipAEhpRmke3CBYvFxilJUS5mVkYGAQ4ilILcrNLEGVf8UozsGoJMx7EG QKT2ZeCdy+V0CnMAGdMmcG2CkliQgpqQbGjBkxEd/fit+R0PrT3yYtm7zvw+ubuo7HH4Tb3+P 72ab179mPrTf6nX8GduxLjAxSnHBEIinnq7IO46zX0Xb3L4tHn7pvZNPRuUAn+6HgdWfF95xL HF6VMRUv8PF/+fxImIyBzY3lxbnnt0lzyc3eOT+lTnr1o55VqW+FspMYktgP7zfblrNXiaU4I 9FQi7moOBEA37Q85JICAAA= X-Env-Sender: olaf@aepfle.de X-Msg-Ref: server-4.tower-31.messagelabs.com!1500905717!48785307!1 X-Originating-IP: [81.169.146.218] 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 59406 invoked from network); 24 Jul 2017 14:15:17 -0000 Received: from mo4-p00-ob.smtp.rzone.de (HELO mo4-p00-ob.smtp.rzone.de) (81.169.146.218) by server-4.tower-31.messagelabs.com with DHE-RSA-AES256-GCM-SHA384 encrypted SMTP; 24 Jul 2017 14:15:17 -0000 DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; t=1500905717; l=4927; s=domk; d=aepfle.de; h=References:In-Reply-To:Date:Subject:Cc:To:From; bh=Mt430DH6LnQg6hQP29rOPrQlV88cXHk/6A2ICXVqQlk=; b=wKF1WO2nfzD3cM6Ok/L3b4tGa83R/BBbWEFsDbEUsbtj2ufGHHAaY1PyNGlnYIXd98 DmtHWf18YBv3qVkwD1xqllWgrSGOQFdFA531wRyFAGTezFIGxCpYSqXVkVyTnU4k/90x b/NXZEEL3i8E080OqjVXd8LnaWY2Jxr8q5HNg= 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 50583et6OEFFLL4 (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:15 +0200 (CEST) From: Olaf Hering To: xen-devel@lists.xen.org, Ian Jackson , Wei Liu Date: Mon, 24 Jul 2017 16:14:48 +0200 Message-Id: <20170724141450.22971-5-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 4/6] docs: remove markdown 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 A variant in pod format exists now. Signed-off-by: Olaf Hering --- docs/man/xen-pv-channel.markdown.7 | 106 ------------------------------------- 1 file changed, 106 deletions(-) delete mode 100644 docs/man/xen-pv-channel.markdown.7 diff --git a/docs/man/xen-pv-channel.markdown.7 b/docs/man/xen-pv-channel.markdown.7 deleted file mode 100644 index 1c6149dae0..0000000000 --- a/docs/man/xen-pv-channel.markdown.7 +++ /dev/null @@ -1,106 +0,0 @@ -Xen PV Channels -=============== - -A channel is a low-bandwidth private byte stream similar to a serial -link. Typical uses of channels are - - 1. to provide initial configuration information to a VM on boot - (example use: CloudStack's cloud-early-config service) - 2. to signal/query an in-guest agent - (example use: oVirt's guest agent) - -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. - -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: - - 1. Install a guest as normal (no channel configuration necessary) - 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") - 3. Shutdown the guest - 4. Register the guest as a template with the cloud orchestration software - 5. Install the cloud orchestration agent in dom0 - -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) - - 1. A VM is "cloned" from the template - 2. A unique Unix domain socket path in dom0 is allocated - (e.g. /my/cloud/software/talk/to/domain/) - 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/" ] - - 4. The VM is started - 5. In dom0 the cloud orchestration agent connects to the Unix domain - socket, writes a handshake message and waits for a reply - 6. Assuming the guest kernel has CONFIG_HVC_XEN_FRONTEND set then the console - driver will generate a hotplug event - 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 - - 8. The in-guest agent uses inotify to see the creation of the /dev/xen-channel - symlink and opens the device. - 9. The in-guest agent completes the handshake with the dom0 agent - 10. The dom0 agent transmits the unique VM configuration: hostname, IP - address, ssh keys etc etc - 11. The in-guest agent receives the configuration and applies it. - -Using channels avoids having to use a temporary disk device or network -connection. - -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. - -Limitations ------------ - -Hotplug and unplug of channels is not currently implemented. - -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