.. Reminder for header structure:
  Parts (H1)          : #################### with overline
  Chapters (H2)       : ******************** with overline
  Sections (H3)       : ====================
  Subsections (H4)    : --------------------
  Subsubsections (H5) : ^^^^^^^^^^^^^^^^^^^^
  Paragraphs (H6)     : """"""""""""""""""""

.. meta::
  :description: Introduction to WAPT
  :keywords: WAPT, Why, How, principles, documentation, history, genesis

.. |host-status-ok| image:: wapt-resources/icon_host-status-ok.png
  :alt: OK host status icon in the WAPT Console

.. |host-status-need-upgrade| image:: wapt-resources/icon_host-status-need-upgrade.png
  :alt: NEED-UPGRADE host status icon in the WAPT Console

.. |host-status-need-remove| image:: wapt-resources/icon_host-status-need-remove.png
  :alt: NEED-REMOVE host status icon in the WAPT Console

.. |host-status-error| image:: wapt-resources/icon_host-status-error.png
  :alt: ERROR host status icon in the WAPT Console

.. |host-status-need-install| image:: wapt-resources/icon_host-status-need-install.png
  :alt: NEED-INSTALL host status icon in the WAPT Console

.. _wapt_general_presentation:

##############################
Fundamental principles of WAPT
##############################

********************
Introduction to WAPT
********************


For what purpose is WAPT useful?
================================

**WAPT** installs, updates and removes software and configurations on Windows, Linux and macOS devices. Software deployment (Firefox, MS Office, etc.) can be carried out from a central server using a graphical console.
WAPT is taking many ideas from Debian Linux apt package management tool, hence its great name.

Private companies of all sizes, Colleges, Schools, Universities, research labs, local and state governments, Hospitals, city governments, state ministries around the world are successfully using **WAPT**.

**WAPT** exists in two versions, **Discovery** and **Enterprise**, both proprietary, the **Community** version having been friendly forked to the Opensource Community.
In this documentation, when you see the image of wapt enterprise like this |enterprise_feature|. This will indicate that a wapt feature is only available in the **enterprise version**.

**WAPT** is very efficient to address **recurrent Firefox or Chrome update needs** and it is often to cover that basic need that WAPT is initially adopted; it then becomes a tool of choice for the sysadmin's daily tasks.

..
  ************************************************************
..
  Security Certification from French Cyberdefense Agency ANSSI
..
  ************************************************************

..
  .. figure:: wapt-resources/icon_visa_anssi_fr.png
  :align: center
  :target: https://www.ssi.gouv.fr/administration/certification_cspn/wapt-entreprise-v-1-5-0-13/
  :alt: Security Visa from ANSSI dated 14th of February 2018 for WAPT Enterprise Edition 1.5.0.13

  Security Visa from ANSSI dated 14th of February 2018 for WAPT Enterprise Edition 1.5.0.13

..
  Following its first level security certification obtained on 14 February 2018, WAPT has obtained on 15 march 2018 a `higher level certification <https://www.tranquil.it/wp-content/uploads/qualification-anssi-tranquil-it.pdf>`_ from ANSSI.


The genesis of WAPT
===================

Our assessment after 15 years of IT management
----------------------------------------------

Managing large IT installed bases of Microsoft Windows computers is today a difficult task in a secured environment:

* Common ghosting methods (*Clonezilla* or *Ghost*) are efficient on homogeneous IT infrastructures with roaming user profiles.

* Deployment tools (*OCSInventory* or *WPKG*) can broadcast software but do not easily allow software level or user level customizations that are useful to prevent or limit user support requests.

* Software from smaller vendors often need :term:`Local Administrator` rights to run properly.

* Currently available solutions to address theses problems are either too expensive or too inefficient, and they are in every case too complex.

WAPT development hypotheses and motivations
-------------------------------------------

The development of WAPT is motivated by these two principles:

* What is **complicated** should be made **simple**.

* What is **simple** should be made **trivial**.

WAPT relies on a small set of fundamental hypotheses:

* Sysadmins should know a scripting language and WAPT has chosen Python for the depth and breadth of its libraries.

* Sysadmins who have little experience with scripting languages **MUST** find inspiration in simple and efficient examples that they will adapt to fit their needs.

