From 04d6d5ca99ebfd1cebb8ce06618fb3811fc1a8aa Mon Sep 17 00:00:00 2001 From: Charles Date: Thu, 9 Jan 2020 10:55:03 +0100 Subject: phpmyadmin working --- srcs/phpmyadmin/doc/html/_sources/setup.txt | 1148 +++++++++++++++++++++++++++ 1 file changed, 1148 insertions(+) create mode 100644 srcs/phpmyadmin/doc/html/_sources/setup.txt (limited to 'srcs/phpmyadmin/doc/html/_sources/setup.txt') diff --git a/srcs/phpmyadmin/doc/html/_sources/setup.txt b/srcs/phpmyadmin/doc/html/_sources/setup.txt new file mode 100644 index 0000000..cb517e3 --- /dev/null +++ b/srcs/phpmyadmin/doc/html/_sources/setup.txt @@ -0,0 +1,1148 @@ +.. _setup: + +Installation +============ + +phpMyAdmin does not apply any special security methods to the MySQL +database server. It is still the system administrator's job to grant +permissions on the MySQL databases properly. phpMyAdmin's :guilabel:`Users` +page can be used for this. + +.. warning:: + + :term:`Mac` users should note that if you are on a version before + :term:`Mac OS X`, StuffIt unstuffs with :term:`Mac` formats. So you'll have + to resave as in BBEdit to Unix style ALL phpMyAdmin scripts before + uploading them to your server, as PHP seems not to like :term:`Mac`-style + end of lines character ("``\r``"). + +Linux distributions ++++++++++++++++++++ + +phpMyAdmin is included in most Linux distributions. It is recommended to use +distribution packages when possible - they usually provide integration to your +distribution and you will automatically get security updates from your distribution. + +.. _debian-package: + +Debian and Ubuntu +----------------- + +Debian's package repositories include a phpMyAdmin package, but be aware that +the configuration file is maintained in ``/etc/phpmyadmin`` and may differ in +some ways from the official phpMyAdmin documentation. Specifically, it does: + +* Configuration of a web server (works for Apache and lighttpd). +* Creating of :ref:`linked-tables` using dbconfig-common. +* Securing setup script, see :ref:`debian-setup`. + +.. seealso:: + + More information can be found in `README.Debian `_ + (it is installed as :file:`/usr/share/doc/phmyadmin/README.Debian` with the package). + +OpenSUSE +-------- + +OpenSUSE already comes with phpMyAdmin package, just install packages from +the `openSUSE Build Service `_. + +Gentoo +------ + +Gentoo ships the phpMyAdmin package, both in a near-stock configuration as well +as in a ``webapp-config`` configuration. Use ``emerge dev-db/phpmyadmin`` to +install. + +Mandriva +-------- + +Mandriva ships the phpMyAdmin package in their ``contrib`` branch and can be +installed via the usual Control Center. + +Fedora +------ + +Fedora ships the phpMyAdmin package, but be aware that the configuration file +is maintained in ``/etc/phpMyAdmin/`` and may differ in some ways from the +official phpMyAdmin documentation. + +Red Hat Enterprise Linux +------------------------ + +Red Hat Enterprise Linux itself and thus derivatives like CentOS don't +ship phpMyAdmin, but the Fedora-driven repository +`Extra Packages for Enterprise Linux (EPEL) `_ +is doing so, if it's +`enabled `_. +But be aware that the configuration file is maintained in +``/etc/phpMyAdmin/`` and may differ in some ways from the +official phpMyAdmin documentation. + +Installing on Windows ++++++++++++++++++++++ + +The easiest way to get phpMyAdmin on Windows is using third party products +which include phpMyAdmin together with a database and web server such as +`XAMPP `_. + +You can find more of such options at `Wikipedia `_. + +Installing from Git ++++++++++++++++++++ + +In order to install from Git, you'll need a few supporting applications: + +* `Git `_ to download the source, or you can download the most recent source directly from `Github `_ +* `Composer `__ +* `Node.js `_ (version 8 or higher) +* `Yarn `_ + +You can clone current phpMyAdmin source from +``https://github.com/phpmyadmin/phpmyadmin.git``: + +.. code-block:: sh + + git clone https://github.com/phpmyadmin/phpmyadmin.git + +Additionally you need to install dependencies using `Composer `__: + +.. code-block:: sh + + composer update + +If you do not intend to develop, you can skip the installation of developer tools +by invoking: + +.. code-block:: sh + + composer update --no-dev + +Finally, you'll need to use `Yarn`_ to install some JavaScript dependencies: + +.. code-block:: sh + + yarn install + +.. _composer: + +Installing using Composer ++++++++++++++++++++++++++ + +You can install phpMyAdmin using the `Composer tool`_, since 4.7.0 the releases +are automatically mirrored to the default `Packagist`_ repository. + +.. note:: + + The content of the Composer repository is automatically generated + separately from the releases, so the content doesn't have to be + 100% same as when you download the tarball. There should be no + functional differences though. + +To install phpMyAdmin simply run: + +.. code-block:: sh + + composer create-project phpmyadmin/phpmyadmin + +Alternatively you can use our own composer repository, which contains +the release tarballs and is available at +: + +.. code-block:: sh + + composer create-project phpmyadmin/phpmyadmin --repository-url=https://www.phpmyadmin.net/packages.json --no-dev + +.. _docker: + +Installing using Docker ++++++++++++++++++++++++ + +phpMyAdmin comes with a `Docker image`_, which you can easily deploy. You can +download it using: + +.. code-block:: sh + + docker pull phpmyadmin/phpmyadmin + +The phpMyAdmin server will listen on port 80. It supports several ways of +configuring the link to the database server, either by Docker's link feature +by linking your database container to ``db`` for phpMyAdmin (by specifying +``--link your_db_host:db``) or by environment variables (in this case it's up +to you to set up networking in Docker to allow the phpMyAdmin container to access +the database container over the network). + +.. _docker-vars: + +Docker environment variables +---------------------------- + +You can configure several phpMyAdmin features using environment variables: + +.. envvar:: PMA_ARBITRARY + + Allows you to enter a database server hostname on login form. + + .. seealso:: :config:option:`$cfg['AllowArbitraryServer']` + +.. envvar:: PMA_HOST + + Hostname or IP address of the database server to use. + + .. seealso:: :config:option:`$cfg['Servers'][$i]['host']` + +.. envvar:: PMA_HOSTS + + Comma-separated hostnames or IP addresses of the database servers to use. + + .. note:: Used only if :envvar:`PMA_HOST` is empty. + +.. envvar:: PMA_VERBOSE + + Verbose name of the database server. + + .. seealso:: :config:option:`$cfg['Servers'][$i]['verbose']` + +.. envvar:: PMA_VERBOSES + + Comma-separated verbose name of the database servers. + + .. note:: Used only if :envvar:`PMA_VERBOSE` is empty. + +.. envvar:: PMA_USER + + User name to use for :ref:`auth_config`. + +.. envvar:: PMA_PASSWORD + + Password to use for :ref:`auth_config`. + +.. envvar:: PMA_PORT + + Port of the database server to use. + +.. envvar:: PMA_PORTS + + Comma-separated ports of the database server to use. + + .. note:: Used only if :envvar:`PMA_PORT` is empty. + +.. envvar:: PMA_ABSOLUTE_URI + + The fully-qualified path (``https://pma.example.net/``) where the reverse + proxy makes phpMyAdmin available. + + .. seealso:: :config:option:`$cfg['PmaAbsoluteUri']` + +By default, :ref:`cookie` is used, but if :envvar:`PMA_USER` and +:envvar:`PMA_PASSWORD` are set, it is switched to :ref:`auth_config`. + +.. note:: + + The credentials you need to log in are stored in the MySQL server, in case + of Docker image, there are various ways to set it (for example + :samp:`MYSQL_ROOT_PASSWORD` when starting the MySQL container). Please check + documentation for `MariaDB container `_ + or `MySQL container `_. + +.. _docker-custom: + +Customizing configuration +------------------------- + +Additionally configuration can be tweaked by :file:`/etc/phpmyadmin/config.user.inc.php`. If +this file exists, it will be loaded after configuration is generated from above +environment variables, so you can override any configuration variable. This +configuration can be added as a volume when invoking docker using +`-v /some/local/directory/config.user.inc.php:/etc/phpmyadmin/config.user.inc.php` parameters. + +Note that the supplied configuration file is applied after :ref:`docker-vars`, +but you can override any of the values. + +For example to change the default behavior of CSV export you can use the following +configuration file: + +.. code-block:: php + + [ + 'auth_type' => 'cookie', + 'host' => 'mydb1', + 'port' => 3306, + 'verbose' => 'Verbose name 1', + ], + 2 => [ + 'auth_type' => 'cookie', + 'host' => 'mydb2', + 'port' => 3306, + 'verbose' => 'Verbose name 2', + ], + ]; + +.. seealso:: + + See :ref:`config` for detailed description of configuration options. + +Docker Volumes +-------------- + +You can use the following volumes to customize image behavior: + +:file:`/etc/phpmyadmin/config.user.inc.php` + + Can be used for additional settings, see the previous chapter for more details. + +:file:`/sessions/` + + Directory where PHP sessions are stored. You might want to share this + for example when using :ref:`auth_signon`. + +:file:`/www/themes/` + + Directory where phpMyAdmin looks for themes. By default only those shipped + with phpMyAdmin are included, but you can include additional phpMyAdmin + themes (see :ref:`themes`) by using Docker volumes. + +Docker Examples +--------------- + +To connect phpMyAdmin to a given server use: + +.. code-block:: sh + + docker run --name myadmin -d -e PMA_HOST=dbhost -p 8080:80 phpmyadmin/phpmyadmin + +To connect phpMyAdmin to more servers use: + +.. code-block:: sh + + docker run --name myadmin -d -e PMA_HOSTS=dbhost1,dbhost2,dbhost3 -p 8080:80 phpmyadmin/phpmyadmin + +To use arbitrary server option: + +.. code-block:: sh + + docker run --name myadmin -d --link mysql_db_server:db -p 8080:80 -e PMA_ARBITRARY=1 phpmyadmin/phpmyadmin + +You can also link the database container using Docker: + +.. code-block:: sh + + docker run --name phpmyadmin -d --link mysql_db_server:db -p 8080:80 phpmyadmin/phpmyadmin + +Running with additional configuration: + +.. code-block:: sh + + 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 + +Running with additional themes: + +.. code-block:: sh + + docker run --name phpmyadmin -d --link mysql_db_server:db -p 8080:80 -v /custom/phpmyadmin/theme/:/www/themes/theme/ phpmyadmin/phpmyadmin + +Using docker-compose +-------------------- + +Alternatively, you can also use docker-compose with the docker-compose.yml from +. This will run phpMyAdmin with an +arbitrary server - allowing you to specify MySQL/MariaDB server on the login page. + +.. code-block:: sh + + docker-compose up -d + +Customizing configuration file using docker-compose +--------------------------------------------------- + +You can use an external file to customize phpMyAdmin configuration and pass it +using the volumes directive: + +.. code-block:: yaml + + phpmyadmin: + image: phpmyadmin/phpmyadmin + container_name: phpmyadmin + environment: + - PMA_ARBITRARY=1 + restart: always + ports: + - 8080:80 + volumes: + - /sessions + - ~/docker/phpmyadmin/config.user.inc.php:/etc/phpmyadmin/config.user.inc.php + - /custom/phpmyadmin/theme/:/www/themes/theme/ + +.. seealso:: :ref:`docker-custom` + +Running behind haproxy in a subdirectory +---------------------------------------- + +When you want to expose phpMyAdmin running in a Docker container in a +subdirectory, you need to rewrite the request path in the server proxying the +requests. + +For example, using haproxy it can be done as: + +.. code-block:: text + + frontend http + bind *:80 + option forwardfor + option http-server-close + + ### NETWORK restriction + acl LOCALNET src 10.0.0.0/8 192.168.0.0/16 172.16.0.0/12 + + # /phpmyadmin + acl phpmyadmin path_dir /phpmyadmin + use_backend phpmyadmin if phpmyadmin LOCALNET + + backend phpmyadmin + mode http + + reqirep ^(GET|POST|HEAD)\ /phpmyadmin/(.*) \1\ /\2 + + # phpMyAdmin container IP + server localhost 172.30.21.21:80 + +When using traefik, something like following should work: + +.. code-block:: text + + defaultEntryPoints = ["http"] + [entryPoints] + [entryPoints.http] + address = ":80" + [entryPoints.http.redirect] + regex = "(http:\\/\\/[^\\/]+\\/([^\\?\\.]+)[^\\/])$" + replacement = "$1/" + + [backends] + [backends.myadmin] + [backends.myadmin.servers.myadmin] + url="http://internal.address.to.pma" + + [frontends] + [frontends.myadmin] + backend = "myadmin" + passHostHeader = true + [frontends.myadmin.routes.default] + rule="PathPrefixStrip:/phpmyadmin/;AddPrefix:/" + +You then should specify :envvar:`PMA_ABSOLUTE_URI` in the docker-compose +configuration: + +.. code-block:: yaml + + version: '2' + + services: + phpmyadmin: + restart: always + image: phpmyadmin/phpmyadmin + container_name: phpmyadmin + hostname: phpmyadmin + domainname: example.com + ports: + - 8000:80 + environment: + - PMA_HOSTS=172.26.36.7,172.26.36.8,172.26.36.9,172.26.36.10 + - PMA_VERBOSES=production-db1,production-db2,dev-db1,dev-db2 + - PMA_USER=root + - PMA_PASSWORD= + - PMA_ABSOLUTE_URI=http://example.com/phpmyadmin/ + +.. _quick_install: + +Quick Install ++++++++++++++ + +#. Choose an appropriate distribution kit from the phpmyadmin.net + Downloads page. Some kits contain only the English messages, others + contain all languages. We'll assume you chose a kit whose name + looks like ``phpMyAdmin-x.x.x -all-languages.tar.gz``. +#. Ensure you have downloaded a genuine archive, see :ref:`verify`. +#. Untar or unzip the distribution (be sure to unzip the subdirectories): + ``tar -xzvf phpMyAdmin_x.x.x-all-languages.tar.gz`` in your + webserver's document root. If you don't have direct access to your + document root, put the files in a directory on your local machine, + and, after step 4, transfer the directory on your web server using, + for example, FTP. +#. Ensure that all the scripts have the appropriate owner (if PHP is + running in safe mode, having some scripts with an owner different from + the owner of other scripts will be a problem). See :ref:`faq4_2` and + :ref:`faq1_26` for suggestions. +#. Now you must configure your installation. There are two methods that + can be used. Traditionally, users have hand-edited a copy of + :file:`config.inc.php`, but now a wizard-style setup script is provided + for those who prefer a graphical installation. Creating a + :file:`config.inc.php` is still a quick way to get started and needed for + some advanced features. + +Manually creating the file +-------------------------- + +To manually create the file, simply use your text editor to create the +file :file:`config.inc.php` (you can copy :file:`config.sample.inc.php` to get +a minimal configuration file) in the main (top-level) phpMyAdmin +directory (the one that contains :file:`index.php`). phpMyAdmin first +loads :file:`libraries/config.default.php` and then overrides those values +with anything found in :file:`config.inc.php`. If the default value is +okay for a particular setting, there is no need to include it in +:file:`config.inc.php`. You'll probably need only a few directives to get going; a +simple configuration may look like this: + +.. code-block:: xml+php + + or use setup script on our demo +server: . + +.. _verify: + +Verifying phpMyAdmin releases ++++++++++++++++++++++++++++++ + +Since July 2015 all phpMyAdmin releases are cryptographically signed by the +releasing developer, who through January 2016 was Marc Delisle. His key id is +0xFEFC65D181AF644A, his PGP fingerprint is: + +.. code-block:: console + + 436F F188 4B1A 0C3F DCBF 0D79 FEFC 65D1 81AF 644A + +and you can get more identification information from . + +Beginning in January 2016, the release manager is Isaac Bennetch. His key id is +0xCE752F178259BD92, and his PGP fingerprint is: + +.. code-block:: console + + 3D06 A59E CE73 0EB7 1B51 1C17 CE75 2F17 8259 BD92 + +and you can get more identification information from . + +Some additional downloads (for example themes) might be signed by Michal Čihař. His key id is +0x9C27B31342B7511D, and his PGP fingerprint is: + +.. code-block:: console + + 63CB 1DF1 EF12 CF2A C0EE 5A32 9C27 B313 42B7 511D + +and you can get more identification information from . + +You should verify that the signature matches the archive you have downloaded. +This way you can be sure that you are using the same code that was released. +You should also verify the date of the signature to make sure that you +downloaded the latest version. + +Each archive is accompanied by ``.asc`` files which contain the PGP signature +for it. Once you have both of them in the same folder, you can verify the signature: + +.. code-block:: console + + $ gpg --verify phpMyAdmin-4.5.4.1-all-languages.zip.asc + gpg: Signature made Fri 29 Jan 2016 08:59:37 AM EST using RSA key ID 8259BD92 + gpg: Can't check signature: public key not found + +As you can see gpg complains that it does not know the public key. At this +point, you should do one of the following steps: + +* Download the keyring from `our download server `_, then import it with: + +.. code-block:: console + + $ gpg --import phpmyadmin.keyring + +* Download and import the key from one of the key servers: + +.. code-block:: console + + $ gpg --keyserver hkp://pgp.mit.edu --recv-keys 3D06A59ECE730EB71B511C17CE752F178259BD92 + gpg: requesting key 8259BD92 from hkp server pgp.mit.edu + gpg: key 8259BD92: public key "Isaac Bennetch " imported + gpg: no ultimately trusted keys found + gpg: Total number processed: 1 + gpg: imported: 1 (RSA: 1) + +This will improve the situation a bit - at this point, you can verify that the +signature from the given key is correct but you still can not trust the name used +in the key: + +.. code-block:: console + + $ gpg --verify phpMyAdmin-4.5.4.1-all-languages.zip.asc + gpg: Signature made Fri 29 Jan 2016 08:59:37 AM EST using RSA key ID 8259BD92 + gpg: Good signature from "Isaac Bennetch " + gpg: aka "Isaac Bennetch " + gpg: WARNING: This key is not certified with a trusted signature! + gpg: There is no indication that the signature belongs to the owner. + Primary key fingerprint: 3D06 A59E CE73 0EB7 1B51 1C17 CE75 2F17 8259 BD92 + +The problem here is that anybody could issue the key with this name. You need to +ensure that the key is actually owned by the mentioned person. The GNU Privacy +Handbook covers this topic in the chapter `Validating other keys on your public +keyring`_. The most reliable method is to meet the developer in person and +exchange key fingerprints, however, you can also rely on the web of trust. This way +you can trust the key transitively though signatures of others, who have met +the developer in person. For example, you can see how `Isaac's key links to +Linus's key`_. + +Once the key is trusted, the warning will not occur: + +.. code-block:: console + + $ gpg --verify phpMyAdmin-4.5.4.1-all-languages.zip.asc + gpg: Signature made Fri 29 Jan 2016 08:59:37 AM EST using RSA key ID 8259BD92 + gpg: Good signature from "Isaac Bennetch " [full] + +Should the signature be invalid (the archive has been changed), you would get a +clear error regardless of the fact that the key is trusted or not: + +.. code-block:: console + + $ gpg --verify phpMyAdmin-4.5.4.1-all-languages.zip.asc + gpg: Signature made Fri 29 Jan 2016 08:59:37 AM EST using RSA key ID 8259BD92 + gpg: BAD signature from "Isaac Bennetch " [unknown] + +.. _Validating other keys on your public keyring: https://www.gnupg.org/gph/en/manual.html#AEN335 + +.. _Isaac's key links to Linus's key: https://pgp.cs.uu.nl/paths/79be3e4300411886/to/ce752f178259bd92.html + +.. index:: + single: Configuration storage + single: phpMyAdmin configuration storage + single: pmadb + +.. _linked-tables: + +phpMyAdmin configuration storage +++++++++++++++++++++++++++++++++ + +.. versionchanged:: 3.4.0 + + Prior to phpMyAdmin 3.4.0 this was called Linked Tables Infrastructure, but + the name was changed due to the extended scope of the storage. + +For a whole set of additional features (:ref:`bookmarks`, comments, :term:`SQL`-history, +tracking mechanism, :term:`PDF`-generation, :ref:`transformations`, :ref:`relations` +etc.) you need to create a set of special tables. Those tables can be located +in your own database, or in a central database for a multi-user installation +(this database would then be accessed by the controluser, so no other user +should have rights to it). + +.. _zeroconf: + +Zero configuration +------------------ + +In many cases, this database structure can be automatically created and +configured. This is called “Zero Configuration” mode and can be particularly +useful in shared hosting situations. “Zeroconf” mode is on by default, to +disable set :config:option:`$cfg['ZeroConf']` to false. + +The following three scenarios are covered by the Zero Configuration mode: + +* When entering a database where the configuration storage tables are not + present, phpMyAdmin offers to create them from the Operations tab. +* When entering a database where the tables do already exist, the software + automatically detects this and begins using them. This is the most common + situation; after the tables are initially created automatically they are + continually used without disturbing the user; this is also most useful on + shared hosting where the user is not able to edit :file:`config.inc.php` and + usually the user only has access to one database. +* When having access to multiple databases, if the user first enters the + database containing the configuration storage tables then switches to + another database, + phpMyAdmin continues to use the tables from the first database; the user is + not prompted to create more tables in the new database. + +Manual configuration +-------------------- + +Please look at your ``./sql/`` directory, where you should find a +file called *create\_tables.sql*. (If you are using a Windows server, +pay special attention to :ref:`faq1_23`). + +If you already had this infrastructure and: + +* upgraded to MySQL 4.1.2 or newer, please use + :file:`sql/upgrade_tables_mysql_4_1_2+.sql`. +* upgraded to phpMyAdmin 4.3.0 or newer from 2.5.0 or newer (<= 4.2.x), + please use :file:`sql/upgrade_column_info_4_3_0+.sql`. +* upgraded to phpMyAdmin 4.7.0 or newer from 4.3.0 or newer, + please use :file:`sql/upgrade_tables_4_7_0+.sql`. + +and then create new tables by importing :file:`sql/create_tables.sql`. + +You can use your phpMyAdmin to create the tables for you. Please be +aware that you may need special (administrator) privileges to create +the database and tables, and that the script may need some tuning, +depending on the database name. + +After having imported the :file:`sql/create_tables.sql` file, you +should specify the table names in your :file:`config.inc.php` file. The +directives used for that can be found in the :ref:`config`. + +You will also need to have a controluser +(:config:option:`$cfg['Servers'][$i]['controluser']` and +:config:option:`$cfg['Servers'][$i]['controlpass']` settings) +with the proper rights to those tables. For example you can create it +using following statement: + +And for any MariaDB version: + +.. code-block:: mysql + + CREATE USER 'pma'@'localhost' IDENTIFIED VIA mysql_native_password USING 'pmapass'; + GRANT SELECT, INSERT, UPDATE, DELETE ON ``.* TO 'pma'@'localhost'; + +For MySQL 8.0 and newer: + +.. code-block:: mysql + + CREATE USER 'pma'@'localhost' IDENTIFIED WITH caching_sha2_password BY 'pmapass'; + GRANT SELECT, INSERT, UPDATE, DELETE ON .* TO 'pma'@'localhost'; + +For MySQL older than 8.0: + +.. code-block:: mysql + + CREATE USER 'pma'@'localhost' IDENTIFIED WITH mysql_native_password AS 'pmapass'; + GRANT SELECT, INSERT, UPDATE, DELETE ON .* TO 'pma'@'localhost'; + +Note that MySQL installations with PHP older than 7.4 and MySQL newer than 8.0 may require +using the mysql_native_password authentication as a workaround, see +:ref:`faq1_45` for details. + +.. _upgrading: + +Upgrading from an older version ++++++++++++++++++++++++++++++++ + +.. warning:: + + **Never** extract the new version over an existing installation of + phpMyAdmin, always first remove the old files keeping just the + configuration. + + This way, you will not leave any old or outdated files in the directory, + which can have severe security implications or can cause various breakages. + +Simply copy :file:`config.inc.php` from your previous installation into +the newly unpacked one. Configuration files from old versions may +require some tweaking as some options have been changed or removed. +For compatibility with PHP 5.3 and later, remove a +``set_magic_quotes_runtime(0);`` statement that you might find near +the end of your configuration file. + +You should **not** copy :file:`libraries/config.default.php` over +:file:`config.inc.php` because the default configuration file is version- +specific. + +The complete upgrade can be performed in a few simple steps: + +1. Download the latest phpMyAdmin version from . +2. Rename existing phpMyAdmin folder (for example to ``phpmyadmin-old``). +3. Unpack freshly downloaded phpMyAdmin to the desired location (for example ``phpmyadmin``). +4. Copy :file:`config.inc.php`` from old location (``phpmyadmin-old``) to the new one (``phpmyadmin``). +5. Test that everything works properly. +6. Remove backup of a previous version (``phpmyadmin-old``). + +If you have upgraded your MySQL server from a version previous to 4.1.2 to +version 5.x or newer and if you use the phpMyAdmin configuration storage, you +should run the :term:`SQL` script found in +:file:`sql/upgrade_tables_mysql_4_1_2+.sql`. + +If you have upgraded your phpMyAdmin to 4.3.0 or newer from 2.5.0 or +newer (<= 4.2.x) and if you use the phpMyAdmin configuration storage, you +should run the :term:`SQL` script found in +:file:`sql/upgrade_column_info_4_3_0+.sql`. + +Do not forget to clear the browser cache and to empty the old session by +logging out and logging in again. + +.. index:: Authentication mode + +.. _authentication_modes: + +Using authentication modes +++++++++++++++++++++++++++ + +:term:`HTTP` and cookie authentication modes are recommended in a **multi-user +environment** where you want to give users access to their own database and +don't want them to play around with others. Nevertheless, be aware that MS +Internet Explorer seems to be really buggy about cookies, at least till version +6. Even in a **single-user environment**, you might prefer to use :term:`HTTP` +or cookie mode so that your user/password pair are not in clear in the +configuration file. + +:term:`HTTP` and cookie authentication +modes are more secure: the MySQL login information does not need to be +set in the phpMyAdmin configuration file (except possibly for the +:config:option:`$cfg['Servers'][$i]['controluser']`). +However, keep in mind that the password travels in plain text unless +you are using the HTTPS protocol. In cookie mode, the password is +stored, encrypted with the AES algorithm, in a temporary cookie. + +Then each of the *true* users should be granted a set of privileges +on a set of particular databases. Normally you shouldn't give global +privileges to an ordinary user unless you understand the impact of those +privileges (for example, you are creating a superuser). +For example, to grant the user *real_user* with all privileges on +the database *user_base*: + +.. code-block:: mysql + + GRANT ALL PRIVILEGES ON user_base.* TO 'real_user'@localhost IDENTIFIED BY 'real_password'; + +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 +------------------------ + +* Uses :term:`HTTP` Basic authentication + method and allows you to log in as any valid MySQL user. +* Is supported with most PHP configurations. For :term:`IIS` (:term:`ISAPI`) + support using :term:`CGI` PHP see :ref:`faq1_32`, for using with Apache + :term:`CGI` see :ref:`faq1_35`. +* When PHP is running under Apache's :term:`mod_proxy_fcgi` (e.g. with PHP-FPM), + ``Authorization`` headers are not passed to the underlying FCGI application, + such that your credentials will not reach the application. In this case, you can + add the following configuration directive: + + .. code-block:: apache + + SetEnvIf Authorization "(.*)" HTTP_AUTHORIZATION=$1 + +* 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 a limitation that you can not + login with the same user after logout. + +.. index:: pair: Cookie; Authentication mode + +.. _cookie: + +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 (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 ``openssl`` extension + will speed up access considerably, but is not required. + +.. index:: pair: Signon; Authentication mode + +.. _auth_signon: + +Signon authentication mode +-------------------------- + +* This mode is a convenient way of using credentials from another + application to authenticate to phpMyAdmin to implement a single signon + solution. +* The other application has to store login information into session + data (see :config:option:`$cfg['Servers'][$i]['SignonSession']` and + :config:option:`$cfg['Servers'][$i]['SignonCookieParams']`) or you + need to implement script to return the credentials (see + :config:option:`$cfg['Servers'][$i]['SignonScript']`). +* When no credentials are available, the user is being redirected to + :config:option:`$cfg['Servers'][$i]['SignonURL']`, where you should handle + the login process. + +The very basic example of saving credentials in a session is available as +:file:`examples/signon.php`: + +.. literalinclude:: ../examples/signon.php + :language: php + +Alternatively, you can also use this way to integrate with OpenID as shown +in :file:`examples/openid.php`: + +.. literalinclude:: ../examples/openid.php + :language: php + +If you intend to pass the credentials using some other means than, you have to +implement wrapper in PHP to get that data and set it to +:config:option:`$cfg['Servers'][$i]['SignonScript']`. There is a very minimal example +in :file:`examples/signon-script.php`: + +.. literalinclude:: ../examples/signon-script.php + :language: php + +.. seealso:: + :config:option:`$cfg['Servers'][$i]['auth_type']`, + :config:option:`$cfg['Servers'][$i]['SignonSession']`, + :config:option:`$cfg['Servers'][$i]['SignonCookieParams']`, + :config:option:`$cfg['Servers'][$i]['SignonScript']`, + :config:option:`$cfg['Servers'][$i]['SignonURL']`, + :ref:`example-signon` + +.. index:: pair: Config; Authentication mode + +.. _auth_config: + +Config authentication mode +-------------------------- + +* This mode is sometimes the less secure one because it requires you to fill the + :config:option:`$cfg['Servers'][$i]['user']` and + :config:option:`$cfg['Servers'][$i]['password']` + fields (and as a result, anyone who can read your :file:`config.inc.php` + can discover your username and password). +* In the :ref:`faqmultiuser` section, there is an entry explaining how + to protect your configuration file. +* For additional security in this mode, you may wish to consider the + Host authentication :config:option:`$cfg['Servers'][$i]['AllowDeny']['order']` + and :config:option:`$cfg['Servers'][$i]['AllowDeny']['rules']` configuration directives. +* Unlike cookie and http, does not require a user to log in when first + loading the phpMyAdmin site. This is by design but could allow any + user to access your installation. Use of some restriction method is + suggested, perhaps a :term:`.htaccess` file with the HTTP-AUTH directive or disallowing + incoming HTTP requests at one’s router or firewall will suffice (both + of which are beyond the scope of this manual but easily searchable + with Google). + +.. _securing: + +Securing your phpMyAdmin installation ++++++++++++++++++++++++++++++++++++++ + +The phpMyAdmin team tries hard to make the application secure, however there +are always ways to make your installation more secure: + +* Follow our `Security announcements `_ and upgrade + phpMyAdmin whenever new vulnerability is published. +* Serve phpMyAdmin on HTTPS only. Preferably, you should use HSTS as well, so that + you're protected from protocol downgrade attacks. +* Ensure your PHP setup follows recommendations for production sites, for example + `display_errors `_ + should be disabled. +* Remove the ``test`` directory from phpMyAdmin, unless you are developing and need a test suite. +* Remove the ``setup`` directory from phpMyAdmin, you will probably not + use it after the initial setup. +* Properly choose an authentication method - :ref:`cookie` + is probably the best choice for shared hosting. +* Deny access to auxiliary files in :file:`./libraries/` or + :file:`./templates/` subfolders in your webserver configuration. + Such configuration prevents from possible path exposure and cross side + scripting vulnerabilities that might happen to be found in that code. For the + Apache webserver, this is often accomplished with a :term:`.htaccess` file in + those directories. +* Deny access to temporary files, see :config:option:`$cfg['TempDir']` (if that + is placed inside your web root, see also :ref:`web-dirs`. +* It is generally a good idea to protect a public phpMyAdmin installation + against access by robots as they usually can not do anything good there. You + can do this using ``robots.txt`` file in the root of your webserver or limit + access by web server configuration, see :ref:`faq1_42`. +* In case you don't want all MySQL users to be able to access + phpMyAdmin, you can use :config:option:`$cfg['Servers'][$i]['AllowDeny']['rules']` to limit them + or :config:option:`$cfg['Servers'][$i]['AllowRoot']` to deny root user access. +* Enable :ref:`2fa` for your account. +* Consider hiding phpMyAdmin behind an authentication proxy, so that + users need to authenticate prior to providing MySQL credentials + to phpMyAdmin. You can achieve this by configuring your web server to request + HTTP authentication. For example in Apache this can be done with: + + .. code-block:: apache + + AuthType Basic + AuthName "Restricted Access" + AuthUserFile /usr/share/phpmyadmin/passwd + Require valid-user + + Once you have changed the configuration, you need to create a list of users which + can authenticate. This can be done using the :program:`htpasswd` utility: + + .. code-block:: sh + + htpasswd -c /usr/share/phpmyadmin/passwd username + +* If you are afraid of automated attacks, enabling Captcha by + :config:option:`$cfg['CaptchaLoginPublicKey']` and + :config:option:`$cfg['CaptchaLoginPrivateKey']` might be an option. +* Failed login attemps are logged to syslog (if available, see + :config:option:`$cfg['AuthLog']`). This can allow using a tool such as + fail2ban to block brute-force attempts. Note that the log file used by syslog + is not the same as the Apache error or access log files. +* In case you're running phpMyAdmin together with other PHP applications, it is + generally advised to use separate session storage for phpMyAdmin to avoid + possible session-based attacks against it. You can use + :config:option:`$cfg['SessionSavePath']` to achieve this. + +.. _ssl: + +Using SSL for connection to database server ++++++++++++++++++++++++++++++++++++++++++++ + +It is recommended to use SSL when connecting to remote database server. There +are several configuration options involved in the SSL setup: + +:config:option:`$cfg['Servers'][$i]['ssl']` + Defines whether to use SSL at all. If you enable only this, the connection + will be encrypted, but there is not authentication of the connection - you + can not verify that you are talking to the right server. +:config:option:`$cfg['Servers'][$i]['ssl_key']` and :config:option:`$cfg['Servers'][$i]['ssl_cert']` + This is used for authentication of client to the server. +:config:option:`$cfg['Servers'][$i]['ssl_ca']` and :config:option:`$cfg['Servers'][$i]['ssl_ca_path']` + The certificate authorities you trust for server certificates. + This is used to ensure that you are talking to a trusted server. +:config:option:`$cfg['Servers'][$i]['ssl_verify']` + This configuration disables server certificate verification. Use with + caution. + +.. seealso:: + + :ref:`example-google-ssl`, + :config:option:`$cfg['Servers'][$i]['ssl']`, + :config:option:`$cfg['Servers'][$i]['ssl_key']`, + :config:option:`$cfg['Servers'][$i]['ssl_cert']`, + :config:option:`$cfg['Servers'][$i]['ssl_ca']`, + :config:option:`$cfg['Servers'][$i]['ssl_ca_path']`, + :config:option:`$cfg['Servers'][$i]['ssl_ciphers']`, + :config:option:`$cfg['Servers'][$i]['ssl_verify']` + +Known issues +++++++++++++ + +Users with column-specific privileges are unable to "Browse" +------------------------------------------------------------ + +If a user has only column-specific privileges on some (but not all) columns in a table, "Browse" +will fail with an error message. + +As a workaround, a bookmarked query with the same name as the table can be created, this will +run when using the "Browse" link instead. `Issue 11922 `_. + +Trouble logging back in after logging out using 'http' authentication +---------------------------------------------------------------------- + +When using the 'http' ``auth_type``, it can be impossible to log back in (when the logout comes +manually or after a period of inactivity). `Issue 11898 `_. + +.. _Composer tool: https://getcomposer.org/ +.. _Packagist: https://packagist.org/ +.. _Docker image: https://hub.docker.com/r/phpmyadmin/phpmyadmin/ -- cgit