1. Home
  2. Docs
  3. ClusterControl
  4. Installation
  5. Manual Installation

Manual Installation

If you want to have more control over the installation process, you may perform a manual installation. ClusterControl requires a number of packages to be installed and configured, as described in the following list:

  • clustercontrol – ClusterControl web user interface.
  • clustercontrol-controller – ClusterControl CMON controller.
  • clustercontrol-notifications – ClusterControl notification module, if you would like to integrate with third-party tools like PagerDuty and Slack.
  • clustercontrol-ssh – ClusterControl web-based SSH module, if you would like to access the host via SSH directly from ClusterControl UI.
  • clustercontrol-cloud – ClusterControl cloud module, if you would like to manage your cloud instances directly from ClusterControl UI.
  • clustercontrol-clud – ClusterControl cloud file manager module, if you would like to upload and download backups from cloud storage. It requires clustercontrol-cloud.
  • s9s-tools – ClusterControl CLI client, if you would like to manage your cluster using a command-line interface.
Note

Installing and uninstalling ClusterControl should not bring any downtime to the managed database cluster.

Requirements

Make sure the following is ready prior to this installation:

  • Verify that sudo is working properly if you are using a non-root user.
  • ClusterControl node must be able to access all database nodes via passwordless SSH.
  • You must have an internet connection on the ClusterControl node during the installation process. Otherwise, see Offline Installation.

Installation Steps

Steps described in the following sections should be performed on the ClusterControl node unless specified otherwise.

Red Hat/CentOSDebian/Ubuntu

1. Setup ClusterControl repository – YUM Repository.

2. Setup ClusterControl CLI repository – RHEL/CentOS.

3. Disable SElinux and open required ports (or stop iptables):

$ sed -i 's|SELINUX=enforcing|SELINUX=disabled|g' /etc/selinux/config
$ setenforce 0
$ service iptables stop # RedHat/CentOS 6
$ systemctl stop firewalld # RedHat 7/8 or CentOS 7/8

4. Install required packages via package manager:

# RHEL/CentOS 8
$ yum -y install curl mailx cronie nc bind-utils mariadb mariadb-server httpd mod_ssl php php-pdo php-json php-mysqlnd# RHEL/CentOS 7
$ yum -y install curl mailx cronie nc bind-utils mariadb mariadb-server httpd mod_ssl php php-pdo php-json php-mysql
# RHEL/CentOS 6
$ yum -y install curl mailx cronie nc bind-utils mysql mysql-server httpd mod_ssl php php-pdo php-mysql

5. Install ClusterControl packages:

$ yum -y install clustercontrol \
  clustercontrol-controller \
  clustercontrol-ssh \
  clustercontrol-notifications \
  clustercontrol-cloud \
  clustercontrol-clud \
  s9s-tools

6. Start MySQL server (MariaDB for RHEL 7/8 or CentOS 7/8), enable it on boot and set a MySQL root password:

$ service mysqld start # Redhat/CentOS 6
$ systemctl start mariadb # Redhat/CentOS 7/8
$ chkconfig mysqld on # Redhat/CentOS 6
$ systemctl enable mariadb # Redhat/CentOS 7/8
$ mysqladmin -uroot password 'themysqlrootpassword'

7. Create two databases called cmon and dcps and grant the cmon user:

$ mysql -uroot -p -e 'DROP SCHEMA IF EXISTS cmon; CREATE SCHEMA cmon'
$ mysql -uroot -p -e 'DROP SCHEMA IF EXISTS dcps; CREATE SCHEMA dcps'
$ mysql -uroot -p -e 'GRANT ALL PRIVILEGES ON *.* TO "cmon"@"localhost" IDENTIFIED BY "{cmonpassword}" WITH GRANT OPTION'
$ mysql -uroot -p -e 'GRANT ALL PRIVILEGES ON *.* TO "cmon"@"127.0.0.1" IDENTIFIED BY "{cmonpassword}" WITH GRANT OPTION'
$ mysql -uroot -p -e 'FLUSH PRIVILEGES'
Note

