Configuring WAPT

The WAPT Server having been successfully installed, the next steps are as follow:

Installing the WAPT management console

Note

  • managing WAPT is done mainly via the WAPT console installed on the Administrator’s workstation;

  • the Administrator’s computer must be joined to the Organization’s Active Directory;

  • the host name of the Administrator’s workstation must not be longer than 15 characters. This is a limit of sAMAccountName attribute in Active Directory;

  • the Administrator’s computer will become critical for WAPT administration and WAPT package testing;

  • if DNS records are properly configured, you should be able to access the WAPT web interface by visiting: https://srvwapt.mydomain.lan;

If WAPT is installed on Windows Server

Warning

The WAPT console MUST NOT be installed on your Windows based WAPT server.

The WAPT console must be installed on the workstation from which you manage your network.

Before installing WAPT Console, download on Tranquil IT server:

  • Discovery version: WAPT Discovery will be released later. For the time being the free Edition of WAPT please use WAPT-1.8 console and server.

  • Enterprise version:

    • Download waptsetup on the WAPT server;

    • rename the file waptsetup-tis;

    • copy to C:\wapt\waptserver\repository\wapt;

You may now go on downloading and launching the installation of the WAPT console on the Administrator’s computer

If WAPT is installed on a Linux server

Go to next step.

Downloading and launching the installation of the WAPT console on the Administrator’s computer

WAPT Server web interface

WAPT Server web interface

  • if DNS records are properly configured, you should be able to access the WAPT web interface by visiting: https://srvwapt.mydomain.lan;

  • click on WAPTSetup link on the right-hand side of the WAPT Server web page;

  • start the executable installer as Local Administrator on the Administrator’s workstation;

  • choose the language and click on OK to install the WAPT console;

Choose the language for WAPT

Choose the language for WAPT

  • click on OK to go on to the next step;

Accept the WAPT license terms

Accept the WAPT license terms

  • accept the licence terms and click on Next to go to next step;

  • click on Next and choose your installation options (default value should be right for most installations);

Choose the installer's options

Choose the installer’s options

Note

  • check Install WAPT service if you want to have the WAPT service running on your Administrator workstation;

  • check Launch notification tray upon session opening if you want to have the WAPT icon running in the tray by default;

  • setting up the WAPT Server URL

Hint

Here, two choices become available to you.

  1. If first installation and WAPT agent not build/installed

Check Static WAPT Informations and set :

Choose the WAPT repository and server

Choose the WAPT repository and server; click Next

  1. If console or agent is already install

Check Don’t change current setup

The WAPT repository and server already set

The WAPT repository and server already set; click Next

  • resume of installation

The WAPT console installation abstract

The WAPT console installation abstract

  • click Install to launch the installation, wait for the installation to complete, then click on Finish (leave default options)

  • install in progress

Installation Wizard in progress

Installation Wizard in progress

  • install finished

Installation Wizard has finished

Installation Wizard has finished.

Uncheck Show installation documentation.

Starting the WAPT console

  • launch the WAPT console :

    • by looking for the binary

    C:\Program Files (x86)\wapt\waptconsole.exe

    • by Start Menu

    WAPT Console Start Menu
  • log into the WAPT console with the SuperAdmin login and password;

WAPT Server connexion form

WAPT Server connexion form

If you have any issue logging into the WAPT console, please refer to the FAQ: Error message when opening the WAPT console;

For Enterprise version, it’s possible to logging with Enabling Active Directory authentication.

First start after server installation

Hint

On first start, you must start the WAPT console with elevated privileges. Right-click on the WAPT console binary –> Start as Local Administrator;

Note

A message may appear indicating that your WAPT agent version is obsolete or not yet present.

Wapt agent not present

Wapt agent not present

Go to the next step to create your certificate.

Generating the Administrator’s certificate for signing WAPT packages

Hint

  • name of the private key: wapt-private.pem;

  • public certificate signed with private key: wapt-private.crt;

Private key wapt-private.pem

Attention

The wapt-private.pem file is fundamental for security. It must be stored in a safe place and correctly protected.

The wapt-private.pem file is the private key, it is located by default in the C:\private folder of the Administrator workstation and is password protected.

This private key will be used along with the certificate to sign packages before uploading them onto the WAPT repository.

Public certificate signed with the private key: wapt-private.crt

The wapt-private.crt file is the public certificate that is used along with the private key. It is by default created in the C:\private folder of the Administrator, copied and deployed in C:\Program Files (x86)\wapt\ssl on the Windows desktops or in /opt/wapt/ssl on the Linux and MacOS devices managed by the Administrator via a WAPT package, a GPO or an Ansible role.

This certificate is used to validate the signature of packages before installation.

Building a certificate

In the WAPT console go to Tools ‣ Build certificate;

Building a self-signed certificate

Building a self-signed certificate

WAPT Discovery

  • fill in the following fields:

Creating a self-signed certificate for Discovery version

Creating a self-signed certificate for Discovery version

Required informations are:

  • Target keys directory: folder where the private key and the public certificate will be stored: required;

  • Key filename: name of the .pem and Name of the private key;

  • Private key password: password for locking and unlocking the key: required;

  • Certificate name: name of the .crt certificate: required;

  • Common Name (CN): name of the certificate: required;

Optional information

  • Additional details stored in the private key. This information will help with identifying the origin of the certificate and WAPT package;

Hint

The password complexity must comply with your Organization’s security requirements (eg. ANSSI password recommendations).

Danger

  • the path to your private key must not be in the installation path of WAPT (C:\Program Files (x86)\wapt);

  • if your key is stored in C:\Program Files (x86)\wapt, your Administrator private key will be deployed on your clients, absolutely a no go!

  • click on OK to go on to the next step;

If everything has gone well the following message will appear:

Certificate generated successfully

Certificate generated successfully

  • click on OK.

Confirmation of the copy of the certificate in the ssl folder

Confirmation of the copy of the certificate in the ssl folder

  • click on Yes to copy the newly generated certificate in the folder C:\Program Files (x86)\wapt\ssl on Windows or /opt/wapt/ssl on Linux or MacOS. This certificate will be picked up during the compilation of the WAPT agent and deployed on the client computers;

You may go on to the next step and Building the WAPT agent installer.

WAPT Enterprise

With WAPT Enterprise, you can create a Master key with a Certificate Authority flag that can both sign packages and sign new certificates.

Hint

In order to create new signed certificates for delegated, please refer to Differentiating user roles in WAPT.

Creating a self-signed certificate for Enterprise version

Creating a self-signed certificate for Enterprise version

Required informations are:

  • Target keys directory: folder where the private key and the public certificate will be stored: required;

  • Key filename: name of the .pem and Name of the private key;

  • Private key password: password for locking and unlocking the key: required;

  • Certificate name: name of the .crt certificate: required;

  • Common Name (CN): name of the certificate: required;

  • Tag as code signing: check this box if the certificate/ key pair will be allowed to sign software packages: required;

  • Tag as CA certificate: check this box if this certificate can be used to sign other certificates (main or intermediate Certificate Authority): required;

Optional information

  • Additional details stored in the private key. This information will help with identifying the origin of the certificate and WAPT package;

Hint

The password complexity must comply with your Organization’s security requirements (eg. ANSSI password recommendations).

Note

If your Organization is already equipped with an Certificate Authority (CA), you will have to fill the certificate and the key in the fields CA Certificate and CA Key.

With this procedure you can generate new certificates/ key pairs with or without Code Signing capability.

Danger

  • the path to your private key must not be in the installation path of WAPT (C:\Program Files (x86)\wapt );

  • if your key is stored in C:\Program Files (x86)\wapt , your Administrator private key will be deployed on your clients, absolutely a no go!

If everything has gone well the following message will appear:

Certificate generated successfully

Certificate generated successfully

  • click on OK to go on to the next step;

Confirmation of the copy of the certificate in the ssl folder

Confirmation of the copy of the certificate in the ssl folder

  • click on Yes to copy the newly generated certificate in the C:\Program Files (x86)\wapt\ssl folder. This certificate will be picked up during the compilation of the WAPT agent and deployed on the clients computers;

You may go on to the next step and Building the WAPT agent installer.

