3. Using the WAPT Console advanced features

This page details the advanced use of the WAPT Console.

3.1. Using Organizational Unit packages in WAPT

3.1.1. Working principle

WAPT Enterprise offers Organizational Unit package functionality.

unit packages automate software and configuration installations based on the Active Directory tree. It is a very powerful feature when used properly.

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

Note

If the computer is removed from an Organizational Unit, obsolete unit packages are removed.

The WAPT Agent is aware of its position in the Active Directory tree structure, therefore it knows the hierarchy of Organizational Units that concerns it, for example:

DC=ad,DC=mydomain,DC=lan
OU=Paris,DC=ad,DC=mydomain,DC=lan
OU=computers,OU=Paris,DC=ad,DC=mydomain,DC=lan
OU=service1,OU=computers,OU=Paris,DC=ad,DC=mydomain,DC=lan

If a unit package is defined on each Organisational Unit level, the WAPT Agent will automatically download WAPT packages and configurations that are attached to each level. Using inheritance, WAPT will apply WAPT packages and dependencies that are attached to each Organizational Unit.

3.1.2. Creating Organizational Unit packages

You can create unit packages by Right-clicking on an OU ‣ Create or Edit Organizational Unit package.

A window opens and you are prompted to choose which packages to include in the unit bundle.

Adding WAPT packages to a unit bundle

Save the WAPT package and it will be deployed to all hosts belonging to the selected OU.

When you have a unit bundle, you will see a cube before the OU name in the WAPT Console.

3.1.3. Actions available with Organizational Units

Menu items for creating or editing Organizational Unit package

Menu item	Description
The Create or Edit Organizational Unit package menu item	Visit this documentation for more details on creating or editing OU packages.
The Check updates on all hosts of this OU menu item	Allows to upload the current state of the host to the WAPT Server and force the WAPT Server to display whether the hosts in the selected OU have pending updates.
The Apply upgrades on all hosts of the OU menu item	Allows to apply waiting WAPT updates and upgrades on the all hosts in the OU.

Hint

You may filter how hosts are displayed based on the Active Directory OU they belong to.

The checkbox Include hosts in subfolders allows to display hosts in subfolders.

3.1.4. Faking Organizational Units for WORKGROUP hosts

It can happen that some specific hosts cannot be joined to an Active Directory domain.

Therefore, these hosts do not show up in the Active Directory Organizational Units in the WAPT Console.

To make all hosts show up in the WAPT Console under the right Organizational Unit, whether they are joined to an AD domain or not, WAPT allows to specify a fake Organizational Unit in the WAPT Agent configuration file.

The benefits of this very useful trick are:

• You can manage out-of-domain, workgroup and Windows Home Edition hosts with WAPT as if they were joined to the Active Directory.

• Out-of-domain, workgroup and Windows Home Edition hosts are now showing up in the Active Directory tree view in the WAPT Console.

To setup a fake Organizational Unit on hosts, create an empty WAPT package, then use the following code:

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

uninstallkey = []

def install():

  print('Setting Fake Organizational Unit')
  fake_ou = "OU=REAL_AD_SUB_OU,OU=REAL_AD_OU,DC=MYDOMAIN,DC=LAN"
  inifile_writestring(WAPT.config_filename,'global','host_organizational_unit_dn',fake_ou)

  print('Reload WAPT configuration')
  WAPT.reload_config_if_updated()

def update_package():
  pass

The host_organizational_unit_dn will be like below in wapt-get.ini:

[global]
host_organizational_unit_dn=OU=REAL_AD_SUB_OU,OU=REAL_AD_OU,DC=MYDOMAIN,DC=LAN

Note

• Stick to a specific case with your host_organizational_unit_dn (do not mix “dc”s and “DC”s, “ou”s and “OU”s …).

• Follow the letter case used in the DN/computer_ad_dn fields in the hosts inventory grid.

3.2. Using profile bundles in WAPT

3.2.1. Working principle

WAPT Enterprise offers an Active Directory profile bundle functionality.

