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

#####################
FAQ - Packages Issues
#####################

*******************************************
Conflict between Wapt configuration and GPO
*******************************************

Some :abbr:`GPOs (Group Policy Objects)` that are enforced by the Domain Controler may conflict configuration strategies enforced by WAPT.

Basically, what will happen is that one policy will recurrently reset the other policy. If WAPT audit scripts are checking such configuration options, audits will constantly flutter between **|OK|** and **|ERROR|**.

As a general rule of thumb, if you have the WAPT Enterprise version which implements **audit**, your will get your best results using WAPT to enforce policies for the following 3 reasons :

* There may be a difference between which :abbr:`OUs (Organizational Units)` the Active Directory shows in the standard :abbr:`RSAT (Remote Server Administration Tool)` console and where the end-point really knows it is in the Active Directory tree. This explains in good part why sometimes you think you are applying a GPO on a host of a OU, and then you observe that the policy has not applied on the host or some members of a OU. The WAPT agent knows exactly which OUs the device is a member of.

* There is no native way with Windows to report on whether GPOs have correctly applied or not. When using WAPT to configure policies, using the audit function in the WAPT configuration package is a simple way to ensure that the policy has been correctly applied. The policy will appear in the WAPT Console as **|OK|** or **|ERROR|**. If you use :code:`print()` statements in your audit script, you can then know where and why your configuration has failed.

* Finally, configuration GPOs that embed confidential information such as identifiers and password may be easily intercepted by a threat actor. :ref:`WAPT includes a simple method that allows to encrypt sensitive data that can then only be deciphered by the destination endpoint <encryting_sensitive_data_in_package>`.

Therefore, we recommand using WAPT configuration packages instead of GPOs to deploy policies to your fleets, whenever possible.

*****************************************************************************************************************
I have deployed a software package on an organisation unit (OU), but I would like to exclude certain workstations 
*****************************************************************************************************************

Unfortunately, due to **OU inheritance**. If a package is in dependency or conflict, it is **not possible to exclude certain machines natively**.

In this situation, it you remain two solutions :

**1/ Manual Installation**: If you want the package installed only on specific workstations within the OU, you must remove it from the OU-level deployment and install it manually on the targeted machines.

**2/ Using a meta-package**: Alternatively, you can create a meta-package that includes custom logic to target or exclude specific machines. This approach allows you to bypass the limitations of OU inheritance. You can find more information on how to create a meta-package :ref:`here <meta-package>`.

***************************************
Installation that needs a system reboot
***************************************

* You may need to install an application that implies a system reboot.

.. white_toggle::
  :titleen: Here is a code example that lets you do it:
  :titlefr: Voici un exemple de code qui vous permet de le faire :

  .. code-block:: python

    from setuphelpers import *

    def install():
        last_boot = str(host_metrics()['last_bootup_time']).rsplit('.',1)[0]
        file_last_bootup_time = r'C:\last_bootup_time'


        if not isfile(file_last_bootup_time):
            print('first time installation is executed')
            
          # Insert here the code to be executed before the reboot.

            with open(file_last_bootup_time,'w') as f:
                f.write(last_boot)
            return "NEEDREBOOT"


        else:

            with open(file_last_bootup_time,'r') as f:
                data = f.read()

            if data == last_boot:
                print("Install already executed but system has not rebooted")
                return "NEEDREBOOT"
            else:
                print("Install already executed and system rebooted, I can continue")
                
                # Insert here the code to be executed after the reboot.


************************************************
Updating WAPT packages from Python 2 to Python 3
************************************************

.. _python2to3:

.. attention::

  With WAPT 2.0, the WAPT internals have switched to python3.
  WAPT packages **MUST** follow the new python3 syntax.

.. list-table:: The principal syntax differences
  :header-rows: 1
  :widths: 80, 10, 10

  * - Syntax
    - Python 2
    - Python 3
  * - print
    - :code:`print'Hello'`
    - :code:`print('Hello')`
  * - unicode string
    - :code:`ur`
    - :code:`r`
  * - operators
    - :code:`<> <=> !=`
    - :code:`!=`
  * - Windows registry access
    - :code:`_winreg`
    - :code:`winreg`

.. hint::

  For more details, visit:

  * https://python-future.org/compatible_idioms.html.

  * https://blog.couchbase.com/tips-and-tricks-for-upgrading-from-python-2-to-python-3/.

*********************************************
Wapt service crashes during install or remove
*********************************************

