Installing MySQL on UNIX
Distributions are available for several versions of MySQL. The current stable releases have version numbers in the 3.22 series. The current development releases are in the 3.23 series. Generally, you should use the highest-numbered version in the series you want to use that is available in the distribution format you want to work with.
MySQL distributions come in binary, RPM, and source format. Binary and RPM distributions are easier to install, but you must accept the installation layout and configuration defaults that are built into the distribution. Source distributions are more difficult to install because you must compile the software, but you also get more control over configuration parameters. For example, you can compile the distribution for client support only without building the server, and you can change the location where you want to install the software.
The distributions contain one or more of the following components:
The mysqld server
Client programs (mysql, mysqladmin, and so forth), and client programming support (libraries and header files)
Documentation
The benchmark database
Language support
Source and binary distributions contain all of these items. Each RPM file contains only some of them, so you may need to install multiple RPMs to get everything you need.
If you plan to connect to a server that's already running on another machine, you don't need to install a server. But you should always install client software:
If you don't run a server, you'll need the clients so that you can connect to a server on another machine.
If you do run a server, you'll want to be able to connect to it from the server host, not be forced to log in on another machine that has the client software just to test your server.
Overview of MySQL Installation
Installing MySQL on UNIX involves the following steps:
Create a UNIX account for the user and group that the server will run as (if you are installing the server).
Obtain and unpack any distributions you want to install. If you are using a source distribution, compile it and install it.
Run the mysql_install_db script to initialize the data directory and grant tables (first-time installation only).
Start the server.
Read Chapter 11, "General MySQL Administration," to become familiar with general administrative procedures. In particular, you should read the sections on server startup and shutdown and on running the server as an unprivileged user.
Creating an Account for the MySQL User
You can skip this section if you're running MySQL client software only and are not going to run a MySQL server.
The MySQL server can be run as any UNIX user on your system, but for security and administrative reasons, it's best that you not run the server as root. I recommend that you create a separate account to use for MySQL administration and that you run the server as that user. That way, you can log in as that user and have full privileges in the data directory for performing maintenance and troubleshooting. Procedures for creating user accounts vary from system to system. Consult your local documentation for specific details.
This book uses mysqladm and mysqlgrp for the UNIX user and group names of this account. If you plan to install MySQL only for your own use, you can run it as yourself, in which case you'll use your own login and group names wherever you see mysqladm and mysqlgrp in this book. If you are installing from RPM files, a user named mysql is created automatically as part of the RPM installation procedure. In that case, you will want to substitute mysql for mysqladm.
Advantages of using a separate, unprivileged account rather than root for running MySQL are:
If you do not run MySQL as root, no one can exploit the server as a security hole to gain root access.
It's safer to perform MySQL administrative tasks as an unprivileged user than as root.
The server will create files owned by mysqladm rather than by root. The fewer root-owned files on your system, the better.
It's cleaner conceptually to separate MySQL activity into its own account, and it's easier to see what things on your system are MySQL related. For example, in the directory where cron files are kept, you'll have a separate file for the MySQL user, mysqladm. Otherwise, the MySQL cron jobs would be in root's file, along with everything else done as root on a periodic basis.
Obtaining and Installing the MySQL Distribution
In the following instructions, I use version to stand for the version number of the MySQL distribution you're working with and platform to stand for the name of the platform on which you're installing it. These are used in distribution filenames so that distributions can be identified easily and distinguished one from another. A version number is something like 3.22.26 or 3.23.4-alpha. A platform name is something like sgi-irix6.3-mips or dec-osf4.0b-alpha.
Installing a Binary Distribution
Binary distribution files have names such as mysql-version-platform.tar.gz. Obtain the distribution file for the version and platform you want and put it in the directory under which you want to install MySQL—for example, /usr/local.
Unpack the distribution using one of the following commands (use the second command if your version of tar doesn't understand the z option for uncompressing the distribution):
% tar zxf mysql-version-platform.tar.gz % gunzip < mysql-version-platform.tar.gz | tar xf -
Unpacking the distribution creates a directory, mysql-version-platform, containing the contents of the distribution. To make it easier to refer to this directory, create a symbolic link:
% ln -s mysql-version-platform mysql
Now you can refer to the installation directory as /usr/local/mysql if you installed MySQL under /usr/local.
If you are going to use only the client support provided by the distribution and are not running a server, you're done installing MySQL. If you are installing MySQL for the first time, however, go to the section "Initializing the Data Directory and Grant Tables." If you are updating an existing installation, go to the section "Starting the Server."
Installing an RPM Distribution
RPM files are available for installing MySQL on Linux systems. These have filenames like the following:
MySQL-version-platform.rpm
The server software.
MySQL-client.version-platform.rpm
The client programs.
MySQL-devel.version-platform.rpm
Development support (client libraries and header files) for writing client programs. You'll need this if you want to use or write Perl DBI scripts for accessing MySQL databases.
MySQL-bench.version-platform.rpm
Benchmarks and tests. These require Perl and the Msql-Mysql-modules module. You can get an RPM for Msql-Mysql-modules at http://www.mysql.com.
MySQL-version.src.rpm
The source for the server, clients, benchmarks, and tests.
You don't need to be in any particular directory when you install from an RPM because RPM files include information indicating where the files they contain should be installed. For any RPM file rpm_file, you can find out where its contents will be installed with the following command:
% rpm -qpl rpm_file
To install an RPM file, use this command:
% rpm -i rpm_file
Various parts of MySQL are divided into different RPM files, so you may need to install more than one RPM. To install client support, use this command:
% rpm -i MySQL-client-version-platform.rpm
For server support, use this command:
% rpm -i MySQL-version-platform.rpm
If you plan to write your own programs using the client programming support make sure to install the development RPM file:
% rpm -i MySQL-devel-version-platform.rpm
If you plan to use only the client support provided by the distribution and are not running a server, you're done installing MySQL. If you are installing MySQL for the first time, however, go to the section "Initializing the Data Directory and Grant Tables." If you are updating an existing installation, go to the section "Starting the Server."
If you want to install from the source RPM file, the following command should be sufficient:
% rpm --recompile MySQL-version.src.rpm
Installing a Source Distribution
Source distributions have names such as mysql-version.tar.gz, where version is the MySQL version number. Pick the directory under which you want to unpack the distribution and move into it. Obtain the distribution file and unpack it using one of the following commands (use the second command if your version of tar doesn't understand the z option for uncompressing the distribution):
% tar zxf mysql-version.tar.gz % gunzip < mysql-version.tar.gz | tar xf -
Unpacking the distribution creates a directory mysql-version containing the contents of the distribution. Move into this directory:
% cd mysql-version
Now you need to configure and compile the distribution before you can install it. If these steps fail, check the chapter "Installing MySQL" in the MySQL Reference Manual, particularly any system-specific notes it may contain about your type of machine.
Use the configure command to configure the distribution:
% ./configure
You may want to specify options for configure. To obtain a list of available options, run this command:
% ./configure --help
The following list shows some configuration options many people find helpful:
--without-server
Configure for building client support only (client programs or client libraries). You might do this if you're planning to access a server that's already running on another machine.
--prefix=path_name
By default, the installation root directory is /usr/local. The data directory, clients, the server, client libraries, and header files are installed in the var, bin, libexec, lib, and include directories under this directory. If you want to change the installation root, use the --prefix option.
--localstatedir=path_name
This option changes the location of the data directory. You can use this if you don't want to keep your databases under /usr/local/var.
--with-low-memory
The sql/sql_yacc.cc source file requires a lot of memory to compile, which sometimes causes the build to blow up. Symptoms of this problem include error messages about "fatal signal 11" or exhaustion of virtual memory. The --with-low-memory option causes the compiler to be invoked with options that result in lower memory use.
After you run configure, compile the distribution and then install it:
% make % make install
You may need to be root to run the install command if you haven't used the --prefix option to specify an installation directory in which you have write permission.
If you are going to use only the client support provided by the distribution and are not running a server, you're done installing MySQL. If you are installing MySQL for the first time, however, go to the next section. If you are updating an existing installation, go to the section "Starting the Server."
Initializing the Data Directory and Grant Tables
Before you can use your MySQL installation, you need to initialize the mysql database that contains the grant tables controlling network access to your server. This step is needed only for a new installation and only if you will run a server. Those performing client-only installations can skip it. For a binary distribution, run the commands from the installation directory (the parent of the bin directory created by the distribution). For a source distribution, run the commands from the top-level directory of the distribution.
DATADIR is the pathname to your data directory. Normally, you run the following commands as root. If you're logged in as mysqladm or you're installed MySQL under your own account because you intend to run it for yourself, you can run the commands without being root and can skip the chown and chmod commands.
Set up the default grant tables by running the mysql_install_db script:[1]
[1] You need not do this if you are installing from RPM files because mysql_install_db will be run for you automatically.
# scripts/mysql_install_db
If mysql_install_db fails, consult the chapter "Installing MySQL" in the MySQL Reference Manual to see if it says anything about the problem you're encountering, and then try again. Note that if mysql_install_db doesn't run to completion successfully, any grant tables it creates are likely incomplete. You should remove them because mysql_install_db may not try to re-create any tables that it finds already existing. You can remove the entire mysql database like this:
# rm -rf DATADIR/mysql
After running mysql_install_db, shut down the server if you are installing a version of MySQL older than 3.22.10 (with newer versions, mysql_install_db does this automatically):
# bin/mysqladmin --user=root shutdown
With the server down, change the user and group ownership and mode of all files under the data directory:
# chown -R mysqladm.mysqlgrp DATADIR # chmod -R go-rwx DATADIR
The chown command changes the ownership to the MySQL user, and the chmod changes the mode to keep everybody out of the data directory except mysqladm.
Starting the Server
This step is needed only if you will run a server. Those performing client-only installations can skip it. Run the commands in this section from the same directory indicated in the previous section. Normally, you run the commands as root. If you're logged in as mysqladm or you're installed MySQL under your own account, you can run the commands without being root and should omit the --user option.
Use the following command to start the server:
# bin/safe_mysqld --user=mysqladm &
The --user option tells the server to run as mysqladm. If you want to enable logging, use this command instead:
# bin/safe_mysqld --user=mysqladm --log &
The default installation allows the MySQL root user to connect without a password. It's a good idea to establish a password. You should also arrange for the server to start up and shut down when your system starts up and shuts down. In addition, it's recommended that you enable update logging because that can be useful for data recovery procedures. For instructions on performing any of these actions, see Chapter 11.
Installing Perl DBI Support
Install the DBI software if you want to write Perl scripts that access MySQL databases. DBI requires that you've installed MySQL client programming support because it uses the MySQL C client library. You can also install the CGI.pm module if you want to write Web-based DBI scripts. The DBI software requires a reasonably recent version of Perl (5.004 or later). If you don't have Perl installed, visit http://www.perl.com/, download a Perl distribution, and install it before you install DBI support.
DBI support requires three modules, which you can install from source or from RPM files:
Data-Dumper. A module for processing Perl data structures conveniently.
Msql-Mysql-modules. The MySQL-specific driver used by DBI when you connect to a MySQL server.
If you install from source, install the modules in the order shown in the preceding list. Otherwise, the test step of the following installation instructions won't work.
Installation for all three modules is similar. When you install from source, you unpack a distribution file using one of the following commands (use the second command if your version of tar doesn't understand the z option for uncompressing the distribution):
% tar zxf dist_file.tar.gz % gunzip < dist_file.tar.gz | tar xf -
Then move into the distribution directory created by the tar command and run these commands (you may need to be root to run the installation step):
% perl Makefile.PL % make % make test % make install
If you run the preceding commands for the Msql-Mysql-modules distribution, the perl command will ask you some questions when you generate the Makefile:
Which drivers do you want to install? There are choices for various combinations of MySQL and mSQL. Unless you also run mSQL, select MySQL to keep things simple.
Do you want to install the MysqlPerl emulation? MysqlPerl is the old Perl interface for MySQL. It is obsolete. Answer no to this unless you have old MysqlPerl scripts and want to enable emulation support for them in the DBI module.
Where is your MySQL installed? This should be the grandparent of the directory containing your MySQL header files, probably /usr/local or /usr/local/mysql unless you installed MySQL in a non-standard location.
Which database should I use for testing the MySQL drivers? The default is test, which should be okay, unless you've turned off anonymous access to it. In that case, you'll need to give a database name to which you have access and then specify a valid MySQL username and password for the next couple of questions.
On which host is the database running? localhost should be sufficient if you're running a local server. If not, name a host that is running a server to which you have access. The MySQL server must be running on this host when you run the make test command or the tests will fail.
User name for connecting to the database? Password for connecting to the database? The name and password to use for connecting to the MySQL server for testing. The default is undef for both questions. This causes the driver to connect as the anonymous user. Specify non-blank values if you need to connect non-anonymously.
If you have problems installing the Perl modules, consult the README file for the relevant distribution as well as the mail archives for the DBI mailing list because the answers for most installation problems can be found there.
If you want to use CGI.pm, it may already be present in your Perl installation. Try running the command perldoc CGI. If it displays CGI documentation, CGI is installed. Otherwise, obtain the distribution and unpack and install it using the same instructions as for the other Perl modules.
If you want to install the mod_perl Apache module for use with Web-based DBI scripts, visit the mod_perl area of the Apache Web site at the following location for more information:
Installing PHP and Apache
The following instructions should get you going. If you encounter problems, check the "VERBOSE INSTALL" section of the INSTALL file included with the PHP distribution. (It's not a bad idea to read that file anyway. It contains lots of useful information.)
These instructions assume you have an Apache source distribution available and that you'll run PHP as an Apache module. They also assume that you have Apache 1.3.9 and PHP 3.0.12 and that you are in a directory under which the apache_1.3.9 and php-3.0.12 directories containing the source distributions are located. If you have different versions or locations, substitute your actual version numbers and pathnames when you use the following instructions.
To configure and build PHP, begin by running the following commands (the procedure looks a little strange because you begin with the Apache distribution, but that's correct):
% cd apache_1.3.9 % ./configure
The configure command for Apache is necessary because some of the header files that PHP needs are generated at configuration time. If you don't run configure in the Apache distribution, the PHP configuration process won't be able to find the files. After configuring Apache, move into the PHP distribution directory, configure PHP, build it, and install it. You can also install a copy of the PHP initialization file:
% cd ../php-3.0.12 % ./configure --with-mysql --with-apache=../apache_1.3.9 --enable-track-vars % make % make install % cp php3.ini-dist /usr/local/lib/php3.ini
The configure command for PHP tells it that you want MySQL support and indicates where the Apache source tree is located. The --enable-track-vars option turns on automatic conversion of form input into variables that you can access easily from within your PHP pages. The make commands compile and install PHP. You might need to be root to install the initialization file php3.ini.
When you build PHP as a module, "installing" it simply copies the module into the Apache source tree so that it can be linked into the Apache binary. After that is done you can compile and install Apache:
% cd ../apache_1.3.9 % ./configure --activate-module=src/modules/php3/libphp3.a % make % make install
These steps reconfigure Apache so that it knows about the PHP module file and then build and install it. You should edit your Apache configuration file httpd.conf so that Apache recognizes PHP scripts. PHP recognition is based on the filename extension that you use for PHP scripts. For example, if you want Apache to recognize both .php and .php3, include the following lines in the configuration file:
AddType application/x-httpd-php3 .php AddType application/x-httpd-php3 .php3
The suffixes to use depend on how you plan to name your PHP scripts. .php and .php3 are probably the most common. Another common extension is .phtml. You can simply enable them all if you want. This may be best anyway if you're going to be installing pages that you obtain from other people that use one or another of these extensions.
You can also tell Apache to recognize index.php or index.php3 as the default file for a directory when no filename is specified at the end of a URL. You'll probably find a line in the configuration file that looks like this:
DirectoryIndex index.html
Change it to this:
DirectoryIndex index.html index.php index.php3
After editing the Apache configuration file, bring down the httpd server if one was already running, and then start the new httpd that you just installed. On many systems, the following commands (executed as root) accomplish this:
# /usr/local/apache/bin/apachectl stop # /usr/local/apache/bin/apachectl start
You should also set up Apache to start up and shut down at system startup and shutdown time. See the Apache documentation for instructions. Normally, this involves running apachectl start at boot time and apachectl stop at shutdown time.