Merge pull request #15 from glyptodon/update-usage
GUAC-1221: Update general usage documentation
diff --git a/src/chapters/administration.xml b/src/chapters/administration.xml
index 4c4ad38..b0f2f33 100644
--- a/src/chapters/administration.xml
+++ b/src/chapters/administration.xml
@@ -14,27 +14,90 @@
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 options within the user menu.</para>
+ privileges, you will see management sections listed within the settings screen:</para>
<informalfigure>
<mediaobject>
<imageobject>
- <imagedata fileref="images/manage-button.png" format="PNG" contentwidth="1.5in"/>
+ <imagedata fileref="images/guacamole-settings-sections.png" format="PNG"
+ contentwidth="1.5in"/>
</imageobject>
<caption>
- <para>Management options within the Guacamole user menu.</para>
+ <para>Sections within the Guacamole settings screen.</para>
</caption>
</mediaobject>
</informalfigure>
- <para>Clicking any of these options will take you to a corresponding screen where you can
- perform administrative tasks.</para>
+ <para>Clicking any of these options will take you to a corresponding management section where
+ you can perform administrative tasks.</para>
+ <section xml:id="session-management">
+ <title>Managing sessions</title>
+ <indexterm>
+ <primary>session management</primary>
+ </indexterm>
+ <para>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.</para>
+ <para>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.</para>
+ <informalfigure>
+ <screenshot>
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="images/manage-sessions.png" format="PNG"
+ contentwidth="5in"/>
+ </imageobject>
+ <caption>
+ <para>Session management interface</para>
+ </caption>
+ </mediaobject>
+ </screenshot>
+ </informalfigure>
+ <para>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.</para>
+ <section xml:id="filtering-sessions">
+ <title>Filtering and sorting</title>
+ <para>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.</para>
+ <para>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.</para>
+ <informalfigure>
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="images/session-filter-example-1.png" format="PNG"
+ contentwidth="5in"/>
+ </imageobject>
+ </mediaobject>
+ </informalfigure>
+ <para>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.</para>
+ <informalfigure>
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="images/session-filter-example-2.png" format="PNG"
+ contentwidth="5in"/>
+ </imageobject>
+ </mediaobject>
+ </informalfigure>
+ </section>
+ </section>
<section xml:id="user-management">
<title>User management</title>
<indexterm>
<primary>user management</primary>
</indexterm>
- <para>Clicking "Users" within the user menu will take you to the user management screen.
- Here you can add new users or edit the properties and privileges of existing
- users.</para>
+ <para>Clicking "Users" within the list of settings sections will take you to the user
+ management screen. Here you can add new users or edit the properties and privileges of
+ existing users.</para>
<para>To add a new user, type the username of the new user within the text box inside the
user management screen, and click the "New User" button. The new user will be added and
made available. The new user will have no access to any existing connections, nor any
@@ -54,10 +117,14 @@
</screenshot>
</informalfigure>
<para>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, add or remove administrative
- permissions, and add or remove read access to specific connections or groups.</para>
+ 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 or groups.</para>
<para>If you have delete permission on the user, you will also see a "Delete" button.
- Clicking this button will permanently delete the user.</para>
+ 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.</para>
<informalfigure>
<screenshot>
<mediaobject>
@@ -82,9 +149,9 @@
<indexterm>
<primary>groups</primary>
</indexterm>
- <para>Clicking "Manage Connections" within the user menu will take you to the connection
- management screen. The connection management screen allows administrators to create and
- edit connections and connection groups.</para>
+ <para>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 and connection groups.</para>
<para>To add a new connection or group, click the "New Connection" or "New Group" button.
This 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
@@ -155,66 +222,4 @@
</informalfigure>
</section>
</section>
- <section xml:id="session-management">
- <title>Managing sessions</title>
- <indexterm>
- <primary>session management</primary>
- </indexterm>
- <para>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.</para>
- <para>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.</para>
- <informalfigure>
- <screenshot>
- <mediaobject>
- <imageobject>
- <imagedata fileref="images/manage-sessions.png" format="PNG"
- contentwidth="5in"/>
- </imageobject>
- <caption>
- <para>Session management interface</para>
- </caption>
- </mediaobject>
- </screenshot>
- </informalfigure>
- <para>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.</para>
- <section xml:id="filtering-sessions">
- <title>Filtering and sorting</title>
- <para>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.</para>
- <para>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.</para>
- <informalfigure>
- <mediaobject>
- <imageobject>
- <imagedata fileref="images/session-filter-example-1.png" format="PNG"
- contentwidth="5in"/>
- </imageobject>
- </mediaobject>
- </informalfigure>
- <para>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.</para>
- <informalfigure>
- <mediaobject>
- <imageobject>
- <imagedata fileref="images/session-filter-example-2.png" format="PNG"
- contentwidth="5in"/>
- </imageobject>
- </mediaobject>
- </informalfigure>
- </section>
- </section>
</chapter>
diff --git a/src/chapters/images/edit-user.png b/src/chapters/images/edit-user.png
index 2cdf0d8..768bad4 100644
--- a/src/chapters/images/edit-user.png
+++ b/src/chapters/images/edit-user.png
Binary files differ
diff --git a/src/chapters/images/guac-menu-disconnect.png b/src/chapters/images/guac-menu-disconnect.png
new file mode 100644
index 0000000..028c2c1
--- /dev/null
+++ b/src/chapters/images/guac-menu-disconnect.png
Binary files differ
diff --git a/src/chapters/images/guacamole-client-interface.png b/src/chapters/images/guacamole-client-interface.png
index ed71cbd..5a9e327 100644
--- a/src/chapters/images/guacamole-client-interface.png
+++ b/src/chapters/images/guacamole-client-interface.png
Binary files differ
diff --git a/src/chapters/images/guacamole-home-screen.png b/src/chapters/images/guacamole-home-screen.png
index cf2ba75..ba20c61 100644
--- a/src/chapters/images/guacamole-home-screen.png
+++ b/src/chapters/images/guacamole-home-screen.png
Binary files differ
diff --git a/src/chapters/images/guacamole-preferences.png b/src/chapters/images/guacamole-preferences.png
new file mode 100644
index 0000000..b751e8d
--- /dev/null
+++ b/src/chapters/images/guacamole-preferences.png
Binary files differ
diff --git a/src/chapters/images/guacamole-settings-sections.png b/src/chapters/images/guacamole-settings-sections.png
new file mode 100644
index 0000000..4677804
--- /dev/null
+++ b/src/chapters/images/guacamole-settings-sections.png
Binary files differ
diff --git a/src/chapters/images/manage-connections.png b/src/chapters/images/manage-connections.png
index beb649f..5af894a 100644
--- a/src/chapters/images/manage-connections.png
+++ b/src/chapters/images/manage-connections.png
Binary files differ
diff --git a/src/chapters/images/manage-sessions.png b/src/chapters/images/manage-sessions.png
index 475cf70..f0fd5b5 100644
--- a/src/chapters/images/manage-sessions.png
+++ b/src/chapters/images/manage-sessions.png
Binary files differ
diff --git a/src/chapters/images/manage-users.png b/src/chapters/images/manage-users.png
index 0460945..7d7ce53 100644
--- a/src/chapters/images/manage-users.png
+++ b/src/chapters/images/manage-users.png
Binary files differ
diff --git a/src/chapters/images/touchpad.png b/src/chapters/images/touchpad.png
new file mode 100644
index 0000000..fa9df42
--- /dev/null
+++ b/src/chapters/images/touchpad.png
Binary files differ
diff --git a/src/chapters/images/touchscreen.png b/src/chapters/images/touchscreen.png
new file mode 100644
index 0000000..85d669c
--- /dev/null
+++ b/src/chapters/images/touchscreen.png
Binary files differ
diff --git a/src/chapters/using.xml b/src/chapters/using.xml
index 8bca010..2fbf48d 100644
--- a/src/chapters/using.xml
+++ b/src/chapters/using.xml
@@ -14,11 +14,12 @@
possible.</para>
<section xml:id="home-screen">
<title>Home screen</title>
- <para>Once you have successfully logged in, the first thing you will see is the Guacamole
- home screen. The home screen is a list of available remote desktop connections. This
- list contains all connections which you have been granted permission to access. If you
- have used Guacamole in this specific web browser before, you will also see thumbnails of
- recently used connections.</para>
+ <para>Once you have successfully logged in, you will be taken to either the Guacamole home
+ screen, where all available connections are listed, or directly to a connection, if you
+ only have access to one connection.</para>
+ <para>The list of connections on the home screen contains all connections for which you have
+ been granted access. If you have used Guacamole in this specific web browser before, you
+ will also see thumbnails of recently used connections.</para>
<informalfigure>
<screenshot>
<mediaobject>
@@ -49,17 +50,19 @@
<varlistentry>
<term>Home</term>
<listitem>
- <para>Navigates back to the home screen, if you are not already
- there.</para>
+ <para>Navigates back to the home screen, if you are not already there. If
+ you only have access to one connection, this will be replaced with a
+ link to that connection.</para>
</listitem>
</varlistentry>
<varlistentry>
- <term>Change password</term>
+ <term>Settings</term>
<listitem>
- <para>Changes the password for your account. This option may not be
- available if your user account lacks sufficient permissions, or if the
- authentication system installed does not provide for changing
- passwords.</para>
+ <para>Navigates to the settings interface, which provides access to user
+ preferences such as display language. If you have access to
+ administrative functions, those are found within the settings interface,
+ as well, and are discussed in more detail in <xref
+ linkend="administration"/>.</para>
</listitem>
</varlistentry>
<varlistentry>
@@ -70,39 +73,11 @@
</listitem>
</varlistentry>
</variablelist>
- <para>If you have administrator-level access to Guacamole, you may also see options
- specific to managing users, connection, or sessions. These are discussed in more
- detail in <xref linkend="administration"/>.</para>
- <variablelist>
- <varlistentry>
- <term>Users</term>
- <listitem>
- <para>Shows all other Guacamole user accounts. Depending on your access
- level, users may be created, modified, and deleted.</para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>Manage connections</term>
- <listitem>
- <para>Shows available Guacamole connections and connection groups. Depending
- on your access level, the connections displayed here may be created,
- modified, and deleted.</para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>Active sessions</term>
- <listitem>
- <para>Shows all active Guacamole connections, the address from which the
- connection originates, and when the connection began. Administrators can
- select and kill active connections at will.</para>
- </listitem>
- </varlistentry>
- </variablelist>
</section>
</section>
<section xml:id="client-screen">
<title>Client screen</title>
- <para>Once you open a connection, you will see a realtime view of the remote display. You
+ <para>Once you open a connection, you will see a real-time view of the remote display. You
can interact with this display just as you would your normal desktop. Your mouse and
keyboard will function as if they were connected directly to the remote machine.</para>
<informalfigure>
@@ -177,6 +152,30 @@
text within the remote desktop, you will see that text within the text area, and can
manually copy it into the local clipboard if desired.</para>
</section>
+ <section xml:id="client-user-menu">
+ <title>Disconnecting and navigation</title>
+ <para>When you are done using the current connection, or you wish to navigate elsewhere
+ temporarily, options to do so are within the user menu inside the Guacamole menu:</para>
+ <informalfigure>
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="images/guac-menu-disconnect.png" format="PNG"
+ contentwidth="6in"/>
+ </imageobject>
+ <caption>
+ <para>The user menu within the Guacamole menu.</para>
+ </caption>
+ </mediaobject>
+ <para>The user menu within the Guacamole menu provides an additional "Disconnect" option
+ that allows you to explicitly close the current connection only. Clicking "Logout"
+ will also implicitly disconnect all active connections, including the current
+ connection.</para>
+ <para>Navigating back to the home screen or to the settings screen will not disconnect
+ you: your connection will continue running in the background while you change
+ settings or initiate another connection, and you can resume any active connection by
+ clicking on it within the home screen.</para>
+ </informalfigure>
+ </section>
<section xml:id="file-transfer">
<title>Transferring files</title>
<indexterm>
@@ -297,6 +296,14 @@
"relative" mouse emulation. Relative mouse emulation provides a way to deal with
the need for accurate pointer control, when a true pointer device is not
present.</para>
+ <informalfigure>
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="images/touchscreen.png" format="PNG"
+ contentwidth="1.5in"/>
+ </imageobject>
+ </mediaobject>
+ </informalfigure>
</section>
<section xml:id="relative-mouse-emulation">
<title>Relative mode (touchpad)</title>
@@ -311,6 +318,14 @@
pinch-to-zoom will not work while relative mouse emulation is enabled. Instead,
the screen will automatically pan to keep the mouse pointer in view, and you can
zoom through the buttons in the menu.</para>
+ <informalfigure>
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="images/touchpad.png" format="PNG"
+ contentwidth="1.5in"/>
+ </imageobject>
+ </mediaobject>
+ </informalfigure>
</section>
</section>
<section xml:id="text-input">
@@ -334,5 +349,60 @@
desktop.</para>
</section>
</section>
+ <section xml:id="preferences">
+ <title>Changing preferences</title>
+ <para>User preferences can be changed within the settings screen. These preferences are
+ stored locally within the browser, so if you use multiple computers to access Guacamole,
+ you can have different settings for each location. The settings screen allows users to
+ change the language of the Guacamole interface, to change the default input method used
+ by Guacamole connections, and to change the default mouse emulation mode for if a touch
+ device is used. If you have sufficient permissions, you may also change your password,
+ or administer the system.</para>
+ <informalfigure>
+ <screenshot>
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="images/guacamole-preferences.png" format="PNG"
+ contentwidth="6in"/>
+ </imageobject>
+ <caption>
+ <para>Guacamole preferences screen.</para>
+ </caption>
+ </mediaobject>
+ </screenshot>
+ </informalfigure>
+ <section xml:id="display-language">
+ <title>Display language</title>
+ <para>The Guacamole interface is currently available in English, French, and Russian. By
+ default, Guacamole will attempt to determine the appropriate display language by
+ checking the language preferences of the browser in use. If this fails, or the
+ browser is using a language not yet available within Guacamole, English will be used
+ as a fallback.</para>
+ <para>If you wish to override the current display language, you can do so by selecting a
+ different language within the "Display language" field. The change will take effect
+ immediately.</para>
+ </section>
+ <section xml:id="changing-password">
+ <title>Changing your password</title>
+ <para>System administrators can restrict the ability of individual users to change their
+ own passwords, so this section may not always be available. If your account
+ <emphasis>does</emphasis> have permission, the preferences screen will contain a
+ "Change Password" section.</para>
+ <para>To change your password, you must provide your current password, enter the desired
+ new password, and click "Update Password". You will remain logged in, and the change
+ will affect any future login attempt.</para>
+ </section>
+ <section xml:id="default-input-settings">
+ <title>Default input settings</title>
+ <para>Guacamole provides multiple keyboard input methods and multiple mouse emulation
+ modes. Many of these settings are specifically useful for touch devices, while
+ others are aimed mainly at traditional desktop use. By default, Guacamole will use
+ the keyboard and mouse modes most commonly preferred by users, but you can change
+ these defaults if they do not fit your tastes or your current device.</para>
+ <para>The choices available mirror those within the Guacamole menu discussed earlier in
+ this chapter, and changing these settings will affect the default values selected
+ within the Guacamole menu of future connections.</para>
+ </section>
+ </section>
</chapter>
