4. FAQ - Agent Issues¶

4.1. Private key management¶

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

Show solution

1. Generate a new private key and public certificate

Follow the procedure described in Generate a new 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: C:Program Files (x86)ssl

  • Linux and macOS: /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:

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

Show 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: C:Program Files (x86)ssl

  • Linux and macOS: /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 a 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.

4.2. Host registration and deployment¶

4.2.1. Why does host registration fail with a connection error?¶

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

FATAL ERROR : ConnectionError: HTTPSConnectionPool(host='XXX.XXX.XXX.XXX', port=443): Max retries exceeded with url: /add_host
Show 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 wapt-get register again.

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

Show solution

There are two ways to address this issue.

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

We recommend adding waptdeploy.exe to the startup and shutdown scripts as described in Deploying the WAPT Agent using a GPO.

Option 2: Configure Windows to wait for the network

Enable the following Group Policy setting:

Computer Configuration ‣ Administrative Templates ‣ System ‣ Logon ‣ Always wait for the network at computer startup and logon

GPO to wait network startup

GPO to wait network startup¶

4.3. WAPT Exit execution issues¶

4.3.1. Why does WAPT Exit not run when the computer shuts down?¶

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

Show 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 wapt-get.ini file, as described in WAPT Agent configuration options.

You can also configure this setting when creating the WAPT Agent.

A WAPT package is available to disable hybrid shutdown:

tis-disable-hybrid-shutdown.

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 C:Program Files (x86)waptwapt-get.exe with the argument upgrade.

Case 3: Repair corrupted local Group Policy settings

Local security policies may become corrupted. To repair them:

  1. Delete the file C:WindowsSystem32GroupPolicygpt.ini.

  2. Restart the computer.

  3. Reinstall the shutdown scheduled tasks by running:

    wapt-get add-upgrade-shutdown

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

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

Show solution

Option 1: Increase the WAPT Agent timeout values

In the WAPT Agent’s wapt-get.ini file, increase the values of pre_shutdown_timeout and max_gpo_script_wait.

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

max_gpo_script_wait = 360
pre_shutdown_timeout = 360

See WAPT Agent configuration options for details.

To modify the WAPT Agent configuration, use the Host Agent Dynamic configuration package and open Advanced Editing to locate and modify the two parameters mentioned above.

WAPT Agent timeout values for GPO

WAPT Agent timeout values for GPO¶

Option 2: Configure the script execution timeout through a GPO

You can also use a GPO with a File.ini configuration.

Using a GPO ini File to configured the script execution delay

Using a GPO ini File to configured the script execution delay¶

4.4. WAPTWUA issues¶

4.4.1. How to remove a KB using WAPTWUA¶

Show solution

First, check whether Microsoft allows the KB to be uninstalled.

In the WAPT Console, go to Inventory, select the computer, and open the Windows Update tab. Right-click the table header and select Show/Hide Columns > Uninstallable.

If the value is False, Microsoft does not allow the update to be uninstalled through the standard Windows Update mechanism.


You can nevertheless try to uninstall the KB :

  • In the wua tab right-clicking the KB and selecting Trigger the uninstall of selected Windows Updates.

  • If the uninstallation fails, you can use the following script. Create a package using an empty package and add the script below (don’t forget to personalize the KB).

# -*- coding: utf-8 -*-
from setuphelpers import *
import re
import subprocess

def install():
   for u in installed_softwares("KB0000001"):
         guids = re.findall(r"\{[0-9A-Fa-f-]{36}\}", u["key"])

         if len(guids) < 2:
            continue

         product_guid = guids[0]
         patch_guid = guids[-1]

         print("PRODUCT =", product_guid)
         print("PATCH   =", patch_guid)

         subprocess.run([
            r"C:\Windows\System32\msiexec.exe",
            "/package", product_guid,
            "/uninstall", patch_guid,
            "/qn",
            "/norestart",
            "REBOOT=ReallySuppress"
         ])