Merge pull request #6920 from wazuh/wp-1422-improve-offline-documenta…

…tion-4.9 Added offline installation with the assistant
wazuh · Jan 8, 2024 · 7035ece · 7035ece
2 parents 5eee608 + 533cee0
commit 7035ece
Show file tree

Hide file tree

Showing 5 changed files with 310 additions and 152 deletions.
diff --git a/source/_static/js/redirects.js b/source/_static/js/redirects.js
@@ -65,8 +65,34 @@ removedUrls['x.y'] = [
 
 /* *** RELEASE 4.9 ****/
 
+/* Redirections from 4.8 to 4.9  */
+
+redirections.push(
+  {
+    'target': ['4.8=>4.9', '4.9=>4.8'],
+    '4.8': '/deployment-options/offline-installation.html',
+    '4.9': '/deployment-options/offline-installation/index.html',
+  },
+  {
+    'target': ['4.9=>4.8'],
+    '4.8': '/deployment-options/offline-installation.html',
+    '4.9': '/deployment-options/offline-installation/step-by-step.html',
+  },
+);
+
+/* Pages added in 4.9 */
+
 newUrls['4.9'] = [
   '/release-notes/release-4-9-0.html',
+  '/deployment-options/offline-installation/index.html',
+  '/deployment-options/offline-installation/step-by-step.html',
+  '/deployment-options/offline-installation/installation-assistant.html',
+];
+
+/* Pages no longer available in 4.9 */
+
+removedUrls['4.9'] = [
+  '/deployment-options/offline-installation.html',
 ];
 
 /* *** RELEASE 4.8 ****/

diff --git a/source/deployment-options/index.rst b/source/deployment-options/index.rst
@@ -38,7 +38,7 @@ All the alternatives include instructions on how to install the :doc:`Wazuh cent
 
     <h3>Offline</h3>
 
-- :doc:`offline-installation`: Installing the solution offline involves downloading the Wazuh components to later install them on a system with no internet connection. 
+- :doc:`offline-installation/index`: Installing the solution offline involves downloading the Wazuh components to later install them on a system with no internet connection. 
 
 
 .. raw:: html
@@ -158,7 +158,7 @@ These alternatives guide you to install the Wazuh central components along with
     amazon-machine-images/amazon-machine-images
     docker/index 
     deploying-with-kubernetes/index
-    offline-installation
+    offline-installation/index
     wazuh-from-sources/index
     deploying-with-ansible/index
     deploying-with-puppet/index
diff --git a/source/deployment-options/offline-installation/index.rst b/source/deployment-options/offline-installation/index.rst
@@ -0,0 +1,77 @@
+.. Copyright (C) 2015, Wazuh, Inc.
+
+.. meta::
+  :description: Discover the offline step-by-step process to install the Wazuh central components without connection to the Internet.
+
+Offline installation
+====================
+
+You can install Wazuh even when there is no connection to the Internet. Installing the solution offline involves downloading the Wazuh central components to later install them on a system with no Internet connection. The Wazuh server, the Wazuh indexer, and the Wazuh dashboard can be installed and configured on the same host in an all-in-one deployment, or each component can be installed on a separate host as a distributed deployment, depending on your environment needs. 
+
+For more information about the hardware requirements and the recommended operating systems, check the :ref:`Requirements <installation_requirements>` section.
+
+.. note:: You need root user privileges to run all the commands described below.
+
+Prerequisites
+-------------
+
+- ``curl``, ``tar``, and ``setcap`` need to be installed in the target system where the offline installation will be carried out. ``gnupg`` might need to be installed as well for some Debian-based systems.
+
+- In some systems, the command ``cp`` is an alias for ``cp -i`` — you can check this by running ``alias cp``. If this is your case, use ``unalias cp`` to avoid being asked for confirmation to overwrite files.
+
+Download the packages and configuration files
+---------------------------------------------
+
+#. Run the following commands from any Linux system with Internet connection. This action executes a script that downloads all required files for the offline installation on x86_64 architectures. Select the package format to download.
+
+   .. tabs::
+
+        .. group-tab:: RPM
+
+            .. code-block:: console
+        
+               # curl -sO https://packages.wazuh.com/|WAZUH_CURRENT_MINOR|/wazuh-install.sh
+               # chmod 744 wazuh-install.sh
+               # ./wazuh-install.sh -dw rpm
+
+        .. group-tab:: DEB
+
+            .. code-block:: console
+        
+               # curl -sO https://packages.wazuh.com/|WAZUH_CURRENT_MINOR|/wazuh-install.sh
+               # chmod 744 wazuh-install.sh
+               # ./wazuh-install.sh -dw deb
+          
+#. Download the certificates configuration file.
+
+      .. code-block:: console
+        
+         # curl -sO https://packages.wazuh.com/|WAZUH_CURRENT_MINOR|/config.yml
+
+#. Edit ``config.yml`` to prepare the certificates creation.
+
+   -  If you are performing an all-in-one deployment, replace ``"<indexer-node-ip>"``, ``"<wazuh-manager-ip>"``, and ``"<dashboard-node-ip>"`` with ``127.0.0.1``.
+
+   -  If you are performing a distributed deployment, replace the node names and IP values with the corresponding names and IP addresses. You need to do this for all the Wazuh server, the Wazuh indexer, and the Wazuh dashboard nodes. Add as many node fields as needed.
+
+
+#.  Run the ``./wazuh-install.sh -g`` to create the certificates. For a multi-node cluster, these certificates need to be later deployed to all Wazuh instances in your cluster.
+
+    .. code-block:: console
+    
+        # ./wazuh-install.sh -g            
+
+#. Copy or move ``wazuh-offline.tar.gz`` and ``wazuh-install-files.tar`` files to a folder accessible to the host(s) from where the offline installation will be carried out. This can be done by using ``scp``.
+
+
+Next steps
+----------
+
+Once the Wazuh files are ready and copied to the specified hosts, it is necessary to install the Wazuh components.
+
+
+.. toctree::
+  :maxdepth: 1
+
+  installation-assistant
+  step-by-step
diff --git a/source/deployment-options/offline-installation/installation-assistant.rst b/source/deployment-options/offline-installation/installation-assistant.rst
@@ -0,0 +1,122 @@
+Install Wazuh components using the assistant
+--------------------------------------------
+
+Install and configure the different Wazuh components with the aid of the Wazuh installation assistant. 
+
+.. note:: You need root user privileges to run all the commands described below.
+
+Please, make sure that a copy of the ``wazuh-install-files.tar`` and ``wazuh-offline.tar.gz`` files, created during the initial configuration step, is placed in your working directory.
+
+Installing the Wazuh indexer
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Install and configure the Wazuh indexer nodes. 
+
+
+#. Run the assistant with the ``--offline-install`` to perform an offline installation. Use the option ``--wazuh-indexer`` and the node name to install and configure the Wazuh indexer. The node name must be the same one used in ``config.yml`` for the initial configuration, for example, ``node-1``.
+
+   .. code-block:: console
+
+      # bash wazuh-install.sh --offline-install --wazuh-indexer node-1 
+
+   Repeat this step for every Wazuh indexer node in your cluster. Then proceed with initializing your single-node or multi-node cluster in the next step.
+
+#. Run the Wazuh installation assistant with option ``--start-cluster`` on any Wazuh indexer node to load the new certificates information and start the cluster. 
+
+   .. code-block:: console
+ 
+      # bash wazuh-install.sh --start-cluster
+ 
+   .. note:: You only have to initialize the cluster `once`, there is no need to run this command on every node. 
+
+Testing the cluster installation
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+#. Run the following command to get the *admin* password:
+
+   .. code-block:: console
+
+      # tar -axf wazuh-install-files.tar wazuh-install-files/wazuh-passwords.txt -O | grep -P "\'admin\'" -A 1
+
+#. Run the following command to confirm that the installation is successful. Replace ``<ADMIN_PASSWORD>`` with the password gotten from the output of the previous command. Replace ``<WAZUH_INDEXER_IP>`` with the configured Wazuh indexer IP address:
+
+   .. code-block:: console
+
+      # curl -k -u admin:<ADMIN_PASSWORD> https://<WAZUH_INDEXER_IP>:9200
+
+   .. code-block:: none
+      :class: output
+
+      {
+        "name" : "node-1",
+        "cluster_name" : "wazuh-cluster",
+        "cluster_uuid" : "095jEW-oRJSFKLz5wmo5PA",
+        "version" : {
+          "number" : "7.10.2",
+          "build_type" : "rpm",
+          "build_hash" : "db90a415ff2fd428b4f7b3f800a51dc229287cb4",
+          "build_date" : "2023-06-03T06:24:25.112415503Z",
+          "build_snapshot" : false,
+          "lucene_version" : "9.6.0",
+          "minimum_wire_compatibility_version" : "7.10.0",
+          "minimum_index_compatibility_version" : "7.0.0"
+        },
+        "tagline" : "The OpenSearch Project: https://opensearch.org/"
+      }
+
+#. Replace ``<WAZUH_INDEXER_IP>`` and ``<ADMIN_PASSWORD>``, and run the following command to check if the cluster is working correctly:
+
+   .. code-block:: console
+
+      # curl -k -u admin:<ADMIN_PASSWORD> https://<WAZUH_INDEXER_IP>:9200/_cat/nodes?v
+
+Installing the Wazuh server
+^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+#. Run the assistant with the ``--offline-install`` to perform an offline installation. Use the option ``--wazuh-server`` followed by the node name to install the Wazuh server. The node name must be the same one used in ``config.yml`` for the initial configuration, for example, ``wazuh-1``.
+
+   .. code-block:: console
+  
+      # bash wazuh-install.sh --offline-install --wazuh-server wazuh-1
+
+Your Wazuh server is now successfully installed. 
+
+-  If you want a Wazuh server multi-node cluster, repeat this step on every Wazuh server node.
+-  If you want a Wazuh server single-node cluster, everything is set and you can proceed directly with the next stage.
+
+Installing the Wazuh dashboard
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+#. Run the assistant with the ``--offline-install`` to perform an offline installation. Use the option ``--wazuh-dashboard`` and the node name to install and configure the Wazuh dashboard. The node name must be the same one used in ``config.yml`` for the initial configuration, for example, ``dashboard``.
+
+   .. code-block:: console
+
+      # bash wazuh-install.sh --wazuh-dashboard dashboard
+
+   The default Wazuh web user interface port is 443, used by the Wazuh dashboard. You can change this port using the optional parameter ``-p|--port <port_number>``. Some recommended ports are 8443, 8444, 8080, 8888, and 9000.
+
+   Once the assistant finishes the installation, the output shows the access credentials and a message that confirms that the installation was successful.
+
+   .. code-block:: none
+      :emphasize-lines: 3,4          
+    
+      INFO: --- Summary ---
+      INFO: You can access the web interface https://<wazuh-dashboard-ip>
+         User: admin
+         Password: <ADMIN_PASSWORD>
+
+      INFO: Installation finished.
+
+   You now have installed and configured Wazuh. All passwords generated by the Wazuh installation assistant can be found in the ``wazuh-passwords.txt`` file inside the ``wazuh-install-files.tar`` archive. To print them, run the following command:
+
+   .. code-block:: console
+   
+      # tar -O -xvf wazuh-install-files.tar wazuh-install-files/wazuh-passwords.txt
+
+#. Access the Wazuh web interface with your credentials. 
+
+   -  URL: *https://<wazuh-dashboard-ip>*
+   -  **Username**: *admin*
+   -  **Password**: *<ADMIN_PASSWORD>*
+
+   When you access the Wazuh dashboard for the first time, the browser shows a warning message stating that the certificate was not issued by a trusted authority. An exception can be added in the advanced options of the web browser. For increased security, the ``root-ca.pem`` file previously generated can be imported to the certificate manager of the browser instead. Alternatively, a certificate from a trusted authority can be configured.