Replace {cmonpassword} with respective value.

8. Import cmon and dcps schema structure and data:

$ mysql -uroot -p cmon < /usr/share/cmon/cmon_db.sql
$ mysql -uroot -p cmon < /usr/share/cmon/cmon_data.sql
$ mysql -uroot -p dcps < /var/www/html/clustercontrol/sql/dc-schema.sql

9. Generate a ClusterControl key to be used by RPC_TOKEN and rpc_key:

$ uuidgen | tr -d '-'
6856d96a19d049aa8a7f4a5ba57a34740b3faf57

And create the ClusterControl Controller (cmon) configuration file at /etc/cmon.cnf with the following configuration options:

mysql_port=3306
mysql_hostname=127.0.0.1
mysql_password={cmonpassword}
hostname={ClusterControl primary IP address}
logfile=/var/log/cmon.log
rpc_key={ClusterControl API key as generated above}

Example as follows:

$ cat /etc/cmon.cnf
mysql_port=3306
mysql_hostname=127.0.0.1
mysql_password=cmon
hostname=192.168.1.85
logfile=/var/log/cmon.log
rpc_key=6856d96a19d049aa8a7f4a5ba57a34740b3faf57
Attention

The value of the hostname must be either a valid FQDN or IP address of the ClusterControl node. If the host has multiple IP addresses, pick the primary IP address of the host.

10. ClusterControl event and cloud modules require their service definition inside /etc/default/cmon. Create the file and add the following lines:

EVENTS_CLIENT="http://127.0.0.1:9510"
CLOUD_SERVICE="http://127.0.0.1:9518"

11. Copy the provided Apache configuration files to their locations and prepare SSL key and certificate:

$ cp /var/www/html/clustercontrol/app/tools/apache2/s9s.conf /etc/httpd/conf.d/s9s.conf 
$ cp /var/www/html/clustercontrol/app/tools/apache2/s9s-ssl.conf /etc/httpd/conf.d/s9s-ssl.conf 
$ cp -f /var/www/html/clustercontrol/ssl/server.crt /etc/pki/tls/certs/s9server.crt 
$ cp -f /var/www/html/clustercontrol/ssl/server.key /etc/pki/tls/private/s9server.key 
$ rm -rf /var/www/html/clustercontrol/ssl 
$ sed -i 's|AllowOverride None|AllowOverride All|g' /etc/httpd/conf/httpd.conf

12. Replace the directives for SSLCertificateFile and SSLCertificateKeyFile  in file /etc/conf.d/s9s-ssl.conf.

$ sed -i 's|SSLCertificateFile.*|SSLCertificateFile /etc/pki/tls/certs/s9server.crt|g' /etc/httpd/conf.d/s9s-ssl.conf
$ sed -i 's|SSLCertificateKeyFile.*|SSLCertificateKeyFile /etc/pki/tls/private/s9server.key|g' /etc/httpd/conf.d/s9s-ssl.conf

13. Rename the ClusterControl UI default file and assign correct permission:

$ cp /var/www/html/clustercontrol/bootstrap.php.default /var/www/html/clustercontrol/bootstrap.php
$ chmod 644 /var/www/html/clustercontrol/bootstrap.php

14. Assign correct ownership and permission for the following paths:

$ chmod -R 777 /var/www/html/clustercontrol/app/tmp
$ chmod -R 777 /var/www/html/clustercontrol/app/upload
$ chown -Rf apache.apache /var/www/html/clustercontrol/

15. Use the generated value from step #9 and specify it inside /var/www/html/clustercontrol/bootstrap.php under RPC_TOKEN constant and configure MySQL credentials for the ClusterControl UI by updating the DB_PASS and DB_PORT constants with the cmon user password and MySQL port for dcps database:

define('DB_PASS', '{cmonpassword}');
define('DB_PORT', '3306');
define('RPC_TOKEN', '{Generated ClusterControl API token}');
Note

Replace {cmonpassword} and {Generated ClusterControl API token} with appropriate values.

