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

.. |ok| image:: wapt-resources/icon-ok.png
  :scale: 5%
  :alt: Feature available

.. |nok| image:: wapt-resources/icon-nok.png
  :scale: 5%
  :alt: Feature not available

.. |date| date::

.. meta::
  :description: Deploying the WAPT Agent
  :keywords: waptconsole, waptagent, wapt_deploy, WAPT, preferences, documentation, WAPT Console, Windows, Linux, macOS


.. _how_to_use_wapt:

This section of the documentation covers the daily use of WAPT.

All WAPT functionalities are explained in detail for the :term:`Administrators`, the :term:`Users` and the :term:`Package Deployers`. 

.. _deploying_waptagent:

########################
Deploying the WAPT Agent
########################


***********************************
Deploying the WAPT Agent on Windows
***********************************

.. note::

  To install WAPT on a Windows client, the minimal requirements are:

  * 512Mo Ram;
  * 1 CPU;
  * 300Mo Drive space (without package cache).

.. list-table:: List of Windows versions available.
  :header-rows: 1
  :widths: auto

  * - Windows Version
    - WAPT Support
  * - Windows 11 ARM
    - Tech Preview
  * - Win2h25
    - |ok|
  * - Windows 11 Professional/Enterprise
    - |ok|
  * - Win2k22
    - |ok|
  * - Win2k19
    - |ok| 
  * - Win2k16
    - |ok|  
  * - Windows 10 32/64bit Intel
    - |ok|   
  * - Win2012r2
    - |ok|
  * - Windows 7 32/64bit
    - |ok| 

.. note::

  **Win11 ARM** is currently in Tech Preview. Not all WAPT functionalities are available, such as Windows Update Agent (WUA). Some duplicates in software or hardware inventory have been observed.

.. attention::

  If you install the WAPT Agent on **Windows Server 2012r2**, it needs these features need to be activated before installing the WAPT Agent:

  * :download:`KB2919442 <https://www.microsoft.com/en-us/download/details.aspx?id=42334>`.

  * :download:`KB2919355 <https://www.microsoft.com/en-us/download/details.aspx?id=42334>`.

  * :download:`vcredist2015 <https://www.microsoft.com/en-us/download/details.aspx?id=48145>`

|

Two methods are available to deploy the :program:`waptagent.exe`.

* The first method is manual and the procedure **MUST** be applied on each host.

* The second one is automated and relies on a :abbr:`GPO (Group Policy Objects)`.

The :program:`waptagent.exe` installer is available at WAPT serveur web home page.
The direct download link is for example: https://srvwapt.mydomain.lan/wapt/waptagent.exe.


.. _install_agent:

Manually
========

Manually installing the WAPT Agent requires :term:`Local Administrator` rights on the computer. 

Manual deployment method is efficient in these cases:

  * Testing WAPT.

  * Using WAPT in an organization with a small number of computers.

  * If you do not have a means of mass deployment.

* Download the WAPT Agent from your WAPT Server then launch the installer from URL https://srvwapt.mydomain.lan/wapt/waptagent.exe.

.. note::

  Since WAPT 2.5, a basic authentification if required to access to your WaptServer website.

  .. figure:: wapt-resources/waptserver_authentication_window.png
   :scale: 75%
   :align: center
   :alt: The WAPT server authentication window

   The WAPT server authentication window



.. figure:: wapt-resources/wapt_server_web-interface_browser-window.png
  :scale: 75%
  :align: center
  :alt: The WAPT Server interface in a web browser

  The WAPT Server interface in a web browser

Manually installing the WAPT Agent requires :term:`Local Administrator` rights on the computer.

* Download the WAPT Agent from your WAPT Server then launch the installer.
  The :program:`waptagent.exe` installer is available at WAPT serveur web home page.
  The direct download link is for example: https://srvwapt.mydomain.lan/wapt/waptagent.exe.

* Choose the language for the WAPT installer and click on :guilabel:`OK` to go on to the next step.

* Accept the licence terms and click on :guilabel:`Next` to go to next step.

* Just click on :guilabel:`Next` until the :guilabel:`Install` button.

.. image:: wapt-resources/quickstart-install-waptagent.gif
  :align: center
  :alt: Installation Wizard has finished

Automatically
=============

.. 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 :term:`Organization`.

With the WAPT Deployment utility
--------------------------------

:program:`waptagent.exe` is an `InnoSetup <https://jrsoftware.org/isinfo.php>`_ installer, it can be executed with these silent argument:

