source: server/databases/mysql.xml@ cc2e31b6

<?xml version="1.0" encoding="ISO-8859-1"?>
<!DOCTYPE sect1 PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
   "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
  <!ENTITY % general-entities SYSTEM "../../general.ent">
  %general-entities;

  <!ENTITY mysql-download-http "&sources-anduin-http;/m/mysql-&mysql-version;.tar.gz">
  <!ENTITY mysql-download-ftp  "&sources-anduin-ftp;/m/mysql-&mysql-version;.tar.gz">
  <!ENTITY mysql-md5sum        "0841fbc79872c5f467d8c8842f45257a">
  <!ENTITY mysql-size          "24 MB">
  <!ENTITY mysql-buildsize     "930 MB (additional 170 MB to run the test suite)">
  <!ENTITY mysql-time          "4.4 SBU (Test suite is an additional 45 minutes, only partially CPU dependent)">
]>

<sect1 id="mysql" xreflabel="MySQL-&mysql-version;">
  <?dbhtml filename="mysql.html"?>

  <sect1info>
    <othername>$LastChangedBy$</othername>
    <date>$Date$</date>
  </sect1info>

  <title>MySQL-&mysql-version;</title>

  <indexterm zone="mysql">
    <primary sortas="a-MySQL">MySQL</primary>
  </indexterm>

  <sect2 role="package">
    <title>Introduction to MySQL</title>

    <para><application>MySQL</application> is a widely used and fast SQL
    database server. It is a client/server implementation that consists of a
    server daemon and many different client programs and libraries.</para>

    <para>There may be a more recent release available from the
    <application>MySQL</application> home page. You can check
    <ulink url="http://dev.mysql.com/"/> and probably use the
    existing BLFS instructions. Note that versions other than the one shown
    in the download URLs have not been tested in a BLFS environment.</para>

    &lfs71_checked;

    <bridgehead renderas="sect3">Package Information</bridgehead>
    <itemizedlist spacing="compact">
      <listitem>
        <para>Download (HTTP): <ulink url="&mysql-download-http;"/></para>
      </listitem>
      <listitem>
        <para>Download (FTP): <ulink url="&mysql-download-ftp;"/></para>
      </listitem>
      <listitem>
        <para>Download MD5 sum: &mysql-md5sum;</para>
      </listitem>
      <listitem>
        <para>Download size: &mysql-size;</para>
      </listitem>
      <listitem>
        <para>Estimated disk space required: &mysql-buildsize;</para>
      </listitem>
      <listitem>
        <para>Estimated build time: &mysql-time;</para>
      </listitem>
    </itemizedlist>

    <bridgehead renderas="sect3">Additional Downloads</bridgehead>
    <itemizedlist spacing="compact">
      <listitem>
        <para>Optional patch: <ulink
        url="&patch-root;/mysql-&mysql-version;-embedded-library-shared-1.patch"/></para>
      </listitem>
      <listitem>
        <para>Optional Documentation (see tip below):
          <ulink url="http://dev.mysql.com/doc/"/>
        </para>
       </listitem>
    </itemizedlist>

    <note><para>The patch is required only if you plan to install <application>
    Amarok</application>.</para></note>
    
    <bridgehead renderas="sect3">MySQL Dependencies</bridgehead>

    <bridgehead renderas="sect4">Required</bridgehead>
    <para role="optional"><xref linkend="cmake"/></para>

    <bridgehead renderas="sect4">Recommended</bridgehead>
    <para role="optional"><xref linkend="openssl"/></para>

    <bridgehead renderas="sect4">Optional</bridgehead>
    <para role="optional"><xref linkend="tcpwrappers"/> and
    <ulink url="http://packages.debian.org/squeeze/libaio-dev">libaio</ulink></para>

    <para condition="html" role="usernotes">User Notes:
    <ulink url="&blfs-wiki;/mysql"/></para>

  </sect2>

  <sect2 role="installation">
    <title>Installation of MySQL</title>

    <para>For security reasons, running the server as an unprivileged user
    and group is strongly encouraged:</para>

<screen role="root"><userinput>groupadd -g 40 mysql &amp;&amp;
useradd -c "MySQL Server" -d /dev/null -g mysql -s /bin/false -u 40 mysql</userinput></screen>

    <note><para>There are a great many options available to
    <userinput>cmake</userinput>.  Check the output of the `<userinput>cmake .
    -LH</userinput>` for additional customization options.  See the <ulink
    url="http://dev.mysql.com/doc/refman/5.5/en/source-configuration-options.html">MySQL
    Documentation</ulink> for a full listing of all options.</para></note>

 <note><para>If you plan to install <application>Amarok</application>, you need to 
 apply the optional patch, add the cmake option 
 <userinput>-DWITH_EMBEDDED_SERVER=ON</userinput> and add 
 <userinput>Embedded</userinput> to the <userinput>SEGMENTS</userinput> variable 
 below.</para></note>
    
    <para>Apply the optional patch:</para>
    
 <screen><userinput>patch -Np1 -i ../mysql-&mysql-version;-embedded-library-shared-1.patch</userinput></screen>    
    
    <para>Build and install <application>MySQL</application> by
    running the following commands:</para>
    
