.. Reminder for header structure: Parts (H1) : #################### with overline Chapters (H2) : ******************** with overline Sections (H3) : ==================== Subsections (H4) : -------------------- Subsubsections (H5) : ^^^^^^^^^^^^^^^^^^^^ Paragraphs (H6) : """"""""""""""""""""" .. |enterprise_feature| image:: wapt-resources/wapt_enterprise.png :scale: 3% :alt: WAPT Enterprise feature only .. |date| date:: .. meta:: :description: Deploying the WAPT agent :keywords: waptconsole, waptagent, wapt_deploy, WAPT, preferences, documentation .. _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 ************************ Windows ======= Two methods are available to deploy the :program:`waptagent.exe`. * The first method is manual and the procedure must be applied on each machine. * The second one is automated and relies on a :abbr:`GPO (Group Policy Objects)`. .. note:: 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. .. warning:: If you do not sign the :program:`waptagent.exe` installer with a commercial ``Code Signing`` certificate or a ``Code Signing`` certificate issued by the :term:`Certificate Authority` of your Organization after having generated it, web browsers will show a warning message when downloading the installer. To remove the warning message, you must sign the :mimetype:`.exe` with a ``Code Signing`` certificate that can be verified by a CA bundle stored in the machine's certificate store. .. _install_agent: Manually -------- .. attention:: Manually installing the WAPT agent requires :term:`Local Administrator` rights on the computer. Manually installing the WAPT agent using a Domain Admin account **WILL NOT WORK**. .. hint:: When to deploy the WAPT agent manually? Manual deployment method is efficient in these cases: * Testing WAPT. * Using WAPT in an organization with a small number of computers. * If you don't have a means of mass deployment. * Download the WAPT agent from your WAPT server then launch the installer. .. figure:: wapt-resources/web-interface-server.png :align: center :alt: Download the WAPT agent to be deployed on computers Download the WAPT agent to be deployed on computers * Choose the language and click on :guilabel:`OK` to go to next step. .. figure:: wapt-resources/waptagent-choose-language.png :align: center :alt: Choose the installation language Choose the installation language * Accept the license terms and click on :guilabel:`Next` to go to next step. .. figure:: wapt-resources/waptagent-accept-license.png :align: center :alt: Accepting the EULA Accepting the EULA * Choose the additional parameters and click on :guilabel:`Next` to go to next step. .. figure:: wapt-resources/waptagent-select-additional-tasks.png :align: center :alt: Choose the installer's options Choose the installer's options .. list-table:: Avialable options :header-rows: 1 :widths: auto :align: center * - Settings - Description - Default value * - Install WAPT service - Add WAPT service on your computer - Checked * - Launch notification icon upon session opening - Launch waptagent on systray at startup - Not checked * - Disable hiberboot, and increase shutdown GPO timeout (recommended) - Disable Windows fast startup for stability, enlarge timout for WAPTexit - Checked * - Use a random UUID to identify the computer instead of BIOS - To resolve :ref:`BIOS UUID bugs ` - Not checked * Choose the WAPT repository and the WAPT Server and click on :guilabel:`Next` to go to next step. .. figure:: wapt-resources/waptagent-choose-repo-and-server-url.png :align: center :alt: Choose the WAPT repository and server Choose the WAPT repository and server * Install the WAPT agent by clicking on :guilabel:`Install`. .. figure:: wapt-resources/waptagent-ready-to-install.png :align: center :alt: Summary of installation options Summary of installation options * Wait for the installation of the WAPT agent to finish, then click on :guilabel:`Finish` to exit. .. figure:: wapt-resources/waptagent-installation-in-progress.png :align: center :alt: Installation in progress Installation in progress The installation of the WAPT agent is finished. The registration of the host with the WAPT server is done automatically. .. figure:: wapt-resources/waptagent-installation-finished.png :align: center :alt: End of WAPT agent installation End of WAPT agent installation To manage your Organization's WAPT clients, visit the :ref:`documentation on using the WAPT console `. 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 waptdeploy ^^^^^^^^^^^^^^^ :program:`waptagent.exe` is an `InnoSetup `_ installer, it can be executed with these silent argument: .. code-block:: bash waptagent.exe /VERYSILENT * Additional arguments are available for waptdeploy. .. list-table:: Description of available options for deploying the WAPT agent silently :header-rows: 1 :widths: auto * - Options - Description * - ``/dnsdomain`` = mydomain.lan - Domain in :file:`wapt-get.ini` filled in during installation. * - ``/wapt_server`` = https://srvwapt.mydomain.lan - URL of the WAPT server in :file:`wapt-get.ini` filled in during installation. * - ``/repo_url`` = https://repo1.mydomain.lan/wapt - URL of the WAPT repository in :file:`wapt-get.ini` filled in during installation. * - ``/StartPackages`` = basic-group - Group of WAPT packages to install by default. * - ``/verify_cert=`` = 1 or relative path :file:`ssl\\server\\srvwapt.mydomain.lan.crt`. - Value of ``verify_cert`` entered during installation. * - ``/CopyServersTrustedCA`` = path to a bundle to copy to :file:`ssl\\server` - Certificate bundle for https connections (to be defined by ``verify_cert``). * - ``/CopypackagesTrustedCA`` = path to a certificate bundle to copy into :file:`ssl` - Certificate bundle for verifying package signatures. .. hint:: The :file:`.iss` file for the InnoSetup installer is available here : :file:`C:\\Program Files (x86)\\wapt\\waptsetup\\waptsetup.iss`. You may choose to adapt it to your specific needs. Once modified, you'll just have to recreate a :program:`waptagent`. To learn more about the options available with *InnoSetup*, visit this `documentation `_ :program:`waptdeploy` 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:: :program:`waptdeploy` must be started as :term:`Local Administrator`, that is why we advise you to use a GPO. Download :file:`waptdeploy.exe` from you'r WAPT server homepage. .. figure:: wapt-resources/web-interface-server.png :align: center :alt: Download the waptdeploy Download the waptdeploy .. _deploy_waptagent_with_GPO: With a GPO """""""""" * Create a new group strategy 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/waptdeploy-add-gpo.gif :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/waptdeploy-browse.gif :align: center :alt: Finding the waptdeploy.exe file on your computer Finding the waptdeploy.exe file on your computer * Copy :file:`waptdeploy.exe` in the destination folder. .. figure:: wapt-resources/waptdeploy-copy-waptdeploy.gif :align: center :alt: Selecting the waptdeploy.exe script Selecting the waptdeploy.exe script * Click on :guilabel:`Open` to import the :file:`waptdeploy.exe`. .. figure:: wapt-resources/waptdeploy-select-file.gif :align: center :alt: Selecting the waptdeploy.exe script Selecting the waptdeploy.exe script * Click on :guilabel:`Open` to confirm the importation of the :program:`waptdeploy` binary. .. hint:: It is necessary to provide the checksum of the :file:`waptagent.exe` as an argument to the *waptdeploy* GPO. This will prevent the remote host from executing an erroneous / corrupted :program:`waptagent` binary. .. code-block:: bash --hash=checksum WaptAgent --minversion=1.2.3 --wait=15 --waptsetupurl=http://srvwapt.mydomain.lan/wapt/waptagent.exe Parameters and :program:`waptagent.exe` checksum to use for the *waptdeploy* GPO are available on the WAPT Server by visiting https://srvwapt.mydomain.lan. .. figure:: wapt-resources/waptdeploy-copy-parameters.png :align: center :alt: Web console of the WAPT Server Web console of the WAPT Server * Copy the required parameters. .. figure:: wapt-resources/waptdeploy-add-extra-parameter.png :align: center :alt: add the *waptdeploy* script to the startup GPO add the *waptdeploy* script to the startup GPO * Click on :guilabel:`OK` to go on to the next step. .. figure:: wapt-resources/waptdeploy-gpo-ready.png :align: center :alt: WAPTdeploy GPO to be deployed on next startup WAPTdeploy 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 waptdeploy .. list-table:: Description of available options for waptdeploy :header-rows: 1 :widths: auto * - Options - Description * - ``--force`` - Install waptagent.exe even if not needed. * - ``--hash`` = - Check that the downloaded waptagent.exe setup sha256 hash matches the hash. * - ``--help`` - Displays the options * - ``--minversion`` = 1.2.3 - Install waptagent.exe if installed version is less than minversion. * - ``--tasks`` = autorunTray,installService,installredist2008,autoUpgradePolicy - If given, pass this arguments to the /TASKS options of the waptagent installer. Default = installService,installredist2008, autoUpgradePolicy. * - ``--repo_url`` = https://srvwapt.mydomain.lan/wapt - Location of the repository to get :file:`waptagent.exe`. * - ``--setupargs`` = - Add this to the command line of waptagent.exe. * - ``--wait`` = - Wait running and pending tasks to complete if waptservice is running before install. * - ``--waptsetupurl`` = https://srvwapt.mydomain.lan/wapt/waptagent.exe - Explicit location to download setup executable. Can be a local path (default=:file:`/waptagent.exe`. .. code-block:: bash With a scheduled task ^^^^^^^^^^^^^^^^^^^^^ You may also choose to launch :program:`waptdeploy` using a scheduled task that has been set by GPO. .. hint:: This method is particularly effective for deploying WAPT on workstations when the network is neither available on starting up or shutting down. The method consists of using a GPO to copy 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 waptdeploy. .. figure:: wapt-resources/waptdeploy-newfilecopy.png :align: center :alt: New file on GPO New file on GPO * Set parameters. .. list-table:: Description of options for copy :header-rows: 1 :align: center :widths: auto * - Options - Value * - Action - Replace * - Source file(s) - :file:`\\\mydomain.lan\\netlogon\\waptdeploy.exe` * - Destination File - :file:`C:\\Temp\\waptdeploy.exe` * - Suppress errors on individual file actions - not checked * - Read-only - not checked * - Hidden - not checked * - Archive - checked .. figure:: wapt-resources/waptdeploy-filecopy-waptdeploy.png :align: center :alt: WAPT agent installation progress WAPT agent installation progress * Create a new file and copy waptagent. .. figure:: wapt-resources/waptdeploy-newfilecopy.png :align: center :alt: New file on GPO New file on GPO * Set parameters. .. list-table:: Description of options for copy :header-rows: 1 :align: center :widths: auto * - Options - Value * - Action - Replace * - Source file(s) - :file:`\\\mydomain.lan\\netlogon\\waptagent.exe` * - Destination File - :file:`C:\\Temp\\waptagent.exe` * - Suppress errors on individual file actions - not checked * - Read-only - not checked * - Hidden - not checked * - Archive - checked .. figure:: wapt-resources/waptdeploy-filecopy-agent.png :align: center :alt: WAPT agent installation progress WAPT agent installation progress * 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/waptdeploy-task-create.png :align: center :alt: Task Create in *deploywapt* Properties window Task Create in *deploywapt* Properties window .. figure:: wapt-resources/waptdeploy-task-general.png :align: center :alt: General tab in *deploywapt* Properties window General tab in *deploywapt* Properties window * 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 `_ 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/waptdeploy-task-trigger.png :align: center :alt: Trigger tab in *deploywapt* Properties window Trigger tab in *deploywapt* Properties window * 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/waptdeploy-task-actions.png :align: center :alt: Actions tab * Create a new action :guilabel:`Start a program` for :file:`waptdeploy.exe`. .. figure:: wapt-resources/waptdeploy-task-actions.gif :align: center :alt: Actions tab .. list-table:: Description of options to copy :header-rows: 1 :align: center :widths: auto * - Options - Value * - Action - Start a program * - Program / script - :file:`C:\\Temp\\waptagent.exe` * - Add arguments (optional) - See the next point * - Start in (optional) - empty .. hint:: It is necessary to provide the checksum of the :file:`waptagent.exe` as an argument to the *waptdeploy*. This will prevent the remote host from executing an erroneous / corrupted :program:`waptagent` binary. .. code-block:: bash --hash=checksum WaptAgent --minversion=1.2.3 --wait=15 --waptsetupurl=http://srvwapt.mydomain.lan/wapt/waptagent.exe Parameters and the :program:`waptagent.exe` checksum to use for the *waptdeploy* GPO are available on the WAPT Server by visiting https://srvwapt.mydomain.lan. .. figure:: wapt-resources/waptdeploy-copy-parameters.png :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=1.2.3 --wait=15 --waptsetupurl=C:\Temp\waptagent.exe .. hint:: More arguments are available for waptdeploy .. list-table:: Description of available options for waptdeploy :header-rows: 1 :widths: auto * - Options - Description * - ``--force`` - Install waptagent.exe even if not needed * - ``--hash`` = - Check that the downloaded waptagent.exe setup sha256 hash matches the hash. * - ``--help`` - Displays the options. * - ``--minversion`` = 1.2.3 - Install waptagent.exe if installed version is less than minversion. * - ``--tasks`` = autorunTray,installService,installredist2008,autoUpgradePolicy - If given, pass this arguments to the /TASKS options of the waptagent installer. Default = installService,installredist2008, autoUpgradePolicy * - ``--repo_url`` = https://srvwapt.mydomain.lan/wapt - Location of repository to get the :file:`waptagent.exe`. * - ``--setupargs`` = - Add this to the command line of waptagent.exe. * - ``--wait`` = - Wait running and pending tasks to complete if :file:`waptservice` is running before install. * - ``--waptsetupurl`` = https://srvwapt.mydomain.lan/wapt/waptagent.exe - Explicit location to download setup executable. This can be a local path (default=:file:`/waptagent.exe`). * Go on to the :guilabel:`Settings` tab. .. figure:: wapt-resources/waptdeploy-task-settings.png :align: center :alt: Settings tab in *deploywapt* Properties window Settings tab in *deploywapt* Properties window * In the :guilabel:`Settings` tab, only check :guilabel:`Run task as soon as possible after a scheduled start is missed`. .. hint:: To verify that your :abbr:`GPO (Group Policy Object)` is working, you can run the :command:`gpupdate /force` command and verify that the scheduled task is present on your computer by launching :program:`Task Scheduler` as a Local Administrator. .. _install_waptagent_linux: Linux ===== A Linux agent is available for :ref:`Debian `, :ref:`Ubuntu ` and :ref:`RedHat / Centos `. .. note:: The following procedure installs a WAPT agent using Tranquil IT's repositories; .. _install_on_debian: Debian ------ Discovery ^^^^^^^^^^ .. important:: Follow this procedure for getting the right packages for the WAPT **Discovery** Edition. For WAPT **Enterprise** Edition please refer to the next block. .. note:: Not Available as of |date|. WAPT Discovery will be release later. For the free version, refer to wapt-1.8 documentation https://www.wapt.fr/en/doc-1.8/ Enterprise ^^^^^^^^^^ .. important:: **Follow this procedure for getting the right packages for the WAPT Enterprise** Edition. For WAPT **Discovery** Edition please refer to the previous block. * Update the distribution : .. code-block:: bash apt update && apt upgrade -y * Install ``apt-transport-https`` for the use of https : .. code-block:: bash apt install apt-transport-https lsb-release gnupg -y * Retrieving the key :file:`.gpg` and adding the Tranquil'iT repository : .. code-block:: bash wget -O - https://wapt.tranquil.it/debian/tiswapt-pub.gpg | apt-key add - echo "deb https://srvwapt-pro.tranquil.it/entreprise/debian/wapt-2.1/ $(lsb_release -c -s) main" > /etc/apt/sources.list.d/wapt.list * Create :file:`wapt.conf` in :file:`/etc/apt/auth.conf.d` to store your login information .. hint:: Replace **user** and **password** to access WAPT Enterprise repository, with those provided by our sales department. .. code-block:: bash cat > /etc/apt/auth.conf.d/wapt.conf < /etc/apt/sources.list.d/wapt.list * Create :file:`wapt.conf` in :file:`/etc/apt/auth.conf.d` to store your login information .. hint:: Replace **user** and **password** to access WAPT Enterprise repository, with those provided by our sales department. .. code-block:: bash cat > /etc/apt/auth.conf.d/wapt.conf < /etc/yum.repos.d/wapt.repo <`_ (10.13); * `Mojave `_ (10.14); * `Catalina `_ (10.15); * `Big Sur `_ (10.16). Discovery --------- .. important:: Follow this procedure for getting the right packages for the WAPT **Discovery** Edition. For WAPT **Enterprise** Edition please refer to the next block. .. note:: Not Available as of |date|. WAPT Discovery will be release later. For the free version, refer to wapt-1.8 documentation https://www.wapt.fr/en/doc-1.8/ Enterprise ---------- .. important:: Follow this procedure for getting the right packages for the WAPT **Enterprise** Edition. For WAPT **Discovery** Edition please refer to the previous block. To access WAPT Enterprise resources, you must use the username and password provided by our sales department. On the command line ^^^^^^^^^^^^^^^^^^^ .. hint:: Replace **user** and **password** in the **baseurl** parameter to access WAPT **Enterprise** repository. * recovery of the list of available files .. code-block:: bash sudo curl --user "user:password" https://srvwapt-pro.tranquil.it/entreprise/release/latest/ * on result, copy :file:`tis-waptagent-version-macos-hash.pkg`; * create the complete link with : 1. ``https://srvwapt-pro.tranquil.it/entreprise/release/latest/`` and 2. ``tis-waptagent-version-macos-hash.pkg`` copied previously; * download WAPT agent : .. attention:: Remplace ```` by link create before; .. code-block:: bash sudo curl --user "user:password" --output tis-waptagent.pkg * install the downloaded package: .. code-block:: bash sudo installer -pkg tis-waptagent.pkg -target / Creating the agent configuration file """"""""""""""""""""""""""""""""""""" .. hint:: Use your server adress on **repo_url** and **wapt_server**. .. code-block:: bash sudo cat > /opt/wapt/wapt-get.ini <`, you must copy the certificate in your WAPT Linux agent. The certificate should be located on your Windows machine 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 your :file:`/opt/wapt/wapt-get.ini` config file the path to your certificate. * And give absolute path of your cert. .. code-block:: ini verify_cert=/opt/wapt/ssl/server/YOURCERT.crt .. hint:: Change :file:`YOURCERT.crt` by your certificate name. Graphically ^^^^^^^^^^^ * recovery the last :file:`.dpkg` .. code-block:: bash https://srvwapt-pro.tranquil.it/entreprise/release/latest/ * run the :file:`.dpkg` Registering ----------- * restart the WAPT service: .. code-block:: bash sudo launchctl unload /Library/LaunchDaemons/it.tranquil.waptservice.plist sudo launchctl load /Library/LaunchDaemons/it.tranquil.waptservice.plist * finally, execute the following command to register your MacOS host with the WAPT server: .. code-block:: bash sudo wapt-get register Your MacOS Agent is installed and configured and it will now appear in your WAPT Console with an apple icon. Unsupported features -------------------- * installing updates on shutdown; * WAPT console is not currently available on MacOS; * any Windows specific feature; Particularities with domain functionality ----------------------------------------- * testing was carried out with sssd with an Active Directory domain and kerberos authentication; * to integrate a machine in the Active Directory domain, you can choose to follow `this documentation `_ * to force the update of Organizational Units on the host, you can apply a :command:`gpupdate` from the WAPT console; * 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 member of; .. attention:: We have noticed that the kerberos LDAP query does not work if the reverse DNS record is not configured correctly for your domain controllers. These records must therefore be created if they do not exist. ************************ Updating the WAPT agents ************************ For each server's :ref:`upgrade `, you'll have to upgrade WAPT agent. To do so, you have to :ref:`generate ` agent and deploy it. Manually ======== You can do that manually, it's the same as an agent :ref:`installation `. .. hint:: It's the only upgrade solution available for now for MacOS and Linux. Via waptupgrade =============== While you :ref:`generate ` WAPT agent, package named :file:`waptupgrade` is created. This package is a standard WAPT package designed to upgrade WAPT agents on client machines. .. hint:: For now, :file:`waptupgrade` only work for Windows. Upgrading the WAPT agents using the :file:`waptupgrade` package is a two step process: * first the package copies the new :file:`waptagent.exe` file on the client computer and creates a new scheduled task that will run :program:`waptagent.exe` with predefined installation flags two minutes after the creation of the scheduled task. At that point the package itself is installed and the inventory on the server shows the package installation as *OK*, with correct version installed, but the inventory will still show the old version as the agent is not yet updated. * after two minutes the scheduled task starts and runs :program:`waptagent.exe`. :program:`waptagent.exe` shutdowns the local WAPT service, upgrades the local WAPT install, and then restarts the service. The scheduled task is then automatically removed and the WAPT agent sends back its inventory to the WAPT server. Now the inventory on the server will show the new version of the agent. It is recommanded to install :file:`waptupgrade` on all hosts in order to get automtical updates for agents.