docs: Document xenstore paths
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.
PATCH 1/4 docs: Document control features the can be advertised by guests...
...via xenstore.
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-halt: PV drivers/agent can halt 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.
--- docs/misc/xenstore-paths.markdown | 38 +++++++++++++++++++++++++++++++++++--- 1 file changed, 35 insertions(+), 3 deletions(-)
docs/misc/xenstore-paths.markdown +35 -3
@@ -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
@@ -321,12 +321,44 @@ by udev ("0") or will be run by the toolstack directly ("1"). #### ~/control/shutdown = (""|COMMAND) [w] This is the PV shutdown control node. A toolstack can write various -commands here to cause various guest shutdown, reboot or suspend +commands here to cause various guest halt, reboot or suspend activities. The guest acknowledges a request by writing the empty string back to the command node. The precise protocol is not yet documented. +#### ~/control/feature-halt = (""|"0"|"1") [w] + +This is initialized to "" by the toolstack but may be set to 0 or 1 by +a guest to indicate that it is capable or incapable, respectively, of +halting if 'halt' is written to ~/control/shutdown. + +#### ~/control/feature-reboot = (""|"0"|"1") [w] + +This is initialized to "" by the toolstack but may be set to 0 or 1 by +a guest to indicate that it is capable or incapable, respectively, of +rebooting if 'reboot' is written to ~/control/shutdown. + +#### ~/control/feature-suspend = (""|"0"|"1") [w] + +This is initialized to "" by the toolstack but may be set to 0 or 1 by +a guest to indicate that it is capable or incapable, respectively, of +suspending if 'suspend' is written to ~/control/shutdown. + +#### ~/control/feature-s3 = (""|"0"|"1") [w,HVM] + +This is initialized to "" by the toolstack but may be set to 0 or 1 by +a guest to indicate that it is capable or incapable, respectively, of +triggering a guest sleep if 's3' is written to ~/control/shutdown and +~/platform/acpi_s3 is 1. + +#### ~/control/feature-s4 = (""|"0"|"1") [w,HVM] + +This is initialized to "" by the toolstack but may be set to 0 or 1 by +a guest to indicate that it is capable or incapable, respectively, of +triggering a guest hibernate if 's4' is written to ~/control/shutdown +and ~/platform/acpi_s4 is 1. + #### ~/control/platform-feature-multiprocessor-suspend = (0|1) [] Indicates to the guest that this platform supports the multiprocessor
Signature · 1 line
2.1.4
Re: [PATCH 1/4] docs: Document control features the can be advertised by guests...
Quoted 10 lines
Quoted 1 line
Quoted 1 line · On 06.11.15 at 18:21, <[email protected]> wrote:
...via xenstore.
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).
If these can't be set by a guest with the current default toolstack anyway, what's the point of documenting them (the more without warning about that fact in the text being added)?
Jan
Re: [PATCH 1/4] docs: Document control features the can be advertised by guests...
Quoted 20 lines
-----Original Message-----
From: Jan Beulich [mailto:[email protected]]
Sent: 09 November 2015 10:44
To: Paul Durrant
Cc: Ian Campbell; Ian Jackson; [email protected]; Keir (Xen.org); Tim (Xen.org)
Subject: Re: [PATCH 1/4] docs: Document control features the can be advertised by guests...Quoted 10 lines
Quoted 1 line
Quoted 1 line · On 06.11.15 at 18:21, <[email protected]> wrote:
...via xenstore.
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).
Quoted 4 lines
If these can't be set by a guest with the current default toolstack anyway, what's the point of documenting them (the more without warning about that fact in the text being added)?
Because I want to add them to libxl.
Paul
Quoted 1 line
Jan
PATCH 2/4 docs: Document a xenstore path for PV driver version information...
In reply to Paul Durrant...to be advertised by a guest.
For domain management purposes it is convenient to be able to see PV driver version information 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.
--- docs/misc/xenstore-paths.markdown | 10 ++++++++++ 1 file changed, 10 insertions(+)
docs/misc/xenstore-paths.markdown +10 -0
@@ -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 +* $NAME -- a string identifying an object within a domain. Typically + comprising only alphanumeric characters. VALUES are strings and can take the following forms:
@@ -51,6 +53,9 @@ 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 ")". +* VERSION -- 2 or 3 integers, in decimal form separated by ".", + specifying major version, minor version, and then + (optionally) micro version. Additional TAGS may follow as a comma separated set of the following tags enclosed in square brackets.
@@ -377,6 +382,11 @@ protocol definition. A domain writable path. Available for arbitrary domain use. +#### ~/drivers/$NAME/version = VERSION [w] + +A domain may write version information for PV driver $NAME using +this path. + ### Paths private to the toolstack #### ~/device-model/$DOMID/state [w]
Signature · 1 line
2.1.4
Re: [PATCH 2/4] docs: Document a xenstore path for PV driver version information...
Quoted 33 lines · Paul Durrant
...to be advertised by a guest.
For domain management purposes it is convenient to be able to see PV driver version information 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.
Signed-off-by Paul Durrant <[email protected]>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]>--- docs/misc/xenstore-paths.markdown | 10 ++++++++++ 1 file changed, 10 insertions(+)docs/misc/xenstore-paths.markdown +2
-0@@ -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 +* $NAME -- a string identifying an object within a domain. Typically + comprising only alphanumeric characters. VALUES are strings and can take the following forms:
docs/misc/xenstore-paths.markdown VALUES are strings and can take the following forms: · line 58
Quoted 6 lines
docs/misc/xenstore-paths.markdown +3
-0@@ -51,6 +53,9 @@ 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 ")". +* VERSION -- 2 or 3 integers, in decimal form separated by ".", + specifying major version, minor version, and then + (optionally) micro version.
I am not sure version should come with a restriction like this. For debug builds, it might be common to have a suffix. Furthermore, not all software conforms to the $MAJOR.$MINOR.$MICRO scheme.
I would just leave it specified as a "string which identifies the version of the driver", without any specific restrictions
~Andrew
PATCH 2/4 docs: Document a path for PV driver version information...
In reply to Paul Durrant...to be advertised by a guest.
For domain management purposes it is convenient to be able to see PV driver version information 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.
--- docs/misc/xenstore-paths.markdown | 10 ++++++++++ 1 file changed, 10 insertions(+)
docs/misc/xenstore-paths.markdown +10 -0
@@ -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 +* $NAME -- a string identifying an object within a domain. Typically + comprising only alphanumeric characters. VALUES are strings and can take the following forms:
@@ -51,6 +53,9 @@ 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 ")". +* VERSION -- 2 or 3 integers, in decimal form separated by ".", + specifying major version, minor version, and then + (optionally) micro version. Additional TAGS may follow as a comma separated set of the following tags enclosed in square brackets.
@@ -377,6 +382,11 @@ protocol definition. A domain writable path. Available for arbitrary domain use. +#### ~/drivers/$NAME/version = VERSION [w] + +A domain may write version information for PV driver $NAME using +this path. + ### Paths private to the toolstack #### ~/device-model/$DOMID/state [w]
Signature · 1 line
2.1.4
Re: [PATCH 2/4] docs: Document a path for PV driver version information...
Quoted 10 lines
-----Original Message-----
From: Paul Durrant [mailto:[email protected]]
Sent: 06 November 2015 17:22
To: [email protected]
Cc: Paul Durrant
Subject: [PATCH 2/4] docs: Document a path for PV driver version information......to be advertised by a guest.
Quoted 8 lines
For domain management purposes it is convenient to be able to see PV driver version information 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.
Signed-off-by Paul Durrant <[email protected]>
Sorry, this one is stale. It should not have been sent... Sorry for the noise.
Paul
Quoted 42 lines
--- docs/misc/xenstore-paths.markdown | 10 ++++++++++ 1 file changed, 10 insertions(+)docs/misc/xenstore- renamed from docs/misc/xenstore-paths.markdown +0
-0paths.markdown
index ec3cc5f..7701632 100644docs/misc/xenstore-paths.markdown +10
-1@@ -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 +* $NAME -- a string identifying an object within a domain. Typically + comprising only alphanumeric characters. VALUES are strings and can take the following forms:@@ -51,6 +53,9 @@ 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 ")". +* VERSION -- 2 or 3 integers, in decimal form separated by ".", + specifying major version, minor version, and then + (optionally) micro version. Additional TAGS may follow as a comma separated set of the following tags enclosed in square brackets.@@ -377,6 +382,11 @@ protocol definition. A domain writable path. Available for arbitrary domain use. +#### ~/drivers/$NAME/version = VERSION [w] + +A domain may write version information for PV driver $NAME using +this path. + ### Paths private to the toolstack #### ~/device-model/$DOMID/state [w] --2.1.4
PATCH 3/4 docs: Document xenstore paths for domain hotplug features
In reply to Paul DurrantWithout some indication from an HVM domain 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 instantiated in a guest. (In other words whether PV drivers are present and functioning).
This patch document two paths which vif and vbd frontend drivers can use to advertise their ability to respond to new vif or vbd instantiations.
--- docs/misc/xenstore-paths.markdown | 12 ++++++++++++ 1 file changed, 12 insertions(+)
docs/misc/xenstore-paths.markdown +12 -0
@@ -387,6 +387,18 @@ A domain writable path. Available for arbitrary domain use. A domain may write version information for PV driver $NAME using this path. +#### ~/feature/hotplug/vif = ("0"|"1") [w,HVM] + +An HVM domain can indicate to a toolstack that it is capable +of responding to instantiation of a new vif by bringing online a +new PV network device without the need for a reboot. + +#### ~/feature/hotplug/vbd = ("0"|"1") [w,HVM] + +An HVM domain can indicate to a toolstack that it is capable +of responding to instantiation of a new vbd by bringing online a +new PV block device without the need for a reboot. + ### Paths private to the toolstack #### ~/device-model/$DOMID/state [w]
Signature · 1 line
2.1.4
Re: [PATCH 3/4] docs: Document xenstore paths for domain hotplug features
Quoted 29 lines · Paul Durrant
Without some indication from an HVM domain 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 instantiated in a guest. (In other words whether PV drivers are present and functioning).
This patch document two paths which vif and vbd frontend drivers can use to advertise their ability to respond to new vif or vbd instantiations.
Signed-off-by Paul Durrant <[email protected]>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]>--- docs/misc/xenstore-paths.markdown | 12 ++++++++++++ 1 file changed, 12 insertions(+)docs/misc/xenstore-paths.markdown +1
-0@@ -387,6 +387,18 @@ A domain writable path. Available for arbitrary domain use. A domain may write version information for PV driver $NAME using this path. +#### ~/feature/hotplug/vif = ("0"|"1") [w,HVM]
docs/misc/xenstore-paths.markdown A domain writable path. Available for arbitrary domain use. · line 400
Quoted 10 lines
docs/misc/xenstore-paths.markdown +10
-0+ +An HVM domain can indicate to a toolstack that it is capable +of responding to instantiation of a new vif by bringing online a +new PV network device without the need for a reboot. + +#### ~/feature/hotplug/vbd = ("0"|"1") [w,HVM] + +An HVM domain can indicate to a toolstack that it is capable +of responding to instantiation of a new vbd by bringing online a +new PV block device without the need for a reboot.
These flags are not inherently restricted to HVM guests. Therefore, I would avoid specifying them as such. (It is quite possible for a PV guest not to be able to hotplug a vbd for example.)
~Andrew
Re: [PATCH 3/4] docs: Document xenstore paths for domain hotplug features
Quoted 39 lines
-----Original Message-----
From: Andrew Cooper [mailto:[email protected]]
Sent: 06 November 2015 18:08
To: Paul Durrant; [email protected]
Cc: Keir (Xen.org); Ian Campbell; Tim (Xen.org); Ian Jackson; Jan Beulich
Subject: Re: [Xen-devel] [PATCH 3/4] docs: Document xenstore paths for domain hotplug featuresdocs/misc/xenstore-
Quoted 21 lines · Paul Durrant
Without some indication from an HVM domain 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 instantiated in a guest. (In other words whether PV drivers are present and functioning).
This patch document two paths which vif and vbd frontend drivers can use to advertise their ability to respond to new vif or vbd instantiations.
Signed-off-by Paul Durrant <[email protected]>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]>--- docs/misc/xenstore-paths.markdown | 12 ++++++++++++ 1 file changed, 12 insertions(+)docs/misc/xenstore- renamed from docs/misc/xenstore-paths.markdown +0
-0paths.markdown
docs/misc/xenstore-paths.markdown A domain writable path. Available for arbitrary
Quoted 4 lines
index 7701632..9e98d6f 100644
docs/misc/xenstore-paths.markdown +0
-0@@ -387,6 +387,18 @@ A domain writable path. Available for arbitrarydomain use.
Quoted 3 lines
docs/misc/xenstore-paths.markdown +0
-0A domain may write version information for PV driver $NAME using this path.
Quoted 15 lines
docs/misc/xenstore-paths.markdown A domain writable path. Available for arbitrary domain use. · line 400
Quoted 11 lines
docs/misc/xenstore-paths.markdown +11
-0+#### ~/feature/hotplug/vif = ("0"|"1") [w,HVM] + +An HVM domain can indicate to a toolstack that it is capable +of responding to instantiation of a new vif by bringing online a +new PV network device without the need for a reboot. + +#### ~/feature/hotplug/vbd = ("0"|"1") [w,HVM] + +An HVM domain can indicate to a toolstack that it is capable +of responding to instantiation of a new vbd by bringing online a +new PV block device without the need for a reboot.These flags are not inherently restricted to HVM guests. Therefore, I would avoid specifying them as such. (It is quite possible for a PV guest not to be able to hotplug a vbd for example.)
I wasn't sure that was true. My belief was that all pure PV guests would have frontends handling hot attach. I'm happy to drop the HVM tag in v2 though.
Paul
Quoted 2 lines
~Andrew
Re: [PATCH 3/4] docs: Document xenstore paths for domain hotplug features
Quoted 56 lines
Quoted 40 lines
Quoted 1 line · On 09.11.15 at 10:51, <[email protected]> wrote:
-----Original Message-----
From: Andrew Cooper [mailto:[email protected]]
Sent: 06 November 2015 18:08
To: Paul Durrant; [email protected]
Cc: Keir (Xen.org); Ian Campbell; Tim (Xen.org); Ian Jackson; Jan Beulich
Subject: Re: [Xen-devel] [PATCH 3/4] docs: Document xenstore paths for domain hotplug featuresdocs/misc/xenstore-
Quoted 21 lines · Paul Durrant
Without some indication from an HVM domain 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 instantiated in a guest. (In other words whether PV drivers are present and functioning).
This patch document two paths which vif and vbd frontend drivers can use to advertise their ability to respond to new vif or vbd instantiations.
Signed-off-by Paul Durrant <[email protected]>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]>--- docs/misc/xenstore-paths.markdown | 12 ++++++++++++ 1 file changed, 12 insertions(+)docs/misc/xenstore- renamed from docs/misc/xenstore-paths.markdown +0
-0paths.markdown
docs/misc/xenstore-paths.markdown A domain writable path. Available for arbitrary
Quoted 4 lines
index 7701632..9e98d6f 100644
docs/misc/xenstore-paths.markdown +0
-0@@ -387,6 +387,18 @@ A domain writable path. Available for arbitrarydomain use.
Quoted 3 lines
docs/misc/xenstore-paths.markdown +0
-0A domain may write version information for PV driver $NAME using this path.Quoted 15 lines
docs/misc/xenstore-paths.markdown A domain writable path. Available for arbitrary domain use. · line 400
Quoted 11 lines
docs/misc/xenstore-paths.markdown +11
-0+#### ~/feature/hotplug/vif = ("0"|"1") [w,HVM] + +An HVM domain can indicate to a toolstack that it is capable +of responding to instantiation of a new vif by bringing online a +new PV network device without the need for a reboot. + +#### ~/feature/hotplug/vbd = ("0"|"1") [w,HVM] + +An HVM domain can indicate to a toolstack that it is capable +of responding to instantiation of a new vbd by bringing online a +new PV block device without the need for a reboot.These flags are not inherently restricted to HVM guests. Therefore, I would avoid specifying them as such. (It is quite possible for a PV guest not to be able to hotplug a vbd for example.)
Quoted 3 lines
I wasn't sure that was true. My belief was that all pure PV guests would have frontends handling hot attach. I'm happy to drop the HVM tag in v2 though.
With intermediate steps between HVM and PVH planned to become possible, I think not overly limiting the scope of such entries would indeed desirable.
Jan
Re: [PATCH 3/4] docs: Document xenstore paths for domain hotplug features
Quoted 64 lines
-----Original Message-----
From: Jan Beulich [mailto:[email protected]]
Sent: 09 November 2015 10:50
To: Andrew Cooper; Paul Durrant; [email protected]
Cc: Ian Campbell; Ian Jackson; Keir (Xen.org); Tim (Xen.org)
Subject: RE: [Xen-devel] [PATCH 3/4] docs: Document xenstore paths for domain hotplug featuresQuoted 56 lines
Quoted 55 lines
Quoted 1 line · On 09.11.15 at 10:51, <[email protected]> wrote:
-----Original Message-----
From: Andrew Cooper [mailto:[email protected]]
Sent: 06 November 2015 18:08
To: Paul Durrant; [email protected]
Cc: Keir (Xen.org); Ian Campbell; Tim (Xen.org); Ian Jackson; Jan Beulich
Subject: Re: [Xen-devel] [PATCH 3/4] docs: Document xenstore paths for domain hotplug featuresdocs/misc/xenstore-
Quoted 21 lines · Paul Durrant
Without some indication from an HVM domain 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 instantiated in a guest. (In other words whether PV drivers are present and functioning).
This patch document two paths which vif and vbd frontend drivers can use to advertise their ability to respond to new vif or vbd instantiations.
Signed-off-by Paul Durrant <[email protected]>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]>--- docs/misc/xenstore-paths.markdown | 12 ++++++++++++ 1 file changed, 12 insertions(+)docs/misc/xenstore- renamed from docs/misc/xenstore-paths.markdown +0
-0paths.markdown
docs/misc/xenstore-paths.markdown A domain writable path. Available for arbitrary
Quoted 4 lines
index 7701632..9e98d6f 100644
docs/misc/xenstore-paths.markdown +0
-0@@ -387,6 +387,18 @@ A domain writable path. Available for arbitrarydomain use.
Quoted 4 lines
docs/misc/xenstore-paths.markdown +1
-0A domain may write version information for PV driver $NAME using this path. +#### ~/feature/hotplug/vif = ("0"|"1") [w,HVM]docs/misc/xenstore-paths.markdown A domain writable path. Available for arbitrary domain use. · line 400
Quoted 10 lines
docs/misc/xenstore-paths.markdown +10
-0+ +An HVM domain can indicate to a toolstack that it is capable +of responding to instantiation of a new vif by bringing online a +new PV network device without the need for a reboot. + +#### ~/feature/hotplug/vbd = ("0"|"1") [w,HVM] + +An HVM domain can indicate to a toolstack that it is capable +of responding to instantiation of a new vbd by bringing online a +new PV block device without the need for a reboot.These flags are not inherently restricted to HVM guests. Therefore, I would avoid specifying them as such. (It is quite possible for a PV guest not to be able to hotplug a vbd for example.)
Quoted 8 lines
Quoted 3 lines
I wasn't sure that was true. My belief was that all pure PV guests would have frontends handling hot attach. I'm happy to drop the HVM tag in v2 though.
With intermediate steps between HVM and PVH planned to become possible, I think not overly limiting the scope of such entries would indeed desirable.
Ok.
Paul
Quoted 1 line
Jan
PATCH 4/4 docs: Document xenstore paths for domain network address information
In reply to Paul DurrantIt is useful to be able to see the network addresses in use by a domain for a particular vif in xenstore, for example so that ssh can be invoked by a toolstack to log into the guest domain.
This patch documents paths to allow a domain to advertise MAC (unicast and multicast) and IP (versions 4 and 6) address information.
--- docs/misc/xenstore-paths.markdown | 29 +++++++++++++++++++++++++++++ 1 file changed, 29 insertions(+)
docs/misc/xenstore-paths.markdown +29 -0
@@ -39,6 +39,8 @@ before regexp expansion: * $UUID -- a UUID in the form xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx * $NAME -- a string identifying an object within a domain. Typically comprising only alphanumeric characters. +* $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:
@@ -56,6 +58,13 @@ VALUES are strings and can take the following forms: * VERSION -- 2 or 3 integers, in decimal form separated by ".", specifying major version, minor version, and then (optionally) micro version. +* MAC_ADDRESS -- 6 integers, in hexadecimal form, separated by ':', + specifying an ethernet MAC address. +* IPV4_ADDRESS -- 4 integers, in decimal form, separated by '.', + specifying an IP version 4 address. +* IPV6_ADDRESS -- 8 integers, in hexadecimal form, separated by ':', + specifying an IP version 6 address. (There should + be strictly 8 integers i.e. '::' compression). Additional TAGS may follow as a comma separated set of the following tags enclosed in square brackets.
@@ -399,6 +408,26 @@ An HVM domain can indicate to a toolstack that it is capable of responding to instantiation of a new vbd by bringing online a new PV block device without the need for a reboot. +#### ~/attr/vif/$DEVID/name = STRING [w] + +A domain may write its internal 'friendly' name for a network device +using this path. + +#### ~/attr/vif/$DEVID/mac/$INDEX = MAC_ADDRESS [w] + +A domain may write the set of MAC addresses (unicast and multicast) +in use by the network frontend using paths of this form. + +#### ~/attr/vif/$DEVID/ipv4/$INDEX = IPV4_ADDRESS [w] + +A domain may write the set of IP version 4 addresses in use by the +stack bound to the network frontend using paths of this form. + +#### ~/attr/vif/$DEVID/ipv6/$INDEX = IPV6_ADDRESS [w] + +A domain may write the set of IP version 6 addresses in use by the +stack bound to the network frontend using paths of this form. + ### Paths private to the toolstack #### ~/device-model/$DOMID/state [w]
Signature · 1 line
2.1.4
Re: [PATCH 4/4] docs: Document xenstore paths for domain network address information
Quoted 31 lines · Paul Durrant
It is useful to be able to see the network addresses in use by a domain for a particular vif in xenstore, for example so that ssh can be invoked by a toolstack to log into the guest domain.
This patch documents paths to allow a domain to advertise MAC (unicast and multicast) and IP (versions 4 and 6) address information.
Signed-off-by Paul Durrant <[email protected]>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]>--- docs/misc/xenstore-paths.markdown | 29 +++++++++++++++++++++++++++++ 1 file changed, 29 insertions(+)docs/misc/xenstore-paths.markdown +2
-0@@ -39,6 +39,8 @@ before regexp expansion: * $UUID -- a UUID in the form xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx * $NAME -- a string identifying an object within a domain. Typically comprising only alphanumeric characters. +* $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:
docs/misc/xenstore-paths.markdown VALUES are strings and can take the following forms: · line 67
Quoted 10 lines
docs/misc/xenstore-paths.markdown +7
-0@@ -56,6 +58,13 @@ VALUES are strings and can take the following forms: * VERSION -- 2 or 3 integers, in decimal form separated by ".", specifying major version, minor version, and then (optionally) micro version. +* MAC_ADDRESS -- 6 integers, in hexadecimal form, separated by ':', + specifying an ethernet MAC address. +* IPV4_ADDRESS -- 4 integers, in decimal form, separated by '.', + specifying an IP version 4 address. +* IPV6_ADDRESS -- 8 integers, in hexadecimal form, separated by ':', + specifying an IP version 6 address. (There should + be strictly 8 integers i.e. '::' compression).
Given the "strictly", I presume you mean no "::" compression?
But why enforce that restriction? "::" compression is unambiguous and typically makes the addresses rather more human readable.
~Andrew
Re: [PATCH 4/4] docs: Document xenstore paths for domain network address information
Quoted 41 lines
-----Original Message-----
From: Andrew Cooper [mailto:[email protected]]
Sent: 06 November 2015 18:17
To: Paul Durrant; [email protected]
Cc: Keir (Xen.org); Ian Campbell; Tim (Xen.org); Ian Jackson; Jan Beulich
Subject: Re: [Xen-devel] [PATCH 4/4] docs: Document xenstore paths for domain network address informationQuoted 7 lines · Paul Durrant
It is useful to be able to see the network addresses in use by a domain for a particular vif in xenstore, for example so that ssh can be invoked by a toolstack to log into the guest domain.
This patch documents paths to allow a domain to advertise MAC (unicast and multicast) and IP (versions 4 and 6) address information.
Quoted 8 lines
Signed-off-by Paul Durrant <[email protected]>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]>--- docs/misc/xenstore-paths.markdown | 29+++++++++++++++++++++++++++++
docs/misc/xenstore-
Quoted 3 lines
1 file changed, 29 insertions(+)docs/misc/xenstore- renamed from docs/misc/xenstore-paths.markdown +0
-0paths.markdown
Quoted 12 lines
index 9e98d6f..68d3dbf 100644
docs/misc/xenstore-paths.markdown +2
-0@@ -39,6 +39,8 @@ before regexp expansion: * $UUID -- a UUID in the form xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx * $NAME -- a string identifying an object within a domain. Typically comprising only alphanumeric characters. +* $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:
Quoted 13 lines
docs/misc/xenstore-paths.markdown VALUES are strings and can take the following forms: · line 67
Quoted 11 lines
docs/misc/xenstore-paths.markdown +7
-0@@ -56,6 +58,13 @@ VALUES are strings and can take the following forms: * VERSION -- 2 or 3 integers, in decimal form separated by ".", specifying major version, minor version, and then (optionally) micro version. +* MAC_ADDRESS -- 6 integers, in hexadecimal form, separated by ':', + specifying an ethernet MAC address. +* IPV4_ADDRESS -- 4 integers, in decimal form, separated by '.', + specifying an IP version 4 address. +* IPV6_ADDRESS -- 8 integers, in hexadecimal form, separated by ':', + specifying an IP version 6 address. (There should + be strictly 8 integers i.e. '::' compression).Given the "strictly", I presume you mean no "::" compression?
Yes, I missed the 'no'
Quoted 4 lines
But why enforce that restriction? "::" compression is unambiguous and typically makes the addresses rather more human readable.
That's true but I didn't want to put the coding burden on the frontend. Defining it this way makes it a trivial printf into xenstore. Whatever picks the address up can do the compression afterwards before display. I suppose it would be better to allow compression but state that it's not required.
Paul
Quoted 1 line
~Andrew