diff --git a/docs/en-US/about-password-encryption.xml b/docs/en-US/about-password-encryption.xml new file mode 100644 index 00000000000..3f7c4c84350 --- /dev/null +++ b/docs/en-US/about-password-encryption.xml @@ -0,0 +1,65 @@ + + +%BOOK_ENTITIES; +]> + +
+ About Password and Key Encryption + &PRODUCT; stores several sensitive passwords and secret keys that are used to provide + security. These values are always automatically encrypted: + + + Database secret key + + + Database password + + + SSH keys + + + Compute node root password + + + VPN password + + + User API secret key + + + VNC password + + + &PRODUCT; uses the Java Simplified Encryption (JASYPT) library. The data values are + encrypted and decrypted using a database secret key, which is stored in one of &PRODUCT;’s + internal properties files along with the database password. The other encrypted values listed + above, such as SSH keys, are in the &PRODUCT; internal database. + Of course, the database secret key itself can not be stored in the open – it must be + encrypted. How then does &PRODUCT; read it? A second secret key must be provided from an + external source during Management Server startup. This key can be provided in one of two ways: + loaded from a file or provided by the &PRODUCT; administrator. The &PRODUCT; database has a new + configuration setting that lets it know which of these methods will be used. If the encryption + type is set to “file,” the key must be in a file in a known location. If the encryption type is + set to “web,” the administrator runs the utility + com.cloud.utils.crypt.EncryptionSecretKeySender, which relays the key to the Management Server + over a known port. + The encryption type, database secret key, and Management Server secret key are set during + &PRODUCT; installation. They are all parameters to the &PRODUCT; database setup script + (cloud-setup-databases). The default values are file, password, and password. It is, of course, + highly recommended that you change these to more secure keys. +
diff --git a/docs/en-US/management-server-install-db-external.xml b/docs/en-US/management-server-install-db-external.xml index a749dc76c0d..3bba45f3ee1 100644 --- a/docs/en-US/management-server-install-db-external.xml +++ b/docs/en-US/management-server-install-db-external.xml @@ -21,95 +21,120 @@ specific language governing permissions and limitations 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 . - - - 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 . - - - - - 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 + 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 . + + 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 . + + + + 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 /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 +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 Ubuntu, restart MySQL. + service mysqld restart + + + (CentOS and RHEL only; not required on Ubuntu) + + 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: + + + 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 - 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 Ubuntu, restart MySQL. - service mysqld restart + Now reload the iptables rules. + service iptables restart + + + + + Return to the root shell on your first Management Server. + + + 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. - (CentOS and RHEL only; not required on Ubuntu) - - 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 + 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. - 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: - - - 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 - - - - Return to the root shell on your first Management Server. - 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. - (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>@<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.” + (Optional) For encryption_type, use file or web to indicate the technique used to + pass in the database encryption password. Default: file. See . - + + (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 . + + + 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.” + +
diff --git a/docs/en-US/management-server-install-db-local.xml b/docs/en-US/management-server-install-db-local.xml index 9880c54571b..3e09c554df0 100644 --- a/docs/en-US/management-server-install-db-local.xml +++ b/docs/en-US/management-server-install-db-local.xml @@ -1,5 +1,5 @@ - %BOOK_ENTITIES; ]> @@ -21,69 +21,105 @@ specific language governing permissions and limitations 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 . - - - 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 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 + 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 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 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 max_connections=350 log-bin=mysql-bin binlog-format = 'ROW' + + + 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 Ubuntu, restart MySQL. + service mysqld restart + + + (CentOS and RHEL only; not required on Ubuntu) + + 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 + + + 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 although that is not recommended. - 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 Ubuntu, restart MySQL. - service mysqld restart + 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. - (CentOS and RHEL only; not required on Ubuntu) - - 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 + (Optional) For encryption_type, use file or web to indicate the technique used to + pass in the database encryption password. Default: file. See . - 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 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> - When this script is finished, you should see a message like “Successfully initialized the database.” + + (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 . - 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 - This type of single-machine setup is recommended only for a trial installation. + + (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 . - 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 “&PRODUCT; Management Server setup is done.” - - + + 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.” + + + 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 + + This type of single-machine setup is recommended only for a trial installation. + + + + 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 “&PRODUCT; Management Server setup is done.” + +
diff --git a/docs/en-US/prepare-system-vm-template.xml b/docs/en-US/prepare-system-vm-template.xml index 5ed78f7d5a3..22674d47952 100644 --- a/docs/en-US/prepare-system-vm-template.xml +++ b/docs/en-US/prepare-system-vm-template.xml @@ -23,8 +23,8 @@ -->
Prepare the System VM Template - Secondary storage must be seeded with a template that is used for &PRODUCT; system - VMs. + Secondary storage must be seeded with a template that is used for &PRODUCT; system VMs. + Citrix provides you with the necessary binary package of the system VM. 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. @@ -37,8 +37,8 @@ If your secondary storage mount point is not named /mnt/secondary, substitute your own mount point name. If you set the &PRODUCT; 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. + you must now add the parameter -s <management-server-secret-key>. See . This process will require approximately 5 GB of free space on the local file system and up to 30 minutes each time it runs. @@ -57,8 +57,11 @@ - 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. + If you are using a separate NFS server, perform this step. + + Do not perform this step if you are using the Management Server as the NFS + server. + When the script has finished, unmount secondary storage and remove the created directory. # umount /mnt/secondary