From patchwork Wed Jul 26 14:39: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: 9865191 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 467EC6038C for ; Wed, 26 Jul 2017 14:42:34 +0000 (UTC) Received: from mail.wl.linuxfoundation.org (localhost [127.0.0.1]) by mail.wl.linuxfoundation.org (Postfix) with ESMTP id 3BAC92785D for ; Wed, 26 Jul 2017 14:42:34 +0000 (UTC) Received: by mail.wl.linuxfoundation.org (Postfix, from userid 486) id 3071D28733; Wed, 26 Jul 2017 14:42:34 +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 EC0A72785D for ; Wed, 26 Jul 2017 14:42:32 +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 1daNTs-00054T-CT; Wed, 26 Jul 2017 14:40:08 +0000 Received: from mail6.bemta6.messagelabs.com ([193.109.254.103]) by lists.xenproject.org with esmtp (Exim 4.84_2) (envelope-from ) id 1daNTq-00051a-OL for xen-devel@lists.xen.org; Wed, 26 Jul 2017 14:40:06 +0000 Received: from [85.158.143.35] by server-6.bemta-6.messagelabs.com id 4B/8A-03937-6C9A8795; Wed, 26 Jul 2017 14:40:06 +0000 X-Brightmail-Tracker: H4sIAAAAAAAAA+NgFmpgkeJIrShJLcpLzFFi42IJXDlpge7RlRW RBv9fCVgs+biYxYHR4+ju30wBjFGsmXlJ+RUJrBmv1p1kKXjrW3Hwxz/GBsYzDl2MXBwsAr+Z JC6cms/excjJISGQKzGndy5rFyMHkC0i8eR/GkiNkMAhJok3jzeD1bAJKEnsPXicEcQWEUiVm DG1mwXEZhZQkHjxfCsTiC0s4Cgx9983NhCbRUBV4uDeOWC9vALGEk33p7JB7JKXeNf/FKyeU8 BEYtLu92A1QkA1K689Y5nAyLuAkWEVo0ZxalFZapGukaVeUlFmekZJbmJmjq6hgZlebmpxcWJ 6ak5iUrFecn7uJkZgODAAwQ7GA4sCDzFKcjApifJOMq2IFOJLyk+pzEgszogvKs1JLT7EKMPB oSTBW7MCKCdYlJqeWpGWmQMMTJi0BAePkghvI0iat7ggMbc4Mx0idYrRmONO34YvTByvJvz/x iTEkpeflyolzlsHUioAUppRmgc3CBYxlxhlpYR5GYFOE+IpSC3KzSxBlX/FKM7BqCTMuxBkCk 9mXgncvldApzABnTJnRinIKSWJCCmpBsY95cWLXt3McrQN9T+5cnNrrWCYhaDGt+l9DlM3lLp tn+I3U/HbP77Z7lxWGlpKYSWHjfI22uZorfZ/fvqs3+tp7w6cZl8pa5Qu8Fehg92Xf+3HfPn7 VS63FnGvnvz6vE/B+qhFlelLDvb/MojLDD3XxH78z5UNx6wL2l/sypeVi7/+0CrYK0iJpTgj0 VCLuag4EQDLuUPakwIAAA== X-Env-Sender: olaf@aepfle.de X-Msg-Ref: server-10.tower-21.messagelabs.com!1501080004!68410200!1 X-Originating-IP: [81.169.146.160] X-SpamReason: No, hits=0.0 required=7.0 tests=sa_preprocessor: QmFkIElQOiA4MS4xNjkuMTQ2LjE2MCA9PiA1NTc3MTg=\n,sa_preprocessor: QmFkIElQOiA4MS4xNjkuMTQ2LjE2MCA9PiA1NTc3MTg=\n X-StarScan-Received: X-StarScan-Version: 9.4.25; banners=-,-,- X-VirusChecked: Checked Received: (qmail 30041 invoked from network); 26 Jul 2017 14:40:05 -0000 Received: from mo4-p00-ob.smtp.rzone.de (HELO mo4-p00-ob.smtp.rzone.de) (81.169.146.160) by server-10.tower-21.messagelabs.com with DHE-RSA-AES256-GCM-SHA384 encrypted SMTP; 26 Jul 2017 14:40:05 -0000 DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; t=1501080004; l=10121; s=domk; d=aepfle.de; h=References:In-Reply-To:Date:Subject:Cc:To:From; bh=/fIQxc8C00u1A3TgMzfsb3kg/ok+oHJKJCcfMGum6uk=; b=moKZ4UPk8LfPhfh8WcrYGRIQorRu6305dYhYy3fdqurXos+dk/Zk+7dhWHxA2C8Bcb BwvZcj3J8apYRhiTzFYol2WudVMURARhiH43NiradroaGsfhRKee9QWUruNSlwfgxUKr xaFZ7rrUKmI3co6faVAuaWofgREm4cTwVcG/A= X-RZG-AUTH: :P2EQZWCpfu+qG7CngxMFH1J+yackYocTD1iAi8x+OWi/zfN1cLnAYQz4nTxeMfYqQUynrTNSUxxRmo+kS0vrvFOiwqvPcA== X-RZG-CLASS-ID: mo00 Received: from sender ([2001:a61:3458:10ff:1629:d398:f8f9:5e72]) by smtp.strato.de (RZmta 41.1 AUTH) with ESMTPSA id v056act6QEdwCuA (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); Wed, 26 Jul 2017 16:39:58 +0200 (CEST) From: Olaf Hering To: xen-devel@lists.xen.org, Ian Jackson , Wei Liu Date: Wed, 26 Jul 2017 16:39:48 +0200 Message-Id: <20170726143950.30329-2-olaf@aepfle.de> X-Mailer: git-send-email 2.13.2 In-Reply-To: <20170726143950.30329-1-olaf@aepfle.de> References: <20170726143950.30329-1-olaf@aepfle.de> Cc: Olaf Hering Subject: [Xen-devel] [PATCH v3 1/3] 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 Convert source for xen-pv-channel.7 from markdown to pod. 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.markdown.7 | 106 --------------------- docs/man/xen-pv-channel.pod.7 | 188 +++++++++++++++++++++++++++++++++++++ 2 files changed, 188 insertions(+), 106 deletions(-) delete mode 100644 docs/man/xen-pv-channel.markdown.7 create mode 100644 docs/man/xen-pv-channel.pod.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 diff --git a/docs/man/xen-pv-channel.pod.7 b/docs/man/xen-pv-channel.pod.7 new file mode 100644 index 0000000000..2333083cce --- /dev/null +++ b/docs/man/xen-pv-channel.pod.7 @@ -0,0 +1,188 @@ +=encoding utf8 + + +=head1 NAME + +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 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