* Sysadmins **MUST** be able to communicate on the efficiency of their actions to their superiors and report process gaps to internal or external auditors.

* Sysadmins **MUST** be able to collaborate with their IT team; thereby WAPT local repositories provide signed packages that they can trust to be deployed on their network.
  Alternatively, they can choose external public repositories providing them the security guarantees that they consider sufficient.

* Sysadmins are aware that user workstations serve business purposes and some customizations **MUST** be possible.
  The adaptation of the infrastructure to the business needs is facilitated by the notion of groups and :abbr:`OU (Organizational Units)`; it allows to select a large number of hosts to customize their configuration.

**********************
Fundamental principles
**********************

Repository principle
====================

Packages are stored in a web repository. They are not stored in a database.

.. note::

  Transport protocol used for deploying packages is **HTTPS**.

WAPT packages are served by the :program:`Nginx` web server, available with Linux and Windows.

The :file:`Packages` index file is the only thing necessary.
It lists the packages available on allowed repositories and some basic information on each package.

That mechanism allows to easily set up a replication process between multiple repositories.

.. figure:: wapt-resources/wapt_concept_repository_header_flow-diagram.png
    :align: center
    :alt: Replication and multiple repositories

    Replication and multiple repositories

Large organizations with remote sites and subsidiaries sometimes require services to be replicated locally to avoid bandwidth congestion (*Edge Computing*).


Replicated repository |enterprise_feature|
==========================================

**WAPT Enterprise offers the possibility to upgrade remote WAPT Agents to serve as remote repositories that can be managed directly from the WAPT Console.
All WAPT Agents can then be centrally configured to automatically select the best repository based on a set of rules**.

When WAPT is used on bandwidth limited remote sites, it makes sense to have a local device that will replicate the main WAPT repository to reduce the network bandwidth consumed when deploying updates on remote devices.

With remote repositories, WAPT remains a solution with a low operating cost because high bandwidth **fiber links are not required** to take advantage of WAPT.

.. figure:: wapt-resources/wapt_concept_repository-replication_flow-diagram.png
    :align: center
    :alt: Replicating WAPT repositories

    Replicating WAPT repositories

It works as follows:

  * A small form factor and no maintenance appliance with the role of secondary repository is deployed on the local network of each remote site; a workstation can also be used, although it may not be up and running if you want to connect to it.

  * The remote repository replicates the packages from the main repository.

  * The WAPT clients connect in priority with the repository that is the closest to them, the local repository.

To learn more about the replicated repositories, visit the documentation on the :ref:`replicating a repository <replication_usage>`.

Packages principle
==================

A WAPT package structure is similar to Debian Linux **.deb** packages.
Each WAPT package includes the binaries to be executed and the other files it needs.

A package is easily transportable.

Here is how a WAPT package looks:

.. figure:: wapt-resources/windows_concept_wapt-package-structure_browser-window.png
  :scale: 75%
  :align: center
  :alt: WAPT package structure shown in Windows Explorer

  WAPT package structure shown in Windows Explorer

To learn more about the composition of a WAPT package, visit the documentation on the :ref:`structure of a WAPT package <structure_wapt_package>`.

.. _type_of_packages:

Types of WAPT packages
----------------------

There are 8 types of WAPT packages:

.. figure:: wapt-resources/wapt_concept_simple-package_flow-diagram.png
  :scale: 75%
  :align: center
  :alt: Anatomy of a simple WAPT package

  Anatomy of a simple WAPT package

.. _base_packages:

*base* packages
^^^^^^^^^^^^^^^

They are classic software packages.

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

.. note::
  If a package is installed on a workstation, removing a dependency will not uninstall the package itself.
  
  To uninstall a package from multiple workstations, you must explicitly uninstall it.

.. _group_packages:

*group* packages
^^^^^^^^^^^^^^^^

They are groups of packages.

Each group often correspond to:

* a service in an organization (ex: **accounting**).

* a room, building, etc.

.. hint::

  A host can be a member of several groups.

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

.. note::
  If a package is installed on a workstation, removing a dependency will not uninstall the package itself.
  
  To uninstall a package from multiple workstations, you must explicitly uninstall it.

|

.. _host_packages:

*host* packages
^^^^^^^^^^^^^^^