The profile bundle automates the installation of WAPT packages and configuration packages on hosts based on their membership to Active Directory Computer Security Groups.

The WAPT Agent will report to the WAPT Server the Active Directory groups to which the host belongs.

If a profile package has the same name as an Active Directory group, then the WAPT agent will install automatically the profile package for the Active Directory group of which the host is a member.

If the host is no longer a member of its Active Directory group, then the matching profile package will be uninstalled.

Profile packages are stored in the web directory https://srvwapt.mydomain.lan/wapt/.

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 WAPT upgrades.

Note

For performance reasons, this feature is enabled only if the use_ad_groups option is enabled in the wapt-get.ini configuration file of the WAPT Agent.

Important

The Active Directory Computers security groups and sub-groups contain Computers, not Users.

Window showing the Computers group in Active Directory

Warning

Automatically installing software and configurations based on user and user group membership is not implemented with WAPT and such implementation is not desirable. The use case of installing software based on user profile is better served with the differentiated self-service feature that is also available with WAPT Enterprise.

The name of the group MUST be lower case in Active Directory and in the WAPT Console.

3.2.2. Creating WAPT profile bundles in the WAPT Console

You can create profile bundle WAPT packages by clicking on Make package template from setup file ‣ AD profile.

Important

Requirements:

• The profile AD group name and the profile package MUST be all lower case.

Example:

• AD Security group: hw_laptops;

• WAPT profile bundle: hw_laptops.

A window opens and you are prompted to choose which WAPT packages are to be included in the newly created profile bundle.

Adding WAPT packages to a profile bundle in the WAPT Console

Save the profile bundle and it will be uploaded to the WAPT Server.

3.3. Adding plugins in the WAPT Console

To add custom plugins, go to the Tools ‣ Preference ‣ Plugins Tab.

Creating a custom plugin in the WAPT Console

Click Add to add a plugin, then edit the corresponding columns.

Column	Description
Name	Name that will appear in the menu.
Executable	Path of the executable that will be executed.
Arguments	Arguments passed to the executable. All the parameters that are diplayed in the grid can be used, like {ip}, {uuid} or {computer_fqdn}. To get the parameter name, you may right-click on the column header, and the name will be displayed in parentheses beside the column name.

Plugins will then appear in the menu:

Creating a custom plugin in the WAPT Console

3.4. Managing several WAPT Server profiles in the WAPT Console

You can connect the WAPT Console to several WAPT Servers.

To do so, go to %localappdata%waptconsole, copy the waptconsole.ini file and rename it, for example waptconsole2.ini. Modify the new file with the second WAPT Server parameters (ex: IP / DNS, prefix, etc).

Then, when you re-open the WAPT Console, you can select one WAPT Server or the other.

Window showing connections with several WAPT Server profiles

Hint

You can have several WAPT Server connection profiles but the WAPT Servers do not communicate between them.

3.5. Using the WAPT System Tray utility

The WAPT System Tray utility is a systray program working in user context.

The WAPT System Tray utility launches at logon if you enable it with the following package: tis-enable-wapttray. The icon will show up in the Windows tray toolbar.

One can also launch the WAPT System Tray utility manually on C:\Program Files (x86)\wapt\wapttray.exe.

3.5.1. Functionalities of the WAPT System Tray utility

Main functionsConfiguration functions

List of functionalities of the WAPT System Tray utility

Action	Description
View software status	Launches the local web interface in a web browser.
Update software inventory	Refreshes the list of available WAPT packages. Double-clicking on the tray icon brings about the same effect.
Install updates	Launches the installation of pending upgrades.
Run WAPT Self-service	Launches the WAPT Self-Service.
Run WAPT Console	Launches the WAPT Console.
Configuration	See following table for detailed list of options.
Configuring all installed packages for your own session	Launches a session-setup to configure user environment for all packages installed on the host.
View tasks	Display the task list on the local web interface in the web browser.
Cancel current task	Cancels a running task on WAPT Agent.
Cancel all current tasks	Cancels all running tasks on WAPT Agent.
WAPT service running	Stops and reloads the WAPT service.
Quit	Closes the tray icon without stopping the local WAPT service.

