MySQL Cluster Configuration User Guide

## Introduction

This is the user guide for the MySQL Cluster configuration tool. You can read the user guide sequentially, or you can get help regarding the wizard page you are currently at by choosing the proper entry in the Help menu. This user guide is divided into the following main parts:

- Installing and Starting will describe what the system requirements are for running the configuration tool. How to install and start it will also be explained.
- The Wizard Overview will provide a high level description of the main parts of the system and how they interact. How to use the configuration tool in terms of navigation, settings, etc. will also be covered.
- In Wizard Pages, the individual pages of the wizard will be examined. The various input widgets will be explained in detail.

### Tool Name

The configuration tool is a part of the MySQL Cluster Software, and hence, it does not have a particular name. In this user guide, we refer to the installer, configurator, configuration tool, configuration wizard or simply wizard.

## Installing and Starting

The configuration tool is installed together with the MySQL Cluster software. Please refer to the regarding installation. This section describes the requirements to the environment of the tool, important information about security, and explains how to start the wizard.

### Installation Layout

The configuration tool may end up in various locations depending on the context (note that the default paths may be overridden at install time for some package formats).

### Wizard Options

The wizard supports the following command line options:

- -h, --help show this help message and exit
- -N SERVER_NAME, --server_name=SERVER_NAME server name: [default: localhost]
- -p PORT, --port=PORT port for the web server: [default: 8081]
- -n, --no-browser do not open the server's start page in a browser
- -s BROWSER_START_PAGE, --browser-start-page=BROWSER_START_PAGE start page for browser: [default: index.html]
- -d DEBUG_LEVEL, --debug-level=DEBUG_LEVEL Python logging module debug level (DEBUG, INFO, WARNING, ERROR or CRITICAL). [default: WARNING]
- -o SERVER_LOG_FILE, --server-log-file=SERVER_LOG_FILE log requests to this file. The value - means log to stderr: [default: ndb_setup-1541.log]
- -S, --use-https use https to secure communication with browser
- -c CERT_FILE, --cert-file=CERT_FILE file containing X509 certificate which identifies the server (possibly self-signed): [default: cfg.pem]
- -k KEY_FILE, --key-file=KEY_FILE file containing private key when if not included in cert-file: [default: none]
- -a CA_CERTS_FILE, --ca-certs-file=CA_CERTS_FILE file containing list of client certificates allowed to connect to the server [default: none (no client authentication)]

### Starting the Wizard

First, you need to identify the directory where the `ndb_setup` tool is located. This location depends on which package was downloaded and how it was installed. Then, you can start in the following ways:

- From the command line: Either change current directory to the one identified above, or enter the command prefixed by its absolute or relative path.
- Double clicking the appropriate icon: Open the file browser, go to the appropriate directory, identify the `ndb_setup` executable, and double click it.

### Supported Platforms

The configuration tool makes it a top priority to support the following platforms:

- Generic Linux
- Linux OL6
- SUSE Linux 11
- Windows 7
- Windows 2008
- Windows XP

Additionally, the tool will attempt, as far as possible, to support the following platforms:

- Ubuntu 11
- Windows Vista
- Solaris 11 Sparc
- Solaris 11 x86
- Mac OS x 10.7

### Supported Browsers

The configuration tool makes it a top priority to support the following browsers:

- Firefox
- Microsoft Internet Explorer

Additionally, the following browsers are supported as far as possible:

- Chrome
- Opera
- Safari

### Required Software

The following software must be installed on the host where the configuration tool is started:

- Python: Interpreter and libraries for the configuration tool. Version 2.6 or higher is required, and can be downloaded from http://python.org/download/
- Paramiko: SSH implementation required to communicate with remote hosts. Version 1.7.7.1 or higher is required, and can be downloaded from http://www.lag.net/paramiko/
- Pycrypto: Cryptography module required by Paramiko. Version 2.6 or higher is required, and can be downloaded from https://www.dlitz.net/software/pycrypto/

If you install the Windows version of the configuration tool, the above software comes bundled and is installed automatically. If you intend to deploy MySQL Cluster only on the same host as the configuration tool is running, you will not need the Paramiko and Pycrypto software.

The following software must be installed on the remote hosts that will be used to deploy the MySQL Cluster:

- SSH server: Most Linux and Solaris distributions run this as default. For Windows users, see e.g. http://en.wikipedia.org/wiki/Comparison_of_SSH_servers for an overview of SSH servers.
- User authentication: This is no particular software, of course, but the user wanting to access the remote host must be able to authenticate himself through SSH by means of user credentials or keys.

### Security

Three basic security mechanisms may be utilized by the configuration tool:

- SSH: Secure shell is used to enable the back end to perform actions on remote hosts. Thus, the remote host being accessed must have an SSH server up and running. Additionally, the configuration tool user must have access to the remote server by means of a user name and password, or by keys.
- https: Communication between the front end and the back end is not encrypted by default. This means that e.g. the SSH password is transmitted in a format that is readable to anyone. For communication to be encrypted, the back end must have a certificate, and the front end must communicate with the back end using https rather than http. The easiest way to enable this is to issue a self signed certificate. After the certificate is issued, it must be made available to, and used by, the back end. This can be done by starting the wizard with the options `--use-https` and `--cert-file=<certificate file name>`.
- Authentication: The back end process can execute commands on its local host as well as remote hosts. Thus, anyone connecting to the back end can take charge of how commands are executed. To reject unwanted connections to the back end, certificates may be used for authentication of the client. Thus, a certificate must be issued by the user, installed in the browser, and made available to the back end for authentication purposes. This can be done by starting the back end with the option `--ca-certs-file=<certificate list file name>`.

## Wizard overview

Two main components comprise the cluster configuration tool:

- The front end is a client implemented in Javascript, running in your favorite web browser.
- The back end is a server implemented in Python, running on your desktop or on another host.

The two main components communicate using messages wrapped in http. The back end can manage MySQL cluster software on any host. If the software is on the same host as the back end itself, the Python interfaces are used for file system operations, process manipulation, etc. If the MySQL Cluster software is on another host, the back end relies on SSH access the hosts, using the Paramiko package for executing commands remotely.

The remainder of this section will describe overall usage of the wizard in terms of navigating between pages, various settings, and how to get help.

### Navigation

The configuration tool is implemented as a wizard with a number of pages covering different steps. There are two ways to navigate between pages. First, the navigation toolbar or breadcrumb trail displays the titles of the various pages. A specific page can be selected by clicking the page title:

In the breadcrumb trail, the title of the current page is highlighted. The advantage of the breadcrumb trail is that you can jump more than one page in either direction.

The second navigation mechanism is to use the three navigation buttons at the bottom of the page. These can be used to advance to the next or previous page, or to go to the very last page. The buttons are disabled as needed, e.g., if you are at the last page, the Next and Finish buttons are disabled, while if you are on the first page, the Prev button is disabled.

### Settings

At the top right in the wizard window, next to the Help menu, you will find the Settings menu:

The various menu entries in the Settings menu are:

- Clear configuration and restart: This will remove all hosts and processes, reset parameter values to the default, and start the wizard over at the first page.
- Automatically save configuration as cookies: This will save your configuration information (host names, processes, parameter values etc.) as a cookie in the browser you are using. All information except the SSH password will be saved. Hence, you can quit and restart you browser, and continue working on the same configuration.
- Show advanced configuration options: This setting means that advanced configuration parameters will be visible in the wizard and editable for the user. The advanced parameters will always be used in the configuration file, this setting just controls whether they are visible in the wizard.
- Automatically get resource information for new hosts: With this setting checked, new hosts that are added will be queried automatically for hardware resource information. The information can be overridden afterwards if desired.

Some of the entries in the menu might be disabled if they are irrelevant due to choices you have made in the wizard. We will come back to that later in this user guide.

### Getting Help

At the very top right in the wizard window, next to the Settings menu, you will find the Help menu:

The various menu entries in the Help menu are:

- Content: This will show the user guide (i.e., the document you are currently reading) in a separate window, so you can read it while using the wizard.
- Current page: This will open the user guide at the section describing the page currently displayed in the wizard.
- About: This will show a small dialog displaying the tool name and version number.

In addition to the help menu, there are tool tips for most of the input widgets. They are displayed when you hover the widget, or there is a small orange question mark next to the widget's label which can be hovered for help. For the configuration parameters, the parameter names are linked to the MySQL Cluster documentation, so if you click the parameter name, the appropriate documentation is displayed in a separate frame.

## Wizard Pages

This section will describe the various wizard pages in detail.

### Welcome

The first page displayed after the `ndb_setup` command is invoked is the welcome page. Here, you get two alternatives:

- Create New MySQL Cluster: Start the wizard with a new cluster configuration
- Continue Previous Cluster Configuration: Start the wizard, continuing where you left the last time.

It is worth noticing that in the latter case, you must use the same web browser as you did the last time you were using the wizard. Additionally, the `ndb_setup` tool must run at the same host as it did the last time. The reason for this is that the configuration details are stored in the web browser as cookies.

### Define Cluster

Once you select one of the alternatives on the welcome page, you will be taken to the define cluster page. Here, you can decide on overall settings for the cluster you are going to configure.

The page contains the following input fields:

- Cluster name: This field can be used as a label reflecting the purpose of the cluster you are configuring.
- Host list: Here, a comma separated list of host names can be added. The default is to list only 127.0.0.1, which means the host where the `ndb_setup` command was issued. Host names can be added to or deleted from this list. If a host name is deleted, the processes configured to run on that host will also be deleted.
- Application area: This describes the overall way the cluster will be used. You can choose between the following three alternatives:
  - Simple testing: Here, the cluster will require little hardware resources, but this will also make the cluster performance suffer greatly. This application area should not be used in a production context.
  - Web application: For a web application, the configuration parameters will be defined in a way that maximizes performance, given the host hardware resources.
  - Realtime: The realtime configuration is much the same as the web application, the difference is that the realtime configuration is more sensitive to timeouts in the heartbeat mechanism to detect failing processes faster.
- Write load: You get to choose among the following settings:
  - Low: This is assumed to be less than 100 write transactions per second for the entire cluster.
  - Medium: This is assumed to be between 100 and 1000 write transactions per second for the entire cluster.
  - High: This is assumed to be more than than 1000 write transactions per second for the entire cluster.
- SSH Property: Here you can specify the SSH credentials needed to access a remote host. If your host list (see above) only contains 127.0.0.1, no SSH credentials are required. The credentials that can be specified are:
  - Key based SSH: Check this box if you have enabled key based login on the remote host. This will disable the two fields below.
  - User name: Submit your remote SSH user name here.
  - Password: Submit your remote SSH password here. The password will not be stored by the configurator except in main memory, so if the configuration tool is restarted, continuing with the same configuration, the password must be re-entered.

### Define Hosts

After the overall cluster properties have been defined, you can refine the host details. The wizard page is shown below:

Here, hosts can be added by pressing the Add hosts button and entering a list of comma separated host names or ip addresses. This works in the same way as the host list on the define cluster page. The hosts currently entered are displayed in the grid with various pieces of information. A host, or a selection of several hosts, can be removed from the configuration by pressing the Remove selected host(s) button. If processes have been configured to run on these hosts, the processes will be removed from the configuration too.

If the setting Automatically get resource information for new hosts is checked in the settings menu (see previous section), the platform name, RAM size and number of CPU cores will be filled in automatically and displayed in the grid. Otherwise, an ellipsis in the grid will indicate that the information was not obtained. The status of the automated resourced information fetching is displayed in the Resource info column. Please note that fetching the information may take some time, particularly on remote Windows hosts.

If the SSH user credentials on the define cluster page are changed, the tool will try to re-fetch the hardware information for hosts where a piece of information is missing. When the information is re-fetched, the various fields will be updated. If a field has been edited by the user, the information will not be overwritten by the re-fetched value.

The hardware resource information, platform name, install directory and data directory can be edited by the user by clicking the appropriate cell in the grid. It is also possible to select a set of hosts and press the button Edit selected host(s). Then, a dialog will appear where the various fields can be edited. The edited values will be applied to all hosts that were selected:

### Define Processes

After the hosts have been defined, the next step is to define which processes should be part of the cluster. This page is shown below:

There are two main areas here, there is a process tree to the left, with the various hosts and the processes configured to run on them. To the right is an information pane which displays information about the currently selected item in the tree. When the user enters this page the first time for a cluster configuration, a set of processes is defined as default. The processes defined depend on the number of hosts. If the user goes back to the previous page, removes all hosts, and adds other hosts, then a new set of processes will also be defined.

The processes are of the following main types:

- Management node: Node for administrative tasks such as stopping individual data nodes, querying status, running backup, etc.
- Single threaded data node: Node for storing the actual data and executing queries.
- Multi threaded data node: Same as above, but with several working threads executing in parallel.
- SQL node: MySQL server for executing SQL queries against the database.
- API node: Node accessing the database through a proprietary API rather than SQL.

In the process tree to the left, each node has a numeric suffix, which is incremented for each new process of that type. This is just to be able to tell the different processes apart. In the tree, in addition to the hosts you enter, there is a special entry Any host. This special "host" is really just a placeholder where processes that should be allowed to run on an arbitrary host may be located. Usually, a process is configured to run on a specific host, and thus will not be allowed to run on an arbitrary host. If this is desirable, the process should be added to the Any host entry. Please note that only API processes may be located on the special entryAny host.

In the process tree, you can right click a host for a pop up menu displaying an entry Add process. Selecting this entry will take you to the add process dialog. Alternatively, you can select a host, and press the Add process button below the process tree. The add process dialog lets you select among the available process types, and you can also enter an arbitrary process name instead of the default suggestion:

In the tree, you can also right click a process and select delete process from the pop up menu, or select a process and press the delete process button below the process tree. If a process is selected in the process tree, information about that process is displayed in the information pane to the right. You may edit the process name, and you may change the process type to another compatible type. Currently, the only compatible process types are the two variants of the data node; single threaded or multi threaded. If you want to change to an entirely different type, you need to delete the process first, and then add a new process with the desired type.