Building the WAPT agent installer

The waptagent binary is an InnoSetup installer.

Once the WAPT console has been installed on the Administrator computer, we have all files required to build the WAPT agent installer.

  • files that will be used during building of the WAPT agent are located in C:\Program Files (x86)\wapt;

  • installer source files (.iss files) are located in C:\Program Files (x86)\wapt\waptsetup;

Hint

Before building the WAPT agent, please verify the public certificate(s) in C:\Program Files (x86)\wapt\ssl.

If you wish to deploy other public certificates on your Organization’s computers that are equipped with WAPT, you will have to copy them in that folder.

Danger

DO NOT COPY the private key of any Administrator in C:\Program Files (x86)\wapt.

This folder is used when building the WAPT agent and the private keys would then be deployed on all the computers.

Building the WAPT agent

  • In the WAPT console, go to Tools ‣ Build WAPT agent.

Generate the WAPT agent from the console

Generate the WAPT agent from the console

Hint

Before building agent, choose the identifing mode

Choosing the mode to uniquely identify the WAPT agents

In WAPT you can choose the unique identification mode of the agents.

When a WAPT agent registers the server must know if it is a new machine or if it is a machine already registered.

For this, the WAPT server looks at the unique number “UUID” in the inventory.

WAPT offers 3 modes of operation to help you distinguish between hosts, it is up to you to choose the mode that best suits you.

Attention

After choosing a mode of operation it is difficult to change it, think carefully!

Identifying the WAPT agents by their BIOS UUID (serial number)

This mode of operation makes it possible to identify the machines in the console in a physical manner.

If you replace a computer and give the new computer the same name as the previous one, you will have two computers that will appear in the WAPT console since you will have physically two different computers.

Note

Some vendors do inadequate work and assign the same BIOS UUIDs to entire batches of computers. In this case, WAPT will only see one computer …

Identifying the WAPT agent by host name

This mode of operation is similar to that in Active Directory. The machines are identified by their hostname.

Note

This mode does not work if several machines in your fleet share the same name. We all know it should not happen!!

Identifying the WAPT agents with a randomly generated UUID

This mode of operation allows PCs to be identified by their WAPT installation. Each installation of WAPT generates a unique random number. If you uninstall WAPT and then reinstall it, you will see a new pc appear in your console.

WAPT Discovery

Generate the WAPT agent from the console

Generate the WAPT agent from the console

  • fill in the informations that are necessary for the installer:

    • the field Public certificate: required;

      example : C:\private\mydomain.crt

    • the field Main WAPT repository: required;

      example : https://srvwapt.mydomain.lan/wapt

    • the field WAPT Server address: required;

      example : https://srvwapt.mydomain.lan

    • the checkbox Verify HTTPS server certificate;

    • the field Path to the https servers CA certificates bundle to verify the HTTPS certificate of the WAPT Server;

    • the checkbox Use kerberos for initial registering;

    • the field Organization to identify the origin of WAPT packages;

    • the field Use computer FQDN for UUID and Use random host UUID (for buggy BIOS) (see explanation in the previous paragraph of this documentation);

    • the field Enable AD Groups enables the installation of profile packages based on the Active Directory groups of which the machine is a member. This feature can degrade the performance of WAPT;

    • the field Append host’s profiles allows you to define a list of WAPT packages to install obligatorily;

    • the field Automatic periodic packages audit scheduling defines the frequency at which the WAPT agent checks whether it has audits to perform;

    • Windows update section, refer to this article on configuring WAPTWUA on the WAPT agent;

Danger

  • The checkbox Use kerberos for the initial registration must be checked ONLY IF you have followed the documentation on Configuring the kerberos authentication.

  • The checkbox Verify the WAPT Server HTTPS certificate**must be checked **ONLY IF you have followed the documentation on Activating the verification of the SSL / TLS certificate.

Fill in the informations on your Organization

Fill in the informations on your Organization

  • provide the password for unlocking the private key:

Provide the password for unlocking the private key

Provide the password for unlocking the private key

Progression of WAPT agent installer building

Progression of WAPT agent installer building

Once the WAPT agent installer has finished building, a confirmation dialog pops up indicating that the waptagent binary has been successfully uploaded to https://srvwapt.mydomain.lan/wapt/.

Confirmation of the WAPT agent loading onto WAPT repository

Confirmation of the WAPT agent loading onto WAPT repository

Note

A warning shows up indicating that the GPO hash value should be changed. GPOs may be used to deploy the WAPT agent on your Organization’s computer.

Danger

After building the agent, install the new WAPT agent on the WAPT management console.

WAPT Enterprise

  • fill in the informations that are necessary for the installer:

    • the field Public certificate: required;

      example : C:\private\mydomain.crt

    • the field Address of the WAPT repository: required;

      example : https://srvwapt.mydomain.lan/wapt

    • the field Address of the WAPT Server: required;

      example : https://srvwapt.mydomain.lan

    • the checkbox Verify the WAPT Server HTTPS certificate;

    • the field Path to the bundle of certificates to verify the HTTPS certificate of the WAPT Server;

    • the checkbox Use kerberos for registering WAPT agents;

    • the field Organization to identify the origin of WAPT packages;

    • the field Sign waptupgrade with both sha256 and sha1 can be ignored because it is only useful when upgrading from version 1.3;

    • the field Use computer FQDN for UUID and Use random host UUID (for buggy BIOS) (see explanation in the previous paragraph of this documentation);

    • the field Enable AD Groups enables the installation of profile packages based on the Active Directory groups of which the machine is a member. This feature can degrade the performance of WAPT;

    • the field Append host’s profiles allows you to define a list of WAPT packages to install obligatorily;

    • the field Automatic periodic packages audit scheduling defines the frequency at which the WAPT agent checks whether it has audits to perform;

    • Windows update section, refer to this article on configuring WAPTWUA on the WAPT agent;

Danger

  • The checkbox Use kerberos for the initial registration must be checked ONLY IF you have followed the documentation on Configuring the kerberos authentication.

  • The checkbox Verify the WAPT Server HTTPS certificate**must be checked **ONLY IF you have followed the documentation on Activating the verification of the SSL / TLS certificate.

Fill in the informations on your Organization

Fill in the informations on your Organization

  • provide the password for unlocking the private key:

Provide the password for unlocking the private key

Provide the password for unlocking the private key

Progression of WAPT agent installer building

Progression of WAPT agent installer building

Once the WAPT agent installer has finished building, a confirmation dialog pops up indicating that the waptagent binary has been successfully uploaded to https://srvwapt.mydomain.lan/wapt/.

Confirmation of the WAPT agent loading onto WAPT repository

Confirmation of the WAPT agent loading onto WAPT repository

Note

A warning shows up indicating that the GPO hash value should be changed. GPOs may be used to deploy the WAPT agent on your Organization’s computer.

Danger

After building the agent, install the new WAPT agent on the WAPT management console.

Updating the WAPT agents

The test-waptupgrade package has also been uploaded on the repository.

The test-waptupgrade package contains the WAPT agent with arguments specified during the installation of WAPT on your Administrator’s computer.

New WAPT agent in the repository

New WAPT agent in the repository

Note

This package is a standard WAPT package designed to upgrade WAPT agents on client machines.

Upgrading the WAPT agents using the xxx-waptupgrade package is a two step process:

  • first the package copies the new waptagent.exe file on the client computer and creates a new scheduled task that will run waptagent.exe with predefined installation flags two minutes after the creation of the scheduled task. At that point the package itself is installed and the inventory on the server shows the package installation as OK, with correct version installed, but the inventory will still show the old version as the agent is not yet updated.

  • after two minutes the scheduled task starts and runs waptagent.exe. waptagent.exe shutdowns the local WAPT service, upgrades the local WAPT install, and then restarts the service. The scheduled task is then automatically removed and the WAPT agent sends back its inventory to the WAPT server. Now the inventory on the server will show the new version of the agent.

From an administrator point of view, looking at the console you will see the following steps:

  • xxx-waptupgrade package starts being installed;

  • xxx-waptupgrade is installed, the machine is up to date from a package list point of view, but the version in the inventory is still the old version of the WAPT agent;

  • after two minutes the computer connectivity status switches to disconnected as the WAPT agent is updated;

  • after around two minutes the client computer gets back up online in the console and updates its inventory and shows the new version;

