Installing mod ndb
| mod_ndb |
|
|---|
Contents |
[edit] How to install mod_ndb
Mod_ndb is distributed as source code. It supports several versions of MySQL Cluster (including 5.0 and 5.1) and several versions of the Apache web server (including 1.3, 2.0, and 2.2). It is available for any operating system and platform that supports both MySQL Cluster and Apache. MySQL Cluster (and mod_ndb) do not currently run on Microsoft Windows operating systems.
[edit] Install MySQL
Mod_ndb requires a complete installation of MySQL, including NDB Cluster, and including headers and libraries. (If MySQL was installed from source code or from a tar.gz archive, it is likely to be complete, but if it was installed by an operating system packager or from RPMs, it may be missing some of the required files). The scripts that build mod_ndb rely on the output of the utility mysql_config to find the required headers and libraries. These include
- The MySQL libraries libmystrings and libmysys
- The NDB API client library libndbclient
- Some MySQL header files such as my_global.h
- MySQL Cluster header files like NdbApi.hpp
All of these files should be present somewhere under the path indicated by mysql_config --include
[edit] Install and test a MySQL Cluster
The process of getting a cluster up and running is described in the MySQL manual, for instance in the Multi-Computer How To section.
In the cluster configuration file, you should allocate a few spare [API] nodes before trying to test mod_ndb. At runtime, each Apache process will join the cluster as an API node. You will also need to be able to connect to a MySQL server in the cluster from a mysql command-line client on the machine where you are testing mod_ndb, in order to run the SQL scripts that create the mod_ndb's test and example databases.
[edit] Install Apache 1.3
Mod_ndb supports both Apache 1.3 and Apache 2. Whenever possible, you should run mod_ndb in Apache 2 using a multi-threaded execution model such as the worker MPM. The mod_ndb build scripts rely on Apache's apxs utility to configure the build for your particular installed version of Apache. Unfortunately, you must always have Apache 1.3 installed on a machine to build mod_ndb, even if you are building it for Apache 2. This is due to the known bug that apxs in Apache 2 does not work as documented and is not backwards-compatible with apxs from Apache 1.3.
[edit] Install Apache 2 (optional but recommended)
If you will be running mod_ndb under Apache 2, as recommended, be sure that it is installed as well. In particular, you will want an Apache 2 that includes a threaded MPM, such as the worker MPM.
[edit] Configure the build
Mod_ndb's build system does not directly use GNU autoconf (which should not be required, since autoconf has already been used to build MySQL and Apache for the system), but it does include a small "configure" script similar to the one in an autoconf package.
The configure script takes the following options:
- --mysql=/path/to/mysql_config (required) : indicates the required mysql_config binary
- --apxs=/path/to/apxs (required) : indicates the required apxs binary for Apache 1.3, 2.0, or 2.2.
- --apxs1=/path/to/apache13/apxs : required only when building mod_ndb for Apache 2; indicates the apxs binary from Apache 1.3
- --debug : compile with -g -O0 (otherwise, compile with -O3)
- --thread-safe : usually not needed, but this can be used to resolve a runtime linker error on some platforms where MySQL was built with the --enable-thread-safe-client option. This option will cause mod_ndb to use mysql_config --libs_r rather than mysql_config --libs
- --aprconfig=/path/to/apr-config : also usually not needed, but on a system such as Ubuntu 6 where the APR is installed separately from Apache 2, this option allows mod_ndb to find the APR header files. The is useful whenever mod_ndb fails to compile because it cannot find apr_strings.h.
[edit] Run "make"
If the build completes succesfully, you will have an Apache module object file called mod_ndb.so in the source directory.
[edit] Edit the file "test.conf"
The file test.conf includes a partial Apache configuration. In this file you should
- Uncomment ndb-connectstring and set it to correctly denote the cluster management server.
- If you have PHP available as an Apache module, uncomment the correct LoadModule line for PHP 4 or PHP 5.
[edit] Start the test server
Type "make start". If everything has gone well, Apache and mod_ndb will start running and listen for connections on port 3080. To verify this, look in the Apache error log file, logs/ndb_error_log. You can also stop or restart the server, using "make stop" and "make restart".
[edit] The mod_ndb test suite
Beginning with beta revision 370, mod_ndb includes a test suite in the Tests/ directory, which can be used to test and demonstrate the server. The test suite relies on the "curl" utility for making HTTP requests to the server. If curl is not installed on your system, it can be obtained from http://curl.haxx.se/ . The test suite also uses a "mysql" command-line client to connect to the cluster and run "CREATE TABLE" or "INSERT" commands needed to set up the test cases.
[edit] Files in the test suite
- run-test
- The main utility used for running the test suite.
- httpd.conf
- Apache configuration file for the test suite.
- my.cnf
- MySQL options file. This file must contain whatever options (such as host, port, user, or password) are needed to connect to a mysql server in the cluster.
- test.list
- Plain text file defining the test cases. By convention, every test case has a six-character name, e.g. "ses001"
- results/
- Directory containing canonical, correct results for each test case.
- current/
- Directory containing the most recently recorded results for each test case.
- SQL/
- Directory containing SQL scripts needed for setting up test cases.
... plus various sed and awk scripts used to implement the test suite.
[edit] The run-test command
To run tests, make the Tests direectory your working directory, and use the run-test command. run-test takes as an argument a "group" name of a single test case, a prefix matching multiple cases, or a regular expression. For example:
- run-test ses001: run the test case ses001 and display the results
- run-test ses0: run all test cases beginning with ses0
- run-test ses: run all test cases beginning with ses
- run-test typ[12]: run all test cases beginning with typ1 or typ2
If no group is supplied, run-test runs every test in test.list. run-test also takes the following options:
- -h
- display a help page
- -t
- run test case(s), compare results to the recorded results, and indicate "pass" or "fail"
- -d
- run test case, indicate pass or fail, and display the difference between the current result and the recorded result
- -l
- do not run tests, but list the test cases from test.list that match "group"
- -e
- do not run tests, print the shell commands that would be executed to run them
- -s
- do not run tests, but run SQL scripts to set up the database for testing
- -c
- display the section of httpd.conf defining the HTTP endpoint that is used in the test case
- -R
- run tests and officially record the results in results/. This will refuse to overwrite any existing results files, so you must remove or rename them first.
[edit] Idempotency
For any set of tests in test.list that can be identified by a three- or four- character prefix, it should be possible to run the tests in sequence and obtain the same results each time. In practice, this means that any set of tests that changes the database also cleans up its changes. For an example, see run-test -l ses. Test ses004 inserts a row of data, and test ses006 subsequently deletes that row. Test ses002 updates a row, and ses008 updates it again with the original value. As a whole, the "ses" group leaves the database in the same state that it found it.
[edit] Platform Notes
[edit] Overview
When you successfully build mod_ndb, you link three components: Apache, MySQL, and mod_ndb itself. For this to happen, all three parts need to be built in similar ways. For instance, the NDB API uses C++, and there is no true standard C++ binary format across compilers, so all three components usually have to be built using the same compiler. On platforms that support a variety of compilers, or a variety of object formats, a number of things might go wrong.
[edit] Mac OS X 10.5
Apache 2.2.8 is included in OS X 10.5, but it is built as a "fat" binary:
$ file /usr/sbin/httpd /usr/sbin/httpd: Mach-O universal binary with 4 architectures /usr/sbin/httpd (for architecture ppc7400): Mach-O executable ppc /usr/sbin/httpd (for architecture ppc64): Mach-O 64-bit executable ppc64 /usr/sbin/httpd (for architecture i386): Mach-O executable i386 /usr/sbin/httpd (for architecture x86_64): Mach-O 64-bit executable x86_64
You can only use this built-in apache if MySQL Cluster and mod_ndb are also "fat". I prefer to install a separate apache in /usr/local/apache22.
Configure apache like this:
./configure --prefix=/usr/local/apache22 --with-mpm=worker --enable-mods-shared=most
Then configure mod_ndb like this:
./configure --mysql=/Users/jdd/mysql-builds/6.3.13/bin/mysql_config \
--apxs=/usr/local/apache22/bin/apxs \
--aprconfig=/usr/bin/apr-1-config