mike-jumper commented on a change in pull request #165:
URL: https://github.com/apache/guacamole-manual/pull/165#discussion_r642140602
##########
File path: src/administration.md
##########
@@ -0,0 +1,314 @@
+Administration
+==============
+
+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 [](jdbc-auth).
+
+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 database authentication providers, and you
+are logged in as a user with sufficient privileges, you will see management
+sections listed within the settings screen:
+
+
+
+Clicking any of these options will take you to a corresponding management
+section where you can perform administrative tasks.
+
+(session-management)=
+
+Managing sessions
+-----------------
+
+Clicking "Active Sessions" navigates to the session management screen. The
+session management screen displays all active sessions and allows system
+administrators to kill them as needed.
+
+When any user accesses a particular remote desktop connection, a unique session
+is created and will appear in the list of active sessions in the session
+management screen. Each active session is displayed in a sortable table,
+showing the corresponding user's username, how long the session has been
+active, the IP address of the machine from which the user is connecting, and
+the name of the connection being used.
+
+
+
+To kill one or more sessions, select the sessions by clicking their checkboxes.
+Once all desired sessions have been selected, clicking "Kill Sessions" will
+immediately disconnect those users from the associated connection.
+
+(filtering-sessions)=
+
+### Filtering and sorting
+
+The table can be resorted by clicking on the column headers. Clicking any
+column will resort the table by the values within that column, while clicking a
+column which is already sorted will toggle between ascending and descending
+order.
+
+The content of the table can be limited through search terms specified in the
+"Filter" field. Entering search terms will limit the table to only sessions
+containing those terms. For example, to list only connections by the user
+"guacadmin" which have been active since March, 2015, you would enter:
+"guacadmin 2015-03". Beware that if a search term needs to contain spaces, it
+must be enclosed in double quotes to avoid being interpreted as multiple terms.
+
+
+
+If you wish to narrow the content of the table to only those connections which
+originate from a particular block of IP addresses, you can do this by
+specifying the block in standard CIDR notation, such "10.0.0.0/8" or
+"2001:db8:1234::/48". This will work with both IPv4 and IPv6 addresses.
+
+
+
+Connection history
+------------------
+
+Clicking "History" navigates to the connection history screen. The connection
+history screen displays a table of the most recent connections, including the
+user that used that connection, the time the connection began, and how long the
+connection was used.
+
+
+
+(filtering-history)=
+
+### Filtering and sorting
+
+Initially, the connection history table will display only the most recent
+history records. You can page through these records to see how and when
+Guacamole has been used.
+
+Just as with the table of active sessions described earlier, the table of
+history records can be resorted by clicking on the column headers or filtered
+by entering search terms within the "Filter" field.
+
+The same filtering format applies - a search term containing spaces must be
+enclosed in double quotes to avoid being interpreted as multiple terms, and
+only history records which contain each term will be included in the history
+table. Unlike the table of active sessions, however, the filter will only take
+effect once you click the "Search" button. This is due to the nature of the
+connection history, as the number of records may be quite extensive.
+
+(user-management)=
+
+User management
+---------------
+
+Clicking "Users" within the list of settings sections will take you to the user
+management screen. Here you can add new users, edit the properties and
+privileges of existing users, and view the times that each user last logged in.
+If you have a large number of users, you can also enter search terms within the
+"Filter" field to filter the list of users by username.
+
+To add a new user, click the "New User" button. This will take you to a screen
+where you will be allowed to enter the details of the new user, such as the
+password and username. Note that, unless you specify otherwise, the new user
+will have no access to any existing connections, nor any administrative
+privileges, and you will need to manually set the user's password before they
+will be able to log in.
+
+
+
+To edit a user, just click on the user you wish to edit. You will be taken to a
+screen which allows you to change the user's password, expire their password
+(such that it must be changed at next login), add or remove administrative
+permissions, and add or remove read access to specific connections, sharing
+profiles, or 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. Groups will be filtered by
+name and connections will be filtered by name or protocol.
+
+If you have delete permission on the user, you will also see a "Delete" button.
+Clicking this button will permanently delete the user. Alternatively, if you
+only wish to temporarily disable the account, checking "Login disabled" will
+achieve the same effect while not removing the user entirely. If they attempt
+to log in, the attempt will be rejected as if their account did not exist at
+all.
+
+
+
+(user-group-membership)=
+
+### Editing group membership
+
+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.
+
+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:
+
+
+
+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.
+
+(user-group-management)=
+
+User group management
+---------------------
+
+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:
+
+
+
+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.
+
+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.
+
+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.
Review comment:
IMHO, this is already really clear. I suspect [the mailing list thread
in
question](https://lists.apache.org/thread.html/r0a942a19a539f5158750aa43896edbf359e08452f2362c663459deba%40%3Cuser.guacamole.apache.org%3E)
was not due to misunderstanding the docs, but rather guessing what "Disable"
means without consulting the docs.
To avoid such confusion in the future, I think the best path would be to
include some sort of inline help or tooltips alongside most of the admin
options.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
For queries about this service, please contact Infrastructure at:
us...@infra.apache.org