Some customers have reported wapt service crashes. 

When we dug deeper, we realised that these were caused by Bitdefender prohibiting the execution of Powershell.
As a result, Bitdefender was shutting down the wapt server process.

This can be extended to all antivirus programs. **Stay vigilant**.

*************************************
Problems when creating a WAPT package
*************************************

Problems with access rights and PyScripter
==========================================

When trying to install a package from :program:`PyScripter`, if the following message appears:

.. image:: wapt-resources/windows_pyscripter_read-only-install-package_dialog-box.png
  :align: center
  :alt: OperationnalError: attempt to write a read-only database

Launch :program:`PyScripter` using a :term:`Local Administrator` account and redo the desired action.

.. _package_too_big:

The WAPT package is too big and I can not upload it on the repository
=====================================================================

A message "Stream write error" can appear if you lack disk space on the machine that imports the package. Indeed, much space is needed because the package is first extracted, then signed, built and finally uploaded to the server (3 times the package size is needed). In that case, please apply the following procedure.

When a package is too big, it is necessary to build the WAPT package locally then to upload it with :program:`WinSCP` or an equivalent utility.

* Build the WAPT package with :program:`PyScripter` or manually :ref:`build the package <build_package>`.

.. hint::

  The WAPT package in :file:`C:\\waptdev`.

* Download and install :program:`WinSCP`

* Using :program:`WinSCP`, upload the WAPT package in the correct :ref:`repository location <repository_location>` according to the version of the WAPT repository.

* Once the upload has finished, recreate the :file:`Packages` index file on the WAPT repository using the following command and remplacing **repository** by the :ref:`repository location <repository_location>` according to the version of the WAPT repository.

.. code-block:: bash

  wapt-scanpackages repository

Unable to create a file
=======================

.. figure:: wapt-resources/wapt-unable_to_create_file.png
  :align: center
  :alt: Unable to create a file

  WAPT - unable to create a file


You can try to clean the cache here :  **Appdata\local\waptconsole\cache**.

Access violation error while re-signing a WAPT package
======================================================

.. image:: wapt-resources/wapt_console_package-resign-error_screen-item.png
  :align: center
  :alt: Signature processing has not ended successfully

If the **Access violation** error appear, it may mean that the WAPT package is too big.

Manually edit the package and visit :ref:`this procedure for signing large WAPT packages <package_too_big>`.

WAPT package in error
=====================

.. _common_problems_installing_a_package:

Problem installing a WAPT package
---------------------------------

I have a WAPT package that returns in error and the software is not installed on the computer when I physically go to check on the computer.

Explanation
^^^^^^^^^^^

An error has occurred during the execution of the :file:`setup.py`.

You can read and analyze error messages returned in the WAPT Console and try to understand and solve them.

The installation of the package will be retried at each :command:`upgrade` cycle until the package does not return an error.

Solution
^^^^^^^^

* If WAPT returns an error code, research the error code on the Internet.

  Example for a MSI: *1618*: another installation in already running.
  Restarting the computer should solve the problem.

.. note::

  MSI error codes are available by visiting `this website <https://docs.microsoft.com/en-us/windows/win32/msi/windows-installer-error-messages?redirectedfrom=MSDN>`_.

* Go to the computer and try to install the package with the WAPT command line utility.
  Then check that the software has installed.

.. attention::

  Once the silent installation has finished, do nothing else.

  The objective is to reproduce the behavior of the WAPT Agent.

* If the package installs silently in user context, this may mean that the software installer does not work in *SYSTEM* context.

* If it is still not working, launch the installation manually.
  It is possible for an error to appear explicitly describing the problem (ex: missing dependency, etc).

* It is possible that the installer does not support installing over an older version of the software, so you will have to explicitly
  remove older versions of the application before installing the new one.

Error "timed out after seconds with output '600.0'"
---------------------------------------------------

Some packages return the following error in the WAPT Console:

.. code-block:: bash

  "Error timed out after seconds with output '600.0'"

Explanation
^^^^^^^^^^^

By default, when installing a WAPT package embedding a :command:`run` and a :command:`install_msi_if_needed` command, WAPT will wait 600 seconds for the installer to finish its task.

If the installer has not finished in this delay, WAPT will stop the running installation.

Solution
^^^^^^^^

If the software to be installed is known to be big (Microsoft Office, Solidworks, LibreOffice, Katia, Adobe Creative Suite), it is possible that the 600 second delay will be too short.

