Chapter 2 MySQL Cluster Manager Installation, Configuration, Cluster Setup

Install the MySQL Cluster Manager agent on Linux and similar platforms by following the instructions below.

Extract the MySQL Cluster Manager 1.3.6 program and other files from the distribution archive.  You must install a copy of MySQL Cluster Manager on each computer that you intend to use as a MySQL Cluster host. In other words, you need to install MySQL Cluster Manager on each host that is a member of a MySQL Cluster Manager management site. For each host, you should use the MySQL Cluster Manager build that matches that computer's operating system and processor architecture.

On Linux systems, you can unpack the archive using the following command, using mcm-1.3.6-cluster-7.4.6-linux-sles11-x86-64bit.tar.gz as an example (the actual filename will vary according to the MySQL Cluster Manager build that you intend to deploy):

shell> tar -zxvf mcm-1.3.6-cluster-7.4.6-linux-sles11-x86-64bit.tar.gz

This command unpacks the archive into a directory having the same name as the archive, less the .tar.gz extension. The top-level directory within the archive is named mcm-1.3.6.

In general, the location where you place the unpacked MySQL Cluster Manager directory and the name of this directory can be arbitrary. However, we recommend that you use a standard location for optional software, such as /opt on Linux systems, and that you name the directory using the 1.3.6 version number. (This facilitates subsequent upgrades.) On a typical Linux system you can accomplish this task like this:

shell> cd mcm-1.3.6-cluster-7.4.6-linux-sles11-x86-64bit
shell> mv mcm-1.3.6 /opt/mcm-1.3.6

For ease of use, we recommend that you put the MySQL Cluster Manager files in the same directory on each host where you intend to run it.

Contents of the MySQL Cluster Manager Unix Distribution Archive.  If you change to the directory where you placed the extracted MySQL Cluster Manager archive and list the contents, you should see something similar to what is shown here:

shell> cd /opt/mcm-1.3.6
shell> ls
bin  cluster  etc  lib  libexec  licenses  share  var

These directories are described in the following table:

Normally, the only directories of those shown in the preceding table that you need be concerned with are the bin and etc directories.

For MySQL Cluster Manager 1.3.6 distributions that include MySQL Cluster, the complete MySQL Cluster NDB 7.4.6 binary distribution is included in the cluster directory. Within this directory, the layout of the MySQL Cluster distribution is the same as that of the standalone MySQL Cluster binary distribution. For example, MySQL Cluster binary programs such as ndb_mgmd, ndbd, ndbmtd, and ndb_mgm can be found in cluster/bin. For more information, see MySQL Installation Layout for Generic Unix/Linux Binary Package, and Installing an NDB Cluster Binary Release on Linux, in the MySQL Manual.

If you wish to use the included MySQL Cluster software, it is recommended that you move the cluster directory and all its contents to a location outside the MySQL Cluster Manager installation directory, such as /opt/ndb-version. For example, on a Linux system, you can move the MySQL Cluster NDB 7.4.6 software that is bundled with MySQL Cluster Manager 1.3.6 to a suitable location by first navigating to the MySQL Cluster Manager installation directory and then using a shell command similar to what is shown here:

shell> mv cluster /opt/ndb-7.4.6

shell> ln -s /opt/ndb-7.4.6 cluster

After doing this, you can use the mcm client commands add package and upgrade cluster to upgrade any desired cluster or clusters to the new MySQL Cluster software version.

The MySQL Cluster Manager agent by default writes its log file as mcmd.log in the installation directory. When the agent runs for the first time, it creates a directory where the agent stores its own configuration data; by default, this is /opt/mcm_data. The configuration data, log files, and data node file systems for a given MySQL Cluster under MySQL Cluster Manager control, and named cluster_name, can be found in clusters/cluster_name under this data directory (sometimes also known as the MySQL Cluster Manager data repository).

The location of the MySQL Cluster Manager agent configuration file, log file, and data directory can be controlled with mcmd start-up options or by making changes in the agent configuration file. To simplify upgrades of MySQL Cluster Manager, we recommend that you change the data repository to a directory outside the MySQL Cluster Manager installation directory, such as /var/opt/mcm. See Section 2.4, “MySQL Cluster Manager Configuration File”, and Section 3.2, “Starting and Stopping the MySQL Cluster Manager Agent”, for more information.

On Linux and other Unix-like systems, you can set up the MySQL Cluster Manager agent to run as a daemon, using the unit script that is supplied with the MySQL Cluster Manager distribution. To do this, follow the steps listed here:

The MySQL Cluster Manager agent should now be started automatically whenever the system is restarted.