**Host** packages are named after the :term:`UUID` of the computer BIOS or the :term:`FQDN` of the host.

Each host will look for its **host** package to know the packages that it must install (i.e. *dependencies*).

**Host** packages are stored in the web directory https://srvwapt.mydomain.lan/wapt-host/.

.. note::
  If a package is installed on a workstation, removing a dependency will not uninstall the package itself.
  
  To uninstall a package from multiple workstations, you must explicitly uninstall it.

|

.. _unit_packages:

*unit* packages |enterprise_feature|
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

**Unit** packages bear the complete name of :abbr:`OU (Organizational Unit)`, example: **OU=room1,OU=prod,OU=computers,DC=mydomain,DC=lan**.

By default, each computer looks for the unit packages and then installs the list of associated dependencies.

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

.. note::
  If a package is installed on a workstation, removing a dependency will not uninstall the package itself.
  
  To uninstall a package from multiple workstations, you must explicitly uninstall it.

|

.. _waptwua_packages:

*wsus* packages |enterprise_feature|
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

**Wsus** packages contain the list of authorized or prohibited Windows Updates.

When this package is installed on the endpoints, the next update scan performed by WAPT will choose Windows updates based on this filtering.

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

|

.. _self-service_packages:

*self-service* packages |enterprise_feature|
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

**Self-service** packages contain a list of groups or users (Active Directory or local) and their associated lists of authorized packages that Users are allowed to install by themselves.

**Self-service** packages are stored in the web directory https://srvwapt.mydomain.lan/wapt/.

|

.. _profile_packages:

*profile* packages |enterprise_feature|
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

**Profile** packages are similar to **group** packages.

However, **profile** packages work a little differently and are most useful when an Active Directory Server is operating within the :term:`Organization`:

* The WAPT Agent will list the Active Directory groups to which the host belongs.

* If a *profile* package has the same name as an Active Directory group (case sensitive), then the WAPT agent will install automatically the *profile* package for the Active Directory group of which it is a member.

* If the **host is no longer a member** of its Active Directory group, then the corresponding *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 the WAPT upgrade.

.. note::

 For performance reasons, this feature is enabled only if the :code:`use_ad_groups` option is enabled in the :file:`wapt-get.ini` configuration file.

.. note::
  If a package is installed on a workstation, removing a dependency will not uninstall the package itself.
  
  To uninstall a package from multiple workstations, you must explicitly uninstall it.

|

.. _config_packages:

*config* packages |enterprise_feature|
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

**Config** packages are used for modifying the WAPT Agents configuration parameters.
This way, it is possible to have a generic WAPT Agent and to customize the WAPT Agents configuration using host profiles.
For example, some hosts may need different WAPTWUA rules and some other hosts may need to be set to a DEV maturity, etc.

When a dynamic configuration package is applied, it creates a section called default-"X" (default-global, default-waptwua or default-reposync) in the wapt-get.ini file.
Therefore, to read the content of the parameters currently applied to the agent, you must refer to the default-"X" section and not the X section.
The X section is displayed to consult the initial configuration of our agent.

Additionally, the JSON files of the packages are present in "C:\Program Files (x86)\wapt\conf.d" in the format: configpackagename.json.

.. _dependency_mechanism:

Dependency mechanism
====================

In WAPT everything works on the principle of dependencies.

By default, the WAPT Agent will look for its *host* package.
The *host* package lists WAPT packages to install on the computer.

The *host* package is correctly installed when all its dependencies are satisfied.

Each sub-dependency **MUST** be satisfied to satisfy an upper-level dependency.

When every dependency has been satisfied, the host notifies its status to the WAPT Server.
The host status indicator turns **OK** and green in the WAPT Console, meaning the host has the host profile that the :term:`Administrator` or :term:`Package Deployer` has defined for it.

.. figure:: wapt-resources/wapt_concept_dependencies_flow-diagram.png
  :align: center
  :alt: Conceptual diagram of the dependency mechanism

  Conceptual diagram of the dependency mechanism

.. hint::

  When attributing a software package to a host as a dependency, only the software canonical name without its version number is registered as a dependency (ex: I want :program:`Freemind` to be installed on this host in its latest version and :program:`Freemind` to be configured so that the :term:`User` does not call me because she does not find the icon on her desktop!).

