| <?xml version="1.0" encoding="UTF-8" standalone="no"?> |
| <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>Chapter 16. Administration</title><link rel="stylesheet" type="text/css" href="gug.css" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="home" href="index.html" title="Guacamole Manual" /><link rel="up" href="users-guide.html" title="Part I. User's Guide" /><link rel="prev" href="using-guacamole.html" title="Chapter 15. Using Guacamole" /><link rel="next" href="troubleshooting.html" title="Chapter 17. Troubleshooting" /> |
| <meta name="viewport" content="width=device-width, initial-scale=1.0, maximum-scale=1.0, minimum-scale=1.0, user-scalable=no, target-densitydpi=device-dpi"/> |
| </head><body> |
| <!-- CONTENT --> |
| |
| <div id="page"><div id="content"> |
| <div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">Chapter 16. Administration</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="using-guacamole.html">Prev</a> </td><th width="60%" align="center">Part I. User's Guide</th><td width="20%" align="right"> <a accesskey="n" href="troubleshooting.html">Next</a></td></tr></table><hr /></div><div xml:lang="en" class="chapter" lang="en"><div class="titlepage"><div><div><h2 class="title"><a id="administration"></a>Chapter 16. Administration</h2></div></div></div><div class="toc"><p><strong>Table of Contents</strong></p><dl class="toc"><dt><span class="section"><a href="administration.html#session-management">Managing sessions</a></span></dt><dd><dl><dt><span class="section"><a href="administration.html#filtering-sessions">Filtering and sorting</a></span></dt></dl></dd><dt><span class="section"><a href="administration.html#connection-history">Connection history</a></span></dt><dd><dl><dt><span class="section"><a href="administration.html#filtering-history">Filtering and sorting</a></span></dt></dl></dd><dt><span class="section"><a href="administration.html#user-management">User management</a></span></dt><dd><dl><dt><span class="section"><a href="administration.html#user-group-membership">Editing group membership</a></span></dt></dl></dd><dt><span class="section"><a href="administration.html#user-group-management">User group management</a></span></dt><dd><dl><dt><span class="section"><a href="administration.html#idm46420845391936">Group membership of groups</a></span></dt></dl></dd><dt><span class="section"><a href="administration.html#connection-management">Connections and connection groups</a></span></dt><dd><dl><dt><span class="section"><a href="administration.html#connection-group-management">Connection organization and balancing</a></span></dt><dt><span class="section"><a href="administration.html#idm46420845357872">Connection sharing</a></span></dt></dl></dd></dl></div><a id="idm46420847313712" class="indexterm"></a><p>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 <a class="xref" href="jdbc-auth.html" title="Chapter 6. Database authentication">Chapter 6, <em>Database authentication</em></a>.</p><p>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:</p><div class="informalfigure"><div class="mediaobject"><img src="images/guacamole-settings-sections.png" width="315" /><div class="caption"><p>Sections within the Guacamole settings screen.</p></div></div></div><p>Clicking any of these options will take you to a corresponding management section where |
| you can perform administrative tasks.</p><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="session-management"></a>Managing sessions</h2></div></div></div><a id="idm46420847271824" class="indexterm"></a><p>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.</p><p>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.</p><div class="informalfigure"><div class="screenshot"><div class="mediaobject"><img src="images/manage-sessions.png" width="450" /><div class="caption"><p>Session management interface</p></div></div></div></div><p>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.</p><div class="section"><div class="titlepage"><div><div><h3 class="title"><a id="filtering-sessions"></a>Filtering and sorting</h3></div></div></div><p>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.</p><p>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.</p><div class="informalfigure"><div class="mediaobject"><img src="images/session-filter-example-1.png" width="450" /></div></div><p>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.</p><div class="informalfigure"><div class="mediaobject"><img src="images/session-filter-example-2.png" width="450" /></div></div></div></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="connection-history"></a>Connection history</h2></div></div></div><a id="idm46420847827344" class="indexterm"></a><a id="idm46420847826448" class="indexterm"></a><p>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.</p><div class="informalfigure"><div class="screenshot"><div class="mediaobject"><img src="images/manage-history.png" width="450" /><div class="caption"><p>Connection history interface</p></div></div></div></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a id="filtering-history"></a>Filtering and sorting</h3></div></div></div><p>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.</p><p>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.</p><p>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.</p></div></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="user-management"></a>User management</h2></div></div></div><a id="idm46420847696272" class="indexterm"></a><p>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.</p><p>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.</p><div class="informalfigure"><div class="screenshot"><div class="mediaobject"><img src="images/manage-users.png" width="450" /><div class="caption"><p>User management interface</p></div></div></div></div><p>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.</p><p>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.</p><div class="informalfigure"><div class="screenshot"><div class="mediaobject"><img src="images/edit-user.png" width="450" /><div class="caption"><p>Editing a user</p></div></div></div></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a id="user-group-membership"></a>Editing group membership</h3></div></div></div><p>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.</p><p>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:</p><div class="informalfigure"><div class="screenshot"><div class="mediaobject"><img src="images/edit-user-membership.png" width="450" /><div class="caption"><p>Editing group membership of a user</p></div></div></div></div><p>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.</p></div></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="user-group-management"></a>User group management</h2></div></div></div><a id="idm46420847720688" class="indexterm"></a><a id="idm46420847719792" class="indexterm"></a><a id="idm46420847718896" class="indexterm"></a><p>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:</p><div class="informalfigure"><div class="screenshot"><div class="mediaobject"><img src="images/manage-groups.png" width="450" /><div class="caption"><p>User group management interface</p></div></div></div></div><p>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.</p><p>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.</p><p>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.</p><div class="informalfigure"><div class="screenshot"><div class="mediaobject"><img src="images/edit-user-group.png" width="450" /><div class="caption"><p>Editing a user group</p></div></div></div></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a id="idm46420845391936"></a>Group membership of groups</h3></div></div></div><p>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 <a class="link" href="administration.html#user-group-membership" title="Editing group membership">group memberships of users</a>, with a |
| corresponding section dedicated to each within the user group editor:</p><div class="informalfigure"><div class="screenshot"><div class="mediaobject"><img src="images/edit-group-memberships.png" width="450" /><div class="caption"><p>Editing the various membership relations of a user group</p></div></div></div></div><p>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 <a class="link" href="jdbc-auth.html" title="Chapter 6. Database authentication">database |
| authentication extension</a> 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.</p></div></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="connection-management"></a>Connections and connection groups</h2></div></div></div><a id="idm46420845382368" class="indexterm"></a><a id="idm46420845381472" class="indexterm"></a><a id="idm46420845380576" class="indexterm"></a><p>Clicking "Connections" within the list of settings sections will take you to the |
| connection management screen. The connection management screen allows administrators to |
| 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.</p><p>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.</p><p>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 connection group, you must <a class="link" href="administration.html#user-management" title="User management">edit that |
| user</a> or <a class="link" href="administration.html#user-group-management" title="User group management">a user group that the user is a member of</a>, |
| checking the box corresponding to the connection or connection group you created.</p><div class="informalfigure"><div class="screenshot"><div class="mediaobject"><img src="images/manage-connections.png" width="450" /><div class="caption"><p>Connection management interface</p></div></div></div></div><p>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.</p><p>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.</p><div class="informalfigure"><div class="screenshot"><div class="mediaobject"><img src="images/edit-connection.png" width="450" /><div class="caption"><p>Editing a connection</p></div></div></div></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a id="connection-group-management"></a>Connection organization and balancing</h3></div></div></div><p>Connection groups can be either "organizational" or "balancing". Each group can |
| contain any number of other connections or groups, but the semantics of the group |
| change depending on the type.</p><p>An organizational group behaves exactly as a folder or directory in a file system. |
| It simply contains connections and other groups, but provides no other behavior. |
| Clicking on an organizational group within a connection list will expand the group, |
| revealing its contents.</p><p>A balancing group behaves as a connection. It dynamically balances load across the |
| connections it contains, choosing the connection with the fewest number of active |
| users. Unlike organizational groups, clicking on a balancing group causes a new |
| connection to be opened. The actual underlying connection used depends on which |
| connection has the least load at the time the group was clicked, and whether session |
| affinity is enabled on that group.</p><p><a id="idm46420845362960" class="indexterm"></a>Enabling session affinity for a balancing group ensures that users are |
| consistently routed to the same underlying connections until they log out of |
| Guacamole. The load balancing behavior of the balancing group will apply only for |
| the first time a particular user connects to the group. If your users may lose their |
| desktop state if they are routed to a different underlying connection, this option |
| should be enabled.</p><div class="informalfigure"><div class="screenshot"><div class="mediaobject"><img src="images/edit-group.png" width="450" /><div class="caption"><p>Editing a connection group</p></div></div></div></div></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a id="idm46420845357872"></a>Connection sharing</h3></div></div></div><p>The ability to share a connection is governed through the use of "sharing |
| profiles". If a sharing profile is created for a connection, users with access to |
| both that connection and that sharing profile will be able to share the connection |
| with other users by <a class="link" href="using-guacamole.html#client-share-menu" title="Sharing the connection">generating connection sharing links</a>, even if |
| those users do not otherwise have user accounts within Guacamole.</p><p>The name of the sharing profile will be presented an option within the <a class="link" href="using-guacamole.html#client-share-menu" title="Sharing the connection">share |
| menu</a> for any users with access, while the level of access granted to |
| users of generated share links will be dictated by the parameters specified for the |
| sharing profile.</p><div class="important"><h3 class="title">Important</h3><p><span class="emphasis"><em>The only extension which ships with Guacamole and implements enough |
| of the <a class="link" href="guacamole-ext.html" title="Chapter 22. guacamole-ext">Guacamole extension API</a> to share its |
| connections is the <a class="link" href="jdbc-auth.html" title="Chapter 6. Database authentication">database authentication extension</a></em></span>. |
| If you wish to share connections (or allow your users to share connections), you |
| will need to use the database authentication extension to store those |
| connections.</p><p>If you need to use other authentication schemes, keep in mind that the |
| database authentication extension can be used <a class="link" href="ldap-auth.html#ldap-and-database" title="Associating LDAP with a database">alongside other extensions</a>, with the database handling connection |
| storage and permissions only. Writing your own extension which supports sharing |
| is another alternative, though that may be overly complicated if everything you |
| need is already provided.</p></div><p>Unlike connections and groups, there is no "New Sharing Profile" button. Sharing |
| profiles are created through clicking the "New Sharing Profile" placeholders which |
| appear when connections are expanded. Just as expanding a connection group reveals |
| the connections or groups therein, expanding a connection reveals the sharing |
| profiles associated with that connection. This holds true with both <a class="link" href="administration.html#connection-management" title="Connections and connection groups">the |
| list of connections in the connection management screen</a> and <a class="link" href="administration.html#user-management" title="User management">the list of |
| connections in the user editor</a>.</p><p>Creating or editing a sharing profile is virtually identical to creating or |
| editing a connection, with the exception that not all connection parameters are |
| available:</p><div class="informalfigure"><div class="screenshot"><div class="mediaobject"><img src="images/edit-sharing-profile.png" width="450" /><div class="caption"><p>Editing a sharing profile</p></div></div></div></div></div></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="using-guacamole.html">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="users-guide.html">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="troubleshooting.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">Chapter 15. Using Guacamole </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right" valign="top"> Chapter 17. Troubleshooting</td></tr></table></div> |
| |
| </div></div> |
| </body></html> |