.. 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_agent:

##################
FAQ - Agent Issues
##################

**********************
Private key management
**********************

.. _lost_private_key:

Why do I need to replace a lost WAPT private key?
=================================================

WAPT security and correct operation rely on private keys and their associated public certificates.

If a private key is lost, you must generate a new key and its associated certificates, deploy the new certificates to the organization's computers, and re-sign the packages in the repositories.

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

   **1. Generate a new private key and public certificate**

   Follow the procedure described in :ref:`Generate a new certificate <create_certificate>`.

   Store the private key (``.pem`` file) in a secure location.

   **2. Deploy the new public certificate to client computers**

   Deploy the new ``.crt`` certificate manually, using a GPO (Group Policy Object), or using an Ansible role (not documented).

   Copy the certificate to the ``ssl`` folder on each client:

   - Windows: :file:`C:\Program Files (x86)\ssl`
   - Linux and macOS: :file:`/opt/wapt/ssl`

   **3. Re-sign the packages in the repositories**

   Packages in the repositories were signed using the former private key. You **MUST** re-sign every package using the new key.

   You can do this:

   - :ref:`Using the WAPT Console <re_sign_package_gui>`
   - :ref:`Using the command line <re_sign_package_cmd>`


Why must I act immediately if my WAPT private key has been stolen?
==================================================================

WAPT security relies on protecting private keys. If a private key is stolen, certificates associated with it can no longer be considered trustworthy.

WAPT does not currently support key revocation through a CRL (Certificate Revocation List).

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

   **1. Remove the certificates associated with the stolen key**

   Delete every ``.crt`` certificate associated with the stolen private key from the ``ssl`` folder:

   - Windows: :file:`C:\Program Files (x86)\ssl`
   - Linux and macOS: :file:`/opt/wapt/ssl`

   You can perform this operation manually, using a GPO, using a WAPT package, or using an Ansible role (not documented).

   **2. Generate and deploy replacement certificates**

   Follow the same procedure as for :ref:`a lost private key <lost_private_key>`.

   This includes generating a new key pair, deploying the new public certificate to client computers, and re-signing the packages in the repositories.


********************************
Host registration and deployment
********************************


Why does host registration fail with a connection error?
========================================================

When you run :command:`wapt-get register`, the command may return the following error:

.. code-block:: text

   FATAL ERROR : ConnectionError: HTTPSConnectionPool(host='XXX.XXX.XXX.XXX', port=443): Max retries exceeded with url: /add_host

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

   **1. Check port forwarding**

   Make sure that TCP port 443 is correctly forwarded to the WAPT Server.

   **2. Check firewall rules**

   Verify that no firewall between the client and the WAPT Server blocks TCP port 443.

   **3. Retry host registration**

   Once connectivity has been restored, run :command:`wapt-get register` again.


Why does Windows start the computer before the network is ready?
================================================================

By default, Windows does not wait for the network to be available when the computer starts.

This can prevent the WAPT Deployment utility from retrieving the new WAPT Agent because network connectivity is not yet available.

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

   There are two ways to address this issue.

   **Option 1: Add waptdeploy.exe to the startup and shutdown scripts**

   We recommend adding :file:`waptdeploy.exe` to the startup and shutdown scripts as described in :ref:`Deploying the WAPT Agent using a GPO <deploy_waptagent_with_GPO>`.

   **Option 2: Configure Windows to wait for the network**

   Enable the following Group Policy setting:

   :menuselection:`Computer Configuration --> Administrative Templates --> System --> Logon --> Always wait for the network at computer startup and logon`

   .. figure:: wapt-resources/wapt_deploy_gpo-wait-network_browser-window.png
      :align: center
      :scale: 75%
      :alt: GPO to wait network startup

      GPO to wait network startup


**************************
WAPT Exit execution issues
**************************


Why does WAPT Exit not run when the computer shuts down?
========================================================

Even when the shutdown script is registered in the local security policy, the :program:`waptexit` script may fail to run when the computer shuts down.

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

   **Case 1: Disable Windows hybrid shutdown**

   Windows 10 hybrid shutdown **MUST** be disabled because it can cause problems that prevent WAPT Exit from running during shutdown.

   Configure the relevant setting in the WAPT Agent's :file:`wapt-get.ini` file, as described in :ref:`WAPT Agent configuration options <waptexit_ini_file_options>`.

   You can also configure this setting when :ref:`creating the WAPT Agent <create_WAPT_agent>`.

   A WAPT package is available to disable hybrid shutdown:

   `tis-disable-hybrid-shutdown <https://store.wapt.fr/store/tis-disable-hybrid-shutdownt>`_.

   **Case 2: Check whether the computer runs Windows Home**

   Local security policies are not available on Windows Home editions. As a result, the shutdown script may not run.

   As a workaround, create a scheduled task that runs :file:`C:\Program Files (x86)\wapt\wapt-get.exe` with the argument :code:`upgrade`.

   **Case 3: Repair corrupted local Group Policy settings**

   Local security policies may become corrupted. To repair them:

   1. Delete the file :file:`C:\Windows\System32\GroupPolicy\gpt.ini`.
   2. Restart the computer.
   3. Reinstall the shutdown scheduled tasks by running:

      .. code-block:: bash

         wapt-get add-upgrade-shutdown

   If the issue occurs again, another application may be modifying the local Group Policy settings.


Why does WAPT Exit stop after 15 minutes without finishing package installation?
================================================================================

By default, Windows allows shutdown scripts to run for only 15 minutes. If a script does not finish within this time, Windows interrupts it.

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

   **Option 1: Increase the WAPT Agent timeout values**

   In the WAPT Agent's :file:`wapt-get.ini` file, increase the values of :code:`pre_shutdown_timeout` and :code:`max_gpo_script_wait`.

   For example, use the following values to allow a longer execution period:

   .. code-block:: ini

      max_gpo_script_wait = 360
      pre_shutdown_timeout = 360

   See :ref:`WAPT Agent configuration options <waptexit_ini_file_options>` for details.

   The WAPT package `tis-wapt-conf-policy <https://store.wapt.fr/store/tis-wapt-conf-policy>`_ can apply this configuration.

   **Option 2: Configure the script execution timeout through a GPO**

   You can also use a GPO with a :file:`File.ini` configuration.

   .. figure:: wapt-resources/wapt_deploy_gpo-ini-file_dialog-box.png
      :align: center
      :scale: 75%
      :alt: Using a GPO ini File to configured the script execution delay

      Using a GPO ini File to configured the script execution delay