### Define Parameters

The page for defining parameters looks somewhat similar to the previous page for defining processes. To the left is a tree with the processes, to the right is a pane with information regarding the currently selected tree item:

However, looking at this in more detail, we see that the process tree is organized differently. On the previous page, it reflected which hosts the processes were running on, whereas on this page, it shows the processes grouped by process type. Thus, the root nodes in the tree are the process types, and the children are the process instances. You may notice that the compatible processes are grouped into the same process type, hence, the two data node processes will both be in the Data layer process type.

Below the process tree, you will see a check box labeled Show advanced configuration parameters. This check box will make advanced parameters visible or hidden in the information pane to the right. If you, e.g., select the Data layer process group, you will see that toggling the check box makes a lot of parameters appear or disappear in the pane to the right. The significance of this visibility is only that the parameters need to be visible for you to be able to change them. The parameters will be set anyway and used in the configuration of the cluster.

Now, the purpose of this page is to define the various configuration parameters for the processes. This can be done in two main ways:

- If a process instance is selected in the tree to the left, a list of available configuration parameters is displayed in the information pane to the right. If a parameter is changed, then it will apply only to the selected process.
- If a process group is selected in the tree to the left, you will also see a list of available configuration parameters in the pane to the right. However, if you change a parameter in this pane, the changed value will apply to all process instances in that process group unless the instance also has an overridden value for the parameter that was changed. Thus, parameter changes done for a process instance will overrule changes done for the process group.

When a process group or process instance is selected, you will see, e.g., the following information in the pane to the right (if an SQL process is selected):

In the information pane shown above, you see the various parameter names, their values, and for some of them, there is also a green button with a plus sign to the right. That button means that the parameter can be overridden. Thus, if you push the button, the input widget for the parameter will be enabled, and you will be able to change its value. The various parameters will have predefined values. If you, e.g., look at the parameter DataDir you will see it is a predefined path. This path is constructed based on the host on which the process will run, taking the data directory you entered for this host on the define hosts page, and appending the node id. All configuration parameters displayed by the tool will have predefined values, and usually, the values may just be left as they are. It is highly recommended that you read the documentation before making changes to the parameter values. Each parameter name is a hyper link into the MySQL documentation, so it is easy to find the relevant information.

If a configuration parameter has been changed, you may revert the change and go back to the predefined value: When the value has been overridden, the green button with a plus sign turns into a big red X, as shown below:

Now, if you press this red X, the change is reverted, and the parameter is reset to the predefined value.

### Deploy Configuration

The last page in the wizard is the deployment page. Here, you can inspect the startup commands and actual configuration files that will be applied, you can distribute the configuration files and create the necessary files and directories on the hosts involved, and you can start and stop the cluster you have configured. The page looks similar to the previous one:

To the left, you will find the same process tree as on the previous page. The processes are listed grouped by the process type they belong to. To the right of the process tree, there are two information panes. The upper one will display the startup commands necessary to start the process. For some processes, more than one command may be required, e.g. if initialization is needed. The lower pane will show the contents of the configuration file for the given process. Currently, the only processes having a configuration file are the management nodes. The other processes are configured by means of command line parameters submitted with the startup command, or by getting their configuration parameters by asking the management nodes dynamically.

In the process tree, the icons in front of the processes will change depending on the status of the processes. I.e., when the cluster starts or stops, the icons will turn red (stopped), yellow (starting or stopping) or green (running). This status information is based on querying the management daemon.

Below the process three, you will find three buttons:

- Deploy cluster: First, the configuration is verified, e.g., if you have specified the same value for two different data directories, you will not be allowed to deploy the configuration. Secondly, the required directories are created on the hosts involved, and the configuration files are distributed onto the hosts. A progress bar will show how the deployment proceeds.
- Start cluster: First, the configuration is deployed and the directories are created, i.e., the same as the above. Then, the processes that are defined are started in the correct order. Please note that starting the processes may take some time. If the estimated time usage is large, you will be alerted and asked to cancel or confirm continuation of the startup procedure. A progress bar will inform you about the current status of the startup procedure, and the icons in the process tree will also indicate how the start progresses.
- Stop cluster: When the cluster has been started, you may stop it using the Stop button. Here, you will also see a progress bar displaying the current status of the stopping procedure, and the icons the process tree are also updated regularly.

Below is an example of a progress bar displayed while starting the cluster:

It is worth noticing that the configuration tool cannot guarantee that the cluster is available for usage when it has been started. Hence, after the processes have been started, you will be informed that the processes are starting, but may need some time to initialize before they are ready for usage.