Skip to contentSkip to conversation

docs: Document xenstore paths

PATCH In review Paul Durrant 5 participants 12 messages Nov 17, 2015 – Nov 24, 2015

lore
Share & tools
lore
#0 lore raw

v5 cover docs: Document xenstore paths

Patch #1 documents paths, some already in used by XenServer, which can be used by guests to advertise contol capabilities.

Patch #2 documents paths which can be used to advertise PV driver versions.

Patch #3 documents paths which can be used by guests to advertise hotplug capabilities.

Patch #4 documents paths which can be used by guests to advertise network addresses.

#1 lore raw

PATCH v5 1/4 docs: Introduce xenstore paths for PV control features

XenServer already makes use of ~/control/feature-suspend being written to advertise guest capability of responding to 'suspend' when written to ~/control/shutdown and, since they are derived from XenServer drivers, the Xen Project Windows PV drivers attempt to write this value. The write currently fails for libxl provisioned VMs because ~/control is read-only to the guest (only ~/control/shutdown is writable, for ackowledgement purposes).

This patch documents feature-suspend and also a set of similar control feature flags, so that that they may be added to libxl provisioned guests by subsequent patches:

feature-poweroff: PV drivers/agent can shut down the guest
feature-reboot: PV drivers/agent can reboot the guest
feature-s3: PV drivers/agent can trigger guest sleep (HVM only)
feature-s4: PV drivers/agent can trigger guest hibernate (HVM only)

The patch (bacause it adds features relating to S3 and S4 power states) also clarifies that the initial set of platform properties mentioned are booleans, and updates the specifier accordingly.

---

v4:
- Clarify use of control features

v3:
- Changed feature-halt to feature-poweroff since writing 'poweroff' to control/shutdown is the currently implemented method of PV domain shutdown

---
 docs/misc/xenstore-paths.markdown | 39 +++++++++++++++++++++++++++++++++++++--
 1 file changed, 37 insertions(+), 2 deletions(-)
docs/misc/xenstore-paths.markdown +37 -2
index d94ea9d..2d2ce46 100644
@@ -178,9 +178,9 @@ will not relocate guest memory.
 
 The BIOS used by this domain.
 
-#### ~/platform/* [HVM,INTERNAL]
+#### ~/platform/* = ("0"|"1") [HVM,INTERNAL]
 
-Various platform properties.
+Various boolean platform properties.
 
 * acpi -- is ACPI enabled for this domain
 * acpi_s3 -- is ACPI S3 support enabled for this domain
@@ -327,6 +327,41 @@ string back to the command node.
 
 The precise protocol is not yet documented.
 
+#### ~/control/feature-poweroff = (""|"0"|"1") [w]
+#### ~/control/feature-reboot = (""|"0"|"1") [w]
+#### ~/control/feature-suspend = (""|"0"|"1") [w]
+
+These may be initialized to "" by the toolstack and may then be set
+to 0 or 1 by a guest to indicate whether it is capable or incapable,
+respectively, of responding to the corresponding command when written
+to ~/control/shutdown.
+A toolstack may then sample the feature- value at the point of issuing
+a PV control command and respond accordingly:
+
+"0" -> the frontend should not be expected to respond, so fail the
+       control operation
+"1" -> the frontend should be expected to respond, so wait for it to
+       do so and maybe fail the control operation after some reasonable
+       timeout.
+""  -> the frontend may or may not respond, so wait for it to do so and
+       then maybe try an alternative control mechanism after some
+       reasonable timeout.
+
+Since a toolstack may not initialize these paths, and the parent
+~/control path is read-only to a guest, a guest should not expect a
+write to succeed. If it fails the guest may log the failure but should
+continue to process the corresponding command when written to
+~/control/shutdown regardless.
+
+#### ~/control/feature-s3 = (""|"0"|"1") [w,HVM]
+#### ~/control/feature-s4 = (""|"0"|"1") [w,HVM]
+
+These purpose of these feature flags is identical to feature-poweroff,
+feature-reboot and feature-suspend above but concern triggering the
+S3 or S4 power states of HVM guests.
+A toolstack may create these values, but should not sample them unless
+the corresponding acpi_ feature flag is set in ~/platform.
+
 #### ~/control/platform-feature-multiprocessor-suspend = (0|1) []
 
 Indicates to the guest that this platform supports the multiprocessor
Signature · 1 line
2.1.4
#2 lore raw

