doc/1.5.2/gug/administration.html

<!DOCTYPE html> <html class="writer-html5" lang="en" > <head> <meta charset="utf-8" /><meta name="generator" content="Docutils 0.17.1: http://docutils.sourceforge.net/" /> <meta name="viewport" content="width=device-width, initial-scale=1.0" /> <title>Administration — Apache Guacamole Manual v1.5.2</title> <link rel="stylesheet" href="_static/pygments.css" type="text/css" /> <link rel="stylesheet" href="_static/css/theme.css" type="text/css" /> <link rel="stylesheet" href="_static/tabs.css" type="text/css" /> <link rel="stylesheet" href="_static/gug.css" type="text/css" />  <script data-url_root="./" id="documentation_options" src="_static/documentation_options.js"></script> <script src="_static/jquery.js"></script> <script src="_static/underscore.js"></script> <script src="_static/_sphinx_javascript_frameworks_compat.js"></script> <script src="_static/doctools.js"></script> <script src="_static/sphinx_highlight.js"></script> <script src="_static/tabs.js"></script> <script src="_static/js/theme.js"></script> <link rel="index" title="Index" href="genindex.html" /> <link rel="search" title="Search" href="search.html" /> <link rel="next" title="Troubleshooting" href="troubleshooting.html" /> <link rel="prev" title="Viewing session recordings in-browser" href="recording-playback.html" /> </head> <body class="wy-body-for-nav"> <div class="wy-grid-for-nav"> <nav data-toggle="wy-nav-shift" class="wy-nav-side"> <div class="wy-side-scroll"> <div class="wy-side-nav-search" > <a href="index.html" class="icon icon-home"> Apache Guacamole </a> <div class="version"> 1.5.2 </div> <div role="search"> <form id="rtd-search-form" class="wy-form" action="search.html" method="get"> <input type="text" name="q" placeholder="Search docs" /> <input type="hidden" name="check_keywords" value="yes" /> <input type="hidden" name="area" value="default" /> </form> </div> </div><div class="wy-menu wy-menu-vertical" data-spy="affix" role="navigation" aria-label="Navigation menu"> <p class="caption" role="heading"><span class="caption-text">Overview</span></p> <ul> <li class="toctree-l1"><a class="reference internal" href="introduction.html">Introduction</a></li> </ul> <p class="caption" role="heading"><span class="caption-text">User's Guide</span></p> <ul class="current"> <li class="toctree-l1"><a class="reference internal" href="guacamole-architecture.html">Implementation and architecture</a></li> <li class="toctree-l1"><a class="reference internal" href="installing-guacamole.html">Installing Guacamole natively</a></li> <li class="toctree-l1"><a class="reference internal" href="guacamole-docker.html">Installing Guacamole with Docker</a></li> <li class="toctree-l1"><a class="reference internal" href="reverse-proxy.html">Proxying Guacamole</a></li> <li class="toctree-l1"><a class="reference internal" href="configuring-guacamole.html">Configuring Guacamole</a></li> <li class="toctree-l1"><a class="reference internal" href="jdbc-auth.html">Database authentication</a></li> <li class="toctree-l1"><a class="reference internal" href="ldap-auth.html">LDAP authentication</a></li> <li class="toctree-l1"><a class="reference internal" href="vault.html">Retrieving secrets from a vault</a></li> <li class="toctree-l1"><a class="reference internal" href="duo-auth.html">Duo two-factor authentication</a></li> <li class="toctree-l1"><a class="reference internal" href="totp-auth.html">TOTP two-factor authentication</a></li> <li class="toctree-l1"><a class="reference internal" href="header-auth.html">HTTP header authentication</a></li> <li class="toctree-l1"><a class="reference internal" href="json-auth.html">Encrypted JSON authentication</a></li> <li class="toctree-l1"><a class="reference internal" href="cas-auth.html">CAS Authentication</a></li> <li class="toctree-l1"><a class="reference internal" href="openid-auth.html">OpenID Connect Authentication</a></li> <li class="toctree-l1"><a class="reference internal" href="saml-auth.html">SAML Authentication</a></li> <li class="toctree-l1"><a class="reference internal" href="radius-auth.html">RADIUS Authentication</a></li> <li class="toctree-l1"><a class="reference internal" href="adhoc-connections.html">Ad-hoc Connections</a></li> <li class="toctree-l1"><a class="reference internal" href="using-guacamole.html">Using Guacamole</a></li> <li class="toctree-l1"><a class="reference internal" href="recording-playback.html">Viewing session recordings in-browser</a></li> <li class="toctree-l1 current"><a class="current reference internal" href="#">Administration</a><ul> <li class="toctree-l2"><a class="reference internal" href="#managing-sessions">Managing sessions</a><ul> <li class="toctree-l3"><a class="reference internal" href="#filtering-and-sorting">Filtering and sorting</a></li> </ul> </li> <li class="toctree-l2"><a class="reference internal" href="#connection-history">Connection history</a><ul> <li class="toctree-l3"><a class="reference internal" href="#filtering-history">Filtering and sorting</a></li> </ul> </li> <li class="toctree-l2"><a class="reference internal" href="#user-management">User management</a><ul> <li class="toctree-l3"><a class="reference internal" href="#editing-group-membership">Editing group membership</a></li> </ul> </li> <li class="toctree-l2"><a class="reference internal" href="#user-group-management">User group management</a><ul> <li class="toctree-l3"><a class="reference internal" href="#group-membership-of-groups">Group membership of groups</a></li> </ul> </li> <li class="toctree-l2"><a class="reference internal" href="#connections-and-connection-groups">Connections and connection groups</a><ul> <li class="toctree-l3"><a class="reference internal" href="#connection-organization-and-balancing">Connection organization and balancing</a></li> <li class="toctree-l3"><a class="reference internal" href="#connection-sharing">Connection sharing</a></li> </ul> </li> </ul> </li> <li class="toctree-l1"><a class="reference internal" href="troubleshooting.html">Troubleshooting</a></li> </ul> <p class="caption" role="heading"><span class="caption-text">Developer's Guide</span></p> <ul> <li class="toctree-l1"><a class="reference internal" href="guacamole-protocol.html">The Guacamole protocol</a></li> <li class="toctree-l1"><a class="reference internal" href="libguac.html">libguac</a></li> <li class="toctree-l1"><a class="reference internal" href="guacamole-common.html">guacamole-common</a></li> <li class="toctree-l1"><a class="reference internal" href="guacamole-common-js.html">guacamole-common-js</a></li> <li class="toctree-l1"><a class="reference internal" href="guacamole-ext.html">guacamole-ext</a></li> <li class="toctree-l1"><a class="reference internal" href="custom-protocols.html">Adding new protocols</a></li> <li class="toctree-l1"><a class="reference internal" href="custom-auth.html">Custom authentication</a></li> <li class="toctree-l1"><a class="reference internal" href="event-listeners.html">Event listeners</a></li> <li class="toctree-l1"><a class="reference internal" href="writing-you-own-guacamole-app.html">Writing your own Guacamole application</a></li> </ul> <p class="caption" role="heading"><span class="caption-text">Appendices</span></p> <ul> <li class="toctree-l1"><a class="reference internal" href="protocol-reference.html">Guacamole protocol reference</a></li> </ul> </div> </div> </nav> <section data-toggle="wy-nav-shift" class="wy-nav-content-wrap"><nav class="wy-nav-top" aria-label="Mobile navigation menu" > <i data-toggle="wy-nav-top" class="fa fa-bars"></i> <a href="index.html">Apache Guacamole</a> </nav> <div class="wy-nav-content"> <div class="rst-content"> <div role="navigation" aria-label="Page navigation"> <ul class="wy-breadcrumbs"> <li><a href="index.html" class="icon icon-home"></a> »</li> <li>Administration</li> <li class="wy-breadcrumbs-aside"> <a href="_sources/administration.md.txt" rel="nofollow"> View page source</a> </li> </ul> <hr/> </div> <div role="main" class="document" itemscope="itemscope" itemtype="http://schema.org/Article"> <div itemprop="articleBody"> <section id="administration"> <h1>Administration<a class="headerlink" href="#administration" title="Permalink to this heading"></a></h1> <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="reference internal" href="jdbc-auth.html"><span class="doc std std-doc">Database authentication</span></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> <p><img alt="Sections within the Guacamole settings screen." src="_images/guacamole-settings-sections.png" /></p> <p>Clicking any of these options will take you to a corresponding management section where you can perform administrative tasks.</p> <section id="managing-sessions"> <span id="session-management"></span><h2>Managing sessions<a class="headerlink" href="#managing-sessions" title="Permalink to this heading"></a></h2> <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> <p><img alt="Session management interface" src="_images/manage-sessions.png" /></p> <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> <section id="filtering-and-sorting"> <span id="filtering-sessions"></span><h3>Filtering and sorting<a class="headerlink" href="#filtering-and-sorting" title="Permalink to this heading"></a></h3> <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> <p><img alt="" src="_images/session-filter-example-1.png" /></p> <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> <p><img alt="" src="_images/session-filter-example-2.png" /></p> </section> </section> <section id="connection-history"> <h2>Connection history<a class="headerlink" href="#connection-history" title="Permalink to this heading"></a></h2> <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, how long the connection was used, and whether a corresponding recording is available for viewing:</p> <p><img alt="Connection history interface with recordings" src="_images/history-table-with-recordings.png" /></p> <p>Recordings are only made for a connection if an administrator explicitly configures the connection to produce recordings, and those recordings are only available from this screen if the administrator explicitly configures the connection to <a class="reference internal" href="recording-playback.html"><span class="doc std std-doc">store those recordings in a location dedicated for future in-browser playback</span></a>.</p> <section id="filtering-history"> <span id="id1"></span><h3>Filtering and sorting<a class="headerlink" href="#filtering-history" title="Permalink to this heading"></a></h3> <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> </section> </section> <section id="user-management"> <span id="id2"></span><h2>User management<a class="headerlink" href="#user-management" title="Permalink to this heading"></a></h2> <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> <p><img alt="User management interface" src="_images/manage-users.png" /></p> <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> <p><img alt="Editing a user" src="_images/edit-user.png" /></p> <section id="editing-group-membership"> <span id="user-group-membership"></span><h3>Editing group membership<a class="headerlink" href="#editing-group-membership" title="Permalink to this heading"></a></h3> <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> <p><img alt="Editing group membership of a user" src="_images/edit-user-membership.png" /></p> <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> </section> </section> <section id="user-group-management"> <span id="id3"></span><h2>User group management<a class="headerlink" href="#user-group-management" title="Permalink to this heading"></a></h2> <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> <p><img alt="User group management interface" src="_images/manage-groups.png" /></p> <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> <p><img alt="Editing a user group" src="_images/edit-user-group.png" /></p> <section id="group-membership-of-groups"> <h3>Group membership of groups<a class="headerlink" href="#group-membership-of-groups" title="Permalink to this heading"></a></h3> <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="reference internal" href="#user-group-membership"><span class="std std-ref">group memberships of users</span></a>, with a corresponding section dedicated to each within the user group editor:</p> <p><img alt="Editing the various membership relations of a user group" src="_images/edit-group-memberships.png" /></p> <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="reference internal" href="jdbc-auth.html"><span class="doc std std-doc">database authentication extension</span></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> </section> </section> <section id="connections-and-connection-groups"> <span id="connection-management"></span><h2>Connections and connection groups<a class="headerlink" href="#connections-and-connection-groups" title="Permalink to this heading"></a></h2> <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="reference internal" href="#user-management"><span class="std std-ref">edit that user</span></a> or <a class="reference internal" href="#user-group-management"><span class="std std-ref">a user group that the user is a member of</span></a>, checking the box corresponding to the connection or connection group you created.</p> <p><img alt="Connection management interface" src="_images/manage-connections.png" /></p> <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> <p><img alt="Editing a connection" src="_images/edit-connection.png" /></p> <section id="connection-organization-and-balancing"> <span id="connection-group-management"></span><h3>Connection organization and balancing<a class="headerlink" href="#connection-organization-and-balancing" title="Permalink to this heading"></a></h3> <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>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> <p><img alt="Editing a connection group" src="_images/edit-group.png" /></p> </section> <section id="connection-sharing"> <h3>Connection sharing<a class="headerlink" href="#connection-sharing" title="Permalink to this heading"></a></h3> <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="reference internal" href="using-guacamole.html#client-share-menu"><span class="std std-ref">generating connection sharing links</span></a>, even if those users do not otherwise have user accounts within Guacamole.</p> <p>The name of the sharing profile will be presented as an option within the <a class="reference internal" href="using-guacamole.html#client-share-menu"><span class="std std-ref">share menu</span></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="admonition important"> <p class="admonition-title">Important</p> <p><em>The only extension which ships with Guacamole and implements enough of the <a class="reference internal" href="guacamole-ext.html"><span class="doc std std-doc">Guacamole extension API</span></a> to share its connections is the <a class="reference internal" href="jdbc-auth.html"><span class="doc std std-doc">database authentication extension</span></a>.</em> 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="reference internal" href="ldap-auth.html#ldap-and-database"><span class="std std-ref">alongside other extensions</span></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="reference internal" href="#connection-management"><span class="std std-ref">the list of connections in the connection management screen</span></a> and <a class="reference internal" href="#user-management"><span class="std std-ref">the list of connections in the user editor</span></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> <p><img alt="Editing a sharing profile" src="_images/edit-sharing-profile.png" /></p> </section> </section> </section> </div> </div> <footer><div class="rst-footer-buttons" role="navigation" aria-label="Footer"> <a href="recording-playback.html" class="btn btn-neutral float-left" title="Viewing session recordings in-browser" accesskey="p" rel="prev"><span class="fa fa-arrow-circle-left" aria-hidden="true"></span> Previous</a> <a href="troubleshooting.html" class="btn btn-neutral float-right" title="Troubleshooting" accesskey="n" rel="next">Next <span class="fa fa-arrow-circle-right" aria-hidden="true"></span></a> </div> <hr/> <div role="contentinfo"> <p>Copyright © 2023 <a href="http://www.apache.org/">The Apache Software Foundation</a>, Licensed under the <a href="http://www.apache.org/licenses/LICENSE-2.0">Apache License, Version 2.0</a>. Apache Guacamole, Guacamole, Apache, the Apache feather logo, and the Apache Guacamole project logo are trademarks of The Apache Software Foundation.</p> </div> Built with <a href="https://www.sphinx-doc.org/">Sphinx</a> using a <a href="https://github.com/readthedocs/sphinx_rtd_theme">theme</a> provided by <a href="https://readthedocs.org">Read the Docs</a>. </footer> </div> </div> </section> </div> <script> jQuery(function () { SphinxRtdTheme.Navigation.enable(true); }); </script> </body> </html>

doc/1.5.2/gug/administration.html (412 lines of code) (raw):