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

.. meta::
  :description: 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
##################


.. _lost_private_key:

**************************
I lost my WAPT private key
**************************

WAPT security and its correct functioning rely on sets of private keys and public certificates.

Losing a private key thus requires to :ref:`generate a new key <create_certificate>` and its associated certificates, and then to deploy the new keys and the new certificates on the Organization's computers.

Therefore, losing a key bears some consequences, the process to recover from a lost key is not trivial, although it is relatively simple.

Generating or renewing a private key
====================================

The procedure is:

* :ref:`Generate a new private key/ public certificate <create_certificate>`.
  You will then keep the private key (file :mimetype:`.pem`) in a safe location;

* Deploy, manually, using a :abbr:`GPO (Group Policy Object)` or using an Ansible role (not documented), the new certificate :mimetype:`.crt` on your clients in the **ssl** folder.

  * :file:`C:\\Program Files (x86)\\ssl` on Windows;

  * :file:`/opt/wapt/ssl` on Linux and macOS.

Re-signing packages in the repositories
=======================================

WAPT packages hosted on the repositories were signed using the former private key, so you **MUST** re-sign every package of the repository using the new key:

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

******************************
My private key has been stolen
******************************

.. attention::

  **WAPT security relies on protecting your private keys.**

WAPT does not handle key revocation yet using a :abbr:`CRL (Certificate Revocation List)`.

The solution consists in deleting every :mimetype:`.crt` certificate associated to the stolen private key, located in the **ssl** folder:

* :file:`C:\\Program Files (x86)\\ssl` on Windows;

* :file:`/opt/wapt/ssl` on Linux and macOS.

That operation can be done using a GPO, manually, with a WAPT package or with an Ansible role (not documented).

Finally, you will have to follow the same steps as for :ref:`the loss of your private key <lost_private_key>`.

******************************************
Problems with registering a host with WAPT
******************************************

If you do a :command:`wapt-get register` and it returns:

.. code-block:: bash

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

You need to check that the 443 port is correctly forwarded to the WAPT Server and not blocked by a firewall.

**************************************************************
Windows does not wait for the network to be running on startup
**************************************************************

By default Windows does not wait for the network to be up at computer startup.

This can cause problems during the WAPT Deployment utility execution because the WAPT Deployment utility requires network connectivity to retrieve the new WAPT Agent.

There are **2** solutions:

1. We recommend adding :file:`waptdeploy.exe` to the startup and shutdown scripts :ref:`on the GPO <deploy_waptagent_with_GPO>`.

2. You can enable the GPO: **Always wait for the network at computer startup and logon** with :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

*************************************
The WAPT Exit utility will not launch
*************************************

Despite the script actually being registered in the local security shutdown strategy, the :program:`waptexit` script does not launch at computer shutdown.

Hybrid shutdown
===============

Windows 10 hybrid shutdown **MUST** be disabled because it causes many problems and strange behaviors, disabling Hybrid Shutdown will restore the WAPT Exit script execution at shutdown.

Hybrid shutdown can be disabled by setting a value in :file:`wapt-get.ini` file :ref:`of the WAPT Agent <waptexit_ini_file_options>`.

It is possible to set this value when :ref:`creating the WAPT Agent <create_WAPT_agent>`.

A WAPT package exists to solve the Hybrid Shutdown problem: `tis-disable-hybrid-shutdown <https://store.wapt.fr/store/tis-disable-hybrid-shutdownt>`_.

Windows Home edition
====================

Local security policies are not available when using a Windows Home edition computer, so it is normal that the script will not launch.

The workaround consists in using a scheduled task that will launch :file:`C:\\Program Files (x86)\\wapt\\wapt-get.exe` with the argument :code:`upgrade`.

Corrupted local GPO
===================

It sometimes happens that local security policies on a computer are corrupted.

One of the possible solutions is to:

* Remove local security strategies by deleting the file :file:`C:\\Windows\\System32\\GroupPolicy\\gpt.ini`;

* Restart the computer;

* Re-install the shutdown scheduled tasks with:

.. code-block:: bash

  wapt-get add-upgrade-shutdown

If the problem occurs again, this may mean that another application also manipulates the local GPO.

*********************************************************************************************
The WAPT Exit utility halts after 15 minutes and does not finish installing the WAPT packages
*********************************************************************************************

By default, Windows shutdown scripts are only allowed to run for 15 minutes.

If a script has not finished before that limit, Windows will interrupt the script.

To solve that problem, increase the :code:`pre_shutdown_timeout` value and the :code:`max_gpo_script_wait` value in the :file:`wapt-get.ini` file of the WAPT Agent.

Define :ref:`these values <waptexit_ini_file_options>` to change the default behavior.

.. code-block:: ini

  max_gpo_script_wait = 360
  pre_shutdown_timeout = 360

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

The other solution may be to use the GPO :file:`File.ini`.

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