PATCH v5 2/4 docs: Introduce xenstore paths for PV driver information

In reply to Paul Durrant

For domain management purposes it is convenient to be able to see information about PV drivers in xenstore. The XAPI toolstack in XenServer has always created a ~/drivers path for this purpose.

This patch documents that path and also adds a specification of how it should be used.

Cc Ian Campbell <[email protected]>
Cc Ian Jackson <[email protected]>
Cc Jan Beulich <[email protected]>
Cc Keir Fraser <[email protected]>
Cc Tim Deegan <[email protected]>

---

v5:
- Add more clarification to DISTRIBUTION section.

v4:
- Rather than just version information, expand the definition of paths under ~/drivers to include full distribution information, including vendor name.

v2:
- Modify version specifier to allow for single-part version numbers and also arbitrary string suffix (e.g. '-debug')

---
 docs/misc/xenstore-paths.markdown | 29 +++++++++++++++++++++++++++++
 1 file changed, 29 insertions(+)
docs/misc/xenstore-paths.markdown +29 -0
index 2d2ce46..b8788f2 100644
@@ -37,6 +37,8 @@ before regexp expansion:
   the "other" domain. i.e. ~ refers to the domain providing a service
   while $DOMID is the consumer of that service.
 * $UUID -- a UUID in the form xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
+* $INDEX -- an integer used as part of a path when listing a set of
+            values. Typically these integers are contiguous.
 
 VALUES are strings and can take the following forms:
 
@@ -51,6 +53,28 @@ VALUES are strings and can take the following forms:
 * (VALUE | VALUE | ... ) -- a set of alternatives. Alternatives are
   separated by a "|" and all the alternatives are enclosed in "(" and
   ")".
+* DISTRIBUTION -- information about a software distribution, comprised
+                  of 3 or 4 space separated UTF-8 strings as follows:
+
+                  VENDOR -- Commonly used vendor short name,
+                            e.g "Citrix" rather than "Citrix Systems
+                            Inc."
+
+                  PRODUCT -- Commonly used product (e.g. driver) name
+                             without version information.
+
+                  If the toolstack needs to match on either of the above
+                  values it should support Unix glob style matching.
+
+                  VERSION -- A version number that will sort properly
+                             under coreutils version sorting (sort -V)
+                             rules.
+
+                  ATTRIBUTES -- Optional human readable text to denote
+                                attributes of the software, e.g. "debug".
+                                This text is freeform and no meaning
+                                should be inferred. It is intended for
+                                display purposes only.
 
 Additional TAGS may follow as a comma separated set of the following
 tags enclosed in square brackets.
@@ -380,6 +404,11 @@ protocol definition.
 
 A domain writable path. Available for arbitrary domain use.
 
+#### ~/drivers/$INDEX = DISTRIBUTION [w]
+
+A domain may write information about installed PV drivers using
+paths of this form.
+
 ### Paths private to the toolstack
 
 #### ~/device-model/$DOMID/state [w]
Signature · 1 line
2.1.4
Acked-by on v5 2/4
#3 lore raw

Re: [PATCH v5 2/4] docs: Introduce xenstore paths for PV driver information

Paul Durrant writes ("[PATCH v5 2/4] docs: Introduce xenstore paths for PV driver information"):

Quoted 6 lines

For domain management purposes it is convenient to be able to see information about PV drivers in xenstore. The XAPI toolstack in XenServer has always created a ~/drivers path for this purpose.

This patch documents that path and also adds a specification of how it should be used.

#4 lore raw

PATCH v5 3/4 docs: Introduce xenstore paths for hotplug features

In reply to Paul Durrant

Without some indication from a guest it is not possible for a toolstack to know whether instantiation of a new vbd or vif should result in a new PV device of the appropriate type being brought online. (In other words whether guest PV drivers are present and functioning).

This patch documents two paths which vif and vbd frontend drivers can use to advertise their ability to respond to new vif or vbd instantiations.

Cc Ian Campbell <[email protected]>
Cc Ian Jackson <[email protected]>
Cc Jan Beulich <[email protected]>
Cc Keir Fraser <[email protected]>
Cc Tim Deegan <[email protected]>

---

v4:
- Clarify use of the hotplug feature paths

v2:
- Drop HVM restriction

---
 docs/misc/xenstore-paths.markdown | 12 ++++++++++++
 1 file changed, 12 insertions(+)
