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``").
24 #. Choose an appropriate distribution kit from the phpmyadmin.net
25 Downloads page. Some kits contain only the English messages, others
26 contain all languages. We'll assume you chose a kit whose name
27 looks like ``phpMyAdmin-x.x.x -all-languages.tar.gz``.
28 #. Untar or unzip the distribution (be sure to unzip the subdirectories):
29 ``tar -xzvf phpMyAdmin_x.x.x-all-languages.tar.gz`` in your
30 webserver's document root. If you don't have direct access to your
31 document root, put the files in a directory on your local machine,
32 and, after step 4, transfer the directory on your web server using,
34 #. Ensure that all the scripts have the appropriate owner (if PHP is
35 running in safe mode, having some scripts with an owner different from
36 the owner of other scripts will be a problem). See :ref:`faq4_2` and
37 :ref:`faq1_26` for suggestions.
38 #. Now you must configure your installation. There are two methods that
39 can be used. Traditionally, users have hand-edited a copy of
40 :file:`config.inc.php`, but now a wizard-style setup script is provided
41 for those who prefer a graphical installation. Creating a
42 :file:`config.inc.php` is still a quick way to get started and needed for
43 some advanced features.
49 To manually create the file, simply use your text editor to create the
50 file :file:`config.inc.php` (you can copy :file:`config.sample.inc.php` to get
51 minimal configuration file) in the main (top-level) phpMyAdmin
52 directory (the one that contains :file:`index.php`). phpMyAdmin first
53 loads :file:`libraries/config.default.php` and then overrides those values
54 with anything found in :file:`config.inc.php`. If the default value is
55 okay for a particular setting, there is no need to include it in
56 :file:`config.inc.php`. You'll need a few directives to get going, a
57 simple configuration may look like this:
59 .. code-block:: xml+php
63 $cfg['blowfish_secret'] = 'ba17c1ec07d65003'; // use here a value of your choice
67 $cfg['Servers'][$i]['auth_type'] = 'cookie';
70 Or, if you prefer to not be prompted every time you log in:
72 .. code-block:: xml+php
79 $cfg['Servers'][$i]['user'] = 'root';
80 $cfg['Servers'][$i]['password'] = 'cbb74bc'; // use here your password
81 $cfg['Servers'][$i]['auth_type'] = 'config';
84 For a full explanation of possible configuration values, see the
85 :ref:`config` of this document.
87 .. index:: Setup script
94 Instead of manually editing :file:`config.inc.php`, you can use the `Setup
95 Script <setup/>`_. First you must manually create a folder ``config``
96 in the phpMyAdmin directory. This is a security measure. On a
97 Linux/Unix system you can use the following commands:
103 mkdir config # create directory for saving
104 chmod o+rw config # give it world writable permissions
106 And to edit an existing configuration, copy it over first:
111 cp config.inc.php config/ # copy current configuration for editing
112 chmod o+w config/config.inc.php # give it world writable permissions
114 On other platforms, simply create the folder and ensure that your web
115 server has read and write access to it. :ref:`faq1_26` can help with
118 Next, open ``setup/`` in your browser. Note that **changes are
119 not saved to disk until explicitly choose ``Save``** from the
120 *Configuration* area of the screen. Normally the script saves the new
121 :file:`config.inc.php` to the ``config/`` directory, but if the webserver does
122 not have the proper permissions you may see the error "Cannot load or
123 save configuration." Ensure that the ``config/`` directory exists and
124 has the proper permissions - or use the ``Download`` link to save the
125 config file locally and upload (via FTP or some similar means) to the
128 Once the file has been saved, it must be moved out of the ``config/``
129 directory and the permissions must be reset, again as a security
135 mv config/config.inc.php . # move file to current directory
136 chmod o-rw config.inc.php # remove world read and write permissions
137 rm -rf config # remove not needed directory
139 Now the file is ready to be used. You can choose to review or edit the
140 file with your favorite editor, if you prefer to set some advanced
141 options which the setup script does not provide.
143 #. If you are using the ``auth_type`` "config", it is suggested that you
144 protect the phpMyAdmin installation directory because using config
145 does not require a user to enter a password to access the phpMyAdmin
146 installation. Use of an alternate authentication method is
147 recommended, for example with HTTP–AUTH in a :term:`.htaccess` file or switch to using
148 ``auth_type`` cookie or http. See the :ref:`faqmultiuser`
149 for additional information, especially :ref:`faq4_4`.
150 #. Open the `main phpMyAdmin directory <index.php>`_ in your browser.
151 phpMyAdmin should now display a welcome screen and your databases, or
152 a login dialog if using :term:`HTTP` or
153 cookie authentication mode.
154 #. You should deny access to the ``./libraries`` and ``./setup/lib``
155 subfolders in your webserver configuration. For Apache you can use
156 supplied :term:`.htaccess` file in that folder, for other webservers, you should
157 configure this yourself. Such configuration prevents from possible
158 path exposure and cross side scripting vulnerabilities that might
159 happen to be found in that code.
160 #. It is generally good idea to protect public phpMyAdmin installation
161 against access by robots as they usually can not do anything good
162 there. You can do this using ``robots.txt`` file in root of your
163 webserver or limit access by web server configuration, see
167 single: Configuration storage
168 single: phpMyAdmin configuration storage
173 phpMyAdmin configuration storage
174 ++++++++++++++++++++++++++++++++
176 For a whole set of new features (bookmarks, comments, :term:`SQL`-history,
177 tracking mechanism, :term:`PDF`-generation, column contents transformation,
178 etc.) you need to create a set of special tables. Those tables can be located
179 in your own database, or in a central database for a multi-user installation
180 (this database would then be accessed by the controluser, so no other user
181 should have rights to it).
183 Please look at your ``./examples/`` directory, where you should find a
184 file called *create\_tables.sql*. (If you are using a Windows server,
185 pay special attention to :ref:`faq1_23`).
187 If you already had this infrastructure and upgraded to MySQL 4.1.2 or
188 newer, please use :file:`examples/upgrade_tables_mysql_4_1_2+.sql`
189 and then create new tables by importing
190 :file:`examples/create_tables.sql`.
192 You can use your phpMyAdmin to create the tables for you. Please be
193 aware that you may need special (administrator) privileges to create
194 the database and tables, and that the script may need some tuning,
195 depending on the database name.
197 After having imported the :file:`examples/create_tables.sql` file, you
198 should specify the table names in your :file:`config.inc.php` file. The
199 directives used for that can be found in the :ref:`config`. You will also need to
200 have a controluser with the proper rights to those tables (see section
201 :ref:`authentication_modes` below).
205 Upgrading from an older version
206 +++++++++++++++++++++++++++++++
208 Simply copy :file:`config.inc.php` from your previous installation into
209 the newly unpacked one. Configuration files from old versions may
210 require some tweaking as some options have been changed or removed.
211 For compatibility with PHP 6, remove a
212 ``set_magic_quotes_runtime(0);`` statement that you might find near
213 the end of your configuration file.
215 You should **not** copy :file:`libraries/config.default.php` over
216 :file:`config.inc.php` because the default configuration file is version-
219 If you have upgraded your MySQL server from a version previous to 4.1.2 to
220 version 5.x or newer and if you use the phpMyAdmin configuration storage, you
221 should run the :term:`SQL` script found in
222 :file:`examples/upgrade_tables_mysql_4_1_2+.sql`.
224 .. index:: Authentication mode
226 .. _authentication_modes:
228 Using authentication modes
229 ++++++++++++++++++++++++++
231 :term:`HTTP` and cookie authentication modes are recommended in a **multi-user
232 environment** where you want to give users access to their own database and
233 don't want them to play around with others. Nevertheless be aware that MS
234 Internet Explorer seems to be really buggy about cookies, at least till version
235 6. Even in a **single-user environment**, you might prefer to use :term:`HTTP`
236 or cookie mode so that your user/password pair are not in clear in the
239 :term:`HTTP` and cookie authentication
240 modes are more secure: the MySQL login information does not need to be
241 set in the phpMyAdmin configuration file (except possibly for the
242 :config:option:`$cfg['Servers'][$i]['controluser']`).
243 However, keep in mind that the password travels in plain text, unless
244 you are using the HTTPS protocol. In cookie mode, the password is
245 stored, encrypted with the blowfish algorithm, in a temporary cookie.
249 This section is only applicable if your MySQL server is running
250 with ``--skip-show-database``.
252 For ':term:`HTTP`' and 'cookie' modes, phpMyAdmin needs a controluser that has
253 **only** the ``SELECT`` privilege on the *`mysql`.`user` (all columns except
254 `Password`)*, *`mysql`.`db` (all columns)*, *`mysql`.`host` (all columns)* and
255 *`mysql`.`tables\_priv` (all columns except `Grantor` and `Timestamp`)* tables.
256 You must specify the details for the controluser in the :file:`config.inc.php`
257 file under the :config:option:`$cfg['Servers'][$i]['controluser']` and
258 :config:option:`$cfg['Servers'][$i]['controlpass']` settings. The following
259 example assumes you want to use ``pma`` as the controluser and ``pmapass`` as
260 the controlpass, but **this is only an example: use something else in your
261 file!** Input these statements from the phpMyAdmin :term:`SQL` Query window or
262 mysql command–line client. Of course you have to replace ``localhost`` with the
263 webserver's host if it's not the same as the MySQL server's one.
265 .. code-block:: mysql
267 GRANT USAGE ON mysql.* TO 'pma'@'localhost' IDENTIFIED BY 'pmapass';
269 Host, User, Select_priv, Insert_priv, Update_priv, Delete_priv,
270 Create_priv, Drop_priv, Reload_priv, Shutdown_priv, Process_priv,
271 File_priv, Grant_priv, References_priv, Index_priv, Alter_priv,
272 Show_db_priv, Super_priv, Create_tmp_table_priv, Lock_tables_priv,
273 Execute_priv, Repl_slave_priv, Repl_client_priv
274 ) ON mysql.user TO 'pma'@'localhost';
275 GRANT SELECT ON mysql.db TO 'pma'@'localhost';
276 GRANT SELECT ON mysql.host TO 'pma'@'localhost';
277 GRANT SELECT (Host, Db, User, Table_name, Table_priv, Column_priv)
278 ON mysql.tables_priv TO 'pma'@'localhost';
280 If you want to use the many new relation and bookmark features:
282 .. code-block:: mysql
284 GRANT SELECT, INSERT, UPDATE, DELETE ON <pma_db>.* TO 'pma'@'localhost';
286 (this of course requires that your :ref:`linked-tables` be set up).
288 Then each of the *true* users should be granted a set of privileges
289 on a set of particular databases. Normally you shouldn't give global
290 privileges to an ordinary user, unless you understand the impact of those
291 privileges (for example, you are creating a superuser).
292 For example, to grant the user *real_user* with all privileges on
293 the database *user_base*:
295 .. code-block:: mysql
297 GRANT ALL PRIVILEGES ON user_base.* TO 'real_user'@localhost IDENTIFIED BY 'real_password';
300 What the user may now do is controlled entirely by the MySQL user management
301 system. With HTTP or cookie authentication mode, you don't need to fill the
302 user/password fields inside the :config:option:`$cfg['Servers']`.
304 .. index:: pair: HTTP; Authentication mode
306 HTTP authentication mode
307 ------------------------
309 * Uses :term:`HTTP` Basic authentication
310 method and allows you to log in as any valid MySQL user.
311 * Is supported with most PHP configurations. For :term:`IIS` (:term:`ISAPI`)
312 support using :term:`CGI` PHP see :ref:`faq1_32`, for using with Apache
313 :term:`CGI` see :ref:`faq1_35`.
314 * See also :ref:`faq4_4` about not using the :term:`.htaccess` mechanism along with
315 ':term:`HTTP`' authentication mode.
317 .. index:: pair: Cookie; Authentication mode
321 Cookie authentication mode
322 --------------------------
324 * You can use this method as a replacement for the :term:`HTTP` authentication
325 (for example, if you're running :term:`IIS`).
326 * Obviously, the user must enable cookies in the browser, but this is
327 now a requirement for all authentication modes.
328 * With this mode, the user can truly log out of phpMyAdmin and log in
329 back with the same username.
330 * If you want to log in to arbitrary server see :config:option:`$cfg['AllowArbitraryServer']` directive.
331 * As mentioned in the :ref:`require` section, having the ``mcrypt`` extension will
332 speed up access considerably, but is not required.
334 .. index:: pair: Signon; Authentication mode
336 Signon authentication mode
337 --------------------------
339 * This mode is a convenient way of using credentials from another
340 application to authenticate to phpMyAdmin.
341 * The other application has to store login information into session
345 :config:option:`$cfg['Servers'][$i]['auth_type']`,
346 :config:option:`$cfg['Servers'][$i]['SignonSession']`,
347 :config:option:`$cfg['Servers'][$i]['SignonScript']`,
348 :config:option:`$cfg['Servers'][$i]['SignonURL']`
351 .. index:: pair: Config; Authentication mode
353 Config authentication mode
354 --------------------------
356 * This mode is the less secure one because it requires you to fill the
357 :config:option:`$cfg['Servers'][$i]['user']` and
358 :config:option:`$cfg['Servers'][$i]['password']`
359 fields (and as a result, anyone who can read your :file:`config.inc.php`
360 can discover your username and password). But you don't need to setup
361 a "controluser" here: using the :config:option:`$cfg['Servers'][$i]['only_db']` might be enough.
362 * In the :ref:`faqmultiuser` section, there is an entry explaining how
363 to protect your configuration file.
364 * For additional security in this mode, you may wish to consider the
365 Host authentication :config:option:`$cfg['Servers'][$i]['AllowDeny']['order']`
366 and :config:option:`$cfg['Servers'][$i]['AllowDeny']['rules']` configuration directives.
367 * Unlike cookie and http, does not require a user to log in when first
368 loading the phpMyAdmin site. This is by design but could allow any
369 user to access your installation. Use of some restriction method is
370 suggested, perhaps a :term:`.htaccess` file with the HTTP-AUTH directive or disallowing
371 incoming HTTP requests at one’s router or firewall will suffice (both
372 of which are beyond the scope of this manual but easily searchable
375 .. index:: pair: Swekey; Authentication mode
379 Swekey authentication mode
380 --------------------------
382 The Swekey is a low cost authentication USB key that can be used in
383 web applications. When Swekey authentication is activated, phpMyAdmin
384 requires the users's Swekey to be plugged before entering the login
385 page (currently supported for cookie authentication mode only). Swekey
386 Authentication is disabled by default. To enable it, add the following
387 line to :file:`config.inc.php`:
391 $cfg['Servers'][$i]['auth_swekey_config'] = '/etc/swekey.conf';
393 You then have to create the ``swekey.conf`` file that will associate
394 each user with their Swekey Id. It is important to place this file
395 outside of your web server's document root (in the example, it is
396 located in ``/etc``). A self documented sample file is provided in the
397 ``examples`` directory. Feel free to use it with your own users'
398 information. If you want to purchase a Swekey please visit
399 `http://phpmyadmin.net/auth\_key <http://phpmyadmin.net/auth_key>`_
400 since this link provides funding for phpMyAdmin.
402 .. seealso:: :config:option:`$cfg['Servers'][$i]['auth_swekey_config']`
405 Securing your phpMyAdmin installation
406 +++++++++++++++++++++++++++++++++++++
408 The phpMyAdmin team tries hardly to make the application secure, however there
409 are always ways to make your installation more secure:
411 * remove ``setup`` directory from phpMyAdmin, you will probably not
412 use it after initial setup
413 * prevent access to ``libraries`` directory from browser,
414 as it is not needed, supplied ``.htaccess`` file does this
415 * properly choose authentication method - :ref:`cookie`
416 is probably the best choice for shared hosting
417 * in case you don't want all MySQL users to be able to access
418 phpMyAdmin, you can use :config:option:`$cfg['Servers'][$i]['AllowDeny']['rules']` to limit them
419 * consider hiding phpMyAdmin behind authentication proxy, so that
420 MySQL credentials are not all users need to login
421 * if you are afraid of automated attacks, enabling Captcha by
422 :config:option:`$cfg['CaptchaLoginPublicKey']` and
423 :config:option:`$cfg['CaptchaLoginPrivateKey']` might be an option.