"11.2.5.2. Using Mountbroker for Slaves" does not really explain when it is advised to use mountbroker (give an example or use-case). Some more details on the functionality would benefit the chapter.
Csaba, Niels has suggested us to add an example or use-case to enhance the usability of mountbroker feature. Could you help us by providing an example or use case for mountbroker? Thanks, Divya
The title and the opening paragraphs of 11.2.5.2: """ ### Using Mountbroker for Slaves `mountbroker` is a new service of glusterd. This service allows an unprivileged process to own a glusterfs mount by registering a label (and DSL (Domain-specific language) options ) with glusterd through a glusterd volfile. Using CLI, you can send a mount request to glusterd to receive an alias (symlink) of the mounted volume. On request from the agent, the unprivileged slave agents use the mountbroker service of glusterd to set up an auxiliary glusterfs mount for the agent in a special environment which ensures that the agent is only allowed to access with special parameters that provide administrative level access to the particular volume. """ are a great summary for mountbroker in general. And true it is, it cries for a concrete example to make it clear how it looks in action. However, I suggest to not go that route. As of my knowledge, there is no plan to expose mountbroker as a service for users. It's an internal service, manageable with hidden cli commands. Moreover, if we were coming to the point that it is to be exposed, then it should not be placed under geo-rep section, as the mountbroker service in general is not specific to geo-rep (it has some special support to geo-rep only at the syntax level). The "geo-rep-with-mountbroker" use case is much clear than "mountbroker-as-such", and it is self explanatory, because in fact it can be called the "geo-rep-with-unprivileged-ssh-slave" case. The corresponding explanation -- steps 1.-5. -- indeed look to be an example to me... So I suggest to change the emphasis in the section title and opening paragraphs and then we won't leave users puzzled with unnecessary new concepts (for example, knowing of the DSL counts as such). So a sketchy suggestion: """ ### Unprivileged gluster slave over ssh Geo-replication supports access to gluster slaves through ssh using an unprivileged account. This is the recommended way of usage, as reducing master's capabilities over slave to the necessary minimum is an important security measure. This feature relies on an internal service of glusterd called "mountbroker" that manages mounts for unprivileged slave accounts. Such a setup requires the administrator to do some extra steps and to configure glusterd with the appropriate mountbroker access control directives. We demonstrate this process via the example below. **To setup an auxiliary glusterfs mount for the agent**: ... etc. """ Please adjust terminology and wording to context if needed.
Csaba, The following is the revised version of your input: Geo-replication supports access to Gluster slaves through SSH using an unprivileged account. This method is recommended as it is more secure and it reduces the master's capabilities over slave to the minimum. This feature relies on "mountbroker", an internal service of glusterd which manages the mounts for unprivileged slave accounts. You must perform additional steps to configure glusterd with the appropriate mountbroker's access control directives. The above information seems to be incomplete without the explanation of what an unprivileged account is. Could you provide an brief/one line explanation of an unprivileged account. Thanks, Divya
Divya, the text is excellent but I'm uncertain what kind of clarification you need regarding "unprivileged account". It's a generic term, users are expected to be familiar with the Unix security model (http://en.wikipedia.org/wiki/Unix_security) and it's not in the document's scope to explain that. If you want to pin it down exactly, you can define it as "user account with non-zero uid".
I have updated the guide based on Neil's suggestion and Csaba's inputs. Updated documentation is available at: http://documentation-devel.engineering.redhat.com/docs/en-US/Red_Hat_Storage/2.0/html/Administration_Guide/chap-User_Guide-Geo_Rep-Preparation-Settingup_Slave.html
Moving this bug to VERIFIED state