<screen><userinput> mkdir build &amp;&amp;                                 \
cd    build &amp;&amp;                                 \
cmake ..                                          \
      -DSYSCONFDIR=/etc                           \
      -DMYSQL_DATADIR=/srv/mysql                  \
      -DINSTALL_MYSQLDATADIR=/srv/mysql           \
      -DCMAKE_INSTALL_PREFIX=/usr                 \
      -DINSTALL_BINDIR=bin                        \
      -DINSTALL_SBINDIR=sbin                      \
      -DINSTALL_DOCDIR=share/doc/mysql            \
      -DINSTALL_DOCREADMEDIR=share/doc/mysql      \
      -DINSTALL_INCLUDEDIR=include/mysql          \
      -DINSTALL_INFODIR=share/info                \
      -DINSTALL_LIBDIR=lib                        \
      -DINSTALL_MANDIR=share/man                  \
      -DINSTALL_MYSQLSHAREDIR=share/mysql         \
      -DINSTALL_MYSQLTESTDIR=share/mysql-test     \
      -DINSTALL_PLUGINDIR=lib/plugin              \
      -DINSTALL_SCRIPTDIR=bin                     \
      -DINSTALL_SHAREDIR=share/mysql              \
      -DINSTALL_SQLBENCHDIR=share/mysql-bench     \
      -DINSTALL_SUPPORTFILESDIR=share/mysql/support-files \
      -DWITH_ZLIB=system                          \
      -DWITH_SSL=system                           \
      -DWITH_READLINE=system                      \
      -DMYSQL_UNIX_ADDR=/var/run/mysql/mysql.sock \
      -DWITH_ARCHIVE_STORAGE_ENGINE=1             \
      -DWITH_FEDERATED_STORAGE_ENGINE=1           \
      -DWITH_BLACKHOLE_STORAGE_ENGINE=1           \
      -DMYSQL_MAINTAINER_MODE=OFF                 \
      -DWITH_DEBUG=OFF                            &amp;&amp;

make</userinput></screen>

    <para>To test the results, issue: <command>make test-force 2>&amp;1 | tee
    test.log</command>.  This forces the test to run to completion and logs all
    the test output.  There will be many tests that are not run due to
    configuration options and developer considerations.  Note that if you use
    TCP Wrappers and have a restrictive <filename>/etc/hosts.deny</filename>
    file, you will need to add an appropriate entry to the
    <filename>/etc/hosts.allow</filename> file for the
    <command>mysqld</command> daemon. Otherwise many of the tests will
    fail.  Also, two tests will fail if ipv6 is not available in the kernel
    either as a module or built in.</para>

    <note><para>The ssl tests may fail due to expired certifictes.</para></note>

    <para>Now, as the <systemitem class="username">root</systemitem> user:</para>

<screen role="root"><userinput>SEGMENTS="Client Server IniFiles ManPages SharedLibraries"
SEGMENTS="$SEGMENTS Development Documentation Info Readme"

for segment in $SEGMENTS; do
   cmake -DCMAKE_INSTALL_COMPONENT=$segment -P cmake_install.cmake
done

unset SEGMENTS</userinput></screen>

    <tip>
      <para>The only documentation shipped in the source tarball are
      <filename>mysql.info</filename> and man pages. You can download various
      formats of the <application>MySQL</application> Reference Manual
      from <ulink url="http://dev.mysql.com/doc/"/>.</para>
    </tip>

    <note><para>If you only want to build and install the 
      <command>mysql</command> client, use:</para>

      <screen><userinput>cmake . &amp;&amp;
make mysqlclient libmysql</userinput></screen>

      <para>Continue as root:</para>

      <screen role="root"><userinput>make install</userinput></screen>
    </note>

  </sect2>

  <sect2 role="commands">
    <title>Command Explanations</title>

    <para><command>cmake -DCMAKE_INSTALL_COMPONENT=$segment ...</command>: This
    command installs the appropriate portion of the package.  Different
    segemnts may be added or deleted as desired.  Valid segments are listed
    with `<command>make list_install_components</command>`.  Note that the
    'DataFiles' install segment does not honor the -DMYSQL_DATADIR or
    -DINSTALL_MYSQLDATADIR statements.</para>

  </sect2>

  <sect2 role="configuration">
    <title>Configuring MySQL</title>

    <sect3 id="mysql-config">
      <title>Config Files</title>

      <para><filename>/etc/my.cnf</filename> and
      <filename>~/.my.cnf</filename></para>

      <indexterm zone="mysql mysql-config">
        <primary sortas="e-AA.my.cnf">~/.my.cnf</primary>
      </indexterm>

      <indexterm zone="mysql mysql-config">
        <primary sortas="e-etc-my.cnf">/etc/my.cnf</primary>
      </indexterm>

    </sect3>

    <sect3>
      <title>Configuration Information</title>

      <para>There are several default configuration files available in
      <filename class="directory">/usr/share/mysql</filename> which you can
      use. When creating the file, ensure binary logs are disabled unless you
      are doing database replication.  Create <filename>/etc/my.cnf</filename>
      using the following commands as the <systemitem
      class="username">root</systemitem> user:</para>