What can go wrong during the upgrades?

  • 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!!

Deploying the WAPT agent for Windows

Two methods are available to deploy the waptagent.exe.

The first method is manual and the procedure must be applied on each machine.

The second one is automated and relies on a GPO.

Note

The waptagent.exe installer is available at https://srvwapt.mydomain.lan/wapt/waptagent.exe.

If you do not sign the waptagent.exe installer with a commercial Code Signing certificate or a Code Signing certificate issued by the Certificate Authority of your Organization after having generated it, web browsers will show a warning message when downloading the installer. To remove the warning message, you must sign the .exe with a Code Signing certificate that can be verified by a CA bundle stored in the machine’s certificate store.

Hint

When to deploy the WAPT agent manually?

Manual deployment method is efficient in these cases:

  • testing WAPT;

  • using WAPT in an organization with a small number of computers, etc;

Deploying waptagent.exe manually

Attention

This operation requires Local Administrator rights on the local computer.

Installing waptagent.exe

Download the WAPT agent from https://srvwapt.mydomain.lan/wapt/waptagent.exe then launch the installer.

Download the WAPT agent to be deployed on computers

Download the WAPT agent to be deployed on computers

  • choose the language and click on Next to go to next step;

    Choose the installation language

    Choose the installation language

  • accept the license terms and click on Next to go to next step;

    Accepting the EULA

    Accepting the EULA

  • choose the installation directory and click on Next to go to next step;

    Select the installation folder for the WAPT agent

    Select the installation folder for the WAPT agent

  • choose the additional parameters and click on Next to go to next step;

    Hint

    leave Force-reinstall VC++ enabled checked. If the option box is ticked it is because its installation is necessary.

    Choose the installer's options

    Choose the installer’s options

  • choose the WAPT repository and the WAPT Server and click on Next to go to next step;

    Choose the WAPT repository and server

    Choose the WAPT repository and server

  • install the WAPT agent by clicking on Install;

    Summary of installation options

    Summary of installation options

  • wait for the installation of the WAPT agent to finish, then click on Finish to exit;

    Installation in progress

    Installation in progress

The installation of the WAPT agent is finished. With cmd.exe, launch a register to register the machine with the WAPT Server and an update to display the list of available WAPT packages.

End of WAPT agent installation

End of WAPT agent installation

Note

  • tick Register this host on WAPT Server to register the computer on the WAPT inventory server;

  • tick Update package list from repository to update the list of available packages;

To manage your Organization’s WAPT clients, visit the documentation on using the WAPT console.

Automatically deploying the WAPT agents

Important

Technical pre-requisites

Advanced network and system administration knowledge is required to achieve this procedure. A properly configured network will ensure its success.

Hint

When to deploy the WAPT agent automatically? The following method is useful in these cases:

  • a large organization with many computers;

  • a Samba Active Directory or Microsoft Active Directory for which you have enough administration privileges;

  • the security and the traceability of actions are important to you or to your Organization;

Deploying the WAPT agents silently

Without waptdeploy

waptagent.exe is an InnoSetup installer, it can be executed with these silent switches:

waptagent.exe /VERYSILENT
  • Additional arguments available for waptdeploy

Description of available options for deploying the WAPT agent silently

Options

Description

/dnsdomain = mydomain.lan

Domain in wapt-get.ini filled in during installation.

/wapt_server = https://srvwapt.mydomain.lan

URL of the WAPT server in wapt-get.ini filled in during installation

/repo_url = https://repo1.mydomain.lan/wapt

URL of the WAPT repository in wapt-get.ini filled in during installation.

/StartPackages = basic-group

Group of WAPT packages to install by default.

/verify_cert= = 1 or relative path ssl\server\srvwapt.mydomain.lan.crt

Value of verify_cert entered during installation

/CopyServersTrustedCA = path to a bundle to copy to ssl\server.

Certificate bundle for https connections (to be defined by verify_cert)

/CopypackagesTrustedCA = path to a certificate bundle to copy into ssl

Certificate bundle for verifying package signatures

Hint

The iss file for the InnoSetup installer is available here: C:\Program Files (x86)\wapt\waptsetup\waptsetup.iss.

You may choose to adapt it to your specific needs. Once modified, you’ll just have to recreate a waptagent.

To learn more about the options available with InnoSetup, visit this documentation.

With waptdeploy

waptdeploy is a small binary that:

  • checks the version of the WAPT agent;

  • downloads via https the waptagent.exe installer;

  • launches the silent installer with arguments (checked options defined during the compilation of the WAPT agent);

/VERYSILENT /MERGETASKS= ""useWaptServer""
  • updates the WAPT Server with the WAPT agent status (WAPT version, package status);

    Note

    waptdeploy must be started as Local Administrator, that is why we advise you to use a GPO.

Creating a GPO to deploy the WAPT agents

Download waptdeploy.exe by visiting: https://wapt.tranquil.it/wapt/releases/latest/waptdeploy.exe.

Creating the GPO
  • create a new group strategy called install_wapt on the Active Directory server (Microsoft or Samba-AD);

  • add a new strategy: Computer configuration ‣ Strategies ‣ Windows configuration ‣ Scripts ‣ Startup ‣ Add;

    Creating a group strategy to deploy the WAPT agent

    Creating a group strategy to deploy the WAPT agent

  • click on Browse to select the waptdeploy.exe script;

    Finding the waptdeploy.exe file on your computer

    Finding the waptdeploy.exe file on your computer

  • copy waptdeploy.exe in the destination folder;

    Selecting the waptdeploy.exe script

    Selecting the waptdeploy.exe script

  • click on Open to import the waptdeploy.exe script;

    Selecting the waptdeploy.exe script

    Selecting the waptdeploy.exe script

  • click on Open to confirm the importation of the waptdeploy binary;

Passing arguments

Hint

Starting with version 1.3.7, it is necessary to provide the checksum of the waptagent.exe as an argument to the waptdeploy GPO.

This will prevent the remote machine from executing an erroneous/ corrupted waptagent binary.

--hash="checksum du WaptAgent" --minversion=1.5.1.23 --wait=15

Note

Parameters and waptagent.exe checksum to use for the waptdeploy GPO are available on the WAPT Server by visiting https://srvwapt.mydomain.lan.

Web console of the WAPT Server

Web console of the WAPT Server

  • copy the required parameters;

    add the *waptdeploy* script to the startup GPO

    add the waptdeploy script to the startup GPO

  • click on OK to go on to the next step;

    WAPTdeploy GPO to be deployed on next startup

    WAPTdeploy GPO to be deployed on next startup

  • click on OK to go on to the next step;

  • apply resulting GPO strategy to the Organization’s Computers OU;

Additional arguments available for waptdeploy
Additional arguments available for waptdeploy

Options

Value

Description

--force

Forces the installation of waptagent.exe even if the WAPT agent is already installed.

--waptsetupurl

https://srvwapt.mydomain.lan/wapt/waptagent.exe

Gives explicitly the WAPT agent URL/path to use to download the WAPT agent

--tasks

autorunTray,installService,installredist2008,autoUpgradePolicy

Sets waptagent installation tasks

--wait

10

Timeout for installing the WAPT agent.

--setupargs=

/dnsdomain=mydomain.lan /wapt_server= /repo_url=

Passing additional parameters to waptagent

--hash="43254648348435423486"--minversion=1.8.1 --waptsetupurl=http://srvwapt.mydomain.lan/wapt/waptagent.exe --wait=10

Launching waptdeploy with a scheduled task

For waptdeploy to work best, you may execute the GPO upon computer shutdown;

You may also choose to launch waptdeploy using a scheduled task that has been set by GPO.

Hint

This method is particularly effective for deploying WAPT on workstations when the network is neither available on starting up or shutting down.

The method consists of using a GPO to copy waptdeploy.exe and waptagent.exe:

  • source: \mydomain.lan\netlogon\waptagent.exe

  • destination: C:\windows\temp\waptagent.exe

    WAPT agent installation progress

    WAPT agent installation progress

  • copy waptdeploy.exe and waptagent.exe in the netlogon share of your Active Directory Server;

  • then create a GPO to set up a scheduled task:

Task Create in *deploywapt* Properties window

Task Create in deploywapt Properties window

General tab in *deploywapt* Properties window

General tab in deploywapt Properties window

  • use S-1-5-18 as a user account;

  • check Run with highest privileges;

Trigger tab in *deploywapt* Properties window

Trigger tab in deploywapt Properties window

  • check Daily, select today’s date and Repeat Task every 1 hour;

Actions tab

Arguments:

--hash="43254648348435423486" --minversion=1.5.1.23 --waptsetupurl=C:\windows\temp\waptagent.exe --wait=10

Attention

The hash and min_version arguments will change in reality compared to the documentation as WAPT continues to improve.

Conditions tab in *deploywapt* Properties window

Conditions tab in deploywapt Properties window

Settings tab in *deploywapt* Properties window

Settings tab in deploywapt Properties window

  • check Run task as soon as possible after a scheduled start is missed;

To verify that your GPO is working, you can run the gpupdate /force command and verify that the schedule task is present on your computer.

Deploying the WAPT Agent on Linux

New in version 1.8.

Starting with WAPT 1.8, a Linux agent is available for Debian / Ubuntu and RedHat / Centos.

Note

  • the following procedure installs a WAPT agent using Tranquil IT’s repositories for Debian/CentOS;

  • if you wish to install it manually, you can look for your corresponding version;

  • copy the link of the binary that you need, download and install it with dpkg / rpm;

Installing the WAPT agent on Debian

The most secure and reliable way to install the latest WAPT agent on Linux Debian is using Tranquil IT’s public repository.

  • add Tranquil IT’s repository in apt repository lists:

Important

Follow this procedure for getting the right packages for the WAPT Enterprise Edition. For WAPT Discovery Edition please refer to the next block.

To access WAPT Enterprise resources, you must use the username and password provided by our sales department.

Replace user and password in the deb parameter to access WAPT Enterprise repository.

apt update && apt upgrade -y
apt install apt-transport-https lsb-release gnupg
wget -O - https://wapt.tranquil.it/debian/tiswapt-pub.gpg  | apt-key add -
echo "deb https://user:password@srvwapt-pro.tranquil.it/entreprise/debian/wapt-1.8/ $(lsb_release -c -s) main" > /etc/apt/sources.list.d/wapt.list

Important

Follow this procedure for getting the right packages for the WAPT Discovery Edition. For WAPT Enterprise Edition please refer to the previous block.

apt update && apt upgrade -y
apt install apt-transport-https lsb-release gnupg
wget -O - https://wapt.tranquil.it/debian/tiswapt-pub.gpg  | apt-key add -
echo "deb https://wapt.tranquil.it/debian/wapt-1.8/ $(lsb_release -c -s) main" > /etc/apt/sources.list.d/wapt.list
  • install WAPT agent using apt-get:

apt update
apt install tis-waptagent

Installing the WAPT agent on CentOS

The most secure and reliable way to install the latest WAPT agent on Linux CentOS is using Tranquil IT’s public repository.

  • add Tranquil IT’s repository in yum repository lists:

Important

Follow this procedure for getting the right packages for the WAPT Enterprise Edition. For WAPT Discovery Edition please refer to the next block.

To access WAPT Enterprise resources, you must use the username and password provided by our sales department.

Replace user and password in the baseurl parameter to access WAPT Enterprise repository.

cat > /etc/yum.repos.d/wapt.repo <<EOF
[wapt]
name=WAPT Server Repo
baseurl=https://user:password@srvwapt-pro.tranquil.it/entreprise/centos7/wapt-1.8/
enabled=1
gpgcheck=1
EOF

Important

Follow this procedure for getting the right packages for the WAPT Discovery Edition. For WAPT Enterprise Edition please refer to the previous block.

cat > /etc/yum.repos.d/wapt.repo <<EOF
[wapt]
name=WAPT Server Repo
baseurl=https://wapt.tranquil.it/centos7/wapt-1.8/
enabled=1
gpgcheck=1
EOF
  • install WAPT agent using yum:

    wget -q -O /tmp/tranquil_it.gpg "https://wapt.tranquil.it/centos7/RPM-GPG-KEY-TISWAPT-7"; rpm --import /tmp/tranquil_it.gpg
    yum install tis-waptagent
    

Creating the agent configuration file

The requisites for your WAPT agent to work are:

  • wapt-get.ini config file in /opt/wapt/;

  • a public certificate of the package-signing authority in /opt/wapt/ssl/;

You need to create and configure the wapt-get.ini file in /opt/wapt (Configuring the WAPT agent).

An example of what it should look like is present further down on this page. You may use it after changing the parameters to suit your needs.

vim /opt/wapt/wapt-get.ini
[global]
repo_url=https://srvwapt.mydomain.lan/wapt
wapt_server=https://srvwapt.mydomain.lan/
use_hostpackages=1
use_kerberos=0
verify_cert=0

Copying the package-signing certificate

You need to copy manually, or by script, the public certificate of your package signing certificate authority.

The certificate should be located on your Windows machine in C:\Program Files (x86)\wapt\ssl\.

Copy your certificate(s) in /opt/wapt/ssl using WinSCP or rsync if you are deploying on Linux or MacOS.

Copying the SSL/TLS certificate

If you already have configured your WAPT server to use correct Nginx SSL/TLS certificates, you must copy the certificate in your WAPT Linux agent.

The certificate should be located on your Windows machine in C:\Program Files (x86)\wapt\ssl\server\.

Copy your certificate(s) in /opt/wapt/ssl/server/ using WinSCP or rsync if you are deploying on Linux or MacOS.

Then, modify in your config file the path to your certificate.

vim /opt/wapt/wapt-get.ini

And give absolute path of your cert.

verify_cert=/opt/wapt/ssl/server/YOURCERT.crt

Attention

If you are not using SSL/TLS certificates with your WAPT Server, you must change it in /opt/wapt/wapt-get.ini the following lines to 0:

verify_cert=0

Registering your Linux agent with the WAPT server

Attention

  • beware, by default, WAPT takes the system language by default for packages, you may have to define the language in wapt-get.ini with locales=.

  • restart the WAPT service:

    systemctl restart waptservice.service
    
  • finally, execute the following command to register your Linux host with the WAPT server:

    wapt-get register
    wapt-get update
    

Congratulations, your Linux Agent is now installed and configured and it will now appear in your WAPT Console with a pinguin icon!!

Unsupported features

  • installing updates on shutdown;

  • WAPT console is not currently available on linux;

  • any Windows specific feature;

Particularities with domain functionality

  • testing was carried out with sssd with an Active Directory domain and kerberos authentication;

  • to integrate a machine in the Active Directory domain, you can choose to follow this documentation

  • to force the update of Organizational Units on the host, you can apply a gpupdate from the WAPT console;

  • in order for Active Directory groups to function properly, you must verify that the id hostname$ command returns the list of groups the host is member of;

Attention

We have noticed that the kerberos LDAP query does not work if the reverse DNS record is not configured correctly for your domain controllers. These records must therefore be created if they do not exist.

Deploying the WAPT agent on MacOS

New in version 1.8.

Attention

Currently, the agent has only been tested on High Sierra (version 10.13) and Mojave (10.14) while the latest MacOS version is Catalina (10.15). Catalina may have introduced changes that could prevent the agent from working.

Installing the WAPT Agent package from Tranquil IT’s public repository

  • download WAPT agent for Apple Mac OSX from Tranquil IT’s public repository

    sudo curl <PastedLink> tis-waptagent.pkg
    
  • install the downloaded package:

    sudo installer -pkg tis-waptagent.pkg -target /
    

Creating the agents configuration file

The requisites for your WAPT agent to work are:

  • wapt-get.ini config file in /opt/wapt/;

  • a public certificate of the package-signing authority in /opt/wapt/ssl/;

You need to create and configure the wapt-get.ini file in /opt/wapt (Configuring the WAPT agent).

An example of what it should look like is present further down on this page. You may use it after changing the parameters to suit your needs.