For each dependency, the WAPT Agent will take care of automatically installing the latest available package version.
So if several versions of :program:`Freemind` are available on the repository, the WAPT Agent will always get the latest version, unless I have pinned the version for reason of compatibility with other sets of tools.

Afterwards, when the WAPT Agent contacts the repository to check for new updates, it will compare the package versions on the repository with its own local list of packages already installed on the host.

If an update of an installed package is available, the client will switch the status of the package to **NEED UPGRADE**.
It will then install the software updates during the next :command:`upgrade`.

.. note::
  If a package is installed on a workstation, removing a dependency will not uninstall the package itself.
  
  To uninstall a package from multiple workstations, you must explicitly uninstall it.

Private key / Public certificate principle
==========================================

Like Android **APK** packages, WAPT packages are signed; a hash of the control sum of all the files included in the package is calculated.

This signing method guarantees the origin and integrity of the package.

.. figure:: wapt-resources/wapt_concept_private-public-key_flow-diagram.png
  :align: center
  :alt: Private key / public certificate

  Private key / public certificate

To work properly, WAPT requires a private key / public certificate pair (self-signed, issued by an internal :term:`Certificate Authority` or commercially issued).

The **private key** will be used to **sign** WAPT packages whereas the **public certificate** will be distributed with every WAPT client so that WAPT Agents may validate the files that were signed with the private key.

The different public certificates will be stored in the WAPT subdirectory :file:`ssl`.
That folder can contain several public certificates.

Package verification
--------------------

When a WAPT package is downloaded, the WAPT Agent (:term:`waptagent`) will check the integrity of the package, and then check that the package has been properly **signed**.

If the WAPT package signature does not match any of the public certificates located in :file:`C:\\Program Files (x86)\\wapt\\ssl` on Windows or in :file:`/opt/wapt/ssl` on Linux and macOS, the WAPT Agent will refuse to install the package.

For more information, please refer to the documentation on :ref:`how the integrity of the installation process a WAPT package is insured <encryting_sensitive_data_in_package>`.

The private certificate is important
------------------------------------

.. attention::

  The private key **MUST NOT** be stored on the WAPT Server, nor on any public or shared storage that could be accessed by non-authorized personnel.
  Indeed, WAPT security is based on keeping the private key **private**.

  The private key **MUST** be stored in a safe place, because **she who has your key controls your network**!

  Finally, to ensure maximum security, the private key can be secured in a smartcard or a cryptographic token that WAPT :term:`Administrators` or :term:`Package Deployer` will carry physically on them, using the smartcard or the token only when needed to sign a WAPT package.

The private key is protected with a password by default.

More informations on :ref:`generating the Administrator's certificate for signing WAPT packages <create_certificate>`.

.. _new_crt_with_ca:

Differentiating user roles in WAPT |enterprise_feature|
-------------------------------------------------------

WAPT offers the possibility to differentiate roles based on:

* A :abbr:`PKI (Public Key Infrastructure)`;

* :abbr:`ACLs (Access Control Lists)`.

Public Key Infrastructure
^^^^^^^^^^^^^^^^^^^^^^^^^

.. hint::

  The usage of an existing PKI is possible, the WAPT Console comes with a simple certificate generator.

WAPT works as a :abbr:`CA (Certificate Authority)` mode in regards to PKI.

By design, WAPT is capable of generating certificates that may be used as parent keys to generate other public and private child keys.

Therefore the main WAPT Administrator who acts as a may issue certificates for each IT admin so their actions may be identified when they use WAPT.

Child certificates issued from the CA can themselves be configured as:

  * Code-signing certificate to allow IT admins to package, sign and deploy WAPT packages containing executable loads (i.e. :file:`setup.py`).

  * :abbr:`CA (Certificate Authority)` certificate to delegate to other IT admins the right to issue certificates.

  * Simple SSL certficate to limit IT admins to only deploying packages containing non executable loads (i.e. configure hosts).

.. figure:: wapt-resources/wapt_concept_role-separation_flow-diagram.png
  :align: center
  :alt: WAPT user role differentiation

  WAPT user role differentiation

To learn more on generating the Certificate Authority (CA) with WAPT, visit :ref:`this documentation <generating_CA>`.

Access Control Lists
^^^^^^^^^^^^^^^^^^^^

