Merge lp:~hingo/drizzle/7.1-docs-reviewfixes into lp:~drizzle-trunk/drizzle/development

Proposed by Henrik Ingo on 2011-11-14
Status: Merged
Approved by: Mark Atwood on 2011-11-15
Approved revision: 2458
Merged at revision: 2460
Proposed branch: lp:~hingo/drizzle/7.1-docs-reviewfixes
Merge into: lp:~drizzle-trunk/drizzle/development
Diff against target: 524 lines (+221/-122)
11 files modified
docs/administration/authentication.rst (+25/-13)
docs/administration/authorization.rst (+22/-4)
docs/administration/drizzled.rst (+12/-4)
docs/administration/logging.rst (+5/-5)
docs/administration/plugins.rst (+66/-31)
docs/configuration/options.rst (+15/-10)
docs/contributing/more_ways.rst (+3/-1)
docs/installing/from_source.rst (+67/-30)
docs/installing/redhat.rst (+0/-20)
plugin/auth_pam/docs/index.rst (+4/-4)
plugin/js/docs/index.rst (+2/-0)
To merge this branch: bzr merge lp:~hingo/drizzle/7.1-docs-reviewfixes
Reviewer Review Type Date Requested Status
Drizzle Merge Team 2011-11-14 Pending
Review via email: mp+82231@code.launchpad.net

Description of the change

Fixes to Daniel's new documentation as discussed / reviewed on drizzle-discuss.

To post a comment you must log in.

Preview Diff

