| Message ID | 20250311073131.13539-1-jgross@suse.com (mailing list archive) |
|---|---|
| State | Superseded |
| Headers | show |
| Series | [v2] docs: specify numerical values of Xenstore commands | expand |
Hi Juergen, On 11/03/2025 07:31, Juergen Gross wrote: > In docs/misc/xenstore.txt all Xenstore commands are specified, but > the specifications lack the numerical values of the commands. > > Add a table with all commands, their values, and a potential remark > (e.g. whether the command is optional). > > Reported-by: Jan Beulich <jbeulich@suse.com> > Signed-off-by: Juergen Gross <jgross@suse.com> > --- > V2: > - replace "ŕ" with plain "r" (Jan Beulich) > - replace hard tabs with blanks (Jan Beulich) > - allow GET_FEATURES and GET_QUOTA support without SET_* (Jan Beulich) > --- > docs/misc/xenstore.txt | 57 ++++++++++++++++++++++++++++++++++++++++++ > 1 file changed, 57 insertions(+) > > diff --git a/docs/misc/xenstore.txt b/docs/misc/xenstore.txt > index 7e1f031520..8b4b790e11 100644 > --- a/docs/misc/xenstore.txt > +++ b/docs/misc/xenstore.txt > @@ -86,6 +86,63 @@ parts of xenstore inaccessible to some clients. In any case passing > bulk data through xenstore is not recommended as the performance > properties are poor. > > +---------- Defined Xenstore message types ---------- > + > +Below is a table with all defined Xenstore message types (type name > +and its associated numerical value). > + > +Some types are optional to be supported by a specific Xenstore > +implementation. If an optional type is not supported by a Xenstore > +implementation, Xen tools will continue to work, maybe with slightly > +reduced functionality. A mandatory type not being supported will > +result in severely reduced functionality, like inability to create > +domains. In case a type is optional, this is stated in the table with > +the lost functionality in case Xenstore doesn't support that type. > + > +XS_CONTROL 0 optional > + If not supported, xenstore-control command will not work. Are we documenting anywhere how a user could figure out if the command is not supported? Is it a specific error code? > + XS_DEBUG is a deprecated alias of XS_CONTROL. > +XS_DIRECTORY 1> +XS_READ 2 > +XS_GET_PERMS 3 > +XS_WATCH 4 > +XS_UNWATCH 5 > +XS_TRANSACTION_START 6 > +XS_TRANSACTION_END 7 > +XS_INTRODUCE 8 > +XS_RELEASE 9 > +XS_GET_DOMAIN_PATH 10 > +XS_WRITE 11 > +XS_MKDIR 12 > +XS_RM 13 > +XS_SET_PERMS 14 > +XS_WATCH_EVENT 15 > + Not valid in client sent messages. > + Only valid in Xenstore replies. > +XS_ERROR 16 > + Not valid in client sent messages. > + Only valid in Xenstore replies. > +XS_IS_DOMAIN_INTRODUCED 17 > +XS_RESUME 18 > +XS_SET_TARGET 19 > +XS_RESTRICT 20 no longer supported > + XS_RESTRICT has been removed, the type value 20 is invalid. > +XS_RESET_WATCHES 21 > +XS_DIRECTORY_PART 22 optional > + If not supported, the output of xenstore-ls might be incomplete > + with more than ca. 1000 domains active. Why are we making this specific to number of domains? Wouldn't the problem be the same if you have 1000 node within a parent node? > +XS_GET_FEATURE 23 optional > +XS_SET_FEATURE 24 optional > + XS_SET_FEATURE requires XS_GET_FEATURE to be supported. > + If unsupported, setting availability of Xenstore features per > + domain is not possible. > +XS_GET_QUOTA 25 optional > +XS_SET_QUOTA 26 optional > + XS_SET_QUOTA requires XS_GET_QUOTA to be supported. > + If unsupported, setting of Xenstore quota per domain is not > + possible. > +XS_INVALID 65535 > + Guaranteed invalid type (never supported). > > ---------- Xenstore protocol details - introduction ---------- > Cheers,
On 11.03.25 10:21, Julien Grall wrote: > Hi Juergen, > > On 11/03/2025 07:31, Juergen Gross wrote: >> In docs/misc/xenstore.txt all Xenstore commands are specified, but >> the specifications lack the numerical values of the commands. >> >> Add a table with all commands, their values, and a potential remark >> (e.g. whether the command is optional). >> >> Reported-by: Jan Beulich <jbeulich@suse.com> >> Signed-off-by: Juergen Gross <jgross@suse.com> >> --- >> V2: >> - replace "ŕ" with plain "r" (Jan Beulich) >> - replace hard tabs with blanks (Jan Beulich) >> - allow GET_FEATURES and GET_QUOTA support without SET_* (Jan Beulich) >> --- >> docs/misc/xenstore.txt | 57 ++++++++++++++++++++++++++++++++++++++++++ >> 1 file changed, 57 insertions(+) >> >> diff --git a/docs/misc/xenstore.txt b/docs/misc/xenstore.txt >> index 7e1f031520..8b4b790e11 100644 >> --- a/docs/misc/xenstore.txt >> +++ b/docs/misc/xenstore.txt >> @@ -86,6 +86,63 @@ parts of xenstore inaccessible to some clients. In any >> case passing >> bulk data through xenstore is not recommended as the performance >> properties are poor. >> +---------- Defined Xenstore message types ---------- >> + >> +Below is a table with all defined Xenstore message types (type name >> +and its associated numerical value). >> + >> +Some types are optional to be supported by a specific Xenstore >> +implementation. If an optional type is not supported by a Xenstore >> +implementation, Xen tools will continue to work, maybe with slightly >> +reduced functionality. A mandatory type not being supported will >> +result in severely reduced functionality, like inability to create >> +domains. In case a type is optional, this is stated in the table with >> +the lost functionality in case Xenstore doesn't support that type. >> + >> +XS_CONTROL 0 optional >> + If not supported, xenstore-control command will not work. > > Are we documenting anywhere how a user could figure out if the command is not > supported? Is it a specific error code? I can add that not supported commands will return "ENOSYS" as an error response. > >> + XS_DEBUG is a deprecated alias of XS_CONTROL. > > +XS_DIRECTORY 1> +XS_READ 2 >> +XS_GET_PERMS 3 >> +XS_WATCH 4 >> +XS_UNWATCH 5 >> +XS_TRANSACTION_START 6 >> +XS_TRANSACTION_END 7 >> +XS_INTRODUCE 8 >> +XS_RELEASE 9 >> +XS_GET_DOMAIN_PATH 10 >> +XS_WRITE 11 >> +XS_MKDIR 12 >> +XS_RM 13 >> +XS_SET_PERMS 14 >> +XS_WATCH_EVENT 15 >> + Not valid in client sent messages. >> + Only valid in Xenstore replies. >> +XS_ERROR 16 >> + Not valid in client sent messages. >> + Only valid in Xenstore replies. >> +XS_IS_DOMAIN_INTRODUCED 17 >> +XS_RESUME 18 >> +XS_SET_TARGET 19 >> +XS_RESTRICT 20 no longer supported >> + XS_RESTRICT has been removed, the type value 20 is invalid. >> +XS_RESET_WATCHES 21 >> +XS_DIRECTORY_PART 22 optional >> + If not supported, the output of xenstore-ls might be incomplete >> + with more than ca. 1000 domains active. > > Why are we making this specific to number of domains? Wouldn't the problem be > the same if you have 1000 node within a parent node? Let me reiterate the answer I gave to Jan when he asked: And elsewhere there can't be very many nodes resulting in a similar situation? Not without someone trying to force this by will (only possible by a root user of dom0, e.g. via creating lots of nodes in the same directory via "xenstore-write"). Having lots of domains is an "easy" way to create this scenario via perfectly valid and sensible operations. I can rephrase the remark like this: If not supported, the output of xenstore-ls might be incomplete with a node's sub-node list exceeding the maximum payload size (e.g. the "/local/domain" node with more than ca. 1000 domains active). Juergen
Hi Juergen, On 11/03/2025 09:40, Jürgen Groß wrote: > On 11.03.25 10:21, Julien Grall wrote: >> Hi Juergen, >> >> On 11/03/2025 07:31, Juergen Gross wrote: >>> In docs/misc/xenstore.txt all Xenstore commands are specified, but >>> the specifications lack the numerical values of the commands. >>> >>> Add a table with all commands, their values, and a potential remark >>> (e.g. whether the command is optional). >>> >>> Reported-by: Jan Beulich <jbeulich@suse.com> >>> Signed-off-by: Juergen Gross <jgross@suse.com> >>> --- >>> V2: >>> - replace "ŕ" with plain "r" (Jan Beulich) >>> - replace hard tabs with blanks (Jan Beulich) >>> - allow GET_FEATURES and GET_QUOTA support without SET_* (Jan Beulich) >>> --- >>> docs/misc/xenstore.txt | 57 ++++++++++++++++++++++++++++++++++++++++++ >>> 1 file changed, 57 insertions(+) >>> >>> diff --git a/docs/misc/xenstore.txt b/docs/misc/xenstore.txt >>> index 7e1f031520..8b4b790e11 100644 >>> --- a/docs/misc/xenstore.txt >>> +++ b/docs/misc/xenstore.txt >>> @@ -86,6 +86,63 @@ parts of xenstore inaccessible to some clients. >>> In any case passing >>> bulk data through xenstore is not recommended as the performance >>> properties are poor. >>> +---------- Defined Xenstore message types ---------- >>> + >>> +Below is a table with all defined Xenstore message types (type name >>> +and its associated numerical value). >>> + >>> +Some types are optional to be supported by a specific Xenstore >>> +implementation. If an optional type is not supported by a Xenstore >>> +implementation, Xen tools will continue to work, maybe with slightly >>> +reduced functionality. A mandatory type not being supported will >>> +result in severely reduced functionality, like inability to create >>> +domains. In case a type is optional, this is stated in the table with >>> +the lost functionality in case Xenstore doesn't support that type. >>> + >>> +XS_CONTROL 0 optional >>> + If not supported, xenstore-control command will not work. >> >> Are we documenting anywhere how a user could figure out if the command >> is not supported? Is it a specific error code? > > I can add that not supported commands will return "ENOSYS" as an error > response. Yes please. > >> >>> + XS_DEBUG is a deprecated alias of XS_CONTROL. >> > +XS_DIRECTORY 1> +XS_READ 2 >>> +XS_GET_PERMS 3 >>> +XS_WATCH 4 >>> +XS_UNWATCH 5 >>> +XS_TRANSACTION_START 6 >>> +XS_TRANSACTION_END 7 >>> +XS_INTRODUCE 8 >>> +XS_RELEASE 9 >>> +XS_GET_DOMAIN_PATH 10 >>> +XS_WRITE 11 >>> +XS_MKDIR 12 >>> +XS_RM 13 >>> +XS_SET_PERMS 14 >>> +XS_WATCH_EVENT 15 >>> + Not valid in client sent messages. >>> + Only valid in Xenstore replies. >>> +XS_ERROR 16 >>> + Not valid in client sent messages. >>> + Only valid in Xenstore replies. >>> +XS_IS_DOMAIN_INTRODUCED 17 >>> +XS_RESUME 18 >>> +XS_SET_TARGET 19 >>> +XS_RESTRICT 20 no longer supported >>> + XS_RESTRICT has been removed, the type value 20 is invalid. >>> +XS_RESET_WATCHES 21 >>> +XS_DIRECTORY_PART 22 optional >>> + If not supported, the output of xenstore-ls might be incomplete >>> + with more than ca. 1000 domains active. >> >> Why are we making this specific to number of domains? Wouldn't the >> problem be the same if you have 1000 node within a parent node? > > Let me reiterate the answer I gave to Jan when he asked: > > And elsewhere there can't be very many nodes resulting in a similar > situation? > > Not without someone trying to force this by will (only possible by a > root user of dom0, e.g. via creating lots of nodes in the same directory > via "xenstore-write"). That's assuming the admin has not changed the default quotas, right? > > Having lots of domains is an "easy" way to create this scenario via > perfectly valid and sensible operations. > > > I can rephrase the remark like this: > > If not supported, the output of xenstore-ls might be incomplete > with a node's sub-node list exceeding the maximum payload size > (e.g. the "/local/domain" node with more than ca. 1000 domains > active). That would be better. It doesn't tie the problem to the default quotas. Cheers,
On 11.03.25 20:36, Julien Grall wrote: > Hi Juergen, > > On 11/03/2025 09:40, Jürgen Groß wrote: >> On 11.03.25 10:21, Julien Grall wrote: >>> Hi Juergen, >>> >>> On 11/03/2025 07:31, Juergen Gross wrote: >>>> In docs/misc/xenstore.txt all Xenstore commands are specified, but >>>> the specifications lack the numerical values of the commands. >>>> >>>> Add a table with all commands, their values, and a potential remark >>>> (e.g. whether the command is optional). >>>> >>>> Reported-by: Jan Beulich <jbeulich@suse.com> >>>> Signed-off-by: Juergen Gross <jgross@suse.com> >>>> --- >>>> V2: >>>> - replace "ŕ" with plain "r" (Jan Beulich) >>>> - replace hard tabs with blanks (Jan Beulich) >>>> - allow GET_FEATURES and GET_QUOTA support without SET_* (Jan Beulich) >>>> --- >>>> docs/misc/xenstore.txt | 57 ++++++++++++++++++++++++++++++++++++++++++ >>>> 1 file changed, 57 insertions(+) >>>> >>>> diff --git a/docs/misc/xenstore.txt b/docs/misc/xenstore.txt >>>> index 7e1f031520..8b4b790e11 100644 >>>> --- a/docs/misc/xenstore.txt >>>> +++ b/docs/misc/xenstore.txt >>>> @@ -86,6 +86,63 @@ parts of xenstore inaccessible to some clients. In any >>>> case passing >>>> bulk data through xenstore is not recommended as the performance >>>> properties are poor. >>>> +---------- Defined Xenstore message types ---------- >>>> + >>>> +Below is a table with all defined Xenstore message types (type name >>>> +and its associated numerical value). >>>> + >>>> +Some types are optional to be supported by a specific Xenstore >>>> +implementation. If an optional type is not supported by a Xenstore >>>> +implementation, Xen tools will continue to work, maybe with slightly >>>> +reduced functionality. A mandatory type not being supported will >>>> +result in severely reduced functionality, like inability to create >>>> +domains. In case a type is optional, this is stated in the table with >>>> +the lost functionality in case Xenstore doesn't support that type. >>>> + >>>> +XS_CONTROL 0 optional >>>> + If not supported, xenstore-control command will not work. >>> >>> Are we documenting anywhere how a user could figure out if the command is not >>> supported? Is it a specific error code? >> >> I can add that not supported commands will return "ENOSYS" as an error >> response. > > Yes please. > >> >>> >>>> + XS_DEBUG is a deprecated alias of XS_CONTROL. >>> > +XS_DIRECTORY 1> +XS_READ 2 >>>> +XS_GET_PERMS 3 >>>> +XS_WATCH 4 >>>> +XS_UNWATCH 5 >>>> +XS_TRANSACTION_START 6 >>>> +XS_TRANSACTION_END 7 >>>> +XS_INTRODUCE 8 >>>> +XS_RELEASE 9 >>>> +XS_GET_DOMAIN_PATH 10 >>>> +XS_WRITE 11 >>>> +XS_MKDIR 12 >>>> +XS_RM 13 >>>> +XS_SET_PERMS 14 >>>> +XS_WATCH_EVENT 15 >>>> + Not valid in client sent messages. >>>> + Only valid in Xenstore replies. >>>> +XS_ERROR 16 >>>> + Not valid in client sent messages. >>>> + Only valid in Xenstore replies. >>>> +XS_IS_DOMAIN_INTRODUCED 17 >>>> +XS_RESUME 18 >>>> +XS_SET_TARGET 19 >>>> +XS_RESTRICT 20 no longer supported >>>> + XS_RESTRICT has been removed, the type value 20 is invalid. >>>> +XS_RESET_WATCHES 21 >>>> +XS_DIRECTORY_PART 22 optional >>>> + If not supported, the output of xenstore-ls might be incomplete >>>> + with more than ca. 1000 domains active. >>> >>> Why are we making this specific to number of domains? Wouldn't the problem be >>> the same if you have 1000 node within a parent node? >> >> Let me reiterate the answer I gave to Jan when he asked: > > > And elsewhere there can't be very many nodes resulting in a similar >> situation? > > > Not without someone trying to force this by will (only possible by a >> root user of dom0, e.g. via creating lots of nodes in the same directory >> via "xenstore-write"). > > That's assuming the admin has not changed the default quotas, right? No, I don't think this is related to quotas. This is purely related to the fact that XS_DIRECTORY is not capable to return a full list of the node's children, as this list would exceed XENSTORE_PAYLOAD_MAX, which is a hard wired part of the protocol. > >> >> Having lots of domains is an "easy" way to create this scenario via >> perfectly valid and sensible operations. > > > >> I can rephrase the remark like this: >> >> If not supported, the output of xenstore-ls might be incomplete >> with a node's sub-node list exceeding the maximum payload size >> (e.g. the "/local/domain" node with more than ca. 1000 domains >> active). > > > That would be better. It doesn't tie the problem to the default quotas. I'll use that then. Juergen
diff --git a/docs/misc/xenstore.txt b/docs/misc/xenstore.txt index 7e1f031520..8b4b790e11 100644 --- a/docs/misc/xenstore.txt +++ b/docs/misc/xenstore.txt @@ -86,6 +86,63 @@ parts of xenstore inaccessible to some clients. In any case passing bulk data through xenstore is not recommended as the performance properties are poor. +---------- Defined Xenstore message types ---------- + +Below is a table with all defined Xenstore message types (type name +and its associated numerical value). + +Some types are optional to be supported by a specific Xenstore +implementation. If an optional type is not supported by a Xenstore +implementation, Xen tools will continue to work, maybe with slightly +reduced functionality. A mandatory type not being supported will +result in severely reduced functionality, like inability to create +domains. In case a type is optional, this is stated in the table with +the lost functionality in case Xenstore doesn't support that type. + +XS_CONTROL 0 optional + If not supported, xenstore-control command will not work. + XS_DEBUG is a deprecated alias of XS_CONTROL. +XS_DIRECTORY 1 +XS_READ 2 +XS_GET_PERMS 3 +XS_WATCH 4 +XS_UNWATCH 5 +XS_TRANSACTION_START 6 +XS_TRANSACTION_END 7 +XS_INTRODUCE 8 +XS_RELEASE 9 +XS_GET_DOMAIN_PATH 10 +XS_WRITE 11 +XS_MKDIR 12 +XS_RM 13 +XS_SET_PERMS 14 +XS_WATCH_EVENT 15 + Not valid in client sent messages. + Only valid in Xenstore replies. +XS_ERROR 16 + Not valid in client sent messages. + Only valid in Xenstore replies. +XS_IS_DOMAIN_INTRODUCED 17 +XS_RESUME 18 +XS_SET_TARGET 19 +XS_RESTRICT 20 no longer supported + XS_RESTRICT has been removed, the type value 20 is invalid. +XS_RESET_WATCHES 21 +XS_DIRECTORY_PART 22 optional + If not supported, the output of xenstore-ls might be incomplete + with more than ca. 1000 domains active. +XS_GET_FEATURE 23 optional +XS_SET_FEATURE 24 optional + XS_SET_FEATURE requires XS_GET_FEATURE to be supported. + If unsupported, setting availability of Xenstore features per + domain is not possible. +XS_GET_QUOTA 25 optional +XS_SET_QUOTA 26 optional + XS_SET_QUOTA requires XS_GET_QUOTA to be supported. + If unsupported, setting of Xenstore quota per domain is not + possible. +XS_INVALID 65535 + Guaranteed invalid type (never supported). ---------- Xenstore protocol details - introduction ----------
In docs/misc/xenstore.txt all Xenstore commands are specified, but the specifications lack the numerical values of the commands. Add a table with all commands, their values, and a potential remark (e.g. whether the command is optional). Reported-by: Jan Beulich <jbeulich@suse.com> Signed-off-by: Juergen Gross <jgross@suse.com> --- V2: - replace "ŕ" with plain "r" (Jan Beulich) - replace hard tabs with blanks (Jan Beulich) - allow GET_FEATURES and GET_QUOTA support without SET_* (Jan Beulich) --- docs/misc/xenstore.txt | 57 ++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 57 insertions(+)