With WAPT, it is possible to define user access rights using :abbr:`ACL (Access Control Lists)`.

Each IT technician is identified with his own certificate and rights can therefore be be finely applied on an individual basis.

For exemple, a WAPT Console user may have a ``View`` right on a host but may not be allowed to click on :guilabel:`Edit hosts`.

.. figure:: wapt-resources/wapt_concept-acl_flow-diagram.png
  :align: center
  :alt: ACL roles differentiation

  ACL roles differentiation

To learn more on ACLS in WAPT, visit :ref:`this documentation <ACL>`.

**********************
WAPT mode of operation
**********************

Inventory
=========

WAPT keeps a hardware and software inventory of each host.

That inventory is stored in a small database integrated in each WAPT Agent.

.. figure:: wapt-resources/wapt_concept-host-inventory_flow-diagram.png
  :align: center
  :alt: Inventory feedback mechanism in WAPT

  Inventory feedback mechanism in WAPT

* When first registering with the WAPT Server, the WAPT Agent sends its entire inventory (BIOS, hardware, software) to the WAPT Server.

* When the WAPT Agent updates, the WAPT Agent will report its new inventory status to the WAPT Server.

.. figure:: wapt-resources/wapt_console_hardware-inventory_browser-window.png
  :scale: 75%
  :align: center
  :alt: The inventory in the WAPT Console

  The inventory in the WAPT Console

The central inventory allows you to filter hosts by their components, software or any other searchable argument.

Information feedback
====================

The WAPT Agents also report back their WAPT package status.

.. figure:: wapt-resources/wapt_concept_package-status-update_flow-diagram.png
  :align: center
  :alt: Flow diagram of the inventory feedback returned to the WAPT Server

  Flow diagram of the inventory feedback returned to the WAPT Server

In case of errors during package installation, the information will be reported to the WAPT Server.
The host will then appear in **ERROR** in the WAPT Console.

.. image:: wapt-resources/wapt_console_package-status-error_screen-item.png
  :align: center
  :alt: Packages with ERROR status in the WAPT Console

.. _host_package_status:

The possibles status of a host in the WAPT Console are:

.. list-table:: Available host status in the WAPT Console
  :header-rows: 1
  :widths: auto

  * - Status
    - Status Icon
  * - *OK*
    - |host-status-ok|
  * - *NEED-UPGRADE*
    - |host-status-need-upgrade|
  * - *NEED-REMOVE*
    - |host-status-need-remove|
  * - *ERROR*
    - |host-status-error|
  * - *NEED-INSTALL*
    - |host-status-need-install|

The :term:`Administrator` can see the packages returned in error in the WAPT Console and fix the package accordingly.

For each upgrade, WAPT will try to install a new version of the package until no error status is returned.

.. note::

  WAPT Agents sign their inventory before sending it to the WAPT Server.

  For more information, please refer to :ref:`signing inventory updates <signing_inventory_updates>`.

WAPT common interactions
========================

update
------

When an *update* command is launched on a WAPT Agent, it is equivalent to ordering the Agent to check the WAPT repository for new packages.
**By default, the WAPT Agent will look for updates every two hours**.

If the date of the :file:`Packages` index file has changed since the last *update*, then the WAPT Agent downloads the new :file:`Packages` file (between 20 and 100k), otherwise, it does nothing.

The WAPT Agent then compares the :file:`Packages` file with its own local database.

If the WAPT Agent detects that a package **MUST** be added or updated, it will switch the status of the host and the status of the package to *NEED-UPGRADE*.

It will not launch the installation of the package immediately.
The WAPT Agent will wait for an *upgrade* order to launch the upgrade.

upgrade
-------

When we launch an *upgrade*, we ask the WAPT Agent to install the packages having a *NEED-UPGRADE* status.

An :command:`wapt-get update` **MUST** come before a :command:`wapt-get upgrade`, otherwise the Agent will not know whether updates are available.

By default, the WAPT Agent will trigger an :command:`wapt-get update`/ :command:`wapt-get download-upgrade` at startup; after starting up, **the WAPT Agent will then check every 2 hours to see whether it has something to do**.

Packages to be installed will be downloaded and cached in the folder :file:`C:\\Program Files (x86)\\wapt\\cache`.

