diff --git a/doc/config.rst b/doc/config.rst
index 005c3ca42e..1004615ff3 100644
--- a/doc/config.rst
+++ b/doc/config.rst
@@ -5,10 +5,15 @@
Configuration
=============
-Almost all configurable data is placed in :file:`config.inc.php`. If this file
-does not exist, please refer to the :ref:`setup` section to create one. This
-file only needs to contain the parameters you want to change from their
-corresponding default value in :file:`libraries/config.default.php`.
+All configurable data is placed in :file:`config.inc.php` in phpMyAdmin's
+toplevel directory. If this file does not exist, please refer to the
+:ref:`setup` section to create one. This file only needs to contain the
+parameters you want to change from their corresponding default value in
+:file:`libraries/config.default.php` (this file is not inteded for changes).
+
+.. seealso::
+
+ :ref:`config-examples` for examples of configurations
If a directive is missing from your file, you can just add another line with
the file. This file is for over-writing the defaults; if you wish to use the
@@ -49,13 +54,12 @@ Basic settings
Sets here the complete :term:`URL` (with full path) to your phpMyAdmin
installation's directory. E.g.
``http://www.example.net/path_to_your_phpMyAdmin_directory/``. Note also
- that the :term:`URL` on most of web servers are case–sensitive. Don’t
- forget the trailing slash at the end.
+ that the :term:`URL` on most of web servers are case sensitive (even on
+ Windows). Don’t forget the trailing slash at the end.
Starting with version 2.3.0, it is advisable to try leaving this blank. In
most cases phpMyAdmin automatically detects the proper setting. Users of
- port forwarding will need to set :config:option:`$cfg['PmaAbsoluteUri']`
- (`more info `_).
+ port forwarding or complex reverse proxy setup might need to set this.
A good test is to browse a table, edit a row and save it. There should be
an error message if phpMyAdmin is having trouble auto–detecting the correct
@@ -458,13 +462,13 @@ Server connection settings
Whether config or cookie or :term:`HTTP` or signon authentication should be
used for this server.
- * 'config' authentication (``$auth_type = 'config'``) is the plain old
+ * 'config' authentication (``$auth_type = 'config'``) is the plain old
way: username and password are stored in :file:`config.inc.php`.
- * 'cookie' authentication mode (``$auth_type = 'cookie'``) allows you to
+ * 'cookie' authentication mode (``$auth_type = 'cookie'``) allows you to
log in as any valid MySQL user with the help of cookies.
* 'http' authentication allows you to log in as any
valid MySQL user via HTTP-Auth.
- * 'signon' authentication mode (``$auth_type = 'signon'``) allows you to
+ * 'signon' authentication mode (``$auth_type = 'signon'``) allows you to
log in from prepared PHP session data or using supplied PHP script.
.. seealso:: :ref:`authentication_modes`
@@ -2967,11 +2971,69 @@ Developer
This is used for `phpMyAdmin demo server `_.
+.. _config-examples:
+
Examples
--------
See following configuration snippets for usual setups of phpMyAdmin.
+Basic example
++++++++++++++
+
+Example configuration file, which can be copied to :file:`config.inc.php` to
+get some core configuration layout, it is distributed with phpMyAdmin as
+:file:`config.sample.inc.php`. Please note that it does not contain all
+configuration options, only the most frequently used ones.
+
+.. literalinclude:: ../config.sample.inc.php
+ :language: php
+
+.. warning::
+
+ Don't use the controluser 'pma' if not existing yet and don't use 'pmapass'
+ as password.
+
+
+.. _example-signon:
+
+Example for signon authentication
++++++++++++++++++++++++++++++++++
+
+This example uses :file:`examples/signon.php` to demostrate usage of :ref:`auth_signon`:
+
+.. code-block:: php
+
+ `
+
+Example for IP address limited autologin
+++++++++++++++++++++++++++++++++++++++++
+
+If you want to automatically login when accessing phpMyAdmin locally while ask
+for password when remotely, you can achieve it using following snippet:
+
+.. code-block:: php
+
+ if ($_SERVER["REMOTE_ADDR"] == "127.0.0.1") {
+ $cfg['Servers'][$i]['auth_type'] = 'config';
+ $cfg['Servers'][$i]['user'] = 'root';
+ $cfg['Servers'][$i]['password'] = 'yourpassword';
+ } else {
+ $cfg['Servers'][$i]['auth_type'] = 'cookie';
+ }
+
+.. note::
+
+ Filtering based on IP addresses isn't reliable over the internet, use it
+ only for local address.
+
.. _example-google-ssl:
Google Cloud SQL with SSL
diff --git a/doc/setup.rst b/doc/setup.rst
index 7a0dc4beff..937e2d0ff0 100644
--- a/doc/setup.rst
+++ b/doc/setup.rst
@@ -310,6 +310,12 @@ Linux/Unix system you can use the following commands:
mkdir config # create directory for saving
chmod o+rw config # give it world writable permissions
+.. note::
+
+ Following documentation covers default behavior of phpMyAdmin. Some
+ distributions have changed this, please check following sections for
+ information on this topic.
+
And to edit an existing configuration, copy it over first:
.. code-block:: sh
@@ -318,11 +324,6 @@ And to edit an existing configuration, copy it over first:
cp config.inc.php config/ # copy current configuration for editing
chmod o+w config/config.inc.php # give it world writable permissions
-.. note::
-
- Debian and Ubuntu have simplified this setup and all you need to do is to
- execute :program:`/usr/sbin/pma-configure`.
-
On other platforms, simply create the folder and ensure that your web
server has read and write access to it. :ref:`faq1_26` can help with
this.
@@ -349,10 +350,6 @@ measure:
chmod o-rw config.inc.php # remove world read and write permissions
rm -rf config # remove not needed directory
-.. note::
-
- Debian and Ubuntu have simplified this setup and all you need to do is to
- execute :program:`/usr/sbin/pma-secure`.
Now the file is ready to be used. You can choose to review or edit the
file with your favorite editor, if you prefer to set some advanced
@@ -370,6 +367,32 @@ options which the setup script does not provide.
a login dialog if using :term:`HTTP` or
cookie authentication mode.
+Setup script on Debian, Ubuntu and derivatives
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Debian and Ubuntu have changed way how setup is enabled and disabled, in a way
+that single command has to be executed for either of these.
+
+To allow editing configuration invoke:
+
+.. code-block:: sh
+
+ /usr/sbin/pma-configure
+
+To block editing configuration invoke:
+
+.. code-block:: sh
+
+ /usr/sbin/pma-secure
+
+Setup script on openSUSE
+~~~~~~~~~~~~~~~~~~~~~~~~
+
+Some openSUSE releases do not include setup script in the package. In case you
+want to generate configuration on these you can either download original
+package from or use setup script on our demo
+server: .
+
.. _verify:
@@ -627,8 +650,18 @@ What the user may now do is controlled entirely by the MySQL user management
system. With HTTP or cookie authentication mode, you don't need to fill the
user/password fields inside the :config:option:`$cfg['Servers']`.
+.. seealso::
+
+ :ref:`faq1_32`,
+ :ref:`faq1_35`,
+ :ref:`faq4_1`,
+ :ref:`faq4_2`,
+ :ref:`faq4_3`
+
.. index:: pair: HTTP; Authentication mode
+.. _auth_http:
+
HTTP authentication mode
------------------------
@@ -649,6 +682,13 @@ HTTP authentication mode
* See also :ref:`faq4_4` about not using the :term:`.htaccess` mechanism along with
':term:`HTTP`' authentication mode.
+.. note::
+
+ There is no way to do proper logout in HTTP authentication, most browsers
+ will remember credentials until there is no different successful
+ authentication. Because of this this method has limitation that you can not
+ login with same user after logout.
+
.. index:: pair: Cookie; Authentication mode
.. _cookie:
@@ -659,12 +699,12 @@ Cookie authentication mode
* Username and password are stored in cookies during the session and password
is deleted when it ends.
* With this mode, the user can truly log out of phpMyAdmin and log
- back in with the same username.
+ back in with the same username (this is not possible with :ref:`auth_http`).
* If you want to allow users to enter any hostname to connect (rather than only
servers that are configured in :file:`config.inc.php`),
see the :config:option:`$cfg['AllowArbitraryServer']` directive.
-* As mentioned in the :ref:`require` section, having the ``mcrypt`` extension will
- speed up access considerably, but is not required.
+* As mentioned in the :ref:`require` section, having the ``mcrypt`` or
+ ``openssl`` extension will speed up access considerably, but is not required.
.. index:: pair: Signon; Authentication mode
@@ -708,7 +748,8 @@ in :file:`examples/signon-script.php`:
:config:option:`$cfg['Servers'][$i]['auth_type']`,
:config:option:`$cfg['Servers'][$i]['SignonSession']`,
:config:option:`$cfg['Servers'][$i]['SignonScript']`,
- :config:option:`$cfg['Servers'][$i]['SignonURL']`
+ :config:option:`$cfg['Servers'][$i]['SignonURL']`,
+ :ref:`example-signon`
.. index:: pair: Config; Authentication mode