3.5.2. Video demonstration

3.6. Using the WAPT Exit utility

The WAPT Exit utility allows to upgrade and install WAPT packages when a host is shutting down, at the user’s request, or at a scheduled time.

The mechanism is simple. If WAPT packages are waiting to be upgraded, they will be installed.

The WAPT Exit method is very effective in most situation because it does not require the intervention of the User or the Administrator.

The WAPT Exit utility executes by default on shutdown, it is installed with the WAPT Agent.

The behavior of the WAPT Exit utility is customizable in wapt-get.ini of the WAPT Agent.

Warning

If a WAPT task is running, the shutdown of the host is suspended until the task has completed or timed-out.

The WAPT Exit utility can be manually executed by running C:\Program Files (x86)\wapt\waptexit.exe.

3.6.1. Triggering the WAPT Exit utility with a scheduled task

One can deploy a GPO or a WAPT package that will trigger the WAPT Exit utility at a pre-scheduled time.

Triggering the WAPT Exit utility with a scheduled task is best suited for servers that are not shutdown frequently.

You may adapt the procedure describing how to deploy the WAPT Agent to trigger the WAPT Exit utility script at the most appropriate time.

You can use the following script for your scheduled task, adapted to your need:

waptpython -c "from waptservice.enterprise import start_waptexit start_waptexit('',{'only_priorities':False,'only_if_not_process_running':True, 'install_wua_updates':False,'countdown':300},'schtask')"

Warning

• All running software that are upgraded may be killed with possible loss of data.

• The WAPT Exit utility may fail to upgrade a software program if a software that you are upgrading is in the impacted_process list of the control file. See below for more information.

• The method of triggering the WAPT Exit utility at a scheduled time is the least recommended method for desktops. It is better to let the WAPT Exit utility execute at shutdown or on user request.

3.6.2. The WAPT Exit utility settings in wapt-get.ini

It is possible to modify the behavior of the WAPT Exit utility in the wapt-get.ini.

It is also possible to modify the behavior of the WAPT Exit utility directly from the command line, see the next points.

3.6.3. The WAPT Exit utility options with the command line

3.6.3.1. Avoiding the cancellation of upgrades

To disable the interruption of the installation of updates you can run the WAPT Exit utility with the argument:

waptexit.exe -allow_cancel_upgrade = True

3.6.3.2. Increasing the trigger time in the WAPT Exit utility

To specify the wait time before the automatic start of the installations you can start the WAPT Exit utility with the argument:

waptexit.exe -waptexit_countdown = 10000

3.6.3.3. Avoiding to interrupt user activity

To tell WAPT not to run an upgrade of software titles currently running on the host (impacted_process attribute of the WAPT package), the WAPT Exit utility may be run with the argument -only_if_not_process_running.

waptexit.exe -only_if_not_process_running = True

If not specified, the WAPT Exit utility will take the value indicated in C:\Program Files (x86)\wapt\wapt-get.ini.

3.6.3.4. Launching the installation of WAPT packages with a special level of priority

To tell WAPT to only upgrade WAPT packages with a specific priority, you can run the WAPT Exit utility with the argument -priorities.

waptexit.exe -priorities = high

3.6.3.5. Registering/ unregistering the WAPT Exit utility

To register or unregister the WAPT Exit utility in local shutdown group strategy scripts, use:

• to enable the WAPT Exit utility at host shutdown:

wapt-get add-upgrade-shutdown

• to disable the WAPT Exit utility at host shutdown:

wapt-get remove-upgrade-shutdown

3.6.3.6. Video demonstration

3.7. Customizing WAPT for better user acceptance

It is possible to customize WAPT with your company colors to improve user acceptance.

3 components of WAPT are customizable:

• the WAPT Exit utility;

• the WAPT Self-Service;

• the WAPT Message utility.

It is possible to use the same logo for all programs.

