USERDOCAP-639 Update High Availability setup section

Change-Id: I8bb01b6232f08c795a109b5d801d8eed2ca79188
Signed-off-by: Toma Bilius <Toma.Bilius@enea.com>

3 files changed, 116 insertions, 116 deletions

diff --git a/doc/book-enea-nfv-access-getting-started/doc/advanced_configurations.xml b/doc/book-enea-nfv-access-getting-started/doc/advanced_configurations.xml
index 74ff1dd..c85f30d 100644
--- a/doc/book-enea-nfv-access-getting-started/doc/advanced_configurations.xml
+++ b/doc/book-enea-nfv-access-getting-started/doc/advanced_configurations.xml
@@ -425,8 +425,8 @@ node0.1048576kB = 3 </programlisting>
     <title>Installing the Enea uCPE Manager in High Availability Mode</title>
 
     <para>The following describes the setup needed for running the Enea uCPE
-    Manager in High Availabilty (HA) mode, with a MariaDB database cluster.
-    The desired setup is depicted in the following diagram:</para>
+    Manager in High Availabilty (HA) mode, with a MariaDB database cluster. A
+    setup example is illustrated in the diagram below.</para>
 
     <figure>
       <title>The High Availability setup</title>
@@ -439,10 +439,32 @@ node0.1048576kB = 3 </programlisting>
       </mediaobject>
     </figure>
 
+    <para>The setup consists of two sub-clusters, placed in different
+    geographical locations. Each sub-cluster contains three MariaDB servers,
+    thus avoiding the split-brain problem. In this example, two of the
+    machines are running only MariaDB, while the rest are hosting a MariaDB
+    server and an Enea uCPE Manager instance. The entire network is hidden behind a
+    firewall that performs NAT. While in protection (cluster) mode, the
+    Enea uCPE Manager instances promote a Virtual IP (VIP) that represents the IP address of the
+    entire cluster. The firewall in this case will allocate a public IP for
+    the outside world that will be translated into the VIP. Also in this
+    example, the traffic towards the cluster from outside the firewall is done
+    through HTTPS, which will be translated to HTTP inside the private
+    network.</para>
+
+    <note>
+      <para>By default, communication to the Enea uCPE Manager is done with HTTPS.
+      To enable HTTP, go to <emphasis role="bold">System</emphasis>, <emphasis
+      role="bold">Configuration</emphasis>, click on the <emphasis
+      role="bold">Web Access</emphasis> tab and check the <emphasis
+      role="bold">Enable HTTP</emphasis> checkbox.</para>
+    </note>
+
     <section id="ha_reqs">
       <title>Requirements for High Availability</title>
-      
-      <para>The following hardware is needed for deploying the base configuration:</para>
+
+      <para>The following hardware is needed for deploying the base
+      configuration:</para>
 
       <itemizedlist>
         <listitem>
@@ -480,39 +502,19 @@ node0.1048576kB = 3 </programlisting>
             </listitem>
           </itemizedlist>
         </listitem>
-
-        <listitem>
-          <para>The Enea uCPE Manager machines should run CentOS 7, this is
-          the only currently supported version.</para>
-        </listitem>
-
-        <listitem>
-          <para>All machines should be on the same subnet. For geographically
-          distributed servers, a VPN can be used.</para>
-        </listitem>
-
-        <listitem>
-          <para>All VCPE devices will typically connect to the external IP
-          (WAN) address (exported by the Big-IP firewall).</para>
-        </listitem>
-
-        <listitem>
-          <para>WAN traffic will be HTTPS, whereas internal communication will
-          be through HTTP.</para>
-        </listitem>
-
-        <listitem>
-          <para>External clients (browsers using the GUI as well as clients
-          using the REST API) will connect to the external (WAN)
-          address.</para>
-        </listitem>
       </itemizedlist>
     </section>
 
     <section id="firewall_rules">
       <title>Firewall Rules</title>
 
-      <para>The following firewall configuration is needed:</para>
+      <para>Please refer to <olink
+      targetdoc="book_enea_nfv_access_getting_started"
+      targetptr="firewall_config">Firewall Configuration in the
+      <ns:include href="../../s_docbuild/olinkdb/pardoc-names.xml"
+      xmlns:ns="http://www.w3.org/2001/XInclude"
+      xpointer="element(book_enea_nfv_access_getting_started/1)" /></olink> Manual.
+      In addition, the following configuration is needed:</para>
 
       <orderedlist>
         <listitem>
@@ -532,8 +534,8 @@ SELINUXTYPE=targeted</programlisting>
       </orderedlist>
 
       <para>The following ports should be opened in the local firewall (not
-      Big-IP), for each Enea uCPE Manager machine:</para>
-
+      the one doing NAT), for each Enea uCPE Manager machine:</para>
+      
       <table>
         <title>Ports for Enea uCPE Manager Machines</title>
 
@@ -552,7 +554,7 @@ SELINUXTYPE=targeted</programlisting>
             <row>
               <entry>80 (TCP)</entry>
 
-              <entry>HTTP (used by Big-IP firewall)</entry>
+              <entry>HTTP</entry>
             </row>
 
             <row>
@@ -588,7 +590,8 @@ SELINUXTYPE=targeted</programlisting>
         </tgroup>
       </table>
 
-      <para>For each MariaDB machine, the following firewall configuration is needed:</para>
+      <para>For MariaDB, the following ports must be opened (on each MariaDB
+      server, including the ones hosting the Enea uCPE Manager):</para>
 
       <table>
         <title>Ports for MariaDB Machines</title>
@@ -633,7 +636,7 @@ SELINUXTYPE=targeted</programlisting>
       </table>
 
       <para>The following ports should be accessible externally and translated
-      to the Virtual IP side as shown below (by the Big-IP firewall):</para>
+      to the Virtual IP side as shown below:</para>
 
       <table>
         <title>Ports for Virtual IP</title>
@@ -683,9 +686,9 @@ SELINUXTYPE=targeted</programlisting>
     <section id="ha_installation">
       <title>Installing High Availability</title>
 
-      <para>The Enea uCPE Manager can be installed in High Availability mode with 
-      a MariaDB database cluster by performing the following steps. The mandatory 
-      Java configuration is also detailed.</para>
+      <para>The Enea uCPE Manager can be installed in High Availability mode
+      with a MariaDB database cluster by performing the following steps. The
+      mandatory Java configuration is also detailed.</para>
 
       <section id="ha_mariadb">
         <title>Installing and configuring the MariaDB cluster</title>
@@ -701,6 +704,27 @@ SELINUXTYPE=targeted</programlisting>
 
         <orderedlist>
           <listitem>
+            <para>Install the MariaDB official yum repository. Create a file
+            named <literal>mariadb.repo</literal> in
+            <literal>/etc/yum.repos.d/</literal> with the following
+            content:<programlisting># MariaDB 10.5 CentOS repository list - created 2021-02-16 08:46 UTC
+# http://downloads.mariadb.org/mariadb/repositories/
+[mariadb]
+name = MariaDB
+baseurl = http://yum.mariadb.org/10.5/centos7-amd64
+gpgkey=https://yum.mariadb.org/RPM-GPG-KEY-MariaDB
+gpgcheck=1
+</programlisting></para>
+
+            <note>
+              <para>For more information about setting the repository,
+              consult <ulink
+  url="https://downloads.mariadb.org/mariadb/repositories/#mirror=nxtHost">Downloads
+  - Setting up MariaDB Repositories</ulink>.</para>
+            </note>
+          </listitem>
+
+          <listitem>
             <para>Make sure the following packages are installed:</para>
 
             <programlisting>MariaDB-compat-10.5.8-1.el7.centos.x86_64
@@ -716,43 +740,43 @@ galera-4-26.4.6-1.el7.centos.x86_64</programlisting>
           <listitem>
             <para>Copy the <literal>wsrep</literal> template:</para>
 
-            <programlisting>[root@localhost ~]# cp /usr/share/mysql/wsrep.cnf /etc/my.cnf.d</programlisting>
+            <programlisting>[root@localhost ~]# cp /usr/share/mysql/wsrep.cnf /etc/my.cnf.d
+            </programlisting>
           </listitem>
 
           <listitem>
-            <para>Change the following configuration:</para>
+            <para>Change the following configuration in 
+              <filename>/etc/my.cnf.d/wsrep.cnf</filename>:</para>
 
             <programlisting># Full path to wsrep provider library or 'none'
-wsrep_provider=/usr/lib64/galera-4/libgalera_smm.so
+<emphasis role="bold">wsrep_provider=/usr/lib64/galera-4/libgalera_smm.so</emphasis>
 
 # Provider specific configuration options
 #wsrep_provider_options=
 
 # Logical cluster name. Should be the same for all nodes.
-wsrep_cluster_name="ucpemanager"
+<emphasis role="bold">wsrep_cluster_name="ucpemanager"</emphasis>
 
 # Group communication system handle
-wsrep_cluster_address="gcomm://192.168.10.11,192.168.10.12,..,192.168.10.16"
+<emphasis role="bold">wsrep_cluster_address="gcomm://192.168.10.11,192.168.10.12,..,192.168.10.16"</emphasis>
 
 # Human-readable node name (non-unique). Hostname by default.
-wsrep_node_name=Node1  
-# current node's name. set node name for each server in the cluster
+<emphasis role="bold">wsrep_node_name=Node1</emphasis> # current node's name. set node name for each server in the cluster
 
 # Base replication &lt;address|hostname&gt;[:port] of the node.
 # The values supplied will be used as defaults for state transfer receiving,
 # listening ports and so on. Default: address of the first network interface.
-wsrep_node_address=192.168.10.11 
-#current node's interface IP . must be set for each node in the cluster</programlisting>
+<emphasis role="bold">wsrep_node_address=192.168.10.11</emphasis> #current node's interface IP . must be set for each node in the cluster</programlisting>
 
             <note>
-              <para>Steps 2 and 3 must be performed for each MariaDB node in
-              the cluster.</para>
+              <para>Steps 2, 3 and 4 must be performed for each MariaDB node
+              in the cluster.</para>
             </note>
           </listitem>
 
           <listitem>
-            <para>Bootstrap the first node in the cluster (identified by
-            <literal>Node1</literal> for example), by running:</para>
+            <para>Bootstrap the first node in the cluster (referred to as
+            <literal>Node1</literal> in this example), by running:</para>
 
             <programlisting>[root@localhost ~]# galera_new_cluster</programlisting>
 
@@ -796,30 +820,30 @@ MariaDB [(none)]&gt; show status like 'wsrep_cluster_conf_%';
 
             <programlisting>[root@localhost ~]# mysql_secure_installation
 
-Switch to unix_socket authentication [Y/n] Y
+Switch to unix_socket authentication [Y/n] <emphasis role="bold">Y</emphasis>
 Enabled successfully!
 Reloading privilege tables..
  ... Success!
 …
-Change the root password? [Y/n] Y
+Change the root password? [Y/n] <emphasis role="bold">Y</emphasis>
 New password: 
 Re-enter new password: 
 Password updated successfully!
 Reloading privilege tables..
  ... Success!
 …
-Remove anonymous users? [Y/n] Y
+Remove anonymous users? [Y/n] <emphasis role="bold">Y</emphasis>
  ... Success!
 …
-Disallow root login remotely? [Y/n] Y
+Disallow root login remotely? [Y/n] <emphasis role="bold">Y</emphasis>
  ... Success!
 …
-Remove test database and access to it? [Y/n] Y (optional)
+Remove test database and access to it? [Y/n] <emphasis role="bold">Y (optional)</emphasis>
  - Dropping test database...
  ... Success!
  - Removing privileges on test database...
  ... Success!
-Reload privilege tables now? [Y/n] Y
+Reload privilege tables now? [Y/n] <emphasis role="bold">Y</emphasis>
  ... Success!
 
 Cleaning up...
@@ -847,54 +871,21 @@ TO 'enea'@'%' IDENTIFIED BY 'somepassword' WITH GRANT OPTION;</programlisting>
       <section id="ha_java_sdk_install">
         <title>Installing the Java SDK</title>
 
-        <para>The following steps describe the installation of Java 11 SDK on
-        the CentOS 7 machines that will run the Enea uCPE Manager
-        installation:</para>
-
-        <orderedlist>
-          <listitem>
-            <para>Install the following packages:</para>
-
-            <programlisting>java-11-openjdk-devel-11.0.10.0.9-0.el7_9.x86_64
-java-11-openjdk-11.0.10.0.9-0.el7_9.x86_64</programlisting>
-          </listitem>
-
-          <listitem>
-            <para>Check that java points to the current JRE:</para>
-
-            <programlisting>root@localhost ~]# java -version
-openjdk version "11.0.10" 2021-01-19 LTS
-OpenJDK Runtime Environment 18.9 (build 11.0.10+9-LTS)
-OpenJDK 64-Bit Server VM 18.9 (build 11.0.10+9-LTS, mixed mode, sharing)</programlisting>
-
-            <para>If it doesn't, then check the alternatives, and make sure
-            that java points to the JDK11 installation:</para>
-
-            <programlisting>[root@localhost ~]# alternatives --config java</programlisting>
-          </listitem>
-
-          <listitem>
-            <para>Set the <literal>JAVA_HOME</literal> environment variable
-            and update paths:</para>
-
-            <programlisting>export JAVA_HOME=$(dirname $(dirname $(readlink $(readlink $(which javac)))))
-export PATH=$PATH:$JAVA_HOME/bin
-export CLASSPATH=.:$JAVA_HOME/jre/lib:$JAVA_HOME/lib:$JAVA_HOME/lib/tools.jar</programlisting>
-
-            <para>As an alternative, the variables can be written into the
-            <filename>.bashrc</filename> file, so that they load every time a
-            console is opened. To enable these settings for all users, add the
-            variables to <literal>/etc/environment</literal>.</para>
-          </listitem>
-
-          <listitem>
-            <para>The <literal>JAVA_HOME</literal> variable should point
-            to:</para>
-
-            <programlisting>[root@localhost ~]# echo $JAVA_HOME
-/usr/lib/jvm/java-11-openjdk-11.0.10.0.9-0.el7_9.x86_64</programlisting>
-          </listitem>
-        </orderedlist>
+        <para>Please refer to <olink
+        targetdoc="book_enea_nfv_access_getting_started"
+        targetptr="openjdk_postgresql_config">Configuring OpenJDK and
+        PostgreSQL in the <ns:include
+        href="../../s_docbuild/olinkdb/pardoc-names.xml"
+        xmlns:ns="http://www.w3.org/2001/XInclude"
+        xpointer="element(book_enea_nfv_access_getting_started/1)" /></olink> 
+          Manual, for details on how to install and configure Java OpenJDK.</para>
+        
+        <para>Make sure the <literal>JAVA_HOME</literal> variable points to the 
+          OpenJDK 11 installation:</para>
+
+        <programlisting>[root@localhost ~]# echo $JAVA_HOME
+/usr/lib/jvm/java-11-openjdk-11.0.10.0.9-0.el7_9.x86_64
+</programlisting>
       </section>
 
       <section id="ha_ucpe_mg">
@@ -902,7 +893,8 @@ export CLASSPATH=.:$JAVA_HOME/jre/lib:$JAVA_HOME/lib:$JAVA_HOME/lib/tools.jar</p
         mode</title>
 
         <para>These steps must be taken on each of the CentOS 7 machines that
-        will host the Enea uCPE Manager.</para>
+        will host the Enea uCPE Manager. The Enea uCPE Manager will be installed 
+        and the setup for the external database cluster will be prepared.</para>
 
         <para>As the root user, go to the distribution folder of the Enea uCPE
         Manager, and run:</para>
@@ -911,12 +903,12 @@ export CLASSPATH=.:$JAVA_HOME/jre/lib:$JAVA_HOME/lib:$JAVA_HOME/lib/tools.jar</p
 Enea_NFV_Access_uCPEManager_2.3.0-build23.tar.gz
 This will install uCPEManager into /opt/ucpemanager folder.
 Select the following options, while asked by the installation script:
-Are you using the embedded PostgreSQL database? [Y/N]: N
+Are you using the embedded PostgreSQL database? [Y/N]: <emphasis role="bold">N</emphasis>
 External database selected, getting user information ...
 Press 1 for PostgreSQL, 2 for MariaDB, 3 for SQL Server, 4 for Oracle and 5 \
-for MySQL: 2
+for MySQL: <emphasis role="bold">2</emphasis>
 Specify database server name(s) or IP Address(es): \
-192.168.10.11,192.168.10.12,…,192.168.10.16 *(see note)
+<emphasis role="bold">192.168.10.11,192.168.10.12,…,192.168.10.16 *(see note)</emphasis>
 Specify database ID (or name) [ucpemanager]: 
 Specify database server port [3306]: 
 Specify database user name [root]: enea
@@ -930,10 +922,10 @@ Installing ucpemanager service ..
 Specify service username [ucpemanager]: 
 Specify service password [ucpemanager]: somepassword
 …
-Specify the IP address of the local interface: 192.168.10.11
-Is this server part of a cluster? [Y/N]: Y
+Specify the IP address of the local interface: <emphasis role="bold">192.168.10.11</emphasis>
+Is this server part of a cluster? [Y/N]: <emphasis role="bold">Y</emphasis>
 Specify the name of the cluster [ucpemanager]: 
-Specify the shared (virtual) cluster IP address: 192.168.10.10
+Specify the shared (virtual) cluster IP address: <emphasis role="bold">192.168.10.10</emphasis>
 Specify the netmask for the cluster IP address [255.255.255.0]: 
 HA Configuration files modified successfully.
 Configuration complete.</programlisting>
@@ -963,8 +955,8 @@ Configuration complete.</programlisting>
 
       <orderedlist>
         <listitem>
-          <para>We start with the assumption that
-          <literal>ucpeManager-1</literal>is the "PRIMARY" server.</para>
+          <para>We start with the assumption that <literal>ucpeManager-1
+          </literal>is the "PRIMARY" server.</para>
         </listitem>
 
         <listitem>
diff --git a/doc/book-enea-nfv-access-getting-started/doc/images/high_av_setup.png b/doc/book-enea-nfv-access-getting-started/doc/images/high_av_setup.png
index e2edd67..23cc973 100644
--- a/doc/book-enea-nfv-access-getting-started/doc/images/high_av_setup.png
+++ b/doc/book-enea-nfv-access-getting-started/doc/images/high_av_setup.png
diff --git a/doc/book-enea-nfv-access-getting-started/doc/upgrade_ena.xml b/doc/book-enea-nfv-access-getting-started/doc/upgrade_ena.xml
index 2f5801c..1b714f2 100644
--- a/doc/book-enea-nfv-access-getting-started/doc/upgrade_ena.xml
+++ b/doc/book-enea-nfv-access-getting-started/doc/upgrade_ena.xml
@@ -1,4 +1,4 @@
-<?xml version="1.0" encoding="ISO-8859-1"?>
+<?xml version="1.0" encoding="UTF-8"?>
 <chapter id="upgrade_ena">
   <title>Upgrading Enea NFV Access</title>
 
@@ -71,6 +71,14 @@ Enea_NFV_Access_uCPEManager_&lt;version&gt;-build&lt;build_number&gt;.tar.gz</pr
       </listitem>
     </itemizedlist>
 
+    <para>For an example on how to upgrade an Enea uCPE Manager installation in a
+    High Availability setup, consult <olink
+    targetdoc="book_enea_nfv_access_getting_started"
+    targetptr="ha_upgrade">Upgrading a High Availability Deployment in the
+    <ns:include href="../../s_docbuild/olinkdb/pardoc-names.xml"
+    xpointer="element(book_enea_nfv_access_getting_started/1)"
+    xmlns:ns="http://www.w3.org/2001/XInclude" /></olink> Manual.</para>
+
     <section id="restore_prev_ucpe_install">
       <title>Restoring a previous Enea uCPE Manager Installation</title>