WAPT package structure

A WAPT package is a .zip file containing several things:

WAPT package structure

WAPT package structure

  • a file setup.py;

  • one or several binary files;

  • some additional optional files;

  • a control file in the WAPT folder;

  • a icon.png file in the WAPT folder;

  • a certificate.crt file in the folder WAPT;

  • a manifest.sha256 file in the folder WAPT;

  • a signature.sha256 file in the folder WAPT;

  • a wapt.psproj file in the folder WAPT, this file is used to store the PyScripter configuration data for the WAPT package;

  • since WAPT 1.8, a hidden .vscode folder that contains a launch.json and a settings.json file used to store the VScode configuration data for the WAPT package;

The control file

The control file is the identity card of a package.

package           : tis-firefox-esr
version           : 62.0-0
architecture      : all
section           : base
priority          : optional
maintainer        : Administrateur
description       : Firefox Web Browser French
description_fr    : Navigateur Web Firefox Français
description_es    : Firefox Web Browser
depends           :
conflicts         :
maturity          : PROD
locale            : fr
target_os         : windows
min_os_version    :
max_os_version    :
min_wapt_version  : 1.6.2
sources           :
installed_size    :
impacted_process  : firefox.exe
audit_schedule    :
editor            : Mozilla
keywords          : Navigateur
licence           : MPL
homepage          : https://www.mozilla.org/en-US/firefox/organizations/
signer            : Tranquil IT
signer_fingerprint: 459934db53fd804bbb1dee79412a46b7d94b638737b03a0d73fc4907b994da5d
signature         : MLOzLiz0qCHN5fChdylnvXUZ8xNJj4rEu5FAAsDTdEtQ(...)hsduxGRJpN1wLEjGRaMLBlod/p8w==
signature_date    : 20170704-164552
signed_attributes : package,version,architecture,section,priority,maintainer,description,depends,conflicts,maturity,locale,min_os_version,max_os_version,min_wapt_version,sources,installed_size,signer,signer_fingerprint,signature_date,signed_attributes
Description of options of the control file

Settings

Description

Example value

package

Package name

tis-geogebra

version

Package version, can not contain more than 5 delimiters, the last number being the version number of the packaging

5.0.309.0-1

architecture

Processor architecture

x64

section

Package type (host, group, base)

base

priority

Package install priority (optional)

Not mandatory for the moment

maintainer

Author of the package

Arnold Schwarzenegger <terminator@mydomain.lan>

description

Package description that will appear in the console and on the web interface

The Graphing Calculator for Functions, Geometry, Algebra, Calculus, Statistics and 3D

description_fr

Localized description of the package

Calculatrice graphique

depends

Packages that must be installed before installing the package

tis-java

conflicts

Packages that must be uninstalled before installing the package

tis-graph

maturity

Maturity level (BETA, DEV, PROD)

PROD

locale

Language environment for the package

fr,en,es

target_os

Accepted Operating System for the package

windows,mac,linux

min_os_version

Minimum version of Windows for the package to be seen by the WAPT agent

6.0

max_os_version

Maximum version of Windows for the package to be seen by the WAPT agent

8.0

min_wapt_version

WAPT’s minimal version for the package to work properly

1.3.8

sources

Path to the SVN location of the package (source command)

https://srv-svn.mydomain.lan/sources/tis-geogebra-wapt/trunk/

installed_size

Minimum required free disk space to install the package

254251008

impacted_process

Indicates a list of impacted processes when installing a package

firefox.exe

audit_schedule

Periodicity of execution of the audit function in the WAPT package

60

editor

Editor of the software package

Mozilla

license

Reference of the software license

GPLV3

keywords

Set of keywords describing the WAPT package

Productivity,Text Processor

homepage

Official homepage of the software embedded in the WAPT package

https://www.tranquil.it/

signer

CommonName (CN) of the package’s signer

Tranquil IT

signer_fingerprint

Fingerprint of the certificate holder’s signature

2BAFAF007C174A3B00F12E9CA1E74956

signature

SHA256 hash of the package

MLOzLiz0qCHN5fChdylnvXUZ8xNJj4rEu5FAAsDTdEtQ(…)hsduxGRJpN1wLEjGRaMLBlod/p8w==