sudo vim /opt/wapt/wapt-get.ini
[global]
repo_url=https://srvwapt.mydomain.lan/wapt
wapt_server=https://srvwapt.mydomain.lan/
use_hostpackages=1
use_kerberos=0
verify_cert=0

Copying the package-signing certificate

You need to copy manually, or by script, the public certificate of your package signing certificate authority.

The certificate should be located on your Windows machine in C:\Program Files (x86)\wapt\ssl\.

Copy your certificate(s) in /opt/wapt/ssl using WinSCP or rsync.

Copying the SSL/TLS certificate

If you already have configured your WAPT server to use correct Nginx SSL/TLS certificates, you must copy the certificate in your WAPT Mac agent.

The certificate should be located on your Windows machine in C:\Program Files (x86)\wapt\ssl\server\.

Copy your certificate(s) in /opt/wapt/ssl/server/ using WinSCP or rsync.

Then, modify in your wapt-get.ini config file the path to your certificate.

sudo vim /opt/wapt/wapt-get.ini

And give absolute path of your cert.

verify_cert=/opt/wapt/ssl/server/YOURCERT.crt

Attention

If you are not using SSL/TLS certificates with your WAPT Server, you must set the following lines to 0 in /opt/wapt/wapt-get.ini:

verify_cert=0

Registering your MacOS agent with the WAPT server

Attention

Beware, by default, WAPT takes the system language by default for packages, you may have to define the language in wapt-get.ini with locales=.

  • restart the WAPT service:

    sudo launchctl unload /Library/LaunchDaemons/com.tranquilit.tis-waptagent.plist
    sudo launchctl load /Library/LaunchDaemons/com.tranquilit.tis-waptagent.plist
    
  • finally, execute the following command to register your MacOS host with the WAPT server:

  • you must logon as root to run:

    wapt-get register
    
  • then switch back to normal user for the following:

    sudo wapt-get update
    

Congratulations, your MacOS Agent is now installed and configured and it will now appear in your WAPT Console with an apple icon!

Unsupported features

  • installing updates on shutdown;

  • WAPT console is not currently available on linux;

  • any Windows specific feature;

Particularities with domain functionality

  • testing was carried out with sssd with an Active Directory domain and kerberos authentication;

  • to integrate a machine in the Active Directory domain, you can choose to follow this documentation

  • to force the update of Organizational Units on the host, you can apply a gpupdate from the WAPT console;

  • in order for Active Directory groups to function properly, you must verify that the id hostname$ command returns the list of groups the host is member of;

Attention

We have noticed that the kerberos LDAP query does not work if the reverse DNS record is not configured correctly for your domain controllers. These records must therefore be created if they do not exist.

Deploying the Linux WAPT Agent with Ansible

To avoid mistakes and automate your WAPT agents deployment on Linux, we provide Ansible roles for installing WAPT agents on:

  • Debian

  • Ubuntu

  • Redhat / CentOS

You can explore the role source code by visiting this link on Github.

Requirements

  • Debian Linux or CentOS hosts;

  • a sudoers user on these hosts;

  • Ansible 2.8;

Installing the Ansible role

  • install tranquilit.waptagent Ansible role;

    ansible-galaxy install tranquilit.waptagent
    
  • to install the role elsewhere, use the -p subcommand like this;

    ansible-galaxy install tranquilit.waptagent -p /path/to/role/directory/
    

Using the Ansible role

  • ensure you have a working ssh key deployed on your hosts, if not you can generate and copy one like below;

    ssh-keygen -t ed25519
    ssh-copy-id -i id_ed25519.pub user@computer1.mydomain.lan
    ssh user@computer1.mydomain.lan -i id_ed25519.pub
    
  • edit Ansible hosts inventory ( ./hosts ) and add the Linux hosts;

    [computers]
    computer1.mydomain.lan ansible_host=192.168.1.50
    computer1.mydomain.lan ansible_host=192.168.1.60
    
  • create a playbook with the following content in ./playbooks/deploywaptagent.yml;

    - hosts: computers
      roles:
        - { role: tranquilit.waptagent }
    
  • ensure all variables are correctly set (see wapt-get.ini variables);

    • wapt_server_url;

    • wapt_repo_url;

    • wapt_crt;

Important

Variables configuration is important as it will configure the behavior of the WAPT.

You must replace the default certificate with your Code-Signing public certificate.

  • run your playbook with the following command;

ansible-playbook -i ./hosts ./playbooks/deploywaptagent.yml -u user --become --become-method=sudo -K

Congratulations, you have installed your WAPT agent on your Linux hosts!

Role variables

Available variables are listed below, along with default values (see defaults/main.yml).

WAPT agent variables

  • version of WAPT that will be installed from WAPT Deb/RPM repository;

wapt_version: "1.8"
  • version of CentOS used for RPM repository address;

centos_version: "centos7"

wapt-get.ini variables

The wapt_server_url parameter points to your WAPT server and is used by default for the wapt_repo_url.

wapt_server_url: "https://srvwapt.mydomain.lan"
wapt_repo_url: "{{ wapt_server_url }}/wapt/"

You can override it like so:

wapt_server_url: "https://wapt.landomain.lan"
wapt_repo_url: "https://wapt.otherdomain.com/wapt/"

Certificate filename located in files/ subdirectory of the role:

wapt_crt: "wapt_ca.crt"

Example Ansible playbook

Here is an example of an Ansible playbook.

- hosts: hosts
  vars_files:
    - vars/main.yml
  roles:
    - tranquilit.waptagent

Uninstalling WAPT agent from clients

On Windows

If you need to uninstall WAPT agents from clients, the uninstaller is automatically created in the WAPT install location, by default it is C:\Program Files (x86)\wapt\unins000.exe.

  • default silent uninstall of a WAPT agent can be achieved with the following command:

    unins000.exe /VERYSILENT
    
  • an additional argument can be passed to unins000.exe to cleanup everything:

    unins000.exe /VERYSILENT /purge_wapt_dir=1
    
Complete list of command-line arguments for unins000.exe

Settings

Description

/VERYSILENT

Launches unins000.exe silently

/purge_wapt_dir = 1

Purges WAPT directory (removes all folders and files)

Re-enabling Windows Updates before uninstalling

In the case you have used WAPT to manage Windows Updates (Enterprise only), you might want to re-enable Windows Updates default behavior before uninstalling the WAPT agent.

To do so, here is an example package to push before uninstalling the WAPT agent:

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

uninstallkey = []

def install():
    print('Disable WAPT WUA')
    inifile_writestring(WAPT.config_filename,'waptwua','enabled','false')

    print('DisableWindowsUpdateAccess registry to 0')
    registry_set(HKEY_LOCAL_MACHINE,r'Software\Policies\Microsoft\Windows\WindowsUpdate','DisableWindowsUpdateAccess',0,REG_DWORD)

    print('AUOptions registry to 0')
    registry_set(HKEY_LOCAL_MACHINE,r'SOFTWARE\Microsoft\Windows\CurrentVersion\WindowsUpdate\Auto Update','AUOptions',0,REG_DWORD)

    print('Enable wuauserv')
    run_notfatal('sc config wuauserv start= auto')
    run_notfatal('net start wuauserv')

On Linux

  • default uninstall of a WAPT agent can be achieved with the following command, depending on your Linux OS:

    # Debian / Ubuntu
    apt remove --purge tis-waptagent
    
    # CentOS / Redhat
    yum remove tis-waptagent
    
  • an additional step can be done using these commands (WIP):

    rm -f /opt/wapt/
    
    # Debian / Ubuntu
    rm /etc/apt/sources.list.d/wapt.list
    
    # CentOS / Redhat
    rm /etc/yum/yum.repos.d/wapt.list
    

On MacOS

  • default uninstall of a WAPT agent can be achieved with the following command:

    # List all files to delete
    pkgutil --only-files --files com.tranquilit.tis-waptagent-enterprise > file_list
    
    # Remove packages
    sudo pkgutil --forget com.tranquilit.tis-waptagent-enterprise
    

Advanced WAPT configuration

To go further, more configuration options are available in this part of the documentation:

Configuring the WAPT agent

The configuration file C:\Program Files(x86)\wapt\wapt-get.ini defines the behavior of the WAPT agent.

The [global] section is required:

[global]

