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 the 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 a 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 probably need only 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 phpMyAdmin's
166 setup feature. 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
187 Debian and Ubuntu have simplified this setup and all you need to do is to
188 execute :program:`/usr/sbin/pma-configure`.
190 On other platforms, simply create the folder and ensure that your web
191 server has read and write access to it. :ref:`faq1_26` can help with
194 Next, open your browser and visit the location where you installed phpMyAdmin, with the ``/setup`` suffix. If you have an existing configuration,
195 use the ``Load`` button to bring its content inside the setup panel.
196 Note that **changes are not saved to disk until you explicitly choose ``Save``**
197 from the *Configuration* area of the screen. Normally the script saves the new
198 :file:`config.inc.php` to the ``config/`` directory, but if the webserver does
199 not have the proper permissions you may see the error "Cannot load or
200 save configuration." Ensure that the ``config/`` directory exists and
201 has the proper permissions - or use the ``Download`` link to save the
202 config file locally and upload it (via FTP or some similar means) to the
205 Once the file has been saved, it must be moved out of the ``config/``
206 directory and the permissions must be reset, again as a security
212 mv config/config.inc.php . # move file to current directory
213 chmod o-rw config.inc.php # remove world read and write permissions
214 rm -rf config # remove not needed directory
218 Debian and Ubuntu have simplified this setup and all you need to do is to
219 execute :program:`/usr/sbin/pma-secure`.
221 Now the file is ready to be used. You can choose to review or edit the
222 file with your favorite editor, if you prefer to set some advanced
223 options which the setup script does not provide.
225 #. If you are using the ``auth_type`` "config", it is suggested that you
226 protect the phpMyAdmin installation directory because using config
227 does not require a user to enter a password to access the phpMyAdmin
228 installation. Use of an alternate authentication method is
229 recommended, for example with HTTP–AUTH in a :term:`.htaccess` file or switch to using
230 ``auth_type`` cookie or http. See the :ref:`faqmultiuser`
231 for additional information, especially :ref:`faq4_4`.
232 #. Open the `main phpMyAdmin directory <index.php>`_ in your browser.
233 phpMyAdmin should now display a welcome screen and your databases, or
234 a login dialog if using :term:`HTTP` or
235 cookie authentication mode.
236 #. You should deny access to the ``./libraries`` and ``./setup/lib``
237 subfolders in your webserver configuration.
238 Such configuration prevents from possible
239 path exposure and cross side scripting vulnerabilities that might
240 happen to be found in that code. For the Apache webserver, this is
241 often accomplished with a :term:`.htaccess` file in those directories.
242 #. It is generally a good idea to protect a public phpMyAdmin installation
243 against access by robots as they usually can not do anything good
244 there. You can do this using ``robots.txt`` file in root of your
245 webserver or limit access by web server configuration, see
249 single: Configuration storage
250 single: phpMyAdmin configuration storage
255 phpMyAdmin configuration storage
256 ++++++++++++++++++++++++++++++++
258 For a whole set of additional features (bookmarks, comments, :term:`SQL`-history,
259 tracking mechanism, :term:`PDF`-generation, column contents transformation,
260 etc.) you need to create a set of special tables. Those tables can be located
261 in your own database, or in a central database for a multi-user installation
262 (this database would then be accessed by the controluser, so no other user
263 should have rights to it).
268 In many cases, this database structure can be automatically created and
269 configured. This is called “Zero Configuration” mode and can be particularly
270 useful in shared hosting situations. “Zeroconf” mode is on by default, to
271 disable set :config:option:`$cfg['ZeroConf']` to false.
273 The following three scenarios are covered by the Zero Configuration mode:
275 * When entering a database where the configuration storage tables are not
276 present, phpMyAdmin offers to create them from the Operations tab.
277 * When entering a database where the tables do already exist, the software
278 automatically detects this and begins using them. This is the most common
279 situation; after the tables are initially created automatically they are
280 continually used without disturbing the user; this is also most useful on
281 shared hosting where the user is not able to edit :file:`config.inc.php` and
282 usually the user only has access to one database.
283 * When having access to multiple databases, if the user first enters the
284 database containing the configuration storage tables then switches to
286 phpMyAdmin continues to use the tables from the first database; the user is
287 not prompted to create more tables in the new database.
293 Please look at your ``./sql/`` directory, where you should find a
294 file called *create\_tables.sql*. (If you are using a Windows server,
295 pay special attention to :ref:`faq1_23`).
297 If you already had this infrastructure and:
299 * upgraded to MySQL 4.1.2 or newer, please use
300 :file:`sql/upgrade_tables_mysql_4_1_2+.sql`.
301 * upgraded to phpMyAdmin 4.3.0 or newer from 2.5.0 or newer (<= 4.2.x),
302 please use :file:`sql/upgrade_column_info_4_3_0+.sql`.
304 and then create new tables by importing :file:`sql/create_tables.sql`.
306 You can use your phpMyAdmin to create the tables for you. Please be
307 aware that you may need special (administrator) privileges to create
308 the database and tables, and that the script may need some tuning,
309 depending on the database name.
311 After having imported the :file:`sql/create_tables.sql` file, you
312 should specify the table names in your :file:`config.inc.php` file. The
313 directives used for that can be found in the :ref:`config`.
315 You will also need to have a controluser
316 (:config:option:`$cfg['Servers'][$i]['controluser']` and
317 :config:option:`$cfg['Servers'][$i]['controlpass']` settings)
318 with the proper rights to those tables. For example you can create it
319 using following statement:
321 .. code-block:: mysql
323 GRANT SELECT, INSERT, UPDATE, DELETE ON <pma_db>.* TO 'pma'@'localhost' IDENTIFIED BY 'pmapass';
327 Upgrading from an older version
328 +++++++++++++++++++++++++++++++
330 **Never** extract the new version over an existing installation
331 of phpMyAdmin; we had evidence of problems caused by this.
333 Simply copy :file:`config.inc.php` from your previous installation into
334 the newly unpacked one. Configuration files from old versions may
335 require some tweaking as some options have been changed or removed.
336 For compatibility with PHP 5.3 and later, remove a
337 ``set_magic_quotes_runtime(0);`` statement that you might find near
338 the end of your configuration file.
340 You should **not** copy :file:`libraries/config.default.php` over
341 :file:`config.inc.php` because the default configuration file is version-
344 If you have upgraded your MySQL server from a version previous to 4.1.2 to
345 version 5.x or newer and if you use the phpMyAdmin configuration storage, you
346 should run the :term:`SQL` script found in
347 :file:`sql/upgrade_tables_mysql_4_1_2+.sql`.
349 If you have upgraded your phpMyAdmin to 4.3.0 or newer from 2.5.0 or
350 newer (<= 4.2.x) and if you use the phpMyAdmin configuration storage, you
351 should run the :term:`SQL` script found in
352 :file:`sql/upgrade_column_info_4_3_0+.sql`.
354 .. index:: Authentication mode
356 .. _authentication_modes:
358 Using authentication modes
359 ++++++++++++++++++++++++++
361 :term:`HTTP` and cookie authentication modes are recommended in a **multi-user
362 environment** where you want to give users access to their own database and
363 don't want them to play around with others. Nevertheless be aware that MS
364 Internet Explorer seems to be really buggy about cookies, at least till version
365 6. Even in a **single-user environment**, you might prefer to use :term:`HTTP`
366 or cookie mode so that your user/password pair are not in clear in the
369 :term:`HTTP` and cookie authentication
370 modes are more secure: the MySQL login information does not need to be
371 set in the phpMyAdmin configuration file (except possibly for the
372 :config:option:`$cfg['Servers'][$i]['controluser']`).
373 However, keep in mind that the password travels in plain text, unless
374 you are using the HTTPS protocol. In cookie mode, the password is
375 stored, encrypted with the AES algorithm, in a temporary cookie.
377 Then each of the *true* users should be granted a set of privileges
378 on a set of particular databases. Normally you shouldn't give global
379 privileges to an ordinary user, unless you understand the impact of those
380 privileges (for example, you are creating a superuser).
381 For example, to grant the user *real_user* with all privileges on
382 the database *user_base*:
384 .. code-block:: mysql
386 GRANT ALL PRIVILEGES ON user_base.* TO 'real_user'@localhost IDENTIFIED BY 'real_password';
389 What the user may now do is controlled entirely by the MySQL user management
390 system. With HTTP or cookie authentication mode, you don't need to fill the
391 user/password fields inside the :config:option:`$cfg['Servers']`.
393 .. index:: pair: HTTP; Authentication mode
395 HTTP authentication mode
396 ------------------------
398 * Uses :term:`HTTP` Basic authentication
399 method and allows you to log in as any valid MySQL user.
400 * Is supported with most PHP configurations. For :term:`IIS` (:term:`ISAPI`)
401 support using :term:`CGI` PHP see :ref:`faq1_32`, for using with Apache
402 :term:`CGI` see :ref:`faq1_35`.
403 * See also :ref:`faq4_4` about not using the :term:`.htaccess` mechanism along with
404 ':term:`HTTP`' authentication mode.
406 .. index:: pair: Cookie; Authentication mode
410 Cookie authentication mode
411 --------------------------
413 * Username and password are stored in cookies during the session and password
414 is deleted when it ends.
415 * With this mode, the user can truly log out of phpMyAdmin and log
416 back in with the same username.
417 * If you want to allow users to enter any hostname to connect (rather than only
418 servers that are configured in :file:`config.inc.php`),
419 see the :config:option:`$cfg['AllowArbitraryServer']` directive.
420 * As mentioned in the :ref:`require` section, having the ``mcrypt`` extension will
421 speed up access considerably, but is not required.
423 .. index:: pair: Signon; Authentication mode
427 Signon authentication mode
428 --------------------------
430 * This mode is a convenient way of using credentials from another
431 application to authenticate to phpMyAdmin to implement single signon
433 * The other application has to store login information into session
434 data (see :config:option:`$cfg['Servers'][$i]['SignonSession']`) or you
435 need to implement script to return the credentials (see
436 :config:option:`$cfg['Servers'][$i]['SignonScript']`).
437 * When no credentials are available, the user is being redirected to
438 :config:option:`$cfg['Servers'][$i]['SignonURL']`, where you should handle
441 The very basic example of saving credentials in a session is available as
442 :file:`examples/signon.php`:
444 .. literalinclude:: ../examples/signon.php
447 Alternatively you can also use this way to integrate with OpenID as shown
448 in :file:`examples/openid.php`:
450 .. literalinclude:: ../examples/openid.php
453 If you intend to pass the credentials using some other means than, you have to
454 implement wrapper in PHP to get that data and set it to
455 :config:option:`$cfg['Servers'][$i]['SignonScript']`. There is very minimal example
456 in :file:`examples/signon-script.php`:
458 .. literalinclude:: ../examples/signon-script.php
462 :config:option:`$cfg['Servers'][$i]['auth_type']`,
463 :config:option:`$cfg['Servers'][$i]['SignonSession']`,
464 :config:option:`$cfg['Servers'][$i]['SignonScript']`,
465 :config:option:`$cfg['Servers'][$i]['SignonURL']`
468 .. index:: pair: Config; Authentication mode
470 Config authentication mode
471 --------------------------
473 * This mode is sometimes the less secure one because it requires you to fill the
474 :config:option:`$cfg['Servers'][$i]['user']` and
475 :config:option:`$cfg['Servers'][$i]['password']`
476 fields (and as a result, anyone who can read your :file:`config.inc.php`
477 can discover your username and password).
478 * In the :ref:`faqmultiuser` section, there is an entry explaining how
479 to protect your configuration file.
480 * For additional security in this mode, you may wish to consider the
481 Host authentication :config:option:`$cfg['Servers'][$i]['AllowDeny']['order']`
482 and :config:option:`$cfg['Servers'][$i]['AllowDeny']['rules']` configuration directives.
483 * Unlike cookie and http, does not require a user to log in when first
484 loading the phpMyAdmin site. This is by design but could allow any
485 user to access your installation. Use of some restriction method is
486 suggested, perhaps a :term:`.htaccess` file with the HTTP-AUTH directive or disallowing
487 incoming HTTP requests at one’s router or firewall will suffice (both
488 of which are beyond the scope of this manual but easily searchable
491 .. index:: pair: Swekey; Authentication mode
495 Swekey authentication mode
496 --------------------------
498 The Swekey is a low cost authentication USB key that can be used in
499 web applications. When Swekey authentication is activated, phpMyAdmin
500 requires the users's Swekey to be plugged before entering the login
501 page (currently supported for cookie authentication mode only). Swekey
502 Authentication is disabled by default. To enable it, add the following
503 line to :file:`config.inc.php`:
507 $cfg['Servers'][$i]['auth_swekey_config'] = '/etc/swekey.conf';
509 You then have to create the ``swekey.conf`` file that will associate
510 each user with their Swekey Id. It is important to place this file
511 outside of your web server's document root (in the example, it is
512 located in ``/etc``). Feel free to use it with your own users'
513 information. If you want to purchase a Swekey please visit
514 `http://phpmyadmin.net/auth\_key <http://phpmyadmin.net/auth_key>`_
515 since this link provides funding for phpMyAdmin.
517 A self documented sample file is provided in the
518 file :file:`examples/swekey.sample.conf`:
520 .. literalinclude:: ../examples/swekey.sample.conf
523 .. seealso:: :config:option:`$cfg['Servers'][$i]['auth_swekey_config']`
526 Securing your phpMyAdmin installation
527 +++++++++++++++++++++++++++++++++++++
529 The phpMyAdmin team tries hard to make the application secure, however there
530 are always ways to make your installation more secure:
532 * Remove the ``setup`` directory from phpMyAdmin, you will probably not
533 use it after the initial setup.
534 * Properly choose an authentication method - :ref:`cookie`
535 is probably the best choice for shared hosting.
536 * In case you don't want all MySQL users to be able to access
537 phpMyAdmin, you can use :config:option:`$cfg['Servers'][$i]['AllowDeny']['rules']` to limit them.
538 * Consider hiding phpMyAdmin behind an authentication proxy, so that
539 users need to authenticate prior to providing MySQL credentials
541 * If you are afraid of automated attacks, enabling Captcha by
542 :config:option:`$cfg['CaptchaLoginPublicKey']` and
543 :config:option:`$cfg['CaptchaLoginPrivateKey']` might be an option.