.. code-block:: bash

  waptagent.exe /VERYSILENT

* Additional arguments are available for the WAPT Deployment utility.

.. list-table:: Description of available options for deploying the WAPT Agent silently
  :header-rows: 1
  :widths: auto

  * - Options
    - Description
  * - :code:`/dnsdomain` = ``mydomain.lan``
    - Domain in :file:`wapt-get.ini` filled in during installation.
  * - :code:`/wapt_server` = ``https://srvwapt.mydomain.lan``
    - URL of the WAPT Server in :file:`wapt-get.ini` filled in during installation.
  * - :code:`/repo_url` = ``https://repo1.mydomain.lan/wapt``
    - URL of the WAPT repository in :file:`wapt-get.ini` filled in during installation.
  * - :code:`/StartPackages` = ``basic-group``
    - Group of WAPT packages to install by default.
  * - :code:``/verify_cert = ``True`` or relative path :file:`ssl\\server\\srvwapt.mydomain.lan.crt`.
    - Value of :code:`verify_cert` entered during installation.
  * - :code:`/CopyServersTrustedCA` = path to a bundle to copy to :file:`ssl\\server`
    - Certificate bundle for https connections (to be defined by :code:`verify_cert`).
  * - :code:`/CopypackagesTrustedCA` = path to a certificate bundle to copy into :file:`ssl`
    - Certificate bundle for verifying package signatures.


The WAPT Deployment utility is a small binary that:

* Checks the version of the WAPT Agent.

* Downloads via https the :program:`waptagent.exe` installer.

* Launches the silent installer with arguments (checked options defined during the compilation of the WAPT Agent).

.. code-block:: bash

  /VERYSILENT /MERGETASKS= ""useWaptServer""

* Updates the WAPT Server with the WAPT Agent status (WAPT version, package status).

.. warning::

  The WAPT Deployment utility **MUST** be started as :term:`Local Administrator`, that is why a :abbr:`GPO (Group Policy Object)` is a good method to deploy the WAPT Agent.

Download :file:`waptdeploy.exe` from your WAPT Server homepage, or on https://srvwapt.domain.lan/wapt/waptagent/waptdeploy.exe.

.. figure:: wapt-resources/wapt_server_web-interface_browser-window.png
  :scale: 75%
  :align: center
  :alt: The WAPT Server interface in a web browser

  The WAPT Server interface in a web browser

.. _deploy-wapt-with-scheduled-task:

GPO with a Scheduled Task
-------------------------

You may also choose to launch the WAPT Deployment utility 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 locally :file:`waptdeploy.exe` and :file:`waptagent.exe` and create a scheduled task for installing.

* Copy :file:`waptdeploy.exe` and :file:`waptagent.exe` in the netlogon share of your Active Directory Server (:file:`\\mydomain.lan\\netlogon\\waptagent.exe`).

* Create a new group strategy on the Active Directory server (Microsoft Active Directory or Samba-AD).

* Add a new strategy with :menuselection:`Computer configuration --> Preferences --> Windows Settings --> Files`.

* Create a new file and copy the WAPT Deployment utility.

.. image:: wapt-resources/windows_rsat_gpo-new-file-copy_screen-item.png
  :align: center
  :alt: Selecting a new file to include in the GPO

* Set parameters.

.. list-table:: Description of options for copy
  :header-rows: 1
  :widths: auto

  * - Options
    - Value
  * - :guilabel:`Action` dropdown menu list
    - Replace
  * - :guilabel:`Source file(s)` field
    - :file:`\\\\\\mydomain.lan\\netlogon\\waptdeploy.exe`
  * - :guilabel:`Destination File` field
    - :file:`C:\\windows\\systemtemp\\waptdeploy.exe`
  * - :guilabel:`Suppress errors on individual file actions` checkbox
    - not checked
  * - :guilabel:`Read-only` checkbox
    - checked
  * - :guilabel:`Hidden` checkbox
    - not checked
  * - :guilabel:`Archive` checkbox
    - checked

.. note::

  The **C:\\Windows\\SystemTemp** directory has been available since Windows 10, version 20H2.

  If your system is running an earlier version of Windows, you can use the following directories as alternative destinations for temporary files:

  *  C:\\Windows\\Temp (less secure)

  * C:\\Temp (less secure)

