Deploy Windows Agents using Active Directory Group Policy

Overview

In Windows Server operating systems, a Domain Controller (DC) is a server that responds to security authentication requests (logging in, checking permissions, etc.) within a Windows Server domain. A Group Policy Object (GPO) is a collection of settings that define what a system will look like and how it will behave for a defined collection of user or computer objects.

If you have environments, customer devices, or networks that are controlled by Windows Server Active Directory DCs, you can leverage the Active Directory GPO framework to deploy the Datto RMM Agent to Windows devices joined to the domain. This is the quickest and most scalable method of Agent deployment.

NOTE  A standard software installation GPO relies on the availability of the software installer to be attached as a Microsoft Installer (MSI) file. Since the Datto RMM Agent is offered as an EXE file, a standard software installation GPO cannot be used.

Video

Deploy RMM Agent by AD GPO [WIN] component

There is a component available in the ComStore that you can use to target all of your domain-controlled environments. It is called Deploy RMM Agent by AD GPO [WIN]. This component features the following:

  • Functionality for both on-premise and hosted (for example, on Azure or Amazon Web Services) DCs, as well as Azure Active Directory Domain Services (AADDS) environments via the use of Management Servers.
  • Automatic downloading of the necessary Agent for the site in which the DC resides, negating the need to download individual Agents on a per-site basis. This means you can run the same component on any DC (or Management Server, in the case of AADDS environments) in any site. The download feature has been confirmed to work behind proxy servers.
  • Optional Organization Unit (OU)-level targeting of the Datto RMM Agent deployment with optional site override. By default, the component will link the created GPO at domain root level, but with this option you can create granularity and limit the deployment for application only to computer objects in specific OUs; additionally, you can optionally override the Datto RMM sites that the Agents installed on the computer objects in the respective OUs associate to. Detailed instructions on the use of this feature can be found in the Variable configuration section below.
  • A GPO script file, which is copied into a sub-folder within the System Volume (SYSVOL) share together with the downloaded Agent installer file. This feature has two benefits:
    • For on-premise and hosted DCs in a multi-DC environment, it leverages Distributed File System (DFS) replication in order to automatically replicate to other DCs in the domain.
    • For AADDS environments, you do not have to keep a Management Server online 24/7 to host the files since they are stored directly on Microsoft’s Azure DCs.
  • Deployment via an Immediate Scheduled Task GPO, which launches the GPO script file to install the Agent. This means that all Windows devices joined to the domain will install the Agent automatically upon next policy refresh.

NOTE  The default policy refresh period is 90 minutes (plus 0-30 minutes randomization), but there is an option to attempt to force an immediate and silent GPUpdate within the component. Refer to Variable configuration below for more details.

NOTE  Certain behavioral-type antivirus solutions may block the GPO due to the fact that it is fired by Immediate Scheduled Task under the local System account on the computer objects. If this happens, you can simply add the created GPO to the allowlist. Below is an example screenshot:

  • The GPO will also successfully target remote domain-joined devices connected via VPN.

IMPORTANT  The default for a GPO script timeout is 10 minutes, but it can be configured for a longer duration. The Agent deployment will fail against VPN-connected devices with slow WAN links if the total of the download, execution, and completion times is longer than the timeout period.

  • Automatic launch of the Agent Browser as the logged-in user because the Agent is installed by the local machine System account by the script run by the GPO. Note this feature fully supports both multiple simultaneous local logons and RDS servers and will launch the Agent Browser as all logged-in users simultaneously.
  • Automatic DFS replication to support domains with multiple DCs.
  • Full error trapping in the event that something does not work as expected; for example, if the download fails due to incorrect proxy credentials or the GPO is not created successfully due to the user context of the job run. In this example, the status of the job run will be Failed, with a useful message in StdErr explaining the reason for the error.
  • Ability to remove the GPO from the domain together with associated files for situations where you need to do so. Refer to the Variable configuration section below for full details.

With these features, you must be mindful of the user context in which the component is run. The user context must allow for the downloading of files from the Internet, writing to the SYSVOL share, and creating, importing, and linking GPOs. By default, a quick job or a scheduled job that has not been configured to run in the logged-in user context will always run in the NT AUTHORITY\SYSTEM user context. Refer to Quick jobs - New UI and Scheduled jobs - New UI.