16. Insert the generated API token from step #9 into dcps.apis table, so ClusterControl UI can use the security token to retrieve cluster information from the controller service:

$ mysql -uroot -p -e "INSERT IGNORE INTO dcps.apis (id, company_id, user_id, url, token, created) values (1,1,1,'http://127.0.0.1','{generated ClusterControl API token}', UNIX_TIMESTAMP())"
Note

Replace {generated ClusterControl API token} with appropriate value.

17. Enable ClusterControl and Apache daemons on boot and start them:

For sysvinit:

$ chkconfig --levels 235 cmon on
$ chkconfig --levels 235 cmon-ssh on
$ chkconfig --levels 235 cmon-events on
$ chkconfig --levels 235 cmon-cloud on
$ chkconfig --levels 235 httpd on
$ service cmon start
$ service cmon-ssh start
$ service cmon-events start
$ service cmon-cloud start
$ service httpd start

For systemd:

$ systemctl enable cmon cmon-ssh cmon-events cmon-cloud httpd
$ systemctl start cmon cmon-ssh cmon-events cmon-cloud httpd

18. Create the ccrpc user which is required since the ClusterControl version 1.8.2 to support new user management

$ export S9S_USER_CONFIG=$HOME/.s9s/ccrpc.conf
$ s9s user --create --new-password={generated ClusterControl API token} --generate-key --private-key-file==$HOME/.s9s/ccrpc.key --group=admins --controller=https://localhost:9501 ccrpc
$ s9s user --set --first-name=RPC --last-name=API --cmon-user=ccrpc &>/dev/null

19. Generate an SSH key to be used by ClusterControl when connecting to all managed hosts. In this example, we are using the root user to connect to the managed hosts. To generate an SSH key for the root user, do:

$ whoami
root
$ ssh-keygen -t rsa # Press enter for all prompts
Note

If you are running as sudoer, the default SSH key will be located under /home/$USER/.ssh/id_rsa. See Operating System User.

20. Before creating or importing a database server/cluster into ClusterControl, set up passwordless SSH from the ClusterControl host to the database host(s). Use the following command to copy the SSH key to the target hosts:

$ ssh-copy-id -i ~/.ssh/id_rsa {SSH user}@{IP address of the target node}
Note

Replace {SSH user} and {IP address of the target node} with appropriate values. Repeat the command for all target hosts.

20. Open ClusterControl UI at https://ClusterControl_host/clustercontrol and create the default admin password by providing a valid email address and password. You will be redirected to the ClusterControl default page.

The installation is complete and you can start to import existing or deploy a new database cluster. Please review the User Guide (GUI) for details.

The following steps should be performed on the ClusterControl node unless specified otherwise. Ensure you have the Severalnines repository and ClusterControl UI installed. Please refer to the Severalnines Repository section for details. Omit sudo if you are installing as the root user. Take note that for Ubuntu 12.04/Debian 7 and earlier, replace all occurrences of /var/www/html with /var/www in the following instructions.

1. Setup APT Repository.

2. Setup ClusterControl CLI repository – Debian/Ubuntu DEB Repositories.

3. If you have AppArmor running, disable it and open the required ports (or stop iptables):

$ sudo /etc/init.d/apparmor stop
$ sudo /etc/init.d/apparmor teardown
$ sudo update-rc.d -f apparmor remove
$ sudo service iptables stop

4. Install ClusterControl dependencies:

$ sudo apt-get update
$ sudo apt-get install -y curl apache2 libapache2-mod-php mailutils dnsutils mysql-client mysql-server php-common php-mysql php-gd php-ldap php-curl php-json

5. Install the ClusterControl controller package:

$ sudo apt-get install -y clustercontrol-controller \
  clustercontrol \
  clustercontrol-ssh \
  clustercontrol-notifications \
  clustercontrol-cloud \
  clustercontrol-clud \
  s9s-tools

6. Create two databases called cmon and dcps and grant user cmon:

$ mysql -uroot -p -e 'DROP SCHEMA IF EXISTS cmon; CREATE SCHEMA cmon'
$ mysql -uroot -p -e 'DROP SCHEMA IF EXISTS dcps; CREATE SCHEMA dcps'
$ mysql -uroot -p -e 'GRANT ALL PRIVILEGES ON *.* TO "cmon"@"localhost" IDENTIFIED BY "{cmonpassword}" WITH GRANT OPTION'
$ mysql -uroot -p -e 'GRANT ALL PRIVILEGES ON *.* TO "cmon"@"127.0.0.1" IDENTIFIED BY "{cmonpassword}" WITH GRANT OPTION'
$ mysql -uroot -p -e 'FLUSH PRIVILEGES'
Note

Replace {cmonpassword} with respective value.

7. For Apache 2.4 and later (Ubuntu 14.04/Debian 8 and later), the default document root is /var/www/html. Create a symbolic link for the components:

$ ln -sfn /var/www/clustercontrol /var/www/html/clustercontrol
$ ln -sfn /var/www/cmon /var/www/html/cmon

8. Import cmon and dcps schema:

$ mysql -uroot -p cmon < /usr/share/cmon/cmon_db.sql
$ mysql -uroot -p cmon < /usr/share/cmon/cmon_data.sql
$ mysql -uroot -p dcps < /var/www/clustercontrol/sql/dc-schema.sql

9. Generate a ClusterControl key to be used by RPC_TOKEN and rpc_key:

$ uuidgen | tr -d '-'
6856d96a19d049aa8a7f4a5ba57a34740b3faf57

And create the ClusterControl Controller (cmon) configuration file at /etc/cmon.cnf with the following configuration options:

mysql_port=3306
mysql_hostname=127.0.0.1
mysql_password={cmonpassword}
hostname={ClusterControl primary IP address}
rpc_key={ClusterControl API key as generated above}

Example as follows:

$ cat /etc/cmon.cnf
mysql_port=3306
mysql_hostname=127.0.0.1
mysql_password=cmon
hostname=192.168.1.85
rpc_key=6856d96a19d049aa8a7f4a5ba57a34740b3faf57
Attention

The value of hostname must be either a valid FQDN or IP address of the ClusterControl node. If the host has multiple IP addresses, pick the primary IP address of the host.

10. ClusterControl’s event and cloud modules require /etc/default/cmon for service definition. Create the file and add the following lines:

EVENTS_CLIENT="http://127.0.0.1:9510"
CLOUD_SERVICE="http://127.0.0.1:9518"

11. Copy the provided Apache configuration files to their locations, create symlinks to the configuration files and prepare SSL key and certificate:

$ cp -f /var/www/clustercontrol/ssl/server.crt /etc/ssl/certs/s9server.crt
$ cp -f /var/www/clustercontrol/ssl/server.key /etc/ssl/certs/s9server.key
$ rm -rf /var/www/clustercontrol/ssl
$ cp -f /var/www/clustercontrol/app/tools/apache2/s9s.conf /etc/apache2/sites-available/
$ cp -f /var/www/clustercontrol/app/tools/apache2/s9s-ssl.conf /etc/apache2/sites-available/
$ rm -f /etc/apache2/sites-enabled/000-default.conf
$ rm -f /etc/apache2/sites-enabled/default-ssl.conf
$ rm -f /etc/apache2/sites-enabled/001-default-ssl.conf
$ ln -sfn /etc/apache2/sites-available/s9s.conf /etc/apache2/sites-enabled/001-s9s.conf
$ ln -sfn /etc/apache2/sites-available/s9s-ssl.conf /etc/apache2/sites-enabled/001-s9s-ssl.conf
$ sed -i 's|^[ \t]*SSLCertificateFile.*|SSLCertificateFile /etc/ssl/certs/s9server.crt|g' /etc/apache2/sites-available/s9s-ssl.conf
$ sed -i 's|^[ \t]*SSLCertificateKeyFile.*|SSLCertificateKeyFile /etc/ssl/certs/s9server.key|g' /etc/apache2/sites-available/s9s-ssl.conf