You will have to increase the timeout value, ex: :code:`timeout` = ``1200``.

.. code-block:: bash

  run('"setup.exe" /adminfile office2010noreboot.MSP', timeout = 1200)

Error "has been installed but the uninstall key can not be found"
-----------------------------------------------------------------

Some WAPT packages return the following error in the WAPT Console:

.. code-block:: bash

  XXX has been installed but the uninstall key can not be found.

Explanation
^^^^^^^^^^^

WAPT relies on Windows to install :mimetype:`.msi` binaries with :code:`install_msi_if_needed` and :mimetype:`.exe` binaries with :command:`install_exe_if_needed`.

By default, WAPT accepts return codes *0* (OK) and *3010* (computer restart required) and it verifies that the *uninstall key* is present.

Unfortunately, we can not fully trust these return codes, so WAPT does additional checks after completing the installation to make sure that all has gone well:

* It checks the presence of the *uninstall key* on the host.

* It checks that the version number of the software is equal or greater than the version number in the :file:`control` file.

* If this is not the case, it infers that the software may not be present on the host.

The function returns the WAPT package in error.
The installation will be retried at every *upgrade* cycle until the WAPT package returns no error.

Solution
^^^^^^^^

.. attention::

  Before doing anything, it is advisable to go physically to the computer returning in error and to **manually check whether the software has correctly installed**.
  If the software has not installed correctly, refer to the :ref:`section of this documentation on installing a package <common_problems_installing_a_package>`.

* If the software has installed correctly, this may mean that the uninstall key or the software version in the package is not correct.

* Retrieve the correct *uninstall key* and make changes to the WAPT package accordingly.

* If the error happens when using the :code:`install_msi_if_needed` function, this means that the MSI installer is badly packaged and that it is returning an incorrect *uninstall key*.

Error "has been installed and the uninstall key found but version is not good"
------------------------------------------------------------------------------

Some WAPT packages return the following error in the WAPT Console:

.. code-block:: bash

  XXX has been installed and the *uninstall key* found but version is not good.

Explanation
^^^^^^^^^^^

When using :code:`install_msi_if_needed` or :code:`install_exe_if_needed` functions, additional checks are performed to make sure that all has gone well.

.. attention::

  Before doing anything, it is advisable to go physically to the computer returning in error and to **manually check whether the software has correctly installed**.
  If the software has not installed correctly, refer to the :ref:`section of this documentation on installing a package <common_problems_installing_a_package>`.

Solution: with ``install_msi_if_needed``
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

The informations being extracted from the MSI installer, this means that the MSI file does not return correct values or that the *uninstall key* is incorrect.

You can check using the Windows Command Line utility.

.. code-block:: bash

   wapt-get list-registry

If the returned key is not that which has been entered in the install section of the :file:`setup.py`, it is not possible to use :code:`install_msi_if_needed`.

You **MUST** review the install section of your :file:`setup.py`, use the :code:`run()` function and manually manage exceptions.

Solution: with ``install_exe_if_needed``
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

This probably means that the version number entered in the :program:`install_exe_if_needed` function is not correct.
Make corrections to the WAPT package accordingly.

.. note::

  If the :code:`min_version` argument has not been entered, WAPT will try to retrieve the version automatically from the :mimetype:`.exe` installer.

You can check the *uninstall key* and the version number using the command:

.. code-block:: bash

   wapt-get list-registry

If no version is provided with the :command:`wapt-get list-registry` command, this means that the software installer does not provide an *uninstall key*.

There are **2** solutions:

* Use the argument :code:`get_version` to provide the path to another :code:`uninstallkey`.

.. code-block:: python

   def install():

      def versnaps2(key):
          return key['name'].replace('NAPS2 ','')

      install_exe_if_needed('naps2-5.3.3-setup.exe',silentflags='/VERYSILENT',key='NAPS2 (Not Another PDF Scanner 2)_is1',get_version=versnaps2)

* Providing an empty value for :code:`min_version` tells WAPT not to check for versions.

.. code-block:: ini

  min_version=' '

.. attention::

  With this method, **versions are no longer checked during updates!**

Error "DNSName values should be passed as an A-label string"
------------------------------------------------------------

.. code-block:: bash
  
  FATAL ERROR : ValueError: DNSName values should be passed as an A-label string. This means unicode characters should be encoded via a library like idna.

Ensure that your workstation name does not contain any special characters.