When the agent is configured as a daemon, cluster processes are started automatically when the agent is restarted, as long as the cluster was running when the agent shut down. Note that StopOnError must be disabled (set to 0) for all data nodes in order for this to work. If the cluster was stopped when the agent shut down, it is necessary to supply a script which waits for the agent to complete its startup and recovery phases, and then, when the agent is ready, starts the cluster using a command such as mcmdir/bin/mcm -e 'start cluster --background cluster_name;'.

To install MySQL Cluster Manager 1.3.6 on Windows platforms, you should first have downloaded the MSI installer file mcm-1.3.6-cluster-7.4.6-win32-x86.msi (see Section 2.1, “Obtaining MySQL Cluster Manager”). 1.3.6 for Windows is 32-bit, as is the bundled MySQL Cluster NDB 7.4.6; these run on both 32-bit and 64-bit versions of Windows.

As mentioned elsewhere (see, for example, Section 3.4.1, “Creating a MySQL Cluster with MySQL Cluster Manager”), you must install a copy of MySQL Cluster Manager on each computer where you intend to host a MySQL Cluster node. Therefore, the following procedure must be performed separately on each host computer. For ease of installations and upgrades on multiple machines, it is recommended that you install MySQL Cluster Manager to the same location on each host. This is C:\Program Files\MySQL\MySQL Cluster Manager 1.3.6\ or C:\Program Files (x86)\MySQL\MySQL Cluster Manager 1.3.6\ by default, but it is possible to install MySQL Cluster Manager to an alternate location such as C:\mcm\.

In the discussion that follows, we assume that you have downloaded the MySQL Cluster Manager 1.2.1 MSI installer as user jon to this user's Downloads directory (C:\Users\jon\Downloads\MCM) on a 64-bit Windows system. Navigate to this directory in Windows Explorer, as shown here:

To run the installer, double-click on the file icon in Windows Explorer. Some versions of Windows also provide an Install item in the Windows Explorer menu that can be used to run the installer. When you start the installer, you may see a Windows Security Warning screen. If you obtained the installer from a trusted source and know that it has not been tampered with, choose Run from the dialog, which allows the installer to continue to the Welcome screen, as shown here:

Click the Next button to continue to the License Agreement screen, as shown in the next figure:

You should read the license text in the text area, and when you have done so, check the box labelled I accept the terms in the License Agreement. Until you have checked the box, you cannot complete the MySQL Cluster Manager installation; it is possible only to go back to the previous screen, print the license, or cancel the installation (using the buttons labelled Back, Print, and Cancel, respectively). Checking the box enables the Next button, as shown here:

Click the Next button to continue to the Destination Folder screen, where you can choose the installation directory. The next figure shows the Destination Folder screen with the default location. On English-language 32-bit Windows systems, this is C:\Program Files\MySQL\MySQL Cluster Manager version\); on English 64-bit Windows systems, the default is C:\Program Files (x86)\MySQL\MySQL Cluster Manager version\. (In this example, we are installing MySQL Cluster Manager 1.2.1 on a 64-bit system, so the default is C:\Program Files (x86)\MySQL\MySQL Cluster Manager 1.2.1\.) You can click the Change button to change the directory where MySQL Cluster Manager should be installed; the default directory is adequate for most cases.

Once you have selected the destination directory, the installer has gathered all the information that it requires to perform the installation. Click Next to continue to the Ready screen, shown here:

Click the Install button to install MySQL Cluster Manager. As the installer begins to copy files and perform other tasks affecting the system, you may see a warning dialog from Windows User Access Control, as shown here:

If this occurs, click the Yes button to allow the installation to continue. A Setup Wizard screen with a progress bar is displayed while the installer runs, as shown in the next figure:

The Setup Wizard may require several minutes to copy all of the necessary files for MySQL Cluster Manager 1.3.6 and MySQL Cluster NDB 7.4.6 to the installation directory and to perform other required changes.

When the Setup Wizard finishes, the installer displays the Installation Completed screen, as shown here:

MySQL Cluster Manager 1.3.6 has now been installed to the destination directory; click the Finish button to exit the installer.

2.3.2.1 Installing the MySQL Cluster Manager Agent as a Windows Service

After installing the MySQL Cluster Manager Agent as a Windows service, you can start and stop the agent using the Windows Service Manager. The installation also configures the agent to start automatically whenever Windows starts, and to shut down safely whenever Windows shuts down.

Note

The Windows service can be used to control the running of MySQL Cluster Manager agents on a single host only. To shut down agents on multiple hosts, you can use the stop agents command in the MySQL Cluster Manager client.