12. Enable required Apache modules and create a symlink to sites-enabled for default HTTPS virtual host:

$ a2enmod ssl rewrite proxy proxy_http proxy_wstunnel
$ a2ensite default-ssl

13. Rename the ClusterControl UI default file and assign correct permission to the file:

$ mv /var/www/clustercontrol/bootstrap.php.default /var/www/clustercontrol/bootstrap.php
$ chmod 644 /var/www/clustercontrol/bootstrap.php

14. Assign correct ownership and permissions:

$ chmod -R 777 /var/www/html/clustercontrol/app/tmp
$ chmod -R 777 /var/www/html/clustercontrol/app/upload
$ chown -Rf www-data.www-data /var/www/html/clustercontrol/

15. Use the generated value from step #9 and specify it in /var/www/clustercontrol/bootstrap.php under the RPC_TOKEN constant and configure MySQL credentials for the ClusterControl UI by updating the DB_PASS and DB_PORT constants with the cmon user password and MySQL port for dcps database:

define('DB_PASS', '{cmonpassword}');
define('DB_PORT', '3306');
define('RPC_TOKEN', '{Generated ClusterControl API token}');
Note
Replace {cmonpassword} and {Generated ClusterControl API token} with appropriate values.

16. Insert the generated API token from step #9 into dcps.apis table, so ClusterControl UI can use the security token to retrieve cluster information from the controller service:

$ mysql -uroot -p -e "INSERT IGNORE INTO dcps.apis (id, company_id, user_id, url, token, created) values (1,1,1,'http://127.0.0.1','{generated ClusterControl API token}', UNIX_TIMESTAMP())"
Note

Replace {generated ClusterControl API token} with appropriate value.

17. Restart Apache webserver to apply the changes:

$ sudo service apache2 restart

18. Enable ClusterControl on boot and start them:

For sysvinit/upstart:

$ sudo update-rc.d cmon defaults
$ sudo update-rc.d cmon-ssh defaults
$ sudo update-rc.d cmon-events defaults
$ sudo update-rc.d cmon-cloud defaults
$ service cmon start
$ service cmon-ssh start
$ service cmon-events start
$ service cmon-cloud start

For systemd:

$ systemctl enable cmon cmon-ssh cmon-events cmon-cloud
$ systemctl restart cmon cmon-ssh cmon-events cmon-cloud

19. Create the ccrpc user which is required since the ClusterControl version 1.8.2 to support new user management

$ export S9S_USER_CONFIG=$HOME/.s9s/ccrpc.conf
$ s9s user --create --new-password={generated ClusterControl API token} --generate-key --private-key-file==$HOME/.s9s/ccrpc.key --group=admins --controller=https://localhost:9501 ccrpc
$ s9s user --set --first-name=RPC --last-name=API --cmon-user=ccrpc &>/dev/null

20. Generate an SSH key to be used by ClusterControl when connecting to all managed hosts. In this example, we are using the ‘root’ user to connect to the managed hosts. To generate an SSH key for the root user, do:

$ whoami
root
$ ssh-keygen -t rsa # Press enter for all prompts
Note

If you are running as sudoer, the default SSH key will be located under /home/$USER/.ssh/id_rsa. See Operating System User.

21. Before importing a database server/cluster into ClusterControl or deploy a new cluster, set up passwordless SSH from ClusterControl host to the database host(s). Use the following command to copy the SSH key to the target hosts:

$ ssh-copy-id -i ~/.ssh/id_rsa {SSH user}@{IP address of the target node}
Note

Replace {SSH user} and {IP address of the target node} with appropriate values. Repeat the command for all target hosts.

22. Open ClusterControl UI at https://{ClusterControl_host}/clustercontrol and create the default admin password by providing a valid email address and password. You will be redirected to the ClusterControl default page.

The installation is complete and you can start to import existing or deploy a new database cluster. Please review the User Guide (GUI) for details.

Was this article helpful to you? Yes No 1