.. figure:: wapt-resources/windows_rsat_gpo-waptdeploy-replace_dialog-box.png
  :align: center
  :scale: 50%
  :alt: WAPT Agent installation progress

  WAPT Agent installation progress

* Create a new file and copy the the :program:`waptagent.exe` file. 

.. image:: wapt-resources/windows_rsat_gpo-new-file-copy_screen-item.png
  :align: center
  :alt: Selecting a new file to include in the GPO

* Set parameters.

.. list-table:: Description of options for update
  :header-rows: 1
  :widths: auto

  * - Options
    - Value
  * - :guilabel:`Action` dropdown menu list
    - Update
  * - :guilabel:`Source file(s)` field
    - :file:`\\\\\\mydomain.lan\\netlogon\\waptagent.exe`
  * - :guilabel:`Destination File` field
    - :file:`C:\\windows\\systemtemp\\waptagent.exe`
  * - :guilabel:`Suppress errors on individual file actions` checkbox
    - not checked
  * - :guilabel:`Read-only` checkbox
    - checked
  * - :guilabel:`Hidden` checkbox
    - not checked
  * - :guilabel:`Archive` checkbox
    - checked

.. note::

  The **C:\\Windows\\SystemTemp** directory has been available since Windows 10, version 20H2.

  If your system is running an earlier version of Windows, you can use the following directories as alternative destinations for temporary files:

  *  C:\\Windows\\Temp (less secure)

  * C:\\Temp (less secure)

.. figure:: wapt-resources/windows_rsat_gpo-filecopy-agent_dialog-box.png
  :align: center
  :scale: 50%
  :alt: Preparing the WAPT update GPO

  Preparing the WAPT update GPO

* Then go to the Scheduled Task menu with :menuselection:`Computer configuration --> Preferences --> Control Panel Settings --> Scheduled Tasks`.

* Create a new Scheduled Task with :menuselection:`Right-click --> New --> Scheduled Task (At least Windows 7)`.

.. figure:: wapt-resources/windows_rsat_gpo-task-create_menu-item.png
  :scale: 75%
  :align: center
  :alt: Create the scheduled task for the WAPT Deployment utility Properties window in RSAT

  Create the scheduled task for the WAPT Deployment utility Properties window in RSAT

.. figure:: wapt-resources/windows_rsat_gpo-task-general_dialog-box.png
  :scale: 75%
  :align: center
  :alt: General tab in the Properties window in RSAT

  General tab in the Properties window in RSAT

* Set :guilabel:`Action` to ``Replace``.

* For :guilabel:`When running the task, use the following user account` paste *S-1-5-18* `(system account).
  You can visit <https://docs.microsoft.com/en-us/windows/security/identity-protection/access-control/security-identifiers>`_ for more information.

* Check :guilabel:`Run whether user is logged on or not`.

* Check :guilabel:`Run with highest privileges`, then go on to the :guilabel:`Triggers` tab.

.. figure:: wapt-resources/windows_rsat_gpo-task-trigger_dialog-box.png
  :scale: 75%
  :align: center
  :alt: Trigger tab in the Properties window in RSAT

  Trigger tab in the Properties window in RSAT

* Create a new trigger.

* Check :guilabel:`Daily`, select :guilabel:`today's date`.

* Check :guilabel:`Repeat Task every` and select :guilabel:`1 hour` and :guilabel:`for a duration of` select :guilabel:`1 day`.

* Check :guilabel:`Stop task if it runs longer than` and select :guilabel:`2 hours`.

* Check that :guilabel:`Enabled` is checked, and then go to the :guilabel:`Actions` tab.

.. figure:: wapt-resources/windows_rsat_gpo-task-actions_dialog-box.png
  :scale: 75%
  :align: center
  :alt: Actions tab in the Properties window in RSAT

  Actions tab in the Properties window in RSAT

* Create a new action :guilabel:`Start a program` for :file:`waptdeploy.exe`.

.. list-table:: Description of options to copy
  :header-rows: 1
  :widths: auto

  * - Options
    - Value
  * - :guilabel:`Action`
    - Start a program
  * - :guilabel:`Program / script`
    - C:\\Temp\\waptagent.exe
  * - :guilabel:`Add arguments (optional)`
    - See the next point
  * - :guilabel:`Start in (optional)`
    - empty


.. figure:: wapt-resources/windows_rsat_gpo-task-actions_dialog-box.gif
  :scale: 75%
  :align: center
  :alt: Actions tab in the Properties window in RSAT

  Actions tab in the Properties window in RSAT


