Re: [PATCH] docs: clarify xenstore permission documentation

[Andrew Cooper <andrew.cooper3@xxxxxxxxxx>]

On 09/02/2023 2:41 pm, Juergen Gross wrote:
> In docs/misc/xenstore.txt the description of the Xenstore node access
> permissions is missing one important aspect, which can be found only
> in the code or in the wiki [1]:
>
> The first permission entry is defining the owner of the node via the
> domid, and the access rights for all domains NOT having a dedicated
> permission entry.
>
> Make that aspect clear in the official documentation.
>
> [1]: https://wiki.xenproject.org/wiki/XenBus#Permissions
>
> Signed-off-by: Juergen Gross <jgross@xxxxxxxx>

I feel as if Edvin deserves some kind of credit here, seeing as it was
his observation...

Also, CC to double check the wording.

~Andrew

> ---
>  docs/misc/xenstore.txt | 17 ++++++++++-------
>  1 file changed, 10 insertions(+), 7 deletions(-)
>
> diff --git a/docs/misc/xenstore.txt b/docs/misc/xenstore.txt
> index 8887e7df88..d807ef0709 100644
> --- a/docs/misc/xenstore.txt
> +++ b/docs/misc/xenstore.txt
> @@ -45,13 +45,16 @@ them to within 2048 bytes.  (See XENSTORE_*_PATH_MAX in 
> xs_wire.h.)
>  
>  Each node has one or multiple permission entries.  Permissions are
>  granted by domain-id, the first permission entry of each node specifies
> -the owner of the node.  Permissions of a node can be changed by the
> -owner of the node, the owner can only be modified by the control
> -domain (usually domain id 0).  The owner always has the right to read
> -and write the node, while other permissions can be setup to allow
> -read and/or write access.  When a domain is being removed from Xenstore
> -nodes owned by that domain will be removed together with all of those
> -nodes' children.
> +the owner of the node, who always has full access to the node (read and
> +write permission).  The access rights of the first entry specify the
> +allowed access for all domains not having a dedicated permission entry
> +(the default is "n", removing access for all domains not explicitly
> +added via additional permission entries).  Permissions of a node can be
> +changed by the owner of the node, the owner can only be modified by the
> +control domain (usually domain id 0).  Other permissions can be setup to
> +allow read and/or write access for other domains.  When a domain is
> +being removed from Xenstore nodes owned by that domain will be removed
> +together with all of those nodes' children.
>  
>  
>  Communication with xenstore is via either sockets, or event channel