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.
14 phpMyAdmin is included in most Linux distributions. It is recommended to use
15 distribution packages when possible - they usually provide integration to your
16 distribution and you will automatically get security updates from your distribution.
23 Most Debian and Ubuntu versions include a phpMyAdmin package, but be aware that
24 the configuration file is maintained in ``/etc/phpmyadmin`` and may differ in
25 some ways from the official phpMyAdmin documentation. Specifically, it does:
27 * Configuration of a web server (works for Apache and lighttpd).
28 * Creating of :ref:`linked-tables` using dbconfig-common.
29 * Securing setup script, see :ref:`debian-setup`.
31 More specific details about installing Debian or Ubuntu packages are available
32 `in our wiki <https://github.com/phpmyadmin/phpmyadmin/wiki/DebianUbuntu>`_.
36 More information can be found in `README.Debian <https://salsa.debian.org/phpmyadmin-team/phpmyadmin/blob/debian/latest/debian/README.Debian>`_
37 (it is installed as :file:`/usr/share/doc/phpmyadmin/README.Debian` with the package).
42 OpenSUSE already comes with phpMyAdmin package, just install packages from
43 the `openSUSE Build Service <https://software.opensuse.org/package/phpMyAdmin>`_.
48 Gentoo ships the phpMyAdmin package, both in a near-stock configuration as well
49 as in a ``webapp-config`` configuration. Use ``emerge dev-db/phpmyadmin`` to
55 Mandriva ships the phpMyAdmin package in their ``contrib`` branch and can be
56 installed via the usual Control Center.
61 Fedora ships the phpMyAdmin package, but be aware that the configuration file
62 is maintained in ``/etc/phpMyAdmin/`` and may differ in some ways from the
63 official phpMyAdmin documentation.
65 Red Hat Enterprise Linux
66 ------------------------
68 Red Hat Enterprise Linux itself and thus derivatives like CentOS don't
69 ship phpMyAdmin, but the Fedora-driven repository
70 `Extra Packages for Enterprise Linux (EPEL) <https://fedoraproject.org/wiki/EPEL>`_
72 `enabled <https://fedoraproject.org/wiki/EPEL/FAQ#howtouse>`_.
73 But be aware that the configuration file is maintained in
74 ``/etc/phpMyAdmin/`` and may differ in some ways from the
75 official phpMyAdmin documentation.
80 The easiest way to get phpMyAdmin on Windows is using third party products
81 which include phpMyAdmin together with a database and web server such as
82 `XAMPP <https://www.apachefriends.org/index.html>`_.
84 You can find more of such options at `Wikipedia <https://en.wikipedia.org/wiki/List_of_AMP_packages>`_.
89 In order to install from Git, you'll need a few supporting applications:
91 * `Git <https://git-scm.com/downloads>`_ to download the source, or you can download the most recent source directly from `Github <https://codeload.github.com/phpmyadmin/phpmyadmin/zip/master>`_
92 * `Composer <https://getcomposer.org/download/>`__
93 * `Node.js <https://nodejs.org/en/download/>`_ (version 10 or higher)
94 * `Yarn <https://classic.yarnpkg.com/en/docs/install>`_
96 You can clone current phpMyAdmin source from
97 ``https://github.com/phpmyadmin/phpmyadmin.git``:
101 git clone https://github.com/phpmyadmin/phpmyadmin.git
103 Additionally you need to install dependencies using `Composer <https://getcomposer.org>`__:
109 If you do not intend to develop, you can skip the installation of developer tools
114 composer update --no-dev
116 Finally, you'll need to use `Yarn`_ to install some JavaScript dependencies:
120 yarn install --production
124 Installing using Composer
125 +++++++++++++++++++++++++
127 You can install phpMyAdmin using the `Composer tool`_, since 4.7.0 the releases
128 are automatically mirrored to the default `Packagist`_ repository.
132 The content of the Composer repository is automatically generated
133 separately from the releases, so the content doesn't have to be
134 100% same as when you download the tarball. There should be no
135 functional differences though.
137 To install phpMyAdmin simply run:
141 composer create-project phpmyadmin/phpmyadmin
143 Alternatively you can use our own composer repository, which contains
144 the release tarballs and is available at
145 <https://www.phpmyadmin.net/packages.json>:
149 composer create-project phpmyadmin/phpmyadmin --repository-url=https://www.phpmyadmin.net/packages.json --no-dev
153 Installing using Docker
154 +++++++++++++++++++++++
156 phpMyAdmin comes with a `Docker official image`_, which you can easily deploy. You can
161 docker pull phpmyadmin
163 The phpMyAdmin server will listen on port 80. It supports several ways of
164 configuring the link to the database server, either by Docker's link feature
165 by linking your database container to ``db`` for phpMyAdmin (by specifying
166 ``--link your_db_host:db``) or by environment variables (in this case it's up
167 to you to set up networking in Docker to allow the phpMyAdmin container to access
168 the database container over the network).
172 Docker environment variables
173 ----------------------------
175 You can configure several phpMyAdmin features using environment variables:
177 .. envvar:: PMA_ARBITRARY
179 Allows you to enter a database server hostname on login form.
181 .. seealso:: :config:option:`$cfg['AllowArbitraryServer']`
185 Hostname or IP address of the database server to use.
187 .. seealso:: :config:option:`$cfg['Servers'][$i]['host']`
189 .. envvar:: PMA_HOSTS
191 Comma-separated hostnames or IP addresses of the database servers to use.
193 .. note:: Used only if :envvar:`PMA_HOST` is empty.
195 .. envvar:: PMA_VERBOSE
197 Verbose name of the database server.
199 .. seealso:: :config:option:`$cfg['Servers'][$i]['verbose']`
201 .. envvar:: PMA_VERBOSES
203 Comma-separated verbose name of the database servers.
205 .. note:: Used only if :envvar:`PMA_VERBOSE` is empty.
209 User name to use for :ref:`auth_config`.
211 .. envvar:: PMA_PASSWORD
213 Password to use for :ref:`auth_config`.
217 Port of the database server to use.
219 .. envvar:: PMA_PORTS
221 Comma-separated ports of the database server to use.
223 .. note:: Used only if :envvar:`PMA_PORT` is empty.
225 .. envvar:: PMA_ABSOLUTE_URI
227 The fully-qualified path (``https://pma.example.net/``) where the reverse
228 proxy makes phpMyAdmin available.
230 .. seealso:: :config:option:`$cfg['PmaAbsoluteUri']`
232 .. envvar:: HIDE_PHP_VERSION
234 If defined, this option will hide the PHP version (`expose_php = Off`).
235 Set to any value (such as `HIDE_PHP_VERSION=true`).
237 .. envvar:: UPLOAD_LIMIT
239 If set, this option will override the default value for apache and php-fpm (this will change ``upload_max_filesize`` and ``post_max_size`` values).
241 .. note:: Format as `[0-9+](K,M,G)` default value is `2048K`
243 .. envvar:: PMA_CONFIG_BASE64
245 If set, this option will override the default `config.inc.php` with the base64 decoded contents of the variable.
247 .. envvar:: PMA_USER_CONFIG_BASE64
249 If set, this option will override the default `config.user.inc.php` with the base64 decoded contents of the variable.
252 By default, :ref:`cookie` is used, but if :envvar:`PMA_USER` and
253 :envvar:`PMA_PASSWORD` are set, it is switched to :ref:`auth_config`.
257 The credentials you need to log in are stored in the MySQL server, in case
258 of Docker image, there are various ways to set it (for example
259 :samp:`MYSQL_ROOT_PASSWORD` when starting the MySQL container). Please check
260 documentation for `MariaDB container <https://hub.docker.com/_/mariadb>`_
261 or `MySQL container <https://hub.docker.com/_/mysql>`_.
265 Customizing configuration
266 -------------------------
268 Additionally configuration can be tweaked by :file:`/etc/phpmyadmin/config.user.inc.php`. If
269 this file exists, it will be loaded after configuration is generated from above
270 environment variables, so you can override any configuration variable. This
271 configuration can be added as a volume when invoking docker using
272 `-v /some/local/directory/config.user.inc.php:/etc/phpmyadmin/config.user.inc.php` parameters.
274 Note that the supplied configuration file is applied after :ref:`docker-vars`,
275 but you can override any of the values.
277 For example to change the default behavior of CSV export you can use the following
283 $cfg['Export']['csv_columns'] = true;
285 You can also use it to define server configuration instead of using the
286 environment variables listed in :ref:`docker-vars`:
291 /* Override Servers array */
294 'auth_type' => 'cookie',
297 'verbose' => 'Verbose name 1',
300 'auth_type' => 'cookie',
303 'verbose' => 'Verbose name 2',
309 See :ref:`config` for detailed description of configuration options.
314 You can use the following volumes to customize image behavior:
316 :file:`/etc/phpmyadmin/config.user.inc.php`
318 Can be used for additional settings, see the previous chapter for more details.
322 Directory where PHP sessions are stored. You might want to share this
323 for example when using :ref:`auth_signon`.
327 Directory where phpMyAdmin looks for themes. By default only those shipped
328 with phpMyAdmin are included, but you can include additional phpMyAdmin
329 themes (see :ref:`themes`) by using Docker volumes.
334 To connect phpMyAdmin to a given server use:
338 docker run --name myadmin -d -e PMA_HOST=dbhost -p 8080:80 phpmyadmin/phpmyadmin
340 To connect phpMyAdmin to more servers use:
344 docker run --name myadmin -d -e PMA_HOSTS=dbhost1,dbhost2,dbhost3 -p 8080:80 phpmyadmin/phpmyadmin
346 To use arbitrary server option:
350 docker run --name myadmin -d --link mysql_db_server:db -p 8080:80 -e PMA_ARBITRARY=1 phpmyadmin/phpmyadmin
352 You can also link the database container using Docker:
356 docker run --name phpmyadmin -d --link mysql_db_server:db -p 8080:80 phpmyadmin/phpmyadmin
358 Running with additional configuration:
362 docker run --name phpmyadmin -d --link mysql_db_server:db -p 8080:80 -v /some/local/directory/config.user.inc.php:/etc/phpmyadmin/config.user.inc.php phpmyadmin/phpmyadmin
364 Running with additional themes:
368 docker run --name phpmyadmin -d --link mysql_db_server:db -p 8080:80 -v /custom/phpmyadmin/theme/:/www/themes/theme/ phpmyadmin/phpmyadmin
373 Alternatively, you can also use docker-compose with the docker-compose.yml from
374 <https://github.com/phpmyadmin/docker>. This will run phpMyAdmin with an
375 arbitrary server - allowing you to specify MySQL/MariaDB server on the login page.
381 Customizing configuration file using docker-compose
382 ---------------------------------------------------
384 You can use an external file to customize phpMyAdmin configuration and pass it
385 using the volumes directive:
390 image: phpmyadmin/phpmyadmin
391 container_name: phpmyadmin
399 - ~/docker/phpmyadmin/config.user.inc.php:/etc/phpmyadmin/config.user.inc.php
400 - /custom/phpmyadmin/theme/:/www/themes/theme/
402 .. seealso:: :ref:`docker-custom`
404 Running behind haproxy in a subdirectory
405 ----------------------------------------
407 When you want to expose phpMyAdmin running in a Docker container in a
408 subdirectory, you need to rewrite the request path in the server proxying the
411 For example, using haproxy it can be done as:
418 option http-server-close
420 ### NETWORK restriction
421 acl LOCALNET src 10.0.0.0/8 192.168.0.0/16 172.16.0.0/12
424 acl phpmyadmin path_dir /phpmyadmin
425 use_backend phpmyadmin if phpmyadmin LOCALNET
430 reqirep ^(GET|POST|HEAD)\ /phpmyadmin/(.*) \1\ /\2
432 # phpMyAdmin container IP
433 server localhost 172.30.21.21:80
435 When using traefik, something like following should work:
439 defaultEntryPoints = ["http"]
443 [entryPoints.http.redirect]
444 regex = "(http:\\/\\/[^\\/]+\\/([^\\?\\.]+)[^\\/])$"
449 [backends.myadmin.servers.myadmin]
450 url="http://internal.address.to.pma"
455 passHostHeader = true
456 [frontends.myadmin.routes.default]
457 rule="PathPrefixStrip:/phpmyadmin/;AddPrefix:/"
459 You then should specify :envvar:`PMA_ABSOLUTE_URI` in the docker-compose
469 image: phpmyadmin/phpmyadmin
470 container_name: phpmyadmin
472 domainname: example.com
476 - PMA_HOSTS=172.26.36.7,172.26.36.8,172.26.36.9,172.26.36.10
477 - PMA_VERBOSES=production-db1,production-db2,dev-db1,dev-db2
480 - PMA_ABSOLUTE_URI=http://example.com/phpmyadmin/
485 One of our users has created a helpful guide for installing phpMyAdmin on the
486 `IBM Cloud platform <https://github.com/KissConsult/phpmyadmin_tutorial#readme>`_.
493 #. Choose an appropriate distribution kit from the phpmyadmin.net
494 Downloads page. Some kits contain only the English messages, others
495 contain all languages. We'll assume you chose a kit whose name
496 looks like ``phpMyAdmin-x.x.x -all-languages.tar.gz``.
497 #. Ensure you have downloaded a genuine archive, see :ref:`verify`.
498 #. Untar or unzip the distribution (be sure to unzip the subdirectories):
499 ``tar -xzvf phpMyAdmin_x.x.x-all-languages.tar.gz`` in your
500 webserver's document root. If you don't have direct access to your
501 document root, put the files in a directory on your local machine,
502 and, after step 4, transfer the directory on your web server using,
504 #. Ensure that all the scripts have the appropriate owner (if PHP is
505 running in safe mode, having some scripts with an owner different from
506 the owner of other scripts will be a problem). See :ref:`faq4_2` and
507 :ref:`faq1_26` for suggestions.
508 #. Now you must configure your installation. There are two methods that
509 can be used. Traditionally, users have hand-edited a copy of
510 :file:`config.inc.php`, but now a wizard-style setup script is provided
511 for those who prefer a graphical installation. Creating a
512 :file:`config.inc.php` is still a quick way to get started and needed for
513 some advanced features.
515 Manually creating the file
516 --------------------------
518 To manually create the file, simply use your text editor to create the
519 file :file:`config.inc.php` (you can copy :file:`config.sample.inc.php` to get
520 a minimal configuration file) in the main (top-level) phpMyAdmin
521 directory (the one that contains :file:`index.php`). phpMyAdmin first
522 loads the default configuration values and then overrides those values
523 with anything found in :file:`config.inc.php`. If the default value is
524 okay for a particular setting, there is no need to include it in
525 :file:`config.inc.php`. You'll probably need only a few directives to get going; a
526 simple configuration may look like this:
528 .. code-block:: xml+php
531 // use here a value of your choice at least 32 chars long
532 $cfg['blowfish_secret'] = '1{dd0`<Q),5XP_:R9UK%%8\"EEcyH#{o';
536 $cfg['Servers'][$i]['auth_type'] = 'cookie';
537 // if you insist on "root" having no password:
538 // $cfg['Servers'][$i]['AllowNoPassword'] = true;
540 Or, if you prefer to not be prompted every time you log in:
542 .. code-block:: xml+php
548 $cfg['Servers'][$i]['user'] = 'root';
549 $cfg['Servers'][$i]['password'] = 'changeme'; // use here your password
550 $cfg['Servers'][$i]['auth_type'] = 'config';
554 Storing passwords in the configuration is insecure as anybody can then
555 manipulate your database.
557 For a full explanation of possible configuration values, see the
558 :ref:`config` of this document.
560 .. index:: Setup script
564 Using the Setup script
565 ----------------------
567 Instead of manually editing :file:`config.inc.php`, you can use phpMyAdmin's
568 setup feature. The file can be generated using the setup and you can download it
569 for upload to the server.
571 Next, open your browser and visit the location where you installed phpMyAdmin,
572 with the ``/setup`` suffix. The changes are not saved to the server, you need to
573 use the :guilabel:`Download` button to save them to your computer and then upload
576 Now the file is ready to be used. You can choose to review or edit the
577 file with your favorite editor, if you prefer to set some advanced
578 options that the setup script does not provide.
580 #. If you are using the ``auth_type`` "config", it is suggested that you
581 protect the phpMyAdmin installation directory because using config
582 does not require a user to enter a password to access the phpMyAdmin
583 installation. Use of an alternate authentication method is
584 recommended, for example with HTTP–AUTH in a :term:`.htaccess` file or switch to using
585 ``auth_type`` cookie or http. See the :ref:`faqmultiuser`
586 for additional information, especially :ref:`faq4_4`.
587 #. Open the main phpMyAdmin directory in your browser.
588 phpMyAdmin should now display a welcome screen and your databases, or
589 a login dialog if using :term:`HTTP` or
590 cookie authentication mode.
594 Setup script on Debian, Ubuntu and derivatives
595 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
597 Debian and Ubuntu have changed the way in which the setup script is enabled and disabled, in a way
598 that single command has to be executed for either of these.
600 To allow editing configuration invoke:
604 /usr/sbin/pma-configure
606 To block editing configuration invoke:
612 Setup script on openSUSE
613 ~~~~~~~~~~~~~~~~~~~~~~~~
615 Some openSUSE releases do not include setup script in the package. In case you
616 want to generate configuration on these you can either download original
617 package from <https://www.phpmyadmin.net/> or use setup script on our demo
618 server: <https://demo.phpmyadmin.net/master/setup/>.
622 Verifying phpMyAdmin releases
623 +++++++++++++++++++++++++++++
625 Since July 2015 all phpMyAdmin releases are cryptographically signed by the
626 releasing developer, who through January 2016 was Marc Delisle. His key id is
627 0xFEFC65D181AF644A, his PGP fingerprint is:
629 .. code-block:: console
631 436F F188 4B1A 0C3F DCBF 0D79 FEFC 65D1 81AF 644A
633 and you can get more identification information from <https://keybase.io/lem9>.
635 Beginning in January 2016, the release manager is Isaac Bennetch. His key id is
636 0xCE752F178259BD92, and his PGP fingerprint is:
638 .. code-block:: console
640 3D06 A59E CE73 0EB7 1B51 1C17 CE75 2F17 8259 BD92
642 and you can get more identification information from <https://keybase.io/ibennetch>.
644 Some additional downloads (for example themes) might be signed by Michal Čihař. His key id is
645 0x9C27B31342B7511D, and his PGP fingerprint is:
647 .. code-block:: console
649 63CB 1DF1 EF12 CF2A C0EE 5A32 9C27 B313 42B7 511D
651 and you can get more identification information from <https://keybase.io/nijel>.
653 You should verify that the signature matches the archive you have downloaded.
654 This way you can be sure that you are using the same code that was released.
655 You should also verify the date of the signature to make sure that you
656 downloaded the latest version.
658 Each archive is accompanied by ``.asc`` files which contain the PGP signature
659 for it. Once you have both of them in the same folder, you can verify the signature:
661 .. code-block:: console
663 $ gpg --verify phpMyAdmin-4.5.4.1-all-languages.zip.asc
664 gpg: Signature made Fri 29 Jan 2016 08:59:37 AM EST using RSA key ID 8259BD92
665 gpg: Can't check signature: public key not found
667 As you can see gpg complains that it does not know the public key. At this
668 point, you should do one of the following steps:
670 * Download the keyring from `our download server <https://files.phpmyadmin.net/phpmyadmin.keyring>`_, then import it with:
672 .. code-block:: console
674 $ gpg --import phpmyadmin.keyring
676 * Download and import the key from one of the key servers:
678 .. code-block:: console
680 $ gpg --keyserver hkp://pgp.mit.edu --recv-keys 3D06A59ECE730EB71B511C17CE752F178259BD92
681 gpg: requesting key 8259BD92 from hkp server pgp.mit.edu
682 gpg: key 8259BD92: public key "Isaac Bennetch <bennetch@gmail.com>" imported
683 gpg: no ultimately trusted keys found
684 gpg: Total number processed: 1
685 gpg: imported: 1 (RSA: 1)
687 This will improve the situation a bit - at this point, you can verify that the
688 signature from the given key is correct but you still can not trust the name used
691 .. code-block:: console
693 $ gpg --verify phpMyAdmin-4.5.4.1-all-languages.zip.asc
694 gpg: Signature made Fri 29 Jan 2016 08:59:37 AM EST using RSA key ID 8259BD92
695 gpg: Good signature from "Isaac Bennetch <bennetch@gmail.com>"
696 gpg: aka "Isaac Bennetch <isaac@bennetch.org>"
697 gpg: WARNING: This key is not certified with a trusted signature!
698 gpg: There is no indication that the signature belongs to the owner.
699 Primary key fingerprint: 3D06 A59E CE73 0EB7 1B51 1C17 CE75 2F17 8259 BD92
701 The problem here is that anybody could issue the key with this name. You need to
702 ensure that the key is actually owned by the mentioned person. The GNU Privacy
703 Handbook covers this topic in the chapter `Validating other keys on your public
704 keyring`_. The most reliable method is to meet the developer in person and
705 exchange key fingerprints, however, you can also rely on the web of trust. This way
706 you can trust the key transitively though signatures of others, who have met
707 the developer in person.
709 Once the key is trusted, the warning will not occur:
711 .. code-block:: console
713 $ gpg --verify phpMyAdmin-4.5.4.1-all-languages.zip.asc
714 gpg: Signature made Fri 29 Jan 2016 08:59:37 AM EST using RSA key ID 8259BD92
715 gpg: Good signature from "Isaac Bennetch <bennetch@gmail.com>" [full]
717 Should the signature be invalid (the archive has been changed), you would get a
718 clear error regardless of the fact that the key is trusted or not:
720 .. code-block:: console
722 $ gpg --verify phpMyAdmin-4.5.4.1-all-languages.zip.asc
723 gpg: Signature made Fri 29 Jan 2016 08:59:37 AM EST using RSA key ID 8259BD92
724 gpg: BAD signature from "Isaac Bennetch <bennetch@gmail.com>" [unknown]
726 .. _Validating other keys on your public keyring: https://www.gnupg.org/gph/en/manual.html#AEN335
729 single: Configuration storage
730 single: phpMyAdmin configuration storage
735 phpMyAdmin configuration storage
736 ++++++++++++++++++++++++++++++++
738 .. versionchanged:: 3.4.0
740 Prior to phpMyAdmin 3.4.0 this was called Linked Tables Infrastructure, but
741 the name was changed due to the extended scope of the storage.
743 For a whole set of additional features (:ref:`bookmarks`, comments, :term:`SQL`-history,
744 tracking mechanism, :term:`PDF`-generation, :ref:`transformations`, :ref:`relations`
745 etc.) you need to create a set of special tables. Those tables can be located
746 in your own database, or in a central database for a multi-user installation
747 (this database would then be accessed by the controluser, so no other user
748 should have rights to it).
755 In many cases, this database structure can be automatically created and
756 configured. This is called “Zero Configuration” mode and can be particularly
757 useful in shared hosting situations. “Zeroconf” mode is on by default, to
758 disable set :config:option:`$cfg['ZeroConf']` to false.
760 The following three scenarios are covered by the Zero Configuration mode:
762 * When entering a database where the configuration storage tables are not
763 present, phpMyAdmin offers to create them from the Operations tab.
764 * When entering a database where the tables do already exist, the software
765 automatically detects this and begins using them. This is the most common
766 situation; after the tables are initially created automatically they are
767 continually used without disturbing the user; this is also most useful on
768 shared hosting where the user is not able to edit :file:`config.inc.php` and
769 usually the user only has access to one database.
770 * When having access to multiple databases, if the user first enters the
771 database containing the configuration storage tables then switches to
773 phpMyAdmin continues to use the tables from the first database; the user is
774 not prompted to create more tables in the new database.
779 Please look at your ``./sql/`` directory, where you should find a
780 file called *create\_tables.sql*. (If you are using a Windows server,
781 pay special attention to :ref:`faq1_23`).
783 If you already had this infrastructure and:
785 * upgraded to MySQL 4.1.2 or newer, please use
786 :file:`sql/upgrade_tables_mysql_4_1_2+.sql`.
787 * upgraded to phpMyAdmin 4.3.0 or newer from 2.5.0 or newer (<= 4.2.x),
788 please use :file:`sql/upgrade_column_info_4_3_0+.sql`.
789 * upgraded to phpMyAdmin 4.7.0 or newer from 4.3.0 or newer,
790 please use :file:`sql/upgrade_tables_4_7_0+.sql`.
792 and then create new tables by importing :file:`sql/create_tables.sql`.
794 You can use your phpMyAdmin to create the tables for you. Please be
795 aware that you may need special (administrator) privileges to create
796 the database and tables, and that the script may need some tuning,
797 depending on the database name.
799 After having imported the :file:`sql/create_tables.sql` file, you
800 should specify the table names in your :file:`config.inc.php` file. The
801 directives used for that can be found in the :ref:`config`.
803 You will also need to have a controluser
804 (:config:option:`$cfg['Servers'][$i]['controluser']` and
805 :config:option:`$cfg['Servers'][$i]['controlpass']` settings)
806 with the proper rights to those tables. For example you can create it
807 using following statement:
809 And for any MariaDB version:
811 .. code-block:: mysql
813 CREATE USER 'pma'@'localhost' IDENTIFIED VIA mysql_native_password USING 'pmapass';
814 GRANT SELECT, INSERT, UPDATE, DELETE ON `<pma_db>`.* TO 'pma'@'localhost';
816 For MySQL 8.0 and newer:
818 .. code-block:: mysql
820 CREATE USER 'pma'@'localhost' IDENTIFIED WITH caching_sha2_password BY 'pmapass';
821 GRANT SELECT, INSERT, UPDATE, DELETE ON <pma_db>.* TO 'pma'@'localhost';
823 For MySQL older than 8.0:
825 .. code-block:: mysql
827 CREATE USER 'pma'@'localhost' IDENTIFIED WITH mysql_native_password AS 'pmapass';
828 GRANT SELECT, INSERT, UPDATE, DELETE ON <pma_db>.* TO 'pma'@'localhost';
830 Note that MySQL installations with PHP older than 7.4 and MySQL newer than 8.0 may require
831 using the mysql_native_password authentication as a workaround, see
832 :ref:`faq1_45` for details.
836 Upgrading from an older version
837 +++++++++++++++++++++++++++++++
841 **Never** extract the new version over an existing installation of
842 phpMyAdmin, always first remove the old files keeping just the
845 This way, you will not leave any old or outdated files in the directory,
846 which can have severe security implications or can cause various breakages.
848 Simply copy :file:`config.inc.php` from your previous installation into
849 the newly unpacked one. Configuration files from old versions may
850 require some tweaking as some options have been changed or removed.
851 For compatibility with PHP 5.3 and later, remove a
852 ``set_magic_quotes_runtime(0);`` statement that you might find near
853 the end of your configuration file.
855 The complete upgrade can be performed in a few simple steps:
857 1. Download the latest phpMyAdmin version from <https://www.phpmyadmin.net/downloads/>.
858 2. Rename existing phpMyAdmin folder (for example to ``phpmyadmin-old``).
859 3. Unpack freshly downloaded phpMyAdmin to the desired location (for example ``phpmyadmin``).
860 4. Copy :file:`config.inc.php`` from old location (``phpmyadmin-old``) to the new one (``phpmyadmin``).
861 5. Test that everything works properly.
862 6. Remove backup of a previous version (``phpmyadmin-old``).
864 If you have upgraded your MySQL server from a version previous to 4.1.2 to
865 version 5.x or newer and if you use the phpMyAdmin configuration storage, you
866 should run the :term:`SQL` script found in
867 :file:`sql/upgrade_tables_mysql_4_1_2+.sql`.
869 If you have upgraded your phpMyAdmin to 4.3.0 or newer from 2.5.0 or
870 newer (<= 4.2.x) and if you use the phpMyAdmin configuration storage, you
871 should run the :term:`SQL` script found in
872 :file:`sql/upgrade_column_info_4_3_0+.sql`.
874 Do not forget to clear the browser cache and to empty the old session by
875 logging out and logging in again.
877 .. index:: Authentication mode
879 .. _authentication_modes:
881 Using authentication modes
882 ++++++++++++++++++++++++++
884 :term:`HTTP` and cookie authentication modes are recommended in a **multi-user
885 environment** where you want to give users access to their own database and
886 don't want them to play around with others. Nevertheless, be aware that MS
887 Internet Explorer seems to be really buggy about cookies, at least till version
888 6. Even in a **single-user environment**, you might prefer to use :term:`HTTP`
889 or cookie mode so that your user/password pair are not in clear in the
892 :term:`HTTP` and cookie authentication
893 modes are more secure: the MySQL login information does not need to be
894 set in the phpMyAdmin configuration file (except possibly for the
895 :config:option:`$cfg['Servers'][$i]['controluser']`).
896 However, keep in mind that the password travels in plain text unless
897 you are using the HTTPS protocol. In cookie mode, the password is
898 stored, encrypted with the AES algorithm, in a temporary cookie.
900 Then each of the *true* users should be granted a set of privileges
901 on a set of particular databases. Normally you shouldn't give global
902 privileges to an ordinary user unless you understand the impact of those
903 privileges (for example, you are creating a superuser).
904 For example, to grant the user *real_user* with all privileges on
905 the database *user_base*:
907 .. code-block:: mysql
909 GRANT ALL PRIVILEGES ON user_base.* TO 'real_user'@localhost IDENTIFIED BY 'real_password';
911 What the user may now do is controlled entirely by the MySQL user management
912 system. With HTTP or cookie authentication mode, you don't need to fill the
913 user/password fields inside the :config:option:`$cfg['Servers']`.
923 .. index:: pair: HTTP; Authentication mode
927 HTTP authentication mode
928 ------------------------
930 * Uses :term:`HTTP` Basic authentication
931 method and allows you to log in as any valid MySQL user.
932 * Is supported with most PHP configurations. For :term:`IIS` (:term:`ISAPI`)
933 support using :term:`CGI` PHP see :ref:`faq1_32`, for using with Apache
934 :term:`CGI` see :ref:`faq1_35`.
935 * When PHP is running under Apache's :term:`mod_proxy_fcgi` (e.g. with PHP-FPM),
936 ``Authorization`` headers are not passed to the underlying FCGI application,
937 such that your credentials will not reach the application. In this case, you can
938 add the following configuration directive:
940 .. code-block:: apache
942 SetEnvIf Authorization "(.*)" HTTP_AUTHORIZATION=$1
944 * See also :ref:`faq4_4` about not using the :term:`.htaccess` mechanism along with
945 ':term:`HTTP`' authentication mode.
949 There is no way to do proper logout in HTTP authentication, most browsers
950 will remember credentials until there is no different successful
951 authentication. Because of this, this method has a limitation that you can not
952 login with the same user after logout.
954 .. index:: pair: Cookie; Authentication mode
958 Cookie authentication mode
959 --------------------------
961 * Username and password are stored in cookies during the session and password
962 is deleted when it ends.
963 * With this mode, the user can truly log out of phpMyAdmin and log
964 back in with the same username (this is not possible with :ref:`auth_http`).
965 * If you want to allow users to enter any hostname to connect (rather than only
966 servers that are configured in :file:`config.inc.php`),
967 see the :config:option:`$cfg['AllowArbitraryServer']` directive.
968 * As mentioned in the :ref:`require` section, having the ``openssl`` extension
969 will speed up access considerably, but is not required.
971 .. index:: pair: Signon; Authentication mode
975 Signon authentication mode
976 --------------------------
978 * This mode is a convenient way of using credentials from another
979 application to authenticate to phpMyAdmin to implement a single signon
981 * The other application has to store login information into session
982 data (see :config:option:`$cfg['Servers'][$i]['SignonSession']` and
983 :config:option:`$cfg['Servers'][$i]['SignonCookieParams']`) or you
984 need to implement script to return the credentials (see
985 :config:option:`$cfg['Servers'][$i]['SignonScript']`).
986 * When no credentials are available, the user is being redirected to
987 :config:option:`$cfg['Servers'][$i]['SignonURL']`, where you should handle
990 The very basic example of saving credentials in a session is available as
991 :file:`examples/signon.php`:
993 .. literalinclude:: ../examples/signon.php
996 Alternatively, you can also use this way to integrate with OpenID as shown
997 in :file:`examples/openid.php`:
999 .. literalinclude:: ../examples/openid.php
1002 If you intend to pass the credentials using some other means than, you have to
1003 implement wrapper in PHP to get that data and set it to
1004 :config:option:`$cfg['Servers'][$i]['SignonScript']`. There is a very minimal example
1005 in :file:`examples/signon-script.php`:
1007 .. literalinclude:: ../examples/signon-script.php
1011 :config:option:`$cfg['Servers'][$i]['auth_type']`,
1012 :config:option:`$cfg['Servers'][$i]['SignonSession']`,
1013 :config:option:`$cfg['Servers'][$i]['SignonCookieParams']`,
1014 :config:option:`$cfg['Servers'][$i]['SignonScript']`,
1015 :config:option:`$cfg['Servers'][$i]['SignonURL']`,
1016 :ref:`example-signon`
1018 .. index:: pair: Config; Authentication mode
1022 Config authentication mode
1023 --------------------------
1025 * This mode is sometimes the less secure one because it requires you to fill the
1026 :config:option:`$cfg['Servers'][$i]['user']` and
1027 :config:option:`$cfg['Servers'][$i]['password']`
1028 fields (and as a result, anyone who can read your :file:`config.inc.php`
1029 can discover your username and password).
1030 * In the :ref:`faqmultiuser` section, there is an entry explaining how
1031 to protect your configuration file.
1032 * For additional security in this mode, you may wish to consider the
1033 Host authentication :config:option:`$cfg['Servers'][$i]['AllowDeny']['order']`
1034 and :config:option:`$cfg['Servers'][$i]['AllowDeny']['rules']` configuration directives.
1035 * Unlike cookie and http, does not require a user to log in when first
1036 loading the phpMyAdmin site. This is by design but could allow any
1037 user to access your installation. Use of some restriction method is
1038 suggested, perhaps a :term:`.htaccess` file with the HTTP-AUTH directive or disallowing
1039 incoming HTTP requests at one’s router or firewall will suffice (both
1040 of which are beyond the scope of this manual but easily searchable
1045 Securing your phpMyAdmin installation
1046 +++++++++++++++++++++++++++++++++++++
1048 The phpMyAdmin team tries hard to make the application secure, however there
1049 are always ways to make your installation more secure:
1051 * Follow our `Security announcements <https://www.phpmyadmin.net/security/>`_ and upgrade
1052 phpMyAdmin whenever new vulnerability is published.
1053 * Serve phpMyAdmin on HTTPS only. Preferably, you should use HSTS as well, so that
1054 you're protected from protocol downgrade attacks.
1055 * Ensure your PHP setup follows recommendations for production sites, for example
1056 `display_errors <https://www.php.net/manual/en/errorfunc.configuration.php#ini.display-errors>`_
1058 * Remove the ``test`` directory from phpMyAdmin, unless you are developing and need a test suite.
1059 * Remove the ``setup`` directory from phpMyAdmin, you will probably not
1060 use it after the initial setup.
1061 * Properly choose an authentication method - :ref:`cookie`
1062 is probably the best choice for shared hosting.
1063 * Deny access to auxiliary files in :file:`./libraries/` or
1064 :file:`./templates/` subfolders in your webserver configuration.
1065 Such configuration prevents from possible path exposure and cross side
1066 scripting vulnerabilities that might happen to be found in that code. For the
1067 Apache webserver, this is often accomplished with a :term:`.htaccess` file in
1069 * Deny access to temporary files, see :config:option:`$cfg['TempDir']` (if that
1070 is placed inside your web root, see also :ref:`web-dirs`.
1071 * It is generally a good idea to protect a public phpMyAdmin installation
1072 against access by robots as they usually can not do anything good there. You
1073 can do this using ``robots.txt`` file in the root of your webserver or limit
1074 access by web server configuration, see :ref:`faq1_42`.
1075 * In case you don't want all MySQL users to be able to access
1076 phpMyAdmin, you can use :config:option:`$cfg['Servers'][$i]['AllowDeny']['rules']` to limit them
1077 or :config:option:`$cfg['Servers'][$i]['AllowRoot']` to deny root user access.
1078 * Enable :ref:`2fa` for your account.
1079 * Consider hiding phpMyAdmin behind an authentication proxy, so that
1080 users need to authenticate prior to providing MySQL credentials
1081 to phpMyAdmin. You can achieve this by configuring your web server to request
1082 HTTP authentication. For example in Apache this can be done with:
1084 .. code-block:: apache
1087 AuthName "Restricted Access"
1088 AuthUserFile /usr/share/phpmyadmin/passwd
1091 Once you have changed the configuration, you need to create a list of users which
1092 can authenticate. This can be done using the :program:`htpasswd` utility:
1096 htpasswd -c /usr/share/phpmyadmin/passwd username
1098 * If you are afraid of automated attacks, enabling Captcha by
1099 :config:option:`$cfg['CaptchaLoginPublicKey']` and
1100 :config:option:`$cfg['CaptchaLoginPrivateKey']` might be an option.
1101 * Failed login attempts are logged to syslog (if available, see
1102 :config:option:`$cfg['AuthLog']`). This can allow using a tool such as
1103 fail2ban to block brute-force attempts. Note that the log file used by syslog
1104 is not the same as the Apache error or access log files.
1105 * In case you're running phpMyAdmin together with other PHP applications, it is
1106 generally advised to use separate session storage for phpMyAdmin to avoid
1107 possible session-based attacks against it. You can use
1108 :config:option:`$cfg['SessionSavePath']` to achieve this.
1112 Using SSL for connection to database server
1113 +++++++++++++++++++++++++++++++++++++++++++
1115 It is recommended to use SSL when connecting to remote database server. There
1116 are several configuration options involved in the SSL setup:
1118 :config:option:`$cfg['Servers'][$i]['ssl']`
1119 Defines whether to use SSL at all. If you enable only this, the connection
1120 will be encrypted, but there is not authentication of the connection - you
1121 can not verify that you are talking to the right server.
1122 :config:option:`$cfg['Servers'][$i]['ssl_key']` and :config:option:`$cfg['Servers'][$i]['ssl_cert']`
1123 This is used for authentication of client to the server.
1124 :config:option:`$cfg['Servers'][$i]['ssl_ca']` and :config:option:`$cfg['Servers'][$i]['ssl_ca_path']`
1125 The certificate authorities you trust for server certificates.
1126 This is used to ensure that you are talking to a trusted server.
1127 :config:option:`$cfg['Servers'][$i]['ssl_verify']`
1128 This configuration disables server certificate verification. Use with
1131 When the database server is using a local connection or private network and SSL can not be configured
1132 you can use :config:option:`$cfg['MysqlSslWarningSafeHosts']` to explicitly list the hostnames that are considered secure.
1136 :ref:`example-google-ssl`,
1137 :ref:`example-aws-ssl`,
1138 :config:option:`$cfg['Servers'][$i]['ssl']`,
1139 :config:option:`$cfg['Servers'][$i]['ssl_key']`,
1140 :config:option:`$cfg['Servers'][$i]['ssl_cert']`,
1141 :config:option:`$cfg['Servers'][$i]['ssl_ca']`,
1142 :config:option:`$cfg['Servers'][$i]['ssl_ca_path']`,
1143 :config:option:`$cfg['Servers'][$i]['ssl_ciphers']`,
1144 :config:option:`$cfg['Servers'][$i]['ssl_verify']`
1149 Users with column-specific privileges are unable to "Browse"
1150 ------------------------------------------------------------
1152 If a user has only column-specific privileges on some (but not all) columns in a table, "Browse"
1153 will fail with an error message.
1155 As a workaround, a bookmarked query with the same name as the table can be created, this will
1156 run when using the "Browse" link instead. `Issue 11922 <https://github.com/phpmyadmin/phpmyadmin/issues/11922>`_.
1158 Trouble logging back in after logging out using 'http' authentication
1159 ----------------------------------------------------------------------
1161 When using the 'http' ``auth_type``, it can be impossible to log back in (when the logout comes
1162 manually or after a period of inactivity). `Issue 11898 <https://github.com/phpmyadmin/phpmyadmin/issues/11898>`_.
1164 .. _Composer tool: https://getcomposer.org/
1165 .. _Packagist: https://packagist.org/
1166 .. _Docker official image: https://hub.docker.com/_/phpmyadmin