Management Server Installation
Overview
This section describes installing the Management Server. There are two slightly different installation flows, depending on how many Management Server nodes will be in your cloud:
A single Management Server node, with MySQL on the same node.
Multiple Management Server nodes, with MySQL on a node separate from the Management Servers.
In either case, each machine must meet the system requirements described in Minimum System Requirements.
Warning
For the sake of security, be sure the public Internet can not access port 8096 or port 8250 on the Management Server.
The procedure for installing the Management Server is:
Prepare the Operating System
(XenServer only) Download and install vhd-util.
Install the First Management Server
Install and Configure the MySQL database
Prepare NFS Shares
Prepare and Start Additional Management Servers (optional)
Prepare the System VM Template
Prepare the Operating System
The OS must be prepared to host the Management Server using the following steps. These steps must be performed on each Management Server node.
Log in to your OS as root.
Check for a fully qualified hostname.
hostname --fqdn
This should return a fully qualified hostname such as “management1.lab.example.org”. If it does not, edit /etc/hosts so that it does.
Make sure that the machine can reach the Internet.
ping cloudstack.apache.org
Turn on NTP for time synchronization.
Note
An NTP daemon is required to synchronize the clocks of the servers in your cloud.
Install chrony.
In RHEL or CentOS:
$ yum install chrony
In Ubuntu:
$ apt install chrony
In SUSE:
$ zypper install chrony
Repeat all of these steps on every host where the Management Server will be installed.
Warning
CloudStack 4.19 requires Java 11 JRE. Installing CloudStack packages will
automatically install Java 11, but it’s good to explicitly confirm that the Java 11
is the selected/active one (in case you had a previous Java version already installed)
with alternatives --config java
after CloudStack packages are already installed.
Install the Management Server on the First Host
The first step in installation, whether you are installing the Management Server on one host or many, is to install the software on a single node.
Note
If you are planning to install the Management Server on multiple nodes for high availability, do not proceed to the additional nodes yet. That step will come later.
The CloudStack Management server can be installed using either RPM or DEB packages. These packages will depend on everything you need to run the Management server.
Configure package repository
CloudStack is only distributed from source from the official mirrors. However, members of the CloudStack community may build convenience binaries so that users can install Apache CloudStack without needing to build from source.
If you didn’t follow the steps to build your own packages from source in the sections for “Building RPMs from Source” or “Building DEB packages” you may find pre-built DEB and RPM packages for your convenience linked from the downloads page.
Note
These repositories contain both the Management Server and KVM Hypervisor packages.
RPM package repository
There is a RPM package repository for CloudStack so you can easily install on RHEL and SUSE based platforms.
If you’re using an RPM-based system, you’ll want to add the Yum repository so that you can install CloudStack with Yum.
In RHEL or CentOS:
Yum repository information is found under /etc/yum.repos.d
. You’ll
see several .repo
files in this directory, each one denoting a
specific repository.
To add the CloudStack repository, create
/etc/yum.repos.d/cloudstack.repo
and insert the following
information.
In the case of RHEL being used, you can replace ‘centos’ by ‘rhel’ in the value of baseurl
[cloudstack] name=cloudstack baseurl=http://download.cloudstack.org/centos/$releasever/4.19/ enabled=1 gpgcheck=0
Now you should now be able to install CloudStack using Yum.
In SUSE:
Zypper repository information is found under /etc/zypp/repos.d/
. You’ll
see several .repo
files in this directory, each one denoting a
specific repository.
To add the CloudStack repository, create
/etc/zypp/repos.d/cloudstack.repo
and insert the following
information.
[cloudstack] name=cloudstack baseurl=http://download.cloudstack.org/suse/4.19/ enabled=1 gpgcheck=0
Now you should now be able to install CloudStack using zypper.
DEB package repository
You can add a DEB package repository to your apt sources with the following commands. Replace the code name with your Ubuntu LTS version : Ubuntu 16.04 (Xenial), Ubuntu 18.04 (Bionic) and Ubuntu 20.04 (Focal) . Ubuntu 14.04 (Trusty) is no longer supported.
Use your preferred editor and open (or create)
/etc/apt/sources.list.d/cloudstack.list
. Add the community provided
repository to the file (replace “trusty” with “xenial” or “bionic” if it is the case):
deb https://download.cloudstack.org/ubuntu focal 4.19
We now have to add the public key to the trusted keys.
wget -O - https://download.cloudstack.org/release.asc |sudo tee /etc/apt/trusted.gpg.d/cloudstack.asc
Now update your local apt cache.
sudo apt update
Your DEB package repository should now be configured and ready for use.
Install on CentOS/RHEL
yum install cloudstack-management
Install on SUSE
zypper install cloudstack-management
Install on Ubuntu
sudo apt install cloudstack-management
Downloading vhd-util
This procedure is required only for installations where XenServer is installed on the hypervisor hosts.
Before setting up the Management Server, download
vhd-util from
http://download.cloudstack.org/tools/vhd-util.
and copy it into /usr/share/cloudstack-common/scripts/vm/hypervisor/xenserver
of the Management Server.
Install the database server
The CloudStack management server uses a MySQL database server to store its data. When you are installing the management server on a single node, you can install the MySQL server locally. For an installation that has multiple management server nodes, we assume the MySQL database also runs on a separate node.
CloudStack has been tested with MySQL 5.1 and 5.5. These versions are included in RHEL/CentOS and Ubuntu.
Install the Database on the Management Server Node
This section describes how to install MySQL on the same machine with the Management Server. This technique is intended for a simple deployment that has a single Management Server node. If you have a multi-node Management Server deployment, you will typically use a separate node for MySQL. See Install the Database on a Separate Node.
Install MySQL from the package repository of your distribution:
yum install mysql-server
zypper install mysql-server
sudo apt install mysql-server
Open the MySQL configuration file. The configuration file is
/etc/my.cnf
or/etc/mysql/my.cnf
, depending on your OS.Insert the following lines in the
[mysqld]
section.You can put these lines below the datadir line. The max_connections parameter should be set to 350 multiplied by the number of Management Servers you are deploying. This example assumes one Management Server.
innodb_rollback_on_timeout=1 innodb_lock_wait_timeout=600 max_connections=350 log-bin=mysql-bin binlog-format = 'ROW'
Note
For Ubuntu 16.04 and later, make sure you specify a
server-id
in your.cnf
file for binary logging. Set theserver-id
according to your database setup.server-id=source-01 innodb_rollback_on_timeout=1 innodb_lock_wait_timeout=600 max_connections=350 log-bin=mysql-bin binlog-format = 'ROW'
Note
You can also create a file
/etc/mysql/conf.d/cloudstack.cnf
and add these directives there. Don’t forget to add[mysqld]
on the first line of the file.Start or restart MySQL to put the new configuration into effect.
On RHEL/CentOS, MySQL doesn’t automatically start after installation. Start it manually.
systemctl start mysqld
On SUSE, start MySQL
systemctl start mysql
On Ubuntu, restart MySQL.
sudo systemctl restart mysql
(CentOS and RHEL only; not required on Ubuntu)
Warning
On RHEL and CentOS, MySQL does not set a root password by default. It is very strongly recommended that you set a root password as a security precaution.
Run the following command to secure your installation. You can answer “Y” to all questions.
mysql_secure_installation
CloudStack can be blocked by security mechanisms, such as SELinux. Disable SELinux to ensure + that the Agent has all the required permissions.
Configure SELinux (RHEL and CentOS):
Check whether SELinux is installed on your machine. If not, you can skip this section.
In RHEL or CentOS, SELinux is installed and enabled by default. You can verify this with:
rpm -qa | grep selinux
Set the SELINUX variable in
/etc/selinux/config
to “permissive”. This ensures that the permissive setting will be maintained after a system reboot.In RHEL or CentOS:
vi /etc/selinux/config
Change the following line
SELINUX=enforcing
to this:
SELINUX=permissive
Set SELinux to permissive starting immediately, without requiring a system reboot.
setenforce permissive
Set up the database.
The cloudstack-setup-databases script is used for creating the cloudstack databases (cloud, cloud_usage), creating a User (cloud), granting permissions to the User and preparing the tables for the first startup of the management server.
The following command creates the “cloud” user on the database.
cloudstack-setup-databases cloud:<dbpassword>@localhost [ --deploy-as=root:<password> | --schema-only ] -e <encryption_type> -m <management_server_key> -k <database_key> -i <management_server_ip>
In dbpassword, specify the password to be assigned to the “cloud” user. You can choose to provide no password although that is not recommended.
In deploy-as, specify the username and password of the user deploying the database. In the following command, it is assumed the root User is deploying the database and creating the “cloud” User.
(Optional) There is an option to bypass the creating of the databases, User and granting permissions to the user. This is useful if you don’t want to expose your root credentials but still want the database to be prepared for first start up. These skipped steps will have had to be done manually prior to executing this script. This behaviour can be invoked by passing the –schema-only flag. This flag conflicts with the –deploy-as flag so the two cannot be used together. To set up the databases and user manually before executing the script with the flag, these commands can be executed:
-- Create the cloud and cloud_usage databases CREATE DATABASE `cloud`; CREATE DATABASE `cloud_usage`; -- Create the cloud user CREATE USER cloud@`localhost` identified by '<password>'; CREATE USER cloud@`%` identified by '<password>'; -- Grant all privileges to the cloud user on the databases GRANT ALL ON cloud.* to cloud@`localhost`; GRANT ALL ON cloud.* to cloud@`%`; GRANT ALL ON cloud_usage.* to cloud@`localhost`; GRANT ALL ON cloud_usage.* to cloud@`%`; -- Grant process list privilege for all other databases GRANT process ON *.* TO cloud@`localhost`; GRANT process ON *.* TO cloud@`%`;
(Optional) For encryption_type, use file or web to indicate the technique used to pass in the database encryption password. Default: file. See About Password and Key Encryption.
(Optional) For management_server_key, substitute the default key that is used to encrypt confidential parameters in the CloudStack properties file. Default: password. It is highly recommended that you replace this with a more secure value. See About Password and Key Encryption.
(Optional) For database_key, substitute the default key that is used to encrypt confidential parameters in the CloudStack database. Default: password. It is highly recommended that you replace this with a more secure value. See About Password and Key Encryption.
(Optional) For management_server_ip, you may explicitly specify cluster management server node IP. If not specified, the local IP address will be used.
When this script is finished, you should see a message like “Successfully initialized the database.”
Note
If the script is unable to connect to the MySQL database, check the “localhost” loopback address in
/etc/hosts
. It should be pointing to the IPv4 loopback address “127.0.0.1” and not the IPv6 loopback address::1
. Alternatively, reconfigure MySQL to bind to the IPv6 loopback interface.If you are running the KVM hypervisor on the same machine with the Management Server, edit /etc/sudoers and add the following line:
Defaults:cloud !requiretty
Now that the database is set up, you can finish configuring the OS for the Management Server. This command will set up iptables, sudoers, and start the Management Server.
cloudstack-setup-management
You should get the output message “CloudStack Management Server setup is done.” If the servlet container is Tomcat7 the argument –tomcat7 must be used.
Install the Database on a Separate Node
This section describes how to install MySQL on a standalone machine, separate from the Management Server. This technique is intended for a deployment that includes several Management Server nodes. If you have a single-node Management Server deployment, you will typically use the same node for MySQL. See “Install the Database on the Management Server Node”.
Note
The management server doesn’t require a specific distribution for the MySQL node. You can use a distribution or Operating System of your choice. Using the same distribution as the management server is recommended, but not required. See “Management Server, Database, and Storage System Requirements”.
Install MySQL from the package repository from your distribution:
yum install mysql-server
zypper install mysql-server
sudo apt install mysql-server
Edit the MySQL configuration (/etc/my.cnf or /etc/mysql/my.cnf, depending on your OS) and insert the following lines in the [mysqld] section. You can put these lines below the datadir line. The max_connections parameter should be set to 350 multiplied by the number of Management Servers you are deploying. This example assumes two Management Servers.
Note
On Ubuntu, you can also create /etc/mysql/conf.d/cloudstack.cnf file and add these directives there. Don’t forget to add [mysqld] on the first line of the file.
innodb_rollback_on_timeout=1 innodb_lock_wait_timeout=600 max_connections=700 log-bin=mysql-bin binlog-format = 'ROW' bind-address = 0.0.0.0
Start or restart MySQL to put the new configuration into effect.
On RHEL/CentOS, MySQL doesn’t automatically start after installation. Start it manually.
service mysqld start
On SUSE, enable and start MySQL
systemctl enable mysql systemctl start mysql
On Ubuntu, restart MySQL.
sudo service mysql restart
(CentOS and RHEL only; not required on Ubuntu)
Warning
On RHEL and CentOS, MySQL does not set a root password by default. It is very strongly recommended that you set a root password as a security precaution. Run the following command to secure your installation. You can answer “Y” to all questions except “Disallow root login remotely?”. Remote root login is required to set up the databases.
mysql_secure_installation
If a firewall is present on the system, open TCP port 3306 so external MySQL connections can be established.
On Ubuntu, UFW is the default firewall. Open the port with this command:
ufw allow mysql
On RHEL/CentOS/SUSE:
Edit the /etc/sysconfig/iptables file and add the following line at the beginning of the INPUT chain.
-A INPUT -p tcp --dport 3306 -j ACCEPT
Now reload the iptables rules.
service iptables restart
Warning
On CentOS 8 / SUSE, firewalld is the default firewall manager and controls iptables. It is recommended that it be disabled
systemctl stop firewalld ; systemctl disable firewalld
, since CloudStack directly manipulates the iptable rules to manage Networks.Warning
On SUSE, iptables are not persisted on reboot, so it is recommended that iptables and ip6tables service be created to ensure that they persist
Return to the root shell on your first Management Server.
Set up the database.
The cloudstack-setup-databases script is used for creating the cloudstack databases (cloud, cloud_usage), creating a user (cloud), granting permissions to the user and preparing the tables for the first startup of the management server.
The following command creates the cloud user on the database.
cloudstack-setup-databases cloud:<dbpassword>@<ip address mysql server> [ --deploy-as=root:<password> | --schema-only ]-e <encryption_type> -m <management_server_key> -k <database_key> -i <management_server_ip>
In dbpassword, specify the password to be assigned to the cloud user. You can choose to provide no password.
In deploy-as, specify the username and password of the user deploying the database. In the following command, it is assumed the root user is deploying the database and creating the cloud user.
(Optional) There is an option to bypass the creating of the databases, user and granting permissions to the user. This is useful if you don’t want to expose your root credentials but still want the database to be prepared for first start up. These skipped steps will have had to be done manually prior to executing this script. This behaviour can be envoked by passing the –schema-only flag. This flag conflicts with the –deploy-as flag so the two cannot be used together. To set up the databases and user manually before executing the script with the flag, these commands can be executed:
-- Create the cloud and cloud_usage databases CREATE DATABASE `cloud`; CREATE DATABASE `cloud_usage`; -- Create the cloud user CREATE USER cloud@`localhost` identified by '<password>'; CREATE USER cloud@`%` identified by '<password>'; -- Grant all privileges to the cloud user on the databases GRANT ALL ON cloud.* to cloud@`localhost`; GRANT ALL ON cloud.* to cloud@`%`; GRANT ALL ON cloud_usage.* to cloud@`localhost`; GRANT ALL ON cloud_usage.* to cloud@`%`; -- Grant process list privilege for all other databases GRANT process ON *.* TO cloud@`localhost`; GRANT process ON *.* TO cloud@`%`;(Optional) For encryption_type, use file or web to indicate the technique used to pass in the database encryption password. Default: file. See About Password and Key Encryption.
(Optional) For management_server_key, substitute the default key that is used to encrypt confidential parameters in the CloudStack properties file. Default: password. It is highly recommended that you replace this with a more secure value. See About Password and Key Encryption.
(Optional) For database_key, substitute the default key that is used to encrypt confidential parameters in the CloudStack database. Default: password. It is highly recommended that you replace this with a more secure value. See About Password and Key Encryption.
(Optional) For management_server_ip, you may explicitly specify cluster management server node IP. If not specified, the local IP address will be used.
cloudstack-setup-databases cloud:<dbpassword>@<ip address mysql server> --deploy-as=root:<password> -e <encryption_type> -m <management_server_key> -k <database_key> -i <management_server_ip>When this script is finished, you should see a message like “Successfully initialized the database.”
Now that the database is set up, you can finish configuring the OS for the Management Server. This command will set up iptables, sudoers, and start the Management Server.
cloudstack-setup-management
You should get the output message “CloudStack Management Server setup is done!”
Warning
On RHEL and CentOS systems, firewalld (installed by default) will override all iptables rules set by the cloudstack-setup-management script, so ensure that the firewalld is disabled or ensure the correct firewalld rules are in place to allow traffic to ports 8080, 8250 and 9090 to the management server.
Additional Management Servers
For your second and subsequent Management Servers, you will install the Management Server software, connect it to the database, and set up the OS for the Management Server.
Perform the steps in “Prepare the Operating System” and “Building RPMs from Source” or “Building DEB packages” as appropriate.
This step is required only for installations where XenServer is installed on the hypervisor hosts.
Download vhd-util from vhd-util
Copy vhd-util to
/usr/share/cloudstack-common/scripts/vm/hypervisor/xenserver
.Ensure that necessary services are started and set to start on boot.
service rpcbind start service nfs start chkconfig nfs on chkconfig rpcbind on
Configure the database client. Note the absence of the –deploy-as argument in this case. (For more details about the arguments to this command, see Install the Database on a Separate Node.)
cloudstack-setup-databases cloud:dbpassword@dbhost -e encryption_type -m management_server_key -k database_key -i management_server_ip
Configure the OS and start the Management Server:
cloudstack-setup-management
The Management Server on this node should now be running. If the servlet container is Tomcat7 the argument –tomcat7 must be used.
Warning
On RHEL and CentOS systems, firewalld (installed by default) will override all iptables rules set by the cloudstack-setup-management script, so ensure that the firewalld is disabled or ensure the correct firewalld rules are in place to allow traffic to ports 8080, 8250 and 9090 to the management server.
Repeat these steps on each additional Management Server.
Be sure to configure a load balancer for the Management Servers. See Management Server Load Balancing
Prepare the System VM Template
From Apache CloudStack v4.16 onwards, upgrade path handles SystemVM Template registration, if not done prior to initiating upgrade. One may choose, to also omit the SystemVM Template seeding step during fresh installation of CloudStack, as support has been added to initiate SystemVM Template registration for all hypervisors present in the zone when the first secondary storage pool is added. Secondary storage must be seeded with a Template that is used for CloudStack System VMs.
Note
When copying and pasting a command, be sure the command has pasted as a single line before executing. Some document viewers may introduce unwanted line breaks in copied text.
On the Management Server, run one or more of the following
cloud-install-sys-tmplt
commands to retrieve and decompress the System VM Template. Run the command for each hypervisor type that you expect end Users to run in this Zone.If your secondary storage mount point is not named
/mnt/secondary
, substitute your own mount point name.If you set the CloudStack database encryption type to “web” when you set up the database, you must now add the parameter
-s <management-server-secret-key>
. See About Password and Key Encryption.This process will require approximately 5 GB of free space on the local file system and up to 30 minutes each time it runs.
For Hyper-V
/usr/share/cloudstack-common/scripts/storage/secondary/cloud-install-sys-tmplt -m /mnt/secondary -u http://download.cloudstack.org/systemvm/4.19/systemvmtemplate-4.19.1-hyperv.vhd.zip -h hyperv -s <optional-management-server-secret-key> -F
For XenServer:
/usr/share/cloudstack-common/scripts/storage/secondary/cloud-install-sys-tmplt -m /mnt/secondary -u http://download.cloudstack.org/systemvm/4.19/systemvmtemplate-4.19.1-xen.vhd.bz2 -h xenserver -s <optional-management-server-secret-key> -F
For vSphere:
/usr/share/cloudstack-common/scripts/storage/secondary/cloud-install-sys-tmplt -m /mnt/secondary -u http://download.cloudstack.org/systemvm/4.19/systemvmtemplate-4.19.1-vmware.ova -h vmware -s <optional-management-server-secret-key> -F
For KVM:
/usr/share/cloudstack-common/scripts/storage/secondary/cloud-install-sys-tmplt -m /mnt/secondary -u http://download.cloudstack.org/systemvm/4.19/systemvmtemplate-4.19.1-kvm.qcow2.bz2 -h kvm -s <optional-management-server-secret-key> -F
For LXC:
/usr/share/cloudstack-common/scripts/storage/secondary/cloud-install-sys-tmplt -m /mnt/secondary -u http://download.cloudstack.org/systemvm/4.19/systemvmtemplate-4.19.1-kvm.qcow2.bz2 -h lxc -s <optional-management-server-secret-key> -F
For OVM3:
/usr/share/cloudstack-common/scripts/storage/secondary/cloud-install-sys-tmplt -m /mnt/secondary -u http://download.cloudstack.org/systemvm/4.19/systemvmtemplate-4.19.1-ovm.raw.bz2 -h ovm3 -s <optional-management-server-secret-key> -F
If you are using a separate NFS server, perform this step. If you are using the Management Server as the NFS server, you MUST NOT perform this step.
When the script has finished, unmount secondary storage and remove the created directory.
umount /mnt/secondary rmdir /mnt/secondary
Repeat these steps for each secondary storage server.
Installation Complete! Next Steps
Congratulations! You have now installed CloudStack Management Server and the database it uses to persist system data.
What should you do next?
Even without adding any cloud infrastructure, you can run the UI to get a feel for what’s offered and how you will interact with CloudStack on an ongoing basis. See Log In to the UI.
When you’re ready, add the cloud infrastructure and try running some Instances on it, so you can watch how CloudStack manages the infrastructure. See Provision Your Cloud Infrastructure.