<screen role="root"><userinput>install -v -m644 /usr/share/mysql/support-files/my-medium.cnf /etc/my.cnf
sed -i 's/^log-bin/#log-bin/' /etc/my.cnf</userinput></screen>

      <para>You can now install a database and change the ownership to the
      unprivileged user and group (perform as the <systemitem
      class="username">root</systemitem> user):</para>

<screen role="root"><userinput>mysql_install_db --basedir=/usr --datadir=/srv/mysql --user=mysql &amp;&amp;
chgrp -v mysql /srv/mysql{,/test,/mysql}</userinput></screen>

      <para>Further configuration requires that the
      <application>MySQL</application> server is running. Start
      the server using the following commands as the <systemitem
      class="username">root</systemitem> user:</para>

<screen role="root"><userinput>install -v -m755 -o mysql -g mysql -d /var/run/mysql &amp;&amp;
mysqld_safe --user=mysql 2&gt;&amp;1 &gt;/dev/null &amp;</userinput></screen>

      <para>A default installation does not set up a password for the
      administrator, so use the following command as the <systemitem
      class="username">root</systemitem> user to set one. Replace
      <replaceable>&lt;new-password&gt;</replaceable> with your own.</para>

<screen role="root"><userinput>mysqladmin -u root password <replaceable>&lt;new-password&gt;</replaceable></userinput></screen>

      <para>Configuration of the server is now finished. Shut the server
      down using the following command as the <systemitem
      class="username">root</systemitem> user:</para>

<screen role="root"><userinput>mysqladmin -p shutdown</userinput></screen>

    </sect3>

    <sect3  id="mysql-init">
      <title>Boot Script</title>

      <para>Install the <filename>/etc/rc.d/init.d/mysql</filename> init script
      included in the <xref linkend="bootscripts"/> package as
      the <systemitem class="username">root</systemitem> user to start the
      <application>MySQL</application> server during system boot-up.</para>

      <indexterm zone="mysql mysql-init">
        <primary sortas="f-mysql">mysql</primary>
      </indexterm>

<screen role="root"><userinput>make install-mysql</userinput></screen>

    </sect3>

  </sect2>

  <sect2 role="content">
    <title>Contents</title>

    <segmentedlist>
      <segtitle>Installed Programs</segtitle>
      <segtitle>Installed Libraries</segtitle>
      <segtitle>Installed Directories</segtitle>

      <seglistitem>
        <seg>comp_err, innochecksum, msql2mysql, my_print_defaults,
        myisam_ftdump, myisamchk, myisamlog, myisampack, mysql,
        mysql_client_test, mysql_config, mysql_convert_table_format,
        mysql_create_system_tables, mysql_explain_log, mysql_find_rows,
        mysql_fix_extensions, mysql_fix_privilege_tables, mysql_install_db,
        mysql_secure_installation, mysql_setpermission, mysql_tableinfo,
        mysql_tzinfo_to_sql, mysql_waitpid, mysql_zap, mysqlaccess, mysqladmin,
        mysqlbinlog, mysqlbug, mysqlcheck, mysqld, mysqld_multi, mysqld_safe,
        mysqldump, mysqldumpslow, mysqlhotcopy, mysqlimport, mysqlmanager,
        mysqlshow, mysqltest, mysqltestmanager, mysqltestmanager-pwgen,
        mysqltestmanagerc, perror, replace, resolve_stack_dump, and
        resolveip</seg>
        <seg>libdbug.a, libheap.a, libmyisam.a, libmyisammrg.a,
        libmysqlclient.{so,a}, libmysqlclient_r.{so,a}, libmystrings.a,
        libmysys.a, and libvio.a</seg>
        <seg>/srv/mysql, /usr/include/mysql, /usr/lib/plugin, /usr/share/mysql and
        /var/run/mysql</seg>
      </seglistitem>
    </segmentedlist>

    <bridgehead renderas="sect3">Short Descriptions</bridgehead>

    <para>Descriptions of all the programs and libraries would be several
    pages long. Instead, consult the <filename>mysql.info</filename>
    documentation or the on-line reference manual at <ulink
    url="http://dev.mysql.com/doc/refman/5.1/en/index.html"/>.</para>

    <para>The <application>Perl</application> DBI modules must be installed
    for some of the <application>MySQL</application> support programs to
    function properly.</para>

  </sect2>

</sect1>