.. hint::

  It is necessary to provide the checksum of the :file:`waptagent.exe` as argument to the WAPT Deployment utility.
  This will prevent the remote host from executing an erroneous / corrupted :program:`waptagent` binary.

  .. code-block:: bash

    --hash=checksum WaptAgent --minversion=|wapt_last_release| --wait=15 --waptsetupurl=http://srvwapt.mydomain.lan/wapt/waptagent.exe

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

  .. figure:: wapt-resources/wapt_deploy_gpo-copy-parameter_browser-window.png
    :scale: 50%
    :align: center
    :alt: Web console of the WAPT Server

    Web console of the WAPT Server

* Copy the required parameters and change ``waptsetupurl`` to :file:`C:\\Temp\\waptagent.exe`.

  .. code-block:: bash

    --hash=checksum WaptAgent --minversion=|wapt_last_release| --wait=15 --waptsetupurl=C:\Temp\waptagent.exe

.. list-table:: Description of available options for the WAPT Deployment utility
  :header-rows: 1
  :widths: auto

  * - Options
    - Description
  * - ``--force``
    - Installs waptagent.exe even if not needed
  * - ``--hash`` = <sha256hash>
    - Checks that the downloaded waptagent.exe setup sha256 hash matches the hash.
  * - ``--help``
    - Displays the options.
  * - ``--minversion`` = 2.6.0
    - Installs waptagent.exe if installed version is less than minversion.
  * - ``--tasks`` = autorunTray,installService,installredist2008,autoUpgradePolicy
    - If given, passes this arguments to the /TASKS options of the waptagent installer.
      Default = installService, installredist2008, autoUpgradePolicy
  * - ``--repo_url`` = https://srvwapt.mydomain.lan/wapt
    - Defines the location of the repository to get the :file:`waptagent.exe`.
  * - ``--setupargs`` = <options>
    - Adds arguments to the command line of waptagent.exe.
  * - ``--wait`` = <minutes>
    - Defines the maximum allowed time for running and pending tasks to complete if the WAPT service is running before installing.
  * - ``--waptsetupurl`` = https://srvwapt.mydomain.lan/wapt/waptagent.exe
    - Defines an explicit location to download setup executable.
      This can be a local path (default=:file:`<repo_url>/waptagent.exe`).

* Go on to the :guilabel:`Settings` tab.

  .. figure:: wapt-resources/windows_rsat_gpo-task-settings_dialog-box.png
    :scale: 75%
    :align: center
    :alt: Settings tab in the Properties window in RSAT

    Settings tab in the Properties window in RSAT

* In the :guilabel:`Settings` tab, only check :guilabel:`Run task as soon as possible after a scheduled start is missed`.

.. hint::

  To verify that the :abbr:`GPO (Group Policy Object)` is working, you can run the :command:`gpupdate /force` command and verify that the scheduled task is present on the computer by launching :program:`Task Scheduler` as a Local Administrator.

.. _deploy_waptagent_with_GPO:

GPO with a Startup Script
-------------------------

.. warning::

  This **process does not work** reliably for machines using a **Wi-Fi connection, 802.1X authentication, or a VPN**, for example.
  
  The reason is that the GPO relies on a startup script, but at boot time the machine does not yet have network connectivity. As a result, some **GPOs cannot be applied**.


* Create a new group strategy or add to the group policy with a scheduled task, on the Active Directory server (Microsoft Active Directory or Samba-AD).

* Add a new strategy with :menuselection:`Computer configuration --> Policies --> Windows Settings --> Scripts --> Startup --> Properties --> Add`.

.. figure:: wapt-resources/wapt_deploy_adding-waptdeploy-gpo_container-window.gif
  :scale: 75%
  :align: center
  :alt: Creating a group strategy to deploy the WAPT Agent

  Creating a group strategy to deploy the WAPT Agent

* Click on :guilabel:`Browse` to select the :file:`waptdeploy.exe`.

.. figure:: wapt-resources/wapt_deploy_gpo-browse_container-window.gif
  :scale: 75%
  :align: center
  :alt: Finding the WAPT Deployment utility file on your computer

  Finding the WAPT Deployment utility file on your computer

* Copy :file:`waptdeploy.exe` in the destination folder.

.. figure:: wapt-resources/wapt_deploy_gpo-copy-waptdeploy_browser-window.gif
  :scale: 60%
  :align: center
  :alt: Selecting the the WAPT Deployment utility script

  Selecting the the WAPT Deployment utility script

