Skip to content

Update wazuh.rst to better explain how to use TLS #1105

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 3 commits into
base: stackhpc/2023.1
Choose a base branch
from
Open
Changes from 1 commit
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
29 changes: 25 additions & 4 deletions doc/source/configuration/wazuh.rst
Original file line number Diff line number Diff line change
Expand Up @@ -317,16 +317,37 @@ You will need to create two files matching the following pattern:
- ``{{ dashboard_node_name }}-key.pem`` for the private key
- ``{{ dashboard_node_name }}.pem`` for the certificate

Drop these files into ``$KAYOBE_CONFIG_PATH/environments/<environment>/wazuh/wazuh-certificates/`` if
using the kayobe environments feature, or ``$KAYOBE_CONFIG_PATH/wazuh/wazuh-certificates/`` if not.
The key for the external certificate should be in PKCS#8 format (in its header it may have BEGIN
In order to utilise externally generated certificates, you must first deploy Wazuh Ansible as normal in order to generate the aforementioned certificates; this is because it is unlikely that every Wazuh service will be getting its own custom certificate, especially the ``root`` and ``admin`` certificates. Therefore the ``<...>/wazuh/wazuh-certificates`` directory cannot be manually created as this will result in the Wazuh playbook and ``wazuh-cert-tool.sh`` not generating the remaining non custom certificates.
Custom certificates for Wazuh ``indexer`` may be also be added in a similar way as Wazuh ``dashboard`` by changing the ``indexer_node_name`` such that it's going to match the custom certificate's name.
Once the certificates have been generated a number of steps are required, depending on which set of custom certificates are required to be added or substituted. Regardless, you must ``SSH`` into the ``infra VM`` in which the Wazuh services have been deployed to and, with admin privileges, remove any of the certificates from ``/etc/wazuh-{dashboard | indexer}/certs/`` which are due to be replaced with custom ones. Following this, return to the ``seed`` VM and drop the custom new ``pem`` certificates into ``$KAYOBE_CONFIG_PATH/environments/<environment>/wazuh/wazuh-certificates/`` if
using a kayobe environment, or ``$KAYOBE_CONFIG_PATH/wazuh/wazuh-certificates/`` if not. Finally, rerun the Wazuh Ansible playbook and now the custom certificates should be copied over to their respective directories in the ``infra VM``.

Following this, the ``sudo systemctl status`` for the three Wazuh services should be checked to make sure they are up and running with no errors. Additionally, testing ``sudo filebeat test output`` and trying to ``curl`` the service's IP will also signify if the certificates are working correctly.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
Following this, the ``sudo systemctl status`` for the three Wazuh services should be checked to make sure they are up and running with no errors. Additionally, testing ``sudo filebeat test output`` and trying to ``curl`` the service's IP will also signify if the certificates are working correctly.
Ensure the systemd units for the three Wazuh services are healthy. Additionally, testing ``sudo filebeat test output`` and trying to ``curl`` the service's IP will also signify if the certificates are working correctly.


It should also be noted that the key for the external certificate should be in PKCS#8 format (in its header it may have BEGIN
PRIVATE KEY instead of BEGIN RSA PRIVATE KEY or BEGIN OPENSSH PRIVATE KEY).

Example OpenSSL rune to convert to PKCS#8:

``openssl pkcs8 -topk8 -nocrypt -in wazuh.key -out wazuh.key.pkcs8``

TODO: document how to use a local certificate. Do we need to override all certificates?
.. note::

If you find that your Wazuh playbook isn't generating some of the non custom certificates,
namely the ``indexer`` or ``dashboard`` certificates, it is likely that they aren't being
templated correctly in ``wazuh-cert-tool.sh`` and this could be due to a few reasons but
the variable used to templated into ``wazuh-cert-tool.sh`` is:

.. code-block:: bash

instances:
wazuh:
name: "{{ inventory_hostname }}"
ip: "{{ wazuh_manager_ip }}"
role: indexer

Where ``role`` defines the service which ``wazuh-cert-tool.sh`` will create a certificate for.
This should be defined in ``$KAYOBE_CONFIG_PATH/environments/<environment>/inventory/group_vars/wazuh-manager/wazuh-manager.yml``.

Custom SCA Policies (optional)
------------------------------
Expand Down
Loading