Steven,

There's a discrepancy between documentation https://access.redhat.com/documentation/en-US/Red_Hat_Enterprise_Linux/7/html-single/High_Availability_Add-On_Reference/index.html and real state regarding cluster permissions. Can you take a look at it and fix the doc according to following:


2.2.2. Setting Cluster Permissions

It should be noted these permissions apply not only to web UI but also to all pcs commands that connect to pcsd.

For newly created clusters the hacluster user has full access to the cluster using pcsd (be it web UI or pcs commands connecting to pcsd). There are no other permissions set by default. It's not true the root user or members of the haclient group have access to the cluster as well.


4.5. Setting User Permissions

We should note there is another permissions system which applies when pcs connects to other nodes and link the section 2.2.2. Setting Cluster Permissions in the note.

In here it's true that by default, the root user and any user who is a member of the haclient group has full read/write access to the cluster configuration. However this sentence may be confusing as it is not specified what "cluster configuration" means while ACLs apply to only subset of pcs commands.


I'm thinking if sections 2.2.2 and 4.5 could be merged somehow into one section. The new section would explain there are two levels of permissions. When accessing cluster nodes from web UI or remotely using pcs, pcsd permissions are applied first and then ACLs are applied to commands that edit CIB. When running pcs commands on a cluster node, most of them don't connect to other nodes and then pcsd permissions don't apply. What do you think?


Let me know if you have any questions.

Tomas:

I'm not sure what it means to say "pcs commands connecting to pcsd".  Does that mean any command used remotely -- as in, from a remote or guest node?

Steven

Steven,

I think this will be tricky to document.

There are two kinds of pcs commands with respect to connecting to pcsd:
A) commands which do not connect to pcsd
B) commands which do connect to pcsd

Commands A) are those which run pacemaker or corosync (or other tools) directly on the local host, e.g. commands for editing CIB such as pcs resource, pcs constraint and so on. User runs pcs and pcs process runs the tools for the user.

Commands B) are those which connect to pcsd on local and/or other nodes over network. For example pcs cluster setup, adding and removing nodes and so on. User runs pcs, pcs process connects to pcsd over network and pcsd does the job for the user.

It doesn't matter if a command is run on a full stack or a remote / guest node.

To make it a bit more complicated, "pcs cluster start" belongs to group A) whereas "pcs cluster start --all" and "pcs cluster start node1 node2" belongs to group B). That's because starting other than local nodes must connect to them whereas for a local node the network part can be skipped. However when a non-root user runs "pcs cluster start", pcs connects to pcsd daemon on the local node to start the cluster, because an ordinary user isn't allowed to start cluster services whereas pcsd runs with root privileges.


Is it clearer now? I understand it's quite complicated. We should find a way to deal with this complexity in the documentation so users without knowledge of pcs internals can understand it.

Tomas:

I've been staring at this for a while and I think I'm coming up with an approach for documenting this, which is that the explanation needs to focus on "connects to other nodes" (and what that means) rather than "uses pcsd" -- since "uses pcsd" is an internal concept but "connects to other nodes" seems more user-level. Not that we shouldn't mention that these commands use pcsd, but it's a question of the basic straightforward focus of what we are explaining.

Also if I/we can come up with an explanation of what "connects to other nodes" means in terms that are not about the internal workings than everything else at issue here could be easier to explain -- for example, the issue with what we mean by "cluster configuration" in section 4.5.  Also the issue with the two different aspects of "pcs cluster start" can be explained in those terms (starting only on the local node verses starting on other nodes).

At least that's what I'm thinking now, I keep changing my mind :).  But this leads to a couple of questions:

1) Is "pcs cluster cib-push" a command that uses pcsd?  That is, does this command update the CIB file on all the nodes?

2) Is there a way to set the permissions for all pcs commands that connect to pcsd other than by using the GUI?  

Steven