:term:`waptexit` will launch a :command:`wapt-get upgrade` when the computer shuts down.
An :term:`Administrator` can force the immediate launch of an :command:`upgrade` from the WAPT Console.
Alternatively, an end-user may choose to manually launch an *upgrade*.
Lastly, a scheduled task may be set up on hosts to launch an *upgrade*.

If the WAPT Server is not reachable when upgrading, the WAPT Agent will still be able to install cached packages.
Inventory updates are sent to the WAPT Server when network connectivity returns.

The 5 goals of the WAPT Agent are therefore:

* To install a **base**, a **group** or a **unit** package if it is available.

* To remove obsolete packages.

* To resolve package dependencies and conflicts.

* To make sure all installed WAPT packages are up to date compared to the ones stored on the repository.

* To regularly update the WAPT Server with its hardware status and the status of installed software.

WAPT Agent behavior
===================

A key concept that can be hard to understand is the behavior of a WAPT Agent when installing a package and the considerations around it.

WAPT Agent package installation can be split in simple steps:

* On triggerring a :command:`wapt-get update`, the WAPT Agent downloads *NEED-UPGRADE* or *NEED-INSTALL* packages and stores them in the cache folder.

* On triggerring a :command:`wapt-get upgrade`, the WAPT Agent unzips the packages into a temporary folder.

* The :file:`setup.py` content is parsed and stored in the WAPT Agent database located in :file:`C:\\Program Files (x86)\\wapt\\db\\waptpublicdb.sqlite`.

* The file :file:`setup.py` is executed and the software is installed from unzipped files.

* In case of success: the downloaded packages and unzipped files are deleted.
  An **OK** status is returned to the WAPT Server.

* In case of failure: the downloaded packages are kept and the unzipped files are deleted.
  An **ERROR** status is returned to the WAPT Server.

That behavior is important for understanding the lifecycle of an installed package.

.. figure:: wapt-resources/wapt_concept_installing-packages_flow-diagram.png
  :align: center
  :alt: Flow diagram showing the installation process for a WAPT package

  Flow diagram showing the installation process for a WAPT package

For instance when removing a package, the following steps are taken:

* The :file:`setup.py` content is retrieved from WAPT Agent :program:`sqlite` database located in :file:`C:\\Program Files (x86)\\wapt\\db\\waptpublicdb.sqlite`.

* The WAPT Agent looks up the :code:`UninstallString` in the local database.

* If defined in the :file:`setup.py` copied into the local database during initial installation of the WAPT package, the :command:`uninstall()` function is executed.

Similar steps are activated when executing :command:`session_setup` and :command:`audit`.

.. figure:: wapt-resources/wapt_concept_installing-packages-other-behavior_flow-diagram.png
  :align: center
  :alt: Flow diagram showing the behavior of WAPT regarding uninstall / session_setup and audit

  Flow diagram showing the behavior of WAPT regarding uninstall / session_setup and audit

Complete diagram of the WAPT operating mechanism
================================================

.. figure:: wapt-resources/wapt_concept_general_flow-diagram.png
  :align: center
  :alt: Flow diagram showing the general operating mode with WAPT

  Flow diagram showing the general operating mode with WAPT


We find here the common WAPT behavior, from duplicating a package from an external repository accessible on the Internet, to deploying it on network hosts.

Reading the diagram clockwise, a WAPT Administrator will:

* Import packages from an external repository (or create a new package from scratch).

* Test, validate, build and then sign the package.

* Upload the package onto the main repository.

* Packages are automatically downloaded by WAPT clients.

* Packages are executed based on the selected method:

  - The :term:`Administrator` forces the :command:`upgrade`.

  - The :term:`Administrator` proposes the :command:`upgrade` at :term:`User`.

  - A scheduled task launches the upgrade.

  - The *upgrade* is executed when the host shuts down.

  - The :term:`User` chooses the right time for herself (at shutdown or using the :ref:`self-service <wapt-self-service>`).

* Inventory information is fed back to the WAPT Server.

* The updated inventory is reported in the WAPT Console.

**********************************
Database architecture on the agent
**********************************

Since WAPT version 2.6, the database architecture has been redesigned for enhanced security and efficiency. The agent now uses two SQLite databases: :file:`waptpublicdb.sqlite` (public) and :file:`waptdb.sqlite` (private).

