.. 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/icon_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, the WAPT Console .. _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: ################################## Managing the WAPT Agent on Windows ################################## *********************************** Deploying the WAPT Agent on Windows *********************************** 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)`. .. 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 host'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 do not have a means of mass deployment. * Download the WAPT Agent from your WAPT Server then launch the installer. .. figure:: wapt-resources/wapt_server_web-interface_browser-window.png :align: center :alt: The WAPT Server interface in a web browser The WAPT Server interface in a web browser * Choose the language for the WAPT installer. .. image:: wapt-resources/wapt_deploy_choose-language_dialog-box.png :align: center :alt: Choosing the language for deploying the WAPT installer * Click on :guilabel:`OK` to go on to the next step. .. image:: wapt-resources/wapt_deploy_accept-license_dialog-box.png :align: center :alt: Accepting the WAPT license terms * Accept the licence terms and click on :guilabel:`Next` to go to next step. * Choose additional configuration tasks (leave the default if not sure). .. figure:: wapt-resources/wapt_deploy_additional-configuration-agent_dialog-box.png :align: center :alt: Choosing the installer options for deploying the WAPT Agent Choosing the installer options for deploying the WAPT Agent .. list-table:: Avialable options :header-rows: 1 :widths: auto :align: center * - Settings - Description - Default value * - :guilabel:`Install WAPT service` - Adds the WAPT service on the computer. - Checked * - :guilabel:`Launch notification icon upon session opening` - Launches the WAPT Agent in the System tray on startup. - Not checked * - :guilabel:`Disable hiberboot, and increase shutdown GPO timeout (recommended)` - Disables Windows fast startup for stability, increases the timout for the WAPT Exit utility. - Checked * - :guilabel:`Use a random UUID to identify the computer instead of BIOS` - Solves possible :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/wapt_deploy_choose-repo-and-server-url_dialog-box.png :align: center :alt: Choosing the WAPT repository and the WAPT Server Choosing the WAPT repository and the WAPT Server * Install the WAPT Agent by clicking on :guilabel:`Install`. .. image:: wapt-resources/wapt_deploy_summary-abstract_dialog-box.png :align: center :alt: Dialog box showing the summary of the installation options * Wait for the installation of the WAPT Agent to finish, then click on :guilabel:`Finish` to exit. .. image:: wapt-resources/wapt_deploy_installation-in-progress_dialog-box.png :align: center :alt: Dialog box showing the WAPT installation in progress The installation of the WAPT Agent is finished. The registration of the host with the WAPT Server is done automatically. .. image:: wapt-resources/wapt_deploy_installation-progress-completed_dialog-box.png :align: center :alt: Installation Wizard has finished 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 the WAPT Deployment utility -------------------------------- :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 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. .. hint:: The :mimetype:`.iss` file for the InnoSetup installer is available in :file:`C:\\Program Files (x86)\\wapt\\waptsetup\\waptsetup.iss`. You may choose to adapt it to your specific needs. Once modified, you will just have to recreate a :program:`waptagent`. To learn more about the options available with *InnoSetup*, visit this `documentation `_ 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. .. figure:: wapt-resources/wapt_server_web-interface_browser-window.png :align: center :alt: The WAPT Server interface in a web browser The WAPT Server interface in a web browser .. _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/wapt_deploy_adding-waptdeploy-gpo_container-window.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/wapt_deploy_gpo-browse_container-window.gif :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 :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 :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=1.2.3 --wait=15 --waptsetupurl=http://srvwapt.mydomain.lan/wapt/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. .. figure:: wapt-resources/wapt_deploy_gpo-copy-parameter_browser-window.png :align: center :alt: Web console of the WAPT Server Web console of the WAPT Server * 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` = ```` - Check that the downloaded :program:`waptagent.exe` setup sha256 hash matches the hash. * - :code:`--help` - Displays the options * - :code:`--minversion` = ```` - 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` = ```` - Location of the repository to get :program:`waptagent.exe` (default /wapt) * - :code:`--setupargs` = ```` - Adds arguments to the command line of :program:`waptagent.exe`. * - :code:`--wait` = ```` - Defines the delay for running and pending tasks to complete if :program:`waptservice` is running before installing. * - :code:`--waptsetupurl` = ```` - Explicit location to download setup executable. It can be a local path (default :file:`/waptagent.exe`). .. code-block:: bash 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 :align: center :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:\\Temp\\waptdeploy.exe` * - :guilabel:`Suppress errors on individual file actions` checkbox - not checked * - :guilabel:`Read-only` checkbox - not checked * - :guilabel:`Hidden` checkbox - not checked * - :guilabel:`Archive` checkbox - checked .. figure:: wapt-resources/windows_rsat_gpo-waptdeploy-replace_dialog-box.png :align: center :alt: WAPT Agent installation progress WAPT Agent installation progress * Create a new GPO and copy 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 copy :header-rows: 1 :align: center :widths: auto * - Options - Value * - :guilabel:`Action` dropdown menu list - Replace * - :guilabel:`Source file(s)` field - :file:`\\mydomain.lan\\netlogon\\waptagent.exe` * - :guilabel:`Destination File` field - :file:`C:\\Temp\\waptagent.exe` * - :guilabel:`Suppress errors on individual file actions` checkbox - not checked * - :guilabel:`Read-only` checkbox - not checked * - :guilabel:`Hidden` checkbox - not checked * - :guilabel:`Archive` checkbox - checked .. figure:: wapt-resources/windows_rsat_gpo-filecopy-agent_dialog-box.png :align: center :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 :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 :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 `_ 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 :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 :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`. .. figure:: wapt-resources/windows_rsat_gpo-task-actions_dialog-box.gif :align: center :alt: Actions tab in the Properties window in RSAT Actions tab in the Properties window in RSAT .. list-table:: Description of options to copy :header-rows: 1 :align: center :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 .. 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=1.2.3 --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 :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 .. 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`` = - Checks that the downloaded waptagent.exe setup sha256 hash matches the hash. * - ``--help`` - Displays the options. * - ``--minversion`` = 1.2.3 - 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`` = - Adds arguments to the command line of waptagent.exe. * - ``--wait`` = - 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:`/waptagent.exe`). * Go on to the :guilabel:`Settings` tab. .. figure:: wapt-resources/windows_rsat_gpo-task-settings_dialog-box.png :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. ********************************** Updating the WAPT Agent on Windows ********************************** For each WAPT Server's :ref:`upgrade `, you will have to upgrade the WAPT Agents. To do so, you have to :ref:`generate the WAPT Agent ` and deploy it. Manually ======== You can do that manually :ref:`by following this documentation on installing the WAPT Agent `. .. hint:: It is the only upgrade solution available for now for macOS and Linux. Via waptupgrade =============== While you :ref:`generate ` the WAPT Agent, package named :file:`waptupgrade` is created. This package is a standard WAPT package designed to upgrade the WAPT Agents on remote hosts. .. 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 WAPT Server shows the package installation as *OK*, with the correct version installed, but the inventory will still show the old version as the WAPT 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 WAPT Server will show the new version of the WAPT Agent. It is recommanded to install :file:`waptupgrade` on all hosts for the WAPT Agents to update automatically.