1. Frequent problems and questions¶
1.1. WAPT Server behind a reverse proxy¶
Attention
The support of reverse proxy (WAF, etc.) doing TLS interceptions or TLS terminaison is no longer supported. If you have a reverse proxy in front of the WAPT server, it has to be configured as a simple TLS forwarding proxy based on SNI (cf. ngx_stream_core_module on nginx server for example).
First you need to check if the stream module package (libnginx-mod-stream on Debian/Ubuntu, nginx-mod-stream on RedHat and derivatives) is installed on the NginX Reverse Proxy server.
Then you can insert the following content into /etc/nginx/modules-enabled/80-stream.conf of the NginX Reverse Proxy server:
stream {
tcp_nodelay on;
map $ssl_preread_server_name $https_upstream {
wapt.mydomain.com 192.168.2.5:443; # 192.168.2.5 is the local IP address of the WAPT server
}
server {
listen 443;
resolver 127.0.0.1;
proxy_pass $https_upstream;
ssl_preread on;
}
}
Similar configuration is possible using HAProxy TLS Passthrough module but we do not provide support. Please refer to the corresponding documentation for details.
1.2. Updating WAPT packages from Python 2 to Python 3¶
Attention
With WAPT 2.0, the WAPT internals have switched to python3. WAPT packages MUST follow the new python3 syntax.
Syntax |
Python 2 |
Python 3 |
---|---|---|
|
|
|
unicode string |
|
|
operators |
|
|
Windows registry access |
|
|
Hint
For more details, visit:
1.3. Resetting the WAPT Linux Server password¶
It sometimes happens to setup a WAPT Server and then forget its password.
To reset the WAPT Console SuperAdmin password you have to relaunch the post-configuration process on the WAPT Server:
Connect to the WAPT Server with SSH.
Connect with user root (or use sudo).
Launch the post-configuration script.
1.4. 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 generate a new key 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.
1.4.1. Generating or renewing a private key¶
The procedure is:
Generate a new private key/ public certificate. You will then keep the private key (file .pem) in a safe location;
Deploy, manually, using a GPO or using an Ansible role (not documented), the new certificate .crt on your clients in the ssl folder.
C:\Program Files (x86)\ssl
on Windows;/opt/wapt/ssl
on Linux and macOS.
1.4.2. 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:
Using the WAPT Console, or
1.5. My private key has been stolen¶
Attention
WAPT security relies on protecting your private keys.
WAPT does not handle key revocation yet using a CRL.
The solution consists in deleting every .crt certificate associated to the stolen private key, located in the ssl folder:
C:\Program Files (x86)\ssl
on Windows;/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 the loss of your private key.
1.6. My BIOS UUID bugs¶
Some problems happen sometimes with some BIOSes. WAPT uses the UUID of the host as the host identifier.
The UUID is supposed to be unique. Unfortunately, for some OEMs and some manufacturing batches, BIOS UUID are identical.
The host will register in the WAPT Console but it will replace an existing device, considering that the host has only changed its name.
1.6.1. Solving the BIOS UUID issue¶
WAPT allows to generate a random UUID to replace the one retrieved from the BIOS.
wapt-get generate-uuid
The WAPT Agent FQDN may be used instead of the UUID.
In the wapt-get.ini
configuration file, define in the [global] section:
use_fqdn_as_uuid = True
1.7. The WAPT Deploy utility does not work¶
The the WAPT Deployment utility does not succeed in installing the WAPT agent.
1.7.1. Launching the WAPT Deployment utility locally¶
Launching the WAPT Deployment utility locally can be a good method for showing errors explicitly.
Attention
You MUST launch the command prompt using a Local Administrator account.
Example of command to launch:
C:\Program Files (x86)\wapt\waptdeploy.exe --hash=2a9971aad083d6822b6e4d1ccfb9886be9429ec58bb13246810ff3d6a56ce887 --minversion=2.1.0.10550 --wait=15 --waptsetupurl=https://srvwapt.mydomain.lan/wapt/waptagent.exe
In our case the hash for the WAPT Deploy utility is not correct.
1.7.1.1. The WAPT Deploy utility works manually but does not work with GPO¶
Check that port 8088 is listening correctly on the host:
gpresult /h gpo.html & gpo.html
To force the application of the GPO:
gpupdate /force
If the WAPT Deployment utility does not show up you will have to double check the GPO settings:
You may be using an old WAPT Deployment utility version, then
download the latest version
of the WAPT Deployment utility from the WAPT Server web page.Thanks to Emmanuel EUGENE from French public research institution INSERM who submitted this possible cause for the WAPT Deployment utility not functioning properly, if you are replicating domain controllers, ensure that the GPOs are correctly synchronized between your DCs and that ACLs are identically applied on the
Sysvol
directories.
1.8. 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:
We recommend adding
waptdeploy.exe
to the startup and shutdown scripts on the GPO.You can enable the GPO: Always wait for the network at computer startup and logon with
1.9. The WAPT Exit utility will not launch¶
Despite the script actually being registered in the local security shutdown strategy, the waptexit script does not launch at computer shutdown.
1.9.1. 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 wapt-get.ini
file of the WAPT Agent.
It is possible to set this value when creating the WAPT Agent.
A WAPT package exists to solve the Hybrid Shutdown problem: tis-disable-hybrid-shutdown.
1.9.2. 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 C:\Program Files (x86)\wapt\wapt-get.exe
with the argument upgrade
.
1.9.3. 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
C:\Windows\System32\GroupPolicy\gpt.ini
;Restart the computer;
Re-install the shutdown scheduled tasks with:
wapt-get add-upgrade-shutdown
If the problem occurs again, this may mean that another application also manipulates the local GPO.
1.10. 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 pre_shutdown_timeout
value and the max_gpo_script_wait
value in the wapt-get.ini
file of the WAPT Agent.
Define these values to change the default behavior.
max_gpo_script_wait = 360
pre_shutdown_timeout = 360
The WAPT package tis-wapt-conf-policy sets this configuration.
The other solution may be to use the GPO File.ini
.
1.11. Error message when opening the WAPT Console¶
1.11.1. Version check¶
The WAPT Console version is not the same as the version of the WAPT Server. Upgrading the WAPT Console to the same version of the WAPT Server is the recommanded course of action.
1.11.2. Connection refused¶
The WAPT Console can not contact the WAPT Server on port 443:
Check whether the Nginx web service is running on the WAPT Server.
systemctl status nginx
If Nginx is not running, restart the Nginx service.
systemctl restart nginx
If Nginx still does not start, you will need to analyze the journal logs in:
/var/log/nginx/
on Linux;C:\Program Files (x86)\wapt\waptserver\nginx\logs
on Windows.
1.11.4. Error connecting with SSL … verify failed¶
The WAPT Console seems not to be able to verify the WAPT Server’s HTTPS certificate.
Attention
Before doing anything, be sure that your are not facing a MITM attack!
Note
If you have just rebuilt your WAPT Server and that you use a self-signed certificate, you can recover the old keys of your old WAPT Server in /opt/wapt/waptserver/apache/ssl
.
Close your WAPT Console.
Delete the folder
%appdata%\..\Local\waptconsole
.Launch the command
wapt-get enable-check-certificate
.Be sure that the previous command has gone well.
Restart the WAPT service with
net stop waptservice && net start waptservice
.Restart the WAPT Console.
In case you do not use the certificate pinning method, this tells you that the certificate sent by the WAPT Server can not be verified with the python certifi bundle of certificates. Be sure to have the full chain of certificates on the WAPT Server.
1.11.5. I can’t do anything in the WAPT Console, everything is greyed¶
The WAPT Console seems locked, you can not execute any action, everything is greyed.
If you are connected with another user than the Superadmin, the ACL rules applied to your profile may not be set properly.
To fix this, close the WAPT Console and open it with the Superadmin account. Then, go to
. Here, you will see the user in the list, give the user the appropriate permissions, then save and close the WAPT Console. Re-open the WAPT Console using your login.1.12. Error message about package on the WAPT Console¶
1.12.1. Error when uploading package¶
The WAPT Console shows this error : Error when uploading package : EWaptForbidden('Host matching package UUID_HOST does not trusted signer certificate)
.
You have this error when you try to upload a WAPT package but the used certificate which signed package is not present in your computer’s ssl WAPT install location folder. Be reminded, if you have a WAPT Server running on Windows to not lauch the WAPT Console on the server. Add the WAPT certificate which signed the package in your computer’s ssl WAPT install location folder then retry.
1.12.2. Error locale¶
The WAPT Console shows this error in two situations.
1.12.2.1. Package does not exist in the repository anymore, yet a host needs it¶
There are two possible solutions:
Try to get package anew from Tranquil IT’s store.
Delete the package from the host dependencies.
1.12.2.2. When you try to install a package with a locale that is unknown to the host¶
There are two possible solutions:
Download the WAPT package having the matching locale from Tranquil IT’s store.
Edit your WAPT package and set in the
control
file the optionlocale
with the correct locale (locale=en,fr
).
1.13. Problems with registering a host with WAPT¶
If you do a wapt-get register and it returns:
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.
1.14. Problems when enabling enable-check-certificate¶
1.14.1. Message “Certificate CN ### sent by the WAPT Server does not match URL host ###”¶
This means that the CN in the certificate sent by the WAPT Server does not match the value of the wapt_server
attribute in the wapt-get.ini
file of the WAPT Agent.
There are 2 solutions:
Check the value of
wapt_server
in thewapt-get.ini
file of the WAPT Agent.
If the value is correct, this surely means that an error has happened during the generation of the self-signed certificate during the WAPT Server post-configuration (typing error, …).
You MUST then regenerate your self-signed certificates.
On the WAPT Server, delete the content of the
/opt/wapt/waptserver/apache/ssl/
folder.
Then, relaunch the post-configuration script (the same as the one used during initial installation, with the same arguments and values).
Then, be sure that the value of FQDN for the WAPT Server is correct.
You may now retry enable-check-certificate.
1.15. Problems when creating a WAPT package¶
1.15.1. Problems with access rights and PyScripter¶
When trying to install a package from PyScripter, if the following message appears:
Launch PyScripter using a Local Administrator account and redo the desired action.
1.15.2. The WAPT package is too big and I can not upload it on the repository¶
When a package is too big, it is necessary to build the WAPT package locally then to upload it with WinSCP or an equivalent utility.
Build the WAPT package with PyScripter or manually build the package.
Hint
The WAPT package in C:\waptdev
.
Download and install WinSCP
Using WinSCP, upload the WAPT package in the correct repository location according to the version of the WAPT repository.
Once the upload has finished, recreate the
Packages
index file on the WAPT repository using the following command and remplacing repository by the repository location according to the version of the WAPT repository.
wapt-scanpackages repository
1.15.3. Access violation error while re-signing a WAPT package¶
If the Access violation error appear, it may mean that the WAPT package is too big.
Manually edit the package and visit this procedure for signing large WAPT packages.
1.15.4. WAPT package in error¶
1.15.4.1. 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.
1.15.4.1.1. Explanation¶
An error has occurred during the execution of the 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 upgrade cycle until the package does not return an error.
1.15.4.1.2. 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.
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.
1.15.4.2. Error “timed out after seconds with output ‘600.0’”¶
Some packages return the following error in the WAPT Console:
"Error timed out after seconds with output '600.0'"
1.15.4.2.1. Explanation¶
By default, when installing a WAPT package embedding a run and a 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.
1.15.4.2.2. 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: timeout
= 1200
.
run('"setup.exe" /adminfile office2010noreboot.MSP', timeout = 1200)
1.15.4.3. Error “has been installed but the uninstall key can not be found”¶
Some WAPT packages return the following error in the WAPT Console:
XXX has been installed but the uninstall key can not be found.
1.15.4.3.1. Explanation¶
WAPT relies on Windows to install .msi binaries with install_msi_if_needed
and .exe binaries with 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
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.
1.15.4.3.2. 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 section of this documentation on 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
install_msi_if_needed
function, this means that the MSI installer is badly packaged and that it is returning an incorrect uninstall key.
1.15.4.4. 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:
XXX has been installed and the *uninstall key* found but version is not good.
1.15.4.4.1. Explanation¶
When using install_msi_if_needed
or 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 section of this documentation on installing a package.
1.15.4.4.2. 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.
wapt-get list-registry
If the returned key is not that which has been entered in the install section of the setup.py
, it is not possible to use install_msi_if_needed
.
You MUST review the install section of your setup.py
, use the run()
function and manually manage exceptions.
1.15.4.4.3. Solution: with install_exe_if_needed
¶
This probably means that the version number entered in the install_exe_if_needed function is not correct. Make corrections to the WAPT package accordingly.
Note
If the min_version
argument has not been entered, WAPT will try to retrieve the version automatically from the .exe installer.
You can check the uninstall key and the version number using the command:
wapt-get list-registry
If no version is provided with the wapt-get list-registry command, this means that the software installer does not provide an uninstall key.
There are 2 solutions:
Use the argument
get_version
to provide the path to anotheruninstallkey
.
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
min_version
tells WAPT not to check for versions.
min_version=' '
Attention
With this method, versions are no longer checked during updates!
1.16. Frequent problems caused by Anti-Virus software¶
Some Anti-Virus software falsely raise errors when checking some internal components of WAPT.
Among the components is nssm.exe used by WAPT as a service manager for starting, stopping and restarting the WAPT service.
Below is a list of useful exceptions to declare in your central AV interface to solve false positives related to WAPT:
"C:\Program Files (x86)\wapt\waptservice\win32\nssm.exe"
"C:\Program Files (x86)\wapt\waptservice\win64\nssm.exe"
"C:\Program Files (x86)\wapt\waptagent.exe"
"C:\Program Files (x86)\wapt\waptconsole.exe"
"C:\Program Files (x86)\wapt\waptexit.exe"
"C:\wapt\waptservice\win32\nssm.exe"
"C:\wapt\waptservice\win64\nssm.exe"
"C:\wapt\waptagent.exe"
"C:\wapt\waptconsole.exe"
"C:\wapt\waptexit.exe"
"C:\Windows\Temp\waptdeploy.exe"
"C:\Windows\Temp\waptagent.exe"
"C:\Windows\Temp\is-?????.tmp\waptagent.tmp"
1.17. I have an issue with my proxy - THttpClientSocket.SockRecv(1) read = 0¶
If you have this issue:
The error comes from a timeout
option in the waptconsole.ini
.
Indeed, since WAPT 2.1 version, timeout is defined in milliseconds and not in seconds like before.
You will need to remove the timeout
option in the waptconsole.ini
file located in %localappdata%\waptconsole
.
1.18. What can go wrong during the upgrades of WAPTserver ?¶
The most common issue with the upgrading process is the local antivirus blocking the installation (WAPT is a software installer that keeps a websocket opened to a central management server, so this behavior may be flagged as suspicious by an antivirus, even though this method is the basis of end point management…). If you have an issue when deploying the upgrade, please check your antivirus console and whitelist the waptagent.exe. Another option is to re-sign the waptagent.exe binary if your organization has an internal code signing certificate.
The second most common issue is that for some reason another program is locking a DLL that ships with WAPT. This can happen with poorly designed software installers that pick up the local
%PATH%
variable first and then find WAPTs own openssl or python DLL.The third most common issue is a defective Windows install, that does not run scheduled tasks properly, and yes we have seen this!
1.19. Common mistakes¶
1.19.1. How to move my repository to another partition¶
For any reason, you may to need move the repository to another partition.
Your repository contains 3 folders which can be quite large:
wapt
;
wapt-host
;
waptwua
.
1.19.1.1. Linux¶
On Linux, create a mount point on fstab
.
For this example, the second partition is named part2.
part2 is an ext4 formated partition.
1.19.1.1.1. Debian and derivatives¶
Create a temporary folder.
mkdir /mnt/tmp
Create a temporary mount point.
mount /dev/part2 /mnt/tmp
Move the folders.
mv /var/www /mnt/tmp
Unmont the partition.
umount /dev/part2
Edit the
fstab
file.
vi /etc/fstab
Add the following line to the
fstab
file.
# <file system> <mount point> <type> <options> <dump> <pass>
/dev/part2 /var/www ext4 defaults 0 0
Mount the partition.
mount -a
Hint
If there is no error, the partition is mounted.
You can check by running.
df -h
#Result
Filesystem 1K-blocks Used Available Use% Mounted on
dev/part2 15G 944M 14G 7% /var/www
Remove the temporary folder.
rm -rf mnt/tmp
1.19.1.1.2. RedHat and derivatives¶
Create a temporary folder for copying the folders.
mkdir /mnt/tmp
Create a temporary mount point.
mount /dev/part2 /mnt/tmp
Move the folders.
mv /var/www/html /mnt/tmp
Unmont the partition.
umount /dev/part2
Edit the
fstab
file.
vi /etc/fstab
Add the following line to the
fstab
file.
# <file system> <mount point> <type> <options> <dump> <pass>
/dev/part2 /var/www/html ext4 defaults 0 0
Mount the partition.
mount -a
Hint
If there is no error, the partition is mounted.
You can check by running.
df -h
#Result
Filesystem 1K-blocks Used Available Use% Mounted on
dev/part2 15G 944M 14G 7% /var/www
Remove the temporary folder.
rm -rf mnt/tmp
1.19.1.2. Windows¶
On Windows, the best method is to backup and restore the WAPT Server on the new partition.
Note
It is possible to install the WAPT Server on another partition than C:
.
1.19.2. Using a network drive to store and deliver WAPT packages¶
The standard way WAPT works is with a secure web server delivering WAPT packages to the WAPT Clients.
Tranquil IT advises against using a network drive for delivering WAPT packages for several reasons:
A web server is extremely easy to setup, secure, maintain, backup and monitor.
To work correctly, a WAPT package needs to be self-contained. Indeed, we do not know if the network will be available at the time of the installation launch (for example if we have a waptexit that starts when the workstation is shutting down on a network with 802.1x user authentication, there will no longer be a network available at the time of installation). The self-contained nature of WAPT makes it more deterministic than other deployment solutions.
Network congestion may result from downloading large packages on large fleets of devices because you have less control over bandwidth rates or you may not be able to finish a partial download.
This method breaks or at least weakens the security framework of WAPT.
This method does not allow you to expose your repositories to Internet for your traveling personnel.
Attention
Even though WAPT can work independently of the transport mode, Tranquil IT will not officially support using a network drive to store and deliver WAPT packages.
1.19.3. Using the register() function in your audit scripts¶
The register() function forces the sending to the WAPT Server of the WAPT Agent’s hardware and software inventory.
This function is very taxing on the WAPT Server’s performance because it forces the WAPT Server to parse a relatively large JSON BLOB and to inject the result into the PostgreSQL database.
The function is by default triggered manually or when a new WAPT package upgrade is applied.
When you use the register()
function in a WAPT audit script, it will run every time the audit script is triggered so it will load the WAPT Server with no apparent benefit.
Therefore, we do not recommend the use of the :code:`register()` function in audit scripts.
1.19.4. EWaptBadControl: ‘utf8’ codec can not decode byte¶
If you get this message, it may mean that you have not set up correctly your development environment. Visit this section of the documentation on setting up UTF-8 (no BOM).
1.19.5. I have a lot more hosts in the WAPT Console than I have host packages on my Server?¶
Following a remark from Philippe LEMAIRE from the Lycée Français Alexandre Yersin in Hanoï, if you use the Enterprise version of WAPT and you make heavy use of the unit packages or profile packages, you may realize that you will have many more hosts in your WAPT Console than host packages on you WAPT sSrver. This is normal.
In fact, WAPT unit and profile packages are not explicitly assigned to the host (i.e. as dependencies in the host package) but are implicitly taken into account by the WAPT Agent dependency engine during the WAPT upgrade.
So one might have no host package on the WAPT Server if only unit packages are used for managing a fleet of devices.