docs/misc/xenstore-paths.markdown +12 -0
index b8788f2..624b7fd 100644
@@ -409,6 +409,18 @@ A domain writable path. Available for arbitrary domain use.
 A domain may write information about installed PV drivers using
 paths of this form.
 
+#### ~/feature/hotplug/vif = ("0"|"1") [w]
+#### ~/feature/hotplug/vbd = ("0"|"1") [w]
+
+By setting these paths to "1" a guest can indicate to a toolstack
+that it is capable of responding immediately to instantiation of,
+respectively, new vif by bringing online a new PV network device or
+a new vbd by bringing online a new PV block device.
+If the guest sets this path to "0" then it is indicating that it is
+definitely unable to respond immediately and hence the toolstack should
+defer instantiaton to the next VM start. However, if the path is absent
+then the toolstack may attempt the operation.
+
 ### Paths private to the toolstack
 
 #### ~/device-model/$DOMID/state [w]
Signature · 1 line
2.1.4
Acked-by on v5 3/4
#5 lore raw

Re: [PATCH v5 3/4] docs: Introduce xenstore paths for hotplug features

Paul Durrant writes ("[PATCH v5 3/4] docs: Introduce xenstore paths for hotplug features"):

Quoted 8 lines

Without some indication from a guest it is not possible for a toolstack to know whether instantiation of a new vbd or vif should result in a new PV device of the appropriate type being brought online. (In other words whether guest PV drivers are present and functioning).

This patch documents two paths which vif and vbd frontend drivers can use to advertise their ability to respond to new vif or vbd instantiations.

#6 lore raw

PATCH v5 4/4 docs: Introduce xenstore paths for guest network address information

In reply to Paul Durrant

It is useful for a toolstack to be able to see the network addresses in use by a domain for a particular vif in xenstore for display purposes and, for example, so that a VNC session can be established to the guest GUI.

This patch documents paths to allow a domain to advertise an interface name, MAC (unicast and multicast) and IP (version 4 and 6) address information.

Cc Ian Campbell <[email protected]>
Cc Ian Jackson <[email protected]>
Cc Jan Beulich <[email protected]>
Cc Keir Fraser <[email protected]>
Cc Tim Deegan <[email protected]>

---

v5:
- Add references for MAC and IP address formats
- Further clarification of attr paths

v4:
- Add clarification of use and level of trust that should be placed on the various paths

v2:
- Allow for compression of IPv6 addresses

---
 docs/misc/xenstore-paths.markdown | 36 ++++++++++++++++++++++++++++++++++++
 1 file changed, 36 insertions(+)
docs/misc/xenstore-paths.markdown +36 -0
index 624b7fd..197bb0f 100644
@@ -76,6 +76,15 @@ VALUES are strings and can take the following forms:
                                 should be inferred. It is intended for
                                 display purposes only.
 
+* MAC_ADDRESS -- 6 integers, in hexadecimal form, separated by ':',
+                 specifying an IEEE 802.3 ethernet MAC address.
+* IPV4_ADDRESS -- 4 integers, in decimal form, separated by '.',
+                  specifying an IP version 4 address as described
+                  IETF RFC 791.
+* IPV6_ADDRESS -- Up to 8 integers, in hexadecimal form, separated
+                  by ':', specifying an IP version 6 address as
+                  described in IETF RFC 4291.
+
 Additional TAGS may follow as a comma separated set of the following
 tags enclosed in square brackets.
 
@@ -421,6 +430,33 @@ definitely unable to respond immediately and hence the toolstack should
 defer instantiaton to the next VM start. However, if the path is absent
 then the toolstack may attempt the operation.
 
+#### ~/attr/vif/$DEVID/name = STRING [w]
+
+A domain may write its internal 'friendly' name for a network device
+using this path using UTF-8 encoding. A toolstack or UI may use this
+for display purposes. No particular meaning should be inferred from the
+name.
+
+#### ~/attr/vif/$DEVID/mac/$INDEX = MAC_ADDRESS [w]
+
+Paths of this form may be written by the guest to indicate MAC addresses
+it is currently using. These may be multicast or unicast addresses. For
+any of the paths the value of $INDEX is arbitrary.
+The values written are primarily for display purposes and must not be used
+for packet filtering or routing purposes.
+
+#### ~/attr/vif/$DEVID/ipv4/$INDEX = IPV4_ADDRESS [w]
+#### ~/attr/vif/$DEVID/ipv6/$INDEX = IPV6_ADDRESS [w]
+
+Paths of this form may be written by the guest to indicate IP addresses
+in use by the stack bound to the network frontend. For any of the paths
+the value of $INDEX is arbitrary.
+The values written are primarily for display purposes and must not be used
+for packet filtering or routing purposes. A toolstack may attempt to use an
+address written in one of these paths to, for example, establish a VNC
+session to the guest (although clearly some level of trust is placed
+in the value supplied by the guest in this case).
+
 ### Paths private to the toolstack
 
 #### ~/device-model/$DOMID/state [w]