(In reply to Steven J. Levine from comment #5)
> Tomas:
> 
> I've been staring at this for a while and I think I'm coming up with an
> approach for documenting this, which is that the explanation needs to focus
> on "connects to other nodes" (and what that means) rather than "uses pcsd"
> -- since "uses pcsd" is an internal concept but "connects to other nodes"
> seems more user-level. Not that we shouldn't mention that these commands use
> pcsd, but it's a question of the basic straightforward focus of what we are
> explaining.

I absolutely agree. My idea was to explain it to you in more details and internals to make sure there is no confusion. For the documentation however it's definitely better to hide the details as they are quite complex and unnecessary to describe.

> Also if I/we can come up with an explanation of what "connects to other
> nodes" means in terms that are not about the internal workings than
> everything else at issue here could be easier to explain -- for example, the
> issue with what we mean by "cluster configuration" in section 4.5.  Also the
> issue with the two different aspects of "pcs cluster start" can be explained
> in those terms (starting only on the local node verses starting on other
> nodes).

We are on the same page here.

> At least that's what I'm thinking now, I keep changing my mind :).  But this
> leads to a couple of questions:
> 
> 1) Is "pcs cluster cib-push" a command that uses pcsd?

No.

> That is, does this command update the CIB file on all the nodes?

When editing the CIB, no matter in which pcs command, pcs passes the new CIB to pacemaker on the local node only (by running the "cibadmin" pacemaker tool). Pacemaker is then responsible for synchronizing the CIB across the whole cluster.

> 2) Is there a way to set the permissions for all pcs commands that connect
> to pcsd other than by using the GUI?

Unfortunately not right now, there is a bz for it: bz1389214

Ok, I have an attempt to try to organize this.

I did not wholly combine the two sections under discussion because all of the GUI doc is contained in a single chapter -- so to include a section describing the GUI in a section that is otherwise all pcs didn't seem to work.  This is what I have come up with as a first attempt to redo this.

Section 4.5 on setting user permissions has been redone and reorganized:

http://jenkinscat.gsslab.pnq.redhat.com:8080/job/doc-Red_Hat_Enterprise_Linux-7-High_Availability_Add-On_Reference%20(html-single)/lastSuccessfulBuild/artifact/tmp/en-US/html-single/index.html#s1-accesscontrol-HAAR

I did not talk about "connecting to pcsd" -- the distinction I made is local vs connecting on a network. This might get a little hazy, but if we list out commands that fall in each category that should coce most things.

I then slightly redid the GUI section on setting uesr permissions, section 2.2:


http://jenkinscat.gsslab.pnq.redhat.com:8080/job/doc-Red_Hat_Enterprise_Linux-7-High_Availability_Add-On_Reference%20(html-single)/lastSuccessfulBuild/artifact/tmp/en-US/html-single/index.html#s2-clustpermissionsgui-HAAR

This slightly repeats what's in section 4.5, but not by much. As noted, I left this in the GUI chapter because you have to use the GUI.  When we add the ability to do this with pcs there's already a chapter to put that info in and we might be able to move more of this to chapter 4.

I didn't change section 2.3.4, on configuring ACLs with the GUI, although I did change the description referring to it in section 2.2.

http://jenkinscat.gsslab.pnq.redhat.com:8080/job/doc-Red_Hat_Enterprise_Linux-7-High_Availability_Add-On_Reference%20(html-single)/lastSuccessfulBuild/artifact/tmp/en-US/html-single/index.html#s2-guiaclset-HAAR

Are we any closer?

Steven

It looks very good.

I'm fine with keeping the two section separate. With all the inter-section links and repeated explanations I think it works nicely.

"connecting to pcsd" vs "connecting over a network" - Let's go with "over a network". Under the circumstances it's I think the best we can do.

4.5. Setting User Permissions
I would drop the note box. The thing is when a non-root user runs "pcs cluster start" it always goes over a network even though to localhost. I meant that part for you as an explanation and an example. I think it only complicates things in the doc.


Josef, can you take a look at the updated doc as well and let us know if you think this addresses the customer's issue? Do you have anything to add or change?

I have removed the note referenced in Comment 8.

I'm moving this to release pending but I'll reopen if further comments from Josef require more updates.

Updates are now on the Portal:

https://access.redhat.com/documentation/en-US/Red_Hat_Enterprise_Linux/7/html/High_Availability_Add-On_Reference/s1-accesscontrol-HAAR.html