CLOUDSTACK-400: documening procedure to update MySQL password. Also added a few xrefs in other documents that were missing them.

docs/en-US/about-password-encryption.xml

@@ -54,8 +54,8 @@
     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
+    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.</para>
   <para>The encryption type, database secret key, and Management Server secret key are set during

docs/en-US/change-database-config.xml

@@ -24,5 +24,5 @@
 
 <section id="change-database-config">
     <title>Changing the Database Configuration</title>
-    <para>The &PRODUCT; Management Server stores database configuration information (e.g., hostname, port, credentials) in the file /etc/cloud/management/db.properties.  To effect a change, edit this file on each Management Server, then restart the Management Server.</para> 
-</section>
+    <para>The &PRODUCT; Management Server stores database configuration information (e.g., hostname, port, credentials) in the file <filename>/etc/cloud/management/db.properties</filename>. To effect a change, edit this file on each Management Server, then restart the Management Server.</para> 
+</section>

docs/en-US/change-database-password.xml

@@ -0,0 +1,74 @@
+<?xml version='1.0' encoding='utf-8' ?>
+<!DOCTYPE section PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
+<!ENTITY % BOOK_ENTITIES SYSTEM "cloudstack.ent">
+%BOOK_ENTITIES;
+]>
+
+<!-- Licensed to the Apache Software Foundation (ASF) under one
+ or more contributor license agreements.  See the NOTICE file
+ distributed with this work for additional information
+ regarding copyright ownership.  The ASF licenses this file
+ to you under the Apache License, Version 2.0 (the
+ "License"); you may not use this file except in compliance
+ with the License.  You may obtain a copy of the License at
+ 
+   http://www.apache.org/licenses/LICENSE-2.0
+ 
+ Unless required by applicable law or agreed to in writing,
+ software distributed under the License is distributed on an
+ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ KIND, either express or implied.  See the License for the
+ specific language governing permissions and limitations
+ under the License.
+-->
+
+<section id="change-database-password">
+    <title>Changing the Database Password</title>
+    <para>You may need to change the password for the MySQL account used by CloudStack. If so, you'll need to change the password in MySQL, and then add the encrypted password to <filename>/etc/cloud/management/db.properties</filename>.</para> 
+    <listitem>
+        <para>Before changing the password, you'll need to stop CloudStack's management server and the usage engine if you've deployed that component.</para>
+<screen>
+<command># service cloud-management stop</command>
+<command># service cloud-usage stop</command>
+</screen>
+    </listitem>
+    <listitem>
+        <para>Next, you'll update the password for the CloudStack user on the MySQL server.</para>
+<screen>
+<command># mysql -u root -p</command>
+</screen>
+        <para>At the MySQL shell, you'll change the password and flush privileges:</para>
+<screen>
+<command>update mysql.user set password=PASSWORD("newpassword123") where User='cloud';</command>
+<command>flush privileges;</command>
+<command>quit;</command>
+</screen>
+    </listitem>
+    <listitem>
+        <para>The next step is to encrypt the password and copy the encrypted password to CloudStack's database configuration (<filename>/etc/cloud/management/db.properties</filename>).</para>
+<screen>
+<command># java -classpath /usr/share/java/cloud-jasypt-1.8.jar \
+org.jasypt.intf.cli.JasyptPBEStringEncryptionCLI encrypt.sh \ 
+input="newpassword123" password="`cat /etc/cloud/management/key`" \
+verbose=false 
+</command>
+</screen>
+<note><title>File encryption type</title>
+    <para>Note that this is for the file encryption type. If you're using the web encryption type (see <xref linkend="about-password-encryption" />) then you'll use <command>password="management_server_secret_key"</command></para>
+</note>
+</listitem>
+<listitem>
+    <para>Now, you'll update <filename>/etc/cloud/management/db.properties</filename> with the new ciphertext. Open <filename>/etc/cloud/management/db.properties</filename> in a text editor, and update these parameters: </para>
+    <programlisting>
+db.cloud.password=ENC(encrypted_password_from_above) 
+db.usage.password=ENC(encrypted_password_from_above) 
+</programlisting>
+</listitem>
+<listitem>
+    <para>After copying the new password over, you can now start CloudStack (and the usage engine, if necessary).</para>
+    <screen>
+        <command># service cloud-management start</command>
+        <command># service cloud-usage start</command>
+    </screen>
+</listitem>
+</section>

docs/en-US/manage-cloud.xml

@@ -26,7 +26,8 @@
   <title>Managing the Cloud</title>
   <xi:include href="tagging-resources.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
   <xi:include href="change-database-config.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
+  <xi:include href="change-database-password.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
   <xi:include href="admin-alerts.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
   <xi:include href="customizing-dns.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
   <xi:include href="stop-restart-management-server.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
-</chapter>
+</chapter>

docs/en-US/management-server-install-systemvm.xml

@@ -37,8 +37,7 @@
       <para>If your secondary storage mount point is not named /mnt/secondary, substitute your own
         mount point name.</para>
       <para>If you set the &PRODUCT; database encryption type to "web" when you set up the database,
-        you must now add the parameter -s &lt;management-server-secret-key&gt;. See About Password
-        and Key Encryption.</para>
+          you must now add the parameter -s &lt;management-server-secret-key&gt;. See <xref linkend="about-password-encryption" />.</para>
       <para>This process will require approximately 5 GB of free space on the local file system and
         up to 30 minutes each time it runs.</para>
       <itemizedlist>