You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@guacamole.apache.org by vn...@apache.org on 2018/11/11 02:16:39 UTC
[2/5] guacamole-manual git commit: GUACAMOLE-220: Reorganize JDBC
auth documentation,
bringing high-level tasks to top-level sections and database-specific details
down into nested subsections.
GUACAMOLE-220: Reorganize JDBC auth documentation, bringing high-level tasks to top-level sections and database-specific details down into nested subsections.
Project: http://git-wip-us.apache.org/repos/asf/guacamole-manual/repo
Commit: http://git-wip-us.apache.org/repos/asf/guacamole-manual/commit/b8acdb8b
Tree: http://git-wip-us.apache.org/repos/asf/guacamole-manual/tree/b8acdb8b
Diff: http://git-wip-us.apache.org/repos/asf/guacamole-manual/diff/b8acdb8b
Branch: refs/heads/staging/1.0.0
Commit: b8acdb8b4a8f04dff4991c982fde6daff600971c
Parents: cc2da2e
Author: Michael Jumper <mj...@apache.org>
Authored: Wed Oct 24 23:25:47 2018 -0700
Committer: Michael Jumper <mj...@apache.org>
Committed: Sat Oct 27 23:44:28 2018 -0700
----------------------------------------------------------------------
src/chapters/jdbc-auth.xml | 252 +++++++++++++++++-----------------------
1 file changed, 105 insertions(+), 147 deletions(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/guacamole-manual/blob/b8acdb8b/src/chapters/jdbc-auth.xml
----------------------------------------------------------------------
diff --git a/src/chapters/jdbc-auth.xml b/src/chapters/jdbc-auth.xml
index eca6b58..c871fee 100644
--- a/src/chapters/jdbc-auth.xml
+++ b/src/chapters/jdbc-auth.xml
@@ -169,48 +169,9 @@
of choice, and also make sure that you obtain the proper licensing for the version
and edition of SQL Server you are running.</para>
<para>For the sake of clarity, these instructions will refer to the database as
- "guacamole_db" and the user as "guacamole_user", but the database and user can be named
- whatever you like. Naturally, you should also choose a real password for your user
- rather than the string "some_password" used as a placeholder below.</para>
+ "guacamole_db", but the database can be named whatever you like.</para>
<section xml:id="jdbc-auth-mysql">
<title>MySQL</title>
- <para>If using MySQL, you must create your database and user first:</para>
- <informalexample>
- <screen><prompt>$</prompt> mysql -u root -p
-<prompt>Enter password:</prompt> <userinput><replaceable>password</replaceable></userinput>
-<computeroutput>Welcome to the MySQL monitor. Commands end with ; or \g.
-Your MySQL connection id is 233
-Server version: 5.5.29-0ubuntu0.12.10.1 (Ubuntu)
-
-Copyright (c) 2000, 2012, Oracle and/or its affiliates. All rights reserved.
-
-Oracle is a registered trademark of Oracle Corporation and/or its
-affiliates. Other names may be trademarks of their respective
-owners.
-
-Type 'help;' or '\h' for help. Type '\c' to clear the current input statement.
-</computeroutput>
-<prompt>mysql></prompt> <userinput>CREATE DATABASE <replaceable>guacamole_db</replaceable>;</userinput>
-<computeroutput>Query OK, 1 row affected (0.00 sec)</computeroutput>
-
-<prompt>mysql></prompt> <userinput>CREATE USER '<replaceable>guacamole_user'</replaceable>@'localhost' IDENTIFIED BY '<replaceable>some_password</replaceable>';</userinput>
-<computeroutput>Query OK, 0 rows affected (0.00 sec)</computeroutput>
-
-<prompt>mysql></prompt> <userinput>GRANT SELECT,INSERT,UPDATE,DELETE ON <replaceable>guacamole_db</replaceable>.* TO '<replaceable>guacamole_user'</replaceable>@'localhost';</userinput>
-<computeroutput>Query OK, 0 rows affected (0.00 sec)</computeroutput>
-
-<prompt>mysql></prompt> <userinput>FLUSH PRIVILEGES;</userinput>
-<computeroutput>Query OK, 0 rows affected (0.02 sec)</computeroutput>
-
-<prompt>mysql></prompt> <userinput>quit</userinput>
-<computeroutput>Bye</computeroutput>
-<prompt>$</prompt></screen>
- </informalexample>
- <para>Once the database and user are created, the database schema must be applied by
- running the supplied SQL scripts. These SQL scripts are included in the
- <filename>mysql/schema/</filename> directory of the archive you downloaded from
- the Guacamole website. They are named such that they can be run in order with one
- command:</para>
<informalexample>
<screen><prompt>$</prompt> <userinput>ls schema/</userinput>
<computeroutput>001-create-schema.sql 002-create-admin-user.sql upgrade</computeroutput>
@@ -218,41 +179,9 @@ Type 'help;' or '\h' for help. Type '\c' to clear the current input statement.
<prompt>Enter password:</prompt> <userinput><replaceable>password</replaceable></userinput>
<prompt>$</prompt></screen>
</informalexample>
- <para>If the operation is successful, all tables have been created successfully, and the
- database is now ready for use.</para>
- <important xml:id="jdbc-auth-mysql-upgrade">
- <para>If you are upgrading from an older version of Guacamole and were already using
- MySQL, you may need to run one or more database schema upgrade scripts located
- within the <filename>schema/upgrade/</filename> directory. Each of these scripts
- is named <filename>upgrade-pre-<replaceable>VERSION</replaceable>.sql</filename>
- where <replaceable>VERSION</replaceable> is the version of Guacamole where those
- changes were introduced. They need to be run when you are upgrading from a
- version of Guacamole older than <replaceable>VERSION</replaceable>.</para>
- <para>These scripts are incremental and, when relevant, <emphasis>must be run in
- order</emphasis>. For example, if you are upgrading an existing database
- from version 0.9.10-incubating to version 0.9.13-incubating, you would need to
- run the <filename>upgrade-pre-0.9.11.sql</filename> script (because 0.9.10 is
- older than 0.9.11), followed by the <filename>upgrade-pre-0.9.13.sql</filename>
- script (because 0.9.10 is also older than 0.9.13):</para>
- <informalexample>
- <screen><prompt>$</prompt> <userinput>mysql -u root -p <replaceable>guacamole_db</replaceable> < schema/upgrade/upgrade-pre-0.9.11.sql</userinput>
-<prompt>Enter password:</prompt> <userinput><replaceable>password</replaceable></userinput>
-<prompt>$</prompt>
-<prompt>$</prompt> <userinput>mysql -u root -p <replaceable>guacamole_db</replaceable> < schema/upgrade/upgrade-pre-0.9.13.sql</userinput>
-<prompt>Enter password:</prompt> <userinput><replaceable>password</replaceable></userinput>
-<prompt>$</prompt></screen>
- </informalexample>
- <para>If there are no
- <filename>upgrade-pre-<replaceable>VERSION</replaceable>.sql</filename>
- scripts present in the <filename>schema/upgrade/</filename> directory which
- apply to your existing Guacamole database, then the schema has not changed
- between your version and the version your are installing, and there is no need
- to run any database upgrade scripts.</para>
- </important>
</section>
<section xml:id="jdbc-auth-postgresql">
<title>PostgreSQL</title>
- <para>If using PostgreSQL, the database and schema must be created first:</para>
<informalexample>
<screen><prompt>$</prompt> <userinput>createdb <replaceable>guacamole_db</replaceable></userinput>
<prompt>$</prompt> <userinput>ls schema/</userinput>
@@ -269,16 +198,59 @@ INSERT 0 4
INSERT 0 3</computeroutput>
<prompt>$</prompt></screen>
</informalexample>
- <para>Once the database exists, you can safely create a new user for the database, and
- grant that user sufficient privileges to manage the contents of all tables in the
- database:</para>
+ </section>
+ <section xml:id="jdbc-auth-sqlserver">
+ <title>SQL Server</title>
+ <informalexample>
+ <screen><prompt>$</prompt> <userinput>/opt/mssql-tools/bin/sqlcmd -S localhost -U SA -d <replaceable>guacamole_db</replaceable> -i schema/001-create-schema.sql</userinput>
+<prompt>Password:</prompt> <userinput><replaceable>password</replaceable></userinput>
+<computeroutput>Rule bound to data type.
+The new rule has been bound to column(s) of the specified user data type.
+Rule bound to data type.
+The new rule has been bound to column(s) of the specified user data type.</computeroutput>
+<prompt>$</prompt> <userinput>/opt/mssql-tools/bin/sqlcmd -S localhost -U SA -d <replaceable>guacamole_db</replaceable> -i schema/002-create-admin-user.sql</userinput>
+<prompt>Password:</prompt> <userinput><replaceable>password</replaceable></userinput>
+<computeroutput>
+(1 rows affected)
+
+(3 rows affected)
+
+(5 rows affected)</computeroutput>
+</screen>
+ </informalexample>
+ </section>
+ </section>
+ <section>
+ <title>Upgrading an existing Guacamole database</title>
+ <para>If you are upgrading from an older version of Guacamole, you may need to run one or
+ more database schema upgrade scripts located within the
+ <filename>schema/upgrade/</filename> directory. Each of these scripts is named
+ <filename>upgrade-pre-<replaceable>VERSION</replaceable>.sql</filename> where
+ <replaceable>VERSION</replaceable> is the version of Guacamole where those changes
+ were introduced. They need to be run when you are upgrading from a version of Guacamole
+ older than <replaceable>VERSION</replaceable>.</para>
+ <para>If there are no
+ <filename>upgrade-pre-<replaceable>VERSION</replaceable>.sql</filename> scripts
+ present in the <filename>schema/upgrade/</filename> directory which apply to your
+ existing Guacamole database, then the schema has not changed between your version and
+ the version your are installing, and there is no need to run any database upgrade
+ scripts.</para>
+ <para>These scripts are incremental and, when relevant, <emphasis>must be run in
+ order</emphasis>. For example, if you are upgrading an existing database from
+ version 0.9.13-incubating to version 1.0.0, you would need to run the
+ <filename>upgrade-pre-0.9.14.sql</filename> script (because 0.9.13-incubating is
+ older than 0.9.14), followed by the <filename>upgrade-pre-1.0.0.sql</filename> script
+ (because 0.9.13-incubating is also older than 1.0.0).</para>
+ <important xml:id="jdbc-auth-postgresql-upgrade">
+ <para>Because the permissions granted to the Guacamole-specific PostgreSQL user when the
+ database was first created will not automatically be granted for any new tables and
+ sequences, you will also need to re-grant those permissions after applying any
+ upgrade relevant scripts:</para>
<informalexample>
<screen><prompt>$</prompt> <userinput>psql -d <replaceable>guacamole_db</replaceable></userinput>
<computeroutput>psql (9.3.6)
Type "help" for help.
</computeroutput>
-<prompt>guacamole=# </prompt><userinput>CREATE USER <replaceable>guacamole_user</replaceable> WITH PASSWORD '<replaceable>some_password</replaceable>';</userinput>
-<computeroutput>CREATE ROLE</computeroutput>
<prompt>guacamole=# </prompt><userinput>GRANT SELECT,INSERT,UPDATE,DELETE ON ALL TABLES IN SCHEMA public TO <replaceable>guacamole_user</replaceable>;</userinput>
<computeroutput>GRANT</computeroutput>
<prompt>guacamole=# </prompt><userinput>GRANT SELECT,USAGE ON ALL SEQUENCES IN SCHEMA public TO <replaceable>guacamole_user</replaceable>;</userinput>
@@ -286,66 +258,74 @@ Type "help" for help.
<prompt>guacamole=# </prompt><userinput>\q</userinput>
<prompt>$</prompt></screen>
</informalexample>
- <important xml:id="jdbc-auth-postgresql-upgrade">
- <para>If you are upgrading from an older version of Guacamole and were already using
- PostgreSQL, you may need to run one or more database schema upgrade scripts
- located within the <filename>schema/upgrade/</filename> directory. Each of these
- scripts is named
- <filename>upgrade-pre-<replaceable>VERSION</replaceable>.sql</filename>
- where <replaceable>VERSION</replaceable> is the version of Guacamole where those
- changes were introduced. They need to be run when you are upgrading from a
- version of Guacamole older than <replaceable>VERSION</replaceable>.</para>
- <para>These scripts are incremental and, when relevant, <emphasis>must be run in
- order</emphasis>. For example, if you are upgrading an existing database
- from version 0.9.10-incubating to version 0.9.13-incubating, you would need to
- run the <filename>upgrade-pre-0.9.11.sql</filename> script (because 0.9.10 is
- older than 0.9.11), followed by the <filename>upgrade-pre-0.9.13.sql</filename>
- script (because 0.9.10 is also older than 0.9.13):</para>
- <informalexample>
- <screen><prompt>$</prompt> <userinput>psql -d <replaceable>guacamole_db</replaceable> -f schema/upgrade/upgrade-pre-0.9.11.sql</userinput>
-<computeroutput>ALTER TABLE
-CREATE TABLE
-CREATE INDEX</computeroutput>
-<prompt>$</prompt> <userinput>psql -d <replaceable>guacamole_db</replaceable> -f schema/upgrade/upgrade-pre-0.9.13.sql</userinput>
-<computeroutput>CREATE TYPE
-ALTER TABLE
-ALTER TABLE
-ALTER TABLE
-ALTER TABLE
-ALTER TABLE
-ALTER TABLE
-ALTER TABLE</computeroutput>
+ </important>
+ </section>
+ <section>
+ <title>Granting Guacamole access to the database</title>
+ <para>For Guacamole to be able to execute queries against the database, you must create a
+ new user for the database and grant that user sufficient privileges to manage the
+ contents of all tables in the database. The user created for Guacamole needs only
+ <code>SELECT</code>, <code>UPDATE</code>, <code>INSERT</code>, and
+ <code>DELETE</code> permissions on all Guacamole tables. Additionally, if using
+ PostgreSQL, the user will need <code>SELECT</code> and <code>USAGE</code> permission on
+ all sequences within all Guacamole tables. <emphasis>No other permissions should be
+ granted.</emphasis></para>
+ <para>These instructions will refer to the user as "guacamole_user" but the user can be
+ named whatever you like. Naturally, you should also choose a real password for your user
+ rather than the string "some_password" used as a placeholder below.</para>
+ <section>
+ <title>MySQL</title>
+ <informalexample>
+ <screen><prompt>$</prompt> mysql -u root -p
+<prompt>Enter password:</prompt> <userinput><replaceable>password</replaceable></userinput>
+<computeroutput>Welcome to the MySQL monitor. Commands end with ; or \g.
+Your MySQL connection id is 233
+Server version: 5.5.29-0ubuntu0.12.10.1 (Ubuntu)
+
+Copyright (c) 2000, 2012, Oracle and/or its affiliates. All rights reserved.
+
+Oracle is a registered trademark of Oracle Corporation and/or its
+affiliates. Other names may be trademarks of their respective
+owners.
+
+Type 'help;' or '\h' for help. Type '\c' to clear the current input statement.
+</computeroutput>
+<prompt>mysql></prompt> <userinput>CREATE DATABASE <replaceable>guacamole_db</replaceable>;</userinput>
+<computeroutput>Query OK, 1 row affected (0.00 sec)</computeroutput>
+
+<prompt>mysql></prompt> <userinput>CREATE USER '<replaceable>guacamole_user'</replaceable>@'localhost' IDENTIFIED BY '<replaceable>some_password</replaceable>';</userinput>
+<computeroutput>Query OK, 0 rows affected (0.00 sec)</computeroutput>
+
+<prompt>mysql></prompt> <userinput>GRANT SELECT,INSERT,UPDATE,DELETE ON <replaceable>guacamole_db</replaceable>.* TO '<replaceable>guacamole_user'</replaceable>@'localhost';</userinput>
+<computeroutput>Query OK, 0 rows affected (0.00 sec)</computeroutput>
+
+<prompt>mysql></prompt> <userinput>FLUSH PRIVILEGES;</userinput>
+<computeroutput>Query OK, 0 rows affected (0.02 sec)</computeroutput>
+
+<prompt>mysql></prompt> <userinput>quit</userinput>
+<computeroutput>Bye</computeroutput>
<prompt>$</prompt></screen>
- </informalexample>
- <para>Because the permissions granted to the Guacamole-specific PostgreSQL user when
- the database was first created will not automatically be granted for any new
- tables and sequences, you will also need to re-grant those permissions after
- applying any upgrade relevant scripts:</para>
- <informalexample>
- <screen><prompt>$</prompt> <userinput>psql -d <replaceable>guacamole_db</replaceable></userinput>
+ </informalexample>
+ </section>
+ <section>
+ <title>PostgreSQL</title>
+ <informalexample>
+ <screen><prompt>$</prompt> <userinput>psql -d <replaceable>guacamole_db</replaceable></userinput>
<computeroutput>psql (9.3.6)
Type "help" for help.
</computeroutput>
+<prompt>guacamole=# </prompt><userinput>CREATE USER <replaceable>guacamole_user</replaceable> WITH PASSWORD '<replaceable>some_password</replaceable>';</userinput>
+<computeroutput>CREATE ROLE</computeroutput>
<prompt>guacamole=# </prompt><userinput>GRANT SELECT,INSERT,UPDATE,DELETE ON ALL TABLES IN SCHEMA public TO <replaceable>guacamole_user</replaceable>;</userinput>
<computeroutput>GRANT</computeroutput>
<prompt>guacamole=# </prompt><userinput>GRANT SELECT,USAGE ON ALL SEQUENCES IN SCHEMA public TO <replaceable>guacamole_user</replaceable>;</userinput>
<computeroutput>GRANT</computeroutput>
<prompt>guacamole=# </prompt><userinput>\q</userinput>
<prompt>$</prompt></screen>
- </informalexample>
- <para>If there are no
- <filename>upgrade-pre-<replaceable>VERSION</replaceable>.sql</filename>
- scripts present in the <filename>schema/upgrade/</filename> directory which
- apply to your existing Guacamole database, then the schema has not changed
- between your version and the version your are installing, and there is no need
- to run any database upgrade scripts.</para>
- </important>
+ </informalexample>
</section>
- <section xml:id="jdbc-auth-sqlserver">
+ <section>
<title>SQL Server</title>
- <para>If using SQL Server, the database and schema must be created first. The example below assumes
- that you are running SQL Server on Linux, using the command-line tools to manage it, however, this
- code can be run using any tool capable of running SQL against a SQL Server database.</para>
<informalexample>
<screen><prompt>$</prompt> <userinput>/opt/mssql-tools/bin/sqlcmd -S localhost -U SA</userinput>
<prompt>Password:</prompt> <userinput><replaceable>password</replaceable></userinput>
@@ -361,28 +341,6 @@ Type "help" for help.
<prompt>2></prompt> <userinput>ALTER ROLE db_datareader ADD MEMBER <replaceable>guacamole_user</replaceable>;</userinput>
<prompt>3></prompt> <userinput>GO</userinput></screen>
</informalexample>
- <para>Once the database and user account is created, and the user associated with the database, you can use
- the supplied scripts to load the schema into the database. These scripts are included in the
- <filename>sqlserver/schema/</filename> directory of the archive you downloaded from the Guacamole
- web site.</para>
- <informalexample>
- <screen><prompt>$</prompt> <userinput>/opt/mssql-tools/bin/sqlcmd -S localhost -U <replaceable>guacamole_user</replaceable> -d <replaceable>guacamole_db</replaceable> -i schema/001-create-schema.sql</userinput>
-<prompt>Password:</prompt> <userinput><replaceable>some_password</replaceable></userinput>
-<computeroutput>Rule bound to data type.
-The new rule has been bound to column(s) of the specified user data type.
-Rule bound to data type.
-The new rule has been bound to column(s) of the specified user data type.</computeroutput>
-<prompt>$</prompt> <userinput>/opt/mssql-tools/bin/sqlcmd -S localhost -U <replaceable>guacamole_user</replaceable> -d <replaceable>guacamole_db</replaceable> -i schema/002-create-admin-user.sql</userinput>
-<prompt>Password:</prompt> <userinput><replaceable>some_password</replaceable></userinput>
-<computeroutput>
-(1 rows affected)
-
-(3 rows affected)
-
-(5 rows affected)</computeroutput></screen>
- </informalexample>
- <para>If the operation is successful, the tables and permissions have been created successfully, and you
- can now use the database with the Guacamole client web application.</para>
</section>
</section>
<section xml:id="jdbc-auth-installation">