The installation is performed using the command prompt (cmd.exe); as with installing or removing any Windows service, it must also be done as a user having sufficient permissions, such the system Administrator account.

If the account you are currently using has Administrator privileges, you can simply start cmd.exe. Otherwise, you must run the command prompt program as the Administrator. To do this, first locate a shortcut to the command prompt. On most Windows systems, you can do this using the Start Menu. Find Programs (or All Programs, in some Windows versions), then navigate to Accessories. Under Accessories, right-click on the Command Prompt menu item. From the context menu that appears, select Run as Administrator. You can see how this looks on a typical Windows system in the next figure.

If a Windows UAC dialog referring to cmd.exe appears, click Yes to allow the command prompt to run as Administrator and thus to continue. You should now have a command prompt window open on your desktop, running a session with Administrator privileges.

To install the MySQL Cluster Manager agent as a service, we use the SC CREATE command. This command allows us to specify a name for the service (for use in NET START and NET STOP commands), a display name (to be shown in the Service Manager), a startup mode (automatic or manual start), and a path to the executable to be run as a service. (Use mcmd-svc.exe rather than mcmd.exe as the executable.) The path must also include any arguments needed by the program; in the case of MySQL Cluster Manager, mcmd-svc.exe must be told where to find its configuration file using the --defaults-file option. Both of these paths must be absolute.

Important

Installation of the MySQL Cluster Manager agent as a service is recommended. However, you should not install MySQL Cluster processes (ndb_mgmd.exe, ndbd.exe, ndbmtd.exe, mysqld.exe) as services on Windows hosts to be used as MySQL Cluster nodes under management by MySQL Cluster Manager, since the MySQL Cluster Manager agent itself controls MySQL Cluster nodes independently of the Windows Service Manager.

Assume that you have installed MySQL Cluster Manager to the default location for 64-bit Windows systems C:\Program Files (x86)\MySQL\MySQL Cluster Manager 1.3.6\ (C:\Program Files\MySQL\MySQL Cluster Manager 1.3.6\ on 32-bit Windows systems), and that its configuration file is located in C:\Program Files (x86)\MySQL\MySQL Cluster Manager 1.3.6\etc. Then the following command installs MySQL Cluster Manager as a service named mcm, with the display name “MySQL Cluster Manager 1.3.6”:

C:\> SC CREATE
  "MCM" DisplayName= "MySQL Cluster Manager 1.3.6" Start= "auto"
  BinPath= "C:\Program Files (x86)\MySQL\MySQL Cluster Manager 1.3.6\bin\mcmd-svc.exe
  --defaults-file=\"C:\Program Files (x86)\MySQL\MySQL Cluster Manager 1.3.6\etc\mcmd.ini\""
[SC] CreateService SUCCESS
C:\>

This command can be quite long. For enhanced legibility, we have broken it across several lines, but you should always enter it on a single line, allowing it to wrap naturally, similar to what is shown here:

In addition, you should keep in mind that the spaces after the equals signs following the DisplayName, Start, and BinPath arguments are required.

Starting and stopping the MySQL Cluster Manager agent Windows service.  After installing the service successfully, you can start and stop the service manually, if the need arises, with the NET START and NET STOP commands, as shown here:

Once the service is installed, the MySQL Cluster Manager agent starts automatically whenever Windows is started. You can verify that the service is running with the Windows Task Manager. Open the Task Manager, and switch to the Services tab if it is not already displayed. If the MySQL Cluster Manager agent is running, you can find it in the list of services under MCM in the Name, column and MySQL Cluster Manager 1.3.6 in the Description column, as shown here:

You can also verify if the service is running using the Windows Service Manager, as shown here:

The Service Manager also allows you to start, stop, or pause the MySQL Cluster Manager agent service manually using a GUI.

Note

When first installing the MySQL Cluster Manager agent as a service, the service is not started automatically until Windows is started. If you do not wish to restart Windows, then you must start the service manually using either NET START on the command line or the graphical control provided in the Windows Service Manager.

You can remove the service using the SC DELETE command and the name of the service—in this case MCM—that was used in the SC CREATE command, as shown here:

If the service is running at the time that SC DELETE is executed, the removal of the service takes effect the next time the service is stopped. In such a case, you must stop the previous instance of the service manually, and allow it to be removed, before you can reinstall the service.

Once you have installed the MySQL Cluster Manager agent and the service is running correctly, you are ready to connect to it using the MySQL Cluster Manager client. See Section 3.3, “Starting the MySQL Cluster Manager Client”, for information about how to do this.

Normally it is not necessary to alter the user name or password used by the user agent to administer mysqld processes. However, if you should wish to do so, you can change either or both of these, using the procedure outlined here: