.. Reminder for header structure:
  Parts (H1)          : #################### with overline
  Chapters (H2)       : ******************** with overline
  Sections (H3)       : ====================
  Subsections (H4)    : --------------------
  Subsubsections (H5) : ^^^^^^^^^^^^^^^^^^^^
  Paragraphs (H6)     : """""""""""""""""""""

.. meta::
  :description: WAPT documentation version 2.7 Frequent problems and questions
  :keywords: lost password, lost private key, stolen private key, BIOS bug, waptdeploy, WAPT, documentation, the WAPT Deployment utility

.. _wapt_faq_server:

###################
FAQ - Server Issues
###################


******************************
SSL/TLS certificates and trust
******************************


.. _ca_ssl/tls_renewal_before_expiration:

How can I renew my SSL/TLS Certificate Authority (CA) before expiration?
========================================================================

When replacing a CA certificate before its expiration, the new CA must be deployed to the agents before the WAPT Server starts using the new certificate.

This allows the agents to trust the new certificate while the existing CA is still valid.

.. danger::

   **Important notice for future WAPT Server updates**

   During the next WAPT Server update, ensure that the WAPT agents use the updated certificate rather than the old one. Failure to validate this may result in connectivity issues between the agents and the server.

.. important::

   This procedure is intended for the following certificate transitions:

   - Pinned certificate to pinned certificate, using an internal PKI or a self-signed certificate.
   - Pinned certificate to a commercial certificate.
   - Commercial certificate to a pinned certificate.

   If you are replacing one commercial certificate with another commercial certificate, keeping ``verify_cert = 1`` should be sufficient.

   Test the procedure in a development environment before deploying it to production.

.. white_toggle::
   :titleen: Show solution
   :titlefr: Afficher la solution

   **1. Prepare a test environment**

   Clone the WAPT Server and create a controlled test environment.

   Add the cloned server and a WAPT agent, such as a Windows machine, to the test environment. Ensure that both machines can communicate over the network.

   Install the current WAPT agent from the server on the test machine.

   If the machines are in a workgroup, use the server IP address instead of its FQDN to establish communication. For example:

   .. code-block:: text

      https://10.11.9.70

   Verify that the agent is working correctly:

   - Run ``wapt-get update`` to check package synchronization.
   - Send a test message using ``waptmessage`` to confirm communication.

   Proceed only after these operations succeed.

   **2. Merge the existing and new CA certificates**

   Connect to the WAPT Server and inspect the current certificate file:

   .. code-block:: bash

      cat /opt/wapt/waptserver/ssl/cert.pem

   Identify the current CA certificate at the end of the file.

   Copy the current CA certificate into a text file, for example ``2ca.txt``.

   Open the new CA certificate in a text editor and append its contents to the file.

   Save the resulting file and create a certificate file named ``2ca.crt``.

   **3. Create a configuration package**

   In the WAPT Console, open:

   :guilabel:`WAPT Packages` > :guilabel:`Host agent dynamic configuration`.

   Configure the package as follows:

   - Enter a package name, for example ``prefix-renew_ca-dev``.
   - Set a sufficiently high priority to ensure that the package is applied as intended.
   - Select the ``PROD`` maturity level.
   - Choose the ``Global`` configuration panel.
   - Select :guilabel:`Use specific bundle` and add the new CA file, for example ``wapt/ssl/server/2ca.crt``.
   - Click :guilabel:`Save`.

   .. figure:: wapt-resources/wapt-add-dev-and-new-certificate-ca.png
      :align: center
      :scale: 70%
      :alt: Adding a new CA certificate to a WAPT configuration package

      Adding a new CA certificate to a WAPT configuration package.

   **4. Deploy the configuration package**

   Deploy the configuration package to the test machine.

   Verify that the new CA certificate is present on the agent and that the agent can still communicate with the server.

   Once the procedure has been validated, deploy the package to the rest of your fleet.

   **5. Replace the server certificate**

   Only after all relevant machines have received the new CA should you replace the server certificate.

   Connect to the WAPT Server and open the SSL directory:

   .. code-block:: bash

      cd /opt/wapt/waptserver/ssl/

   Back up the current certificate:

   .. code-block:: bash

      mv cert.pem cert.pem.2025

   Create a new ``cert.pem`` file containing the complete new certificate chain.

   .. code-block:: bash

      vi cert.pem

   If your environment uses an internal PKI or a self-signed certificate and has a separate ``ca_cert.pem`` file, back it up as well:

   .. code-block:: bash

      mv ca_cert.pem ca_cert.pem.2025

   Create a new ``ca_cert.pem`` containing only the new CA certificate.

   Restart Nginx:

   .. code-block:: bash

      systemctl restart nginx.service

   **6. Update the WAPT Console certificate cache**

   When the server starts using the new certificate, the machines may disappear from the WAPT Console because the Console still trusts the old CA.

   The local certificate directory is located at:

   .. code-block:: text

      %LOCALAPPDATA%\waptconsole\ssl\server

   To update the trusted certificate:

   - Remove the old CA certificate file, for example ``xxx.crt``.
   - Copy the merged CA file ``2ca.crt`` into the same directory.
   - Restart the WAPT Console.

   Check that the machines reappear in the inventory. Test package updates and message delivery.

   The CA transition is complete once the agents and the Console communicate successfully using the new certificate.

   **7. Identify machines that have not received the new CA**

   Check for machines that have not communicated with the server recently.

   The following SQL query lists machines that have not been seen for more than 14 days:

   .. code-block:: sql

      SELECT
          uuid,
          computer_name,
          last_seen_on
      FROM
          hosts
      WHERE
          TO_TIMESTAMP(last_seen_on, 'YYYY-MM-DD') <CURRENT_TIMESTAMP - INTERVAL '14 days'
      ORDER BY
          last_seen_on;

   Adjust the interval to match your requirements.

   For information about the reporting tab, see :ref:`wapt_reporting`.

.. _ca_ssl/tls_renewal_after_expiration:

How can I renew an SSL/TLS CA that has already expired?
=======================================================

If the Certificate Authority (CA) has already expired, the agents may no longer be able to establish a trusted connection to the WAPT Server.

There is no single native procedure that automatically restores control of every affected machine. The recovery method depends on the environment and the available management mechanisms.

.. white_toggle::
   :titleen: Show solution
   :titlefr: Afficher la solution

   **Case 1: Machines managed through Active Directory**

   If a significant proportion of the machines belongs to an Active Directory domain, use Group Policy Objects (GPOs) to distribute the new CA certificate and update the WAPT agent configuration.

   **Deploy the new CA certificate**

   Open Group Policy Management and configure the following path:

   :menuselection:`Computer Configuration --> Preferences --> Windows Settings --> Files`

   Use the GPO to copy the new CA certificate to the agent's ``wapt/ssl/server`` directory.

   .. figure:: wapt-resources/copy_crt_by_gpo.png
      :align: center
      :scale: 60%
      :alt: Copying the new CA certificate using a GPO

      Copying the new CA certificate using a GPO.

   **Update the WAPT agent configuration**

   Configure the GPO under:

   :menuselection:`Computer Configuration --> Preferences --> Windows Settings --> INI Files`

   Update the appropriate settings in ``wapt-get.ini`` so that the agent uses the new CA certificate.

   .. figure:: wapt-resources/modify_ini_by_gpo.png
      :align: center
      :scale: 60%
      :alt: Updating the WAPT agent INI configuration using a GPO

      Updating the WAPT agent INI configuration using a GPO.

   This approach allows you to automate the recovery process across domain-joined machines.

   **Case 2: Machines not managed through Active Directory**

   Machines outside Active Directory may require manual intervention.

   First, replace the server certificate with the new certificate and restart Nginx.

   Back up the existing certificate before replacing it:

   .. code-block:: bash

      mv cert.pem cert.pem.2025
      vi cert.pem
      systemctl restart nginx.service

   Ensure that the certificate and private key configuration is correct for your environment. Do not replace or delete a private key unless you have the corresponding replacement key and certificate.

   Next, transfer the new CA certificate to the agent's ``wapt/ssl/server`` directory, for example by using a USB drive.

   Update the ``verify_cert`` setting in ``wapt-get.ini`` to point to the new CA certificate:

   .. code-block:: ini

      verify_cert = C:\Program Files (x86)\wapt\ssl\server\your_new_ca.crt

   Restart the WAPT service and register the agent again:

   .. code-block:: bat

      net stop waptservice
      net start waptservice
      wapt-get register

   Finally, verify that the machine reappears in the WAPT Console and can update packages and send messages.

   This procedure is time-consuming but may be necessary for machines that cannot be managed through Active Directory.

.. hint::

   When replacing one commercial certificate with another commercial certificate, keeping ``verify_cert = 1`` may be sufficient. Validate this behavior in a test environment before deploying the change to production.


.. _error_run_check_cert:

Why does the WAPT agent report a certificate hostname mismatch?
===============================================================

The WAPT agent may report the following error when certificate verification is enabled:

.. code-block:: text

   Certificate CN ### sent by the WAPT Server does not match URL host ###

This means that the certificate's Common Name (CN), or the hostname covered by its Subject Alternative Names (SANs), does not match the hostname used by the agent to connect to the server.

.. white_toggle::
   :titleen: Show solution
   :titlefr: Afficher la solution

   **1. Check the configured server hostname**

   Open the WAPT agent's ``wapt-get.ini`` file and check the value of ``wapt_server``.

   Ensure that the configured hostname matches the hostname covered by the server certificate.

   **2. Check the server certificate**

   If the configured hostname is correct, the certificate may have been generated with an incorrect hostname.

   This can happen if an error occurred during the WAPT Server post-configuration, for example because of a typing mistake.

   **3. Regenerate the self-signed certificates if necessary**

   If the server uses self-signed certificates and the certificate contains the wrong hostname, regenerate the certificates using the correct server FQDN.

   On the WAPT Server, back up the existing SSL directory before making changes.

   The original procedure identifies the following directory:

   .. code-block:: text

      /opt/wapt/waptserver/apache/ssl/

   After backing up the files, remove the obsolete certificate files only if regeneration is required, then rerun the post-configuration script with the same installation arguments and the correct FQDN.

   See :ref:`the wapt postconf <wapt_postconf>` for the post-configuration procedure.

   **4. Retry certificate verification**

   Retry the following command:

   .. code-block:: bash

      wapt-get enable-check-certificate

   Verify that the command completes successfully and that the agent can communicate with the WAPT Server.


**********************************************
WAPT Server availability and disaster recovery
**********************************************


What should I do if my WAPT Server is inoperative?
==================================================

If the WAPT Server is destroyed or becomes unavailable following a fire, flood, hardware failure or another incident, the recovery procedure depends on the urgency and the availability of backups.

.. white_toggle::
   :titleen: Show solution
   :titlefr: Afficher la solution

   **1. Assess the urgency**

   Determine whether immediate action is required.

   - If you need to deploy a package or an urgent update, restoring service is critical.
   - If you do not regularly use WAPT for updates, package deployment or reporting, you may have more time to restore the server.

   **2. Restore from an external backup if available**

   If an external backup solution is available, follow :ref:`backup_server` to recreate the WAPT Server.

   **3. Recreate the WAPT Server if no usable backup is available**

   The following recovery method is intended primarily for environments with an Active Directory and a large number of domain-joined WAPT agents.

   First, create a new WAPT Server:

   - Check the :ref:`server requirements <install_requirements>`.
   - Install the server according to the operating system using :ref:`server_install_index`.
   - Install and configure the WAPT Console using :ref:`installing_the_WAPT_console`.

   **4. Update the WAPT agent configuration using a GPO**

   Before making changes, inspect the existing ``wapt-get.ini`` file on the agents.

   Identify the settings that must change to point the agents to the new server.

   In Group Policy Management, open:

   :menuselection:`Computer Configuration --> Preferences --> Windows Settings --> INI Files`

   Use a GPO to update the relevant parameters in ``wapt-get.ini``.

   .. warning::

      If you use WAPT configuration packages, also check the ``[default-global]`` section and update the settings that refer to the old server.

   .. figure:: wapt-resources/GPO_for_ini_file.png
      :align: center
      :scale: 75%
      :alt: GPO used to update the WAPT agent INI file

      GPO used to update the WAPT agent INI file.

   The example modifies the ``verify_cert`` parameter to pin the new WAPT Server certificate. Other changes may be necessary depending on the configuration.

   Once the GPO has been applied, verify that the agents connect to the new server and reappear in the WAPT inventory.

   **5. Set up regular external backups**

   Configure regular backups stored outside the WAPT Server.

   This allows you to restore the server quickly in the event of another failure.


Why can't the WAPT agents connect after a server recovery?
==========================================================

After rebuilding a WAPT Server, agents may still point to the old server or trust only its certificate.

.. white_toggle::
   :titleen: Show solution
   :titlefr: Afficher la solution

   **1. Check the server address**

   Verify the ``wapt_server`` parameter in ``wapt-get.ini``.

   Make sure that it points to the new server and that the configured hostname resolves to the correct IP address.

   **2. Check the trusted certificate**

   If the server certificate has changed, verify that the agent trusts the new certificate.

   Update ``verify_cert`` and the CA certificate file as required by the certificate configuration.

   **3. Check configuration packages**

   If WAPT configuration packages are used, verify that the ``[default-global]`` section contains the correct server and certificate settings.

   **4. Check communication**

   Once the configuration has been corrected, restart the WAPT service and test package updates and message delivery.


***************************
Reverse proxy configuration
***************************


How should I configure a reverse proxy in front of the WAPT Server?
===================================================================

Reverse proxies that perform TLS interception or TLS termination, including Web Application Firewalls (WAFs), are no longer supported.

A reverse proxy placed in front of the WAPT Server must operate as a simple TLS forwarding proxy based on Server Name Indication (SNI). It must forward the TLS stream without decrypting or inspecting the HTTPS traffic.

With this configuration, TLS processing and certificate verification remain between the client and the WAPT Server.

.. white_toggle::
   :titleen: Show solution
   :titlefr: Afficher la solution

   **1. Configure DNS resolution**

   The WAPT agent resolves the configured server hostname through DNS and connects to the IP address returned.

   The routing decision is therefore made by DNS:

   - On the internal network, internal DNS should resolve the WAPT Server hostname directly to the server's internal IP address, bypassing the reverse proxy.
   - Outside the network, public DNS should resolve the same hostname to the public IP address of the reverse proxy.

   The reverse proxy then forwards the TLS connection to the internal WAPT Server.

   **2. Install the Nginx stream module**

   On the reverse proxy server, ensure that the Nginx stream module is installed.

   - Debian and Ubuntu: ``libnginx-mod-stream``
   - Red Hat and derivatives: ``nginx-mod-stream``

   **3. Configure Nginx stream forwarding**

   Create or edit the following file on the reverse proxy server:

   .. code-block:: text

      /etc/nginx/modules-enabled/80-stream.conf

   Add the following configuration, replacing the hostname and IP address with the values used in your environment:

   .. code-block:: nginx

      stream {
          tcp_nodelay on;

          map $ssl_preread_server_name $https_upstream {
              wapt.mydomain.com 192.168.2.5:443;
          }

          server {
              listen 443;

              resolver 127.0.0.1;

              proxy_pass $https_upstream;
              ssl_preread on;
          }
      }

   In this example, ``192.168.2.5`` is the internal IP address of the WAPT Server.

   Verify that the configuration file is loaded by an appropriate ``include`` directive in ``/etc/nginx/nginx.conf``. Some Nginx installations do not automatically include files from ``modules-enabled``.

   Do not combine this configuration with an HTTP ``server`` block or an HTTP ``default_server`` directive listening on the same address and port. The objective is to forward the raw TLS stream without HTTP-level processing.

   **4. Check the certificate requirements**

   Because the reverse proxy does not terminate TLS, the certificate presented by the WAPT Server is verified by the client.

   The certificate's Common Name (CN) or one of its Subject Alternative Names (SANs) must match the hostname configured in the WAPT agent.

   The certificate must not rely on the reverse proxy's identity.

   **5. Verify the configuration**

   Inspect the logs directly on the WAPT Server, not on the reverse proxy:

   .. code-block:: bash

      tail -f /var/log/nginx/access.log
      tail -f /var/log/nginx/error.log

   Look for requests originating from external clients.

   If external connections do not appear in the WAPT Server logs, check:

   - Public DNS resolution.
   - The reverse proxy's SNI configuration.
   - The forwarding destination and port.
   - Network connectivity between the reverse proxy and the WAPT Server.

.. note::

   A similar configuration can be implemented using HAProxy's TLS passthrough functionality. This configuration is not covered by WAPT support; refer to the HAProxy documentation for details.


******************************************
WAPT Server administration and maintenance
******************************************


How can I reset the WAPT Server SuperAdmin password?
====================================================

If you have forgotten the WAPT Console ``SuperAdmin`` password, you can relaunch the WAPT Server post-configuration process.

.. white_toggle::
   :titleen: Show solution
   :titlefr: Afficher la solution

   **1. Connect to the WAPT Server**

   Connect to the Linux WAPT Server using SSH.

   **2. Obtain administrative privileges**

   Connect as ``root`` or use ``sudo``.

   **3. Relaunch the post-configuration script**

   Run the :ref:`WAPT Server post-configuration script <wapt_postconf>`.

   Follow the prompts to reconfigure the server and reset the relevant administrative settings.


What can go wrong when upgrading the WAPT Server?
=================================================

Several issues may prevent a WAPT Server upgrade from completing successfully.

.. white_toggle::
   :titleen: Show solution
   :titlefr: Afficher la solution

   **1. Antivirus blocks the installation**

   Antivirus software may block the installation or execution of WAPT components.

   WAPT is a software deployment tool that maintains a WebSocket connection to a central management server. This behavior may be flagged as suspicious by some antivirus products.

   If an upgrade fails, check the antivirus management console and its logs.

   If the antivirus is responsible, apply the appropriate exception according to your organization's security policy. In some environments, signing the ``waptagent.exe`` binary with an internal code-signing certificate may also be necessary.

   **2. Another application locks a WAPT DLL**

   Another application may lock a DLL shipped with WAPT.

   This can occur when an installer uses the system ``%PATH%`` variable and loads WAPT's OpenSSL or Python DLLs instead of its own dependencies.

   Check the upgrade logs and identify the process holding the file before retrying the installation.

   **3. Windows scheduled tasks are not working correctly**

   A defective Windows installation or a scheduled-task problem may prevent the upgrade process from running correctly.

   Check the Windows Task Scheduler, the task history and the relevant WAPT logs to identify the failure.


Can the WAPT Server web directory /var/www be relocated to another directory, such as /opt/www?
===============================================================================================

Although some WAPT Server paths can be configured in waptserver.ini, /var/www is still referenced directly by certain WAPT installation scripts and packages. It is therefore not fully supported as a configurable replacement.

.. white_toggle::
   :titleen: Show solution
   :titlefr: Afficher la solution

   Keep /var/www as the expected path and use an fstab mount or a symbolic link to redirect it to the desired storage location, such as /opt/www. This allows the storage to be moved while maintaining compatibility with WAPT.
   to create symbolic link you can see this for `Windows <https://www.it-connect.fr/comment-creer-un-lien-symbolique-sous-windows/>`_ or this for `Linux <https://www.it-connect.fr/creer-un-lien-symbolique-sous-linux/>`_.