[H/L] Next/Prev Comment, [J/K] Next/Prev File, [N/P] Next/Prev Hunk
1=== modified file 'docs/administration/authentication.rst'
2--- docs/administration/authentication.rst 2011-10-23 17:13:20 +0000
3+++ docs/administration/authentication.rst 2011-11-14 22:39:27 +0000
4@@ -2,26 +2,38 @@
5 ==============
6
7 Authentication is any process by which you verify that someone is who they
8-claim they are. [1]_ Drizzle authentication is handled by plugins; there
9-are no grant or privilege tables.
10-
11-One or more authentication plugin must be loaded, else no connections can
12+claim they are. [1]_
13+
14+Drizzle authentication is handled by plugins; by default there is no single
15+source where users are defined, such as a system user table, but each
16+authentication plugin will use different sources to verify the usernames
17+and passwords. (The plugin auth_schema does however keep users in a table inside
18+Drizzle, much like the familiar MySQL way of authenticating users works.).
19+*Choosing an authentication plugin, configuring it, and disabling all other
20+authentication plugins should be one of your first administrative tasks.*
21+
22+One or more authentication plugins must be loaded, else no connections can
23 be made to Drizzle. On most systems, the :doc:`/plugins/auth_all/index`
24 plugin is loaded by default which, as its name suggests, allows all
25 connections regardless of username or password. (Some distributions enable
26 the :doc:`/plugins/auth_file/index` plugin by default instead).
27
28-`Choosing an authentication plugin, configuring it, and disabling all other
29-authentication plugins should be one of your first administrative tasks.`
30+The :doc:`/plugins/auth_schema/index` plugin first shipped with ``Drizzle 7.1
31+Beta 2011.10.28``. This plugin provides an authentication method that is
32+both secure and easy to use, and it is similar to how MySQL authentication
33+works so will be familiar to many users. If you don't know which authentication
34+plugin to use, you should start with configuring
35+:doc:`/plugins/auth_schema/index`. Likewise we warmly recommend distributors to
36+consider enabling this plugin by default.
37
38 The following authentication plugins are included with Drizzle:
39
40-* :doc:`/plugins/auth_all/index`
41-* :doc:`/plugins/auth_file/index`
42-* :doc:`/plugins/auth_http/index`
43-* :doc:`/plugins/auth_ldap/index`
44-* :doc:`/plugins/auth_pam/index`
45-* :doc:`/plugins/auth_schema/index`
46+* :doc:`/plugins/auth_all/index` - Allow all connections without checking username or password.
47+* :doc:`/plugins/auth_file/index` - Define users and passwords in a text file that is read on startup.
48+* :doc:`/plugins/auth_http/index` - Authenticate the username and password against a http server.
49+* :doc:`/plugins/auth_ldap/index` - Define users and passwords in a LDAP directory.
50+* :doc:`/plugins/auth_pam/index` - Authenticate the username and password against system user accounts via PAM.
51+* :doc:`/plugins/auth_schema/index` - Define users and passwords in a system table.
52
53 Protocols
54 ---------
55@@ -48,7 +60,7 @@
56 :ref:`auth_all_plugin` Any
57 :ref:`auth_file_plugin` mysql
58 :ref:`auth_http_plugin` mysql-plugin-auth
59-:ref:`auth_ldap_plugin` mysql-plugin-auth
60+:ref:`auth_ldap_plugin` Any
61 :ref:`auth_pam_plugin` mysql-plugin-auth
62 :ref:`auth_schema_plugin` mysql
63 ========================= ==================
64
65=== modified file 'docs/administration/authorization.rst'
66--- docs/administration/authorization.rst 2011-10-23 05:45:09 +0000
67+++ docs/administration/authorization.rst 2011-11-14 22:39:27 +0000
68@@ -2,13 +2,31 @@
69 =============
70
71 Authorization is finding out if the person, once identified, is permitted to
72-have the resource. [1]_ Drizzle authorization is handled by plugins; there
73-are no grant or privilege tables.
74+have the resource. [1]_
75+
76+Drizzle authorization is handled by plugins. There is no single
77+source where users or access rights are defined, such as a system user table,
78+but each auhtorization plugin will use different sources to define or store
79+access rights. By default no authorization plugin is loaded, this means that
80+any logged in user is authorized to access all database objects and do anything
81+he wants (everyone is super user).
82
83 The following authorization plugins are included with Drizzle:
84
85-* :doc:`/plugins/regex_policy/index`
86-* :doc:`/plugins/simple_user_policy/index`
87+* :doc:`/plugins/regex_policy/index` - ALLOW or REJECT access by matching a regular expression against the table name.
88+* :doc:`/plugins/simple_user_policy/index` - Allow a user to only access a schema that matches their username.
89+
90+Limitations
91+-----------
92+
93+At the moment there doesn't exist a plugin which would implement anything
94+resembling the traditional SQL standard GRANT and REVOKE type of authorization.
95+You are invited to share your opinion on whether that level of authorization
96+control is necessary in a modern database.
97+
98+Note that at the moment there also is no plugin that would distinguish between
99+read and write operations, rather access is always granted to schemas and tables
100+in an all or nothing fashion.
101
102 -------------------------------------------------------------------------------
103
104
105=== modified file 'docs/administration/drizzled.rst'
106--- docs/administration/drizzled.rst 2011-10-23 05:45:09 +0000
107+++ docs/administration/drizzled.rst 2011-11-14 22:39:27 +0000
108@@ -77,13 +77,21 @@
109
110 The ``shutdown`` command is case-sensitive.
111
112-Output
113-------
114+Output and Logging
115+------------------
116
117 :program:`drizzled` does *not* close or redirect output to ``STDOUT`` or
118 ``STDERR`` to a log file or logging facility like :program:`syslog`.
119-You should redirect ``STDOUT`` and ``STDERR`` to a log file as in the above
120-script example for starting Drizzle manually.
121+When starting Drizzle, you should redirect ``STDOUT`` and ``STDERR`` to a log
122+file or to /dev/null, as in the above script example when starting Drizzle.
123+
124+When running :program:`drizzled` manually from a console, just allowing the
125+output to be printed for you can of course be useful.
126+
127+Note that beginning with the first ``Drizzle 7.1 Beta 2011.10.28`` drizzled
128+will also log messages via syslog and this is *in addition* to using ``STDOUT``
129+and ``STDERR``.
130+
131
132 Signaling
133 ---------
134
135=== modified file 'docs/administration/logging.rst'
136--- docs/administration/logging.rst 2011-10-23 16:01:37 +0000
137+++ docs/administration/logging.rst 2011-11-14 22:39:27 +0000
138@@ -12,11 +12,11 @@
139 redirected to a log file when
140 :ref:`starting Drizzle <starting_and_stopping_drizzled>`.
141
142-Since :program:`syslog` is the standard UNIX logging facility,
143-the :ref:`syslog_plugin` plugin is also loaded by default which will log error
144-messages to the system log (:file:`/var/log/syslog` on Ubuntu for example).
145-However, you must start :program:`drizzled` with
146-:option:`--syslog.errmsg-enable` to enable this feature.
147+Note that beginning with the first ``Drizzle 7.1 Beta 2011.10.28`` drizzled
148+will **also** log messages via syslog and this is *in addition* to using
149+``STDOUT`` and ``STDERR``. This functionality is provided by the
150+:ref:`syslog_plugin` plugin. (For example on Ubuntu these messages are written
151+to :file:`/var/log/syslog`).
152
153 Queries
154 -------
155
156=== modified file 'docs/administration/plugins.rst'
157--- docs/administration/plugins.rst 2011-10-23 05:45:09 +0000
158+++ docs/administration/plugins.rst 2011-11-14 22:39:27 +0000
159@@ -14,34 +14,69 @@
160
161 Drizzle loads these plugins by default (see :option:`--plugin-load`):
162
163-* auth_all (:ref:`auth_all_plugin`)
164-* ascii (:ref:`ascii_plugin`)
165-* benchmark (:ref:`benchmark_plugin`)
166-* charlength (:ref:`charlength_plugin`)
167-* compression (:ref:`compression_plugin`)
168-* connection_id (:ref:`connection_id_plugin`)
169-* crc32 (:ref:`crc32_plugin`)
170-* default_replicator (:ref:`default_replicator_plugin`)
171-* drizzle_protocol (:ref:`drizzle_protocol_plugin`)
172-* errmsg_stderr (:ref:`errmsg_stderr_plugin`)
173-* filtered_replicator (:ref:`filtered_replicator_plugin`)
174-* hex_functions (:ref:`hex_functions_plugin`)
175-* innobase (:ref:`innobase_plugin`)
176-* length (:ref:`length_plugin`)
177-* logging_stats (:ref:`logging_stats_plugin`)
178-* math_functions (:ref:`math_functions_plugin`)
179-* md5 (:ref:`md5_plugin`)
180-* memory (:ref:`memory_plugin`)
181-* multi_thread (:ref:`multi_thread_plugin`)
182-* myisam (:ref:`myisam_plugin`)
183-* mysql_protocol (:ref:`mysql_protocol_plugin`)
184-* mysql_unix_socket_protocol (:ref:`mysql_unix_socket_protocol_plugin`)
185-* rand_function (:ref:`rand_function_plugin`)
186-* reverse_function (:ref:`reverse_function_plugin`)
187-* sleep (:ref:`sleep_plugin`)
188-* show_schema_proto (:ref:`show_schema_proto_plugin`)
189-* substr_functions (:ref:`substr_functions_plugin`)
190-* syslog (:ref:`syslog_plugin`)
191-* transaction_log (:ref:`transaction_log_plugin`)
192-* uuid_function (:ref:`uuid_function_plugin`)
193-* version (:ref:`version_plugin`)
194+ * :ref:`ascii_plugin` - Return the ASCII value of a character (ascii)
195+ * :ref:`auth_all_plugin` - Data Dictionary for utility tables (auth_all)
196+ * :ref:`benchmark_plugin` - Measure time for repeated calls to a function. (benchmark)
197+ * :ref:`catalog_plugin` - Basic Catalog functions, data dictionary, and system. (catalog)
198+ * :ref:`charlength_plugin` - Return the number of characters in a string (charlength)
199+ * :ref:`collation_dictionary_plugin` - Data Dictionary for schema, table, column, indexes, etc (collation_dictionary)
200+ * :ref:`compression_plugin` - UDFs for compression functions (compression)
201+ * :ref:`connection_id_plugin` - Return the current connection_id (connection_id)
202+ * :ref:`console_plugin` - Console Client (console)
203+ * :ref:`crc32_plugin` - CRC32 Function (crc32)
204+ * :ref:`default_replicator_plugin` - Default Replicator (default_replicator)
205+ * :ref:`drizzle_protocol_plugin` - Drizzle Protocol (drizzle_protocol)
206+ * :ref:`errmsg_stderr_plugin` - Error Messages to stderr (errmsg_stderr)
207+ * :ref:`error_dictionary_plugin` - Data Dictionary for Errors. (error_dictionary)
208+ * :ref:`function_engine_plugin` - Function Engine provides the infrastructure for Table Functions,etc. (function_engine)
209+ * :ref:`hex_functions_plugin` - Convert a string to HEX() or from UNHEX() (hex_functions)
210+ * :ref:`information_schema_dictionary_plugin` - Data Dictionary for ANSI information schema, etc (information_schema_dictionary)
211+ * :ref:`innobase_plugin` - Supports transactions, row-level locking, and foreign keys (innobase)
212+ * :ref:`ipv6_function_plugin` - IPV6() function (ipv6_function)
213+ * :ref:`js_plugin` - Execute JavaScript code with supplied arguments (js)
214+ * :ref:`length_plugin` - Return the byte length of a string (length)
215+ * :ref:`logging_stats_plugin` - User Statistics as DATA_DICTIONARY tables (logging_stats)
216+ * :ref:`math_functions_plugin` - Math Functions. (math_functions)
217+ * :ref:`md5_plugin` - UDF for computing md5sum (md5)
218+ * :ref:`memory_plugin` - Hash based, stored in memory, useful for temporary tables (memory)
219+ * :ref:`multi_thread_plugin` - One Thread Per Session Scheduler (multi_thread)
220+ * :ref:`myisam_plugin` - Default engine as of MySQL 3.23 with great performance (myisam)
221+ * :ref:`mysql_protocol_plugin` - MySQL Protocol Module (mysql_protocol)
222+ * :ref:`mysql_unix_socket_protocol_plugin` - MySQL Unix Socket Protocol (mysql_unix_socket_protocol)
223+ * :ref:`protocol_dictionary_plugin` - Provides dictionary for protocol counters. (protocol_dictionary)
224+ * :ref:`rand_function_plugin` - RAND Function (rand_function)
225+ * :ref:`registry_dictionary_plugin` - Provides dictionary for plugin registry system. (registry_dictionary)
226+ * :ref:`replication_dictionary_plugin` - Replication Dictionary (replication_dictionary)
227+ * :ref:`reverse_function_plugin` - reverses a string (reverse_function)
228+ * :ref:`schema_dictionary_plugin` - Data Dictionary for schema, table, column, indexes, etc (schema_dictionary)
229+ * :ref:`schema_engine_plugin` - This implements the default file based Schema engine. (schema_engine)
230+ * :ref:`session_dictionary_plugin` - Dictionary for session information, aka proccesslist, user defined variables, etc. (session_dictionary)
231+ * :ref:`show_dictionary_plugin` - Dictionary for show commands. (show_dictionary)
232+ * :ref:`show_schema_proto_plugin` - Shows text representation of schema definition proto (show_schema_proto)
233+ * :ref:`signal_handler_plugin` - Default Signal Handler (signal_handler)
234+ * :ref:`sleep_plugin` - SLEEP Function (sleep)
235+ * :ref:`status_dictionary_plugin` - Dictionary for status, statement, and variable information. (status_dictionary)
236+ * :ref:`string_functions_plugin` - String Functions. (string_functions)
237+ * :ref:`substr_functions_plugin` - SUBSTR and SUBSTR (substr_functions)
238+ * :ref:`syslog_plugin` - Syslog (syslog)
239+ * :ref:`table_cache_dictionary_plugin` - Data Dictionary for table and table definition cache. (table_cache_dictionary)
240+ * :ref:`transaction_log_plugin` - Transaction Log (transaction_log)
241+ * :ref:`user_locks_plugin` - User level locking and barrier functions (user_locks)
242+ * :ref:`utility_functions_plugin` - Utility Functions. (utility_functions)
243+ * :ref:`uuid_function_plugin` - UUID() function using libuuid (uuid_function)
244+ * :ref:`version_plugin` - Print Drizzle version (version)
245+
246+You can list information about the loaded plugins with:
247+
248+.. code-block:: mysql
249+
250+ SELECT * FROM DATA_DICTIONARY.MODULES;
251+
252+Note to editors: The above list of functions can be regenerated at any time with:
253+
254+.. code-block:: mysql
255+
256+ drizzle --silent -e "SELECT CONCAT(' * ', ':ref:\`', MODULE_LIBRARY, '_plugin\` - ', MODULE_DESCRIPTION, ' (', MODULE_LIBRARY, ')')
257+ FROM DATA_DICTIONARY.MODULES ORDER BY MODULE_LIBRARY;"
258+
259+
260
261=== modified file 'docs/configuration/options.rst'
262--- docs/configuration/options.rst 2011-11-06 00:00:03 +0000
263+++ docs/configuration/options.rst 2011-11-14 22:39:27 +0000
264@@ -23,7 +23,7 @@
265 ``drizzled --plugin-add PLUGIN --help`` where ``PLUGIN`` is the name of any
266 plugin. For example:
267
268-.. code-block:: bash
269+.. code-block:: none
270
271 $ drizzled --plugin-add query_log --help
272 sbin/drizzled Ver 2011.08.25.2411 for pc-linux-gnu on i686 (Source distribution (trunk))
273@@ -149,9 +149,9 @@
274 in this directory.)
275
276 A good strategy for configuring Drizzle with multiple config files is to
277-put :ref:`drizzled_options` in :file:`/etc/drizzle/drizzled.cnf`
278+put general :ref:`drizzled_options` in :file:`/etc/drizzle/drizzled.cnf`
279 (:file:`/etc/drizzle` is the default :option:`--config-dir` value)
280-and plugin options in spearate config files in
281+and any options related to a plugin in a separate config file in
282 :file:`/etc/drizzle/conf.d/`. For example:
283
284 .. code-block:: bash
285@@ -168,15 +168,20 @@
286
287 .. code-block:: ini
288
289+ server-id=42
290+ core-file
291+
292+.. code-block:: bash
293+
294+ $ cat /etc/drizzle/conf.d/auth-file
295+
296+.. code-block:: ini
297+
298+ # drizzled option to load the auth_file plugin
299 plugin-remove=auth_all
300 plugin-add=auth_file
301-
302-.. code-block:: bash
303-
304- $ cat /etc/drizzle/conf.d/auth-file
305-
306-.. code-block:: ini
307-
308+
309+ # Options for the plugin itself
310 [auth-file]
311 users=/etc/drizzle/users
312
313
314=== modified file 'docs/contributing/more_ways.rst'
315--- docs/contributing/more_ways.rst 2011-10-23 05:45:09 +0000
316+++ docs/contributing/more_ways.rst 2011-11-14 22:39:27 +0000
317@@ -18,4 +18,6 @@
318
319 Drizzle is an Associated Project at the
320 `Software in the Public Interest (SPI) <http://spi-inc.org/>`_. You
321-can make a financial donation to Drizzle through the SPI.
322+can `make a financial donation to Drizzle
323+<https://co.clickandpledge.com/advanced/default.aspx?wid=46722>`_ through the
324+SPI.
325
326=== modified file 'docs/installing/from_source.rst'
327--- docs/installing/from_source.rst 2011-10-23 05:45:09 +0000
328+++ docs/installing/from_source.rst 2011-11-14 22:39:27 +0000
329@@ -1,11 +1,38 @@
330 Installing Drizzle from Source
331 ==============================
332
333+* :ref:`obtain-source`
334+* :ref:`compile-source`
335 * :ref:`dependencies`
336 * :ref:`ubuntu-install`
337 * :ref:`debian-install`
338-* :ref:`obtain-source`
339-* :ref:`compile-source`
340+* :ref:`redhat-install`
341+
342+.. _obtain-source:
343+
344+Obtaining the Source
345+--------------------
346+The latest source release can always be found on our `LaunchPad site
347+<https://launchpad.net/drizzle>`_. Alternatively, the bzr source from our stable
348+trunk can be obtained by doing:
349+
350+.. code-block:: bash
351+
352+ bzr branch lp:drizzle
353+
354+.. _compile-source:
355+
356+Compiling the Source
357+--------------------
358+Compiling is done by performing the standard automake commands from the top level directory inside the source:
359+
360+.. code-block:: bash
361+
362+ ./config/autorun.sh
363+ ./configure
364+ make
365+ make install
366+
367
368 .. _dependencies:
369
370@@ -53,6 +80,7 @@
371 * libpam0g-dev
372 * libprotobuf-dev (>= 2.1.0)
373 * libtokyocabinet-dev (>= 1.4.23)
374+ * libv8-dev
375 * systemtap-sdt-dev
376 * libnotifymm-dev
377 * doxygen
378@@ -60,8 +88,8 @@
379
380 .. _ubuntu-install:
381
382-Ubuntu Install Commands
383------------------------
384+Installing Build Dependencies on Ubuntu
385+---------------------------------------
386
387 The following commands work on Ubuntu to install the tools and libraries needed to build Drizzle:
388
389@@ -74,8 +102,8 @@
390
391 .. _debian-install:
392
393-Debian Install Commands
394------------------------
395+Installing Build Dependencies on Debian
396+---------------------------------------
397
398 Since apt-repository isn't in Debian, you can instead add the Maverick PPA to /etc/apt/sources.list as follows:
399
400@@ -109,28 +137,37 @@
401
402 apt-get install drizzle
403
404-.. _obtain-source:
405-
406-Obtaining the Source
407---------------------
408-The latest source release can always be found on our `LaunchPad site
409-<https://launchpad.net/drizzle>`_. Alternatively, the bzr source from our stable
410-trunk can be obtained by doing:
411-
412-.. code-block:: bash
413-
414- bzr branch lp:drizzle
415-
416-.. _compile-source:
417-
418-Compiling the Source
419---------------------
420-Compiling is done by performing the standard automake commands from the top level directory inside the source:
421-
422-.. code-block:: bash
423-
424- ./config/autorun.sh
425- ./configure
426- make
427- make install
428+.. _redhat-install:
429+
430+Installing Build Dependencies on Red Hat or Fedora
431+--------------------------------------------------
432+
433+Depending on whether you use Red Hat (RHEL) or Fedora, you should add the
434+repositories as explained in :doc:`redhat`.
435+
436+After that, install the following packages:
437+
438+ * bzr
439+ * boost-devel
440+ * autoconf
441+ * automake
442+ * gcc
443+ * gcc-c++
444+ * libtool
445+ * gperf
446+ * libuuid-devel (part of e2fsprogs-devel on older RedHat based distributions)
447+ * zlib-devel
448+ * pcre-devel
449+ * readline-devel
450+ * flex
451+ * bison
452+
453+Note that you should be able to install all of the above simply with
454+
455+.. code-block:: bash
456+
457+ yum-builddep drizzle
458+
459+
460+
461
462
463=== modified file 'docs/installing/redhat.rst'
464--- docs/installing/redhat.rst 2011-10-23 05:45:09 +0000
465+++ docs/installing/redhat.rst 2011-11-14 22:39:27 +0000
466@@ -73,23 +73,3 @@
467
468 sudo yum install drizzle7-server drizzle7-client
469
470-Compiling from Source
471----------------------
472-To compile from source you will need to add the repositories described above, and then install the following packages:
473-
474- * bzr
475- * boost-devel
476- * autoconf
477- * automake
478- * gcc
479- * gcc-c++
480- * libtool
481- * gperf
482- * libuuid-devel (part of e2fsprogs-devel on older RedHat based distributions)
483- * zlib-devel
484- * pcre-devel
485- * readline-devel
486- * flex
487- * bison
488-
489-You will then be able to compile from source in the normal way.
490
491=== modified file 'plugin/auth_pam/docs/index.rst'
492--- plugin/auth_pam/docs/index.rst 2011-11-06 00:00:03 +0000
493+++ plugin/auth_pam/docs/index.rst 2011-11-14 22:39:27 +0000
494@@ -81,7 +81,7 @@
495
496 Then connect to Drizzle like:
497
498-.. code-block:: bash
499+.. code-block:: none
500
501 $ bin/drizzle -P --protocol mysql-plugin-auth
502 Enter password: [Enter your system password here]
503@@ -99,9 +99,9 @@
504 protocol sends the password in plaintext to Drizzle, which
505 is required for PAM based authentication.
506
507-Note that you don't need to specify the ``-u`` or ``--user`` argument, since
508-Drizzle will default to using your system username, which is exactly what we
509-want when using auth_pam.
510+Note that you typically don't need to specify the ``-u`` or ``--user`` argument,
511+since Drizzle will default to using your system username, which is exactly what
512+we want when using auth_pam.
513
514 .. _auth_pam_security:
515
516
517=== modified file 'plugin/js/docs/index.rst'
518--- plugin/js/docs/index.rst 2011-10-01 10:06:00 +0000
519+++ plugin/js/docs/index.rst 2011-11-14 22:39:27 +0000
520@@ -1,3 +1,5 @@
521+.. _js_plugin:
522+
523 JS
524 ===========
525