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