Place the image in <wapt_folder>\templates.

The logo MUST be named wapt-logo.png.

The recommended size of the logo is 200X55 and the recommended format is .png.

For a different logo per program, see next points.

3.7.1. The WAPT Exit utility

It is possible to customize the WAPT Exit utility by placing the image you want in <wapt_folder>\templates.

The logo MUST be named waptexit-logo.png.

The recommended size of the logo is 200X55 and the recommended format is .png.

If the file is not defined, WAPT uses by default wapt-logo.png.

3.7.2. WAPT Self-Service

It is possible to customize the WAPT Exit utility by placing the image you want in <wapt_folder>\templates.

The logo MUST be named waptself-logo.png

The recommended size of the logo is 200X55 and the recommended format is .png.

If it is not defined, WAPT uses in order waptexit-logo.png, waptself-logo.png and finally the default WAPT logo.

3.7.3. WAPT Message

It is possible to customize the WAPT Exit utility by placing the image you want in <wapt_folder>\templates.

The logo MUST be named waptmessage-logo.png.

The recommended size of the logo is 200X55 and the recommended format is .png.

If it is not defined, WAPT uses in order waptexit-logo.png, waptself-logo.png and finally the default WAPT logo.

3.8. Customizing the WAPT Console with its configuration file

Hint

the WAPT Console configuration is stored in 2 locations:

• C:\Users\%username%\AppData\Local\waptconsole\waptconsole.ini.

• C:\Users\%username%\AppData\Roaming\waptconsole\waptconsole.ini.

These files are automatically generated when the waptconsole is first launched and it is generated from the wapt-get.ini file configured on the Administrator’s workstation.

3.8.1. Description of available sections

Description of available sections for the WAPT Agent

Section	Description
[global]	Defines the global WAPT Console options.
[sections]	Defines external repository options. [wapt-template] repositories
[waptwua]	Defines the WUA options.

All sections are detailed below.

Others sections present on C:\Users\%username%\AppData\Roaming\waptconsole\waptconsole.ini are not editable manually, therefore they are not detailed.

Attention

For parameters both present in wapt-get.ini and waptconsole.ini, values are set in wapt-get.ini and copied to waptconsole.ini. Do not edit manually these parameters.

3.8.2. Description of available options by section

3.8.2.1. [global]

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

Description of available options in AppData\Local