signature_date

Date when the package was signed

20180307-230413

signed_attributes

List of package’s attributes that are signed

package, version, architecture, section, priority, maintainer, description, depends, conflicts, maturity, locale, min_wapt_version, sources, installed_size, signer, signer_fingerprint, signature_date, signed_attributes

Attention

If the control file contains special characters, the control file must be saved in UTF-8 (No BOM) format.

PyScripter - UTF-8 (No BOM)

PyScripter - UTF-8 (No BOM)

Fields details

package

WAPT package name, without any accent, nor space, nor any special or uppercase character.

version

Preferably, always start with the packaged software version (digits only) split by points (.) and finish with the WAPT packaging version separated by a dash (-) character.

architecture

New in version 1.5.

Defines whether the package may be installed on x64 or x32 processor equipped computers.

Note

A x64 package will be invisible for a WAPT agent installed on a x86 machine.

Allowed values:

  • x86: the package is designed for 32bit computers;

  • x64: the package is designed for 64bit computers;

  • all: the package is designed for 32bit or 64bit computers;

section

  • host: host package;

  • group: group package;

  • base: software package;

  • unit: OU package;

priority

This option is not supported at this time. That field will be used to define package installation priority. This feature will become useful to define mandatory security updates.

maintainer

Defines the WAPT package creator.

Note

To define the WAPT package creator’s email address may be useful.

Use Firstname LASTNAME <email@example.com> format.

description

Describes the functionality of the package that will appear in the console and on the local web interface http://127.0.0.1:8088.

Hint

Adding a field description_fr or description_es allows you to internationalize the description of your package. If the language does not exist, the WAPT agent will use the default language description.

depends

Defines the packages that must be installed before, for example tis-java is a dependency for the LibreOffice package and tis-java must be installed before LibreOffice.

Several dependencies may be defined by splitting them with commas (,).

depends: tis-java,tis-firefox-esr,tis-thunderbird

conflicts

Works as the opposite of depends.

conflicts defines package(s) that must be removed before installing a package, for example tis-firefox must be removed before the package tis-firefox-esr is installed, or OpenOffice must be removed before LibreOffice is installed.

Several conflicts may be defined by splitting them with commas (,).

conflicts: tis-firefox

maturity

New in version 1.5.1.19.

Defines the maturity of a package.

By default, WAPT agents will see packages flagged as PROD and packages with an empty maturity.

For a computer to see packages with different maturity levels, you will have to configure the maturities attribute in wapt-get-ini of the WAPT agent.

locale

New in version 1.5.1.19.

Defines the language of the WAPT package.

A WAPT agent will see by default packages that are configured for its language environment(s) and packages with no language specified.

For a computer to see a package in another language, you will have to configure the locales in wapt-get.ini of the WAPT agent.

locales = fr,en,es

The language filled in the field must be in ISO 639-1 format.

target_os

New in version 1.5.1.18.

Defines the Operating System for the package.

A WAPT agent will see by default packages that are configured for its operating system and packages with no operating system specified.

Since version 1.8 the field target_os can either be windows, macos, linux or left empty.

min_os_version

New in version 1.3.9.

For a windows target_os, this field defines the minimal Windows Operating System Version. For example, this attribute may be used to avoid installing on WindowsXP packages that only work on Windows7 and above.

Since version 1.8, it can also define the minimal Mac OS version. We advise not to use it with Linux since there are several different distributions.

max_os_version

New in version 1.3.9.

For a windows target_os, it defines the maximal Windows Operating System Version. For example, this attribute may be used to install on Windows7 more recent versions of a software that are no more supported on Windows XP.

Since version 1.8, it can also define the minimal Mac OS version. We advise not to use it with Linux since there are several different distributions.

min_wapt_version

New in version 1.3.8.

WAPT minimum version to install a package

Note

With functionalities in WAPT evolving, some functions that you may have used in old packages may become obsolete with newer versions of WAPT agents.

sources

Defines a SVN repository, for example:

This method allows to version a package and collaboratively work on it.

Hint

