6 phpMyAdmin does not apply any special security methods to the MySQL
7 database server. It is still the system administrator's job to grant
8 permissions on the MySQL databases properly. phpMyAdmin's :guilabel:`Users`
9 page can be used for this.
13 :term:`Mac` users should note that if you are on a version before
14 :term:`Mac OS X`, StuffIt unstuffs with :term:`Mac` formats. So you'll have
15 to resave as in BBEdit to Unix style ALL phpMyAdmin scripts before
16 uploading them to your server, as PHP seems not to like :term:`Mac`-style
17 end of lines character ("``\r``").
22 phpMyAdmin is included in most Linux distributions. It is recommended to use
23 distribution packages when possible - they usually provide integration to your
24 distribution and you will automatically get security updates from your distribution.
30 Debian's package repositories include a phpMyAdmin package, but be aware that
31 the configuration file is maintained in ``/etc/phpmyadmin`` and may differ in
32 some ways from the official phpMyAdmin documentation.
37 OpenSUSE already comes with phpMyAdmin package, just install packages from
38 the `openSUSE Build Service <http://software.opensuse.org/package/phpMyAdmin>`_.
43 Ubuntu ships phpMyAdmin package, however if you want to use recent version, you
45 `PPA for Michal Čihař <https://launchpad.net/~nijel/+archive/phpmyadmin>`_.
50 Gentoo ships the phpMyAdmin package, both in a near stock configuration as well
51 as in a ``webapp-config`` configuration. Use ``emerge dev-db/phpmyadmin`` to
57 Mandriva ships the phpMyAdmin package in their ``contrib`` branch and can be
58 installed via the usual Control Center.
63 Fedora ships the phpMyAdmin package, but be aware that the configuration file
64 is maintained in ``/etc/phpMyAdmin/`` and may differ in some ways from the
65 official phpMyAdmin documentation.
67 Red Hat Enterprise Linux
68 ------------------------
70 Red Hat Enterprise Linux itself and thus derivatives like CentOS don't
71 ship phpMyAdmin, but the Fedora-driven repository
72 `Extra Packages for Enterprise Linux (EPEL) <http://fedoraproject.org/wiki/EPEL>`_
74 `enabled <http://fedoraproject.org/wiki/EPEL/FAQ#howtouse>`_.
75 But be aware that the configuration file is maintained in
76 ``/etc/phpMyAdmin/`` and may differ in some ways from the
77 official phpMyAdmin documentation.
83 The easiest way to get phpMyAdmin on Windows is using third party products
84 which include phpMyAdmin together with a database and web server such as
85 `XAMPP <http://www.apachefriends.org/en/xampp.html>`_.
87 You can find more of such options at `Wikipedia <https://en.wikipedia.org/wiki/List_of_AMP_packages>`_.
95 #. Choose an appropriate distribution kit from the phpmyadmin.net
96 Downloads page. Some kits contain only the English messages, others
97 contain all languages. We'll assume you chose a kit whose name
98 looks like ``phpMyAdmin-x.x.x -all-languages.tar.gz``.
99 #. Untar or unzip the distribution (be sure to unzip the subdirectories):
100 ``tar -xzvf phpMyAdmin_x.x.x-all-languages.tar.gz`` in your
101 webserver's document root. If you don't have direct access to your
102 document root, put the files in a directory on your local machine,
103 and, after step 4, transfer the directory on your web server using,
105 #. Ensure that all the scripts have the appropriate owner (if PHP is
106 running in safe mode, having some scripts with an owner different from
107 the owner of other scripts will be a problem). See :ref:`faq4_2` and
108 :ref:`faq1_26` for suggestions.
109 #. Now you must configure your installation. There are two methods that
110 can be used. Traditionally, users have hand-edited a copy of
111 :file:`config.inc.php`, but now a wizard-style setup script is provided
112 for those who prefer a graphical installation. Creating a
113 :file:`config.inc.php` is still a quick way to get started and needed for
114 some advanced features.
117 Manually creating file
118 ----------------------
120 To manually create the file, simply use your text editor to create the
121 file :file:`config.inc.php` (you can copy :file:`config.sample.inc.php` to get
122 minimal configuration file) in the main (top-level) phpMyAdmin
123 directory (the one that contains :file:`index.php`). phpMyAdmin first
124 loads :file:`libraries/config.default.php` and then overrides those values
125 with anything found in :file:`config.inc.php`. If the default value is
126 okay for a particular setting, there is no need to include it in
127 :file:`config.inc.php`. You'll need a few directives to get going, a
128 simple configuration may look like this:
130 .. code-block:: xml+php
134 $cfg['blowfish_secret'] = 'ba17c1ec07d65003'; // use here a value of your choice
138 $cfg['Servers'][$i]['auth_type'] = 'cookie';
141 Or, if you prefer to not be prompted every time you log in:
143 .. code-block:: xml+php
150 $cfg['Servers'][$i]['user'] = 'root';
151 $cfg['Servers'][$i]['password'] = 'cbb74bc'; // use here your password
152 $cfg['Servers'][$i]['auth_type'] = 'config';
155 For a full explanation of possible configuration values, see the
156 :ref:`config` of this document.
158 .. index:: Setup script
165 Instead of manually editing :file:`config.inc.php`, you can use the `Setup
166 Script <setup/>`_. First you must manually create a folder ``config``
167 in the phpMyAdmin directory. This is a security measure. On a
168 Linux/Unix system you can use the following commands:
174 mkdir config # create directory for saving
175 chmod o+rw config # give it world writable permissions
177 And to edit an existing configuration, copy it over first:
182 cp config.inc.php config/ # copy current configuration for editing
183 chmod o+w config/config.inc.php # give it world writable permissions
185 On other platforms, simply create the folder and ensure that your web
186 server has read and write access to it. :ref:`faq1_26` can help with
189 Next, open ``setup/`` in your browser. Note that **changes are
190 not saved to disk until explicitly choose ``Save``** from the
191 *Configuration* area of the screen. Normally the script saves the new
192 :file:`config.inc.php` to the ``config/`` directory, but if the webserver does
193 not have the proper permissions you may see the error "Cannot load or
194 save configuration." Ensure that the ``config/`` directory exists and
195 has the proper permissions - or use the ``Download`` link to save the
196 config file locally and upload (via FTP or some similar means) to the
199 Once the file has been saved, it must be moved out of the ``config/``
200 directory and the permissions must be reset, again as a security
206 mv config/config.inc.php . # move file to current directory
207 chmod o-rw config.inc.php # remove world read and write permissions
208 rm -rf config # remove not needed directory
210 Now the file is ready to be used. You can choose to review or edit the
211 file with your favorite editor, if you prefer to set some advanced
212 options which the setup script does not provide.
214 #. If you are using the ``auth_type`` "config", it is suggested that you
215 protect the phpMyAdmin installation directory because using config
216 does not require a user to enter a password to access the phpMyAdmin
217 installation. Use of an alternate authentication method is
218 recommended, for example with HTTP–AUTH in a :term:`.htaccess` file or switch to using
219 ``auth_type`` cookie or http. See the :ref:`faqmultiuser`
220 for additional information, especially :ref:`faq4_4`.
221 #. Open the `main phpMyAdmin directory <index.php>`_ in your browser.
222 phpMyAdmin should now display a welcome screen and your databases, or
223 a login dialog if using :term:`HTTP` or
224 cookie authentication mode.
225 #. You should deny access to the ``./libraries`` and ``./setup/lib``
226 subfolders in your webserver configuration. For Apache you can use
227 supplied :term:`.htaccess` file in that folder, for other webservers, you should
228 configure this yourself. Such configuration prevents from possible
229 path exposure and cross side scripting vulnerabilities that might
230 happen to be found in that code.
231 #. It is generally good idea to protect public phpMyAdmin installation
232 against access by robots as they usually can not do anything good
233 there. You can do this using ``robots.txt`` file in root of your
234 webserver or limit access by web server configuration, see
238 single: Configuration storage
239 single: phpMyAdmin configuration storage
244 phpMyAdmin configuration storage
245 ++++++++++++++++++++++++++++++++
247 For a whole set of new features (bookmarks, comments, :term:`SQL`-history,
248 tracking mechanism, :term:`PDF`-generation, column contents transformation,
249 etc.) you need to create a set of special tables. Those tables can be located
250 in your own database, or in a central database for a multi-user installation
251 (this database would then be accessed by the controluser, so no other user
252 should have rights to it).
254 Please look at your ``./examples/`` directory, where you should find a
255 file called *create\_tables.sql*. (If you are using a Windows server,
256 pay special attention to :ref:`faq1_23`).
258 If you already had this infrastructure and upgraded to MySQL 4.1.2 or
259 newer, please use :file:`examples/upgrade_tables_mysql_4_1_2+.sql`
260 and then create new tables by importing
261 :file:`examples/create_tables.sql`.
263 You can use your phpMyAdmin to create the tables for you. Please be
264 aware that you may need special (administrator) privileges to create
265 the database and tables, and that the script may need some tuning,
266 depending on the database name.
268 After having imported the :file:`examples/create_tables.sql` file, you
269 should specify the table names in your :file:`config.inc.php` file. The
270 directives used for that can be found in the :ref:`config`. You will also need to
271 have a controluser with the proper rights to those tables (see section
272 :ref:`authentication_modes` below).
276 Upgrading from an older version
277 +++++++++++++++++++++++++++++++
279 Simply copy :file:`config.inc.php` from your previous installation into
280 the newly unpacked one. Configuration files from old versions may
281 require some tweaking as some options have been changed or removed.
282 For compatibility with PHP 6, remove a
283 ``set_magic_quotes_runtime(0);`` statement that you might find near
284 the end of your configuration file.
286 You should **not** copy :file:`libraries/config.default.php` over
287 :file:`config.inc.php` because the default configuration file is version-
290 If you have upgraded your MySQL server from a version previous to 4.1.2 to
291 version 5.x or newer and if you use the phpMyAdmin configuration storage, you
292 should run the :term:`SQL` script found in
293 :file:`examples/upgrade_tables_mysql_4_1_2+.sql`.
295 .. index:: Authentication mode
297 .. _authentication_modes:
299 Using authentication modes
300 ++++++++++++++++++++++++++
302 :term:`HTTP` and cookie authentication modes are recommended in a **multi-user
303 environment** where you want to give users access to their own database and
304 don't want them to play around with others. Nevertheless be aware that MS
305 Internet Explorer seems to be really buggy about cookies, at least till version
306 6. Even in a **single-user environment**, you might prefer to use :term:`HTTP`
307 or cookie mode so that your user/password pair are not in clear in the
310 :term:`HTTP` and cookie authentication
311 modes are more secure: the MySQL login information does not need to be
312 set in the phpMyAdmin configuration file (except possibly for the
313 :config:option:`$cfg['Servers'][$i]['controluser']`).
314 However, keep in mind that the password travels in plain text, unless
315 you are using the HTTPS protocol. In cookie mode, the password is
316 stored, encrypted with the blowfish algorithm, in a temporary cookie.
320 This section is only applicable if your MySQL server is running
321 with ``--skip-show-database``.
323 For ':term:`HTTP`' and 'cookie' modes, phpMyAdmin needs a controluser that has
324 **only** the ``SELECT`` privilege on the *`mysql`.`user` (all columns except
325 `Password`)*, *`mysql`.`db` (all columns)*, *`mysql`.`host` (all columns)* and
326 *`mysql`.`tables\_priv` (all columns except `Grantor` and `Timestamp`)* tables.
327 You must specify the details for the controluser in the :file:`config.inc.php`
328 file under the :config:option:`$cfg['Servers'][$i]['controluser']` and
329 :config:option:`$cfg['Servers'][$i]['controlpass']` settings. The following
330 example assumes you want to use ``pma`` as the controluser and ``pmapass`` as
331 the controlpass, but **this is only an example: use something else in your
332 file!** Input these statements from the phpMyAdmin :term:`SQL` Query window or
333 mysql command–line client. Of course you have to replace ``localhost`` with the
334 webserver's host if it's not the same as the MySQL server's one.
336 .. code-block:: mysql
338 GRANT USAGE ON mysql.* TO 'pma'@'localhost' IDENTIFIED BY 'pmapass';
340 Host, User, Select_priv, Insert_priv, Update_priv, Delete_priv,
341 Create_priv, Drop_priv, Reload_priv, Shutdown_priv, Process_priv,
342 File_priv, Grant_priv, References_priv, Index_priv, Alter_priv,
343 Show_db_priv, Super_priv, Create_tmp_table_priv, Lock_tables_priv,
344 Execute_priv, Repl_slave_priv, Repl_client_priv
345 ) ON mysql.user TO 'pma'@'localhost';
346 GRANT SELECT ON mysql.db TO 'pma'@'localhost';
347 GRANT SELECT ON mysql.host TO 'pma'@'localhost';
348 GRANT SELECT (Host, Db, User, Table_name, Table_priv, Column_priv)
349 ON mysql.tables_priv TO 'pma'@'localhost';
351 If you want to use the many new relation and bookmark features:
353 .. code-block:: mysql
355 GRANT SELECT, INSERT, UPDATE, DELETE ON <pma_db>.* TO 'pma'@'localhost';
357 (this of course requires that your :ref:`linked-tables` be set up).
359 Then each of the *true* users should be granted a set of privileges
360 on a set of particular databases. Normally you shouldn't give global
361 privileges to an ordinary user, unless you understand the impact of those
362 privileges (for example, you are creating a superuser).
363 For example, to grant the user *real_user* with all privileges on
364 the database *user_base*:
366 .. code-block:: mysql
368 GRANT ALL PRIVILEGES ON user_base.* TO 'real_user'@localhost IDENTIFIED BY 'real_password';
371 What the user may now do is controlled entirely by the MySQL user management
372 system. With HTTP or cookie authentication mode, you don't need to fill the
373 user/password fields inside the :config:option:`$cfg['Servers']`.
375 .. index:: pair: HTTP; Authentication mode
377 HTTP authentication mode
378 ------------------------
380 * Uses :term:`HTTP` Basic authentication
381 method and allows you to log in as any valid MySQL user.
382 * Is supported with most PHP configurations. For :term:`IIS` (:term:`ISAPI`)
383 support using :term:`CGI` PHP see :ref:`faq1_32`, for using with Apache
384 :term:`CGI` see :ref:`faq1_35`.
385 * See also :ref:`faq4_4` about not using the :term:`.htaccess` mechanism along with
386 ':term:`HTTP`' authentication mode.
388 .. index:: pair: Cookie; Authentication mode
392 Cookie authentication mode
393 --------------------------
395 * You can use this method as a replacement for the :term:`HTTP` authentication
396 (for example, if you're running :term:`IIS`).
397 * Obviously, the user must enable cookies in the browser, but this is
398 now a requirement for all authentication modes.
399 * With this mode, the user can truly log out of phpMyAdmin and log in
400 back with the same username.
401 * If you want to log in to arbitrary server see :config:option:`$cfg['AllowArbitraryServer']` directive.
402 * As mentioned in the :ref:`require` section, having the ``mcrypt`` extension will
403 speed up access considerably, but is not required.
405 .. index:: pair: Signon; Authentication mode
407 Signon authentication mode
408 --------------------------
410 * This mode is a convenient way of using credentials from another
411 application to authenticate to phpMyAdmin.
412 * The other application has to store login information into session
416 :config:option:`$cfg['Servers'][$i]['auth_type']`,
417 :config:option:`$cfg['Servers'][$i]['SignonSession']`,
418 :config:option:`$cfg['Servers'][$i]['SignonScript']`,
419 :config:option:`$cfg['Servers'][$i]['SignonURL']`
422 .. index:: pair: Config; Authentication mode
424 Config authentication mode
425 --------------------------
427 * This mode is the less secure one because it requires you to fill the
428 :config:option:`$cfg['Servers'][$i]['user']` and
429 :config:option:`$cfg['Servers'][$i]['password']`
430 fields (and as a result, anyone who can read your :file:`config.inc.php`
431 can discover your username and password). But you don't need to setup
432 a "controluser" here: using the :config:option:`$cfg['Servers'][$i]['only_db']` might be enough.
433 * In the :ref:`faqmultiuser` section, there is an entry explaining how
434 to protect your configuration file.
435 * For additional security in this mode, you may wish to consider the
436 Host authentication :config:option:`$cfg['Servers'][$i]['AllowDeny']['order']`
437 and :config:option:`$cfg['Servers'][$i]['AllowDeny']['rules']` configuration directives.
438 * Unlike cookie and http, does not require a user to log in when first
439 loading the phpMyAdmin site. This is by design but could allow any
440 user to access your installation. Use of some restriction method is
441 suggested, perhaps a :term:`.htaccess` file with the HTTP-AUTH directive or disallowing
442 incoming HTTP requests at one’s router or firewall will suffice (both
443 of which are beyond the scope of this manual but easily searchable
446 .. index:: pair: Swekey; Authentication mode
450 Swekey authentication mode
451 --------------------------
453 The Swekey is a low cost authentication USB key that can be used in
454 web applications. When Swekey authentication is activated, phpMyAdmin
455 requires the users's Swekey to be plugged before entering the login
456 page (currently supported for cookie authentication mode only). Swekey
457 Authentication is disabled by default. To enable it, add the following
458 line to :file:`config.inc.php`:
462 $cfg['Servers'][$i]['auth_swekey_config'] = '/etc/swekey.conf';
464 You then have to create the ``swekey.conf`` file that will associate
465 each user with their Swekey Id. It is important to place this file
466 outside of your web server's document root (in the example, it is
467 located in ``/etc``). A self documented sample file is provided in the
468 ``examples`` directory. Feel free to use it with your own users'
469 information. If you want to purchase a Swekey please visit
470 `http://phpmyadmin.net/auth\_key <http://phpmyadmin.net/auth_key>`_
471 since this link provides funding for phpMyAdmin.
473 .. seealso:: :config:option:`$cfg['Servers'][$i]['auth_swekey_config']`
476 Securing your phpMyAdmin installation
477 +++++++++++++++++++++++++++++++++++++
479 The phpMyAdmin team tries hardly to make the application secure, however there
480 are always ways to make your installation more secure:
482 * remove ``setup`` directory from phpMyAdmin, you will probably not
483 use it after initial setup
484 * properly choose authentication method - :ref:`cookie`
485 is probably the best choice for shared hosting
486 * in case you don't want all MySQL users to be able to access
487 phpMyAdmin, you can use :config:option:`$cfg['Servers'][$i]['AllowDeny']['rules']` to limit them
488 * consider hiding phpMyAdmin behind authentication proxy, so that
489 MySQL credentials are not all users need to login
490 * if you are afraid of automated attacks, enabling Captcha by
491 :config:option:`$cfg['CaptchaLoginPublicKey']` and
492 :config:option:`$cfg['CaptchaLoginPrivateKey']` might be an option.