After standard installation, the default configuration is:

[global]
waptupdate_task_period=120
waptserver=https://srvwapt.mydomain.lan
repo_url=https://srvwapt.mydomain.lan/wapt/
use_hostpackages=1

Making changes in wapt-get.ini and regenerating an agent is not sufficient to push the new configuration.

You can create a WAPT package to push updated wapt-get.ini settings.

The package is available from the Tranquil IT repository: https://store.wapt.fr/wapt/tis-wapt-conf-policy_6_f913e7abc2f223c3e243cc7b7f95caa5.wapt:

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

uninstallkey = []

def install():

  print('Modify max_gpo_script_wait')
  inifile_writestring(WAPT.config_filename,'global','max_gpo_script_wait',180)

  print('Modify Preshutdowntimeout')
  inifile_writestring(WAPT.config_filename,'global','pre_shutdown_timeout',180)

  print('Disable Hyberboot')
  inifile_writestring(WAPT.config_filename,'global','hiberboot_enabled',0)

  print('Disable Notify User')
  inifile_writestring(WAPT.config_filename,'global','notify_user',0)

Description of available options for the WAPT agent

Note

  • if repo_url and wapt_server fields are empty, the WAPT agent will look for a repository using SRV records in the dnsdomain zone;

  • if there is no wapt_server attribute in the [global] section, no WAPT Server will be used;

  • if there is no repo_url attribute in the [global] section, a repository in the [wapt] section will have to be explicitly defined;

  • it will have to be enabled by adding it to the repositories attribute to the [global] section;

Description of available options for the WAPT agent

Options

Description

use_hostpackages = 1

Use host packages (default 1).

waptupdate_task_period = 120

Update frequency (120 minutes by default).

waptupgrade_task_period = 360

Upgrade frequency (disabled by default)

waptservice_port = 8088

WAPT agent loopback port. It is not accessible from the network.

dbpath = C:\Program Files(x86)\wapt\db\waptdb.sqlite

Path to the local database file.

loglevel = warning

Log level of the WAPT agent. Possible values are: debug, info, warning, critical.

maturities = PROD

List of packages maturities than can be viewed and installed by WAPT Agent. Default value is PROD. Any value can be used.

use_fqdn_as_uuid = 1

Allows you to use the fqdn name rather than the uuid BIOS as the unique machine identifier in wapt.

waptaudit_task_period = 120

Define the frequency where the agent checks if he has audits to perform.

locales = en

Allows you to set the list of wapt agent languages to modify the list of packages visible by wapt (for package filtering). You can add multiple language (eg. locales=fr,en) in order of preference.

host_profiles = tis-firefox,tis-java

Allows you to define a wapt package list that the wapt agent must install.

language = en

Force default langauge for GUI (not for package filtering)

host_organizational_unit_dn = OU=TOTO,OU=TEST,DC=DEMO,DC=LAN

Allows you to force an Organizational Unit on the WAPT agent. (Convenient to assign a fake OU for out-of-domain PC) Make sure it respects a consistent case (don’t mix “dc”s and “DC”s, for example), which you can find in the console (in the DN/computer_ad_dn fields for each machine)

download_after_update_with_waptupdate_task_period = True

Define whether a download of pending packages should be started after an update with waptupdate_task_period

log_to_windows_events = False

Send the log wapt in the window events

service_auth_type = system

How the self service authentication works. Possible values are: system, waptserver-ldap or waptagent-ldap

uninstall_allowed = 1

Whether or not it is possible for the user to uninstall applications via the self-service.

WAPT Server configuration attributes

These options will set WAPT agent behavior when connecting to WAPT Server.

Description of available options for the WAPT Server

Options

Description

wapt_server =

WAPT Server URL. If the attribute is not present, no WAPT Server will be contacted. If the attribute is empty, a DNS query will be triggered to find the WAPT Server using the dnsdomain attribute for the DNS zone.

dnsdomain =

DNS zone on which the DNS SRV _waptserver._tcp is searched.

wapt_server_timeout = 10

WAPT Server HTTPS connection timeout in seconds

use_kerberos = 1

Use kerberos authentication for initial registration on the WAPT Server.

verify_cert = C:\Program Files (x86)\wapt\ssl\server\srvwapt.mydomain.lan.crt (on Windows) verify_cert = /opt/wapt/ssl/server/srvwapt.mydomaine.lan.crt (on Linux and MacOS)

See the documentation on activating the verification of HTTPS certificates

public_certs_dir = C:\Program Files (x86)\wapt\ssl (on Windows) public_certs_dir = /opt/wapt/ssl/ (on Linux and MacOS)

Folder of certificates authorized to verify the signature of WAPT packages, by default, <wapt_base_dir>\\ssl. Only files in this directory with .crt or .pem extension are taken into account. There may be several X509 certificates in each file. Authorized packages in WAPT are those whose signature may be verified by one of the certificates contained in the PEM files of this directory. Each repository may have its own folder of authorized certificates.

Using several repositories

There can be more sections in the wapt-get.ini file to define more repositories:

  • [wapt]: main repository. Relevant attributes: repo_url, verify_cert, dnsdomain, http_proxy, use_http_proxy_for_repo, timeout. If this section does not exist, parameters are read from the [global] section;

  • [wapt-template]: external remote repository that will be used in the WAPT console for importing new or updated packages;

  • [wapt-host]: repository for host packages. If this section does not exist, default locations will be used on the main repository;

More information on that usage can be found in this article on working with multiple public or private repositories.

Note

Active repositories are listed in the repositories attribute of the [global] section.

Description of available options for repositories

Options

Description

repositories = repo1, repo2

List of enabled repositories, separated by a comma. Each value defines a section of the wapt-get.ini file. In each section, it is possible to define repo_url, dnsdomain, public_certs_dir, http_proxy.

Note

This parameter can be configured both in the WAPT agent configuration and in the WAPT console configuration file C:\Users\%username%\AppData\Local\waptconsole\waptconsole.ini.

For information on configuring the WAPT console, please refer to this documentation.

Settings for waptexit

Description of available options for WAPTexit

Options

Description

allow_cancel_upgrade = 1

Prevents users from canceling package upgrades on computer shutdown.

pre_shutdown_timeout = 180

Timeout for scripts at computer shutdown.

max_gpo_script_wait = 180

Timeout for GPO execution at computer shutdown.

hiberboot_enabled = 0

Disables Hiberboot on Windows 10 to make waptexit work correctly.

Settings for WAPT Self-Service and Waptservice Authentification

Description of available options for the WAPT Self-Service and Waptservice Authentification

Options

Description

waptservice_admin_filter = True

Apply selfservice package view filtering for Local Administrators.

service_auth_type = system

Defines the authentication system of the wapt service, available value are system, waptserver-ldap, waptagent-ldap.

ldap_auth_ssl_enabled = False

Useful with waptagent-ldap, defines if the LDAP request must be encrypted.

verify_cert_ldap = True

Useful with waptagent-ldap, define whether the certificate should be verified.

ldap_auth_base_dn = dc=domain,dc=lan

Useful with waptagent-ldap, defines the base dn for the LDAP request.

ldap_auth_server = srvads.domain.lan

Useful with waptagent-ldap, defines the LDAP server to contact.

waptservice_user = admin

Forces a user to authenticate on the WAPT service.

waptservice_password = 5e884898da

sha256 hashed password when waptservice_user is used (the value NOPASSWORD disables the requirement for a password).

Settings for wapttray

Description of available options for the WAPT tray

Options

Description

notify_user = 0

Prevents wapttray from sending notifications (popup).

Proxy settings

Description of available options for the WAPT Server

Options

Description

http_proxy = http://user:pwd@host_fqdn:port

HTTP proxy address

use_http_proxy_for_repo = 0

Use the proxy to access the repositories.

use_http_proxy_for_server = 0

Use a proxy to access the WAPT Server.

use_http_proxy_for_templates = 0

Use a proxy to access package template server.

Settings for creating packages

Description of available options for creating WAPT packages

Options

Description

personal_certificate_path = C:\private\org-coder.crt

Path to the Administrator’s private key.

default_sources_root = C:\waptdev

Directory for storing packages in development.