Package versionning is particularly useful when several people create packages in a collaborative way. This function is also useful to trace the history of a package if you are subject to Regulations in your industry.

installed_size

Defines the required minimum free disk space to install the package.

installed_size: 254251008

The testing of available free disk space is done on the C:\Program Files folder.

The value set in installed_size must be in bytes.

Hint

To convert storage values to bytes, visit https://bit-calculator.com/.

impacted_process

New in version 1.5.1.18.

Indicates processes that are impacted when installing a package.

Example:

impacted_process : firefox.exe,chrome.exe,iexplorer.exe

This field is used by the functions install_msi_if_needed and install_exe_if_needed if killbefore has not been filled.

impacted_process is also used when uninstalling a package. This allows to close the application if the application is running before being uninstalled.

audit_schedule

New in version 1.6.

Periodicity of execution of audit checks.

audit_schedule : 60

The periodicity may be indicated in several ways:

  • an integer (in minutes);

  • an integer followed by a letter (m = minutes, h = hours, d = days, w = weeks);

editor

New in version 1.6.

Software editor of the binaries embedded in the WAPT base package.

editor: Mozilla

The values may be used as filters in the WAPT console and with the self-service.

keywords

New in version 1.6.

Keyword list to categorize the WAPT package.

keywords: office

The values may be used as filters in the WAPT console and with the self-service.

license

New in version 1.6.

Reference of the software license for the embedded software binaries.

license : GPLV3

The values may be used as filters in the WAPT console and with the self-service.

homepage

New in version 1.6.

Official homepage of the software binaries embedded in the WAPT package.

homepage : https://wapt.fr

The values may be used as filters in the WAPT console and with the self-service.

signer

Automatically filled during package signature.

CN of the certificate. It is typically the signer’s full name.

signer_fingerprint

Automatically filled during package signature.

Private key fingerprint of the package signer.

signature

Automatically filled during package signature.

Signature of the attributes of the package.

signature_date

Automatically filled during package signature.

Date when the attributes of the package have been signed.

signed_attributes

Automatically filled during package signature.

List of the package’s attributes that are signed.

The setup.py file

import setuphelpers

That line is found at the beginning of every WAPT package that embeds a setup.py:

from setuphelpers import *

The package imports all setuphelpers functions.

Setuphelpers is a WAPT library that offers many methods to more easily develop highly functional packages.

uninstallkey list

We then find:

uninstallkey = ['tisnaps2','Mozilla Firefox 45.6.0 ESR (x86 fr)']

We associate here a list of uninstall keys to the package. When a package is removed, the WAPT agent looks up the uninstallkey in the registry associated to the package. This uninstallkey will indicate to WAPT the actions to trigger to remove the software.

Even if there is no uninstallkey for a software, it is mandatory to declare an empty uninstallkey array:

uninstallkey = []

Function install()

Then comes the setup.py function declaration.

It is the recipe of the WAPT package, the set of instructions that will be executed.

def install():
    run('"install.exe" /S')

The wapt.psproj file

Package project file wapt.psproj is found in the WAPT folder.

It’s the PyScripter project file for the WAPT package.

To edit a package with PyScripter, just open the file.

The icon.png file

The icon.png icon file is located in the WAPT folder.

It associates an icon to the package.

That icon will appear in the local web interface of WAPT self-service (http://127.0.0.1:8088).

Hint

The icon must be a 48px per 48px PNG file.

The manifest.sha256 file

The manifest.sha256 manifest file is located in the WAPT folder.

It contains the sha256 fingerprint of every file in the WAPT package.

The signature file

The signature file is located in the WAPT folder.

It contains the signature of the manifest.sha256 file.

On installing a package, wapt-get checks:

  • that the signature of manifest.sha256 matches the actual manifest.sha256 file (the agent will verify the public certificates in C:\Program Files (x86)\wapt\ssl on Windows and /opt/wapt/ssl on Linux and MacOS);

  • that the sha256 fingerprint of each file is identical to the fingerprint in the manifest.sha256 file;

Other files

Other files may be embedded in the WAPT package. For example:

  • an installer beside your setup.py to be called in your setup.py;

  • an answer file to pass on to the software installer;

  • a license file;