2. FAQ - Server Issues¶
2.1. SSL/TLS certificates and trust¶
2.1.1. How can I renew my SSL/TLS Certificate Authority (CA) before expiration?¶
When replacing a CA certificate before its expiration, the new CA must be deployed to the agents before the WAPT Server starts using the new certificate.
This allows the agents to trust the new certificate while the existing CA is still valid.
Danger
Important notice for future WAPT Server updates
During the next WAPT Server update, ensure that the WAPT agents use the updated certificate rather than the old one. Failure to validate this may result in connectivity issues between the agents and the server.
Important
This procedure is intended for the following certificate transitions:
Pinned certificate to pinned certificate, using an internal PKI or a self-signed certificate.
Pinned certificate to a commercial certificate.
Commercial certificate to a pinned certificate.
If you are replacing one commercial certificate with another commercial certificate, keeping verify_cert = 1 should be sufficient.
Test the procedure in a development environment before deploying it to production.
Show solution
1. Prepare a test environment
Clone the WAPT Server and create a controlled test environment.
Add the cloned server and a WAPT agent, such as a Windows machine, to the test environment. Ensure that both machines can communicate over the network.
Install the current WAPT agent from the server on the test machine.
If the machines are in a workgroup, use the server IP address instead of its FQDN to establish communication. For example:
https://10.11.9.70
Verify that the agent is working correctly:
Run
wapt-get updateto check package synchronization.Send a test message using
waptmessageto confirm communication.
Proceed only after these operations succeed.
2. Merge the existing and new CA certificates
Connect to the WAPT Server and inspect the current certificate file:
cat /opt/wapt/waptserver/ssl/cert.pem
Identify the current CA certificate at the end of the file.
Copy the current CA certificate into a text file, for example 2ca.txt.
Open the new CA certificate in a text editor and append its contents to the file.
Save the resulting file and create a certificate file named 2ca.crt.
3. Create a configuration package
In the WAPT Console, open:
WAPT Packages > Host agent dynamic configuration.
Configure the package as follows:
Enter a package name, for example
prefix-renew_ca-dev.Set a sufficiently high priority to ensure that the package is applied as intended.
Select the
PRODmaturity level.Choose the
Globalconfiguration panel.Select Use specific bundle and add the new CA file, for example
wapt/ssl/server/2ca.crt.Click Save.
Adding a new CA certificate to a WAPT configuration package.¶
4. Deploy the configuration package
Deploy the configuration package to the test machine.
Verify that the new CA certificate is present on the agent and that the agent can still communicate with the server.
Once the procedure has been validated, deploy the package to the rest of your fleet.
5. Replace the server certificate
Only after all relevant machines have received the new CA should you replace the server certificate.
Connect to the WAPT Server and open the SSL directory:
cd /opt/wapt/waptserver/ssl/
Back up the current certificate:
mv cert.pem cert.pem.2025
Create a new cert.pem file containing the complete new certificate chain.
vi cert.pem
If your environment uses an internal PKI or a self-signed certificate and has a separate ca_cert.pem file, back it up as well:
mv ca_cert.pem ca_cert.pem.2025
Create a new ca_cert.pem containing only the new CA certificate.
Restart Nginx:
systemctl restart nginx.service
6. Update the WAPT Console certificate cache
When the server starts using the new certificate, the machines may disappear from the WAPT Console because the Console still trusts the old CA.
The local certificate directory is located at:
%LOCALAPPDATA%\waptconsole\ssl\server
To update the trusted certificate:
Remove the old CA certificate file, for example
xxx.crt.Copy the merged CA file
2ca.crtinto the same directory.Restart the WAPT Console.
Check that the machines reappear in the inventory. Test package updates and message delivery.
The CA transition is complete once the agents and the Console communicate successfully using the new certificate.
7. Identify machines that have not received the new CA
Check for machines that have not communicated with the server recently.
The following SQL query lists machines that have not been seen for more than 14 days:
SELECT
uuid,
computer_name,
last_seen_on
FROM
hosts
WHERE
TO_TIMESTAMP(last_seen_on, 'YYYY-MM-DD') <CURRENT_TIMESTAMP - INTERVAL '14 days'
ORDER BY
last_seen_on;
Adjust the interval to match your requirements.
For information about the reporting tab, see Using the reporting functions in WAPT 
.
2.1.2. How can I renew an SSL/TLS CA that has already expired?¶
If the Certificate Authority (CA) has already expired, the agents may no longer be able to establish a trusted connection to the WAPT Server.
There is no single native procedure that automatically restores control of every affected machine. The recovery method depends on the environment and the available management mechanisms.
Show solution
Case 1: Machines managed through Active Directory
If a significant proportion of the machines belongs to an Active Directory domain, use Group Policy Objects (GPOs) to distribute the new CA certificate and update the WAPT agent configuration.
Deploy the new CA certificate
Open Group Policy Management and configure the following path:
Use the GPO to copy the new CA certificate to the agent’s wapt/ssl/server directory.
Copying the new CA certificate using a GPO.¶
Update the WAPT agent configuration
Configure the GPO under:
Update the appropriate settings in wapt-get.ini so that the agent uses the new CA certificate.
Updating the WAPT agent INI configuration using a GPO.¶
This approach allows you to automate the recovery process across domain-joined machines.
Case 2: Machines not managed through Active Directory
Machines outside Active Directory may require manual intervention.
First, replace the server certificate with the new certificate and restart Nginx.
Back up the existing certificate before replacing it:
mv cert.pem cert.pem.2025
vi cert.pem
systemctl restart nginx.service
Ensure that the certificate and private key configuration is correct for your environment. Do not replace or delete a private key unless you have the corresponding replacement key and certificate.
Next, transfer the new CA certificate to the agent’s wapt/ssl/server directory, for example by using a USB drive.
Update the verify_cert setting in wapt-get.ini to point to the new CA certificate:
verify_cert = C:\Program Files (x86)\wapt\ssl\server\your_new_ca.crt
Restart the WAPT service and register the agent again:
net stop waptservice
net start waptservice
wapt-get register
Finally, verify that the machine reappears in the WAPT Console and can update packages and send messages.
This procedure is time-consuming but may be necessary for machines that cannot be managed through Active Directory.
Hint
When replacing one commercial certificate with another commercial certificate, keeping verify_cert = 1 may be sufficient. Validate this behavior in a test environment before deploying the change to production.
2.1.3. Why does the WAPT agent report a certificate hostname mismatch?¶
The WAPT agent may report the following error when certificate verification is enabled:
Certificate CN ### sent by the WAPT Server does not match URL host ###
This means that the certificate’s Common Name (CN), or the hostname covered by its Subject Alternative Names (SANs), does not match the hostname used by the agent to connect to the server.
Show solution
1. Check the configured server hostname
Open the WAPT agent’s wapt-get.ini file and check the value of wapt_server.
Ensure that the configured hostname matches the hostname covered by the server certificate.
2. Check the server certificate
If the configured hostname is correct, the certificate may have been generated with an incorrect hostname.
This can happen if an error occurred during the WAPT Server post-configuration, for example because of a typing mistake.
3. Regenerate the self-signed certificates if necessary
If the server uses self-signed certificates and the certificate contains the wrong hostname, regenerate the certificates using the correct server FQDN.
On the WAPT Server, back up the existing SSL directory before making changes.
The original procedure identifies the following directory:
/opt/wapt/waptserver/apache/ssl/
After backing up the files, remove the obsolete certificate files only if regeneration is required, then rerun the post-configuration script with the same installation arguments and the correct FQDN.
See the wapt postconf for the post-configuration procedure.
4. Retry certificate verification
Retry the following command:
wapt-get enable-check-certificate
Verify that the command completes successfully and that the agent can communicate with the WAPT Server.
2.2. WAPT Server availability and disaster recovery¶
2.2.1. What should I do if my WAPT Server is inoperative?¶
If the WAPT Server is destroyed or becomes unavailable following a fire, flood, hardware failure or another incident, the recovery procedure depends on the urgency and the availability of backups.
Show solution
1. Assess the urgency
Determine whether immediate action is required.
If you need to deploy a package or an urgent update, restoring service is critical.
If you do not regularly use WAPT for updates, package deployment or reporting, you may have more time to restore the server.
2. Restore from an external backup if available
If an external backup solution is available, follow Backing up the WAPT Server to recreate the WAPT Server.
3. Recreate the WAPT Server if no usable backup is available
The following recovery method is intended primarily for environments with an Active Directory and a large number of domain-joined WAPT agents.
First, create a new WAPT Server:
Check the server requirements.
Install the server according to the operating system using Installing WAPT Server.
Install and configure the WAPT Console using How to install the management WAPT console.
4. Update the WAPT agent configuration using a GPO
Before making changes, inspect the existing wapt-get.ini file on the agents.
Identify the settings that must change to point the agents to the new server.
In Group Policy Management, open:
Use a GPO to update the relevant parameters in wapt-get.ini.
Warning
If you use WAPT configuration packages, also check the [default-global] section and update the settings that refer to the old server.
GPO used to update the WAPT agent INI file.¶
The example modifies the verify_cert parameter to pin the new WAPT Server certificate. Other changes may be necessary depending on the configuration.
Once the GPO has been applied, verify that the agents connect to the new server and reappear in the WAPT inventory.
5. Set up regular external backups
Configure regular backups stored outside the WAPT Server.
This allows you to restore the server quickly in the event of another failure.
2.2.2. Why can’t the WAPT agents connect after a server recovery?¶
After rebuilding a WAPT Server, agents may still point to the old server or trust only its certificate.
Show solution
1. Check the server address
Verify the wapt_server parameter in wapt-get.ini.
Make sure that it points to the new server and that the configured hostname resolves to the correct IP address.
2. Check the trusted certificate
If the server certificate has changed, verify that the agent trusts the new certificate.
Update verify_cert and the CA certificate file as required by the certificate configuration.
3. Check configuration packages
If WAPT configuration packages are used, verify that the [default-global] section contains the correct server and certificate settings.
4. Check communication
Once the configuration has been corrected, restart the WAPT service and test package updates and message delivery.
2.3. Reverse proxy configuration¶
2.3.1. How should I configure a reverse proxy in front of the WAPT Server?¶
Reverse proxies that perform TLS interception or TLS termination, including Web Application Firewalls (WAFs), are no longer supported.
A reverse proxy placed in front of the WAPT Server must operate as a simple TLS forwarding proxy based on Server Name Indication (SNI). It must forward the TLS stream without decrypting or inspecting the HTTPS traffic.
With this configuration, TLS processing and certificate verification remain between the client and the WAPT Server.
Show solution
1. Configure DNS resolution
The WAPT agent resolves the configured server hostname through DNS and connects to the IP address returned.
The routing decision is therefore made by DNS:
On the internal network, internal DNS should resolve the WAPT Server hostname directly to the server’s internal IP address, bypassing the reverse proxy.
Outside the network, public DNS should resolve the same hostname to the public IP address of the reverse proxy.
The reverse proxy then forwards the TLS connection to the internal WAPT Server.
2. Install the Nginx stream module
On the reverse proxy server, ensure that the Nginx stream module is installed.
Debian and Ubuntu:
libnginx-mod-streamRed Hat and derivatives:
nginx-mod-stream
3. Configure Nginx stream forwarding
Create or edit the following file on the reverse proxy server:
/etc/nginx/modules-enabled/80-stream.conf
Add the following configuration, replacing the hostname and IP address with the values used in your environment:
stream {
tcp_nodelay on;
map $ssl_preread_server_name $https_upstream {
wapt.mydomain.com 192.168.2.5:443;
}
server {
listen 443;
resolver 127.0.0.1;
proxy_pass $https_upstream;
ssl_preread on;
}
}
In this example, 192.168.2.5 is the internal IP address of the WAPT Server.
Verify that the configuration file is loaded by an appropriate include directive in /etc/nginx/nginx.conf. Some Nginx installations do not automatically include files from modules-enabled.
Do not combine this configuration with an HTTP server block or an HTTP default_server directive listening on the same address and port. The objective is to forward the raw TLS stream without HTTP-level processing.
4. Check the certificate requirements
Because the reverse proxy does not terminate TLS, the certificate presented by the WAPT Server is verified by the client.
The certificate’s Common Name (CN) or one of its Subject Alternative Names (SANs) must match the hostname configured in the WAPT agent.
The certificate must not rely on the reverse proxy’s identity.
5. Verify the configuration
Inspect the logs directly on the WAPT Server, not on the reverse proxy:
tail -f /var/log/nginx/access.log
tail -f /var/log/nginx/error.log
Look for requests originating from external clients.
If external connections do not appear in the WAPT Server logs, check:
Public DNS resolution.
The reverse proxy’s SNI configuration.
The forwarding destination and port.
Network connectivity between the reverse proxy and the WAPT Server.
Note
A similar configuration can be implemented using HAProxy’s TLS passthrough functionality. This configuration is not covered by WAPT support; refer to the HAProxy documentation for details.
2.4. WAPT Server administration and maintenance¶
2.4.1. How can I reset the WAPT Server SuperAdmin password?¶
If you have forgotten the WAPT Console SuperAdmin password, you can relaunch the WAPT Server post-configuration process.
Show solution
1. Connect to the WAPT Server
Connect to the Linux WAPT Server using SSH.
2. Obtain administrative privileges
Connect as root or use sudo.
3. Relaunch the post-configuration script
Run the WAPT Server post-configuration script.
Follow the prompts to reconfigure the server and reset the relevant administrative settings.
2.4.2. What can go wrong when upgrading the WAPT Server?¶
Several issues may prevent a WAPT Server upgrade from completing successfully.
Show solution
1. Antivirus blocks the installation
Antivirus software may block the installation or execution of WAPT components.
WAPT is a software deployment tool that maintains a WebSocket connection to a central management server. This behavior may be flagged as suspicious by some antivirus products.
If an upgrade fails, check the antivirus management console and its logs.
If the antivirus is responsible, apply the appropriate exception according to your organization’s security policy. In some environments, signing the waptagent.exe binary with an internal code-signing certificate may also be necessary.
2. Another application locks a WAPT DLL
Another application may lock a DLL shipped with WAPT.
This can occur when an installer uses the system %PATH% variable and loads WAPT’s OpenSSL or Python DLLs instead of its own dependencies.
Check the upgrade logs and identify the process holding the file before retrying the installation.
3. Windows scheduled tasks are not working correctly
A defective Windows installation or a scheduled-task problem may prevent the upgrade process from running correctly.
Check the Windows Task Scheduler, the task history and the relevant WAPT logs to identify the failure.
2.4.3. Can the WAPT Server web directory /var/www be relocated to another directory, such as /opt/www?¶
Although some WAPT Server paths can be configured in waptserver.ini, /var/www is still referenced directly by certain WAPT installation scripts and packages. It is therefore not fully supported as a configurable replacement.