1=encoding utf8
2
3
4=head1 NAME
5
6Xen PV Channels
7
8=head1 DESCRIPTION
9
10A channel is a low-bandwidth private byte stream similar to a serial
11link. Typical uses of channels are
12
13=over
14
15=item 1.
16
17to provide initial configuration information to a VM on boot
18(example use: CloudStack's cloud-early-config service)
19
20
21=item 2.
22
23to signal/query an in-guest agent
24(example use: oVirt's guest agent)
25
26
27=back
28
29Channels are similar to virtio-serial devices and emulated serial links.
30Channels are intended to be used in the implementation of libvirt s
31when running on Xen.
32
33Note: if an application requires a high-bandwidth link then it should use
34vchan instead.
35
36
37=head2 How to use channels: an example
38
39Consider a cloud deployment where VMs are cloned from pre-made templates,
40and customised on first boot by an in-guest agent which sets the IP address,
41hostname, ssh keys etc. To install the system the cloud administrator would
42first:
43
44=over
45
46=item 1.
47
48Install a guest as normal (no channel configuration necessary)
49
50
51=item 2.
52
53Install the in-guest agent specific to the cloud software. This will
54prepare the guest to communicate over the channel, and also prepare
55the guest to be cloned safely (sometimes known as "sysprepping")
56
57
58=item 3.
59
60Shutdown the guest
61
62
63=item 4.
64
65Register the guest as a template with the cloud orchestration software
66
67
68=item 5.
69
70Install the cloud orchestration agent in dom0
71
72
73=back
74
75At runtime, when a cloud tenant requests that a VM is created from the template,
76the sequence of events would be: (assuming a Linux domU)
77
78=over
79
80=item 1.
81
82A VM is "cloned" from the template
83
84
85=item 2.
86
87A unique Unix domain socket path in dom0 is allocated
88(e.g. /my/cloud/software/talk/to/domain/)
89
90
91=item 3.
92
93Domain configuration is created for the VM, listing the channel
94name expected by the in-guest agent. In xl syntax this would be:
95
96channel = [ "connection=socket, name=org.my.cloud.software.agent.version1, path = /my/cloud/software/talk/to/domain/" ]
97
98=item 4.
99
100The VM is started
101
102
103=item 5.
104
105In dom0 the cloud orchestration agent connects to the Unix domain
106socket, writes a handshake message and waits for a reply
107
108
109=item 6.
110
111Assuming the guest kernel has CONFIGI<HVC>XEN_FRONTEND set then the console
112driver will generate a hotplug event
113
114
115=item 7.
116
117A udev rule is activated by the hotplug event.
118
119The udev rule would look something like:
120
121SUBSYSTEM=="xen", DEVPATH=="/devices/console-[0-9]", RUN+="xen-console-setup"
122
123where the "xen-console-setup" script would read the channel name and
124make a symlink in /dev/xen-channel/org.my.cloud.software.agent.version1
125
126
127=item 8.
128
129The in-guest agent uses inotify to see the creation of the /dev/xen-channel
130symlink and opens the device.
131
132
133=item 9.
134
135The in-guest agent completes the handshake with the dom0 agent
136
137
138=item 10.
139
140The dom0 agent transmits the unique VM configuration: hostname, IP
141address, ssh keys etc etc
142
143
144=item 11.
145
146The in-guest agent receives the configuration and applies it.
147
148
149=back
150
151Using channels avoids having to use a temporary disk device or network
152connection.
153
154
155=head2 Design recommendations and pitfalls
156
157It's necessary to install channel-specific software (an "agent") into the guest
158before you can use a channel. By default a channel will appear as a device
159which could be mistaken for a serial port or regular console. It is known
160that some software will proactively seek out serial ports and issue AT commands
161at them; make sure such software is disabled!
162
163Since channels are identified by names, application authors must ensure their
164channel names are unique to avoid clashes. We recommend that channel names
165include parts unique to the application such as a domain names. To assist
166prevent clashes we recommend authors add their names to our global channel
167registry at the end of this document.
168
169
170=head2 Limitations
171
172Hotplug and unplug of channels is not currently implemented.
173
174
175=head2 Channel name registry
176
177It is important that channel names are globally unique. To help ensure
178that no-one's name clashes with yours, please add yours to this list.
179
180    Key:
181    N: Name
182    C: Contact
183    D: Short description of use, possibly including a URL to your software or API
184
185    N: org.xenproject.guest.clipboard.0.1
186    C: David Scott <dave.scott@citrix.com>
187    D: Share clipboard data via an in-guest agent. See:
188       http://wiki.xenproject.org/wiki/Clipboard_sharing_protocol
189