* Click on :guilabel:`Open` to import the :file:`waptdeploy.exe`.

.. figure:: wapt-resources/wapt_deploy_gpo-select-file_browser-window.gif
  :scale: 75%
  :align: center
  :alt: Selecting the the WAPT Deployment utility script

  Selecting the the WAPT Deployment utility script

* Click on :guilabel:`Open` to confirm the importation of the the WAPT Deployment utility binary.

.. hint::

  It is necessary to provide the checksum of the :file:`waptagent.exe` as an argument to the the WAPT Deployment utility GPO.
  This will prevent the remote host from executing an erroneous / corrupted :program:`waptagent` binary.

  .. code-block:: bash

   --hash=checksum WaptAgent --minversion=|wapt_last_release| --wait=15 --waptsetupurl=http://srvwapt.mydomain.lan/api/v3/get_waptagent_exe/{{ip}}/waptagent.exe

 Parameters and :program:`waptagent.exe` checksum to use for the the WAPT Deployment utility GPO are available on the WAPT Server by visiting https://srvwapt.mydomain.lan.
 When :program:`waptdeploy.exe` queries the WAPT Server to obtain the WAPT Agent URL, the download repository is chosen according to the rules defined for remote repositories.
 The benefit of this method is that you only need one GPO to deploy WAPT onto your entire fleet of computers!

  .. figure:: wapt-resources/wapt_deploy_gpo-copy-parameter_browser-window.png
   :scale: 50%
   :align: center
   :alt: Web console of the WAPT Server

   Web console of the WAPT Server

   .. warning:: 

    This **method does not work in CSPN mode**, as the homepage is intentionally disabled by design.

    It is technically possible to re-enable the homepage using the homepage_enable parameter; however, **this is not recommended**.

    Alternatively, when the agent is generated, it is automatically stored on the administrator's workstation that performed the generation. The SHA-256 hash can then be computed locally using any standard tool available on the system (such as 7-Zip, or equivalent utilities).

* Copy the required parameters into the GPO.

.. figure:: wapt-resources/windows_rsat_gpo-add-extra-parameter_dialog-box.png
  :align: center
  :alt: Adding the the WAPT Deployment utility script to the startup GPO

  Adding the the WAPT Deployment utility script to the startup GPO

* Click on :guilabel:`OK` to go on to the next step.

.. figure:: wapt-resources/windows_rsat_gpo-ready_dialog-box.png
  :align: center
  :alt: The WAPT Deployment utility GPO to be deployed on next startup

  The WAPT Deployment utility GPO to be deployed on next startup

* Click on :guilabel:`OK` to go on to the next step.

* Apply resulting GPO strategy to the Organization's Computers :abbr:`OU (Organizational Units)`.

.. note::

  We recommend adding :file:`waptdeploy.exe` to the startup and shutdown scripts on the GPO.

.. hint::

  More arguments are available for the WAPT Deployment utility

.. list-table:: Description of available options for the WAPT Deployment utility
  :header-rows: 1
  :widths: auto

  * - Options
    - Description
  * - :code:`--force`
    - Forces the installation of :program:`waptagent.exe` even if alread installed.
  * - :code:`--hash` = ``<sha256hash>``
    - Check that the downloaded :program:`waptagent.exe` setup sha256 hash matches the hash.
  * - :code:`--help`
    - Displays the options
  * - :code:`--minversion` = ``<version>``
    - Install :program:`waptagent.exe` if installed version is less than minversion.
  * - :code:`--tasks` = autorunTray,installService,installredist2008,autoUpgradePolicy
    - If given, it passes the arguments to the /TASKS options of the :program:`waptagent` installer (default ``installService, installredist2008, autoUpgradePolicy``).
  * - :code:`--repo_url` = ``<repo_url>``
    - Location of the repository to get :program:`waptagent.exe` (default <repo_url>/wapt)
  * - :code:`--setupargs` = ``<setupargs>``
    - Adds arguments to the command line of :program:`waptagent.exe`. For logs --setupargs="C:/windows/systemtemp/myfile.log"
  * - :code:`--wait` = ``<minutes>``
    - Defines the delay for running and pending tasks to complete if :program:`waptservice` is running before installing.
  * - :code:`--waptsetupurl` = ``<waptsetupurl>``
    - Explicit location to download setup executable.
      It can be a local path (default :file:`<repo_url>/waptagent.exe`).