Signature · 1 line
2.1.4
#7 lore raw

Re: [PATCH v5 4/4] docs: Introduce xenstore paths for guest network address information

Quoted 3 lines · Paul Durrant

This patch documents paths to allow a domain to advertise an interface name, MAC (unicast and multicast) and IP (version 4 and 6) address information.

How does the domU do that in practice?
With some variant of xenstore-write or with the PV vif driver? Last time I tried to use xenstore* commands in domU it was unable to use relative paths, which forced me to specify the domid value for the paths. Might be a usage error on my side, or just a bug in the xenstore commands.

Olaf

#8 lore raw

Re: [PATCH v5 4/4] docs: Introduce xenstore paths for guest network address information

Quoted 9 lines

-----Original Message-----
From: Olaf Hering [mailto:[email protected]]
Sent: 18 November 2015 12:00
To: Paul Durrant
Cc: [email protected]; Keir (Xen.org); Ian Campbell; Tim (Xen.org); Ian Jackson; Jan Beulich
Subject: Re: [Xen-devel] [PATCH v5 4/4] docs: Introduce xenstore paths for guest network address information

Quoted 8 lines
Quoted 3 lines · Paul Durrant

This patch documents paths to allow a domain to advertise an interface name, MAC (unicast and multicast) and IP (version 4 and 6) address information.

How does the domU do that in practice?
With some variant of xenstore-write or with the PV vif driver?

In the case of Windows, the IP helper is available to the XENVIF driver so it will do the xenstore writes using the XENBUS_STORE interface provided by the XENBUS driver.

Quoted 5 lines

Last time I tried to use xenstore* commands in domU it was unable to use relative paths, which forced me to specify the domid value for the paths. Might be a usage error on my side, or just a bug in the xenstore commands.

I've not had an issue with using relative paths in Windows so I guess it's an implementation issue in whatever frontend OS you are using.

Paul

Quoted 2 lines

Olaf

#9 lore raw

Re: [PATCH v5 4/4] docs: Introduce xenstore paths for guest network address information

In reply to Olaf Hering
Quoted 11 lines · Olaf Hering
Quoted 3 lines · Paul Durrant

This patch documents paths to allow a domain to advertise an interface name, MAC (unicast and multicast) and IP (version 4 and 6) address information.

How does the domU do that in practice?
With some variant of xenstore-write or with the PV vif driver? Last time I tried to use xenstore* commands in domU it was unable to use relative paths, which forced me to specify the domid value for the paths. Might be a usage error on my side, or just a bug in the xenstore commands.

Where possible, the frontends themselves ought to be in charge of keeping this information up to date.

This will reduce the dependence on an ancillary userspace component, and make it less likely for the information to go stale.

~Andrew

Acked-by on v5 4/4
#10 lore raw

Re: [PATCH v5 4/4] docs: Introduce xenstore paths for guest network address information

In reply to Paul Durrant

Paul Durrant writes ("[PATCH v5 4/4] docs: Introduce xenstore paths for guest network address information"):

Quoted 8 lines

It is useful for a toolstack to be able to see the network addresses in use by a domain for a particular vif in xenstore for display purposes and, for example, so that a VNC session can be established to the guest GUI.

This patch documents paths to allow a domain to advertise an interface name, MAC (unicast and multicast) and IP (version 4 and 6) address information.

#11 lore raw
In reply to Paul Durrant

On Tue, 2015-11-17 at 11:32 +0000, Paul Durrant wrote:

All applied with Ian's acks.

Quoted 16 lines

Patch #1 documents paths, some already in used by XenServer, which can be used by guests to advertise contol capabilities.

Patch #2 documents paths which can be used to advertise PV driver versions.

Patch #3 documents paths which can be used by guests to advertise hotplug capabilities.

Patch #4 documents paths which can be used by guests to advertise network addresses.

_______________________________________________
Xen-devel mailing list
[email protected]
http://lists.xen.org/xen-devel