If any of your domains have been configured not to allow the local SYSTEM user account for the DC to download files from the internet, write to the SYSVOL share, or create, modify, or link GPOs (this is not the default behavior of a DC, but can be configured as such), then once you download the component from the ComStore:

  1. Make a copy of the component.

  2. Select the This component requires site credentials check box.

  3. Save the copy and delete the original. Refer to Creating a component.

  4. For each site where this is the case, navigate to Settings > Credentials > Edit to configure the credentials for a user account that has appropriate privileges (this will normally be a user with membership of the Domain Admins group). Refer to Credentials.

NOTE   If the component is configured to run using site credentials but is run on a DC within a site in which the credentials have not been configured, it will revert to run as NT AUTHORITY\SYSTEM. Therefore, you only need to add site credentials to those sites where the DC SYSTEM account does not have the appropriate privileges required to run the component.

NOTE   You can confirm the user context the component was run under in the StdOut when the job completes.

NOTE  If you re-run the component on a DC on which it was previously run, it will merely update the Agent installer. Given the monthly release cadence for Datto RMM, we recommend you run this component in a monthly scheduled job against your Domain Controllers and AADDS Management Servers in order to ensure the Agent installer is always up-to-date. The GPO script file, GPO, and link(s) will remain unchanged. Note that the Datto RMM Agent updates itself automatically.

NOTE   If a DC that had this component applied is ever moved to another site, ensure that you re-run the component after the move in order to download the Agent for the new site and to overwrite the Agent installer file accordingly. This will ensure the GPO always deploys Agents to the correct site. Failure to do so will result in new domain-joined computer objects installing Agents assigned to the DC's original site.

Variable configuration

There are four variables you can configure when running the component on your DC(s):

  1. ImmediateGPUpdate: Windows Server 2012 and above can run GPUpdate natively, but the GPUpdate CMD window will be displayed on all client devices (which may cause concern to your users and result in a brief increase in tickets). Additionally, it can take up to ten minutes to launch. However, when this variable is set to True (the default), the component will attempt to run a GP Update silently and immediately once the GPO has been imported and linked. Note that your client devices must respond to PING for this variable to work.

NOTE  This functionality uses files from Specops Gpupdate, although it doesn’t actually install it.

  1. UseOUTargeting: By default, the component will link the GPO at the root of the domain. If you want to apply the GPO to specific OUs so only the computer objects in those OUs have the Agent installed, or to override the sites within Datto RMM that those Agents are associated to, set this variable to True. The first time you run the component, it will generate a CSV file containing all the OUs in the domain. Each row will contain the short name, distinguished name, and canonical name of the OU, together with the site ID of the DC or Management Server running the component. You can get the location where the CSV file was saved from the StdOut output. Open the file, then delete all rows pertaining to OUs you do not want to deploy Datto RMM Agents to. For those remaining, if you would like to override the site the computer objects in those OUs associate to, simply paste the new site ID into that cell. Save the file once done and then re-run the component, again setting this variable to True. It will then link only those OUs to the GPO, and the script the GPO fires will override the site the Agent associates to with the site stipulated by the site ID for that OU in the CSV file.

NOTE  The CSV file is saved to the SYSVOL share of the DC the device running the component is using as the Logon Server. In multiple-DC environments, it may be the case that this is not the same DC as the one targeted by the component. However, DFS replication is forced throughout the process, so this should have no impact.

NOTE  When you save your changes to the CSV file, it must be done under a user context with privileges to save to the sub-folder in the SYSVOL share.

NOTE  The component includes logic to ensure that the CSV file has been modified before it creates the GPO links. If it hasn’t been modified, it has the same effect as linking the GPO at domain root but actually links to every OU, so in this situation, the component will fail with a message in StdErr to this effect. If you wish to link to every OU, simply set the variable to False to link at domain root.

  1. RemoveGPO: If you want to remove the GPO and links and the generated sub-folder created in the SYSVOL sub-folder and all of its contents, simply set this variable to True.

  2. RecreateCSV: When the CSV file is created after the first run setting UseOUTargeting to True, subsequent runs will use the file to create the GPO links. If you make changes to your AD structure and you want to recreate the CSV from scratch to align with these changes, set this variable to True.

NOTE  The value of the RecreateCSV variable will only be considered when UseOUTargeting is set to True.