*******************************************
Deploying the WAPT Agent on Linux and macOS
*******************************************

.. note::

  To install WAPT on a Linux or MacOS client, the minimal requirements are:

  * 512Mo Ram;
  * 1 CPU;
  * 300Mo Drive space (without package cache).

.. _install_waptagent_linux:
.. _install_on_debian:
.. _install_on_ubuntu:
.. _install_on_redhat-based:

The procedure depends on your operating system:

.. tabs::

  .. comments TAB DEBIAN XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX

  .. tab:: Debian and derivatives

    .. hint::

      The WAPT Agent for Debian has been tested on Debian 9, 10, 11 and 12.

      The WAPT Agent for Ubuntu has only been tested on Ubuntu Bionic and Ubuntu Focal.

    * Update the underlying distribution and check that apt https transport is installed

    .. code-block:: bash

      sudo apt update && sudo apt upgrade -y
      sudo apt install apt-transport-https lsb-release gnupg -y

    * Retrieve the key :mimetype:`.gpg`, add it to the Tranquil IT repository and install the WAPT Agent.

    .. code-block:: bash

      bash -c 'wget -qO- https://wapt.tranquil.it/$(lsb_release -is)/tiswapt-pub-2026.gpg > /usr/share/keyrings/tiswapt-pub.gpg'
      echo "deb [signed-by=/usr/share/keyrings/tiswapt-pub.gpg] https://wapt.tranquil.it/$(lsb_release -is)/wapt-2.6/ $(lsb_release -cs) main" | sudo tee /etc/apt/sources.list.d/wapt.list > /dev/null

    .. warning::

      **breaking change:** For WAPT versions earlier than 2.6.1.17654, please use this :mimetype:`gpg` key.

      .. code-block::
        
        wget -qO- https://wapt.tranquil.it/$(lsb_release -is)/tiswapt-pub.gpg > /usr/share/keyrings/tiswapt-pub.gpg


    .. code-block:: bash
      
      export DEBIAN_FRONTEND=noninteractive
      sudo apt update
      sudo apt install tis-waptagent -y
      unset DEBIAN_FRONTEND

  .. comments TAB REDHAT XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX

  .. tab:: RedHat based distributions

    .. hint::

      The WAPT Agent for RedHat based system has been tested on RedHat 7/8/9 and derivatives on x86_64 platforms.

    * Update the underlying distribution.

    .. code-block:: bash

      yum update

    * Retrieve the key :file:`.gpg` and configure the WAPT repository.

    .. code-block:: bash
      :substitutions:

      RH_VERSION=$(cat /etc/system-release-cpe | awk -F: '{ print $5}')
      wget -q -O /tmp/tranquil_it.gpg "https://wapt.tranquil.it/redhat${RH_VERSION}/RPM-GPG-KEY-TISWAPT-${RH_VERSION}"; rpm --import /tmp/tranquil_it.gpg

      cat > /etc/yum.repos.d/wapt.repo <<EOF
      [wapt]
      name = WAPT Server Repo
      baseurl = https://wapt.tranquil.it/redhat${RH_VERSION}/wapt-|wapt_short_version|/
      enabled = True
      gpgcheck = True
      EOF

    * install the WAPT Agent using yum:

    .. code-block:: bash

      yum install tis-waptagent

  .. comments TAB MACOS XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX

  .. _install_waptagent_macos:

  .. tab:: macOS

    .. warning::

      The WAPT agent for macOS is currently only available in the WAPT Enterprise version.

    .. hint::

      The WAPT Agent has only been tested on **Intel architecture** and **Apple Silicon M Series** processors:

      * `Mojave <https://en.wikipedia.org/wiki/MacOS_Mojave>`_ (10.14);

      * `Catalina <https://en.wikipedia.org/wiki/MacOS_Catalina>`_ (10.15);

      * `Big Sur <https://en.wikipedia.org/wiki/MacOS_Big_Sur>`_ (11.x);

      * `Monterey <https://en.wikipedia.org/wiki/MacOS_Monterey>`_ (12.x).

      * `Ventura <https://en.wikipedia.org/wiki/MacOS_Ventura>`_ (13.x).

      * `Sonoma <https://en.wikipedia.org/wiki/MacOS_Sonoma>`_ (14.x).

      * `Sequoia <https://en.wikipedia.org/wiki/MacOS_Sequoia>`_ (15.x).


    * Download and install the WAPT Agent (note: the hash string may change, to get the latest, point your browser on the url https://wapt.tranquil.it/wapt/releases/wapt-|wapt_short_version|/).
      Choose the version depending on your processor architecture (intel or m1):

    .. code-block:: bash
      :substitutions:
      
      # for mac m1
      curl -OL http://wapt.tranquil.it/wapt/releases/wapt-|wapt_last_release|-|git_hash|/tis-waptagent-|wapt_last_release|-|git_hash|-macos-all-arm64.pkg
      # for mac intel
      curl -OL http://wapt.tranquil.it/wapt/releases/wapt-|wapt_last_release|-|git_hash|/tis-waptagent-|wapt_last_release|-|git_hash|-macos-all-x86_64.pkg

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

.. _deploying_initial_config_package:

Installing the WAPT Agent configuration file
============================================

Before installing the WAPT Agent configuration file, you have to create a :ref:`initial config for you agent <creating_initial_config_package>` in your WAPT Console.

.. warning::

  The WAPT Agent configuration wizard is only available on WAPT Entreprise Edition.
  To configure Linux WAPT Agent, please refer to the :ref:`manual WAPT Agent configuration method <manual_wapt_agent_config_method>`.


When done, copy the command with the :guilabel:`Copy installation command`.

.. figure:: wapt-resources/wapt_console_initial-configuration_windows-copy-menu.png
  :align: center
  :alt: Menu list showing the *Copy installation command*

  Menu list showing the *Copy installation command*

Then use this copied command prompt on the Linux / macOS agent.

.. code-block:: bash

  wapt-get reset-config-from-url https://srvwapt.mydomain.lan/wapt/conf.d/default_f0288df2131b8dce667b8c34b9999959bdc2d253b3934fcb3be2eabad8a50021.json f0288cf2131b9dce667b8c34b9999959bdc2d253b3934fcb3be2eabad8a50020

Finally, execute the following command to register the Linux / macOS host with the WAPT Server:

.. code-block:: bash

  sudo wapt-get register

When you have modified the configuration of the WAPT Agent, you should restart the WAPT Agent using the following command:

.. code-block:: bash

  sudo wapt-get restart-waptservice

Feature matrix
--------------

There are some features that are not currently available on Linux and macOS:

* Installing updates on shutdown (WAPT Exit);

* Any Windows specific feature.

Particularities with domain functionality
-----------------------------------------

On Linux:

* Testing was carried out with sssd with an Active Directory domain and kerberos authentication.

* To integrate a host in the Active Directory domain, you can choose to follow `this documentation <https://dev.tranquil.it/samba/en/samba_config_client/client_join_clients_linux.html>`_.

* In order for Active Directory groups to function properly, you **MUST** verify that the :command:`id hostname$` command returns the list of groups the host is a member of.

.. attention::

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


Manual method to configure the WAPT Agent running on Linux / macOS
==================================================================


.. _manual_wapt_agent_config_method:

.. attention::

  Please, see the new method :ref:`to deploy configuration file <deploying_initial_config_package>` instead if you are using WAPT Entreprise Edition.

Creating the WAPT Agent configuration file
------------------------------------------

Use the WAPT Server :abbr:`FQDN (Fully Qualified Domain Name)` address for the :code:`repo_url` and the :code:`wapt_server` arguments.

.. code-block:: bash

  sudo cat > /opt/wapt/wapt-get.ini <<EOF
  [global]
  repo_url = https://srvwapt.mydomain.lan/wapt
  wapt_server = https://srvwapt.mydomain.lan
  use_hostpackages = True
  use_kerberos = False
  verify_cert = False
  EOF

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 host in :file:`C:\\Program Files (x86)\\wapt\\ssl\\`.

Copy your certificate(s) in :file:`/opt/wapt/ssl` using :program:`WinSCP` or :program:`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 :ref:`Nginx SSL/TLS certificates <activating_HTTPS_certificate_verification>`, you **MUST** copy the certificate in your WAPT Linux or macOS Agent.

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

* Copy your certificate(s) in :file:`/opt/wapt/ssl/server/` using :program:`WinSCP` or :program:`rsync` if you are deploying on Linux or macOS.

* Then, modify in the :file:`/opt/wapt/wapt-get.ini` configuration file the path to your certificate.

* And give the absolute path of your certificate.

.. code-block:: ini

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

.. hint::

  Change the :mimetype:`.crt` file with your certificate name.
