1xen-pv-channel(7)                     Xen                    xen-pv-channel(7)
2
3
4

NAME

6       xen-pv-channel - Xen PV Channels
7

DESCRIPTION

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