The public database, located in :file:`C:\\Program Files (x86)\\wapt\\db\waptpublicdb.sqlite`, stores scripts like :file:`setup.py` and :file:`session-setup.py`, as well as the list of installed packages. It is used for session operations (example ; wapt-get session-setup) without exposing sensitive data.

The private database, located in :file:`C:\\Program Files (x86)\\wapt\\private\\db\\waptdb.sqlite`, contains everything else: package audits, hardware inventory (WMI/DMI), logs and detailed installation history. 

This separation minimizes the risk of tampering with critical data and improves performance.


************************
WAPT Server architecture
************************

The WAPT Server architecture relies on several distinct roles:

* The *repository role* for distributing packages.

* The *inventory* and *central server* role for hardware and software inventory.

* The *proxy* role to relay actions between the WAPT Console and the WAPT Agents.

Repository role
===============

First, the WAPT Server serves as a web repository.

.. figure:: wapt-resources/wapt_concept_repository_flow-diagram.png
  :align: center
  :alt: Flow diagram of the WAPT repository mechanism

  Flow diagram of the WAPT repository mechanism

* The repository role is accomplished by a :program:`Nginx` web server.

* The repository allows the distribution of WAPT packages, the installers for :term:`waptagent` and :term:`waptsetup`.

* WAPT packages are available via a web browser by visiting https://srvwapt.mydomain.lan/wapt.

* The *host* packages are stored in a directory that is not accessible by default (https://srvwapt.mydomain.lan/wapt/wapt-host/).

Inventory server role
=====================

Second, the WAPT Server serves as an inventory server.

The inventory server is a passive service that collects information reported by WAPT Agents:

* Hardware inventory.

* Software inventory.

* WAPT packages status.

* Tasks status (*running*, *pending*, *error*).

.. note::

  The WAPT service is not active in the sense that it only receives information from clients. As a consequence, if the WAPT inventory Server fails, the inventory will recover by itself from inventory status reports received from the deployed WAPT Agents.

  In the **Discovery** version of WAPT, access to inventory data is only possible through the WAPT Console.

  WAPT **Enterprise** comes with :ref:`reporting <wapt_reporting>` capabilities.
  In parallel, it is possible to push WAPT inventory to :ref:`GLPI <wapt_glpi>` ITSM tool.

Proxy role
==========

Third, the WAPT Server serves as a command relay proxy.

It acts as a relay between the WAPT management Console and deployed WAPT Agents.

.. figure:: wapt-resources/wapt_concept_proxy-server_flow-diagram.png
  :align: center
  :alt: Flow diagram of the WAPT proxy mechanism

  Flow diagram of the WAPT proxy mechanism

.. note::

  Every action triggered on a WAPT Agent from the WAPT Server are signed with a private key.

  **Without a valid private key, it is not possible to trigger remote actions on remote WAPT equipped devices**.

  For more information on remote actions, please refer to the documenation on :ref:`signing actions relayed to the WAPT Agents <signing_actions_relayed_to_WAPT_agents>`.

*****************************************
WAPT language and development environment
*****************************************

WAPT is built using the `Python language <https://www.python.org>`_.

Any :abbr:`RAD (Rapid Application Development)` environment intended for Python development is suitable.

Tranquil IT has developed some useful WAPT specific plugins for the :program:`PyScripter` `IDE <https://sourceforge.net/projects/pyscripter>`_.

Tranquil IT recommends using :program:`PyScripter` for developing WAPT packages for Windows and :program:`vscode` for developing WAPT packages for macOS and Linux.

The strength of Python
======================

All the power of :program:`Python` can be advantageously put to use.

Many libraries already exist in Python for:

* Doing conditional loops (if ... then ... else ...).

* Copying, pasting, moving files and directories.

* Checking whether files or directories exist.

* Checking whether registry keys exist.

* Checking access rights, modifying access rights.

* Looking up information on external data sources (LDAP, databases, files, etc).

* And more.

The power of WAPT
=================

Functions most commonly used with WAPT have been simplified and integrated within libraries called :term:`Setuphelpers`.

**SetupHelpers** libraries simplify the process of creating and testing WAPT packages, thus validating WAPT's main objectives:

**That which was complicated is made simple**.
