1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
|
=encoding utf8
=head1 NAME
xen-pv-channel - 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 CONFIG_HVC_XEN_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
pointing to /dev/hvcN. N is the same number as the number in "/devices/console-[0-9]".
In other words, "/devices/console-2" maps to /dev/hvc2.
=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 <dave.scott@citrix.com>
D: Share clipboard data via an in-guest agent. See:
https://wiki.xenproject.org/wiki/Clipboard_sharing_protocol
|
