GUACAMOLE-220: Document management of user groups and group membership.
diff --git a/src/chapters/administration.xml b/src/chapters/administration.xml
index 7a62c34..e33f735 100644
--- a/src/chapters/administration.xml
+++ b/src/chapters/administration.xml
@@ -6,10 +6,10 @@
<indexterm>
<primary>administration</primary>
</indexterm>
- <para>Users, connections, and active sessions can be administered from within the web interface
- if the underlying authentication module supports this. The only officially-supported
- authentication modules supporting this are the MySQL and PostgreSQL extensions, which are
- documented in <xref linkend="jdbc-auth"/>.</para>
+ <para>Users, user groups, connections, and active sessions can be administered from within the
+ web interface if the underlying authentication module supports this. The only
+ officially-supported authentication modules supporting this are the database extensions,
+ which are documented in <xref linkend="jdbc-auth"/>.</para>
<para>If you are using the default authentication mechanism, or another authentication
extension, this chapter probably does not apply to you, and the management options will not
be visible in the Guacamole interface. If, on the other hand, you are using one of the
@@ -19,7 +19,7 @@
<mediaobject>
<imageobject>
<imagedata fileref="images/guacamole-settings-sections.png" format="PNG"
- contentwidth="1.5in"/>
+ contentwidth="3.5in"/>
</imageobject>
<caption>
<para>Sections within the Guacamole settings screen.</para>
@@ -183,9 +183,120 @@
</mediaobject>
</screenshot>
</informalfigure>
+ <section xml:id="user-group-membership">
+ <title>Editing group membership</title>
+ <para>When editing a user, the groups that user is a member of may be modified within
+ the "Groups" section. By default, only groups that the user is already a member of
+ will be displayed. If you have permission to modify the user's membership within a
+ group, an "X" icon will be available next to that group's name. Clicking the "X"
+ will remove the user from that group, taking effect after the user is saved.</para>
+ <para>To add users to a group, the arrow next to the list of groups must be clicked to
+ expand the section and reveal all available groups. Available groups may then be
+ checked/unchecked to modify the user's membership within those groups:</para>
+ <informalfigure>
+ <screenshot>
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="images/edit-user-membership.png" format="PNG"
+ contentwidth="5in"/>
+ </imageobject>
+ <caption>
+ <para>Editing group membership of a user</para>
+ </caption>
+ </mediaobject>
+ </screenshot>
+ </informalfigure>
+ <para>If you have a large number of available groups, you can also enter search terms
+ within the "Filter" field to filter the list of groups by name.</para>
+ </section>
+ </section>
+ <section xml:id="user-group-management">
+ <title>User group management</title>
+ <indexterm>
+ <primary>user group management</primary>
+ </indexterm>
+ <indexterm>
+ <primary>user groups</primary>
+ </indexterm>
+ <indexterm>
+ <primary>groups</primary>
+ </indexterm>
+ <para>Clicking "Groups" within the list of settings sections will take you to the user group
+ management screen. Here you can add new groups and edit the properties and privileges of
+ existing groups. If you have a large number of user groups, you can also enter search
+ terms within the "Filter" field to filter the list of groups by name:</para>
+ <informalfigure>
+ <screenshot>
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="images/manage-groups.png" format="PNG"
+ contentwidth="5in"/>
+ </imageobject>
+ <caption>
+ <para>User group management interface</para>
+ </caption>
+ </mediaobject>
+ </screenshot>
+ </informalfigure>
+ <para>To add a new group, click the "New Group" button. This will take you to a screen where
+ you will be allowed to enter the details of the new group, including membership and any
+ permissions that members of the group should have.</para>
+ <para>To edit a group, just click on the group you wish to edit. You will be taken to a
+ screen which allows you to modify membership, add or remove administrative permissions,
+ and add or remove read access to specific connections, sharing profiles, or connection
+ groups. If you are managing a large number of connections or groups and wish to reduce
+ the size of the list displayed, you can do so by specifying search terms within the
+ "Filter" field. Connection groups will be filtered by name and connections will be
+ filtered by name or protocol.</para>
+ <para>If you have delete permission on the group, you will also see a "Delete" button.
+ Clicking this button will permanently delete the group. Alternatively, if you only wish
+ to temporarily disable the effects of membership in the group, checking "Disabled" will
+ achieve the same effect while not removing the group entirely.</para>
+ <informalfigure>
+ <screenshot>
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="images/edit-user-group.png" format="PNG"
+ contentwidth="5in"/>
+ </imageobject>
+ <caption>
+ <para>Editing a user group</para>
+ </caption>
+ </mediaobject>
+ </screenshot>
+ </informalfigure>
+ <section>
+ <title>Group membership of groups</title>
+ <para>Managing the group membership of groups is more complex than that of users, as
+ groups may contain both users and groups, with permissions from parent groups
+ possibly being inherited. Parent groups, member groups, and member users, can all be
+ managed identically to the <link xmlns:xlink="http://www.w3.org/1999/xlink"
+ linkend="user-group-membership">group memberships of users</link>, with a
+ corresponding section dedicated to each within the user group editor:</para>
+ <informalfigure>
+ <screenshot>
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="images/edit-group-memberships.png" format="PNG"
+ contentwidth="5in"/>
+ </imageobject>
+ <caption>
+ <para>Editing the various membership relations of a user group</para>
+ </caption>
+ </mediaobject>
+ </screenshot>
+ </informalfigure>
+ <para>Note that it is ultimately up to the extension providing the group to determine
+ how permissions granted to that group are inherited, if at all. The <link
+ xmlns:xlink="http://www.w3.org/1999/xlink" linkend="jdbc-auth">database
+ authentication extension</link> implements full recursive inheritance of group
+ permissions, with permissions granted to a group being granted to all
+ members/descendants of that group, regardless of how deeply those members are
+ nested.</para>
+ </section>
</section>
<section xml:id="connection-management">
- <title>Connections and groups</title>
+ <title>Connections and connection groups</title>
<indexterm>
<primary>connection management</primary>
</indexterm>
@@ -200,16 +311,19 @@
create and edit connections, sharing profiles, and connection groups. If you have a
large number of connections, you can also enter search terms within the "Filter" field
to filter the list of connections by name or protocol.</para>
- <para>To add a new connection or group, click the "New Connection" or "New Group" button, or
- the "New Connection" or "New Group" placeholders which appear when you expand an
- existing group. These options will take you to a screen where you will be allowed to
- enter the details of the new object, such as its location, parameters, and name. This
- name should be descriptive, but must also be unique with respect to other objects in the
- same location.</para>
+ <para>To add a new connection or connection group, click the "New Connection" or "New Group"
+ button, or the "New Connection" or "New Group" placeholders which appear when you expand
+ an existing connection group. These options will take you to a screen where you will be
+ allowed to enter the details of the new object, such as its location, parameters, and
+ name. This name should be descriptive, but must also be unique with respect to other
+ objects in the same location.</para>
<para>Once you click "Save", the new object will be added, but will initially only be usable
by administrators and your current user. To grant another user access to the new
- connection or group, you must edit that user, checking the box corresponding to the
- connection or group you created.</para>
+ connection or connection group, you must <link
+ xmlns:xlink="http://www.w3.org/1999/xlink" linkend="user-management">edit that
+ user</link> or <link xmlns:xlink="http://www.w3.org/1999/xlink"
+ linkend="user-group-management">a user group that the user is a member of</link>,
+ checking the box corresponding to the connection or connection group you created.</para>
<informalfigure>
<screenshot>
<mediaobject>
@@ -223,10 +337,10 @@
</mediaobject>
</screenshot>
</informalfigure>
- <para>Editing connections, sharing profiles, and groups works identically to editing a user.
- Click on the object you wish to edit, and you will be taken to screen which allows you
- to edit it. The screen will display all properties of the object, including its usage
- history, if applicable.</para>
+ <para>Editing connections, sharing profiles, and connection groups works identically to
+ editing a user. Click on the object you wish to edit, and you will be taken to screen
+ which allows you to edit it. The screen will display all properties of the object,
+ including its usage history, if applicable.</para>
<para>If you have delete permission on the object, you will also see a "Delete" button.
Clicking this button will permanently delete the object being edited.</para>
<informalfigure>
diff --git a/src/chapters/images/edit-group-memberships.png b/src/chapters/images/edit-group-memberships.png
new file mode 100644
index 0000000..3845373
--- /dev/null
+++ b/src/chapters/images/edit-group-memberships.png
Binary files differ
diff --git a/src/chapters/images/edit-user-group.png b/src/chapters/images/edit-user-group.png
new file mode 100644
index 0000000..16dbae8
--- /dev/null
+++ b/src/chapters/images/edit-user-group.png
Binary files differ
diff --git a/src/chapters/images/edit-user-membership.png b/src/chapters/images/edit-user-membership.png
new file mode 100644
index 0000000..ef7d5d9
--- /dev/null
+++ b/src/chapters/images/edit-user-membership.png
Binary files differ
diff --git a/src/chapters/images/manage-groups.png b/src/chapters/images/manage-groups.png
new file mode 100644
index 0000000..b7126f5
--- /dev/null
+++ b/src/chapters/images/manage-groups.png
Binary files differ