default_sources_root_host = C:\waptdev\hosts

Directory for storing host packages in development.

default_package_prefix = tis

Default prefix for new or imported packages.

default_sources_suffix = wapt

Default prefix for new or imported packages.

Settings for WAPT Windows Updates

Refer to this article on configuring WAPTWUA on the WAPT agent.

Overriding settings of upload functions

It’s possible to override upload commands to define a particular behavior when uploading packages. It’s possible for example to upload packages on several repositories, or via another protocol, etc.

To upload packages on the repository (wapt-get upload-package or build-upload), use:

upload_cmd="C:\\Program Files (x86)\\WinSCP\\WinSCP.exe" admin@srvwapt.mydomain.lan /upload %(waptfile)s

To upload host-packages on the repository (upload-package or build-upload of a host package), use:

upload_cmd_host="C:\\Program Files (x86)"\\putty\\pscp -v -l admin %(waptfile)s srvwapt.mydomain.lan:/var/www/wapt-host/

To launch a command after a package upload, use:

after_upload="C:\\Program Files (x86)"\\putty\\plink -v -l admin srvwapt.mydomain.lan "python /var/www/wapt/wapt-scanpackages.py /var/www/%(waptdir)s/"

Configuring the agents using a WAPT package

After standard installation, the default configuration is:

[global]
waptupdate_task_period=120
waptserver=https://srvwapt.mydomain.lan
repo_url=https://srvwapt.mydomain.lan/wapt/
use_hostpackages=1

Making changes in wapt-get.ini and regenerating an agent is not sufficient to push the new configuration.

You can create a WAPT package to push updated wapt-get.ini settings.

The package is available from the Tranquil IT repository: https://store.wapt.fr/wapt/tis-wapt-conf-policy_6_f913e7abc2f223c3e243cc7b7f95caa5.wapt:

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

uninstallkey = []

def install():

  print('Modify max_gpo_script_wait')
  inifile_writestring(WAPT.config_filename,'global','max_gpo_script_wait',180)

  print('Modify Preshutdowntimeout')
  inifile_writestring(WAPT.config_filename,'global','pre_shutdown_timeout',180)

  print('Disable Hyberboot')
  inifile_writestring(WAPT.config_filename,'global','hiberboot_enabled',0)

  print('Disable Notify User')
  inifile_writestring(WAPT.config_filename,'global','notify_user',0)

Configuring the WAPT console

Hint

The configuration file for the WAPT console is stored in C:\Users\%username%\AppData\Local\waptconsole\waptconsole.ini. This file is automatically generated when the waptconsole is first launched and it is generated from the wapt-get.ini file configured on the Administrator’s workstation.

Several options are available in the [global] section of the waptconsole.ini file:

Description of available options for the WAPT console

Options

Description

wapt_server = https://srvwapt.mydomain.lan

Address of the WAPT Server.

repo_url = https://srvwapt.mydomain.lan/wapt

Address of the main WAPT repository.

last_usage_report = 03/01/2017 18:45:51

Date when the WAPT console was last used.

http_proxy =

Address of the proxy server in the console.

use_http_proxy_for_server = 0

Use a proxy to connect to the WAPT Server from the console.

use_http_proxy_for_repo = 0

Use a proxy to connect to the main WAPT repository from the console.

default_package_prefix = tis

Prefix used for naming WAPT packages.

default_sources_root = C:\waptdev

WAPT base package development folder.

personal_certificate_path = C:\private\mykey.crt

Path to the certificate associated with the Administrator’s private key.

send_usage_report = 1

Allows the WAPT console to send anonymous statistics to Tranquil IT.

language = en

Language of the WAPT console.

advanced_mode = 0

Launches the console in debug mode.

verify_cert = C:\Program Files (x86)\wapt\ssl\server\srvwapt.mydomain.lan.crt (on Windows)

For verifying HTTPS certificates.

waptservice_timeout = 2

Timeout for actions applied to WAPT agents (ex: update).

enable_external_tools = 0

Displays the actions that call external applications (RDP, VNC, etc…).

enable_management_features = 0

Displays the button to create self-signed certificates or to create the WAPT agent’s installer.

hide_unavailable = 0

Hides actions that are not available for the WAPT agent.

check_certificates_validity = 1

Forces the package certificate’s date and CRL to be verified.

sign_digests = sha256,sha1

List of allowed signature algorithms for the WAPT packages.

Configuring external repositories

You may add several external repositories by adding [sections] in C:\Users\%username%\AppData\Local\waptconsole\waptconsole.ini.

Example:

[store.wapt.fr]
repo_url=https://store.wapt.fr/waptdev
verify_cert=1
http_proxy=http://proxy.mydomain.lan:8080
public_certs_dir=
timeout=2

[otherwapt.tranquil.it]
repo_url=https://otherwapt.tranquil.it/waptdev
verify_cert=0
http_proxy=
public_certs_dir=c:\Users\admin\Documents\ssl\otherwapt\
timeout=2
Description of available options for external repositories

Options

Description

repo_url = http://srvwapt.mydomain.lan/wapt

Address of the external WAPT repository.

http_proxy = http://proxy.mydomain.lan:8080

Address of the proxy to use to access the external repository referenced in the [section].

verify_cert = 1

For verifying HTTPS certificates.

public_certs_dir =

Folder that contains the certificates used to authenticate downloaded external packages.

timeout = 2

Timeout for the external repository referenced in the [section]. If left empty, no verification is performed.

Settings for creating WAPT packages

Description of available options for creating WAPT packages

Options

Description

personal_certificate_path = C:\private\coder.crt

Path to the private key to be used to sign packages.

default_sources_root = C:\waptdev

WAPT base package development folder.

default_sources_root_host = C:\waptdev\hosts

WAPT host package development folder.

default_package_prefix = tis

Default prefix for new WAPT packages.

default_sources_suffix = wapt

Default suffix for new WAPT packages.

Configuring the WAPT Server

The WAPT Server configuration file on GNU/ Linux systems is found in /opt/wapt/conf/waptserver.ini.

The WAPT Server configuration file on Windows systems is found in C:\wapt\conf\waptserver.ini.

Attention

Modification of these files is reserved for advanced users!!

Section [option]

Several options can be defined in the section:

[options]
Available parameters for the [option] section of waptserver.ini

Options

Description

allow_unauthenticated_connect = False

Defines whether websocket connections should be authenticated

allow_unauthenticated_registration = True

Allows the initial registration of the WAPT agent using a login and password

allow_unsigned_status_data = False

Debug only - Allows unsigned status data from agent

application_root = ‘’

Set custom WAPT server application root path (ex: wapt)

auto_create_ldap_users = True

Related to user ACLs

client_certificate_lifetime = 3650

Host certificate lifetime

clients_read_timeout = 5

Websocket client timeout

clients_signing_certificate =

Host certificates signing cert

clients_signing_crl_days =

Host certificates signing CRL day

clients_signing_crl =

Host certificates signing CRL

clients_signing_crl_url =

Host certificates signing CRL URL

clients_signing_key =

Host certificates signing key

client_tasks_timeout = 1

Maximum allowed delay before WAPT agent requests timeout

db_connect_timeout = 10

Maximum allowed delay before PostgreSQL queries timeout

db_host =

Address of the PostgreSQL server (empty by default, it will use a local Unix Socket).

db_max_connections = 100

Maximum simultaneous connections to the PostgreSQL database

db_name = wapt

Name of the PostgreSQL database that the WAPT Server will connect to.

db_password =

Password for authenticating the user on the PostgreSQL database (default: empty, it will use a local UNIX socket)

db_port = 5432

Port of the PostgreSQL server

db_stale_timeout = 300

Database stale timeout, default to 300 seconds

db_user =

Name of the PostgreSQL user connecting to the database (default: empty, it will use a local UNIX socket).

enable_store = False

Enables WAPT Store Webui (WAPT Enterprise only)

encrypt_host_packages = False

Encrypt host package with client certificate

htpasswd_path = None

Adds basic authentication to WAPT Server

http_proxy = http://srvproxy.mydomain.lan:3128

Defines the proxy server to allow the WAPT server to recover its CRL

known_certificates_folder = /opt/wapt/ssl/