Options (Default Value)	Description	Example
advanced_mode (default False)	Launches the WAPT Console in debug mode.	advanced_mode = True
allow_remote_reboot (default False)	Allows to reboot the selected host(s) remotely from the WAPT Console.	allow_remote_reboot = True
allow_remote_shutdown (default False)	Allows to shut down the selected host(s) remotely from the WAPT Console.	allow_remote_shutdown = True
client_certificate (default None)	Defines whether the remote repository is using Client Side SSL Authentification.	client_certificate = C:\private\org-coder.crt
client_private_key (default None)	Defines whether the remote repository is using Client Side SSL Authentification.	client_private_key = C:\private\org-coder.pem
check_certificates_validity (default False)	Forces the package certificate’s date and CRL to be verified.	check_certificates_validity = True
default_maturity (default None)	Defines the default upload maturity for WAPT packages.	default_maturity = PROD
default_package_prefix (default tis)	Defines the default prefix for new or imported packages. Prefix is case sensitive, we recommand to use lower case.	default_package_prefix = doc
default_sources_root (default C:\waptdev on Windows or ~/waptdev on Linux)	Defines the directory for storing packages while in development.	default_sources_root = C:\waptdev
grid_hosts_plugins (default W10=)	Lists external plugins for the WAPT Console. Default is W10= because [] is encoded in base64.	grid_hosts_plugins = W3siZXhlY3V0YWJsZSI6ImV4cGxd
host_profiles (default None)	Defines a WAPT package list that the WAPT Agent MUST install.	host_profiles = tis-firefox,tis-java
hiberboot_enabled (default False)	Disables Hiberboot on Windows 10 to make waptexit	hiberboot_enabled = True
http_proxy (default None)	Defines the address of the proxy server in the WAPT Console.	http_proxy = https://proxy.mydomain.lan
last_usage_report (default None)	Provides the date when the WAPT Console was last used.	last_usage_report = 12/05/2021 18:45:51
lastwaptserveruser (default None)	Provides the last user logged on this WAPT Console.	lastwaptserveruser = admin
max_gpo_script_wait (default 180)	Defines the timeout for GPO execution at computer shutdown (in seconds).	max_gpo_script_wait = 360
personal_certificate_path (default None)	Defines the path to the certificate associated with the Administrator’s private key.	personal_certificate_path = C:\private\mykey.crt
pre_shutdown_timeout (default 180)	Defines the timeout for scripts at computer shutdown (in seconds).	pre_shutdown_timeout = 360
repo_url (default your WAPT repo address)	Defines the address of the main WAPT repository.	repo_url = https://srvwapt.mydomain.lan/wapt
send_usage_report (default True)	Allows the WAPT Console to send anonymous statistics to Tranquil IT. Set to False to disable telemetry.	send_usage_report = True
sign_digests (default sha256)	Lists allowed signature algorithms for the WAPT packages.	sign_digests = sha1
use_ad_groups (default False)	Allows using unit packages.	use_ad_groups = True
use_fqdn_as_uuid (default False)	Allows using the FQDN rather than the BIOS UUID as the unique host identifier in WAPT.	use_fqdn_as_uuid = True
use_kerberos (default False)	Allows using kerberos authentication for initial registration of WAPT Agents with the WAPT Server.	use_kerberos = True
use_hostpackages (default False)	Allows using host packages.	use_hostpackages = True
use_http_proxy_for_repo (default False)	Allows using a proxy to connect to the main WAPT repository from the WAPT Console.	use_http_proxy_for_repo = True
use_http_proxy_for_server (default False)	Allows using a proxy to connect to the WAPT Server from the WAPT Console.	use_http_proxy_for_server = True
use_repo_rules (default False)	Allows using replication for repositories.	use_repo_rules = True
verify_cert (default False)	Allows verifying SSL / TLS certificate.	verify_cert = True
wapt_server (default None)	Defines the address of the WAPT Server.	wapt_server = https://srvwapt.mydomain.lan

Description of available options on AppData\Roaming

Options (Default Value)	Description	Example
advanced_mode (default False)	Launches the WAPT Console in debug mode.	advanced_mode = True
enable_external_tools (default False)	Displays the actions that call external applications (RDP, Windows tools etc…).	enable_external_tools = True
enable_management_features (default False)	Displays the button to create self-signed certificates or to create the WAPT Agent’s installer.	enable_management_features = True
hide_unavailable_actions (default False)	Hides actions that are not available for the WAPT Agent	hide_unavailable_actions = True
HostsLimit (default 2000)	Limits hosts displayed in the WAPT Console.	HostsLimit = 300
language (default language on the WAPT Client)	Forces the default langage for GUI (not for package filtering)	language = en
lastappinifilename (default None)	Defines the .ini file used to store the WAPT Console configuration.	lastappinifilename = C:\Users\%username%\AppData\Roaming\waptconsole\waptconsole.ini
show_host_audit_data_tab (default False)	Displays the Audit data tab on host inventory.	show_host_audit_data_tab = True
use_ad_groups (default False)	Allows using unit packages.	use_ad_groups = True
use_fqdn_as_uuid (default False)	Forces the use of the FQDN instead of the uuid BIOS as the unique host identifier in WAPT.	use_fqdn_as_uuid = True
waptconsole.version (default None)	Displays the version of the WAPT Console.	waptconsole.version = 2.0.0.9424
waptwua_enabled (default False)	Allows displaying the Windows Update tab on the WAPT Console.	waptwua_enabled = True

3.8.2.2. [sections]

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

Attention

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

For information on configuring the WAPT Agent, please refer to this point.

See available parameters and configurations by visiting this documentation on setting up multiple repositories.