From 5c4cf11860bb1103d6e660ee4d72b3f329cfefd7 Mon Sep 17 00:00:00 2001 From: Wido den Hollander Date: Tue, 25 Sep 2012 16:56:49 +0200 Subject: [PATCH] docs: Update the documentation for the database installtion. This adds more documentation about installing the MySQL database locally or on an external node. It also adds Ubuntu documentation. --- .../management-server-install-db-external.xml | 101 ++++++++++-------- .../management-server-install-db-local.xml | 82 ++++++-------- docs/en-US/management-server-install-db.xml | 34 ++++++ docs/en-US/management-server-install-flow.xml | 3 +- .../management-server-install-multi-node.xml | 2 +- 5 files changed, 122 insertions(+), 100 deletions(-) create mode 100644 docs/en-US/management-server-install-db.xml diff --git a/docs/en-US/management-server-install-db-external.xml b/docs/en-US/management-server-install-db-external.xml index bc768290ce3..e77380fc54c 100644 --- a/docs/en-US/management-server-install-db-external.xml +++ b/docs/en-US/management-server-install-db-external.xml @@ -22,71 +22,82 @@ under the License. --> -
+
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 . + See . + + 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 . + + - If you already have a version of MySQL installed on the Management Server node, make one of the following choices, depending on what version of MySQL it is. The most recent version tested is 5.1.58. - - If you already have installed MySQL version 5.1.58 or later, skip to step 3. - - If you have installed a version of MySQL earlier than 5.1.58, you can either skip to step 3 or uninstall MySQL and proceed to step 2 to install a more recent version. - - It is important that you choose the right database version. Never downgrade a MySQL installation. - - Log in as root to your Database Node and run the following commands. If you are going to install a replica database, then log in to the master. - -# yum install mysql-server -# chkconfig --level 35 mysqld on - + + Install MySQL from the package repository from your distribution: + On RHEL or CentOS: + yum install mysql-server + On Ubuntu: + apt-get 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. + + On Ubuntu 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. + innodb_rollback_on_timeout=1 innodb_lock_wait_timeout=600 max_connections=700 log-bin=mysql-bin binlog-format = 'ROW' - - The binlog-format variable is supported in MySQL versions 5.1 and greater. It is not supported in MySQL 5.0. In some versions of MySQL, an underscore character is used in place of the hyphen in the variable name. For the exact syntax and spelling of each variable, consult the documentation for your version of MySQL. - - Restart the MySQL service, then invoke MySQL as the root user. - -# service mysqld restart -# mysql -u root +bind-address = 0.0.0.0 - Best Practice: 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 commands, and substitute your own desired root password. - mysql> SET PASSWORD = PASSWORD('password'); - From now on, start MySQL with mysql -p so it will prompt you for the password. + + On RHEL/CentOS MySQL doesn't start after installation, start it manually. + service mysqld start - To grant access privileges to remote users, perform the following steps. + + + 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 commands, and substitute your own desired root password. This step is not required on Ubuntu as it asks for a root password during installation. + + Run this command to secure your installation. You can answer "Y" to all questions except to "Disallow root login remotely?". This 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. - Run the following commands from the mysql prompt: - -mysql> GRANT ALL PRIVILEGES ON *.* TO 'root'@'%' WITH GRANT OPTION; -mysql> exit - + + On RHEL/CentOS: + + + 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 + + - Restart the MySQL service. - # service mysqld restart - - Open the MySQL server port (3306) in the firewall to allow remote clients to connect. - # iptables -I INPUT -p tcp --dport 3306 -j ACCEPT - - 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 + + On Ubuntu: + UFW is the default firewall on Ubuntu, open the port with this command: + ufw allow mysql - Set up the database. The following command creates the cloud user on the database. + + Set up the database. The following command creates the cloud user on the database. + + This command should be run on the first Management server node! + 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. @@ -94,12 +105,12 @@ mysql> exit (Optional) For management_server_key, substitute the default key that is used to encrypt confidential parameters in the &PRODUCT; 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 &PRODUCT; database. Default: password. It is highly recommended that you replace this with a more secure value. See About Password and Key Encryption. - # cloud-setup-databases cloud:<dbpassword>@localhost --deploy-as=root:<password> -e <encryption_type> -m <management_server_key> -k <database_key> + cloud-setup-databases cloud:<dbpassword>@<ip address mysql server> \ + --deploy-as=root:<password> \ + -e <encryption_type> \ + -m <management_server_key> \ + -k <database_key> 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. - # cloud-setup-management - You should see the message “Management Server setup is done.” -
diff --git a/docs/en-US/management-server-install-db-local.xml b/docs/en-US/management-server-install-db-local.xml index 238f9dee629..ae8cfd1edca 100644 --- a/docs/en-US/management-server-install-db-local.xml +++ b/docs/en-US/management-server-install-db-local.xml @@ -22,28 +22,22 @@ under the License. --> -
+
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 . - + 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 . - If you already have a version of MySQL installed on the Management Server node, make one of the following choices, depending on what version of MySQL it is. The most recent version tested is 5.1.58. - - If you already have installed MySQL version 5.1.58 or later, skip to step 4. - - If you have installed a version of MySQL earlier than 5.1.58, you can either skip to step 4 or uninstall MySQL and proceed to step 2 to install a more recent version. - - It is important that you choose the right database version. Never downgrade a MySQL installation. + + Install MySQL from the package repository from your distribution: + On RHEL or CentOS: + yum install mysql-server + On Ubuntu: + apt-get install mysql-server - On the same computer where you installed the Management Server, re-run install.sh. - # ./install.sh - You should see a few messages as the installer prepares, followed by a list of choices. - - Choose D to install the MySQL server from the distribution’s repo. - > D - Troubleshooting: If you do not see the D option, you already have MySQL installed. Please go back to step 1. - - 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 one Management 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 one Management Server. + + On Ubuntu 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. + innodb_rollback_on_timeout=1 innodb_lock_wait_timeout=600 @@ -51,48 +45,32 @@ max_connections=350 log-bin=mysql-bin binlog-format = 'ROW' - The binlog-format variable is supported in MySQL versions 5.1 and greater. It is not supported in MySQL 5.0. In some versions of MySQL, an underscore character is used in place of the hyphen in the variable name. For the exact syntax and spelling of each variable, consult the documentation for your version of MySQL. - Restart the MySQL service, then invoke MySQL as the root user. - -# service mysqld restart -# mysql -u root - + + On RHEL/CentOS MySQL doesn't start after installation, start it manually. + service mysqld start - Best Practice: 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 commands, and substitute your own desired root password. - mysql> SET PASSWORD = PASSWORD('password'); - From now on, start MySQL with mysql -p so it will prompt you for the password. + + + 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 commands, and substitute your own desired root password. This step is not required on Ubuntu as it asks for a root password during installation. + + Run this command to secure your installation. Since we are running MySQL locally you can answer "Y" to all questions. + mysql_secure_installation - To grant access privileges to remote users, perform the following steps. - - Run the following commands from the mysql prompt: - -mysql> GRANT ALL PRIVILEGES ON *.* TO 'root'@'%' WITH GRANT OPTION; -mysql> exit - - - Restart the MySQL service. - # service mysqld restart - Open the MySQL server port (3306) in the firewall to allow remote clients to connect. - # iptables -I INPUT -p tcp --dport 3306 -j ACCEPT - 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 - - - Set up the database. The following command creates the cloud user on the database. + Set up the database. The following command creates the "cloud" user on the database. - 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. + 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) 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 &PRODUCT; 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 &PRODUCT; database. Default: password. It is highly recommended that you replace this with a more secure value. See About Password and Key Encryption. - # cloud-setup-databases cloud:<dbpassword>@localhost --deploy-as=root:<password> -e <encryption_type> -m <management_server_key> -k <database_key> + cloud-setup-databases cloud:<dbpassword>@localhost \ + --deploy-as=root:<password> \ + -e <encryption_type> \ + -m <management_server_key> \ + -k <database_key> 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. - # cloud-setup-management - You should see the message “Management Server setup is done.” -
diff --git a/docs/en-US/management-server-install-db.xml b/docs/en-US/management-server-install-db.xml new file mode 100644 index 00000000000..24e638ad005 --- /dev/null +++ b/docs/en-US/management-server-install-db.xml @@ -0,0 +1,34 @@ + + +%BOOK_ENTITIES; +]> + + + +
+ Install the database server + The &PRODUCT; management server uses a MySQL database server to store it's data. + When you are installing the management server on a single node you can install the MySQL server locally. + When using a multi-node installation the MySQL database has to run on an external node. + + &PRODUCT; has been tested with MySQL 5.1 and 5.5, both should work fine. These versions are included in RHEL/CentOS and Ubuntu. + + +
\ No newline at end of file diff --git a/docs/en-US/management-server-install-flow.xml b/docs/en-US/management-server-install-flow.xml index 112771bb500..33bcac9c85b 100644 --- a/docs/en-US/management-server-install-flow.xml +++ b/docs/en-US/management-server-install-flow.xml @@ -27,8 +27,7 @@ - - + diff --git a/docs/en-US/management-server-install-multi-node.xml b/docs/en-US/management-server-install-multi-node.xml index 17d0f868b3c..db4bca5f83e 100644 --- a/docs/en-US/management-server-install-multi-node.xml +++ b/docs/en-US/management-server-install-multi-node.xml @@ -56,7 +56,7 @@ 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 .) + (For more details about the arguments to this command, see .) # cloud-setup-databases cloud:<dbpassword>@<dbhost> -e <encryption_type> -m <management_server_key> -k <database_key>