Adds additional knowed CA for certificate validation

ldap_auth_base_dn = None

Defines LDAP authentication base DN

ldap_auth_server = None

Defines LDAP authentication server

ldap_auth_ssl_enabled = True

Sets SSL auth on LDAP connections

loglevel = debug

Debug level. default level is warning

max_clients = 4096

Sets maximum simultaneous WAPT clients connection

min_password_length = 10

Sets minimum admin password length

nginx_http = 80

Defines Nginx http port (Windows only)

nginx_https = 443

Defines Nginx https port (Windows only)

remote_repo_diff = False

Enable remote repositories diff

remote_repo_support = True

Enables remote repositories functionality on WAPT Server

remote_repo_websockets = True

Enables websocket communication with remote repositories agents

secret_key = FKjfzjfkF687fjrkeznfkj7678jknk78687

Random string for initializing the Python Flask application server. It is generated when first installing the WAPT Server and is unique for every WAPT Server.

server_uuid = 76efezfa6-b309-1fez5-92cd-8ea48fc122dc

WAPT Server UUID (this anonymous id is used for WAPT statistics).

signature_clockskew = 72000

Maximum allowed time difference for the websockets

token_lifetime = 43200

Authentication token lifetime

trusted_signers_certificates_folder = None

Path to trusted signers certificate directory

trusted_users_certificates_folder = None

Path to trusted users CA certificate directory

use_kerberos = True

Requires a kerberos authentication when first registering the WAPT agent.

use_ssl_client_auth = False

Enables client certification authentication

wapt_admin_group_dn = CN=waptadmins,OU=groups,DC=ad,DC=mydomain,DC=lan

LDAP DN of Active Directory User Group allowed to connect to WAPT console

wapt_admin_group = None

CN of Active Directory User Group allowed to connect to WAPT console

wapt_folder = /var/www/wapt

Directory of the WAPT repository.

wapt_huey_db = C:\Program Files(x86)\wapt\db\waptservertasks.sqlite

Path to database that handles tasks

wapt_password = 46642dd2b1dfezfezgfezgadf0ezgeezgezf53d

SuperAdmin password for connecting to the WAPT console.

waptserver_port = 8080

Specify WAPT Server python service port, default to 8080

wapt_user = admin

Defines the SuperAdmin username in the WAPT console.

waptwua_folder = /var/www/waptwua

Location of WAPT WUA folder

wol_port = 9,123,4000

List of WakeOnLAN UDP ports to send magic packets to

wapt_bind_interface = 127.0.0.1

Define how to listen to the waptserver service

Configuring Nginx

The default Nginx configuration is as follows:

server {
  listen                      80;
  listen                      443 ssl;
  server_name                 _;
  ssl_certificate             "/opt/wapt/waptserver/ssl/cert.pem";
  ssl_certificate_key         "/opt/wapt/waptserver/ssl/key.pem";
  ssl_protocols               TLSv1.2;
  ssl_dhparam                 /etc/ssl/certs/dhparam.pem;
  ssl_prefer_server_ciphers   on;
  ssl_ciphers                 'EECDH+AESGCM:EDH+AESGCM:AES256+EECDH:AES256+EDH';
  ssl_stapling                on;
  ssl_stapling_verify         on;
  ssl_session_cache           none;
  ssl_session_tickets         off;
  index index.html;

  location ~ ^/wapt.* {
    proxy_set_header Cache-Control "store, no-cache, must-revalidate, post-check=0, pre-check=0";
    proxy_set_header Pragma "no-cache";
    proxy_set_header Expires "Sun, 19 Nov 1978 05:00:00 GMT";
    root "/var/www";
    }

  location / {
    proxy_set_header X-Real-IP  $remote_addr;
    proxy_set_header Host $host;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_set_header X-Forwarded-Proto $scheme;

  location  ~ ^/(api/v3/upload_packages|api/v3/upload_hosts/|upload_waptsetup)  {
    proxy_pass http://127.0.0.1:8080;
    client_max_body_size 4096m;
    client_body_timeout 1800;
    }

  location /wapt-host/Packages {
    return 403;
    }

  location /wapt-host/add_host_kerberos {
    return 403;
    }

  location / {
    proxy_pass http://127.0.0.1:8080;
    }

  location /socket.io {
    proxy_http_version 1.1;
    proxy_buffering off;
    proxy_set_header Upgrade $http_upgrade;
    proxy_set_header Connection "Upgrade";
    proxy_pass http://127.0.0.1:8080/socket.io;
    }
  }
}

Configuring WAPT Server for large deployments

The default operating system, Nginx and Postgresql settings are adapted for around 400 WAPT agents. If you have more than 400 clients it is necessary to modify a few system level parameters along with PostgreSQL database, Nginx web and WAPT Server python server.

In the future the postconf.sh script might take charge of this configuration depending on the expected number of client computers.

With the following parameters, one WAPT Server should scale up to around 5000 concurrent active clients. You may have more clients in the database if they are not all running at the same time. If you have more than 5000 clients it is recommended to have more than one WAPT Server.

The limit in the number of end point clients is due to the bottleneck in the python code and the PostgreSQL backend. WAPT performance gets better with time and in the future WAPT Server might support a large base on a single server. However the Nginx part scales very well and it can takes full advantage of a 10Gbps connection for high load package deployments.

Note

The parameters to be modified below are linked together and should be modified globally and not individually.

Configuring Nginx

In the /etc/nginx/nginx.conf file (for Windows C:\wapt\waptserver\nginx\conf\nginx.conf), modify worker_connections parameter. The value should be around 2.5 times the number of WAPT clients (n connections for websockets and n connections for package downloads and inventory upload + some margin).

events {
    worker_connections 4096;
}

Then upgrade the number of filedescriptors in the /etc/nginx/nginx.conf file (for Windows C:\wapt\waptserver\nginx\conf\nginx.conf):

worker_rlimit_nofile 32768;

Depending on the partitioning of your WAPT server you might have to be careful with the Nginx temporary file upload directory. Nginx acts as a reverse proxy for the WAPTServer Python engine and its does a caching of packages uploaded when uploading a new package from the console.

The packages are stored in the /var/lib/nginx/proxy directory. You have to make sure that the partition hosting this directory is large enough. You may change this directory location using the following Nginx configuration parameter.

$client_body_temp_path

Configuring the Linux System

Increase the number of filedescriptors. The system unit file asks for an increase in the allowed number of filedescriptors (LimitNOFILE=32768). We should have the same thing for Nginx. There are a few limits to modify.

First we modify system wide the number of filedescriptors allowed for Nginx and WAPT.

  • create the /etc/security/limits.d/wapt.conf:

    cat > /etc/security/limits.d/wapt.conf <<EOF
    wapt         hard    nofile      32768
    wapt         soft    nofile      32768
    www-data     hard    nofile      32768
    www-data     soft    nofile      32768
    EOF
    

Nginx serves as a reverse proxy and makes quite a lot of connections. Each WAPT client keeps a websocket connection up all the time in order to respond to actions from the WAPT Server.

The Linux kernel has a protection against having too many TCP connections opened at the same time and one may get the SYN flooding on port message in the Nginx log. In order to avoid these messages, it is necessary to modify the two following parameters. It must around 1.5 times the number of WAPT clients.

cat > /etc/sysctl.d/wapt.conf <<EOF
net.ipv4.tcp_max_syn_backlog=4096
net.core.somaxconn=4096
EOF

sysctl --system

Configuring the PostgreSQL database

A higher number of clients need a higher number of connections to the PostgreSQL database. In the postgresql.conf file (file:/etc/postgresql/11/main/postgresql.conf on debian 10 for example or for Windows C:\wapt\waptserver\pgsql9.6_data\postgresql.conf), you need to increase the following parameter to approximately 1/4 the number of active WAPT agents.

max_connections = 1000

In /opt/wapt/conf/waptserver.ini file (for Windows C:\wapt\conf\waptserver.ini, db_max_connections should be equal to PostgreSQL max_connections minus 10 (PostgreSQL needs to keep some connections for its housekeeping stuff). The max_clients parameter should be set around 1.2 times the number of WAPT agents:

[options]
...
max_clients = 4096
db_max_connections =  990